@ggui-ai/protocol 0.14.0 → 0.16.0

package/dist/integrations/mcp-apps.js

@@ -131,18 +131,7 @@ export function deriveContextName(slotKey) {
  * @public
  */
 export const MCP_APP_AI_GGUI_RENDER_META_KEY = 'ai.ggui/render';
-/**
- * Read the `ai.ggui/render` slice off a parsed JSON-RPC `_meta` object.
- *
- * Structural validation only. Missing key returns `{ok: true, meta: undefined}`
- * — not a failure. Required-fields gate (sessionId / appId / runtimeUrl)
- * fires only when the key is present. Field-level optional-field
- * defensive parsing (e.g. context-slot schema narrowing, expiresAt date
- * parse) lives downstream in the iframe-runtime's `validateMeta`.
- *
- * @public
- */
-export function parseMcpAppAiGguiRenderMeta(meta) {
+export function parseMcpAppAiGguiRenderMeta(meta, options = {}) {
     if (!isRecord(meta)) {
         return { ok: true };
     }
@@ -241,6 +230,9 @@ export function parseMcpAppAiGguiRenderMeta(meta) {
     // slice (tolerant degrade, consistent with the other optional fields).
     const themeParse = s.theme !== undefined ? appThemeSchema.safeParse(s.theme) : undefined;
     const parsedTheme = themeParse?.success === true ? themeParse.data : undefined;
+    if (themeParse !== undefined && !themeParse.success) {
+        options.onInvalidTheme?.(themeParse.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`));
+    }
     const slice = {
         sessionId: s.sessionId,
         appId: s.appId,
@@ -601,6 +593,14 @@ export function isGguiSubmitActionInput(value) {
             return true;
     }
 }
+/**
+ * Narrow a guarded envelope to its `dispatch` member. Sound because
+ * {@link isGguiSubmitActionInput}'s closed-set `switch` validates the
+ * `'dispatch'` payload before any extension kind can carry that literal.
+ */
+export function isGguiSubmitDispatchInput(env) {
+    return env.kind === 'dispatch';
+}
 /**
  * Does this slice carry at least one MOUNT MODE discriminator?
  * Mirrors the iframe-runtime's `validateMeta`: the runtime needs
@@ -686,7 +686,7 @@ export function toolResultGguiRender(result) {
  *
  * @public
  */
-export const GGUI_RENDER_SHELL_SURFACE = 'var(--ggui-shell-background, var(--ggui-color-surface, var(--ggui-shell-scheme-surface, #f9fafb)))';
+export const GGUI_RENDER_SHELL_SURFACE = 'var(--ggui-shell-background, var(--ggui-color-ground, var(--ggui-shell-scheme-surface, #f9fafb)))';
 /**
  * Inline `<style>` block that gives the shell's pre-render placeholder
  * a SCHEME-AWARE neutral ground (#662). Before the runtime injects

package/dist/integrations/overlay-hash.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Overlay attestation (ggui#987 §6.3): ONE canonical serialization and ONE
+ * hash for the per-app theme overlay, so every minter (a platform's
+ * projector, a console, a CLI) and every write door compute the same bytes.
+ *
+ * Canonical JSON: object keys sorted recursively, no whitespace, `undefined`
+ * members omitted, strings/numbers as JSON emits them. Hash: SHA-256 over the
+ * UTF-8 bytes, lowercase hex. Async because it uses Web Crypto
+ * (`globalThis.crypto.subtle`), available in every runtime the protocol
+ * targets.
+ */
+import type { AppTheme } from '../schemas/app-theme.js';
+/** The attested part of an overlay — never `mode`, `name` or `frameless`. */
+export type OverlayHashInput = Pick<AppTheme, 'overlays' | 'cssVariables' | 'keyframes'>;
+/** The canonical JSON the hash is taken over — exported so tests and other minters can pin it. */
+export declare function canonicalOverlayJson(input: OverlayHashInput): string;
+/** `sha256(canonicalOverlayJson(input))` as lowercase hex — the value `AppTheme.overlayHash` carries. */
+export declare function canonicalOverlayHash(input: OverlayHashInput): Promise<string>;
+//# sourceMappingURL=overlay-hash.d.ts.map

package/dist/integrations/overlay-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-hash.d.ts","sourceRoot":"","sources":["../../src/integrations/overlay-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,GAAG,cAAc,GAAG,WAAW,CAAC,CAAC;AAczF,kGAAkG;AAClG,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAOpE;AAMD,yGAAyG;AACzG,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAGnF"}

package/dist/integrations/overlay-hash.js

@@ -0,0 +1,29 @@
+function canonicalize(v) {
+    if (v === undefined)
+        return 'null';
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map((x) => canonicalize(x)).join(',')}]`;
+    const keys = Object.keys(v)
+        .filter((k) => v[k] !== undefined)
+        .sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalize(v[k])}`).join(',')}}`;
+}
+/** The canonical JSON the hash is taken over — exported so tests and other minters can pin it. */
+export function canonicalOverlayJson(input) {
+    const doc = {
+        overlays: input.overlays,
+        cssVariables: input.cssVariables,
+        keyframes: input.keyframes,
+    };
+    return canonicalize(doc);
+}
+function toHex(bytes) {
+    return Array.from(new Uint8Array(bytes), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** `sha256(canonicalOverlayJson(input))` as lowercase hex — the value `AppTheme.overlayHash` carries. */
+export async function canonicalOverlayHash(input) {
+    const bytes = new TextEncoder().encode(canonicalOverlayJson(input));
+    return toHex(await globalThis.crypto.subtle.digest('SHA-256', bytes));
+}

package/dist/integrations/theme-binding.d.ts

@@ -7,8 +7,8 @@
  * ## The normative total order
  *
  * ```
- * themeMode:  consolePick  >  staticConfig  >  sessionSidecar  >  hostAnnounced
- * themeId:    consolePick  >  renderOverride  >  staticConfig  >  sidecarName
+ * themeMode:  hostAnnounced  >  consolePick  >  staticConfig  >  sessionSidecar
+ * themeId:    consolePick  >  renderOverride  >  staticConfig
  * ```
  *
  * - `consolePick`    — the live operator pick (console theme provider).
@@ -17,8 +17,12 @@
  * - `sessionSidecar` — the per-app `App.theme` sidecar snapshotted at
  *   render-commit: its `mode` (for `themeMode`) / its `name` (for
  *   `themeId`, the registered-theme base-ladder binding).
- * - `hostAnnounced`  — the embedding host's `hostContext.theme`
- *   (mode only; hosts announce no theme id).
+ * - `hostAnnounced`  — the embedding host's `hostContext.theme` (mode
+ *   only; hosts announce no theme id). HIGHEST rank since ggui#987 (D4):
+ *   the embedding host owns runtime mode; every other layer is a default
+ *   the host's announce overrides. A one-palette sidecar can no longer
+ *   exist (`appThemeSchema` requires both projections), so following the
+ *   host never paints the wrong palette.
  *
  * An unresolved fact is `undefined` — NEVER defaulted to `'light'`.
  * Absence is load-bearing: it is the signal that lets the next layer
@@ -72,7 +76,7 @@ export interface ThemeModeEffectiveSources {
     readonly stamped?: ThemeModeOpinion | undefined;
     /** The slice theme OBJECT's own `mode` (the sidecar, read directly). */
     readonly sessionSidecar?: ThemeModeOpinion | undefined;
-    /** The embedding host's `hostContext.theme` announce — final fallback. */
+    /** The embedding host's `hostContext.theme` announce — HIGHEST rank (ggui#987). */
     readonly hostAnnounced?: ThemeModeOpinion | undefined;
 }
 /** Server projection of the `themeMode` total order → the stamped field. */
@@ -88,16 +92,14 @@ export interface ThemeIdStampSources {
     /** Static `ggui.json#theme` deps. */
     readonly staticConfig?: string | undefined;
 }
-/** Client-visible `themeId` layers, highest rank first. */
+/**
+ * Client-visible `themeId` layers. Since ggui#987 (D2 = B, the registration
+ * tier is gone) the sidecar's `name` is a label and never a binding: the
+ * only client-visible layer is the stamp.
+ */
 export interface ThemeIdEffectiveSources {
     /** The slice's stamped top-level `themeId`. */
     readonly stamped?: string | undefined;
-    /**
-     * The slice theme OBJECT's `name` — the registered-theme base-ladder
-     * binding (ggui#589 ask 3): an unregistered name is harmless by
-     * construction (renderer falls back to the default ladder).
-     */
-    readonly sidecarName?: string | undefined;
 }
 /** Server projection of the `themeId` total order → the stamped field. */
 export declare function stampThemeId(s: ThemeIdStampSources): string | undefined;

package/dist/integrations/theme-binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme-binding.d.ts","sourceRoot":"","sources":["../../src/integrations/theme-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhD,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpD,qCAAqC;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACrD,mEAAmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACxD;AAED,6DAA6D;AAC7D,MAAM,WAAW,yBAAyB;IACxC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAChD,wEAAwE;IACxE,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACvD,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACvD;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAC5B,CAAC,EAAE,qBAAqB,GACvB,gBAAgB,GAAG,SAAS,CAE9B;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,yBAAyB,GAC3B,gBAAgB,GAAG,SAAS,CAE9B;AAED,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,qCAAqC;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACtC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,uBAAuB,GAAG,MAAM,GAAG,SAAS,CAE/E"}
+{"version":3,"file":"theme-binding.d.ts","sourceRoot":"","sources":["../../src/integrations/theme-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhD,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACpD,qCAAqC;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACrD,mEAAmE;IACnE,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACxD;AAED,6DAA6D;AAC7D,MAAM,WAAW,yBAAyB;IACxC,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAChD,wEAAwE;IACxE,QAAQ,CAAC,cAAc,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACvD,mFAAmF;IACnF,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACvD;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAC5B,CAAC,EAAE,qBAAqB,GACvB,gBAAgB,GAAG,SAAS,CAE9B;AAED,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,yBAAyB,GAC3B,gBAAgB,GAAG,SAAS,CAE9B;AAED,2DAA2D;AAC3D,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,qCAAqC;IACrC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,uBAAuB,GAAG,MAAM,GAAG,SAAS,CAE/E"}

package/dist/integrations/theme-binding.js

@@ -7,8 +7,8 @@
  * ## The normative total order
  *
  * ```
- * themeMode:  consolePick  >  staticConfig  >  sessionSidecar  >  hostAnnounced
- * themeId:    consolePick  >  renderOverride  >  staticConfig  >  sidecarName
+ * themeMode:  hostAnnounced  >  consolePick  >  staticConfig  >  sessionSidecar
+ * themeId:    consolePick  >  renderOverride  >  staticConfig
  * ```
  *
  * - `consolePick`    — the live operator pick (console theme provider).
@@ -17,8 +17,12 @@
  * - `sessionSidecar` — the per-app `App.theme` sidecar snapshotted at
  *   render-commit: its `mode` (for `themeMode`) / its `name` (for
  *   `themeId`, the registered-theme base-ladder binding).
- * - `hostAnnounced`  — the embedding host's `hostContext.theme`
- *   (mode only; hosts announce no theme id).
+ * - `hostAnnounced`  — the embedding host's `hostContext.theme` (mode
+ *   only; hosts announce no theme id). HIGHEST rank since ggui#987 (D4):
+ *   the embedding host owns runtime mode; every other layer is a default
+ *   the host's announce overrides. A one-palette sidecar can no longer
+ *   exist (`appThemeSchema` requires both projections), so following the
+ *   host never paints the wrong palette.
  *
  * An unresolved fact is `undefined` — NEVER defaulted to `'light'`.
  * Absence is load-bearing: it is the signal that lets the next layer
@@ -61,7 +65,7 @@ export function stampThemeMode(s) {
 }
 /** Client projection of the `themeMode` total order → the effective mode. */
 export function effectiveThemeMode(s) {
-    return s.stamped ?? s.sessionSidecar ?? s.hostAnnounced;
+    return s.hostAnnounced ?? s.stamped ?? s.sessionSidecar;
 }
 /** Server projection of the `themeId` total order → the stamped field. */
 export function stampThemeId(s) {
@@ -69,5 +73,5 @@ export function stampThemeId(s) {
 }
 /** Client projection of the `themeId` total order → the effective id. */
 export function effectiveThemeId(s) {
-    return s.stamped ?? s.sidecarName;
+    return s.stamped;
 }

package/dist/registry/blueprint-key.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blueprint-key.d.ts","sourceRoot":"","sources":["../../src/registry/blueprint-key.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,CAGvE;AAMD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,iCAAiC,EACjC,+BAA+B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,GACnC,MAAM,yBAAyB,CAAC;AAIjC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"blueprint-key.d.ts","sourceRoot":"","sources":["../../src/registry/blueprint-key.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,CAGvE;AAMD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,iCAAiC,EACjC,+BAA+B,EAC/B,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,GACnC,MAAM,yBAAyB,CAAC;AAIjC,cAAc,sBAAsB,CAAC"}

package/dist/registry/blueprint-key.js

@@ -10,9 +10,10 @@
  * 16-character sha256 prefix — matches the existing `blueprintHash`
  * shape in `cache-trace-sink` and `generation-cache.ts`. Collision
  * probability for 100s-of-thousands of distinct contract is ~10^-6
- * (birthday-bound on 2^64), well below the budget for the OSS
- * single-tenant scope. Hosted multi-tenant deployments scope keys
- * by appId so the bound is per-tenant, never global.
+ * (birthday-bound on 2^64), well below the budget for a single
+ * deployment's key space. A deployment that serves many apps scopes
+ * keys by `appId`, so the bound holds per app, never across the whole
+ * store.
  */
 import { createHash } from 'node:crypto';
 import { canonicalizeContracts } from './canonicalize-contract.js';

package/dist/schemas/app-theme.d.ts

@@ -26,23 +26,59 @@ export declare const GGUI_CSS_VAR_KEY_RE: RegExp;
  * bare regex on its own.
  */
 export declare const CSS_VALUE_SAFE_RE: RegExp;
+/**
+ * The grammar a per-mode `keyframes` string MUST satisfy (ggui#987 §3.4,
+ * follower D). The renderer injects the text verbatim into the card's
+ * `<style>` after the variables, so the text is bounded to what that slot
+ * is FOR: zero or more `@keyframes <ident> { <frame-selectors> { <declarations> } … }`
+ * blocks and nothing else — no other at-rule (`@import`, `@font-face`,
+ * `@media`, …), no `<` / `>`, braces balanced and nested exactly one level
+ * inside a block. Comments (`/* … *\/`) are stripped before the walk and are
+ * therefore allowed, as `cssVariableMap` values allow `url(`; the deny-list
+ * on values (`;{}<>@`) cannot apply verbatim here because `;`, `{`, `}` and
+ * the one `@` ARE the grammar. Same principal, same slot, one rule.
+ */
+export declare const KEYFRAMES_NAME_RE: RegExp;
+export declare function isKeyframesText(text: string): boolean;
 export declare const appThemeSchema: z.ZodObject<{
-    mode: z.ZodEnum<{
+    mode: z.ZodOptional<z.ZodEnum<{
         light: "light";
         dark: "dark";
-    }>;
-    cssVariables: z.ZodRecord<z.ZodString, z.ZodString>;
+    }>>;
     name: z.ZodOptional<z.ZodString>;
-    base: z.ZodOptional<z.ZodObject<{
-        documentHash: z.ZodString;
+    overlayHash: z.ZodString;
+    overlays: z.ZodObject<{
         light: z.ZodRecord<z.ZodString, z.ZodString>;
         dark: z.ZodRecord<z.ZodString, z.ZodString>;
-        keyframes: z.ZodOptional<z.ZodObject<{
-            light: z.ZodOptional<z.ZodString>;
-            dark: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>;
-        frameless: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>;
+    cssVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    keyframes: z.ZodOptional<z.ZodObject<{
+        light: z.ZodOptional<z.ZodString>;
+        dark: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
+    frameless: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export type AppTheme = z.infer<typeof appThemeSchema>;
+/**
+ * The ONE refusal body every write door returns for an overlay it will not
+ * store (ggui#987 §3.4): REST 422 `invalid_app_config`, the AppSync
+ * `errorInfo`, the MCP ops door's `{ ok: false }` structured content. A
+ * discriminated union by key — exactly one of the four.
+ */
+export declare const appThemeRefusalBodySchema: z.ZodUnion<readonly [z.ZodObject<{
+    uncovered: z.ZodObject<{
+        light: z.ZodArray<z.ZodString>;
+        dark: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    unknown: z.ZodObject<{
+        light: z.ZodArray<z.ZodString>;
+        dark: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    overlayHash: z.ZodLiteral<"mismatch">;
+}, z.core.$strict>, z.ZodObject<{
+    refused: z.ZodLiteral<"v1 shape">;
+}, z.core.$strict>]>;
+export type AppThemeRefusalBody = z.infer<typeof appThemeRefusalBodySchema>;
 //# sourceMappingURL=app-theme.d.ts.map

package/dist/schemas/app-theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-theme.d.ts","sourceRoot":"","sources":["../../src/schemas/app-theme.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,QAA2B,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,QAAiB,CAAC;AAahD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;kBAkDhB,CAAC;AAEZ,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}
+{"version":3,"file":"app-theme.d.ts","sourceRoot":"","sources":["../../src/schemas/app-theme.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,QAA2B,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,QAAiB,CAAC;AAahD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,QAA+B,CAAC;AAE9D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAoCrD;AAQD,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;kBAuChB,CAAC;AAEZ,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;oBAKpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/schemas/app-theme.js

@@ -35,54 +35,122 @@ const cssValue = z
 const cssVariableMap = z
     .record(z.string().regex(GGUI_CSS_VAR_KEY_RE, 'css var key must be --ggui-*'), cssValue)
     .refine((m) => Object.keys(m).length <= 200, 'too many css variables (max 200)');
+/**
+ * The grammar a per-mode `keyframes` string MUST satisfy (ggui#987 §3.4,
+ * follower D). The renderer injects the text verbatim into the card's
+ * `<style>` after the variables, so the text is bounded to what that slot
+ * is FOR: zero or more `@keyframes <ident> { <frame-selectors> { <declarations> } … }`
+ * blocks and nothing else — no other at-rule (`@import`, `@font-face`,
+ * `@media`, …), no `<` / `>`, braces balanced and nested exactly one level
+ * inside a block. Comments (`/* … *\/`) are stripped before the walk and are
+ * therefore allowed, as `cssVariableMap` values allow `url(`; the deny-list
+ * on values (`;{}<>@`) cannot apply verbatim here because `;`, `{`, `}` and
+ * the one `@` ARE the grammar. Same principal, same slot, one rule.
+ */
+export const KEYFRAMES_NAME_RE = /^[A-Za-z_-][A-Za-z0-9_-]*$/;
+export function isKeyframesText(text) {
+    const s = text.replace(/\/\*[\s\S]*?\*\//g, ' ');
+    if (/[<>]/.test(s))
+        return false;
+    let i = 0;
+    const n = s.length;
+    const skipWs = () => {
+        while (i < n && /\s/.test(s[i]))
+            i += 1;
+    };
+    for (;;) {
+        skipWs();
+        if (i >= n)
+            return true;
+        if (!s.startsWith('@keyframes', i))
+            return false;
+        i += '@keyframes'.length;
+        if (i >= n || !/\s/.test(s[i]))
+            return false;
+        skipWs();
+        const nameStart = i;
+        while (i < n && /[A-Za-z0-9_-]/.test(s[i]))
+            i += 1;
+        if (!KEYFRAMES_NAME_RE.test(s.slice(nameStart, i)))
+            return false;
+        skipWs();
+        if (s[i] !== '{')
+            return false;
+        i += 1;
+        // Inside the block: frame rules only — `selectors { declarations }` at depth 1, no `@`.
+        let depth = 1;
+        while (i < n && depth > 0) {
+            const ch = s[i];
+            if (ch === '@')
+                return false;
+            if (ch === '{') {
+                depth += 1;
+                if (depth > 2)
+                    return false;
+            }
+            else if (ch === '}') {
+                depth -= 1;
+            }
+            i += 1;
+        }
+        if (depth !== 0)
+            return false;
+    }
+}
+/** A per-mode keyframes string: `@keyframes` blocks only (see {@link isKeyframesText}), 8 KiB cap unchanged. */
+const keyframesText = z
+    .string()
+    .max(8192)
+    .refine(isKeyframesText, 'keyframes must be `@keyframes <name> { … }` blocks and nothing else');
 export const appThemeSchema = z
     .object({
-    mode: z.enum(['light', 'dark']),
-    cssVariables: cssVariableMap,
+    /**
+     * Default appearance: the mode painted when NO embedding host announces
+     * one. Never a pin — the host owns runtime mode (ggui#987 D4; see
+     * `integrations/theme-binding.ts`). Absent ⇒ mode-neutral.
+     */
+    mode: z.enum(['light', 'dark']).optional(),
+    /** A label the author's tooling reads back. Never resolved by a renderer. */
     name: z.string().min(1).max(64).optional(),
     /**
-     * The REGISTERED base ladder, delivered (runtime theme
-     * registration): both modes' resolved variable sets ride the
-     * envelope so a mid-session mode switch is a local operation and
-     * delivery never depends on the iframe being able to fetch. The
-     * renderer injects the mode-selected set BELOW `cssVariables` (the
-     * per-app overlay) in the documented precedence. `documentHash` is
-     * the registration's identity: it joins painted ladders to
-     * registration records, and a receiver holding the hash may be
-     * served a future envelope without the variable sets.
+     * Delivery attestation: `canonicalOverlayHash({ overlays, cssVariables,
+     * keyframes })` (`integrations/overlay-hash.ts`). Every write door
+     * recomputes it and refuses a mismatch; read doors pass it through.
      */
-    base: z
+    overlayHash: z.string().regex(/^[0-9a-f]{64}$/, 'overlayHash must be sha256 lowercase hex'),
+    /**
+     * The projection, both modes — the derived `--ggui-*` sets a card
+     * injects for the effective mode (ggui#987 §2.4: produced by ONE
+     * function on every path). REQUIRED, both: an overlay that could not
+     * follow the host's mode is not accepted.
+     */
+    overlays: z.object({ light: cssVariableMap, dark: cssVariableMap }).strict(),
+    /** Mode-agnostic per-app overrides, injected above both projections. */
+    cssVariables: cssVariableMap.optional(),
+    /** Per-mode `@keyframes` blocks, injected verbatim after the variables — bounded to that grammar by {@link isKeyframesText}. */
+    keyframes: z
         .object({
-        documentHash: z
-            .string()
-            .regex(/^[0-9a-f]{64}$/, 'documentHash must be sha256 lowercase hex'),
-        light: cssVariableMap,
-        dark: cssVariableMap,
-        /**
-         * Per-mode `@keyframes` blocks from the registration document
-         * (ggui#613 residual 2). A mode key is absent when its
-         * document declares no motion keyframes; the whole field is
-         * absent on pre-#613 registrations (additive optional — old
-         * bases stay valid). Injected verbatim after the variable
-         * ladder, same position the compiled path gives
-         * `theme.cssKeyframes`.
-         */
-        keyframes: z
-            .object({
-            light: z.string().max(8192).optional(),
-            dark: z.string().max(8192).optional(),
-        })
-            .strict()
-            .optional(),
-        /**
-         * `$metadata.frameless` delivered (OR of both modes): the
-         * embedding host owns the card silhouette, so the renderer
-         * appends the root-children border-suppression rule — the
-         * SAME rule the compiled path emits.
-         */
-        frameless: z.boolean().optional(),
+        light: keyframesText.optional(),
+        dark: keyframesText.optional(),
     })
         .strict()
         .optional(),
+    /**
+     * The embedding host owns the card silhouette: the renderer appends the
+     * root-children border-suppression rule.
+     */
+    frameless: z.boolean().optional(),
 })
     .strict();
+/**
+ * The ONE refusal body every write door returns for an overlay it will not
+ * store (ggui#987 §3.4): REST 422 `invalid_app_config`, the AppSync
+ * `errorInfo`, the MCP ops door's `{ ok: false }` structured content. A
+ * discriminated union by key — exactly one of the four.
+ */
+export const appThemeRefusalBodySchema = z.union([
+    z.object({ uncovered: z.object({ light: z.array(z.string()), dark: z.array(z.string()) }).strict() }).strict(),
+    z.object({ unknown: z.object({ light: z.array(z.string()), dark: z.array(z.string()) }).strict() }).strict(),
+    z.object({ overlayHash: z.literal('mismatch') }).strict(),
+    z.object({ refused: z.literal('v1 shape') }).strict(),
+]);

package/dist/schemas/blueprint.d.ts

@@ -5,13 +5,14 @@
  * here is `z.ZodType<Blueprint>` so any drift fails compile.
  */
 import { z } from 'zod';
-import type { AppBlueprintSearchConfig, Blueprint, BlueprintVariance } from '../types/blueprint';
-import type { BlueprintSource, CuratedBlueprintSource, LlmBlueprintSource, UserBlueprintSource } from '../types/blueprint-source';
+import type { AppBlueprintSearchConfig, Blueprint, BlueprintVariance } from '../types/blueprint.js';
+import type { BlueprintSource, CuratedBlueprintSource, LlmBlueprintSource, UserBlueprintSource } from '../types/blueprint-source.js';
 /**
  * Zod mirror of {@link LlmBlueprintSource} — the engine-generated arm.
  * Both provenance fields are REQUIRED: every generation mint site has
  * them in scope, and an engine-generated artifact that cannot name its
- * engine + model is not a real state.
+ * engine + model is not a real state. Since ggui#924 the identity is
+ * de-modeled (`ui-gen-<tier>`) and the model is the run's `ModelRef`.
  */
 export declare const llmBlueprintSourceSchema: z.ZodType<LlmBlueprintSource>;
 /** Zod mirror of {@link UserBlueprintSource} — no engine claim exists. */

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

@@ -1 +1 @@
-{"version":3,"file":"blueprint.d.ts","sourceRoot":"","sources":["../../src/schemas/blueprint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,wBAAwB,EACxB,SAAS,EACT,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,2BAA2B,CAAC;AAGnC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAMvB,CAAC;AAE7C,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAExB,CAAC;AAE9C,oDAAoD;AACpD,eAAO,MAAM,4BAA4B,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAE3B,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAI7B,CAAC;AAEjC;;;;;;;;;GASG;AACH,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,4DAA6D,CAAC;AAElG,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAgCtB,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAwBd,CAAC;AAmBpC;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAM7B,CAAC"}
+{"version":3,"file":"blueprint.d.ts","sourceRoot":"","sources":["../../src/schemas/blueprint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,wBAAwB,EACxB,SAAS,EACT,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,2BAA2B,CAAC;AAKnC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAexD,CAAC;AAEZ,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,EAAE,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAExB,CAAC;AAE9C,oDAAoD;AACpD,eAAO,MAAM,4BAA4B,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAE3B,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAI7B,CAAC;AAEjC;;;;;;;;;GASG;AACH,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,4DAA6D,CAAC;AAElG,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAgCtB,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAwBd,CAAC;AAmBpC;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAM7B,CAAC"}

package/dist/schemas/blueprint.js

@@ -5,18 +5,30 @@
  * here is `z.ZodType<Blueprint>` so any drift fails compile.
  */
 import { z } from 'zod';
+import { isGeneratorId } from '../types/blueprint-source.js';
+import { MODEL_REF_PREFIXES, isModelRef } from '../types/llm-route.js';
 import { dataContractSchema, jsonValueSchema } from './data-contract.js';
 /**
  * Zod mirror of {@link LlmBlueprintSource} — the engine-generated arm.
  * Both provenance fields are REQUIRED: every generation mint site has
  * them in scope, and an engine-generated artifact that cannot name its
- * engine + model is not a real state.
+ * engine + model is not a real state. Since ggui#924 the identity is
+ * de-modeled (`ui-gen-<tier>`) and the model is the run's `ModelRef`.
  */
 export const llmBlueprintSourceSchema = z
     .object({
     kind: z.literal('llm'),
-    generator: z.string().min(1),
-    model: z.string().min(1),
+    // ggui#924: the de-modeled identity and the run's `ModelRef` — a
+    // modeled id, a bare model name or a second spelling is refused here,
+    // naming the field. Template literals (not `z.custom`) so the fields
+    // keep their literal types AND render to JSON Schema as `pattern` —
+    // this schema is embedded in tool inputs that `tools/list` renders.
+    generator: z.templateLiteral(['ui-gen-', z.string()]).refine(isGeneratorId, {
+        error: 'generator is the de-modeled identity `ui-gen-<tier>` — one tier token, no model segment (e.g. `ui-gen-default`)',
+    }),
+    model: z.templateLiteral([z.enum(MODEL_REF_PREFIXES), '/', z.string()]).refine(isModelRef, {
+        error: 'model is the run route in the registry spelling `<prefix>/<model>` (e.g. `anthropic/claude-haiku-4-5`)',
+    }),
 })
     .strict();
 /** Zod mirror of {@link UserBlueprintSource} — no engine claim exists. */

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

@@ -7,7 +7,7 @@
  * Output-side seams that type-narrow contract on the wire —
  * `renderOutputSchema.contract` and the various `decision` echoes — use
  * `z.custom<DataContract>()` because they trust the shape (it
- * originates from internal pod state).
+ * originates from internal server state).
  *
  * The input seam is different: agents author contract on
  * `story.contract` and the handler MUST plumb them to the generator.
@@ -51,7 +51,7 @@
  * just to accept the contract and pass it to the generator.
  */
 import { z } from 'zod';
-import type { DataContract, JsonValue, JsonSchema, JsonObject } from '../types/data-contract';
+import type { DataContract, JsonValue, JsonSchema, JsonObject } from '../types/data-contract.js';
 /**
  * Recursive {@link JsonValue} — string | number | boolean | null |
  * array | object. All fields on contract entries that carry default
@@ -211,26 +211,6 @@ export declare const agentCapabilitiesSpecSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$loose>;
-/**
- * `App.publicEnv` key regex.
- *
- * Each key in `App.publicEnv` MUST match this pattern. The prefix is
- * the **security boundary** — operators can't accidentally stash
- * sensitive credentials under arbitrary names, and downstream consumers
- * (render gate, bootstrap projection, iframe shim) can rely on the
- * naming convention to mean "public-by-design".
- *
- * Rule: `GGUI_PUBLIC_APP_` prefix, then uppercase letters / digits /
- * underscores, at least one char after the prefix.
- *
- * `GGUI_PUBLIC_USER_*` keys are RESERVED for a future per-user
- * channel. The current regex rejects them so App-side config can't
- * pre-emptively use the namespace.
- *
- * Hoisted above `gadgetDescriptorSchema` so the wrapper's `requires`
- * array can reference it at schema-construction time (TDZ-safe).
- */
-export declare const PUBLIC_ENV_APP_KEY_RE: RegExp;
 /**
  * Single source of truth for the `requires[]` field shape on gadget
  * descriptors. The wire-permissive `gadgetDescriptorSchema`, the
@@ -244,7 +224,7 @@ export declare const PUBLIC_ENV_APP_KEY_RE: RegExp;
  * that declare a `requires` key must have a corresponding App-side
  * publicEnv value at render time (gate: `assertPublicEnvSatisfied`).
  */
-export declare const gadgetRequiresSchema: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+export declare const gadgetRequiresSchema: z.ZodArray<z.ZodString>;
 /**
  * SRI hash format for gadget bundles. Registry install writes
  * `bundleSri` in this shape; iframe-runtime emits it verbatim into
@@ -367,7 +347,7 @@ export declare function bundleHostScheme(host: string): 'http' | 'https';
  * needs the grammars and which this module imports
  * `KNOWN_PERMISSION_NAMES` from).
  */
-export { HOOK_NAME_RE, COMPONENT_NAME_RE } from './gadget-name-grammar';
+export { HOOK_NAME_RE, COMPONENT_NAME_RE } from './gadget-name-grammar.js';
 /**
  * Wire-permissive {@link GadgetExport} schema — a union of a
  * hook-export shape (carries `hook`) and a component-export shape
@@ -475,8 +455,8 @@ export declare const gadgetDescriptorSchema: z.ZodObject<{
     bundleHost: z.ZodOptional<z.ZodString>;
     bundleSri: z.ZodOptional<z.ZodString>;
     styleUrl: z.ZodOptional<z.ZodURL>;
-    connect: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodURL>>>;
-    requires: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    connect: z.ZodOptional<z.ZodArray<z.ZodURL>>;
+    requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
     typesUrl: z.ZodOptional<z.ZodURL>;
     typesSri: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -550,8 +530,8 @@ export declare const strictGadgetDescriptorSchema: z.ZodObject<{
     bundleHost: z.ZodOptional<z.ZodString>;
     bundleSri: z.ZodOptional<z.ZodString>;
     styleUrl: z.ZodOptional<z.ZodURL>;
-    connect: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodURL>>>;
-    requires: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    connect: z.ZodOptional<z.ZodArray<z.ZodURL>>;
+    requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
     typesUrl: z.ZodOptional<z.ZodURL>;
     typesSri: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -640,8 +620,8 @@ export declare const registeredGadgetDescriptorSchema: z.ZodObject<{
     bundleHost: z.ZodOptional<z.ZodString>;
     bundleSri: z.ZodOptional<z.ZodString>;
     styleUrl: z.ZodOptional<z.ZodURL>;
-    connect: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodURL>>>;
-    requires: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    connect: z.ZodOptional<z.ZodArray<z.ZodURL>>;
+    requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
     typesUrl: z.ZodOptional<z.ZodURL>;
     typesSri: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -718,7 +698,7 @@ export declare const clientCapabilitiesSpecSchema: z.ZodObject<{
  *   - Defensive re-validation in the iframe-runtime slice-meta
  *     extractors (`parseMetaFromGlobal`, `parseMetaFromToolResult`).
  */
-export declare const appPublicEnvSchema: z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>;
+export declare const appPublicEnvSchema: z.ZodRecord<z.ZodString, z.ZodString>;
 /**
  * {@link DataContract} — the unified four-spec contract surface
  * agents author on `story.contract` and that the generator