forgebook 0.1.8 → 0.3.0

package/dist/src/vite/indexedParameters.js

@@ -0,0 +1,130 @@
+import { deviceSettingProblem, isDeviceOrientation } from "../deviceView.js";
+import { REQUIRED_FIRST_LAYOUTS } from "../propGroups.js";
+import { keyName, parameter, unwrapped } from "./indexFields.js";
+/** Why `parameters.device` cannot be read as it is written. */
+const DEVICE_PROBLEM = '`parameters.device` must be written as a plain object (`{ frame: true, model: "iphone-16" }`)';
+/**
+ * A boolean parameter: `true` or `false` written plainly, `undefined` when none, or a problem otherwise.
+ *
+ * @param value - the parameter's value.
+ * @param name - its name, for the problem.
+ */
+const booleanOf = (value, name) => {
+    if (value === undefined)
+        return undefined;
+    if (value.type === "Literal" && typeof value.value === "boolean")
+        return value.value;
+    return new Error(`\`${name}\` must be written as a plain \`true\` or \`false\``);
+};
+/**
+ * A plain string field of a device setting: `undefined` when none, the string, or a problem.
+ *
+ * @param value - the field's value.
+ * @param name - its name, for the problem.
+ */
+const stringOf = (value, name) => {
+    if (value === undefined)
+        return undefined;
+    if (value.type === "Literal" && typeof value.value === "string")
+        return value.value;
+    return new Error(`\`parameters.device.${name}\` must be written as a plain string`);
+};
+/**
+ * The fields `parameters.device` writes, by name, or a problem when it is written by code or names a field the
+ * setting has not.
+ *
+ * @param value - the parameter's value.
+ */
+const deviceFields = (value) => {
+    if (value.type !== "ObjectExpression")
+        return new Error(DEVICE_PROBLEM);
+    const fields = new Map();
+    for (const property of value.properties) {
+        const name = property.type === "Property" && !property.computed ? keyName(property.key) : undefined;
+        if (property.type !== "Property" || name === undefined)
+            return new Error(DEVICE_PROBLEM);
+        if (!["frame", "model", "orientation", "touch", "edgeToEdge"].includes(name))
+            return new Error(`\`parameters.device\` has no field \`${name}\`: it takes frame, model, orientation, touch and edgeToEdge`);
+        fields.set(name, unwrapped(property.value));
+    }
+    return fields;
+};
+/**
+ * `parameters.device`: `undefined` when none, the setting with the fields it writes, or a problem when it is written
+ * by code, names a field the setting has not, or a model or an orientation that is none.
+ *
+ * @param value - the parameter's value.
+ */
+const deviceOf = (value) => {
+    if (value === undefined)
+        return undefined;
+    const fields = deviceFields(value);
+    if (fields instanceof Error)
+        return fields;
+    const frame = booleanOf(fields.get("frame"), "parameters.device.frame");
+    if (frame instanceof Error)
+        return frame;
+    const touch = booleanOf(fields.get("touch"), "parameters.device.touch");
+    if (touch instanceof Error)
+        return touch;
+    const edgeToEdge = booleanOf(fields.get("edgeToEdge"), "parameters.device.edgeToEdge");
+    if (edgeToEdge instanceof Error)
+        return edgeToEdge;
+    const model = stringOf(fields.get("model"), "model");
+    if (model instanceof Error)
+        return model;
+    const orientation = stringOf(fields.get("orientation"), "orientation");
+    if (orientation instanceof Error)
+        return orientation;
+    if (orientation !== undefined && !isDeviceOrientation(orientation))
+        return new Error(`\`parameters.device\`: "${orientation}" is no orientation; write portrait or landscape`);
+    const setting = {
+        ...(frame === undefined ? {} : { frame }),
+        ...(model === undefined ? {} : { model }),
+        ...(orientation === undefined ? {} : { orientation }),
+        ...(touch === undefined ? {} : { touch }),
+        ...(edgeToEdge === undefined ? {} : { edgeToEdge })
+    };
+    const problem = deviceSettingProblem(setting);
+    return problem === undefined ? setting : new Error(`\`parameters.device\`: ${problem}`);
+};
+/**
+ * `parameters.requiredFirst`: `undefined` when none, `"in-groups"`, `"section"` or `false` written plainly, or a
+ * problem otherwise.
+ *
+ * @param value - the parameter's value.
+ */
+const requiredFirstOf = (value) => {
+    if (value === undefined)
+        return undefined;
+    const written = value.type === "Literal" ? value.value : undefined;
+    const layout = REQUIRED_FIRST_LAYOUTS.find((each) => each === written);
+    if (layout !== undefined)
+        return layout;
+    return new Error('`parameters.requiredFirst` must be written as a plain `"in-groups"`, `"section"` or `false`');
+};
+/**
+ * The parameters only the index reads, each only when written, or the first problem.
+ *
+ * @param fields - the story's or the meta's fields.
+ */
+export const indexedParameters = (fields) => {
+    const touch = booleanOf(parameter(fields, "touch"), "parameters.touch");
+    if (touch instanceof Error)
+        return touch;
+    const logic = booleanOf(parameter(fields, "logic"), "parameters.logic");
+    if (logic instanceof Error)
+        return logic;
+    const device = deviceOf(parameter(fields, "device"));
+    if (device instanceof Error)
+        return device;
+    const requiredFirst = requiredFirstOf(parameter(fields, "requiredFirst"));
+    if (requiredFirst instanceof Error)
+        return requiredFirst;
+    return {
+        ...(touch === undefined ? {} : { isTouch: touch }),
+        ...(logic === undefined ? {} : { isLogic: logic }),
+        ...(device === undefined ? {} : { device }),
+        ...(requiredFirst === undefined ? {} : { requiredFirst })
+    };
+};

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;