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