forgebook 0.1.8 → 0.3.0

package/dist/src/vite/nearestToken.js

@@ -0,0 +1,295 @@
+/** How many tokens a search gives: an agent needs the best and what is close to it. */
+const NEAREST_LIMIT = 3;
+/** The pixels of a rem, the browsers' default. */
+const REM_PIXELS = 16;
+/** Below this the two values are equal, whatever the arithmetic left behind. */
+const EXACT = 1e-6;
+/** Oklab's distance that a person barely tells apart, times 100. */
+const CLOSE_COLOR = 2;
+/** The share of a size or a time that still reads as the same. */
+const CLOSE_SHARE = 0.05;
+/** A number as CSS writes it, with what follows. */
+const MEASURE = /^([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)([a-z%]*)$/i;
+/** The font weights the format names, as numbers. */
+const FONT_WEIGHTS = {
+    thin: 100,
+    hairline: 100,
+    "extra-light": 200,
+    "ultra-light": 200,
+    light: 300,
+    normal: 400,
+    regular: 400,
+    book: 400,
+    medium: 500,
+    "semi-bold": 600,
+    "demi-bold": 600,
+    bold: 700,
+    "extra-bold": 800,
+    "ultra-bold": 800,
+    black: 900,
+    heavy: 900,
+    "extra-black": 950,
+    "ultra-black": 950
+};
+/** What a CSS property or a loose word compares with, for an agent that names what it is writing. */
+const TYPE_WORDS = {
+    color: "color",
+    colour: "color",
+    background: "color",
+    "background-color": "color",
+    "border-color": "color",
+    fill: "color",
+    stroke: "color",
+    dimension: "dimension",
+    size: "dimension",
+    spacing: "dimension",
+    space: "dimension",
+    padding: "dimension",
+    margin: "dimension",
+    gap: "dimension",
+    width: "dimension",
+    height: "dimension",
+    radius: "dimension",
+    "border-radius": "dimension",
+    "font-size": "dimension",
+    duration: "duration",
+    "transition-duration": "duration",
+    "animation-duration": "duration",
+    number: "number",
+    "line-height": "number",
+    opacity: "number",
+    fontweight: "fontWeight",
+    "font-weight": "fontWeight"
+};
+/** A channel without sRGB's curve. */
+const linear = (channel) => channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+/** Linear sRGB in Oklab, the published conversion. */
+const fromLinear = (r, g, b, alpha) => {
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    return {
+        l: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+        alpha
+    };
+};
+/** sRGB channels of 0 to 1 in Oklab. */
+const fromSrgb = (r, g, b, alpha) => fromLinear(linear(r), linear(g), linear(b), alpha);
+/** Linear Display P3 in Oklab, through linear sRGB, the standard matrix. */
+const fromDisplayP3 = (r, g, b, alpha) => {
+    const [lr, lg, lb] = [linear(r), linear(g), linear(b)];
+    return fromLinear(1.2249401 * lr - 0.2249404 * lg, -0.0420569 * lr + 1.0420571 * lg, -0.0196376 * lr - 0.0786361 * lg + 1.0982735 * lb, alpha);
+};
+/** A hex colour; none unless it has 3, 4, 6 or 8 digits. */
+const hexColor = (text) => {
+    const digits = /^#((?:[0-9a-f]{3,4}){1,2})$/.exec(text)?.[1];
+    if (digits === undefined)
+        return undefined;
+    const long = digits.length <= 4 ? [...digits].map((digit) => digit + digit).join("") : digits;
+    const byte = (start) => Number.parseInt(long.slice(start, start + 2), 16) / 255;
+    return fromSrgb(byte(0), byte(2), byte(4), long.length === 8 ? byte(6) : 1);
+};
+/** A function's arguments: its channels and its alpha, commas or spaces, `none` as zero. */
+const functionArguments = (text) => {
+    const match = /^([a-z-]+)\((.*)\)$/.exec(text);
+    if (match === null)
+        return undefined;
+    const [channels = "", alpha] = (match[2] ?? "").split("/");
+    const parts = channels.trim().split(/[\s,]+/);
+    const commaAlpha = alpha === undefined && parts.length === 4 ? parts.pop() : undefined;
+    const written = (alpha ?? commaAlpha)?.trim();
+    const opacity = written === undefined ? 1 : percentOf(written, 1);
+    return { name: match[1] ?? "", parts, alpha: opacity };
+};
+/** A channel that may be a percentage of a full scale; `none` is zero. */
+const percentOf = (text, full) => {
+    if (text === "none")
+        return 0;
+    return text.endsWith("%") ? (Number(text.slice(0, -1)) / 100) * full : Number(text);
+};
+/** Hue, saturation and lightness as sRGB. */
+const hslChannels = (hue, saturation, lightness) => {
+    const chroma = saturation * Math.min(lightness, 1 - lightness);
+    const channel = (offset) => {
+        const k = (offset + hue / 30) % 12;
+        return lightness - chroma * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+    };
+    return [channel(0), channel(8), channel(4)];
+};
+/** Polar Oklab as Oklab. */
+const fromOklch = (l, chroma, hue, alpha) => ({
+    l,
+    a: chroma * Math.cos((hue * Math.PI) / 180),
+    b: chroma * Math.sin((hue * Math.PI) / 180),
+    alpha
+});
+/** A CSS colour function; none for one this cannot place in Oklab. */
+const functionColor = (text) => {
+    const call = functionArguments(text);
+    if (call === undefined)
+        return undefined;
+    const { name, parts, alpha } = call;
+    const [first = "", second = "", third = "", fourth = ""] = parts;
+    const fromRgb = () => fromSrgb(percentOf(first, 255) / 255, percentOf(second, 255) / 255, percentOf(third, 255) / 255, alpha);
+    const fromHsl = () => {
+        const [r, g, b] = hslChannels(percentOf(first, 360), percentOf(second, 1), percentOf(third, 1));
+        return fromSrgb(r, g, b, alpha);
+    };
+    const convert = {
+        rgb: fromRgb,
+        rgba: fromRgb,
+        hsl: fromHsl,
+        hsla: fromHsl,
+        oklab: () => ({ l: percentOf(first, 1), a: percentOf(second, 0.4), b: percentOf(third, 0.4), alpha }),
+        oklch: () => fromOklch(percentOf(first, 1), percentOf(second, 0.4), percentOf(third, 360), alpha),
+        color: () => {
+            const [r, g, b] = [percentOf(second, 1), percentOf(third, 1), percentOf(fourth, 1)];
+            if (first === "srgb")
+                return fromSrgb(r, g, b, alpha);
+            if (first === "srgb-linear")
+                return fromLinear(r, g, b, alpha);
+            return first === "display-p3" ? fromDisplayP3(r, g, b, alpha) : undefined;
+        }
+    };
+    return convert[name]?.();
+};
+/** A colour as CSS writes it, in Oklab; none for what cannot be read. Keywords beyond these three carry no design. */
+const parsedColor = (written) => {
+    const text = written.trim().toLowerCase();
+    if (text === "transparent")
+        return fromSrgb(0, 0, 0, 0);
+    if (text === "black")
+        return fromSrgb(0, 0, 0, 1);
+    if (text === "white")
+        return fromSrgb(1, 1, 1, 1);
+    const color = text.startsWith("#") ? hexColor(text) : functionColor(text);
+    const isReadable = color !== undefined && [color.l, color.a, color.b, color.alpha].every(Number.isFinite);
+    return isReadable ? color : undefined;
+};
+/** A number with a unit, in the unit a type compares in; none when it is something else. */
+const measure = (text, units) => {
+    const match = MEASURE.exec(text.trim());
+    const scale = units[(match?.[2] ?? "").toLowerCase()];
+    return match === null || scale === undefined ? undefined : Number(match[1]) * scale;
+};
+/** Two measures' distance. */
+const measured = (units) => (first, second) => {
+    const [a, b] = [measure(first, units), measure(second, units)];
+    return a === undefined || b === undefined ? undefined : Math.abs(a - b);
+};
+/** What counts as near a measure: a share of it, or a floor for small values. */
+const nearMeasure = (units, floor) => (value) => Math.max(floor, Math.abs(measure(value, units) ?? 0) * CLOSE_SHARE);
+/** A font weight as a number. */
+const fontWeight = (text) => {
+    const named = FONT_WEIGHTS[text.trim().toLowerCase()];
+    return named ?? measure(text, { "": 1 });
+};
+/** The units of dimensions, in pixels. */
+const PIXELS = { px: 1, rem: REM_PIXELS, "": 1 };
+/** The units of durations, in milliseconds. */
+const MILLISECONDS = { ms: 1, s: 1000 };
+/** How each type compares; a type not here has no meaningful distance. */
+const COMPARISONS = {
+    color: {
+        unit: "Oklab distance × 100: under 2 reads as the same colour; alpha counts",
+        distance: (first, second) => {
+            const [a, b] = [parsedColor(first), parsedColor(second)];
+            if (a === undefined || b === undefined)
+                return undefined;
+            return (Math.hypot(a.l - b.l, a.a - b.a, a.b - b.b) + Math.abs(a.alpha - b.alpha)) * 100;
+        },
+        closeAt: () => CLOSE_COLOR
+    },
+    dimension: {
+        unit: "px, a rem being 16",
+        distance: measured(PIXELS),
+        closeAt: nearMeasure(PIXELS, 1)
+    },
+    duration: { unit: "ms", distance: measured(MILLISECONDS), closeAt: nearMeasure(MILLISECONDS, 10) },
+    number: { unit: "the number", distance: measured({ "": 1 }), closeAt: nearMeasure({ "": 1 }, 0) },
+    fontWeight: {
+        unit: "weight",
+        distance: (first, second) => {
+            const [a, b] = [fontWeight(first), fontWeight(second)];
+            return a === undefined || b === undefined ? undefined : Math.abs(a - b);
+        },
+        closeAt: () => 0
+    }
+};
+/** The type a value's form tells, for a question that names none. */
+const inferredType = (value) => {
+    const text = value.trim().toLowerCase();
+    if (parsedColor(text) !== undefined)
+        return "color";
+    if (measure(text, MILLISECONDS) !== undefined)
+        return "duration";
+    if (measure(text, { px: 1, rem: 1 }) !== undefined)
+        return "dimension";
+    if (FONT_WEIGHTS[text] !== undefined)
+        return "fontWeight";
+    return measure(text, { "": 1 }) === undefined ? undefined : "number";
+};
+/** A token's best match for a value, over its base value and each theme's; a tie goes to the base. */
+const bestMatch = (token, value, comparison) => {
+    const options = [
+        ...(token.isThemeOnly === true ? [] : [{ mode: undefined, value: token.value }]),
+        ...Object.entries(token.modes).map(([mode, text]) => ({ mode, value: text }))
+    ];
+    const matches = options.flatMap((option) => {
+        const distance = comparison.distance(value, option.value);
+        if (distance === undefined || !Number.isFinite(distance))
+            return [];
+        return [
+            {
+                name: token.name,
+                value: option.value,
+                ...(option.mode === undefined ? {} : { mode: option.mode }),
+                ...(token.alias === undefined ? {} : { alias: token.alias }),
+                distance: Math.round(distance * 100) / 100,
+                isExact: distance < EXACT,
+                isClose: distance <= comparison.closeAt(value)
+            }
+        ];
+    });
+    return matches.toSorted((first, second) => first.distance - second.distance)[0];
+};
+/** The order of matches: nearest first, the base before a theme when they tie, since the base holds in every theme. */
+const byDistance = (first, second) => first.distance - second.distance || Number(first.mode !== undefined) - Number(second.mode !== undefined);
+/** The type a word names: a token type, or a CSS property. */
+const typeOfWord = (word) => TYPE_WORDS[word.trim().toLowerCase()];
+/**
+ * The tokens nearest a value, nearest first. Deprecated tokens are left out: code must not move onto one.
+ *
+ * @param tokens - the tokens.
+ * @param value - the value, as code writes it (`#1c1b1b`, `rgb(1 2 3 / 50%)`, `hsl(0 100% 50%)`, `16px`, `200ms`).
+ * @param asked - a token type, or a CSS property (`background`, `font-size`); none reads it from the value.
+ */
+export const nearestTokens = (tokens, value, asked) => {
+    const type = asked === undefined ? inferredType(value) : typeOfWord(asked);
+    const comparison = type === undefined ? undefined : COMPARISONS[type];
+    if (type === undefined || comparison === undefined) {
+        const reason = asked === undefined
+            ? `Cannot tell what kind of value ${value} is: name its type.`
+            : `Cannot compare "${asked}": name color, dimension, duration, number or fontWeight, or a CSS property.`;
+        return { type: undefined, unit: undefined, matches: [], uncompared: 0, reason };
+    }
+    if (comparison.distance(value, value) === undefined) {
+        return {
+            type,
+            unit: undefined,
+            matches: [],
+            uncompared: 0,
+            reason: `Cannot read ${value} as a ${type}.`
+        };
+    }
+    const candidates = tokens.filter((token) => token.type === type && token.deprecated === undefined);
+    const found = candidates.flatMap((token) => bestMatch(token, value, comparison) ?? []);
+    return {
+        type,
+        unit: comparison.unit,
+        matches: found.toSorted(byDistance).slice(0, NEAREST_LIMIT),
+        uncompared: candidates.length - found.length
+    };
+};

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

@@ -0,0 +1,97 @@
+/**
+ * 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 opens one of its pages (a link, an embed) or a public file, which shows it but lets nobody read it.
+ * No other address is opened for another origin's page: a server's route acts when opened (`/__open-in-editor` opens a
+ * file), and a module or a source file has no use as a page.
+ *
+ * Vite checks `Host` first, on both ports, against `server.allowedHosts`: a page that reaches `127.0.0.1` through its
+ * own domain (DNS rebinding) is not told apart here, since it is same-origin for its browser, and over plain HTTP on
+ * that domain its browser sends no `Sec-Fetch-*`.
+ *
+ * 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 as an address parser reads it, without the query (`/frame.html`): the routes behind the guards read the
+     * same, so `//x/__forgebook/api/stories` or `/./__forgebook/api/stories` is the route it would reach.
+     */
+    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 unless it opens a page or a public file, 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.
+ * @param isPublic - whether a path names a file of the public folder; asked only of another origin's navigation.
+ */
+export declare const catalogueAnswer: (request: RequestFacts, framedPages: ReadonlySet<string>, isPublic?: (path: string) => boolean) => 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,172 @@
+/**
+ * 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 opens one of its pages (a link, an embed) or a public file, which shows it but lets nobody read it.
+ * No other address is opened for another origin's page: a server's route acts when opened (`/__open-in-editor` opens a
+ * file), and a module or a source file has no use as a page.
+ *
+ * Vite checks `Host` first, on both ports, against `server.allowedHosts`: a page that reaches `127.0.0.1` through its
+ * own domain (DNS rebinding) is not told apart here, since it is same-origin for its browser, and over plain HTTP on
+ * that domain its browser sends no `Sec-Fetch-*`.
+ *
+ * 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 catalogue's pages, by their addresses: what another origin's page may open, with public files and framed routes. */
+const CATALOGUE_PAGES = new Set(["/", "/index.html", FRAME_PAGE_PATH]);
+/** 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 unless it opens a page or a public file, 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.
+ * @param isPublic - whether a path names a file of the public folder; asked only of another origin's navigation.
+ */
+export const catalogueAnswer = (request, framedPages, isPublic = () => false) => {
+    if (isFromAnotherOrigin(request))
+        return "refuse";
+    const isOpenable = () => CATALOGUE_PAGES.has(request.path) ||
+        (isDocumentRequest(request) && (framedPages.has(request.path) || isPublic(request.path)));
+    if (isAnyFromAnotherOrigin(request) && !isOpenable())
+        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;