forgebook 0.1.7 → 0.2.0

package/dist/bin/forgebook/importers/storybookReactNative.js

@@ -0,0 +1,179 @@
+/**
+ * What `forgebook init --from storybook` reads of a React Native project's Storybook: the options of Storybook's React
+ * Native Web framework or of its older addon, turned into `reactNativeWeb()`'s, and what on-device Storybook draws
+ * differently in a browser.
+ *
+ * @remarks
+ * Pure: the options `main` gives in, the adapter's options and the notes out; `storybookFrameworks.ts` chooses the
+ * framework and hands them over. The packages Storybook compiled (`modulesToTranspile`) become `nativePackages`; its
+ * `pluginReactOptions` (the JSX import source, Babel's plugins and presets, the files) become the adapter's options of
+ * the same meaning; what cannot be written as a plain value (a function, a regular expression) is named in a note.
+ *
+ * @module
+ */
+/** Storybook's React Native framework for the browser, on Vite. */
+export const REACT_NATIVE_WEB_VITE = "@storybook/react-native-web-vite";
+/** Storybook's older React Native Web addon, on webpack, beside a React framework. */
+export const REACT_NATIVE_WEB_ADDON = "@storybook/addon-react-native-web";
+/** On-device Storybook's package, which `main` names as its framework or not at all. */
+export const ON_DEVICE_STORYBOOK = "@storybook/react-native";
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * A value read as a list: a list as it is, nothing as none, anything else as a list of itself.
+ *
+ * @param value - the value.
+ */
+const listOf = (value) => {
+    if (Array.isArray(value))
+        return value;
+    return value === undefined ? [] : [value];
+};
+/**
+ * The texts of a list, with a note when it holds something else (a function, a regular expression), which cannot be
+ * written as a plain value.
+ *
+ * @param value - the list, as `main` writes it.
+ * @param field - its name, for the note.
+ */
+const texts = (value, field) => {
+    const list = listOf(value);
+    const values = list.filter((item) => typeof item === "string");
+    const notes = values.length === list.length ? [] : [`${field}: only names are written; copy the others by hand`];
+    return { values, notes };
+};
+/**
+ * Whether a value is written as it is in JSON: texts, finite numbers, booleans, `null`, and lists and objects of them.
+ *
+ * @param value - the value.
+ */
+const isPlain = (value) => {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isPlain);
+    return (isRecord(value) &&
+        Object.getPrototypeOf(value) === Object.prototype &&
+        Object.values(value).every(isPlain));
+};
+/**
+ * Babel's plugins or presets as the configuration writes them: a name, or a name and plain options.
+ *
+ * @param value - the list, as `main` writes it.
+ * @param field - its name, for the note.
+ */
+const babelItems = (value, field) => {
+    const list = Array.isArray(value) ? value : [];
+    const values = list.filter((item) => typeof item === "string" ||
+        (Array.isArray(item) &&
+            item.length === 2 &&
+            typeof item[0] === "string" &&
+            isRecord(item[1]) &&
+            isPlain(item[1])));
+    const notes = values.length === list.length
+        ? []
+        : [
+            `${field}: an item that is not a name, or a name with plain options (a function, a regular expression, a third element), is not written; copy it by hand`
+        ];
+    return { values, notes };
+};
+/**
+ * The notes on Storybook options that are not read at all: the deprecated `pluginBabelOptions`, and a `babel` that is
+ * not a plain object.
+ *
+ * @param options - the framework's options.
+ * @param react - its `pluginReactOptions`.
+ */
+const shapeNotes = (options, react) => {
+    const notes = [];
+    if (options["pluginBabelOptions"] !== undefined)
+        notes.push("pluginBabelOptions is not read (Storybook no longer reads it either): name Babel's plugins in babel");
+    if (react["babel"] !== undefined && !isRecord(react["babel"]))
+        notes.push("pluginReactOptions.babel is not a plain object: copy its plugins and presets into babel by hand");
+    return notes;
+};
+/**
+ * `reactNativeWeb()`'s options from a Storybook React Native framework's: `modulesToTranspile` as `nativePackages`,
+ * `pluginReactOptions`' JSX import source, Babel plugins and presets, and files.
+ *
+ * @param options - the framework's or the addon's options.
+ */
+const reactNativeWebOptions = (options) => {
+    const react = isRecord(options["pluginReactOptions"]) ? options["pluginReactOptions"] : {};
+    const babel = isRecord(react["babel"]) ? react["babel"] : {};
+    const nativePackages = texts(options["modulesToTranspile"], "modulesToTranspile");
+    // the older addon names its Babel plugins beside its options
+    const plugins = babelItems(babel["plugins"] ?? options["babelPlugins"], "babel.plugins");
+    const presets = babelItems(babel["presets"], "babel.presets");
+    const include = texts(react["include"], "pluginReactOptions.include");
+    const exclude = texts(react["exclude"], "pluginReactOptions.exclude");
+    const jsxImportSource = react["jsxImportSource"];
+    const notes = [
+        ...shapeNotes(options, react),
+        ...nativePackages.notes,
+        ...plugins.notes,
+        ...presets.notes,
+        ...include.notes,
+        ...exclude.notes,
+        ...(react["jsxRuntime"] === "classic"
+            ? ["jsxRuntime classic is not read: JSX is compiled for the automatic runtime"]
+            : [])
+    ];
+    const written = {
+        ...(nativePackages.values.length === 0 ? {} : { nativePackages: nativePackages.values }),
+        ...(typeof jsxImportSource === "string" && jsxImportSource !== "react" ? { jsxImportSource } : {}),
+        ...(plugins.values.length === 0 && presets.values.length === 0
+            ? {}
+            : {
+                babel: {
+                    ...(plugins.values.length === 0 ? {} : { plugins: plugins.values }),
+                    ...(presets.values.length === 0 ? {} : { presets: presets.values })
+                }
+            }),
+        ...(include.values.length === 0 ? {} : { include: include.values }),
+        ...(exclude.values.length === 0 ? {} : { exclude: exclude.values })
+    };
+    return { options: written, notes };
+};
+/**
+ * What a React Native project's Storybook gives `reactNativeWeb()`.
+ *
+ * @param storybook - the Storybook package read: the framework on Vite, the older addon, or on-device Storybook.
+ * @param options - that framework's or addon's options.
+ * @param main - `main`'s configuration, for on-device Storybook's device addons.
+ */
+export const importReactNative = (storybook, options, main) => {
+    if (storybook === ON_DEVICE_STORYBOOK)
+        return {
+            options: undefined,
+            notes: [
+                "On-device Storybook: the stories are drawn in the browser through react-native-web, so a component that needs a native module does not draw",
+                ...(main["deviceAddons"] === undefined
+                    ? []
+                    : ["The device addons are left out: Forgebook has its own panel"])
+            ]
+        };
+    const read = reactNativeWebOptions(options);
+    const written = Object.keys(read.options).length === 0 ? undefined : read.options;
+    return storybook === REACT_NATIVE_WEB_ADDON
+        ? {
+            options: written,
+            notes: [
+                `${REACT_NATIVE_WEB_ADDON} ran on webpack: Forgebook draws React Native through react-native-web on Vite`,
+                ...read.notes
+            ]
+        }
+        : { options: written, notes: read.notes };
+};
+/**
+ * The packages `reactNativeWeb()` needs beside its own that a project may not have yet.
+ *
+ * @param options - the adapter's options.
+ */
+export const reactNativePeers = (options) => [
+    "react-native-web",
+    // Babel runs through Rolldown's plugin, which a catalogue without Babel installs not
+    ...(options !== undefined && "babel" in options ? ["@rolldown/plugin-babel", "@babel/core"] : [])
+];

package/dist/bin/forgebook/initCommands.d.mts

@@ -6,4 +6,3 @@ import { type ForgebookOptions } from "./catalogueCommands.ts";
  * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
  */
 export declare const initCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;
-//# sourceMappingURL=initCommands.d.mts.map

package/dist/bin/forgebook/initCommands.mjs

@@ -3,7 +3,7 @@
  * files, so a project on Storybook tries Forgebook in one command, its stories read as they are.
  *
  * @remarks
- * Defined here, on the scope `forgebook.mts` hands it, so the entry stays a list of commands; the reading is the
+ * Defined here, on the scope `forgebookCommands.mts` hands it, so the commands module stays a list of commands; the reading is the
  * importer's (`importers/storybook.ts`), the writing `initConfig.ts`'s. A configuration already there is never
  * replaced unless asked (`--force`): it may hold a person's work.
  *
@@ -15,21 +15,31 @@ import { join, resolve } from "node:path";
 import { ScriptError } from "@ensiria/cli-kit/script";
 import { CONFIG_FILES } from "../../src/vite/configFile.js";
 import { COMMAND } from "./catalogueCommands.js";
-import { importStorybook } from "./importers/storybook.js";
+import { frameworkPeers } from "./importers/storybookFrameworks.js";
 import { CONFIG_FILE, initConfigText } from "./initConfig.js";
-/** The modules the written configuration imports, by the package that has each. */
-const CONFIG_IMPORTS = {
+/**
+ * The modules the written configuration needs, by the package that has each: what it imports, and the framework's
+ * peers.
+ *
+ * @param imported - what the importer read: the framework and its options.
+ */
+const configImports = (imported) => ({
     forgebook: "forgebook",
-    "@forgebook/react": "@forgebook/react/vite"
-};
+    [`@forgebook/${imported.framework}`]: `@forgebook/${imported.framework}/vite`,
+    ...Object.fromEntries(frameworkPeers(imported.framework, imported.frameworkOptions).map((peer) => [
+        peer,
+        `${peer}/package.json`
+    ]))
+});
 /**
- * The packages the written configuration imports that the project cannot load yet.
+ * The packages the written configuration needs that the project cannot load yet.
  *
  * @param dir - the project's folder.
+ * @param imported - what the importer read: the framework and its options.
  */
-const missingPackages = (dir) => {
+const missingPackages = (dir, imported) => {
     const require = createRequire(join(dir, "package.json"));
-    return Object.entries(CONFIG_IMPORTS).flatMap(([name, specifier]) => {
+    return Object.entries(configImports(imported)).flatMap(([name, specifier]) => {
         try {
             require.resolve(specifier);
             return [];
@@ -53,7 +63,7 @@ export const initCommands = (forgebook) => ({
                 required: true,
                 choices: ["storybook"],
                 valueName: "tool",
-                description: "The tool whose files are read (its folder in the current one: .storybook)."
+                description: "The tool whose files are read (its folder in the current one: .storybook, or on-device Storybook's .rnstorybook)."
             },
             force: { type: "boolean", description: `Replace a ${CONFIG_FILE} that is already there.` }
         },
@@ -71,6 +81,8 @@ export const initCommands = (forgebook) => ({
                 throw new ScriptError(`${existing} is already there`, {
                     hint: "Give --force to replace it with the one read from Storybook"
                 });
+            // the importer reads Storybook's files with the compiler: only this command loads it
+            const { importStorybook } = await import("./importers/storybook.js");
             const imported = await importStorybook(process.cwd());
             if (typeof imported === "string")
                 throw new ScriptError(imported);
@@ -78,7 +90,7 @@ export const initCommands = (forgebook) => ({
             log.success(`${CONFIG_FILE} written: ${imported.stories.length} story globs`);
             for (const note of imported.notes)
                 log.warn(note);
-            const missing = missingPackages(process.cwd());
+            const missing = missingPackages(process.cwd(), imported);
             if (missing.length > 0)
                 log.info(`Install what it imports first: npm install --save-dev ${missing.join(" ")}`);
             log.info(`Next: ${COMMAND} dev to open the catalogue, ${COMMAND} stories to list what did not read, ` +
@@ -86,4 +98,3 @@ export const initCommands = (forgebook) => ({
         }
     })
 });
-//# sourceMappingURL=initCommands.mjs.map

package/dist/bin/forgebook/initConfig.d.ts

@@ -19,4 +19,3 @@ export declare const CONFIG_FILE = "forgebook.config.ts";
  * @param tool - the tool's name, for the file's comment (`Storybook`).
  */
 export declare const initConfigText: (imported: ImportedConfig, tool: string) => string;
-//# sourceMappingURL=initConfig.d.ts.map

package/dist/bin/forgebook/initConfig.js

@@ -1,3 +1,4 @@
+import { ADAPTER_FUNCTIONS } from "./importers/storybookFrameworks.js";
 /** The file `forgebook init` writes. */
 export const CONFIG_FILE = "forgebook.config.ts";
 /**
@@ -11,6 +12,19 @@ const sourceOf = (value, indent) => JSON.stringify(value, null, 2)
     .replace(/^(\s*)"([A-Za-z_$][\w$]*)":/gm, "$1$2:")
     .split("\n")
     .join(`\n${indent}`);
+/**
+ * A framework's options as its adapter's argument: on one line when each is a single value
+ * (`{ dir: "web", nextConfig: "next.config.mjs" }`), one field a line when one holds a list or an object.
+ *
+ * @param options - the options read; none for the adapter's defaults.
+ */
+const adapterArgument = (options) => {
+    if (options === undefined)
+        return "";
+    const isFlat = Object.values(options).every((value) => typeof value !== "object" || value === null);
+    const source = sourceOf(options, "  ");
+    return isFlat ? source.replace(/\n\s*/g, " ") : source;
+};
 /**
  * The configuration file's text.
  *
@@ -18,8 +32,9 @@ const sourceOf = (value, indent) => JSON.stringify(value, null, 2)
  * @param tool - the tool's name, for the file's comment (`Storybook`).
  */
 export const initConfigText = (imported, tool) => {
+    const adapter = ADAPTER_FUNCTIONS[imported.framework];
     const fields = [
-        "  framework: react(),",
+        `  framework: ${adapter}(${adapterArgument(imported.frameworkOptions)}),`,
         `  title: ${JSON.stringify(imported.title)},`,
         `  stories: ${sourceOf(imported.stories, "  ")},`,
         ...(imported.preview === undefined ? [] : [`  preview: ${JSON.stringify(imported.preview)},`]),
@@ -39,7 +54,7 @@ export const initConfigText = (imported, tool) => {
         " *",
         " * @module",
         " */",
-        'import { react } from "@forgebook/react/vite";',
+        `import { ${adapter} } from "@forgebook/${imported.framework}/vite";`,
         'import { defineConfig } from "forgebook";',
         "",
         "export default defineConfig({",
@@ -48,4 +63,3 @@ export const initConfigText = (imported, tool) => {
         ""
     ].join("\n");
 };
-//# sourceMappingURL=initConfig.js.map

package/dist/bin/forgebook/mcpCommand.d.mts

@@ -0,0 +1,8 @@
+import type { CommandNode, CommandScope } from "@ensiria/cli-kit/commands.types";
+import { type ForgebookOptions } from "./catalogueCommands.ts";
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export declare const mcpCommands: (forgebook: CommandScope<ForgebookOptions>) => Readonly<Record<string, CommandNode>>;

package/dist/bin/forgebook/mcpCommand.mjs

@@ -0,0 +1,99 @@
+/**
+ * `forgebook mcp`: the catalogue's tools for agents over the Model Context Protocol, from a dev server or from a built
+ * catalogue's index; and `forgebook plugins`, what its `list_plugins` answers, read from the configuration alone.
+ *
+ * @module
+ */
+import { resolve } from "node:path";
+import { formatJson, readPackageVersion } from "@ensiria/cli-kit/files";
+import { pluginsDocument } from "../../src/vite/pluginConfig.js";
+import { catalogueClient, previewServer } from "./agentClient.js";
+import { pluginsText } from "./agentText.js";
+import { builtCatalogueServer, serveMcp } from "./builtCatalogue.js";
+import { COMMAND, configOf } from "./catalogueCommands.js";
+import { previewResource } from "./mcpPreview.js";
+import { catalogueTools } from "./mcpTools.js";
+import { newStoriesFile } from "./newStoriesFile.js";
+import { SEMANTIC_OPTIONS, semanticModelOf } from "./semanticOptions.js";
+import { runPageCheck, runStoryCheck, runStoryDiff, runStoryShot } from "./storyCheckRun.js";
+import { baselinesOf, visualDiffTool } from "./visualCommands.mjs";
+/**
+ * The commands.
+ *
+ * @param forgebook - the scope of the `forgebook` command, whose options every command takes.
+ */
+export const mcpCommands = (forgebook) => ({
+    mcp: forgebook.command({
+        summary: "Serve the catalogue's stories to an agent over the Model Context Protocol, on stdin and stdout.",
+        header: false,
+        options: {
+            url: {
+                type: "string",
+                env: "FORGEBOOK_URL",
+                valueName: "address",
+                description: "Where forgebook dev runs, when not at Vite's default address (http://localhost:5173)."
+            },
+            from: {
+                type: "string",
+                valueName: "address or folder",
+                description: "A catalogue built with --agent-index: read-only, with no server and no repository."
+            },
+            ...SEMANTIC_OPTIONS
+        },
+        examples: [
+            {
+                command: `${COMMAND} mcp`,
+                description: "What an agent's MCP configuration runs (npx forgebook mcp)."
+            },
+            {
+                command: `${COMMAND} mcp --from https://ui.example.com`,
+                description: "A published library's catalogue, for a team that consumes it."
+            }
+        ],
+        run: async ({ options, io, log }) => {
+            if (options.from !== undefined) {
+                const version = readPackageVersion(import.meta.dirname);
+                await serveMcp(await builtCatalogueServer(options.from, version), io);
+                return;
+            }
+            const config = await configOf(options.config);
+            // kept for the server's life: an agent's questions in a row each answer at once
+            const client = await catalogueClient(config, options.url);
+            log.debug(client.runningAt === undefined ? "Answering from a server of its own" : `Asking ${client.runningAt}`);
+            const version = readPackageVersion(import.meta.dirname);
+            const preview = previewServer(config, client.runningAt);
+            const server = {
+                info: { name: "forgebook", version },
+                instructions: `The stories of the Forgebook catalogue "${config.title}". list_stories finds a story's id, get_story gives its args and its component's props, story_address gives the links a person opens to see it. list_pages and get_page read its guides, search_catalogue finds a prop or a sentence anywhere in it.`,
+                tools: [
+                    visualDiffTool((input, outDir) => runStoryDiff(config, options.url, input, {
+                        baselines: baselinesOf(config.dir),
+                        outDir
+                    })),
+                    ...catalogueTools({
+                        ask: client.ask,
+                        writeNew: (file, exportName) => newStoriesFile(resolve(config.dir, file), exportName, config.framework.name),
+                        check: (input) => runStoryCheck(config, options.url, input, semanticModelOf(options)),
+                        shot: (input, outDir) => runStoryShot(config, options.url, input, outDir),
+                        checkPage: (address) => runPageCheck(config, [address]),
+                        servePreview: preview.serve,
+                        plugins: pluginsDocument(config.plugins)
+                    })
+                ],
+                apps: [previewResource({ origin: preview.origin, strings: config.lists.strings ?? {}, version })]
+            };
+            await serveMcp(server, io);
+            await preview.close();
+            await client.close();
+        }
+    }),
+    plugins: forgebook.command({
+        summary: "List the plugins the catalogue lists, and what each adds.",
+        json: true,
+        examples: [{ command: `${COMMAND} plugins --json`, description: "As an agent reads them." }],
+        run: async ({ options, io, isJson }) => {
+            const document = pluginsDocument((await configOf(options.config)).plugins);
+            io.stdout.write(isJson ? formatJson(document) : `${pluginsText(document)}\n`);
+        }
+    })
+});

package/dist/bin/forgebook/mcpPreview.d.ts

@@ -0,0 +1,32 @@
+import { type AgentAnswer } from "../../src/vite/agentRoutes.ts";
+import type { McpAppResource, McpTool } from "../../src/vite/mcpProtocol.ts";
+/** The address of the page a preview is shown in. */
+export declare const PREVIEW_URI = "ui://forgebook/story-preview";
+/** What the tool reaches the catalogue through. */
+export type PreviewReach = {
+    /** Asks the catalogue. */
+    readonly ask: (route: string, params: URLSearchParams) => Promise<AgentAnswer>;
+    /** Serves the catalogue where a browser can open it, and answers where. */
+    readonly serve: () => Promise<string>;
+};
+/**
+ * The tool that shows a story to the person, inside the client.
+ *
+ * @param reach - what it reaches the catalogue through.
+ */
+export declare const previewTool: ({ ask, serve }: PreviewReach) => McpTool;
+/** What the resource is made from. */
+export type PreviewResourceOptions = {
+    /** Where the story will be served, with nothing started. */
+    readonly origin: () => Promise<string>;
+    /** The catalogue's `strings`, which replace the page's words by name. */
+    readonly strings: Readonly<Record<string, string>>;
+    /** Forgebook's version. */
+    readonly version: string;
+};
+/**
+ * The resource a preview is shown in.
+ *
+ * @param options - what it is made from.
+ */
+export declare const previewResource: ({ origin, strings, version }: PreviewResourceOptions) => McpAppResource;

package/dist/bin/forgebook/mcpPreview.js

@@ -0,0 +1,107 @@
+/**
+ * The inline preview `forgebook mcp` offers a client that renders apps (MCP Apps, specification 2026-01-26): the tool
+ * `story_preview` and the `ui://` resource its answer is shown in.
+ *
+ * @remarks
+ * Nothing here runs for a client that renders no apps: the tool is not listed to it, and it keeps `story_shot`. For one
+ * that does, the order follows what the specification lets a host do: it may read the resource at any time, so a read
+ * starts nothing; the catalogue is served when the tool is called; and the story's own code loads in the host's frame
+ * when the page sets the address the answer gives. The page's source is imported at the first read.
+ *
+ * @module
+ */
+import { isStoriesDocument } from "../../src/vite/agentApi.js";
+import { namedStory } from "../../src/vite/agentIds.js";
+import { AGENT_API } from "../../src/vite/agentRoutes.js";
+import { PREVIEW_ROUTE } from "../../src/vite/previewRoute.js";
+/** The address of the page a preview is shown in. */
+export const PREVIEW_URI = "ui://forgebook/story-preview";
+/** The MCP Apps version the page speaks, the extension's own and apart from the protocol's. */
+const APPS_VERSION = "2026-01-26";
+/** The tool that takes the picture a host that cannot show the story gets instead. */
+const SHOT_TOOL = "story_shot";
+/** How long a story may stay silent before its picture is asked for, in ms: long enough for a cold dev server. */
+const SILENCE_MS = 20_000;
+/** The tool's name. */
+const PREVIEW_TOOL = "story_preview";
+/** A link on another origin: a server of the command's own serves on its own port, not where the links say. */
+const linkAt = (origin, link) => {
+    const { pathname, search } = new URL(link);
+    return `${origin}${pathname}${search}`;
+};
+/**
+ * The tool that shows a story to the person, inside the client.
+ *
+ * @param reach - what it reaches the catalogue through.
+ */
+export const previewTool = ({ ask, serve }) => ({
+    name: PREVIEW_TOOL,
+    description: `Show a story to the person, live, inside this conversation. You do not see it: to look at it yourself call ${SHOT_TOOL}.`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            id: { type: "string", description: "The story's id, as list_stories gives it." },
+            view: {
+                type: "string",
+                description: "The view to show it in, as the catalogue's address writes it (theme=dark&lang=it); none for the default."
+            }
+        },
+        required: ["id"],
+        additionalProperties: false
+    },
+    appResource: PREVIEW_URI,
+    call: async (args) => {
+        const view = typeof args["view"] === "string" ? args["view"] : "";
+        const answer = await ask("stories", new URLSearchParams({ view }));
+        if (answer.status !== 200 || !isStoriesDocument(answer.body))
+            return { structured: answer.body, isError: true };
+        // a former id (`formerStoryId`) names its story too, which is answered under its own id
+        const named = namedStory(answer.body, typeof args["id"] === "string" ? args["id"] : "");
+        if (named === undefined)
+            return { structured: { error: `No story "${String(args["id"])}"` }, isError: true };
+        const { story } = named;
+        const { id } = story;
+        let origin;
+        try {
+            origin = await serve();
+        }
+        catch (error) {
+            // the story exists: with no address to show it at, the page takes its picture instead
+            const problem = error instanceof Error ? error.message : String(error);
+            return { structured: { id, links: story.links, problem }, isError: false };
+        }
+        const preview = `${origin}${AGENT_API}${PREVIEW_ROUTE}?${new URLSearchParams({ id, view }).toString()}`;
+        return {
+            structured: {
+                id,
+                preview,
+                links: { address: linkAt(origin, story.links.address), frame: linkAt(origin, story.links.frame) }
+            },
+            isError: false
+        };
+    }
+});
+/**
+ * The resource a preview is shown in.
+ *
+ * @param options - what it is made from.
+ */
+export const previewResource = ({ origin, strings, version }) => ({
+    uri: PREVIEW_URI,
+    name: "story_preview",
+    description: "A story of the catalogue, live, or its picture when the client cannot show it live.",
+    read: async () => {
+        const { previewViewPage } = await import("../../src/vite/previewPages.js");
+        const { previewTexts } = await import("../../src/previewTexts.js");
+        return {
+            html: previewViewPage({
+                texts: previewTexts(strings),
+                version,
+                protocolVersion: APPS_VERSION,
+                shotTool: SHOT_TOOL,
+                silenceMs: SILENCE_MS
+            }),
+            frameDomains: [new URL(await origin()).origin]
+        };
+    }
+});

package/dist/bin/forgebook/mcpToolParts.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What the tools `forgebook mcp` offers share: how they ask the catalogue, their view argument and how an answer
+ * becomes a result.
+ *
+ * @module
+ */
+import type { AgentAnswer } from "../../src/vite/agentRoutes.ts";
+import type { McpToolResult } from "../../src/vite/mcpProtocol.ts";
+/** Asks the catalogue one of its answers. */
+export type Ask = (route: string, params: URLSearchParams) => Promise<AgentAnswer>;
+/** The schema of the view argument, shared by the tools. */
+export declare const VIEW: {
+    readonly type: "string";
+    readonly description: "The view the links open in, as the catalogue's address writes it (theme=dark&lang=it, audience=designer); none for the default.";
+};
+/**
+ * A text argument, or none.
+ *
+ * @param args - the tool's arguments.
+ * @param name - the argument's name.
+ */
+export declare const textOf: (args: Readonly<Record<string, unknown>>, name: string) => string | undefined;
+/**
+ * An answer as a tool's result: a failure when the catalogue did not answer 200.
+ *
+ * @param answer - the catalogue's answer.
+ */
+export declare const resultOf: (answer: AgentAnswer) => McpToolResult;

package/dist/bin/forgebook/mcpToolParts.js

@@ -0,0 +1,24 @@
+/** The schema of the view argument, shared by the tools. */
+export const VIEW = {
+    type: "string",
+    description: "The view the links open in, as the catalogue's address writes it (theme=dark&lang=it, audience=designer); none for the default."
+};
+/**
+ * A text argument, or none.
+ *
+ * @param args - the tool's arguments.
+ * @param name - the argument's name.
+ */
+export const textOf = (args, name) => {
+    const value = args[name];
+    return typeof value === "string" && value !== "" ? value : undefined;
+};
+/**
+ * An answer as a tool's result: a failure when the catalogue did not answer 200.
+ *
+ * @param answer - the catalogue's answer.
+ */
+export const resultOf = (answer) => ({
+    structured: answer.body,
+    isError: answer.status !== 200
+});