Labyricorn/XZBT-NGN
1
0
Fork 0
generated from Labyricorn/labyricorn-project-template
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Step 6.2 Complete — Museum Gallery reference exhibit and Contract 5.3 spec

Browse Source
This commit is contained in:
Labyricorn
2026-09-14 14:09:13 -07:00
parent 961919e017
commit 44f2ad3ee6
20 changed files with 5672 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/XZBT-Multi-Surface-Model-Step6.1.md
+755
View File
@@ -0,0 +1,755 @@
# XZBT Multi-Surface Presentation Model — Step 6.1
## Status
**Revision 2 — for final approval.** Contract 5.3 has been approved by the
owner as the intended version for multi-surface presentation (Section 14).
The versioned `v5.3.md` contract file has **not** been minted and Phase 6.2
has **not** begun; both remain gated on approval of this revised document.
This revision addresses five items raised against Revision 1:
1. defines a generic surface-attachment mechanism (new Section 7.2);
2. restores the canonical target-ID grammar for surface IDs, with no carve-out
(Section 5.1);
3. tightens `primary` and backward-compatibility semantics, resolving the
ambiguity previously left as Open Question 1 (Section 6);
4. relaxes the direct-open standalone requirement so it no longer conflicts
with the new attachment mechanism (Section 10);
5. adds an explicit URL-resolution algorithm for the surface `url` field
(new Section 6.3).
---
## 1. Purpose
Step 5 closed the XZBT-NGN MVP around a single implicit assumption: one
exhibit has one renderable visual surface, shown in the one iframe the host
loads.
Step 6 removes that assumption. An XZBT-compatible exhibit may have more than
one full-screen visual presentation — a main interface, an observation
display, an information wall, a second dome view — that are all views onto
**one logical exhibit instance and one authoritative state**, not independent
exhibits.
This document defines:
- what a presentation surface is and is not;
- how an exhibit advertises its surfaces;
- the generic mechanism by which a surface document attaches to the one
authoritative exhibit state, regardless of exhibit implementation;
- how surfaces stay synchronized to that one state;
- the lifecycle a surface goes through;
- who owns what (exhibit / NGN / transport / display endpoint);
- whether this requires a new contract version;
- what remains explicitly out of scope (Step 7).
It does not define casting, remote displays, or any display-transport
mechanism. Those are Step 7.
---
## 2. Definitions
**Logical exhibit instance.** One running exhibit session, with one
`sessionId`, one `stateRevision` history, and one authoritative set of
contract-visible persistent state values, as already defined by Contract 5.2
§13–§14. Multi-surface support does not change this definition; it depends on
it remaining singular.
**Presentation surface.** A renderable, full-screen(-capable) visual view of
the logical exhibit instance, addressable by a stable identifier, that an
exhibit advertises as independently viewable. A surface displays a coherent
subset (or the whole) of the exhibit's presentation, driven by the same
underlying state and the same contract session as every other surface of the
same exhibit.
**Surface descriptor.** The machine-readable metadata an exhibit publishes
describing one presentation surface: identifier, label, lifecycle-relevant
metadata, and enough information for a generic host to open it without any
exhibit-specific knowledge.
**Exhibit State Core.** The single in-exhibit authority for contract-visible
state, mutation, and event fan-out. Every exhibit already has exactly one of
these today, whether or not it is named as such — it is whatever internal
object/module the existing contract adapter (e.g.
`test-fixtures/reference-exhibits/shared/contract-core.js`) reads and writes.
Multi-surface support does not introduce a new core; it requires that every
surface, however many documents or windows are involved, attach to that one
existing core rather than instantiate a second one (Section 7.2).
**Control UI.** The operator-facing interface NGN renders from `describe`
(targets, state, events). It is not a presentation surface. It may run
alongside any number of open presentation surfaces.
**Display endpoint (Step 7, referenced only for contrast).** Where a surface
is physically or logically shown — a local browser window, a monitor, a
casting receiver. Step 6 defines *what* can be shown; Step 7 defines *where*.
---
## 3. Surface vs. Target Distinction
Contract 5.2 already has a generic extensibility mechanism: targets
(state/range/selection/impulse) discovered through `describe`. It is tempting
to model a surface as a `state`-kind target (e.g. `surface.observation.open:
boolean`). This proposal rejects that approach for surfaces themselves, for
four reasons:
1. **A target represents a piece of exhibit state or an action on it.** A
surface is neither — it is a *view*. Modeling "is this surface open" as
exhibit state conflates NGN-side presentation bookkeeping with exhibit
domain state, which Contract §2 explicitly prohibits ("The contract MUST
NOT be expanded merely to move Exhibit Engine responsibilities into the
exhibit").
2. **Targets have no place to carry surface-specific metadata** a generic
host needs to *render a window* rather than *render a control* — no field
in the base or kind-specific descriptors (§9) accommodates a document URL,
an aspect ratio hint, or a role.
3. **A target-based encoding would force every exhibit author to hand-roll an
ad hoc convention** (e.g. a `surface.*` naming prefix) for something that
should be a first-class, uniformly validated concept — exactly the kind of
silent protocol behavior the Step 6 brief prohibits inventing.
4. **Surfaces are discovered once per registry revision, not read/written
like state.** Their lifecycle (open/visible/hidden/closed) is host-side
presentation bookkeeping, not a `set`/`invoke` operation on exhibit state.
Surfaces are therefore modeled as a **new, parallel discovery construct**:
a `surfaces` array returned by `describe`, structurally independent of
`targets` and `capabilities`, but discovered through the same message and
governed by the same `registryRevision`.
**What is NOT a presentation surface:**
- the control/admin UI NGN renders from targets — that is an NGN-owned
concept and never appears in `surfaces`;
- a capability (§17) — capabilities describe whether a subsystem is usable,
not whether a view exists;
- a target of any kind — including a hypothetical `kind: "surface"` target,
which this proposal does not introduce;
- a display endpoint — monitors, browser windows, casting receivers are
Step 7 and are never named inside a surface descriptor;
- a scenario, recording, or packaging artifact.
---
## 4. Ownership Model
| Concern | Owner |
| --- | --- |
| What surfaces exist, their identifiers, labels, and descriptors | **Exhibit** |
| The actual rendering of each surface (HTML/CSS/JS/canvas/audio) | **Exhibit** |
| One authoritative state, `stateRevision`, and event stream (the Exhibit State Core) | **Exhibit**, shared by all surfaces of that exhibit |
| How surface documents attach to the Exhibit State Core internally | **Exhibit** (Section 7.2 defines the generic pattern; the specific transport choice is an exhibit implementation decision) |
| Discovering surfaces from `describe` and reacting to `registry.changed` | **NGN** |
| Deciding which surfaces are currently open and where | **NGN** (Step 6: local rendering only) |
| Routing a native in-surface interaction back into one canonical mutation path | **Exhibit internally**, using the same contract-visible state mechanism regardless of which surface originated the interaction |
| Transport connecting NGN's contract session to the exhibit | **Exhibit + transport binding**, unchanged from Contract §4 |
| Where a surface is physically displayed (monitor, window, cast target) | **Step 7 — out of scope here** |
The exhibit remains the single owner of truth. NGN never maintains a second
copy of exhibit state per surface; it discovers surfaces, opens/closes their
presentation, and continues to observe the one session's state and events
exactly as it does today. This is the direct application of Contract §2: the
exhibit exposes capabilities and state, NGN decides how to coordinate
presentation of them.
---
## 5. Surface Descriptor Proposal
### 5.1 Minimum required fields
```json
{
"id": "surface.control",
"label": "Control Room",
"kind": "surface",
"primary": true,
"url": "control.html"
}
```
| Field | Requirement | Notes |
| --- | --- | --- |
| `id` | REQUIRED string | **MUST conform exactly to the canonical target-ID grammar in Contract §8.1** — lowercase ASCII letters, digits, hyphens, and dots; begins with a lowercase letter; one or more dot-separated segments; no whitespace; no empty segments; recommended grammar `[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+`. No surface-specific carve-out exists: a bare single-segment ID (e.g. `"observation"`) is **not** valid, exactly as it would not be valid for a target ID. Authors are expected to namespace surface IDs meaningfully (e.g. `surface.control`, `surface.observation`, or an exhibit-specific namespace such as `gallery.artifact-wall`), the same discretion Contract §8 already gives target authors. Stability rule of §8.2 applies identically: once published, a surface ID is part of the exhibit's compatibility surface and SHOULD NOT be renamed casually. |
| `label` | REQUIRED string | Human-readable, for generic host display. |
| `kind` | REQUIRED, constant `"surface"` | Distinguishes this array's entries from targets/capabilities defensively, even though they already live in a separate array; makes the descriptor self-describing if ever handled outside its parent array. |
| `primary` | REQUIRED boolean | See Section 6.2 for the exact structural invariant and its enforcement. |
| `url` | REQUIRED string | See Section 6.3 for the full resolution algorithm. Summary: a same-origin, relative reference (path, and/or query/hash) resolved against the exhibit's own base URL — never an absolute or cross-origin URL. |
### 5.2 Optional fields (useful, not yet mandatory)
| Field | Purpose |
| --- | --- |
| `description` | Longer human-readable text for admin display. |
| `role` | Free-text or small controlled vocabulary hint (e.g. `"control"`, `"ambient"`, `"information"`) for host UI grouping. Advisory only; no contract behavior depends on it in 5.3. |
| `aspectRatio` | e.g. `"16:9"`. Advisory hint for window sizing. |
| `category` | Mirrors target `category` (§9) for consistent grouping conventions across the contract. |
| `requires` | Array of capability IDs (§17), same semantics as target `requires`: the surface remains discoverable but SHOULD be presented as degraded/unavailable if a required capability is not `ready`. |
### 5.3 Explicitly excluded fields
No field in the surface descriptor may name a display transport, a casting
protocol, a network endpoint, a device class, or a rendering target other than
"a document this host can load." This is the Step 6/Step 7 boundary enforced
at the schema level, not just by convention.
---
## 6. Discovery Proposal
Surfaces are discovered exactly where targets and capabilities are discovered:
in the `describe.result` response, as a new top-level array:
```json
{
"xzbt": "5.3",
"type": "describe.result",
"requestId": "req-010",
"sessionId": "sess-7f2a",
"exhibit": { "product": "museum-gallery", "version": "0.1.0", "build": "dev" },
"contract": { "major": 5, "minor": 3 },
"registryRevision": 1,
"stateRevision": 4,
"capabilities": [],
"targets": [],
"surfaces": [
{ "id": "surface.control", "label": "Control Room", "kind": "surface", "primary": true, "url": "control.html" },
{ "id": "surface.artifact", "label": "Artifact Display", "kind": "surface", "primary": false, "url": "artifact.html" },
{ "id": "surface.info-wall", "label": "Information Wall", "kind": "surface", "primary": false, "url": "info-wall.html" }
]
}
```
- `surfaces` is governed by `registryRevision`, identically to `targets`. A
`registry.changed` event MUST cause NGN to re-run `describe`, which
re-reads the current surface set along with the current target set. There
is no separate "surface revision" counter — one registry, one revision,
covering both targets and surfaces (Section 9).
### 6.1 Malformed individual entries
A malformed *individual* surface entry (missing `id`/`label`/`url`, invalid
`id` grammar per §8.1, non-relative or unresolvable `url` per Section 6.3) is
handled the same way a malformed target entry is already handled: the host
SHOULD skip only that entry and log a diagnostic, rather than discarding the
entire `surfaces` array. This mirrors the existing pattern in
`src/validation.js` and must be proven, not merely asserted, in Phase 6.3.
### 6.2 `primary` — structural invariant and backward compatibility
This is tightened relative to the prior revision to remove ambiguity.
**Three, and only three, recognized forms of `surfaces`:**
1. **Field absent.** The exhibit does not advertise multi-surface support at
all — an ordinary Contract 5.2 exhibit, or a 5.3 exhibit that has not
adopted the feature. A 5.3-aware host MUST behave exactly as NGN does
today: treat the exhibit's currently-loaded document/frame as one
implicit primary surface, with no surface picker UI, no `surfaces`
validation, and no behavior change from Step 5. This is the sole
legacy/compatibility path and needs no special-casing beyond "the field
isn't there."
2. **Field present and empty (`[]`).** Treated **identically** to the field
being absent (form 1). This removes the ambiguity left open in the prior
revision: an exhibit MAY emit `surfaces: []` (e.g. because it computes the
field programmatically) without that being treated as an error or as
"zero surfaces available." A host MUST NOT distinguish `[]` from absence.
3. **Field present and non-empty.** The array MUST contain **exactly one**
entry with `primary: true`. This is a *structural* invariant over the
whole array, not a per-entry validation concern (unlike the field-level
checks in Section 6.1). If the array contains zero `primary: true`
entries, or more than one, the **entire `surfaces` array is rejected as
malformed** — not just the offending entries — and the host falls back to
form 1 behavior (implicit single primary surface = current frame), logging
one clear diagnostic identifying the exhibit and the violation. This
fallback exists specifically so a broken multi-surface descriptor
degrades to "acts like Step 5" rather than to an undefined or partially
rendered surface list.
**Why this matters:** `primary` is what lets a 5.3-aware host that has *not*
been updated with any surface-picker UI still do the right thing by default
(open the primary surface, ignore the rest) — and it is what tells a fully
updated host which surface to treat as "the" exhibit view when no operator
choice has been made yet. Exactly one candidate for that role must exist
whenever `surfaces` claims to describe more than nothing.
### 6.3 URL resolution
`url` MUST be one of:
- a path relative to the exhibit's own base document location — the same
base URL NGN already resolved to load the exhibit's primary document in
the first place (i.e., the same resolution basis `src/connection.js` uses
today for the initial exhibit URL, not NGN's own admin-page location, and
not the requesting surface's future location);
- such a relative path with an appended query string and/or fragment
(`index.html?view=observation`, `control.html#panel-2`);
- a bare query string and/or fragment with no path segment
(`#observation`, `?surface=observation`), for a single-page exhibit where
surfaces are views within one already-served document rather than separate
files. In this form, resolution yields the exhibit's own base document URL
with that query/fragment applied.
**Resolution algorithm:**
1. Start from the exhibit's currently-established base URL — the same
absolute URL already used to load the exhibit and already validated by
`src/connection.js`'s same-origin/path-containment checks.
2. Resolve `url` against that base using standard relative-URL resolution.
3. The resolved absolute URL MUST remain same-origin with the base (Contract
§25's same-origin requirement extended to surfaces).
4. The resolved path component MUST pass the same path-containment check
`server/serve.js` already applies to the primary exhibit path (confined to
`public/`, `src/`, or `test-fixtures/`, no `..` escape).
5. `url` values that are absolute (`https://…`), protocol-relative
(`//…`), or resolve cross-origin or outside the served roots MUST be
rejected at step 3 or 4 as a malformed individual entry (Section 6.1) —
they do not invalidate the rest of the array.
This makes explicit what was previously only stated as a prohibition:
surface URLs are resolved on exactly the same basis, and validated by
exactly the same containment logic, as the primary exhibit document is
today. No new resolution concept is introduced.
---
## 7. State Synchronization Model
This is the section the whole feature stands or falls on, per the Step 6
brief's critical architectural rule.
### 7.1 One session, one state, many views
A surface does **not** open its own contract session. All surfaces of one
exhibit instance share the exhibit's single `sessionId`, single
`stateRevision` history, and single event `sequence` stream, exactly as
defined in Contract §5, §14, and §16 today. Multi-surface support adds zero
new session or state-authority concepts — it only adds more places that
*read* the one existing truth and more places a native interaction can
*originate from*.
### 7.2 The generic surface-attachment mechanism
Revision 1 left this as an unresolved implementation choice. This revision
defines a concrete, generic pattern every multi-surface exhibit is expected
to implement, independent of how many documents or windows are involved.
**The pattern has two required properties, one required sequence, and two
permitted transport shapes.**
**Required properties:**
- Exactly one Exhibit State Core exists per exhibit instance (Section 2).
Every surface attaches to that one Core. No surface ever instantiates a
second Core, a cached copy of state, or an independent computation of
state.
- Attachment is a runtime relationship between a surface document and the
Core, entirely internal to the exhibit. It is not part of the XZBT Exhibit
Contract and does not appear in Contract 5.3 — the contract only needs to
know that surfaces exist and how NGN opens one (Section 6). This mirrors
Contract §4's transport independence: the contract defines semantics, not
one mandatory internal wiring.
**Required attachment sequence** (identical regardless of transport shape
below):
1. The surface document loads and requests attachment from the Core.
2. The Core responds with the current authoritative state snapshot — sourced
from the same internal read path the contract adapter itself already uses
to answer `state.get`, not a second computation — and the current
`stateRevision`.
3. The Core registers the surface as a subscriber for ongoing
`state.changed` / `selection.changed` / relevant event notifications.
4. Any native interaction originating in the surface calls the Core's one
canonical mutation entry point (Section 7.4) — the same entry point a
contract `set`/`invoke` from NGN already uses.
5. On detach (surface closed), the Core drops the subscription. No state is
held by the surface, so nothing needs to be reconciled or discarded.
**Two permitted transport shapes for attachment** (an exhibit MUST implement
at least one; which one is an exhibit implementation decision, not a
contract requirement):
- **In-process attachment.** The surface is a view rendered within the same
JavaScript runtime/document that owns the Core — e.g. a single-page
exhibit that swaps visible panels, or a document that embeds other
surfaces as same-document components. Attachment is a direct in-memory
subscription; no cross-document transport is involved.
- **Cross-document attachment.** The surface runs in a separate browsing
context (its own window/tab, its own `url` per Section 6.3) and attaches
to the Core over a same-origin, exhibit-internal channel — e.g.
`BroadcastChannel`, a `SharedWorker`, or same-origin `postMessage` to
whichever document hosts the Core (typically the primary surface's
document). This channel is entirely separate from, and must not be
confused with, the NGN↔exhibit contract transport (Contract §4); it
carries no contract envelope and is never observed by NGN.
The Museum Gallery reference exhibit (Phase 6.2) is required to implement and
prove one concrete instance of this pattern — expected to be cross-document
attachment, since its surfaces are separate documents/windows opened by NGN
(Section 8) — and to document it as the reusable template Phase 6.7 adapts
for SciFi-XZBT's Observation surface. Phase 6.2 MAY also demonstrate
in-process attachment if useful for the control surface specifically, but at
least one cross-document instance must exist to prove the multi-window case
the brief requires.
### 7.3 How a surface receives ongoing state changes
Covered by the attachment sequence in 7.2 (steps 2–3): a surface never
polls; it subscribes at attachment time and receives the same
`state.changed`/`selection.changed` notifications the Core already emits
internally, over whichever transport shape (in-process or cross-document)
its attachment uses.
### 7.4 Native interaction routing (the canonical mutation path)
A user acting on any surface — clicking a control on the "Artifact Display,"
adjusting a slider on the "Information Wall" — MUST result in exactly the
same internal mutation call the exhibit's existing single-surface UI would
make, which is the same call the contract adapter uses to satisfy an
NGN-issued `set`/`invoke`. There must be exactly **one** function/method per
mutable target that changes exhibit state, on the Exhibit State Core itself;
every UI element on every surface, and every contract `set`/`invoke` from
NGN, calls into that same function. This is not new architecture — it is the
existing single-authoritative-state requirement from Contract §14, restated
for the case where more than one DOM document can trigger it.
Concretely for the reference exhibit: the same `contract-adapter.js` /
`exhibit.js` core already used by the Step 5 reference fixtures (see
`test-fixtures/reference-exhibits/shared/contract-core.js`) is the pattern to
extend into a proper Exhibit State Core, not replace. A surface's document is
a thin presentation layer attached to that core; it must not contain a
second, parallel copy of state or mutation logic.
### 7.5 What "no duplicate authoritative state" rules out
Explicitly disallowed by this model, matching the brief's stated
anti-pattern:
- launching a separate exhibit instance (a second `hello`/session with its
own `stateRevision` history) per surface;
- a surface document that keeps its own local copy of state and only
periodically reconciles it, rather than attaching per Section 7.2;
- a surface whose native interactions call an exhibit-internal function that
bypasses the Core's one canonical mutation entry point;
- two surfaces attaching to two different Core instances of the same
exhibit, however attachment is transported.
---
## 8. Lifecycle
A surface descriptor's existence in `surfaces` only establishes that the
surface is **available**. Whether it is currently shown is host-side,
per-surface, per-session bookkeeping — not exhibit state, and not persisted
across a full exhibit reload.
| State | Meaning | Who tracks it |
| --- | --- | --- |
| `available` | The surface is discoverable via `describe` but no host action has been taken on it. | Derived from `surfaces` array; not separately tracked. |
| `opened` | NGN has loaded the surface's document (Step 6: in a local browser window/view), which then performs the attachment sequence in Section 7.2. | NGN, per session. |
| `visible` | The opened surface's window/view currently has visual presence (not minimized/backgrounded). Best-effort; browsers do not always expose this reliably. | NGN, best-effort. |
| `hidden` | Opened but not currently visible (backgrounded, minimized). | NGN, best-effort. |
| `closed` | NGN has torn down the surface's window/view; the surface's document detaches from the Core (Section 7.2, step 5). The surface remains `available` for reopening. | NGN, per session. |
| `unavailable` | A `requires` capability (Section 5.2) is not `ready`. The surface stays listed but SHOULD be presented as non-operable. | NGN, derived from `capabilities`. |
Lifecycle transitions are entirely local bookkeeping on the NGN side about
*presentation*, not contract-visible exhibit state. Opening, closing, or
reopening a surface MUST NOT itself cause a `set`/`invoke`, MUST NOT change
`stateRevision`, and MUST NOT be recorded as an `action.executed` event. It
may optionally be logged as an NGN-local diagnostic entry, exactly as
`src/host.js` already logs connection lifecycle events today.
**Reopen behavior.** When a previously-closed surface is opened again, its
document performs the same attachment sequence as a first open (Section
7.2). Because state lives in the Core, not in the surface, a reopened
surface reflects current state automatically — there is nothing to "restore"
at the surface level.
---
## 9. Session/Revision Implications
- `registryRevision` covers `surfaces` in addition to `targets`/`capabilities`.
No separate surface-registry counter is introduced. A `registry.changed`
event already means "re-run `describe`"; that now also refreshes the known
surface set.
- `stateRevision` and event `sequence` are entirely unaffected by
multi-surface support — they remain properties of the one session, per
Contract §14 and §16, regardless of how many surfaces are open or how they
attach to the Core.
- **Reconnect.** On session loss and reconnect (existing `src/connection.js`
behavior), NGN re-runs the full negotiation and rediscovery, which
naturally re-obtains the current `surfaces` array. Any currently-open
surface windows are host-side presentation state and are NOT automatically
torn down by a reconnect; whether they should be is a Phase 6.5/6.6
implementation question (recommend: leave open, let the surface's own
document's attachment to the Core recover independently, rather than NGN
force-closing surface windows on transient session loss).
- **Are surface definitions static per registry revision?** Yes. Within one
`registryRevision`, the `surfaces` array is a stable snapshot, exactly like
`targets`. An exhibit that wants to change its surface set (add/remove a
surface) MUST bump `registryRevision` and emit `registry.changed`, per the
existing §23 mechanism — no new mechanism needed.
---
## 10. Standalone Behavior
A standalone exhibit — opened directly in a browser tab, with no NGN attached
— MUST continue to work with zero dependency on this model, per Contract §2's
governing rule. This revision relaxes the prior draft's requirement that
*every* surface be independently openable without any other document present,
because that conflicted with the cross-document attachment shape defined in
Section 7.2 (a surface attaching via `postMessage`/`BroadcastChannel` to
whichever document hosts the Core may genuinely need that document to already
be open).
The precise, tightened requirement:
- **The primary surface** (Section 6.2) MUST remain fully, unconditionally
standalone-capable: a person navigating directly to the exhibit's normal
entry point (its existing `index.html`) gets a complete, independently
usable experience with zero dependency on NGN, on any other surface being
open, or on any attachment sequence having occurred. This is the exhibit's
existing standalone guarantee, entirely unchanged by Step 6. Nothing about
standalone use of the primary surface requires a person to know surfaces
exist.
- **Non-primary surfaces** SHOULD remain directly openable without NGN
whenever the exhibit's chosen attachment mechanism allows it:
- an exhibit using **in-process attachment**, or a **cross-document**
mechanism where the surface can bootstrap its own Core connection
on demand (e.g. attaching to a `SharedWorker` that starts itself), can
and should support a non-primary surface being opened first, with no
other document present — matching how SciFi-XZBT's existing Observation
view already behaves today;
- an exhibit using **cross-document attachment that depends on the primary
document already being open** (e.g. plain `postMessage` to a specific
existing window) MAY require the primary surface to be open first for a
non-primary surface to attach successfully. This is an accepted
consequence of an exhibit's internal transport choice (Section 7.2), not
a contract violation, and MUST NOT be worked around by having the
non-primary surface silently start a second Core.
- In either case, this is a same-origin, exhibit-internal dependency
between the exhibit's own documents — never a dependency on NGN. A
non-primary surface opened without NGN and without its dependency met
SHOULD degrade to a clear "waiting for exhibit" state rather than
silently diverging into independent state.
- Nothing about surface discovery itself requires network access, a host, or
any NGN-specific code inside the exhibit. `surfaces` is just more
`describe` metadata; an exhibit run standalone never calls `describe` on
itself.
---
## 11. Host (NGN) Behavior
- On `describe`, NGN parses `surfaces` alongside `targets`/`capabilities`
using the validation discipline in Sections 6.1–6.2: tolerate individually
malformed entries, but reject the whole array (falling back to implicit
single-primary behavior) on a `primary` structural violation.
- NGN's admin/control UI (`src/ui.js`) gains a generic, descriptor-driven
surface list — rendered from `label`/`role`/`primary`, never from any
hard-coded surface name. This is the direct analog of the existing generic
target-rendering rule in the NGN Implementation Plan §8; no exhibit
vocabulary may leak into `src/`.
- Opening a surface (Phase 6.4) means NGN loads that surface's resolved `url`
(Section 6.3) into a new local browser window/view, same-origin, using the
same hosting mechanism `server/serve.js` already provides for the primary
exhibit frame today.
- NGN's control UI and any number of open surface windows coexist; closing
or reloading a surface window never tears down the underlying exhibit
session, and disconnecting the exhibit session (existing Disconnect
behavior) SHOULD close any surface windows NGN opened, since they have
nothing left to observe.
- A single-surface exhibit (ordinary case, including every Step 5 reference
fixture, and every exhibit using discovery form 1 or 2 from Section 6.2)
continues to work with **zero NGN behavior change**: one implicit or
declared primary surface, opened automatically into the one frame NGN
already loads today, with no surface picker UI shown when there is nothing
to pick between.
---
## 12. Non-Goals (Explicitly Out of Scope for Step 6)
Restating the brief's guardrails as binding scope boundaries for this
document and everything built from it:
- Casting, Chromecast, Google TV, Android clients, remote/network display
endpoints — all Step 7.
- Any encoding of a physical or network display target inside a surface
descriptor.
- MIDI, MCP, webhooks, scenarios, recording, telemetry acquisition,
multi-exhibit orchestration, databases, cloud services, user accounts.
- Any redesign of Contract 5.2 behavior unrelated to surfaces.
- Any surface concept that requires per-surface authentication/authorization
beyond the existing same-origin session trust boundary (§25) — internet-
facing auth remains NGN's problem generally, unchanged by this feature.
- Standardizing the cross-document attachment transport (`BroadcastChannel`
vs. `SharedWorker` vs. `postMessage`) as a contract-level choice — Section
7.2 deliberately leaves this to the exhibit.
---
## 13. Security / Origin Considerations
- Every surface `url` resolves same-origin per the algorithm in Section 6.3,
a direct extension of Contract §25's same-origin `postMessage` validation
requirement (`event.origin` and `event.source` checks) to the new case of
multiple documents. A surface document is exactly as trusted, and exactly
as constrained, as the exhibit's primary document already is.
- The exhibit-internal attachment channel (Section 7.2) — `BroadcastChannel`,
`SharedWorker`, or same-origin `postMessage` — inherits the same
same-origin trust boundary. It carries no contract envelope and MUST NOT be
reachable from any other origin; this is ordinary same-origin browser
isolation, not a new security mechanism.
- No surface descriptor field may contain executable markup, a remote origin,
or a URL scheme other than a relative path/fragment into the served
exhibit. This mirrors the existing safe-text-injection rule (§20) applied
to the new descriptor type.
- NGN's server (`server/serve.js`) already restricts served paths to
`public/`, `src/`, and `test-fixtures/` and denies path escapes; surface
`url` values are subject to the same path-containment validation (Section
6.3, step 4) before the host will load them — a malformed or escaping
`url` is a rejected individual entry (Section 6.1), not a followed one.
- Multiple surface documents observing one session is a same-origin,
same-trust-boundary fan-out, not a new external trust relationship. No new
authentication concept is introduced in Step 6.
---
## 14. Contract-Version Decision — APPROVED, NOT YET MINTED
### 14.1 Decision
**The owner has approved Contract 5.3 as the intended version for
multi-surface presentation.** This is no longer a pending recommendation; it
is the settled architectural direction this document and Phase 6.2 onward
are written against.
**What remains explicitly deferred, per this instruction, until separately
authorized:**
- minting the actual versioned file
(`docs/contract/XZBT-Exhibit-Contract-Specification-v5.3.md`);
- any change to `contract.major`/`contract.minor` reported by real
`describe.result` responses;
- any edit to the existing, currently-normative
`XZBT-Exhibit-Contract-Specification-v5.2.md` document.
This document (6.1) continues to illustrate `describe.result` examples as
`"xzbt": "5.3"` / `contract: {major: 5, minor: 3}` (Section 6) purely as the
**target shape** the eventual 5.3 document will formalize — this is
illustrative design content, not a claim that the file or the reported
version exists yet.
### 14.2 Why 5.3 (retained from Revision 1, unchanged)
`describe.result` gains a new top-level array, `surfaces`. This is additive
in the sense that an unaware consumer can ignore an unknown field — but
Contract §28.2 is explicit: *"Backward-compatible additions may increase the
minor version."* A new, normatively defined top-level response field with its
own validation rules (Section 6), its own descriptor grammar (Section 5), and
its own required/optional field contract is exactly the category of change
§28.2 describes, not a same-version clarification. Step 5's `arguments` field
addition (Contract §9.5) was explicitly scoped as *"clarifies Contract 5.2;
it does not introduce Contract 5.3"* — because it formalized behavior that
was already implicitly required (impulse arguments had to be validated
somehow) without adding a new discoverable construct. Surfaces are different:
nothing in 5.2 implies surfaces exist, and no 5.2-conformant exhibit or host
is required to know what `surfaces` means.
Contract major stays 5 — this is additive, not breaking. An exhibit that
only implements 5.2 behavior remains fully conformant; it simply never
emits `surfaces` (Section 6.2, form 1), and a 5.3-aware host tolerates that
identically to an exhibit that emits `surfaces: []` (form 2) or a single
`primary` entry (form 3). A 5.3-aware host MUST remain fully capable of
driving a 5.2-only exhibit exactly as it does today.
### 14.3 What still requires owner sign-off before the file is minted
- Timing: whether to mint the versioned file once this 6.1 design is
approved, or defer the formal document bump until the surface model has
additionally been proven out end-to-end in the reference exhibit (Phases
6.2–6.6).
- Any wording changes to the *existing* 5.2 document (this proposal
recommends none — 5.3 is additive-only — but that remains a decision to
reconfirm at minting time).
---
## 15. Open Questions
Revision 1's Open Question 1 (empty vs. absent `surfaces`) is now resolved by
Section 6.2 and removed from this list.
1. Should `role` (Section 5.2) start as free text or a small closed
enumeration? This proposal leaves it free text for 6.1–6.6 and defers
tightening it until real reference-exhibit and SciFi-XZBT usage exists to
generalize from.
2. Exact behavior when a currently-open surface's descriptor disappears from
a new `describe` result (e.g. `registryRevision` bump removes a surface
that is currently open in a window) — recommend NGN closes the window and
surfaces a diagnostic, but this needs to be proven in Phase 6.5/6.6, not
just asserted here.
3. Whether `requires` on a surface (Section 5.2) should block *opening* the
surface outright, or only annotate it as degraded while still allowing
open (consistent with how a target with an unavailable capability remains
discoverable per §9). This proposal recommends the latter, for
consistency, but flags it for confirmation during Phase 6.3.
4. Whether the generic attachment mechanism (Section 7.2) should eventually
be *documented* (not contractually mandated) as a recommended pattern in
the Authoring Guide, once the reference exhibit and SciFi-XZBT adaptation
have both proven it out — so future exhibit authors aren't reinventing
attachment transport choices from scratch. Recommend deferring this
documentation question to after Phase 6.8.
---
## 16. Acceptance Criteria for 6.1 (Revision 2)
This document satisfies Phase 6.1 when:
- [x] It defines what a presentation surface is and is not (Sections 2–3).
- [x] It defines the surface descriptor, required and optional fields
(Section 5), with surface IDs conforming exactly to the existing
canonical target-ID grammar (Section 5.1) — no carve-out.
- [x] It defines discovery as an extension to `describe` governed by
`registryRevision` (Sections 6, 9), with a tightened, unambiguous
`primary`/backward-compatibility invariant covering exactly three
recognized forms of `surfaces` (Section 6.2).
- [x] It defines an explicit, generic surface-attachment mechanism — required
properties, a required attachment sequence, and two permitted
transport shapes — that any exhibit implementation can follow without
inventing its own protocol (Section 7.2).
- [x] It defines an explicit URL-resolution algorithm for the surface `url`
field, including same-origin and path-containment enforcement (Section
6.3).
- [x] It defines a state-synchronization model with a single authoritative
state (the Exhibit State Core) shared by all surfaces, and explicitly
rules out per-surface duplicated state (Section 7).
- [x] It defines the surface lifecycle (Section 8).
- [x] It defines ownership across exhibit / NGN / transport / display
endpoint (Section 4), explicitly deferring display endpoints to Step 7.
- [x] It defines standalone-exhibit compatibility with a precise,
non-conflicting requirement split between the primary surface
(unconditional) and non-primary surfaces (best-effort, attachment-
mechanism-dependent) (Section 10).
- [x] It defines security/origin assumptions, extended to the attachment
channel (Section 13).
- [x] It records the owner-approved Contract 5.3 decision, with the file
mint and contract-document edits still explicitly deferred (Section
14).
- [x] It lists genuine remaining open questions rather than inventing answers
where none are warranted (Section 15).
- [x] It does not begin implementation, does not create the Contract 5.3
file, and does not modify existing source or contract documents.
**Next step, upon final owner approval of this revision:** mint the
versioned Contract 5.3 file per Section 14.3's timing decision, then begin
Phase 6.2 — build the Museum Gallery reference exhibit proving this model.
Neither has begun as part of this document.