generated from Labyricorn/labyricorn-project-template
156 lines
8.4 KiB
Markdown
156 lines
8.4 KiB
Markdown
# 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.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](docs/reference/XZBT-NGN-Step6.10-Closure-Report.md) and
|
||
[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. 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](.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).
|