create-ailk 0.6.1 → 0.8.0

package/dist/programmatic.js

@@ -15,21 +15,24 @@
  *   import { scaffoldSync } from './programmatic.js';
  *   const result = scaffoldSync({ targetDir: '/tmp/my-site', projectName: 'my-site' });
  */
-import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { existsSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
+import { AddModuleRefusedError, applyModuleToScaffold, } from "./add-module.js";
 import { CATALOG_TARGET_PATH, writeComponentCatalog, } from "./component-catalog.js";
 import { buildScaffoldMarkers, copyTemplate } from "./copy.js";
 import { deriveArchitecture } from "./derive-architecture.js";
 import { extractModuleBundle, installBundleTree, } from "./lib/extract-module-bundle.js";
 import { fetchTemplate } from "./lib/fetch-template.js";
-import { resolvePaidModules } from "./lib/module-license-gate.js";
+import { assertLicenseKeyShape, writeLicenseKeyFiles, } from "./lib/license-key-files.js";
+import { FREE_DESIGNS, assertDesignAllowed, deriveLevel, resolveModuleSet, resolvePaidModules, } from "./lib/module-license-gate.js";
 import { classifyModules } from "./lib/module-tier.js";
 import { normalizeModules } from "./module-architecture.js";
+import { RECOGNIZED_SHAPES, RESERVED_SHAPES, } from "./parse-args.js";
 import { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.js";
 import { GATEABLE_SURFACES, MODULE_SURFACES, NAV_CONFIG_PATH, excludedRoutePaths, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
-import { BASE_LAYER_DIR, mergeRoster, resolveTemplate, resolveTemplateLineage, templateDelivery, } from "./template-manifest.js";
+import { BASE_LAYER_DIR, SHAPE_STARTERS, STARTER_DESIGNS, TEMPLATE_MANIFESTS, TemplateError, mergeRoster, resolveTemplate, resolveTemplateLineage, rosterDeclares, templateDelivery, templateTreeDir, } from "./template-manifest.js";
 import { validateTarget } from "./validate.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATES_DIR = resolve(PKG_ROOT, "templates");
@@ -73,6 +76,37 @@ function countFiles(dir) {
     }
     return count;
 }
+/**
+ * The template a `shape` scaffolds (#6754 D5, extended #6757 D6 row 1): the
+ * one FREE-delivery manifest of that shape — a declared `--template` alias
+ * (`TEMPLATE_MANIFESTS`) or a bare-shape starter with no alias of its own
+ * (`SHAPE_STARTERS`), the union the candidate set draws from. Reads manifest
+ * fields only — no roster.
+ *
+ * @throws TemplateError on a reserved or unknown shape, a shape with no Free
+ *   starter yet (D6), or more than one (never picked silently).
+ */
+function resolveShapeTemplate(shape) {
+    if (!RECOGNIZED_SHAPES.includes(shape)) {
+        const known = RECOGNIZED_SHAPES.join(", ");
+        throw new TemplateError(RESERVED_SHAPES.includes(shape)
+            ? `shape "${shape}" is not available yet. Choose one of: ${known}.`
+            : `unknown shape "${shape}". Recognized: ${known}`);
+    }
+    const ofShape = [
+        ...Object.values(TEMPLATE_MANIFESTS),
+        ...Object.values(SHAPE_STARTERS),
+    ].filter((manifest) => manifest.shape === shape);
+    const free = ofShape.filter((manifest) => templateDelivery(manifest) === "free");
+    if (free.length === 0) {
+        const names = ofShape.map((manifest) => manifest.name).join(", ");
+        throw new TemplateError(`shape "${shape}" has no Free starter yet — its page list lands with #6743. Templates built on this shape: ${names || "none"}.`);
+    }
+    if (free.length > 1) {
+        throw new TemplateError(`shape "${shape}" has more than one Free starter: ${free.map((manifest) => manifest.name).join(", ")}`);
+    }
+    return free[0];
+}
 /**
  * Scaffold an AI Launch Kit starter project into targetDir (synchronous).
  *
@@ -110,13 +144,18 @@ export function scaffoldSync(opts) {
     // template's `layout` block; a bare `scaffoldSync` call (every existing
     // synchronous caller) writes DEFAULT_SITE_CHROME, byte-identical to the
     // monorepo's own committed apps/web/lib/site-chrome.ts.
-    writeFileSync(join(targetAbs, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(opts.layout)));
+    writeFileSync(join(targetAbs, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(opts.layout, opts.design)));
     // Opt-in only (#4636). Every write above this line is unconditional, so a
     // scaffold with `withCatalog` unset touches exactly the files it did before.
     if (opts.withCatalog === true)
         writeComponentCatalog(targetAbs);
     const filesCreated = countFiles(targetAbs);
-    return { targetDir: targetAbs, filesCreated, surfaces: enabledSurfaces };
+    return {
+        targetDir: targetAbs,
+        filesCreated,
+        surfaces: enabledSurfaces,
+        modules: normalizeModules(opts.modules ?? ["marketing"]),
+    };
 }
 /**
  * Scaffold an AI Launch Kit starter project into targetDir (async wrapper).
@@ -136,8 +175,14 @@ export function scaffoldSync(opts) {
  *      its fetched bundle or — when it requires only free modules — from the
  *      `site-templates/` tree this package ships.
  *
- * And, ahead of all five when `opts.template` is set (0): resolve the
- * template and union its `requires` with `opts.modules`, so every step above
+ * Between 2 and 3, `assertDesignAllowed` (#6760) refuses a design the caller
+ * CHOSE (`opts.design`) for a level below Pro, HERE, also before anything is
+ * written to disk. A template's own declared design is never gated (#6778
+ * option (c)): the template's `requires` already decide its level.
+ *
+ * And, ahead of all five when `opts.template` (or `opts.shape`, #6754 D5) is
+ * set (0): resolve the template and union its `requires` with `opts.modules`,
+ * so every step above
  * runs over the EFFECTIVE module set rather than the requested one.
  *
  * `scaffoldSync` itself stays licensing-oblivious on purpose: every existing
@@ -146,35 +191,134 @@ export function scaffoldSync(opts) {
  * with a paid module in `opts.modules` exercises the gate at all.
  */
 export async function scaffold(opts) {
+    // #6683 D9 — refused before anything is fetched or written, like the
+    // template and design refusals below. The message never repeats the value.
+    if (opts.license !== undefined)
+        assertLicenseKeyShape(opts.license);
+    const licenseKey = opts.license ?? opts.licenseKey;
     // Resolved first, and by the registry rather than re-validated here: the
     // name already passed `parse-args.ts`, and `resolveTemplate` throws a
-    // `TemplateError` for a programmatic caller that skipped the parser.
-    const template = opts.template !== undefined ? resolveTemplate(opts.template) : undefined;
+    // `TemplateError` for a programmatic caller that skipped the parser. A
+    // `shape` resolves to its one Free starter and from there is the template
+    // path verbatim (#6754 D5); neither leaves the bare overlay untouched.
+    if (opts.template !== undefined && opts.shape !== undefined) {
+        throw new TemplateError("pass a template or a shape, not both");
+    }
+    const template = opts.template !== undefined
+        ? resolveTemplate(opts.template)
+        : opts.shape !== undefined
+            ? resolveShapeTemplate(opts.shape)
+            : undefined;
+    // #6638 — the design this scaffold renders: the caller's override, else the
+    // template's own. Unset for a scaffold naming neither.
+    const design = opts.design ?? template?.design;
+    if (design !== undefined && !STARTER_DESIGNS.includes(design)) {
+        throw new TemplateError(`unknown design "${design}". Declared: ${STARTER_DESIGNS.join(", ")}`);
+    }
     // #5618 D2 — the `extends` chain is resolved in the client registry before
     // any fetch: an unknown parent or a cycle is refused here, with the target
-    // still non-existent, like the four refusals below.
-    if (template !== undefined)
-        resolveTemplateLineage(template.name);
+    // still non-existent, like the four refusals below. The registry is the
+    // union of TEMPLATE_MANIFESTS and SHAPE_STARTERS (#6757 D6 row 1): a
+    // `--shape` run's resolved template may be a bare-shape starter, whose name
+    // (the shape itself) `TEMPLATE_MANIFESTS` alone does not carry.
+    if (template !== undefined) {
+        resolveTemplateLineage(template.name, {
+            ...TEMPLATE_MANIFESTS,
+            ...SHAPE_STARTERS,
+        });
+    }
     // The effective module set: union(template.requires, parsed --modules),
     // normalized through `normalizeModules` — the single ordering authority
     // (parent record D7). Order-independence falls out rather than being
     // engineered: it returns `RECOGNIZED_MODULES.filter(...)`, declaration-
     // ordered and deduped, so the same SET in any argument order is the same
     // list.
-    const modules = normalizeModules([
-        ...(template?.requires ?? []),
-        ...(opts.modules ?? ["marketing"]),
-    ]);
-    const { paid } = classifyModules(modules);
-    const bundles = await resolvePaidModules({
-        paidModules: paid,
-        licenseKey: opts.licenseKey,
-        ...(template !== undefined ? { templateName: template.name } : {}),
-        ...(opts.moduleRegistryUrl !== undefined
-            ? { registryUrl: opts.moduleRegistryUrl }
-            : {}),
-        ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
-    });
+    let modules;
+    let bundles;
+    // The run's derived level (#6759), for `assertDesignAllowed` below.
+    // Undefined on the alias branch and on a `--modules`-keep run (D2/D4 in
+    // module-license-gate.ts — the level plays no part in composing either),
+    // so a non-`standard` design on either path derives it separately, below.
+    let level;
+    if (opts.template !== undefined) {
+        // Alias run — untouched (NFR-4): the union line and its
+        // resolvePaidModules({ …, templateName }) call stay exactly as they were.
+        modules = normalizeModules([
+            ...(template?.requires ?? []),
+            ...(opts.modules ?? ["marketing"]),
+        ]);
+        const { paid } = classifyModules(modules);
+        bundles = await resolvePaidModules({
+            paidModules: paid,
+            licenseKey,
+            ...(template !== undefined ? { templateName: template.name } : {}),
+            ...(opts.moduleRegistryUrl !== undefined
+                ? { registryUrl: opts.moduleRegistryUrl }
+                : {}),
+            ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+        });
+        // #6760 — `resolveModuleSet` never runs on this branch (NFR-4), so no
+        // level was derived above. Derive one — from the registry's per-module
+        // answers, never a key claim (D2) — only when the caller CHOSE a
+        // non-`standard` design alongside the template (`opts.design`). An
+        // alias's own declared design is never gated (#6778 option (c)), so a
+        // plain `--template minimalism-site` run makes no extra network call and
+        // is never refused on its design.
+        if (opts.design !== undefined && !FREE_DESIGNS.includes(opts.design)) {
+            ({ level } = await deriveLevel({
+                licenseKey,
+                ...(opts.moduleRegistryUrl !== undefined
+                    ? { registryUrl: opts.moduleRegistryUrl }
+                    : {}),
+                ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+            }));
+        }
+    }
+    else {
+        // Shape and bare runs — the key's level decides (#6759 D6), never a flag,
+        // a manifest or a key claim.
+        const chosen = await resolveModuleSet({
+            named: opts.modules,
+            licenseKey,
+            ...(opts.moduleRegistryUrl !== undefined
+                ? { registryUrl: opts.moduleRegistryUrl }
+                : {}),
+            ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+        });
+        bundles = chosen.bundles;
+        level = chosen.level;
+        modules =
+            template !== undefined
+                ? normalizeModules([...template.requires, ...chosen.modules])
+                : chosen.modules;
+        // A paid member of the shape's own starter `requires` not already
+        // fetched during the level probe (D6) — every buildable shape's starter
+        // requires only `marketing` today, so this is presently a no-op branch.
+        if (template !== undefined) {
+            const templatePaid = classifyModules(template.requires).paid;
+            const stillMissing = templatePaid.filter((m) => !bundles.has(m));
+            if (stillMissing.length > 0) {
+                const extra = await resolvePaidModules({
+                    paidModules: stillMissing,
+                    licenseKey,
+                    ...(opts.moduleRegistryUrl !== undefined
+                        ? { registryUrl: opts.moduleRegistryUrl }
+                        : {}),
+                    ...(opts.fetchImpl !== undefined
+                        ? { fetchImpl: opts.fetchImpl }
+                        : {}),
+                });
+                for (const [k, v] of extra)
+                    bundles.set(k, v);
+            }
+        }
+    }
+    // #6760 D4 — after the level is resolved, before any fetch or write below.
+    // Only the caller's chosen design is gated (#6778 option (c)); a template's
+    // own declared design is not. `level ?? "free"` fails closed: a
+    // `--modules`-keep run under-reports its level by design (NFR-2), so a
+    // chosen non-`standard` design on that path is refused rather than trusted.
+    assertDesignAllowed(opts.design, level ?? "free");
     // The template's OWN bundle, fetched here — before `scaffoldSync` — so the
     // fourth refusal (the template's bundle unpublished, parent record D17 /
     // spec 5481 § 3 DD5 row 4) throws with the target still non-existent, like
@@ -189,7 +333,7 @@ export async function scaffold(opts) {
     const templateBundle = template !== undefined && templateDelivery(template) === "paid"
         ? await fetchTemplate({
             templateName: template.name,
-            token: opts.licenseKey ?? process.env["AILK_LICENSE_KEY"] ?? "",
+            token: licenseKey ?? process.env["AILK_LICENSE_KEY"] ?? "",
             ...(opts.templateRegistryUrl !== undefined
                 ? { registryUrl: opts.templateRegistryUrl }
                 : {}),
@@ -224,9 +368,11 @@ export async function scaffold(opts) {
         ...(surfaces !== undefined ? { surfaces } : {}),
         // #5612 D1/D2 — the code registry's own `layout` block, known
         // synchronously (unlike a bundle's `ailk-template.json`, only readable
-        // after install below). A template declaring none resolves to the same
-        // defaults `scaffoldSync` already writes for a templateless scaffold.
+        // after install below). A template declaring none resolves to its
+        // design's knobs (#6638), and a `standard` one to the same defaults
+        // `scaffoldSync` already writes for a templateless scaffold.
         ...(template?.layout !== undefined ? { layout: template.layout } : {}),
+        ...(design !== undefined ? { design } : {}),
     });
     // Threaded to extractModuleBundle for `package.json` patch targets'
     // `workspace:*` substitution (spec 5418 § 3 D2) — the same version map
@@ -311,7 +457,7 @@ export async function scaffold(opts) {
                 ownership,
             })
             : (() => {
-                const sourceRoot = join(SITE_TEMPLATES_DIR, template.name);
+                const sourceRoot = join(SITE_TEMPLATES_DIR, templateTreeDir(template.name));
                 if (!existsSync(sourceRoot)) {
                     throw new Error(`template "${template.name}": ${sourceRoot} is missing — the published package must carry site-templates/ in its "files" list`);
                 }
@@ -327,11 +473,73 @@ export async function scaffold(opts) {
                 });
             })();
         if (installed.layout !== undefined) {
-            writeFileSync(join(result.targetDir, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(installed.layout)));
+            writeFileSync(join(result.targetDir, SITE_CHROME_PATH), renderSiteChrome(resolveSiteChrome(installed.layout, design)));
         }
+        pruneUnrosteredSeeds(result.targetDir, mergeRoster(template, template.requires), result.surfaces, ownership);
+    }
+    // #6683 D9 — persisted only after every layer landed, and only when the
+    // caller passed `license`: a scaffold without it writes nothing new.
+    if (opts.license !== undefined) {
+        writeLicenseKeyFiles(result.targetDir, opts.license);
+    }
+    // #6754 D4/D5 — the resolved starter, so the CLI names what it built.
+    if (template !== undefined && design !== undefined) {
+        return {
+            ...result,
+            starter: { template: template.name, shape: template.shape, design },
+        };
     }
     return result;
 }
+/**
+ * The per-row install of the two SHARED seed layers (#6646 D1, disposition
+ * (b)): with every layer landed, remove each `content/en/**.mdx` that the
+ * `templates/` snapshot (the overlay — no `ownership` entry) or the `_base`
+ * layer wrote and no merged roster row names. Those two layers serve every
+ * template, so each carries seeds some templates do not roster (`/pricing`
+ * on a services site); a template's own tree and its modules' bundles are
+ * never pruned — a seed THEY ship without a row is drift, which the manifest
+ * generator's `--check` fails on instead.
+ *
+ * Merged over the template's own `requires`, as `rosterSurfaces` is: the
+ * rows that name shared-layer seeds are the template's own. A seed inside
+ * the content directory of a surface this scaffold ENABLES is kept too, so
+ * an explicit `--surfaces pricing` on a template that does not roster
+ * `/pricing` gets its route and its seed together.
+ */
+function pruneUnrosteredSeeds(targetDir, roster, surfaces, ownership) {
+    // `installBundleTree`'s ownership label for the base layer: it installs
+    // with `templateRequires: []`, so it records as a template. The overlay
+    // (the `templates/` snapshot) records no owner at all.
+    const shared = new Set([undefined, `template "${BASE_LAYER_DIR}"`]);
+    const enabledDirs = GATEABLE_SURFACES.filter((surface) => surfaces.includes(surface.id)).flatMap((surface) => surface.content.map((dir) => `${dir.replace("<locale>", "en")}/`));
+    const root = join(targetDir, "content", "en");
+    if (!existsSync(root))
+        return;
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(abs);
+                continue;
+            }
+            if (!entry.name.endsWith(".mdx"))
+                continue;
+            const path = relative(targetDir, abs).split(sep).join("/");
+            if (shared.has(ownership.get(path)) &&
+                !rosterDeclares(roster, path) &&
+                !enabledDirs.some((prefix) => path.startsWith(prefix))) {
+                rmSync(abs);
+                if (readdirSync(dir).length === 0)
+                    rmdirSync(dir);
+            }
+        }
+    }
+}
 /**
  * The MODULE-LESS gateable-surface ids a template's merged roster names
  * (#5469 D10): every `GATEABLE_SURFACES` entry no module contributes
@@ -478,6 +686,57 @@ export function syncRoutesSync(opts) {
         versions: readVersionMap(),
     });
 }
+/**
+ * Apply a purchased module to an already-scaffolded site in place
+ * (`create-ailk add-module`, #6653). The thin package-rooted wrapper around
+ * `add-module.ts`'s `applyModuleToScaffold`, the `syncRoutesSync` split:
+ *
+ *   1. the target must be an existing scaffold — the same check as the sync
+ *      subcommands above;
+ *   2. a free module is refused before any key read or network call — it
+ *      ships with every scaffold, there is no bundle to add;
+ *   3. `resolvePaidModules` — the SAME gate `scaffold()` runs, so a missing
+ *      key or a key that does not cover the module is refused with the
+ *      scaffold-time message, before anything is written;
+ *   4. the fetched bundle is merged under the plus-config policy.
+ */
+export async function addModule(opts) {
+    const targetAbs = resolve(opts.targetDir);
+    if (!existsSync(targetAbs)) {
+        throw new Error(`add-module target does not exist: ${targetAbs}. Point add-module at an already-scaffolded repo.`);
+    }
+    if (!statSync(targetAbs).isDirectory()) {
+        throw new Error(`add-module target is not a directory: ${targetAbs}`);
+    }
+    if (!existsSync(join(targetAbs, "architecture.yaml"))) {
+        throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
+    }
+    const { paid } = classifyModules([opts.moduleName]);
+    if (paid.length === 0) {
+        throw new AddModuleRefusedError(`"${opts.moduleName}" ships with every scaffold — there is no module bundle to add`);
+    }
+    const bundles = await resolvePaidModules({
+        paidModules: paid,
+        licenseKey: opts.licenseKey,
+        ...(opts.moduleRegistryUrl !== undefined
+            ? { registryUrl: opts.moduleRegistryUrl }
+            : {}),
+        ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    const bundleBytes = bundles.get(opts.moduleName);
+    if (bundleBytes === undefined) {
+        throw new Error(`module "${opts.moduleName}": no bundle was resolved`);
+    }
+    return applyModuleToScaffold({
+        targetDir: targetAbs,
+        moduleName: opts.moduleName,
+        bundleBytes,
+        versions: readVersionMap(),
+        markers: buildScaffoldMarkers(basename(targetAbs)),
+        templatesDir: TEMPLATES_DIR,
+        siteTemplatesDir: SITE_TEMPLATES_DIR,
+    });
+}
 /** Re-exported so the CLI can name the file it wrote without duplicating it. */
 export { CATALOG_TARGET_PATH };
 /**

package/dist/site-chrome.d.ts

@@ -15,11 +15,17 @@
  * `apps/web/lib/site-chrome.ts` every scaffold gets — beside `nav-config.ts`,
  * the same GENERATED-header idiom (`surfaces.ts` `renderNavConfig`).
  *
- * Every field is optional and DEFAULTS to today's render (`full` / `columns`
- * / `true` / `default`) — a scaffold naming no template, or a template naming
- * no `layout` block, gets these defaults written, byte-identical to the
- * monorepo's own committed `apps/web/lib/site-chrome.ts`.
+ * Every field is optional and DEFAULTS to `full` / `columns` / `false` /
+ * `default` — the announcement banner is off unless a template turns it on
+ * (#6469). A scaffold naming no template, or a template naming no `layout`
+ * block, gets these defaults written, byte-identical to the monorepo's own
+ * committed `apps/web/lib/site-chrome.ts`.
+ *
+ * A template's DESIGN supplies layout knobs too (#6638): `DESIGN_LAYOUTS` in
+ * `template-manifest.ts`, read by `resolveSiteChrome`'s optional `design`
+ * argument between an explicit `layout` and these defaults.
  */
+import { type StarterDesign } from "./template-manifest.js";
 /** The `nav` knob's vocabulary. `mark-only` → the layout passes Nav an empty
  *  `navItems` (brand mark + the existing actions/theme/locale controls only). */
 export type SiteChromeNav = "full" | "mark-only";
@@ -47,7 +53,7 @@ export interface ResolvedSiteChrome {
     announcementBanner: boolean;
     home: SiteChromeHome;
 }
-/** Byte-identical-to-today defaults (#5612 D1). */
+/** Defaults (#5612 D1; banner off since #6469). */
 export declare const DEFAULT_SITE_CHROME: ResolvedSiteChrome;
 /** Template-relative path of the generated site-chrome registry — beside `NAV_CONFIG_PATH`. */
 export declare const SITE_CHROME_PATH = "apps/web/lib/site-chrome.ts";
@@ -68,8 +74,13 @@ export declare class TemplateLayoutError extends Error {
  * @param subject Caller-supplied context for the error message (e.g. `template "foo"`).
  */
 export declare function validateTemplateLayout(value: unknown, subject: string): TemplateLayout;
-/** Fill every field a `TemplateLayout` leaves unset with `DEFAULT_SITE_CHROME`'s value. */
-export declare function resolveSiteChrome(layout?: TemplateLayout): ResolvedSiteChrome;
+/**
+ * Fill every field a `TemplateLayout` leaves unset — from `design`'s
+ * `DESIGN_LAYOUTS` entry when one is named (#6638), then from
+ * `DEFAULT_SITE_CHROME`. The explicit `layout` wins field by field, so a
+ * template can wear a design and still override one knob of it.
+ */
+export declare function resolveSiteChrome(layout?: TemplateLayout, design?: StarterDesign): ResolvedSiteChrome;
 /**
  * Render `apps/web/lib/site-chrome.ts` for a resolved layout — the same
  * GENERATED-header idiom `renderNavConfig` uses. `layout.tsx` imports

package/dist/site-chrome.js

@@ -15,16 +15,22 @@
  * `apps/web/lib/site-chrome.ts` every scaffold gets — beside `nav-config.ts`,
  * the same GENERATED-header idiom (`surfaces.ts` `renderNavConfig`).
  *
- * Every field is optional and DEFAULTS to today's render (`full` / `columns`
- * / `true` / `default`) — a scaffold naming no template, or a template naming
- * no `layout` block, gets these defaults written, byte-identical to the
- * monorepo's own committed `apps/web/lib/site-chrome.ts`.
+ * Every field is optional and DEFAULTS to `full` / `columns` / `false` /
+ * `default` — the announcement banner is off unless a template turns it on
+ * (#6469). A scaffold naming no template, or a template naming no `layout`
+ * block, gets these defaults written, byte-identical to the monorepo's own
+ * committed `apps/web/lib/site-chrome.ts`.
+ *
+ * A template's DESIGN supplies layout knobs too (#6638): `DESIGN_LAYOUTS` in
+ * `template-manifest.ts`, read by `resolveSiteChrome`'s optional `design`
+ * argument between an explicit `layout` and these defaults.
  */
-/** Byte-identical-to-today defaults (#5612 D1). */
+import { DESIGN_LAYOUTS, TemplateError, } from "./template-manifest.js";
+/** Defaults (#5612 D1; banner off since #6469). */
 export const DEFAULT_SITE_CHROME = {
     nav: "full",
     footer: "columns",
-    announcementBanner: true,
+    announcementBanner: false,
     home: "default",
 };
 /** Template-relative path of the generated site-chrome registry — beside `NAV_CONFIG_PATH`. */
@@ -85,13 +91,25 @@ export function validateTemplateLayout(value, subject) {
     }
     return result;
 }
-/** Fill every field a `TemplateLayout` leaves unset with `DEFAULT_SITE_CHROME`'s value. */
-export function resolveSiteChrome(layout) {
+/**
+ * Fill every field a `TemplateLayout` leaves unset — from `design`'s
+ * `DESIGN_LAYOUTS` entry when one is named (#6638), then from
+ * `DEFAULT_SITE_CHROME`. The explicit `layout` wins field by field, so a
+ * template can wear a design and still override one knob of it.
+ */
+export function resolveSiteChrome(layout, design) {
+    const fromDesign = design !== undefined ? DESIGN_LAYOUTS[design] : {};
+    // A JS caller (or a cast) can reach here with an undeclared design.
+    if (fromDesign === undefined) {
+        throw new TemplateError(`unknown design "${design}". Declared: ${Object.keys(DESIGN_LAYOUTS).join(", ")}`);
+    }
     return {
-        nav: layout?.nav ?? DEFAULT_SITE_CHROME.nav,
-        footer: layout?.footer ?? DEFAULT_SITE_CHROME.footer,
-        announcementBanner: layout?.announcementBanner ?? DEFAULT_SITE_CHROME.announcementBanner,
-        home: layout?.home ?? DEFAULT_SITE_CHROME.home,
+        nav: layout?.nav ?? fromDesign.nav ?? DEFAULT_SITE_CHROME.nav,
+        footer: layout?.footer ?? fromDesign.footer ?? DEFAULT_SITE_CHROME.footer,
+        announcementBanner: layout?.announcementBanner ??
+            fromDesign.announcementBanner ??
+            DEFAULT_SITE_CHROME.announcementBanner,
+        home: layout?.home ?? fromDesign.home ?? DEFAULT_SITE_CHROME.home,
     };
 }
 /**
@@ -106,8 +124,8 @@ export function renderSiteChrome(resolved) {
 //
 // GENERATED by create-ailk from the declared template's \`layout\` block
 // (#5612). A scaffold with no template, or a template with no \`layout\`
-// block, gets these defaults — byte-identical to every scaffold before this
-// file existed. \`apps/web/app/[locale]/layout.tsx\` reads this to decide:
+// block, gets the defaults below (the announcement banner is off unless a
+// template turns it on, #6469). \`apps/web/app/[locale]/layout.tsx\` reads this to decide:
 //   - nav: "mark-only" → Nav renders the brand mark + right-hand controls
 //     only (no nav links).
 //   - footer: "centered" → Footer renders its existing centered variant.