cronus-ui 0.6.0

package/dist/compose/plan.js

@@ -0,0 +1,506 @@
+/**
+ * Pure plan builder + validator. Turns a parsed {@link AppManifest} + caller
+ * `choices` into a {@link ComposePlan} the renderer consumes, and aggregates ALL
+ * semantic errors (block exists? kind fits slot? routes unique/valid? no
+ * dynamic-slug collisions Next rejects? chrome refs exist? extras resolve to a
+ * page-kind special file? deps safe?) before returning — never bailing on the
+ * first. Nothing here touches the filesystem; the command feeds it the registry
+ * index, meta, and shipped chrome sources.
+ */
+import { assertValidDependency, closestName } from "../utils.js";
+import { blockRefParts } from "./manifest.js";
+/** Thrown by {@link buildComposePlan} carrying EVERY semantic error found. */
+export class ComposePlanError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Invalid compose plan:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
+        this.name = "ComposePlanError";
+        this.errors = errors;
+    }
+}
+/** Valid App Router route: "/", or "/seg" parts of `[a-z0-9-]` / dynamic `[x]`/`[...x]`. */
+const ROUTE_SEGMENT_RE = /^(?:\[(?:\.\.\.)?[a-z0-9-]+\]|[a-z0-9-]+)$/;
+function isValidRoute(route) {
+    if (route === "/")
+        return true;
+    if (!route.startsWith("/"))
+        return false;
+    const segments = route.slice(1).split("/");
+    if (segments.some((s) => s.length === 0))
+        return false; // trailing/double slash
+    return segments.every((s) => ROUTE_SEGMENT_RE.test(s));
+}
+/** True for a dynamic segment `[x]` / `[...x]`. */
+function isDynamicSegment(seg) {
+    return seg.startsWith("[") && seg.endsWith("]");
+}
+/** The slug NAME inside a dynamic segment (`[...id]` → "id", `[id]` → "id"). */
+function dynamicSlugName(seg) {
+    return seg.slice(1, -1).replace(/^\.\.\./, "");
+}
+/**
+ * The static route SKELETON: every dynamic segment collapsed to a positional
+ * marker so `/products/[id]` and `/products/[slug]` share a skeleton (Next treats
+ * them as the same path shape and refuses two different slug names for it).
+ */
+function routeSkeleton(route) {
+    if (route === "/")
+        return "/";
+    return route
+        .slice(1)
+        .split("/")
+        .map((seg) => (isDynamicSegment(seg) ? "[*]" : seg))
+        .join("/");
+}
+/**
+ * The Next special-file names an `extras` block may target in F1. Each maps its
+ * extras KEY to the emitted `app/<file>` special-file path. Only page-kind blocks
+ * may fill these (they are full-page surfaces).
+ */
+const EXTRAS_SPECIAL_FILES = {
+    "not-found": "app/not-found.tsx",
+};
+/** Resolve the brand string: explicit choice → manifest default (filled) → appName. */
+function resolveBrand(manifest, input) {
+    const appName = input.appName ?? manifest.name;
+    if (input.brand !== undefined && input.brand.length > 0)
+        return input.brand;
+    const dflt = manifest.manifest.defaults?.brand;
+    if (dflt !== undefined && dflt.length > 0)
+        return dflt.replaceAll("__APP_NAME__", appName);
+    return appName;
+}
+/** Build the normalized (sorted-key) choices record persisted to `composed{}`. */
+function normalizeChoices(manifest, input, planPages) {
+    const variants = input.variants ?? {};
+    const sortedVariants = {};
+    for (const key of Object.keys(variants).sort()) {
+        const v = variants[key];
+        if (v !== undefined)
+            sortedVariants[key] = v;
+    }
+    return {
+        variants: sortedVariants,
+        pages: planPages.map((p) => p.route),
+        brand: resolveBrand(manifest, input),
+        ...(input.seed !== undefined ? { seed: input.seed } : {}),
+    };
+}
+/**
+ * Build a {@link ComposePlan} from a parsed manifest, caller choices, the registry
+ * index, meta, and the shipped chrome sources. Aggregates ALL semantic errors and
+ * THROWS {@link ComposePlanError} when invalid. The returned plan is a pure
+ * function of its inputs (stable ordering, no I/O/Date).
+ */
+export function buildComposePlan(manifest, input, index, meta, chromeSources) {
+    const errors = [];
+    const known = new Set(index.map((i) => i.name));
+    const blockNames = index.filter((i) => i.type === "registry:block").map((i) => i.name);
+    const body = manifest.manifest;
+    const appName = input.appName ?? manifest.name;
+    // Page subset (F2 `--pages`); default = all manifest pages, in order.
+    const wantRoutes = input.pages;
+    const selectedPages = wantRoutes === undefined ? body.pages : body.pages.filter((p) => wantRoutes.includes(p.route));
+    if (wantRoutes !== undefined) {
+        for (const route of wantRoutes) {
+            if (!body.pages.some((p) => p.route === route)) {
+                errors.push(`--pages: route "${route}" is not in the "${manifest.name}" template`);
+            }
+        }
+        if (selectedPages.length === 0) {
+            errors.push(`--pages: selection matched no pages in the "${manifest.name}" template`);
+        }
+    }
+    // Per-family variant overrides from choices (`--variant login=split`); a
+    // present override wins over whatever variant the manifest ref declared.
+    const variantOverrides = input.variants ?? {};
+    // Resolve a block ref against the registry index + meta, collecting errors,
+    // honoring variants: the effective variant is the choices override (if any),
+    // else the manifest ref's `{ block, variant }`. The default variant resolves to
+    // the bare `<slug>` item + the block's own export; a non-default variant to
+    // `<slug>--<id>` + the variant's export (both read from meta so a generated
+    // page imports exactly what ships).
+    const resolveBlock = (ref, where) => {
+        const { slug, variant: manifestVariant } = blockRefParts(ref);
+        if (!known.has(slug)) {
+            const suggestion = closestName(slug, blockNames);
+            errors.push(suggestion
+                ? `${where}: unknown block "${slug}". Did you mean "${suggestion}"?`
+                : `${where}: unknown block "${slug}".`);
+            return undefined;
+        }
+        const m = meta.blocks[slug];
+        if (m === undefined) {
+            errors.push(`${where}: block "${slug}" has no metadata (regenerate registry meta.json).`);
+            return undefined;
+        }
+        // Choice override wins over the manifest-declared variant.
+        const wantVariant = variantOverrides[slug] ?? manifestVariant;
+        if (wantVariant === undefined) {
+            // Default variant → bare item + the block's own export.
+            return { slug, item: slug, exportName: m.exportName, kind: m.kind };
+        }
+        const variants = m.variants ?? [];
+        const match = variants.find((v) => v.id === wantVariant);
+        if (match === undefined) {
+            const ids = variants.map((v) => v.id);
+            const suggestion = closestName(wantVariant, ids);
+            const hint = ids.length > 0 ? ` (known: ${ids.join(", ")})` : " (this block has no variants)";
+            errors.push(suggestion
+                ? `${where}: unknown variant "${wantVariant}" for block "${slug}". Did you mean "${suggestion}"?`
+                : `${where}: unknown variant "${wantVariant}" for block "${slug}"${hint}.`);
+            return undefined;
+        }
+        // Meta named a variant item; the registry index must actually publish it,
+        // else `registry.resolve(plan.blockSlugs)` would later crash with a raw
+        // ENOENT on the missing item file. This can happen on a drifted custom
+        // `--registry` whose meta references a variant its index omits; the shipped
+        // registry is protected by check-registry's validateVariantItems gate.
+        if (!known.has(match.item)) {
+            errors.push(`${where}: variant "${wantVariant}" of block "${slug}" resolves to item "${match.item}", ` +
+                `which the registry index does not publish (regenerate/repair the registry).`);
+            return undefined;
+        }
+        // A matched variant carries its own registry item + export. The default
+        // variant's meta `item` equals the bare slug (so `variant` stays absent);
+        // a non-default variant records its id so the renderer imports from
+        // `<slug>--<id>`.
+        const isDefault = match.item === slug;
+        return {
+            slug,
+            item: match.item,
+            exportName: match.exportName,
+            kind: m.kind,
+            ...(isDefault ? {} : { variant: match.id }),
+        };
+    };
+    // --- Pages ---------------------------------------------------------------
+    const seenRoutes = new Set();
+    const planPages = [];
+    const chromeGroupsUsed = new Set();
+    // Family slugs a page/extras block references — the ONLY slots where a
+    // `--variant` override is consulted (inside resolveBlock). Chrome-slot slugs
+    // and slugs matching no slot are validated separately below so an override
+    // that had no effect is never silently accepted+persisted.
+    const variantTargetSlugs = new Set();
+    for (const page of selectedPages) {
+        const where = `page "${page.route}"`;
+        if (!isValidRoute(page.route)) {
+            errors.push(`${where}: invalid route (use "/" or lowercase "/a-z0-9-" / dynamic "[id]").`);
+        }
+        if (seenRoutes.has(page.route)) {
+            errors.push(`${where}: duplicate route.`);
+        }
+        seenRoutes.add(page.route);
+        if (!(page.chrome in body.chrome)) {
+            errors.push(`${where}: chrome group "${page.chrome}" is not defined in manifest.chrome.`);
+        }
+        else {
+            chromeGroupsUsed.add(page.chrome);
+        }
+        const blocks = [];
+        page.blocks.forEach((ref, i) => {
+            variantTargetSlugs.add(blockRefParts(ref).slug);
+            const resolved = resolveBlock(ref, `${where}.blocks[${i}]`);
+            if (resolved === undefined)
+                return;
+            // Semantic slot check: email never in a page; chrome only in a chrome slot.
+            if (resolved.kind === "email") {
+                errors.push(`${where}.blocks[${i}]: block "${resolved.slug}" is an email template — it cannot be a page section.`);
+            }
+            if (resolved.kind === "chrome") {
+                errors.push(`${where}.blocks[${i}]: block "${resolved.slug}" is layout chrome — it belongs in a chrome group, not a page.`);
+            }
+            blocks.push(resolved);
+        });
+        planPages.push({
+            route: page.route,
+            title: page.title,
+            ...(page.nav !== undefined ? { nav: page.nav } : {}),
+            chrome: page.chrome,
+            blocks,
+        });
+    }
+    // Dynamic-slug collisions Next.js rejects at build time, checked per chrome
+    // group (route groups are path-transparent, so sibling routes in the SAME group
+    // share a URL namespace):
+    //   1. Two routes with the same static skeleton but different dynamic-slug NAMES
+    //      → "You cannot use different slug names for the same dynamic path".
+    //   2. A single route that repeats a slug name across its dynamic segments
+    //      → "You cannot have the same slug name repeated within a single path".
+    // isValidRoute only validates each segment in isolation; seenRoutes only dedupes
+    // whole strings — neither catches these, so an otherwise-clean plan would fail
+    // `next build`. Grouped by chrome so identical routes under different groups (a
+    // real, valid layout split) are not falsely flagged.
+    const skeletonSlugByGroup = new Map();
+    for (const page of planPages) {
+        if (!isValidRoute(page.route))
+            continue; // already reported; skeleton is meaningless
+        // (2) repeated slug name within one path.
+        const dynSegs = page.route === "/" ? [] : page.route.slice(1).split("/").filter(isDynamicSegment);
+        const namesSeen = new Set();
+        for (const seg of dynSegs) {
+            const name = dynamicSlugName(seg);
+            if (namesSeen.has(name)) {
+                errors.push(`page "${page.route}": dynamic slug "[${name}]" is repeated in the same route.`);
+            }
+            namesSeen.add(name);
+        }
+        // (1) same skeleton, different slug name, within the same chrome group.
+        if (dynSegs.length === 0)
+            continue;
+        const skeleton = routeSkeleton(page.route);
+        const name = dynSegs.map(dynamicSlugName).join("/");
+        let bySkeleton = skeletonSlugByGroup.get(page.chrome);
+        if (bySkeleton === undefined) {
+            bySkeleton = new Map();
+            skeletonSlugByGroup.set(page.chrome, bySkeleton);
+        }
+        const prior = bySkeleton.get(skeleton);
+        if (prior !== undefined && prior.name !== name) {
+            errors.push(`page "${page.route}": dynamic slug name(s) differ from "${prior.route}" for the same route shape ` +
+                `— Next.js requires one slug name per dynamic path position.`);
+        }
+        else if (prior === undefined) {
+            bySkeleton.set(skeleton, { route: page.route, name });
+        }
+    }
+    // --- Chrome groups -------------------------------------------------------
+    const planChromes = [];
+    const chromeSlugsSet = new Set();
+    // Family slugs a chrome slot (navbar/footer/shell) references in a USED group,
+    // whether or not the ref resolved — chrome slots never consult `--variant`, so
+    // an override targeting one is rejected below rather than silently dropped.
+    const chromeSlotSlugs = new Set();
+    let usesNavbar = false;
+    let usesFooter = false;
+    let usesShell = false;
+    let navbarSlug;
+    let footerSlug;
+    let shellSlug;
+    // The renderer collapses the shell to SINGLE globals (one shellSlug + one
+    // AppShellNav wrapper scoped to one group). Two shell groups would both import
+    // that single wrapper and mis-render the sidebar nav of every group after the
+    // first, so only one shell group per app is supported. Count them to fail loud.
+    const shellGroups = [];
+    // Only groups actually used by an included page get a layout (sorted for stability).
+    for (const group of [...chromeGroupsUsed].sort()) {
+        const def = body.chrome[group];
+        if (def === undefined)
+            continue; // already reported above
+        const chrome = { group };
+        // Validate one chrome-block ref (navbar / footer / shell): the block must
+        // exist, have meta, and be kind "chrome". On success it records the slug in
+        // `chrome` + the shared wrapper globals. `slot` is only used for the error
+        // wording; the caller wires the resolved slug into the right field.
+        const checkChromeRef = (slug, slot) => {
+            if (!known.has(slug)) {
+                const suggestion = closestName(slug, blockNames);
+                errors.push(suggestion
+                    ? `chrome "${group}".${slot}: unknown block "${slug}". Did you mean "${suggestion}"?`
+                    : `chrome "${group}".${slot}: unknown block "${slug}".`);
+                return;
+            }
+            const m = meta.blocks[slug];
+            if (m === undefined) {
+                errors.push(`chrome "${group}".${slot}: block "${slug}" has no metadata.`);
+                return;
+            }
+            if (m.kind !== "chrome") {
+                errors.push(`chrome "${group}".${slot}: block "${slug}" is kind "${m.kind}" — only chrome blocks belong in a chrome slot.`);
+                return;
+            }
+            chromeSlugsSet.add(slug);
+            if (slot === "navbar") {
+                chrome.navbar = slug;
+                usesNavbar = true;
+                navbarSlug = slug;
+            }
+            else if (slot === "footer") {
+                chrome.footer = slug;
+                usesFooter = true;
+                footerSlug = slug;
+            }
+            else {
+                chrome.block = slug;
+                usesShell = true;
+                shellSlug = slug;
+            }
+        };
+        if (def.navbar !== undefined) {
+            chromeSlotSlugs.add(def.navbar);
+            checkChromeRef(def.navbar, "navbar");
+        }
+        if (def.footer !== undefined) {
+            chromeSlotSlugs.add(def.footer);
+            checkChromeRef(def.footer, "footer");
+        }
+        // The app-shell chrome block (sidebar shell): the (app)-group layout wraps
+        // {children} in it, exactly as (site) wraps SiteNav/SiteFooter. Mixing a
+        // shell with navbar/footer in one group is a design error — a shell IS the
+        // full page frame — so reject that combination up front.
+        if (def.block !== undefined) {
+            if (def.navbar !== undefined || def.footer !== undefined) {
+                errors.push(`chrome "${group}": a shell "block" cannot be combined with navbar/footer in the same group.`);
+            }
+            shellGroups.push(group);
+            chromeSlotSlugs.add(def.block);
+            checkChromeRef(def.block, "block");
+        }
+        planChromes.push(chrome);
+    }
+    // Only ONE shell group per app is supported: the renderer emits a single
+    // AppShellNav wrapper backed by one block copy scoped to one group, so a
+    // second shell group would silently render the first group's sidebar nav.
+    // Fail loud, mirroring the shell+navbar/footer guard above.
+    if (shellGroups.length > 1) {
+        const [, ...extras] = shellGroups;
+        for (const group of extras) {
+            errors.push(`chrome "${group}": only one shell "block" group is supported per app ` +
+                `(already used by "${shellGroups[0]}").`);
+        }
+    }
+    // --- Chrome sources + meta lookups (for the renderer) --------------------
+    const resolvedChromeSources = {};
+    const dataSlotsBySlug = {};
+    const brandTokensBySlug = {};
+    for (const slug of [...chromeSlugsSet].sort()) {
+        const source = chromeSources[slug];
+        if (source === undefined) {
+            errors.push(`chrome block "${slug}": shipped source is unavailable (registry read failed).`);
+        }
+        else {
+            resolvedChromeSources[slug] = source;
+        }
+        const m = meta.blocks[slug];
+        if (m !== undefined) {
+            dataSlotsBySlug[slug] = [...m.dataSlots];
+            brandTokensBySlug[slug] = m.brandTokens.map((b) => ({ ...b }));
+        }
+    }
+    // --- Extras (Next special-file blocks, e.g. not-found → app/not-found.tsx) ---
+    // Resolve each declared extras block the same way page blocks are, then require
+    // it to be a page-kind block (special files are full-page surfaces) and map its
+    // KEY to a supported Next special-file path. Resolved extras are installed and
+    // wrapped by the renderer under the golden rule. Sorted by key for determinism.
+    const planExtras = [];
+    const extras = body.extras ?? {};
+    for (const key of Object.keys(extras).sort()) {
+        const slug = extras[key];
+        if (slug === undefined)
+            continue; // never happens (own key); satisfies the checker
+        const where = `extras."${key}"`;
+        const file = EXTRAS_SPECIAL_FILES[key];
+        if (file === undefined) {
+            const suggestion = closestName(key, Object.keys(EXTRAS_SPECIAL_FILES));
+            errors.push(suggestion
+                ? `${where}: unsupported special file "${key}". Did you mean "${suggestion}"?`
+                : `${where}: unsupported special file "${key}" (supported: ${Object.keys(EXTRAS_SPECIAL_FILES).join(", ")}).`);
+            continue;
+        }
+        variantTargetSlugs.add(blockRefParts(slug).slug);
+        const resolved = resolveBlock(slug, where);
+        if (resolved === undefined)
+            continue; // resolveBlock already pushed the error
+        if (resolved.kind !== "page") {
+            errors.push(`${where}: block "${resolved.slug}" is kind "${resolved.kind}" — a Next special file needs a page-kind block.`);
+            continue;
+        }
+        planExtras.push({ key, file, slug: resolved.slug, exportName: resolved.exportName });
+    }
+    // --- Variant-override targets --------------------------------------------
+    // A `--variant slug=id` override is consulted ONLY inside resolveBlock, i.e.
+    // only for a family slug some included page/extras block references. If the
+    // slug is a chrome-slot slug (navbar/footer/shell), the override is silently
+    // ignored (chrome variants are out of F2 scope); if it matches no slot at all
+    // (typo / dead / nonexistent slug), it is silently ignored too. Either way the
+    // override is still persisted into choices.variants, producing a record that
+    // does not match the generated app. Cross-check every override key here so an
+    // override that had no effect fails loud instead — mirroring the clear
+    // did-you-mean error a page-block variant typo already gets.
+    for (const slug of Object.keys(variantOverrides).sort()) {
+        if (variantTargetSlugs.has(slug))
+            continue; // applied by a page/extras block
+        if (chromeSlotSlugs.has(slug)) {
+            errors.push(`--variant "${slug}": chrome slots (navbar/footer/shell) do not accept --variant.`);
+            continue;
+        }
+        const suggestion = closestName(slug, [...variantTargetSlugs]);
+        errors.push(suggestion
+            ? `--variant "${slug}": no included page/extras block uses block "${slug}". Did you mean "${suggestion}"?`
+            : `--variant "${slug}": no included page/extras block uses block "${slug}".`);
+    }
+    // --- Dependencies (arg-injection guard reuse) ----------------------------
+    // Collect the registry ITEM names to install (a non-default variant contributes
+    // its `<slug>--<variant>` item, not the bare slug), so resolve/install and the
+    // arg-injection guard both run over exactly what lands on disk. Chrome + extras
+    // are bare items (no variants in those slots in F2).
+    const allBlockItems = new Set();
+    for (const page of planPages)
+        for (const b of page.blocks)
+            allBlockItems.add(b.item);
+    for (const slug of chromeSlugsSet)
+        allBlockItems.add(slug);
+    for (const extra of planExtras)
+        allBlockItems.add(extra.slug);
+    for (const entry of index) {
+        if (!allBlockItems.has(entry.name))
+            continue;
+        for (const dep of entry.dependencies) {
+            try {
+                assertValidDependency(dep);
+            }
+            catch (err) {
+                errors.push(`block "${entry.name}": ${err.message}`);
+            }
+        }
+    }
+    const navbarMeta = navbarSlug !== undefined ? meta.blocks[navbarSlug] : undefined;
+    const footerMeta = footerSlug !== undefined ? meta.blocks[footerSlug] : undefined;
+    const shellMeta = shellSlug !== undefined ? meta.blocks[shellSlug] : undefined;
+    const plan = {
+        templateName: manifest.name,
+        appName,
+        planVersion: manifest.planVersion,
+        title: body.title,
+        description: body.description,
+        choices: normalizeChoices(manifest, input, planPages),
+        pages: planPages,
+        chromes: planChromes,
+        extras: planExtras,
+        blockSlugs: [...allBlockItems].sort(),
+        chromeSlugs: [...chromeSlugsSet].sort(),
+        chromeSources: resolvedChromeSources,
+        dataSlotsBySlug,
+        brandTokensBySlug,
+        usesNavbar,
+        usesFooter,
+        usesShell,
+        ...(navbarSlug !== undefined ? { navbarSlug } : {}),
+        ...(footerSlug !== undefined ? { footerSlug } : {}),
+        ...(shellSlug !== undefined ? { shellSlug } : {}),
+        ...(navbarMeta !== undefined ? { navbarExportName: navbarMeta.exportName } : {}),
+        ...(footerMeta !== undefined ? { footerExportName: footerMeta.exportName } : {}),
+        ...(shellMeta !== undefined ? { shellExportName: shellMeta.exportName } : {}),
+    };
+    if (errors.length > 0)
+        throw new ComposePlanError(errors);
+    return plan;
+}
+/**
+ * Validate-only entry point: builds the plan and returns the aggregated error
+ * list (empty when valid) instead of throwing. Handy for `--dry-run` callers and
+ * tests that assert on the full error set. The successful plan is returned too.
+ */
+export function validateComposePlan(manifest, input, index, meta, chromeSources) {
+    try {
+        const plan = buildComposePlan(manifest, input, index, meta, chromeSources);
+        return { plan, errors: [] };
+    }
+    catch (err) {
+        if (err instanceof ComposePlanError)
+            return { errors: err.errors };
+        throw err;
+    }
+}
+//# sourceMappingURL=plan.js.map

package/dist/compose/preview.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Deterministic textual preview of a compose plan (the `--dry-run` human view):
+ * a sitemap tree, the block stack + chrome per page, the nav labels, and the
+ * theme/brand. Pure — a function of the plan only, no I/O/Date — so it reads the
+ * same every run and can be snapshot-tested.
+ */
+import type { ComposePlan } from "./plan.js";
+/** Render the plan to a multi-line preview string (no trailing newline). */
+export declare function renderPreview(plan: ComposePlan): string;
+//# sourceMappingURL=preview.d.ts.map

package/dist/compose/preview.js

@@ -0,0 +1,48 @@
+/**
+ * Deterministic textual preview of a compose plan (the `--dry-run` human view):
+ * a sitemap tree, the block stack + chrome per page, the nav labels, and the
+ * theme/brand. Pure — a function of the plan only, no I/O/Date — so it reads the
+ * same every run and can be snapshot-tested.
+ */
+/** Render the plan to a multi-line preview string (no trailing newline). */
+export function renderPreview(plan) {
+    const lines = [];
+    lines.push(`App: ${plan.title} (${plan.appName})`);
+    if (plan.description.length > 0)
+        lines.push(`  ${plan.description}`);
+    lines.push(`Brand: ${plan.choices.brand}`);
+    if (plan.choices.seed !== undefined)
+        lines.push(`Seed: ${plan.choices.seed}`);
+    // Chrome groups.
+    lines.push("");
+    lines.push("Chrome:");
+    for (const chrome of plan.chromes) {
+        const parts = [];
+        if (chrome.navbar !== undefined)
+            parts.push(`navbar=${chrome.navbar}`);
+        if (chrome.footer !== undefined)
+            parts.push(`footer=${chrome.footer}`);
+        if (chrome.block !== undefined)
+            parts.push(`shell=${chrome.block}`);
+        lines.push(`  (${chrome.group}) ${parts.length > 0 ? parts.join(" ") : "bare"}`);
+    }
+    // Sitemap: one entry per page, with its block stack.
+    lines.push("");
+    lines.push("Pages:");
+    for (const page of plan.pages) {
+        const navMark = page.nav !== undefined ? ` [nav: ${page.nav}]` : "";
+        lines.push(`  ${page.route}  "${page.title}"  (${page.chrome})${navMark}`);
+        for (const block of page.blocks) {
+            const variantMark = block.variant !== undefined ? ` (variant: ${block.variant})` : "";
+            lines.push(`    - ${block.slug}${variantMark} <${block.exportName}> (${block.kind})`);
+        }
+    }
+    // Nav labels (in order).
+    const navLabels = plan.pages
+        .filter((p) => p.nav !== undefined)
+        .map((p) => `${p.nav} → ${p.route}`);
+    lines.push("");
+    lines.push(`Nav: ${navLabels.length > 0 ? navLabels.join(", ") : "(none)"}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=preview.js.map

package/dist/compose/reload.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Compose reload + base-snapshot helpers shared by add-page and upgrade.
+ *
+ * Snapshots live at `.cronus-ui/base/<composedKey>/` (the `composed{}` key =
+ * template name). Pre-F4 compose wrote them under the package.json name
+ * (`plan.appName`); readers fall back to that dir when the composed-key dir
+ * (or a given file in it) is missing. New writes always use the composed key.
+ */
+import type { ComposedRecord } from "../config.js";
+import { type AppManifest } from "./manifest.js";
+/** Base-snapshot directory for an app's generated bytes (F4 merge base). */
+export declare function baseSnapshotDir(appKey: string): string;
+/**
+ * Absolute dest of a snapshot file for a NEW write. Always the composed key —
+ * never the legacy package-name dir.
+ */
+export declare function baseSnapshotDest(cwd: string, composedKey: string, relPath: string): string;
+/**
+ * Read one snapshot file. Prefers `.cronus-ui/base/<composedKey>/<rel>`; if that
+ * file is missing, falls back to `.cronus-ui/base/<appName>/<rel>` (legacy
+ * compose). Returns undefined when neither exists.
+ */
+export declare function readBaseSnapshot(cwd: string, composedKey: string, appName: string, relPath: string): Promise<string | undefined>;
+/**
+ * Rel paths present in the snapshot tree(s). Unions the composed-key dir with
+ * the legacy appName dir when both exist, so a mixed pre/post-fix project
+ * still sees every snapshotted file.
+ */
+export declare function listBaseSnapshotRels(cwd: string, composedKey: string, appName: string): Promise<string[]>;
+/**
+ * Reload the app's manifest: an explicit `--manifest` file wins, else the bundled
+ * template whose name equals the composed key. A `--manifest`-composed app whose
+ * name is not a bundled template must re-supply `--manifest` (its manifest is not
+ * recoverable from `composed{}` alone) — we fail loud with that hint.
+ *
+ * PROVENANCE GUARD: the bundled fallback is keyed only on the app NAME, but a
+ * `--manifest`-composed app is keyed by the manifest's own `name` field, which can
+ * COLLIDE with a bundled template name (store/landing/saas). In that case
+ * `loadTemplate` silently returns the WRONG (bundled) manifest, and a re-plan
+ * would then drop every composed route/chrome group that the bundled template does
+ * not declare — silently corrupting the nav + composed record. So we verify the
+ * reloaded bundled template's content fingerprint against the compose-time
+ * `manifestHash` provenance recorded in `composed{}` and fail loud on a mismatch,
+ * demanding `--manifest`. A legacy record (composed before provenance existed) has
+ * no hash to check, so that case falls back to the prior lenient behavior.
+ */
+export declare function reloadManifest(appName: string, manifestPath: string | undefined, composed: ComposedRecord): Promise<AppManifest>;
+/**
+ * Restrict a reloaded manifest to the pages this app actually composed
+ * (`composed.choices.pages`, preserving manifest order). Add-page grafts that
+ * are not in the bundled/reloaded template are omitted from the synthetic
+ * manifest (they have no upstream render) — callers must keep them in
+ * `choices.pages` and on disk.
+ */
+export declare function filterManifestToComposedPages(base: AppManifest, composed: ComposedRecord): AppManifest;
+//# sourceMappingURL=reload.d.ts.map