@happyvertical/smrt-planner 0.0.2 → 0.1.1

package/dist/planner/host/session.svelte.js

@@ -0,0 +1,186 @@
+import { untrack } from 'svelte';
+import { cookbookStore } from "../../cookbook/store.svelte.js";
+import { parseCookbook } from "../../cookbook/validate.js";
+let mounted = false;
+/** One authoritative Kitchen plan projected into the stores the existing panels read. */
+export function createHostSession(callTool) {
+    let current = $state.raw(null);
+    let busy = $state(false);
+    let error = $state('');
+    let pendingPlanId = $state(null);
+    let draft = $state.raw(null);
+    let preservedDraft = $state.raw(null);
+    let pending = $state.raw(null);
+    let baseline = '';
+    let disposed = false;
+    const copy = (value) => JSON.parse(JSON.stringify(value));
+    function refresh(value) {
+        if (disposed)
+            return;
+        const payload = value;
+        const next = payload?.state
+            ? { planId: payload.planId, ...payload.state }
+            : value;
+        if (!next ||
+            typeof next.planId !== 'string' ||
+            !Number.isInteger(next.snapshot?.revision))
+            throw new Error('Kitchen did not return a plan snapshot.');
+        if (current && next.planId !== current.planId)
+            throw new Error('Kitchen returned a different plan.');
+        const parsed = parseCookbook(next.cookbook);
+        if (!parsed.ok)
+            throw new Error(parsed.error);
+        if (current && next.snapshot.revision < current.snapshot.revision)
+            return;
+        if (current && next.snapshot.revision === current.snapshot.revision)
+            return;
+        if (current && JSON.stringify(cookbookStore.snapshot()) !== baseline) {
+            preservedDraft ??= copy(cookbookStore.snapshot());
+            error =
+                'Kitchen updated the plan while you were editing. Your draft is preserved; dismiss it to keep editing.';
+        }
+        current = { ...next, cookbook: copy(parsed.cookbook) };
+        pendingPlanId = null;
+        cookbookStore.apply(current.cookbook);
+        cookbookStore.loaded = true;
+        baseline = JSON.stringify(cookbookStore.snapshot());
+    }
+    async function invoke() {
+        if (!pending || busy || disposed)
+            return;
+        busy = true;
+        error = '';
+        const submitted = draft;
+        try {
+            const result = (await callTool('run_commands', pending));
+            if (disposed)
+                return;
+            if (result?.state || (result?.snapshot && result?.cookbook))
+                refresh(result);
+            if (!result?.ok) {
+                pending = null;
+                preservedDraft ??= submitted ? copy(submitted) : null;
+                throw new Error(result?.error?.message ??
+                    'Kitchen rejected this edit. Your draft is preserved below; dismiss it to keep editing.');
+            }
+            pending = null;
+            if (draft === submitted)
+                draft = null;
+        }
+        catch (cause) {
+            if (!disposed) {
+                if (!pending)
+                    preservedDraft ??= submitted ? copy(submitted) : null;
+                error = cause instanceof Error ? cause.message : String(cause);
+            }
+        }
+        finally {
+            busy = false;
+        }
+    }
+    return {
+        get current() {
+            return current;
+        },
+        get busy() {
+            return busy;
+        },
+        get error() {
+            return error;
+        },
+        get pendingPlanId() {
+            return pendingPlanId;
+        },
+        get draft() {
+            return draft;
+        },
+        get preservedDraft() {
+            return preservedDraft;
+        },
+        dismissPreservedDraft() {
+            preservedDraft = null;
+            if (!pending)
+                error = '';
+        },
+        get retryable() {
+            return pending !== null;
+        },
+        /** Edits wait while a request is unresolved or a preserved draft is unacknowledged. */
+        get locked() {
+            return busy || pending !== null || preservedDraft !== null;
+        },
+        refresh,
+        reportError(cause) {
+            error = cause instanceof Error ? cause.message : String(cause);
+        },
+        receive(value) {
+            if (disposed)
+                return;
+            const id = value?.planId;
+            if (!current && typeof id === 'string')
+                pendingPlanId = id;
+            try {
+                refresh(value);
+                if (!pending && !draft)
+                    error = '';
+            }
+            catch (cause) {
+                error = cause instanceof Error ? cause.message : String(cause);
+            }
+        },
+        async connect(planId) {
+            try {
+                const result = await callTool('get_plan', { planId });
+                if (disposed)
+                    return;
+                refresh(result);
+                if (!pending && !draft)
+                    error = '';
+            }
+            catch (cause) {
+                if (!disposed)
+                    error = String(cause);
+            }
+        },
+        retry: invoke,
+        mount() {
+            if (mounted)
+                throw new Error('Only one host-backed Planner may be mounted in this document.');
+            mounted = true;
+            const stop = $effect.root(() => {
+                $effect(() => {
+                    const value = JSON.stringify(cookbookStore.snapshot());
+                    untrack(() => {
+                        if (!current || value === baseline || disposed)
+                            return;
+                        draft = JSON.parse(value);
+                        cookbookStore.apply(current.cookbook);
+                        baseline = JSON.stringify(cookbookStore.snapshot());
+                        if (busy || pending) {
+                            error =
+                                'An edit is already pending. Your additional draft is preserved.';
+                            return;
+                        }
+                        pending = {
+                            planId: current.planId,
+                            id: crypto.randomUUID(),
+                            expectedRevision: current.snapshot.revision,
+                            commands: [
+                                {
+                                    name: 'import_cookbook',
+                                    input: { document: draft, replace: true },
+                                },
+                            ],
+                        };
+                        void invoke();
+                    });
+                });
+            });
+            return () => {
+                disposed = true;
+                stop();
+                mounted = false;
+            };
+        },
+    };
+}

package/dist/planner/routes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The model pages' paths and how a route under `/m/` reads. One place for the
+ * static app (`src/routes/m/`), the mounted `Planner`'s hash router and every
+ * link to a record, so they agree:
+ *
+ * - `/m/<pkg>/<Model>/` the list; `?<fk>=<id>` narrows it to the rows whose
+ *   reference field `<fk>` points at the record `<id>` ("View all" on a
+ *   record's related panel).
+ * - `/m/<pkg>/<Model>/<key>/` a keyed nav entry (a model shown twice in the
+ *   menu); the key is known from the recipes.
+ * - `/m/<pkg>/<Model>/<id>/` a record's view page, `/<id>/edit/` its edit
+ *   page. A segment that is not a known key is a record id.
+ */
+import type { CatalogModel } from '../catalog/types.ts';
+import type { RowScope } from '../recipes/scope.ts';
+export type RecordMode = 'view' | 'edit';
+export interface ModelRoute {
+    packageId: string;
+    modelName: string;
+    /** The nav entry key, for a keyed entry page. */
+    view?: string;
+    /** The record the page shows, with how. */
+    recordId?: string;
+    mode?: RecordMode;
+}
+export declare function modelPath(packageId: string, modelName: string): string;
+export declare function recordPath(packageId: string, modelName: string, id: string, mode?: RecordMode): string;
+/** The list narrowed to the rows whose `field` points at the record `id`. */
+export declare function filteredListPath(packageId: string, modelName: string, field: string, id: string): string;
+/**
+ * Read the segments after `m/` (`['commerce', 'Order', <id>, 'edit']`).
+ * `isViewKey` says whether a third segment is a keyed nav entry of the model;
+ * otherwise it is a record id. `undefined` for a shape that is not a model
+ * page (`m/commerce/Order/x/y/` and the like).
+ */
+export declare function parseModelRoute(parts: readonly string[], isViewKey: (packageId: string, modelName: string, key: string) => boolean): ModelRoute | undefined;
+/** A fragment route (`/m/commerce/Order/?customerId=x`) split into path and query. */
+export declare function splitRoute(route: string): {
+    path: string;
+    search: string;
+};
+/**
+ * The `?<fk>=<id>` filter of a list page, when the query names a reference
+ * field of the model with a non-empty value. Any other parameter (the package
+ * selection, the Planner tab) is not a filter.
+ */
+export declare function recordFilter(search: string, model: Pick<CatalogModel, 'fields'>): RowScope | undefined;
+/** The `?<fk>=<id>` pair as a query fragment to keep in a list page's URL. */
+export declare function recordFilterQuery(scope: RowScope | undefined): string;

package/dist/planner/routes.js

@@ -0,0 +1,64 @@
+const REF_TYPES = new Set(['foreignKey', 'crossPackageRef']);
+export function modelPath(packageId, modelName) {
+    return `/m/${packageId}/${modelName}/`;
+}
+export function recordPath(packageId, modelName, id, mode = 'view') {
+    const base = `${modelPath(packageId, modelName)}${encodeURIComponent(id)}/`;
+    return mode === 'edit' ? `${base}edit/` : base;
+}
+/** The list narrowed to the rows whose `field` points at the record `id`. */
+export function filteredListPath(packageId, modelName, field, id) {
+    return `${modelPath(packageId, modelName)}?${encodeURIComponent(field)}=${encodeURIComponent(id)}`;
+}
+/**
+ * Read the segments after `m/` (`['commerce', 'Order', <id>, 'edit']`).
+ * `isViewKey` says whether a third segment is a keyed nav entry of the model;
+ * otherwise it is a record id. `undefined` for a shape that is not a model
+ * page (`m/commerce/Order/x/y/` and the like).
+ */
+export function parseModelRoute(parts, isViewKey) {
+    const [packageId, modelName, third, fourth, ...rest] = parts;
+    if (!packageId || !modelName || rest.length)
+        return undefined;
+    if (third === undefined)
+        return { packageId, modelName };
+    if (fourth === undefined) {
+        if (isViewKey(packageId, modelName, third)) {
+            return { packageId, modelName, view: third };
+        }
+        return { packageId, modelName, recordId: third, mode: 'view' };
+    }
+    if (fourth !== 'edit' || isViewKey(packageId, modelName, third)) {
+        return undefined;
+    }
+    return { packageId, modelName, recordId: third, mode: 'edit' };
+}
+/** A fragment route (`/m/commerce/Order/?customerId=x`) split into path and query. */
+export function splitRoute(route) {
+    const at = route.indexOf('?');
+    return at < 0
+        ? { path: route, search: '' }
+        : { path: route.slice(0, at), search: route.slice(at) };
+}
+/**
+ * The `?<fk>=<id>` filter of a list page, when the query names a reference
+ * field of the model with a non-empty value. Any other parameter (the package
+ * selection, the Planner tab) is not a filter.
+ */
+export function recordFilter(search, model) {
+    const params = new URLSearchParams(search);
+    for (const field of model.fields) {
+        if (!REF_TYPES.has(field.type))
+            continue;
+        const value = params.get(field.name);
+        if (value)
+            return { field: field.name, equals: value };
+    }
+    return undefined;
+}
+/** The `?<fk>=<id>` pair as a query fragment to keep in a list page's URL. */
+export function recordFilterQuery(scope) {
+    return scope?.equals !== undefined
+        ? `${encodeURIComponent(scope.field)}=${encodeURIComponent(scope.equals)}`
+        : '';
+}

package/dist/planner/shell.d.ts

@@ -0,0 +1,40 @@
+import type { AppShell, DockToggle } from '@happyvertical/smrt-svelte/app';
+import type { PanelEdge, ShellPanelDefaults } from '@happyvertical/smrt-svelte/workspace';
+import type { ComponentProps } from 'svelte';
+/**
+ * The Planner starts with its navigation open so footer controls stay in the
+ * left sidebar. Hosts embedding Planner can use the same shell defaults.
+ */
+export declare const PLANNER_SHELL_EDGE_TOGGLES: Partial<Record<PanelEdge, boolean>>;
+/** Panel defaults shared by Planner's static shell and embedding hosts. */
+export declare const PLANNER_SHELL_PANEL_DEFAULTS: ShellPanelDefaults;
+/**
+ * The shell's assistant control: the built-in `dock:assistant` item (a
+ * chat-bubble `header.end` button, the dock tab on phones) toggling the
+ * `assistant` `ShellDockTool`. Until the assistant can answer (`ready`, from
+ * `aiState.assistantReady`) the shell renders it as a link to `href`, the AI
+ * setup page, instead of opening an empty dock.
+ */
+export declare function plannerAssistantToggle(href: string, ready: boolean): DockToggle;
+type ShellUser = NonNullable<ComponentProps<typeof AppShell>['user']>;
+/**
+ * The visitor, as the shell's account item (`item:account`: full identity in
+ * the expanded sidebar footer, the compact avatar in the collapsed rail and on
+ * phones). A static demo has no sign-in, so this stands in for one.
+ */
+export declare const PLANNER_SHELL_USER: ShellUser;
+/** Props for an AppShell that hosts Planner. */
+export declare function plannerShellProps(): {
+    edgeToggles: Partial<Record<PanelEdge, boolean>>;
+    config: Partial<Record<PanelEdge, false | Partial<import("@happyvertical/smrt-svelte/workspace").ShellPanelConfig>>>;
+    hotkeys: boolean;
+    user: {
+        readonly id: string | null | undefined;
+        readonly email?: string | null;
+        readonly name?: string | null;
+        readonly avatarUrl?: string | null;
+    };
+    phoneTabBar: boolean;
+    phoneDock: "sheet";
+};
+export {};

package/dist/planner/shell.js

@@ -0,0 +1,56 @@
+/**
+ * The Planner starts with its navigation open so footer controls stay in the
+ * left sidebar. Hosts embedding Planner can use the same shell defaults.
+ */
+export const PLANNER_SHELL_EDGE_TOGGLES = {
+    left: true,
+};
+/** Panel defaults shared by Planner's static shell and embedding hosts. */
+export const PLANNER_SHELL_PANEL_DEFAULTS = {
+    left: { initial: 'expanded' },
+    right: { initial: 'collapsed', rail: false, presentation: 'overlay' },
+    bottom: { initial: 'hidden' },
+};
+/**
+ * The shell's assistant control: the built-in `dock:assistant` item (a
+ * chat-bubble `header.end` button, the dock tab on phones) toggling the
+ * `assistant` `ShellDockTool`. Until the assistant can answer (`ready`, from
+ * `aiState.assistantReady`) the shell renders it as a link to `href`, the AI
+ * setup page, instead of opening an empty dock.
+ */
+export function plannerAssistantToggle(href, ready) {
+    return {
+        tool: 'assistant',
+        label: 'Assistant',
+        labelNotReady: 'Set up the assistant',
+        href,
+        ready,
+    };
+}
+/**
+ * The visitor, as the shell's account item (`item:account`: full identity in
+ * the expanded sidebar footer, the compact avatar in the collapsed rail and on
+ * phones). A static demo has no sign-in, so this stands in for one.
+ */
+export const PLANNER_SHELL_USER = {
+    id: 'visitor',
+    slug: null,
+    created_at: null,
+    updated_at: null,
+    profileId: 'visitor',
+    email: '',
+    status: 'active',
+    lastLoginAt: null,
+    name: 'You',
+};
+/** Props for an AppShell that hosts Planner. */
+export function plannerShellProps() {
+    return {
+        edgeToggles: PLANNER_SHELL_EDGE_TOGGLES,
+        config: PLANNER_SHELL_PANEL_DEFAULTS,
+        hotkeys: false,
+        user: PLANNER_SHELL_USER,
+        phoneTabBar: true,
+        phoneDock: 'sheet',
+    };
+}

package/dist/planner/tab.svelte.d.ts

@@ -1,11 +1,14 @@
-export declare const PLANNER_TABS: readonly ["cookbooks", "recipes", "features", "layout", "settings", "export"];
+export declare const PLANNER_TABS: readonly ["cookbooks", "recipes", "features", "layout", "theme", "settings", "export"];
 export type PlannerTab = (typeof PLANNER_TABS)[number];
-/** `fallback` (Recipes) unless the query names another known tab. */
+/** `fallback` (Cookbooks) unless the query names another known tab. */
 export declare function parseTab(search: string, fallback?: PlannerTab): PlannerTab;
 /** The Planner page's active tab; the address bar mirrors it (`?tab=`). */
 declare class PlannerTabState {
-    active: "export" | "settings" | "features" | "recipes" | "layout" | "cookbooks";
+    active: "export" | "settings" | "features" | "recipes" | "theme" | "layout" | "cookbooks";
     fromSearch(search: string, fallback?: PlannerTab): void;
+    /** The chef's hat from Export: `#/configure/` names no tab, so leave Export
+     *  for the default rather than stay on it; any other tab is kept. */
+    leaveExport(fallback?: PlannerTab): void;
 }
 export declare const plannerTab: PlannerTabState;
 export {};

package/dist/planner/tab.svelte.js

@@ -4,19 +4,26 @@ export const PLANNER_TABS = [
     'recipes',
     'features',
     'layout',
+    'theme',
     'settings',
     'export',
 ];
-/** `fallback` (Recipes) unless the query names another known tab. */
-export function parseTab(search, fallback = 'recipes') {
+/** `fallback` (Cookbooks) unless the query names another known tab. */
+export function parseTab(search, fallback = 'cookbooks') {
     const value = new URLSearchParams(search).get(TAB_PARAM);
     return PLANNER_TABS.find((tab) => tab === value) ?? fallback;
 }
 /** The Planner page's active tab; the address bar mirrors it (`?tab=`). */
 class PlannerTabState {
-    active = $state('recipes');
-    fromSearch(search, fallback = 'recipes') {
+    active = $state('cookbooks');
+    fromSearch(search, fallback = 'cookbooks') {
         this.active = parseTab(search, fallback);
     }
+    /** The chef's hat from Export: `#/configure/` names no tab, so leave Export
+     *  for the default rather than stay on it; any other tab is kept. */
+    leaveExport(fallback = 'cookbooks') {
+        if (this.active === 'export')
+            this.active = fallback;
+    }
 }
 export const plannerTab = new PlannerTabState();

package/dist/planner/title.d.ts

@@ -0,0 +1,15 @@
+import type { Cookbook } from '../cookbook/types.ts';
+import type { LibraryCookbook } from '../library/types.ts';
+/** The shell's brand label when nothing names the app. */
+export declare const DEFAULT_PLANNER_TITLE = "Planner";
+/** What the title derivation reads of the cookbook document. */
+export type TitledCookbook = Pick<Cookbook, 'name' | 'recipes' | 'features'>;
+/**
+ * The app's title, for the shell brand and the page `<title>`: an explicit
+ * app name (`set_name`, carried in the cookbook document) wins; else the
+ * library cookbook the visitor applied and still holds (its friendly `name`,
+ * never its id); else `fallback` (a host's `defaultTitle`, "Planner" by default). A reset, a replacing import or removing the
+ * cookbook's recipes drops the library name the same way the Cookbooks tab
+ * stops marking it "in use".
+ */
+export declare function plannerTitle(cookbook: TitledCookbook, applied: string | null | undefined, library?: readonly LibraryCookbook[], fallback?: string): string;

package/dist/planner/title.js

@@ -0,0 +1,21 @@
+import { holdsCookbook } from "../library/apply.js";
+import { libraryCookbooks } from "../library/index.js";
+/** The shell's brand label when nothing names the app. */
+export const DEFAULT_PLANNER_TITLE = 'Planner';
+/**
+ * The app's title, for the shell brand and the page `<title>`: an explicit
+ * app name (`set_name`, carried in the cookbook document) wins; else the
+ * library cookbook the visitor applied and still holds (its friendly `name`,
+ * never its id); else `fallback` (a host's `defaultTitle`, "Planner" by default). A reset, a replacing import or removing the
+ * cookbook's recipes drops the library name the same way the Cookbooks tab
+ * stops marking it "in use".
+ */
+export function plannerTitle(cookbook, applied, library = libraryCookbooks, fallback = DEFAULT_PLANNER_TITLE) {
+    const name = cookbook.name?.trim();
+    if (name)
+        return name;
+    const entry = applied ? library.find((c) => c.id === applied) : undefined;
+    if (entry && holdsCookbook(entry, cookbook))
+        return entry.name;
+    return fallback;
+}

package/dist/planner/title.svelte.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The live app title over the module stores. Call it inside a `$derived` so
+ * a cookbook applied, imported, named or reset re-reads it. `fallback` is the
+ * title when no cookbook name or library cookbook applies.
+ */
+export declare function currentPlannerTitle(fallback?: string): string;

package/dist/planner/title.svelte.js

@@ -0,0 +1,11 @@
+import { cookbookStore } from "../cookbook/store.svelte.js";
+import { libraryState } from "../library/state.svelte.js";
+import { plannerTitle } from "./title.js";
+/**
+ * The live app title over the module stores. Call it inside a `$derived` so
+ * a cookbook applied, imported, named or reset re-reads it. `fallback` is the
+ * title when no cookbook name or library cookbook applies.
+ */
+export function currentPlannerTitle(fallback) {
+    return plannerTitle(cookbookStore.snapshot(), libraryState.active, undefined, fallback);
+}

package/dist/planner/types.d.ts

@@ -6,7 +6,7 @@ export interface PlannerHandle {
     /** Present when `inference` was given: a chat transport driven by the controller. */
     assistant?: PlannerAssistant;
 }
-/** The `Planner` component's props. */
+/** Shared props for the complete Planner and the separately mounted controls. */
 export interface PlannerProps {
     /**
      * The commands to drive the planner with and the snapshot to read. Defaults
@@ -15,16 +15,23 @@ export interface PlannerProps {
      */
     controller?: PlannerController;
     /**
-     * Where the planner's own pages are served from (`''`, `'/planner'`). Only
-     * links to planner pages use it; the component needs no router of its own.
+     * Where the customization controls' own pages are served from (`''`,
+     * `'/planner'`). The complete Planner uses fragment paths for its app
+     * sections and model pages, so it needs no host router.
      */
     basePath?: string;
-    /** A model for the planner's assistant; see `createPlannerAssistant`. */
+    /**
+     * A model for the planner's assistant; see `createPlannerAssistant`. The
+     * complete `Planner` then shows the assistant icon at the end of its
+     * header: it opens the chat dock once a model is ready and the AI models
+     * page (`#/ai/`, where a visitor downloads a model or connects their own
+     * endpoint) before. Without it the planner has no assistant.
+     */
     inference?: PlannerInference;
     /**
-     * `'own'` (the default) edits the menu layout on a headless controller built
-     * from the cookbook. `'shell'` edits the nearest smrt-svelte `AppShell`'s, as
-     * the static app does (it also holds panel and slot placements).
+     * `PlannerControls` uses `'own'` by default, editing the menu layout on a
+     * headless controller. `'shell'` edits the nearest smrt-svelte `AppShell`.
+     * The complete `Planner` always uses its own shell for these controls.
      */
     layout?: 'own' | 'shell';
     /**
@@ -35,7 +42,32 @@ export interface PlannerProps {
     persistence?: 'self' | 'host';
     /** Show the theme preset and light/dark controls (they need a theme provider). */
     themeControls?: boolean;
+    /** Link to the host's Advanced Styles page, when mounting controls alone. */
+    advancedStylesHref?: string;
+    /**
+     * The shell title shown when no cookbook name and no applied library
+     * cookbook names the app (the brand label, and the fallback for a section
+     * page without a heading). A host that calls the planner something else
+     * passes it here. Defaults to `'Planner'`. The complete `Planner` only.
+     */
+    defaultTitle?: string;
     /** Tabs to show, in order; defaults to all. */
     tabs?: readonly PlannerTabId[];
+    /**
+     * A host's way back, rendered at the start of the planner's header beside
+     * the brand (`{ href: '/', label: 'Back to documentation' }`). Off by
+     * default. The complete `Planner` only.
+     */
+    backLink?: PlannerBackLink;
+    /**
+     * Called once the planner is mounted, with its controller and (when
+     * `inference` was given) the assistant transport, for a host that drives
+     * the plan itself.
+     */
     onready?: (handle: PlannerHandle) => void;
 }
+/** A link out of the planner, shown in its header. */
+export interface PlannerBackLink {
+    href: string;
+    label: string;
+}

package/dist/products/media.d.ts

@@ -0,0 +1,20 @@
+import type { ModelRecord, RecordWrite } from '../data/source.ts';
+/** Canonical records used to attach an image to a product. */
+export declare const ASSET = "@happyvertical/smrt-assets:Asset";
+export declare const PRODUCT_ASSET = "@happyvertical/smrt-products:ProductAsset";
+/** The smrt-assets recipe whose library view is the product gallery. */
+export declare const GALLERY_RECIPE = "assets.library";
+export interface ProductImage {
+    id: string;
+    name: string;
+    sourceUri: string;
+    mimeType: string;
+    description: string;
+    sortOrder: number;
+}
+/** Image rows associated with one product, in the order the product declares. */
+export declare function productImages(productId: string, assets: readonly ModelRecord[], associations: readonly ModelRecord[]): ProductImage[];
+/** A single atomic browser-local image selection, stored in canonical records. */
+export declare function planProductImageSave(productId: string, file: Pick<File, 'name' | 'type'>, sourceUri: string, sortOrder: number): RecordWrite[];
+/** Removing a product removes its browser-demo associations and image rows too. */
+export declare function planProductImageDelete(productId: string, associations: readonly ModelRecord[]): RecordWrite[];

package/dist/products/media.js

@@ -0,0 +1,65 @@
+import { catalogModels } from "../forms/shared.js";
+/** Canonical records used to attach an image to a product. */
+export const ASSET = '@happyvertical/smrt-assets:Asset';
+export const PRODUCT_ASSET = '@happyvertical/smrt-products:ProductAsset';
+/** The smrt-assets recipe whose library view is the product gallery. */
+export const GALLERY_RECIPE = 'assets.library';
+/** Image rows associated with one product, in the order the product declares. */
+export function productImages(productId, assets, associations) {
+    const byId = new Map(assets.map((asset) => [asset.id, asset]));
+    return associations
+        .filter((link) => link.productId === productId)
+        .flatMap((link) => {
+        const asset = byId.get(String(link.assetId));
+        const sourceUri = asset?.sourceUri;
+        if (!asset || typeof sourceUri !== 'string')
+            return [];
+        return [
+            {
+                id: asset.id,
+                name: String(asset.name ?? 'Product image'),
+                sourceUri,
+                mimeType: String(asset.mimeType ?? 'image/*'),
+                description: String(asset.description ?? ''),
+                sortOrder: Number(link.sortOrder ?? 0),
+            },
+        ];
+    })
+        .sort((a, b) => a.sortOrder - b.sortOrder || a.name.localeCompare(b.name));
+}
+/** A single atomic browser-local image selection, stored in canonical records. */
+export function planProductImageSave(productId, file, sourceUri, sortOrder) {
+    return [
+        {
+            op: 'save',
+            as: 'asset',
+            model: catalogModels(ASSET),
+            values: {
+                name: file.name || 'Product image',
+                sourceUri,
+                mimeType: file.type || 'image/*',
+                description: `Image selected for this product in the browser demo.`,
+                sourceType: 'browser-demo',
+            },
+        },
+        {
+            op: 'save',
+            model: catalogModels(PRODUCT_ASSET),
+            values: {
+                productId,
+                assetId: { ref: 'asset' },
+                relationship: 'gallery',
+                sortOrder,
+            },
+        },
+    ];
+}
+/** Removing a product removes its browser-demo associations and image rows too. */
+export function planProductImageDelete(productId, associations) {
+    return associations
+        .filter((link) => link.productId === productId)
+        .flatMap((link) => [
+        { op: 'delete', model: catalogModels(PRODUCT_ASSET), id: link.id },
+        { op: 'delete', model: catalogModels(ASSET), id: String(link.assetId) },
+    ]);
+}