XZBT-NGN/test-fixtures/reference-exhibits

Local copy notice. This directory contains locally corrected copies of the upstream reference exhibits. The corrections are documented in ../PROVENANCE.md. The text below is the original upstream README; its verification claims describe the upstream state, not this corrected copy. Re-copying from the upstream source without reapplying corrections will reintroduce known defects.

XZBT Exhibit Contract 5.2 — Reference Exhibits

Three unrelated exhibits and one generic host, all speaking XZBT Exhibit Contract 5.2. The point of the set is not the exhibits; it is that a single unmodified host drives all three, and that the contract layer is shared rather than reimplemented per exhibit.

reference-exhibits/
  shared/
    contract-core.js      generic contract engine (no domain knowledge)
    host-transport.js     same-origin postMessage transport (optional)
    exhibit-shell.js      generic DOM helpers (optional)
    exhibit-shell.css     generic page chrome (optional)
  aquarium/               exhibit 1 — reef tank
  planetarium/            exhibit 2 — sky dome
  haunted-house/          exhibit 3 — the one with a real capability lifecycle
  host-harness/           a generic host that knows nothing about any of them
  tests/                  Node test suites + a static server for manual checks

Running it

No build step, no dependencies, no package manager.

Standalone. Open any exhibit's index.html directly in a browser. It works from file:// with the network off. The header reads standalone and nothing is ever posted anywhere.

With a host. The harness uses postMessage with an origin check, and file:// documents report origin null, so serve over HTTP:

node tests/serve.js

Then open http://localhost:8731/host-harness/index.html, pick an exhibit, and press Connect. The harness performs the handshake, reads describe, and builds its entire control surface from the descriptors the exhibit published.

Tests.

node tests/run-all.js

137 checks, no dependencies. See Verification below for what they do and do not cover.

The layering

Each exhibit is split into four files, and the split is the whole argument:

File	Knows about	Does not know about
exhibit.js	the domain, the canvas, the native controls	the contract, target IDs, events
contract-adapter.js	the contract, the target catalog	rendering, DOM
boot.js	composition only	everything else
index.html	markup and script order	behaviour

exhibit.js is a complete, working exhibit on its own. Delete contract-adapter.js, host-transport.js, and boot.js's last three lines and you still have a functioning aquarium. That is deliberate: the contract is a layer added on top of a working exhibit, not a scaffold the exhibit is built inside of.

The shared contract-core.js is domain-free. It knows the shape of the contract — envelopes, target kinds, revisions, sequences, error codes, capability lifecycle — and nothing about fish, stars, or ghosts. Each adapter supplies three things and gets a conforming surface:

1. a target catalog (canonical dotted IDs → descriptors)
2. a setter table (target ID → absolute, idempotent setter)
3. an action table (target ID → real impulse implementation)

The three exhibits

	Aquarium	Planetarium	Haunted House
Targets	12	14	13
Capabilities	render	render	render, audio
Notable	step-validated ranges	action with a typed argument	a genuinely gated action

The Haunted House is the interesting one. Its audio is synthesized with the Web Audio API, and browsers refuse to start an audio context until the user has interacted with the page. So audio really does begin available, really does pass through loading to ready on the first gesture, and really does report error if the context cannot be created. The adapter mirrors that real state into the capability registry; it never invents a transition to make the contract look busy. action.moan and action.slam-door declare requires: ['audio'] and return CAPABILITY_UNAVAILABLE until the engine is actually ready — while staying discoverable in describe the whole time.

Contract decisions worth stating

One mutation chokepoint. Every persistent-state change — native UI, hotkey, or host set — goes through applyMutation. One call is one transaction: commit, increment stateRevision at most once, then emit the resulting events carrying that revision. A host set and a slider drag are the same transaction with a different source.

No silent clamping. An out-of-range value is rejected with INVALID_VALUE, not quietly pinned to the boundary. A value off the declared step is rejected too. A host that sends nonsense should be told.

No-ops do not move the revision. Setters are absolute and idempotent and report whether anything actually changed. Setting a value to what it already is returns changed: false and leaves stateRevision alone, so a host can poll without inflating history.

stateRevision survives reconnects; sequence does not. A new session resets the event sequence but deliberately leaves stateRevision intact, so a reconnecting host can tell whether it missed anything.

Source is assigned at the trusted boundary. A source field inside an incoming message is ignored. The transport stamps host; the UI path stamps ui.

Event shape is identical on every path. correlationId is always present (null when the change did not originate from a request) so a host can rely on one schema regardless of what caused the change.

Capabilities are honest. An exhibit that cannot fail declares ready once. An exhibit with a real lifecycle reports it. Nothing fakes a transition.

Text is data. Every string that reaches the DOM goes through textContent. Nothing in this project assigns innerHTML, so a string arriving from a host or a scenario can never become markup or script.

Verification

Automated — node tests/run-all.js

conformance.test.js (126 checks). Loads the real contract-core.js and the real contract-adapter.js from each exhibit into a sandbox, with a small stub standing in for the exhibit's own services. The adapter under test is the genuine article; only the domain object behind it is a stub. Covers handshake and session validation, describe shape, canonical target IDs, state.get filtering, mutation semantics (commit, revision, no-op, absolute, rejection), action semantics, event envelopes and monotonic sequence, session reset, source trust, UI/host parity, malformed input, the capability lifecycle, and action arguments. A final cross-exhibit group runs one generic request sequence against all three.

transport.test.js (11 checks). Covers the postMessage layer against a fake window: origin and source validation, version filtering, and — the reason the file exists — that events are pushed to a connected host, not just responses.

Manual — browser

Verified in a real browser against a local server:

• All three exhibits render (canvas confirmed painted, not blank) and load with a clean console.
• Every native control on all three exhibits was exercised; each routes through the canonical path and produces the expected event with source: 'ui'.
• The generic host connected to all three exhibits unmodified, built its UI from their descriptors, and drove them: host set → exhibit commits → event pushed back → host revision, sequence, and readout all update.
• The Haunted House capability lifecycle was observed end to end from a real button click: available → loading → ready, with two capability.changed events, after which the gated action succeeded.
• Standalone: each exhibit opened from file:// with the server stopped. Renders, contract works, native UI works, and performance.getEntriesByType('resource') shows zero external resources.

Not covered

• No automated browser tests. Rendering and the browser's audio policy are verified by hand, as above.
• The exhibits are reference implementations, not production art. The simulation is simple by design; the contract is the subject.

Bugs found and fixed during verification

Recorded because they are the kind that pass a unit suite and fail a user:

1. Target IDs were not canonical. action.cleanGlass, telemetry.fishCount, sky.magnitudeLimit and others used camelCase segments. The catalog validator rejected them at construction. All IDs are now lowercase-hyphenated (action.clean-glass, telemetry.fish-count, sky.magnitude-limit).
2. The transport never forwarded events. It sent responses only, so a host could issue a set, receive an acknowledgement, and never learn that anything had changed. The exhibit looked correct in isolation and the conformance suite passed; only the host/exhibit link was broken. The transport now forwards the core's events to a connected host, and transport.test.js pins it down.
3. The harness raced its own navigation. connect() called disconnect() first, which queued an about:blank load that then beat the real navigation, leaving an empty frame.
4. The harness page never loaded exhibit-shell.js. harness.js uses XZBTShell for element lookup, so it threw on load and the page was inert.
5. correlationId was conditionally present. It was omitted for UI-originated changes and included for host-originated ones, so the event shape differed by path. It is now always present, null when not applicable.

Adding a fourth exhibit

1. Write exhibit.js — a working exhibit with absolute, idempotent setters that return { changed }, a read(targetId), and real actions. No contract awareness.
2. Write contract-adapter.js — declare the catalog, bind setters, readers, and actions, and route the UI through core.applyMutation / core.invokeAction.
3. Write boot.js and index.html following an existing exhibit.
4. Add the exhibit to EXHIBITS in tests/conformance.test.js and to ADAPTER_EXPORTS. The shared conformance group then runs against it automatically.
5. Add it to the harness dropdown. No harness code changes — that is the test.