forgebook 0.1.8 → 0.2.0

package/dist/src/usedIn.d.ts

@@ -22,6 +22,34 @@ export type UsingComponent = {
 };
 /** For each component of a group or a source, by title, the components that use it, direct ones first. */
 export type UsageIndex = Readonly<Record<string, readonly UsingComponent[]>>;
+/**
+ * A usage index as a module writes it: each title and each list of stories once, the pairs pointing at them. In a
+ * library whose components all reach one another through a barrel, the plain index names every story of every
+ * component once per component it uses: megabytes, on a dev server's thread and down to the page. Packed, it still
+ * grows with the pairs of a component and a user, which in such a library is the square of its components: three
+ * numbers a pair, where the plain index wrote every story's name.
+ */
+export type PackedUsage = {
+    /** The titles, each once. */
+    readonly titles: readonly string[];
+    /** The lists of stories, each once. */
+    readonly lists: readonly (readonly string[])[];
+    /** For each used component's title, its users: the user's title, whether directly (1) or not (0), its stories. */
+    readonly users: Readonly<Record<string, readonly (readonly [title: number, isDirect: number, list: number])[]>>;
+};
+/**
+ * A usage index written once per title and list.
+ *
+ * @param index - the index.
+ */
+export declare const packedUsage: (index: UsageIndex) => PackedUsage;
+/**
+ * A packed index as the page reads it; a list of stories repeated is one array, shared.
+ *
+ * @param packed - the packed index.
+ * @returns the index, or none when it is not one: an entry that is not three numbers, or points past its lists.
+ */
+export declare const unpackedUsage: (packed: PackedUsage) => UsageIndex | undefined;
 /** How many using components a page shows before "and N more". */
 export declare const USED_IN_SHOWN = 12;
 /**
@@ -57,4 +85,3 @@ export declare const sourceUsage: (source: StorySource) => Promise<UsageIndex |
  * @param source - the source.
  */
 export declare const usageLoader: (source: StorySource) => (() => Promise<UsageIndex | string>);
-//# sourceMappingURL=usedIn.d.ts.map

package/dist/src/usedIn.js

@@ -1,3 +1,93 @@
+/**
+ * A usage index written once per title and list.
+ *
+ * @param index - the index.
+ */
+export const packedUsage = (index) => {
+    const titles = [];
+    const lists = [];
+    const titleAt = new Map();
+    const listAt = new Map();
+    const at = (value, key, known, all) => {
+        const found = known.get(key);
+        if (found !== undefined)
+            return found;
+        known.set(key, all.length);
+        all.push(value);
+        return all.length - 1;
+    };
+    const users = Object.fromEntries(Object.entries(index).map(([title, using]) => [
+        title,
+        using.map((user) => [
+            at(user.title, user.title, titleAt, titles),
+            user.isDirect ? 1 : 0,
+            at(user.stories, user.stories.join("\n"), listAt, lists)
+        ])
+    ]));
+    return { titles, lists, users };
+};
+/**
+ * Whether a module's answer is a packed usage index.
+ *
+ * @param value - what the module exports by default.
+ */
+const isPackedUsage = (value) => typeof value === "object" &&
+    value !== null &&
+    "titles" in value &&
+    Array.isArray(value.titles) &&
+    "lists" in value &&
+    Array.isArray(value.lists) &&
+    "users" in value &&
+    typeof value.users === "object" &&
+    value.users !== null &&
+    // a plain index has a list under every title, so one with components named like these fields is told apart
+    !Array.isArray(value.users);
+/**
+ * Whether a value is a packed user: three whole numbers.
+ *
+ * @param value - an entry of a packed index's users.
+ */
+const isPackedUser = (value) => Array.isArray(value) && value.length === 3 && value.every((each) => Number.isInteger(each));
+/**
+ * A packed index as the page reads it; a list of stories repeated is one array, shared.
+ *
+ * @param packed - the packed index.
+ * @returns the index, or none when it is not one: an entry that is not three numbers, or points past its lists.
+ */
+export const unpackedUsage = (packed) => {
+    // a module's answer is read from outside the type system: every part is checked before it is used
+    const users = packed.users;
+    // each list checked once: a library's pairs share a few lists
+    const lists = packed.lists.map((list) => (isStrings(list) ? list : undefined));
+    const index = {};
+    for (const [title, entries] of Object.entries(users)) {
+        if (!Array.isArray(entries))
+            return undefined;
+        const using = [];
+        for (const entry of entries) {
+            if (!isPackedUser(entry))
+                return undefined;
+            const [user, isDirect, list] = entry;
+            const userTitle = packed.titles[user];
+            const stories = lists[list];
+            if (typeof userTitle !== "string" || stories === undefined)
+                return undefined;
+            using.push({ title: userTitle, isDirect: isDirect === 1, stories });
+        }
+        index[title] = using;
+    }
+    return index;
+};
+/**
+ * A module's answer as an index: packed, as the plugin writes it, or plain.
+ *
+ * @param answer - what the module exports by default.
+ */
+const readUsage = (answer) => {
+    if (isPackedUsage(answer))
+        return unpackedUsage(answer);
+    return isUsageIndex(answer) ? answer : undefined;
+};
 /** How many using components a page shows before "and N more". */
 export const USED_IN_SHOWN = 12;
 /**
@@ -64,9 +154,10 @@ export const sourceUsage = async (source) => {
             "error" in answer &&
             typeof answer.error === "string")
             return answer.error;
-        if (!isUsageIndex(answer))
+        const index = readUsage(answer);
+        if (index === undefined)
             return "A usage module answered something that is not a usage index";
-        indexes.push(answer);
+        indexes.push(index);
     }
     return mergedUsage(indexes);
 };
@@ -89,4 +180,3 @@ export const usageLoader = (source) => {
     LOADERS.set(source, load);
     return load;
 };
-//# sourceMappingURL=usedIn.js.map

package/dist/src/viewState.d.ts

@@ -6,12 +6,15 @@
  * Only values that differ from the defaults are written; an unknown or invalid value reads as the default. The view
  * holds a value for each switch the catalogue declares (`switches.ts`: the theme, the contrast, the language, the
  * library's own), which the frame applies on its root or hands the story; and Forgebook's own settings: the style
- * sheets, the root font size and the backdrop Forgebook draws behind the story. The stage's width, height, zoom and tools and the panel (open, its tab) are the shell's alone: a frame's address leaves them
- * out. Pure.
+ * sheets, the root font size and the backdrop Forgebook draws behind the story. The stage's width, height, zoom, tools and
+ * device frame, the panel (open, its tab) and who a component's page is read by are the shell's alone: a frame's
+ * address leaves them out. Pure.
  *
  * @module
  */
-import type { CatalogueSettings, PanelTabId } from "./catalogue.ts";
+import { type AudienceId } from "./audiences.ts";
+import type { CatalogueSettings } from "./catalogue.ts";
+import { type DeviceChoice, type OrientationChoice } from "./deviceView.ts";
 import { type TouchChoice, type ViewSwitch } from "./switches.ts";
 /**
  * What Forgebook draws behind the story, in place of its page's colour: `plain`, the page's colour itself,
@@ -37,12 +40,12 @@ export type MeasureTool = "outline" | "grid" | "measure";
 /** The story's zoom on the stage, in percent: it scales the drawing, never the layout. */
 export type Zoom = number;
 /** A tab of the panel under a story. */
-export type PanelTab = PanelTabId;
+export type PanelTab = string;
 /** The story's width on the stage: the stage's whole width, or a width in CSS px (a preset, or dragged). */
 export type StageWidth = "fill" | number;
 /**
  * The story's height on the stage: its own (`auto`: the story's content, at least the height it declares) or a
- * height in CSS px dragged with the handle at its foot (note 142).
+ * height in CSS px dragged with the handle at its foot.
  */
 export type StageHeight = "auto" | number;
 /** Every switch of the toolbar. */
@@ -69,6 +72,12 @@ export type ViewState = {
     readonly zoom: Zoom;
     /** The tools drawn over the story, in `MEASURE_TOOLS`' order. */
     readonly tools: readonly MeasureTool[];
+    /** Who a component's page is read by. */
+    readonly audience: AudienceId;
+    /** The device frame around the story: the story's own default (`auto`), none, or a model. */
+    readonly device: DeviceChoice;
+    /** How the device is held: the story's own default (`auto`), or one way. */
+    readonly orientation: OrientationChoice;
 };
 /** The part of the view a frame applies on its root without loading again, so the story keeps its state. */
 export type LiveView = Pick<ViewState, "switches" | "backdrop" | "text">;
@@ -85,7 +94,7 @@ export declare const isComparing: (view: ViewState) => boolean;
 /** Every tool, in the bar's order. */
 export declare const MEASURE_TOOLS: readonly MeasureTool[];
 /** What the view reads of a catalogue: its switches and the lists its values are checked against. */
-export type ViewCatalogue = Pick<CatalogueSettings, "switches" | "widthRange" | "zooms" | "textSizes" | "backdrops" | "tabs" | "ownControls">;
+export type ViewCatalogue = Pick<CatalogueSettings, "switches" | "widthRange" | "zooms" | "textSizes" | "backdrops" | "tabs" | "ownControls" | "audience">;
 /**
  * A width kept in a catalogue's range, in whole pixels.
  *
@@ -122,9 +131,11 @@ export declare const defaultView: (catalogue: ViewCatalogue) => ViewState;
  *
  * @param view - the view.
  * @param switches - the catalogue's switches.
+ * @param defaultAudience - the audience the catalogue starts with: `everyone` must be written in a catalogue that starts
+ * with another, or the link would open that one.
  * @returns the parameters, in a stable order.
  */
-export declare const viewParams: (view: ViewState, switches: readonly ViewSwitch[]) => URLSearchParams;
+export declare const viewParams: (view: ViewState, switches: readonly ViewSwitch[], defaultAudience?: AudienceId) => URLSearchParams;
 /**
  * Whether one of the given controls' values is changed (a switch, the background, the style sheets, the text size;
  * the stage's width is not a view setting): the View menu's button shows a dot for the controls it holds, so a view
@@ -133,8 +144,9 @@ export declare const viewParams: (view: ViewState, switches: readonly ViewSwitch
  * @param view - the view.
  * @param switches - the catalogue's switches.
  * @param ids - the controls' ids.
+ * @param defaultAudience - the audience the catalogue starts with.
  */
-export declare const hasViewChanges: (view: ViewState, switches: readonly ViewSwitch[], ids: readonly string[]) => boolean;
+export declare const hasViewChanges: (view: ViewState, switches: readonly ViewSwitch[], ids: readonly string[], defaultAudience?: AudienceId) => boolean;
 /**
  * The address of a story's frame.
  *
@@ -221,4 +233,20 @@ export declare const frameAddressOf: (frameUrl: string, id: string, search: stri
  * @param search - the view's query (`theme=dark&lang=it`), with or without `?`.
  */
 export declare const storyAddressOf: (pageUrl: string, id: string, search: string) => string;
-//# sourceMappingURL=viewState.d.ts.map
+/**
+ * The address of a component's page in the catalogue from a catalogue's address query: for a tool that does not know
+ * the catalogue's switches, the view kept as written, an audience's among it.
+ *
+ * @param pageUrl - the catalogue's page.
+ * @param id - the component's id.
+ * @param search - the view's query; empty for the default view.
+ */
+export declare const componentAddressOf: (pageUrl: string, id: string, search: string) => string;
+/**
+ * A docs page's address in the catalogue, in a view.
+ *
+ * @param pageUrl - the catalogue's page.
+ * @param id - the page's id.
+ * @param search - the view's query; empty for the default view.
+ */
+export declare const docPageAddressOf: (pageUrl: string, id: string, search: string) => string;

package/dist/src/viewState.js

@@ -6,11 +6,14 @@
  * Only values that differ from the defaults are written; an unknown or invalid value reads as the default. The view
  * holds a value for each switch the catalogue declares (`switches.ts`: the theme, the contrast, the language, the
  * library's own), which the frame applies on its root or hands the story; and Forgebook's own settings: the style
- * sheets, the root font size and the backdrop Forgebook draws behind the story. The stage's width, height, zoom and tools and the panel (open, its tab) are the shell's alone: a frame's address leaves them
- * out. Pure.
+ * sheets, the root font size and the backdrop Forgebook draws behind the story. The stage's width, height, zoom, tools and
+ * device frame, the panel (open, its tab) and who a component's page is read by are the shell's alone: a frame's
+ * address leaves them out. Pure.
  *
  * @module
  */
+import { AUDIENCE_IDS, DEFAULT_AUDIENCE } from "./audiences.js";
+import { DEVICE_PARAMETER, isDeviceId, isDeviceOrientation, ORIENTATION_PARAMETER } from "./deviceView.js";
 import { switchValueOf, switchWithRole } from "./switches.js";
 /** The page's own colour: no backdrop drawn. */
 export const PLAIN_BACKDROP = "plain";
@@ -28,7 +31,10 @@ export const DEFAULT_VIEW = {
     isPanelOpen: true,
     panelTab: "props",
     zoom: 100,
-    tools: []
+    tools: [],
+    audience: DEFAULT_AUDIENCE,
+    device: "auto",
+    orientation: "auto"
 };
 /** Every style sheet setting, in the menu's order. */
 export const SHEETS_CHOICES = ["full", "structure", "restyled"];
@@ -70,6 +76,10 @@ const stageHeight = (value) => {
     const height = Number(value);
     return value !== null && Number.isInteger(height) && clampedHeight(height) === height ? height : "auto";
 };
+/** The device a parameter names: `off` or a model's id, otherwise the story's own. */
+const deviceChoice = (value) => value === "off" || isDeviceId(value) ? value : "auto";
+/** The orientation a parameter names, otherwise the story's own. */
+const orientationChoice = (value) => isDeviceOrientation(value) ? value : "auto";
 /** The value of a parameter when it is one of the choices, otherwise the default. */
 const choice = (value, choices, fallback) => choices.find((option) => String(option) === value) ?? fallback;
 /**
@@ -129,7 +139,10 @@ export const parseView = (search, catalogue) => {
         isPanelOpen: params.get("panel") !== "closed",
         panelTab: choice(params.get("tab"), catalogue.tabs, catalogue.tabs[0] ?? DEFAULT_VIEW.panelTab),
         zoom: choice(params.get("zoom"), catalogue.zooms, DEFAULT_VIEW.zoom),
-        tools: toolsOf(params.get("tools"))
+        tools: toolsOf(params.get("tools")),
+        audience: choice(shown("audience"), AUDIENCE_IDS, catalogue.audience),
+        device: deviceChoice(params.get(DEVICE_PARAMETER)),
+        orientation: orientationChoice(params.get(ORIENTATION_PARAMETER))
     };
 };
 /**
@@ -174,9 +187,11 @@ const frameParams = (view, switches) => {
  *
  * @param view - the view.
  * @param switches - the catalogue's switches.
+ * @param defaultAudience - the audience the catalogue starts with: `everyone` must be written in a catalogue that starts
+ * with another, or the link would open that one.
  * @returns the parameters, in a stable order.
  */
-export const viewParams = (view, switches) => {
+export const viewParams = (view, switches, defaultAudience = DEFAULT_AUDIENCE) => {
     const params = frameParams(view, switches);
     if (isComparing(view))
         params.set("compare", view.compare.join(","));
@@ -192,6 +207,12 @@ export const viewParams = (view, switches) => {
         params.set("zoom", String(view.zoom));
     if (view.tools.length > 0)
         params.set("tools", view.tools.join(","));
+    if (view.audience !== defaultAudience)
+        params.set("audience", view.audience);
+    if (view.device !== DEFAULT_VIEW.device)
+        params.set(DEVICE_PARAMETER, view.device);
+    if (view.orientation !== DEFAULT_VIEW.orientation)
+        params.set(ORIENTATION_PARAMETER, view.orientation);
     return params;
 };
 /**
@@ -202,11 +223,15 @@ export const viewParams = (view, switches) => {
  * @param view - the view.
  * @param switches - the catalogue's switches.
  * @param ids - the controls' ids.
+ * @param defaultAudience - the audience the catalogue starts with.
  */
-export const hasViewChanges = (view, switches, ids) => switches.some((each) => ids.includes(each.id) && !isDefault(view, each)) ||
+export const hasViewChanges = (view, switches, ids, defaultAudience = DEFAULT_AUDIENCE) => switches.some((each) => ids.includes(each.id) && !isDefault(view, each)) ||
     (ids.includes("backdrop") && view.backdrop !== DEFAULT_VIEW.backdrop) ||
     (ids.includes("sheets") && view.sheets !== DEFAULT_VIEW.sheets) ||
-    (ids.includes("text") && view.text !== DEFAULT_VIEW.text);
+    (ids.includes("text") && view.text !== DEFAULT_VIEW.text) ||
+    (ids.includes("audience") && view.audience !== defaultAudience) ||
+    (ids.includes(DEVICE_PARAMETER) &&
+        (view.device !== DEFAULT_VIEW.device || view.orientation !== DEFAULT_VIEW.orientation));
 /**
  * The address of a story's frame.
  *
@@ -315,9 +340,13 @@ const SHELL_PARAMETERS = [
     "tab",
     "zoom",
     "tools",
+    DEVICE_PARAMETER,
+    ORIENTATION_PARAMETER,
     "args",
     "matrix",
-    "component"
+    "component",
+    "embed",
+    "audience"
 ];
 /**
  * The address of a story's frame from a catalogue's address query, for a tool that does not know the catalogue's
@@ -346,8 +375,37 @@ export const frameAddressOf = (frameUrl, id, search) => {
 export const storyAddressOf = (pageUrl, id, search) => {
     const params = new URLSearchParams(search);
     params.delete("component");
+    params.delete("page");
     params.delete("story");
     params.set("story", id);
     return `${pageUrl}?${params.toString()}`;
 };
-//# sourceMappingURL=viewState.js.map
+/**
+ * The address of a component's page in the catalogue from a catalogue's address query: for a tool that does not know
+ * the catalogue's switches, the view kept as written, an audience's among it.
+ *
+ * @param pageUrl - the catalogue's page.
+ * @param id - the component's id.
+ * @param search - the view's query; empty for the default view.
+ */
+export const componentAddressOf = (pageUrl, id, search) => {
+    const params = new URLSearchParams(search);
+    params.delete("story");
+    params.delete("page");
+    params.set("component", id);
+    return `${pageUrl}?${params.toString()}`;
+};
+/**
+ * A docs page's address in the catalogue, in a view.
+ *
+ * @param pageUrl - the catalogue's page.
+ * @param id - the page's id.
+ * @param search - the view's query; empty for the default view.
+ */
+export const docPageAddressOf = (pageUrl, id, search) => {
+    const params = new URLSearchParams(search);
+    params.delete("component");
+    params.delete("story");
+    params.set("page", id);
+    return `${pageUrl}?${params.toString()}`;
+};

package/dist/src/viewWords.d.ts

@@ -1,15 +1,3 @@
-/**
- * A view written the short way, as words (`dark it 360`), turned into the address's form (`theme=dark&lang=it&width=360`),
- * for `forgebook check`, `forgebook shot` and their MCP tools.
- *
- * @remarks
- * A word is a value of exactly one of the catalogue's switches, or a number, the story's width. The words are
- * separated by spaces or `+` (a comma would split the option into several views). A view that already holds `=` is the
- * address's form and is kept as it is. A word no switch has, or one two switches share, is refused with what to write
- * instead. Pure.
- *
- * @module
- */
 import type { ViewSwitch } from "./switches.ts";
 /**
  * A view in the address's form.
@@ -23,4 +11,3 @@ export declare const viewQuery: (text: string, switches: readonly ViewSwitch[])
 } | {
     readonly error: string;
 };
-//# sourceMappingURL=viewWords.d.ts.map

package/dist/src/viewWords.js

@@ -1,3 +1,33 @@
+/**
+ * A view written the short way, as words (`dark it 360`), turned into the address's form (`theme=dark&lang=it&width=360`),
+ * for `forgebook check`, `forgebook shot` and their MCP tools.
+ *
+ * @remarks
+ * A word is a value of exactly one of the catalogue's switches, a number (the story's width), a device model's id
+ * (`iphone-16`: the story in that device's frame) or `portrait` and `landscape` (how it is held). The words are
+ * separated by spaces or `+` (a comma would split the option into several views). A view that already holds `=` is the
+ * address's form and is kept as it is. A word no switch has, or one two switches share, is refused with what to write
+ * instead. Pure.
+ *
+ * @module
+ */
+import { DEVICE_PARAMETER, isDeviceId, isDeviceOrientation, ORIENTATION_PARAMETER } from "./deviceView.js";
+/**
+ * Why a view's words cannot hold together, or none: how a device is held means nothing without a device, and a
+ * device sets the width itself.
+ *
+ * @param parts - the view's parameters, as words made them.
+ */
+const deviceWordsProblem = (parts) => {
+    const hasDevice = parts.some((part) => part.startsWith(`${DEVICE_PARAMETER}=`));
+    if (!hasDevice && parts.some((part) => part.startsWith(`${ORIENTATION_PARAMETER}=`)))
+        return {
+            error: "portrait and landscape need a device: write a model's id beside them (iphone-16 landscape)"
+        };
+    if (hasDevice && parts.some((part) => part.startsWith("width=")))
+        return { error: "a device sets the width itself: write the model's id or a width, not both" };
+    return undefined;
+};
 /**
  * A view in the address's form.
  *
@@ -16,14 +46,22 @@ export const viewQuery = (text, switches) => {
         }
         const owners = switches.filter((each) => each.values.some((value) => value.value === word));
         const [owner] = owners;
+        // a switch's own value wins: a device's words are Forgebook's, a catalogue's switch may use one
+        if (owner === undefined && isDeviceId(word)) {
+            parts.push(`${DEVICE_PARAMETER}=${word}`);
+            continue;
+        }
+        if (owner === undefined && isDeviceOrientation(word)) {
+            parts.push(`${ORIENTATION_PARAMETER}=${word}`);
+            continue;
+        }
         if (owner === undefined)
-            return { error: `No switch has the value "${word}"` };
+            return { error: `No switch has the value "${word}", and no device is named so` };
         if (owners.length > 1)
             return {
                 error: `"${word}" is a value of ${owners.map((each) => each.id).join(" and ")}: write ${owner.id}=${word}`
             };
         parts.push(`${owner.id}=${word}`);
     }
-    return { query: parts.join("&") };
+    return deviceWordsProblem(parts) ?? { query: parts.join("&") };
 };
-//# sourceMappingURL=viewWords.js.map

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

@@ -11,6 +11,7 @@
  * @module
  */
 import type { PluginOption } from "vite";
+import type { AddressTexts } from "../addressTexts.ts";
 import type { ComponentDocs, NoComponentDocs } from "../componentDocs.ts";
 /** A story file's component: its docs and the file that declares it. */
 export type StoryComponent = {
@@ -58,6 +59,42 @@ export type FrameworkAdapter = {
     readonly browserDependencies?: readonly string[];
     /** The Vite plugins the framework needs in a catalogue (React's Fast Refresh); none by default. */
     readonly vitePlugins?: () => Promise<readonly PluginOption[]>;
+    /** The framework's own kind of component file, for a framework whose components are not all TypeScript; none by default. */
+    readonly componentFiles?: ComponentFiles;
+    /**
+     * How its stories take the texts a catalogue's address carries (`addressTexts.ts`): `plain` for a framework whose
+     * stories may write a text into markup (an HTML string), so a shared link's texts reach a story only when they are
+     * plain words. `any` by default, where a text stays text.
+     */
+    readonly addressTexts?: AddressTexts;
+    /**
+     * Whether an edited story file is drawn anew in its open frames, which keep what the reader did in the story
+     * (`hotModules.ts`); `true` by default. `false` for a framework whose compiler makes a story file anew from its own
+     * program and leaves out the code Vite's plugins add to it (Angular's): an edit of its story files reloads the pages.
+     */
+    readonly redrawsEditedStories?: boolean;
+};
+/**
+ * A framework's own kind of component file (Vue's `.vue`): what the plugin must know of a file that is not TypeScript,
+ * so an edit to one renews the docs and a page finds the comment that opens its script.
+ */
+export type ComponentFiles = {
+    /** The files' extension, with its dot (`.vue`). */
+    readonly extension: string;
+    /**
+     * The script a file holds, as TypeScript reads it.
+     *
+     * @param text - the file's text.
+     * @returns the script's text; empty when it has none.
+     */
+    readonly scriptOf: (text: string) => string;
+};
+/** Where `forgebook new` writes a component's stories, and how they import it. */
+export type StoryFileShape = {
+    /** The stories file's extension (`.stories.ts`). */
+    readonly extension: string;
+    /** The statement that imports the component (`import Badge from "./Badge.vue";`). */
+    readonly importStatement: string;
 };
 /** Reads the component a file exports (`forgebook new`): the export named, or the file's only component. */
 export type ExtractFileComponent = (file: string, exportName?: string) => StoryComponentResult;
@@ -69,6 +106,18 @@ export type DocsModule = {
     readonly extractFileComponent?: ExtractFileComponent;
     /** The module a story file imports its types from (`@forgebook/react`); none when not given. */
     readonly storyTypesModule?: string;
+    /**
+     * How a component's stories file is written: a `.stories.tsx` importing the named export, without one.
+     *
+     * @param name - the component's name.
+     * @param file - the component's file, absolute.
+     */
+    readonly storyFileShape?: (name: string, file: string) => StoryFileShape;
+    /**
+     * Called in the docs' worker when a source file changed, for a framework that keeps a program of its own: the core's
+     * programs (`docsProgram.ts`) renew themselves. None by default.
+     */
+    readonly sourcesChanged?: () => void;
 };
 /**
  * Whether a module is a framework's docs module.
@@ -76,4 +125,16 @@ export type DocsModule = {
  * @param module - the module, as `import()` gave it.
  */
 export declare const isDocsModule: (module: unknown) => module is DocsModule;
-//# sourceMappingURL=adapter.d.ts.map
+/**
+ * The files under a folder, as a pattern a Vite plugin's `include` or `exclude` takes: Vite names a module by its path
+ * with forward slashes.
+ *
+ * @param folder - the folder's absolute path.
+ */
+export declare const filesUnder: (folder: string) => RegExp;
+/**
+ * The core's own files: its shell is React, so a framework's plugin that compiles JSX its own way (Solid's compiler,
+ * Preact's refresh) leaves them to Vite. They matter when the core is linked as sources (a workspace); installed, they
+ * are JavaScript already, which such plugins do not read.
+ */
+export declare const FORGEBOOK_FILES: RegExp;

package/dist/src/vite/adapter.js

@@ -10,6 +10,7 @@
  *
  * @module
  */
+import { join } from "node:path";
 /**
  * Whether a module is a framework's docs module.
  *
@@ -20,5 +21,22 @@ export const isDocsModule = (module) => typeof module === "object" &&
     "extractStoryComponent" in module &&
     typeof module.extractStoryComponent === "function" &&
     (!("extractFileComponent" in module) || typeof module.extractFileComponent === "function") &&
-    (!("storyTypesModule" in module) || typeof module.storyTypesModule === "string");
-//# sourceMappingURL=adapter.js.map
+    (!("storyTypesModule" in module) || typeof module.storyTypesModule === "string") &&
+    (!("storyFileShape" in module) || typeof module.storyFileShape === "function") &&
+    (!("sourcesChanged" in module) || typeof module.sourcesChanged === "function");
+/**
+ * The files under a folder, as a pattern a Vite plugin's `include` or `exclude` takes: Vite names a module by its path
+ * with forward slashes.
+ *
+ * @param folder - the folder's absolute path.
+ */
+export const filesUnder = (folder) => {
+    const path = folder.split("\\").join("/").replace(/\/$/, "");
+    return new RegExp(`^${path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`);
+};
+/**
+ * The core's own files: its shell is React, so a framework's plugin that compiles JSX its own way (Solid's compiler,
+ * Preact's refresh) leaves them to Vite. They matter when the core is linked as sources (a workspace); installed, they
+ * are JavaScript already, which such plugins do not read.
+ */
+export const FORGEBOOK_FILES = filesUnder(join(import.meta.dirname, "..", ".."));