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

package/dist/controller/editor-tree.d.ts

@@ -0,0 +1,161 @@
+import type { AroundFill, JsonValue, SlotFill, SlotPlan, StoryAround } from '../lib/types.js';
+export type { AroundFill, SlotFill, SlotPlan, StoryAround };
+type Json = unknown;
+/** A fill the editor cannot author: a `raw` body, a `scoped` slot or a
+ *  `part` call, each per-target strings. It is held verbatim, so it can be
+ *  moved or removed but not edited, and serializes back unchanged. */
+export type OpaqueFill = Extract<SlotFill, {
+    kind: 'raw' | 'scoped' | 'part';
+}>;
+export type EditorNode = {
+    kind: 'text';
+    value: string;
+    id?: string;
+} | {
+    kind: 'element';
+    component: string;
+    props: Record<string, Json>;
+    slots: Record<string, EditorNode[]>;
+    id?: string;
+} | {
+    kind: 'html';
+    tag: string;
+    props: Record<string, Json>;
+    slots: Record<string, EditorNode[]>;
+    id?: string;
+} | {
+    kind: 'opaque';
+    fill: OpaqueFill;
+    id?: string;
+};
+/** A node that holds content of its own: an element or an HTML tag. */
+export type ContainerNode = Extract<EditorNode, {
+    kind: 'element' | 'html';
+}>;
+export declare function isContainer(node: EditorNode): node is ContainerNode;
+export declare const DEFAULT_SLOT = "default";
+/** The plain wrapper tags an HTML node can be, picked from a list rather than
+ *  typed: the layout and content elements a slot fill might need around its
+ *  children. */
+export declare const HTML_TAGS: string[];
+/** Gives every node in the content an id, in place: idempotent, and the spreads
+ *  every update makes carry a node's id along. */
+export declare function ensureIds(content: Record<string, EditorNode[]>): void;
+/** The root's state: its component, its props and its content keyed by
+ *  slot. The content the story renders beside the root is not the tree's: it
+ *  is the story's (`PreviewComponent.around`), which no edit reaches. */
+export interface EditorState {
+    root: string;
+    props: Record<string, Json>;
+    slots: Record<string, EditorNode[]>;
+}
+/** One hop into a slot: which slot, and the node's index in it. */
+export interface Step {
+    slot: string;
+    index: number;
+}
+/** A node's address: the hops from the root, one per slot it descends into.
+ *  The empty path `[]` addresses the root itself. */
+export type NodePath = Step[];
+/** Where a move lands: into `slot` of the node at `parent`, before `index`
+ *  (counted before the moved node is removed). */
+export interface DropTarget {
+    parent: Step[];
+    slot: string;
+    index: number;
+}
+/** Apply `transform` to the node at `path` (path must be non-empty). */
+export declare function updateAt(content: Record<string, EditorNode[]>, path: Step[], transform: (node: EditorNode) => EditorNode): Record<string, EditorNode[]>;
+/** Insert `child` into `slot` of the node at `parentPath` (empty path = the
+ *  root's slots) at `index`; an omitted index appends. */
+export declare function insertAt(content: Record<string, EditorNode[]>, parentPath: Step[], slot: string, child: EditorNode, index?: number): Record<string, EditorNode[]>;
+/** Remove the node at `path` (path must be non-empty). */
+export declare function removeAt(content: Record<string, EditorNode[]>, path: Step[]): Record<string, EditorNode[]>;
+/** The node at `path`, or null when nothing is there. The root is the tree
+ *  itself rather than a node of its content, so the empty path gives null. */
+export declare function nodeAt(content: Record<string, EditorNode[]>, path: Step[]): EditorNode | null;
+/**
+ * The path of a child: the node at `index` in `slot` of the node at `parent`.
+ *
+ * @param parent - The parent's path; `[]` for the root.
+ * @param slot - The slot the child is in.
+ * @param index - The child's index in the slot.
+ * @returns The child's path.
+ */
+export declare function childPath(parent: NodePath, slot: string, index: number): NodePath;
+/**
+ * A string that identifies a path, for a key or a lookup: `'root'` for the
+ * root, otherwise each step's slot and index.
+ *
+ * @param path - The path.
+ * @returns The key, such as `'default:0/header:1'`.
+ */
+export declare function pathKey(path: NodePath): string;
+/** Move the node at `from` to `target`: remove it, then insert it, adjusting the
+ *  target for the index shift the removal causes in a shared sibling list. The
+ *  root, a missing node, and a drop into the node's own subtree leave the
+ *  content unchanged (the same object back). */
+export declare function moveNode(content: Record<string, EditorNode[]>, from: Step[], target: DropTarget): Record<string, EditorNode[]>;
+/** A sortable list's address: the parent whose slot it lists, and the slot. */
+export interface SortableListAddress {
+    parent: Step[];
+    slot: string;
+}
+/** Translate a sortable move (where the node ends up in its list) into the path
+ *  it leaves and the drop target `moveNode` takes (the index it goes before,
+ *  counted before the removal). */
+export declare function resolveSortableMove(source: SortableListAddress, target: SortableListAddress, sameList: boolean, fromIndex: number, toIndex: number): {
+    from: Step[];
+    target: DropTarget;
+};
+/** What the editor reads of a manifest component to seed a node from it. */
+export interface SeedableComponent {
+    name: string;
+    defaultProps: Record<string, Json>;
+    content?: SlotPlan;
+}
+/** A component swapped in under an existing node: its default props, with a
+ *  string `children` default as a default-slot text child (children is the
+ *  default slot, not a prop). */
+export declare function seedNode(component: SeedableComponent): EditorNode;
+/** A component added through the add dialog. With `props` the node carries them
+ *  plus the component's curated slot content (the default or a named scenario);
+ *  without, it comes in empty - no props, no content. */
+export declare function seedComponentNode(component: SeedableComponent, props?: Record<string, Json>): EditorNode;
+/** The root seeded from its story file content, so the tree starts from what the
+ *  browse view renders, with `props` (a story's scenario-merged props) or the
+ *  component's defaults. */
+export declare function seedRoot(component: SeedableComponent, props?: Record<string, Json>): EditorState;
+/**
+ * A key for a tree's slot content, equal for two trees of the same content
+ * whatever their node ids or the order of their props' keys: what the
+ * regeneration payload would carry, serialized with sorted keys.
+ */
+export declare function slotsKey(slots: Record<string, EditorNode[]>): string;
+/** A value as JSON with every object's keys sorted, so two values equal by
+ *  content serialize the same; `undefined` entries are left out. */
+export declare function stableStringify(value: unknown): string;
+/**
+ * The props as JSON, each one left unset (`undefined`) left out. An empty
+ * string is a value like any other and stays, so a component given `''`
+ * keeps it on every update; a story unsets a prop with `null`.
+ *
+ * @param record - The props, from the controls or a pane's write-back.
+ * @returns The props that are set.
+ */
+export declare function cleanRecord(record: Record<string, Json>): Record<string, JsonValue>;
+export declare function namedFills(slots: Record<string, EditorNode[]>): Record<string, SlotFill>;
+export declare function fillToNodes(fill: SlotFill | undefined): EditorNode[];
+/** Seed a root component's slot content from its story file SlotPlan, falling back to
+ *  a default-slot text child when a string `children` prop is the only content. */
+export declare function seedSlots(content: SlotPlan | undefined, props: Record<string, Json>): Record<string, EditorNode[]>;
+/** The regeneration payload for a root component, its props and its slot
+ *  content. */
+export declare function toPayload(state: EditorState): {
+    rootComponent: string;
+    props: Record<string, JsonValue>;
+    slots: {
+        named?: Record<string, SlotFill> | undefined;
+        default?: SlotFill | undefined;
+    } | undefined;
+};

package/dist/controller/editor-tree.js

@@ -0,0 +1,373 @@
+export function isContainer(node) {
+    return node.kind === 'element' || node.kind === 'html';
+}
+export const DEFAULT_SLOT = 'default';
+/** The plain wrapper tags an HTML node can be, picked from a list rather than
+ *  typed: the layout and content elements a slot fill might need around its
+ *  children. */
+export const HTML_TAGS = [
+    'div',
+    'section',
+    'article',
+    'aside',
+    'header',
+    'footer',
+    'main',
+    'nav',
+    'p',
+    'span',
+    'strong',
+    'em',
+    'small',
+    'code',
+    'pre',
+    'blockquote',
+    'ul',
+    'ol',
+    'li',
+];
+let nodeIdCounter = 0;
+/** Gives every node in the content an id, in place: idempotent, and the spreads
+ *  every update makes carry a node's id along. */
+export function ensureIds(content) {
+    for (const list of Object.values(content)) {
+        for (const node of list) {
+            if (!node.id)
+                node.id = `editor-node-${nodeIdCounter++}`;
+            if (isContainer(node))
+                ensureIds(node.slots);
+        }
+    }
+}
+/** Apply `transform` to the node at `path` (path must be non-empty). */
+export function updateAt(content, path, transform) {
+    const [step, ...rest] = path;
+    const list = content[step.slot] ?? [];
+    const nextList = list.map((node, index) => {
+        if (index !== step.index)
+            return node;
+        if (rest.length === 0)
+            return transform(node);
+        if (!isContainer(node))
+            return node;
+        return { ...node, slots: updateAt(node.slots, rest, transform) };
+    });
+    return { ...content, [step.slot]: nextList };
+}
+/** Insert `child` into `slot` of the node at `parentPath` (empty path = the
+ *  root's slots) at `index`; an omitted index appends. */
+export function insertAt(content, parentPath, slot, child, index) {
+    if (parentPath.length === 0) {
+        const list = content[slot] ?? [];
+        const at = index ?? list.length;
+        return {
+            ...content,
+            [slot]: [...list.slice(0, at), child, ...list.slice(at)],
+        };
+    }
+    const [step, ...rest] = parentPath;
+    const list = content[step.slot] ?? [];
+    const nextList = list.map((node, position) => position === step.index && isContainer(node)
+        ? { ...node, slots: insertAt(node.slots, rest, slot, child, index) }
+        : node);
+    return { ...content, [step.slot]: nextList };
+}
+/** Remove the node at `path` (path must be non-empty). */
+export function removeAt(content, path) {
+    const [step, ...rest] = path;
+    const list = content[step.slot] ?? [];
+    if (rest.length === 0)
+        return {
+            ...content,
+            [step.slot]: list.filter((_, index) => index !== step.index),
+        };
+    const nextList = list.map((node, index) => index === step.index && isContainer(node)
+        ? { ...node, slots: removeAt(node.slots, rest) }
+        : node);
+    return { ...content, [step.slot]: nextList };
+}
+/** The node at `path`, or null when nothing is there. The root is the tree
+ *  itself rather than a node of its content, so the empty path gives null. */
+export function nodeAt(content, path) {
+    let slots = content;
+    let node = null;
+    for (const step of path) {
+        node = (slots[step.slot] ?? [])[step.index] ?? null;
+        if (!node)
+            return null;
+        slots = isContainer(node) ? node.slots : {};
+    }
+    return node;
+}
+/**
+ * The path of a child: the node at `index` in `slot` of the node at `parent`.
+ *
+ * @param parent - The parent's path; `[]` for the root.
+ * @param slot - The slot the child is in.
+ * @param index - The child's index in the slot.
+ * @returns The child's path.
+ */
+export function childPath(parent, slot, index) {
+    return [...parent, { slot, index }];
+}
+/**
+ * A string that identifies a path, for a key or a lookup: `'root'` for the
+ * root, otherwise each step's slot and index.
+ *
+ * @param path - The path.
+ * @returns The key, such as `'default:0/header:1'`.
+ */
+export function pathKey(path) {
+    return path.length === 0
+        ? 'root'
+        : path.map((step) => `${step.slot}:${step.index}`).join('/');
+}
+/** True if `candidate` addresses `path` itself or one of its ancestors
+ *  (`candidate` is a prefix of `path`). Used to forbid dropping a node into its
+ *  own subtree. */
+function isAncestorOrSelf(candidate, path) {
+    if (candidate.length > path.length)
+        return false;
+    return candidate.every((step, position) => step.slot === path[position].slot && step.index === path[position].index);
+}
+/** Removing the node at `from` shifts the indices of its later siblings, so a
+ *  target parent path that runs through one of them shifts down by one. */
+function adjustForRemoval(target, from) {
+    const fromParent = from.slice(0, -1);
+    const fromStep = from[from.length - 1];
+    if (target.length <= fromParent.length)
+        return target;
+    for (let k = 0; k < fromParent.length; k++) {
+        if (target[k].slot !== fromParent[k].slot ||
+            target[k].index !== fromParent[k].index)
+            return target;
+    }
+    const divergence = target[fromParent.length];
+    if (divergence.slot === fromStep.slot && divergence.index > fromStep.index) {
+        const next = [...target];
+        next[fromParent.length] = { ...divergence, index: divergence.index - 1 };
+        return next;
+    }
+    return target;
+}
+/** Move the node at `from` to `target`: remove it, then insert it, adjusting the
+ *  target for the index shift the removal causes in a shared sibling list. The
+ *  root, a missing node, and a drop into the node's own subtree leave the
+ *  content unchanged (the same object back). */
+export function moveNode(content, from, target) {
+    if (from.length === 0)
+        return content;
+    if (isAncestorOrSelf(from, target.parent))
+        return content;
+    const node = nodeAt(content, from);
+    if (!node)
+        return content;
+    const fromParent = from.slice(0, -1);
+    const fromStep = from[from.length - 1];
+    const sameList = pathKey(fromParent) === pathKey(target.parent) &&
+        fromStep.slot === target.slot;
+    const index = sameList && fromStep.index < target.index ? target.index - 1 : target.index;
+    const removed = removeAt(content, from);
+    return insertAt(removed, adjustForRemoval(target.parent, from), target.slot, node, index);
+}
+/** Translate a sortable move (where the node ends up in its list) into the path
+ *  it leaves and the drop target `moveNode` takes (the index it goes before,
+ *  counted before the removal). */
+export function resolveSortableMove(source, target, sameList, fromIndex, toIndex) {
+    return {
+        from: childPath(source.parent, source.slot, fromIndex),
+        target: {
+            parent: target.parent,
+            slot: target.slot,
+            index: sameList && toIndex > fromIndex ? toIndex + 1 : toIndex,
+        },
+    };
+}
+/** A component swapped in under an existing node: its default props, with a
+ *  string `children` default as a default-slot text child (children is the
+ *  default slot, not a prop). */
+export function seedNode(component) {
+    const props = { ...component.defaultProps };
+    const slots = {};
+    if (typeof props.children === 'string')
+        slots[DEFAULT_SLOT] = [{ kind: 'text', value: props.children }];
+    delete props.children;
+    return { kind: 'element', component: component.name, props, slots };
+}
+/** A component added through the add dialog. With `props` the node carries them
+ *  plus the component's curated slot content (the default or a named scenario);
+ *  without, it comes in empty - no props, no content. */
+export function seedComponentNode(component, props) {
+    if (!props)
+        return { kind: 'element', component: component.name, props: {}, slots: {} };
+    const nodeProps = { ...props };
+    const slots = seedSlots(component.content, nodeProps);
+    delete nodeProps.children;
+    return {
+        kind: 'element',
+        component: component.name,
+        props: nodeProps,
+        slots,
+    };
+}
+/** The root seeded from its story file content, so the tree starts from what the
+ *  browse view renders, with `props` (a story's scenario-merged props) or the
+ *  component's defaults. */
+export function seedRoot(component, props) {
+    const rootProps = { ...(props ?? component.defaultProps) };
+    const slots = seedSlots(component.content, rootProps);
+    delete rootProps.children;
+    return { root: component.name, props: rootProps, slots };
+}
+/**
+ * A key for a tree's slot content, equal for two trees of the same content
+ * whatever their node ids or the order of their props' keys: what the
+ * regeneration payload would carry, serialized with sorted keys.
+ */
+export function slotsKey(slots) {
+    return stableStringify(toPayload({ root: '', props: {}, slots }).slots);
+}
+/** A value as JSON with every object's keys sorted, so two values equal by
+ *  content serialize the same; `undefined` entries are left out. */
+export function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+// --- serialization to the regeneration payload -------------------------------------
+/**
+ * The props as JSON, each one left unset (`undefined`) left out. An empty
+ * string is a value like any other and stays, so a component given `''`
+ * keeps it on every update; a story unsets a prop with `null`.
+ *
+ * @param record - The props, from the controls or a pane's write-back.
+ * @returns The props that are set.
+ */
+export function cleanRecord(record) {
+    const out = {};
+    for (const [key, value] of Object.entries(record))
+        if (value !== undefined)
+            out[key] = value;
+    return out;
+}
+function listToFill(nodes) {
+    const fills = nodes.map(nodeToFill);
+    if (fills.length === 0)
+        return undefined;
+    if (fills.length === 1)
+        return fills[0];
+    return { kind: 'fragment', children: fills };
+}
+export function namedFills(slots) {
+    const out = {};
+    for (const [name, nodes] of Object.entries(slots)) {
+        if (name === DEFAULT_SLOT)
+            continue;
+        const fill = listToFill(nodes);
+        if (fill)
+            out[name] = fill;
+    }
+    return out;
+}
+function nodeToFill(node) {
+    if (node.kind === 'text')
+        return { kind: 'text', value: node.value };
+    if (node.kind === 'opaque')
+        return node.fill;
+    const children = listToFill(node.slots[DEFAULT_SLOT] ?? []);
+    if (node.kind === 'html') {
+        return {
+            kind: 'html',
+            tag: node.tag,
+            props: cleanRecord(node.props),
+            ...(children ? { children } : {}),
+        };
+    }
+    const named = namedFills(node.slots);
+    return {
+        kind: 'element',
+        component: node.component,
+        props: cleanRecord(node.props),
+        ...(children ? { children } : {}),
+        ...(Object.keys(named).length ? { slots: named } : {}),
+    };
+}
+// --- seeding from story file content (SlotFill → EditorNode) --------------------
+// Inverse of nodeToFill: turn a story file's SlotFill into the editor's node list so
+// a per-story tree starts from the curated content the browse view renders. A
+// `fragment` flattens into its siblings; a `raw` or `scoped` fill or a call to
+// a part becomes one opaque node that keeps the fill as authored.
+export function fillToNodes(fill) {
+    if (!fill)
+        return [];
+    if (fill.kind === 'text')
+        return [{ kind: 'text', value: fill.value }];
+    if (fill.kind === 'fragment')
+        return fill.children.flatMap(fillToNodes);
+    if (fill.kind === 'raw' || fill.kind === 'scoped' || fill.kind === 'part')
+        return [{ kind: 'opaque', fill }];
+    const slots = {};
+    const def = fillToNodes(fill.children);
+    if (def.length)
+        slots[DEFAULT_SLOT] = def;
+    if (fill.kind === 'html') {
+        return [
+            { kind: 'html', tag: fill.tag, props: { ...(fill.props ?? {}) }, slots },
+        ];
+    }
+    for (const [name, named] of Object.entries(fill.slots ?? {})) {
+        const nodes = fillToNodes(named);
+        if (nodes.length)
+            slots[name] = nodes;
+    }
+    return [
+        {
+            kind: 'element',
+            component: fill.component,
+            props: { ...(fill.props ?? {}) },
+            slots,
+        },
+    ];
+}
+/** Seed a root component's slot content from its story file SlotPlan, falling back to
+ *  a default-slot text child when a string `children` prop is the only content. */
+export function seedSlots(content, props) {
+    if (content) {
+        const slots = {};
+        const def = fillToNodes(content.default);
+        if (def.length)
+            slots[DEFAULT_SLOT] = def;
+        for (const [name, fill] of Object.entries(content.named ?? {})) {
+            const nodes = fillToNodes(fill);
+            if (nodes.length)
+                slots[name] = nodes;
+        }
+        return slots;
+    }
+    if (typeof props.children === 'string')
+        return { [DEFAULT_SLOT]: [{ kind: 'text', value: props.children }] };
+    return {};
+}
+/** The regeneration payload for a root component, its props and its slot
+ *  content. */
+export function toPayload(state) {
+    const def = listToFill(state.slots[DEFAULT_SLOT] ?? []);
+    const named = namedFills(state.slots);
+    const hasContent = def || Object.keys(named).length > 0;
+    return {
+        rootComponent: state.root,
+        props: cleanRecord(state.props),
+        slots: hasContent
+            ? {
+                ...(def ? { default: def } : {}),
+                ...(Object.keys(named).length ? { named } : {}),
+            }
+            : undefined,
+    };
+}

package/dist/controller/html-source.d.ts

@@ -0,0 +1,62 @@
+import type { JsonValue, SlotPlan, StoryAround } from '../lib/types.js';
+/** A story to print as html: the root component, its props and its slot content. */
+export interface HtmlSourceRequest {
+    /** The root component's name. */
+    rootComponent: string;
+    /** The props to render it with. */
+    props: Record<string, JsonValue>;
+    /** Its slot content: the default slot and the named slots. */
+    slots?: SlotPlan;
+    /** The content beside the root, as its siblings: `before` and `after` it. */
+    around?: StoryAround;
+}
+/**
+ * A story's html: its markup, with the styles the kit's build wrote for the
+ * components it renders when there are any and the warnings for what the
+ * markup leaves out when there are any, or what keeps it from having markup.
+ */
+export type HtmlSourceResponse = {
+    markup: string;
+    stylesheet?: string;
+    warnings?: string[];
+} | {
+    missing: string[];
+};
+/**
+ * Prints a story's html. It resolves with the markup or what the story holds
+ * that has no markup, and rejects with the reason it could not print; the
+ * controller aborts `signal` when the story changes before it answers.
+ */
+export type HtmlSourceTransport = (request: HtmlSourceRequest, signal: AbortSignal) => Promise<HtmlSourceResponse>;
+/**
+ * Reads the html printed ahead of time for a component's scenarios, by
+ * scenario id (`''` for the anonymous default). It rejects when there is
+ * none to read.
+ */
+export type ScenarioHtmlSourceLoader = (componentId: string) => Promise<Record<string, HtmlSourceResponse>>;
+/** The path the preview's development server answers html source requests on. */
+export declare const HTML_SOURCE_ENDPOINT = "/__preview_html_source";
+/** The directory, under the URL the preview is served from, that the static
+ *  build keeps each component's scenario html in, one `<component id>.json`
+ *  each. */
+export declare const HTML_SOURCE_DIRECTORY = "html-source";
+/**
+ * A transport that POSTs the story as JSON to the development server's html
+ * source endpoint and reads the JSON it answers. A response that is not ok
+ * rejects with the response's text, or its status when the text is empty.
+ *
+ * @param endpoint - The endpoint's path; the development server's by default.
+ * @param fetchImplementation - The `fetch` to use; the global one by default.
+ * @returns The transport.
+ */
+export declare function createFetchHtmlSourceTransport(endpoint?: string, fetchImplementation?: typeof fetch): HtmlSourceTransport;
+/**
+ * A loader that fetches a component's scenario html from the files the
+ * static build serves, `<baseUrl>html-source/<component id>.json`, once per
+ * component.
+ *
+ * @param baseUrl - The URL the preview is served under, ending in `/`.
+ * @param fetchImplementation - The `fetch` to use; the global one by default.
+ * @returns The loader.
+ */
+export declare function createStaticHtmlSourceLoader(baseUrl: string, fetchImplementation?: typeof fetch): ScenarioHtmlSourceLoader;

package/dist/controller/html-source.js

@@ -0,0 +1,61 @@
+// Where the controller gets a story's html source: the markup the story
+// renders to, which needs the kit's templates and so cannot be printed in the
+// browser. The development server prints it for any story on request; the
+// static build prints it once per scenario and serves one file per
+// component. A controller with neither reports html as unavailable.
+// Browser-safe.
+/** The path the preview's development server answers html source requests on. */
+export const HTML_SOURCE_ENDPOINT = '/__preview_html_source';
+/** The directory, under the URL the preview is served from, that the static
+ *  build keeps each component's scenario html in, one `<component id>.json`
+ *  each. */
+export const HTML_SOURCE_DIRECTORY = 'html-source';
+/**
+ * A transport that POSTs the story as JSON to the development server's html
+ * source endpoint and reads the JSON it answers. A response that is not ok
+ * rejects with the response's text, or its status when the text is empty.
+ *
+ * @param endpoint - The endpoint's path; the development server's by default.
+ * @param fetchImplementation - The `fetch` to use; the global one by default.
+ * @returns The transport.
+ */
+export function createFetchHtmlSourceTransport(endpoint = HTML_SOURCE_ENDPOINT, fetchImplementation = (...parameters) => fetch(...parameters)) {
+    return async (request, signal) => {
+        const response = await fetchImplementation(endpoint, {
+            method: 'POST',
+            body: JSON.stringify(request),
+            signal,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            throw new Error(text || `HTTP ${response.status}`);
+        }
+        return (await response.json());
+    };
+}
+/**
+ * A loader that fetches a component's scenario html from the files the
+ * static build serves, `<baseUrl>html-source/<component id>.json`, once per
+ * component.
+ *
+ * @param baseUrl - The URL the preview is served under, ending in `/`.
+ * @param fetchImplementation - The `fetch` to use; the global one by default.
+ * @returns The loader.
+ */
+export function createStaticHtmlSourceLoader(baseUrl, fetchImplementation = (...parameters) => fetch(...parameters)) {
+    const loaded = new Map();
+    return (componentId) => {
+        let pending = loaded.get(componentId);
+        if (!pending) {
+            pending = fetchImplementation(`${baseUrl}${HTML_SOURCE_DIRECTORY}/${encodeURIComponent(componentId)}.json`).then(async (response) => {
+                if (!response.ok)
+                    throw new Error(`HTTP ${response.status}`);
+                return (await response.json());
+            });
+            // A failed read is tried again the next time.
+            pending.catch(() => loaded.delete(componentId));
+            loaded.set(componentId, pending);
+        }
+        return pending;
+    };
+}

package/dist/controller/index.d.ts

@@ -0,0 +1,9 @@
+export { createPreviewController, PREVIEW_FRAME_SHOWN_ATTRIBUTE, REGENERATION_DEBOUNCE_MILLISECONDS, SCRATCH_STORY_ID, type PreviewController, type PreviewControllerOptions, type PreviewEditorState, type PreviewEvent, type PreviewFrameReadiness, type PreviewFrameTarget, type PreviewHtmlSource, type PreviewInsertTarget, type PreviewNodeRequest, type PreviewOptionDescriptor, type PreviewRegenerationStatus, type PreviewSelection, type PreviewSortableDrop, type PreviewCode, type PreviewState, type PreviewTimers, } from './create-preview-controller.js';
+export { printStorySource, type PreviewTargetCode } from './source.js';
+export { createFetchHtmlSourceTransport, createStaticHtmlSourceLoader, HTML_SOURCE_DIRECTORY, HTML_SOURCE_ENDPOINT, type HtmlSourceRequest, type HtmlSourceResponse, type HtmlSourceTransport, type ScenarioHtmlSourceLoader, } from './html-source.js';
+export { previewStore, type PreviewStore } from './store.js';
+export type { PreviewPaneWidth } from '../lib/types.js';
+export { catalogFromManifest, DEFAULT_PANE_WIDTHS, defaultScenarioId, nodeAddSlots, nodeSlots, scenarioChoices, storyFrameKey, type CatalogManifest, type PreviewBinding, type PreviewCatalog, type PreviewCatalogView, type PreviewComponent, type PreviewImport, type PreviewLanding, type PreviewNavigationNode, type PreviewPropType, type PreviewScenario, type PreviewSource, type PreviewStoryReference, type ScenarioChoice, } from './catalog.js';
+export { acceptsPropValue, changedProps, isPaneWidth, MAXIMUM_PANE_WIDTH, parseTargets, parseOptionValue, parsePaneWidth, parseProps, readUrlState, storageKey, URL_PARAMETER, writeUrlState, type PreviewStorage, type UrlState, type UrlStateToWrite, } from './persistence.js';
+export { createFetchRegenerationTransport, REGENERATION_ENDPOINT, type RegenerationPayload, type RegenerationTransport, } from './regeneration.js';
+export { childPath, cleanRecord, DEFAULT_SLOT, HTML_TAGS, isContainer, nodeAt, pathKey, seedNode, type AroundFill, type ContainerNode, type DropTarget, type EditorNode, type EditorState, type NodePath, type OpaqueFill, type SortableListAddress, type Step, type StoryAround, } from './editor-tree.js';

package/dist/controller/index.js

@@ -0,0 +1,12 @@
+// The preview controller and what a shell reads from it: the catalog, the
+// state, the editor's tree types and operations, the regeneration transport, and the
+// query parameters it keeps its state in.
+// Browser-safe: no node imports.
+export { createPreviewController, PREVIEW_FRAME_SHOWN_ATTRIBUTE, REGENERATION_DEBOUNCE_MILLISECONDS, SCRATCH_STORY_ID, } from './create-preview-controller.js';
+export { printStorySource } from './source.js';
+export { createFetchHtmlSourceTransport, createStaticHtmlSourceLoader, HTML_SOURCE_DIRECTORY, HTML_SOURCE_ENDPOINT, } from './html-source.js';
+export { previewStore } from './store.js';
+export { catalogFromManifest, DEFAULT_PANE_WIDTHS, defaultScenarioId, nodeAddSlots, nodeSlots, scenarioChoices, storyFrameKey, } from './catalog.js';
+export { acceptsPropValue, changedProps, isPaneWidth, MAXIMUM_PANE_WIDTH, parseTargets, parseOptionValue, parsePaneWidth, parseProps, readUrlState, storageKey, URL_PARAMETER, writeUrlState, } from './persistence.js';
+export { createFetchRegenerationTransport, REGENERATION_ENDPOINT, } from './regeneration.js';
+export { childPath, cleanRecord, DEFAULT_SLOT, HTML_TAGS, isContainer, nodeAt, pathKey, seedNode, } from './editor-tree.js';