create-ailk 0.12.1 → 0.14.0

package/dist/apply-design.d.ts

@@ -1,3 +1,4 @@
+import { type HomeSeedOutcome } from "./design-home.js";
 export interface ApplyDesignOptions {
     /** The design: a shipped name, or a directory holding a DESIGN.md. */
     design: string;
@@ -6,6 +7,8 @@ export interface ApplyDesignOptions {
     /** Package-rooted inputs, supplied by the caller (cli.ts from its PKG_ROOT). */
     designsDir: string;
     siteTemplatesDir: string;
+    /** The overlay's `templates/` (#7743 D7) — where a treeless shape's home lives. Default: `templates` beside `siteTemplatesDir`. */
+    templatesDir?: string;
     catalogPath: string;
     /** Where a relative design path resolves from. Default process.cwd(). */
     cwd?: string;
@@ -21,6 +24,9 @@ export type ApplyDesignChange = {
 } | {
     path: string;
     kind: "layout";
+} | {
+    path: string;
+    kind: "fonts";
 } | {
     path: string;
     kind: "design";
@@ -28,6 +34,11 @@ export type ApplyDesignChange = {
     path: string;
     kind: "preset";
     fields: string[];
+} | {
+    path: string;
+    kind: "home";
+    action: "seeded" | "restored";
+    fields: string[];
 } | {
     path: string;
     kind: "manifest";
@@ -39,15 +50,23 @@ export interface ApplyDesignResult {
     /** In write order (D4); [] when nothing changed. */
     changes: ApplyDesignChange[];
     manifest: "recorded" | "unchanged" | "no-roster" | "legacy-roster";
+    /** #7743 D7 — what the design did to the home page's sections. */
+    home: HomeSeedOutcome;
+    /** #7743 D7 — the design ships a home arc for this site, so a home it leaves alone is reported. */
+    homeArc?: true;
     /** The site-relative roster file, when there is one. */
     rosterPath?: string;
+    /** #7720 D4.2 — the distinct families written to site-fonts.ts, display first; set only when faces are written. */
+    fonts?: string[];
+    /** #7720 D4.2 — faces were written, but the site's layout.tsx does not read lib/site-fonts. */
+    fontsUnwired?: true;
 }
 export interface ApplyDesignArgs {
     design: string | undefined;
     target: string | undefined;
     help: boolean;
 }
-export declare const APPLY_DESIGN_HELP = "create-ailk apply-design \u2014 make an existing site wear a design.\n\nUsage:\n  create-ailk apply-design <name> [--target <site-dir>]\n  create-ailk apply-design <path> [--target <site-dir>]\n\nArguments:\n  <name|path>              A shipped design (standard, minimalism), or a\n                           directory holding a DESIGN.md. A relative path\n                           resolves from the current directory.\n\nOptions:\n  --target <site-dir>      An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n  --help, -h               Print this message.\n\nWrites only the look: DESIGN.md (replaced whole by the design's, keeping the\nsite's Source template and Version lines), the theme: block of\ncontent/_site.mdx, the generated apps/web/lib/site-chrome.ts, the look fields\nof sections the site's pages already place, and the design/layout/theme record\nin .ailk-site-manifest.json.\nNever adds, removes or renames a route or page, never touches a content field\nor the brand: block, and leaves every page's structured data unchanged.\n\nA design other than standard needs a Pro or Pro Plus key: the site's own\nailk.key (put one there with create-ailk license set <key>), else\nAILK_LICENSE_KEY. A malformed package, a preset the validator refuses or a\nmissing key is refused before any file is written.\n\nA preset sets the look fields it names and never unsets one: a field it does\nnot name keeps whatever value the page has. Running it again changes nothing.\n";
+export declare const APPLY_DESIGN_HELP = "create-ailk apply-design \u2014 make an existing site wear a design.\n\nUsage:\n  create-ailk apply-design <name> [--target <site-dir>]\n  create-ailk apply-design <path> [--target <site-dir>]\n\nArguments:\n  <name|path>              A shipped design (standard, minimalism), or a\n                           directory holding a DESIGN.md. A relative path\n                           resolves from the current directory.\n\nOptions:\n  --target <site-dir>      An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n  --help, -h               Print this message.\n\nWrites only the look: DESIGN.md (replaced whole by the design's, keeping the\nsite's Source template and Version lines), the theme: block of\ncontent/_site.mdx, the generated apps/web/lib/site-chrome.ts, the generated\napps/web/lib/site-fonts.ts, the look fields of sections the site's pages\nalready place, and the design/layout/theme record in .ailk-site-manifest.json.\nNever adds, removes or renames a route or page, never touches a content field\n(except a placeholder home's sections, below) or the brand: block, and leaves\nevery other page's structured data unchanged.\n\nA design may seed the placeholder home's sections \u2014 its home arc \u2014 while they\nare still a placeholder: the shape's own, or a design's arc of them. It never\nchanges a home whose sections were edited; it reports it and leaves it. A\nseeded home takes the design's looks; look values on the sections it replaced\nare not kept. A design that ships no arc restores the shape's own sections on\na home that still wears another design's untouched arc.\n\nA design other than standard needs a Pro or Pro Plus key: the site's own\nailk.key (put one there with create-ailk license set <key>), else\nAILK_LICENSE_KEY. A malformed package, a preset the validator refuses or a\nmissing key is refused before any file is written.\n\nA preset sets the look fields it names and never unsets one: a field it does\nnot name keeps whatever value the page has. Running it again changes nothing.\n";
 /**
  * Parse the argv AFTER the `apply-design` word (D1). Strict `node:util`
  * parseArgs, like `parseSyncRoutesArgs`: exactly one positional, the design
@@ -57,7 +76,7 @@ export declare function parseApplyDesignArgs(argv: string[]): ApplyDesignArgs;
 /**
  * Apply a design to an existing site (D2–D7). Refuses before any write
  * (C1–C6); otherwise writes only the files whose text changes — page files,
- * `site-chrome.ts`, `DESIGN.md`, `_site.mdx`, then the manifest last.
+ * `site-chrome.ts`, `site-fonts.ts`, `DESIGN.md`, `_site.mdx`, then the manifest last.
  */
 export declare function applyDesign(opts: ApplyDesignOptions): Promise<ApplyDesignResult>;
 /** The changed-file report (D9). */

package/dist/apply-design.js

@@ -7,7 +7,9 @@
  * resolver and theme splicer, #6816's preset validator and applier, #6760's
  * design gate and #6813's manifest writer. Every refusal happens before the
  * first write (D3); every new text is planned in memory, then written in one
- * pass (D4). Routes, content fields, `brand:` and structured data never move.
+ * pass (D4). Routes, content fields, `brand:` and structured data never move —
+ * except a placeholder home's `sections:`, which a design's home arc may
+ * replace (#7743 D7).
  *
  * Reads no module URL of its own — every package directory it reads is passed in
  * — so Jest's CJS transform can import it, unlike `programmatic.ts`.
@@ -16,7 +18,8 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSy
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { planDesignMd } from "./apply-design-md.js";
-import { compileDesignTheme } from "./design-compile.js";
+import { compileDesignFonts, compileDesignTheme } from "./design-compile.js";
+import { HOME_PAGE_PATH, designHomeSeeds, planDesignHome, shapeHomePath, shippedHomeSeeds, } from "./design-home.js";
 import { applyDesignPresets, readSectionLookCatalog, shippedPageTypes, validateDesignPresets, } from "./design-presets.js";
 import { resolveDesign, spliceThemeBlock } from "./design-scaffold.js";
 import { LICENSE_KEY_FILE } from "./lib/license-key-files.js";
@@ -24,7 +27,10 @@ import { CONVERSION_HINT_URL, LicenseRequiredError, assertDesignAllowed, deriveL
 import { LEVEL_LABEL } from "./lib/module-tier.js";
 import { ParseError } from "./parse-args.js";
 import { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.js";
-import { SITE_ROSTER_PATH, planSiteManifestDesign, readSiteRoster, } from "./site-roster.js";
+import { SITE_FONTS_PATH, renderSiteFonts } from "./site-fonts.js";
+import { SITE_ROSTER_PATH, planHomeRecord, planSiteManifestDesign, readSiteRoster, } from "./site-roster.js";
+/** The site's locale layout — the one reader of the generated site-fonts.ts. */
+const SITE_LAYOUT_PATH = "apps/web/app/[locale]/layout.tsx";
 export const APPLY_DESIGN_HELP = `create-ailk apply-design — make an existing site wear a design.
 
 Usage:
@@ -43,11 +49,19 @@ Options:
 
 Writes only the look: DESIGN.md (replaced whole by the design's, keeping the
 site's Source template and Version lines), the theme: block of
-content/_site.mdx, the generated apps/web/lib/site-chrome.ts, the look fields
-of sections the site's pages already place, and the design/layout/theme record
-in .ailk-site-manifest.json.
+content/_site.mdx, the generated apps/web/lib/site-chrome.ts, the generated
+apps/web/lib/site-fonts.ts, the look fields of sections the site's pages
+already place, and the design/layout/theme record in .ailk-site-manifest.json.
 Never adds, removes or renames a route or page, never touches a content field
-or the brand: block, and leaves every page's structured data unchanged.
+(except a placeholder home's sections, below) or the brand: block, and leaves
+every other page's structured data unchanged.
+
+A design may seed the placeholder home's sections — its home arc — while they
+are still a placeholder: the shape's own, or a design's arc of them. It never
+changes a home whose sections were edited; it reports it and leaves it. A
+seeded home takes the design's looks; look values on the sections it replaced
+are not kept. A design that ships no arc restores the shape's own sections on
+a home that still wears another design's untouched arc.
 
 A design other than standard needs a Pro or Pro Plus key: the site's own
 ailk.key (put one there with create-ailk license set <key>), else
@@ -118,7 +132,7 @@ function readSiteKey(targetAbs, env) {
 /**
  * Apply a design to an existing site (D2–D7). Refuses before any write
  * (C1–C6); otherwise writes only the files whose text changes — page files,
- * `site-chrome.ts`, `DESIGN.md`, `_site.mdx`, then the manifest last.
+ * `site-chrome.ts`, `site-fonts.ts`, `DESIGN.md`, `_site.mdx`, then the manifest last.
  */
 export async function applyDesign(opts) {
     const targetAbs = resolve(opts.targetDir);
@@ -146,13 +160,18 @@ export async function applyDesign(opts) {
     const { pkg } = resolved;
     const hasPresets = Object.keys(pkg.sections).length > 0;
     // C4 — the presets, validated exactly as scaffold() validates them.
+    let lookCatalog;
+    const catalog = () => (lookCatalog ??= readSectionLookCatalog(opts.catalogPath));
     if (hasPresets) {
         validateDesignPresets(pkg.sections, {
-            catalog: readSectionLookCatalog(opts.catalogPath),
+            catalog: catalog(),
             pageTypes: shippedPageTypes(opts.siteTemplatesDir),
             file: join(resolved.dir, "DESIGN.md"),
         });
     }
+    // #7743 D7 — the home seeds (the design's and every shipped design's), validated beside the presets.
+    const designSeeds = designHomeSeeds(resolved, { designsDir: opts.designsDir, catalog });
+    const shippedSeeds = shippedHomeSeeds({ designsDir: opts.designsDir, catalog });
     // C5 — the design gate, fed the site's own key (D6). A Free design reads no key.
     if (!resolved.free) {
         const key = readSiteKey(targetAbs, env);
@@ -179,11 +198,45 @@ export async function applyDesign(opts) {
     const chromePath = join(targetAbs, SITE_CHROME_PATH);
     const chromeCurrent = existsSync(chromePath) ? readFileSync(chromePath, "utf8") : undefined;
     const chromeNext = renderSiteChrome(chrome);
+    // #7720 D4.2 — a face-less design never adds the file to a site that lacks it.
+    const fonts = compileDesignFonts(pkg);
+    const fontsPath = join(targetAbs, SITE_FONTS_PATH);
+    const fontsCurrent = existsSync(fontsPath) ? readFileSync(fontsPath, "utf8") : undefined;
+    const fontsNext = renderSiteFonts(fonts);
+    const writeFonts = fontsNext !== fontsCurrent && (fontsCurrent !== undefined || fonts !== undefined);
+    const fontFamilies = writeFonts && fonts !== undefined
+        ? [...new Set([fonts.display?.family, fonts.body?.family])].filter((family) => family !== undefined)
+        : undefined;
+    const layoutPath = join(targetAbs, SITE_LAYOUT_PATH);
+    const fontsUnwired = fontFamilies !== undefined &&
+        !(existsSync(layoutPath) && readFileSync(layoutPath, "utf8").includes("lib/site-fonts"));
     const designMdPath = join(targetAbs, "DESIGN.md");
     const designMdCurrent = existsSync(designMdPath) ? readFileSync(designMdPath, "utf8") : undefined;
     const designMdNext = planDesignMd(resolved.dir, targetAbs);
+    // #7743 D7 — the home is planned before the presets, so a seeded home is
+    // written once, carrying both. The one `planDesignHome` call site here.
+    const shape = roster?.template.shape;
+    const target = designSeeds.find((seed) => seed.shape === shape);
+    // The arc this site would take: the shape's seed, or (with no shape to pick one) any seed at all.
+    const homeArc = target !== undefined || (shape === undefined && designSeeds.length > 0);
+    const homePath = join(targetAbs, ...HOME_PAGE_PATH.split("/"));
+    const current = existsSync(homePath) ? readFileSync(homePath, "utf8") : undefined;
+    const homePlan = planDesignHome({
+        current,
+        shape,
+        target,
+        shapeHome: shape === undefined || current === undefined
+            ? ""
+            : readFileSync(shapeHomePath(shape, {
+                siteTemplatesDir: opts.siteTemplatesDir,
+                templatesDir: opts.templatesDir ?? join(dirname(opts.siteTemplatesDir), "templates"),
+            }), "utf8"),
+        shippedSeeds,
+        catalog: catalog(),
+    });
+    const homeAction = homePlan.outcome === "seeded" || homePlan.outcome === "restored" ? homePlan.outcome : undefined;
     const pageWrites = [];
-    if (hasPresets && roster !== undefined) {
+    if (roster !== undefined && (hasPresets || homeAction !== undefined)) {
         const pageTypes = new Set();
         for (const row of roster.rows) {
             const pageType = row.value["pageType"];
@@ -191,17 +244,28 @@ export async function applyDesign(opts) {
                 pageTypes.add(pageType);
         }
         const contentDir = join(targetAbs, "content");
+        // An authored home kept from a design's arc is reported as kept, so no preset dresses it either (D3, F4).
+        const homeKept = homePlan.outcome === "authored" && homeArc;
         const pages = listMdxFiles(contentDir)
-            .filter((path) => path !== siteMdxPath)
-            .map((path) => ({ path, text: readFileSync(path, "utf8") }));
-        const presetResult = applyDesignPresets(pages, pkg.sections, { pageTypes });
-        for (const page of presetResult.pages) {
+            .filter((path) => path !== siteMdxPath && !(homeKept && path === homePath))
+            .map((path) => ({
+            path,
+            text: path === homePath && homePlan.text !== undefined ? homePlan.text : readFileSync(path, "utf8"),
+        }));
+        const presetResult = hasPresets
+            ? applyDesignPresets(pages, pkg.sections, { pageTypes })
+            : { pages: [], applied: [] };
+        for (const page of pages) {
+            const preset = presetResult.pages.find((p) => p.path === page.path);
+            const home = page.path === homePath ? homeAction : undefined;
+            if (preset === undefined && home === undefined)
+                continue;
             const fields = [
                 ...new Set(presetResult.applied
                     .filter((a) => a.path === page.path)
                     .map((a) => `${a.sectionType}.${a.field}`)),
             ].sort();
-            pageWrites.push({ path: page.path, text: page.text, fields });
+            pageWrites.push({ path: page.path, text: preset?.text ?? page.text, fields, ...(home !== undefined ? { home } : {}) });
         }
     }
     let manifest = "no-roster";
@@ -210,23 +274,37 @@ export async function applyDesign(opts) {
     if (roster !== undefined && rosterAbs !== undefined) {
         if (roster.path === SITE_ROSTER_PATH) {
             manifestNext = planSiteManifestDesign(readFileSync(rosterAbs, "utf8"), { design: resolved.recorded, layout: chrome, theme }, rosterAbs);
+            // #7743 D6 — the `/` row records the home as written, in the same single write.
+            const home = pageWrites.find((page) => page.home !== undefined);
+            if (home !== undefined) {
+                manifestNext =
+                    planHomeRecord(manifestNext ?? readFileSync(rosterAbs, "utf8"), home.text, catalog()) ?? manifestNext;
+            }
             manifest = manifestNext === undefined ? "unchanged" : "recorded";
         }
         else {
             manifest = "legacy-roster";
         }
     }
-    // Write — page files, site-chrome.ts, DESIGN.md, _site.mdx, the manifest last (D4).
+    // Write — page files, site-chrome.ts, site-fonts.ts, DESIGN.md, _site.mdx, the manifest last (D4).
     const changes = [];
     for (const page of pageWrites) {
         writeFileSync(page.path, page.text);
-        changes.push({ path: siteRelative(targetAbs, page.path), kind: "preset", fields: page.fields });
+        const path = siteRelative(targetAbs, page.path);
+        changes.push(page.home !== undefined
+            ? { path, kind: "home", action: page.home, fields: page.fields }
+            : { path, kind: "preset", fields: page.fields });
     }
     if (chromeNext !== chromeCurrent) {
         mkdirSync(dirname(chromePath), { recursive: true });
         writeFileSync(chromePath, chromeNext);
         changes.push({ path: SITE_CHROME_PATH, kind: "layout" });
     }
+    if (writeFonts) {
+        mkdirSync(dirname(fontsPath), { recursive: true });
+        writeFileSync(fontsPath, fontsNext);
+        changes.push({ path: SITE_FONTS_PATH, kind: "fonts" });
+    }
     if (designMdNext !== designMdCurrent) {
         writeFileSync(designMdPath, designMdNext);
         changes.push({ path: "DESIGN.md", kind: "design" });
@@ -245,7 +323,11 @@ export async function applyDesign(opts) {
         display: resolved.display,
         changes,
         manifest,
+        home: homePlan.outcome,
+        ...(homeArc ? { homeArc: true } : {}),
         ...(roster !== undefined ? { rosterPath: roster.path } : {}),
+        ...(fontFamilies !== undefined ? { fonts: fontFamilies } : {}),
+        ...(fontsUnwired ? { fontsUnwired: true } : {}),
     };
 }
 /** The changed-file report (D9). */
@@ -257,11 +339,30 @@ export function formatApplyDesignReport(result) {
     else {
         lines.push(`[create-ailk] Applied design "${result.design}" to ${result.targetDir}`);
         for (const change of result.changes) {
-            const suffix = change.kind === "preset" ? ` (${change.fields.join(", ")})` : "";
+            const suffix = change.kind === "preset"
+                ? ` (${change.fields.join(", ")})`
+                : change.kind === "home"
+                    ? ` (${[change.action, change.fields.join(", ")].filter((part) => part !== "").join("; ")})`
+                    : "";
             lines.push(`  ${change.kind.padEnd(8)}  ${change.path}${suffix}`);
         }
         const n = result.changes.length;
-        lines.push(`${n} file${n === 1 ? "" : "s"} changed. Routes, page content and structured data are unchanged.`);
+        const homeWritten = result.changes.some((change) => change.kind === "home");
+        lines.push(`${n} file${n === 1 ? "" : "s"} changed. ${homeWritten
+            ? "Routes are unchanged; the home page's sections were replaced."
+            : "Routes and structured data are unchanged."}`);
+    }
+    if (result.home === "authored" && result.homeArc === true) {
+        lines.push(`home kept: ${HOME_PAGE_PATH} has authored sections — the ${result.design} home arc was not applied`);
+    }
+    else if (result.home === "no-shape" && result.homeArc === true) {
+        lines.push("home not seeded: the site records no shape");
+    }
+    if (result.fonts !== undefined) {
+        lines.push(`fonts: ${result.fonts.join(", ")} load at next build through next/font/google — a family that is not a variable Google font fails there`);
+    }
+    if (result.fontsUnwired === true) {
+        lines.push(`fonts not loaded: ${SITE_LAYOUT_PATH} predates lib/site-fonts — update the layout from the current create-ailk overlay`);
     }
     if (result.manifest === "legacy-roster") {
         lines.push(`manifest not recorded: ${result.rosterPath} predates the design record`);

package/dist/cli.js

@@ -201,6 +201,7 @@ async function main() {
             targetDir: args.target ?? process.cwd(),
             designsDir: resolve(PKG_ROOT, "site-templates", "designs"),
             siteTemplatesDir: resolve(PKG_ROOT, "site-templates"),
+            templatesDir: resolve(PKG_ROOT, "templates"),
             catalogPath: resolve(PKG_ROOT, "component-catalog.json"),
         });
         process.stdout.write(formatApplyDesignReport(result));

package/dist/design-compile.d.ts

@@ -15,7 +15,7 @@
  * this compiles to what `SiteThemeSchema` accepts is test-only, by relative
  * path, in `design-compile.test.ts`.
  */
-import type { DesignPackage } from "./design-package.js";
+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. */
@@ -28,11 +28,72 @@ export interface CompiledDesignTheme {
     eyebrowCase?: "upper" | "sentence";
     placeholders?: "outline" | "fill";
     checkmarks?: "circle" | "plain";
+    /** #7741 D7 — the button shape, copied from `treatments.buttonShape`. */
+    buttonShape?: "control" | "pill";
+    /** #7739 D2 — the ink of headings and labels on a dark ground, verbatim from the package. */
+    darkInk?: "fg" | "accent";
+    /** #7739 D2 — the stat-numeral treatment, verbatim from the package. */
+    figures?: "platform" | "display";
+    /**
+     * #7720 D2 — the display leading pair, present only when the display role
+     * declares `lineHeightMobile`; or, under `typeScale: design` (#7739 D2.2),
+     * every declared field of the five compiled roles.
+     */
+    typography?: CompiledTypography;
+    /**
+     * #7719 D6 — `"site"` paints dark-scoped bands with the site's own dark
+     * colours. Derived (never authored): emitted when the package names the
+     * `solid-dark` surface or declares `darkInk: accent` (#7739 D2.3); absent otherwise.
+     */
+    darkBands?: "platform" | "site";
     colors: {
         light: CompiledColorPalette;
         dark: CompiledColorPalette;
     };
 }
+/**
+ * The compiled type roles (#7720, #7739 D2.2) — the shape `SiteThemeSchema`'s
+ * `typography` accepts. Each role is present only when it carries a field.
+ */
+export interface CompiledTypography {
+    display?: {
+        fontSize?: string;
+        fontSizeMobile?: string;
+        fontWeight?: number;
+        lineHeight?: number;
+        lineHeightMobile?: number;
+    };
+    "heading-section"?: {
+        fontSize?: string;
+        fontSizeMobile?: string;
+        fontWeight?: number;
+    };
+    "heading-item"?: {
+        fontSize?: string;
+        fontSizeMobile?: string;
+        fontWeight?: number;
+    };
+    body?: {
+        fontSize?: string;
+        lineHeight?: number;
+    };
+    eyebrow?: {
+        fontSize?: string;
+        fontWeight?: number;
+    };
+}
+/** One sourced face (#7720 D3.1): the first family, unquoted, and the rest of the authored stack. */
+export interface CompiledFace {
+    source: "google";
+    family: string;
+    /** The authored stack after the first comma, trimmed and verbatim; "" when there is none. */
+    fallback: string;
+}
+/** `compileDesignFonts`'s return shape — the faces `apps/web/lib/site-fonts.ts` loads. */
+export interface CompiledDesignFonts {
+    display?: CompiledFace;
+    body?: CompiledFace;
+}
 /** 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. */
@@ -59,7 +120,7 @@ export declare const DESIGN_COLOR_MAP: readonly DesignColorMapRow[];
  */
 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 L7: "typography, rounded and spacing are carried in the package and not compiled — SiteThemeSchema rejects fonts/radius/spacing by name. Three exceptions: the display role's leading pair (lineHeight, lineHeightMobile) compiles into theme.typography.display when lineHeightMobile is declared (#7720); the display/body faces a fontSource names compile to apps/web/lib/site-fonts.ts (#7720); and under treatments.typeScale: design the display, heading-section, heading-item, body and eyebrow roles' sizes, phone sizes, weights and leadings compile into theme.typography (#7739) — never their families or letterSpacing.";
     readonly L8: "an absent treatments key is omitted from the compiled theme block, not defaulted.";
 };
 /**
@@ -68,4 +129,11 @@ export declare const DESIGN_COMPILE_LOSSY: {
  * performs no I/O.
  */
 export declare function compileDesignTheme(pkg: DesignPackage): CompiledDesignTheme;
+/**
+ * The faces a package's display and body roles source (#7720 D3.1), or
+ * `undefined` when neither declares `fontSource`. Pure, like
+ * `compileDesignTheme`; `readDesignPackage` has already constrained every
+ * stack it reads here.
+ */
+export declare function compileDesignFonts(pkg: DesignPackage): CompiledDesignFonts | undefined;
 export {};

package/dist/design-compile.js

@@ -1,3 +1,32 @@
+/**
+ * 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 { unquoteFamily } from "./design-package.js";
+/**
+ * #7739 D2.2 — the fields `typeScale: design` compiles, per role, in emission
+ * order. Roles are emitted in this table's order.
+ */
+const COMPILED_TYPE_FIELDS = {
+    display: ["fontSize", "fontSizeMobile", "fontWeight", "lineHeight", "lineHeightMobile"],
+    "heading-section": ["fontSize", "fontSizeMobile", "fontWeight"],
+    "heading-item": ["fontSize", "fontSizeMobile", "fontWeight"],
+    body: ["fontSize", "lineHeight"],
+    eyebrow: ["fontSize", "fontWeight"],
+};
 /**
  * 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
@@ -62,9 +91,46 @@ export const DESIGN_COLOR_MAP = [
  */
 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.",
+    L7: "typography, rounded and spacing are carried in the package and not compiled — SiteThemeSchema rejects fonts/radius/spacing by name. Three exceptions: the display role's leading pair (lineHeight, lineHeightMobile) compiles into theme.typography.display when lineHeightMobile is declared (#7720); the display/body faces a fontSource names compile to apps/web/lib/site-fonts.ts (#7720); and under treatments.typeScale: design the display, heading-section, heading-item, body and eyebrow roles' sizes, phone sizes, weights and leadings compile into theme.typography (#7739) — never their families or letterSpacing.",
     L8: "an absent treatments key is omitted from the compiled theme block, not defaulted.",
 };
+/** Whether a package names the `solid-dark` surface — in its deck grounds or any section preset (#7719 D6). */
+function usesSolidDark(pkg) {
+    if (pkg.layout.deckGrounds?.includes("solid-dark"))
+        return true;
+    return Object.values(pkg.sections).some((sections) => Object.values(sections).some((preset) => typeof preset === "object" &&
+        preset !== null &&
+        preset.surface === "solid-dark"));
+}
+/** The `typography` group a package compiles (#7720 D2, #7739 D2.2), or `undefined`. */
+function compileTypography(pkg) {
+    if (pkg.treatments?.typeScale === "design") {
+        const result = {};
+        for (const [role, fields] of Object.entries(COMPILED_TYPE_FIELDS)) {
+            const def = pkg.typography[role];
+            if (def === undefined)
+                continue;
+            const compiled = {};
+            for (const field of fields) {
+                const value = def[field];
+                if (value !== undefined)
+                    compiled[field] = value;
+            }
+            if (Object.keys(compiled).length > 0)
+                result[role] = compiled;
+        }
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    const display = pkg.typography["display"];
+    if (display?.lineHeightMobile === undefined)
+        return undefined;
+    return {
+        display: {
+            ...(display.lineHeight !== undefined && { lineHeight: display.lineHeight }),
+            lineHeightMobile: display.lineHeightMobile,
+        },
+    };
+}
 /**
  * Translate a `DesignPackage` into the `theme:` block `SiteThemeSchema.parse`
  * accepts (D4). Pure and idempotent — reads `pkg` only, mutates nothing, and
@@ -88,11 +154,41 @@ export function compileDesignTheme(pkg) {
         target[row.runtime] = value;
     }
     const treatments = pkg.treatments ?? {};
+    const typography = compileTypography(pkg);
+    // #7739 D2.3 — accent ink needs the site's own palette on the band, or the
+    // accent there would be the platform's.
+    const darkBands = usesSolidDark(pkg) || treatments.darkInk === "accent";
     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 }),
+        ...(treatments.buttonShape !== undefined && { buttonShape: treatments.buttonShape }),
+        ...(treatments.darkInk !== undefined && { darkInk: treatments.darkInk }),
+        ...(treatments.figures !== undefined && { figures: treatments.figures }),
+        ...(typography !== undefined && { typography }),
+        ...(darkBands && { darkBands: "site" }),
         colors: { light, dark },
     };
 }
+/**
+ * The faces a package's display and body roles source (#7720 D3.1), or
+ * `undefined` when neither declares `fontSource`. Pure, like
+ * `compileDesignTheme`; `readDesignPackage` has already constrained every
+ * stack it reads here.
+ */
+export function compileDesignFonts(pkg) {
+    const fonts = {};
+    for (const role of ["display", "body"]) {
+        const def = pkg.typography[role];
+        if (def?.fontSource === undefined || def.fontFamily === undefined)
+            continue;
+        const comma = def.fontFamily.indexOf(",");
+        fonts[role] = {
+            source: def.fontSource,
+            family: unquoteFamily(comma === -1 ? def.fontFamily : def.fontFamily.slice(0, comma)),
+            fallback: comma === -1 ? "" : def.fontFamily.slice(comma + 1).trim(),
+        };
+    }
+    return fonts.display !== undefined || fonts.body !== undefined ? fonts : undefined;
+}

package/dist/design-home.d.ts

@@ -0,0 +1,74 @@
+import { type SectionLookCatalog } from "./design-presets.js";
+import type { ResolvedDesign } from "./design-scaffold.js";
+/** Where a site's home page lives, site-relative. */
+export declare const HOME_PAGE_PATH = "content/en/HomePage/home.mdx";
+/** One `home/<shape>.mdx` file of a design package (D1). */
+export interface HomeSeed {
+    readonly shape: string;
+    /** Absolute path, for refusals. */
+    readonly file: string;
+    readonly text: string;
+}
+export type HomeSeedOutcome = "seeded" | "restored" | "unchanged" | "authored" | "no-shape" | "no-home";
+/**
+ * Read and validate `<dir>/home/*` (D1). Refuses with a `DesignPackageError`
+ * naming the file, before any write: a basename that is not a recognized
+ * shape, a page whose `type` is not `HomePage`, `sections` that cannot be
+ * located (or are not in the flow form a carry can splice), a section type
+ * the catalog does not carry, or a `logoCloud` whose `logos` is not `[]`.
+ */
+export declare function readDesignHomeSeeds(dir: string, opts: {
+    catalog: () => SectionLookCatalog;
+}): HomeSeed[];
+/**
+ * The seeds a resolved design uses (D1): its own `home/`, else — a
+ * byte-identical copy of a shipped design IS that design — the shipped
+ * design's, else none.
+ */
+export declare function designHomeSeeds(resolved: ResolvedDesign, opts: {
+    designsDir: string;
+    catalog: () => SectionLookCatalog;
+}): HomeSeed[];
+/** Every shipped design's seeds (D3's placeholder set reads them all). */
+export declare function shippedHomeSeeds(opts: {
+    designsDir: string;
+    catalog: () => SectionLookCatalog;
+}): HomeSeed[];
+/** The shape's own home: its shape tree's, else the overlay's (spec § 1.4). */
+export declare function shapeHomePath(shape: string, opts: {
+    siteTemplatesDir: string;
+    templatesDir: string;
+}): string;
+/**
+ * A home's content fingerprint (D3): per section in order, its type and its
+ * non-look `data` entries as `[key, normalized raw value]`, sorted by key.
+ * A reflow, a look-field change or a preset leaves it unchanged; ids, the
+ * title, the description and the body are not in it.
+ */
+export declare function fingerprint(text: string, catalog: SectionLookCatalog, file?: string): string;
+/**
+ * The seed's `sections:` value with D4's carry applied from `home`: a seed
+ * `logoCloud` (its `logos: []`) takes the raw `logos` of the home's first
+ * `logoCloud`, or is dropped when the home has none.
+ */
+export declare function applySeed(home: string, seed: HomeSeed, file?: string): string;
+/**
+ * Plan a site home under a design (D3). Writes nothing: `text` is the new
+ * home when the outcome is `seeded` or `restored`, and absent otherwise.
+ */
+export declare function planDesignHome(opts: {
+    /** The site's content/en/HomePage/home.mdx, if any. */
+    current: string | undefined;
+    /** The roster's template shape. */
+    shape: string | undefined;
+    /** The applied design's seed for that shape (D1). */
+    target: HomeSeed | undefined;
+    /** The text of the shape's own home file (spec § 1.4). */
+    shapeHome: string;
+    /** Every shipped design's seeds (filtered to `shape` here). */
+    shippedSeeds: readonly HomeSeed[];
+    catalog: SectionLookCatalog;
+}): {
+    outcome: HomeSeedOutcome;
+    text?: string;
+};