forgebook 0.1.8 → 0.2.0

package/dist/src/packedText.js

@@ -0,0 +1,36 @@
+/**
+ * What a build keeps gzipped, unpacked in the page when it is asked for: what a static catalogue weighs most and reads
+ * least (axe's script, "Used in"). A build names such files `.bin`, since `.gz` makes some hosts send them with
+ * `Content-Encoding: gzip`, which the browser would unpack before the page does.
+ *
+ * @module
+ */
+/**
+ * A gzipped file's content, unpacked.
+ *
+ * @param address - the file's address.
+ * @throws when it cannot be fetched.
+ */
+const unpacked = async (address) => {
+    const response = await fetch(address);
+    if (!response.ok || response.body === null)
+        throw new Error(`${address} could not be loaded (${response.status})`);
+    return new Response(response.body.pipeThrough(new DecompressionStream("gzip")));
+};
+/**
+ * A gzipped script, at an address a script element can load: a blob URL, which its loader revokes once it ran.
+ *
+ * @param address - the file's address.
+ * @throws when it cannot be fetched.
+ */
+export const unpackedScript = async (address) => {
+    const script = await (await unpacked(address)).arrayBuffer();
+    return URL.createObjectURL(new Blob([script], { type: "text/javascript" }));
+};
+/**
+ * A gzipped JSON document, parsed.
+ *
+ * @param address - the file's address.
+ * @throws when it cannot be fetched, or is not JSON.
+ */
+export const packedJson = async (address) => (await unpacked(address)).json();

package/dist/src/pageAddress.d.ts

@@ -0,0 +1,26 @@
+/**
+ * How a docs page is named in an address: its slug and a heading's anchor.
+ *
+ * @remarks
+ * Apart from the rest of what the plugin and the shell share (`docPages.ts`) because the tree and the address need these
+ * on every catalogue's first load, and a catalogue that opens no page must not pay for the rest. Pure.
+ *
+ * @module
+ */
+/**
+ * A fragment read back as a heading's anchor: a `%` that encodes nothing stays as written.
+ *
+ * @param fragment - the fragment, without its `#`; none when there is none.
+ * @returns the anchor; none for an empty fragment.
+ */
+export declare const anchorOf: (fragment: string | undefined) => string | undefined;
+/**
+ * A page's slug: the part of its id after the source's, from its title.
+ *
+ * @remarks
+ * As CSF writes ids (`kebab`), keeping every language's letters: a title in Japanese would otherwise have no slug at
+ * all, and two such pages would collide. For a Latin title the two agree.
+ *
+ * @param title - the page's title.
+ */
+export declare const pageSlug: (title: string) => string;

package/dist/src/pageAddress.js

@@ -0,0 +1,39 @@
+/**
+ * How a docs page is named in an address: its slug and a heading's anchor.
+ *
+ * @remarks
+ * Apart from the rest of what the plugin and the shell share (`docPages.ts`) because the tree and the address need these
+ * on every catalogue's first load, and a catalogue that opens no page must not pay for the rest. Pure.
+ *
+ * @module
+ */
+/**
+ * A fragment read back as a heading's anchor: a `%` that encodes nothing stays as written.
+ *
+ * @param fragment - the fragment, without its `#`; none when there is none.
+ * @returns the anchor; none for an empty fragment.
+ */
+export const anchorOf = (fragment) => {
+    if (fragment === undefined || fragment === "")
+        return undefined;
+    try {
+        return decodeURIComponent(fragment);
+    }
+    catch {
+        return fragment;
+    }
+};
+/**
+ * A page's slug: the part of its id after the source's, from its title.
+ *
+ * @remarks
+ * As CSF writes ids (`kebab`), keeping every language's letters: a title in Japanese would otherwise have no slug at
+ * all, and two such pages would collide. For a Latin title the two agree.
+ *
+ * @param title - the page's title.
+ */
+export const pageSlug = (title) => title
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, "-")
+    .replace(/^-|-$/g, "");

package/dist/src/pageConfig.d.ts

@@ -6,6 +6,7 @@
  */
 import type { StoryLanguage } from "@forgebook/story-format/source";
 import type { CatalogueLists } from "./catalogue.ts";
+import type { FramesPlacement } from "./frameOrigins.ts";
 import type { ViewSwitch } from "./switches.ts";
 /** What the shell and the frame pages read of a configuration: data, as the plugin hands it to them. */
 export type PageConfig = {
@@ -19,5 +20,6 @@ export type PageConfig = {
     readonly languages: readonly StoryLanguage[];
     /** The lists (widths, backgrounds, story groups, texts…), the presets' and the catalogue's merged. */
     readonly lists: CatalogueLists;
+    /** Where the frames run: the shell loads them there, and each side hears only the other's origin. */
+    readonly frames: FramesPlacement;
 };
-//# sourceMappingURL=pageConfig.d.ts.map

package/dist/src/pageConfig.js

@@ -1 +0,0 @@
-//# sourceMappingURL=pageConfig.js.map

package/dist/src/pageTree.d.ts

@@ -0,0 +1,79 @@
+/**
+ * A catalogue's docs pages in its tree: their ids, their places and reading order, built from the sources' indexes, and
+ * what they name that the tree does not have.
+ *
+ * @remarks
+ * A page's place comes from its title, as a component's does: `Guides/Theming` is a page of the group Guides, so the
+ * sidebar needs no list kept by hand. Its id is the title in kebab case, prefixed by the source's id. Pure.
+ *
+ * @module
+ */
+import type { StorySource } from "@forgebook/story-format/source";
+import type { StoryTree, TreeSource } from "./storyTree.ts";
+/** One docs page. */
+export type TreePage = {
+    /** `<source>:<slug>`: the URL's `page` parameter. */
+    readonly id: string;
+    /** The part of its id after the source's: what a link between two pages of a source names. */
+    readonly slug: string;
+    /** The last segment of the title (`Theming`). */
+    readonly name: string;
+    /** The whole title (`Guides/Theming`). */
+    readonly title: string;
+    /** The segments before the name; none for a page outside any group. */
+    readonly group: string | undefined;
+    /** Its file, a key of the source's pages. */
+    readonly file: string;
+    /** What it is about, in a sentence; none when it does not say. */
+    readonly description: string | undefined;
+    /** The ids of the stories it shows. */
+    readonly stories: readonly string[];
+    /** The ids of the components whose API tables it shows. */
+    readonly components: readonly string[];
+    /** The slugs of the pages it links to. */
+    readonly links: readonly string[];
+};
+/**
+ * The docs pages of one source, from their index; a title that cannot be placed, or is taken, is a problem.
+ *
+ * @param source - the source.
+ * @param problems - receives the problems.
+ */
+export declare const treePages: (source: StorySource, problems: string[]) => TreePage[];
+/**
+ * What the docs pages name that the tree does not have: a story or a component renamed under a page must fail the
+ * index, or the page would break unseen.
+ *
+ * @param sources - the tree's sources.
+ * @param stories - the ids of its stories.
+ * @param components - the ids of its components.
+ */
+export declare const pageProblems: (sources: readonly TreeSource[], stories: ReadonlySet<string>, components: ReadonlySet<string>) => string[];
+/** Where a docs page is. */
+export type PageLocation = {
+    /** Its source. */
+    readonly source: TreeSource;
+    /** The page. */
+    readonly page: TreePage;
+};
+/**
+ * Finds a docs page by its id.
+ *
+ * @param tree - the tree.
+ * @param id - the page's id.
+ */
+export declare const findPage: (tree: StoryTree, id: string) => PageLocation | undefined;
+/** A source's docs pages under one heading. */
+export type PageGroup = {
+    /** The heading; none for pages outside any group. */
+    readonly name: string | undefined;
+    /** Its pages, in their order. */
+    readonly pages: readonly TreePage[];
+};
+/**
+ * Pages under their headings, in reading order: a named group sits where its first page is and takes all its pages, and
+ * pages without a group stay between the groups where their order puts them.
+ *
+ * @param pages - the pages, in their order.
+ */
+export declare const pageGroups: (pages: readonly TreePage[]) => PageGroup[];

package/dist/src/pageTree.js

@@ -0,0 +1,108 @@
+import { pageSlug } from "./pageAddress.js";
+import { sourcePages } from "./sourceFiles.js";
+/**
+ * A page's place, from its title: the last segment its name, the ones before its group. An empty segment is a problem.
+ *
+ * @param title - the page's title.
+ */
+const pagePlace = (title) => {
+    const segments = title.split("/").map((segment) => segment.trim());
+    if (segments.some((segment) => segment === ""))
+        return `"${title}" has an empty segment`;
+    const name = segments.at(-1) ?? title;
+    const group = segments.slice(0, -1).join(" / ");
+    return { name, group: group === "" ? undefined : group };
+};
+/** A page's position: its `order`, or after every page with one. */
+const orderOf = (entry) => entry.order ?? Number.POSITIVE_INFINITY;
+/**
+ * The docs pages of one source, from their index; a title that cannot be placed, or is taken, is a problem.
+ *
+ * @param source - the source.
+ * @param problems - receives the problems.
+ */
+export const treePages = (source, problems) => {
+    const seen = new Map();
+    const entries = Object.entries(sourcePages(source).index).sort(([, left], [, right]) => orderOf(left) - orderOf(right) || left.title.localeCompare(right.title));
+    return entries.flatMap(([file, entry]) => {
+        for (const note of entry.notes ?? [])
+            problems.push(`${source.name}: ${file}: ${note}`);
+        const place = pagePlace(entry.title);
+        if (typeof place === "string") {
+            problems.push(`${source.name}: ${file}: ${place}`);
+            return [];
+        }
+        const slug = pageSlug(entry.title);
+        const other = seen.get(slug);
+        if (other !== undefined) {
+            problems.push(`${source.name}: ${file} and ${other} have the same title "${entry.title}"`);
+            return [];
+        }
+        seen.set(slug, file);
+        return [
+            {
+                id: `${source.id}:${slug}`,
+                slug,
+                title: entry.title,
+                ...place,
+                file,
+                description: entry.description,
+                stories: entry.stories,
+                components: entry.components,
+                links: entry.links
+            }
+        ];
+    });
+};
+/**
+ * What the docs pages name that the tree does not have: a story or a component renamed under a page must fail the
+ * index, or the page would break unseen.
+ *
+ * @param sources - the tree's sources.
+ * @param stories - the ids of its stories.
+ * @param components - the ids of its components.
+ */
+export const pageProblems = (sources, stories, components) => sources.flatMap((source) => source.pages.flatMap((page) => [
+    ...page.stories
+        .filter((id) => !stories.has(id))
+        .map((id) => `${source.name}: ${page.file} shows the story "${id}": no such story`),
+    ...page.components
+        .filter((id) => !components.has(id))
+        .map((id) => `${source.name}: ${page.file} shows the component "${id}": no such component`),
+    ...page.links
+        .filter((slug) => !source.pages.some((other) => other.slug === slug))
+        .map((slug) => `${source.name}: ${page.file} links to "${slug}": no such page`)
+]));
+/**
+ * Finds a docs page by its id.
+ *
+ * @param tree - the tree.
+ * @param id - the page's id.
+ */
+export const findPage = (tree, id) => {
+    for (const source of tree.sources) {
+        const page = source.pages.find((candidate) => candidate.id === id);
+        if (page !== undefined)
+            return { source, page };
+    }
+    return undefined;
+};
+/**
+ * Pages under their headings, in reading order: a named group sits where its first page is and takes all its pages, and
+ * pages without a group stay between the groups where their order puts them.
+ *
+ * @param pages - the pages, in their order.
+ */
+export const pageGroups = (pages) => {
+    const groups = [];
+    for (const page of pages) {
+        const named = groups.find((group) => page.group !== undefined && group.name === page.group);
+        const last = groups.at(-1);
+        const group = page.group === undefined && last?.name === undefined ? last : named;
+        if (group === undefined)
+            groups.push({ name: page.group, pages: [page] });
+        else
+            group.pages.push(page);
+    }
+    return groups;
+};

package/dist/src/playTrace.d.ts

@@ -38,4 +38,3 @@ export type PlayTrace = {
  * @param value - the message's trace.
  */
 export declare const isPlayTrace: (value: unknown) => value is PlayTrace;
-//# sourceMappingURL=playTrace.d.ts.map

package/dist/src/playTrace.js

@@ -32,4 +32,3 @@ export const isPlayTrace = (value) => {
     const steps = record["steps"];
     return isStatus(record["status"]) && Array.isArray(steps) && steps.every(isStep) && hasOptionalEnd(record);
 };
-//# sourceMappingURL=playTrace.js.map

package/dist/src/plugin.d.ts

@@ -0,0 +1,230 @@
+/**
+ * The plugin API: what a package gives a catalogue. Version 1 of a public contract; `PLUGINS.md` beside the package's
+ * README states it, with what it leaves out.
+ *
+ * @remarks
+ * A plugin is plain data, read on Node from the configuration's `plugins`: everything that runs in a page is a module
+ * it names, so a catalogue that lists none has nothing to load, and a tab's code loads the first time the tab opens.
+ * There are four places to add to, and no other: a panel tab, a switch of the toolbar and the View menu, a block of a
+ * docs page, and what runs around a story in its frame.
+ *
+ * A view (a tab, a block) is handed an element and draws in it with whatever it likes. The contract never names React:
+ * the shell's own components, hooks and state stay free to change, and `forgebook/plugin-react` is the few lines a
+ * React view needs. Everything a view may read arrives in its context; the messages between the shell and the frames
+ * stay private, so a plugin reaches its frame module through `report` alone.
+ *
+ * Runs on Node and in both pages: this module imports nothing of either.
+ *
+ * @module
+ */
+import type { FigmaLink } from "@forgebook/story-format/source";
+import type { LoadedBeforeEach, LoadedDecorator } from "./frame/storyModule.ts";
+import type { ViewSwitch } from "./switches.ts";
+/**
+ * A version of this contract. A plugin writes the number itself, not a constant of this package: a constant would read
+ * as whichever Forgebook is installed, and no plugin could ever be refused.
+ */
+export type PluginApiVersion = 1;
+/** A value that crosses between a frame and the shell, and stays what it was: JSON. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * When a tab is offered. `parameter` is known once the story's frame ran, so such a tab comes in then, and not at all
+ * for a story that fails before it. `design` is known at once: the index reads it, and offers the tab only for a link
+ * that passed its check.
+ */
+export type PluginCondition = {
+    /** The story's parameter, a top-level name (`msw`). */
+    readonly parameter: string;
+} | {
+    /** The design tool the story must have a link to. */
+    readonly design: "figma";
+};
+/** A panel tab. */
+export type PluginTab = {
+    /**
+     * Its id, in the address (`?tab=figma`) and in the catalogue's `tabs`: the plugin's id, or that and a hyphen and a
+     * word, so no later tab of Forgebook's or another plugin's can take it.
+     */
+    readonly id: string;
+    /** Its name, in English; a catalogue replaces it as any tab's (`strings: { "tabs.figma": "…" }`). */
+    readonly label: string;
+    /** The module that draws it, as a specifier the catalogue's folder resolves: it exports a `PluginView` as `view`. */
+    readonly view: string;
+    /** When it is offered; for every story by default. */
+    readonly when?: PluginCondition;
+};
+/** A block of a docs page, written as a fenced block named after it, at the page's top level. */
+export type PluginDocBlock = {
+    /** The fence's name, which a page writes after its opening backticks: named as a tab's id is. */
+    readonly fence: string;
+    /** The module that draws it, as a specifier the catalogue's folder resolves: it exports a `PluginView` as `view`. */
+    readonly view: string;
+};
+/** A switch a plugin adds: a catalogue's, without the roles the catalogue itself reads, which stay the catalogue's. */
+export type PluginSwitch = Omit<ViewSwitch, "role">;
+/** What a package gives a catalogue. */
+export type ForgebookPlugin = {
+    /** The contract it is written for: the number, written out. */
+    readonly apiVersion: PluginApiVersion;
+    /** Its id (`figma`), lower-case words and hyphens: it starts the ids of what it adds, and names its texts. */
+    readonly id: string;
+    /** The tabs it adds to the panel, after Code and before Accessibility, in the order of `plugins`. */
+    readonly tabs?: readonly PluginTab[];
+    /** The switches it adds, after the catalogue's own, each id named as a tab's is. */
+    readonly switches?: readonly PluginSwitch[];
+    /** The blocks it adds to docs pages. */
+    readonly docBlocks?: readonly PluginDocBlock[];
+    /**
+     * The module that runs in every frame, as a specifier the catalogue's folder resolves: it exports what
+     * `definePluginFrame` makes as `frame`. One module for every framework, or one per framework by the adapter's name
+     * (`{ react: "…" }`), since what a decorator returns is the framework's; a catalogue of another framework refuses the
+     * plugin. It loads with every story, so a heavy tool is imported inside its `prepare`.
+     */
+    readonly frame?: string | Readonly<Record<string, string>>;
+    /** The packages its modules import in the browser: pre-bundled, and a catalogue without one is told at once. */
+    readonly browserDependencies?: readonly string[];
+};
+/** What every view is told. */
+export type PluginViewContext = {
+    /** The shell's appearance now: a view that follows it draws itself again on `update`. */
+    readonly appearance: "light" | "dark";
+    /**
+     * A text the view shows: the catalogue's replacement (`strings: { "plugin.figma.compare": "…" }`), or the English
+     * given, with `{name}` replaced by its value. The same function for the view's whole life.
+     *
+     * @param key - the text's name within the plugin (`compare`).
+     * @param fallback - the text in English.
+     * @param values - what its `{name}`s stand for.
+     */
+    readonly text: (key: string, fallback: string, values?: Readonly<Record<string, string>>) => string;
+};
+/** The story a tab is shown for. */
+export type PluginStory = {
+    /** The story's id (`kit:inputs-select--overview`). */
+    readonly id: string;
+    /** The story's name. */
+    readonly name: string;
+    /** The component's title, its place in the sidebar. */
+    readonly title: string;
+    /** The component's name. */
+    readonly componentName: string;
+    /** Its design, by tool: only a link that passed the check. */
+    readonly design: {
+        /** Its node or file in Figma. */
+        readonly figma?: FigmaLink;
+    };
+};
+/** A story's second frame, drawn in an element of a view. */
+export type PluginStoryFrame = {
+    /** Takes it away. */
+    readonly remove: () => void;
+};
+/** What a tab is told. */
+export type PluginTabContext = PluginViewContext & {
+    /** The story shown. A view lives for one story: another story mounts it anew. */
+    readonly story: PluginStory;
+    /**
+     * The last value the plugin's frame module reported for this story; none before it reported, and none in the
+     * compare view, where no frame is the story's.
+     */
+    readonly report: JsonValue | undefined;
+    /**
+     * Draws the story again in an element of the view, at the stage's width, with the panel's values and the view of
+     * this moment; a second frame, which tells the stage nothing. The same function for the view's whole life.
+     *
+     * @param target - the element.
+     * @param options - the frame's accessible name.
+     */
+    readonly showStory: (target: HTMLElement, options: {
+        /** The frame's accessible name. */
+        readonly title: string;
+    }) => PluginStoryFrame;
+};
+/** What a docs block is told. */
+export type PluginDocBlockContext = PluginViewContext & {
+    /** What the fence's line says after the block's name. */
+    readonly argument: string;
+    /** The text inside the fence. */
+    readonly body: string;
+    /**
+     * Draws a story in an element of the block, in the page's view. The same function for the view's whole life.
+     *
+     * @param target - the element.
+     * @param options - the frame's accessible name, and the story.
+     * @throws when the catalogue has no such story.
+     */
+    readonly showStory: (target: HTMLElement, options: {
+        /** The frame's accessible name. */
+        readonly title: string;
+        /** The story's id. */
+        readonly storyId: string;
+    }) => PluginStoryFrame;
+};
+/** A view that is drawing, as the shell keeps it. */
+export type PluginViewHandle<TContext extends PluginViewContext> = {
+    /** Draws it again with a new context. */
+    readonly update: (context: TContext) => void;
+    /** Takes it away from its element. */
+    readonly unmount: () => void;
+};
+/**
+ * A tab or a docs block: the `view` export of the module its declaration names.
+ *
+ * @param target - the element it draws in, which it owns; it has no box of its own (`display: contents`).
+ * @param context - what it is told.
+ * @returns what the shell keeps of it.
+ */
+export type PluginView<TContext extends PluginViewContext> = (target: HTMLElement, context: TContext) => PluginViewHandle<TContext>;
+/** What goes with a report. */
+export type PluginReportOptions = {
+    /** A short note beside a tab's name (a count); none shows nothing. */
+    readonly hint?: string;
+    /** The tab the note is for, by id; the plugin's first by default. */
+    readonly tab?: string;
+};
+/** What a plugin's frame module is given. */
+export type PluginFrameHost = {
+    /**
+     * Tells the plugin's tabs about this story. The value replaces the last one, so it holds all they need (a log is sent
+     * whole, kept short).
+     *
+     * @param value - what a tab receives as `report`.
+     * @param options - a note beside a tab's name.
+     */
+    readonly report: (value: JsonValue, options?: PluginReportOptions) => void;
+};
+/** What `prepare` is told: the context of a CSF `beforeEach`. */
+export type PluginPrepareContext = Parameters<LoadedBeforeEach>[0];
+/** What a plugin runs around a story, in its frame. */
+export type PluginFrame = {
+    /** Wrap every story, outside the catalogue's own. What one returns is the framework's. */
+    readonly decorators?: readonly LoadedDecorator[];
+    /**
+     * Runs before every mount, ahead of the story's loaders, with the context of a CSF `beforeEach`; what it returns runs
+     * when the story is mounted again or left, and the next mount waits for it, two seconds at most. What it throws
+     * is shown as the story's error.
+     */
+    readonly prepare?: LoadedBeforeEach;
+};
+/**
+ * The `frame` export of a plugin's frame module, called once per frame. What it throws is shown in place of the story,
+ * in every frame.
+ *
+ * @param host - how it reaches its tabs.
+ * @returns what it runs around the story.
+ */
+export type CreatePluginFrame = (host: PluginFrameHost) => PluginFrame;
+/**
+ * A plugin, typed: what a plugin package's main export returns.
+ *
+ * @param plugin - the plugin.
+ */
+export declare const definePlugin: (plugin: ForgebookPlugin) => ForgebookPlugin;
+/**
+ * A plugin's frame module, typed.
+ *
+ * @param create - makes what runs around the story, once per frame.
+ */
+export declare const definePluginFrame: (create: CreatePluginFrame) => CreatePluginFrame;

package/dist/src/plugin.js

@@ -0,0 +1,12 @@
+/**
+ * A plugin, typed: what a plugin package's main export returns.
+ *
+ * @param plugin - the plugin.
+ */
+export const definePlugin = (plugin) => plugin;
+/**
+ * A plugin's frame module, typed.
+ *
+ * @param create - makes what runs around the story, once per frame.
+ */
+export const definePluginFrame = (create) => create;

package/dist/src/pluginReact.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A plugin's view written in React: the few lines between the contract, which hands a view an element, and a component.
+ *
+ * @remarks
+ * The view gets a React root of its own, so nothing of the shell's reaches it but its context. An error it does not
+ * catch would otherwise leave its panel empty, so it is said in place. The root goes away a moment after the shell asks:
+ * the shell asks while React commits, when a root cannot be unmounted.
+ *
+ * @module
+ */
+import type { ComponentType } from "react";
+import type { PluginView, PluginViewContext } from "./plugin.ts";
+/** The props of a view written in React. */
+export type PluginViewProps<TContext extends PluginViewContext> = {
+    /** What the view is told, new on every change. */
+    readonly context: TContext;
+};
+/**
+ * A component as a view: what a tab's or a block's module exports as `view`.
+ *
+ * @param View - the component.
+ */
+export declare const reactView: <TContext extends PluginViewContext>(View: ComponentType<PluginViewProps<TContext>>) => PluginView<TContext>;

package/dist/src/pluginReact.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createRoot } from "react-dom/client";
+/**
+ * A component as a view: what a tab's or a block's module exports as `view`.
+ *
+ * @param View - the component.
+ */
+export const reactView = (View) => (target, context) => {
+    const root = createRoot(target, {
+        onUncaughtError: (error) => {
+            const problem = target.ownerDocument.createElement("p");
+            problem.className = "forgebook-problems";
+            problem.setAttribute("role", "alert");
+            problem.textContent = error instanceof Error ? error.message : String(error);
+            target.replaceChildren(problem);
+        }
+    });
+    const draw = (next) => _jsx(View, { context: next });
+    root.render(draw(context));
+    return {
+        update: (next) => root.render(draw(next)),
+        unmount: () => queueMicrotask(() => root.unmount())
+    };
+};

package/dist/src/previewRelay.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The page between a client's app and a story's frame: it shows the frame and says when the story is up and how tall.
+ *
+ * @remarks
+ * The app runs on an origin the host chooses, so a frame cannot talk to it: a frame posts to the catalogue's origin
+ * only, which keeps its messages (a story's args among them) from any page that embeds it. This page is on the
+ * catalogue's origin, reads the messages of the frame, on the frames' origin, as the shell does, and passes the app
+ * three facts and nothing else: that it runs, that something was drawn, and the height. A page that embeds it learns no
+ * more than that, so it can post to any origin, as it has to: the app's may be opaque. A story that fails counts as
+ * drawn, as the frame shows the error itself.
+ *
+ * A frame opened alone on a cold dev server can stay blank: when the server prepares a dependency again, a static import
+ * of the frame's own entry fails before any of its code runs, so its reload for a stale module never happens and no
+ * shell is there to load it again. So the relay does, once, when the frame loaded and has said nothing at all, by
+ * loading its address again: the frame's own `location` is another origin's, which this page may not reload.
+ *
+ * Runs in the page, written into it by its source (`previewPages.ts`), so it takes no import.
+ *
+ * @module
+ */
+/** What the relay tells the app. */
+export type PreviewRelayMessage = {
+    /** The relay runs: the host let the frame in, so it is worth waiting for the story. */
+    readonly type: "forgebook:preview-started";
+} | {
+    /** The story was drawn, or its error was. */
+    readonly type: "forgebook:preview-ready";
+} | {
+    /** The story's height changed. */
+    readonly type: "forgebook:preview-size";
+    /** The height, in CSS px. */
+    readonly height: number;
+};
+/**
+ * Shows a story's frame and tells the embedding app about it.
+ *
+ * @param frameAddress - the story's frame, on the frames' origin.
+ * @param title - the frame's name for a screen reader: the story's id.
+ */
+export declare const previewRelay: (frameAddress: string, title: string) => void;