@happyvertical/smrt-planner 0.0.0-stage → 0.0.2

package/dist/library/menu.d.ts

@@ -0,0 +1,18 @@
+import type { ShellNavGroup } from '@happyvertical/smrt-svelte/workspace';
+import type { Cookbook } from '../cookbook/types.ts';
+import type { CookbookLayout, MenuSection } from './types.ts';
+/**
+ * The navigation a cookbook produces before its layout: one group per nav
+ * section, items in recipe order, with the same stable ids the app shell uses
+ * (`navItemId`), so a layout's ids line up with what the app generates.
+ */
+export declare function cookbookNavGroups(cookbook: Pick<Cookbook, 'recipes' | 'features'>): ShellNavGroup[];
+/**
+ * The menu a cookbook gives its app, in the visitor's own words: sections and
+ * entries after the layout is applied (moves, hides, renames), with each
+ * entry's `layout.items` label. Pure, so the Cookbooks preview shows exactly
+ * what applying the cookbook will build.
+ */
+export declare function previewMenu(cookbook: Pick<Cookbook, 'recipes' | 'features'> & {
+    layout?: CookbookLayout;
+}): MenuSection[];

package/dist/library/menu.js

@@ -0,0 +1,72 @@
+import { applyShellLayout } from '@happyvertical/smrt-svelte/workspace/layout';
+import { FEATURE_SECTION, featureNavItems } from "../recipes/features.js";
+import { buildNavSections, recipeNav, recipesById } from "../recipes/index.js";
+import { navItemId } from "../recipes/sections.js";
+/**
+ * The navigation a cookbook produces before its layout: one group per nav
+ * section, items in recipe order, with the same stable ids the app shell uses
+ * (`navItemId`), so a layout's ids line up with what the app generates.
+ */
+export function cookbookNavGroups(cookbook) {
+    const added = cookbook.recipes.flatMap((id) => {
+        const recipe = recipesById.get(id);
+        return recipe ? [recipe] : [];
+    });
+    // A section none of whose recipes has a menu entry (an assistant, a settings
+    // panel) is left out rather than shown empty.
+    const groups = buildNavSections(added)
+        .map((section) => {
+        const seen = new Set();
+        const items = [];
+        for (const recipe of section.recipes) {
+            for (const entry of recipeNav(recipe)) {
+                const id = navItemId(entry.packageId, entry.model.name, entry.key);
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                items.push({
+                    id,
+                    href: '#',
+                    label: entry.label,
+                    icon: entry.icon,
+                    description: entry.description,
+                });
+            }
+        }
+        return { id: `section:${section.id}`, heading: section.label, items };
+    })
+        .filter((group) => group.items.length > 0);
+    const features = featureNavItems(cookbook.features).map((item) => ({
+        id: item.id,
+        href: '#',
+        label: item.label,
+        icon: item.icon,
+        description: item.description,
+    }));
+    if (features.length) {
+        groups.push({
+            id: `section:${FEATURE_SECTION.id}`,
+            heading: FEATURE_SECTION.label,
+            items: features,
+        });
+    }
+    return groups;
+}
+/**
+ * The menu a cookbook gives its app, in the visitor's own words: sections and
+ * entries after the layout is applied (moves, hides, renames), with each
+ * entry's `layout.items` label. Pure, so the Cookbooks preview shows exactly
+ * what applying the cookbook will build.
+ */
+export function previewMenu(cookbook) {
+    const layout = cookbook.layout;
+    const applied = applyShellLayout([], cookbookNavGroups(cookbook), undefined, layout);
+    return applied.groups.map((group) => ({
+        id: group.id ?? String(group.heading),
+        label: group.heading ?? '',
+        entries: group.items.map((item) => ({
+            id: item.id ?? item.href,
+            label: layout?.items?.[item.id ?? item.href]?.label?.trim() || item.label,
+        })),
+    }));
+}

package/dist/library/state.svelte.d.ts

@@ -0,0 +1,10 @@
+/** Which cookbook the visitor last applied; a UI note, not part of the cookbook. */
+export declare const COOKBOOK_KEY = "smrt-planner:cookbook";
+declare class CookbookState {
+    active: string | null;
+    /** Read the remembered cookbook (browser only; never throws). */
+    load(storage?: Storage | null): void;
+    select(id: string, storage?: Storage | null): void;
+}
+export declare const libraryState: CookbookState;
+export {};

package/dist/library/state.svelte.js

@@ -0,0 +1,28 @@
+import { browserStorage } from "../cookbook/storage.js";
+import { setSamplePack } from "../data/packs.js";
+/** Which cookbook the visitor last applied; a UI note, not part of the cookbook. */
+export const COOKBOOK_KEY = 'smrt-planner:cookbook';
+class CookbookState {
+    active = $state(null);
+    /** Read the remembered cookbook (browser only; never throws). */
+    load(storage = browserStorage()) {
+        try {
+            this.active = storage?.getItem(COOKBOOK_KEY) ?? null;
+        }
+        catch {
+            this.active = null;
+        }
+        // The sample data follows the cookbook the visitor last applied.
+        setSamplePack(this.active);
+    }
+    select(id, storage = browserStorage()) {
+        this.active = id;
+        try {
+            storage?.setItem(COOKBOOK_KEY, id);
+        }
+        catch {
+            // Remembered in memory only.
+        }
+    }
+}
+export const libraryState = new CookbookState();

package/dist/library/types.d.ts

@@ -0,0 +1,57 @@
+import type { ShellLayout } from '@happyvertical/smrt-svelte/workspace/layout';
+import type { Cookbook } from '../cookbook/types.ts';
+/**
+ * `ShellLayout` plus the per-entry rename smrt-svelte is adding
+ * (`layout.items[<navItemId>].label`). The planner writes it today; it renders
+ * once the installed smrt-svelte reads it, and the cookbook preview reads the
+ * same labels either way. Delete this type when `ShellLayout` carries `items`.
+ */
+export type CookbookLayout = ShellLayout & {
+    items?: Record<string, {
+        label?: string;
+        description?: string;
+    }>;
+};
+/** The app-wide defaults a cookbook sets (the policy rows realise them). */
+export interface CookbookSettings {
+    /** ISO currency code, e.g. `USD`. */
+    currency?: string;
+    /** Default payment terms on customer-facing documents and customers. */
+    paymentTerms?: string;
+    /** Default line-item tax rate as a fraction (0.0825 is 8.25%). */
+    taxRate?: number;
+}
+/** A curated, ready-made cookbook with the words that introduce it. */
+export interface LibraryCookbook {
+    id: string;
+    name: string;
+    /** A key of `COOKBOOK_ICONS`. */
+    icon: string;
+    summary: string;
+    /**
+     * Words and phrases that point at this cookbook ("brakes", "oil change").
+     * The assistant matches them against what the person types; the name is
+     * matched too. Ambiguous words (like "car" or "classes") only hint.
+     */
+    keywords: string[];
+    settings: CookbookSettings;
+    /**
+     * One line per custom section (`custom:<id>`), shown under its title on the
+     * section's page. The section's icon is in `cookbook.layout.sections`.
+     */
+    sectionDescriptions?: Record<string, string>;
+    /** The same document the Export tab saves. */
+    document: Cookbook;
+}
+export interface LibraryFile {
+    cookbooks: LibraryCookbook[];
+}
+export interface MenuEntry {
+    id: string;
+    label: string;
+}
+export interface MenuSection {
+    id: string;
+    label: string;
+    entries: MenuEntry[];
+}

package/dist/library/types.js

@@ -0,0 +1 @@
+export {};

package/dist/overviews/definitions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Which overviews exist and what each declares (smrt#3727). Every navigation
+ * section page is an editable overview whose id is the section's layout id
+ * (`section:sales`, `custom:shop-2`), so a cookbook's `overviews` key names the
+ * page it customises and stays valid when the section is renamed.
+ *
+ * Definitions are static per section (they never depend on which recipes are
+ * on), so a saved override always resolves against the same defaults: the
+ * cookbook loader, the import and the page agree on what is canonical.
+ */
+import { type OverviewDefinition } from '@happyvertical/smrt-svelte/overview';
+import type { ShellLayout } from '@happyvertical/smrt-svelte/workspace/layout';
+/**
+ * The overview a section page renders; one frozen definition per id.
+ * `undefined` for an id no overview can have (a hand-edited layout's custom
+ * section id outside the overview id pattern): the page then shows its menu.
+ */
+export declare function sectionOverview(sectionId: string): OverviewDefinition | undefined;
+/**
+ * Whether `id` names an overview in a cookbook with this layout: a section a
+ * recipe suggests, More, or one of the layout's custom sections. Anything else
+ * (a typo, a section from another app) is unknown and its override is dropped.
+ */
+export declare function isOverviewId(id: string, layout?: ShellLayout): boolean;

package/dist/overviews/definitions.js

@@ -0,0 +1,97 @@
+/**
+ * Which overviews exist and what each declares (smrt#3727). Every navigation
+ * section page is an editable overview whose id is the section's layout id
+ * (`section:sales`, `custom:shop-2`), so a cookbook's `overviews` key names the
+ * page it customises and stays valid when the section is renamed.
+ *
+ * Definitions are static per section (they never depend on which recipes are
+ * on), so a saved override always resolves against the same defaults: the
+ * cookbook loader, the import and the page agree on what is canonical.
+ */
+import { defineOverview, OVERVIEW_PAGE_ID_PATTERN, } from '@happyvertical/smrt-svelte/overview';
+import { catalog } from "../catalog/index.js";
+import { humanize, pluralize } from "../data/format.js";
+import { FEATURE_SECTION } from "../recipes/features.js";
+import { buildNavSections, recipeNav, recipes } from "../recipes/index.js";
+import { CORE_WIDGET_TYPES, RECIPE_WIDGET_TYPES } from "./registry.js";
+const NAV_SECTIONS = new Map(buildNavSections(recipes).map((section) => [
+    `section:${section.id}`,
+    section,
+]));
+/** Every model a widget may read: the catalog's, the data the sample source holds. */
+const MODELS = catalog.packages.flatMap((pkg) => pkg.models.map((model) => model.id));
+const ALLOWED = [
+    ...CORE_WIDGET_TYPES,
+    ...RECIPE_WIDGET_TYPES,
+];
+/**
+ * The section's lead model: the first menu entry of the first recipe that
+ * suggests the section. Its count and records follow the shortcuts.
+ */
+function leadModel(sectionId) {
+    const section = NAV_SECTIONS.get(sectionId);
+    for (const recipe of section?.recipes ?? []) {
+        const entry = recipeNav(recipe)[0];
+        if (entry)
+            return { id: entry.model.id, name: humanize(entry.model.name) };
+    }
+    return undefined;
+}
+function defaults(sectionId) {
+    const widgets = [
+        { id: 'shortcuts', type: 'shortcuts', span: 4, options: {} },
+    ];
+    const lead = leadModel(sectionId);
+    if (lead) {
+        widgets.push({
+            id: 'count',
+            type: 'metric',
+            span: 1,
+            options: {
+                title: pluralize(lead.name),
+                model: lead.id,
+                measure: 'count',
+            },
+        }, {
+            id: 'latest',
+            type: 'records',
+            span: 3,
+            options: { title: `${lead.name} records`, model: lead.id, limit: 5 },
+        });
+    }
+    return widgets;
+}
+const cache = new Map();
+/**
+ * The overview a section page renders; one frozen definition per id.
+ * `undefined` for an id no overview can have (a hand-edited layout's custom
+ * section id outside the overview id pattern): the page then shows its menu.
+ */
+export function sectionOverview(sectionId) {
+    if (!OVERVIEW_PAGE_ID_PATTERN.test(sectionId))
+        return undefined;
+    let definition = cache.get(sectionId);
+    if (!definition) {
+        definition = defineOverview({
+            id: sectionId,
+            allowed: ALLOWED,
+            models: MODELS,
+            defaults: defaults(sectionId),
+        });
+        cache.set(sectionId, definition);
+    }
+    return definition;
+}
+/**
+ * Whether `id` names an overview in a cookbook with this layout: a section a
+ * recipe suggests, More, or one of the layout's custom sections. Anything else
+ * (a typo, a section from another app) is unknown and its override is dropped.
+ */
+export function isOverviewId(id, layout) {
+    if (NAV_SECTIONS.has(id) || id === `section:${FEATURE_SECTION.id}`) {
+        return true;
+    }
+    return (id.startsWith('custom:') &&
+        OVERVIEW_PAGE_ID_PATTERN.test(id) &&
+        (layout?.customSections ?? []).some((section) => section.id === id));
+}

package/dist/overviews/page.d.ts

@@ -0,0 +1,21 @@
+/**
+ * How a section page wires its overview to the cookbook (smrt#3727): the
+ * controller reads the page's stored override from the cookbook store and
+ * writes every edit back, so the cookbook is the single source of truth.
+ * `SectionOverview.svelte` calls this; tests drive the same wiring.
+ */
+import { type OverviewController, type OverviewDefinition, type OverviewOverride, type OverviewWidget } from '@happyvertical/smrt-svelte/overview';
+import { type PlannerWidgetContext } from './registry.ts';
+/** The part of the cookbook store an overview reads and writes. */
+export interface OverviewStore {
+    overview(id: string): OverviewOverride | null;
+    setOverview(id: string, override: OverviewOverride | null): void;
+}
+/**
+ * One widget's data from the in-browser source, through the same
+ * sanitize-and-load path (timeout, serializable check) as a page load. A
+ * failed load throws, which the grid shows as that widget's error tile.
+ */
+export declare function loadSectionWidget(definition: OverviewDefinition, context: PlannerWidgetContext, widget: OverviewWidget, signal?: AbortSignal): Promise<unknown>;
+/** The controller of a section's overview, persisted through `store`. */
+export declare function createSectionOverview(definition: OverviewDefinition, store: OverviewStore, context?: () => PlannerWidgetContext): OverviewController;

package/dist/overviews/page.js

@@ -0,0 +1,36 @@
+/**
+ * How a section page wires its overview to the cookbook (smrt#3727): the
+ * controller reads the page's stored override from the cookbook store and
+ * writes every edit back, so the cookbook is the single source of truth.
+ * `SectionOverview.svelte` calls this; tests drive the same wiring.
+ */
+import { createOverview, loadOverview, } from '@happyvertical/smrt-svelte/overview';
+import { overviewRegistry } from "./registry.js";
+/**
+ * One widget's data from the in-browser source, through the same
+ * sanitize-and-load path (timeout, serializable check) as a page load. A
+ * failed load throws, which the grid shows as that widget's error tile.
+ */
+export async function loadSectionWidget(definition, context, widget, signal) {
+    const loaded = await loadOverview({ widgets: [widget] }, definition, overviewRegistry, { ...context, signal, locale: 'en-US' });
+    const result = loaded.widgets[0];
+    if (!result || result.status === 'error') {
+        throw new Error(result?.error?.code ?? 'load_failed');
+    }
+    return result.data;
+}
+/** The controller of a section's overview, persisted through `store`. */
+export function createSectionOverview(definition, store, context) {
+    const id = definition.id;
+    return createOverview({
+        definition,
+        registry: overviewRegistry,
+        override: () => store.overview(id),
+        onchange: (override) => store.setOverview(id, override),
+        ...(context
+            ? {
+                loadWidget: (widget, signal) => loadSectionWidget(definition, context(), widget, signal),
+            }
+            : {}),
+    });
+}

package/dist/overviews/registry.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The planner's overview widgets (smrt#3727): one registry for every section
+ * overview, the core widgets wired to the IN-BROWSER sample data, and the
+ * recipes' `widget` surfaces. Validation (`cookbook/validate.ts`) and the
+ * section pages share it, so what a cookbook may hold is exactly what a page
+ * can render.
+ *
+ * Loaders receive validated options only. What they read comes from the host
+ * capabilities a page passes in the load context ({@link PlannerWidgetContext}),
+ * never from option values: an option names a model or field, the loader looks
+ * it up in the catalog and asks the `DataSource` for it.
+ */
+import { type RecipeExportResolver, type RecipeWidgetSource, type ShortcutNavSection } from '@happyvertical/smrt-svelte/overview';
+import type { DataSource } from '../data/source.ts';
+import type { SectionEntry } from '../sections/entries.ts';
+/** The capabilities a section page hands its widgets' loaders. */
+export interface PlannerWidgetContext {
+    /** The in-browser sample data. */
+    source: DataSource;
+    /** The shell's resolved sections (renames and hides applied). */
+    sections: readonly ShortcutNavSection[];
+    /** Layout item id -> the model and scope it lists, for record counts. */
+    entries: ReadonlyMap<string, SectionEntry>;
+    /** An in-app path with the app query (`appHref`). */
+    href: (path: string) => string;
+}
+/** The registry every planner overview uses. */
+export declare const overviewRegistry: import("@happyvertical/smrt-svelte/overview").WidgetRegistry;
+/** The core widget types a section overview offers. */
+export declare const CORE_WIDGET_TYPES: readonly ["shortcuts", "metric", "records", "note"];
+export declare const resolveRecipeExport: RecipeExportResolver;
+/** Recipes that declare at least one `widget` surface. */
+export declare const widgetRecipes: readonly RecipeWidgetSource[];
+/**
+ * Widget types the recipes contribute, allowed on every section overview. A
+ * widget's own `allowedIn` still confines it.
+ */
+export declare const RECIPE_WIDGET_TYPES: readonly string[];
+/**
+ * Register the recipes' widgets. Surfaces without a `migrate` register
+ * synchronously inside this call (the helper awaits only `migrate` exports), so
+ * validation at load sees them; the promise reports what was skipped.
+ */
+export declare const recipeWidgets: Promise<import("@happyvertical/smrt-svelte/overview").RecipeWidgetRegistration>;

package/dist/overviews/registry.js

@@ -0,0 +1,191 @@
+/**
+ * The planner's overview widgets (smrt#3727): one registry for every section
+ * overview, the core widgets wired to the IN-BROWSER sample data, and the
+ * recipes' `widget` surfaces. Validation (`cookbook/validate.ts`) and the
+ * section pages share it, so what a cookbook may hold is exactly what a page
+ * can render.
+ *
+ * Loaders receive validated options only. What they read comes from the host
+ * capabilities a page passes in the load context ({@link PlannerWidgetContext}),
+ * never from option values: an option names a model or field, the loader looks
+ * it up in the catalog and asks the `DataSource` for it.
+ */
+import { createWidgetRegistry, registerCoreWidgets, registerRecipeWidgets, shortcutsFromNav, } from '@happyvertical/smrt-svelte/overview';
+import { getModelByQualifiedName } from "../catalog/index.js";
+import { isMoneyField } from "../data/fakes.js";
+import { recordCount } from "../data/format.js";
+import { recordLabel } from "../data/labels.js";
+import { recipes } from "../recipes/index.js";
+import { inScope } from "../recipes/scope.js";
+/** The registry every planner overview uses. */
+export const overviewRegistry = createWidgetRegistry();
+function capabilities(ctx) {
+    const { source, sections, entries, href } = ctx;
+    if (!source || !sections || !entries || !href) {
+        throw new Error('the planner widget context is missing');
+    }
+    return { source, sections, entries, href };
+}
+function modelOf(qualified) {
+    const found = typeof qualified === 'string'
+        ? getModelByQualifiedName(qualified)
+        : undefined;
+    if (!found)
+        throw new Error(`unknown model ${String(qualified)}`);
+    return {
+        model: found.model,
+        path: `/m/${found.pkg.id}/${found.model.name}/`,
+    };
+}
+/** The sample data has no named filters yet: naming one is an error tile. */
+function refuseFilter(filter) {
+    if (typeof filter === 'string' && filter !== '') {
+        throw new Error(`unknown filter ${filter}`);
+    }
+}
+const numeric = (value) => typeof value === 'number' && Number.isFinite(value);
+/**
+ * `metric`: a count, or the sum / average / min / max of one numeric field,
+ * over the model's sample rows. Money fields stay integer minor units.
+ */
+async function loadMetric(options, ctx) {
+    const { source, href } = capabilities(ctx);
+    const { model, path } = modelOf(options.model);
+    refuseFilter(options.filter);
+    const rows = await source.list(model);
+    const measure = typeof options.measure === 'string' ? options.measure : '';
+    if (measure === 'count' || measure === '') {
+        return {
+            value: rows.length,
+            format: 'integer',
+            href: href(path),
+        };
+    }
+    const field = model.fields.find((f) => f.name === options.field);
+    if (!field || (field.type !== 'integer' && field.type !== 'decimal')) {
+        throw new Error(`${measure} needs a numeric field of ${model.name}`);
+    }
+    const values = rows.map((row) => row[field.name]).filter(numeric);
+    let value = 0;
+    if (values.length) {
+        if (measure === 'sum' || measure === 'avg') {
+            value = values.reduce((total, v) => total + v, 0);
+            if (measure === 'avg')
+                value /= values.length;
+        }
+        else if (measure === 'min')
+            value = Math.min(...values);
+        else if (measure === 'max')
+            value = Math.max(...values);
+        else
+            throw new Error(`unknown measure ${measure}`);
+    }
+    const money = isMoneyField(field);
+    return {
+        // Money is integer minor units, also for an average.
+        value: money ? Math.round(value) : value,
+        format: money ? 'money' : field.type === 'integer' ? 'integer' : 'decimal',
+        ...(money ? { currency: 'USD' } : {}),
+        href: href(path),
+    };
+}
+function compare(a, b) {
+    if (numeric(a) && numeric(b))
+        return a - b;
+    return String(a ?? '').localeCompare(String(b ?? ''));
+}
+/** `records`: the first `limit` sample rows, optionally sorted by a field. */
+async function loadRecords(options, ctx) {
+    const { source, href } = capabilities(ctx);
+    const { model, path } = modelOf(options.model);
+    refuseFilter(options.filter);
+    let rows = await source.list(model);
+    if (typeof options.sort === 'string' && options.sort) {
+        const sort = options.sort;
+        if (!model.fields.some((f) => f.name === sort)) {
+            throw new Error(`${model.name} has no field ${sort}`);
+        }
+        const sign = options.direction === 'asc' ? 1 : -1;
+        rows = [...rows].sort((a, b) => sign * compare(a[sort], b[sort]));
+    }
+    const limit = numeric(options.limit) ? options.limit : 5;
+    const shown = rows.slice(0, limit);
+    return {
+        rows: await Promise.all(shown.map(async (row) => ({
+            id: String(row.id),
+            title: await recordLabel(source, model, row),
+        }))),
+        ...(rows.length > shown.length ? { total: rows.length } : {}),
+        href: href(path),
+    };
+}
+/**
+ * `shortcuts`: the section's menu entries as cards, as the shell resolves them
+ * (renames, hides, moves), each with its record count. `section` names another
+ * section by its id without the `section:` / `custom:` prefix; absent, the
+ * overview's own section.
+ */
+async function loadShortcuts(options, ctx) {
+    const { source, sections, entries } = capabilities(ctx);
+    const named = typeof options.section === 'string' ? options.section : '';
+    const sectionId = named
+        ? sections.find((s) => s.id === `section:${named}` || s.id === `custom:${named}`)?.id
+        : ctx.overviewId;
+    if (!sectionId)
+        throw new Error(`unknown section ${named}`);
+    const data = shortcutsFromNav(sections, sectionId);
+    const items = await Promise.all(data.items.map(async (item) => {
+        const entry = entries.get(item.id);
+        if (!entry)
+            return item;
+        const rows = await source.list(entry.model);
+        const count = recordCount(rows.filter((row) => inScope(entry.scope, row)).length);
+        return {
+            ...item,
+            // The count first: a long description is clipped.
+            description: item.description
+                ? `${count} · ${item.description}`
+                : count,
+        };
+    }));
+    return { items };
+}
+registerCoreWidgets(overviewRegistry, {
+    metric: loadMetric,
+    records: loadRecords,
+    shortcuts: loadShortcuts,
+});
+/** The core widget types a section overview offers. */
+export const CORE_WIDGET_TYPES = [
+    'shortcuts',
+    'metric',
+    'records',
+    'note',
+];
+/**
+ * How a recipe widget's `'<specifier>#<Export>'` becomes a module: a static map
+ * of dynamic imports, one entry per package that ships widgets. No published
+ * recipe declares a `widget` surface yet, so it is empty and every lookup is
+ * `undefined` (the widget then renders as unavailable).
+ */
+const RECIPE_WIDGET_MODULES = {};
+export const resolveRecipeExport = async (specifier, exportName) => {
+    const load = RECIPE_WIDGET_MODULES[specifier];
+    if (!load)
+        return undefined;
+    const module = (await load());
+    return module[exportName];
+};
+/** Recipes that declare at least one `widget` surface. */
+export const widgetRecipes = recipes.filter((recipe) => recipe.surfaces?.some((surface) => surface.kind === 'widget'));
+/**
+ * Widget types the recipes contribute, allowed on every section overview. A
+ * widget's own `allowedIn` still confines it.
+ */
+export const RECIPE_WIDGET_TYPES = widgetRecipes.flatMap((recipe) => (recipe.surfaces ?? []).flatMap((surface) => surface.kind === 'widget' ? [surface.type] : []));
+/**
+ * Register the recipes' widgets. Surfaces without a `migrate` register
+ * synchronously inside this call (the helper awaits only `migrate` exports), so
+ * validation at load sees them; the promise reports what was skipped.
+ */
+export const recipeWidgets = registerRecipeWidgets(overviewRegistry, widgetRecipes, resolveRecipeExport);

package/dist/overviews/validate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The cookbook's `overviews` field: one sparse smrt-svelte `OverviewOverride`
+ * per overview id. A stored override is untrusted data. Each one is checked
+ * with `checkOverviewOverride` against its page's definition; what fails (an
+ * unknown or disallowed widget type, options outside the widget's schema, an
+ * unknown overview id, a malformed entry) is dropped and reported, never
+ * rendered or loaded, and only the canonical override is kept.
+ */
+import { type OverviewIssue, type OverviewOverride } from '@happyvertical/smrt-svelte/overview';
+import type { ShellLayout } from '@happyvertical/smrt-svelte/workspace/layout';
+export type CookbookOverviews = Record<string, OverviewOverride>;
+export interface ParsedOverviews {
+    /** Canonical, non-empty overrides by overview id, keys sorted. */
+    overviews: CookbookOverviews;
+    /** One sentence per dropped override or widget. */
+    dropped: string[];
+}
+/**
+ * Check one stored override. `checkOverviewOverride` is strict (any issue
+ * rejects); when it rejects, the offending widgets are taken out and the rest
+ * checked again, so one bad widget does not cost the visitor the others.
+ */
+export declare function checkStoredOverride(id: string, raw: unknown): {
+    override: OverviewOverride | null;
+    issues: OverviewIssue[];
+};
+/**
+ * Read a cookbook's `overviews` value. `null` when it is not an object (the
+ * caller rejects the file, as for any malformed field); otherwise every entry
+ * is checked and what fails is dropped and reported.
+ */
+export declare function parseOverviews(input: unknown, layout: ShellLayout | undefined): ParsedOverviews | null;