cronus-ui 0.6.0

package/dist/compose/data-slots.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Anchored replacement of a block's `@cronus:data <name>` data const and its brand
+ * literal. Both mechanisms are marker/literal driven and FAIL LOUD when the anchor
+ * is absent — the composer must never silently target a missing slot or brand
+ * (the same guarantee `registry:check` enforces at build time, re-checked here
+ * against the bytes actually on disk).
+ *
+ * The data-slot replacement operates on DATA CONSTS ONLY (never JSX): the region
+ * between `/* @cronus:data X *\/` and the FIRST following `/* @cronus:data-end *\/`
+ * is replaced wholesale with a freshly-serialized const, keeping the markers so a
+ * re-compose stays idempotent. The brand replacement, by contrast, targets JSX
+ * TEXT (the chrome wordmark/copyright), so its injected value is JSX-escaped —
+ * source-side literal matching alone does NOT make the destination context safe.
+ */
+/** The exact marker pair for a named data-slot (mirrors build-registry's `dataSlotMarkers`). */
+export declare function dataSlotMarkers(name: string): {
+    open: string;
+    close: string;
+};
+/** Thrown when a required data-slot marker or brand literal is missing from a source. */
+export declare class DataSlotError extends Error {
+    constructor(message: string);
+}
+/**
+ * Replace the body delimited by a named data-slot's markers with `replacement`
+ * (the full const declaration, e.g. `const NAVBAR_LINKS = [...];`). The markers
+ * themselves are preserved so the result stays re-composable. Throws
+ * {@link DataSlotError} when the opening marker is absent or ambiguous (appears
+ * more than once), or when no closing marker follows it — never a silent no-op.
+ *
+ * The close marker is GENERIC (`/* @cronus:data-end *\/`) and shared by every slot,
+ * so a block with two data-slots carries two close markers. We therefore pair the
+ * open marker with the FIRST close marker that follows it (its own region end),
+ * rather than rejecting any source in which the shared close marker repeats. This
+ * is deterministic and unambiguous because slot regions are flat siblings (never
+ * nested), so the first `data-end` after an `@cronus:data <name>` open always
+ * belongs to that same slot. The only ambiguity we still reject is a duplicated
+ * OPEN marker for this named slot (we would not know which region to rewrite).
+ *
+ * `source` — the on-disk block copy; `name` — the slot id; `replacement` — the
+ * new const source (no surrounding markers/newlines; they are re-added).
+ */
+export declare function replaceDataSlot(source: string, name: string, replacement: string): string;
+/**
+ * JSX-escape a value destined for a JSX **text** context (element children). The
+ * chrome brand literal (`Cronus`) lives inside JSX text nodes — the navbar/footer
+ * wordmark `<span>…</span>` and the footer copyright `<p>…</p>` — so a raw
+ * substitution of a brand containing `<`, `>`, `{` or `}` would emit invalid TSX
+ * (`<`/`>` are token starts) or an undefined JSX expression container (`{Store}`),
+ * breaking `next build`. Escaping here makes ANY brand safe regardless of source,
+ * which is stronger than validate-and-reject. `&` is escaped first so we never
+ * double-escape the entities we introduce. A brand with none of these characters
+ * is returned unchanged (no-op for safe brands like `Acme`).
+ */
+export declare function escapeJsxText(value: string): string;
+/**
+ * Replace EVERY occurrence of a brand `literal` in the source with `brand`. Used
+ * for the chrome wordmark/copyright (`Cronus` → the app brand), which sit in JSX
+ * text nodes. Throws {@link DataSlotError} when the literal is absent so a
+ * renamed/removed anchor fails loud instead of leaving the placeholder brand.
+ *
+ * The `literal` MATCH is literal (not regex), so special characters in the search
+ * literal do not misbehave. The injected `brand`, however, lands in a JSX text
+ * context, so it is JSX-escaped ({@link escapeJsxText}) before substitution —
+ * otherwise a brand like `Tom > Jerry`, `Ben <Labs>`, `Acme {Store}` or `A & B`
+ * would emit invalid TSX / an undefined JSX expression and break `next build`.
+ * Escaping is a no-op for brands with no `& < > { }`, so safe brands are
+ * byte-identical to a raw substitution.
+ */
+export declare function replaceBrandLiteral(source: string, literal: string, brand: string): string;
+//# sourceMappingURL=data-slots.d.ts.map

package/dist/compose/data-slots.js

@@ -0,0 +1,104 @@
+/**
+ * Anchored replacement of a block's `@cronus:data <name>` data const and its brand
+ * literal. Both mechanisms are marker/literal driven and FAIL LOUD when the anchor
+ * is absent — the composer must never silently target a missing slot or brand
+ * (the same guarantee `registry:check` enforces at build time, re-checked here
+ * against the bytes actually on disk).
+ *
+ * The data-slot replacement operates on DATA CONSTS ONLY (never JSX): the region
+ * between `/* @cronus:data X *\/` and the FIRST following `/* @cronus:data-end *\/`
+ * is replaced wholesale with a freshly-serialized const, keeping the markers so a
+ * re-compose stays idempotent. The brand replacement, by contrast, targets JSX
+ * TEXT (the chrome wordmark/copyright), so its injected value is JSX-escaped —
+ * source-side literal matching alone does NOT make the destination context safe.
+ */
+/** The exact marker pair for a named data-slot (mirrors build-registry's `dataSlotMarkers`). */
+export function dataSlotMarkers(name) {
+    return { open: `/* @cronus:data ${name} */`, close: "/* @cronus:data-end */" };
+}
+/** Thrown when a required data-slot marker or brand literal is missing from a source. */
+export class DataSlotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DataSlotError";
+    }
+}
+/**
+ * Replace the body delimited by a named data-slot's markers with `replacement`
+ * (the full const declaration, e.g. `const NAVBAR_LINKS = [...];`). The markers
+ * themselves are preserved so the result stays re-composable. Throws
+ * {@link DataSlotError} when the opening marker is absent or ambiguous (appears
+ * more than once), or when no closing marker follows it — never a silent no-op.
+ *
+ * The close marker is GENERIC (`/* @cronus:data-end *\/`) and shared by every slot,
+ * so a block with two data-slots carries two close markers. We therefore pair the
+ * open marker with the FIRST close marker that follows it (its own region end),
+ * rather than rejecting any source in which the shared close marker repeats. This
+ * is deterministic and unambiguous because slot regions are flat siblings (never
+ * nested), so the first `data-end` after an `@cronus:data <name>` open always
+ * belongs to that same slot. The only ambiguity we still reject is a duplicated
+ * OPEN marker for this named slot (we would not know which region to rewrite).
+ *
+ * `source` — the on-disk block copy; `name` — the slot id; `replacement` — the
+ * new const source (no surrounding markers/newlines; they are re-added).
+ */
+export function replaceDataSlot(source, name, replacement) {
+    const { open, close } = dataSlotMarkers(name);
+    const openAt = source.indexOf(open);
+    if (openAt === -1) {
+        throw new DataSlotError(`data-slot "${name}": opening marker \`${open}\` not found in source`);
+    }
+    if (source.indexOf(open, openAt + open.length) !== -1) {
+        throw new DataSlotError(`data-slot "${name}": opening marker \`${open}\` appears more than once`);
+    }
+    // Pair with the FIRST close marker after this slot's open marker — that is this
+    // slot's region end. Other slots' close markers appearing later in the source
+    // are irrelevant (they close their own regions), so we do NOT reject them.
+    const closeAt = source.indexOf(close, openAt + open.length);
+    if (closeAt === -1) {
+        throw new DataSlotError(`data-slot "${name}": closing marker \`${close}\` not found after the opening marker`);
+    }
+    const before = source.slice(0, openAt);
+    const after = source.slice(closeAt + close.length);
+    return `${before}${open}\n${replacement}\n${close}${after}`;
+}
+/**
+ * JSX-escape a value destined for a JSX **text** context (element children). The
+ * chrome brand literal (`Cronus`) lives inside JSX text nodes — the navbar/footer
+ * wordmark `<span>…</span>` and the footer copyright `<p>…</p>` — so a raw
+ * substitution of a brand containing `<`, `>`, `{` or `}` would emit invalid TSX
+ * (`<`/`>` are token starts) or an undefined JSX expression container (`{Store}`),
+ * breaking `next build`. Escaping here makes ANY brand safe regardless of source,
+ * which is stronger than validate-and-reject. `&` is escaped first so we never
+ * double-escape the entities we introduce. A brand with none of these characters
+ * is returned unchanged (no-op for safe brands like `Acme`).
+ */
+export function escapeJsxText(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/\{/g, "&#123;")
+        .replace(/\}/g, "&#125;");
+}
+/**
+ * Replace EVERY occurrence of a brand `literal` in the source with `brand`. Used
+ * for the chrome wordmark/copyright (`Cronus` → the app brand), which sit in JSX
+ * text nodes. Throws {@link DataSlotError} when the literal is absent so a
+ * renamed/removed anchor fails loud instead of leaving the placeholder brand.
+ *
+ * The `literal` MATCH is literal (not regex), so special characters in the search
+ * literal do not misbehave. The injected `brand`, however, lands in a JSX text
+ * context, so it is JSX-escaped ({@link escapeJsxText}) before substitution —
+ * otherwise a brand like `Tom > Jerry`, `Ben <Labs>`, `Acme {Store}` or `A & B`
+ * would emit invalid TSX / an undefined JSX expression and break `next build`.
+ * Escaping is a no-op for brands with no `& < > { }`, so safe brands are
+ * byte-identical to a raw substitution.
+ */
+export function replaceBrandLiteral(source, literal, brand) {
+    if (!source.includes(literal)) {
+        throw new DataSlotError(`brand literal "${literal}" not found in source`);
+    }
+    return source.split(literal).join(escapeJsxText(brand));
+}
+//# sourceMappingURL=data-slots.js.map

package/dist/compose/manifest.d.ts

@@ -0,0 +1,90 @@
+/**
+ * App-manifest types + a strict, hand-rolled structural parser/validator (no new
+ * dep). The parser is deliberately paranoid: manifests arrive from disk (bundled
+ * template or `--manifest` file) and drive code generation, so an unknown
+ * `planVersion` or any unknown field is a HARD ERROR (D3 graft) rather than a
+ * silently-ignored typo. Only structural/shape checks live here — semantic checks
+ * that need the registry index/meta (does the block exist? does its kind fit the
+ * slot?) live in `plan.ts`.
+ */
+/** The only plan schema version F1 understands. Unknown values are rejected. */
+export declare const SUPPORTED_PLAN_VERSION = 1;
+/** A block reference in a page: a bare slug (default variant) or `{ block, variant }`. */
+export type BlockRef = string | {
+    block: string;
+    variant?: string;
+};
+/** One route in the app. `nav` presence lists it in the generated navbar/footer. */
+export interface Page {
+    /** App Router route, e.g. "/", "/products", "/products/[id]". */
+    route: string;
+    /** <title> metadata for the page. */
+    title: string;
+    /** Label shown in the nav; omit to keep the page out of the nav. */
+    nav?: string;
+    /** Which chrome group the page renders under (key of `chrome`). */
+    chrome: string;
+    /** The blocks stacked (top-to-bottom) inside the page's <main>. */
+    blocks: BlockRef[];
+}
+/** One chrome group → the route group + its layout furniture. F1 supports site/bare. */
+export interface ChromeGroup {
+    /** Navbar block slug (chrome kind). Omit for a bare/centered group. */
+    navbar?: string;
+    /** Footer block slug (chrome kind). Omit for a bare/centered group. */
+    footer?: string;
+    /** App-shell block slug (F2 sidebar shell). Present in the type; unused in F1. */
+    block?: string;
+}
+export type ChromeMap = Record<string, ChromeGroup>;
+/** App-level defaults baked into the generated app. */
+export interface ManifestDefaults {
+    theme?: string;
+    mode?: string;
+    /** Brand wordmark; `__APP_NAME__` is substituted with the project name. */
+    brand?: string;
+}
+/** The manifest body (everything under the top-level `manifest` key). */
+export interface ManifestBody {
+    title: string;
+    description: string;
+    chrome: ChromeMap;
+    pages: Page[];
+    /** Next special-file blocks by kind, e.g. `{ "not-found": "not-found" }`. */
+    extras?: Record<string, string>;
+    defaults?: ManifestDefaults;
+}
+/** A full app-template manifest as stored in `packages/cli/templates/apps/*.json`. */
+export interface AppManifest {
+    name: string;
+    type: "registry:app";
+    planVersion: number;
+    manifest: ManifestBody;
+}
+/** Thrown by {@link parseManifest} with EVERY structural problem found, aggregated. */
+export declare class ManifestError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Parse + strictly validate a raw (JSON-parsed) manifest value into a typed
+ * {@link AppManifest}. Aggregates ALL structural problems and throws a single
+ * {@link ManifestError} listing them (never on the first). Rejects an unknown
+ * `planVersion` and any unknown field at every level (strict D3 graft) so a
+ * template typo can never be silently ignored by the generator.
+ */
+export declare function parseManifest(raw: unknown): AppManifest;
+/** Normalize a block reference to its `{ slug, variant }` parts (default variant = undefined). */
+export declare function blockRefParts(ref: BlockRef): {
+    slug: string;
+    variant?: string;
+};
+/**
+ * A deterministic content fingerprint of a parsed manifest, used as compose
+ * provenance persisted in `composed{}.manifestHash`. Keyed on the manifest's
+ * meaningful shape (name + planVersion + body) via canonical sorted-key JSON, so
+ * two manifests fingerprint equal iff they describe the same app — independent of
+ * source key order or whitespace. Pure (no Date/random) so it stays byte-stable.
+ */
+export declare function manifestFingerprint(manifest: AppManifest): string;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/compose/manifest.js

@@ -0,0 +1,224 @@
+/**
+ * App-manifest types + a strict, hand-rolled structural parser/validator (no new
+ * dep). The parser is deliberately paranoid: manifests arrive from disk (bundled
+ * template or `--manifest` file) and drive code generation, so an unknown
+ * `planVersion` or any unknown field is a HARD ERROR (D3 graft) rather than a
+ * silently-ignored typo. Only structural/shape checks live here — semantic checks
+ * that need the registry index/meta (does the block exist? does its kind fit the
+ * slot?) live in `plan.ts`.
+ */
+import { createHash } from "node:crypto";
+/** The only plan schema version F1 understands. Unknown values are rejected. */
+export const SUPPORTED_PLAN_VERSION = 1;
+/** Thrown by {@link parseManifest} with EVERY structural problem found, aggregated. */
+export class ManifestError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Invalid app manifest:\n${errors.map((e) => `  - ${e}`).join("\n")}`);
+        this.name = "ManifestError";
+        this.errors = errors;
+    }
+}
+/** True for a plain (non-array, non-null) object. */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Push an "unknown field" error for every key of `obj` not in `allowed`. */
+function rejectUnknownKeys(obj, allowed, where, errors) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.includes(key)) {
+            errors.push(`${where}: unknown field "${key}" (allowed: ${allowed.join(", ")})`);
+        }
+    }
+}
+const MANIFEST_TOP_KEYS = ["name", "type", "planVersion", "manifest"];
+const MANIFEST_BODY_KEYS = [
+    "title",
+    "description",
+    "chrome",
+    "pages",
+    "extras",
+    "defaults",
+];
+const PAGE_KEYS = ["route", "title", "nav", "chrome", "blocks"];
+const CHROME_GROUP_KEYS = ["navbar", "footer", "block"];
+const DEFAULTS_KEYS = ["theme", "mode", "brand"];
+const BLOCKREF_KEYS = ["block", "variant"];
+function validateBlockRef(value, where, errors) {
+    if (typeof value === "string") {
+        if (value.length === 0)
+            errors.push(`${where}: block reference is an empty string`);
+        return;
+    }
+    if (!isRecord(value)) {
+        errors.push(`${where}: block reference must be a string or { block, variant }`);
+        return;
+    }
+    rejectUnknownKeys(value, BLOCKREF_KEYS, where, errors);
+    if (typeof value.block !== "string" || value.block.length === 0) {
+        errors.push(`${where}: block reference object needs a non-empty "block" string`);
+    }
+    if (value.variant !== undefined && typeof value.variant !== "string") {
+        errors.push(`${where}: block "variant" must be a string when present`);
+    }
+}
+function validateChromeGroup(value, where, errors) {
+    if (!isRecord(value)) {
+        errors.push(`${where}: chrome group must be an object`);
+        return;
+    }
+    rejectUnknownKeys(value, CHROME_GROUP_KEYS, where, errors);
+    for (const key of ["navbar", "footer", "block"]) {
+        if (value[key] !== undefined && typeof value[key] !== "string") {
+            errors.push(`${where}: "${key}" must be a string when present`);
+        }
+    }
+}
+function validatePage(value, index, errors) {
+    const where = `pages[${index}]`;
+    if (!isRecord(value)) {
+        errors.push(`${where}: page must be an object`);
+        return;
+    }
+    rejectUnknownKeys(value, PAGE_KEYS, where, errors);
+    if (typeof value.route !== "string" || value.route.length === 0) {
+        errors.push(`${where}: "route" must be a non-empty string`);
+    }
+    if (typeof value.title !== "string" || value.title.length === 0) {
+        errors.push(`${where}: "title" must be a non-empty string`);
+    }
+    if (value.nav !== undefined && (typeof value.nav !== "string" || value.nav.length === 0)) {
+        errors.push(`${where}: "nav" must be a non-empty string when present`);
+    }
+    if (typeof value.chrome !== "string" || value.chrome.length === 0) {
+        errors.push(`${where}: "chrome" must be a non-empty string`);
+    }
+    if (!Array.isArray(value.blocks) || value.blocks.length === 0) {
+        errors.push(`${where}: "blocks" must be a non-empty array`);
+    }
+    else {
+        value.blocks.forEach((b, i) => {
+            validateBlockRef(b, `${where}.blocks[${i}]`, errors);
+        });
+    }
+}
+function validateBody(value, errors) {
+    if (!isRecord(value)) {
+        errors.push(`"manifest" must be an object`);
+        return;
+    }
+    rejectUnknownKeys(value, MANIFEST_BODY_KEYS, "manifest", errors);
+    if (typeof value.title !== "string" || value.title.length === 0) {
+        errors.push(`manifest.title must be a non-empty string`);
+    }
+    if (typeof value.description !== "string") {
+        errors.push(`manifest.description must be a string`);
+    }
+    if (!isRecord(value.chrome)) {
+        errors.push(`manifest.chrome must be an object`);
+    }
+    else {
+        for (const [key, group] of Object.entries(value.chrome)) {
+            validateChromeGroup(group, `manifest.chrome.${key}`, errors);
+        }
+    }
+    if (!Array.isArray(value.pages) || value.pages.length === 0) {
+        errors.push(`manifest.pages must be a non-empty array`);
+    }
+    else {
+        value.pages.forEach((p, i) => {
+            validatePage(p, i, errors);
+        });
+    }
+    if (value.extras !== undefined) {
+        if (!isRecord(value.extras)) {
+            errors.push(`manifest.extras must be an object when present`);
+        }
+        else {
+            for (const [key, slug] of Object.entries(value.extras)) {
+                if (typeof slug !== "string" || slug.length === 0) {
+                    errors.push(`manifest.extras.${key} must be a non-empty string`);
+                }
+            }
+        }
+    }
+    if (value.defaults !== undefined) {
+        if (!isRecord(value.defaults)) {
+            errors.push(`manifest.defaults must be an object when present`);
+        }
+        else {
+            rejectUnknownKeys(value.defaults, DEFAULTS_KEYS, "manifest.defaults", errors);
+            for (const key of DEFAULTS_KEYS) {
+                if (value.defaults[key] !== undefined && typeof value.defaults[key] !== "string") {
+                    errors.push(`manifest.defaults.${key} must be a string when present`);
+                }
+            }
+        }
+    }
+}
+/**
+ * Parse + strictly validate a raw (JSON-parsed) manifest value into a typed
+ * {@link AppManifest}. Aggregates ALL structural problems and throws a single
+ * {@link ManifestError} listing them (never on the first). Rejects an unknown
+ * `planVersion` and any unknown field at every level (strict D3 graft) so a
+ * template typo can never be silently ignored by the generator.
+ */
+export function parseManifest(raw) {
+    const errors = [];
+    if (!isRecord(raw)) {
+        throw new ManifestError(["manifest must be a JSON object"]);
+    }
+    rejectUnknownKeys(raw, MANIFEST_TOP_KEYS, "manifest root", errors);
+    if (typeof raw.name !== "string" || raw.name.length === 0) {
+        errors.push(`"name" must be a non-empty string`);
+    }
+    if (raw.type !== "registry:app") {
+        errors.push(`"type" must be "registry:app"`);
+    }
+    if (raw.planVersion !== SUPPORTED_PLAN_VERSION) {
+        errors.push(`unsupported "planVersion" ${JSON.stringify(raw.planVersion)} — ` +
+            `this CLI only understands planVersion ${SUPPORTED_PLAN_VERSION}.`);
+    }
+    validateBody(raw.manifest, errors);
+    if (errors.length > 0)
+        throw new ManifestError(errors);
+    // Every branch above is proven; the cast is safe.
+    return raw;
+}
+/** Normalize a block reference to its `{ slug, variant }` parts (default variant = undefined). */
+export function blockRefParts(ref) {
+    if (typeof ref === "string")
+        return { slug: ref };
+    return ref.variant !== undefined
+        ? { slug: ref.block, variant: ref.variant }
+        : { slug: ref.block };
+}
+/** Canonical (sorted-key) JSON of a value — deterministic regardless of key order. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const obj = value;
+    const entries = Object.keys(obj)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`);
+    return `{${entries.join(",")}}`;
+}
+/**
+ * A deterministic content fingerprint of a parsed manifest, used as compose
+ * provenance persisted in `composed{}.manifestHash`. Keyed on the manifest's
+ * meaningful shape (name + planVersion + body) via canonical sorted-key JSON, so
+ * two manifests fingerprint equal iff they describe the same app — independent of
+ * source key order or whitespace. Pure (no Date/random) so it stays byte-stable.
+ */
+export function manifestFingerprint(manifest) {
+    const canonical = canonicalJson({
+        name: manifest.name,
+        type: manifest.type,
+        planVersion: manifest.planVersion,
+        manifest: manifest.manifest,
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+//# sourceMappingURL=manifest.js.map

package/dist/compose/plan.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 type { ComposedChoices } from "../config.js";
+import type { RegistryIndex } from "../registry.js";
+import { type AppManifest } from "./manifest.js";
+/** Semantic kind of a block (mirrors build-registry's BlockKind, read from meta). */
+export type BlockKind = "page" | "section" | "chrome" | "email";
+/** A brand-token anchor as recorded in meta. */
+export interface BrandToken {
+    token: string;
+    literal: string;
+}
+/**
+ * A block variant as recorded in meta: its id + the registry `item` the composer
+ * installs (bare `<slug>` for the default, `<slug>--<id>` otherwise) + the
+ * component `exportName` a generated page imports.
+ */
+export interface VariantMetaRef {
+    id: string;
+    item: string;
+    exportName: string;
+}
+/** The subset of `registry/meta.json` the planner reads. */
+export interface ComposeMetaBlock {
+    exportName: string;
+    kind: BlockKind;
+    dataSlots: string[];
+    brandTokens: BrandToken[];
+    /** Declared variants (default first); empty when the block has none. */
+    variants?: VariantMetaRef[];
+}
+export interface ComposeMeta {
+    blocks: Record<string, ComposeMetaBlock>;
+}
+/**
+ * A resolved block inside a page: its family slug, the registry `item` name to
+ * install (bare `<slug>`, or `<slug>--<variant>` for a non-default variant), the
+ * `exportName` a generated page imports, the block kind, and the selected
+ * `variant` id when a non-default variant was chosen (absent for the default).
+ */
+export interface PlanBlock {
+    slug: string;
+    /** Registry item name to install/import from (`<slug>` or `<slug>--<variant>`). */
+    item: string;
+    exportName: string;
+    kind: BlockKind;
+    /** Selected non-default variant id (absent = default variant). */
+    variant?: string;
+}
+/** A resolved page ready to render. */
+export interface PlanPage {
+    route: string;
+    title: string;
+    nav?: string;
+    chrome: string;
+    blocks: PlanBlock[];
+}
+/** A resolved chrome group (route group + its navbar/footer/shell slugs). */
+export interface PlanChrome {
+    group: string;
+    navbar?: string;
+    footer?: string;
+    /** App-shell chrome block slug (sidebar shell), when the group uses one. */
+    block?: string;
+}
+/**
+ * A resolved Next special-file block (from `manifest.extras`). `file` is the
+ * emitted Next special-file path (e.g. `app/not-found.tsx`) and the block is a
+ * page-kind block wrapped by the renderer under the golden rule.
+ */
+export interface PlanExtra {
+    /** The extras KEY = the Next special-file name (e.g. "not-found"). */
+    key: string;
+    /** Emitted file path under `app/` (e.g. "app/not-found.tsx"). */
+    file: string;
+    /** The resolved block slug for this special file. */
+    slug: string;
+    /** The block's meta export name (what the wrapper imports). */
+    exportName: string;
+}
+/** The fully-resolved, validated plan the renderer turns into files. */
+export interface ComposePlan {
+    /** The template/manifest name — the key of the `composed{}` record. */
+    templateName: string;
+    /** The project name (brand default + `__APP_NAME__` + legacy snapshot-dir fallback). */
+    appName: string;
+    planVersion: number;
+    title: string;
+    description: string;
+    choices: ComposedChoices;
+    pages: PlanPage[];
+    chromes: PlanChrome[];
+    /** Resolved Next special-file blocks (from `manifest.extras`), sorted by key. */
+    extras: PlanExtra[];
+    /**
+     * Every unique registry ITEM the plan installs (pages + chrome + extras),
+     * sorted. Item names, not family slugs: a non-default variant contributes its
+     * `<slug>--<variant>` item, so this is what the composer resolves/installs.
+     */
+    blockSlugs: string[];
+    /** Chrome block slugs used by any group, sorted. */
+    chromeSlugs: string[];
+    /** Shipped source per chrome slug (for the in-place data-slot/brand rewrite). */
+    chromeSources: Record<string, string>;
+    /** Declared data-slots per chrome slug (from meta). */
+    dataSlotsBySlug: Record<string, string[]>;
+    /** Declared brand tokens per chrome slug (from meta). */
+    brandTokensBySlug: Record<string, BrandToken[]>;
+    /** Whether any group uses a navbar / footer / shell (drives wrapper emission). */
+    usesNavbar: boolean;
+    usesFooter: boolean;
+    usesShell: boolean;
+    navbarSlug?: string;
+    footerSlug?: string;
+    shellSlug?: string;
+    navbarExportName?: string;
+    footerExportName?: string;
+    shellExportName?: string;
+}
+/** Thrown by {@link buildComposePlan} carrying EVERY semantic error found. */
+export declare class ComposePlanError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/** Options a caller passes to shape the plan (F1: brand, seed, page subset). */
+export interface ComposeChoiceInput {
+    /** Brand wordmark; falls back to manifest default (with `__APP_NAME__` filled) then appName. */
+    brand?: string;
+    /** Aesthetic PRNG seed (recorded when present; F1 renderer does not vary on it yet). */
+    seed?: number;
+    /** Route subset to include (F2); when omitted, all manifest pages are used. */
+    pages?: string[];
+    /**
+     * Per-family variant override (`{ login: "split" }`); a present entry wins over
+     * the manifest ref's declared variant for that slug. Recorded in `composed{}`.
+     */
+    variants?: Record<string, string>;
+    /** Project name, used to fill `__APP_NAME__` in the manifest brand default. */
+    appName?: string;
+}
+/**
+ * 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 declare function buildComposePlan(manifest: AppManifest, input: ComposeChoiceInput, index: RegistryIndex, meta: ComposeMeta, chromeSources: Record<string, string>): ComposePlan;
+/**
+ * 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 declare function validateComposePlan(manifest: AppManifest, input: ComposeChoiceInput, index: RegistryIndex, meta: ComposeMeta, chromeSources: Record<string, string>): {
+    plan?: ComposePlan;
+    errors: string[];
+};
+//# sourceMappingURL=plan.d.ts.map