@ggui-ai/protocol 0.14.0 → 0.16.0

package/dist/types/blueprint-source.js

@@ -11,7 +11,7 @@
  *
  *   - `llm` — engine-generated. `generator` is the slug of the
  *     {@link UiGenerator} that produced the component code; `model` is
- *     the LLM model id the engine called. Both REQUIRED: every
+ *     the route the engine called, as a `ModelRef`. Both REQUIRED: every
  *     generation mint site has them in scope, and an engine-generated
  *     artifact without them is not a real state.
  *   - `user` — developer-registered / hand-authored. Covers
@@ -31,8 +31,21 @@
  * rows are dropped at the trust boundary, never coerced.
  */
 import { isRecord } from "../validation/is-record.js";
+import { isModelRef } from "./llm-route.js";
 /** Closed list of `BlueprintSource` discriminants. */
 export const BLUEPRINT_SOURCE_KINDS = ["llm", "user", "curated"];
+/**
+ * The de-modeled generator identity (ggui#924): `ui-gen-` + ONE tier token
+ * — `ui-gen-default`, `ui-gen-advanced`, or an operator-defined tier. No
+ * model segment: the model is its own field, so a model retirement never
+ * renames an identity or re-keys a stored record. The template admits any
+ * `ui-gen-*` at the type level; {@link isGeneratorId} is the grammar.
+ */
+export const GENERATOR_ID_PATTERN = /^ui-gen-[a-z0-9]+$/;
+/** Whether `value` is a generator identity: one tier token, no model segment. */
+export function isGeneratorId(value) {
+    return GENERATOR_ID_PATTERN.test(value);
+}
 /**
  * Validating narrower for trust boundaries (DB row → union, JSON
  * artifact → union). Returns a CANONICAL rebuild of the union value —
@@ -50,9 +63,12 @@ export function parseBlueprintSource(value) {
         case "llm": {
             const generator = v["generator"];
             const model = v["model"];
-            if (typeof generator !== "string" || generator.length === 0)
+            // ggui#924: a modeled identity (`ui-gen-default-haiku-4-5`) or a
+            // non-route model (a bare `claude-…`, a dated API name) is not a
+            // provenance — null.
+            if (typeof generator !== "string" || !isGeneratorId(generator))
                 return null;
-            if (typeof model !== "string" || model.length === 0)
+            if (typeof model !== "string" || !isModelRef(model))
                 return null;
             return { kind: "llm", generator, model };
         }

package/dist/types/blueprint.d.ts

@@ -18,7 +18,7 @@
  *     advanced-generator iterative-loop output routinely exceeds
  *     them). The in-memory adapter skips the body store (in-process
  *     `Map<codeHash, string>`).
- *   - **Tenancy.** Scoped per `(appId, contractHash)`. Different apps'
+ *   - **App scope.** Scoped per `(appId, contractHash)`. Different apps'
  *     contract may coincidentally hash the same; their blueprints
  *     must never cross-pollinate. Rows are keyed by `blueprintId`;
  *     lookups go through an indexed `(appId, contractHash)` query.
@@ -127,7 +127,7 @@ export interface Blueprint {
      * key.
      */
     readonly contractHash: string;
-    /** Tenancy scope. Composite secondary key with `contractHash`. */
+    /** App scope. Composite secondary key with `contractHash`. */
     readonly appId: string;
     /**
      * S3 URL (`s3://<bucket>/<key>`) of the generated code body when

package/dist/types/blueprint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blueprint.d.ts","sourceRoot":"","sources":["../../src/types/blueprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAsB;IACrC;;qDAEiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;0CACsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;yCACqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;yCACqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAwB;IACvC;8CAC0C;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACnD;yCACqC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC;;;;;;;;;OASG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC;IAClC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,UAAU,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD"}
+{"version":3,"file":"blueprint.d.ts","sourceRoot":"","sources":["../../src/types/blueprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAsB;IACrC;;qDAEiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;0CACsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;yCACqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;yCACqC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,wBAAwB;IACvC;8CAC0C;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACnD;yCACqC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC;;;;;;;;;OASG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC;IAClC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,UAAU,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD"}

package/dist/types/contract-inference.d.ts

@@ -1,4 +1,4 @@
-import type { DataContract, JsonObject, JsonSchemaTypeName, JsonValue } from './data-contract';
+import type { DataContract, JsonObject, JsonSchemaTypeName, JsonValue } from './data-contract.js';
 /**
  * Extract the JSON Schema `required` array from a schema literal as a
  * string union. Resolves to `never` when `required` is absent, empty,

package/dist/types/data-contract.d.ts

@@ -188,7 +188,7 @@ export interface StreamChannelEntry {
      * `CTR_SCHEMA_INCOMPAT` linter additionally checks that the feed
      * tool's declared return schema is a subset of this schema — see
      * the docstring on {@link ActionEntry.schema} for the schema-subset
-     * algorithm and the `SCHEMA_MISMATCH_ERROR` failure surface.
+     * algorithm and the `schema_mismatch_error` failure surface.
      */
     schema: JsonSchema;
     /** Example payload (used for documentation and smoke testing). Typed as {@link JsonValue}. */
@@ -276,7 +276,7 @@ export interface ActionEntry {
      * advisory — the agent owns the actual tool call on its next turn
      * and is responsible for shaping the payload as the tool expects.
      * For tools registered on THIS server, the F4 schema-compat checker
-     * surfaces a `SCHEMA_MISMATCH_ERROR` at render-time / blueprint-
+     * surfaces a `schema_mismatch_error` at render-time / blueprint-
      * registration-time so authors get fail-loud feedback.
      *
      * The canonical algorithm lives in
@@ -610,7 +610,7 @@ export interface GadgetDescriptor {
     package: string;
     /**
      * ggui-hosted bundle URL — the preferred distribution path. Same
-     * origin as the iframe in single-tenant OSS deployments (served
+     * origin as the iframe in single-deployment installs (served
      * from `/_ggui/libs/<libId>/bundle.js`) and the ggui marketplace
      * CDN in cloud deployments. CSP `script-src` allowlists only the
      * ggui origin — no per-plugin third-party origins.

package/dist/types/domain-error-codes.d.ts

@@ -0,0 +1,167 @@
+/**
+ * The Plane-2 registry — the ONLY list of domain-error slugs (ggui#880).
+ *
+ * SPEC §7.9 Plane 2: a recoverable, contract-level failure the caller can
+ * fix — a missing session or handshake, props that do not satisfy the
+ * contract, an undeclared channel. The MCP SDK ships a thrown handler error
+ * to the agent as `{content: [{type: 'text', text: error.message}],
+ * isError: true}` and nothing else, so the slug travels as the LEADING
+ * token of that text — `<code>: <detail>` — composed by the `DomainError`
+ * base in `../errors/domain-error` from a code in this registry. A reader
+ * branches on `text.startsWith(code + ': ')` for a registered code and on
+ * nothing else.
+ *
+ * Same posture as the refusal registry in `./refusal-codes`: `code === key`
+ * is forced at the definer, the code type is derived from the keys, and
+ * the two registries are disjoint (pinned) — one code names one plane.
+ */
+/**
+ * How a caller recovers from a Plane-2 failure.
+ *
+ * - `retry-same-id` — fix the input and retry on the SAME handshakeId /
+ *   sessionId; nothing was consumed.
+ * - `re-mint` — the id itself is gone (unknown, consumed, expired,
+ *   another app's); mint a fresh one (`ggui_handshake`, then `ggui_render`).
+ * - `later` — a dependency the server fetches was unavailable; time
+ *   restores it, the input was fine.
+ */
+export declare const DOMAIN_ERROR_RECOVERIES: readonly ["retry-same-id", "re-mint", "later"];
+/** One member of {@link DOMAIN_ERROR_RECOVERIES}. */
+export type DomainErrorRecovery = (typeof DOMAIN_ERROR_RECOVERIES)[number];
+/**
+ * A data-plane `tools/call` name a Plane-2 slug may be emitted on. The
+ * template admits any `ggui_*` name at the type level; the registry's own
+ * suite narrows every row's `tools` to the data-plane set (no `ggui_ops_*`,
+ * no `ggui_protocol_*`).
+ */
+export type DataPlaneToolName = `ggui_${string}`;
+/**
+ * The registry with its per-key literal types kept (ggui#889):
+ * `DOMAIN_ERROR_ROWS.session_not_found.code` is `'session_not_found'`,
+ * its `recovery` is `'re-mint'`. {@link DOMAIN_ERROR_REGISTRY} is the
+ * same object read through the normalized row type.
+ */
+export declare const DOMAIN_ERROR_ROWS: {
+    readonly session_not_found: {
+        readonly code: "session_not_found";
+        readonly tools: readonly ["ggui_consume", "ggui_get_session", "ggui_get_render_source", "ggui_update", "ggui_amend", "ggui_emit", "ggui_runtime_pull"];
+        readonly recovery: "re-mint";
+        readonly emitter: "the session lookup on every session-scoped tool";
+        readonly description: "The sessionId names no session this caller can reach — never minted, expired, closed, or owned by another app (cross-app access surfaces uniformly). Re-handshake and re-render to mint a fresh one.";
+    };
+    readonly handshake_not_found: {
+        readonly code: "handshake_not_found";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "re-mint";
+        readonly emitter: "the handshake-record lookup at ggui_render";
+        readonly description: "The handshakeId is unknown, already consumed by a render, or expired. Call ggui_handshake again for a fresh id, then render with the new pair.";
+    };
+    readonly contract_violation: {
+        readonly code: "contract_violation";
+        readonly tools: readonly ["ggui_render", "ggui_update", "ggui_amend", "ggui_emit"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "the props / payload validator against the contract";
+        readonly description: "Props or a payload do not satisfy the contract's spec — a missing required prop included. Fix the values and retry with the same id; nothing was consumed.";
+    };
+    readonly schema_mismatch_error: {
+        readonly code: "schema_mismatch_error";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "the schema-compatibility check between the contract and the registered tool shapes";
+        readonly description: "An actionSpec or streamSpec schema is not a subset of the named tool's registered shape. Adjust the contract or the tool, then retry with the same handshakeId.";
+    };
+    readonly contract_validation_failed: {
+        readonly code: "contract_validation_failed";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "the contract lint gate (shape, retired fields, schema metadata, cross-references, schema compatibility)";
+        readonly description: "The contract failed the lint gate; the detail names the category and the finding. Fix the contract and retry with the same handshakeId.";
+    };
+    readonly override_contract_invalid: {
+        readonly code: "override_contract_invalid";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "the override gate at ggui_render";
+        readonly description: "override.contract failed validation — an override commits the caller to a conforming contract. Drop the override and render the suggestion, or fix the draft.";
+    };
+    readonly channel_not_declared: {
+        readonly code: "channel_not_declared";
+        readonly tools: readonly ["ggui_emit"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "ggui_emit's channel check against the contract's streamSpec";
+        readonly description: "The channel is not declared by the session's contract. Emit on a declared channel; the detail lists them.";
+    };
+    readonly invalid_complete: {
+        readonly code: "invalid_complete";
+        readonly tools: readonly ["ggui_emit"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "ggui_emit's completion check";
+        readonly description: "A completion was signalled for a channel that cannot complete in its current state. Emit on the channel first, or omit the completion.";
+    };
+    readonly gadget_not_registered: {
+        readonly code: "gadget_not_registered";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "the gadget gate at ggui_render";
+        readonly description: "A clientCapabilities.gadgets reference names an export the app's gadget registry does not carry. Drop the reference or fix the name; the detail suggests the nearest match.";
+    };
+    readonly gadget_package_mismatch: {
+        readonly code: "gadget_package_mismatch";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "the gadget gate at ggui_render";
+        readonly description: "A gadget export is registered, but only under a different package than the contract requested. Request the registered package; the detail names it.";
+    };
+    readonly gadget_public_env_missing: {
+        readonly code: "gadget_public_env_missing";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "the gadget gate at ggui_render";
+        readonly description: "A registered wrapper requires a public-env key the app has not set. Set the key on the app's public env, then retry.";
+    };
+    readonly duplicate_gadget_hook: {
+        readonly code: "duplicate_gadget_hook";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "the gadget gate at ggui_render";
+        readonly description: "Two gadget packages export the same name; the generated import would collide. Reference one of them.";
+    };
+    readonly gadget_types_fetch_failed: {
+        readonly code: "gadget_types_fetch_failed";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "later";
+        readonly emitter: "the gadget type fetch before cold generation";
+        readonly description: "Fetching a gadget package's types failed; the input was fine. Retry after a short delay.";
+    };
+    readonly gadget_catalog_integrity: {
+        readonly code: "gadget_catalog_integrity";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "the app's gadget catalog resolver at ggui_render";
+        readonly description: "The app's gadget catalog is inconsistent with its registrations. Repair the catalog, then retry with the same handshakeId.";
+    };
+    readonly blueprint_rejected: {
+        readonly code: "blueprint_rejected";
+        readonly tools: readonly ["ggui_render"];
+        readonly recovery: "retry-same-id";
+        readonly emitter: "the blueprint registry on registration";
+        readonly description: "The blueprint was rejected by the registry's error-level findings; the detail lists them. Fix the contract and retry with the same handshakeId.";
+    };
+};
+/** A domain-error code = a registry key. Derived; never a second list. */
+export type DomainErrorCode = keyof typeof DOMAIN_ERROR_ROWS;
+/** A registry row, as consumers read it. */
+export interface DomainErrorRow {
+    readonly code: DomainErrorCode;
+    readonly tools: readonly DataPlaneToolName[];
+    readonly recovery: DomainErrorRecovery;
+    readonly emitter: string;
+    readonly description: string;
+}
+/** The registry consumers read. */
+export declare const DOMAIN_ERROR_REGISTRY: Readonly<Record<DomainErrorCode, DomainErrorRow>>;
+/** Whether `value` is a registered domain-error code. */
+export declare function isDomainErrorCode(value: string): value is DomainErrorCode;
+/** Every registered code, in registry order. */
+export declare const DOMAIN_ERROR_CODES: readonly DomainErrorCode[];
+//# sourceMappingURL=domain-error-codes.d.ts.map

package/dist/types/domain-error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-error-codes.d.ts","sourceRoot":"","sources":["../../src/types/domain-error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,gDAAiD,CAAC;AAEtF,qDAAqD;AACrD,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,MAAM,EAAE,CAAC;AAyBjD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsI5B,CAAC;AAEH,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE7D,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,mCAAmC;AACnC,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,cAAc,CAAC,CACjE,CAAC;AAEpB,yDAAyD;AACzD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,eAAe,CAEzE;AAED,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EACC,CAAC"}

package/dist/types/domain-error-codes.js

@@ -0,0 +1,170 @@
+/**
+ * The Plane-2 registry — the ONLY list of domain-error slugs (ggui#880).
+ *
+ * SPEC §7.9 Plane 2: a recoverable, contract-level failure the caller can
+ * fix — a missing session or handshake, props that do not satisfy the
+ * contract, an undeclared channel. The MCP SDK ships a thrown handler error
+ * to the agent as `{content: [{type: 'text', text: error.message}],
+ * isError: true}` and nothing else, so the slug travels as the LEADING
+ * token of that text — `<code>: <detail>` — composed by the `DomainError`
+ * base in `../errors/domain-error` from a code in this registry. A reader
+ * branches on `text.startsWith(code + ': ')` for a registered code and on
+ * nothing else.
+ *
+ * Same posture as the refusal registry in `./refusal-codes`: `code === key`
+ * is forced at the definer, the code type is derived from the keys, and
+ * the two registries are disjoint (pinned) — one code names one plane.
+ */
+/**
+ * How a caller recovers from a Plane-2 failure.
+ *
+ * - `retry-same-id` — fix the input and retry on the SAME handshakeId /
+ *   sessionId; nothing was consumed.
+ * - `re-mint` — the id itself is gone (unknown, consumed, expired,
+ *   another app's); mint a fresh one (`ggui_handshake`, then `ggui_render`).
+ * - `later` — a dependency the server fetches was unavailable; time
+ *   restores it, the input was fine.
+ */
+export const DOMAIN_ERROR_RECOVERIES = ['retry-same-id', 're-mint', 'later'];
+/**
+ * The registry is the ONLY list of domain-error codes: {@link DomainErrorCode}
+ * is derived from the keys below, and this definer forces every row's
+ * `code` to equal its key at the type level.
+ */
+function defineDomainErrorRegistry(rows) {
+    return rows;
+}
+/**
+ * The registry with its per-key literal types kept (ggui#889):
+ * `DOMAIN_ERROR_ROWS.session_not_found.code` is `'session_not_found'`,
+ * its `recovery` is `'re-mint'`. {@link DOMAIN_ERROR_REGISTRY} is the
+ * same object read through the normalized row type.
+ */
+export const DOMAIN_ERROR_ROWS = /* @__PURE__ */ defineDomainErrorRegistry({
+    // ── identity ──────────────────────────────────────────────────────
+    session_not_found: {
+        code: 'session_not_found',
+        tools: [
+            'ggui_consume',
+            'ggui_get_session',
+            'ggui_get_render_source',
+            'ggui_update',
+            'ggui_amend',
+            'ggui_emit',
+            'ggui_runtime_pull',
+        ],
+        recovery: 're-mint',
+        emitter: 'the session lookup on every session-scoped tool',
+        description: 'The sessionId names no session this caller can reach — never minted, expired, closed, or owned by another app (cross-app access surfaces uniformly). Re-handshake and re-render to mint a fresh one.',
+    },
+    handshake_not_found: {
+        code: 'handshake_not_found',
+        tools: ['ggui_render'],
+        recovery: 're-mint',
+        emitter: 'the handshake-record lookup at ggui_render',
+        description: 'The handshakeId is unknown, already consumed by a render, or expired. Call ggui_handshake again for a fresh id, then render with the new pair.',
+    },
+    // ── the contract gate ─────────────────────────────────────────────
+    contract_violation: {
+        code: 'contract_violation',
+        tools: ['ggui_render', 'ggui_update', 'ggui_amend', 'ggui_emit'],
+        recovery: 'retry-same-id',
+        emitter: 'the props / payload validator against the contract',
+        description: "Props or a payload do not satisfy the contract's spec — a missing required prop included. Fix the values and retry with the same id; nothing was consumed.",
+    },
+    schema_mismatch_error: {
+        code: 'schema_mismatch_error',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the schema-compatibility check between the contract and the registered tool shapes',
+        description: "An actionSpec or streamSpec schema is not a subset of the named tool's registered shape. Adjust the contract or the tool, then retry with the same handshakeId.",
+    },
+    contract_validation_failed: {
+        code: 'contract_validation_failed',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the contract lint gate (shape, retired fields, schema metadata, cross-references, schema compatibility)',
+        description: 'The contract failed the lint gate; the detail names the category and the finding. Fix the contract and retry with the same handshakeId.',
+    },
+    override_contract_invalid: {
+        code: 'override_contract_invalid',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the override gate at ggui_render',
+        description: 'override.contract failed validation — an override commits the caller to a conforming contract. Drop the override and render the suggestion, or fix the draft.',
+    },
+    // ── the live channel ──────────────────────────────────────────────
+    channel_not_declared: {
+        code: 'channel_not_declared',
+        tools: ['ggui_emit'],
+        recovery: 'retry-same-id',
+        emitter: "ggui_emit's channel check against the contract's streamSpec",
+        description: "The channel is not declared by the session's contract. Emit on a declared channel; the detail lists them.",
+    },
+    invalid_complete: {
+        code: 'invalid_complete',
+        tools: ['ggui_emit'],
+        recovery: 'retry-same-id',
+        emitter: "ggui_emit's completion check",
+        description: 'A completion was signalled for a channel that cannot complete in its current state. Emit on the channel first, or omit the completion.',
+    },
+    // ── the gadget gate ───────────────────────────────────────────────
+    gadget_not_registered: {
+        code: 'gadget_not_registered',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the gadget gate at ggui_render',
+        description: "A clientCapabilities.gadgets reference names an export the app's gadget registry does not carry. Drop the reference or fix the name; the detail suggests the nearest match.",
+    },
+    gadget_package_mismatch: {
+        code: 'gadget_package_mismatch',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the gadget gate at ggui_render',
+        description: 'A gadget export is registered, but only under a different package than the contract requested. Request the registered package; the detail names it.',
+    },
+    gadget_public_env_missing: {
+        code: 'gadget_public_env_missing',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the gadget gate at ggui_render',
+        description: "A registered wrapper requires a public-env key the app has not set. Set the key on the app's public env, then retry.",
+    },
+    duplicate_gadget_hook: {
+        code: 'duplicate_gadget_hook',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the gadget gate at ggui_render',
+        description: 'Two gadget packages export the same name; the generated import would collide. Reference one of them.',
+    },
+    gadget_types_fetch_failed: {
+        code: 'gadget_types_fetch_failed',
+        tools: ['ggui_render'],
+        recovery: 'later',
+        emitter: 'the gadget type fetch before cold generation',
+        description: "Fetching a gadget package's types failed; the input was fine. Retry after a short delay.",
+    },
+    gadget_catalog_integrity: {
+        code: 'gadget_catalog_integrity',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: "the app's gadget catalog resolver at ggui_render",
+        description: "The app's gadget catalog is inconsistent with its registrations. Repair the catalog, then retry with the same handshakeId.",
+    },
+    // ── the blueprint registry ────────────────────────────────────────
+    blueprint_rejected: {
+        code: 'blueprint_rejected',
+        tools: ['ggui_render'],
+        recovery: 'retry-same-id',
+        emitter: 'the blueprint registry on registration',
+        description: "The blueprint was rejected by the registry's error-level findings; the detail lists them. Fix the contract and retry with the same handshakeId.",
+    },
+});
+/** The registry consumers read. */
+export const DOMAIN_ERROR_REGISTRY = DOMAIN_ERROR_ROWS;
+/** Whether `value` is a registered domain-error code. */
+export function isDomainErrorCode(value) {
+    return Object.hasOwn(DOMAIN_ERROR_ROWS, value);
+}
+/** Every registered code, in registry order. */
+export const DOMAIN_ERROR_CODES = Object.keys(DOMAIN_ERROR_ROWS).filter(isDomainErrorCode);

package/dist/types/events.d.ts

@@ -1,4 +1,4 @@
-import type { JsonValue } from './data-contract';
+import type { JsonValue } from './data-contract.js';
 /**
  * Event type that flows from user to agent.
  *

package/dist/types/ggui-session-event.d.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod';
-import type { runtimePullEventsPageSchema } from '../schemas/mcp';
-import type { DeepReadonly } from './readonly';
+import type { runtimePullEventsPageSchema } from '../schemas/mcp.js';
+import type { DeepReadonly } from './readonly.js';
 /**
  * GguiSessionEvent ledger — wire-frame replay primitives (R7).
  *

package/dist/types/handshake-suggestion.d.ts

@@ -89,12 +89,12 @@ export interface BlueprintDraft {
         readonly seedPrompt?: string;
     };
     /**
-     * Generator slug hint (e.g. `'ui-gen-advanced-opus-4-7'`). The
+     * Generator identity hint (e.g. `'ui-gen-advanced'` — de-modeled, ggui#924). The
      * server resolves the effective generator as:
      *
      *   1. Operator app-pin (`App.pinnedGenerator`) — wins if set.
      *   2. This hint — if registered in the GeneratorRegistry.
-     *   3. Registry default (`ui-gen-default-haiku-4-5`).
+     *   3. Registry default (`ui-gen-default`).
      *
      * Hint-only; unknown slugs fall through to the registry default.
      */

package/dist/types/host-context.d.ts

@@ -40,12 +40,12 @@
  * projection widenings can be detected; this module is the canonical
  * shape for the current schema major.
  */
-import type { JsonValue } from './data-contract';
+import type { JsonValue } from './data-contract.js';
 export type { McpUiDisplayMode, McpUiHostContext, McpUiHostCapabilities, } from '@modelcontextprotocol/ext-apps';
 import type { McpUiDisplayMode } from '@modelcontextprotocol/ext-apps';
 import type { z } from 'zod';
-import type { hostContextProjectionSchema, mcpUiDisplayModeSchema } from '../schemas/mcp';
-import type { DeepReadonly } from './readonly';
+import type { hostContextProjectionSchema, mcpUiDisplayModeSchema } from '../schemas/mcp.js';
+import type { DeepReadonly } from './readonly.js';
 /**
  * The wire enum is assignable to ext-apps' `McpUiDisplayMode` — checked at
  * compile time, so a display mode the host SDK adds is a protocol change

package/dist/types/interface-context.d.ts

@@ -6,7 +6,7 @@
  *
  * Allows Claude to generate UIs adapted to the user's device/viewport.
  */
-import type { JsonObject } from './data-contract';
+import type { JsonObject } from './data-contract.js';
 export type PlatformType = 'web' | 'mobile' | 'desktop';
 export type DeviceType = 'phone' | 'tablet' | 'desktop';
 export type Orientation = 'portrait' | 'landscape';

package/dist/types/invoke.d.ts

@@ -5,7 +5,7 @@
  * of truth. Do not hand-author parallel types here.
  */
 import type { z } from 'zod';
-import type { textBlockSchema, toolUseBlockSchema, toolResultBlockSchema, contentBlockSchema, invokeEventSchema, invokeErrorCodeSchema, invokeTurnSchema } from '../schemas/invoke';
+import type { textBlockSchema, toolUseBlockSchema, toolResultBlockSchema, contentBlockSchema, invokeEventSchema, invokeErrorCodeSchema, invokeTurnSchema } from '../schemas/invoke.js';
 export type TextBlock = z.infer<typeof textBlockSchema>;
 export type ToolUseBlock = z.infer<typeof toolUseBlockSchema>;
 export type ToolResultBlock = z.infer<typeof toolResultBlockSchema>;

package/dist/types/lifecycle.d.ts

@@ -33,7 +33,7 @@
  *   - This module is `data` only — no functions, no reducers. Pure
  *     types so the protocol bundle stays tiny.
  */
-import type { JsonObject } from './data-contract';
+import type { JsonObject } from './data-contract.js';
 /**
  * Emitted when the server starts processing a `ggui_handshake` call.
  * Progress UIs transition from their current state into a

package/dist/types/live-channel.d.ts

@@ -15,15 +15,15 @@
  * The corresponding inbound user-action envelope ({@link ActionEnvelope})
  * lives in `types/events.ts` alongside the event-type enum.
  */
-import type { GguiSession } from './render';
-import type { JsonObject, JsonValue, StreamChannelMode } from './data-contract';
+import type { GguiSession } from './render.js';
+import type { JsonObject, JsonValue, StreamChannelMode } from './data-contract.js';
 /**
  * Payload for subscribe message
  */
 export interface SubscribePayload {
     sessionId: string;
     /**
-     * App (tenant) identity. OPTIONAL — absent ⇒ the server resolves the
+     * App identity — the `appId` the session belongs to. OPTIONAL — absent ⇒ the server resolves the
      * caller's identity-default app, the same resolution rule the MCP
      * route uses: a token binding (`wsToken` binds `(sessionId, appId)`)
      * wins, then the deployment's identity → appId mapping, then the