forgebook 0.1.8 → 0.2.0

package/dist/src/vite/agentIds.js

@@ -0,0 +1,41 @@
+/**
+ * Finds a component or a story of the stories' document by an id, the id an earlier rule gave it included, for the
+ * commands that read the document rather than the tree (`forgebook check`, `forgebook shot`, `forgebook diff`, the
+ * `story_links` tool).
+ *
+ * @remarks
+ * The tree finds a former id itself (`findStory`); the document carries only the current ids, so the former ones are
+ * worked out from each component's source and title and each story's export, by the same rule. Pure.
+ *
+ * @module
+ */
+import { formerComponentId, formerStoryId } from "../storyTree.js";
+/**
+ * The component an id names: by its id, else by the id the former rule gave it.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id.
+ */
+export const namedComponent = (document, id) => document.components.find((component) => component.id === id) ??
+    document.components.find((component) => formerComponentId(component.source, component.title) === id);
+/**
+ * The story an id names, with its component: by its id, else by the id the former rule gave it.
+ *
+ * @param document - the catalogue's stories.
+ * @param id - the id.
+ */
+export const namedStory = (document, id) => {
+    const stories = document.components.flatMap((component) => component.stories.map((story) => ({ component, story })));
+    return (stories.find(({ story }) => story.id === id) ??
+        stories.find(({ component, story }) => formerStoryId(component.source, component.title, story.exportName) === id));
+};
+/**
+ * The id the former rule gave a story of the document, when it differs from its id: its pictures may still carry it.
+ *
+ * @param component - the story's component.
+ * @param story - the story.
+ */
+export const formerIdOf = (component, story) => {
+    const former = formerStoryId(component.source, component.title, story.exportName);
+    return former === story.id ? undefined : former;
+};

package/dist/src/vite/agentIndex.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The catalogue as a file, for `forgebook mcp --from`: what its read-only tools answer with no dev server and no repository.
+ *
+ * @remarks
+ * `forgebook build --agent-index` writes it beside the pages. It holds what the dev server's answers hold (stories, their
+ * props and docs, tokens), and the links are made when it is read, since only the reader knows where the catalogue is
+ * served. The questions run the code the dev server runs, so a built catalogue answers as a running one does.
+ *
+ * @module
+ */
+import type { UsageGuidance } from "../componentDocs.ts";
+import type { StoriesDocument, StoryDocument } from "./agent.types.ts";
+import { type CataloguePages } from "./agentApi.ts";
+import type { AgentAnswer } from "./agentRoutes.ts";
+import { type FindableComponent } from "./findComponent.ts";
+import { type TokenReading } from "./tokenAnswers.ts";
+/** The file's name in the built catalogue. */
+export declare const AGENT_INDEX_FILE = "forgebook-agent.json";
+/** A component as a search finds it, with what its answer carries. */
+export type IndexedComponent = FindableComponent & {
+    /** Its first story's id. */
+    readonly story: string | undefined;
+    /** When to use it and when not, when its TSDoc says. */
+    readonly guidance?: UsageGuidance;
+};
+/** The file. */
+export type AgentIndex = {
+    /** The shape's version. */
+    readonly schema: 1;
+    /** The list of stories, with "Used in" where the catalogue offers it. */
+    readonly stories: StoriesDocument;
+    /** Each story in detail, by id. */
+    readonly details: Readonly<Record<string, StoryDocument>>;
+    /** What the intent search reads. */
+    readonly findable: readonly IndexedComponent[];
+    /** The tokens. */
+    readonly tokens: TokenReading;
+    /** The stories that could not be read when it was written. */
+    readonly problems: readonly string[];
+};
+/**
+ * Everything the index says went wrong while it was written, for whoever builds it: a story that failed to load is an
+ * answer with problems, not a missing one.
+ *
+ * @param index - the file.
+ */
+export declare const indexProblems: (index: AgentIndex) => readonly string[];
+/**
+ * Whether a value is an index this version reads.
+ *
+ * @param value - the parsed file.
+ */
+export declare const isAgentIndex: (value: unknown) => value is AgentIndex;
+/**
+ * Answers one of the API's paths from the file.
+ *
+ * @param index - the file.
+ * @param pages - where the catalogue is served, for the links.
+ * @param route - the path, as a dev server takes it.
+ * @param params - the query.
+ * @returns the same answer a dev server gives, or a 404 for what only a dev server can do.
+ */
+export declare const indexAnswer: (index: AgentIndex, pages: CataloguePages, route: string, params: URLSearchParams) => AgentAnswer;

package/dist/src/vite/agentIndex.js

@@ -0,0 +1,91 @@
+import { storyLinks } from "./agentApi.js";
+import { findComponents } from "./findComponent.js";
+import { TOKEN_ANSWERS } from "./tokenAnswers.js";
+/** The file's name in the built catalogue. */
+export const AGENT_INDEX_FILE = "forgebook-agent.json";
+/**
+ * Everything the index says went wrong while it was written, for whoever builds it: a story that failed to load is an
+ * answer with problems, not a missing one.
+ *
+ * @param index - the file.
+ */
+export const indexProblems = (index) => [
+    ...index.problems,
+    ...index.stories.problems,
+    ...index.tokens.unread,
+    ...index.tokens.problems,
+    ...Object.entries(index.details).flatMap(([id, detail]) => detail.problems.map((problem) => `${id}: ${problem}`))
+];
+/** Whether a value is a plain object. */
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Whether a value is an index this version reads.
+ *
+ * @param value - the parsed file.
+ */
+export const isAgentIndex = (value) => isRecord(value) &&
+    value["schema"] === 1 &&
+    isRecord(value["stories"]) &&
+    isRecord(value["details"]) &&
+    Array.isArray(value["findable"]) &&
+    isRecord(value["tokens"]) &&
+    Array.isArray(value["problems"]);
+/** The list with the links of where the reader finds the catalogue, and "Used in" only when asked for. */
+const storiesAnswer = ({ stories }, pages, params) => {
+    const view = params.get("view") ?? "";
+    const isUsageAsked = params.get("usedIn") === "true";
+    const components = stories.components.map(({ usedIn, ...component }) => ({
+        ...component,
+        ...(isUsageAsked && usedIn !== undefined ? { usedIn } : {}),
+        stories: component.stories.map((story) => ({ ...story, links: storyLinks(pages, story.id, view) }))
+    }));
+    return { status: 200, body: { ...stories, components } };
+};
+/** One story, with the same links. */
+const storyAnswer = ({ details }, pages, params) => {
+    const id = params.get("id") ?? "";
+    const detail = Object.hasOwn(details, id) ? details[id] : undefined;
+    if (detail === undefined)
+        return { status: 404, body: { error: `No story "${id}"` } };
+    const links = storyLinks(pages, id, params.get("view") ?? "");
+    return { status: 200, body: { ...detail, story: { ...detail.story, links } } };
+};
+/** The components a description fits. */
+const findAnswer = ({ findable }, pages, params) => {
+    const query = params.get("query") ?? "";
+    if (query.trim() === "")
+        return { status: 400, body: { error: "No words to look for" } };
+    const components = findComponents(findable, query).map((found) => {
+        const component = findable.find((each) => each.id === found.id);
+        const story = component?.story;
+        return {
+            ...found,
+            story,
+            links: story === undefined ? undefined : storyLinks(pages, story, ""),
+            ...(component?.guidance === undefined ? {} : { guidance: component.guidance })
+        };
+    });
+    const body = { schema: 1, query, components };
+    return { status: 200, body };
+};
+/**
+ * Answers one of the API's paths from the file.
+ *
+ * @param index - the file.
+ * @param pages - where the catalogue is served, for the links.
+ * @param route - the path, as a dev server takes it.
+ * @param params - the query.
+ * @returns the same answer a dev server gives, or a 404 for what only a dev server can do.
+ */
+export const indexAnswer = (index, pages, route, params) => {
+    if (route === "stories")
+        return storiesAnswer(index, pages, params);
+    if (route === "story")
+        return storyAnswer(index, pages, params);
+    if (route === "find")
+        return findAnswer(index, pages, params);
+    const tokenAnswer = Object.hasOwn(TOKEN_ANSWERS, route) ? TOKEN_ANSWERS[route] : undefined;
+    if (tokenAnswer !== undefined)
+        return tokenAnswer(index.tokens, params);
+    return { status: 404, body: { error: `A built catalogue cannot answer "${route}"` } };
+};

package/dist/src/vite/agentIndexRoute.d.ts

@@ -0,0 +1,10 @@
+import { type AgentAnswer, type RouteContext } from "./agentRoutes.ts";
+import type { TokenReading } from "./tokenAnswers.ts";
+/**
+ * The whole catalogue, as one document.
+ *
+ * @param context - what the routes read.
+ * @param tokens - the tokens, read.
+ * @returns the index, with the stories that could not be answered at all in its problems.
+ */
+export declare const agentIndexAnswer: (context: RouteContext, tokens: TokenReading) => Promise<AgentAnswer>;

package/dist/src/vite/agentIndexRoute.js

@@ -0,0 +1,35 @@
+import { isStoriesDocument, isStoryDocument } from "./agentApi.js";
+import { storiesAnswer, storyAnswer } from "./agentRoutes.js";
+import { indexedComponents } from "./findRoute.js";
+/**
+ * The whole catalogue, as one document.
+ *
+ * @param context - what the routes read.
+ * @param tokens - the tokens, read.
+ * @returns the index, with the stories that could not be answered at all in its problems.
+ */
+export const agentIndexAnswer = async (context, tokens) => {
+    const listed = await storiesAnswer({ ...context, params: new URLSearchParams({ usedIn: "true" }) });
+    if (!isStoriesDocument(listed.body))
+        return listed;
+    const stories = listed.body;
+    const ids = stories.components.flatMap((component) => component.stories.map((story) => story.id));
+    const details = {};
+    const problems = [];
+    for (const id of ids) {
+        const answer = await storyAnswer({ ...context, params: new URLSearchParams({ id }) });
+        if (answer.status === 200 && isStoryDocument(answer.body))
+            details[id] = answer.body;
+        else
+            problems.push(`${id}: ${JSON.stringify(answer.body)}`);
+    }
+    const body = {
+        schema: 1,
+        stories,
+        details,
+        findable: await indexedComponents(context),
+        tokens,
+        problems
+    };
+    return { status: 200, body };
+};

package/dist/src/vite/agentRoutes.d.ts

@@ -1,21 +1,53 @@
-/**
- * The dev server's answers to tools and agents, under `/__forgebook/api/`: `stories` (every story) and `story?id=…`
- * (one in detail), each with an optional `view` (the view's query, `theme=dark&lang=it`) the links open in.
- *
- * @remarks
- * The server loads the sources and the previews with the same imports the pages use (`AGENT_SOURCES_FILE`), so a tool
- * sees what the shell shows. A story module that fails on Node (it reads `window` while it loads) gives its story a
- * problem in the answer instead of an error. Served by the dev server only, where Vite listens (localhost by default);
- * a build has none of it.
- *
- * @module
- */
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { ViteDevServer } from "vite";
+import type { StorySource } from "@forgebook/story-format/source";
+import { type ViteDevServer } from "vite";
+import { type LoadedPreview } from "../frame/storyModule.ts";
+import type { FramesPlacement, PageOrigins } from "../frameOrigins.ts";
 import type { LiveErrors } from "../liveErrors.ts";
+import { type StoryTree } from "../storyTree.ts";
+import { type CataloguePages, type LoadedStoryParts } from "./agentApi.ts";
 import type { ResolvedConfig } from "./configFile.ts";
 /** The path the answers live under. */
 export declare const AGENT_API = "/__forgebook/api/";
+/**
+ * The pages under `AGENT_API` another origin's page may frame: a client's inline preview. They show a story and act on
+ * nothing, so the catalogue's guard lets another origin open them, as it does the catalogue's page.
+ */
+export declare const FRAMED_AGENT_PAGES: ReadonlySet<string>;
+/** What the agent module gives: the sources and the previews merged. */
+type AgentModule = {
+    /** The catalogue's sources, in its order. */
+    readonly sources: readonly StorySource[];
+    /** Its previews merged. */
+    readonly preview: LoadedPreview;
+    /** Why a preview was left out: it could not load on the server. */
+    readonly problems: readonly string[];
+};
+/**
+ * The agent module read with the catalogue's previews, or why it is not what the plugin generates.
+ *
+ * @param module - the module of `AGENT_SOURCES_FILE`, as the server loaded it.
+ * @param previews - what loads each preview, in the configuration's order.
+ */
+export declare const agentModuleOf: (module: unknown, previews: readonly (() => Promise<unknown>)[]) => Promise<AgentModule>;
+/** A loader's value, or why it failed. */
+export declare const settled: (load: (() => Promise<unknown>) | undefined) => Promise<LoadedStoryParts["docs"]>;
+/** What an answer asks of the dev server. */
+export type AgentServer = {
+    /** Loads a module on the server. */
+    readonly load: (id: string) => Promise<unknown>;
+    /** Loads a preview on the server, with what only a browser can load left as placeholders (`previewRunner.ts`). */
+    readonly loadPreview: (file: string) => Promise<unknown>;
+    /** The file a source's module specifier leads to, as the pages' imports find it; none when nothing does. */
+    readonly resolveSource: (specifier: string) => Promise<string | undefined>;
+};
+/**
+ * What the answers ask of a dev server.
+ *
+ * @param server - the dev server.
+ * @param config - the catalogue's configuration, whose generated module the sources are imported from.
+ */
+export declare const agentServer: (server: ViteDevServer, config: ResolvedConfig) => AgentServer;
 /** An answer: its HTTP status and its JSON body. */
 export type AgentAnswer = {
     /** 200, 404 for a story or a path that does not exist, 500 when the sources fail to load. */
@@ -32,26 +64,55 @@ export declare const ROOT_HEADER = "forgebook-root";
  * @param dir - the catalogue's folder.
  */
 export declare const rootHeaderValue: (dir: string) => string;
+/** What every route reads: the catalogue's sources and tree, its configuration, the query and the links' pages. */
+export type RouteContext = {
+    /** The sources and the preview, as the dev server loaded them. */
+    readonly loaded: AgentModule;
+    /** The sources' story tree. */
+    readonly tree: StoryTree;
+    /** The catalogue's configuration. */
+    readonly config: ResolvedConfig;
+    /** The query. */
+    readonly params: URLSearchParams;
+    /** Where the catalogue is served, for the links. */
+    readonly pages: CataloguePages;
+    /** The view the links open in; empty for the default view. */
+    readonly view: string;
+};
+/**
+ * The stories, with each component's "Used in" when asked for and offered.
+ *
+ * @param context - what the routes read.
+ */
+export declare const storiesAnswer: (context: RouteContext) => Promise<AgentAnswer>;
+/**
+ * One story in detail, its component's "Used in" when offered.
+ *
+ * @param context - what the routes read.
+ */
+export declare const storyAnswer: (context: RouteContext) => Promise<AgentAnswer>;
 /**
  * Answers one of the API's paths.
  *
- * @param load - loads a module on the server (the dev server's `ssrLoadModule`).
+ * @param server - what the answers ask of the dev server.
  * @param config - the catalogue's configuration.
  * @param route - the path under `AGENT_API` (`stories`, `story`).
- * @param params - the query: `id` for a story, `view` for the links, `usedIn=true` for the list's "Used in" (a
+ * @param params - the query: `id` for a story, `view` for the links, `category`, `name`, `value` and `type` for the
+ *   tokens, `query` and `limit` for a search, `usedIn=true` for the list's "Used in" (a
  *   story's comes with it when the catalogue offers it).
- * @param origin - where the catalogue is served (`http://localhost:5173`), for the links.
+ * @param origins - where the catalogue is served (`http://localhost:5173`) and where its frames are, for the links.
  * @param live - the errors the open frames reported, on a dev server a browser uses; none for a server of the
  *   command's own, which no frame reports to.
  */
-export declare const agentAnswer: (load: (id: string) => Promise<unknown>, config: ResolvedConfig, route: string, params: URLSearchParams, origin: string, live?: LiveErrors) => Promise<AgentAnswer>;
+export declare const agentAnswer: (server: AgentServer, config: ResolvedConfig, route: string, params: URLSearchParams, origins: PageOrigins, live?: LiveErrors) => Promise<AgentAnswer>;
 /**
  * The middleware that answers under `AGENT_API`, for a catalogue's dev server.
  *
  * @param server - the dev server, which loads the modules.
  * @param config - the catalogue's configuration.
  * @param live - the errors the open frames report.
+ * @param placement - where the frames run, for the links to them.
  * @returns a Connect middleware: it answers its own paths and passes every other request on.
  */
-export declare const agentMiddleware: (server: ViteDevServer, config: ResolvedConfig, live: LiveErrors) => (request: IncomingMessage, response: ServerResponse, next: (error?: unknown) => void) => void;
-//# sourceMappingURL=agentRoutes.d.ts.map
+export declare const agentMiddleware: (server: ViteDevServer, config: ResolvedConfig, live: LiveErrors, placement: () => Promise<FramesPlacement>) => (request: IncomingMessage, response: ServerResponse, next: (error?: unknown) => void) => void;
+export {};

package/dist/src/vite/agentRoutes.js

@@ -1,12 +1,47 @@
-import { join } from "node:path";
-import { mergedPreviews, readPreview } from "../frame/storyModule.js";
+/**
+ * The dev server's answers to tools and agents, under `/__forgebook/api/`: `stories` (every story) and `story?id=…`
+ * (one in detail), `pages` and `page?id=…` (the docs pages), `search?query=…` (everything, by its text), each with an
+ * optional `view` (the view's query, `theme=dark&lang=it`) the links open in; and `preview?id=…`, the page that shows a
+ * story inside a client that renders apps, the one answer that is not JSON.
+ *
+ * @remarks
+ * The server loads the sources with the same imports the pages use (`AGENT_SOURCES_FILE`), so a tool sees what the
+ * shell shows. A story module that fails on Node (it reads `window` while it loads) gives its story a problem in the
+ * answer instead of an error. A preview is written for a browser, and only its args and parameters are read here: it
+ * loads with what it imports that needs a browser left as placeholders (`previewRunner.ts`), and one that still fails is
+ * left out of the answers and named among their problems, so it costs a tool neither the catalogue nor answers changed
+ * without a word. Served by the dev server only, where
+ * Vite listens (localhost by default); a build has none of it.
+ *
+ * @module
+ */
+import { realpath } from "node:fs/promises";
+import { createIdResolver } from "vite";
+import { mergedPreviews, NO_PREVIEW, readPreview } from "../frame/storyModule.js";
 import { sourceFiles } from "../sourceFiles.js";
-import { findStory, storyTree } from "../storyTree.js";
+import { findComponentByTitle, findStory, storyTree } from "../storyTree.js";
 import { sourceUsage } from "../usedIn.js";
-import { storiesDocument, storyDocument } from "./agentApi.js";
-import { AGENT_SOURCES_FILE } from "./pages.js";
+import { frameAddressOf } from "../viewState.js";
+import { storiesDocument, storyDocument, storyLinks } from "./agentApi.js";
+import { agentIndexAnswer } from "./agentIndexRoute.js";
+import { pageAnswer, pagesAnswer } from "./docPagesRoute.js";
+import { findAnswer } from "./findRoute.js";
+import { framesOriginOf } from "./framesConfig.js";
+import { hostOf } from "./framesServer.js";
+import { catalogueChangedFiles, changeBase, changedFiles } from "./gitChange.js";
+import { AGENT_SOURCES_FILE, pageModulePath } from "./pages.js";
+import { PREVIEW_ROUTE } from "./previewRoute.js";
+import { loadPreview } from "./previewRunner.js";
+import { searchAnswer } from "./searchRoute.js";
+import { catalogueTokens, STORYLESS_ROUTES } from "./storylessRoutes.js";
+import { affectedStories } from "./storyReach.js";
 /** The path the answers live under. */
 export const AGENT_API = "/__forgebook/api/";
+/**
+ * The pages under `AGENT_API` another origin's page may frame: a client's inline preview. They show a story and act on
+ * nothing, so the catalogue's guard lets another origin open them, as it does the catalogue's page.
+ */
+export const FRAMED_AGENT_PAGES = new Set([`${AGENT_API}${PREVIEW_ROUTE}`]);
 /** Whether a value is a plain object. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** Whether a value is a source, as far as the answers read one: its id, name and story files. */
@@ -14,15 +49,35 @@ const isStorySource = (value) => isRecord(value) &&
     typeof value["id"] === "string" &&
     typeof value["name"] === "string" &&
     Array.isArray(value["files"]);
-/** The agent module read, or why it is not what the plugin generates. */
-const agentModuleOf = (module) => {
-    if (!isRecord(module) || !Array.isArray(module["sources"]) || !Array.isArray(module["previews"]))
+/** A preview, read from what loads it, or why it cannot load on the server. */
+const loadedPreview = async (load) => {
+    try {
+        return readPreview(await load());
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return `a preview did not load on the server, so its args and parameters are left out of these answers: ${message}`;
+    }
+};
+/**
+ * The agent module read with the catalogue's previews, or why it is not what the plugin generates.
+ *
+ * @param module - the module of `AGENT_SOURCES_FILE`, as the server loaded it.
+ * @param previews - what loads each preview, in the configuration's order.
+ */
+export const agentModuleOf = async (module, previews) => {
+    if (!isRecord(module) || !Array.isArray(module["sources"]))
         throw new Error("The catalogue's sources did not load");
     const sources = module["sources"].filter(isStorySource);
-    return { sources, preview: mergedPreviews(module["previews"].map(readPreview)) };
+    const loaded = await Promise.all(previews.map(loadedPreview));
+    return {
+        sources,
+        preview: mergedPreviews(loaded.map((each) => (typeof each === "string" ? NO_PREVIEW : each))),
+        problems: loaded.filter((each) => typeof each === "string")
+    };
 };
 /** A loader's value, or why it failed. */
-const settled = async (load) => {
+export const settled = async (load) => {
     if (load === undefined)
         return { value: { name: null } };
     try {
@@ -41,6 +96,22 @@ const usageBySource = async (sources) => {
     const answers = await Promise.all(sources.map(async (source) => [source.id, await sourceUsage(source)]));
     return new Map(answers.flatMap(([id, index]) => (typeof index === "string" ? [] : [[id, index]])));
 };
+/**
+ * What the answers ask of a dev server.
+ *
+ * @param server - the dev server.
+ * @param config - the catalogue's configuration, whose generated module the sources are imported from.
+ */
+export const agentServer = (server, config) => {
+    // Vite's resolver, not Node's: a catalogue's aliases and a package's export conditions lead to the same file; `scan`
+    // keeps it on the package's own file and away from the optimizer, which would answer with a prebundle
+    const resolveId = createIdResolver(server.config, { scan: true });
+    return {
+        load: (id) => server.ssrLoadModule(id),
+        loadPreview: (file) => loadPreview(server.environments.ssr, file),
+        resolveSource: (specifier) => resolveId(server.environments.client, specifier, pageModulePath(config.dir, AGENT_SOURCES_FILE))
+    };
+};
 /** The header that names the catalogue's folder, so a client knows the server it found serves its catalogue. */
 export const ROOT_HEADER = "forgebook-root";
 /**
@@ -71,19 +142,47 @@ const errorsAnswer = (context, live) => {
  *
  * @param context - what the routes read.
  */
-const storiesAnswer = async (context) => {
+export const storiesAnswer = async (context) => {
     const { config, params, tree, pages, view, loaded } = context;
     const usage = config.lists.usedIn !== false && params.get("usedIn") === "true"
         ? await usageBySource(loaded.sources)
         : undefined;
     return { status: 200, body: storiesDocument(config.title, tree, pages, view, usage) };
 };
+/** Whether a value is a list of stories with what they reach. */
+const isReach = (value) => Array.isArray(value);
+/**
+ * The stories a change touches, read from the files git names and the import graph "Used in" reads.
+ *
+ * @param context - what the routes read.
+ */
+const changedAnswer = async ({ config, loaded, tree, params, pages, view }) => {
+    const since = params.get("since") || "HEAD";
+    const base = await changeBase(config.dir, since);
+    if (base === undefined)
+        return { status: 400, body: { error: `"${since}" names no commit here` } };
+    const { root, files } = await changedFiles(config.dir, base);
+    const reaches = await Promise.all(loaded.sources.flatMap((source) => source.files.map(async (group) => {
+        const reach = await group.reach?.();
+        return { source: source.id, reach: isReach(reach) ? reach : [] };
+    })));
+    const changed = catalogueChangedFiles(config.dir, await realpath(config.dir), root, files);
+    const stories = reaches.flatMap(({ source, reach }) => affectedStories(reach, changed).flatMap((story) => {
+        const component = findComponentByTitle(tree, source, story.title)?.component;
+        const found = [...(component?.stories ?? []), ...(component?.unlisted ?? [])].find((each) => each.exportName === story.exportName);
+        return found === undefined
+            ? []
+            : [{ id: found.id, title: story.title, links: storyLinks(pages, found.id, view) }];
+    }));
+    const body = { schema: 1, since, files, stories, problems: [] };
+    return { status: 200, body };
+};
 /**
  * One story in detail, its component's "Used in" when offered.
  *
  * @param context - what the routes read.
  */
-const storyAnswer = async (context) => {
+export const storyAnswer = async (context) => {
     const { config, params, tree, pages, view, loaded } = context;
     const id = params.get("id") ?? "";
     const location = findStory(tree, id);
@@ -91,7 +190,8 @@ const storyAnswer = async (context) => {
     if (location === undefined || source === undefined)
         return { status: 404, body: { error: `No story "${id}"` } };
     const files = sourceFiles(source);
-    const file = location.component.file;
+    // the story's own file: its module, and the docs of the component its meta names, which its args are for
+    const file = location.story.file;
     const parts = {
         module: await settled(files.stories[file]),
         docs: await settled(files.docs[file]),
@@ -105,24 +205,29 @@ const storyAnswer = async (context) => {
 /**
  * Answers one of the API's paths.
  *
- * @param load - loads a module on the server (the dev server's `ssrLoadModule`).
+ * @param server - what the answers ask of the dev server.
  * @param config - the catalogue's configuration.
  * @param route - the path under `AGENT_API` (`stories`, `story`).
- * @param params - the query: `id` for a story, `view` for the links, `usedIn=true` for the list's "Used in" (a
+ * @param params - the query: `id` for a story, `view` for the links, `category`, `name`, `value` and `type` for the
+ *   tokens, `query` and `limit` for a search, `usedIn=true` for the list's "Used in" (a
  *   story's comes with it when the catalogue offers it).
- * @param origin - where the catalogue is served (`http://localhost:5173`), for the links.
+ * @param origins - where the catalogue is served (`http://localhost:5173`) and where its frames are, for the links.
  * @param live - the errors the open frames reported, on a dev server a browser uses; none for a server of the
  *   command's own, which no frame reports to.
  */
-export const agentAnswer = async (load, config, route, params, origin, live) => {
+export const agentAnswer = async (server, config, route, params, origins, live) => {
     try {
-        const loaded = agentModuleOf(await load(join(config.dir, AGENT_SOURCES_FILE)));
+        const answerAlone = STORYLESS_ROUTES[route];
+        if (answerAlone !== undefined)
+            return await answerAlone(config, params, server.resolveSource);
+        const loaded = await agentModuleOf(await server.load(pageModulePath(config.dir, AGENT_SOURCES_FILE)), config.previews.map((file) => () => server.loadPreview(file)));
+        const tree = storyTree(loaded.sources);
         const context = {
             loaded,
-            tree: storyTree(loaded.sources),
+            tree: { ...tree, problems: [...loaded.problems, ...tree.problems] },
             config,
             params,
-            pages: { page: `${origin}/`, frame: `${origin}/frame.html` },
+            pages: { page: `${origins.catalogue}/`, frame: `${origins.frames}/frame.html` },
             view: params.get("view") ?? ""
         };
         if (route === "errors")
@@ -131,28 +236,67 @@ export const agentAnswer = async (load, config, route, params, origin, live) =>
             return await storiesAnswer(context);
         if (route === "story")
             return await storyAnswer(context);
+        if (route === "find")
+            return await findAnswer(context);
+        if (route === "search")
+            return await searchAnswer(context);
+        if (route === "pages")
+            return await pagesAnswer(context);
+        if (route === "page")
+            return await pageAnswer(context);
+        if (route === "changed")
+            return await changedAnswer(context);
+        if (route === "agent-index")
+            return await agentIndexAnswer(context, await catalogueTokens(config, server.resolveSource));
         return { status: 404, body: { error: `No answer at ${AGENT_API}${route}` } };
     }
     catch (error) {
         return { status: 500, body: { error: error instanceof Error ? error.message : String(error) } };
     }
 };
+/**
+ * Answers a story's preview page. Its code is read here, on the first request for one: a dev server no client asks for a
+ * preview never loads it.
+ *
+ * @param url - the request's address: `id` and `view` in its query.
+ * @param framesOrigin - the frames' origin, where the page loads the story's frame.
+ * @param response - the answer.
+ */
+const answerPreview = async (url, framesOrigin, response) => {
+    const { previewRelayPage } = await import("./previewPages.js");
+    const id = url.searchParams.get("id") ?? "";
+    const frame = frameAddressOf(`${framesOrigin}/frame.html`, id, url.searchParams.get("view") ?? "");
+    response.setHeader("Content-Type", "text/html");
+    response.setHeader("Cache-Control", "no-store");
+    response.end(previewRelayPage(frame, id));
+};
 /**
  * The middleware that answers under `AGENT_API`, for a catalogue's dev server.
  *
  * @param server - the dev server, which loads the modules.
  * @param config - the catalogue's configuration.
  * @param live - the errors the open frames report.
+ * @param placement - where the frames run, for the links to them.
  * @returns a Connect middleware: it answers its own paths and passes every other request on.
  */
-export const agentMiddleware = (server, config, live) => (request, response, next) => {
-    const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "localhost"}`);
+export const agentMiddleware = (server, config, live, placement) => (request, response, next) => {
+    const scheme = server.config.server.https === undefined ? "http:" : "https:";
+    const url = new URL(request.url ?? "/", `${scheme}//${hostOf(request) ?? "localhost"}`);
     if (!url.pathname.startsWith(AGENT_API)) {
         next();
         return;
     }
     const route = url.pathname.slice(AGENT_API.length);
-    void agentAnswer((id) => server.ssrLoadModule(id), config, route, url.searchParams, url.origin, live)
+    const origins = placement().then((frames) => ({
+        catalogue: url.origin,
+        frames: framesOriginOf(frames, url.href) ?? url.origin
+    }));
+    if (route === PREVIEW_ROUTE) {
+        void origins.then((each) => answerPreview(url, each.frames, response)).catch(next);
+        return;
+    }
+    void origins
+        .then((each) => agentAnswer(agentServer(server, config), config, route, url.searchParams, each, live))
         .then(({ status, body }) => {
         response.statusCode = status;
         response.setHeader("Content-Type", "application/json");
@@ -165,4 +309,3 @@ export const agentMiddleware = (server, config, live) => (request, response, nex
         response.end(`${JSON.stringify({ error: error instanceof Error ? error.message : String(error) })}\n`);
     });
 };
-//# sourceMappingURL=agentRoutes.js.map