@scaffold-ui-kit/preview 0.0.0-stage → 2.3.0

package/dist/controller/create-preview-controller.js

@@ -0,0 +1,1707 @@
+// The preview controller: the behavior of the preview with no UI of its own.
+// It holds what is selected, the scenario, the option values, which target
+// panes are shown (html's among them, where the kit builds html), whether each
+// has loaded and how large its content is, the
+// scenario editor's tree and the regeneration of the scratch story, and it owns the iframes: a shell
+// hands it elements to mount them in and never speaks to them itself, the
+// selection's panes and detached panes of any story alike. It keeps the
+// selection, the scenario, the root props, the visible targets, the story
+// panes' width and the option values in the host page's query parameters once
+// a person acts, and
+// the global option values in local storage when the kit asks.
+// A shell's own options ride along, namespaced under `shell.`, and never
+// reach the iframes. Every input is passed in, so it runs the same in a
+// browser and in a test.
+import { acceptsOptionValue, optionDefaults, shellOptionId, } from '../options.js';
+import { catalogMessage, codeFrameUrl, codeMessage, componentFrameUrl, globalsMessage, isPreviewMessage, markupMessage, PREVIEW_MESSAGE, PREVIEW_TARGETS, propsMessage, readContentSize, setStoryMessage, standaloneFrameUrl, viewFrameUrl, } from '../protocol.js';
+import { defaultScenarioId, nodeAddSlots, nodeSlots, storyFrameKey, } from './catalog.js';
+import { cleanRecord, DEFAULT_SLOT, ensureIds, insertAt, isContainer, moveNode, nodeAt, pathKey, removeAt, resolveSortableMove, seedComponentNode, seedRoot, slotsKey, stableStringify, toPayload, updateAt, } from './editor-tree.js';
+import { isPlaceholder, printSourceStory, resolveSourceStory, } from './source.js';
+import { changedProps, isPaneWidth, parseTargets, parseOptionValue, parsePaneWidth, parseProps, readStoredOptions, readUrlState, storageKey, writeStoredOptions, writeUrlState, } from './persistence.js';
+/** The time edits coalesce for before the preview regenerates what they
+ *  change, in milliseconds: the scratch story, and a story's html from the
+ *  development server. */
+export const REGENERATION_DEBOUNCE_MILLISECONDS = 250;
+/** The story id the regenerated scratch story is mounted under. */
+export const SCRATCH_STORY_ID = 'scratch';
+/**
+ * The attribute the controller sets on an iframe it mounted once the iframe
+ * shows its first content, and takes away while it loads again. Until then
+ * the iframe is hidden; a shell's CSS can show a loading note beside one
+ * without it.
+ */
+export const PREVIEW_FRAME_SHOWN_ATTRIBUTE = 'data-preview-shown';
+/** How many recorded events `state.events` keeps. */
+const EVENT_LOG_LENGTH = 100;
+/** Each target's source language, as a code block's highlighter names it. */
+const CODE_LANGUAGES = {
+    react: 'tsx',
+    vue: 'vue',
+    svelte: 'svelte',
+    html: 'html',
+};
+/** A story's props without its slot content, which the Empty scenario strips. */
+function withoutContent(props) {
+    const { children: _children, ...rest } = props;
+    return rest;
+}
+/** The text of a tree's root when its default slot holds one text node and
+ *  nothing else. */
+function rootText(tree) {
+    const nodes = tree.slots[DEFAULT_SLOT];
+    return nodes?.length === 1 && nodes[0].kind === 'text'
+        ? nodes[0].value
+        : undefined;
+}
+function withoutUndefined(props) {
+    const out = {};
+    for (const [name, value] of Object.entries(props))
+        if (value !== undefined)
+            out[name] = value;
+    return out;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function sameTargets(a, b) {
+    return (a.length === b.length && a.every((target, index) => target === b[index]));
+}
+const DEFAULT_TIMERS = {
+    setTimeout: (callback, milliseconds) => setTimeout(callback, milliseconds),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+/**
+ * The props a scripted pane mounts its story with: the story's, less each
+ * prop it unsets with `null`, which the pane leaves out as the story's code
+ * does, so the component's own default applies. A two-way prop given `null`
+ * stays: the story controls it at `null`, as its code binds it.
+ *
+ * @param props - The story's root props.
+ * @param component - The story's root component, for its two-way props.
+ * @returns The props without those unset with `null`.
+ */
+function paneProps(props, component) {
+    const twoWay = new Set((component?.bindings ?? []).map((binding) => binding.prop));
+    return Object.fromEntries(Object.entries(props).filter(([name, value]) => value !== null || twoWay.has(name)));
+}
+/**
+ * Create a preview controller.
+ *
+ * @param controllerOptions - The catalog, the options and the environment.
+ * @returns The controller.
+ * @example
+ * ```ts
+ * const controller = createPreviewController({
+ *   catalog: catalogFromManifest(manifest, views),
+ *   options: previewOptions,
+ *   regeneration: createFetchRegenerationTransport(),
+ * });
+ * const stop = controller.subscribe((state) => render(state));
+ * controller.actions.selectComponent('components-button');
+ * ```
+ */
+export function createPreviewController(controllerOptions) {
+    const { catalog, regeneration } = controllerOptions;
+    const options = [
+        ...controllerOptions.options.map(({ apply: _apply, ...option }) => ({
+            ...option,
+            origin: 'kit',
+        })),
+        ...(controllerOptions.shellOptions ?? []).map((option) => ({
+            ...option,
+            id: shellOptionId(option.id),
+            scope: 'global',
+            origin: 'shell',
+        })),
+    ];
+    const shellOptionIds = new Set(options
+        .filter((option) => option.origin === 'shell')
+        .map((option) => option.id));
+    const hostWindow = controllerOptions.window ?? globalThis.window;
+    const timers = controllerOptions.timers ?? DEFAULT_TIMERS;
+    const baseUrl = controllerOptions.baseUrl ?? '/';
+    const storage = controllerOptions.persistence === 'url-and-local-storage'
+        ? resolveStorage()
+        : undefined;
+    const storedOptionsKey = storageKey(catalog.kitName);
+    function resolveStorage() {
+        if (controllerOptions.storage)
+            return controllerOptions.storage;
+        try {
+            // Reading `localStorage` itself throws where storage is blocked.
+            return hostWindow?.localStorage ?? undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const listeners = new Set();
+    const frames = [];
+    const stories = catalog.components.filter((component) => component.standalone);
+    // The stories a reader browses: an unlisted one is reachable at its address
+    // and selectable by id, but never listed or selected first.
+    const listedStories = stories.filter((component) => !component.unlisted);
+    const componentById = (id) => catalog.components.find((component) => component.id === id);
+    const componentByName = (name) => catalog.components.find((component) => component.name === name);
+    // The catalog a custom view builds its context from: the browseable stories.
+    const catalogPayload = {
+        kitName: catalog.kitName,
+        sources: catalog.sources,
+        components: listedStories.map((component) => ({
+            id: component.id,
+            title: component.title,
+            source: component.source,
+        })),
+    };
+    // --- what the state derives from --------------------------------------------
+    let globalValues = optionDefaults(options, 'global');
+    let storyOverrides = {};
+    const kitTargets = PREVIEW_TARGETS.filter((target) => catalog.targets.includes(target));
+    const visibleTargets = new Set(PREVIEW_TARGETS);
+    const storyOptionIds = options
+        .filter((option) => option.scope === 'story')
+        .map((option) => option.id);
+    // The root props the selected scenario seeded: the address carries the
+    // props only while they differ from these.
+    let seededProps = {};
+    // The editor tree's slot content as it was seeded, for `editor.modified`.
+    let seededSlots = '';
+    // Whether the panes render the regenerated scratch story or the real one.
+    let scratchActive = false;
+    // The panes' story mounts so far: each set-story the host broadcasts is one.
+    let storyMount = 0;
+    let reloadCount = 0;
+    let regenerationTimer = null;
+    let regenerationSequence = 0;
+    function storyDefaultsFor(component) {
+        const base = optionDefaults(options, 'story');
+        for (const [id, value] of Object.entries(component?.options ?? {})) {
+            if (value !== false)
+                base[id] = value;
+        }
+        return base;
+    }
+    function unavailableOptionsFor(component) {
+        return Object.entries(component?.options ?? {})
+            .filter(([, value]) => value === false)
+            .map(([id]) => id);
+    }
+    function mergedOptions(component) {
+        return {
+            ...globalValues,
+            ...storyDefaultsFor(component),
+            ...storyOverrides,
+        };
+    }
+    /** The values the iframes apply: the kit's options alone. */
+    function kitValues(values) {
+        if (shellOptionIds.size === 0)
+            return values;
+        const kit = {};
+        for (const [id, value] of Object.entries(values))
+            if (!shellOptionIds.has(id))
+                kit[id] = value;
+        return kit;
+    }
+    /** The kit's global option values, for a code block: it shows source, not
+     *  a story, so a story option has nothing there to set. */
+    function codeValues(values) {
+        const global = { ...kitValues(values) };
+        for (const id of storyOptionIds)
+            delete global[id];
+        return global;
+    }
+    /** The values a detached pane of `component` applies: the global values,
+     *  the story options as selecting the component would seed them, and the
+     *  values its scenario sets over those. */
+    function detachedOptions(component, scenarioValues = {}) {
+        return kitValues({
+            ...globalValues,
+            ...storyDefaultsFor(component),
+            ...scenarioValues,
+        });
+    }
+    /** The option values a scenario of `component` sets that apply to it: the
+     *  kit's options it names, with a value each accepts, less those the
+     *  component makes unavailable. */
+    function scenarioOptionValues(component, scenarioId) {
+        const carried = component.scenarios.find((candidate) => candidate.id === scenarioId)?.options;
+        const values = {};
+        if (!carried)
+            return values;
+        const unavailable = unavailableOptionsFor(component);
+        for (const [id, value] of Object.entries(carried)) {
+            const option = options.find((candidate) => candidate.id === id && candidate.origin === 'kit');
+            if (option &&
+                !unavailable.includes(id) &&
+                acceptsOptionValue(option, value))
+                values[id] = value;
+        }
+        return values;
+    }
+    /**
+     * Set the option values a scenario of `component` carries, the way
+     * `setOption` sets a value: a global one for the session, a story one over
+     * the story's own until another story is selected. Picking a scenario
+     * that carries none leaves every value as it is.
+     *
+     * @returns Which kinds of value changed: whether any did, and whether a
+     *   global one did, which detached panes follow.
+     */
+    function applyScenarioOptions(component, scenarioId) {
+        const values = scenarioOptionValues(component, scenarioId);
+        let globalChanged = false;
+        for (const [id, value] of Object.entries(values)) {
+            const option = options.find((candidate) => candidate.id === id);
+            if (option.scope === 'story') {
+                storyOverrides = { ...storyOverrides, [id]: value };
+            }
+            else {
+                globalChanged ||= globalValues[id] !== value;
+                globalValues = { ...globalValues, [id]: value };
+            }
+        }
+        return { changed: Object.keys(values).length > 0, globalChanged };
+    }
+    function targetsFor(component) {
+        // Every story has an html pane where the kit builds html: one with no
+        // markup says why.
+        const supported = kitTargets.filter((target) => target === 'html' || (component?.targets.includes(target) ?? true));
+        const visible = kitTargets.filter((target) => visibleTargets.has(target));
+        return {
+            supported,
+            visible,
+            panes: visible.filter((target) => supported.includes(target)),
+        };
+    }
+    /** The props an address may set: those the component declares, and the
+     *  text of its default slot as `children` when it has one. */
+    function addressableProps(component) {
+        const declaresChildren = component.propTypes.some((propType) => propType.name === 'children');
+        return component.slots.default && !declaresChildren
+            ? [...component.propTypes, { name: 'children', control: 'text' }]
+            : component.propTypes;
+    }
+    /** The props as the address holds them: those that differ from the
+     *  scenario's, and each prop of the scenario's the story leaves out as
+     *  `null`, so that a link opens on what renders and stays short however
+     *  much data the story's props hold. While the story renders from a tree
+     *  (the editor, or Empty), `children` is the tree's content, which the
+     *  address does not hold, so a missing `children` is not marked. */
+    function addressedProps(component, props) {
+        const addressable = new Set(addressableProps(component).map(({ name }) => name));
+        return changedProps(props, seededProps, (name) => addressable.has(name) && !(name === 'children' && state.editor.tree));
+    }
+    /**
+     * Whether the story of the tree's root draws its default slot from the
+     * string `children` prop, having no default-slot content of its own. The
+     * editor holds that `children` as the root's text, so it can be edited,
+     * wrapped or replaced like any node, and `state.props` shows the root's
+     * lone text as `children`. A story with content of its own renders that
+     * content and not `children`, so its tree's text is never `children`.
+     */
+    function drawsChildren(tree) {
+        const root = componentByName(tree.root);
+        const selected = selectedComponent();
+        // The selection's own story is read as its scenario shows it.
+        const shown = root !== undefined && selected?.name === root.name
+            ? onScenario(root, state.scenario)
+            : root;
+        return !shown?.content?.default;
+    }
+    /** The root props a tree shows: its own, and, where the story draws its
+     *  default slot from `children`, its root's lone text as `children`. */
+    function treeProps(tree) {
+        const text = drawsChildren(tree) ? rootText(tree) : undefined;
+        return text === undefined ? tree.props : { ...tree.props, children: text };
+    }
+    function seedProps(component, scenarioId) {
+        const scenario = component.scenarios.find((candidate) => candidate.id === scenarioId);
+        const props = { ...component.defaultProps, ...(scenario?.props ?? {}) };
+        // The placeholder text a component with no content starts from is the
+        // preview's own; a scenario that fills the default slot replaces it.
+        if (scenario?.content?.default !== undefined &&
+            component.previewDefaults?.children !== undefined &&
+            !('children' in (scenario.props ?? {}))) {
+            delete props.children;
+        }
+        return props;
+    }
+    /** The scenario of `component` with slot content of its own, by id. */
+    function contentScenario(component, scenarioId) {
+        const scenario = component.scenarios.find((candidate) => candidate.id === scenarioId);
+        return scenario?.content === undefined ? undefined : scenario;
+    }
+    /** The id the panes mount `component`'s story by on a scenario: the
+     *  scenario's own story when it has content of its own, else the
+     *  component's. */
+    function paneStoryId(component, scenarioId) {
+        return contentScenario(component, scenarioId)?.story ?? component.id;
+    }
+    /** `component` as a scenario shows it: with the scenario's content in
+     *  place of the story's, for a scenario that has its own. */
+    function onScenario(component, scenarioId) {
+        const scenario = contentScenario(component, scenarioId);
+        return scenario ? { ...component, content: scenario.content } : component;
+    }
+    /** The component each scenario story renders, by the story's id. */
+    const scenarioStoryComponents = new Map(stories.flatMap((component) => component.scenarios.flatMap((scenario) => scenario.story === undefined
+        ? []
+        : [[scenario.story, component]])));
+    const first = listedStories[0] ?? stories[0];
+    seededProps = first ? seedProps(first, defaultScenarioId(first)) : {};
+    let state = {
+        selection: { kind: 'component', id: first?.id ?? '' },
+        scenario: defaultScenarioId(first),
+        props: seededProps,
+        options: mergedOptions(first),
+        unavailableOptions: unavailableOptionsFor(first),
+        targets: targetsFor(first),
+        frames: {},
+        storyFrames: {},
+        frameSizes: {},
+        frameErrors: {},
+        events: [],
+        storyFrameSizes: {},
+        editor: { open: false, modified: false },
+        regeneration: { status: 'idle' },
+    };
+    function selectedComponent() {
+        return state.selection.kind === 'component'
+            ? componentById(state.selection.id)
+            : undefined;
+    }
+    function commit(changes) {
+        state = withCode({ ...state, ...changes });
+        persist();
+        postHtml();
+        postCode();
+        for (const listener of listeners)
+            listener(state);
+    }
+    // --- the source ------------------------------------------------------------
+    // The scripted targets' source is printed whenever what the panes show changes; the
+    // html is asked of the server, or read from what the static build printed,
+    // once per story, and a request for a story since replaced is dropped.
+    let sourcedFrom;
+    let htmlKey;
+    let htmlTimer = null;
+    let htmlAbort;
+    let htmlSequence = 0;
+    const STATIC_EDITED_REASON = 'The static build prints html for the scenarios alone: there is none for changed props or edited content.';
+    function cancelHtml() {
+        if (htmlTimer !== null) {
+            timers.clearTimeout(htmlTimer);
+            htmlTimer = null;
+        }
+        htmlAbort?.abort();
+        htmlAbort = undefined;
+        htmlSequence += 1;
+    }
+    function htmlFrom(response) {
+        if (response && 'markup' in response)
+            return {
+                status: 'ready',
+                source: response.markup,
+                ...(response.stylesheet === undefined
+                    ? {}
+                    : { stylesheet: response.stylesheet }),
+                ...(response.warnings === undefined || response.warnings.length === 0
+                    ? {}
+                    : { warnings: response.warnings }),
+            };
+        if (response && 'missing' in response)
+            return {
+                status: 'unavailable',
+                reason: `This story has no html: it holds ${response.missing.join('; ')}.`,
+            };
+        return {
+            status: 'unavailable',
+            reason: 'No html was printed for this scenario.',
+        };
+    }
+    /** Land an html answer, unless the story changed since it was asked. */
+    function settleHtml(sequence, html) {
+        if (sequence !== htmlSequence || !state.code)
+            return;
+        commit({ code: { ...state.code, html } });
+    }
+    /** Start getting the html of a story, returning what the state shows meanwhile. */
+    function requestHtml(component, request, scenarioId, edited) {
+        cancelHtml();
+        const sequence = htmlSequence;
+        const htmlSource = controllerOptions.htmlSource;
+        const scenarioHtmlSources = controllerOptions.scenarioHtmlSources;
+        if (htmlSource) {
+            htmlTimer = timers.setTimeout(() => {
+                htmlTimer = null;
+                const abort = new AbortController();
+                htmlAbort = abort;
+                htmlSource(request, abort.signal).then((response) => settleHtml(sequence, htmlFrom(response)), (reason) => {
+                    if (abort.signal.aborted)
+                        return;
+                    settleHtml(sequence, {
+                        status: 'unavailable',
+                        reason: reason instanceof Error ? reason.message : String(reason),
+                    });
+                });
+            }, REGENERATION_DEBOUNCE_MILLISECONDS);
+            return { status: 'loading' };
+        }
+        if (scenarioHtmlSources) {
+            if (edited)
+                return { status: 'unavailable', reason: STATIC_EDITED_REASON };
+            scenarioHtmlSources(component.id).then((byScenario) => settleHtml(sequence, htmlFrom(byScenario[scenarioId])), (reason) => settleHtml(sequence, {
+                status: 'unavailable',
+                reason: `No html was printed for this story: ${reason instanceof Error ? reason.message : String(reason)}`,
+            }));
+            return { status: 'loading' };
+        }
+        return {
+            status: 'unavailable',
+            reason: 'This preview has no way to print html.',
+        };
+    }
+    /** `next` with the code of what its panes show, printed afresh when that changed. */
+    function withCode(next) {
+        const tree = next.editor.tree;
+        if (sourcedFrom &&
+            sourcedFrom.selection === next.selection &&
+            sourcedFrom.scenario === next.scenario &&
+            sourcedFrom.props === next.props &&
+            sourcedFrom.tree === tree)
+            return next;
+        sourcedFrom = {
+            selection: next.selection,
+            scenario: next.scenario,
+            props: next.props,
+            tree,
+        };
+        const component = next.selection.kind === 'component'
+            ? componentById(next.selection.id)
+            : undefined;
+        if (!component) {
+            cancelHtml();
+            htmlKey = undefined;
+            return next.code === undefined ? next : { ...next, code: undefined };
+        }
+        const scenario = component.scenarios.find((candidate) => candidate.id === next.scenario);
+        const story = resolveSourceStory(component, {
+            props: next.props,
+            scenario,
+            tree,
+        });
+        const printed = printSourceStory(catalog, story, component.targets);
+        const previous = next.code;
+        const targets = previous &&
+            Object.keys(printed).length === Object.keys(previous.targets).length &&
+            component.targets.every((target) => printed[target] === previous.targets[target])
+            ? previous.targets
+            : printed;
+        // The html pane shows an unfilled default slot's placeholder, as the
+        // scripted panes do, though the printed code leaves it out.
+        const placeholder = !tree &&
+            !story.children &&
+            typeof next.props.children === 'string' &&
+            isPlaceholder(component, next.props.children, { scenario })
+            ? { kind: 'text', value: next.props.children }
+            : undefined;
+        const shownChildren = story.children ?? placeholder;
+        const request = {
+            rootComponent: story.component,
+            props: story.props,
+            ...(shownChildren || Object.keys(story.named).length > 0
+                ? {
+                    slots: {
+                        ...(shownChildren ? { default: shownChildren } : {}),
+                        ...(Object.keys(story.named).length > 0
+                            ? { named: story.named }
+                            : {}),
+                    },
+                }
+                : {}),
+            ...(story.around ? { around: story.around } : {}),
+        };
+        // The static build printed the scenarios as they are seeded.
+        const edited = tree !== undefined ||
+            stableStringify(next.props) !== stableStringify(seededProps);
+        const key = stableStringify([component.id, next.scenario, edited, request]);
+        let html = previous?.html;
+        if (key !== htmlKey || !html) {
+            htmlKey = key;
+            html = requestHtml(component, request, next.scenario, edited);
+        }
+        if (previous && previous.targets === targets && previous.html === html)
+            return next;
+        return { ...next, code: { targets, html } };
+    }
+    // --- persistence -----------------------------------------------------------
+    // Off while the starting state is read back.
+    let persisting = false;
+    // Above zero while a shell's action runs. The address is the controller's to
+    // write only from the first action on, so a page that is only opened, or a
+    // shell's own page the controller has not been asked to change, keeps the
+    // address it was opened with.
+    let acting = 0;
+    let ownsAddress = false;
+    let lastStored;
+    /** Run `work` as a shell's action: a change it commits claims the address. */
+    function action(work) {
+        return (...parameters) => {
+            acting += 1;
+            try {
+                return work(...parameters);
+            }
+            finally {
+                acting -= 1;
+            }
+        };
+    }
+    /** The global values that differ from their defaults: what is remembered. */
+    function changedGlobalValues() {
+        const changed = {};
+        for (const option of options) {
+            const value = globalValues[option.id];
+            if (option.scope === 'global' &&
+                value !== undefined &&
+                value !== option.default)
+                changed[option.id] = value;
+        }
+        return changed;
+    }
+    /** The option values the URL keeps: the changed globals, and the selected
+     *  story's own overrides that differ from its defaults. */
+    function urlOptionValues() {
+        const values = changedGlobalValues();
+        const component = selectedComponent();
+        if (!component)
+            return values;
+        const defaults = storyDefaultsFor(component);
+        const unavailable = unavailableOptionsFor(component);
+        for (const [id, value] of Object.entries(storyOverrides)) {
+            if (!unavailable.includes(id) && value !== defaults[id])
+                values[id] = value;
+        }
+        // A value the scenario sets that was changed back to its default since
+        // goes in too, or opening the address would set the scenario's again.
+        const merged = mergedOptions(component);
+        for (const [id, value] of Object.entries(scenarioOptionValues(component, state.scenario))) {
+            if (merged[id] !== value)
+                values[id] = merged[id];
+        }
+        return values;
+    }
+    function persist() {
+        if (!persisting)
+            return;
+        if (acting > 0)
+            ownsAddress = true;
+        if (ownsAddress)
+            writeUrl();
+        storeOptions();
+    }
+    function storeOptions() {
+        if (!storage)
+            return;
+        const changed = changedGlobalValues();
+        const serialized = JSON.stringify(changed);
+        if (serialized === lastStored)
+            return;
+        lastStored = serialized;
+        writeStoredOptions(storage, storedOptionsKey, changed);
+    }
+    function writeUrl() {
+        const location = hostWindow?.location;
+        const history = hostWindow?.history;
+        if (!location || typeof history?.replaceState !== 'function')
+            return;
+        const component = selectedComponent();
+        const scenario = component && state.scenario !== defaultScenarioId(component)
+            ? state.scenario
+            : undefined;
+        const changed = component
+            ? addressedProps(component, state.props)
+            : undefined;
+        const props = changed && Object.keys(changed).length > 0 ? changed : undefined;
+        const targets = kitTargets.every((target) => visibleTargets.has(target))
+            ? undefined
+            : kitTargets.filter((target) => visibleTargets.has(target));
+        const search = writeUrlState(location.search, {
+            selection: state.selection,
+            scenario,
+            props,
+            targets,
+            width: state.paneWidth,
+            options: urlOptionValues(),
+        });
+        if (search === location.search.replace(/^\?/, ''))
+            return;
+        try {
+            // Replace, not push: a change of option is no step to go back to.
+            history.replaceState(history.state, '', `${location.pathname}${search ? `?${search}` : ''}${location.hash}`);
+        }
+        catch {
+            // A page that cannot rewrite its URL keeps the state in memory alone.
+        }
+    }
+    /** Whether the kit's landing entry is a view the catalog has. One it
+     *  lacks is told of once, in the console, and the first story shows. */
+    function landsOnView() {
+        const landing = catalog.landing;
+        if (landing?.kind !== 'view')
+            return false;
+        if (catalog.views.some((view) => view.id === landing.id))
+            return true;
+        console.warn(`[preview] preview.landing names view '${landing.id}', which the views module does not register; the preview opens on the first story. The views: ${catalog.views.map((view) => view.id).join(', ') || 'none'}.`);
+        return false;
+    }
+    /** Whether the kit's landing entry is a story the catalog has. */
+    function landsOnComponent() {
+        const landing = catalog.landing;
+        return (landing?.kind === 'component' &&
+            stories.some((component) => component.id === landing.id));
+    }
+    /** Start from what the URL and storage say: stored globals, then the URL's
+     *  values over them, the visible targets, its selection and scenario,
+     *  its story options and its props. Where the address names no view or
+     *  story, the kit's landing entry shows, else the first listed story. The
+     *  address itself is left as it is. */
+    function restore() {
+        const fromUrl = readUrlState(hostWindow?.location?.search ?? '');
+        const globalOptions = options.filter((option) => option.scope === 'global');
+        const stored = storage
+            ? readStoredOptions(storage, storedOptionsKey, globalOptions)
+            : {};
+        lastStored = storage ? JSON.stringify(stored) : undefined;
+        const fromUrlGlobals = {};
+        for (const option of globalOptions) {
+            const raw = fromUrl.options[option.id];
+            const value = raw === undefined ? undefined : parseOptionValue(option, raw);
+            if (value !== undefined)
+                fromUrlGlobals[option.id] = value;
+        }
+        globalValues = { ...globalValues, ...stored, ...fromUrlGlobals };
+        const visible = fromUrl.targets === undefined
+            ? undefined
+            : parseTargets(fromUrl.targets, kitTargets);
+        if (visible) {
+            for (const target of kitTargets) {
+                if (visible.includes(target))
+                    visibleTargets.add(target);
+                else
+                    visibleTargets.delete(target);
+            }
+        }
+        const paneWidth = fromUrl.width === undefined ? undefined : parsePaneWidth(fromUrl.width);
+        if (paneWidth !== undefined)
+            state = { ...state, paneWidth };
+        if (fromUrl.view !== undefined &&
+            catalog.views.some((view) => view.id === fromUrl.view)) {
+            selectView(fromUrl.view);
+        }
+        else if (fromUrl.component !== undefined &&
+            stories.some((component) => component.id === fromUrl.component)) {
+            selectComponent(fromUrl.component);
+            const component = selectedComponent();
+            const scenario = fromUrl.scenario;
+            const known = component.scenarios.find((candidate) => candidate.id === scenario);
+            // Empty renders through a regeneration, which a static build cannot do.
+            if (scenario === '' ||
+                (scenario !== undefined && known && (!known.empty || regeneration)))
+                pickScenario(scenario);
+            // The address's values win over those the scenario sets.
+            globalValues = { ...globalValues, ...fromUrlGlobals };
+            const unavailable = unavailableOptionsFor(component);
+            for (const option of options) {
+                const raw = fromUrl.options[option.id];
+                if (option.scope !== 'story' ||
+                    raw === undefined ||
+                    unavailable.includes(option.id))
+                    continue;
+                const value = parseOptionValue(option, raw);
+                if (value !== undefined)
+                    storyOverrides = { ...storyOverrides, [option.id]: value };
+            }
+            const props = fromUrl.props === undefined
+                ? undefined
+                : parseProps(fromUrl.props, addressableProps(component), 
+                // The address holds the props that differ from the
+                // scenario's, which a story rendering from a tree (Empty)
+                // seeds without its content.
+                seededProps, seededProps, catalog.colorTokens);
+            if (props)
+                setProps(props);
+        }
+        else if (landsOnView()) {
+            selectView(catalog.landing.id);
+            globalValues = { ...globalValues, ...fromUrlGlobals };
+        }
+        else if (landsOnComponent()) {
+            // The kit's landing story, on its scenario or its baseline, with the
+            // values that scenario sets, the address's winning.
+            const landing = catalog.landing;
+            selectComponent(landing.id);
+            const scenario = landing.kind === 'component' ? landing.scenario : undefined;
+            const known = selectedComponent().scenarios.find((candidate) => candidate.id === scenario);
+            // Empty renders through a regeneration, which a static build cannot
+            // do: the story opens on its baseline, and the console says why.
+            if (known && (!known.empty || regeneration))
+                pickScenario(known.id);
+            else if (known?.empty)
+                console.warn(`[preview] preview.landing names the scenario '${known.id}' of '${landing.id}', which renders through the development server alone; the static build opens the story on its baseline.`);
+            globalValues = { ...globalValues, ...fromUrlGlobals };
+        }
+        else if (first) {
+            // The first story shows on its baseline scenario, with the values that
+            // scenario sets, the address's winning.
+            applyScenarioOptions(first, defaultScenarioId(first));
+            globalValues = { ...globalValues, ...fromUrlGlobals };
+        }
+        state = withCode({
+            ...state,
+            options: mergedOptions(selectedComponent()),
+            targets: targetsFor(selectedComponent() ?? first),
+        });
+        persisting = true;
+        storeOptions();
+    }
+    // --- the iframes -----------------------------------------------------------
+    function postTo(frame, message) {
+        frame.iframe.contentWindow?.postMessage(message, '*');
+    }
+    /** The selection's set-story message: the story, its props, its events
+     *  and the two-way props a pane writes back itself, the scratch story's
+     *  those of the editor's root component. Each message but a pane's answer
+     *  to its ready (`fresh` false) is a new mount of the story, which the
+     *  panes tag their events with: an event of a story since replaced writes
+     *  nothing back. */
+    function storyMessage(id, props, fresh = true) {
+        if (fresh)
+            storyMount += 1;
+        const component = storyComponent(id);
+        return setStoryMessage(id, paneProps(props, component), component?.events, 
+        // Only a binding whose change prop is a recorded event: a pane writes
+        // back only what it then reports, so the host can answer each write.
+        component?.bindings.flatMap((binding) => binding.changeProp === undefined ||
+            !component.events.includes(binding.changeProp)
+            ? []
+            : [{ prop: binding.prop, changeProp: binding.changeProp }]), storyMount);
+    }
+    /** The id the panes mount the selected story by: its scenario's own
+     *  story when that has content of its own, else the selection's. */
+    function selectionStoryId() {
+        const component = selectedComponent();
+        return component
+            ? paneStoryId(component, state.scenario)
+            : state.selection.id;
+    }
+    /** The component the story `id` renders at its root: the story's own, or,
+     *  for the scratch story, the editor's root component. */
+    function storyComponent(id) {
+        return id === SCRATCH_STORY_ID
+            ? state.editor.tree
+                ? componentByName(state.editor.tree.root)
+                : undefined
+            : (componentById(id) ?? scenarioStoryComponents.get(id));
+    }
+    /** The panes' story's root component: the selection's, or the editor's
+     *  root while the scratch story shows. */
+    function shownComponent() {
+        if (state.selection.kind !== 'component')
+            return undefined;
+        return storyComponent(scratchActive ? SCRATCH_STORY_ID : state.selection.id);
+    }
+    /**
+     * Take the value a pane reports through a two-way prop's change callback
+     * as the story's new prop, when the story gives the prop: a controlled
+     * story then follows a click in any pane, every pane and the html with
+     * it, as `setProps` does. A story that leaves the prop out lets the
+     * component keep its own value, and an unchanged value changes nothing.
+     */
+    function writeBack(name, data) {
+        if (!('value' in data))
+            return;
+        // An event the pane recorded under a story it has since been told to
+        // replace.
+        if (typeof data.mount === 'number' && data.mount !== storyMount)
+            return;
+        // Every two-way prop the story gives that reports through this change
+        // prop and holds another value.
+        const changed = (shownComponent()?.bindings ?? []).filter((binding) => binding.changeProp === name &&
+            state.props[binding.prop] !== undefined &&
+            stableStringify(state.props[binding.prop]) !==
+                stableStringify(data.value));
+        if (changed.length === 0)
+            return;
+        // A change the story's reader made: it claims the address, as a shell's
+        // action does.
+        action(setProps)({
+            ...state.props,
+            ...Object.fromEntries(changed.map((binding) => [binding.prop, data.value])),
+        });
+    }
+    /** Post to the selection's scripted panes; a detached pane keeps its own
+     *  story, and the html pane shows the markup `postHtml` sends it. */
+    function broadcast(message) {
+        for (const frame of frames)
+            if (!frame.story && frame.target !== 'html')
+                postTo(frame, message);
+    }
+    /** Post the story's new root props to the selection's scripted panes,
+     *  each message naming the newest of that pane's own write-backs the
+     *  host has taken, so a pane keeps a later write of its own over them. */
+    function broadcastProps(props) {
+        const shown = paneProps(props, shownComponent());
+        for (const frame of frames)
+            if (!frame.story && frame.target !== 'html')
+                postTo(frame, propsMessage(shown, frame.answered ?? 0));
+    }
+    /** Post option values to the selection's panes, the html pane's included. */
+    function broadcastGlobals(values) {
+        for (const frame of frames)
+            if (!frame.story)
+                postTo(frame, globalsMessage(kitValues(values)));
+        for (const frame of codeFrames)
+            if (frame.ready)
+                frame.iframe.contentWindow?.postMessage(globalsMessage(codeValues(values)), '*');
+    }
+    /** The html pane's message for the html the state holds. */
+    function htmlPaneMessage() {
+        const html = state.code?.html;
+        if (html?.status === 'ready')
+            return markupMessage(html.stylesheet === undefined
+                ? { markup: html.source }
+                : { markup: html.source, stylesheet: html.stylesheet });
+        if (html?.status === 'unavailable')
+            return markupMessage({ reason: html.reason });
+        return markupMessage({});
+    }
+    // The html the html panes were last sent, so each change is sent once.
+    let postedHtml;
+    /** Send the html panes the state's html when it changed since last sent. */
+    function postHtml() {
+        const html = state.code?.html;
+        if (html === postedHtml)
+            return;
+        postedHtml = html;
+        if (!html)
+            return;
+        // A pane still loading gets the html when it answers the handshake.
+        const message = htmlPaneMessage();
+        for (const frame of frames)
+            if (frame.target === 'html' && readinessOf(frame) === 'ready')
+                postTo(frame, message);
+    }
+    // The events recorded so far, numbering each.
+    let eventCount = 0;
+    const codeFrames = [];
+    /** Hide an iframe until it shows its first content: a frame's page would
+     *  otherwise show the browser's blank canvas, then whatever it paints on the
+     *  way. Hidden, it leaves the shell's ground (and any loading note the shell
+     *  draws beneath it) in view. */
+    function conceal(iframe) {
+        iframe.style.visibility = 'hidden';
+        iframe.removeAttribute(PREVIEW_FRAME_SHOWN_ATTRIBUTE);
+    }
+    /** Show an iframe whose first content has painted, marked for a shell's CSS. */
+    function reveal(iframe) {
+        iframe.style.removeProperty('visibility');
+        iframe.setAttribute(PREVIEW_FRAME_SHOWN_ATTRIBUTE, '');
+    }
+    // Whether the shell wraps its code panes, which the code blocks follow.
+    let codeWrap = false;
+    /** What a code block shows for `target`: its source, or why it has none;
+     *  with neither, the source is being printed. */
+    function codeContent(target) {
+        const language = CODE_LANGUAGES[target];
+        const wrap = codeWrap;
+        const code = state.code;
+        if (target === 'html') {
+            const html = code?.html;
+            if (html?.status === 'ready')
+                return { target, language, wrap, source: html.source };
+            if (html?.status === 'unavailable')
+                return { target, language, wrap, reason: html.reason };
+            return { target, language, wrap };
+        }
+        const printed = code?.targets[target];
+        return printed === undefined
+            ? {
+                target,
+                language,
+                wrap,
+                reason: `The story does not render in ${target}.`,
+            }
+            : { target, language, wrap, source: printed };
+    }
+    // The source the code blocks were last sent, so each change is sent once.
+    let postedCode;
+    /** Send each code block its target's source when it changed since last
+     *  sent, or every block its content when `force`d. */
+    function postCode(force = false) {
+        if (!force && state.code === postedCode)
+            return;
+        postedCode = state.code;
+        for (const frame of codeFrames)
+            if (frame.ready)
+                frame.iframe.contentWindow?.postMessage(codeMessage(codeContent(frame.target)), '*');
+    }
+    function mountCode(element, target) {
+        const iframe = element.ownerDocument.createElement('iframe');
+        iframe.setAttribute('title', `${target} code`);
+        iframe.setAttribute('src', codeFrameUrl(target, catalog.codeBlock?.framework, baseUrl));
+        conceal(iframe);
+        element.appendChild(iframe);
+        const frame = { target, iframe, ready: false };
+        codeFrames.push(frame);
+        return () => {
+            const index = codeFrames.indexOf(frame);
+            if (index === -1)
+                return;
+            codeFrames.splice(index, 1);
+            iframe.remove();
+        };
+    }
+    /** Bring each detached pane up to the current global values. */
+    function postDetachedGlobals() {
+        for (const frame of frames) {
+            if (frame.story)
+                postTo(frame, globalsMessage(detachedOptions(frame.story.component, frame.story.options)));
+        }
+    }
+    function readinessOf(frame) {
+        return frame.story
+            ? state.storyFrames[frame.story.key]
+            : state.frames[frame.target];
+    }
+    /** The state change that sets a frame's readiness, or clears it. */
+    function withReadiness(frame, readiness) {
+        if (frame.story) {
+            const storyFrames = { ...state.storyFrames };
+            if (readiness)
+                storyFrames[frame.story.key] = readiness;
+            else
+                delete storyFrames[frame.story.key];
+            return { storyFrames };
+        }
+        const next = { ...state.frames };
+        if (readiness)
+            next[frame.target] = readiness;
+        else
+            delete next[frame.target];
+        return { frames: next };
+    }
+    function sizeOf(frame) {
+        return frame.story
+            ? state.storyFrameSizes[frame.story.key]
+            : state.frameSizes[frame.target];
+    }
+    /** The state change that sets the size of what a frame shows, or clears it. */
+    function withSize(frame, size) {
+        if (frame.story) {
+            const storyFrameSizes = { ...state.storyFrameSizes };
+            if (size)
+                storyFrameSizes[frame.story.key] = size;
+            else
+                delete storyFrameSizes[frame.story.key];
+            return { storyFrameSizes };
+        }
+        const frameSizes = { ...state.frameSizes };
+        if (size)
+            frameSizes[frame.target] = size;
+        else
+            delete frameSizes[frame.target];
+        return { frameSizes };
+    }
+    /** The state change that sets what a selection's pane threw, or clears it. */
+    function withError(target, message) {
+        const frameErrors = { ...state.frameErrors };
+        if (message === undefined)
+            delete frameErrors[target];
+        else
+            frameErrors[target] = message;
+        return { frameErrors };
+    }
+    /** Whether two frames report their readiness under the same key. */
+    function sameReadinessKey(a, b) {
+        return a.story
+            ? b.story?.key === a.story.key
+            : !b.story && b.target === a.target;
+    }
+    function mountFrame(element, description, title, source) {
+        const iframe = element.ownerDocument.createElement('iframe');
+        iframe.setAttribute('title', title);
+        iframe.setAttribute('src', source);
+        conceal(iframe);
+        element.appendChild(iframe);
+        const frame = { ...description, iframe };
+        frames.push(frame);
+        // The new readiness is reported after the shell's mount call returns, so
+        // no subscriber runs inside it: a shell that mounts in an effect reading
+        // the state would otherwise see that state change within its own effect.
+        // A pane unmounted before then is never reported.
+        queueMicrotask(() => {
+            if (!frames.includes(frame) || readinessOf(frame) === 'loading')
+                return;
+            commit(withReadiness(frame, 'loading'));
+        });
+        return () => {
+            const index = frames.indexOf(frame);
+            if (index === -1)
+                return;
+            frames.splice(index, 1);
+            iframe.remove();
+            if (frames.some((candidate) => sameReadinessKey(frame, candidate)) ||
+                (readinessOf(frame) === undefined &&
+                    sizeOf(frame) === undefined &&
+                    (frame.story || state.frameErrors[frame.target] === undefined)))
+                return;
+            commit({
+                ...withReadiness(frame, undefined),
+                ...withSize(frame, undefined),
+                ...(frame.story ? {} : withError(frame.target, undefined)),
+            });
+        };
+    }
+    function mountStory(element, target, story) {
+        const component = stories.find((candidate) => candidate.id === story.component);
+        if (!component)
+            throw new Error(`The catalog has no story "${story.component}" to mount: a detached pane takes the id of a standalone component.`);
+        if (!component.targets.includes(target))
+            throw new Error(`The story "${component.id}" does not render in ${target}: its targets are ${component.targets.join(', ')}.`);
+        const scenarioId = story.scenario ?? defaultScenarioId(component);
+        const scenario = component.scenarios.find((candidate) => candidate.id === scenarioId);
+        if (scenarioId !== '' && !scenario)
+            throw new Error(`The story "${component.id}" has no scenario "${scenarioId}".`);
+        if (scenario?.empty)
+            throw new Error(`The Empty scenario of "${component.id}" renders through the selection's regenerated story and cannot be mounted apart from it: leave out the scenarios marked empty.`);
+        const props = {
+            ...seedProps(component, scenarioId),
+            ...withoutUndefined(story.props ?? {}),
+        };
+        return mountFrame(element, {
+            target: target,
+            story: {
+                key: storyFrameKey(target, story),
+                component,
+                id: paneStoryId(component, scenarioId),
+                props,
+                options: scenarioOptionValues(component, scenarioId),
+            },
+        }, `${component.shortTitle}${scenario ? `: ${scenario.label}` : ''} (${target})`, componentFrameUrl(target, reloadCount, baseUrl));
+    }
+    function reloadPanes() {
+        reloadCount += 1;
+        const next = { ...state.frames };
+        for (const frame of frames) {
+            // A view, the html pane and a detached pane show no scratch story.
+            if (frame.target === 'view' || frame.target === 'html' || frame.story)
+                continue;
+            conceal(frame.iframe);
+            frame.iframe.setAttribute('src', componentFrameUrl(frame.target, reloadCount, baseUrl));
+            next[frame.target] = 'loading';
+        }
+        commit({ frames: next });
+    }
+    function answerReady(frame) {
+        // A pane that announces ready again was reloaded, and counts its
+        // writes from zero.
+        frame.answered = 0;
+        if (frame.story) {
+            postTo(frame, setStoryMessage(frame.story.id, paneProps(frame.story.props, frame.story.component)));
+            postTo(frame, globalsMessage(detachedOptions(frame.story.component, frame.story.options)));
+            postTo(frame, catalogMessage(catalogPayload));
+            return;
+        }
+        if (frame.target === 'html') {
+            postTo(frame, globalsMessage(kitValues(state.options)));
+            postTo(frame, htmlPaneMessage());
+            return;
+        }
+        // The scratch story holds the root's text as content, not as a prop.
+        const tree = state.editor.tree;
+        if (scratchActive && tree)
+            postTo(frame, storyMessage(SCRATCH_STORY_ID, tree.props, false));
+        else
+            postTo(frame, storyMessage(selectionStoryId(), state.props, false));
+        postTo(frame, globalsMessage(kitValues(state.options)));
+        postTo(frame, catalogMessage(catalogPayload));
+    }
+    function onMessage(event) {
+        const data = event.data;
+        if (isPreviewMessage(data, PREVIEW_MESSAGE.shown)) {
+            const shown = [...frames, ...codeFrames].find((candidate) => candidate.iframe.contentWindow === event.source);
+            if (shown)
+                reveal(shown.iframe);
+            return;
+        }
+        if (isPreviewMessage(data, PREVIEW_MESSAGE.ready)) {
+            const code = codeFrames.find((candidate) => candidate.iframe.contentWindow === event.source);
+            if (code) {
+                code.ready = true;
+                const codeWindow = code.iframe.contentWindow;
+                codeWindow?.postMessage(globalsMessage(codeValues(state.options)), '*');
+                codeWindow?.postMessage(codeMessage(codeContent(code.target)), '*');
+                return;
+            }
+            const frame = frames.find((candidate) => candidate.iframe.contentWindow === event.source);
+            if (!frame)
+                return;
+            answerReady(frame);
+            commit(withReadiness(frame, 'ready'));
+            return;
+        }
+        if (isPreviewMessage(data, PREVIEW_MESSAGE.select)) {
+            // Only the view pane the controller mounted may select a story: a
+            // component pane, the selection's or a detached one, never asks.
+            const frame = frames.find((candidate) => candidate.target === 'view' &&
+                candidate.iframe.contentWindow === event.source);
+            if (!frame || typeof data.id !== 'string')
+                return;
+            if (!stories.some((component) => component.id === data.id))
+                return;
+            action(selectComponent)(data.id, isRecord(data.props) ? data.props : undefined);
+            return;
+        }
+        if (isPreviewMessage(data, PREVIEW_MESSAGE.event)) {
+            // The selection's scripted panes record their story's events; a
+            // detached pane's stay its own.
+            const frame = frames.find((candidate) => !candidate.story && candidate.iframe.contentWindow === event.source);
+            if (!frame || typeof data.name !== 'string')
+                return;
+            eventCount += 1;
+            const recorded = {
+                id: eventCount,
+                target: frame.target,
+                name: data.name,
+                payload: typeof data.payload === 'string' ? data.payload : '',
+                time: Date.now(),
+            };
+            commit({ events: [...state.events, recorded].slice(-EVENT_LOG_LENGTH) });
+            // The write the event reports is the host's from here on, whether or
+            // not it changes the story: the next props to the pane answer it.
+            if (typeof data.write === 'number' && data.write > (frame.answered ?? 0))
+                frame.answered = data.write;
+            writeBack(data.name, data);
+            return;
+        }
+        if (isPreviewMessage(data, PREVIEW_MESSAGE.renderError)) {
+            // A detached story pane's error stays its own; the selection's panes
+            // report theirs.
+            const frame = frames.find((candidate) => !candidate.story && candidate.iframe.contentWindow === event.source);
+            if (!frame)
+                return;
+            const message = typeof data.message === 'string' ? data.message : undefined;
+            if (state.frameErrors[frame.target] === message)
+                return;
+            commit(withError(frame.target, message));
+            return;
+        }
+        if (isPreviewMessage(data, PREVIEW_MESSAGE.contentSize)) {
+            const frame = frames.find((candidate) => candidate.iframe.contentWindow === event.source);
+            const size = readContentSize(data);
+            if (!frame || !size)
+                return;
+            const current = sizeOf(frame);
+            if (current?.width === size.width && current.height === size.height)
+                return;
+            commit(withSize(frame, size));
+        }
+    }
+    hostWindow?.addEventListener('message', onMessage);
+    // --- regeneration ----------------------------------------------------------
+    function dropPendingRegeneration() {
+        if (regenerationTimer !== null) {
+            timers.clearTimeout(regenerationTimer);
+            regenerationTimer = null;
+        }
+        regenerationSequence += 1;
+        return state.regeneration.status === 'pending'
+            ? { status: 'idle' }
+            : state.regeneration;
+    }
+    /** Regenerate `tree` once edits pause. The returned status is the one to commit. */
+    function scheduleRegeneration(tree) {
+        dropPendingRegeneration();
+        if (!regeneration) {
+            return {
+                status: 'error',
+                message: 'This preview cannot regenerate a story: it has no regeneration endpoint.',
+            };
+        }
+        const generation = regenerationSequence;
+        regenerationTimer = timers.setTimeout(() => {
+            regenerationTimer = null;
+            // The tree as it stands when the edits pause: the root's props may have
+            // changed live since the last structural edit.
+            const current = state.editor.tree ?? tree;
+            // The content beside the root is the story's as the catalog has it now,
+            // which no edit reaches.
+            const around = componentById(state.selection.id)?.around;
+            regeneration({
+                ...toPayload(current),
+                ...(around ? { around } : {}),
+            }).then(() => {
+                if (generation !== regenerationSequence)
+                    return;
+                reloadPanes();
+                commit({ regeneration: { status: 'idle' } });
+            }, (reason) => {
+                if (generation !== regenerationSequence)
+                    return;
+                const message = reason instanceof Error ? reason.message : String(reason);
+                commit({ regeneration: { status: 'error', message } });
+            });
+        }, REGENERATION_DEBOUNCE_MILLISECONDS);
+        return { status: 'pending' };
+    }
+    // --- selection -------------------------------------------------------------
+    function selectComponent(id, props) {
+        const component = stories.find((candidate) => candidate.id === id);
+        if (!component)
+            return;
+        const regenerationStatus = dropPendingRegeneration();
+        scratchActive = false;
+        const baseline = props
+            ? undefined
+            : component.scenarios.find((scenario) => scenario.default);
+        seededProps = seedProps(component, baseline?.id ?? '');
+        const nextProps = { ...seededProps, ...(props ?? {}) };
+        broadcast(storyMessage(paneStoryId(component, baseline?.id ?? ''), nextProps));
+        storyOverrides = {};
+        const { globalChanged } = baseline
+            ? applyScenarioOptions(component, baseline.id)
+            : { globalChanged: false };
+        const merged = mergedOptions(component);
+        broadcastGlobals(merged);
+        if (globalChanged)
+            postDetachedGlobals();
+        const targets = targetsFor(component);
+        commit({
+            selection: { kind: 'component', id },
+            events: [],
+            scenario: baseline?.id ?? '',
+            props: nextProps,
+            options: merged,
+            unavailableOptions: unavailableOptionsFor(component),
+            targets: sameTargets(targets.supported, state.targets.supported)
+                ? state.targets
+                : targets,
+            editor: { open: false, modified: false },
+            regeneration: regenerationStatus,
+        });
+    }
+    function selectView(id) {
+        if (!catalog.views.some((view) => view.id === id))
+            return;
+        const regenerationStatus = dropPendingRegeneration();
+        scratchActive = false;
+        commit({
+            selection: { kind: 'view', id },
+            events: [],
+            options: mergedOptions(undefined),
+            // A view has no story to apply a story option to.
+            unavailableOptions: storyOptionIds,
+            editor: { open: false, modified: false },
+            regeneration: regenerationStatus,
+        });
+    }
+    function pickScenario(id) {
+        const component = selectedComponent();
+        if (!component)
+            return;
+        const scenario = id
+            ? component.scenarios.find((candidate) => candidate.id === id)
+            : undefined;
+        // Empty renders through a regeneration, which a static build cannot do.
+        if (scenario?.empty && !regeneration)
+            return;
+        if (scenario?.empty) {
+            // Empty is content the real story cannot show, so it renders through the
+            // regenerated scratch story: the story's props, no slot content.
+            const tree = {
+                root: component.name,
+                props: withoutContent(seedProps(component, id)),
+                slots: {},
+            };
+            scratchActive = true;
+            seededProps = tree.props;
+            seededSlots = slotsKey(tree.slots);
+            broadcast(storyMessage(SCRATCH_STORY_ID, cleanRecord(tree.props)));
+            const regenerationStatus = scheduleRegeneration(tree);
+            commit({
+                scenario: id,
+                props: tree.props,
+                editor: { open: state.editor.open, tree, modified: false },
+                regeneration: regenerationStatus,
+            });
+            return;
+        }
+        const regenerationStatus = dropPendingRegeneration();
+        scratchActive = false;
+        const props = seedProps(component, id);
+        seededProps = props;
+        broadcast(storyMessage(paneStoryId(component, id), props));
+        const carried = applyScenarioOptions(component, id);
+        const merged = carried.changed ? mergedOptions(component) : state.options;
+        if (carried.changed)
+            broadcastGlobals(merged);
+        if (carried.globalChanged)
+            postDetachedGlobals();
+        let tree;
+        if (state.editor.open) {
+            // The props read from the tree, as `open` seeds it.
+            tree = seedRoot(onScenario(component, id), props);
+            ensureIds(tree.slots);
+            seededProps = treeProps(tree);
+            seededSlots = slotsKey(tree.slots);
+        }
+        commit({
+            scenario: id,
+            props: seededProps,
+            options: merged,
+            editor: {
+                open: state.editor.open,
+                ...(tree ? { tree } : {}),
+                modified: false,
+            },
+            regeneration: regenerationStatus,
+        });
+    }
+    function setOption(id, value) {
+        const descriptor = options.find((candidate) => candidate.id === id);
+        if (descriptor?.scope === 'story')
+            storyOverrides = { ...storyOverrides, [id]: value };
+        else
+            globalValues = { ...globalValues, [id]: value };
+        const merged = mergedOptions(selectedComponent());
+        // A shell option's value never reaches the iframes, so they are told
+        // nothing of it.
+        if (descriptor?.origin !== 'shell')
+            broadcastGlobals(merged);
+        if (descriptor?.scope === 'global' && descriptor.origin === 'kit')
+            postDetachedGlobals();
+        commit({ options: merged });
+    }
+    function setTargetVisible(target, visible) {
+        if (visible)
+            visibleTargets.add(target);
+        else
+            visibleTargets.delete(target);
+        commit({ targets: targetsFor(selectedComponent()) });
+    }
+    function setPaneWidth(width) {
+        if (width !== undefined && !isPaneWidth(width))
+            return;
+        if (width === state.paneWidth)
+            return;
+        const { paneWidth: _paneWidth, ...rest } = state;
+        state = rest;
+        commit(width === undefined ? {} : { paneWidth: width });
+    }
+    function setProps(props) {
+        if (state.selection.kind !== 'component')
+            return;
+        const next = withoutUndefined(props);
+        const tree = state.editor.tree;
+        if (!tree) {
+            // The root renders with its props as they are: they reach the panes live.
+            broadcastProps(cleanRecord(next));
+            commit({ props: next });
+            return;
+        }
+        // With a tree, where the story draws its default slot from `children`,
+        // `children` is the root's text: a new one replaces the root's default
+        // slot with that text, and one left out removes a lone text. Content
+        // other than a lone text carries no `children` and stays. A story with
+        // default-slot content of its own takes no `children`.
+        const { children, ...rootProps } = next;
+        const text = typeof children === 'string' ? children : undefined;
+        if (drawsChildren(tree) && text !== rootText(tree)) {
+            const slots = { ...tree.slots };
+            if (text === undefined)
+                delete slots[DEFAULT_SLOT];
+            else
+                slots[DEFAULT_SLOT] = [{ kind: 'text', value: text }];
+            editTree({ ...tree, props: rootProps, slots });
+            return;
+        }
+        const nextTree = { ...tree, props: rootProps };
+        const shown = treeProps(nextTree);
+        // The root's props reach the panes live; the scratch story holds the
+        // root's text as content, not as a prop.
+        broadcastProps(cleanRecord(scratchActive ? rootProps : shown));
+        commit({
+            props: sameProps(shown),
+            editor: { ...state.editor, tree: nextTree },
+        });
+    }
+    /** `props`, or the state's own when they are equal, so an unchanged field
+     *  keeps its reference. */
+    function sameProps(props) {
+        return stableStringify(props) === stableStringify(state.props)
+            ? state.props
+            : props;
+    }
+    // --- the editor ------------------------------------------------------------
+    function open() {
+        if (state.editor.open)
+            return;
+        const component = selectedComponent();
+        if (!component)
+            return;
+        let tree = state.editor.tree;
+        if (!tree) {
+            // The root starts from the props the panes show, so a prop set before
+            // the editor opened stays set; the address still measures them against
+            // the scenario's.
+            const shown = onScenario(component, state.scenario);
+            tree = seedRoot(shown, state.props);
+            ensureIds(tree.slots);
+            seededProps = treeProps(seedRoot(shown, seedProps(component, state.scenario)));
+            seededSlots = slotsKey(tree.slots);
+            // The props now read from the tree, which shows what the panes show:
+            // a string `children` stays as the root's text. Where the story's own
+            // content stands in its default slot, the panes render that content
+            // and not the `children` prop, so `props` leaves it out and nothing on
+            // screen changes, with nothing to post.
+            commit({
+                props: sameProps(treeProps(tree)),
+                editor: { open: true, tree, modified: false },
+            });
+            return;
+        }
+        commit({ editor: { ...state.editor, open: true, tree } });
+    }
+    function close() {
+        if (!state.editor.open)
+            return;
+        commit({ editor: { ...state.editor, open: false } });
+    }
+    function createNode(request) {
+        if (request.kind === 'text')
+            return { kind: 'text', value: request.value };
+        if (request.kind === 'html')
+            return { kind: 'html', tag: request.tag, props: {}, slots: {} };
+        const component = componentByName(request.name);
+        if (!component)
+            throw new Error(`The catalog has no component named "${request.name}".`);
+        const baseline = component.scenarios.find((scenario) => scenario.default);
+        const named = component.scenarios.filter((scenario) => !scenario.empty && !scenario.default);
+        // A component with nothing to strip and no scenario to pick has no choice to
+        // make: it comes in with its defaults.
+        const hasChoice = component.slots.default ||
+            component.slots.named.length > 0 ||
+            named.length > 0;
+        const importAs = hasChoice ? (request.importAs ?? 'empty') : 'default';
+        const withDefaults = (over) => ({
+            ...component.defaultProps,
+            ...(over ?? {}),
+        });
+        if (importAs === 'empty')
+            return seedComponentNode(component);
+        // A scenario with content of its own comes in with that content.
+        if (importAs === 'default')
+            return seedComponentNode(onScenario(component, baseline?.id ?? ''), withDefaults(baseline?.props));
+        const scenario = named.find((candidate) => candidate.id === importAs.scenario);
+        return seedComponentNode(onScenario(component, scenario?.id ?? ''), withDefaults(scenario?.props));
+    }
+    /** Apply a change to the tree's slot content: the panes switch to the scratch
+     *  story, which regenerates once edits pause. An unchanged tree does nothing. */
+    /**
+     * Whether the slot `slot` of the node at `parent` takes `node`, moved from
+     * `from` or newly inserted. A scoped fill fills the one slot it names, so
+     * it moves only within its own list; a slot whose content must take its
+     * scope takes nothing else.
+     */
+    function slotTakes(tree, parent, slot, node, from) {
+        if (node.kind === 'opaque' && node.fill.kind === 'scoped')
+            return (from !== undefined &&
+                pathKey(from.slice(0, -1)) === pathKey(parent) &&
+                from[from.length - 1].slot === slot);
+        const holder = parent.length === 0 ? tree : nodeAt(tree.slots, parent);
+        if (!holder)
+            return true;
+        return (!nodeSlots(catalog, holder).includes(slot) ||
+            nodeAddSlots(catalog, holder).includes(slot));
+    }
+    function editContent(transform) {
+        const tree = state.editor.tree;
+        if (!tree)
+            return;
+        const slots = transform(tree.slots);
+        if (slots === tree.slots)
+            return;
+        editTree({ ...tree, slots });
+    }
+    /** Show `next`, whose content differs from the current tree's, through the
+     *  scratch story; the root's text, if it changed, reaches `props`. */
+    function editTree(next) {
+        ensureIds(next.slots);
+        scratchActive = true;
+        broadcast(storyMessage(SCRATCH_STORY_ID, cleanRecord(next.props)));
+        const regenerationStatus = scheduleRegeneration(next);
+        commit({
+            props: sameProps(treeProps(next)),
+            editor: {
+                ...state.editor,
+                tree: next,
+                modified: slotsKey(next.slots) !== seededSlots,
+            },
+            regeneration: regenerationStatus,
+        });
+    }
+    function setNodeProps(path, props) {
+        if (path.length === 0) {
+            // The root's text is content: its props leave it, and `children`, as it is.
+            const tree = state.editor.tree;
+            if (!tree) {
+                setProps(props);
+                return;
+            }
+            const { children: _children, ...rootProps } = props;
+            const text = treeProps(tree).children;
+            setProps(text === undefined ? rootProps : { ...rootProps, children: text });
+            return;
+        }
+        const nextProps = withoutUndefined(props);
+        editContent((slots) => updateAt(slots, path, (node) => isContainer(node) ? { ...node, props: nextProps } : node));
+    }
+    function dispose() {
+        hostWindow?.removeEventListener('message', onMessage);
+        dropPendingRegeneration();
+        cancelHtml();
+        for (const frame of [...frames])
+            frame.iframe.remove();
+        frames.length = 0;
+        for (const frame of [...codeFrames])
+            frame.iframe.remove();
+        codeFrames.length = 0;
+        listeners.clear();
+    }
+    restore();
+    return {
+        apiVersion: 1,
+        catalog,
+        options,
+        capabilities: { regeneration: regeneration !== undefined },
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        actions: {
+            selectComponent: action(selectComponent),
+            selectView: action(selectView),
+            select: action((selection) => {
+                if (selection.kind === 'view')
+                    selectView(selection.id);
+                else
+                    selectComponent(selection.id);
+            }),
+            pickScenario: action(pickScenario),
+            setOption: action(setOption),
+            setTargetVisible: action(setTargetVisible),
+            setPaneWidth: action(setPaneWidth),
+            setProps: action(setProps),
+            clearEvents: action(() => {
+                if (state.events.length > 0)
+                    commit({ events: [] });
+            }),
+        },
+        editor: {
+            open: action(open),
+            close: action(close),
+            createNode,
+            insert: action((target, node) => {
+                const tree = state.editor.tree;
+                if (tree && !slotTakes(tree, target.parent, target.slot, node))
+                    return;
+                editContent((slots) => insertAt(slots, target.parent, target.slot, node, target.index));
+            }),
+            move: action((from, to) => {
+                const tree = state.editor.tree;
+                const node = tree && from.length > 0 ? nodeAt(tree.slots, from) : undefined;
+                if (tree && node && !slotTakes(tree, to.parent, to.slot, node, from))
+                    return;
+                editContent((slots) => moveNode(slots, from, to));
+            }),
+            moveBy: action((path, offset) => {
+                if (path.length === 0)
+                    return;
+                editContent((slots) => {
+                    const parent = path.slice(0, -1);
+                    const { slot, index } = path[path.length - 1];
+                    const holder = parent.length === 0 ? undefined : nodeAt(slots, parent);
+                    const list = holder === undefined
+                        ? slots[slot]
+                        : holder && isContainer(holder)
+                            ? holder.slots[slot]
+                            : undefined;
+                    if (!list || index >= list.length)
+                        return slots;
+                    const destination = Math.min(Math.max(index + Math.trunc(offset), 0), list.length - 1);
+                    if (destination === index)
+                        return slots;
+                    // `moveNode` counts the target index before the node is taken out.
+                    const before = destination > index ? destination + 1 : destination;
+                    return moveNode(slots, path, { parent, slot, index: before });
+                });
+            }),
+            replace: action((path, node) => {
+                if (path.length === 0)
+                    return;
+                editContent((slots) => updateAt(slots, path, () => node));
+            }),
+            remove: action((path) => {
+                if (path.length === 0)
+                    return;
+                editContent((slots) => removeAt(slots, path));
+            }),
+            setNodeProps: action(setNodeProps),
+            setText: action((path, text) => {
+                editContent((slots) => updateAt(slots, path, (node) => node.kind === 'text' ? { ...node, value: text } : node));
+            }),
+            resolveDrop(drop) {
+                const move = resolveSortableMove(drop.source, drop.target, drop.sameList, drop.fromIndex, drop.toIndex);
+                return { from: move.from, to: move.target };
+            },
+        },
+        frames: {
+            mount: (element, target) => mountFrame(element, { target }, target, componentFrameUrl(target, reloadCount, baseUrl)),
+            mountView: (element, viewId) => mountFrame(element, { target: 'view' }, viewId, viewFrameUrl(viewId, catalog.views.find((view) => view.id === viewId)?.framework, baseUrl)),
+            mountStory,
+            mountCode,
+            wrapCode(wrap) {
+                if (wrap === codeWrap)
+                    return;
+                codeWrap = wrap;
+                postCode(true);
+            },
+            reload: action((target) => {
+                const next = { ...state.frames };
+                for (const frame of frames) {
+                    if (frame.story || frame.target !== target)
+                        continue;
+                    conceal(frame.iframe);
+                    frame.iframe.contentWindow?.location.reload();
+                    next[target] = 'loading';
+                }
+                commit({ frames: next });
+            }),
+            standaloneUrl: (target) => {
+                // The scratch story holds the root's text as content, not as a prop.
+                const tree = state.editor.tree;
+                const scratch = scratchActive && tree !== undefined;
+                return standaloneFrameUrl(target, {
+                    id: scratch ? SCRATCH_STORY_ID : selectionStoryId(),
+                    props: paneProps(scratch ? tree.props : state.props, scratch ? componentByName(tree.root) : selectedComponent()),
+                    options: kitValues(state.options),
+                }, baseUrl);
+            },
+        },
+        dispose,
+    };
+}