forgebook 0.3.3 → 0.4.1

package/dist/src/vite/agentApi.js

@@ -7,8 +7,12 @@
  */
 import { isComponentDocs } from "../componentDocs.js";
 import { embedAddressOf } from "../embedCode.js";
+import { panelArgsOf } from "../frame/panelValues.js";
 import { NO_PREVIEW, readStory } from "../frame/storyModule.js";
 import { isLiveErrorReport } from "../liveErrors.js";
+import { controlsOfParameter, excludedControls, panelArgTypesOf } from "../storyArgTypes.js";
+import { checkedSetArgs, customControlProblems, storyControlsOf } from "../storyControls.js";
+import { passesTags } from "../storyTags.js";
 import { findComponentByTitle } from "../storyTree.js";
 import { componentAddressOf, frameAddressOf, storyAddressOf } from "../viewState.js";
 /**
@@ -143,6 +147,14 @@ export const jsonValue = (value) => {
 };
 /** Whether a value is a plain object. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Why a value an agent asked to set was left out, as its answer says it. */
+const DROPPED_REASONS = {
+    undeclared: "the story declares no such arg, or does not let it be set",
+    type: "it is not of the type its control takes (see `controls`)",
+    unreadable: "it is not plain JSON",
+    markup: "this framework writes it into HTML, so only plain text can be set",
+    control: "its custom control's schema refuses it, or could not be read"
+};
 /** The docs a story file's docs loader gave, as a document field, with the problem when there is one. */
 const docsOf = (loaded) => {
     if ("error" in loaded)
@@ -154,6 +166,51 @@ const docsOf = (loaded) => {
         return { docs: undefined, problem: `Its component's docs failed: ${value.error}` };
     return { docs: undefined, problem: undefined };
 };
+/** The story read from its module, with what kept it from being read among the problems. */
+const loadedStoryOf = (parts, location, problems) => {
+    if ("error" in parts.module) {
+        problems.push(`Its story file failed to load: ${parts.module.error}`);
+        return undefined;
+    }
+    const read = readStory(parts.module.value, location.story.exportName, parts.preview ?? NO_PREVIEW);
+    if (typeof read !== "string")
+        return read;
+    problems.push(read);
+    return undefined;
+};
+/**
+ * The custom controls a story names, read from its module before its document is made: their modules load for it.
+ *
+ * @param module - the story file's module, as the dev server loaded it.
+ * @param location - the story's place in the tree.
+ */
+export const customControlNames = (module, location) => {
+    const loaded = loadedStoryOf({ module, docs: { value: undefined } }, location, []);
+    if (loaded === undefined)
+        return [];
+    return Object.values(panelArgTypesOf(loaded.argTypes, [])).flatMap((each) => each.customControl ?? []);
+};
+/** What a loaded story declares of its args, as the shell reads it from the story's frame. */
+const declarationOf = (loaded, docs, { namedValues = {}, customControls }) => ({
+    customSchemas: customControls?.schemas ?? {},
+    props: docs?.props ?? [],
+    argTypes: panelArgTypesOf(loaded.argTypes, excludedControls(loaded.parameters["controls"])),
+    controls: controlsOfParameter(loaded.parameters["controls"]),
+    storyArgs: panelArgsOf(loaded.args, namedValues),
+    namedValues
+});
+/**
+ * A story with the links that carry the values it takes, as a person's link would. Its frame's stays as it is: a frame
+ * takes its values from the shell, which checks them, and alone it draws the story's own. Its component's page shows no
+ * one story's values.
+ */
+const withSetArgLinks = (story, setArgs, pages, view) => {
+    if (setArgs === undefined || setArgs.param === "")
+        return story;
+    const query = new URLSearchParams({ args: setArgs.param }).toString();
+    const links = storyLinks(pages, story.id, view === "" ? query : `${view}&${query}`);
+    return { ...story, links: { ...links, frame: story.links.frame, component: story.links.component } };
+};
 /**
  * One story in detail.
  *
@@ -165,25 +222,25 @@ const docsOf = (loaded) => {
  */
 export const storyDocument = (location, parts, pages, view, usage) => {
     const component = agentComponent(location, pages, view, usage);
-    const story = component.stories.find((each) => each.id === location.story.id) ??
+    const listedStory = component.stories.find((each) => each.id === location.story.id) ??
         agentStory(location.story, false, pages, view);
     const problems = [];
-    let args = {};
-    if ("error" in parts.module)
-        problems.push(`Its story file failed to load: ${parts.module.error}`);
-    else {
-        const read = readStory(parts.module.value, location.story.exportName, parts.preview ?? NO_PREVIEW);
-        if (typeof read === "string")
-            problems.push(read);
-        else {
-            const json = jsonValue(read.args);
-            if (isRecord(json))
-                args = json;
-        }
-    }
+    const loaded = loadedStoryOf(parts, location, problems);
+    const json = loaded === undefined ? undefined : jsonValue(loaded.args);
+    const args = isRecord(json) ? json : {};
     const { docs, problem } = docsOf(parts.docs);
     if (problem !== undefined)
         problems.push(problem);
+    const declaration = loaded === undefined ? undefined : declarationOf(loaded, docs, parts);
+    const setArgs = declaration === undefined || parts.setArgs === undefined
+        ? undefined
+        : checkedSetArgs(parts.setArgs, declaration, parts.addressTexts);
+    for (const { name, reason } of setArgs?.dropped ?? []) {
+        problems.push(`The value of "${name}" was left out: ${DROPPED_REASONS[reason]}`);
+    }
+    const story = withSetArgLinks(listedStory, setArgs, pages, view);
+    const controls = declaration === undefined ? [] : storyControlsOf(declaration);
+    problems.push(...customControlProblems(controls, parts.customControls));
     return {
         schema: 1,
         requiredProps: (docs?.props ?? []).filter((prop) => prop.isRequired).map((prop) => prop.name),
@@ -200,6 +257,8 @@ export const storyDocument = (location, parts, pages, view, usage) => {
         ...agentDesign(location.story, pages, view),
         docs,
         args,
+        controls,
+        ...(setArgs === undefined ? {} : { setArgs: { accepted: setArgs.accepted, dropped: setArgs.dropped } }),
         problems
     };
 };
@@ -211,10 +270,19 @@ export const storyDocument = (location, parts, pages, view, usage) => {
  */
 export const filteredStories = (document, filter) => {
     const text = filter.component?.toLowerCase();
+    const tags = filter.tags ?? [];
     return {
         ...document,
-        components: document.components.filter((component) => (filter.source === undefined || component.source === filter.source) &&
+        components: document.components
+            .filter((component) => (filter.source === undefined || component.source === filter.source) &&
             (text === undefined || component.title.toLowerCase().includes(text)))
+            .flatMap((component) => {
+            if (tags.length === 0)
+                return [component];
+            // an unlisted story is one the catalogue's lists leave out: a filter of those lists leaves it out too
+            const stories = component.stories.filter((story) => !story.isUnlisted && passesTags(story.tags, tags));
+            return stories.length === 0 ? [] : [{ ...component, stories }];
+        })
     };
 };
 /**
@@ -293,7 +361,8 @@ export const isNearestTokensDocument = (value) => isRecord(value) &&
 export const isFoundComponentsDocument = (value) => isRecord(value) &&
     value["schema"] === 1 &&
     typeof value["query"] === "string" &&
-    Array.isArray(value["components"]);
+    Array.isArray(value["components"]) &&
+    Array.isArray(value["corrections"]);
 /**
  * Whether a value is a search's document, as a client receives it over HTTP.
  *
@@ -304,6 +373,7 @@ export const isSearchDocument = (value) => isRecord(value) &&
     typeof value["query"] === "string" &&
     typeof value["total"] === "number" &&
     Array.isArray(value["results"]) &&
+    Array.isArray(value["corrections"]) &&
     Array.isArray(value["problems"]);
 /**
  * Whether a value is the changed stories' document, as a client receives it over HTTP.
@@ -313,7 +383,10 @@ export const isSearchDocument = (value) => isRecord(value) &&
 export const isChangedStoriesDocument = (value) => isRecord(value) &&
     value["schema"] === 1 &&
     Array.isArray(value["stories"]) &&
-    Array.isArray(value["files"]);
+    Array.isArray(value["files"]) &&
+    Array.isArray(value["uiFiles"]) &&
+    Array.isArray(value["outside"]) &&
+    (value["outdated"] === undefined || Array.isArray(value["outdated"]));
 /**
  * Whether a value is the code check's document, as a client receives it over HTTP.
  *

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

@@ -14,8 +14,6 @@ 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. */

package/dist/src/vite/agentIndex.js

@@ -1,8 +1,6 @@
 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.
@@ -55,17 +53,18 @@ 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 { components: found, corrections } = findComponents(findable, query);
+    const components = found.map((match) => {
+        const component = findable.find((each) => each.id === match.id);
         const story = component?.story;
         return {
-            ...found,
+            ...match,
             story,
             links: story === undefined ? undefined : storyLinks(pages, story, ""),
             ...(component?.guidance === undefined ? {} : { guidance: component.guidance })
         };
     });
-    const body = { schema: 1, query, components };
+    const body = { schema: 1, query, components, corrections };
     return { status: 200, body };
 };
 /**

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

@@ -1,3 +1,20 @@
+/**
+ * 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 type { IncomingMessage, ServerResponse } from "node:http";
 import type { StorySource } from "@forgebook/story-format/source";
 import { type ViteDevServer } from "vite";
@@ -66,6 +83,8 @@ export declare const ROOT_HEADER = "forgebook-root";
 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 = {
+    /** What the answers ask of the dev server; none reads no custom control. */
+    readonly server?: AgentServer;
     /** The sources and the preview, as the dev server loaded them. */
     readonly loaded: AgentModule;
     /** The sources' story tree. */
@@ -97,7 +116,7 @@ export declare const storyAnswer: (context: RouteContext) => Promise<AgentAnswer
  * @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, `category`, `name`, `value` and `type` for the
+ * @param params - the query: `id` for a story, `view` for the links, `args` for the values to set, `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 origins - where the catalogue is served (`http://localhost:5173`) and where its frames are, for the links.

package/dist/src/vite/agentRoutes.js

@@ -1,41 +1,29 @@
-/**
- * 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 { offersUsedIn, readsComponentDocs } from "../catalogue.js";
+import { isComponentDocs } from "../componentDocs.js";
 import { mergedPreviews, NO_PREVIEW, readPreview } from "../frame/storyModule.js";
 import { sourceFiles } from "../sourceFiles.js";
-import { findComponentByTitle, findStory, storyTree } from "../storyTree.js";
+import { catalogueStatuses } from "../storyStatuses.js";
+import { findStory, storyTree } from "../storyTree.js";
 import { sourceUsage } from "../usedIn.js";
+import { isValueSchema } from "../valueSchema.js";
 import { frameAddressOf } from "../viewState.js";
-import { storiesDocument, storyDocument, storyLinks } from "./agentApi.js";
+import { customControlNames, storiesDocument, storyDocument } from "./agentApi.js";
 import { agentIndexAnswer } from "./agentIndexRoute.js";
+import { storiesWithStatus, storyWithStatus } from "./agentStatuses.js";
+import { withStoryCode } from "./agentStoryCode.js";
+import { changedAnswer } from "./changedRoute.js";
 import { pageAnswer, pagesAnswer } from "./docPagesRoute.js";
+import { emptyStoryGlobs, emptyStoryGlobsMessage } from "./emptyStoryGlobs.js";
 import { findAnswer } from "./findRoute.js";
 import { framesOriginOf } from "./framesConfig.js";
 import { hostOf } from "./framesServer.js";
-import { catalogueChangedFiles, changeBase, changedFiles } from "./gitChange.js";
+import { hiddenStoryFolders, hiddenStoryFoldersMessage } from "./hiddenStoryFiles.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/";
 /**
@@ -148,43 +136,19 @@ export const storiesAnswer = async (context) => {
     const usage = offersUsedIn(config.lists) && 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) }];
-    }));
-    // without the import graph no story is found, which must not read as a change that touches none
-    const problems = offersUsedIn(config.lists)
-        ? []
-        : [
-            readsComponentDocs(config.lists)
-                ? "No story is found through the imports: the catalogue turns Used in off (usedIn: false), whose import graph this reads"
-                : "No story is found through the imports: the catalogue reads no component docs (componentDocs: false), whose programs read the import graph"
-        ];
-    const body = { schema: 1, since, files, stories, problems };
-    return { status: 200, body };
+    // read for each answer: the file an agent has just written ends the problem
+    const globs = emptyStoryGlobs(config);
+    const hidden = hiddenStoryFolders(config);
+    const said = [
+        ...(globs.length === 0 ? [] : [emptyStoryGlobsMessage(globs)]),
+        ...(hidden.length === 0 ? [] : [hiddenStoryFoldersMessage(hidden)])
+    ];
+    const listed = said.length === 0 ? tree : { ...tree, problems: [...said, ...tree.problems] };
+    const statuses = catalogueStatuses(config.lists.statuses);
+    return {
+        status: 200,
+        body: storiesWithStatus(storiesDocument(config.title, listed, pages, view, usage), listed, statuses)
+    };
 };
 /**
  * One story in detail, its component's "Used in" when offered.
@@ -201,28 +165,129 @@ export const storyAnswer = async (context) => {
     const files = sourceFiles(source);
     // 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 storyModule = await settled(files.stories[file]);
+    const docs = await settled(files.docs[file]);
     const parts = {
-        module: await settled(files.stories[file]),
-        docs: await settled(files.docs[file]),
-        preview: loaded.preview
+        module: storyModule,
+        docs,
+        preview: loaded.preview,
+        namedValues: source.namedValues,
+        setArgs: params.get("args") ?? undefined,
+        customControls: context.server === undefined
+            ? undefined
+            : await customControlsRead([...customControlNames(storyModule, location), ...typedControlNames(docs)], config, context.server),
+        addressTexts: config.framework.addressTexts
     };
+    const code = context.server === undefined
+        ? undefined
+        : {
+            code: await settled(files.code[file]),
+            writer: await codeWriterOf(config, context.server),
+            namedValues: source.namedValues,
+            coders: parts.customControls?.coders ?? {}
+        };
     const index = offersUsedIn(config.lists) ? await sourceUsage(source) : undefined;
     // a usage that cannot be read leaves "Used in" out, never the story
     const usage = index === undefined || typeof index === "string" ? undefined : { tree, index };
-    const document = storyDocument(location, parts, pages, view, usage);
+    const module = "value" in storyModule ? storyModule.value : undefined;
+    const document = storyWithStatus(withStoryCode(storyDocument(location, parts, pages, view, usage), code, {
+        location,
+        module,
+        preview: loaded.preview
+    }), location.component, catalogueStatuses(config.lists.statuses));
     // an agent must tell docs turned off from a story file that names no component
     const body = readsComponentDocs(config.lists)
         ? document
         : { ...document, componentDocs: "off" };
     return { status: 200, body };
 };
+/** Whether a module's `codeOf` is a code writer: a function, as every framework's code module exports it. */
+const isCodeWriter = (value) => typeof value === "function";
+/**
+ * The framework's code writer, loaded on the server as the shell imports it; none when it does not load there.
+ *
+ * @param config - the catalogue's configuration.
+ * @param server - what the answers ask of the dev server.
+ */
+const codeWriterOf = async (config, server) => {
+    try {
+        const id = await server.resolveSource(config.framework.pages.code);
+        // loading a module that does not resolve would only have Vite log its failure
+        const loaded = id === undefined ? undefined : await server.load(id);
+        const writer = typeof loaded === "object" && loaded !== null && "codeOf" in loaded ? loaded.codeOf : undefined;
+        return isCodeWriter(writer) ? writer : undefined;
+    }
+    catch {
+        // a writer that touches the page as it loads has no code to give an agent; the story's answer stands without it
+        return undefined;
+    }
+};
+/**
+ * The controls the catalogue gives a story's props by type or name, as its component's docs say: their modules load for
+ * the story's document too.
+ *
+ * @param docs - the docs, as the dev server loaded them.
+ */
+const typedControlNames = (docs) => "value" in docs && isComponentDocs(docs.value)
+    ? docs.value.props.flatMap((prop) => prop.customControl ?? [])
+    : [];
+/** How long a control's module may take to load for an answer: one that hangs must not hold every answer with it. */
+const CONTROL_LOAD_MS = 5000;
+/** A control's module as the server reads it: its schema and what writes its values as code; a text says why not. */
+const controlReadOf = async (module, server) => {
+    try {
+        const id = await server.resolveSource(module);
+        const timeout = new Promise((_resolve, reject) => {
+            setTimeout(() => reject(new Error(`no answer in ${CONTROL_LOAD_MS} ms`)), CONTROL_LOAD_MS).unref();
+        });
+        const loaded = await Promise.race([server.load(id ?? module), timeout]);
+        const isModule = typeof loaded === "object" && loaded !== null;
+        const schema = isModule && "schema" in loaded ? loaded.schema : undefined;
+        const toCode = isModule && "toCode" in loaded ? loaded.toCode : undefined;
+        if (!isValueSchema(schema))
+            return "its module exports no schema Forgebook can read";
+        return {
+            schema,
+            toCode: typeof toCode === "function"
+                ? (value, argType) => {
+                    const code = toCode(value, argType);
+                    return typeof code === "string" ? code : undefined;
+                }
+                : undefined
+        };
+    }
+    catch (error) {
+        return `its module cannot be read on the server: ${error instanceof Error ? error.message : String(error)}`;
+    }
+};
+/**
+ * The custom controls a story names, as an agent reads them: only those, each module loaded on the server for its schema.
+ * A module that cannot load there (it touches the page as it is imported) has no schema to say, and no value of it can be
+ * checked. Its import runs on the dev server, as a story file's does.
+ *
+ * @param names - the controls the story names.
+ * @param config - the catalogue's configuration.
+ * @param server - what the answers ask of the dev server.
+ */
+const customControlsRead = async (names, config, server) => {
+    const known = names.flatMap((name) => {
+        const control = Object.hasOwn(config.argControls, name) ? config.argControls[name] : undefined;
+        return control === undefined ? [] : [[name, control.module]];
+    });
+    const read = await Promise.all(known.map(async ([name, module]) => [name, await controlReadOf(module, server)]));
+    return {
+        schemas: Object.fromEntries(read.flatMap(([name, each]) => (typeof each === "string" ? [] : [[name, each.schema]]))),
+        coders: Object.fromEntries(read.flatMap(([name, each]) => (typeof each === "string" ? [] : [[name, each.toCode]]))),
+        problems: Object.fromEntries(read.flatMap(([name, each]) => (typeof each === "string" ? [[name, each]] : [])))
+    };
+};
 /**
  * Answers one of the API's paths.
  *
  * @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, `category`, `name`, `value` and `type` for the
+ * @param params - the query: `id` for a story, `view` for the links, `args` for the values to set, `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 origins - where the catalogue is served (`http://localhost:5173`) and where its frames are, for the links.
@@ -242,7 +307,8 @@ export const agentAnswer = async (server, config, route, params, origins, live)
             config,
             params,
             pages: { page: `${origins.catalogue}/`, frame: `${origins.frames}/frame.html` },
-            view: params.get("view") ?? ""
+            view: params.get("view") ?? "",
+            server
         };
         if (route === "errors")
             return errorsAnswer(context, live);
@@ -259,7 +325,10 @@ export const agentAnswer = async (server, config, route, params, origins, live)
         if (route === "page")
             return await pageAnswer(context);
         if (route === "changed")
-            return await changedAnswer(context);
+            return await changedAnswer(context, server.resolveSource);
+        // loaded when asked: it reads syntax with TypeScript, which a dev server's thread must not pay for at start
+        if (route === "visibility")
+            return await (await import("./visibilityRoute.js")).visibilityAnswer(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}` } };

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

@@ -0,0 +1,42 @@
+/**
+ * The statuses in the agents' answers: each story's and each component's (`statuses`), and in a story's answer where its
+ * component's TSDoc and its meta disagree about deprecation.
+ *
+ * @remarks
+ * A deprecated component has two places to say so: `@deprecated` in its TSDoc, which `check_code` reads to warn where
+ * it is imported, and a `deprecated` tag on its meta, which the sidebar, the page and the tag filter read without
+ * building its types. A story's answer reads both, so it gives the component as deprecated when either says it, and
+ * names the place that does not, so the two are made to agree instead of one being trusted over the other. Pure.
+ *
+ * @module
+ */
+import type { ComponentDocs } from "../componentDocs.ts";
+import { type CatalogueStatus } from "../storyStatuses.ts";
+import type { StoryTree, TreeComponent } from "../storyTree.ts";
+import type { StoriesDocument, StoryDocument } from "./agent.types.ts";
+/**
+ * The stories document with each component's and each story's statuses.
+ *
+ * @param document - the stories document.
+ * @param tree - the tree it was made from, whose components hold their meta's tags.
+ * @param statuses - the catalogue's statuses.
+ */
+export declare const storiesWithStatus: (document: StoriesDocument, tree: StoryTree, statuses: readonly CatalogueStatus[]) => StoriesDocument;
+/**
+ * What a component's TSDoc and its meta say of its deprecation, when they disagree: the sentence that names the place
+ * to change; none when they agree, when the catalogue has no `deprecated` status, or when there are no docs to read.
+ *
+ * @param title - the component's title.
+ * @param isTagged - whether its meta holds the `deprecated` tag.
+ * @param docs - its docs; none when they are not read.
+ */
+export declare const deprecationMismatch: (title: string, isTagged: boolean, docs: ComponentDocs | undefined) => string | undefined;
+/**
+ * A story's answer with its statuses and its component's, the component deprecated when its TSDoc says so, and the
+ * disagreement between the two among the problems.
+ *
+ * @param document - the story's answer.
+ * @param component - its component in the tree, which holds its meta's tags.
+ * @param statuses - the catalogue's statuses.
+ */
+export declare const storyWithStatus: (document: StoryDocument, component: TreeComponent, statuses: readonly CatalogueStatus[]) => StoryDocument;

package/dist/src/vite/agentStatuses.js

@@ -0,0 +1,67 @@
+import { DEPRECATED_STATUS, statusesOf } from "../storyStatuses.js";
+/** The ids of the statuses a list of tags holds. */
+const statusIds = (tags, statuses) => statusesOf(tags, statuses).map((status) => status.id);
+/** A value with its statuses, or as it is when it has none: an answer stays short for what has none. */
+const withStatus = (value, statuses) => statuses.length === 0 ? value : { ...value, statuses };
+/**
+ * The stories document with each component's and each story's statuses.
+ *
+ * @param document - the stories document.
+ * @param tree - the tree it was made from, whose components hold their meta's tags.
+ * @param statuses - the catalogue's statuses.
+ */
+export const storiesWithStatus = (document, tree, statuses) => {
+    if (statuses.length === 0)
+        return document;
+    const tagsById = new Map(tree.sources.flatMap((source) => source.families.flatMap((family) => family.groups.flatMap((group) => group.components.map((component) => [component.id, component.tags])))));
+    return {
+        ...document,
+        components: document.components.map((component) => ({
+            ...withStatus(component, statusIds(tagsById.get(component.id) ?? [], statuses)),
+            stories: component.stories.map((story) => withStatus(story, statusIds(story.tags, statuses)))
+        }))
+    };
+};
+/**
+ * What a component's TSDoc and its meta say of its deprecation, when they disagree: the sentence that names the place
+ * to change; none when they agree, when the catalogue has no `deprecated` status, or when there are no docs to read.
+ *
+ * @param title - the component's title.
+ * @param isTagged - whether its meta holds the `deprecated` tag.
+ * @param docs - its docs; none when they are not read.
+ */
+export const deprecationMismatch = (title, isTagged, docs) => {
+    if (docs === undefined)
+        return undefined;
+    const isDocumented = docs.guidance?.deprecated !== undefined;
+    if (isDocumented && !isTagged)
+        return `${title} is @deprecated in its TSDoc, but its meta has no "${DEPRECATED_STATUS}" tag: add tags: ["${DEPRECATED_STATUS}"] to its meta, so the sidebar, its page and the tag filter say so too`;
+    if (isTagged && !isDocumented)
+        return `${title}'s meta is tagged "${DEPRECATED_STATUS}", but its TSDoc has no @deprecated: add one (and @replacedBy when something replaces it), so check_code warns where it is imported`;
+    return undefined;
+};
+/**
+ * A story's answer with its statuses and its component's, the component deprecated when its TSDoc says so, and the
+ * disagreement between the two among the problems.
+ *
+ * @param document - the story's answer.
+ * @param component - its component in the tree, which holds its meta's tags.
+ * @param statuses - the catalogue's statuses.
+ */
+export const storyWithStatus = (document, component, statuses) => {
+    if (statuses.length === 0)
+        return document;
+    const own = statusIds(component.tags, statuses);
+    const hasDeprecated = statuses.some((status) => status.id === DEPRECATED_STATUS);
+    const mismatch = hasDeprecated
+        ? deprecationMismatch(component.title, own.includes(DEPRECATED_STATUS), document.docs)
+        : undefined;
+    const isDocumented = document.docs?.guidance?.deprecated !== undefined;
+    const status = hasDeprecated && isDocumented ? statusIds([...component.tags, DEPRECATED_STATUS], statuses) : own;
+    return {
+        ...document,
+        story: withStatus(document.story, statusIds(document.story.tags, statuses)),
+        component: withStatus(document.component, status),
+        problems: mismatch === undefined ? document.problems : [...document.problems, mismatch]
+    };
+};