@happyvertical/smrt-planner 0.0.1 → 0.1.0

package/dist/cookbook/describe.js

@@ -0,0 +1,164 @@
+import { getThemeName, isValidPreset, } from '@happyvertical/smrt-ui/themes/presets';
+import { humanize } from "../data/format.js";
+import { FEATURE_SECTION } from "../recipes/features.js";
+import { buildNavSections, recipes, recipesById } from "../recipes/index.js";
+import { DEFAULT_PRESET } from "../theme/theme.js";
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const NAV_SECTION_LABELS = new Map(buildNavSections(recipes).map((section) => [section.id, section.label]));
+/** The last segment of a qualified model name, humanized: `@scope/pkg:StockLevel` -> `Stock level`. */
+export function modelLabel(qualified) {
+    return humanize(qualified.slice(qualified.lastIndexOf(':') + 1));
+}
+/** Saved options grouped by model: `Customer: payment terms, currency`. */
+export function describeOptions(policies) {
+    const byModel = new Map();
+    for (const row of policies) {
+        const model = modelLabel(row.objectRef);
+        const fields = byModel.get(model) ?? [];
+        const field = humanize(row.fieldName).toLowerCase();
+        if (!fields.includes(field))
+            fields.push(field);
+        byModel.set(model, fields);
+    }
+    return [...byModel].map(([model, fields]) => `${model}: ${fields.join(', ')}`);
+}
+/** The theme as a few words: preset or brand colour, then what differs from the defaults. */
+export function describeTheme(theme) {
+    const parts = [];
+    if (theme.custom)
+        parts.push(`brand colour ${theme.custom.primary}`);
+    else if (theme.preset && theme.preset !== DEFAULT_PRESET) {
+        parts.push(`${isValidPreset(theme.preset) ? getThemeName(theme.preset) : theme.preset} preset`);
+    }
+    if (theme.colorScheme && theme.colorScheme !== 'system') {
+        parts.push(`${theme.colorScheme} scheme`);
+    }
+    const font = theme.fontFamily ?? theme.custom?.fontFamily;
+    if (font)
+        parts.push(`${font} font`);
+    if (theme.borderRadius)
+        parts.push(`${theme.borderRadius} corners`);
+    if (theme.density === 'touch')
+        parts.push('touch density');
+    if (theme.contrast && theme.contrast !== 'auto') {
+        parts.push(`${theme.contrast} contrast`);
+    }
+    if (theme.customCss?.trim())
+        parts.push('custom CSS');
+    return parts;
+}
+/** The layout delta in counts: custom sections by name, then hidden, renamed, moved, reordered. */
+export function describeLayout(layout) {
+    const parts = [];
+    const custom = layout.customSections ?? [];
+    if (custom.length) {
+        const names = custom.map((section) => section.label).filter(Boolean);
+        parts.push(`${plural(custom.length, 'custom section')}${names.length && names.length <= 4 ? ` (${names.join(', ')})` : ''}`);
+    }
+    const hidden = layout.hidden?.length ?? 0;
+    if (hidden)
+        parts.push(`${hidden} hidden`);
+    const renamed = Object.values(layout.items ?? {}).filter((item) => item.label).length +
+        Object.values(layout.sections ?? {}).filter((section) => section.label || section.icon || section.showTitle === false).length;
+    if (renamed)
+        parts.push(`${renamed} renamed or restyled`);
+    const moved = Object.keys(layout.moved ?? {}).length;
+    if (moved)
+        parts.push(`${moved} moved`);
+    if (layout.sectionOrder?.length ||
+        Object.keys(layout.itemOrder ?? {}).length) {
+        parts.push('reordered');
+    }
+    const placed = Object.keys(layout.placements ?? {}).length;
+    if (placed)
+        parts.push(`${plural(placed, 'shell item')} placed`);
+    if (Object.keys(layout.panels ?? {}).length)
+        parts.push('panel settings');
+    return parts;
+}
+/** A customised page's name from its overview id. */
+export function pageLabel(id, layout) {
+    if (id === `section:${FEATURE_SECTION.id}`)
+        return FEATURE_SECTION.label;
+    if (id.startsWith('section:')) {
+        const key = id.slice('section:'.length);
+        return (layout?.sections?.[id]?.label ??
+            NAV_SECTION_LABELS.get(key) ??
+            humanize(key));
+    }
+    if (id.startsWith('custom:')) {
+        return (layout?.customSections?.find((section) => section.id === id)?.label ??
+            humanize(id.slice('custom:'.length)));
+    }
+    if (id.startsWith('detail:')) {
+        const model = id.slice(id.lastIndexOf('.') + 1);
+        return `${humanize(model)} record`;
+    }
+    return humanize(id);
+}
+/** Every line with content, in display order; empty for an empty cookbook. */
+export function describeCookbook(cookbook) {
+    const lines = [];
+    if (cookbook.recipes.length) {
+        lines.push({
+            id: 'recipes',
+            label: plural(cookbook.recipes.length, 'recipe'),
+            chips: cookbook.recipes.map((id) => recipesById.get(id)?.label ?? id),
+        });
+    }
+    if (cookbook.features.length) {
+        lines.push({
+            id: 'features',
+            label: plural(cookbook.features.length, 'feature'),
+            chips: cookbook.features.map(modelLabel),
+        });
+    }
+    if (cookbook.policies.length) {
+        lines.push({
+            id: 'options',
+            label: plural(cookbook.policies.length, 'saved option'),
+            chips: describeOptions(cookbook.policies),
+        });
+    }
+    const narrowed = Object.entries(cookbook.exposure ?? {}).filter(([, surfaces]) => surfaces.length);
+    if (narrowed.length) {
+        lines.push({
+            id: 'exposure',
+            label: 'Surfaces switched off',
+            chips: narrowed.map(([model, surfaces]) => `${modelLabel(model)}: ${surfaces.join(', ')}`),
+        });
+    }
+    const theme = cookbook.theme ? describeTheme(cookbook.theme) : [];
+    if (theme.length) {
+        lines.push({ id: 'theme', label: 'Theme', text: theme.join(', ') });
+    }
+    const layout = cookbook.layout ? describeLayout(cookbook.layout) : [];
+    if (layout.length) {
+        lines.push({ id: 'layout', label: 'Layout', text: layout.join(', ') });
+    }
+    const pages = Object.keys(cookbook.overviews ?? {});
+    if (pages.length) {
+        lines.push({
+            id: 'pages',
+            label: plural(pages.length, 'customised page'),
+            chips: pages.map((id) => pageLabel(id, cookbook.layout)),
+        });
+    }
+    return lines;
+}
+/** One sentence for confirm dialogs: "3 recipes, 2 saved options, a theme and a layout". */
+export function summarizeCookbook(cookbook) {
+    const lines = describeCookbook(cookbook);
+    if (!lines.length)
+        return 'an empty cookbook';
+    const words = lines.map((line) => line.id === 'theme'
+        ? 'a theme'
+        : line.id === 'layout'
+            ? 'a layout'
+            : line.id === 'exposure'
+                ? 'narrowed surfaces'
+                : line.label);
+    return words.length === 1
+        ? words[0]
+        : `${words.slice(0, -1).join(', ')} and ${words.at(-1)}`;
+}

package/dist/cookbook/file.d.ts

@@ -1,7 +1,13 @@
 import type { Cookbook } from './types.ts';
 export declare const DEFAULT_EXPORT_NAME = "my-app";
+/** A name reduced to a file- and directory-safe slug; empty when nothing survives. */
+export declare function slugify(name?: string): string;
 /** `<name>.cookbook.json`, with the name reduced to a safe slug. */
 export declare function exportFileName(name?: string): string;
+/** The bytes of the file `downloadCookbook` writes. */
+export declare function exportFileSize(cookbook: Cookbook): number;
+/** "3.6 KB" / "12 KB" / "640 bytes", for a note beside a file or a prompt. */
+export declare function formatSize(bytes: number): string;
 export declare function serializeCookbook(cookbook: Cookbook): string;
 /** Offer the cookbook as a `<name>.cookbook.json` download. */
 export declare function downloadCookbook(cookbook: Cookbook, name?: string): void;

package/dist/cookbook/file.js

@@ -1,13 +1,27 @@
 export const DEFAULT_EXPORT_NAME = 'my-app';
-/** `<name>.cookbook.json`, with the name reduced to a safe slug. */
-export function exportFileName(name) {
-    const slug = (name ?? '')
+/** A name reduced to a file- and directory-safe slug; empty when nothing survives. */
+export function slugify(name) {
+    return (name ?? '')
         .normalize('NFD')
         .replace(/\p{M}/gu, '')
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
-    return `${slug || DEFAULT_EXPORT_NAME}.cookbook.json`;
+}
+/** `<name>.cookbook.json`, with the name reduced to a safe slug. */
+export function exportFileName(name) {
+    return `${slugify(name) || DEFAULT_EXPORT_NAME}.cookbook.json`;
+}
+/** The bytes of the file `downloadCookbook` writes. */
+export function exportFileSize(cookbook) {
+    return new TextEncoder().encode(serializeCookbook(cookbook)).length;
+}
+/** "3.6 KB" / "12 KB" / "640 bytes", for a note beside a file or a prompt. */
+export function formatSize(bytes) {
+    if (bytes < 1000)
+        return `${bytes} bytes`;
+    const kb = bytes / 1024;
+    return `${kb < 10 ? kb.toFixed(1) : Math.round(kb)} KB`;
 }
 export function serializeCookbook(cookbook) {
     return `${JSON.stringify(cookbook, null, 2)}\n`;

package/dist/cookbook/prompt.d.ts

@@ -0,0 +1,49 @@
+import type { Cookbook } from './types.ts';
+/**
+ * The Export page's "Copy prompt for your coding agent": one block of text a
+ * person pastes into a coding agent (Claude Code, Codex, …) to get a working
+ * app from the cookbook. The cookbook travels inside it as plain minified
+ * JSON in a quoted heredoc, so the agent writes the file byte for byte and
+ * nothing in it is expanded by the shell.
+ *
+ * Every command here is the released CLI's (`smrt cookbook validate`,
+ * `cookbook apply <file> <dir>`, `--into` for a second apply, `smrt app
+ * install` / `app doctor`); keep them in step with `smrt --help`. It needs no
+ * registry override: every @happyvertical package is on npmjs at the released
+ * version, and the app the CLI makes ships its own `.npmrc`.
+ */
+/** What `@happyvertical/smrt-core`, the CLI and the smrt-start template require. */
+export declare const NODE_REQUIREMENT = "Node 26 or newer";
+export declare const PNPM_REQUIREMENT = "pnpm 11";
+export declare const COOKBOOK_FILE = "cookbook.json";
+/** `npx -y @happyvertical/smrt-cli@<version>`, the CLI without a global install. */
+export declare function cliCommand(version?: string): string;
+/** The app directory `cookbook apply` creates: the cookbook's name as a slug, else the export name, else `my-app`. */
+export declare function appNameFor(cookbook: Cookbook, fallbackName?: string): string;
+/** `… cookbook apply <file> <app>`, the one command the downloaded file needs. */
+export declare function applyCommand(fileName: string, appName: string, version?: string): string;
+/**
+ * A heredoc delimiter no line of `body` equals. Minified JSON is one line
+ * starting with `{`, so the base is normally fine; a body that does carry
+ * the delimiter on a line of its own gets a numbered one.
+ */
+export declare function heredocDelimiter(body: string, base?: string): string;
+/** `cat > <file> <<'<delimiter>'` … `<delimiter>`, quoted so nothing expands. */
+export declare function heredoc(file: string, body: string): string;
+/** The body of the quoted heredoc that writes `file` in `text`; undefined when there is none. */
+export declare function heredocBody(text: string, file: string): string | undefined;
+export interface AgentPrompt {
+    text: string;
+    /** UTF-8 bytes of `text`. */
+    bytes: number;
+    appName: string;
+    version: string;
+    delimiter: string;
+}
+export interface AgentPromptOptions {
+    /** Names the app when the cookbook has no `name` (the library cookbook applied). */
+    fallbackName?: string;
+    version?: string;
+}
+/** The whole prompt for one cookbook. Pure; the page only copies it. */
+export declare function buildAgentPrompt(cookbook: Cookbook, options?: AgentPromptOptions): AgentPrompt;

package/dist/cookbook/prompt.js

@@ -0,0 +1,100 @@
+import { SMRT_VERSION } from "../smrt-version.js";
+import { DEFAULT_EXPORT_NAME, slugify } from "./file.js";
+/**
+ * The Export page's "Copy prompt for your coding agent": one block of text a
+ * person pastes into a coding agent (Claude Code, Codex, …) to get a working
+ * app from the cookbook. The cookbook travels inside it as plain minified
+ * JSON in a quoted heredoc, so the agent writes the file byte for byte and
+ * nothing in it is expanded by the shell.
+ *
+ * Every command here is the released CLI's (`smrt cookbook validate`,
+ * `cookbook apply <file> <dir>`, `--into` for a second apply, `smrt app
+ * install` / `app doctor`); keep them in step with `smrt --help`. It needs no
+ * registry override: every @happyvertical package is on npmjs at the released
+ * version, and the app the CLI makes ships its own `.npmrc`.
+ */
+/** What `@happyvertical/smrt-core`, the CLI and the smrt-start template require. */
+export const NODE_REQUIREMENT = 'Node 26 or newer';
+export const PNPM_REQUIREMENT = 'pnpm 11';
+export const COOKBOOK_FILE = 'cookbook.json';
+const DELIMITER_BASE = 'COOKBOOK_EOF';
+/** `npx -y @happyvertical/smrt-cli@<version>`, the CLI without a global install. */
+export function cliCommand(version = SMRT_VERSION) {
+    return `npx -y @happyvertical/smrt-cli@${version}`;
+}
+/** The app directory `cookbook apply` creates: the cookbook's name as a slug, else the export name, else `my-app`. */
+export function appNameFor(cookbook, fallbackName) {
+    return slugify(cookbook.name) || slugify(fallbackName) || DEFAULT_EXPORT_NAME;
+}
+/** `… cookbook apply <file> <app>`, the one command the downloaded file needs. */
+export function applyCommand(fileName, appName, version = SMRT_VERSION) {
+    return `${cliCommand(version)} cookbook apply ${fileName} ${appName}`;
+}
+/**
+ * A heredoc delimiter no line of `body` equals. Minified JSON is one line
+ * starting with `{`, so the base is normally fine; a body that does carry
+ * the delimiter on a line of its own gets a numbered one.
+ */
+export function heredocDelimiter(body, base = DELIMITER_BASE) {
+    const lines = new Set(body.split('\n'));
+    let delimiter = base;
+    for (let n = 1; lines.has(delimiter); n++)
+        delimiter = `${base}_${n}`;
+    return delimiter;
+}
+/** `cat > <file> <<'<delimiter>'` … `<delimiter>`, quoted so nothing expands. */
+export function heredoc(file, body) {
+    const delimiter = heredocDelimiter(body);
+    return `cat > ${file} <<'${delimiter}'\n${body}\n${delimiter}`;
+}
+/** The body of the quoted heredoc that writes `file` in `text`; undefined when there is none. */
+export function heredocBody(text, file) {
+    const lines = text.split('\n');
+    const prefix = `cat > ${file} <<'`;
+    const start = lines.findIndex((line) => line.startsWith(prefix) && line.endsWith("'"));
+    if (start < 0)
+        return undefined;
+    const delimiter = lines[start].slice(prefix.length, -1);
+    const end = lines.indexOf(delimiter, start + 1);
+    return end < 0 ? undefined : lines.slice(start + 1, end).join('\n');
+}
+/** The whole prompt for one cookbook. Pure; the page only copies it. */
+export function buildAgentPrompt(cookbook, options = {}) {
+    const version = options.version ?? SMRT_VERSION;
+    const appName = appNameFor(cookbook, options.fallbackName);
+    const json = JSON.stringify(cookbook);
+    const delimiter = heredocDelimiter(json);
+    const cli = cliCommand(version);
+    const text = [
+        `Create a new s-m-r-t app from the cookbook below. Work in a new, empty directory outside any existing project, run the steps in order, and when you finish report what you ran and what happened, including anything that failed.`,
+        '',
+        `1. Prerequisites: ${NODE_REQUIREMENT} (\`node --version\`), git, and ${PNPM_REQUIREMENT} or newer (\`npm install -g pnpm\` if missing).`,
+        '',
+        `2. Write the cookbook exactly as given, without reformatting or editing it:`,
+        '',
+        `cat > ${COOKBOOK_FILE} <<'${delimiter}'\n${json}\n${delimiter}`,
+        '',
+        `3. Validate it, then create the app in ./${appName}:`,
+        '',
+        `${cli} cookbook validate ${COOKBOOK_FILE}`,
+        `${cli} cookbook apply ${COOKBOOK_FILE} ${appName}`,
+        '',
+        // TODO(smrt#4009): once a release makes new tenants start on the money
+        // model (`ensureCommerceTenant`), add the step that activates the app's
+        // tenant and its cookbook tax settings (`applyCommerceCookbookSettings`);
+        // until then a fresh app's tenant starts on the legacy model.
+        `4. Set it up (in a subshell, so the commands below still run from this directory):`,
+        '',
+        `(cd ${appName} && pnpm exec smrt app install)`,
+        '',
+        `If any step fails, run \`pnpm exec smrt app doctor\` inside ${appName} and include its findings in your report. Do not hand-edit the app's smrt.cookbook.json: change ${COOKBOOK_FILE} and run \`${cli} cookbook apply ${COOKBOOK_FILE} --into ${appName}\` instead.`,
+        '',
+    ].join('\n');
+    return {
+        text,
+        bytes: new TextEncoder().encode(text).length,
+        appName,
+        version,
+        delimiter,
+    };
+}

package/dist/cookbook/store.svelte.d.ts

@@ -8,6 +8,11 @@ export declare const SHELL_STORAGE_KEY = "smrt-planner:shell";
 export declare const SAVE_DELAY_MS = 300;
 /** `ok`: saved. `memory`: storage unavailable or refusing, working in memory. */
 export type PersistState = 'unknown' | 'ok' | 'memory';
+/**
+ * Sample documents follow the app's money settings (tax rate, prices with or
+ * without tax, rounding, currency) the next time sample rows are generated.
+ */
+export declare function followSettings(cookbook: Pick<Cookbook, 'policies'>): void;
 /**
  * The single source of truth for what a visitor has built. Recipes and
  * options stay in `recipeState` (the one store views read); this adds the
@@ -30,6 +35,8 @@ export declare class CookbookStore {
     persist: PersistState;
     /** False until the saved cookbook has been read; nothing saves before. */
     loaded: boolean;
+    /** Host-backed preview writes through Kitchen instead of browser storage. */
+    hostManaged: boolean;
     /** Why the saved cookbook was not used, if it was not. */
     loadNotice: string;
     /**
@@ -47,6 +54,12 @@ export declare class CookbookStore {
     private previousKept;
     private storage;
     private timer;
+    /**
+     * Plain data only: the `$state` fields are unwrapped with `$state.snapshot`
+     * because the document reaches smrt-core's cookbook engine, whose
+     * `structuredClone` throws on a `$state` proxy (#53: a saved layout then
+     * made the plan unreadable on reload).
+     */
     snapshot(): Cookbook;
     /** A page's stored override, or `null` when it is on its defaults. */
     overview(id: string): OverviewOverride | null;

package/dist/cookbook/store.svelte.js

@@ -1,7 +1,7 @@
 import { isShellLayoutEmpty, } from '@happyvertical/smrt-svelte/workspace/layout';
-import { setSampleTaxRate } from "../data/packs.js";
+import { setSamplePricing, setSampleTaxRate } from "../data/packs.js";
 import { recipeState } from "../recipes/state.svelte.js";
-import { hasTaxRateRow, readSettings, writeSettings, } from "../settings/app-settings.js";
+import { hasTaxRateRow, isSettingRow, readSettings, writeSettings, } from "../settings/app-settings.js";
 import { compactTheme } from "../theme/theme.js";
 import { assembleCookbook } from "./assemble.js";
 import { cookbookFromLegacySearch, hasLegacyState } from "./legacy.js";
@@ -10,6 +10,23 @@ import { parseCookbookText } from "./validate.js";
 /** Where the planner's AppShell keeps its own settings (panel states, sizes). */
 export const SHELL_STORAGE_KEY = 'smrt-planner:shell';
 export const SAVE_DELAY_MS = 300;
+/**
+ * Sample documents follow the app's money settings (tax rate, prices with or
+ * without tax, rounding, currency) the next time sample rows are generated.
+ */
+export function followSettings(cookbook) {
+    const settings = readSettings(cookbook);
+    // Once the app states any setting (a cookbook or the Settings tab did), its
+    // tax rate is what it says, 0 included, as an exported cookbook means; a
+    // fresh app keeps the sample pack's rate.
+    const stated = cookbook.policies.some((row) => row.defaultValue !== undefined && isSettingRow(row));
+    setSampleTaxRate(hasTaxRateRow(cookbook) || stated ? settings.taxRate : undefined);
+    setSamplePricing({
+        pricesIncludeTax: settings.pricesIncludeTax,
+        taxRounding: settings.taxRounding,
+        currency: settings.currency,
+    });
+}
 /**
  * The single source of truth for what a visitor has built. Recipes and
  * options stay in `recipeState` (the one store views read); this adds the
@@ -32,6 +49,8 @@ export class CookbookStore {
     persist = $state('unknown');
     /** False until the saved cookbook has been read; nothing saves before. */
     loaded = $state(false);
+    /** Host-backed preview writes through Kitchen instead of browser storage. */
+    hostManaged = false;
     /** Why the saved cookbook was not used, if it was not. */
     loadNotice = $state('');
     /**
@@ -49,11 +68,17 @@ export class CookbookStore {
     previousKept = false;
     storage = null;
     timer;
+    /**
+     * Plain data only: the `$state` fields are unwrapped with `$state.snapshot`
+     * because the document reaches smrt-core's cookbook engine, whose
+     * `structuredClone` throws on a `$state` proxy (#53: a saved layout then
+     * made the plan unreadable on reload).
+     */
     snapshot() {
-        return assembleCookbook(recipeState.data, {
-            layout: this.layout,
+        return assembleCookbook($state.snapshot(recipeState.data), {
+            layout: $state.snapshot(this.layout),
             theme: $state.snapshot(this.theme),
-            overviews: this.overviews,
+            overviews: $state.snapshot(this.overviews),
             name: this.name,
             description: this.description,
         });
@@ -84,7 +109,7 @@ export class CookbookStore {
         this.name = cookbook.name;
         this.description = cookbook.description;
         this.overviews = { ...(cookbook.overviews ?? {}) };
-        setSampleTaxRate(hasTaxRateRow(cookbook) ? readSettings(cookbook).taxRate : undefined);
+        followSettings(cookbook);
     }
     /**
      * A sentence naming recipes and features the loaded cookbook has that this
@@ -117,7 +142,7 @@ export class CookbookStore {
     setSettings(settings) {
         const next = writeSettings(this.snapshot(), settings);
         recipeState.rows = next.policies.map((row) => ({ ...row }));
-        setSampleTaxRate(hasTaxRateRow(next) ? readSettings(next).taxRate : undefined);
+        followSettings(next);
     }
     /** Replace on the visitor's say-so (an import): saving is allowed again. */
     replace(cookbook) {
@@ -130,6 +155,7 @@ export class CookbookStore {
     /** Back to an empty cookbook, and the shell's own settings to defaults. */
     reset() {
         recipeState.clear();
+        followSettings({ policies: [] });
         this.layout = undefined;
         this.theme = undefined;
         this.name = undefined;
@@ -201,6 +227,8 @@ export class CookbookStore {
         this.timer = undefined;
         if (!this.loaded)
             return false;
+        if (this.hostManaged)
+            return true;
         if (this.saveBlocked) {
             this.persist = 'memory';
             return false;
@@ -217,7 +245,7 @@ export class CookbookStore {
     }
     /** Save soon; many quick edits make one write. */
     scheduleSave() {
-        if (!this.loaded)
+        if (!this.loaded || this.hostManaged)
             return;
         clearTimeout(this.timer);
         this.timer = setTimeout(() => this.save(), SAVE_DELAY_MS);

package/dist/core/app.d.ts

@@ -1,12 +1,37 @@
+import type { InferenceConfig } from '../inference/config.ts';
+import type { KitchenEndpoint } from '../kitchen/client.ts';
 /**
- * Absolute path of the prerendered static planner app inside this package
- * (`app/`, built with the planner's relative base, so it works at `/` and at
- * any sub-path). Node only; kept out of `./core` so that entry stays free of
- * Node built-ins.
- *
- * Serve the files from here, and write your own `planner.config.json` next to
- * its `index.html` (copy the directory, or answer that one path yourself).
+ * Absolute path of the root-built prerendered planner app inside this package.
+ * Node only; kept out of `./core` so that entry stays free of Node built-ins.
+ * Serve it at `/`, or use `materializeApp` for a supported subpath artifact.
  */
 export declare const appDir: string;
-/** Absolute path of one file in the app, e.g. `appFile('planner.config.json')`. */
+/** Absolute path of one packaged app file, e.g. `appFile('index.html')`. */
 export declare function appFile(relativePath: string): string;
+export interface PlannerAppConfig {
+    inference?: InferenceConfig;
+    kitchen?: KitchenEndpoint;
+}
+export interface MaterializeAppOptions {
+    /** New or empty directory that receives the app root. */
+    outDir: string;
+    /** Canonical mount prefix: leading slash, no trailing slash, e.g. `/plan`. */
+    basePath: string;
+    /** Written as `planner.config.json` after validation and normalization. */
+    config: PlannerAppConfig;
+}
+export interface MaterializedApp {
+    outDir: string;
+    configFile: string;
+    fallbackFile: string;
+}
+/** Validate and canonicalize a non-root app mount prefix. */
+export declare function normalizeAppBasePath(basePath: string): string;
+/** Validate config strictly enough for an immutable public artifact. */
+export declare function normalizePlannerAppConfig(config: PlannerAppConfig): PlannerAppConfig;
+/**
+ * Copy the published static app into a deterministic, prefix-safe deployment
+ * artifact. The copy is assembled beside `outDir` and renamed only after its
+ * fallback and config validate, so callers never receive a partial tree.
+ */
+export declare function materializeApp(options: MaterializeAppOptions): MaterializedApp;