XZBT-NGN/README.md

# XZBT-NGN Exhibit Engine

A single-exhibit host for XZBT Exhibit Contract 5.3 (current; see
[Canonical documentation](#canonical-documentation)). It negotiates sessions,
discovers descriptor-driven controls, inspects reported state, sends set/invoke
operations, and displays capabilities, events, revisions, and protocol errors.

Step 5 implementation and verification are recorded in
[the completion report](STEP5-MVP-COMPLETION-REPORT.md). The SciFi-XZBT argument
descriptors are corrected and both text invocations pass through the operator UI.
Step 5 is complete: 27 automated tests and all three browser reference checks
pass. Haunted House reports conformant values, and publishing validation passes.
Steps 6.1–6.3 established Contract 5.3 surface discovery and interoperability.
Step 6.4 adds local presentation panes; see the
[Step 6.4 report](docs/architecture/XZBT-NGN-Step6.4-Local-Surfaces.md).
Step 6.6 validates the reference exhibits, and Step 6.7 adds the SciFi-XZBT
Observation surface, including regenerated packaged-build verification; live
NGN Observation verification remains outstanding — see the
[Step 6.7 closure report](docs/reference/XZBT-NGN-Step6.7-Closure-Report.md).

## Run locally

Requires Node.js 22 or later. No npm dependencies or build step.

```powershell
npm start
```

Open `http://127.0.0.1:4173`. Enter a same-origin exhibit path and select
**Load exhibit**. The host sends `hello`, `describe`, and `state.get` and renders
the discovered controls. Enter another path and select **Load exhibit** to switch.

- **Reconnect** negotiates a new session with the current frame, preserving the
  exhibit instance. After **Disconnect**, it reloads the remembered URL; the new
  exhibit instance starts with its own initial state.
- **Disconnect** removes the frame and clears session, catalog, state and events.
- **Refresh state** reads a new authoritative snapshot.
- **Presentation surfaces** provides Open, Reload and Close for each local view,
  with its label, primary status and lifecycle state. URLs resolve against the
  supplying exhibit's document URL, and must remain same-origin. NGN closes its
  surface panes when disconnecting, reconnecting the session or switching exhibits.
  A primary surface already represented by the control frame is marked as open;
  its lifecycle remains under the Connection controls.
- Controls are grouped by the exhibit's category (or Other when omitted).
  Reported values and draft inputs are distinct; select **Set** or **Invoke**
  to submit. Rediscovery resets drafts.
- Expand **Capabilities**, **State and metadata**, or **Protocol diagnostics**
  details to inspect engineering information. The latest diagnostic is also
  shown near the connection panel. **Clear log** dismisses historical diagnostics.

Included reference fixture paths:

```text
/test-fixtures/reference-exhibits/aquarium/index.html
/test-fixtures/reference-exhibits/planetarium/index.html
/test-fixtures/reference-exhibits/haunted-house/index.html
/test-fixtures/reference-exhibits/museum-gallery/control.html
/test-fixtures/reference-exhibits/scifi/index.html
```

These are locally corrected test/reference fixtures, not NGN product code or
pristine upstream conformance evidence. See [provenance](test-fixtures/PROVENANCE.md).
Place additional trusted HTML exhibits and their relative assets under `public/`
and enter their served URL. A filesystem path or a different server origin cannot
be attached directly. The server exposes only `public/`, `src/`, and
`test-fixtures/`, binds to `127.0.0.1`, and denies paths escaping those directories.
For a port conflict, set `$env:PORT='4175'` before `npm start` and use that origin.

## Verification

```powershell
npm test
python devlog_editor.py --validate
git diff --check
```

Run the browser suite at `/test-fixtures/host-verification.html`; its timestamped
results appear on the page and in the browser console. The normal operator UI
checks and external SciFi-XZBT preparation are documented in
[Step 5 verification](test-fixtures/STEP5-VERIFICATION.md). Saved browser evidence
is under `test-fixtures/evidence/`. No source edits or dedicated harness are
needed for ordinary operation.

## Canonical documentation

This repository is the canonical home for the shared
[XZBT Exhibit Contract Specification 5.3](docs/contract/XZBT-Exhibit-Contract-Specification-v5.3.md) --
the current maintained contract, which additively supersedes
[Contract Specification 5.2](docs/contract/XZBT-Exhibit-Contract-Specification-v5.2.md)
(retained as a historical predecessor; no 5.2 normative requirement was
removed, weakened, or reinterpreted) -- and for the
[XZBT Exhibit Authoring Guide 5.2](docs/authoring/XZBT-Exhibit-Authoring-Guide-v5.2-Step3.7.md).
The [NGN Implementation Plan 5.2](docs/architecture/XZBT-NGN-Exhibit-Engine-Implementation-Plan-v5.2.md)
also belongs here. Its historical phase numbering describes the longer roadmap;
the current Step 5 completion pass does not authorize those later features.
SciFi-XZBT is an external exhibit implementation, not the NGN architecture.
`docs/reference/` contains external implementation context, not host requirements.

NGN and its maintained reference exhibits (Museum Gallery, SciFi-XZBT, Haunted
House, Aquarium, Planetarium) move forward with the contract: there is no
requirement to keep a currently maintained exhibit, or its test coverage,
frozen on an old minor version. The `xzbt` envelope field is advisory metadata
only (Contract §6.5) and is never used as an exact-string compatibility gate;
real compatibility is negotiated by the handshake and contract fields. A
genuine, unmaintained Contract 5.2 exhibit remains protocol-compatible with
this host (Contract §28.2) -- that guarantee is unrelated to which minor
version the exhibits maintained in *this* repository currently declare.

## Implementation and MVP boundary

- `src/host.js`: negotiation, requests, discovery, state cache, events and recovery.
- `src/connection.js`: URL validation and frame load/disconnect/reconnect lifecycle.
- `src/surface-url.js`, `src/local-surfaces.js`: canonical surface URL resolution
  and local presentation frame lifecycle, without additional contract sessions.
- `src/validation.js`: descriptor, state value and argument validation.
- `src/transport/post-message.js`: same-origin frame transport.
- `src/ui.js`, `public/`: generic operator interface.
- `server/serve.js`: loopback static server.
- `tests/`, `test-fixtures/`: automated checks, reference fixtures and browser evidence.

The MVP supports one exhibit, Contract 5.3 discovery, generic target rendering,
state inspection, set/invoke, capabilities, events, session/revision/sequence
tracking, reconnect and synchronization recovery. It has in-memory state only;
logs retain 200 entries. Idle polling is not enabled. The last connection URL is
remembered only until the page is reloaded. Contract 5.3 presentation-surface
discovery and local rendering (Section 31) are implemented and exercised by the
Museum Gallery reference exhibit, and the SciFi-XZBT reference exhibit declares
a console surface plus an Observation surface (Step 6.7B); the other maintained
exhibits do not declare multiple surfaces. Surface errors stay within the
affected pane. Remote/cast display assignment remains deferred. Shared-state
synchronization proof remains Step 6.5; this step adds no host-side surface
communication.

Not implemented: casting/display endpoints, MIDI, MCP/webhooks,
scenarios/recording, telemetry acquisition, multi-exhibit orchestration,
persisted operator configurations, remote deployment, accounts, databases,
cloud services, plugins, commercial licensing or production branding.

## Publishing records

`.labyricorn/` holds this project's Lektor exhibition and development records.
See [publishing guidance](.labyricorn/README.md) and scoped `AGENTS.md` files.
`python devlog_editor.py` opens the standalone publishing editor;
`python devlog_editor.py --validate` validates records without opening the GUI.
Application code lives outside `.labyricorn/`.

## License

See [LICENSE](LICENSE).