@divlet/web 0.0.2 → 0.0.4

package/dist/lib/mcp-provider.d.ts

@@ -0,0 +1,70 @@
+import type { BrowserTool, ToolLimits, ToolRegistry } from './mcp-tools.ts';
+export { defineTools, compileSchema, ToolError, DEFAULT_TOOL_LIMITS } from './mcp-tools.ts';
+export type { BrowserTool, ToolAnnotations, ToolDescriptor, ToolExecution, ToolLimits, ToolOutcome, ToolRegistry, JsonSchema } from './mcp-tools.ts';
+export { registerWebMcpTools } from './webmcp.ts';
+export type { WebMcpModelContext } from './webmcp.ts';
+export declare const PROTOCOL_VERSION = "2026-07-28";
+export declare const SUPPORTED_VERSIONS: readonly string[];
+/** The discovery contract between a page and an agent transport. Project-specific, versioned, not an MCP standard. */
+export declare const ENDPOINT_PROTOCOL = "browser-mcp/1";
+/** Where the endpoint lives on the page's global object: a registered symbol, so it collides with no page or browser name. */
+export declare const ENDPOINT_KEY: unique symbol;
+/** Optional static hint (`<meta name="browser-mcp" content="browser-mcp/1">`): the page intends to expose a provider. */
+export declare const ENDPOINT_META = "browser-mcp";
+/** JSON-RPC and MCP error codes this provider emits. `TOO_MANY_REQUESTS` is application-defined, outside the reserved range. */
+export declare const ERRORS: Readonly<{
+    PARSE: -32700;
+    INVALID_REQUEST: -32600;
+    METHOD_NOT_FOUND: -32601;
+    INVALID_PARAMS: -32602;
+    INTERNAL: -32603;
+    UNSUPPORTED_VERSION: -32022;
+    TOO_MANY_REQUESTS: -31001;
+}>;
+export interface ProviderLimits extends ToolLimits {
+    /** Largest accepted request or emitted response, in UTF-8 bytes. */
+    readonly messageBytes: number;
+    /** Requests that may be executing at once; further requests are refused rather than queued without bound. */
+    readonly concurrent: number;
+}
+export declare const DEFAULT_PROVIDER_LIMITS: ProviderLimits;
+export interface ProviderOptions {
+    readonly name: string;
+    readonly version: string;
+    readonly title?: string;
+    readonly instructions?: string;
+    readonly tools: readonly BrowserTool[] | ToolRegistry;
+    readonly limits?: Partial<ProviderLimits>;
+}
+type Id = string | number;
+type Response = {
+    jsonrpc: '2.0';
+    id: Id | null;
+    result?: Record<string, unknown>;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+};
+export interface BrowserMcpProvider {
+    /** Handle one JSON-RPC message (parsed JSON). Resolves to the response, or `null` for notifications and cancelled requests. */
+    handle(message: unknown): Promise<Response | null>;
+    /** Handle one message as JSON text and answer with JSON text (or `null`), enforcing the byte budget in both directions. */
+    handleText(text: string): Promise<string | null>;
+    /** Abort every running call; later requests are refused. */
+    close(): void;
+    readonly registry: ToolRegistry;
+}
+/** The object a page publishes at `globalThis[ENDPOINT_KEY]`. `instance` changes with every provider, so a transport sees replacement. */
+export interface BrowserMcpEndpoint {
+    readonly protocol: typeof ENDPOINT_PROTOCOL;
+    readonly instance: string;
+    handle(text: string): Promise<string | null>;
+}
+export declare function createBrowserMcpProvider(options: ProviderOptions): BrowserMcpProvider;
+/**
+ * Publish the provider for an agent transport on this page. The endpoint is non-writable and non-enumerable; publishing a second
+ * provider on the same page is refused. Returns a function that withdraws it (and closes the provider).
+ */
+export declare function exposeBrowserMcp(provider: BrowserMcpProvider, target?: object): () => void;

package/dist/lib/mcp-provider.js

@@ -0,0 +1,179 @@
+/*
+ * Owns: the browser-side MCP provider — a JSON-RPC 2.0 handler for MCP protocol revision 2026-07-28 over the canonical tool
+ * registry — and the page's discovery endpoint a local agent transport looks for. Excludes: how messages reach the page
+ * (that is the agent's transport), application semantics (the registered tools own them) and any host privilege: the
+ * provider only answers messages handed to it and never calls out of the page.
+ *
+ * Revision 2026-07-28 is stateless: there is no `initialize` handshake. Every request carries its protocol version and the
+ * client capabilities in `params._meta`, and each request is answered independently. Implemented methods: `server/discover`,
+ * `tools/list`, `tools/call` and the `notifications/cancelled` notification. Resources, prompts, subscriptions, multi
+ * round-trip input and tasks are not offered and are not advertised.
+ */
+import { defineTools, boundedJson } from "./mcp-tools.js";
+export { defineTools, compileSchema, ToolError, DEFAULT_TOOL_LIMITS } from "./mcp-tools.js";
+export { registerWebMcpTools } from "./webmcp.js";
+export const PROTOCOL_VERSION = '2026-07-28';
+export const SUPPORTED_VERSIONS = Object.freeze([PROTOCOL_VERSION]);
+/** The discovery contract between a page and an agent transport. Project-specific, versioned, not an MCP standard. */
+export const ENDPOINT_PROTOCOL = 'browser-mcp/1';
+/** Where the endpoint lives on the page's global object: a registered symbol, so it collides with no page or browser name. */
+export const ENDPOINT_KEY = Symbol.for(ENDPOINT_PROTOCOL);
+/** Optional static hint (`<meta name="browser-mcp" content="browser-mcp/1">`): the page intends to expose a provider. */
+export const ENDPOINT_META = 'browser-mcp';
+const META_VERSION = 'io.modelcontextprotocol/protocolVersion';
+const META_CAPABILITIES = 'io.modelcontextprotocol/clientCapabilities';
+const META_SERVER = 'io.modelcontextprotocol/serverInfo';
+/** Required caching hints for discovery and list results. The tool set belongs to one page instance and may change on reload. */
+const CACHE = Object.freeze({ ttlMs: 0, cacheScope: 'private' });
+/** JSON-RPC and MCP error codes this provider emits. `TOO_MANY_REQUESTS` is application-defined, outside the reserved range. */
+export const ERRORS = Object.freeze({ PARSE: -32700, INVALID_REQUEST: -32600, METHOD_NOT_FOUND: -32601, INVALID_PARAMS: -32602, INTERNAL: -32603, UNSUPPORTED_VERSION: -32022, TOO_MANY_REQUESTS: -31001 });
+export const DEFAULT_PROVIDER_LIMITS = Object.freeze({ messageBytes: 2 * 1024 * 1024, concurrent: 32, resultBytes: 1024 * 1024, timeoutMs: 60_000 });
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const validId = (id) => (typeof id === 'string' && id.length <= 256) || Number.isSafeInteger(id);
+const encoder = new TextEncoder();
+export function createBrowserMcpProvider(options) {
+    if (!options || typeof options.name !== 'string' || !options.name || typeof options.version !== 'string' || !options.version)
+        throw new TypeError('A browser MCP provider needs a name and a version.');
+    const limits = { ...DEFAULT_PROVIDER_LIMITS, ...options.limits };
+    const registry = 'descriptors' in options.tools && typeof options.tools.run === 'function'
+        ? options.tools
+        : defineTools(options.tools, limits);
+    const serverInfo = Object.freeze({ name: options.name, version: options.version, ...(options.title ? { title: options.title } : {}) });
+    const running = new Map();
+    let closed = false;
+    const meta = () => ({ [META_SERVER]: serverInfo });
+    const ok = (id, result) => ({ jsonrpc: '2.0', id, result: { resultType: 'complete', ...result, _meta: meta() } });
+    const fail = (id, code, message, data) => ({ jsonrpc: '2.0', id, error: data === undefined ? { code, message } : { code, message, data } });
+    /** The per-request `_meta` this revision requires; `null` when the request may proceed. */
+    function admit(id, params) {
+        const fields = params._meta;
+        if (!isObject(fields))
+            return fail(id, ERRORS.INVALID_PARAMS, `Missing _meta: every request must carry ${META_VERSION} and ${META_CAPABILITIES}.`);
+        const version = fields[META_VERSION];
+        if (typeof version !== 'string' || !version)
+            return fail(id, ERRORS.INVALID_PARAMS, `Missing _meta["${META_VERSION}"].`);
+        if (!isObject(fields[META_CAPABILITIES]))
+            return fail(id, ERRORS.INVALID_PARAMS, `Missing _meta["${META_CAPABILITIES}"].`);
+        if (!SUPPORTED_VERSIONS.includes(version))
+            return fail(id, ERRORS.UNSUPPORTED_VERSION, 'Unsupported protocol version', { supported: [...SUPPORTED_VERSIONS], requested: version.slice(0, 64) });
+        return null;
+    }
+    async function call(id, params) {
+        const name = params.name;
+        if (typeof name !== 'string' || !registry.has(name))
+            return fail(id, ERRORS.INVALID_PARAMS, `Unknown tool: ${typeof name === 'string' ? name.slice(0, 128) : String(name)}`);
+        if (params.arguments !== undefined && !isObject(params.arguments))
+            return fail(id, ERRORS.INVALID_PARAMS, 'tools/call arguments must be an object.');
+        if (running.size >= limits.concurrent)
+            return fail(id, ERRORS.TOO_MANY_REQUESTS, `Too many concurrent requests (limit ${limits.concurrent}).`);
+        if (running.has(id))
+            return fail(id, ERRORS.INVALID_REQUEST, 'A request with this id is still in progress.');
+        const controller = new AbortController();
+        running.set(id, controller);
+        try {
+            const outcome = await registry.run(name, params.arguments ?? {}, { signal: controller.signal });
+            // A cancelled request gets no response (notifications/cancelled); a closed provider answers nothing further.
+            if (controller.signal.aborted)
+                return null;
+            if (outcome.ok) {
+                const structured = isObject(outcome.value) ? { structuredContent: outcome.value } : {};
+                return ok(id, { content: [{ type: 'text', text: outcome.json }], ...structured, isError: false });
+            }
+            const { code, message, details } = outcome.error;
+            const text = `${code}: ${message}${details === undefined ? '' : `\n${JSON.stringify(details)}`}`;
+            return ok(id, { content: [{ type: 'text', text }], structuredContent: { error: outcome.error }, isError: true });
+        }
+        finally {
+            running.delete(id);
+        }
+    }
+    async function handle(message) {
+        if (!isObject(message) || message.jsonrpc !== '2.0')
+            return fail(isObject(message) && validId(message.id) ? message.id : null, ERRORS.INVALID_REQUEST, 'Invalid request: expected one JSON-RPC 2.0 object.');
+        const { id, method } = message;
+        const params = message.params === undefined ? {} : message.params;
+        if (typeof method !== 'string') {
+            // Responses to requests this provider never sends are ignored rather than answered.
+            return 'result' in message || 'error' in message ? null : fail(validId(id) ? id : null, ERRORS.INVALID_REQUEST, 'Invalid request: method must be a string.');
+        }
+        if (id === undefined) {
+            // Notifications: only cancellation has meaning here; anything else is ignored as the specification requires.
+            if (method === 'notifications/cancelled' && isObject(params) && validId(params.requestId))
+                running.get(params.requestId)?.abort();
+            return null;
+        }
+        if (!validId(id))
+            return fail(null, ERRORS.INVALID_REQUEST, 'Invalid request: id must be a string or an integer.');
+        if (!isObject(params))
+            return fail(id, ERRORS.INVALID_PARAMS, 'params must be an object.');
+        if (closed)
+            return fail(id, ERRORS.INTERNAL, 'The provider has closed.');
+        if (method === 'initialize')
+            return fail(id, ERRORS.METHOD_NOT_FOUND, `This provider implements only the stateless MCP revision(s) ${SUPPORTED_VERSIONS.join(', ')}; there is no initialize handshake.`, { supported: [...SUPPORTED_VERSIONS] });
+        const refused = admit(id, params);
+        if (refused)
+            return refused;
+        switch (method) {
+            case 'server/discover':
+                return ok(id, { supportedVersions: [...SUPPORTED_VERSIONS], capabilities: { tools: {} }, ...(options.instructions ? { instructions: options.instructions } : {}), ...CACHE });
+            case 'tools/list':
+                if (params.cursor !== undefined)
+                    return fail(id, ERRORS.INVALID_PARAMS, 'Invalid cursor: the tool list has a single page.');
+                return ok(id, { tools: registry.descriptors.map(descriptor => JSON.parse(JSON.stringify(descriptor))), ...CACHE });
+            case 'tools/call':
+                return call(id, params);
+            default:
+                return fail(id, ERRORS.METHOD_NOT_FOUND, `Method not found: ${method.slice(0, 128)}`);
+        }
+    }
+    async function handleText(text) {
+        if (typeof text !== 'string')
+            return JSON.stringify(fail(null, ERRORS.INVALID_REQUEST, 'Messages are JSON text.'));
+        if (text.length > limits.messageBytes || encoder.encode(text).byteLength > limits.messageBytes)
+            return JSON.stringify(fail(null, ERRORS.INVALID_REQUEST, `The message exceeds ${limits.messageBytes} bytes.`));
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            return JSON.stringify(fail(null, ERRORS.PARSE, 'Parse error.'));
+        }
+        let response;
+        try {
+            response = await handle(message);
+        }
+        catch (error) {
+            response = fail(isObject(message) && validId(message.id) ? message.id : null, ERRORS.INTERNAL, String(error?.message || error).slice(0, 1000));
+        }
+        if (!response)
+            return null;
+        try {
+            return boundedJson(response, limits.messageBytes);
+        }
+        catch (error) {
+            return JSON.stringify(fail(response.id, ERRORS.INTERNAL, String(error?.message || error)));
+        }
+    }
+    return Object.freeze({
+        handle, handleText, registry,
+        close() { closed = true; for (const controller of running.values())
+            controller.abort(); running.clear(); },
+    });
+}
+/**
+ * Publish the provider for an agent transport on this page. The endpoint is non-writable and non-enumerable; publishing a second
+ * provider on the same page is refused. Returns a function that withdraws it (and closes the provider).
+ */
+export function exposeBrowserMcp(provider, target = globalThis) {
+    if (Object.getOwnPropertyDescriptor(target, ENDPOINT_KEY)?.value)
+        throw new Error('A browser MCP endpoint is already published on this page.');
+    const random = globalThis.crypto?.getRandomValues?.(new Uint8Array(12));
+    const instance = random ? [...random].map(byte => byte.toString(16).padStart(2, '0')).join('') : `${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`;
+    const endpoint = Object.freeze({ protocol: ENDPOINT_PROTOCOL, instance, handle: (text) => provider.handleText(text) });
+    Object.defineProperty(target, ENDPOINT_KEY, { value: endpoint, configurable: true, enumerable: false, writable: false });
+    return () => {
+        if (Object.getOwnPropertyDescriptor(target, ENDPOINT_KEY)?.value === endpoint)
+            delete target[ENDPOINT_KEY];
+        provider.close();
+    };
+}

package/dist/lib/mcp-tools.d.ts

@@ -0,0 +1,71 @@
+export type JsonSchema = {
+    readonly [key: string]: unknown;
+};
+/** Advisory hints, as MCP and WebMCP describe them. A consumer treats them as untrusted claims, never as proof of safety. */
+export interface ToolAnnotations {
+    readonly title?: string;
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+}
+export interface ToolExecution {
+    readonly signal: AbortSignal;
+}
+/** One operation the application exposes. `execute` receives validated arguments and must honour `signal` where it can. */
+export interface BrowserTool {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    readonly annotations?: ToolAnnotations;
+    execute(args: Record<string, unknown>, context: ToolExecution): unknown;
+}
+/** The published description of a tool (no executable member). */
+export interface ToolDescriptor {
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema: JsonSchema;
+    annotations?: ToolAnnotations;
+}
+export interface ToolLimits {
+    /** Largest serialized result accepted from `execute`, in UTF-8 bytes. */
+    readonly resultBytes: number;
+    /** Longest a single execution may run before it is aborted. */
+    readonly timeoutMs: number;
+}
+export declare const DEFAULT_TOOL_LIMITS: ToolLimits;
+/** A failure the caller can report: `code` is a stable machine-readable string. */
+export declare class ToolError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+/** The outcome of one call, already JSON-safe: either the tool's value or a structured refusal. */
+export type ToolOutcome = {
+    readonly ok: true;
+    readonly value: unknown;
+    readonly json: string;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly details?: unknown;
+    };
+};
+export interface ToolRegistry {
+    readonly descriptors: readonly ToolDescriptor[];
+    has(name: string): boolean;
+    /** Validate `args` against the tool's schema, run it under a deadline and return a JSON-safe outcome. */
+    run(name: string, args: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<ToolOutcome>;
+}
+/** Compile a schema once; throws a `ToolError('INVALID_SCHEMA')` for anything outside the supported subset. */
+export declare function compileSchema(schema: unknown, label?: string): (value: unknown) => string | null;
+/** The JSON text of a value, or a refusal when it is not plain JSON data or exceeds the byte budget. */
+export declare function boundedJson(value: unknown, maxBytes: number): string;
+/** Validate tool definitions once and return the registry every adapter shares. */
+export declare function defineTools(tools: readonly BrowserTool[], limits?: Partial<ToolLimits>): ToolRegistry;

package/dist/lib/mcp-tools.js

@@ -0,0 +1,277 @@
+/*
+ * Owns: one canonical registry of browser-executed tools, the bounded JSON Schema subset that validates their input, and the
+ * single execution path every adapter (the browser MCP provider, WebMCP) calls. Excludes: transport, discovery and any
+ * application semantics — a tool's `execute` is the application's own operation.
+ *
+ * A schema keyword this module does not implement is refused when the tool is defined, so a registered schema never claims a
+ * validation this code would silently skip.
+ */
+export const DEFAULT_TOOL_LIMITS = Object.freeze({ resultBytes: 1024 * 1024, timeoutMs: 60_000 });
+/** A failure the caller can report: `code` is a stable machine-readable string. */
+export class ToolError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'ToolError';
+        this.code = code;
+        if (details !== undefined)
+            this.details = details;
+    }
+}
+/* ---- the JSON Schema subset ---------------------------------------------------------------------- */
+const DIALECT = 'https://json-schema.org/draft/2020-12/schema';
+const ANNOTATION_KEYWORDS = new Set(['$schema', 'title', 'description', 'default', 'examples', '$comment', 'deprecated', 'readOnly', 'writeOnly']);
+const ASSERTION_KEYWORDS = new Set(['type', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const', 'anyOf', 'oneOf', 'minimum', 'maximum', 'minLength', 'maxLength', 'minItems', 'maxItems']);
+const TYPES = new Set(['object', 'array', 'string', 'number', 'integer', 'boolean', 'null']);
+const MAX_SCHEMA_NODES = 2000;
+const MAX_SCHEMA_DEPTH = 32;
+const MAX_VALUE_DEPTH = 64;
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const typeOf = (value) => value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value === 'number' ? (Number.isInteger(value) ? 'integer' : 'number') : typeof value;
+const matchesType = (value, type) => {
+    const actual = typeOf(value);
+    return actual === type || (type === 'number' && actual === 'integer');
+};
+const nonNegativeInteger = (value) => Number.isSafeInteger(value) && value >= 0;
+function sameJson(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null || typeof a !== 'object')
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    if (Array.isArray(a))
+        return a.length === b.length && a.every((item, i) => sameJson(item, b[i]));
+    const keysA = Object.keys(a), keysB = Object.keys(b);
+    return keysA.length === keysB.length && keysA.every(key => Object.hasOwn(b, key) && sameJson(a[key], b[key]));
+}
+/** Compile a schema once; throws a `ToolError('INVALID_SCHEMA')` for anything outside the supported subset. */
+export function compileSchema(schema, label = 'schema') {
+    let nodes = 0;
+    const compile = (node, path, depth) => {
+        if (++nodes > MAX_SCHEMA_NODES || depth > MAX_SCHEMA_DEPTH)
+            throw new ToolError('INVALID_SCHEMA', `${label} is too large or too deeply nested.`);
+        if (node === true)
+            return () => null;
+        if (node === false)
+            return (_value, at) => `${at || 'value'} is not allowed`;
+        if (!isObject(node))
+            throw new ToolError('INVALID_SCHEMA', `${label} at ${path || '/'} must be an object or a boolean.`);
+        for (const key of Object.keys(node)) {
+            if (!ANNOTATION_KEYWORDS.has(key) && !ASSERTION_KEYWORDS.has(key))
+                throw new ToolError('INVALID_SCHEMA', `${label} uses the unsupported keyword "${key}" at ${path || '/'}.`);
+        }
+        if ('$schema' in node && node.$schema !== DIALECT)
+            throw new ToolError('INVALID_SCHEMA', `${label} declares an unsupported dialect; only JSON Schema 2020-12 is implemented.`);
+        const checks = [];
+        if ('type' in node) {
+            const types = Array.isArray(node.type) ? node.type : [node.type];
+            if (!types.length || types.some(type => typeof type !== 'string' || !TYPES.has(type)))
+                throw new ToolError('INVALID_SCHEMA', `${label} has an invalid type at ${path || '/'}.`);
+            checks.push((value, at) => types.some(type => matchesType(value, type)) ? null : `${at || 'value'} must be ${types.join(' or ')}`);
+        }
+        if ('enum' in node) {
+            if (!Array.isArray(node.enum) || !node.enum.length)
+                throw new ToolError('INVALID_SCHEMA', `${label} has an empty enum at ${path || '/'}.`);
+            const values = node.enum;
+            checks.push((value, at) => values.some(item => sameJson(item, value)) ? null : `${at || 'value'} must be one of ${values.map(item => JSON.stringify(item)).join(', ')}`);
+        }
+        if ('const' in node) {
+            const expected = node.const;
+            checks.push((value, at) => sameJson(expected, value) ? null : `${at || 'value'} must be ${JSON.stringify(expected)}`);
+        }
+        for (const [key, test] of [['minimum', (v, n) => v >= n], ['maximum', (v, n) => v <= n]]) {
+            if (!(key in node))
+                continue;
+            const limit = node[key];
+            if (typeof limit !== 'number' || !Number.isFinite(limit))
+                throw new ToolError('INVALID_SCHEMA', `${label} has an invalid ${key} at ${path || '/'}.`);
+            checks.push((value, at) => typeof value !== 'number' || test(value, limit) ? null : `${at || 'value'} must be ${key === 'minimum' ? '≥' : '≤'} ${limit}`);
+        }
+        for (const [key, measure, compare] of [
+            ['minLength', 'string', (n, l) => n >= l], ['maxLength', 'string', (n, l) => n <= l],
+            ['minItems', 'array', (n, l) => n >= l], ['maxItems', 'array', (n, l) => n <= l],
+        ]) {
+            if (!(key in node))
+                continue;
+            const limit = node[key];
+            if (!nonNegativeInteger(limit))
+                throw new ToolError('INVALID_SCHEMA', `${label} has an invalid ${key} at ${path || '/'}.`);
+            checks.push((value, at) => {
+                if (measure === 'string' && typeof value === 'string') {
+                    let length = 0;
+                    for (const _ of value)
+                        length++;
+                    return compare(length, limit) ? null : `${at || 'value'} must have ${key.startsWith('min') ? 'at least' : 'at most'} ${limit} characters`;
+                }
+                if (measure === 'array' && Array.isArray(value))
+                    return compare(value.length, limit) ? null : `${at || 'value'} must have ${key.startsWith('min') ? 'at least' : 'at most'} ${limit} items`;
+                return null;
+            });
+        }
+        if ('properties' in node || 'required' in node || 'additionalProperties' in node) {
+            if ('properties' in node && !isObject(node.properties))
+                throw new ToolError('INVALID_SCHEMA', `${label} has invalid properties at ${path || '/'}.`);
+            const properties = new Map(Object.entries((node.properties ?? {})).map(([key, child]) => [key, compile(child, `${path}/properties/${key}`, depth + 1)]));
+            const required = node.required ?? [];
+            if (!Array.isArray(required) || required.some(key => typeof key !== 'string'))
+                throw new ToolError('INVALID_SCHEMA', `${label} has an invalid required list at ${path || '/'}.`);
+            const extra = 'additionalProperties' in node ? compile(node.additionalProperties, `${path}/additionalProperties`, depth + 1) : null;
+            checks.push((value, at, level) => {
+                if (!isObject(value))
+                    return null;
+                for (const key of required)
+                    if (!Object.hasOwn(value, key))
+                        return `${at ? `${at}.` : ''}${key} is required`;
+                for (const [key, item] of Object.entries(value)) {
+                    const child = properties.get(key) ?? extra;
+                    const problem = child?.(item, at ? `${at}.${key}` : key, level + 1);
+                    if (problem)
+                        return problem;
+                }
+                return null;
+            });
+        }
+        if ('items' in node) {
+            const items = compile(node.items, `${path}/items`, depth + 1);
+            checks.push((value, at, level) => {
+                if (!Array.isArray(value))
+                    return null;
+                for (let i = 0; i < value.length; i++) {
+                    const problem = items(value[i], `${at || 'value'}[${i}]`, level + 1);
+                    if (problem)
+                        return problem;
+                }
+                return null;
+            });
+        }
+        for (const key of ['anyOf', 'oneOf']) {
+            if (!(key in node))
+                continue;
+            const list = node[key];
+            if (!Array.isArray(list) || !list.length)
+                throw new ToolError('INVALID_SCHEMA', `${label} has an empty ${key} at ${path || '/'}.`);
+            const variants = list.map((child, i) => compile(child, `${path}/${key}/${i}`, depth + 1));
+            checks.push((value, at, level) => {
+                const passing = variants.filter(variant => variant(value, at, level) === null).length;
+                if (key === 'anyOf' ? passing > 0 : passing === 1)
+                    return null;
+                return `${at || 'value'} does not match ${key === 'anyOf' ? 'any allowed shape' : 'exactly one allowed shape'}`;
+            });
+        }
+        return (value, at, level) => {
+            if (level > MAX_VALUE_DEPTH)
+                return `${at || 'value'} is nested too deeply`;
+            for (const check of checks) {
+                const problem = check(value, at, level);
+                if (problem)
+                    return problem;
+            }
+            return null;
+        };
+    };
+    const root = compile(schema, '', 0);
+    return value => root(value, '', 0);
+}
+/* ---- the registry -------------------------------------------------------------------------------- */
+const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;
+const MAX_DESCRIPTION = 16_384;
+const encoder = new TextEncoder();
+/** The JSON text of a value, or a refusal when it is not plain JSON data or exceeds the byte budget. */
+export function boundedJson(value, maxBytes) {
+    let text;
+    try {
+        text = JSON.stringify(value === undefined ? null : value);
+    }
+    catch (error) {
+        throw new ToolError('INVALID_RESULT', `The result is not JSON data: ${error?.message || error}`);
+    }
+    if (typeof text !== 'string')
+        throw new ToolError('INVALID_RESULT', 'The result is not JSON data.');
+    if (text.length > maxBytes || encoder.encode(text).byteLength > maxBytes)
+        throw new ToolError('RESULT_TOO_LARGE', `The result exceeds ${maxBytes} bytes.`);
+    return text;
+}
+function refusal(error) {
+    const code = typeof error?.code === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(error.code) ? error.code : 'TOOL_FAILED';
+    const message = String(error?.message ?? error ?? 'The tool failed.').slice(0, 4000);
+    let details;
+    try {
+        const raw = error?.details;
+        if (raw !== undefined)
+            details = JSON.parse(boundedJson(raw, 16_384));
+    }
+    catch { /* details are optional; drop what cannot travel */ }
+    return details === undefined ? { code, message } : { code, message, details };
+}
+function annotationsOf(input, name) {
+    if (input === undefined)
+        return undefined;
+    if (!isObject(input))
+        throw new ToolError('INVALID_TOOL', `${name}: annotations must be an object.`);
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (key === 'title' ? typeof value !== 'string' : !['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint'].includes(key) || typeof value !== 'boolean')
+            throw new ToolError('INVALID_TOOL', `${name}: unsupported annotation ${key}.`);
+        out[key] = value;
+    }
+    return out;
+}
+/** Validate tool definitions once and return the registry every adapter shares. */
+export function defineTools(tools, limits = {}) {
+    const budget = { ...DEFAULT_TOOL_LIMITS, ...limits };
+    const entries = new Map();
+    for (const tool of tools) {
+        if (!tool || typeof tool !== 'object' || typeof tool.name !== 'string' || !TOOL_NAME.test(tool.name))
+            throw new ToolError('INVALID_TOOL', 'A tool name must be 1–128 characters of A–Z, a–z, 0–9, "_", "-" or ".".');
+        if (entries.has(tool.name))
+            throw new ToolError('INVALID_TOOL', `Duplicate tool name: ${tool.name}.`);
+        if (typeof tool.description !== 'string' || !tool.description.trim() || tool.description.length > MAX_DESCRIPTION)
+            throw new ToolError('INVALID_TOOL', `${tool.name}: description must be a non-empty string of at most ${MAX_DESCRIPTION} characters.`);
+        if (tool.title !== undefined && typeof tool.title !== 'string')
+            throw new ToolError('INVALID_TOOL', `${tool.name}: title must be a string.`);
+        if (typeof tool.execute !== 'function')
+            throw new ToolError('INVALID_TOOL', `${tool.name}: execute must be a function.`);
+        if (!isObject(tool.inputSchema) || tool.inputSchema.type !== 'object')
+            throw new ToolError('INVALID_SCHEMA', `${tool.name}: inputSchema must be an object schema.`);
+        const annotations = annotationsOf(tool.annotations, tool.name);
+        // The descriptor is a detached JSON copy: later mutation of the caller's object cannot change what was validated.
+        const descriptor = JSON.parse(JSON.stringify({ name: tool.name, ...(tool.title ? { title: tool.title } : {}), description: tool.description, inputSchema: tool.inputSchema, ...(annotations ? { annotations } : {}) }));
+        entries.set(tool.name, { tool, validate: compileSchema(descriptor.inputSchema, `${tool.name} inputSchema`), descriptor });
+    }
+    const descriptors = Object.freeze([...entries.values()].map(entry => Object.freeze(entry.descriptor)));
+    async function run(name, args, { signal } = {}) {
+        const entry = entries.get(name);
+        if (!entry)
+            return { ok: false, error: { code: 'UNKNOWN_TOOL', message: `Unknown tool: ${name}.` } };
+        const input = args === undefined ? {} : args;
+        const problem = entry.validate(input);
+        if (problem)
+            return { ok: false, error: { code: 'INVALID_ARGUMENT', message: `Invalid arguments for ${name}: ${problem}.` } };
+        if (signal?.aborted)
+            return { ok: false, error: { code: 'CANCELLED', message: 'The call was cancelled.' } };
+        const controller = new AbortController();
+        const abort = () => controller.abort(signal?.reason);
+        signal?.addEventListener('abort', abort, { once: true });
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => { const error = new ToolError('TIMEOUT', `${name} did not finish within ${budget.timeoutMs} ms.`); controller.abort(error); reject(error); }, budget.timeoutMs);
+        });
+        const cancelled = new Promise((_, reject) => controller.signal.addEventListener('abort', () => reject(controller.signal.reason instanceof ToolError ? controller.signal.reason : new ToolError('CANCELLED', 'The call was cancelled.')), { once: true }));
+        try {
+            // A detached copy: the tool never receives an object the transport can still mutate.
+            const value = await Promise.race([Promise.resolve().then(() => entry.tool.execute(JSON.parse(JSON.stringify(input)), { signal: controller.signal })), deadline, cancelled]);
+            const json = boundedJson(value, budget.resultBytes);
+            return { ok: true, value: JSON.parse(json), json };
+        }
+        catch (error) {
+            return { ok: false, error: refusal(error) };
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', abort);
+        }
+    }
+    return Object.freeze({ descriptors, has: (name) => entries.has(name), run });
+}

package/dist/lib/palette.js

@@ -1,4 +1,5 @@
 import { $, el, icon, keys } from './util.js';
+import { native } from './host.js';
 import { store, on, documents, descriptor, cachedModel, loadModel, selectArtboards, selectNodes, undo, redo, textChild, parentOf } from './store.js';
 import * as canvas from './canvas.js';
 import * as actions from './actions.js';
@@ -122,8 +123,8 @@ function commands() {
   add(board, sidebar.isOpen('layers') ? 'Hide layers' : 'Show layers', () => sidebar.toggle('layers'), { icon: 'layers', keys: 'L' });
   add(board, sidebar.isOpen('activity') ? 'Hide history' : 'Show history', () => sidebar.toggle('activity'), { icon: 'chat', keys: 'H', words: 'activity log changes replies' });
   add(board, 'Open the site', () => window.open(store.state.site.url, '_blank', 'noopener'), { icon: 'site', when: !!store.state?.site, words: 'markdown pages' });
-  add(board, 'Open project…', () => project.show('open'), { icon: 'folder', keys: keys('Mod+O'), words: 'switch folder load' });
-  add(board, 'Save a copy as…', () => project.show('save'), { icon: 'download', keys: keys('Mod+Shift+S'), words: 'save as copy export project folder', when: project.canShowCopy() });
+  add(board, 'Open project…', () => project.show('open'), { icon: 'folder', keys: keys('Mod+O'), words: 'switch folder load', when: native });
+  add(board, 'Save a copy as…', () => project.show('save'), { icon: 'download', keys: keys('Mod+Shift+S'), words: 'save as copy export project folder', when: native && project.canShowCopy() });
   for (const percent of help.UI_SIZES) add(board, `Interface size ${percent}%`, () => help.setUiSize(percent), { icon: 'search', words: 'scale zoom text bigger smaller ui' });
   add(board, 'Keyboard shortcuts', () => shortcuts.toggle(true), { icon: 'keyboard', keys: '?', words: 'keys hotkeys help' });
   add(board, 'Settings', () => help.toggle(true), { icon: 'gear', keys: keys('Mod') + ' ,', words: 'preferences theme interface size' });