@happyvertical/smrt-svelte 0.55.7 → 0.55.9

package/dist/components/overview/model.js

@@ -0,0 +1,460 @@
+/**
+ * The pure overview data model (#3727): parse untrusted JSON, merge a stored
+ * override onto the page defaults, derive the sparse override back from an
+ * edited document, and sanitize a document against the widget registry.
+ *
+ * Everything here is total and never throws on bad input: unknown, invalid
+ * or disallowed widgets are dropped and reported as {@link OverviewIssue}s,
+ * never executed. Svelte-free; runs on the server on save and on load.
+ */
+import { optionsEqual, validateWidgetOptions } from './schema.js';
+import { OVERVIEW_DEFAULT_MAX_WIDGETS, OVERVIEW_ID_PATTERN, OVERVIEW_MAX_SPAN, OVERVIEW_MIN_SPAN, OVERVIEW_PAGE_ID_PATTERN, } from './types.js';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isSpan(value) {
+    return (typeof value === 'number' &&
+        Number.isInteger(value) &&
+        value >= OVERVIEW_MIN_SPAN &&
+        value <= OVERVIEW_MAX_SPAN);
+}
+function primitiveOptions(raw) {
+    if (raw === undefined)
+        return {};
+    if (!isRecord(raw))
+        return null;
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === null ||
+            typeof value === 'string' ||
+            typeof value === 'boolean' ||
+            (typeof value === 'number' && Number.isFinite(value))) {
+            out[key] = value;
+        }
+        else {
+            return null;
+        }
+    }
+    return out;
+}
+/** Shape-check one widget; `null` when it is not a widget at all. */
+function parseWidget(raw, issues) {
+    const id = isRecord(raw) && typeof raw.id === 'string' ? raw.id : null;
+    const type = isRecord(raw) && typeof raw.type === 'string' ? raw.type : null;
+    const malformed = (message) => {
+        issues.push({ widgetId: id, type, code: 'malformed', message });
+        return null;
+    };
+    if (!isRecord(raw))
+        return malformed('widget is not an object');
+    if (id === null || !OVERVIEW_ID_PATTERN.test(id)) {
+        return malformed('widget id is missing or invalid');
+    }
+    if (type === null)
+        return malformed('widget type is missing');
+    if (!isSpan(raw.span)) {
+        issues.push({
+            widgetId: id,
+            type,
+            code: 'invalid_span',
+            message: 'span must be an integer from 1 to 4',
+        });
+        return null;
+    }
+    const options = primitiveOptions(raw.options);
+    if (options === null) {
+        issues.push({
+            widgetId: id,
+            type,
+            code: 'invalid_options',
+            message: 'options must be an object of primitive values',
+        });
+        return null;
+    }
+    const widget = { id, type, span: raw.span, options };
+    if (raw.version !== undefined) {
+        if (typeof raw.version !== 'number' ||
+            !Number.isSafeInteger(raw.version) ||
+            raw.version < 1) {
+            return malformed('version must be a positive integer');
+        }
+        widget.version = raw.version;
+    }
+    return widget;
+}
+/** Parse untrusted JSON into a document. Malformed widgets are dropped. */
+export function parseOverviewDocument(input) {
+    const issues = [];
+    const widgets = [];
+    const list = isRecord(input) && Array.isArray(input.widgets) ? input.widgets : null;
+    if (list === null) {
+        if (input !== undefined && input !== null) {
+            issues.push({
+                widgetId: null,
+                type: null,
+                code: 'malformed',
+                message: 'overview must be an object with a widgets array',
+            });
+        }
+        return { document: { widgets }, issues };
+    }
+    const seen = new Set();
+    for (const raw of list) {
+        const widget = parseWidget(raw, issues);
+        if (!widget)
+            continue;
+        if (seen.has(widget.id)) {
+            issues.push({
+                widgetId: widget.id,
+                type: widget.type,
+                code: 'duplicate_id',
+                message: 'widget id appears more than once',
+            });
+            continue;
+        }
+        seen.add(widget.id);
+        widgets.push(widget);
+    }
+    return { document: { widgets }, issues };
+}
+/**
+ * Parse an untrusted stored override. Never throws; an unknown version, or
+ * anything that is not an object, yields `null` (no override).
+ */
+export function parseOverviewOverride(input) {
+    const issues = [];
+    if (input === undefined || input === null)
+        return { override: null, issues };
+    if (!isRecord(input) || input.version !== 1) {
+        issues.push({
+            widgetId: null,
+            type: null,
+            code: 'malformed',
+            message: 'override must be an object with version 1',
+        });
+        return { override: null, issues };
+    }
+    const override = { version: 1 };
+    const ids = (value) => {
+        if (!Array.isArray(value))
+            return undefined;
+        const out = value.filter((id) => typeof id === 'string' && OVERVIEW_ID_PATTERN.test(id));
+        return [...new Set(out)];
+    };
+    const order = ids(input.order);
+    if (order?.length)
+        override.order = order;
+    const removed = ids(input.removed);
+    if (removed?.length)
+        override.removed = removed;
+    if (Array.isArray(input.added)) {
+        const { document } = parseOverviewDocument({ widgets: input.added });
+        if (document.widgets.length)
+            override.added = document.widgets;
+        const dropped = input.added.length - document.widgets.length;
+        if (dropped > 0) {
+            issues.push({
+                widgetId: null,
+                type: null,
+                code: 'malformed',
+                message: `${dropped} added widget(s) were malformed and dropped`,
+            });
+        }
+    }
+    if (isRecord(input.changed)) {
+        const changed = {};
+        for (const [id, raw] of Object.entries(input.changed)) {
+            if (!OVERVIEW_ID_PATTERN.test(id) || !isRecord(raw))
+                continue;
+            const patch = {};
+            if (isSpan(raw.span))
+                patch.span = raw.span;
+            const options = raw.options === undefined ? undefined : primitiveOptions(raw.options);
+            if (options)
+                patch.options = options;
+            if (typeof raw.version === 'number' &&
+                Number.isSafeInteger(raw.version) &&
+                raw.version >= 1) {
+                patch.version = raw.version;
+            }
+            if (Object.keys(patch).length)
+                changed[id] = patch;
+        }
+        if (Object.keys(changed).length)
+            override.changed = changed;
+    }
+    return { override: isEmptyOverride(override) ? null : override, issues };
+}
+/** True when an override changes nothing. */
+export function isEmptyOverride(override) {
+    return (override === null ||
+        (!override.order?.length &&
+            !override.removed?.length &&
+            !override.added?.length &&
+            !Object.keys(override.changed ?? {}).length));
+}
+function cloneWidget(widget) {
+    const copy = {
+        id: widget.id,
+        type: widget.type,
+        span: widget.span,
+        options: { ...widget.options },
+    };
+    if (widget.version !== undefined)
+        copy.version = widget.version;
+    return copy;
+}
+/**
+ * Merge an override onto a base document. Total: ids the base no longer has
+ * are ignored, added widgets whose id collides with the base are skipped, and
+ * widgets the order does not list keep their slots (listed ids permute among
+ * the slots they occupy), so a default shipped later still appears.
+ */
+export function applyOverviewOverride(base, override) {
+    if (isEmptyOverride(override) || override === null) {
+        return { widgets: base.widgets.map(cloneWidget) };
+    }
+    const removed = new Set(override.removed ?? []);
+    const baseIds = new Set(base.widgets.map((widget) => widget.id));
+    const widgets = [];
+    for (const widget of base.widgets) {
+        if (removed.has(widget.id))
+            continue;
+        const next = cloneWidget(widget);
+        const patch = override.changed?.[widget.id];
+        if (patch) {
+            if (patch.span !== undefined)
+                next.span = patch.span;
+            if (patch.options !== undefined)
+                next.options = { ...patch.options };
+            if (patch.version !== undefined)
+                next.version = patch.version;
+        }
+        widgets.push(next);
+    }
+    for (const widget of override.added ?? []) {
+        if (baseIds.has(widget.id))
+            continue;
+        widgets.push(cloneWidget(widget));
+    }
+    const order = override.order;
+    if (order?.length) {
+        const byId = new Map(widgets.map((widget) => [widget.id, widget]));
+        const listed = order.filter((id, index) => byId.has(id) && order.indexOf(id) === index);
+        const listedSet = new Set(listed);
+        const queue = listed.map((id) => byId.get(id));
+        let cursor = 0;
+        return {
+            widgets: widgets.map((widget) => listedSet.has(widget.id) ? queue[cursor++] : widget),
+        };
+    }
+    return { widgets };
+}
+/**
+ * The sparse override that turns `base` into `next` (the inverse of
+ * {@link applyOverviewOverride}); `null` when they are the same. Both
+ * documents should already be sanitized so versions compare like for like.
+ */
+export function diffOverview(base, next) {
+    const baseById = new Map(base.widgets.map((widget) => [widget.id, widget]));
+    const nextIds = new Set(next.widgets.map((widget) => widget.id));
+    const override = { version: 1 };
+    const removed = base.widgets
+        .filter((widget) => !nextIds.has(widget.id))
+        .map((widget) => widget.id);
+    if (removed.length)
+        override.removed = removed;
+    const added = next.widgets
+        .filter((widget) => !baseById.has(widget.id))
+        .map(cloneWidget);
+    if (added.length)
+        override.added = added;
+    const changed = {};
+    for (const widget of next.widgets) {
+        const original = baseById.get(widget.id);
+        if (!original)
+            continue;
+        const patch = {};
+        if (widget.span !== original.span)
+            patch.span = widget.span;
+        const versionChanged = (widget.version ?? 1) !== (original.version ?? 1);
+        if (!optionsEqual(widget.options, original.options) || versionChanged) {
+            patch.options = { ...widget.options };
+            if (widget.version !== undefined)
+                patch.version = widget.version;
+        }
+        if (Object.keys(patch).length)
+            changed[widget.id] = patch;
+    }
+    if (Object.keys(changed).length)
+        override.changed = changed;
+    const natural = applyOverviewOverride(base, override).widgets.map((w) => w.id);
+    const wanted = next.widgets.map((widget) => widget.id);
+    if (natural.some((id, index) => id !== wanted[index]))
+        override.order = wanted;
+    return isEmptyOverride(override) ? null : override;
+}
+/**
+ * The next unused widget id (`w1`, `w2`, ...) given every reserved id.
+ *
+ * Total for any reserved ids, including hostile stored ones such as
+ * `w9007199254740992`: only numeric suffixes that are safe integers below
+ * `Number.MAX_SAFE_INTEGER` raise the starting point (beyond it `n + 1` stops
+ * changing the number, which would loop forever), and when the high end is
+ * exhausted the scan restarts at `w1`. The reserved set is finite, so a free
+ * id is found within `size + 1` steps of the restart.
+ */
+export function nextWidgetId(reserved) {
+    const taken = new Set(reserved);
+    let n = 1;
+    for (const id of taken) {
+        const match = /^w(\d+)$/.exec(id);
+        if (!match)
+            continue;
+        const value = Number(match[1]);
+        if (Number.isSafeInteger(value) && value < Number.MAX_SAFE_INTEGER) {
+            n = Math.max(n, value + 1);
+        }
+    }
+    while (n < Number.MAX_SAFE_INTEGER && taken.has(`w${n}`))
+        n += 1;
+    if (!taken.has(`w${n}`))
+        return `w${n}`;
+    // The high end is exhausted: take the first free id counting up from 1.
+    for (n = 1; taken.has(`w${n}`); n += 1)
+        ;
+    return `w${n}`;
+}
+/**
+ * Sanitize a document against the registry and the page's confined set:
+ * drops (and reports) unknown types, types the page does not allow or the
+ * widget refuses (`allowedIn`), future versions, failed migrations, invalid
+ * options, duplicate ids and widgets over the cap; migrates older option
+ * versions; clamps spans to the widget's range. Idempotent. Nothing here
+ * calls a widget's `load`.
+ */
+export function sanitizeOverview(document, { registry, definition }) {
+    const issues = [];
+    const widgets = [];
+    const seen = new Set();
+    const cap = definition.maxWidgets ?? OVERVIEW_DEFAULT_MAX_WIDGETS;
+    const drop = (widget, code, message, extra = {}) => {
+        issues.push({
+            widgetId: widget.id,
+            type: widget.type,
+            code,
+            message,
+            ...extra,
+        });
+    };
+    for (const widget of document.widgets) {
+        if (seen.has(widget.id)) {
+            drop(widget, 'duplicate_id', 'widget id appears more than once');
+            continue;
+        }
+        seen.add(widget.id);
+        const def = registry.get(widget.type);
+        if (!def) {
+            drop(widget, 'unknown_type', 'widget type is not registered');
+            continue;
+        }
+        if ((definition.allowed && !definition.allowed.includes(widget.type)) ||
+            (def.allowedIn && !def.allowedIn.includes(definition.id))) {
+            drop(widget, 'type_not_allowed', 'widget type is not allowed in this overview');
+            continue;
+        }
+        if (widgets.length >= cap) {
+            drop(widget, 'too_many', `an overview holds at most ${cap} widgets`);
+            continue;
+        }
+        const stored = widget.version ?? 1;
+        let raw = widget.options;
+        if (stored > def.version) {
+            drop(widget, 'future_version', 'options were written by a newer widget version');
+            continue;
+        }
+        if (stored < def.version) {
+            let migrated = null;
+            try {
+                migrated = def.migrate
+                    ? def.migrate({ ...widget.options }, stored)
+                    : null;
+            }
+            catch {
+                migrated = null;
+            }
+            if (!migrated || !isRecord(migrated)) {
+                drop(widget, 'migration_failed', `no migration from version ${stored}`);
+                continue;
+            }
+            raw = migrated;
+        }
+        const checked = validateWidgetOptions(def.options, raw, {
+            models: definition.models,
+        });
+        if (!checked.ok) {
+            drop(widget, 'invalid_options', 'options do not match the widget schema', {
+                options: checked.issues,
+            });
+            continue;
+        }
+        widgets.push({
+            id: widget.id,
+            type: widget.type,
+            span: Math.min(def.maxSpan, Math.max(def.minSpan, widget.span)),
+            options: checked.options,
+            version: def.version,
+        });
+    }
+    return { document: { widgets }, issues };
+}
+/**
+ * Resolve an overview: sanitize the page defaults, parse the stored override
+ * (untrusted JSON), merge, and sanitize the result. This is the one call a
+ * page's server load makes before loading widget data.
+ */
+export function resolveOverview(definition, override, registry) {
+    const defaults = sanitizeOverview({ widgets: [...definition.defaults] }, {
+        registry,
+        definition,
+    });
+    const parsed = parseOverviewOverride(override);
+    const merged = applyOverviewOverride(defaults.document, parsed.override);
+    const final = sanitizeOverview(merged, { registry, definition });
+    return {
+        base: defaults.document,
+        document: final.document,
+        override: parsed.override,
+        issues: [...defaults.issues, ...parsed.issues, ...final.issues],
+        overrideIssues: [...parsed.issues, ...final.issues],
+    };
+}
+/**
+ * Validate an override a client wants to save. Strict where load is lenient:
+ * any issue rejects the save. On success the returned override is canonical
+ * (re-derived from the sanitized result), so persist that, not the input.
+ */
+export function checkOverviewOverride(definition, input, registry) {
+    const resolved = resolveOverview(definition, input, registry);
+    if (resolved.overrideIssues.length > 0) {
+        return { ok: false, issues: resolved.overrideIssues };
+    }
+    return { ok: true, override: diffOverview(resolved.base, resolved.document) };
+}
+/** Validate and freeze a page's overview declaration. */
+export function defineOverview(definition) {
+    if (!OVERVIEW_PAGE_ID_PATTERN.test(definition.id)) {
+        throw new Error(`defineOverview: invalid overview id "${definition.id}"`);
+    }
+    const ids = new Set();
+    for (const widget of definition.defaults) {
+        if (!OVERVIEW_ID_PATTERN.test(widget.id) || ids.has(widget.id)) {
+            throw new Error(`defineOverview: invalid or duplicate widget id "${widget.id}"`);
+        }
+        ids.add(widget.id);
+    }
+    return Object.freeze({
+        ...definition,
+        defaults: Object.freeze([...definition.defaults]),
+    });
+}

package/dist/components/overview/recipe-widgets.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Recipe widgets (#3727, phase 2): turn the `widget` surfaces of manifest
+ * recipes into widget-registry registrations.
+ *
+ * The manifest names a widget's component, server loader and migration as
+ * `'<module specifier>#<ExportName>'` references and never imports them. This
+ * helper receives the module resolver from the host, so nothing is imported at
+ * scan time or when the manifest is read; the host decides how a specifier
+ * becomes a module (a static map of dynamic imports in a bundled app).
+ *
+ * Svelte-free apart from type imports, so a server load can call it.
+ */
+import type { RecipeDefinition, RecipeExportRef } from '@happyvertical/smrt-types';
+import type { WidgetRegistry } from './registry.js';
+/**
+ * Resolves one export of a module: `resolveExport('@acme/shop/svelte',
+ * 'SalesTotal')`. The host owns this (import map, dynamic import, or a test
+ * stub); it may reject or return `undefined` for something it does not know.
+ */
+export type RecipeExportResolver = (specifier: string, exportName: string) => unknown | Promise<unknown>;
+/** The part of a recipe this helper reads; a manifest `RecipeDefinition` fits. */
+export type RecipeWidgetSource = Pick<RecipeDefinition, 'id'> & Partial<Pick<RecipeDefinition, 'surfaces'>>;
+export interface RegisterRecipeWidgetsOptions {
+    /** Replace a type that is already registered instead of skipping it. */
+    replace?: boolean;
+    /**
+     * Whether a recipe is on in this app. Widgets of a recipe that is off are
+     * not registered, so they never appear in an add list. Default: all on.
+     */
+    enabled?: (recipeId: string) => boolean;
+}
+export type RecipeWidgetSkipReason = 
+/** The type is already registered (a core widget or another recipe). */
+'duplicate_type'
+/** The surface does not form a valid widget definition. */
+ | 'invalid'
+/** A module export the registration needs eagerly could not be resolved. */
+ | 'unresolved';
+/** A widget surface that was not registered, and why. */
+export interface RecipeWidgetSkip {
+    recipeId: string;
+    type: string;
+    reason: RecipeWidgetSkipReason;
+    /** Developer-facing detail; not localized. */
+    message: string;
+}
+export interface RecipeWidgetRegistration {
+    /** Registered widget types, in registration order. */
+    registered: string[];
+    skipped: RecipeWidgetSkip[];
+    /** Removes exactly the registrations this call made. */
+    dispose: () => void;
+}
+/** Split `'<specifier>#<Name>'`; refuses relative and absolute specifiers. */
+export declare function parseRecipeExportRef(ref: RecipeExportRef | string): {
+    specifier: string;
+    exportName: string;
+} | null;
+/**
+ * Register every `widget` surface of `recipes` on `registry`.
+ *
+ * - Components resolve lazily (`loadComponent`); a page resolves them before
+ *   render with `resolveWidgetComponents`, and one that cannot resolve renders
+ *   as unavailable.
+ * - The server loader resolves on the first `load`; a failure becomes that
+ *   widget's error tile.
+ * - `migrate` is synchronous in the registry, so its export is resolved here,
+ *   before registering; if that fails the widget is skipped.
+ * - Nothing here validates option values: `registry.register` validates the
+ *   schema and spans, and a stored overview is validated against the result
+ *   as for any widget.
+ *
+ * Never throws for a bad surface: it is reported in `skipped` so one broken
+ * package cannot take down the overview.
+ */
+export declare function registerRecipeWidgets(registry: WidgetRegistry, recipes: Iterable<RecipeWidgetSource>, resolveExport: RecipeExportResolver, options?: RegisterRecipeWidgetsOptions): Promise<RecipeWidgetRegistration>;
+//# sourceMappingURL=recipe-widgets.d.ts.map

package/dist/components/overview/recipe-widgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipe-widgets.d.ts","sourceRoot":"","sources":["../../../src/components/overview/recipe-widgets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EAEhB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAWpD;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,KACf,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,kFAAkF;AAClF,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,GAC3D,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC,CAAC;AAE9C,MAAM,WAAW,4BAA4B;IAC3C,wEAAwE;IACxE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CACzC;AAED,MAAM,MAAM,sBAAsB;AAChC,wEAAwE;AACtE,gBAAgB;AAClB,2DAA2D;GACzD,SAAS;AACX,4EAA4E;GAC1E,YAAY,CAAC;AAEjB,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,sBAAsB,CAAC;IAC/B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,sDAAsD;IACtD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,wDAAwD;IACxD,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,eAAe,GAAG,MAAM,GAC5B;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAUlD;AAqFD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACrC,aAAa,EAAE,oBAAoB,EACnC,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,wBAAwB,CAAC,CAyDnC"}

package/dist/components/overview/recipe-widgets.js

@@ -0,0 +1,151 @@
+/** Split `'<specifier>#<Name>'`; refuses relative and absolute specifiers. */
+export function parseRecipeExportRef(ref) {
+    const at = ref.lastIndexOf('#');
+    if (at <= 0 || at === ref.length - 1)
+        return null;
+    const specifier = ref.slice(0, at);
+    const exportName = ref.slice(at + 1);
+    if (specifier.startsWith('.') || specifier.startsWith('/'))
+        return null;
+    if (/\s/.test(specifier) || !/^[A-Za-z_$][\w$]*$/.test(exportName)) {
+        return null;
+    }
+    return { specifier, exportName };
+}
+function resolveRef(ref, resolveExport) {
+    const parsed = parseRecipeExportRef(ref);
+    if (!parsed)
+        return Promise.reject(new Error(`invalid export ref "${ref}"`));
+    return Promise.resolve(resolveExport(parsed.specifier, parsed.exportName)).then((value) => {
+        if (value === undefined || value === null) {
+            throw new Error(`export "${ref}" was not found`);
+        }
+        return value;
+    });
+}
+/** Resolve once and share the result (and a failure) between callers. */
+function once(make) {
+    let pending;
+    return () => {
+        pending ??= make();
+        return pending;
+    };
+}
+function isModuleWithDefault(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'default' in value &&
+        !!value.default);
+}
+function toDefinition(surface, resolveExport, migrate) {
+    const component = once(() => resolveRef(surface.export, resolveExport));
+    const loadFn = surface.data?.load
+        ? once(() => resolveRef(surface.data?.load, resolveExport))
+        : undefined;
+    const def = {
+        type: surface.type,
+        title: surface.label,
+        options: surface.options ?? [],
+        loadComponent: async () => {
+            const value = await component();
+            return (isModuleWithDefault(value) ? value.default : value);
+        },
+    };
+    if (surface.description !== undefined)
+        def.description = surface.description;
+    if (surface.icon !== undefined)
+        def.icon = surface.icon;
+    if (surface.version !== undefined)
+        def.version = surface.version;
+    if (surface.allowedIn)
+        def.allowedIn = surface.allowedIn;
+    if (surface.defaultSpan !== undefined)
+        def.defaultSpan = surface.defaultSpan;
+    if (surface.minSpan !== undefined)
+        def.minSpan = surface.minSpan;
+    if (surface.maxSpan !== undefined)
+        def.maxSpan = surface.maxSpan;
+    if (migrate)
+        def.migrate = migrate;
+    if (loadFn) {
+        const load = async (options, ctx) => {
+            const fn = await loadFn();
+            if (typeof fn !== 'function') {
+                throw new Error(`loader "${surface.data?.load}" is not a function`);
+            }
+            return fn(options, ctx);
+        };
+        def.load = load;
+    }
+    return def;
+}
+/**
+ * Register every `widget` surface of `recipes` on `registry`.
+ *
+ * - Components resolve lazily (`loadComponent`); a page resolves them before
+ *   render with `resolveWidgetComponents`, and one that cannot resolve renders
+ *   as unavailable.
+ * - The server loader resolves on the first `load`; a failure becomes that
+ *   widget's error tile.
+ * - `migrate` is synchronous in the registry, so its export is resolved here,
+ *   before registering; if that fails the widget is skipped.
+ * - Nothing here validates option values: `registry.register` validates the
+ *   schema and spans, and a stored overview is validated against the result
+ *   as for any widget.
+ *
+ * Never throws for a bad surface: it is reported in `skipped` so one broken
+ * package cannot take down the overview.
+ */
+export async function registerRecipeWidgets(registry, recipes, resolveExport, options = {}) {
+    const registered = [];
+    const skipped = [];
+    const disposers = [];
+    for (const recipe of recipes) {
+        if (options.enabled && !options.enabled(recipe.id))
+            continue;
+        for (const surface of recipe.surfaces ?? []) {
+            if (surface.kind !== 'widget')
+                continue;
+            const skip = (reason, message) => skipped.push({
+                recipeId: recipe.id,
+                type: surface.type,
+                reason,
+                message,
+            });
+            if (registry.has(surface.type) && !options.replace) {
+                skip('duplicate_type', `"${surface.type}" is already registered`);
+                continue;
+            }
+            let migrate;
+            if (surface.migrate) {
+                try {
+                    const fn = await resolveRef(surface.migrate, resolveExport);
+                    if (typeof fn !== 'function')
+                        throw new Error('not a function');
+                    migrate = fn;
+                }
+                catch (error) {
+                    skip('unresolved', `migrate "${surface.migrate}": ${error instanceof Error ? error.message : String(error)}`);
+                    continue;
+                }
+            }
+            try {
+                disposers.push(registry.register(toDefinition(surface, resolveExport, migrate), {
+                    replace: options.replace,
+                }));
+                registered.push(surface.type);
+            }
+            catch (error) {
+                skip('invalid', error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    return {
+        registered,
+        skipped,
+        dispose: () => {
+            for (const dispose of disposers.splice(0))
+                dispose();
+        },
+    };
+}