generated from Labyricorn/labyricorn-project-template
Steps 6.4-6.7B — Local surfaces, reference-exhibit validation, SciFi Observation surface
One commit for the work accumulated in the working tree since Step 6.3, which had never been split into per-step commits: - src/local-surfaces.js + src/surface-url.js (new); src/ui.js, src/validation.js, src/connection.js and public/index.html updated for local-surface hosting and generic surface rendering - tests: local-surfaces (20), scifi-surfaces (24) and postmessage-interop (7) new; connection/museum-gallery/surface-validation suites updated - reference exhibits: shared/contract-core.js defaults to Contract 5.3 (major 5, minor 3, xzbt 5.3); museum-gallery advertises its surface catalog; aquarium/haunted-house/planetarium adapters updated - SciFi-XZBT (Step 6.7A/6.7B): surface-mode.js + surface-bus.js, Observation-surface boot branch, local-change hooks, view.pillars / view.warp-flight targets; fixture byte-identical to G:/.vibe/SciFi-XZBT - SciFi-XZBT contract adapter handshake fix: the inbound bridge filter no longer gates on an exact advisory xzbt value (Contract 5.3 §6.5), only on its presence/type, matching the host's own envelope validation; the adapter now advertises contract minor 3 / version 5.3.0, which it already implemented via the 5.3 surfaces field. Root cause of the five failing postmessage-interop tests (host hello was silently dropped). - docs: architecture 6.4 and 6.7A, reference 6.6 and 6.7; evidence logs; test-fixtures/PROVENANCE.md resync record Test results: NGN 154/154 (was 149/154); postmessage-interop 7/7 (was 2/7); SciFi contract harness 21/21, real-adapter suite 32/32. git diff --check clean for changed files; two pre-existing trailing-whitespace lines remain in test-fixtures/reference-exhibits/scifi/index.html, copied verbatim from the authoritative SciFi source. Step 6.7 live verification (browser Observation, packaged standalone) is still pending and is not claimed here.
This commit is contained in:
@@ -1,6 +1,7 @@
|
||||
# XZBT-NGN Exhibit Engine
|
||||
|
||||
A single-exhibit host for XZBT Exhibit Contract 5.2. It negotiates sessions,
|
||||
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.
|
||||
|
||||
@@ -9,7 +10,9 @@ Step 5 implementation and verification are recorded in
|
||||
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.
|
||||
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).
|
||||
|
||||
## Run locally
|
||||
|
||||
@@ -28,6 +31,12 @@ the discovered controls. Enter another path and select **Load exhibit** to switc
|
||||
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.
|
||||
@@ -41,6 +50,8 @@ 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
|
||||
@@ -69,34 +80,55 @@ 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).
|
||||
[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.2 discovery, generic target rendering,
|
||||
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.
|
||||
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; other maintained exhibits do not declare
|
||||
multiple surfaces. Surface errors stay within the affected pane. Remote/cast
|
||||
display assignment remains deferred. Shared-state synchronization proof remains
|
||||
Step 6.5; this step adds no host-side surface communication.
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user