@caelo-cms/shared 0.10.22 → 0.10.24

package/dist/themes-errors.js

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Typed errors emitted by the theme primitive (#45, v0.11.0).
+ *
+ * Per CLAUDE.md §11 ("Failure surfaces are AI-actionable") every error
+ * includes the next step the AI should try inside `.message`. The ops
+ * layer wraps these as `err({kind:"HandlerError", message})`; the AI
+ * tool layer returns them in `content`. Inline classes (vs ad-hoc
+ * strings) so callers can `instanceof` to surface structured fields
+ * (suggestions, supported formats) to the UI / system-prompt later.
+ */
+/**
+ * Loose token name could not be normalized to a canonical DTCG path.
+ * Carries the closest-match suggestions so the AI's next attempt has
+ * a concrete target.
+ */
+export class UnknownTokenName extends Error {
+    input;
+    suggestions;
+    constructor(input, suggestions) {
+        const tail = suggestions.length > 0
+            ? ` — did you mean ${suggestions.map((s) => `'${s}'`).join(" or ")}?`
+            : " — pass a canonical DTCG path like 'color.primary' or 'typography.heading.fontFamily'";
+        super(`UnknownTokenName: cannot infer canonical path for '${input}'${tail}`);
+        this.name = "UnknownTokenName";
+        this.input = input;
+        this.suggestions = suggestions;
+    }
+}
+/**
+ * Value supplied for a color token isn't in a supported CSS color
+ * format. The message names every format we accept so the AI's retry
+ * lands.
+ */
+export class InvalidColorValue extends Error {
+    input;
+    supportedFormats = [
+        "#rrggbb",
+        "#rgb",
+        "oklch(L C H)",
+        "oklch(L C H / A)",
+        "rgb(R G B)",
+        "rgb(R G B / A)",
+    ];
+    constructor(input) {
+        super(`InvalidColorValue: '${input}' is not a recognised CSS color — supported formats: ${[
+            "#rrggbb",
+            "#rgb",
+            "oklch(L C H)",
+            "rgb(R G B)",
+        ].join(", ")}. Try a hex like '#3b82f6' or 'oklch(0.6 0.2 250)'.`);
+        this.name = "InvalidColorValue";
+        this.input = input;
+    }
+}
+/**
+ * v0.11.0 (#45 opt §2) — `themes.import_dtcg` was handed a JSON body
+ * whose shape doesn't look like DTCG (no `$value` anywhere in the
+ * tree). v0.11.1 (issue #76) — auto-detect chain uses this as a
+ * "fall through to next importer" signal; only surfaces verbatim when
+ * the caller explicitly picked the DTCG importer.
+ */
+export class NotDtcgShape extends Error {
+    constructor(message) {
+        super(message ??
+            "NotDtcgShape: the JSON body parsed cleanly but doesn't look like a DTCG document " +
+                "(no `$value` keys anywhere in the tree). Send a DTCG-shaped document — see " +
+                "https://www.designtokens.org/tr/drafts/format/ for the spec.");
+        this.name = "NotDtcgShape";
+    }
+}
+/**
+ * v0.11.1 (issue #76) — Style Dictionary importer rejected input.
+ * Used as a fall-through signal by the auto-detect chain.
+ */
+export class NotStyleDictionaryShape extends Error {
+    constructor(message) {
+        super(message ??
+            "NotStyleDictionaryShape: input has no nested `{ value: … }` leaves typical of " +
+                "Style Dictionary v3/v4. Looks like another format — try DTCG ($value leaves), " +
+                "Tailwind 4 (@theme block), or shadcn (:root CSS variables).");
+        this.name = "NotStyleDictionaryShape";
+    }
+}
+/**
+ * v0.11.1 (issue #76) — Tailwind 4 `@theme { … }` importer rejected
+ * input. Either no `@theme` block found, or the body contained a
+ * construct the line-by-line parser can't handle (calc(), nested
+ * at-rules). Auto-detect chain catches it and falls through.
+ */
+export class NotTailwindShape extends Error {
+    constructor(message) {
+        super(message ??
+            "NotTailwindShape: input has no `@theme { … }` block. Send the contents of your " +
+                "Tailwind 4 theme file or use a different importer.");
+        this.name = "NotTailwindShape";
+    }
+}
+/**
+ * v0.11.1 (issue #76) — Tailwind 4 importer hit a construct it can't
+ * parse (e.g. `calc(…)` values, nested at-rules). Surfaced verbatim
+ * by the auto-detect chain since the input WAS Tailwind-shaped — the
+ * caller should simplify or pre-resolve.
+ */
+export class TailwindImportError extends Error {
+    construct;
+    constructor(construct, line) {
+        super(`TailwindImportError: the @theme block contains '${construct}' which the importer can't parse: '${line.trim()}'. ` +
+            "Pre-resolve calc()/var() to literal values, or split nested at-rules into a separate file.");
+        this.name = "TailwindImportError";
+        this.construct = construct;
+    }
+}
+/**
+ * v0.11.1 (issue #76) — shadcn `:root { … }` importer rejected input
+ * (no `:root` selector found, or values were wrapped in `{value: …}`
+ * style-dictionary shape). Auto-detect chain falls through.
+ */
+export class NotShadcnShape extends Error {
+    constructor(message) {
+        super(message ??
+            "NotShadcnShape: input has no `:root { … }` CSS block with `--<name>: <value>;` pairs. " +
+                "Send a shadcn-style CSS variable list (with optional `.dark { … }` for dark mode).");
+        this.name = "NotShadcnShape";
+    }
+}
+/**
+ * v0.11.1 (issue #76) — loose JSON-object importer rejected input
+ * (not a JSON object, or contains `$value` / `value` leaves that
+ * belong to a different format). Auto-detect chain falls through.
+ */
+export class NotLooseShape extends Error {
+    constructor(message) {
+        super(message ?? "NotLooseShape: input is not a flat JSON object of `{looseName: value}` pairs.");
+        this.name = "NotLooseShape";
+    }
+}
+/**
+ * v0.11.1 (issue #76) — auto-detect chain ran every importer and none
+ * accepted the input. Carries per-format rejection reasons so the AI's
+ * next turn can fix the input or fall back to `set_theme_tokens`.
+ */
+export class NoImporterMatched extends Error {
+    attempts;
+    constructor(attempts) {
+        const summary = attempts.map((a) => `${a.format}: ${a.reason}`).join("; ");
+        super(`NoImporterMatched: none of the supported formats accepted the input. ${summary}. ` +
+            "Fix the input or fall back to `set_theme_tokens` with a normalized object.");
+        this.name = "NoImporterMatched";
+        this.attempts = attempts;
+    }
+}
+/**
+ * Loose-name input resolved to a canonical path but the value's
+ * inferred category doesn't match the category for that path
+ * (e.g. caller put a `0.5rem` value at `color.primary`).
+ */
+export class TokenCategoryMismatch extends Error {
+    canonicalPath;
+    expected;
+    got;
+    constructor(canonicalPath, expected, got) {
+        super(`TokenCategoryMismatch: '${canonicalPath}' expects a ${expected} value, got a ${got} — re-send with a value matching ${expected}.`);
+        this.name = "TokenCategoryMismatch";
+        this.canonicalPath = canonicalPath;
+        this.expected = expected;
+        this.got = got;
+    }
+}
+//# sourceMappingURL=themes-errors.js.map

package/dist/themes-errors.js.map

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

package/dist/themes.d.ts

@@ -0,0 +1,343 @@
+/**
+ * v0.11.0 — DTCG-aligned Zod schemas for the `themes` primitive (#45).
+ *
+ * Mirrors the W3C Design Tokens Format spec (2025.10 stable). Storage
+ * is a single jsonb document grouped by category (color / typography /
+ * spacing / radius / shadow / motion / breakpoint); each leaf carries a
+ * `$value` (required), optional `$type`, optional `$description`, and
+ * may use DTCG aliasing (`{group.token}`) to reference another token.
+ *
+ * Why DTCG: import/export from Figma / Tokens Studio / Style Dictionary
+ * works out of the box. The admin UI doesn't show raw DTCG to
+ * operators — it renders categorized panels — but the storage layer is
+ * the lingua franca so design tooling round-trips cleanly.
+ *
+ * Caelo extensions over plain DTCG:
+ * - Color tokens may carry `{ light, dark }` instead of a flat `$value`
+ *   so the renderer can emit `:root { … }` + `:root.dark { … }` from
+ *   one declaration.
+ * - The `$extensions` namespace is tolerated (DTCG-spec-compatible)
+ *   for tooling-specific metadata; we never inspect it server-side.
+ */
+import { z } from "zod";
+/**
+ * Color token. Either a flat `$value` or a `{light, dark}` pair where
+ * the renderer emits the light value in `:root { … }` and the dark
+ * value in `:root.dark { … }`.
+ */
+export declare const themeColorToken: z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodString]>, z.ZodObject<{
+        light: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+        dark: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+    }, z.core.$strict>]>;
+    $type: z.ZodOptional<z.ZodLiteral<"color">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const themeDimensionToken: z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"dimension">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/**
+ * Typography composite. Each sub-field is independently optional so a
+ * document can ship a heading family without forcing a size, and vice
+ * versa. The renderer emits one CSS variable per declared sub-field
+ * (`--font-<name>`, `--text-<name>`, `--font-weight-<name>`, ...).
+ */
+export declare const themeTypographyComposite: z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodObject<{
+        fontFamily: z.ZodOptional<z.ZodString>;
+        fontSize: z.ZodOptional<z.ZodString>;
+        fontWeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+            bold: "bold";
+            normal: "normal";
+            lighter: "lighter";
+            bolder: "bolder";
+        }>]>>;
+        lineHeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        letterSpacing: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"typography">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const themeShadowComposite: z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodObject<{
+        color: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+        offsetX: z.ZodString;
+        offsetY: z.ZodString;
+        blur: z.ZodString;
+        spread: z.ZodOptional<z.ZodString>;
+        inset: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodArray<z.ZodObject<{
+        color: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+        offsetX: z.ZodString;
+        offsetY: z.ZodString;
+        blur: z.ZodString;
+        spread: z.ZodOptional<z.ZodString>;
+        inset: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>, z.ZodString, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"shadow">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const themeDurationToken: z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"duration">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const themeCubicBezierToken: z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"cubicBezier">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/**
+ * Easing token for `motion.easing`. Accepts, in order of how models
+ * emit them: a CSS easing keyword / `cubic-bezier(...)` string, the DTCG
+ * `cubicBezier` `[x1,y1,x2,y2]` tuple, or a DTCG alias. `$type` may be
+ * omitted, `cubicBezier` (DTCG), or `easing` (Caelo shorthand).
+ */
+export declare const themeEasingToken: z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodString, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"cubicBezier">, z.ZodLiteral<"easing">]>>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const themeGradientToken: z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"gradient">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/**
+ * Any token, in any category. The discriminator is the parent group
+ * key (`color.*` → color, `spacing.*` → dimension, ...), but DTCG
+ * doesn't strictly require `$type` so we accept any leaf carrying a
+ * valid `$value`. Per-category strictness is enforced at the
+ * normalizer + the renderer (which know which namespace the token
+ * is being emitted into).
+ */
+declare const anyThemeToken: z.ZodUnion<readonly [z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodString]>, z.ZodObject<{
+        light: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+        dark: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+    }, z.core.$strict>]>;
+    $type: z.ZodOptional<z.ZodLiteral<"color">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"dimension">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodObject<{
+        fontFamily: z.ZodOptional<z.ZodString>;
+        fontSize: z.ZodOptional<z.ZodString>;
+        fontWeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+            bold: "bold";
+            normal: "normal";
+            lighter: "lighter";
+            bolder: "bolder";
+        }>]>>;
+        lineHeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+        letterSpacing: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"typography">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodObject<{
+        color: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+        offsetX: z.ZodString;
+        offsetY: z.ZodString;
+        blur: z.ZodString;
+        spread: z.ZodOptional<z.ZodString>;
+        inset: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>, z.ZodArray<z.ZodObject<{
+        color: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+        offsetX: z.ZodString;
+        offsetY: z.ZodString;
+        blur: z.ZodString;
+        spread: z.ZodOptional<z.ZodString>;
+        inset: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>, z.ZodString, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"shadow">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"duration">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"cubicBezier">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodString, z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"cubicBezier">, z.ZodLiteral<"easing">]>>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>, z.ZodObject<{
+    $value: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
+    $type: z.ZodOptional<z.ZodLiteral<"gradient">>;
+    $description: z.ZodOptional<z.ZodString>;
+    $extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>]>;
+/**
+ * One category group: a flat record of token-name → (token | sub-group
+ * | `$`-prefixed metadata). DTCG allows arbitrary nesting; the
+ * structural constraints (every non-`$` key must validate as a token
+ * or nested group; `$description` must be a string) are enforced by
+ * the `superRefine` walker at runtime — the TS type stays a permissive
+ * `Record<string, unknown>` to match Zod's inferred type.
+ *
+ * Per DTCG spec, any group (including the document root) MAY carry
+ * `$description` / `$extensions` metadata alongside its real children.
+ * AI-composed documents do this at the root, and Figma / Tokens
+ * Studio / Style Dictionary exports do it at every level.
+ */
+type TokenGroup = Record<string, unknown>;
+/**
+ * Top-level DTCG document. Known category keys:
+ *
+ *   color, typography, spacing, radius, shadow, motion (duration +
+ *   cubicBezier sub-groups), breakpoint, gradient (issue #153 — CSS
+ *   gradient strings emitted as `--gradient-<name>`).
+ *
+ * Unknown root keys are tolerated because DTCG explicitly leaves the
+ * category vocabulary open — we don't want to reject a future
+ * `effect` category that operators bring from Figma.
+ * Root-level `$description` / `$extensions` are also tolerated (DTCG
+ * documents routinely carry these — the seeded default theme and
+ * Figma/Tokens Studio exports all have a root `$description`).
+ */
+export declare const themeDocument: z.ZodType<TokenGroup>;
+export type ThemeDocument = z.infer<typeof themeDocument>;
+export type ThemeColorToken = z.infer<typeof themeColorToken>;
+export type ThemeDimensionToken = z.infer<typeof themeDimensionToken>;
+export type ThemeTypographyComposite = z.infer<typeof themeTypographyComposite>;
+export type ThemeShadowComposite = z.infer<typeof themeShadowComposite>;
+export type ThemeGradientToken = z.infer<typeof themeGradientToken>;
+export type ThemeDurationToken = z.infer<typeof themeDurationToken>;
+export type ThemeCubicBezierToken = z.infer<typeof themeCubicBezierToken>;
+export type ThemeEasingToken = z.infer<typeof themeEasingToken>;
+export type AnyThemeToken = z.infer<typeof anyThemeToken>;
+/**
+ * Theme aggregate — row + resolved asset URLs. The asset URLs are
+ * derived server-side by joining `media`; the `{mediaId, url}` shape
+ * lets the renderer / system-prompt emit either form without re-loading.
+ */
+export interface ThemeAssetRef {
+    readonly mediaId: string;
+    readonly url: string;
+}
+/**
+ * v0.11.4 (issue #76 follow-up) — provenance of the current state.
+ * `seed`: untouched starter palette (e.g. shadcn-default populated by
+ * migration 0099). `ai`: most recent write was by an AI actor. `operator`:
+ * most recent write was by a human actor. The system-prompt `## Theme`
+ * block surfaces this so the AI knows whether it should evolve the
+ * palette for the site being built or treat it as an operator choice.
+ */
+export type ThemeOrigin = "seed" | "ai" | "operator";
+export interface Theme {
+    readonly id: string;
+    readonly slug: string;
+    readonly displayName: string;
+    readonly description: string | null;
+    readonly origin: ThemeOrigin;
+    readonly isActive: boolean;
+    readonly tokens: ThemeDocument;
+    readonly assets: {
+        readonly logo: ThemeAssetRef | null;
+        readonly logoDark: ThemeAssetRef | null;
+        readonly favicon: ThemeAssetRef | null;
+        readonly socialShare: ThemeAssetRef | null;
+    };
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/**
+ * Validate a tokens document. Returns the parsed tree on success;
+ * throws a ZodError on failure (caller wraps into the op's HandlerError
+ * shape per CLAUDE.md §4).
+ */
+export declare function validateThemeTokens(tokens: unknown): ThemeDocument;
+/**
+ * v0.11.1 (issue #76) — Zod schema for `propose_create_theme.overrides`.
+ *
+ * The base shape is a permissive `Record<string, unknown>` (same as
+ * v0.11.0) so loose names like `primaryColor` / `fontHeading` /
+ * `spacing-lg` continue to flow through `normalizeTokens`. The explicit
+ * `primaryColor` recognition (v0.11.1) is documented here — when set,
+ * the propose-create handler derives a `color.primary.{50..900}`
+ * OKLCh ramp from the value (each stop `_derived: true`) instead of
+ * landing a single `color.primary` leaf via the normalizer.
+ *
+ * Operator-supplied `color.primary.<stop>` paths in the same overrides
+ * map layer over the derived ramp (explicit-wins precedence).
+ */
+export declare const createThemeOverridesSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export type CreateThemeOverrides = z.infer<typeof createThemeOverridesSchema>;
+/**
+ * v0.11.1 (issue #76) — extract the `primaryColor` sentinel from a
+ * loose-name overrides map. Returns `{primaryColor, rest}` where `rest`
+ * is the same map minus the `primaryColor` key. Used by the propose-
+ * create handler to split the ramp-seed off before normalizing the
+ * remaining loose names.
+ */
+export declare function extractPrimaryColorSeed(overrides: Record<string, unknown> | undefined): {
+    primaryColor: string | undefined;
+    rest: Record<string, unknown>;
+};
+/**
+ * Walk a tokens document and produce a flat list of `(path, token)`
+ * pairs. Used by the renderer + alias resolver + summary formatter.
+ * Paths use dot-notation: `color.primary`, `typography.heading`,
+ * `color.brand.primary`, ...
+ */
+export declare function flattenTokens(tokens: ThemeDocument): Array<{
+    path: string;
+    token: AnyThemeToken;
+}>;
+/**
+ * Build a one-line category summary for the system-prompt `## Theme`
+ * block ("8 colors, 5 typography, 6 spacing, 5 radii, 3 shadows").
+ */
+export declare function summarizeTokens(tokens: ThemeDocument): string;
+/**
+ * v0.11.0 (#45, step-11 opt §5) — apply a canonical-path → value patch
+ * to a DTCG document. Returns a fresh document; the input is not
+ * mutated.
+ *
+ * Each entry in `writes` becomes a `{$value, $type}` leaf at the dotted
+ * canonical path. The `types` map carries the inferred DTCG `$type` for
+ * each path (already known to the normalizer) so the leaf advertises
+ * the right shape to consumers.
+ *
+ * Both themes.update_tokens (loose-input set path) and
+ * themes.propose_create's execute branch (tokens + overrides merge)
+ * use this same logic — extracted so the dotted-path merge lives in
+ * one place and v0.11.1's OKLCH auto-ramp can extend it without
+ * forking.
+ */
+export declare function applyDtcgWrites(current: ThemeDocument, writes: Record<string, unknown>, types: Record<string, string>): ThemeDocument;
+/**
+ * Companion to `applyDtcgWrites` — drop the leaf at a canonical path
+ * if it exists. Returns `{tokens, removed}` so the caller can report
+ * which paths were actually removed (silent on missing paths so a
+ * remove-list that includes already-absent keys is idempotent).
+ */
+export declare function removeDtcgPath(doc: ThemeDocument, path: string): {
+    tokens: ThemeDocument;
+    removed: boolean;
+};
+export {};
+//# sourceMappingURL=themes.d.ts.map

package/dist/themes.d.ts.map

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