@happyvertical/smrt-planner 0.0.0-stage → 0.0.2

package/dist/cookbook/migrate.js

@@ -0,0 +1,106 @@
+import { legacyNavSectionKeys, navItemId, navSectionOf, recipeNav, recipes, } from "../recipes/index.js";
+const PREFIX = 'section:';
+/**
+ * Nav sections used to be one per group/recipe (`section:commerce.customers`,
+ * `section:products`); recipes now suggest shared ones (`section:sales`).
+ * Rewrites a saved layout's ids from the old keys to the new, once, in the
+ * loader. Idempotent: new ids are not old keys. Section-level hides of a
+ * renamed section are dropped (the merged section may hold other recipes'
+ * items, so one old hide must not hide them); everything else is mapped and
+ * de-duplicated, and ids nothing refers to any more are harmless to the shell.
+ */
+export function migrateLegacySections(layout, keys = legacyNavSectionKeys(recipes)) {
+    const olds = Object.keys(keys).sort((a, b) => b.length - a.length);
+    if (!olds.length)
+        return layout;
+    /** `section:<old>` -> `section:<new>`; `section:<old>:rest` likewise. */
+    const mapId = (id) => {
+        if (!id.startsWith(PREFIX))
+            return id;
+        const rest = id.slice(PREFIX.length);
+        for (const old of olds) {
+            if (rest === old)
+                return `${PREFIX}${keys[old]}`;
+            if (rest.startsWith(`${old}:`)) {
+                return `${PREFIX}${keys[old]}${rest.slice(old.length)}`;
+            }
+        }
+        return id;
+    };
+    const isRenamedSection = (id) => id.startsWith(PREFIX) && olds.includes(id.slice(PREFIX.length));
+    const unique = (ids) => [...new Set(ids)];
+    const next = { ...layout };
+    if (layout.sectionOrder)
+        next.sectionOrder = unique(layout.sectionOrder.map(mapId));
+    if (layout.hidden) {
+        next.hidden = unique(layout.hidden.filter((id) => !isRenamedSection(id)).map(mapId));
+    }
+    if (layout.itemOrder) {
+        const merged = {};
+        for (const [section, ids] of Object.entries(layout.itemOrder)) {
+            const key = mapId(section);
+            merged[key] = unique([...(merged[key] ?? []), ...ids.map(mapId)]);
+        }
+        next.itemOrder = merged;
+    }
+    if (layout.moved) {
+        next.moved = Object.fromEntries(Object.entries(layout.moved).map(([item, to]) => [
+            mapId(item),
+            mapId(to),
+        ]));
+    }
+    return next;
+}
+/**
+ * Old item ids were `section:<nav>:<pkg>:<Model>:<label>` (features
+ * `section:more:<pkg>:<Model>`); they are now `item:<pkg>:<Model>[:<key>]`
+ * (`navItemId`). Section ids (`section:<id>`, no further parts) are unchanged.
+ * Rewrites every id the layout holds (itemOrder, hidden, moved, items), keys
+ * and values alike. An entry declaring a `key` is matched exactly through the
+ * recipes; any other old id maps by its package and model. Idempotent (`item:`
+ * ids are left alone) and unknown ids stay as they are.
+ */
+export function migrateNavItemIds(layout, source = recipes) {
+    const keyed = new Map();
+    for (const recipe of source) {
+        const section = navSectionOf(recipe).id;
+        for (const entry of recipeNav(recipe)) {
+            if (!entry.key)
+                continue;
+            keyed.set(`${PREFIX}${section}:${entry.packageId}:${entry.model.name}:${entry.label}`, navItemId(entry.packageId, entry.model.name, entry.key));
+        }
+    }
+    const mapId = (id) => {
+        const exact = keyed.get(id);
+        if (exact)
+            return exact;
+        if (!id.startsWith(PREFIX))
+            return id;
+        // section : pkg : Model [: label]; a section id has no further parts.
+        const parts = id.slice(PREFIX.length).split(':');
+        if (parts.length < 3 || !parts[1] || !parts[2])
+            return id;
+        return navItemId(parts[1], parts[2]);
+    };
+    const unique = (ids) => [...new Set(ids)];
+    const remap = (record, value) => {
+        const out = {};
+        for (const [key, v] of Object.entries(record)) {
+            const next = mapId(key);
+            if (!(next in out))
+                out[next] = value(v);
+        }
+        return out;
+    };
+    const next = { ...layout };
+    if (layout.hidden)
+        next.hidden = unique(layout.hidden.map(mapId));
+    if (layout.itemOrder) {
+        next.itemOrder = remap(layout.itemOrder, (ids) => unique(ids.map(mapId)));
+    }
+    if (layout.moved)
+        next.moved = remap(layout.moved, mapId);
+    if (layout.items)
+        next.items = remap(layout.items, (item) => item);
+    return next;
+}

package/dist/cookbook/parse.d.ts

@@ -0,0 +1,16 @@
+import type { ShellLayout } from '@happyvertical/smrt-svelte/workspace/layout';
+import type { ParsedOverviews } from '../overviews/validate.ts';
+import { type CookbookResult } from './types.ts';
+/** Check a cookbook's `overviews` value; null when it is not an object. */
+export type OverviewParser = (input: unknown, layout: ShellLayout | undefined) => ParsedOverviews | null;
+export interface ParseCookbookOptions {
+    dropUnknownRecipes?: boolean;
+    /** The page-customisation check; absent: `overviews` are dropped and reported. */
+    overviews?: OverviewParser;
+}
+/**
+ * Check an unknown value (a parsed file or stored JSON) and return a
+ * normalised cookbook, or one clear sentence saying why not. Strict on
+ * purpose: nothing is silently dropped, so a bad file never half-applies.
+ */
+export declare function parseCookbookWith(input: unknown, options?: ParseCookbookOptions): CookbookResult;

package/dist/cookbook/parse.js

@@ -0,0 +1,246 @@
+import { recipesById } from "../recipes/index.js";
+import { withRequirements } from "../recipes/resolve.js";
+import { isSettingRow } from "../settings/app-settings.js";
+import { parseTheme } from "../theme/theme.js";
+import { migrateLegacySections, migrateNavItemIds } from "./migrate.js";
+import { COOKBOOK_SCHEMA, COOKBOOK_VERSION, PREVIOUS_SCHEMA, } from "./types.js";
+const VISIBILITIES = new Set(['basic', 'advanced', 'hidden']);
+const SURFACES = new Set(['api', 'mcp', 'cli']);
+const fail = (error) => ({ ok: false, error });
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isStrings = (value) => Array.isArray(value) && value.every((v) => typeof v === 'string');
+/** One policy row, or the reason it is not one. */
+function parseRow(value, at) {
+    if (!isObject(value))
+        return `${at} is not an object`;
+    const { objectRef, fieldName } = value;
+    if (typeof objectRef !== 'string' || !objectRef) {
+        return `${at} has no objectRef`;
+    }
+    if (typeof fieldName !== 'string' || !fieldName) {
+        return `${at} has no fieldName`;
+    }
+    if (value.scopeType !== 'app')
+        return `${at} must have scopeType "app"`;
+    const row = { objectRef, fieldName, scopeType: 'app' };
+    for (const key of ['defaultValue', 'help', 'label']) {
+        const v = value[key];
+        if (v === undefined)
+            continue;
+        if (typeof v !== 'string' && v !== null)
+            return `${at}.${key} is invalid`;
+        row[key] = v;
+    }
+    if (value.visibility !== undefined) {
+        const v = value.visibility;
+        if (v !== null && !(typeof v === 'string' && VISIBILITIES.has(v))) {
+            return `${at}.visibility is invalid`;
+        }
+        row.visibility = v;
+    }
+    if (value.displayOrder !== undefined) {
+        const v = value.displayOrder;
+        if (v !== null && !(typeof v === 'number' && Number.isFinite(v))) {
+            return `${at}.displayOrder is invalid`;
+        }
+        row.displayOrder = v;
+    }
+    if (value.locked !== undefined) {
+        if (value.locked !== null && typeof value.locked !== 'boolean') {
+            return `${at}.locked is invalid`;
+        }
+        row.locked = value.locked;
+    }
+    return row;
+}
+/** Strictly checked here; the shell's `normalizeShellLayout` is lenient. */
+function parseLayout(value) {
+    if (!isObject(value) || value.version !== 1) {
+        return 'layout must be an object with version 1';
+    }
+    for (const key of ['sectionOrder', 'hidden']) {
+        if (value[key] !== undefined && !isStrings(value[key])) {
+            return `layout.${key} must be a list of strings`;
+        }
+    }
+    for (const key of ['itemOrder', 'moved', 'panels']) {
+        if (value[key] !== undefined && !isObject(value[key])) {
+            return `layout.${key} must be an object`;
+        }
+    }
+    const itemOrder = value.itemOrder;
+    if (isObject(itemOrder)) {
+        for (const [key, ids] of Object.entries(itemOrder)) {
+            if (key === '__proto__' || !isStrings(ids))
+                return `layout.itemOrder.${key} must be a list of strings`;
+        }
+    }
+    const moved = value.moved;
+    if (isObject(moved)) {
+        for (const [key, to] of Object.entries(moved)) {
+            if (key === '__proto__' || typeof to !== 'string')
+                return `layout.moved.${key} must be a string`;
+        }
+    }
+    return value;
+}
+/**
+ * Check an unknown value (a parsed file or stored JSON) and return a
+ * normalised cookbook, or one clear sentence saying why not. Strict on
+ * purpose: nothing is silently dropped, so a bad file never half-applies.
+ */
+export function parseCookbookWith(input, options = {}) {
+    if (!isObject(input))
+        return fail('This is not a cookbook: expected a JSON object.');
+    if (input.$schema !== undefined &&
+        input.$schema !== COOKBOOK_SCHEMA &&
+        input.$schema !== PREVIOUS_SCHEMA) {
+        return fail('This is not a cookbook: its "$schema" is not a cookbook schema this planner knows.');
+    }
+    const { version } = input;
+    if (version === undefined) {
+        return fail('This is not a cookbook: it has no "version".');
+    }
+    if (typeof version !== 'number' || !Number.isInteger(version)) {
+        return fail('The cookbook "version" must be a whole number.');
+    }
+    if (version > COOKBOOK_VERSION) {
+        return fail(`This cookbook is version ${version}, newer than this planner understands (${COOKBOOK_VERSION}). Update the planner or re-export it.`);
+    }
+    if (version !== COOKBOOK_VERSION) {
+        return fail(`Cookbook version ${version} is not supported (this planner reads version ${COOKBOOK_VERSION}).`);
+    }
+    if (!isStrings(input.recipes)) {
+        return fail('The cookbook "recipes" must be a list of recipe ids.');
+    }
+    // Ids this version does not know (renamed, removed, or from a newer
+    // catalog) are kept in the document, not applied: dropping them here would
+    // make the loss permanent on the next save. The store surfaces them.
+    const unknown = input.recipes.filter((id) => !recipesById.has(id));
+    const recipes = [
+        ...new Set([
+            ...withRequirements(input.recipes.filter((id) => recipesById.has(id)), recipesById),
+            ...unknown,
+        ]),
+    ].sort();
+    // Absent in files from before features: read as none.
+    let features = [];
+    if (input.features !== undefined) {
+        if (!isStrings(input.features)) {
+            return fail('The cookbook "features" must be a list of model names.');
+        }
+        const seen = new Set();
+        for (const name of input.features) {
+            if (seen.has(name)) {
+                return fail(`The cookbook lists the feature ${name} more than once.`);
+            }
+            seen.add(name);
+        }
+        // Features this catalog lacks are kept like unknown recipes.
+        features = [...input.features].sort();
+    }
+    // Options only mean something for models an added recipe or feature covers, as in the
+    // app itself; dropping the rest keeps export then import an exact round trip.
+    const covered = new Set([
+        ...recipes.flatMap((id) => recipesById.get(id)?.models ?? []),
+        ...features,
+    ]);
+    if (!Array.isArray(input.policies)) {
+        return fail('The cookbook "policies" must be a list.');
+    }
+    const policies = [];
+    for (const [index, value] of input.policies.entries()) {
+        const row = parseRow(value, `policies[${index}]`);
+        if (typeof row === 'string')
+            return fail(`Invalid cookbook: ${row}.`);
+        if (covered.has(row.objectRef) || isSettingRow(row))
+            policies.push(row);
+    }
+    let exposure;
+    if (input.exposure !== undefined) {
+        if (!isObject(input.exposure)) {
+            return fail('The cookbook "exposure" must be an object.');
+        }
+        const entries = [];
+        for (const [ref, surfaces] of Object.entries(input.exposure)) {
+            if (!isStrings(surfaces) || !surfaces.every((s) => SURFACES.has(s))) {
+                return fail(`Invalid cookbook: exposure for ${ref} must list api, mcp or cli.`);
+            }
+            if (surfaces.length && covered.has(ref)) {
+                entries.push([ref, [...surfaces]]);
+            }
+        }
+        // fromEntries defines own keys, so a "__proto__" ref cannot rewrite the prototype.
+        exposure = Object.fromEntries(entries);
+    }
+    let layout;
+    if (input.layout !== undefined) {
+        const parsed = parseLayout(input.layout);
+        if (typeof parsed === 'string')
+            return fail(`Invalid cookbook: ${parsed}.`);
+        layout = migrateNavItemIds(migrateLegacySections(parsed));
+    }
+    let theme;
+    if (input.theme !== undefined) {
+        const parsed = parseTheme(input.theme);
+        if (parsed.ok)
+            theme = parsed.theme;
+        // A saved value from an older build may name a preset this one lacks:
+        // keep the rest rather than discarding the visitor's work.
+        else if (!options.dropUnknownRecipes)
+            return fail(parsed.error);
+    }
+    // Untrusted: every override is checked against its page's definition; bad
+    // widgets and unknown pages are dropped and reported, never rendered.
+    let overviews;
+    let dropped = [];
+    if (input.overviews !== undefined) {
+        if (!options.overviews) {
+            if (!isObject(input.overviews)) {
+                return fail('The cookbook "overviews" must be an object.');
+            }
+            if (Object.keys(input.overviews).length) {
+                dropped = [
+                    'Page customisations (overviews) are not kept by this host and were dropped.',
+                ];
+            }
+        }
+        else {
+            const parsed = options.overviews(input.overviews, layout);
+            if (!parsed) {
+                return fail('The cookbook "overviews" must be an object.');
+            }
+            overviews = parsed.overviews;
+            dropped = parsed.dropped;
+        }
+    }
+    const cookbook = {
+        $schema: COOKBOOK_SCHEMA,
+        version: COOKBOOK_VERSION,
+        recipes,
+        features,
+        policies,
+    };
+    for (const key of ['name', 'description']) {
+        const value = input[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== 'string') {
+            return fail(`The cookbook "${key}" must be a string.`);
+        }
+        if (value.trim())
+            cookbook[key] = value.trim();
+    }
+    if (exposure && Object.keys(exposure).length)
+        cookbook.exposure = exposure;
+    if (layout)
+        cookbook.layout = layout;
+    if (theme)
+        cookbook.theme = theme;
+    if (overviews && Object.keys(overviews).length) {
+        cookbook.overviews = overviews;
+    }
+    return dropped.length
+        ? { ok: true, cookbook, dropped }
+        : { ok: true, cookbook };
+}

package/dist/cookbook/storage.d.ts

@@ -0,0 +1,45 @@
+import type { Cookbook } from './types.ts';
+/**
+ * The cookbook's localStorage key. The version is in the key so a future
+ * format reads the old key and migrates it; an unknown version is never
+ * guessed at. (`smrt-planner:cookbook` alone is the library selection.)
+ */
+export declare const STORAGE_KEY = "smrt-planner:cookbook-doc:v1";
+/**
+ * Where the document lived while it was called a blueprint. It is read once
+ * when the new key is empty and kept as the backup until the next save.
+ */
+export declare const PREVIOUS_STORAGE_KEY = "smrt-planner:blueprint:v1";
+/** A value that could not be read is kept here, never silently overwritten. */
+export declare const UNREADABLE_KEY = "smrt-planner:cookbook-doc:unreadable";
+/** The cookbook a legacy link replaced, so opening a link loses nothing. */
+export declare const BACKUP_KEY = "smrt-planner:cookbook-doc:backup";
+export type LoadOutcome = {
+    status: 'unavailable';
+} | {
+    status: 'empty';
+} | {
+    status: 'loaded';
+    cookbook: Cookbook;
+    /**
+     * The previous (blueprint) key still holds a value. It is kept as a
+     * backup and removed by the first successful save of the new key.
+     */
+    previousKept: boolean;
+    /** Overview customisations dropped as invalid, one sentence each. */
+    dropped?: string[];
+} | {
+    status: 'unreadable';
+    reason: string;
+    /** Whether the raw value was copied to UNREADABLE_KEY. */
+    keptAside: boolean;
+};
+/** The browser's localStorage, or null when reaching for it throws. */
+export declare function browserStorage(): Storage | null;
+/** Read the saved cookbook. Never throws. */
+export declare function loadCookbook(storage: Storage | null): LoadOutcome;
+/** Write a value under a key; false when storage refused. Never throws. */
+export declare function writeKey(storage: Storage | null, key: string, value: string): boolean;
+/** Remove a key; false when storage refused. Never throws. */
+export declare function removeKey(storage: Storage | null, key: string): boolean;
+export declare function saveCookbook(storage: Storage | null, cookbook: Cookbook): boolean;

package/dist/cookbook/storage.js

@@ -0,0 +1,98 @@
+import { parseCookbookText } from "./validate.js";
+/**
+ * The cookbook's localStorage key. The version is in the key so a future
+ * format reads the old key and migrates it; an unknown version is never
+ * guessed at. (`smrt-planner:cookbook` alone is the library selection.)
+ */
+export const STORAGE_KEY = 'smrt-planner:cookbook-doc:v1';
+/**
+ * Where the document lived while it was called a blueprint. It is read once
+ * when the new key is empty and kept as the backup until the next save.
+ */
+export const PREVIOUS_STORAGE_KEY = 'smrt-planner:blueprint:v1';
+/** A value that could not be read is kept here, never silently overwritten. */
+export const UNREADABLE_KEY = 'smrt-planner:cookbook-doc:unreadable';
+/** The cookbook a legacy link replaced, so opening a link loses nothing. */
+export const BACKUP_KEY = 'smrt-planner:cookbook-doc:backup';
+/** The browser's localStorage, or null when reaching for it throws. */
+export function browserStorage() {
+    try {
+        return globalThis.localStorage ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read the saved cookbook. Never throws. */
+export function loadCookbook(storage) {
+    if (!storage)
+        return { status: 'unavailable' };
+    let raw;
+    try {
+        raw = storage.getItem(STORAGE_KEY);
+    }
+    catch {
+        return { status: 'unavailable' };
+    }
+    let previous = null;
+    try {
+        previous = storage.getItem(PREVIOUS_STORAGE_KEY);
+    }
+    catch {
+        // Treated as absent.
+    }
+    // Nothing under the new key: migrate the value saved while it was a blueprint.
+    const fromPrevious = raw === null && previous !== null;
+    const source = fromPrevious ? previous : raw;
+    if (source === null)
+        return { status: 'empty' };
+    // A saved cookbook from an older build may name recipes this one no longer
+    // has: they are kept in the document (and noticed by the store), and a
+    // theme preset this build lacks is dropped rather than discarding the rest.
+    const parsed = parseCookbookText(source, { dropUnknownRecipes: true });
+    if (parsed.ok) {
+        // Write the migrated document under the new key now; the old key stays as
+        // a backup until the next successful save. If this write fails the old
+        // key simply remains the only copy.
+        if (fromPrevious) {
+            writeKey(storage, STORAGE_KEY, JSON.stringify(parsed.cookbook));
+        }
+        return {
+            status: 'loaded',
+            cookbook: parsed.cookbook,
+            previousKept: previous !== null,
+            ...(parsed.dropped ? { dropped: parsed.dropped } : {}),
+        };
+    }
+    raw = source;
+    // Keep what we could not read; the next save would otherwise destroy it.
+    const keptAside = writeKey(storage, UNREADABLE_KEY, raw);
+    return { status: 'unreadable', reason: parsed.error, keptAside };
+}
+/** Write a value under a key; false when storage refused. Never throws. */
+export function writeKey(storage, key, value) {
+    if (!storage)
+        return false;
+    try {
+        storage.setItem(key, value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove a key; false when storage refused. Never throws. */
+export function removeKey(storage, key) {
+    if (!storage)
+        return false;
+    try {
+        storage.removeItem(key);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function saveCookbook(storage, cookbook) {
+    return writeKey(storage, STORAGE_KEY, JSON.stringify(cookbook));
+}

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

@@ -0,0 +1,94 @@
+import type { OverviewOverride } from '@happyvertical/smrt-svelte/overview/server';
+import { type ShellLayout } from '@happyvertical/smrt-svelte/workspace/layout';
+import { type AppSettings } from '../settings/app-settings.ts';
+import { type ThemeSetting } from '../theme/theme.ts';
+import type { Cookbook, CookbookResult } from './types.ts';
+/** Where the planner's AppShell keeps its own settings (panel states, sizes). */
+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';
+/**
+ * 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
+ * `layout` field and the persistence around both. `snapshot()` is the
+ * Cookbook, whether it is saved, exported or compared.
+ */
+export declare class CookbookStore {
+    /** The shell layout, owned here and passed to `AppShell`. */
+    layout: ShellLayout | undefined;
+    /** The app's name and description (`set_name`); not shown in the UI yet. */
+    name: string | undefined;
+    description: string | undefined;
+    /** The app's theme; undefined is the default. The shell applies it live. */
+    theme: ThemeSetting | undefined;
+    /**
+     * Customised overview pages by overview id, canonical overrides only. Each
+     * page's `createOverview` reads its entry and writes edits back here.
+     */
+    overviews: Record<string, OverviewOverride>;
+    persist: PersistState;
+    /** False until the saved cookbook has been read; nothing saves before. */
+    loaded: boolean;
+    /** Why the saved cookbook was not used, if it was not. */
+    loadNotice: string;
+    /**
+     * True when saving would destroy the only copy of something (an unreadable
+     * value that could not be kept aside, or a saved cookbook a legacy link
+     * replaced without a backup). Nothing is written until the visitor imports
+     * or resets.
+     */
+    private saveBlocked;
+    /** A migrated legacy link whose data is not safely stored: keep the URL. */
+    keepLegacyUrl: boolean;
+    /** A cookbook was chosen (cookbook, import) before the saved one was read. */
+    private replacedBeforeLoad;
+    /** The pre-rename key still holds a backup; the next good save removes it. */
+    private previousKept;
+    private storage;
+    private timer;
+    snapshot(): Cookbook;
+    /** A page's stored override, or `null` when it is on its defaults. */
+    overview(id: string): OverviewOverride | null;
+    /**
+     * An edit from an overview page: the controller's canonical override, or
+     * `null` (back to the defaults), which removes the page's key.
+     */
+    setOverview(id: string, override: OverviewOverride | null): void;
+    /** An edit from the shell or its layout editor; an empty one clears it. */
+    setLayout(next: ShellLayout): void;
+    /** Replace everything from a validated cookbook. */
+    apply(cookbook: Cookbook): void;
+    /**
+     * A sentence naming recipes and features the loaded cookbook has that this
+     * version does not know (they are kept, not applied), or ''.
+     */
+    get unavailableNotice(): string;
+    /** Remove the unavailable ids from the cookbook, on the visitor's say. */
+    removeUnavailable(): void;
+    /** Change the theme; the default (or an empty one) clears it. */
+    setTheme(next: ThemeSetting | undefined): void;
+    /** The app settings (currency, tax rate, payment terms), read from the policy rows. */
+    settings(): AppSettings;
+    /** Write the settings as policy rows. Existing records are untouched. */
+    setSettings(settings: AppSettings): void;
+    /** Replace on the visitor's say-so (an import): saving is allowed again. */
+    replace(cookbook: Cookbook): void;
+    /** Back to an empty cookbook, and the shell's own settings to defaults. */
+    reset(): void;
+    /** Validate and apply JSON text, e.g. a chosen file. Applies nothing on failure. */
+    importText(text: string): CookbookResult;
+    /**
+     * Read the saved cookbook, then migrate a legacy `?r=` / `?o=` link into it.
+     * Call once in the browser, before `loaded` lets saving start. Returns true
+     * when a legacy link was imported, so the caller can clean the URL.
+     */
+    hydrate(search: string, storage?: Storage | null): boolean;
+    /** Save now. Falls back to memory-only (and says so) if storage refuses. */
+    save(): boolean;
+    /** Save soon; many quick edits make one write. */
+    scheduleSave(): void;
+    /** Save any pending change now (page hide). */
+    flush(): void;
+}
+export declare const cookbookStore: CookbookStore;