create-ailk 0.8.0 → 0.10.0

package/dist/lib/design-checks.d.ts

@@ -0,0 +1,78 @@
+/** One row of theme's contrast audit, as the audit script prints it. */
+export interface ContrastRow {
+    name: string;
+    bg: string;
+    fg: string;
+    ratio: number | null;
+    threshold: number;
+    status: "pass" | "fail" | "unmeasurable";
+}
+export type DesignContrastVerdict = {
+    ok: true;
+    pairs: number;
+} | {
+    ok: false;
+    pairs: number;
+    failing: ContrastRow[];
+    reason: string;
+};
+/**
+ * Decide whether `design`'s derived token set passes WCAG AA. Every row whose
+ * status is not `pass` fails it; an audit of no pair never passes.
+ */
+export declare function assessDesignContrast(design: string, results: ContrastRow[]): DesignContrastVerdict;
+/** `__tests__/fixtures/page-jsonld.ts`'s stdout: page path → its composed JSON-LD. */
+export type ComposedPages = Record<string, {
+    jsonld: string;
+    sectionsValid: boolean;
+}>;
+/** One changed node: the page and its JSON-pointer path (or a `(page …)` pseudo-path). */
+export interface DriftNode {
+    page: string;
+    path: string;
+}
+/**
+ * Every node that differs between two compositions, sorted by page then path.
+ * A removed or added page, and a page whose sections no longer validate after,
+ * are one pseudo-path node each; a `logo` subtree is never compared.
+ */
+export declare function jsonLdDrift(before: ComposedPages, after: ComposedPages): DriftNode[];
+export type JsonLdDriftVerdict = {
+    ok: true;
+    pages: number;
+} | {
+    ok: false;
+    pages: number;
+    changed: DriftNode[];
+    reason: string;
+};
+/** Decide whether `apply-design <design>` left every page's JSON-LD unchanged (logo excluded). */
+export declare function assessJsonLdDrift(design: string, before: ComposedPages, after: ComposedPages): JsonLdDriftVerdict;
+export interface MeasureApplyDesignDriftOptions {
+    /** create-ailk's built `dist/cli.js`. */
+    cliPath: string;
+    /** The monorepo's `tsx` binary. */
+    tsxPath: string;
+    /** `__tests__/fixtures/page-jsonld.ts` — the one production composer, run from source. */
+    composerPath: string;
+    /** Its tsconfig, passed as `TSX_TSCONFIG_PATH`. */
+    composerTsconfig: string;
+    /** The design `apply-design` applies (a name or a package path). */
+    design: string;
+    /** An existing empty directory; the drift site is scaffolded at `<workDir>/site`. */
+    workDir: string;
+    /** The loopback registry the CLI resolves modules and templates from. */
+    registryUrl?: string;
+    /** Written to the site's own `ailk.key`, which `apply-design` gates a non-Free design on. */
+    licenseKey?: string;
+}
+/**
+ * Scaffold a keyless `organization-product` site on `standard`, compose its
+ * JSON-LD, run `apply-design <design>` on it, and compose again. A non-zero
+ * exit at any step throws naming the step and the child's stderr.
+ */
+export declare function measureApplyDesignDrift(opts: MeasureApplyDesignDriftOptions): {
+    before: ComposedPages;
+    after: ComposedPages;
+    applyStdout: string;
+};

package/dist/lib/design-checks.js

@@ -0,0 +1,174 @@
+/**
+ * The two design checks a design-wearing run of `scripts/verify-scaffold.mjs`
+ * runs before install (#6823, spec
+ * docs/specs/6823-the-matrix-runs-the-derived-spec.md D3).
+ *
+ * CONTRAST — `assessDesignContrast` turns the rows
+ * `packages/theme/scripts/audit-site-theme-contrast.ts` prints (theme's
+ * `auditTokenSetContrast` over the design's derived token set) into a verdict
+ * naming every non-passing `{bg, fg}` pair and the design. The WCAG math and
+ * the pair list stay theme's; this file only decides pass/fail.
+ *
+ * DRIFT — `jsonLdDrift` / `assessJsonLdDrift` compare every page's composed
+ * JSON-LD before and after `apply-design`, excluding the logo image (the PRD
+ * metric "structural drift after apply"), and `measureApplyDesignDrift`
+ * gathers the two snapshots (the `renderRoute` precedent, #6821 D4): it
+ * touches the filesystem and processes only through the paths it is handed,
+ * so the driver and `__tests__/verify-scaffold-checks.test.ts` run the same
+ * procedure. Nothing here imports `@working-theory/theme`.
+ */
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+function describePair(row) {
+    const measured = row.status === "unmeasurable" || row.ratio === null
+        ? "unmeasurable"
+        : `${row.ratio.toFixed(2)}:1 < ${row.threshold}:1`;
+    return `${row.name} {bg ${row.bg}, fg ${row.fg}} ${measured}`;
+}
+/**
+ * Decide whether `design`'s derived token set passes WCAG AA. Every row whose
+ * status is not `pass` fails it; an audit of no pair never passes.
+ */
+export function assessDesignContrast(design, results) {
+    const pairs = results.length;
+    if (pairs === 0) {
+        return { ok: false, pairs, failing: [], reason: `design ${design}: no contrast pair was audited` };
+    }
+    const failing = results.filter((row) => row.status !== "pass");
+    if (failing.length === 0)
+        return { ok: true, pairs };
+    return {
+        ok: false,
+        pairs,
+        failing,
+        reason: `design ${design}: ${failing.length} of ${pairs} contrast pair(s) below WCAG AA — ${failing
+            .map(describePair)
+            .join("; ")}`,
+    };
+}
+/** schema.org's logo property — the one subtree the PRD's "excluding the logo image" skips. */
+const LOGO_KEY = "logo";
+const kindOf = (value) => value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+function walk(before, after, path, out) {
+    const kind = kindOf(before);
+    if (kind !== kindOf(after)) {
+        out.push(path);
+        return;
+    }
+    if (kind === "array") {
+        const a = before;
+        const b = after;
+        if (a.length !== b.length)
+            out.push(path);
+        for (let i = 0; i < Math.min(a.length, b.length); i++)
+            walk(a[i], b[i], `${path}/${i}`, out);
+        return;
+    }
+    if (kind === "object") {
+        const a = before;
+        const b = after;
+        for (const key of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
+            if (key === LOGO_KEY)
+                continue;
+            walk(a[key], b[key], `${path}/${key}`, out);
+        }
+        return;
+    }
+    if (before !== after)
+        out.push(path);
+}
+/**
+ * Every node that differs between two compositions, sorted by page then path.
+ * A removed or added page, and a page whose sections no longer validate after,
+ * are one pseudo-path node each; a `logo` subtree is never compared.
+ */
+export function jsonLdDrift(before, after) {
+    const nodes = [];
+    for (const page of [...new Set([...Object.keys(before), ...Object.keys(after)])]) {
+        const b = before[page];
+        const a = after[page];
+        if (a === undefined) {
+            nodes.push({ page, path: "(page removed)" });
+        }
+        else if (b === undefined) {
+            nodes.push({ page, path: "(page added)" });
+        }
+        else if (!a.sectionsValid) {
+            nodes.push({ page, path: "(sections invalid)" });
+        }
+        else {
+            const paths = [];
+            walk(JSON.parse(b.jsonld), JSON.parse(a.jsonld), "", paths);
+            for (const path of paths)
+                nodes.push({ page, path: path === "" ? "/" : path });
+        }
+    }
+    const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return nodes.sort((x, y) => cmp(x.page, y.page) || cmp(x.path, y.path));
+}
+/** How many changed nodes a drift reason lists before it stops. */
+const REASON_NODE_LIMIT = 10;
+/** Decide whether `apply-design <design>` left every page's JSON-LD unchanged (logo excluded). */
+export function assessJsonLdDrift(design, before, after) {
+    const pages = Object.keys(before).length;
+    if (pages === 0) {
+        return { ok: false, pages, changed: [], reason: `design ${design}: no page was composed` };
+    }
+    const changed = jsonLdDrift(before, after);
+    if (changed.length === 0)
+        return { ok: true, pages };
+    const listed = changed
+        .slice(0, REASON_NODE_LIMIT)
+        .map((n) => `${n.page} ${n.path}`)
+        .join("; ");
+    return {
+        ok: false,
+        pages,
+        changed,
+        reason: `design ${design}: ${changed.length} JSON-LD node(s) changed by apply-design — ${listed}${changed.length > REASON_NODE_LIMIT ? "; …" : ""}`,
+    };
+}
+/**
+ * Scaffold a keyless `organization-product` site on `standard`, compose its
+ * JSON-LD, run `apply-design <design>` on it, and compose again. A non-zero
+ * exit at any step throws naming the step and the child's stderr.
+ */
+export function measureApplyDesignDrift(opts) {
+    const baseEnv = { ...process.env };
+    delete baseEnv["AILK_LICENSE_KEY"];
+    const registryEnv = opts.registryUrl === undefined
+        ? {}
+        : { AILK_MODULE_REGISTRY_URL: opts.registryUrl, AILK_TEMPLATE_REGISTRY_URL: opts.registryUrl };
+    const site = join(opts.workDir, "site");
+    const exec = (label, cmd, args, env) => {
+        try {
+            return execFileSync(cmd, args, {
+                encoding: "utf8",
+                env: { ...baseEnv, ...env },
+                stdio: ["ignore", "pipe", "pipe"],
+                maxBuffer: 64 * 1024 * 1024,
+            });
+        }
+        catch (err) {
+            const { stderr, message } = err;
+            throw new Error(`drift: ${label} failed: ${(stderr || message || "").trim()}`, { cause: err });
+        }
+    };
+    const compose = (label) => {
+        const stdout = exec(label, opts.tsxPath, [opts.composerPath, site], { TSX_TSCONFIG_PATH: opts.composerTsconfig });
+        try {
+            return JSON.parse(stdout);
+        }
+        catch (err) {
+            throw new Error(`drift: ${label} printed no JSON: ${err.message}`, { cause: err });
+        }
+    };
+    exec("scaffold organization-product on standard", process.execPath, [opts.cliPath, site, "--shape", "organization-product", "--design", "standard"], registryEnv);
+    if (opts.licenseKey !== undefined)
+        writeFileSync(join(site, "ailk.key"), `${opts.licenseKey}\n`);
+    const before = compose("compose JSON-LD before apply-design");
+    const applyStdout = exec(`apply-design ${opts.design}`, process.execPath, [opts.cliPath, "apply-design", opts.design, "--target", site], opts.registryUrl === undefined ? {} : { AILK_MODULE_REGISTRY_URL: opts.registryUrl });
+    const after = compose("compose JSON-LD after apply-design");
+    return { before, after, applyStdout };
+}

package/dist/lib/license-key-files.d.ts

@@ -6,6 +6,15 @@ export declare const LICENSE_ENV_VAR = "AILK_LICENSE_KEY";
  * describes the rule, never the value.
  */
 export declare function assertLicenseKeyShape(key: string): void;
+/**
+ * Write `content` only when it differs, with mode 0600 either way. An existing
+ * file is tightened BEFORE the write — `mode` applies only on creation, so a
+ * looser pre-existing `.env` would otherwise hold the key for a moment at its
+ * old permissions.
+ */
+export declare function writeOwnerOnly(path: string, content: string): void;
+/** `text` plus `line`, starting on a fresh line. */
+export declare function appendLine(text: string, line: string): string;
 /**
  * Persist `key` into the scaffold at `dir`: `ailk.key` (0600), the
  * `apps/api/.env` line (0600, other lines kept), and a `.gitignore` entry for

package/dist/lib/license-key-files.js

@@ -48,7 +48,7 @@ export function assertLicenseKeyShape(key) {
  * looser pre-existing `.env` would otherwise hold the key for a moment at its
  * old permissions.
  */
-function writeOwnerOnly(path, content) {
+export function writeOwnerOnly(path, content) {
     mkdirSync(dirname(path), { recursive: true });
     if (existsSync(path))
         chmodSync(path, 0o600);
@@ -58,7 +58,7 @@ function writeOwnerOnly(path, content) {
     chmodSync(path, 0o600);
 }
 /** `text` plus `line`, starting on a fresh line. */
-function appendLine(text, line) {
+export function appendLine(text, line) {
     const sep = text.length === 0 || text.endsWith("\n") ? "" : "\n";
     return `${text}${sep}${line}\n`;
 }

package/dist/lib/module-license-gate.d.ts

@@ -1,28 +1,4 @@
-/**
- * Paid-module license gate (K1, #5089 — Flavor 3). Orchestrates
- * `module-tier.ts`'s classification + `fetch-module.ts`'s authenticated
- * fetch into the three honest states the CLI must surface:
- *
- *   (a) no key + a paid module requested  → conversion hint, non-zero, ZERO
- *       network (mirrors `install-skill.ts`'s free-tier short-circuit).
- *   (b) a lapsed/invalid key + a paid module → "your licence does not cover
- *       this", non-zero (the module distribution's own 401 — see
- *       `fetch-module.ts`'s file doc for why there is no local JWT
- *       pre-check here).
- *   (c) a valid key → every requested paid module's bundle bytes, ready for
- *       `extract-module-bundle.ts` to merge into the scaffold.
- *
- * A Free-only request (no paid modules) never reaches the key check at all —
- * `resolvePaidModules` returns immediately, before touching `process.env` or
- * the network, so a bare/all-Free scaffold is provably unaffected by this
- * gate (K1's regression floor).
- *
- * Also carries the design gate (#6760): `assertDesignAllowed` refuses a
- * non-`standard` design at the `free` level, naming the design and the
- * run's level, before `scaffold()`'s first disk write.
- */
 import type { ModuleName } from "../parse-args.js";
-import type { StarterDesign } from "../template-manifest.js";
 import { type Level } from "./module-tier.js";
 /**
  * Where a refused run sends the buyer. `/pricing`, not `/pro`: there is no
@@ -39,18 +15,58 @@ export declare const CONVERSION_HINT_URL = "https://ailaunchkit.ai/pricing";
 export declare class LicenseRequiredError extends Error {
     constructor(message: string);
 }
-/** Designs every level renders (#6760 D1). Anything else in `STARTER_DESIGNS` is Pro and up. */
-export declare const FREE_DESIGNS: readonly StarterDesign[];
+/** The five axes `release-scope.json` declares (spec 6977 D3). */
+export type ReleaseAxis = "templates" | "shapes" | "designs" | "modules" | "levels";
+/** `gated` and `deferred` are both refused; only a `gated` one gets negative checks. */
+export type ReleaseStatus = "released" | "gated" | "deferred";
+export type ReleaseScope = Readonly<Record<ReleaseAxis, Readonly<Record<string, ReleaseStatus>>>>;
+/**
+ * The package-root `release-scope.json` (shipped in `files`). A static JSON
+ * import, not an `import.meta.url` read, for `fetch-module.ts`'s reason: jest
+ * loads this module directly. `release-scope.test.ts` pins every registry
+ * name to an entry here (R5).
+ */
+export declare const RELEASE_SCOPE: ReleaseScope;
+/** Thrown for a surface outside the release scope — a refusal, not a licence state. */
+export declare class ReleaseScopeError extends Error {
+    constructor(message: string);
+}
+/**
+ * Refuse any of `names` that `scope[axis]` marks `gated` or `deferred`, with
+ * the not-available message `parse-args.ts` gives a reserved shape. A name
+ * the scope does not list (a customer's own design, say) is not refused.
+ * Bypassed when `AILK_RELEASE_SCOPE=ignore` — this package's jest setup and
+ * an operator's own run; a published CLI never sets it.
+ *
+ * Called on the scaffold path only (`scaffold()`, `cli.ts`, and the level
+ * check in `resolveModuleSet`) — never from `parseModules`, so `add-module`
+ * and `--sync-architecture` keep working on a site that already carries a
+ * gated module.
+ */
+export declare function assertReleased(axis: ReleaseAxis, names: readonly (string | undefined)[], scope?: ReleaseScope): void;
+/**
+ * Design names every level renders (#6760 D1). Anything else in
+ * `STARTER_DESIGNS` is Pro and up. A path design's Free-ness is decided by
+ * `resolveDesign`'s identity rule (#6813 D2), never by this list directly —
+ * `assertDesignAllowed`'s `free` parameter carries that verdict in.
+ */
+export declare const FREE_DESIGNS: readonly string[];
 /** Levels that render any design (#6760 D1) — an allow-list: an unknown level is not in it. */
 export declare const DESIGN_LEVELS: readonly Level[];
 /**
- * Refuse a non-`standard` design at a level below Pro (#6760 D1, D6). Pure
- * and synchronous — takes the level `deriveLevel`/`resolveModuleSet` already
- * resolved; never reads a key or derives a level itself (D2, fail-closed:
- * both checks below are allow-lists, so an unrecognized `level` refuses
- * rather than granting it).
+ * Refuse a non-Free design at a level below Pro (#6760 D1, D6; widened to a
+ * path design #6813 D7). Pure and synchronous — takes the level
+ * `deriveLevel`/`resolveModuleSet` already resolved; never reads a key or
+ * derives a level itself (D2, fail-closed: both checks below are allow-lists,
+ * so an unrecognized `level` refuses rather than granting it).
+ *
+ * @param free Whether `design` is Free — defaults to `FREE_DESIGNS.includes(design)`
+ *   (a design NAME's own answer), so a caller passing a name never changes
+ *   behaviour. A path design's caller (`programmatic.ts`, off `resolveDesign`'s
+ *   identity rule) passes it explicitly: a byte-identical copy of a shipped
+ *   Free design is Free; any other path is not, whatever it is named.
  */
-export declare function assertDesignAllowed(design: StarterDesign | undefined, level: Level): void;
+export declare function assertDesignAllowed(design: string | undefined, level: Level, free?: boolean): void;
 export interface ResolvePaidModulesOptions {
     /** The requested module set's paid subset (see `module-tier.ts`). */
     paidModules: ModuleName[];

package/dist/lib/module-license-gate.js

@@ -1,3 +1,31 @@
+/**
+ * Paid-module license gate (K1, #5089 — Flavor 3). Orchestrates
+ * `module-tier.ts`'s classification + `fetch-module.ts`'s authenticated
+ * fetch into the three honest states the CLI must surface:
+ *
+ *   (a) no key + a paid module requested  → conversion hint, non-zero, ZERO
+ *       network (mirrors `install-skill.ts`'s free-tier short-circuit).
+ *   (b) a lapsed/invalid key + a paid module → "your licence does not cover
+ *       this", non-zero (the module distribution's own 401 — see
+ *       `fetch-module.ts`'s file doc for why there is no local JWT
+ *       pre-check here).
+ *   (c) a valid key → every requested paid module's bundle bytes, ready for
+ *       `extract-module-bundle.ts` to merge into the scaffold.
+ *
+ * A Free-only request (no paid modules) never reaches the key check at all —
+ * `resolvePaidModules` returns immediately, before touching `process.env` or
+ * the network, so a bare/all-Free scaffold is provably unaffected by this
+ * gate (K1's regression floor).
+ *
+ * Also carries the design gate (#6760): `assertDesignAllowed` refuses a
+ * non-`standard` design at the `free` level, naming the design and the
+ * run's level, before `scaffold()`'s first disk write.
+ *
+ * And the release-scope gate (#6984, spec 6977 D3): `assertReleased` refuses
+ * a template, shape, design, module or level that `release-scope.json` marks
+ * `gated` or `deferred`, on the scaffold path only.
+ */
+import releaseScopeJson from "../../release-scope.json" with { type: "json" };
 import { FetchModuleError, fetchModule } from "./fetch-module.js";
 import { assertLicenseKeyShape } from "./license-key-files.js";
 import { ADD_ONS, LEVEL_LABEL, LEVEL_MODULES, OPT_IN_MODULES, PAID_MODULES, classifyModules, composeModuleSet, levelOf, } from "./module-tier.js";
@@ -19,19 +47,98 @@ export class LicenseRequiredError extends Error {
         this.name = "LicenseRequiredError";
     }
 }
-/** Designs every level renders (#6760 D1). Anything else in `STARTER_DESIGNS` is Pro and up. */
+/**
+ * The package-root `release-scope.json` (shipped in `files`). A static JSON
+ * import, not an `import.meta.url` read, for `fetch-module.ts`'s reason: jest
+ * loads this module directly. `release-scope.test.ts` pins every registry
+ * name to an entry here (R5).
+ */
+export const RELEASE_SCOPE = releaseScopeJson;
+const AXIS_NOUN = {
+    templates: "template",
+    shapes: "shape",
+    designs: "design",
+    modules: "module",
+    levels: "level",
+};
+/** Thrown for a surface outside the release scope — a refusal, not a licence state. */
+export class ReleaseScopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReleaseScopeError";
+    }
+}
+const RELEASE_STATUSES = ["released", "gated", "deferred"];
+/**
+ * Refuse a scope carrying a status other than `released`, `gated` or
+ * `deferred` — fail closed: a misspelled status never reads as released.
+ */
+function assertValidScope(scope) {
+    for (const [axis, statuses] of Object.entries(scope)) {
+        for (const [name, status] of Object.entries(statuses)) {
+            if (!RELEASE_STATUSES.includes(status)) {
+                throw new ReleaseScopeError(`release-scope.json ${axis}."${name}" is "${String(status)}" — expected one of: ${RELEASE_STATUSES.join(", ")}`);
+            }
+        }
+    }
+}
+/**
+ * Refuse any of `names` that `scope[axis]` marks `gated` or `deferred`, with
+ * the not-available message `parse-args.ts` gives a reserved shape. A name
+ * the scope does not list (a customer's own design, say) is not refused.
+ * Bypassed when `AILK_RELEASE_SCOPE=ignore` — this package's jest setup and
+ * an operator's own run; a published CLI never sets it.
+ *
+ * Called on the scaffold path only (`scaffold()`, `cli.ts`, and the level
+ * check in `resolveModuleSet`) — never from `parseModules`, so `add-module`
+ * and `--sync-architecture` keep working on a site that already carries a
+ * gated module.
+ */
+export function assertReleased(axis, names, scope = RELEASE_SCOPE) {
+    if (process.env["AILK_RELEASE_SCOPE"] === "ignore")
+        return;
+    assertValidScope(scope);
+    const statuses = scope[axis];
+    for (const name of names) {
+        if (name === undefined)
+            continue;
+        const status = statuses[name];
+        if (status !== "gated" && status !== "deferred")
+            continue;
+        const released = Object.keys(statuses).filter((n) => statuses[n] === "released");
+        // A level comes from the key, never a flag — so it points at what the run CAN choose.
+        const choose = axis === "levels"
+            ? `Your licence key's level is ${name}; name the modules you want with --modules (one of: ${Object.keys(scope.modules)
+                .filter((m) => scope.modules[m] === "released")
+                .join(", ")}).`
+            : `Choose one of: ${released.join(", ")}.`;
+        throw new ReleaseScopeError(`${AXIS_NOUN[axis]} "${name}" is not available yet. ${choose}`);
+    }
+}
+/**
+ * Design names every level renders (#6760 D1). Anything else in
+ * `STARTER_DESIGNS` is Pro and up. A path design's Free-ness is decided by
+ * `resolveDesign`'s identity rule (#6813 D2), never by this list directly —
+ * `assertDesignAllowed`'s `free` parameter carries that verdict in.
+ */
 export const FREE_DESIGNS = ["standard"];
 /** Levels that render any design (#6760 D1) — an allow-list: an unknown level is not in it. */
 export const DESIGN_LEVELS = ["pro", "pro-plus"];
 /**
- * Refuse a non-`standard` design at a level below Pro (#6760 D1, D6). Pure
- * and synchronous — takes the level `deriveLevel`/`resolveModuleSet` already
- * resolved; never reads a key or derives a level itself (D2, fail-closed:
- * both checks below are allow-lists, so an unrecognized `level` refuses
- * rather than granting it).
+ * Refuse a non-Free design at a level below Pro (#6760 D1, D6; widened to a
+ * path design #6813 D7). Pure and synchronous — takes the level
+ * `deriveLevel`/`resolveModuleSet` already resolved; never reads a key or
+ * derives a level itself (D2, fail-closed: both checks below are allow-lists,
+ * so an unrecognized `level` refuses rather than granting it).
+ *
+ * @param free Whether `design` is Free — defaults to `FREE_DESIGNS.includes(design)`
+ *   (a design NAME's own answer), so a caller passing a name never changes
+ *   behaviour. A path design's caller (`programmatic.ts`, off `resolveDesign`'s
+ *   identity rule) passes it explicitly: a byte-identical copy of a shipped
+ *   Free design is Free; any other path is not, whatever it is named.
  */
-export function assertDesignAllowed(design, level) {
-    if (design === undefined || FREE_DESIGNS.includes(design))
+export function assertDesignAllowed(design, level, free = design !== undefined && FREE_DESIGNS.includes(design)) {
+    if (design === undefined || free)
         return;
     if (DESIGN_LEVELS.includes(level))
         return;
@@ -212,6 +319,8 @@ export async function resolveModuleSet(options) {
         return { modules, bundles };
     }
     const { level, bundles } = await deriveLevel(options);
+    // #6984 — a gated level (Pro Plus) is refused before its defaults compose.
+    assertReleased("levels", [level]);
     const modules = composeModuleSet(namedList, level);
     const { paid } = classifyModules(modules);
     const missing = paid.filter((m) => !bundles.has(m));

package/dist/lib/render-verdict.d.ts

@@ -0,0 +1,52 @@
+/** What the driver observed of one route's render. */
+export interface RenderObservation {
+    /** The requested route, e.g. `/` or `/about`. */
+    route: string;
+    /** The message `page.goto` threw with, when it threw. */
+    gotoError?: string;
+    /** The status of the response `page.goto` resolved; undefined when it resolved none. */
+    status: number | undefined;
+    /** `page.url()` after navigation settled. */
+    finalUrl: string;
+    /** The screenshot's size on disk; undefined when none was written. */
+    pngBytes: number | undefined;
+}
+export type RenderVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Decide whether `route` rendered. Checked in order: a navigation error (a
+ * net error — `ERR_TOO_MANY_REDIRECTS` included — or a timeout), a final
+ * status other than 200, a final pathname other than the requested route (a
+ * redirect elsewhere is not a render of this route), and a missing or empty
+ * PNG. Pathnames are compared, never whole URLs, so a query or hash is fine.
+ */
+export declare function assessRender(observation: RenderObservation): RenderVerdict;
+/** The slice of a Playwright `Page` that `renderRoute` uses. */
+export interface RenderPage {
+    goto(url: string, options: {
+        waitUntil: "load";
+        timeout: number;
+    }): Promise<{
+        status(): number;
+    } | null>;
+    url(): string;
+    screenshot(options: {
+        path: string;
+        fullPage: boolean;
+    }): Promise<unknown>;
+}
+/** How long one navigation may take before it counts as a failed render. */
+export declare const RENDER_TIMEOUT_MS = 60000;
+/**
+ * Navigate `page` to `base + route`, screenshot it to `pngPath`, and return
+ * `assessRender`'s verdict on what happened. `status` comes from the response
+ * `page.goto` itself resolved and `finalUrl` from `page.url()` — never the
+ * requested URL, never a side `fetch` — so a redirect cannot pass as a render.
+ * A failed navigation takes no screenshot; a screenshot that throws counts
+ * as no PNG written — never a stale one left at `pngPath` by an earlier run.
+ */
+export declare function renderRoute(page: RenderPage, base: string, route: string, pngPath: string): Promise<RenderVerdict>;

package/dist/lib/render-verdict.js

@@ -0,0 +1,77 @@
+/**
+ * The verdict on one browser render of a scaffold route (#6821, spec
+ * docs/specs/6821-the-shape-design-render-matrix-spec.md D4).
+ *
+ * A design leg of `scripts/verify-scaffold.mjs` renders its scaffold's home
+ * route and one inner route in Chromium and stores a screenshot of each — the
+ * shape × design render matrix. A render that did not happen must fail the
+ * leg, and proving that rule must not cost a scaffold build, so it lives here
+ * as a pure function (`assessRender`, the `api-boot-assertion.ts` precedent)
+ * plus the one function that gathers its facts (`renderRoute`), which touches
+ * Playwright only through the `page` it is handed. The driver loads both from
+ * `dist/`; `__tests__/verify-scaffold-render.test.ts` drives them with a fake
+ * page. Nothing here imports `@playwright/test`.
+ */
+import { existsSync, rmSync, statSync } from "node:fs";
+/**
+ * Decide whether `route` rendered. Checked in order: a navigation error (a
+ * net error — `ERR_TOO_MANY_REDIRECTS` included — or a timeout), a final
+ * status other than 200, a final pathname other than the requested route (a
+ * redirect elsewhere is not a render of this route), and a missing or empty
+ * PNG. Pathnames are compared, never whole URLs, so a query or hash is fine.
+ */
+export function assessRender(observation) {
+    const { route, gotoError, status, finalUrl, pngBytes } = observation;
+    if (gotoError !== undefined) {
+        return { ok: false, reason: `navigation failed: ${gotoError}` };
+    }
+    if (status !== 200) {
+        return {
+            ok: false,
+            reason: status === undefined ? "navigation resolved no response" : `final status ${status}, expected 200`,
+        };
+    }
+    const finalPath = new URL(finalUrl).pathname;
+    if (finalPath !== route) {
+        return { ok: false, reason: `requested "${route}" but the page settled on "${finalPath}"` };
+    }
+    if (typeof pngBytes !== "number" || pngBytes <= 0) {
+        return { ok: false, reason: pngBytes === 0 ? "the screenshot PNG is empty" : "no screenshot PNG was written" };
+    }
+    return { ok: true };
+}
+/** How long one navigation may take before it counts as a failed render. */
+export const RENDER_TIMEOUT_MS = 60_000;
+/**
+ * Navigate `page` to `base + route`, screenshot it to `pngPath`, and return
+ * `assessRender`'s verdict on what happened. `status` comes from the response
+ * `page.goto` itself resolved and `finalUrl` from `page.url()` — never the
+ * requested URL, never a side `fetch` — so a redirect cannot pass as a render.
+ * A failed navigation takes no screenshot; a screenshot that throws counts
+ * as no PNG written — never a stale one left at `pngPath` by an earlier run.
+ */
+export async function renderRoute(page, base, route, pngPath) {
+    let status;
+    try {
+        const response = await page.goto(base + route, { waitUntil: "load", timeout: RENDER_TIMEOUT_MS });
+        status = response === null ? undefined : response.status();
+    }
+    catch (err) {
+        return assessRender({
+            route,
+            gotoError: err instanceof Error ? err.message : String(err),
+            status: undefined,
+            finalUrl: page.url(),
+            pngBytes: undefined,
+        });
+    }
+    rmSync(pngPath, { force: true });
+    try {
+        await page.screenshot({ path: pngPath, fullPage: true });
+    }
+    catch {
+        // Falls through to the missing-PNG check below.
+    }
+    const pngBytes = existsSync(pngPath) ? statSync(pngPath).size : undefined;
+    return assessRender({ route, status, finalUrl: page.url(), pngBytes });
+}