@ggui-ai/protocol-conformance 0.1.0-rc.1

package/dist/conformance-host.js

@@ -0,0 +1,45 @@
+/**
+ * `ConformanceHost` — the seam between the kit's authored fixtures
+ * and the implementation under test.
+ *
+ * Most fixtures declare `setup` / `teardown` directives (see
+ * {@link SetupStep} / {@link TeardownStep} in `./types`) that the host
+ * dispatches against its live server. v1.0 of the kit does NOT
+ * require implementations to ship a host — fixtures that need setup
+ * directives skip cleanly when `runConformance()` is called without
+ * a `host`.
+ *
+ * When a host IS provided, the runner calls `dispatchSetup()` for
+ * every step before driving the fixture's `inputEnvelope`, then
+ * `dispatchTeardown()` for every step after the assertion. Unknown
+ * `kind` values MUST throw so unimplemented directives surface as a
+ * test SKIP with a clear "host does not implement X" reason — never
+ * a silent pass.
+ *
+ * ## Extensibly-closed
+ *
+ * The concrete step vocabulary below mirrors `./types`' vocabulary
+ * but is re-exported here as a host-facing narrower form:
+ *   - Every arm carries the full semantic payload (not the JSON-
+ *     loader's `unknown`-fields view).
+ *   - The tail `(Record<string, unknown> & { readonly kind: string & {} })`
+ *     catches fixture-JSON directives the host hasn't wired — the host
+ *     returns by throwing, the runner maps it to a skip.
+ *
+ * Third-party hosts MAY extend either union with additional arms by
+ * augmenting the declaration in their own module. v1.0 of the kit
+ * does not require exhaustive coverage — it requires *honest*
+ * coverage: either implement the directive OR throw, never silently
+ * succeed on an unknown kind.
+ *
+ * ## Relation to `./types`
+ *
+ * `./types` defines the JSON-authoring surface: every directive has
+ * optional-by-default fields so JSON authors don't have to think
+ * about shape. This module defines the *runtime* surface: once the
+ * loader has validated a directive, the host receives a narrowed
+ * form. The two are intentionally parallel but not identical — JSON
+ * loaders accept what the author wrote; hosts receive what the
+ * runner confirmed is shape-valid.
+ */
+export {};

package/dist/fixtures/bootstrap-protocol/bootstrap-bundle-fetch-failed.json

@@ -0,0 +1,26 @@
+{
+    "name": "bootstrap-bundle-fetch-failed",
+    "description": "Thin shell reads a valid `_meta.ggui.bootstrap.runtimeUrl` but the `<script src>` errors (network failure / 404 / CSP reject). Shell emits `postMessage({type:'ggui:bootstrap-failed', reason:'BUNDLE_FETCH_FAILED', message})` to the parent. No WS opens.",
+    "skipReason": null,
+    "setup": [
+        { "type": "create-session", "sessionId": "ck-bundle-fetch-failed-1" },
+        {
+            "type": "renderer-url-override",
+            "sessionId": "ck-bundle-fetch-failed-1",
+            "url": "http://127.0.0.1:1/does-not-exist.js"
+        }
+    ],
+    "inputEnvelope": {
+        "type": "render",
+        "sessionId": "ck-bundle-fetch-failed-1",
+        "resource": {
+            "uri": "ui://ggui/session"
+        }
+    },
+    "expectedBehavior": {
+        "kind": "bootstrap-failure",
+        "reason": "BUNDLE_FETCH_FAILED",
+        "messageContains": "Runtime bundle failed to load"
+    },
+    "teardown": [{ "type": "close-session", "sessionId": "ck-bundle-fetch-failed-1" }]
+}

package/dist/fixtures/bootstrap-protocol/bootstrap-meta-missing.json

@@ -0,0 +1,32 @@
+{
+    "name": "bootstrap-meta-missing",
+    "description": "Host's `ui/initialize` response returns a tool-output without `_meta.ggui.bootstrap` (or missing the `runtimeUrl` field). Thin shell emits `postMessage({type:'ggui:bootstrap-failed', reason:'BOOTSTRAP_META_MISSING', message})` to the parent. No WS connection opens — live-channel envelopes are out of scope pre-handshake.",
+    "skipReason": null,
+    "setup": [
+        { "type": "create-session", "sessionId": "ck-bootstrap-meta-missing-1" },
+        {
+            "type": "ui-initialize-response-override",
+            "sessionId": "ck-bootstrap-meta-missing-1",
+            "override": {
+                "toolOutput": {
+                    "_meta": {
+                        "ggui": {}
+                    }
+                }
+            }
+        }
+    ],
+    "inputEnvelope": {
+        "type": "render",
+        "sessionId": "ck-bootstrap-meta-missing-1",
+        "resource": {
+            "uri": "ui://ggui/session"
+        }
+    },
+    "expectedBehavior": {
+        "kind": "bootstrap-failure",
+        "reason": "BOOTSTRAP_META_MISSING",
+        "messageContains": "_meta.ggui.bootstrap"
+    },
+    "teardown": [{ "type": "close-session", "sessionId": "ck-bootstrap-meta-missing-1" }]
+}

package/dist/fixtures/bootstrap-protocol/bootstrap-success.json

@@ -0,0 +1,17 @@
+{
+    "name": "bootstrap-success",
+    "description": "Happy-path boot: host reads `_meta.ui.resourceUri`, fetches `ui://ggui/session`, the thin shell loads the renderer bundle, `ui/initialize` returns valid `_meta.ggui.bootstrap.{wsUrl, token, sessionId, appId, runtimeUrl}`, WS handshake succeeds, first stack item renders with `data-ggui-code-ready=\"true\"`. No bootstrap-failed postMessage, no contract-error, no upgrade-required.",
+    "skipReason": null,
+    "setup": [{ "type": "create-session", "sessionId": "ck-bootstrap-success-1" }],
+    "inputEnvelope": {
+        "type": "render",
+        "sessionId": "ck-bootstrap-success-1",
+        "resource": {
+            "uri": "ui://ggui/session"
+        }
+    },
+    "expectedBehavior": {
+        "kind": "bootstrap-success"
+    },
+    "teardown": [{ "type": "close-session", "sessionId": "ck-bootstrap-success-1" }]
+}

package/dist/fixtures/bootstrap-protocol/index.d.ts

@@ -0,0 +1,5 @@
+import type { TestCase } from '../../types.js';
+/** All fixtures asserting the bootstrap contract (Protocol #5 — named
+ *  failure modes + SPEC §8 `GguiBootstrapMeta`). */
+export declare const bootstrapProtocolFixtures: readonly TestCase[];
+//# sourceMappingURL=index.d.ts.map

package/dist/fixtures/bootstrap-protocol/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/fixtures/bootstrap-protocol/index.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;oDACoD;AACpD,eAAO,MAAM,yBAAyB,EAAE,SAAS,QAAQ,EAIxD,CAAC"}

package/dist/fixtures/bootstrap-protocol/index.js

@@ -0,0 +1,24 @@
+/**
+ * `bootstrap-protocol` fixture sub-module.
+ *
+ * Exercises the MCP Apps bootstrap contract (SPEC §8):
+ *   - `ui/initialize` tool-result must stamp `_meta.ggui.bootstrap`
+ *     with a well-formed envelope.
+ *   - Renderer-bundle fetch must succeed (or surface a typed
+ *     `BOOTSTRAP_FAILURE` protocol error).
+ *   - Happy-path boot reaches `data-ggui-code-ready="true"` with no
+ *     error frames.
+ *
+ * Three fixtures today; `bootstrap-success` drives against the
+ * current harness, the other two are `ConformanceHost`-gated.
+ */
+import bootstrapBundleFetchFailed from './bootstrap-bundle-fetch-failed.json' with { type: 'json' };
+import bootstrapMetaMissing from './bootstrap-meta-missing.json' with { type: 'json' };
+import bootstrapSuccess from './bootstrap-success.json' with { type: 'json' };
+/** All fixtures asserting the bootstrap contract (Protocol #5 — named
+ *  failure modes + SPEC §8 `GguiBootstrapMeta`). */
+export const bootstrapProtocolFixtures = [
+    bootstrapBundleFetchFailed,
+    bootstrapMetaMissing,
+    bootstrapSuccess,
+];

package/dist/fixtures/canvas-mode-wire-shapes/canvas-bootstrap-mutual-exclusion.json

@@ -0,0 +1,25 @@
+{
+    "name": "canvas-bootstrap-mutual-exclusion",
+    "description": "Bootstrap with both `canvasMode: true` AND `stackItemId` is malformed — canvas iframes are session-scoped (no pinned stack item). Defensive parsers SHOULD reject; the protocol does not require them to. Reference parser (`@ggui-ai/iframe-runtime` `validateBootstrapMeta`) currently accepts the combination but the field-pair has no defined consumer semantics. This fixture pins the contract intent so future parsers can opt into strict rejection without surprise.",
+    "skipReason": null,
+    "setup": [
+        { "type": "create-session", "sessionId": "ck-canvas-bootstrap-exclusion-1" },
+        {
+            "type": "set-app-mode",
+            "appId": "ck-canvas-bootstrap-exclusion-app",
+            "defaultMcpAppsMode": "canvas"
+        }
+    ],
+    "inputEnvelope": {
+        "type": "render",
+        "sessionId": "ck-canvas-bootstrap-exclusion-1",
+        "resource": {
+            "uri": "ui://ggui/session/ck-canvas-bootstrap-exclusion-1"
+        }
+    },
+    "expectedBehavior": {
+        "kind": "bootstrap-success",
+        "observabilitySequence": []
+    },
+    "teardown": [{ "type": "close-session", "sessionId": "ck-canvas-bootstrap-exclusion-1" }]
+}

package/dist/fixtures/canvas-mode-wire-shapes/canvas-lifecycle-channel-emits-handshake-started.json

@@ -0,0 +1,30 @@
+{
+    "name": "canvas-lifecycle-channel-emits-handshake-started",
+    "description": "When a canvas-mode session (`mcpAppsMode === 'canvas'`) enters `ggui_handshake`, the server publishes a `_ggui:lifecycle` envelope with `CanvasLifecyclePayload {kind: 'handshake_started', handshakeId, intent}` BEFORE the handshake completes. Animator pill state machine advances on receipt. Discriminator-narrowing: payload's `kind` field is the union tag; unknown `kind` values drop with a no-op on the iframe side. Fire-and-forget on the server: failure to publish degrades the animator (no pill state change) but MUST NOT abort the handshake's primary result.",
+    "skipReason": null,
+    "setup": [
+        { "type": "create-session", "sessionId": "ck-canvas-lifecycle-handshake-1" },
+        {
+            "type": "set-app-mode",
+            "appId": "ck-canvas-lifecycle-handshake-app",
+            "defaultMcpAppsMode": "canvas"
+        }
+    ],
+    "inputEnvelope": {
+        "type": "action",
+        "channel": 0,
+        "sessionId": "ck-canvas-lifecycle-handshake-1",
+        "action": {
+            "name": "ggui_handshake",
+            "data": { "intent": "test" }
+        }
+    },
+    "expectedBehavior": {
+        "kind": "stream-update",
+        "channel": "_ggui:lifecycle",
+        "value": {
+            "kind": "handshake_started"
+        }
+    },
+    "teardown": [{ "type": "close-session", "sessionId": "ck-canvas-lifecycle-handshake-1" }]
+}

package/dist/fixtures/canvas-mode-wire-shapes/canvas-navigated-updates-active-stack-item.json

@@ -0,0 +1,30 @@
+{
+    "name": "canvas-navigated-updates-active-stack-item",
+    "description": "Client emits a `canvas_navigated` WS message (Client→Server) carrying `{sessionId, previousActiveItemId, activeItemId}`. Server updates `Session.activeStackItemId` to `activeItemId` (or null when the user popped to empty). Subsequent `ggui_consume` calls observe the new active pipe. Payload omits `appId` — the subscriber binding is the authoritative scope; an inbound message scoped to a wrong session is rejected with `SESSION_MISMATCH` rather than implicit reroute.",
+    "skipReason": null,
+    "setup": [
+        { "type": "create-session", "sessionId": "ck-canvas-navigated-1" },
+        {
+            "type": "seed-channel",
+            "sessionId": "ck-canvas-navigated-1",
+            "channel": "_internal:stack",
+            "value": [
+                { "id": "item-a", "type": "component" },
+                { "id": "item-b", "type": "component" }
+            ]
+        }
+    ],
+    "inputEnvelope": {
+        "type": "canvas_navigated",
+        "payload": {
+            "sessionId": "ck-canvas-navigated-1",
+            "previousActiveItemId": "item-b",
+            "activeItemId": "item-a"
+        }
+    },
+    "expectedBehavior": {
+        "kind": "no-op",
+        "reason": "canvas_navigated has no synchronous response envelope — the side effect is a Session field mutation observed via subsequent ggui_consume / handshake output."
+    },
+    "teardown": [{ "type": "close-session", "sessionId": "ck-canvas-navigated-1" }]
+}

package/dist/fixtures/canvas-mode-wire-shapes/host-context-observed-persists.json

@@ -0,0 +1,22 @@
+{
+    "name": "host-context-observed-persists",
+    "description": "Client iframe echoes the `McpUiHostContext` it received from `ui/initialize` via `host_context_observed` WS message (Client→Server). Server projects to `HostContextProjection` and persists on `Session.hostContext`. Persisted projection is observable via subsequent `ggui_handshake` and `ggui_consume` output. Field shape: `availableDisplayModes`, `displayMode`, `theme` — sourced verbatim from the spec-compliant host's `_meta.ui.host` projection. Stale-snapshot guard: a later `host_context_observed` overwrites earlier values.",
+    "skipReason": null,
+    "setup": [{ "type": "create-session", "sessionId": "ck-host-context-observed-1" }],
+    "inputEnvelope": {
+        "type": "host_context_observed",
+        "payload": {
+            "sessionId": "ck-host-context-observed-1",
+            "hostContext": {
+                "availableDisplayModes": ["inline", "pip", "fullscreen"],
+                "displayMode": "inline",
+                "theme": "light"
+            }
+        }
+    },
+    "expectedBehavior": {
+        "kind": "no-op",
+        "reason": "host_context_observed has no synchronous response — the side effect is `Session.hostContext` mutation observable via subsequent ggui_consume / handshake output."
+    },
+    "teardown": [{ "type": "close-session", "sessionId": "ck-host-context-observed-1" }]
+}

package/dist/fixtures/canvas-mode-wire-shapes/index.d.ts

@@ -0,0 +1,5 @@
+import type { TestCase } from '../../types.js';
+/** All fixtures asserting canvas-mode wire shapes (protocol
+ *  draft-2026-05-17). */
+export declare const canvasModeWireShapesFixtures: readonly TestCase[];
+//# sourceMappingURL=index.d.ts.map

package/dist/fixtures/canvas-mode-wire-shapes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/fixtures/canvas-mode-wire-shapes/index.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;yBACyB;AACzB,eAAO,MAAM,4BAA4B,EAAE,SAAS,QAAQ,EAK3D,CAAC"}

package/dist/fixtures/canvas-mode-wire-shapes/index.js

@@ -0,0 +1,47 @@
+/**
+ * `canvas-mode-wire-shapes` fixture sub-module.
+ *
+ * Exercises the canvas-mode wire additions (protocol draft-2026-05-17):
+ *
+ *   - `GguiBootstrapMeta.canvasMode` — discriminator + mutual-exclusion
+ *     with `stackItemId`. Canvas iframes are session-scoped; no pinned
+ *     item.
+ *   - `_ggui:lifecycle` reserved channel + `CanvasLifecyclePayload`
+ *     discriminated union (`handshake_started` / `handshake_completed` /
+ *     `push_started` / `consume_polling`). Server fires fire-and-forget;
+ *     iframe animator advances state machine on each kind.
+ *   - `canvas_navigated` C→S WS message — user back-navigated; server
+ *     updates `Session.activeStackItemId`. Payload omits `appId` —
+ *     subscriber binding is authoritative scope.
+ *   - `host_context_observed` C→S WS message — iframe echoes
+ *     `McpUiHostContext` so server persists `HostContextProjection` on
+ *     the session.
+ *
+ * All four fixtures ship with `skipReason: null`: the kit does not
+ * JSON-gate skip behavior. The runner dispatches every fixture and
+ * per-fixture skips emerge at RUNTIME from the host adapter throwing
+ * on an unimplemented setup directive (`set-app-mode`,
+ * `assert-session-field`, `assert-channel-envelope`) or from
+ * `match-behavior.ts` returning `unmatchable-on-ws`. Runner
+ * activation against the reference `ConformanceHost` is a follow-up
+ * kit minor once those directives land.
+ *
+ * Rationale: per the kit's drift discipline (see `../../types.ts`
+ * "Authored protocol vocabulary"), fixtures freeze the contract intent
+ * at the time the wire shape lands — not when the runner catches up.
+ * Third-party host implementers can read these JSONs directly to
+ * understand canvas-mode obligations without waiting for the reference
+ * host's directive coverage.
+ */
+import canvasBootstrapMutualExclusion from './canvas-bootstrap-mutual-exclusion.json' with { type: 'json' };
+import canvasLifecycleChannelEmitsHandshakeStarted from './canvas-lifecycle-channel-emits-handshake-started.json' with { type: 'json' };
+import canvasNavigatedUpdatesActiveStackItem from './canvas-navigated-updates-active-stack-item.json' with { type: 'json' };
+import hostContextObservedPersists from './host-context-observed-persists.json' with { type: 'json' };
+/** All fixtures asserting canvas-mode wire shapes (protocol
+ *  draft-2026-05-17). */
+export const canvasModeWireShapesFixtures = [
+    canvasBootstrapMutualExclusion,
+    canvasLifecycleChannelEmitsHandshakeStarted,
+    canvasNavigatedUpdatesActiveStackItem,
+    hostContextObservedPersists,
+];

package/dist/fixtures/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Fixture catalog — every conformance fixture, classified by the
+ * contract or protocol criterion it exercises.
+ *
+ * The sub-module layout (one directory per contract) is load-bearing:
+ * it is how the reporter groups results on the bar-scorecard output,
+ * and how third-party implementers understand which criterion each
+ * fixture asserts. Renaming a sub-module directory breaks the
+ * reporter's output shape — treat the classification as the public
+ * API.
+ *
+ * ## Why static imports
+ *
+ * The fixture JSON files are statically imported (`import … from
+ * './foo.json' with { type: 'json' }`) so tsc inlines the fixture
+ * data into `dist/fixtures/`. Third-party TS consumers get typed
+ * arrays without a runtime file-read. Non-TS consumers (Python, Go,
+ * Rust) read the raw `.json` files directly — they ship in `dist/`
+ * via the package's `files` field.
+ *
+ * ## Current coverage
+ *
+ * Seven sub-modules with content (18 fixtures). Three additional
+ * sub-modules (`data-contract`, `tool-name-uniqueness`,
+ * `contract-error-payload`) are reserved for additive fixture
+ * expansion and not yet materialized — adding fixtures there is a
+ * kit minor version.
+ *
+ * `canvas-mode-wire-shapes` (4 fixtures) ships the canvas-mode wire
+ * contract intent: `canvasMode` bootstrap discriminator,
+ * `_ggui:lifecycle` channel + payload, `canvas_navigated` +
+ * `host_context_observed` C→S WS messages. Runner activation is a
+ * follow-up kit minor once the reference `ConformanceHost` exposes
+ * `set-app-mode` + `assert-session-field` + `assert-channel-envelope`
+ * directives.
+ *
+ * ## What is NOT here — the gadget pure-function obligations
+ *
+ * SPEC §7.7.2's gadget obligations are pure-function obligations, not
+ * transport-observable behaviors: which `clientCapabilities` payloads
+ * a parser accepts (`../schema-conformance`) and which `(contract,
+ * appGadgets)` pairs the push-time registry gate accepts / rejects
+ * (`../registration-conformance`). They are graded against a
+ * caller-supplied function — there is no session, transport, or wire
+ * frame to drive — so they do NOT belong in this behavioral fixture
+ * catalog.
+ */
+export { bootstrapProtocolFixtures } from './bootstrap-protocol/index.js';
+export { canvasModeWireShapesFixtures } from './canvas-mode-wire-shapes/index.js';
+export { observabilityEventsFixtures } from './observability-events/index.js';
+export { refreshSemanticsFixtures } from './refresh-semantics/index.js';
+export { reservedChannelAuthorityFixtures } from './reserved-channel-authority/index.js';
+export { schemaVersionHandshakeFixtures } from './schema-version-handshake/index.js';
+export { wiredActionDispatchFixtures } from './wired-action-dispatch/index.js';
+import type { TestCase } from '../types.js';
+/**
+ * Contract slugs — match the sub-module directory names. The
+ * reporter uses these verbatim as group headers on the scorecard.
+ * Extensibly-closed via `(string & {})` so additive sub-modules
+ * register without an API break.
+ */
+export type ContractSlug = 'bootstrap-protocol' | 'canvas-mode-wire-shapes' | 'observability-events' | 'refresh-semantics' | 'reserved-channel-authority' | 'schema-version-handshake' | 'wired-action-dispatch' | (string & {});
+/**
+ * Every fixture the kit ships, grouped by the contract it exercises.
+ * Order within each group matches the sub-module's `export` order.
+ *
+ * Map shape is load-bearing — the runner iterates
+ * `Object.entries(fixturesByContract)` to produce the bar scorecard,
+ * and consumers iterate it for custom reporters.
+ */
+export declare const fixturesByContract: Readonly<Record<ContractSlug, readonly TestCase[]>>;
+/**
+ * Every fixture flat, in deterministic lexicographic order by
+ * `name`. Runners that don't care about classification iterate this
+ * list directly.
+ */
+export declare const allFixtures: readonly TestCase[];
+//# sourceMappingURL=index.d.ts.map

package/dist/fixtures/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fixtures/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,EAAE,4BAA4B,EAAE,MAAM,oCAAoC,CAAC;AAClF,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAE,gCAAgC,EAAE,MAAM,uCAAuC,CAAC;AACzF,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,2BAA2B,EAAE,MAAM,kCAAkC,CAAC;AAE/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAS5C;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GACpB,oBAAoB,GACpB,yBAAyB,GACzB,sBAAsB,GACtB,mBAAmB,GACnB,4BAA4B,GAC5B,0BAA0B,GAC1B,uBAAuB,GACvB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,SAAS,QAAQ,EAAE,CAAC,CAQlF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,QAAQ,EAGwB,CAAC"}

package/dist/fixtures/index.js

@@ -0,0 +1,87 @@
+/**
+ * Fixture catalog — every conformance fixture, classified by the
+ * contract or protocol criterion it exercises.
+ *
+ * The sub-module layout (one directory per contract) is load-bearing:
+ * it is how the reporter groups results on the bar-scorecard output,
+ * and how third-party implementers understand which criterion each
+ * fixture asserts. Renaming a sub-module directory breaks the
+ * reporter's output shape — treat the classification as the public
+ * API.
+ *
+ * ## Why static imports
+ *
+ * The fixture JSON files are statically imported (`import … from
+ * './foo.json' with { type: 'json' }`) so tsc inlines the fixture
+ * data into `dist/fixtures/`. Third-party TS consumers get typed
+ * arrays without a runtime file-read. Non-TS consumers (Python, Go,
+ * Rust) read the raw `.json` files directly — they ship in `dist/`
+ * via the package's `files` field.
+ *
+ * ## Current coverage
+ *
+ * Seven sub-modules with content (18 fixtures). Three additional
+ * sub-modules (`data-contract`, `tool-name-uniqueness`,
+ * `contract-error-payload`) are reserved for additive fixture
+ * expansion and not yet materialized — adding fixtures there is a
+ * kit minor version.
+ *
+ * `canvas-mode-wire-shapes` (4 fixtures) ships the canvas-mode wire
+ * contract intent: `canvasMode` bootstrap discriminator,
+ * `_ggui:lifecycle` channel + payload, `canvas_navigated` +
+ * `host_context_observed` C→S WS messages. Runner activation is a
+ * follow-up kit minor once the reference `ConformanceHost` exposes
+ * `set-app-mode` + `assert-session-field` + `assert-channel-envelope`
+ * directives.
+ *
+ * ## What is NOT here — the gadget pure-function obligations
+ *
+ * SPEC §7.7.2's gadget obligations are pure-function obligations, not
+ * transport-observable behaviors: which `clientCapabilities` payloads
+ * a parser accepts (`../schema-conformance`) and which `(contract,
+ * appGadgets)` pairs the push-time registry gate accepts / rejects
+ * (`../registration-conformance`). They are graded against a
+ * caller-supplied function — there is no session, transport, or wire
+ * frame to drive — so they do NOT belong in this behavioral fixture
+ * catalog.
+ */
+export { bootstrapProtocolFixtures } from './bootstrap-protocol/index.js';
+export { canvasModeWireShapesFixtures } from './canvas-mode-wire-shapes/index.js';
+export { observabilityEventsFixtures } from './observability-events/index.js';
+export { refreshSemanticsFixtures } from './refresh-semantics/index.js';
+export { reservedChannelAuthorityFixtures } from './reserved-channel-authority/index.js';
+export { schemaVersionHandshakeFixtures } from './schema-version-handshake/index.js';
+export { wiredActionDispatchFixtures } from './wired-action-dispatch/index.js';
+import { bootstrapProtocolFixtures } from './bootstrap-protocol/index.js';
+import { canvasModeWireShapesFixtures } from './canvas-mode-wire-shapes/index.js';
+import { observabilityEventsFixtures } from './observability-events/index.js';
+import { refreshSemanticsFixtures } from './refresh-semantics/index.js';
+import { reservedChannelAuthorityFixtures } from './reserved-channel-authority/index.js';
+import { schemaVersionHandshakeFixtures } from './schema-version-handshake/index.js';
+import { wiredActionDispatchFixtures } from './wired-action-dispatch/index.js';
+/**
+ * Every fixture the kit ships, grouped by the contract it exercises.
+ * Order within each group matches the sub-module's `export` order.
+ *
+ * Map shape is load-bearing — the runner iterates
+ * `Object.entries(fixturesByContract)` to produce the bar scorecard,
+ * and consumers iterate it for custom reporters.
+ */
+export const fixturesByContract = {
+    'bootstrap-protocol': bootstrapProtocolFixtures,
+    'canvas-mode-wire-shapes': canvasModeWireShapesFixtures,
+    'observability-events': observabilityEventsFixtures,
+    'refresh-semantics': refreshSemanticsFixtures,
+    'reserved-channel-authority': reservedChannelAuthorityFixtures,
+    'schema-version-handshake': schemaVersionHandshakeFixtures,
+    'wired-action-dispatch': wiredActionDispatchFixtures,
+};
+/**
+ * Every fixture flat, in deterministic lexicographic order by
+ * `name`. Runners that don't care about classification iterate this
+ * list directly.
+ */
+export const allFixtures = Object.values(fixturesByContract)
+    .flat()
+    .slice()
+    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));

package/dist/fixtures/observability-events/index.d.ts

@@ -0,0 +1,5 @@
+import type { TestCase } from '../../types.js';
+/** All fixtures asserting the observability-event contract
+ *  (SPEC §"Runtime Consequence Chain" Tier 3). */
+export declare const observabilityEventsFixtures: readonly TestCase[];
+//# sourceMappingURL=index.d.ts.map

package/dist/fixtures/observability-events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/fixtures/observability-events/index.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;kDACkD;AAClD,eAAO,MAAM,2BAA2B,EAAE,SAAS,QAAQ,EAG1D,CAAC"}

package/dist/fixtures/observability-events/index.js

@@ -0,0 +1,22 @@
+/**
+ * `observability-events` fixture sub-module.
+ *
+ * Exercises the renderer's observability-event emission contract:
+ * every wired-action dispatch emits a `wired-tool-invoked` event;
+ * every `_ggui:contract-error` envelope emits a matching
+ * `contract-error-emitted` event.
+ *
+ * Both fixtures are `ConformanceHost`-gated — the direct
+ * postMessage-frame assertion requires a `page.exposeBinding` harness
+ * hook that the runner supplies. The effects are asserted implicitly
+ * via DOM state on the `wired-action-success` + contract-error
+ * fixtures in `wired-action-dispatch/`.
+ */
+import observabilityContractErrorEmitted from './observability-contract-error-emitted.json' with { type: 'json' };
+import observabilityWiredToolInvoked from './observability-wired-tool-invoked.json' with { type: 'json' };
+/** All fixtures asserting the observability-event contract
+ *  (SPEC §"Runtime Consequence Chain" Tier 3). */
+export const observabilityEventsFixtures = [
+    observabilityContractErrorEmitted,
+    observabilityWiredToolInvoked,
+];

package/dist/fixtures/observability-events/observability-contract-error-emitted.json

@@ -0,0 +1,29 @@
+{
+    "name": "observability-contract-error-emitted",
+    "description": "Standalone `contract-error-emitted` observability row. Every `_ggui:contract-error` envelope the server emits on the live channel MUST be mirrored as a `contract-error-emitted` observability event for host-side inspection without requiring the host to parse live-channel frames. Asserts the mirror-emission contract directly on the observability envelope.",
+    "skipReason": null,
+    "setup": [
+        { "type": "create-session", "sessionId": "ck-obs-ce-1" },
+        { "type": "register-tool", "toolName": "broken_tool", "handler": "throw" },
+        { "type": "register-actionspec", "name": "triggerBroken", "tool": "broken_tool" }
+    ],
+    "inputEnvelope": {
+        "type": "action",
+        "channel": 0,
+        "sessionId": "ck-obs-ce-1",
+        "action": {
+            "name": "triggerBroken",
+            "data": {}
+        }
+    },
+    "expectedBehavior": {
+        "kind": "observability-event",
+        "event": {
+            "kind": "contract-error-emitted",
+            "code": "TOOL_THREW",
+            "toolName": "broken_tool",
+            "actionName": "triggerBroken"
+        }
+    },
+    "teardown": [{ "type": "close-session", "sessionId": "ck-obs-ce-1" }]
+}

package/dist/fixtures/observability-events/observability-wired-tool-invoked.json

@@ -0,0 +1,28 @@
+{
+    "name": "observability-wired-tool-invoked",
+    "description": "Standalone `wired-tool-invoked` observability row. Distinct from `wired-action-success`'s DOM-level assertion — asserts directly on the postMessage observability envelope shape so Phase 3.1 can assert wire-byte equality without DOM observation.",
+    "skipReason": null,
+    "setup": [
+        { "type": "create-session", "sessionId": "ck-obs-wired-1" },
+        { "type": "register-tool", "toolName": "tasks_complete", "handler": "echo" },
+        { "type": "register-actionspec", "name": "toggleTask", "tool": "tasks_complete" }
+    ],
+    "inputEnvelope": {
+        "type": "action",
+        "channel": 0,
+        "sessionId": "ck-obs-wired-1",
+        "action": {
+            "name": "toggleTask",
+            "data": { "id": "seed-1" }
+        }
+    },
+    "expectedBehavior": {
+        "kind": "observability-event",
+        "event": {
+            "kind": "wired-tool-invoked",
+            "toolName": "tasks_complete",
+            "actionName": "toggleTask"
+        }
+    },
+    "teardown": [{ "type": "close-session", "sessionId": "ck-obs-wired-1" }]
+}

package/dist/fixtures/refresh-semantics/index.d.ts

@@ -0,0 +1,5 @@
+import type { TestCase } from '../../types.js';
+/** All fixtures asserting refresh semantics (SPEC §2.3 StreamSpec +
+ *  §4.4 Envelope Specification refresh triggers). */
+export declare const refreshSemanticsFixtures: readonly TestCase[];
+//# sourceMappingURL=index.d.ts.map

package/dist/fixtures/refresh-semantics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/fixtures/refresh-semantics/index.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;qDACqD;AACrD,eAAO,MAAM,wBAAwB,EAAE,SAAS,QAAQ,EAEvD,CAAC"}

package/dist/fixtures/refresh-semantics/index.js

@@ -0,0 +1,19 @@
+/**
+ * `refresh-semantics` fixture sub-module.
+ *
+ * Exercises stream-refresh contract:
+ *   - Successful action → declared `streamSpec[channel].triggers` list
+ *     triggers a refresh → new stream-update observed on the channel.
+ *   - Failed action → refresh does NOT fire; stream state preserved.
+ *
+ * One fixture today (`stream-refresh-success`) driving through the
+ * `todo-list` blueprint's DOM state. The direct stream-update channel
+ * assertion is `ConformanceHost`-gated pending a channel-subscription
+ * transport seam.
+ */
+import streamRefreshSuccess from './stream-refresh-success.json' with { type: 'json' };
+/** All fixtures asserting refresh semantics (SPEC §2.3 StreamSpec +
+ *  §4.4 Envelope Specification refresh triggers). */
+export const refreshSemanticsFixtures = [
+    streamRefreshSuccess,
+];