create-ailk 0.7.0 → 0.9.0

package/dist/design-compile.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Compile a `DesignPackage` (design-package.ts) into the `theme:` block a
+ * site's `_site.mdx` carries (#6812 D4, spec docs/specs/6812-the-design-package-design-md-spec.md).
+ *
+ * `compileDesignTheme` is pure and idempotent: it reads `pkg` only, never
+ * mutates it, and has no I/O. The authored→runtime key map is the single
+ * exported table `DESIGN_COLOR_MAP` below — every lossy translation (a
+ * runtime slot the authored quartet has no direct source for) is named as a
+ * `fallback` + `lossy` case, and the cases with no row at all are named in
+ * `DESIGN_COMPILE_LOSSY`.
+ *
+ * This module imports nothing from `@working-theory/site-config` — the
+ * `theme:` block's shape is reproduced structurally here so `create-ailk`
+ * gains no runtime dependency (§ 1.5); the cross-package read that proves
+ * this compiles to what `SiteThemeSchema` accepts is test-only, by relative
+ * path, in `design-compile.test.ts`.
+ */
+import type { DesignPackage } from "./design-package.js";
+/** The nine runtime colour slots this compile emits, per mode (D4). */
+export type RuntimeColorSlot = "bg" | "bgMuted" | "surface" | "border" | "text" | "textMuted" | "primary" | "primaryFg" | "accent";
+/** One mode's compiled palette — the shape `SiteThemeSchema`'s partial palette accepts. */
+export type CompiledColorPalette = {
+    [K in RuntimeColorSlot]: string;
+};
+/** `compileDesignTheme`'s return shape — a `SiteThemeSchema`-valid `theme:` block. */
+export interface CompiledDesignTheme {
+    corners?: "rounded" | "square";
+    eyebrowCase?: "upper" | "sentence";
+    placeholders?: "outline" | "fill";
+    checkmarks?: "circle" | "plain";
+    colors: {
+        light: CompiledColorPalette;
+        dark: CompiledColorPalette;
+    };
+}
+/** Every authored colour key the map may read from (design-package.ts D3). */
+type DesignAuthoredColorKey = "bg" | "fg" | "surface" | "surface-secondary" | "border" | "text-muted" | "brand" | "fg-on-brand" | "accent" | "bg-dark" | "fg-dark" | "border-dark" | "brand-dark" | "surface-dark" | "surface-secondary-dark" | "text-muted-dark" | "fg-on-brand-dark" | "accent-dark";
+/** The five named lossy cases with a row (D4) — an authored key absent falls back. */
+export type DesignColorMapLossyCase = "L1" | "L2" | "L3" | "L4" | "L5";
+export interface DesignColorMapRow {
+    readonly mode: "light" | "dark";
+    readonly runtime: RuntimeColorSlot;
+    readonly authored: DesignAuthoredColorKey;
+    readonly fallback?: DesignAuthoredColorKey;
+    readonly lossy?: DesignColorMapLossyCase;
+}
+/**
+ * The authored→runtime key map (D4) — 18 rows, one per emitted runtime slot
+ * per mode, in the overlay block's key order (bg bgMuted surface border text
+ * textMuted primary primaryFg accent). Light rows are 1:1; dark rows are
+ * direct for bg/border/text/primary and fall back for the other five
+ * (L1–L5), each named.
+ */
+export declare const DESIGN_COLOR_MAP: readonly DesignColorMapRow[];
+/**
+ * The lossy cases with no row in `DESIGN_COLOR_MAP` (D4): a runtime slot
+ * never emitted (L6), an authored group carried but never compiled (L7),
+ * and an absent group omitted rather than defaulted (L8).
+ */
+export declare const DESIGN_COMPILE_LOSSY: {
+    readonly L6: "accentFg, destructive and destructiveFg have no authored source and are never emitted by this compile — the partial palette inherits the platform default.";
+    readonly L7: "typography, rounded and spacing are carried in the package and not compiled — SiteThemeSchema rejects fonts/radius/spacing by name.";
+    readonly L8: "an absent treatments key is omitted from the compiled theme block, not defaulted.";
+};
+/**
+ * Translate a `DesignPackage` into the `theme:` block `SiteThemeSchema.parse`
+ * accepts (D4). Pure and idempotent — reads `pkg` only, mutates nothing, and
+ * performs no I/O.
+ */
+export declare function compileDesignTheme(pkg: DesignPackage): CompiledDesignTheme;
+export {};

package/dist/design-compile.js

@@ -0,0 +1,98 @@
+/**
+ * The authored→runtime key map (D4) — 18 rows, one per emitted runtime slot
+ * per mode, in the overlay block's key order (bg bgMuted surface border text
+ * textMuted primary primaryFg accent). Light rows are 1:1; dark rows are
+ * direct for bg/border/text/primary and fall back for the other five
+ * (L1–L5), each named.
+ */
+export const DESIGN_COLOR_MAP = [
+    { mode: "light", runtime: "bg", authored: "bg" },
+    { mode: "light", runtime: "bgMuted", authored: "surface-secondary" },
+    { mode: "light", runtime: "surface", authored: "surface" },
+    { mode: "light", runtime: "border", authored: "border" },
+    { mode: "light", runtime: "text", authored: "fg" },
+    { mode: "light", runtime: "textMuted", authored: "text-muted" },
+    { mode: "light", runtime: "primary", authored: "brand" },
+    { mode: "light", runtime: "primaryFg", authored: "fg-on-brand" },
+    { mode: "light", runtime: "accent", authored: "accent" },
+    { mode: "dark", runtime: "bg", authored: "bg-dark" },
+    {
+        mode: "dark",
+        runtime: "bgMuted",
+        authored: "surface-secondary-dark",
+        fallback: "bg-dark",
+        lossy: "L1",
+    },
+    {
+        mode: "dark",
+        runtime: "surface",
+        authored: "surface-dark",
+        fallback: "bg-dark",
+        lossy: "L2",
+    },
+    { mode: "dark", runtime: "border", authored: "border-dark" },
+    { mode: "dark", runtime: "text", authored: "fg-dark" },
+    {
+        mode: "dark",
+        runtime: "textMuted",
+        authored: "text-muted-dark",
+        fallback: "fg-dark",
+        lossy: "L3",
+    },
+    { mode: "dark", runtime: "primary", authored: "brand-dark" },
+    {
+        mode: "dark",
+        runtime: "primaryFg",
+        authored: "fg-on-brand-dark",
+        fallback: "bg-dark",
+        lossy: "L4",
+    },
+    {
+        mode: "dark",
+        runtime: "accent",
+        authored: "accent-dark",
+        fallback: "brand-dark",
+        lossy: "L5",
+    },
+];
+/**
+ * The lossy cases with no row in `DESIGN_COLOR_MAP` (D4): a runtime slot
+ * never emitted (L6), an authored group carried but never compiled (L7),
+ * and an absent group omitted rather than defaulted (L8).
+ */
+export const DESIGN_COMPILE_LOSSY = {
+    L6: "accentFg, destructive and destructiveFg have no authored source and are never emitted by this compile — the partial palette inherits the platform default.",
+    L7: "typography, rounded and spacing are carried in the package and not compiled — SiteThemeSchema rejects fonts/radius/spacing by name.",
+    L8: "an absent treatments key is omitted from the compiled theme block, not defaulted.",
+};
+/**
+ * Translate a `DesignPackage` into the `theme:` block `SiteThemeSchema.parse`
+ * accepts (D4). Pure and idempotent — reads `pkg` only, mutates nothing, and
+ * performs no I/O.
+ */
+export function compileDesignTheme(pkg) {
+    const colors = pkg.colors;
+    const light = {};
+    const dark = {};
+    for (const row of DESIGN_COLOR_MAP) {
+        const target = row.mode === "light" ? light : dark;
+        const value = colors[row.authored] ?? (row.fallback !== undefined ? colors[row.fallback] : undefined);
+        if (value === undefined) {
+            // Every `authored`/`fallback` name in DESIGN_COLOR_MAP that can be
+            // reached with no fallback names one of the 13 REQUIRED colour keys
+            // (design-package.ts D3), so `readDesignPackage` guarantees this read
+            // never misses. A miss means that invariant broke — fail loudly rather
+            // than silently writing `undefined` into a `string` runtime slot.
+            throw new Error(`compileDesignTheme: no colour value for ${row.mode}.${row.runtime} (authored "${row.authored}"${row.fallback !== undefined ? `, fallback "${row.fallback}"` : ""})`);
+        }
+        target[row.runtime] = value;
+    }
+    const treatments = pkg.treatments ?? {};
+    return {
+        ...(treatments.corners !== undefined && { corners: treatments.corners }),
+        ...(treatments.eyebrowCase !== undefined && { eyebrowCase: treatments.eyebrowCase }),
+        ...(treatments.placeholders !== undefined && { placeholders: treatments.placeholders }),
+        ...(treatments.checkmarks !== undefined && { checkmarks: treatments.checkmarks }),
+        colors: { light, dark },
+    };
+}

package/dist/design-package.d.ts

@@ -0,0 +1,83 @@
+import { type ResolvedSiteChrome } from "./site-chrome.js";
+/** The closed colour key set (D3) — 13 required, 5 optional dark fallbacks. */
+export declare const DESIGN_COLOR_KEYS_REQUIRED: readonly ["bg", "fg", "surface", "surface-secondary", "border", "text-muted", "brand", "fg-on-brand", "accent", "bg-dark", "fg-dark", "border-dark", "brand-dark"];
+export declare const DESIGN_COLOR_KEYS_OPTIONAL: readonly ["surface-dark", "surface-secondary-dark", "text-muted-dark", "fg-on-brand-dark", "accent-dark"];
+type DesignColorKeyRequired = (typeof DESIGN_COLOR_KEYS_REQUIRED)[number];
+type DesignColorKeyOptional = (typeof DESIGN_COLOR_KEYS_OPTIONAL)[number];
+/** Duplicated from `SiteThemeSchema`'s colour regex (D3) — proven equal by test. */
+export declare const DESIGN_COLOR_REGEX: RegExp;
+export type DesignColors = {
+    [K in DesignColorKeyRequired]: string;
+} & {
+    [K in DesignColorKeyOptional]?: string;
+};
+/** Typography role fields, D2's `⊆ {fontFamily, fontSize, fontWeight, lineHeight, letterSpacing}` (`fontSize` required). */
+export interface DesignTypographyRole {
+    fontFamily?: string;
+    fontSize: string;
+    fontWeight?: number;
+    lineHeight?: number;
+    letterSpacing?: string;
+}
+/** Role names are open (D2). */
+export type DesignTypography = Record<string, DesignTypographyRole>;
+/** Names open (D2). */
+export type DesignRounded = Record<string, string>;
+export type DesignSpacing = Record<string, string>;
+/** Duplicated from `SiteThemeSchema`'s enums (D3) — proven equal by test. */
+export declare const DESIGN_CORNERS_VALUES: readonly ["rounded", "square"];
+export declare const DESIGN_EYEBROW_CASE_VALUES: readonly ["upper", "sentence"];
+export declare const DESIGN_PLACEHOLDERS_VALUES: readonly ["outline", "fill"];
+export declare const DESIGN_CHECKMARKS_VALUES: readonly ["circle", "plain"];
+/** D2's optional `treatments` group — the four `SiteThemeSchema` shape settings. */
+export interface DesignTreatments {
+    corners?: (typeof DESIGN_CORNERS_VALUES)[number];
+    eyebrowCase?: (typeof DESIGN_EYEBROW_CASE_VALUES)[number];
+    placeholders?: (typeof DESIGN_PLACEHOLDERS_VALUES)[number];
+    checkmarks?: (typeof DESIGN_CHECKMARKS_VALUES)[number];
+}
+/** D2's optional `sections` group — carried verbatim; look-field validation is #6803's. */
+export type DesignSections = Record<string, Record<string, unknown>>;
+/** The closed copy-density enum (spec 6892 D4). */
+export declare const DESIGN_COPY_DENSITY_VALUES: readonly ["standard", "sparse"];
+/**
+ * Spec 6892 D4's optional `copy` group — how many words a design's own pages
+ * carry. Read only by the fill-page/copywriting agents against the scaffold's
+ * installed `DESIGN.md`; no code branches on it.
+ */
+export interface DesignCopy {
+    density: (typeof DESIGN_COPY_DENSITY_VALUES)[number];
+}
+/** The typed package `readDesignPackage` returns (D2). */
+export interface DesignPackage {
+    name: string;
+    description: string;
+    colors: DesignColors;
+    typography: DesignTypography;
+    rounded: DesignRounded;
+    spacing: DesignSpacing;
+    layout: ResolvedSiteChrome;
+    treatments?: DesignTreatments;
+    sections: DesignSections;
+    /** Absent in `DESIGN.md` resolves to `{ density: "standard" }` (D4). */
+    copy: DesignCopy;
+}
+/**
+ * Thrown by `readDesignPackage` on any malformed package (D2) — never thrown
+ * after a write; every refusal happens before any I/O beyond reading
+ * `DESIGN.md` itself.
+ */
+export declare class DesignPackageError extends Error {
+    readonly file: string;
+    readonly field: string;
+    constructor(file: string, field: string, reason: string);
+}
+/**
+ * Read and validate `<dir>/DESIGN.md`'s frontmatter into a typed
+ * `DesignPackage` (D1/D2). Refuses — naming the file and the field — on any
+ * malformed package: a missing file, an unknown key, a wrong type, an
+ * unknown layout value. Nothing is written; this function has no side
+ * effects beyond the one read.
+ */
+export declare function readDesignPackage(dir: string): DesignPackage;
+export {};