@ggui-ai/protocol 0.15.0 → 0.17.0

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-generation-profile.d.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+/**
+ * The generator PROFILE slot on an app's `generation` section (ggui#991;
+ * the D7 mechanism of ggui#987 — "chosen at generation time, like layout").
+ *
+ * Four members of free text the app's operator writes and the generator
+ * reads when it composes a component: `styling` is the brief (voice,
+ * mood, references), `density` and `layout` are one line each, and
+ * `direction` (2026-09-11, ggui#1027 follower) is the COMPOSITION
+ * direction of one variant — what leads (a hero panel, rows with arrows,
+ * a compact row of chips, a split panel), what is left out (icons,
+ * helper text, status lines), motion or none — one short paragraph, so
+ * a family of variants is one draft under one judge with the direction
+ * as the only arm. The slot
+ * is a GENERATION-TIME input: it is not a theme-document field, not a
+ * consumed token, and MUST never be projected into the `--ggui-*`
+ * vocabulary the card reads. An absent or empty profile MUST leave the
+ * generator's prompts byte-identical to today's.
+ *
+ * Parties and obligations:
+ *   - WRITERS (an operator console, `ggui deploy`) send the object below
+ *     through the app-config write door; the door trims, bounds each
+ *     member at {@link APP_GENERATION_PROFILE_BOUNDS} and refuses control
+ *     characters other than tab, newline and carriage return, answering
+ *     `invalid_app_config` with {@link appGenerationProfileRefusalBodySchema}
+ *     in the transport's refusal slot (REST 422 body, AppSync `errorInfo`,
+ *     MCP `structuredContent`).
+ *   - READERS (`@ggui-ai/ui-gen` behind the server's render path) cap
+ *     defensively at the SAME numbers — a value over the bound is a door
+ *     defect, never a second rule — and treat absent and empty alike.
+ *
+ * Observable violation: a profile that reaches the generator unbounded, or
+ * a profile name surfacing as a `--ggui-*` token, is non-conformant.
+ */
+export declare const APP_GENERATION_PROFILE_BOUNDS: {
+    readonly styling: 2000;
+    readonly density: 200;
+    readonly layout: 200;
+    readonly direction: 600;
+};
+export type AppGenerationProfileMember = keyof typeof APP_GENERATION_PROFILE_BOUNDS;
+/**
+ * The effort level (ggui#1058, founder's A2): ONE name over the reader's
+ * dials (model tier × turn cap × eval rounds × visual bar × judge model).
+ * The wire carries only the name; the name → dials table is the reader's
+ * (versioned by it), so a price line can move without a wire change.
+ * Absent ⇒ the deployment's default level, which MUST equal today's fixed
+ * options. A level the deployment has not enabled is REFUSED at the write
+ * door (`{ profile: { effort: 'unavailable' } }`) — never downgraded.
+ */
+export declare const APP_GENERATION_PROFILE_EFFORTS: readonly ["low", "medium", "high", "xhigh", "ultra"];
+export type AppGenerationProfileEffort = (typeof APP_GENERATION_PROFILE_EFFORTS)[number];
+/** Catalogue entry ids are slugs: trace-line and path safe, 2–64 chars. */
+export declare const APP_GENERATION_AESTHETIC_ID_RE: RegExp;
+/** A preset content version: no whitespace, ≤ 32 chars. */
+export declare const APP_GENERATION_AESTHETIC_VERSION_RE: RegExp;
+/**
+ * A reference INTO the aesthetic/variance catalogue (data, kept by the
+ * deployment, never inside the generator): `id` is the catalogue entry — the
+ * same slug a draft carries as its variance `aesthetic` when both are
+ * present — and `version` pins the preset's content so a preset can be
+ * re-authored without re-keying served takes. The door validates GRAMMAR
+ * only; resolution happens at read, and an unresolvable reference is
+ * NON-FATAL: the generator proceeds without the aesthetic section and
+ * reports `profile_aesthetic_unresolved`.
+ */
+export declare const appGenerationAestheticRefSchema: z.ZodObject<{
+    id: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AppGenerationAestheticRef = z.infer<typeof appGenerationAestheticRefSchema>;
+export declare const appGenerationProfileSchema: z.ZodObject<{
+    styling: z.ZodOptional<z.ZodString>;
+    density: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodString>;
+    direction: z.ZodOptional<z.ZodString>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+        ultra: "ultra";
+    }>>;
+    aesthetic: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AppGenerationProfile = z.infer<typeof appGenerationProfileSchema>;
+/** Why the door refused one member — one reason per member, at least one member named. */
+export declare const appGenerationProfileRefusalReasonSchema: z.ZodEnum<{
+    "too-long": "too-long";
+    "not-text": "not-text";
+    "control-chars": "control-chars";
+    unavailable: "unavailable";
+}>;
+export type AppGenerationProfileRefusalReason = z.infer<typeof appGenerationProfileRefusalReasonSchema>;
+export declare const appGenerationProfileRefusalBodySchema: z.ZodObject<{
+    profile: z.ZodObject<{
+        styling: z.ZodOptional<z.ZodEnum<{
+            "too-long": "too-long";
+            "not-text": "not-text";
+            "control-chars": "control-chars";
+            unavailable: "unavailable";
+        }>>;
+        density: z.ZodOptional<z.ZodEnum<{
+            "too-long": "too-long";
+            "not-text": "not-text";
+            "control-chars": "control-chars";
+            unavailable: "unavailable";
+        }>>;
+        layout: z.ZodOptional<z.ZodEnum<{
+            "too-long": "too-long";
+            "not-text": "not-text";
+            "control-chars": "control-chars";
+            unavailable: "unavailable";
+        }>>;
+        direction: z.ZodOptional<z.ZodEnum<{
+            "too-long": "too-long";
+            "not-text": "not-text";
+            "control-chars": "control-chars";
+            unavailable: "unavailable";
+        }>>;
+        effort: z.ZodOptional<z.ZodEnum<{
+            "too-long": "too-long";
+            "not-text": "not-text";
+            "control-chars": "control-chars";
+            unavailable: "unavailable";
+        }>>;
+        aesthetic: z.ZodOptional<z.ZodEnum<{
+            "too-long": "too-long";
+            "not-text": "not-text";
+            "control-chars": "control-chars";
+            unavailable: "unavailable";
+        }>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type AppGenerationProfileRefusalBody = z.infer<typeof appGenerationProfileRefusalBodySchema>;
+//# sourceMappingURL=app-generation-profile.d.ts.map

package/dist/schemas/app-generation-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-generation-profile.d.ts","sourceRoot":"","sources":["../../src/schemas/app-generation-profile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,6BAA6B;;;;;CAKhC,CAAC;AAEX,MAAM,MAAM,0BAA0B,GAAG,MAAM,OAAO,6BAA6B,CAAC;AA0BpF;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,sDAAuD,CAAC;AACnG,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzF,2EAA2E;AAC3E,eAAO,MAAM,8BAA8B,QAA8B,CAAC;AAC1E,2DAA2D;AAC3D,eAAO,MAAM,mCAAmC,QAA2B,CAAC;AAE5E;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B;;;kBAKjC,CAAC;AACZ,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;kBAS5B,CAAC;AAEZ,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,0FAA0F;AAC1F,eAAO,MAAM,uCAAuC;;;;;EAAmE,CAAC;AACxH,MAAM,MAAM,iCAAiC,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uCAAuC,CAAC,CAAC;AAExG,eAAO,MAAM,qCAAqC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAcvC,CAAC;AAEZ,MAAM,MAAM,+BAA+B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qCAAqC,CAAC,CAAC"}

package/dist/schemas/app-generation-profile.js

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+/**
+ * The generator PROFILE slot on an app's `generation` section (ggui#991;
+ * the D7 mechanism of ggui#987 — "chosen at generation time, like layout").
+ *
+ * Four members of free text the app's operator writes and the generator
+ * reads when it composes a component: `styling` is the brief (voice,
+ * mood, references), `density` and `layout` are one line each, and
+ * `direction` (2026-09-11, ggui#1027 follower) is the COMPOSITION
+ * direction of one variant — what leads (a hero panel, rows with arrows,
+ * a compact row of chips, a split panel), what is left out (icons,
+ * helper text, status lines), motion or none — one short paragraph, so
+ * a family of variants is one draft under one judge with the direction
+ * as the only arm. The slot
+ * is a GENERATION-TIME input: it is not a theme-document field, not a
+ * consumed token, and MUST never be projected into the `--ggui-*`
+ * vocabulary the card reads. An absent or empty profile MUST leave the
+ * generator's prompts byte-identical to today's.
+ *
+ * Parties and obligations:
+ *   - WRITERS (an operator console, `ggui deploy`) send the object below
+ *     through the app-config write door; the door trims, bounds each
+ *     member at {@link APP_GENERATION_PROFILE_BOUNDS} and refuses control
+ *     characters other than tab, newline and carriage return, answering
+ *     `invalid_app_config` with {@link appGenerationProfileRefusalBodySchema}
+ *     in the transport's refusal slot (REST 422 body, AppSync `errorInfo`,
+ *     MCP `structuredContent`).
+ *   - READERS (`@ggui-ai/ui-gen` behind the server's render path) cap
+ *     defensively at the SAME numbers — a value over the bound is a door
+ *     defect, never a second rule — and treat absent and empty alike.
+ *
+ * Observable violation: a profile that reaches the generator unbounded, or
+ * a profile name surfacing as a `--ggui-*` token, is non-conformant.
+ */
+export const APP_GENERATION_PROFILE_BOUNDS = {
+    styling: 2000,
+    density: 200,
+    layout: 200,
+    direction: 600,
+};
+/**
+ * True when the text carries a C0 control character other than tab (0x09),
+ * newline (0x0A) or carriage return (0x0D), or DEL (0x7F). Written as a
+ * code-point walk on purpose: the intent is explicit, and no control
+ * character has to appear in source.
+ */
+function hasForbiddenControlChars(text) {
+    for (const ch of text) {
+        const c = ch.codePointAt(0) ?? 0;
+        if (c === 0x7f)
+            return true;
+        if (c < 0x20 && c !== 0x09 && c !== 0x0a && c !== 0x0d)
+            return true;
+    }
+    return false;
+}
+function profileText(member) {
+    const max = APP_GENERATION_PROFILE_BOUNDS[member];
+    return z
+        .string()
+        .trim()
+        .max(max, `generation.profile.${member} exceeds ${max} characters`)
+        .refine((s) => !hasForbiddenControlChars(s), `generation.profile.${member} contains control characters`);
+}
+/**
+ * The effort level (ggui#1058, founder's A2): ONE name over the reader's
+ * dials (model tier × turn cap × eval rounds × visual bar × judge model).
+ * The wire carries only the name; the name → dials table is the reader's
+ * (versioned by it), so a price line can move without a wire change.
+ * Absent ⇒ the deployment's default level, which MUST equal today's fixed
+ * options. A level the deployment has not enabled is REFUSED at the write
+ * door (`{ profile: { effort: 'unavailable' } }`) — never downgraded.
+ */
+export const APP_GENERATION_PROFILE_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'ultra'];
+/** Catalogue entry ids are slugs: trace-line and path safe, 2–64 chars. */
+export const APP_GENERATION_AESTHETIC_ID_RE = /^[a-z0-9][a-z0-9-]{1,63}$/;
+/** A preset content version: no whitespace, ≤ 32 chars. */
+export const APP_GENERATION_AESTHETIC_VERSION_RE = /^[A-Za-z0-9._-]{1,32}$/;
+/**
+ * A reference INTO the aesthetic/variance catalogue (data, kept by the
+ * deployment, never inside the generator): `id` is the catalogue entry — the
+ * same slug a draft carries as its variance `aesthetic` when both are
+ * present — and `version` pins the preset's content so a preset can be
+ * re-authored without re-keying served takes. The door validates GRAMMAR
+ * only; resolution happens at read, and an unresolvable reference is
+ * NON-FATAL: the generator proceeds without the aesthetic section and
+ * reports `profile_aesthetic_unresolved`.
+ */
+export const appGenerationAestheticRefSchema = z
+    .object({
+    id: z.string().regex(APP_GENERATION_AESTHETIC_ID_RE, 'aesthetic id must be a slug (2–64 chars, lowercase, digits, dashes)'),
+    version: z.string().regex(APP_GENERATION_AESTHETIC_VERSION_RE, 'aesthetic version: 1–32 chars, no whitespace').optional(),
+})
+    .strict();
+export const appGenerationProfileSchema = z
+    .object({
+    styling: profileText('styling').optional(),
+    density: profileText('density').optional(),
+    layout: profileText('layout').optional(),
+    direction: profileText('direction').optional(),
+    effort: z.enum(APP_GENERATION_PROFILE_EFFORTS).optional(),
+    aesthetic: appGenerationAestheticRefSchema.optional(),
+})
+    .strict();
+/** Why the door refused one member — one reason per member, at least one member named. */
+export const appGenerationProfileRefusalReasonSchema = z.enum(['too-long', 'not-text', 'control-chars', 'unavailable']);
+export const appGenerationProfileRefusalBodySchema = z
+    .object({
+    profile: z
+        .object({
+        styling: appGenerationProfileRefusalReasonSchema.optional(),
+        density: appGenerationProfileRefusalReasonSchema.optional(),
+        layout: appGenerationProfileRefusalReasonSchema.optional(),
+        direction: appGenerationProfileRefusalReasonSchema.optional(),
+        effort: appGenerationProfileRefusalReasonSchema.optional(),
+        aesthetic: appGenerationProfileRefusalReasonSchema.optional(),
+    })
+        .strict()
+        .refine((p) => Object.keys(p).length > 0, 'a profile refusal names at least one member'),
+})
+    .strict();

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

@@ -26,23 +26,249 @@ 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;
+/**
+ * One declared font face (ggui#987 §5; lifted here for ggui#1093 / #990 so the
+ * theme DOCUMENT's `typography.faces` and the AppTheme WIRE's `fonts` share
+ * ONE grammar — `@ggui-ai/project-config` imports this schema for the
+ * document door). `src` MUST be `https:` with a well-formed host; the face is
+ * DECLARED, never fetched by any door: the render host unions the origin into
+ * its `font-src`, the shell renders the `@font-face` rule, and a face that
+ * fails to load in the browser falls back down the family's stack.
+ */
+export declare const fontFaceDeclarationSchema: z.ZodObject<{
+    family: z.ZodString;
+    src: z.ZodString;
+    weight: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    style: z.ZodOptional<z.ZodString>;
+    display: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type FontFaceDeclaration = z.infer<typeof fontFaceDeclarationSchema>;
+/** The most faces one theme may declare on the wire — a CSP and a `<style>` block stay bounded. */
+export declare const APP_THEME_FONTS_MAX = 16;
+/** The imagery slots a theme may fill (ggui#1093): a brand mark, a hero image, a repeating pattern. */
+export declare const APP_THEME_IMAGERY_KINDS: readonly ["mark", "hero", "pattern"];
+export type AppThemeImageryKind = (typeof APP_THEME_IMAGERY_KINDS)[number];
+/**
+ * One image asset: https-only `src` (never fetched by a door), an optional
+ * `alt` (≤ 200) and an optional `tone` — the image's own tonality (`light` /
+ * `dark`), so a composer can place ink over it without sampling pixels.
+ */
+export declare const appThemeImageAssetSchema: z.ZodObject<{
+    src: z.ZodString;
+    alt: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+    }>>;
+}, z.core.$strict>;
+export type AppThemeImageAsset = z.infer<typeof appThemeImageAssetSchema>;
+/**
+ * The host's imagery, by slot (ggui#1093, #1075 Track C (a)). Parties: a
+ * WRITER (an operator's design tooling, or a harvest of the host page) declares; the WRITE door
+ * validates this grammar and nothing more; the render host unions every
+ * `src` origin into its `img-src`; the composer reads the slots through
+ * the design primitives. Absent ⇒ no imagery, today's card.
+ */
+export declare const appThemeImagerySchema: z.ZodObject<{
+    mark: z.ZodOptional<z.ZodObject<{
+        src: z.ZodString;
+        alt: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+        }>>;
+    }, z.core.$strict>>;
+    hero: z.ZodOptional<z.ZodObject<{
+        src: z.ZodString;
+        alt: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+        }>>;
+    }, z.core.$strict>>;
+    pattern: z.ZodOptional<z.ZodObject<{
+        src: z.ZodString;
+        alt: z.ZodOptional<z.ZodString>;
+        tone: z.ZodOptional<z.ZodEnum<{
+            light: "light";
+            dark: "dark";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AppThemeImagery = z.infer<typeof appThemeImagerySchema>;
 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>;
+    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>;
+    fonts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        family: z.ZodString;
+        src: z.ZodString;
+        weight: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        style: z.ZodOptional<z.ZodString>;
+        display: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    imagery: z.ZodOptional<z.ZodObject<{
+        mark: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+            tone: z.ZodOptional<z.ZodEnum<{
+                light: "light";
+                dark: "dark";
+            }>>;
+        }, z.core.$strict>>;
+        hero: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+            tone: z.ZodOptional<z.ZodEnum<{
+                light: "light";
+                dark: "dark";
+            }>>;
+        }, z.core.$strict>>;
+        pattern: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+            tone: z.ZodOptional<z.ZodEnum<{
+                light: "light";
+                dark: "dark";
+            }>>;
         }, z.core.$strict>>;
-        frameless: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type AppTheme = z.infer<typeof appThemeSchema>;
+/**
+ * The READ-door posture (ggui#1093 belt, 2026-09-15; VERSION-POLICY §3.6).
+ *
+ * `appThemeSchema` is the WRITE door: strict, an unknown top-level member is
+ * refused (`invalid_app_config`). A READ door — a stored row turned into
+ * paint, a carried `_meta["ai.ggui/render"].theme` slice — parses with THIS
+ * schema instead: an unknown TOP-LEVEL member is stripped, the overlays are
+ * kept, and the caller reports what it stripped (one line per read, keys
+ * only, never theme content). Everything below the top level is unchanged —
+ * nested objects stay strict, token grammar and value safety still refuse,
+ * the v1 shape still refuses — and the attestation is untouched because
+ * `overlayHash` covers `{ overlays, cssVariables, keyframes }` only.
+ *
+ * Why: a reader on release N−1 meeting a member release N added would
+ * otherwise drop the WHOLE theme — colours and all — until it rolled
+ * (guuey#1266's class). Parties: every read door of an `AppTheme` MUST use
+ * this variant (or {@link parseAppThemeAtReadDoor}); every write door MUST
+ * stay on `appThemeSchema`. Observable violation: a read door dropping a
+ * theme whose overlays are valid because of an unknown top-level member —
+ * the kit's `n1-compat` forward case grades it.
+ */
+export declare const appThemeReadSchema: z.ZodObject<{
+    mode: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+    }>>;
+    name: z.ZodOptional<z.ZodString>;
+    overlayHash: z.ZodString;
+    overlays: z.ZodObject<{
+        light: z.ZodRecord<z.ZodString, z.ZodString>;
+        dark: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, 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>;
+    fonts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        family: z.ZodString;
+        src: z.ZodString;
+        weight: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        style: z.ZodOptional<z.ZodString>;
+        display: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    imagery: z.ZodOptional<z.ZodObject<{
+        mark: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+            tone: z.ZodOptional<z.ZodEnum<{
+                light: "light";
+                dark: "dark";
+            }>>;
+        }, z.core.$strict>>;
+        hero: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+            tone: z.ZodOptional<z.ZodEnum<{
+                light: "light";
+                dark: "dark";
+            }>>;
+        }, z.core.$strict>>;
+        pattern: z.ZodOptional<z.ZodObject<{
+            src: z.ZodString;
+            alt: z.ZodOptional<z.ZodString>;
+            tone: z.ZodOptional<z.ZodEnum<{
+                light: "light";
+                dark: "dark";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type AppThemeReadDoorResult = {
+    readonly ok: true;
+    readonly theme: AppTheme;
+    readonly stripped: readonly string[];
+} | {
+    readonly ok: false;
+    readonly issues: readonly string[];
+};
+/**
+ * Parse a stored or carried theme at a READ door: `ok` with the theme and
+ * the top-level members that were stripped (payload order, `[]` when none),
+ * or the issues in `path: message` form when the theme is refused for a
+ * reason the write door would also refuse.
+ */
+export declare function parseAppThemeAtReadDoor(input: unknown): AppThemeReadDoorResult;
+/**
+ * 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;AAwBD;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB;;;;;;kBAMpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,mGAAmG;AACnG,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,uGAAuG;AACvG,eAAO,MAAM,uBAAuB,sCAAuC,CAAC;AAC5E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;kBAInC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;kBAIhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoDhB,CAAC;AAEZ,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAiC,CAAC;AAEjE,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,CAW9E;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;oBAKpC,CAAC;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC"}