generated from Labyricorn/labyricorn-project-template
112 lines
5.3 KiB
Markdown
112 lines
5.3 KiB
Markdown
# XZBT-NGN Exhibit Engine
|
|
|
|
A single-exhibit host for XZBT Exhibit Contract 5.2. 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.
|
|
Step 6 is planned but has not begun.
|
|
|
|
## 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.
|
|
- 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
|
|
```
|
|
|
|
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.2](docs/contract/XZBT-Exhibit-Contract-Specification-v5.2.md)
|
|
and [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.
|
|
|
|
## 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/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.2 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.
|
|
|
|
Not implemented: multi-surface presentation, 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).
|