forgebook 0.1.8 → 0.2.0

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

@@ -9,6 +9,10 @@
  * requests). An `initialize` puts the session in the handshake era; a request carrying the version in `_meta` is
  * answered statelessly. The tools never change while the server runs, so their list is cacheable and public.
  *
+ * The MCP Apps extension (`io.modelcontextprotocol/ui`, specification 2026-01-26) is offered only to a client that
+ * declares it, read from the handshake or from the request's own `_meta`: what depends on it is a function of what the
+ * client said, never of the connection, and any other client gets exactly the answers of a server without it.
+ *
  * @module
  */
 /** The protocol's current version, stateless. */
@@ -17,6 +21,10 @@ export declare const MODERN_VERSION = "2026-07-28";
 export declare const HANDSHAKE_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26"];
 /** Every version served, for `server/discover` and for the error a client with another one gets. */
 export declare const SUPPORTED_VERSIONS: readonly string[];
+/** The MCP Apps extension's identifier, in a client's and the server's capabilities. */
+export declare const UI_EXTENSION = "io.modelcontextprotocol/ui";
+/** The content type of an app's resource, the only one the extension defines. */
+export declare const APP_MIME_TYPE = "text/html;profile=mcp-app";
 /** What a tool gives back: its answer as data, and whether it is a failure the agent should read. */
 export type McpToolResult = {
     /** The answer, as JSON; also sent as text, as the protocol asks. */
@@ -43,6 +51,29 @@ export type McpTool = {
     readonly inputSchema: Readonly<Record<string, unknown>>;
     /** Runs it with the arguments the client sent. */
     readonly call: (args: Readonly<Record<string, unknown>>) => Promise<McpToolResult>;
+    /**
+     * The `ui://` resource a client shows this tool's answer in. A tool that has one is listed only to a client that
+     * renders apps: the others have no use for it, and every tool listed is words in the agent's context.
+     */
+    readonly appResource?: string;
+};
+/** What reading an app's resource gives. */
+export type McpAppContent = {
+    /** The page, one HTML5 document. */
+    readonly html: string;
+    /** The origins the page may frame; the host blocks every other (`frame-src`). */
+    readonly frameDomains: readonly string[];
+};
+/** An app's resource: a `ui://` page a client that renders apps shows a tool's answer in. */
+export type McpAppResource = {
+    /** Its address (`ui://forgebook/story-preview`). */
+    readonly uri: string;
+    /** Its name, for the client's lists. */
+    readonly name: string;
+    /** What it shows. */
+    readonly description: string;
+    /** Reads it. A host may do so at any time, before any tool is called, so it starts nothing. */
+    readonly read: () => Promise<McpAppContent>;
 };
 /** Who the server is, and what it tells an agent about itself. */
 export type McpServer = {
@@ -55,11 +86,15 @@ export type McpServer = {
     readonly instructions: string | undefined;
     /** Its tools. */
     readonly tools: readonly McpTool[];
+    /** The apps' resources its tools show their answers in; none by default. */
+    readonly apps?: readonly McpAppResource[];
 };
-/** What a session remembers between messages: whether the client opened it with the handshake. */
+/** What a session remembers between messages: what the client said when it opened it with the handshake. */
 export type McpSession = {
     /** The handshake version agreed on `initialize`; none in the stateless era or before any request. */
     readonly handshakeVersion: string | undefined;
+    /** Whether the handshake declared that the client renders apps. */
+    readonly isAppHost: boolean;
 };
 /** A new session: no handshake yet. */
 export declare const NEW_SESSION: McpSession;
@@ -79,4 +114,3 @@ export type McpStep = {
  * @returns the answer to write (none for a notification) and the session after the message.
  */
 export declare const answerMcpMessage: (line: string, session: McpSession, server: McpServer) => Promise<McpStep>;
-//# sourceMappingURL=mcpProtocol.d.ts.map

package/dist/src/vite/mcpProtocol.js

@@ -9,6 +9,10 @@
  * requests). An `initialize` puts the session in the handshake era; a request carrying the version in `_meta` is
  * answered statelessly. The tools never change while the server runs, so their list is cacheable and public.
  *
+ * The MCP Apps extension (`io.modelcontextprotocol/ui`, specification 2026-01-26) is offered only to a client that
+ * declares it, read from the handshake or from the request's own `_meta`: what depends on it is a function of what the
+ * client said, never of the connection, and any other client gets exactly the answers of a server without it.
+ *
  * @module
  */
 /** The protocol's current version, stateless. */
@@ -17,6 +21,10 @@ export const MODERN_VERSION = "2026-07-28";
 export const HANDSHAKE_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26"];
 /** Every version served, for `server/discover` and for the error a client with another one gets. */
 export const SUPPORTED_VERSIONS = [MODERN_VERSION, ...HANDSHAKE_VERSIONS];
+/** The MCP Apps extension's identifier, in a client's and the server's capabilities. */
+export const UI_EXTENSION = "io.modelcontextprotocol/ui";
+/** The content type of an app's resource, the only one the extension defines. */
+export const APP_MIME_TYPE = "text/html;profile=mcp-app";
 /** The `_meta` keys of the current era. */
 const META = {
     version: "io.modelcontextprotocol/protocolVersion",
@@ -29,12 +37,14 @@ const ERRORS = {
     invalidRequest: -32600,
     methodNotFound: -32601,
     invalidParams: -32602,
+    internal: -32603,
+    resourceNotFoundBefore: -32002,
     unsupportedVersion: -32022
 };
 /** How long a client may keep the tools' list, in ms: they never change while the server runs. */
 const TOOLS_TTL_MS = 300_000;
 /** A new session: no handshake yet. */
-export const NEW_SESSION = { handshakeVersion: undefined };
+export const NEW_SESSION = { handshakeVersion: undefined, isAppHost: false };
 /** Whether a value is a plain object. */
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** An error answer. */
@@ -73,11 +83,33 @@ const modernProblem = (id, meta) => {
         });
     return undefined;
 };
+/** Whether a client's capabilities say it renders the only kind of app there is. */
+const declaresApps = (capabilities) => {
+    if (!isRecord(capabilities) || !isRecord(capabilities["extensions"]))
+        return false;
+    const settings = capabilities["extensions"][UI_EXTENSION];
+    return (isRecord(settings) &&
+        Array.isArray(settings["mimeTypes"]) &&
+        settings["mimeTypes"].includes(APP_MIME_TYPE));
+};
+/** What the server offers this client: more than its tools only when it has apps and the client renders them. */
+const capabilitiesFor = (server, isAppHost) => isAppHost && server.apps !== undefined
+    ? { tools: {}, resources: {}, extensions: { [UI_EXTENSION]: {} } }
+    : { tools: {} };
+/**
+ * The cache scope of an answer that depends on who asks. A shared cache must not hand one that names apps to a client
+ * that renders none.
+ */
+const scopeFor = (isAppHost) => (isAppHost ? "private" : "public");
+/** The tools a client is offered: an app's only to one that renders it. */
+const toolsFor = (server, isAppHost) => server.tools.filter((tool) => tool.appResource === undefined || isAppHost);
 /** The tools' list as the protocol gives it. */
-const toolList = (server) => server.tools.map((tool) => ({
+const toolList = (server, isAppHost) => toolsFor(server, isAppHost).map((tool) => ({
     name: tool.name,
     description: tool.description,
-    inputSchema: tool.inputSchema
+    inputSchema: tool.inputSchema,
+    // biome-ignore lint/style/useNamingConvention: the protocol names this field
+    ...(tool.appResource === undefined ? {} : { _meta: { ui: { resourceUri: tool.appResource } } })
 }));
 /** A tool's answer as the protocol gives it: its JSON as text and as structured content, then its pictures. */
 const toolResult = async (tool, args) => {
@@ -99,16 +131,64 @@ const toolResult = async (tool, args) => {
         isError
     };
 };
+/**
+ * An app's resource as `resources/read` gives it. The page names the session's origin, so it is never kept
+ * (`ttlMs: 0`), which the handshake era has no way to say.
+ */
+const readApp = async (app, isModern) => {
+    const { html, frameDomains } = await app.read();
+    const content = {
+        uri: app.uri,
+        mimeType: APP_MIME_TYPE,
+        text: html,
+        // biome-ignore lint/style/useNamingConvention: the protocol names this field
+        _meta: { ui: { csp: { frameDomains }, prefersBorder: true } }
+    };
+    return { contents: [content], ...(isModern ? { ttlMs: 0, cacheScope: "private" } : {}) };
+};
+/** Answers a request for the apps' resources, or none for another method or a server without apps. */
+const answerResources = async (server, id, method, params, { isModern, isAppHost }, finish) => {
+    const { apps } = server;
+    if (apps === undefined || !isAppHost)
+        return undefined;
+    const kept = isModern ? { ttlMs: TOOLS_TTL_MS, cacheScope: "private" } : {};
+    if (method === "resources/list") {
+        const resources = apps.map(({ uri, name, description }) => ({
+            uri,
+            name,
+            description,
+            mimeType: APP_MIME_TYPE
+        }));
+        return finish({ resources, ...kept });
+    }
+    if (method === "resources/templates/list")
+        return finish({ resourceTemplates: [], ...kept });
+    if (method !== "resources/read")
+        return undefined;
+    const uri = params["uri"];
+    const app = apps.find((each) => each.uri === uri);
+    if (app === undefined)
+        return failure(id, isModern ? ERRORS.invalidParams : ERRORS.resourceNotFoundBefore, "Resource not found", {
+            uri
+        });
+    try {
+        return finish(await readApp(app, isModern));
+    }
+    catch (error) {
+        return failure(id, ERRORS.internal, error instanceof Error ? error.message : String(error));
+    }
+};
 /** Answers a request in either era: the methods both share. */
-const answerRequest = async (server, id, method, params, isModern) => {
+const answerRequest = async (server, id, method, params, asker) => {
+    const { isModern, isAppHost } = asker;
     const finish = (result) => success(id, isModern ? modernResult(server, result) : result);
     if (method === "tools/list")
         return finish(isModern
-            ? { tools: toolList(server), ttlMs: TOOLS_TTL_MS, cacheScope: "public" }
-            : { tools: toolList(server) });
+            ? { tools: toolList(server, isAppHost), ttlMs: TOOLS_TTL_MS, cacheScope: scopeFor(isAppHost) }
+            : { tools: toolList(server, isAppHost) });
     if (method === "tools/call") {
         const name = params["name"];
-        const tool = server.tools.find((each) => each.name === name);
+        const tool = toolsFor(server, isAppHost).find((each) => each.name === name);
         if (tool === undefined)
             return failure(id, ERRORS.invalidParams, `Unknown tool: ${String(name)}`);
         const args = params["arguments"];
@@ -117,12 +197,13 @@ const answerRequest = async (server, id, method, params, isModern) => {
     if (method === "server/discover" && isModern)
         return finish({
             supportedVersions: SUPPORTED_VERSIONS,
-            capabilities: { tools: {} },
+            capabilities: capabilitiesFor(server, isAppHost),
             ...(server.instructions === undefined ? {} : { instructions: server.instructions }),
             ttlMs: TOOLS_TTL_MS,
-            cacheScope: "public"
+            cacheScope: scopeFor(isAppHost)
         });
-    return failure(id, ERRORS.methodNotFound, `Method not found: ${method}`);
+    const resources = await answerResources(server, id, method, params, asker, finish);
+    return resources ?? failure(id, ERRORS.methodNotFound, `Method not found: ${method}`);
 };
 /** Reads one line as a JSON-RPC message. */
 const readMessage = (line) => {
@@ -152,13 +233,14 @@ const readMessage = (line) => {
 const initialized = (server, id, params) => {
     const asked = params["protocolVersion"];
     const version = HANDSHAKE_VERSIONS.find((each) => each === asked) ?? HANDSHAKE_VERSIONS[0];
+    const isAppHost = declaresApps(params["capabilities"]);
     const result = {
         protocolVersion: version,
-        capabilities: { tools: {} },
+        capabilities: capabilitiesFor(server, isAppHost),
         serverInfo: server.info,
         ...(server.instructions === undefined ? {} : { instructions: server.instructions })
     };
-    return { reply: JSON.stringify(success(id, result)), session: { handshakeVersion: version } };
+    return { reply: JSON.stringify(success(id, result)), session: { handshakeVersion: version, isAppHost } };
 };
 /**
  * Answers one message the client sent: a line of JSON-RPC.
@@ -182,11 +264,14 @@ export const answerMcpMessage = async (line, session, server) => {
             return success(id, {});
         const meta = params["_meta"];
         if (isRecord(meta) && META.version in meta)
-            return modernProblem(id, meta) ?? (await answerRequest(server, id, method, params, true));
+            return (modernProblem(id, meta) ??
+                (await answerRequest(server, id, method, params, {
+                    isModern: true,
+                    isAppHost: declaresApps(meta[META.capabilities])
+                })));
         if (session.handshakeVersion !== undefined)
-            return answerRequest(server, id, method, params, false);
+            return answerRequest(server, id, method, params, { isModern: false, isAppHost: session.isAppHost });
         return failure(id, ERRORS.invalidParams, `A request needs ${META.version} in _meta, or an initialize first`);
     };
     return { reply: JSON.stringify(await answer()), session };
 };
-//# sourceMappingURL=mcpProtocol.js.map

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

@@ -0,0 +1,17 @@
+/**
+ * A file's summary: the first paragraph of its leading `@module` comment, read from its text alone.
+ *
+ * @remarks
+ * A component's page shows it as its lead before any TypeScript program exists, so reading it must not load the
+ * compiler in the dev server's thread; the docs read it the same way. Pure: text in, text out.
+ *
+ * @module
+ */
+/**
+ * The first paragraph of a file's leading comment, its `@module` TSDoc: what the file holds, in a sentence. A
+ * component's own TSDoc is often a bare name ("A button."); its file's comment says what it is and does.
+ *
+ * @param text - the file's text.
+ * @returns the paragraph on one line, or an empty text when the file does not open with a `@module` comment.
+ */
+export declare const moduleSummaryOf: (text: string) => string;

package/dist/src/vite/moduleSummary.js

@@ -0,0 +1,40 @@
+/**
+ * A file's summary: the first paragraph of its leading `@module` comment, read from its text alone.
+ *
+ * @remarks
+ * A component's page shows it as its lead before any TypeScript program exists, so reading it must not load the
+ * compiler in the dev server's thread; the docs read it the same way. Pure: text in, text out.
+ *
+ * @module
+ */
+/** A file's start up to its first comment: a shebang and blank space, which come before any leading comment. */
+const BEFORE_COMMENT = /^(?:#!.*\r?\n)?\s*/;
+/**
+ * The first paragraph of a file's leading comment, its `@module` TSDoc: what the file holds, in a sentence. A
+ * component's own TSDoc is often a bare name ("A button."); its file's comment says what it is and does.
+ *
+ * @param text - the file's text.
+ * @returns the paragraph on one line, or an empty text when the file does not open with a `@module` comment.
+ */
+export const moduleSummaryOf = (text) => {
+    const start = BEFORE_COMMENT.exec(text)?.[0].length ?? 0;
+    const end = text.indexOf("*/", start);
+    if (!text.startsWith("/**", start) || end < 0)
+        return "";
+    const comment = text.slice(start, end + 2);
+    if (!comment.includes("@module"))
+        return "";
+    const lines = comment
+        .replace(/^\/\*\*/, "")
+        .replace(/\*\/$/, "")
+        .split("\n")
+        .map((line) => line.replace(/^\s*\* ?/, "").trimEnd());
+    const first = lines.findIndex((line) => line !== "");
+    const paragraph = [];
+    for (const line of lines.slice(Math.max(first, 0))) {
+        if (line === "" || line.startsWith("@"))
+            break;
+        paragraph.push(line);
+    }
+    return paragraph.join(" ").replace(/\s+/g, " ").trim();
+};

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

@@ -0,0 +1,50 @@
+/**
+ * The tokens nearest a value an agent wrote by hand: what to write instead of a raw colour or size.
+ *
+ * @remarks
+ * Pure. An agent takes the first answer, so the answer has to say whether it is really near (`isClose`) and why there is
+ * none (`reason`): an empty list read as "no such token" is how a raw value ends up in the code. Colours compare in
+ * Oklab, where a distance follows what the eye sees, which RGB does not; alpha counts, or a solid black would pass for a
+ * translucent scrim. Tokens are read back from the CSS they are written as, so tokens and written values take one path.
+ *
+ * @module
+ */
+import type { DesignToken } from "./designTokens.ts";
+/** A token near a value. */
+export type TokenMatch = {
+    /** The token. */
+    readonly name: string;
+    /** Its value there. */
+    readonly value: string;
+    /** The theme that value belongs to; none for the base. */
+    readonly mode?: string;
+    /** The token it is an alias of: the base token is often the one to write. */
+    readonly alias?: string;
+    /** How far, in the answer's `unit`. */
+    readonly distance: number;
+    /** Whether it is the same value. */
+    readonly isExact: boolean;
+    /** Whether it is near enough to use in its place. */
+    readonly isClose: boolean;
+};
+/** The answer. */
+export type NearestTokens = {
+    /** The token type compared with; none when it could not be told. */
+    readonly type: string | undefined;
+    /** What `distance` counts. */
+    readonly unit: string | undefined;
+    /** Up to three tokens, nearest first. */
+    readonly matches: readonly TokenMatch[];
+    /** How many tokens of the type could not be compared (a colour space this cannot place). */
+    readonly uncompared: number;
+    /** Why the question could not be answered: the value or the type could not be read. */
+    readonly reason?: string;
+};
+/**
+ * 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 declare const nearestTokens: (tokens: readonly DesignToken[], value: string, asked: string | undefined) => NearestTokens;

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
+    };
+};