forgebook 0.1.7 → 0.2.0

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

@@ -0,0 +1,87 @@
+/**
+ * What the dev server's two origins answer a browser's request, from what the browser says of it (`Sec-Fetch-*`):
+ * the catalogue's origin refuses what another origin's page asks, and the frames' origin serves only the frame page,
+ * the public folder and the modules the catalogue imports. Pure: a request's facts in, an answer out.
+ *
+ * @remarks
+ * Vite's CORS lets any page on `localhost` or `127.0.0.1` read the dev server, whatever its port: a frame on a second
+ * port would read the catalogue's agent API and files as before. So the catalogue refuses a request another origin
+ * sends, unless it is a navigation (a link, an embed), which shows a page but lets nobody read it.
+ *
+ * The frames' origin would otherwise serve everything the catalogue's does, and a story's script would read the
+ * project from there. It serves a script or a `fetch` (whose body a script reads) only for a module that another
+ * module of the catalogue imports: the browser learns a module's address only from its importer, which Vite reads and
+ * records before answering, so a story's own modules always qualify and a file nothing imports (`/@fs/…?raw`) never
+ * does. A request whose body a script cannot read as text (an image, a font, a style sheet, a worker's script, whose
+ * exports stay in the worker) is left to Vite: the asset a style sheet names and a worker's file are not modules
+ * another module imports.
+ *
+ * A request without `Sec-Fetch-*` comes from a tool (a command, an agent, `curl`) or an older browser: the `Origin`
+ * header then tells another origin's page, and the frames' origin answers it as a script's.
+ *
+ * @module
+ */
+/** What a browser says of a request, from its headers. */
+export type RequestFacts = {
+    /** Its path, without the query (`/frame.html`). */
+    readonly path: string;
+    /** Its query, with its `?` (`?raw`); empty without one. */
+    readonly query: string;
+    /** `Sec-Fetch-Site`: whose page sent it (`same-origin`, `same-site`, `cross-site`, `none`); none from a tool. */
+    readonly site: string | undefined;
+    /** `Sec-Fetch-Mode`: `navigate` for a page or a frame opened. */
+    readonly mode: string | undefined;
+    /** `Sec-Fetch-Dest`: what the response becomes (`document`, `iframe`, `script`, `empty` for a `fetch`…). */
+    readonly dest: string | undefined;
+    /** `Origin`: the origin of the page that sent it, on a `fetch` or a module script; none on a plain navigation. */
+    readonly origin: string | undefined;
+    /** `Host`: the host and port the request was sent to. */
+    readonly host: string | undefined;
+};
+/** The frame page's path. */
+export declare const FRAME_PAGE_PATH = "/frame.html";
+/** What the catalogue's origin does with a request. */
+export type CatalogueAnswer = "serve" | "refuse" | "to-frames";
+/**
+ * What the catalogue's origin does with a request: the frame page goes to the frames' origin, another origin's
+ * request is refused, the rest is served.
+ *
+ * @param request - what the browser says of it.
+ * @param framedPages - the server's routes that are pages made to be framed by another origin's page (a client's
+ *   inline preview), which only show a story and act on nothing.
+ */
+export declare const catalogueAnswer: (request: RequestFacts, framedPages: ReadonlySet<string>) => CatalogueAnswer;
+/** What the frames' origin does with a request: `ask-graph` serves it when another module imports it. */
+export type FramesAnswer = "serve" | "refuse" | "not-found" | "ask-graph";
+/** What the frames' origin knows of a request's path. */
+export type FramesPaths = {
+    /** Whether it names a file of the public folder. */
+    readonly isPublic: boolean;
+    /** Whether the frame page names it (its scripts, its head's tags). */
+    readonly isPageEntry: boolean;
+    /**
+     * Whether the frames' origin serves it as the catalogue's does: the project's API through Vite's proxy, or a path
+     * the configuration names (`frames.paths`, an API a plugin answers).
+     */
+    readonly isServedAlike: boolean;
+};
+/**
+ * What the frames' origin does with a request.
+ *
+ * @param request - what the browser says of it.
+ * @param paths - what the server knows of its path.
+ */
+export declare const framesAnswer: (request: RequestFacts, paths: FramesPaths) => FramesAnswer;
+/**
+ * The paths a page's HTML names: its scripts' and links' addresses, and the modules its inline scripts import.
+ *
+ * @param html - the page's HTML, as Vite transformed it.
+ */
+export declare const pageEntries: (html: string) => ReadonlySet<string>;
+/**
+ * A request's address as Vite's module graph names the module, as Vite's own transform reads it: decoded, a virtual
+ * module's id unwrapped (`/@id/__x00__virtual:…` is `\0virtual:…`); none when it cannot be decoded.
+ *
+ * @param url - the request's address, with its query.
+ */
+export declare const graphUrlOf: (url: string) => string | undefined;

package/dist/src/vite/originGuard.js

@@ -0,0 +1,163 @@
+/**
+ * What the dev server's two origins answer a browser's request, from what the browser says of it (`Sec-Fetch-*`):
+ * the catalogue's origin refuses what another origin's page asks, and the frames' origin serves only the frame page,
+ * the public folder and the modules the catalogue imports. Pure: a request's facts in, an answer out.
+ *
+ * @remarks
+ * Vite's CORS lets any page on `localhost` or `127.0.0.1` read the dev server, whatever its port: a frame on a second
+ * port would read the catalogue's agent API and files as before. So the catalogue refuses a request another origin
+ * sends, unless it is a navigation (a link, an embed), which shows a page but lets nobody read it.
+ *
+ * The frames' origin would otherwise serve everything the catalogue's does, and a story's script would read the
+ * project from there. It serves a script or a `fetch` (whose body a script reads) only for a module that another
+ * module of the catalogue imports: the browser learns a module's address only from its importer, which Vite reads and
+ * records before answering, so a story's own modules always qualify and a file nothing imports (`/@fs/…?raw`) never
+ * does. A request whose body a script cannot read as text (an image, a font, a style sheet, a worker's script, whose
+ * exports stay in the worker) is left to Vite: the asset a style sheet names and a worker's file are not modules
+ * another module imports.
+ *
+ * A request without `Sec-Fetch-*` comes from a tool (a command, an agent, `curl`) or an older browser: the `Origin`
+ * header then tells another origin's page, and the frames' origin answers it as a script's.
+ *
+ * @module
+ */
+/** The frame page's path. */
+export const FRAME_PAGE_PATH = "/frame.html";
+/** What becomes a document: a navigation, or something that opens one. */
+const DOCUMENT_DESTS = new Set(["document", "iframe", "frame", "object", "embed"]);
+/**
+ * What a script cannot read as text: drawn, played or applied as styles. Not a worker's or a worklet's script: a
+ * module worker's own imports are sent as `worker` (an audio worklet's as `audioworklet`) and its exports go back to
+ * the page, so they are served as a script is.
+ */
+const OPAQUE_DESTS = new Set([
+    "image",
+    "font",
+    "style",
+    "audio",
+    "video",
+    "track",
+    "manifest"
+]);
+/** The queries that ask Vite for a module made from a file (its text, its address…), never a file as it is. */
+const TRANSFORM_QUERY = /[?&](?:raw|import|inline|url|worker|worker_file|sharedworker)(?:[&=]|$)/;
+/** The dev server's own routes (`/__forgebook/api/`, `/__open-in-editor`): never a story's. */
+const SERVER_ROUTE_PREFIX = "/__";
+/**
+ * Whether a request's `Origin` names another host than the one it was sent to: for a browser that sends no
+ * `Sec-Fetch-Site`. Never asked of one that does, so a proxy that rewrites `Host` does not turn a page away from itself.
+ *
+ * @param request - what the browser says of it.
+ */
+const isOriginForeign = (request) => {
+    if (request.origin === undefined)
+        return false;
+    try {
+        return new URL(request.origin).host !== request.host;
+    }
+    catch {
+        // `null`, from a sandboxed or opaque document
+        return true;
+    }
+};
+/**
+ * Whether another origin's page sent a request that is not a navigation.
+ *
+ * @param request - what the browser says of it.
+ */
+const isFromAnotherOrigin = (request) => {
+    if (request.mode === "navigate")
+        return false;
+    if (request.site === undefined)
+        return isOriginForeign(request);
+    return request.site === "same-site" || request.site === "cross-site";
+};
+/**
+ * Whether another origin's page sent a request, a navigation included.
+ *
+ * @param request - what the browser says of it.
+ */
+const isAnyFromAnotherOrigin = (request) => request.site === undefined
+    ? isOriginForeign(request)
+    : request.site === "same-site" || request.site === "cross-site";
+/**
+ * Whether a request opens a document: a navigation, or something that opens one.
+ *
+ * @param request - what the browser says of it.
+ */
+const isDocumentRequest = (request) => request.mode === "navigate" || DOCUMENT_DESTS.has(request.dest ?? "");
+/**
+ * What the catalogue's origin does with a request: the frame page goes to the frames' origin, another origin's
+ * request is refused, the rest is served.
+ *
+ * @param request - what the browser says of it.
+ * @param framedPages - the server's routes that are pages made to be framed by another origin's page (a client's
+ *   inline preview), which only show a story and act on nothing.
+ */
+export const catalogueAnswer = (request, framedPages) => {
+    if (isFromAnotherOrigin(request))
+        return "refuse";
+    const isFramedPage = framedPages.has(request.path) && isDocumentRequest(request);
+    // a route of the server acts when it is opened (`/__open-in-editor` opens a file): not on another page's say
+    if (request.path.startsWith(SERVER_ROUTE_PREFIX) && !isFramedPage && isAnyFromAnotherOrigin(request))
+        return "refuse";
+    return request.path === FRAME_PAGE_PATH ? "to-frames" : "serve";
+};
+/** Vite's own client and helpers, which the project's code does not hold. */
+const VITE_PREFIXES = ["/@vite/", "/@id/__x00__vite/"];
+/**
+ * Whether the frames' origin serves a request as it is, without asking the graph: what a script cannot read as text,
+ * the paths the server knows for the frames, and Vite's own client.
+ *
+ * @param request - what the browser says of it.
+ * @param paths - what the server knows of its path.
+ */
+const isServedAsIs = (request, paths) => (OPAQUE_DESTS.has(request.dest ?? "") && !TRANSFORM_QUERY.test(request.query)) ||
+    paths.isPublic ||
+    paths.isPageEntry ||
+    paths.isServedAlike ||
+    VITE_PREFIXES.some((prefix) => request.path.startsWith(prefix));
+/**
+ * What the frames' origin does with a request.
+ *
+ * @param request - what the browser says of it.
+ * @param paths - what the server knows of its path.
+ */
+export const framesAnswer = (request, paths) => {
+    if (isFromAnotherOrigin(request))
+        return "refuse";
+    // the catalogue's page is the catalogue origin's alone; the frame page holds nothing a script could use
+    if (request.path === "/" || request.path === "/index.html")
+        return "not-found";
+    if (request.path === FRAME_PAGE_PATH)
+        return "serve";
+    if (isDocumentRequest(request))
+        return paths.isPublic || paths.isServedAlike ? "serve" : "not-found";
+    if (request.path.startsWith(SERVER_ROUTE_PREFIX))
+        return "refuse";
+    return isServedAsIs(request, paths) ? "serve" : "ask-graph";
+};
+/**
+ * The paths a page's HTML names: its scripts' and links' addresses, and the modules its inline scripts import.
+ *
+ * @param html - the page's HTML, as Vite transformed it.
+ */
+export const pageEntries = (html) => new Set([...html.matchAll(/["'](\/[^"'\s?#]*)/g)].flatMap((match) => (match[1] === undefined ? [] : [match[1]])));
+/** How Vite writes a module id that is no path (a virtual module's) in an address. */
+const ID_PREFIX = "/@id/";
+/**
+ * A request's address as Vite's module graph names the module, as Vite's own transform reads it: decoded, a virtual
+ * module's id unwrapped (`/@id/__x00__virtual:…` is `\0virtual:…`); none when it cannot be decoded.
+ *
+ * @param url - the request's address, with its query.
+ */
+export const graphUrlOf = (url) => {
+    let decoded;
+    try {
+        decoded = decodeURI(url).replace("__x00__", "\0");
+    }
+    catch {
+        return undefined;
+    }
+    return decoded.startsWith(ID_PREFIX) ? decoded.slice(ID_PREFIX.length) : decoded;
+};

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

@@ -0,0 +1,40 @@
+/** Writes a module's JSON as the expression of its value, or of a promise of it. */
+export type PackJson = (json: string) => string;
+/** What the plugin writes a file with: Rolldown's `emitFile`, narrowed to an asset of a known name. */
+export type EmitAsset = (asset: {
+    readonly type: "asset";
+    readonly fileName: string;
+    readonly source: Uint8Array;
+}) => unknown;
+/** The JSON as code of the same value, on a dev server. */
+export declare const inlineJson: PackJson;
+/**
+ * The name a build gives a JSON document's gzipped file: its content's hash, so a host may keep it for ever. Twelve
+ * hex digits: a build writes up to three per story file, and two documents of one name would show one in place of the
+ * other with no error.
+ *
+ * @param json - the document.
+ */
+export declare const packedFileName: (json: string) => string;
+/**
+ * A JSON document gzipped, as a build writes it.
+ *
+ * @param json - the document.
+ */
+export declare const gzippedJson: (json: string) => Uint8Array;
+/**
+ * The code of a function that makes the loader of a packed file by its name (`packedFileName`): the module the page
+ * unpacks with loads on the first such load, never with the code that holds the loaders. A loader keeps its answer,
+ * as an imported module's default is kept, and forgets a failure, so the next load asks again.
+ *
+ * @param name - the function's name in the generated code.
+ */
+export declare const packedLoaderMaker: (name: string) => string;
+/**
+ * The JSON in a gzipped file named by its content, for a build. The module's value is the promise of it, which its
+ * loader (`import(…).then((module) => module.default)`) waits for: no top-level await, which a catalogue's lower
+ * `build.target` would refuse.
+ *
+ * @param emit - writes the file.
+ */
+export declare const packedJsonOf: (emit: EmitAsset) => PackJson;

package/dist/src/vite/packedModule.js

@@ -0,0 +1,74 @@
+/**
+ * A module's JSON kept out of a build's JavaScript: gzipped in a file of its own, unpacked when the module loads
+ * (`packedText.ts`).
+ *
+ * @remarks
+ * A static catalogue's "Used in" is read by few visits and compresses to a tenth, so a build writes it as a file and
+ * the module keeps only its address; a story file's docs, code and page are written the same way (`builtTexts.ts`). A
+ * dev server answers with the JSON itself.
+ *
+ * @module
+ */
+import { createHash } from "node:crypto";
+import { extname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gzipSync } from "node:zlib";
+import { codeLiteral, codeOfJson } from "../codeLiteral.js";
+import { VITE_PATHS } from "./vitePaths.js";
+/**
+ * The module the page unpacks with, by its own path: the generated code imports it as a file of this package, so it is
+ * no public subpath and a project need not resolve the package by name.
+ */
+const PACKED_TEXT = VITE_PATHS.normalize(fileURLToPath(new URL(`../packedText${extname(import.meta.url)}`, import.meta.url)));
+/** The JSON as code of the same value, on a dev server. */
+export const inlineJson = (json) => codeOfJson(json);
+/**
+ * The name a build gives a JSON document's gzipped file: its content's hash, so a host may keep it for ever. Twelve
+ * hex digits: a build writes up to three per story file, and two documents of one name would show one in place of the
+ * other with no error.
+ *
+ * @param json - the document.
+ */
+export const packedFileName = (json) => `assets/${createHash("sha256").update(json).digest("hex").slice(0, 12)}.bin`;
+/**
+ * A JSON document gzipped, as a build writes it.
+ *
+ * @param json - the document.
+ */
+export const gzippedJson = (json) => 
+// gzip's default level: a higher one takes twice as long on a large index for the same size
+gzipSync(json);
+/**
+ * The code of a function that makes the loader of a packed file by its name (`packedFileName`): the module the page
+ * unpacks with loads on the first such load, never with the code that holds the loaders. A loader keeps its answer,
+ * as an imported module's default is kept, and forgets a failure, so the next load asks again.
+ *
+ * @param name - the function's name in the generated code.
+ */
+export const packedLoaderMaker = (name) => [
+    `const ${name} = (file) => {`,
+    "  let loading;",
+    "  return () => {",
+    `    loading ??= import(${codeLiteral(PACKED_TEXT)})`,
+    "      .then((module) => module.packedJson(import.meta.env.BASE_URL + file))",
+    "      .catch((error) => {",
+    "        loading = undefined;",
+    "        throw error;",
+    "      });",
+    "    return loading;",
+    "  };",
+    "};"
+].join("\n");
+/**
+ * The JSON in a gzipped file named by its content, for a build. The module's value is the promise of it, which its
+ * loader (`import(…).then((module) => module.default)`) waits for: no top-level await, which a catalogue's lower
+ * `build.target` would refuse.
+ *
+ * @param emit - writes the file.
+ */
+export const packedJsonOf = (emit) => (json) => {
+    const fileName = packedFileName(json);
+    emit({ type: "asset", fileName, source: gzippedJson(json) });
+    const address = `import.meta.env.BASE_URL + ${codeLiteral(fileName)}`;
+    return `import(${codeLiteral(PACKED_TEXT)}).then((module) => module.packedJson(${address}))`;
+};

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

@@ -1,10 +1,14 @@
+import type { FramesPlacement } from "../frameOrigins.ts";
 import { type ResolvedConfig } from "./configFile.ts";
+import { type VitePaths } from "./vitePaths.ts";
 /** The pages, by their file name. */
 export declare const PAGE_FILES: readonly ["index.html", "frame.html"];
 /** A page's file name. */
 export type PageFile = (typeof PAGE_FILES)[number];
 /** The module the pages read the configuration's data from. */
 export declare const CONFIG_MODULE = "virtual:forgebook/config";
+/** The module the shell reads the design tokens from, imported on first use: a page that shows none never loads it. */
+export declare const TOKENS_MODULE = "virtual:forgebook/tokens";
 /**
  * The entries the pages load, by page: file names in the configuration's folder, never written to disk. Named as
  * files rather than virtual modules because the build names a page's chunk and its style sheet after its entry, and a
@@ -15,47 +19,96 @@ export declare const PAGE_ENTRIES: Readonly<Record<PageFile, string>>;
 export declare const STORIES_SOURCE_FILE = ".forgebook-stories.ts";
 /**
  * The file name, in the configuration's folder, of the module the dev server loads to answer tools and agents: the
- * sources and the previews, as the frame gets them (never written to disk).
+ * sources, as the frame gets them (never written to disk).
  */
 export declare const AGENT_SOURCES_FILE = ".forgebook-agent.ts";
-/** The project's own stories' source id. */
-export declare const OWN_SOURCE_ID = "stories";
+/** A module the plugin generates in the configuration's folder: a page, a page's entry, or one of the two sources. */
+export type PageModule = {
+    readonly kind: "page";
+    readonly page: PageFile;
+} | {
+    readonly kind: "entry";
+    readonly page: PageFile;
+} | {
+    readonly kind: "stories-source";
+} | {
+    readonly kind: "agent-sources";
+};
+/**
+ * A generated module's path, in Vite's form: what the pages import, what Vite's ids name.
+ *
+ * @param dir - the configuration's folder.
+ * @param file - the module's file name (`PAGE_FILES`, `PAGE_ENTRIES`, `STORIES_SOURCE_FILE`, `AGENT_SOURCES_FILE`).
+ * @param paths - the path functions; the running system's unless a test names another.
+ */
+export declare const pageModulePath: (dir: string, file: string, paths?: VitePaths) => string;
+/**
+ * The generated module a path names, when it names one: an id from Vite (`C:/app/.forgebook-shell.ts` on Windows) or
+ * a path from Node (`C:\app\frame.html`, as the build's inputs may arrive) both match.
+ *
+ * @param path - the id or path.
+ * @param dir - the configuration's folder.
+ * @param paths - the path functions; the running system's unless a test names another.
+ */
+export declare const pageModuleOf: (path: string, dir: string, paths?: VitePaths) => PageModule | undefined;
 /**
  * A page's HTML: its title, the frame's head tags, the root the entry mounts in.
  *
  * @param page - the page.
  * @param config - the configuration.
+ * @param placement - where the frames run, which the frame's load guard tells its errors by.
  */
-export declare const pageHtml: (page: PageFile, config: ResolvedConfig) => string;
+export declare const pageHtml: (page: PageFile, config: ResolvedConfig, placement: FramesPlacement) => string;
 /**
  * The configuration's data, as the pages' module exports it.
  *
  * @param config - the configuration.
+ * @param frames - where the frames run: known on the dev server once both of its ports listen.
+ */
+export declare const configModule: (config: ResolvedConfig, frames: FramesPlacement) => string;
+/** The module the entry loads the written home's view from, on first use. */
+export declare const WRITTEN_HOME_MODULE = "forgebook/shell/home";
+/** The module the entry loads the code that draws the plugins' views from, on first use. */
+export declare const PLUGIN_HOSTS_MODULE = "forgebook/shell/plugin-hosts";
+/**
+ * Whether a catalogue lists a plugin with a view in the shell: a tab or a docs block.
+ *
+ * @param config - the configuration.
  */
-export declare const configModule: (config: ResolvedConfig) => string;
+export declare const hasPluginViews: (config: ResolvedConfig) => boolean;
 /**
  * The shell's entry: the shell mounted with the configuration's data, the logo, the sources and the code writer.
  *
  * @param config - the configuration.
  */
 export declare const shellEntry: (config: ResolvedConfig) => string;
+/** How a frame's entry gets the address of axe's script (`axeScript.ts`). */
+export type AxeAddress = {
+    /** The imports it needs. */
+    readonly imports: readonly string[];
+    /** The expression that gives the address. */
+    readonly value: string;
+};
 /**
  * The frame's entry: the framework's frame mounted with the sources, the configuration's data and the previews.
  *
  * @param config - the configuration.
+ * @param axe - how the entry gets the address of axe's script, for the Accessibility card; none when it cannot be
+ *   found, which leaves the card to say so.
  */
-export declare const frameEntry: (config: ResolvedConfig) => string;
+export declare const frameEntry: (config: ResolvedConfig, axe?: AxeAddress) => string;
 /**
- * The module the dev server loads to answer tools and agents: the sources and the previews the frame mounts, as
- * values (`sources`, `previews`), loaded on the server with the same imports the pages use.
+ * The module the dev server loads to answer tools and agents: the sources the frame mounts (`sources`), with the same
+ * imports the pages use. The previews are loaded beside it, each on its own (`previewRunner.ts`): a browser's code may
+ * keep one from loading on the server.
  *
  * @param config - the configuration.
  */
 export declare const agentSourcesModule: (config: ResolvedConfig) => string;
 /**
- * The source of the project's own stories: one `?forgebook-files` import per glob, named after the catalogue.
+ * The source of the project's own stories and docs pages: one `?forgebook-files` or `?forgebook-docs-pages` import per
+ * glob, named after the catalogue.
  *
  * @param config - the configuration.
  */
 export declare const storiesSourceModule: (config: ResolvedConfig) => string;
-//# sourceMappingURL=pages.d.ts.map