forgebook 0.1.8 → 0.3.0

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

@@ -0,0 +1,89 @@
+/**
+ * The `frames` option of a catalogue's configuration: where its stories' frames run, checked and resolved, and the
+ * placement the pages read from it on the dev server and in a build.
+ *
+ * @remarks
+ * The frames get an origin of their own by default: on the dev server a second port, so a story's code cannot reach
+ * the catalogue's page, the agent API or the project's files. A static build has one host unless the configuration
+ * names two (`origins`), so it keeps the catalogue's origin otherwise. `"same-origin"` runs them on the catalogue's
+ * origin everywhere, for a place that gives one port only (a container with one port open).
+ *
+ * @module
+ */
+import { type FramesPlacement, type PageOrigins } from "../frameOrigins.ts";
+/** Where the stories' frames run, as `forgebook.config.ts` writes it. */
+export type FramesOption = "same-origin" | {
+    /**
+     * The dev server's port for the frames: the catalogue's port + 1 by default, the next free one when that is
+     * taken. A port given here must be free.
+     */
+    readonly port?: number;
+    /**
+     * The catalogue's origin and the frames', as the browser reaches them, when the frames' is not the catalogue's
+     * host on the frames' port: a static build served from two hosts (`https://frames.example.com`, a subdomain of
+     * the catalogue's site), or a dev server behind a proxy that gives each port a host of its own.
+     */
+    readonly origins?: {
+        readonly catalogue: string;
+        readonly frames: string;
+    };
+    /**
+     * Paths the frames' port serves as the catalogue's does, for an API a Vite plugin answers (`["/api/"]`): the
+     * frames' port serves only the frame page, the public folder, the modules the stories import and Vite's proxy.
+     */
+    readonly paths?: readonly string[];
+};
+/** The `frames` option, resolved. */
+export type ResolvedFrames = {
+    /** On the catalogue's origin. */
+    readonly kind: "same-origin";
+} | {
+    /** On an origin of their own. */
+    readonly kind: "isolated";
+    /** The dev server's port for the frames, when the configuration gives one. */
+    readonly port: number | undefined;
+    /** The two origins as the browser reaches them, when the configuration names them. */
+    readonly origins: PageOrigins | undefined;
+    /** The paths the frames' port serves as the catalogue's does. */
+    readonly paths: readonly string[];
+};
+/** The default: an origin of their own, on the next port. */
+export declare const ISOLATED_FRAMES: ResolvedFrames;
+/**
+ * Why a `frames` option cannot be used, or none.
+ *
+ * @param value - the option, as the configuration gives it.
+ */
+export declare const framesProblem: (value: unknown) => string | undefined;
+/**
+ * The `frames` option, resolved: the origins normalised as a browser writes them.
+ *
+ * @param option - the option, checked by `framesProblem`.
+ */
+export declare const resolvedFrames: (option: FramesOption | undefined) => ResolvedFrames;
+/**
+ * Where a build's frames run: on the origins the configuration names, or on the catalogue's, the only host a build
+ * can count on.
+ *
+ * @param frames - the resolved option.
+ */
+export declare const builtPlacement: (frames: ResolvedFrames) => FramesPlacement;
+/**
+ * Where the dev server's frames run, once both ports listen: on the origins the configuration names, or on the
+ * catalogue's host at the frames' port.
+ *
+ * @param frames - the resolved option.
+ * @param ports - the catalogue's port and the frames'.
+ */
+export declare const servedPlacement: (frames: ResolvedFrames, ports: {
+    readonly catalogue: number;
+    readonly frames: number;
+}) => FramesPlacement;
+/**
+ * The frames' origin for a catalogue reached at an address, for a line printed or an answer's link; none when they
+ * share the catalogue's.
+ *
+ * @param placement - where the frames run.
+ * @param catalogueUrl - the catalogue's address as it was reached (`http://localhost:5173/`); none when unknown.
+ */
+export declare const framesOriginOf: (placement: FramesPlacement, catalogueUrl: string | undefined) => string | undefined;

package/dist/src/vite/framesConfig.js

@@ -0,0 +1,149 @@
+/**
+ * The `frames` option of a catalogue's configuration: where its stories' frames run, checked and resolved, and the
+ * placement the pages read from it on the dev server and in a build.
+ *
+ * @remarks
+ * The frames get an origin of their own by default: on the dev server a second port, so a story's code cannot reach
+ * the catalogue's page, the agent API or the project's files. A static build has one host unless the configuration
+ * names two (`origins`), so it keeps the catalogue's origin otherwise. `"same-origin"` runs them on the catalogue's
+ * origin everywhere, for a place that gives one port only (a container with one port open).
+ *
+ * @module
+ */
+import { pageOrigins, SAME_ORIGIN } from "../frameOrigins.js";
+/** The default: an origin of their own, on the next port. */
+export const ISOLATED_FRAMES = {
+    kind: "isolated",
+    port: undefined,
+    origins: undefined,
+    paths: []
+};
+/**
+ * The origin a value names, when it is one: `http:` or `https:`, a host and maybe a port, nothing after but a slash.
+ *
+ * @param value - the value.
+ */
+const originOf = (value) => {
+    if (typeof value !== "string")
+        return undefined;
+    try {
+        const url = new URL(value);
+        const isBare = url.pathname === "/" && url.search === "" && url.hash === "" && url.username === "";
+        return (url.protocol === "http:" || url.protocol === "https:") && isBare ? url.origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Why a `frames.port` cannot be used, or none.
+ *
+ * @param port - the port, as the configuration gives it; none when it gives none.
+ */
+const portProblem = (port) => port === undefined || (typeof port === "number" && Number.isInteger(port) && port >= 1 && port <= 65535)
+    ? undefined
+    : "`frames.port` is a port number (1 to 65535)";
+/**
+ * Why `frames.origins` cannot be used, or none.
+ *
+ * @param origins - the origins, as the configuration gives them; none when it gives none.
+ */
+const originsProblem = (origins) => {
+    if (origins === undefined)
+        return undefined;
+    if (typeof origins !== "object" || origins === null || !("catalogue" in origins) || !("frames" in origins))
+        return "`frames.origins` names both origins: `{ catalogue, frames }`";
+    const catalogue = originOf(origins.catalogue);
+    const frames = originOf(origins.frames);
+    if (catalogue === undefined || frames === undefined)
+        return "`frames.origins` are origins: a scheme, a host and a port (`https://frames.example.com`)";
+    return catalogue === frames ? "`frames.origins` are two different origins" : undefined;
+};
+/**
+ * Why `frames.paths` cannot be used, or none.
+ *
+ * @param paths - the paths, as the configuration gives them; none when it gives none.
+ */
+const pathsProblem = (paths) => {
+    if (paths === undefined)
+        return undefined;
+    const isPath = (path) => typeof path === "string" &&
+        path.startsWith("/") &&
+        path !== "/" &&
+        !path.startsWith("/__") &&
+        !path.startsWith("/@");
+    return Array.isArray(paths) && paths.every(isPath)
+        ? undefined
+        : "`frames.paths` are paths of the server under the root (`/api/`), not Vite's or Forgebook's own (`/@…`, `/__…`)";
+};
+/**
+ * Why a `frames` option cannot be used, or none.
+ *
+ * @param value - the option, as the configuration gives it.
+ */
+export const framesProblem = (value) => {
+    if (value === undefined || value === "same-origin")
+        return undefined;
+    if (typeof value !== "object" || value === null)
+        return '`frames` is "same-origin" or `{ port, origins }`';
+    return (portProblem("port" in value ? value.port : undefined) ??
+        originsProblem("origins" in value ? value.origins : undefined) ??
+        pathsProblem("paths" in value ? value.paths : undefined));
+};
+/**
+ * The `frames` option, resolved: the origins normalised as a browser writes them.
+ *
+ * @param option - the option, checked by `framesProblem`.
+ */
+export const resolvedFrames = (option) => {
+    if (option === "same-origin")
+        return { kind: "same-origin" };
+    if (option === undefined)
+        return ISOLATED_FRAMES;
+    const catalogue = originOf(option.origins?.catalogue);
+    const frames = originOf(option.origins?.frames);
+    return {
+        kind: "isolated",
+        port: option.port,
+        origins: catalogue === undefined || frames === undefined ? undefined : { catalogue, frames },
+        paths: option.paths ?? []
+    };
+};
+/**
+ * Where a build's frames run: on the origins the configuration names, or on the catalogue's, the only host a build
+ * can count on.
+ *
+ * @param frames - the resolved option.
+ */
+export const builtPlacement = (frames) => frames.kind === "isolated" && frames.origins !== undefined
+    ? { kind: "origins", ...frames.origins }
+    : SAME_ORIGIN;
+/**
+ * Where the dev server's frames run, once both ports listen: on the origins the configuration names, or on the
+ * catalogue's host at the frames' port.
+ *
+ * @param frames - the resolved option.
+ * @param ports - the catalogue's port and the frames'.
+ */
+export const servedPlacement = (frames, ports) => {
+    if (frames.kind === "same-origin")
+        return SAME_ORIGIN;
+    return frames.origins === undefined ? { kind: "ports", ...ports } : { kind: "origins", ...frames.origins };
+};
+/**
+ * The frames' origin for a catalogue reached at an address, for a line printed or an answer's link; none when they
+ * share the catalogue's.
+ *
+ * @param placement - where the frames run.
+ * @param catalogueUrl - the catalogue's address as it was reached (`http://localhost:5173/`); none when unknown.
+ */
+export const framesOriginOf = (placement, catalogueUrl) => {
+    if (placement.kind === "same-origin" || catalogueUrl === undefined)
+        return undefined;
+    try {
+        return pageOrigins(placement, new URL(catalogueUrl), "catalogue").frames;
+    }
+    catch {
+        return undefined;
+    }
+};

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

@@ -0,0 +1,43 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { ViteDevServer } from "vite";
+import { type FramesPlacement } from "../frameOrigins.ts";
+import type { ResolvedConfig } from "./configFile.ts";
+import type { ResolvedFrames } from "./framesConfig.ts";
+/** A Connect middleware. */
+type Middleware = (request: IncomingMessage, response: ServerResponse, next: (error?: unknown) => void) => void;
+/** The frames' side of a dev server. */
+export type FramesServing = {
+    /** The catalogue origin's guard: installed before every other middleware. */
+    readonly catalogueGuard: Middleware;
+    /** Opens the frames' port once the catalogue's listens; where the frames run then. */
+    readonly start: () => Promise<FramesPlacement>;
+    /** Where the frames run, once `start` is over. */
+    readonly placement: () => Promise<FramesPlacement>;
+};
+/**
+ * The host and port a request was sent to: `Host`, or `:authority` over HTTP/2, which has no `Host`.
+ *
+ * @param request - the request.
+ */
+export declare const hostOf: (request: IncomingMessage) => string | undefined;
+/**
+ * The frames' side of a dev server.
+ *
+ * @param server - the dev server.
+ * @param frames - where the configuration puts the frames.
+ * @param frameHtml - the frame page's HTML, before Vite transforms it.
+ * @param framedPages - the server's pages another origin's page may frame (`catalogueAnswer`).
+ */
+export declare const framesServing: (server: ViteDevServer, frames: ResolvedFrames, frameHtml: string, framedPages: ReadonlySet<string>) => FramesServing;
+/**
+ * Gives the dev server's frames an origin of their own: the catalogue's guard first among the middlewares, the frames'
+ * port opened as the catalogue's listens (a port that cannot be had fails the start), and its address printed with
+ * the catalogue's.
+ *
+ * @param server - the dev server.
+ * @param config - the catalogue's configuration.
+ * @param place - receives where the frames run, for the pages' configuration.
+ * @param framedPages - the server's pages another origin's page may frame (a client's inline preview).
+ */
+export declare const serveFrames: (server: ViteDevServer, config: ResolvedConfig, place: (placement: () => Promise<FramesPlacement>) => void, framedPages: ReadonlySet<string>) => void;
+export {};

package/dist/src/vite/framesServer.js

@@ -0,0 +1,342 @@
+/**
+ * The dev server's second port, for the stories' frames: the same Vite server (its middlewares, its module graph, its
+ * WebSocket) on an origin of its own, and the guards that keep the two origins apart (`originGuard.ts`).
+ *
+ * @remarks
+ * One Vite server, two `http.Server`s: no second module graph, no second watcher. The frames' port listens on the
+ * catalogue's address, over HTTPS when the catalogue does, and hands its WebSocket upgrades (the frames' HMR, the
+ * errors they report) to Vite's. Its port is the catalogue's + 1 by default, the next free one when that is taken; a
+ * port the configuration gives must be free.
+ *
+ * Vite in middleware mode has no server of its own to add a port beside: its frames stay on the catalogue's origin.
+ *
+ * @module
+ */
+import { existsSync, statSync } from "node:fs";
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+import { resolve, sep } from "node:path";
+import { SAME_ORIGIN } from "../frameOrigins.js";
+import { framesOriginOf, servedPlacement } from "./framesConfig.js";
+import { catalogueAnswer, FRAME_PAGE_PATH, framesAnswer, graphUrlOf, pageEntries } from "./originGuard.js";
+import { pageHtml } from "./pages.js";
+/** How many ports after the default one the frames try before taking any free port. */
+const PORT_TRIES = 20;
+/**
+ * A header's single value.
+ *
+ * @param request - the request.
+ * @param name - the header's name, in lower case.
+ */
+const headerOf = (request, name) => {
+    const value = request.headers[name];
+    return Array.isArray(value) ? value[0] : value;
+};
+/**
+ * The host and port a request was sent to: `Host`, or `:authority` over HTTP/2, which has no `Host`.
+ *
+ * @param request - the request.
+ */
+export const hostOf = (request) => headerOf(request, "host") ?? headerOf(request, ":authority");
+/**
+ * Whether a path goes to the project's own server through Vite's proxy (`server.proxy`), as a story's API call does.
+ *
+ * @param proxy - Vite's proxy, by its paths: a prefix, or a regular expression when it starts with `^`.
+ * @param url - the request's address.
+ */
+const isProxied = (proxy, url) => Object.keys(proxy ?? {}).some((key) => key.startsWith("^") ? new RegExp(key).test(url) : url.startsWith(key));
+/**
+ * A request's path as an address parser reads it, which is how the routes behind the guards read it: a guard that read
+ * `//x/__forgebook/api/stories` as written would pass what the route answers as `/__forgebook/api/stories`.
+ *
+ * @param url - the request's address, as it was sent.
+ */
+const parsedPath = (url) => {
+    try {
+        return new URL(url, "http://parsed.invalid").pathname;
+    }
+    catch {
+        return (url.split("?")[0] ?? url).split("#")[0] ?? "/";
+    }
+};
+/**
+ * What the browser says of a request.
+ *
+ * @param request - the request.
+ */
+const factsOf = (request) => {
+    const url = request.url ?? "/";
+    const queryAt = url.indexOf("?");
+    return {
+        path: parsedPath(url),
+        query: queryAt === -1 ? "" : (url.slice(queryAt).split("#")[0] ?? ""),
+        site: headerOf(request, "sec-fetch-site"),
+        mode: headerOf(request, "sec-fetch-mode"),
+        dest: headerOf(request, "sec-fetch-dest"),
+        origin: headerOf(request, "origin"),
+        host: hostOf(request)
+    };
+};
+/**
+ * Whether a path names a file of the public folder.
+ *
+ * @param publicDir - the public folder's absolute path; empty when there is none.
+ * @param path - the request's path.
+ */
+const isPublicFile = (publicDir, path) => {
+    if (publicDir === "")
+        return false;
+    let decoded;
+    try {
+        decoded = decodeURIComponent(path);
+    }
+    catch {
+        return false;
+    }
+    const file = resolve(publicDir, `.${decoded}`);
+    return file.startsWith(`${publicDir}${sep}`) && existsSync(file) && statSync(file).isFile();
+};
+/**
+ * Whether a module the catalogue imports names an address in its code, as a whole string: how a worker's file
+ * (`?worker_file`) is started. Only an imported module counts, and only a whole string: an address asked for directly
+ * writes its own query into its module's code (its HMR context), and a story's script could plant any address there.
+ *
+ * @param modules - the graph's modules.
+ * @param url - the address, as the graph reads it; its `t=` left out.
+ */
+const isNamedInCode = (modules, url) => {
+    const named = JSON.stringify(url.replace(/[?&]t=\d+/, ""));
+    return modules.some((module) => module.importers.size > 0 && module.transformResult?.code.includes(named) === true);
+};
+/**
+ * Ends a request the guards turned down, with its status and nothing a page could use.
+ *
+ * @param response - the response.
+ * @param status - 403 or 404.
+ */
+const turnDown = (response, status) => {
+    response.statusCode = status;
+    response.setHeader("Content-Type", "text/plain");
+    response.end(status === 403 ? "Forbidden to the stories' frames\n" : "Not found\n");
+};
+/**
+ * Listens on a port, or tells why it could not.
+ *
+ * @param server - the server.
+ * @param port - the port; 0 for any free one.
+ * @param host - the address.
+ * @returns the port it listens on, or the error.
+ */
+const listenOn = (server, port, host) => new Promise((done) => {
+    const onError = (error) => done(error);
+    server.once("error", onError);
+    server.listen(port, host, () => {
+        server.off("error", onError);
+        const address = server.address();
+        done(address !== null && typeof address === "object" ? address.port : port);
+    });
+});
+/**
+ * Listens on the first free port of a list.
+ *
+ * @param server - the server.
+ * @param ports - the ports, in order; 0 for any free one.
+ * @param host - the address.
+ * @returns the port it listens on; none when every port is taken.
+ * @throws when listening fails for another reason than a port taken.
+ */
+const listenOnFirstFree = async (server, ports, host) => {
+    for (const port of ports.filter((each) => each <= 65535)) {
+        const listened = await listenOn(server, port, host);
+        if (typeof listened === "number")
+            return listened;
+        if (listened.code !== "EADDRINUSE")
+            throw listened;
+    }
+    return undefined;
+};
+/**
+ * The frames' `http.Server`, over HTTPS when the catalogue's is, its WebSocket upgrades handed to Vite's, closed with
+ * the catalogue's.
+ *
+ * @param server - the dev server.
+ * @param catalogue - the catalogue's own server.
+ * @param handle - answers a request.
+ */
+const framesHttpServer = (server, catalogue, handle) => {
+    const https = server.config.server.https;
+    const framesServer = https === undefined ? createHttpServer(handle) : createHttpsServer(https, handle);
+    framesServer.on("upgrade", (request, socket, head) => {
+        catalogue.emit("upgrade", request, socket, head);
+    });
+    catalogue.once("close", () => {
+        framesServer.closeAllConnections();
+        framesServer.close();
+    });
+    return framesServer;
+};
+/**
+ * The frames' side of a dev server.
+ *
+ * @param server - the dev server.
+ * @param frames - where the configuration puts the frames.
+ * @param frameHtml - the frame page's HTML, before Vite transforms it.
+ * @param framedPages - the server's pages another origin's page may frame (`catalogueAnswer`).
+ */
+export const framesServing = (server, frames, frameHtml, framedPages) => {
+    /** The requests that came in on the frames' port: the catalogue's guard leaves them to the frames'. */
+    const framesRequests = new WeakSet();
+    const sharedPaths = frames.kind === "isolated" ? frames.paths : [];
+    let framesPort;
+    let settle = () => undefined;
+    const placed = new Promise((resolvePlacement) => {
+        settle = resolvePlacement;
+    });
+    // the paths the frame page names, read once from the page as Vite serves it
+    let entries;
+    const pageEntriesOnce = () => {
+        entries ??= server.transformIndexHtml(FRAME_PAGE_PATH, frameHtml).then(pageEntries);
+        return entries;
+    };
+    const scheme = server.config.server.https === undefined ? "http:" : "https:";
+    /** The frames' origin for a request to the catalogue: the configured one, or its host on the frames' port. */
+    const framesOriginFor = (request) => {
+        if (frames.kind === "same-origin" || framesPort === undefined)
+            return undefined;
+        if (frames.origins !== undefined)
+            return frames.origins.frames;
+        const host = hostOf(request);
+        if (host === undefined)
+            return undefined;
+        try {
+            return new URL(`${scheme}//${new URL(`${scheme}//${host}`).hostname}:${framesPort}`).origin;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const catalogueGuard = (request, response, next) => {
+        if (framesRequests.has(request)) {
+            next();
+            return;
+        }
+        const answer = catalogueAnswer(factsOf(request), framedPages, (path) => isPublicFile(server.config.publicDir, path));
+        if (answer === "refuse") {
+            turnDown(response, 403);
+            return;
+        }
+        const framesOrigin = answer === "to-frames" ? framesOriginFor(request) : undefined;
+        if (framesOrigin === undefined) {
+            next();
+            return;
+        }
+        response.statusCode = 307;
+        response.setHeader("Location", `${framesOrigin}${request.url ?? FRAME_PAGE_PATH}`);
+        response.end();
+    };
+    /** What the frames' port does with a request. */
+    const framesAnswerFor = async (request) => {
+        const facts = factsOf(request);
+        const answer = framesAnswer(facts, {
+            isPublic: isPublicFile(server.config.publicDir, facts.path),
+            isPageEntry: (await pageEntriesOnce()).has(facts.path),
+            isServedAlike: isProxied(server.config.server.proxy, request.url ?? "/") ||
+                sharedPaths.some((path) => facts.path.startsWith(path))
+        });
+        if (answer !== "ask-graph")
+            return answer;
+        const url = graphUrlOf(request.url ?? "/");
+        if (url === undefined)
+            return "refuse";
+        const graph = server.environments.client.moduleGraph;
+        const module = await graph.getModuleByUrl(url);
+        if (module !== undefined && module.importers.size > 0)
+            return "serve";
+        // a worker's own file, the file a `?url` import or `new URL(…, import.meta.url)` gives: no module imports them,
+        // the module that uses them names them in its code
+        return isNamedInCode([...graph.idToModuleMap.values()], url) ? "serve" : "refuse";
+    };
+    const handleFrames = (request, response) => {
+        framesRequests.add(request);
+        framesAnswerFor(request)
+            .then((answer) => {
+            if (answer === "serve")
+                server.middlewares(request, response);
+            else
+                turnDown(response, answer === "not-found" ? 404 : 403);
+        })
+            .catch((error) => {
+            server.config.logger.error(`Forgebook's frames: ${error instanceof Error ? error.message : String(error)}`);
+            turnDown(response, 403);
+        });
+    };
+    const start = async () => {
+        const catalogue = server.httpServer?.address();
+        if (frames.kind === "same-origin" || server.httpServer === null || typeof catalogue !== "object") {
+            if (frames.kind === "isolated")
+                server.config.logger.warn("Forgebook's frames share the catalogue's origin: Vite runs without a server of its own (middleware " +
+                    "mode), so there is no port to give them, and a story's code can reach the catalogue");
+            settle(SAME_ORIGIN);
+            return SAME_ORIGIN;
+        }
+        if (catalogue === null)
+            throw new Error("Forgebook's frames start once the catalogue listens");
+        const framesServer = framesHttpServer(server, server.httpServer, handleFrames);
+        const wanted = frames.port ?? catalogue.port + 1;
+        // a port the configuration gives is that port; the default moves on, as Vite's own does
+        const tries = frames.port === undefined
+            ? [...Array.from({ length: PORT_TRIES }, (_, index) => wanted + index), 0]
+            : [wanted];
+        const listened = await listenOnFirstFree(framesServer, tries, catalogue.address);
+        if (listened === undefined)
+            throw new Error(`Forgebook's frames: port ${wanted} is taken (frames.port, --frame-port)`);
+        framesPort = listened;
+        const placement = servedPlacement(frames, { catalogue: catalogue.port, frames: listened });
+        settle(placement);
+        return placement;
+    };
+    return { catalogueGuard, start, placement: () => placed };
+};
+/**
+ * Gives the dev server's frames an origin of their own: the catalogue's guard first among the middlewares, the frames'
+ * port opened as the catalogue's listens (a port that cannot be had fails the start), and its address printed with
+ * the catalogue's.
+ *
+ * @param server - the dev server.
+ * @param config - the catalogue's configuration.
+ * @param place - receives where the frames run, for the pages' configuration.
+ * @param framedPages - the server's pages another origin's page may frame (a client's inline preview).
+ */
+export const serveFrames = (server, config, place, framedPages) => {
+    // the placement only changes the guard's inline script, never the entries this page is read for
+    const frames = framesServing(server, config.frames, pageHtml("frame.html", config, SAME_ORIGIN), framedPages);
+    place(frames.placement);
+    server.middlewares.use(frames.catalogueGuard);
+    // in middleware mode nothing listens here: the frames stay on the catalogue's origin, known at once
+    if (server.httpServer === null) {
+        void frames.start();
+        return;
+    }
+    const listen = server.listen;
+    server.listen = async (port, isRestart) => {
+        const listening = await listen(port, isRestart);
+        try {
+            await frames.start();
+        }
+        catch (error) {
+            // a catalogue whose frames cannot open must not keep serving pages that wait for them
+            await server.close();
+            throw error;
+        }
+        return listening;
+    };
+    const printUrls = server.printUrls;
+    server.printUrls = () => {
+        printUrls();
+        void frames.placement().then((placement) => {
+            const origin = framesOriginOf(placement, server.resolvedUrls?.local[0]);
+            if (origin !== undefined)
+                server.config.logger.info(`  ➜  Frames:  ${origin}/`);
+        });
+    };
+};

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

@@ -0,0 +1,26 @@
+import type { ComponentDocs, NoComponentDocs } from "../componentDocs.ts";
+import type { ExtractFileComponent, ExtractStoryComponent } from "./adapter.ts";
+/**
+ * A story file's component with the file that declares it.
+ *
+ * @param storyFile - the story file's absolute path.
+ * @returns the component, `{ docs: { name: null } }` when the meta names none, or a message saying why the file
+ * cannot be read.
+ */
+export declare const functionStoryComponent: ExtractStoryComponent;
+/**
+ * The docs of a story file's component, without the files they come from.
+ *
+ * @param storyFile - the story file's absolute path.
+ * @returns the component's docs, `{ name: null }` when the meta names no component, or a message saying why the file
+ * cannot be read.
+ */
+export declare const functionComponentDocs: (storyFile: string) => ComponentDocs | NoComponentDocs | string;
+/**
+ * A component a file exports, read from its types, for writing its first stories (`forgebook new`).
+ *
+ * @param file - the component's file, absolute.
+ * @param exportName - the export to read; the file's only component when none.
+ * @returns the component, or a message saying why it cannot be read (no component, several, a name not exported).
+ */
+export declare const functionFileComponent: ExtractFileComponent;