@ggui-ai/project-config 0.14.0 → 0.16.0

package/dist/node.d.ts

@@ -121,6 +121,6 @@ export { discoverLocalUis, discoverFromGguiJsonPath, type DiscoveredUi, type Dis
 export { discoverPrimitives, discoverPrimitivesFromGguiJsonPath, type DiscoveredPrimitiveCatalog, type PrimitiveDiscoveryIssue, type PrimitiveDiscoveryResult, type DiscoverPrimitivesOptions, } from './primitive-discovery.js';
 export { discoverMcpMounts, GGUI_MCP_MOUNT_FACTORY_EXPORT, type DiscoveredMcpMount, type McpMountDiscoveryIssue, type McpMountDiscoveryResult, type DiscoverMcpMountsOptions, } from './mcp-mount-discovery.js';
 export { GGUI_PRIMITIVES_JSON_FILENAME, PrimitivesManifestV1, parsePrimitivesManifest, safeParsePrimitivesManifest, type PrimitivesManifest, } from './primitives-manifest.js';
-export { ThemeDocumentV1, parseThemeDocument, safeParseThemeDocument, type ThemeDocument, } from './theme.js';
+export { ThemeDocumentV2, normalizeThemeDocument, parseThemeDocument, safeParseThemeDocument, type ThemeDocument, } from './theme.js';
 export { loadTheme, loadThemeFromGguiJsonPath, type LoadedTheme, type LoadThemeOptions, type LoadThemeResult, type ThemeLoadIssue, } from './theme-loader.js';
 //# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"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"}

package/dist/node.js

@@ -15,7 +15,7 @@
  *   upward from `process.cwd()` to find the project-root file.
  * - Any hosting integration that reads the open manifest to
  *   reconstitute an agent. Hosting layers treat `ggui.json` as
- *   input-only; per-tenant overlay config lives outside this package.
+ *   input-only; per-app overlay config lives outside this package.
  */
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
@@ -215,9 +215,9 @@ export { discoverMcpMounts, GGUI_MCP_MOUNT_FACTORY_EXPORT, } from './mcp-mount-d
 export { GGUI_PRIMITIVES_JSON_FILENAME, PrimitivesManifestV1, parsePrimitivesManifest, safeParsePrimitivesManifest, } from './primitives-manifest.js';
 // Browser-safe theme document schema + parsers — re-exported on the
 // Node subpath so `ggui serve` / `ggui dev` get the full theme
-// surface from one import path. See `./theme.js` for the v1
+// surface from one import path. See `./theme.js` for the v2
 // plain-DTCG contract.
-export { ThemeDocumentV1, parseThemeDocument, safeParseThemeDocument, } from './theme.js';
+export { ThemeDocumentV2, normalizeThemeDocument, parseThemeDocument, safeParseThemeDocument, } from './theme.js';
 // Filesystem-backed theme loader — consumes `ggui.json#theme`,
 // resolves it against the project root, parses + validates, and
 // returns a `LoadedTheme` ready for the OSS `ggui serve` server.

package/dist/schema.d.ts

@@ -156,7 +156,7 @@ declare const GenerationSchema: z.ZodObject<{
         model: "claude-fable-5-1" | "claude-fable-5" | "claude-opus-5" | "claude-sonnet-5" | "claude-haiku-4-5-20251001" | "claude-opus-4-8" | "claude-sonnet-4-6" | "claude-opus-4-7" | "claude-opus-4-6";
     } | {
         provider: "openai";
-        model: "gpt-5.6" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-5.5" | "gpt-5.5-2026-04-23" | "gpt-5.5-pro" | "gpt-5.5-pro-2026-04-23" | "gpt-5.4" | "gpt-5.4-2026-03-05" | "gpt-5.4-mini" | "gpt-5.4-mini-2026-03-17" | "gpt-5.4-nano" | "gpt-5.4-nano-2026-03-17" | "gpt-5.3-codex";
+        model: "gpt-6-astra" | "gpt-5.6" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-5.5" | "gpt-5.5-2026-04-23" | "gpt-5.5-pro" | "gpt-5.5-pro-2026-04-23" | "gpt-5.4" | "gpt-5.4-2026-03-05" | "gpt-5.4-mini" | "gpt-5.4-mini-2026-03-17" | "gpt-5.4-nano" | "gpt-5.4-nano-2026-03-17" | "gpt-5.3-codex";
     } | {
         provider: "google";
         model: "gemini-3.7-flash" | "gemini-3.6-flash" | "gemini-3.5-flash" | "gemini-3.5-flash-lite" | "gemini-flash-latest" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gemini-3.1-flash-lite-preview" | "gemini-3-flash-preview";
@@ -265,12 +265,12 @@ export declare const GguiJsonV1: 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>>>;
-        publicEnv: z.ZodOptional<z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        publicEnv: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         defaultDisplayMode: z.ZodOptional<z.ZodEnum<{
             inline: "inline";
             fullscreen: "fullscreen";
@@ -333,7 +333,7 @@ export declare const GguiJsonV1: z.ZodObject<{
             model: "claude-fable-5-1" | "claude-fable-5" | "claude-opus-5" | "claude-sonnet-5" | "claude-haiku-4-5-20251001" | "claude-opus-4-8" | "claude-sonnet-4-6" | "claude-opus-4-7" | "claude-opus-4-6";
         } | {
             provider: "openai";
-            model: "gpt-5.6" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-5.5" | "gpt-5.5-2026-04-23" | "gpt-5.5-pro" | "gpt-5.5-pro-2026-04-23" | "gpt-5.4" | "gpt-5.4-2026-03-05" | "gpt-5.4-mini" | "gpt-5.4-mini-2026-03-17" | "gpt-5.4-nano" | "gpt-5.4-nano-2026-03-17" | "gpt-5.3-codex";
+            model: "gpt-6-astra" | "gpt-5.6" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-5.5" | "gpt-5.5-2026-04-23" | "gpt-5.5-pro" | "gpt-5.5-pro-2026-04-23" | "gpt-5.4" | "gpt-5.4-2026-03-05" | "gpt-5.4-mini" | "gpt-5.4-mini-2026-03-17" | "gpt-5.4-nano" | "gpt-5.4-nano-2026-03-17" | "gpt-5.3-codex";
         } | {
             provider: "google";
             model: "gemini-3.7-flash" | "gemini-3.6-flash" | "gemini-3.5-flash" | "gemini-3.5-flash-lite" | "gemini-flash-latest" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gemini-3.1-flash-lite-preview" | "gemini-3-flash-preview";

package/dist/theme-loader.d.ts

@@ -1,33 +1,34 @@
-import type { DtcgTheme, ThemeMode } from '@ggui-ai/design/themes';
+import type { DtcgTheme, ThemeMode, ThemeVariableMap } from '@ggui-ai/design/themes';
 import type { GguiJsonV1, ThemeConfig } from './schema.js';
-import { type ThemeDocument } from './theme.js';
+/**
+ * Both modes' projections of a loaded theme — the `overlays` an app
+ * theme carries on the wire (ggui#987 §3), produced by the ONE producer.
+ */
+export interface ThemeOverlays {
+    readonly light: ThemeVariableMap;
+    readonly dark: ThemeVariableMap;
+}
 /**
  * One loaded theme — discriminated on `source`. Every variant carries
- * the resolved `mode`, the parsed token document, and the pre-rendered
- * `--ggui-*` CSS variable block.
+ * the resolved `mode` (the default the card paints when no host
+ * announces one), the producer-ready document, and both modes'
+ * projections (`overlays`).
  *
- * **`document` is shape-discriminated by `source`** (no casts, two
- * structurally-similar but separately-validated underlying types):
+ * **`document` is the producer's `DtcgTheme` on every variant**: the
+ * registry's own document for `default` / `preset`, and for `file` the
+ * strict-Zod `ThemeDocument` after `normalizeThemeDocument` (the open
+ * `ggui.json#theme` format keeps `motion`/`accessibility`/`zIndex`
+ * optional so external tools that emit only a subset still parse; the
+ * normaliser fills them from the shipped default).
  *
- *   - `default` / `preset` → `DtcgTheme` (the canonical theme shape
- *     consumed by every registry-side theme — produces full
- *     `--ggui-*` CSS through `parseTheme`; every group required).
- *   - `file` → `ThemeDocument` (the strict-Zod schema for the open
- *     `ggui.json#theme` file format — same `color`/`font`/`spacing`/
- *     `shape`/`motion`/`accessibility`/`zIndex` vocabulary
- *     as `DtcgTheme`, but `motion`/`accessibility`/`zIndex`
- *     are optional so external tools that emit only a subset still
- *     parse).
- *
- * Consumers narrow on `source` if they ever need the shape. CSS-variable
- * emission happens upstream into `cssVariables`, so most downstream code
- * only reads that string.
+ * Consumers narrow on `source` only for provenance. The projection
+ * happens here, once, into `overlays`; downstream code reads the maps.
  */
 export type LoadedTheme = {
     readonly source: 'default';
     readonly mode: ThemeMode;
     readonly document: DtcgTheme;
-    readonly cssVariables: string;
+    readonly overlays: ThemeOverlays;
 } | {
     readonly source: 'preset';
     /** Registry id (`'claudic'`, `'ggui'`, …). */
@@ -36,14 +37,15 @@ export type LoadedTheme = {
     /** Flat dot-path token overrides applied on top of the preset. */
     readonly overrides?: Record<string, string>;
     readonly document: DtcgTheme;
-    readonly cssVariables: string;
+    readonly overlays: ThemeOverlays;
 } | {
     readonly source: 'file';
     /** Absolute filesystem path of the loaded theme file. */
     readonly path: string;
     readonly mode: ThemeMode;
-    readonly document: ThemeDocument;
-    readonly cssVariables: string;
+    /** The parsed file, normalised to the producer's document (see `normalizeThemeDocument`). */
+    readonly document: DtcgTheme;
+    readonly overlays: ThemeOverlays;
 };
 /**
  * An error surfaced during theme load. Shape matches the issue

package/dist/theme-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme-loader.d.ts","sourceRoot":"","sources":["../src/theme-loader.ts"],"names":[],"mappings":"AA4CA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,WAAW,GACnB;IACE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEN;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GACvB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC,CAAC;AAEN;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,QAAQ,EAAE,UAAU,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAwCpE;AAyMD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,UAAU,GACnB,eAAe,CAGjB;AAED;;;;;GAKG;AACH,YAAY,EAAE,WAAW,EAAE,CAAC"}
+{"version":3,"file":"theme-loader.d.ts","sourceRoot":"","sources":["../src/theme-loader.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACrF,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG3D;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CACjC;AAUD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,WAAW,GACnB;IACE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,6FAA6F;IAC7F,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;CAClC,CAAC;AAEN;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,mEAAmE;AACnE,MAAM,MAAM,eAAe,GACvB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC,CAAC;AAEN;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,QAAQ,EAAE,UAAU,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAwCpE;AA0MD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,UAAU,GACnB,eAAe,CAGjB;AAED;;;;;GAKG;AACH,YAAY,EAAE,WAAW,EAAE,CAAC"}

package/dist/theme-loader.js

@@ -14,16 +14,15 @@
  * exception. `ggui serve` escalates issues to a fatal exit before
  * binding a port.
  *
- * ## cssVariables pre-rendering
+ * ## Both modes, projected
  *
- * The loader pre-renders the `:root { --ggui-*: value; }` CSS block
- * via `@ggui-ai/design/themes`: `parseTheme(id, DtcgTheme)` for the
- * preset / default paths (full DTCG with motion tokens) and
- * `generateCssVariables(ThemeDocument)` for the file path (the
- * duck-typed walker accepts the plain DTCG document without requiring
- * the strict {@link DtcgTheme} shape). Downstream consumers (console,
- * render endpoint, MCP apps iframe) inject the pre-rendered string
- * without re-walking the token tree.
+ * Every `LoadedTheme` carries `overlays` — the `--ggui-*` variable map
+ * for BOTH modes, produced by `@ggui-ai/design/themes`'
+ * `deriveThemeVariables(document, mode)` (the one producer, ggui#987):
+ * a preset's light document and its dark twin, or a file's single
+ * document projected for each mode. Downstream consumers (the CLI's
+ * deploy PATCH, the console picker) ship the projection as the app's
+ * theme; nothing re-walks the token tree.
  *
  * ## Mode handling
  *
@@ -35,8 +34,15 @@
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { dirname, isAbsolute, resolve } from 'node:path';
-import { generateCssVariables, getRawTheme, getTheme, lightTheme, parseTheme, } from '@ggui-ai/design/themes';
-import { parseThemeDocument } from './theme.js';
+import { ThemeDocumentInvalidError, darkTheme, deriveThemeVariables, getRawTheme, lightTheme, } from '@ggui-ai/design/themes';
+import { normalizeThemeDocument, parseThemeDocument } from './theme.js';
+/** Project a light document (and its dark twin when it has one) for both modes. */
+function deriveOverlays(light, dark) {
+    return {
+        light: deriveThemeVariables(light, 'light'),
+        dark: deriveThemeVariables(dark ?? light, 'dark'),
+    };
+}
 /**
  * Load the theme declared in `ggui.json#theme`, or fall back to the
  * shipped default when the field is absent.
@@ -59,7 +65,7 @@ export function loadTheme(options) {
                 source: 'default',
                 mode: 'light',
                 document: lightTheme,
-                cssVariables: parseTheme('default', lightTheme).cssVariables,
+                overlays: deriveOverlays(lightTheme, darkTheme),
             },
         };
     }
@@ -86,8 +92,8 @@ export function loadTheme(options) {
  * manifest parse.
  */
 function loadPreset(preset, mode, overrides) {
-    // Resolve the raw token tree first so we can layer overrides
-    // before parseTheme walks the leaves.
+    // Resolve the raw token tree first (also the registration check)
+    // before layering overrides and projecting both modes.
     const raw = getRawTheme(preset, mode);
     if (!raw) {
         return {
@@ -100,45 +106,25 @@ function loadPreset(preset, mode, overrides) {
             },
         };
     }
-    // No overrides: hand off to the registry's parser directly so we
-    // share its cache.
-    if (!overrides || Object.keys(overrides).length === 0) {
-        const parsed = getTheme(preset, mode);
-        if (!parsed) {
-            // Should not happen — getRawTheme succeeded above. Defensive.
-            return {
-                ok: false,
-                issue: {
-                    path: preset,
-                    message: `Theme preset "${preset}" parsed unexpectedly empty.`,
-                },
-            };
-        }
-        return {
-            ok: true,
-            theme: {
-                source: 'preset',
-                preset,
-                mode,
-                document: raw,
-                cssVariables: parsed.cssVariables,
-            },
-        };
-    }
-    // With overrides: clone the raw tree, deep-set each leaf's $value,
-    // then re-parse. We bypass the registry's cache because the
-    // override set is per-call and would pollute it.
-    const mutated = applyOverrides(raw, overrides);
-    const parsed = parseTheme(preset, mutated);
+    // Both modes ride the loaded theme (ggui#987 §3): the preset's light
+    // document and its dark twin (a single-mode preset projects the one
+    // document for both), overrides applied to each before projection.
+    // Overrides clone the raw trees so the registry's cache stays clean.
+    const rawLight = getRawTheme(preset, 'light') ?? raw;
+    const rawDark = getRawTheme(preset, 'dark');
+    const hasOverrides = overrides !== undefined && Object.keys(overrides).length > 0;
+    const light = hasOverrides ? applyOverrides(rawLight, overrides) : rawLight;
+    const dark = rawDark === undefined ? undefined : hasOverrides ? applyOverrides(rawDark, overrides) : rawDark;
+    const document = mode === 'dark' ? (dark ?? light) : light;
     return {
         ok: true,
         theme: {
             source: 'preset',
             preset,
             mode,
-            overrides,
-            document: mutated,
-            cssVariables: parsed.cssVariables,
+            ...(hasOverrides ? { overrides } : {}),
+            document,
+            overlays: deriveOverlays(light, dark),
         },
     };
 }
@@ -203,14 +189,35 @@ function loadFile(filePath, mode, projectRoot) {
             },
         };
     }
+    // The producer is the validator of what the schema cannot see (a
+    // family with no `500` anchor, an unparseable colour): its refusal is
+    // the load issue, named by path.
+    const normalized = normalizeThemeDocument(document);
+    let overlays;
+    try {
+        overlays = deriveOverlays(normalized, undefined);
+    }
+    catch (cause) {
+        if (cause instanceof ThemeDocumentInvalidError) {
+            return {
+                ok: false,
+                issue: {
+                    path: absolutePath,
+                    message: `Theme file cannot be projected: ${cause.message}`,
+                    cause,
+                },
+            };
+        }
+        throw cause;
+    }
     return {
         ok: true,
         theme: {
             source: 'file',
             path: absolutePath,
             mode,
-            document,
-            cssVariables: generateCssVariables(document),
+            document: normalized,
+            overlays,
         },
     };
 }

package/dist/theme.d.ts

@@ -1,82 +1,44 @@
 /**
- * `ggui.json#theme` → plain DTCG JSON document.
+ * `ggui.json#theme` → plain DTCG JSON document, v2 (ggui#987).
  *
  * The theme file is a plain JSON document matching the Design Tokens
- * Community Group (DTCG) spec. It is one of the open file-format
- * surfaces in the ggui manifest model, alongside
- * `ggui.primitives.json` and `ggui.ui.json`.
+ * Community Group (DTCG) spec, in the same vocabulary as
+ * `@ggui-ai/design`'s canonical {@link DtcgTheme}: the curated registry
+ * themes and an authored `theme.json` are the same shape.
  *
- * **Shape parity with the internal `DtcgTheme`.** This v1 schema is
- * deliberately the same shape as `@ggui-ai/design`'s canonical
- * {@link DtcgTheme} — `color`/`font`/`spacing`/`shape`/`motion`/
- * `accessibility`/`zIndex` — so an authored `theme.json`
- * uses the same vocabulary the curated registry themes (light/dark/
- * premium-*) use. Previously this schema was Tailwind-style flat
- * (`typography`/`radius`/`shadow` at root); the v1 schema now mirrors
- * the internal shape to remove the divergence.
+ * **What is authored, what is derived.** An author states the six
+ * layering roles (`ground`/`onGround`, `container`/`onContainer`,
+ * `sunken`/`onSunken`), one `500` anchor per family (`primary`,
+ * `success`, `warning`, `error`, `info`), the font families and
+ * weights, spacing, radii, shadows. Everything else — the ten-stop
+ * ramps, every `on*` ink and container, the neutral ladder, outlines,
+ * `elevated`, the type scale from the one `font.ramp` — is DERIVED by
+ * the one producer (`deriveThemeVariables`), so the retired ladders
+ * (`font.size`, `font.lineHeight`, `motion.duration`, `motion.easing`)
+ * and `$metadata.fontUrl` are refused, not ignored. Fonts are declared
+ * as `typography.faces` (https `src` only); the card installs them.
  *
- * **External-tool compatibility.** External tooling (Figma Tokens,
- * Style Dictionary, Tokens Studio) commonly emits only a subset of
- * the canonical shape. Only the original required groups (`color`,
- * `font`, `spacing`, `shape`) stay required; `motion`,
- * `accessibility`, `zIndex`, and the new DTCG metadata fields
- * (`$name`, `$description`, `$metadata`) are all OPTIONAL so tools
- * that only emit colors + dimensions still parse cleanly.
- *
- * **BREAKING for old `theme.json` files.** Authors who hand-wrote a
- * `theme.json` against the pre-rc schema must rename:
- *
- *   - `typography.fontFamily` → `font.family`
- *   - `typography.fontSize` → `font.size`
- *   - `typography.fontWeight` → `font.weight`
- *   - `typography.lineHeight` → `font.lineHeight`
- *   - top-level `radius` → `shape.radius`
- *   - top-level `shadow` → `shape.shadow`
- *   - top-level `duration` → `motion.duration`
- *   - top-level `transition` → `motion.transition`
- *
- * Plus: under `font.family`, `sans` is the only required sub-token
- * (was previously freeform); other family slots (`mono`, …) are
- * optional. The font-family record itself stays open so additional
- * named families parse without a schema change.
+ * **External-tool leniency.** `motion`, `accessibility`, `zIndex` and
+ * the DTCG metadata fields stay OPTIONAL; {@link normalizeThemeDocument}
+ * fills them from the shipped default and flattens the DTCG object
+ * forms (structured shadows, transitions, array font stacks) to the CSS
+ * strings the producer reads.
  *
  * **Ownership boundary:**
  *
  *   - *Where* the theme lives → `ggui.json#theme` (pointer string).
  *   - *What* the theme file looks like → this module's schema.
- *   - *How* DTCG tokens become CSS variables → `@ggui-ai/design`'s
- *     `generateCssVariables` (stays over there; this schema does not
- *     emit). The duck-typed walker accepts any DTCG-shaped tree, so
- *     the new nested groups (`font.size`, `shape.radius`, …) walk
- *     into `--ggui-font-size-md`/`--ggui-shape-radius-md` CSS vars
- *     without code changes.
+ *   - *How* the document becomes CSS variables → `@ggui-ai/design`'s
+ *     `deriveThemeVariables` (the loader calls it for both modes).
  *   - *Built-in default* when `theme` is absent → `@ggui-ai/design`'s
- *     shipped `lightTheme`.
- *
- * **Extending rules:**
- *
- *   1. Additive only within `schema: '1'`. New optional fields must
- *      default to no-op behaviour so older tooling ignores them.
- *   2. Framework-neutral + host-neutral. No vendor names in enum
- *      values, no build-pipeline fields.
- *   3. Root and per-group objects are strict — unknown keys fail
- *      parse. Same discipline as `ggui.json`, `ggui.ui.json`, and
- *      `ggui.primitives.json`.
+ *     shipped `lightTheme` / `darkTheme`.
  *
- * **Strictness tradeoff:**
- *
- * Individual DTCG token leaves are validated with a discriminated
- * union over `$type` (color / dimension / fontFamily / fontWeight /
- * shadow / duration / cubicBezier / transition / number). Each
- * variant validates its `$value` shape. `$description` is accepted
- * everywhere as a free-form docstring. Token leaves under newer
- * groups (`accessibility`, `zIndex`) accept a slightly
- * wider token vocabulary because external tools sometimes encode
- * scalar/array values with permissive `$type` strings (`string`,
- * `array`, …); the schema accepts those without enumerating every
- * possible spelling.
+ * **Extending rules:** additive only within `schema: '1'`; framework-
+ * and host-neutral; root and per-group objects are strict — unknown
+ * keys fail parse, the same discipline as `ggui.json`.
  */
 import { z } from 'zod';
+import type { DtcgTheme } from '@ggui-ai/design/themes';
 /**
  * Plain DTCG theme document v1. Required groups (`color`, `font`,
  * `spacing`, `shape`) map 1:1 to `@ggui-ai/design`'s
@@ -96,25 +58,188 @@ import { z } from 'zod';
  * allow-listed (DTCG metadata); anything else is a typo. Additive
  * slices add new fields here under `schema: '1'`.
  */
-export declare const ThemeDocumentV1: z.ZodObject<{
+export declare const ThemeDocumentV2: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     $version: z.ZodOptional<z.ZodString>;
     $name: z.ZodOptional<z.ZodString>;
     $description: z.ZodOptional<z.ZodString>;
     $metadata: z.ZodOptional<z.ZodObject<{
         font: z.ZodOptional<z.ZodString>;
-        fontUrl: z.ZodOptional<z.ZodString>;
         philosophy: z.ZodOptional<z.ZodString>;
+        frameless: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
-    color: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
-        $type: z.ZodLiteral<"color">;
-        $value: z.ZodString;
-        $description: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>, z.ZodRecord<z.ZodString, z.ZodObject<{
-        $type: z.ZodLiteral<"color">;
-        $value: z.ZodString;
-        $description: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>>]>>;
+    color: z.ZodObject<{
+        primary: z.ZodRecord<z.ZodString, z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        neutral: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        success: z.ZodRecord<z.ZodString, z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        warning: z.ZodRecord<z.ZodString, z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        error: z.ZodRecord<z.ZodString, z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        info: z.ZodRecord<z.ZodString, z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        ground: z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        onGround: z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        container: z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        onContainer: z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        sunken: z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        onSunken: z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        link: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        outline: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        outlineVariant: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onPrimary: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        primaryContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onPrimaryContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onSuccess: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        successContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onSuccessContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onWarning: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        warningContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onWarningContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onError: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        errorContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onErrorContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onInfo: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        infoContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onInfoContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        tertiary: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onTertiary: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        tertiaryContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        onTertiaryContainer: z.ZodOptional<z.ZodObject<{
+            $type: z.ZodLiteral<"color">;
+            $value: z.ZodString;
+            $description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
     spacing: z.ZodRecord<z.ZodString, z.ZodObject<{
         $type: z.ZodLiteral<"dimension">;
         $value: z.ZodString;
@@ -132,26 +257,45 @@ export declare const ThemeDocumentV1: z.ZodObject<{
                 $description: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>;
         }, z.core.$strip>>;
-        size: z.ZodRecord<z.ZodString, z.ZodObject<{
-            $type: z.ZodLiteral<"dimension">;
-            $value: z.ZodString;
-            $description: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>;
         weight: z.ZodRecord<z.ZodString, z.ZodObject<{
             $type: z.ZodLiteral<"fontWeight">;
             $value: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
             $description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
-        lineHeight: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
-            $type: z.ZodLiteral<"number">;
-            $value: z.ZodNumber;
-            $description: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>, z.ZodObject<{
-            $type: z.ZodLiteral<"dimension">;
-            $value: z.ZodString;
-            $description: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>>;
+        letterSpacing: z.ZodOptional<z.ZodObject<{
+            body: z.ZodOptional<z.ZodObject<{
+                $type: z.ZodLiteral<"dimension">;
+                $value: z.ZodString;
+                $description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            heading: z.ZodOptional<z.ZodObject<{
+                $type: z.ZodLiteral<"dimension">;
+                $value: z.ZodString;
+                $description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        ramp: z.ZodOptional<z.ZodObject<{
+            base: z.ZodObject<{
+                $type: z.ZodLiteral<"dimension">;
+                $value: z.ZodString;
+                $description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            ratio: z.ZodObject<{
+                $type: z.ZodLiteral<"number">;
+                $value: z.ZodNumber;
+                $description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
+    typography: z.ZodOptional<z.ZodObject<{
+        faces: 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>>>;
+    }, z.core.$strict>>;
     shape: z.ZodObject<{
         radius: z.ZodRecord<z.ZodString, z.ZodObject<{
             $type: z.ZodLiteral<"dimension">;
@@ -169,18 +313,20 @@ export declare const ThemeDocumentV1: z.ZodObject<{
             }, z.core.$strict>]>;
             $description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
+        border: z.ZodOptional<z.ZodObject<{
+            width: z.ZodOptional<z.ZodObject<{
+                $type: z.ZodLiteral<"dimension">;
+                $value: z.ZodString;
+                $description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            style: z.ZodOptional<z.ZodObject<{
+                $type: z.ZodString;
+                $value: z.ZodString;
+                $description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>;
     motion: z.ZodOptional<z.ZodObject<{
-        duration: z.ZodRecord<z.ZodString, z.ZodObject<{
-            $type: z.ZodLiteral<"duration">;
-            $value: z.ZodString;
-            $description: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>;
-        easing: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
-            $type: z.ZodLiteral<"cubicBezier">;
-            $value: z.ZodString;
-            $description: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>>>;
         transition: z.ZodRecord<z.ZodString, z.ZodObject<{
             $type: z.ZodLiteral<"transition">;
             $value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
@@ -192,7 +338,7 @@ export declare const ThemeDocumentV1: z.ZodObject<{
         }, z.core.$strict>>;
         keyframes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             $type: z.ZodString;
-            $value: z.ZodUnknown;
+            $value: z.ZodString;
             $description: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
@@ -251,9 +397,9 @@ export declare const ThemeDocumentV1: z.ZodObject<{
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 /** Static TypeScript type derived from the v1 schema. */
-export type ThemeDocumentV1 = z.infer<typeof ThemeDocumentV1>;
+export type ThemeDocumentV2 = z.infer<typeof ThemeDocumentV2>;
 /** Canonical type alias used everywhere else. */
-export type ThemeDocument = ThemeDocumentV1;
+export type ThemeDocument = ThemeDocumentV2;
 /**
  * Parse a raw JSON value into a validated {@link ThemeDocument}.
  * Throws a `ZodError` with human-readable issues on invalid input.
@@ -264,5 +410,23 @@ export declare function parseThemeDocument(raw: unknown): ThemeDocument;
  * Prefer this inside CLI tooling where you want to render the issue
  * list without try/catch.
  */
-export declare function safeParseThemeDocument(raw: unknown): ReturnType<typeof ThemeDocumentV1.safeParse>;
+export declare function safeParseThemeDocument(raw: unknown): ReturnType<typeof ThemeDocumentV2.safeParse>;
+/**
+ * Turn a parsed document into the EXACT {@link DtcgTheme} the one
+ * producer (`deriveThemeVariables`) consumes:
+ *
+ *   - names the document (`$name` ⇒ `'custom'`, `$description` ⇒ `''`);
+ *   - drops the DTCG envelope fields the producer does not read
+ *     (`$schema`, `$version`);
+ *   - flattens the DTCG object forms to the CSS strings the producer
+ *     reads: array font stacks → `'Inter, system-ui'`, numeric weights →
+ *     `'400'`, structured shadows → `'0 1px 2px 0 …'`, structured
+ *     transitions → `'<property ?? all> <duration> <timingFunction>'`;
+ *   - fills the optional groups (`motion`, `accessibility`, `zIndex` and
+ *     their sub-records) from the shipped default, so an external tool's
+ *     colours-and-dimensions export still derives every consumed token.
+ *
+ * The authored roles, anchors and faces pass through verbatim.
+ */
+export declare function normalizeThemeDocument(doc: ThemeDocument): DtcgTheme;
 //# sourceMappingURL=theme.d.ts.map

package/dist/theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA4OxB;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA0C1B,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG,eAAe,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,eAAe,CAAC,SAAS,CAAC,CAE9C"}
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["../src/theme.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,wBAAwB,CAAC;AA0PnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA6C1B,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D,iDAAiD;AACjD,MAAM,MAAM,aAAa,GAAG,eAAe,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAE9D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,eAAe,CAAC,SAAS,CAAC,CAE9C;AAYD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,aAAa,GAAG,SAAS,CAmDpE"}

package/dist/theme.js

@@ -1,82 +1,44 @@
 /**
- * `ggui.json#theme` → plain DTCG JSON document.
+ * `ggui.json#theme` → plain DTCG JSON document, v2 (ggui#987).
  *
  * The theme file is a plain JSON document matching the Design Tokens
- * Community Group (DTCG) spec. It is one of the open file-format
- * surfaces in the ggui manifest model, alongside
- * `ggui.primitives.json` and `ggui.ui.json`.
+ * Community Group (DTCG) spec, in the same vocabulary as
+ * `@ggui-ai/design`'s canonical {@link DtcgTheme}: the curated registry
+ * themes and an authored `theme.json` are the same shape.
  *
- * **Shape parity with the internal `DtcgTheme`.** This v1 schema is
- * deliberately the same shape as `@ggui-ai/design`'s canonical
- * {@link DtcgTheme} — `color`/`font`/`spacing`/`shape`/`motion`/
- * `accessibility`/`zIndex` — so an authored `theme.json`
- * uses the same vocabulary the curated registry themes (light/dark/
- * premium-*) use. Previously this schema was Tailwind-style flat
- * (`typography`/`radius`/`shadow` at root); the v1 schema now mirrors
- * the internal shape to remove the divergence.
+ * **What is authored, what is derived.** An author states the six
+ * layering roles (`ground`/`onGround`, `container`/`onContainer`,
+ * `sunken`/`onSunken`), one `500` anchor per family (`primary`,
+ * `success`, `warning`, `error`, `info`), the font families and
+ * weights, spacing, radii, shadows. Everything else — the ten-stop
+ * ramps, every `on*` ink and container, the neutral ladder, outlines,
+ * `elevated`, the type scale from the one `font.ramp` — is DERIVED by
+ * the one producer (`deriveThemeVariables`), so the retired ladders
+ * (`font.size`, `font.lineHeight`, `motion.duration`, `motion.easing`)
+ * and `$metadata.fontUrl` are refused, not ignored. Fonts are declared
+ * as `typography.faces` (https `src` only); the card installs them.
  *
- * **External-tool compatibility.** External tooling (Figma Tokens,
- * Style Dictionary, Tokens Studio) commonly emits only a subset of
- * the canonical shape. Only the original required groups (`color`,
- * `font`, `spacing`, `shape`) stay required; `motion`,
- * `accessibility`, `zIndex`, and the new DTCG metadata fields
- * (`$name`, `$description`, `$metadata`) are all OPTIONAL so tools
- * that only emit colors + dimensions still parse cleanly.
- *
- * **BREAKING for old `theme.json` files.** Authors who hand-wrote a
- * `theme.json` against the pre-rc schema must rename:
- *
- *   - `typography.fontFamily` → `font.family`
- *   - `typography.fontSize` → `font.size`
- *   - `typography.fontWeight` → `font.weight`
- *   - `typography.lineHeight` → `font.lineHeight`
- *   - top-level `radius` → `shape.radius`
- *   - top-level `shadow` → `shape.shadow`
- *   - top-level `duration` → `motion.duration`
- *   - top-level `transition` → `motion.transition`
- *
- * Plus: under `font.family`, `sans` is the only required sub-token
- * (was previously freeform); other family slots (`mono`, …) are
- * optional. The font-family record itself stays open so additional
- * named families parse without a schema change.
+ * **External-tool leniency.** `motion`, `accessibility`, `zIndex` and
+ * the DTCG metadata fields stay OPTIONAL; {@link normalizeThemeDocument}
+ * fills them from the shipped default and flattens the DTCG object
+ * forms (structured shadows, transitions, array font stacks) to the CSS
+ * strings the producer reads.
  *
  * **Ownership boundary:**
  *
  *   - *Where* the theme lives → `ggui.json#theme` (pointer string).
  *   - *What* the theme file looks like → this module's schema.
- *   - *How* DTCG tokens become CSS variables → `@ggui-ai/design`'s
- *     `generateCssVariables` (stays over there; this schema does not
- *     emit). The duck-typed walker accepts any DTCG-shaped tree, so
- *     the new nested groups (`font.size`, `shape.radius`, …) walk
- *     into `--ggui-font-size-md`/`--ggui-shape-radius-md` CSS vars
- *     without code changes.
+ *   - *How* the document becomes CSS variables → `@ggui-ai/design`'s
+ *     `deriveThemeVariables` (the loader calls it for both modes).
  *   - *Built-in default* when `theme` is absent → `@ggui-ai/design`'s
- *     shipped `lightTheme`.
- *
- * **Extending rules:**
+ *     shipped `lightTheme` / `darkTheme`.
  *
- *   1. Additive only within `schema: '1'`. New optional fields must
- *      default to no-op behaviour so older tooling ignores them.
- *   2. Framework-neutral + host-neutral. No vendor names in enum
- *      values, no build-pipeline fields.
- *   3. Root and per-group objects are strict — unknown keys fail
- *      parse. Same discipline as `ggui.json`, `ggui.ui.json`, and
- *      `ggui.primitives.json`.
- *
- * **Strictness tradeoff:**
- *
- * Individual DTCG token leaves are validated with a discriminated
- * union over `$type` (color / dimension / fontFamily / fontWeight /
- * shadow / duration / cubicBezier / transition / number). Each
- * variant validates its `$value` shape. `$description` is accepted
- * everywhere as a free-form docstring. Token leaves under newer
- * groups (`accessibility`, `zIndex`) accept a slightly
- * wider token vocabulary because external tools sometimes encode
- * scalar/array values with permissive `$type` strings (`string`,
- * `array`, …); the schema accepts those without enumerating every
- * possible spelling.
+ * **Extending rules:** additive only within `schema: '1'`; framework-
+ * and host-neutral; root and per-group objects are strict — unknown
+ * keys fail parse, the same discipline as `ggui.json`.
  */
 import { z } from 'zod';
+import { lightTheme } from '@ggui-ai/design/themes';
 // ─── Token leaves ────────────────────────────────────────────────────
 /** A CSS color string. `$value` is not structurally validated (hex,
  *  rgba, color-mix, named, etc. are all legal DTCG colors). */
@@ -112,14 +74,6 @@ const DurationToken = z.strictObject({
     $value: z.string().min(1),
     $description: z.string().optional(),
 });
-/** DTCG cubic-bezier easing token. `$value` is a CSS timing function
- *  string (`"cubic-bezier(0.4, 0, 0.2, 1)"`, keyword aliases like
- *  `"ease-out"`, etc.). */
-const CubicBezierToken = z.strictObject({
-    $type: z.literal('cubicBezier'),
-    $value: z.string().min(1),
-    $description: z.string().optional(),
-});
 /** Structured shadow value — DTCG spec composite shape. */
 const ShadowValue = z.strictObject({
     offsetX: z.string().min(1),
@@ -154,32 +108,34 @@ const NumberToken = z.strictObject({
     $description: z.string().optional(),
 });
 /** Line-height token — DTCG allows unit-less number or dimension. */
-const LineHeightToken = z.union([
-    z.strictObject({
-        $type: z.literal('number'),
-        $value: z.number(),
-        $description: z.string().optional(),
-    }),
-    z.strictObject({
-        $type: z.literal('dimension'),
-        $value: z.string().min(1),
-        $description: z.string().optional(),
-    }),
-]);
-/**
- * Permissive token leaf for the newer optional groups
- * (`motion.keyframes`, `zIndex`). DTCG hasn't standardised every
- * `$type` value the curated registry themes carry — for example
- * easing uses `$type: 'cubicBezier'`. Rather than
- * enumerate every spelling, this leaf accepts any `$type` string and
- * any JSON-serializable `$value`. Strict per-leaf shape stays in
- * force for the original token types via the leaves above.
- */
-const PermissiveToken = z.strictObject({
+/** A token whose `$value` is a CSS string under any `$type` spelling
+ *  (keyframes text, border style, …). */
+const StringToken = z.strictObject({
     $type: z.string().min(1),
-    $value: z.unknown(),
+    $value: z.string().min(1),
     $description: z.string().optional(),
 });
+/** A declared font face (ggui#987 §5): `src` MUST be `https:` with a
+ *  well-formed host — the same rule the design package asserts. */
+const FontFaceDeclarationSchema = z.strictObject({
+    family: z.string().min(1).refine((f) => !/[\r\n]/.test(f), 'family must be one line'),
+    src: z
+        .string()
+        .min(1)
+        .refine((src) => {
+        let url;
+        try {
+            url = new URL(src);
+        }
+        catch {
+            return false;
+        }
+        return url.protocol === 'https:' && /^[a-z0-9.-]+$/i.test(url.hostname) && url.hostname.includes('.');
+    }, 'src must be an https: URL with a well-formed host'),
+    weight: z.union([z.string().min(1), z.number().int().min(1).max(1000)]).optional(),
+    style: z.string().min(1).optional(),
+    display: z.string().min(1).optional(),
+});
 // ─── Groups ──────────────────────────────────────────────────────────
 /**
  * A "palette" group — a record of color tokens keyed by scale step
@@ -188,42 +144,68 @@ const PermissiveToken = z.strictObject({
  */
 const ColorPalette = z.record(z.string(), ColorToken);
 /**
- * Color group — two-tier: `{palette}` records for scales (primary /
- * neutral / semantic scales) plus single-token semantic roles
- * (surface / onSurface / outline / …) at the top level.
- *
- * Kept open (`z.record` not `z.strictObject`) so authored themes
- * can add brand-specific palettes (`accent`, `brand-green`, …) and
- * semantic roles without a schema change. `color` itself is
- * required but its internal shape is author-extensible.
- *
- * Each entry can be EITHER a singleton `ColorToken` (e.g. a Material
- * role like `surface`) OR a `ColorPalette` (a scale like `primary`'s
- * 50-900 stops). Tools that emit only singleton colors (no scales)
- * stay parseable.
+ * The colour block: five family anchors (`500` stated; the other stops
+ * derived unless stated) + the six layering roles, all REQUIRED; the
+ * derived roles (`neutral`, outlines, `on*` inks, containers,
+ * `tertiary`, `link`) are optional and win over derivation when stated.
  */
-const ColorGroup = z.record(z.string(), z.union([ColorToken, ColorPalette]));
+const ColorGroup = z.strictObject({
+    primary: ColorPalette,
+    neutral: ColorPalette.optional(),
+    success: ColorPalette,
+    warning: ColorPalette,
+    error: ColorPalette,
+    info: ColorPalette,
+    ground: ColorToken,
+    onGround: ColorToken,
+    container: ColorToken,
+    onContainer: ColorToken,
+    sunken: ColorToken,
+    onSunken: ColorToken,
+    link: ColorToken.optional(),
+    outline: ColorToken.optional(),
+    outlineVariant: ColorToken.optional(),
+    onPrimary: ColorToken.optional(),
+    primaryContainer: ColorToken.optional(),
+    onPrimaryContainer: ColorToken.optional(),
+    onSuccess: ColorToken.optional(),
+    successContainer: ColorToken.optional(),
+    onSuccessContainer: ColorToken.optional(),
+    onWarning: ColorToken.optional(),
+    warningContainer: ColorToken.optional(),
+    onWarningContainer: ColorToken.optional(),
+    onError: ColorToken.optional(),
+    errorContainer: ColorToken.optional(),
+    onErrorContainer: ColorToken.optional(),
+    onInfo: ColorToken.optional(),
+    infoContainer: ColorToken.optional(),
+    onInfoContainer: ColorToken.optional(),
+    tertiary: ColorToken.optional(),
+    onTertiary: ColorToken.optional(),
+    tertiaryContainer: ColorToken.optional(),
+    onTertiaryContainer: ColorToken.optional(),
+});
 const SpacingGroup = z.record(z.string(), DimensionToken);
 /**
- * Font group — `family` / `size` / `weight` / `lineHeight` records.
- * Renamed from `typography` (previously: `typography.fontFamily`,
- * `typography.fontSize`, …) to mirror the internal `DtcgTheme`
- * shape's `font.family` / `font.size` / `font.weight` /
- * `font.lineHeight`.
- *
- * Inside `family`, `sans` is the only required slot — the canonical
- * theme always carries a sans-serif default. `mono` and any other
- * family slot (e.g. `serif`, `display`) are optional. The record
- * stays open so authors can declare additional named families.
+ * Font group — `family` (the `sans` slot required; `mono`, `heading`
+ * and any other named family optional) and `weight`; optional
+ * `letterSpacing` and the ONE `ramp` the type scale is derived from.
  */
+/** Font families: `sans` required; `mono`, `heading` and any other named family optional. */
 const FontFamilyGroup = z.record(z.string(), FontFamilyToken).and(z.object({
     sans: FontFamilyToken,
 }));
 const FontGroup = z.strictObject({
     family: FontFamilyGroup,
-    size: z.record(z.string(), DimensionToken),
     weight: z.record(z.string(), FontWeightToken),
-    lineHeight: z.record(z.string(), LineHeightToken),
+    letterSpacing: z
+        .strictObject({ body: DimensionToken.optional(), heading: DimensionToken.optional() })
+        .optional(),
+    ramp: z.strictObject({ base: DimensionToken, ratio: NumberToken }).optional(),
+});
+/** Declared font faces (ggui#987 §5). */
+const TypographyGroup = z.strictObject({
+    faces: z.array(FontFaceDeclarationSchema).optional(),
 });
 /**
  * Shape group — `radius` + `shadow`. Moved here from the previous
@@ -233,18 +215,16 @@ const FontGroup = z.strictObject({
 const ShapeGroup = z.strictObject({
     radius: z.record(z.string(), DimensionToken),
     shadow: z.record(z.string(), ShadowToken),
+    border: z.strictObject({ width: DimensionToken.optional(), style: StringToken.optional() }).optional(),
 });
 /**
- * Motion group — `duration` / `easing` / `transition` / `keyframes`.
- * Moved here from the previous top-level `duration` and `transition`
- * fields. `easing` and `keyframes` are optional because external
- * tools (Figma Tokens, Style Dictionary) don't always emit them.
+ * Motion group — `transition` (required sub-record) + `keyframes`
+ * (optional). Durations and easings are not ladders any more: they ride
+ * each transition's own value.
  */
 const MotionGroup = z.strictObject({
-    duration: z.record(z.string(), DurationToken),
-    easing: z.record(z.string(), CubicBezierToken).optional(),
     transition: z.record(z.string(), TransitionToken),
-    keyframes: z.record(z.string(), PermissiveToken).optional(),
+    keyframes: z.record(z.string(), StringToken).optional(),
 });
 const AccessibilityGroup = z.strictObject({
     focusRing: z
@@ -276,8 +256,9 @@ const ZIndexGroup = z.record(z.string(), NumberToken);
  */
 const MetadataGroup = z.strictObject({
     font: z.string().min(1).optional(),
-    fontUrl: z.string().min(1).optional(),
     philosophy: z.string().min(1).optional(),
+    /** The embedding host draws the card silhouette; the renderer suppresses root-children strokes. */
+    frameless: z.boolean().optional(),
 });
 // ─── Root document ───────────────────────────────────────────────────
 /**
@@ -299,7 +280,7 @@ const MetadataGroup = z.strictObject({
  * allow-listed (DTCG metadata); anything else is a typo. Additive
  * slices add new fields here under `schema: '1'`.
  */
-export const ThemeDocumentV1 = z.strictObject({
+export const ThemeDocumentV2 = z.strictObject({
     /** Optional DTCG spec URL. Not validated — the spec hasn't frozen
      *  a canonical URL and hand-authored themes often omit it. */
     $schema: z.string().min(1).optional(),
@@ -320,6 +301,8 @@ export const ThemeDocumentV1 = z.strictObject({
     spacing: SpacingGroup,
     /** Font tokens — `family` / `size` / `weight` / `lineHeight`. Required. */
     font: FontGroup,
+    /** Declared font faces (ggui#987 §5) — https `src` only; the card installs them. */
+    typography: TypographyGroup.optional(),
     /** Shape tokens — `radius` + `shadow`. Required. */
     shape: ShapeGroup,
     /** Motion tokens — `duration` + `transition` (required sub-records),
@@ -336,7 +319,7 @@ export const ThemeDocumentV1 = z.strictObject({
  * Throws a `ZodError` with human-readable issues on invalid input.
  */
 export function parseThemeDocument(raw) {
-    return ThemeDocumentV1.parse(raw);
+    return ThemeDocumentV2.parse(raw);
 }
 /**
  * Safe-parse variant — returns a discriminated `z.safeParse` result.
@@ -344,5 +327,69 @@ export function parseThemeDocument(raw) {
  * list without try/catch.
  */
 export function safeParseThemeDocument(raw) {
-    return ThemeDocumentV1.safeParse(raw);
+    return ThemeDocumentV2.safeParse(raw);
+}
+// ─── Normalisation → the producer's document ─────────────────────────
+function stringToken(token, value) {
+    return { $type: token.$type, $value: value, ...(token.$description !== undefined ? { $description: token.$description } : {}) };
+}
+function mapRecord(record, f) {
+    return Object.fromEntries(Object.entries(record).map(([k, v]) => [k, f(v)]));
+}
+/**
+ * Turn a parsed document into the EXACT {@link DtcgTheme} the one
+ * producer (`deriveThemeVariables`) consumes:
+ *
+ *   - names the document (`$name` ⇒ `'custom'`, `$description` ⇒ `''`);
+ *   - drops the DTCG envelope fields the producer does not read
+ *     (`$schema`, `$version`);
+ *   - flattens the DTCG object forms to the CSS strings the producer
+ *     reads: array font stacks → `'Inter, system-ui'`, numeric weights →
+ *     `'400'`, structured shadows → `'0 1px 2px 0 …'`, structured
+ *     transitions → `'<property ?? all> <duration> <timingFunction>'`;
+ *   - fills the optional groups (`motion`, `accessibility`, `zIndex` and
+ *     their sub-records) from the shipped default, so an external tool's
+ *     colours-and-dimensions export still derives every consumed token.
+ *
+ * The authored roles, anchors and faces pass through verbatim.
+ */
+export function normalizeThemeDocument(doc) {
+    const family = doc.font.family;
+    const fontFamily = (t) => stringToken(t, Array.isArray(t.$value) ? t.$value.join(', ') : t.$value);
+    const accessibility = doc.accessibility;
+    return {
+        $name: doc.$name ?? 'custom',
+        $description: doc.$description ?? '',
+        ...(doc.$metadata !== undefined ? { $metadata: doc.$metadata } : {}),
+        color: doc.color,
+        font: {
+            family: { ...mapRecord(family, fontFamily), sans: fontFamily(family.sans) },
+            weight: mapRecord(doc.font.weight, (t) => stringToken(t, String(t.$value))),
+            ...(doc.font.letterSpacing !== undefined ? { letterSpacing: doc.font.letterSpacing } : {}),
+            ...(doc.font.ramp !== undefined ? { ramp: doc.font.ramp } : {}),
+        },
+        ...(doc.typography !== undefined ? { typography: doc.typography } : {}),
+        spacing: doc.spacing,
+        shape: {
+            radius: doc.shape.radius,
+            shadow: mapRecord(doc.shape.shadow, (t) => stringToken(t, typeof t.$value === 'string'
+                ? t.$value
+                : `${t.$value.offsetX} ${t.$value.offsetY} ${t.$value.blur} ${t.$value.spread} ${t.$value.color}`)),
+            ...(doc.shape.border !== undefined ? { border: doc.shape.border } : {}),
+        },
+        motion: doc.motion === undefined
+            ? lightTheme.motion
+            : {
+                transition: mapRecord(doc.motion.transition, (t) => stringToken(t, typeof t.$value === 'string'
+                    ? t.$value
+                    : `${t.$value.property ?? 'all'} ${t.$value.duration} ${t.$value.timingFunction}`)),
+                keyframes: doc.motion.keyframes ?? lightTheme.motion.keyframes,
+            },
+        accessibility: {
+            focusRing: accessibility?.focusRing ?? lightTheme.accessibility.focusRing,
+            reducedMotion: accessibility?.reducedMotion ?? lightTheme.accessibility.reducedMotion,
+            highContrast: accessibility?.highContrast ?? lightTheme.accessibility.highContrast,
+        },
+        zIndex: doc.zIndex ?? lightTheme.zIndex,
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/project-config",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Schema and loader for `ggui.json` — the portable app/agent manifest for the ggui protocol. Vendor-neutral. Consumed by the `ggui` CLI and any host that reconstitutes an agent from the manifest.",
   "keywords": [
     "ggui",
@@ -33,8 +33,8 @@
   "dependencies": {
     "tinyglobby": "^0.2.16",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.14.0",
-    "@ggui-ai/protocol": "0.14.0"
+    "@ggui-ai/design": "0.16.0",
+    "@ggui-ai/protocol": "0.16.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",