A single-exhibit host for XZBT Exhibit Contract 5.3 (current; see 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. 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. Step 6.5 synchronization is satisfied by existing implementation and later evidence. Step 6.6 validates reference exhibits, Step 6.7 adds the SciFi-XZBT Observation surface, and Step 6.8 validates multi-surface behavior. Step 6 is complete with documented non-blocking follow-up at the Contract 5.3 accepted baseline f163de2 and closed at tag step-6-complete — see the Step 6.10 closure report and Step 6.7 closure report.

Run locally

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

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:

/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. 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

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. 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 -- the current maintained contract, which additively supersedes Contract Specification 5.2 (retained as a historical predecessor; no 5.2 normative requirement was removed, weakened, or reinterpreted) -- and for the XZBT Exhibit Authoring Guide 5.2. The NGN Implementation Plan 5.2 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. Multi-surface state synchronization (Step 6.5) is satisfied by the single-authority state core, snapshot/revision attachment, and owner-mediated mutation routing proven across reference exhibits. Step 6.8 multi-surface behavior is complete and accepted, with a single unreproduced renegotiation noted as non-blocking follow-up.

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 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.

README.md Unescape Escape

XZBT-NGN Exhibit Engine