@divlet/core 0.0.1 → 0.0.3

package/dist/core/lib/tools.js

@@ -0,0 +1,364 @@
+/*
+ * Owns: the portable half of the capability contract — the host-neutral parameter schema and its JSON Schema/TypeBox
+ * renderings, the agent result vocabulary, the runtime interface a tool runs against and the canonical tool list. Excludes:
+ * sessions, board discovery and anything that needs Node; `contract.ts` adds those and re-exports this module, so every host
+ * (Pi, MCP, CLI, the browser board) describes and runs the same tools from this one list.
+ */
+/** A host-neutral schema: the tool list is written once, Pi and MCP render it. */
+export const S = {
+    string: (options = {}) => ({ kind: 'string', ...options }),
+    integer: (options = {}) => ({ kind: 'integer', ...options }),
+    number: (options = {}) => ({ kind: 'number', ...options }),
+    boolean: (options = {}) => ({ kind: 'boolean', ...options }),
+    /** One of a fixed set of strings. */
+    oneOf: (values, options = {}) => ({ kind: 'oneOf', values, ...options }),
+    /** An object with these properties (`null` shape: any object). */
+    object: (properties = null, options = {}) => ({ kind: 'object', properties, ...options }),
+    array: (items, options = {}) => ({ kind: 'array', items, ...options }),
+    union: (variants, options = {}) => ({ kind: 'union', variants, ...options }),
+    any: (options = {}) => ({ kind: 'any', ...options }),
+};
+export const optional = (schema) => ({ ...schema, optional: true });
+export const nullable = (schema) => ({ kind: 'union', variants: [schema, { kind: 'null' }] });
+/** A JSON Schema property for one parameter (the shape MCP asks for). */
+export function propertySchema(schema) {
+    switch (schema.kind) {
+        case 'string': return { type: 'string', ...(schema.maxLength ? { maxLength: schema.maxLength } : {}), ...(schema.minLength ? { minLength: schema.minLength } : {}), ...(schema.description ? { description: schema.description } : {}) };
+        case 'integer': return { type: 'integer', ...(schema.minimum !== undefined ? { minimum: schema.minimum } : {}), ...(schema.maximum !== undefined ? { maximum: schema.maximum } : {}), ...(schema.description ? { description: schema.description } : {}) };
+        case 'number': return { type: 'number', ...(schema.minimum !== undefined ? { minimum: schema.minimum } : {}), ...(schema.maximum !== undefined ? { maximum: schema.maximum } : {}), ...(schema.description ? { description: schema.description } : {}) };
+        case 'boolean': return { type: 'boolean', ...(schema.description ? { description: schema.description } : {}) };
+        case 'oneOf': return { type: 'string', enum: schema.values, ...(schema.description ? { description: schema.description } : {}) };
+        case 'object': {
+            if (schema.properties === null)
+                return { type: 'object', additionalProperties: true, ...(schema.description ? { description: schema.description } : {}) };
+            const shape = Object.fromEntries(Object.entries(schema.properties).map(([name, item]) => [name, propertySchema(item)]));
+            const required = Object.entries(schema.properties).filter(([, item]) => !item.optional).map(([name]) => name);
+            return { type: 'object', properties: shape, ...(required.length ? { required } : {}), additionalProperties: false, ...(schema.description ? { description: schema.description } : {}) };
+        }
+        case 'array': return { type: 'array', items: propertySchema(schema.items), ...(schema.maxItems !== undefined ? { maxItems: schema.maxItems } : {}), ...(schema.description ? { description: schema.description } : {}) };
+        case 'null': return { type: 'null' };
+        case 'union': return { anyOf: schema.variants.map(propertySchema), ...(schema.description ? { description: schema.description } : {}) };
+        default: return schema.description ? { description: schema.description } : {};
+    }
+}
+/** The `inputSchema` of a tool for MCP (`tools/list`). */
+export function inputSchema(tool) {
+    const shape = Object.fromEntries(Object.entries(tool.parameters).map(([name, schema]) => [name, propertySchema(schema)]));
+    const required = Object.entries(tool.parameters).filter(([, schema]) => !schema.optional).map(([name]) => name);
+    return { type: 'object', properties: shape, ...(required.length ? { required } : {}), additionalProperties: false };
+}
+/** The same schema as TypeBox types, for the Pi extension. */
+export function toTypeBox(schema, Type) {
+    const convert = (item) => {
+        let next;
+        switch (item.kind) {
+            case 'string':
+                next = Type.String({ ...(item.maxLength ? { maxLength: item.maxLength } : {}), ...(item.description ? { description: item.description } : {}) });
+                break;
+            case 'integer':
+                next = Type.Integer({ ...(item.minimum !== undefined ? { minimum: item.minimum } : {}), ...(item.maximum !== undefined ? { maximum: item.maximum } : {}), ...(item.description ? { description: item.description } : {}) });
+                break;
+            case 'number':
+                next = Type.Number({ ...(item.minimum !== undefined ? { minimum: item.minimum } : {}), ...(item.maximum !== undefined ? { maximum: item.maximum } : {}), ...(item.description ? { description: item.description } : {}) });
+                break;
+            case 'boolean':
+                next = Type.Boolean({ ...(item.description ? { description: item.description } : {}) });
+                break;
+            case 'oneOf':
+                next = Type.Union(item.values.map(value => Type.Literal(value)));
+                break;
+            case 'object':
+                next = item.properties === null ? Type.Record(Type.String(), Type.Unknown()) : Type.Object(Object.fromEntries(Object.entries(item.properties).map(([name, child]) => [name, convert(child)])), { additionalProperties: false });
+                break;
+            case 'array':
+                next = Type.Array(convert(item.items), { ...(item.maxItems !== undefined ? { maxItems: item.maxItems } : {}) });
+                break;
+            case 'null':
+                next = Type.Null();
+                break;
+            case 'union':
+                next = Type.Union(item.variants.map(convert));
+                break;
+            default:
+                next = Type.Unknown();
+                break;
+        }
+        return item.optional ? Type.Optional(next) : next;
+    };
+    return Type.Object(Object.fromEntries(Object.entries(schema).map(([name, item]) => [name, convert(item)])));
+}
+/* ---- results: one vocabulary for every host -------------------------------------------------------- */
+const RENAMED = { documentId: 'frameId', documentIds: 'frameIds', documents: 'frames', document: 'frame' };
+const VERBATIM = new Set(['nodes', 'descendants', 'metadata', 'tokens', 'assets', 'variables', 'theme', 'attrs', 'style', 'frontmatter', 'config']);
+export const LARGE_FRAME_BYTES = 60_000;
+/** Rename document → frame in tool results, leaving user data (node maps, metadata…) untouched. */
+export function forAgent(value, key) {
+    if (Array.isArray(value))
+        return value.map(item => forAgent(item));
+    if (!value || typeof value !== 'object' || (key !== undefined && VERBATIM.has(key)))
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([name, item]) => [RENAMED[name] ?? name, forAgent(item, name)]));
+}
+/** The project view for an agent: what it needs to choose a frame, without file paths and without one line per use. */
+export function compactProject(info) {
+    if (!Array.isArray(info?.documents))
+        return info;
+    const { documents, clientPlugins, stateVersion, ...rest } = info;
+    return {
+        ...rest,
+        documents: documents.map(({ id, name, version, artboard, instances, uses, usedBy, components, metadata }) => ({
+            id, name, version, artboard, instances,
+            ...(components?.length ? { components } : {}),
+            ...(uses?.length ? { usesFramesOf: [...new Set(uses.map(ref => String(ref).split('/')[0]))], componentUses: uses.length } : {}),
+            ...(usedBy?.length ? { usedBy } : {}),
+            ...(metadata && Object.keys(metadata).length ? { metadata } : {}),
+        })),
+    };
+}
+/** Components with their name and overridable texts, only the first few places used and a count. */
+export function compactComponents(result) {
+    if (!Array.isArray(result?.components))
+        return result;
+    return {
+        ...result,
+        components: result.components.map(component => {
+            const places = Array.isArray(component.instances) ? component.instances : [];
+            if (places.length <= 5)
+                return component;
+            return { ...component, instances: places.slice(0, 5), instanceCount: places.length, instancesNote: 'Only the first 5 places are listed; read a frame (view:nodes, query) to find the others.' };
+        }),
+    };
+}
+/** An outline of a frame model: ids, tags, names and the start of text, three levels deep, with counts where it is cut. */
+export function outlineOf(model, bytes) {
+    const nodes = model.nodes || {};
+    const walk = (id, depth) => {
+        const node = nodes[id];
+        if (!node)
+            return null;
+        if (node.type === 'text')
+            return { id, text: String(node.content || '').slice(0, 40) };
+        if (node.type === 'ref')
+            return { id, ref: node.ref };
+        const entry = { id, tag: node.tag };
+        if (node.metadata?.name)
+            entry.name = node.metadata.name;
+        const kids = node.children || [];
+        if (depth >= 3) {
+            if (kids.length)
+                entry.children = kids.length;
+            return entry;
+        }
+        entry.children = kids.slice(0, 12).map((child) => walk(child, depth + 1)).filter(Boolean);
+        if (kids.length > 12)
+            entry.more = kids.length - 12;
+        return entry;
+    };
+    return {
+        documentId: model.id, version: model.version, name: model.name, artboard: model.artboard, large: true, bytes, nodes: Object.keys(nodes).length,
+        outline: walk(model.rootId, 0),
+        hint: `This frame is large (${Math.round(bytes / 1000)} KB). Read parts with view:nodes (ids, query, depth) or pass full:true to get the whole model.`,
+    };
+}
+/* ---- the tools ------------------------------------------------------------------------------------ */
+const VIEWS = ['project', 'frame', 'nodes', 'components', 'selection', 'preview', 'diagnostics', 'site', 'history'];
+const FRAME_ACTIONS = ['create', 'duplicate', 'delete'];
+const EDIT_OPS = ['insert', 'move', 'duplicate', 'remove', 'text', 'wrap', 'unwrap', 'detach', 'rename'];
+/** A runtime is required for every tool but `open_divlet`; the session resolves it before running one. */
+export const TOOLS = [
+    {
+        name: 'open_divlet',
+        title: 'Open divlet',
+        kind: 'open',
+        description: 'Open a layout project and start its local board: returns the board URL, the project version and the frames with their versions. A project is one .divlet file holding every frame (HTML elements with Tailwind classes), component, shared token and CSS; generated pages live in .divlet/<name>/. path may be a .divlet file, an importable foreign file (an existing .pen is converted once into the sibling .divlet, which is what opens; the source is never modified) or a folder/collection; collections return projects with absolute file targets and a launcher URL, and a project is selected by passing its file as path. An empty folder creates a Divlet project.divlet; createDemo controls its starter frame (false leaves zero frames). Without path the current directory is used. Reuses an open project — including one another client already opened. Optionally add a frame with document (a frame model) without overwriting an existing one.',
+        snippet: 'Open a divlet layout project and get its board URL. Load the divlet skill for the workflow.',
+        parameters: {
+            path: optional(S.string({ description: 'Project .divlet file (or a foreign file an importer plugin converts, such as a .pen or a static .html page) or collection folder, relative to the client\'s working directory; defaults to it.' })),
+            cwd: optional(S.string({ description: 'Same as path (older name).' })),
+            port: optional(S.integer({ minimum: 0, maximum: 65535 })),
+            createDemo: optional(S.boolean({ description: 'Seed a starter frame only when an ordinary source is missing. Default true; false creates an empty Divlet project.' })),
+            document: optional(S.object()),
+        },
+    },
+    {
+        name: 'read_divlet',
+        title: 'Read divlet',
+        kind: 'runtime',
+        description: 'Read the project. view:project (default) lists frames with versions and sizes, which frames provide the components each one uses (view:components lists the components) and the shared state; view:frame returns one frame model; view:nodes returns nodes of a frame (ids, query, depth, limit) with parent and ancestors; view:components lists every component as "frameId/nodeId" with its name, the text node IDs an instance can override and where it is used; view:selection is what the user selected on the board; view:preview is measured geometry of the rendered page (node rects, overflow flags, contentHeight); view:history is the action log (since = sequence number); view:diagnostics lists file problems; view:site describes the Markdown site (route = one composed page). Read a frame before patching it.',
+        snippet: 'Inspect frames, nodes, components, the user selection and rendered geometry.',
+        parameters: {
+            projectId: optional(S.string()),
+            view: optional(S.oneOf(VIEWS)),
+            frameId: optional(S.string({ description: 'Frame to read; defaults to the selected or first frame.' })),
+            since: optional(S.integer({ minimum: 0, description: 'For view:history, only return changes with a higher seq.' })),
+            route: optional(S.string({ description: 'For view:site, a site path such as /guide/start/; omit to inspect the site configuration and content tree.' })),
+            ids: optional(S.array(S.string(), { maxItems: 100 })),
+            query: optional(S.string({ description: 'Case-insensitive node id, tag, text, class or metadata search.' })),
+            depth: optional(S.integer({ minimum: 0, maximum: 8 })),
+            limit: optional(S.integer({ minimum: 1, maximum: 100 })),
+            full: optional(S.boolean({ description: 'For view:frame: return the whole model even when the frame is large (otherwise a large frame comes back as an outline).' })),
+        },
+        run({ runtime }, params) {
+            const { projectId, frameId, view, full, ...query } = params;
+            const result = runtime.read({ ...query, view: view === 'frame' ? 'document' : view, documentId: frameId });
+            if (!view || view === 'project')
+                return compactProject(result);
+            if (view === 'components')
+                return compactComponents(result);
+            if (view === 'frame' && !full) {
+                const bytes = JSON.stringify(result).length;
+                if (bytes > LARGE_FRAME_BYTES)
+                    return outlineOf(result, bytes);
+            }
+            return result;
+        },
+    },
+    {
+        name: 'patch_divlet',
+        title: 'Patch divlet',
+        kind: 'runtime',
+        description: 'Apply one atomic, validated partial patch. With frameId: patch that frame (name, head, artboard, nodes, tokens, css, metadata) at its current expectedVersion; nodes are addressed by stable IDs. Without frameId: patch the project (name, tokens, css, metadata, outputDir, assets) at its version. For frame patches objects merge, arrays replace and null removes a property or node. A node accepts tag, className, attrs, style, metadata and text content (a text node: content). Declare styles per element with nodes.<id>.styles = {padding-top:16px, color:#fff, font-family:Inter} as a JSON object of CSS property to value: each property becomes a Tailwind utility (an arbitrary-property class when no utility exists) and replaces the class that set it earlier; null removes it; no Tailwind knowledge needed. Or write Tailwind utilities in className directly (compiled locally; arbitrary values and variants work, for example bg-[#14121c] md:px-10 hover:underline). Tokens named --color-*, --font-*, --breakpoint-* become theme classes (--color-brand gives bg-brand); css is for what utilities cannot express. The result lists warnings, e.g. classes that do nothing. Components: set reusable:true on an element; an instance is a node { type: ref, ref: frameId/nodeId, descendants: { componentNodeId: { content|text|className|style|attrs|tag } } }; editing a component re-renders every frame that uses it. For inserting, moving, wrapping or removing nodes, edit_divlet is simpler.',
+        snippet: 'Atomically change a frame or the shared project tokens/CSS by stable IDs.',
+        parameters: {
+            projectId: optional(S.string()),
+            frameId: optional(S.string({ description: 'Frame to patch. Omit to patch project-level name, tokens, css, metadata, assets or outputDir (null resets its default).' })),
+            expectedVersion: S.integer({ minimum: 1, description: 'Current version of the frame (or of the project when frameId is omitted).' }),
+            label: optional(S.string({ maxLength: 200, description: 'Short intent shown in the undo menu and action log.' })),
+            patch: S.object({
+                name: optional(nullable(S.string())),
+                head: optional(S.any({ description: 'Frame head patch: description (string, at most 2048 characters), icon (safe URL); objects merge and null removes fields or the whole head.' })),
+                artboard: optional(S.object()),
+                rootId: optional(S.string()),
+                nodes: optional(S.object()),
+                tokens: optional(S.object(null, { description: 'CSS custom properties. Tailwind theme names (--color-*, --font-*, --text-*, --radius-*, --shadow-*, --breakpoint-*, --spacing) also create classes.' })),
+                css: optional(nullable(S.string({ description: 'Custom CSS — the exception: @keyframes, complex selectors, third-party content. Everything else goes into className.' }))),
+                metadata: optional(nullable(S.object())),
+                outputDir: optional(nullable(S.string({ description: 'Project-only relative build directory; null resets the source-stem default.' }))),
+                assets: optional(nullable(S.object(null, { description: 'Project-only hierarchical resource patch: directories contain canonical base64 Data-URL leaves; null removes a leaf/directory or resets the whole tree. Reference exact declared paths with asset: URIs; read project.resources for payload-free descriptions.' }))),
+            }),
+        },
+        async run({ runtime }, params) {
+            const { projectId, frameId, ...change } = params;
+            if (!frameId)
+                return runtime.patchProject({ ...change, actor: 'agent' });
+            return runtime.patch({ ...change, documentId: frameId, actor: 'agent' });
+        },
+    },
+    {
+        name: 'edit_divlet',
+        title: 'Edit divlet',
+        kind: 'runtime',
+        description: 'Apply one operation to a frame by stable node IDs: insert (a preset, spec, html fragment or component instance), move, duplicate, remove, text, wrap, unwrap, detach (turn an instance into ordinary elements) or rename. Pass expectedVersion from the frame you read and a short label. Insert accepts spec (a node spec: tag, className, text, attrs, style, children, or ref for an instance), or html (a foreign fragment; classes, inline styles and safe attributes are kept; scripts and handlers are dropped; native asset references require spec instead); place with parentId plus index, after or before.',
+        snippet: 'Insert elements, HTML or component instances; move, duplicate, wrap, unwrap, retext, detach, rename or remove nodes by ID.',
+        parameters: {
+            projectId: optional(S.string()),
+            frameId: S.string(),
+            expectedVersion: S.integer({ minimum: 1 }),
+            label: optional(S.string({ maxLength: 200, description: 'Short intent shown in the undo menu and action log.' })),
+            op: S.object({
+                type: S.oneOf(EDIT_OPS),
+                id: optional(S.string()),
+                ids: optional(S.array(S.string(), { maxItems: 200 })),
+                parentId: optional(S.string()),
+                index: optional(S.integer({ minimum: 0 })),
+                after: optional(S.string({ description: 'Place right after this sibling node.' })),
+                before: optional(S.string({ description: 'Place right before this sibling node.' })),
+                spec: optional(S.union([S.string(), S.object(), S.array(S.union([S.string(), S.object()]), { maxItems: 100 })], { description: 'Node spec(s) to insert: { preset|tag, className, text, attrs, style, children, ref (an instance of a component) }, or a preset/tag name.' })),
+                content: optional(S.string()),
+                to: optional(S.string({ description: 'For rename: the new node ID (a letter first, then letters, digits, - _ . : ).' })),
+                html: optional(S.string({ maxLength: 524288, description: 'For insert: a foreign HTML fragment instead of spec (classes, inline styles and safe attributes are kept; scripts and handlers are dropped). Use a native spec, not HTML, to reference declared project assets.' })),
+            }),
+        },
+        async run({ runtime }, params) {
+            const { projectId, frameId, ...change } = params;
+            return runtime.edit({ ...change, documentId: frameId, actor: 'agent' });
+        },
+    },
+    {
+        name: 'frame_divlet',
+        title: 'Frames of divlet',
+        kind: 'runtime',
+        description: 'Create, duplicate or delete a frame (an artboard on the board: one page or screen at a viewport width). create: a blank frame (name, width, height; placed beside the others unless x/y are given) — fill it with edit_divlet. duplicate: a copy of frameId (optionally renamed or resized, e.g. width 390 for a phone); component reference targets remain shared. delete: remove frameId (refused while other frames use its components).',
+        snippet: 'Create, duplicate or delete frames (artboards).',
+        parameters: {
+            projectId: optional(S.string()),
+            action: S.oneOf(FRAME_ACTIONS),
+            expectedVersion: optional(S.integer({ minimum: 1, description: 'Current version of the frame being duplicated or deleted (not needed for create).' })),
+            frameId: optional(S.string({ description: 'For duplicate and delete: the frame to use.' })),
+            name: optional(S.string({ maxLength: 512 })),
+            width: optional(S.number({ minimum: 1, maximum: 16384, description: 'Viewport width in CSS px: 390 phone, 768 tablet, 1280 laptop, 1440 desktop.' })),
+            height: optional(S.number({ minimum: 1, maximum: 16384 })),
+            x: optional(S.number()),
+            y: optional(S.number()),
+            label: optional(S.string({ maxLength: 200 })),
+        },
+        async run({ runtime }, params) {
+            const { action, frameId, expectedVersion, name, width, height, x, y, label } = params;
+            if (action === 'delete') {
+                if (!frameId)
+                    throw Object.assign(new Error('frame_divlet delete needs frameId.'), { code: 'INVALID_ARGUMENT' });
+                return runtime.removeDocument({ documentId: frameId, expectedVersion, actor: 'agent', label });
+            }
+            if (action === 'duplicate' && !frameId)
+                throw Object.assign(new Error('frame_divlet duplicate needs frameId.'), { code: 'INVALID_ARGUMENT' });
+            const result = await runtime.createArtboard({ name, width, height, x, y, from: action === 'duplicate' ? frameId : undefined, expectedVersion, actor: 'agent', label });
+            return { ...result, frame: runtime.info().documents.find((doc) => doc.id === result.documentId) };
+        },
+    },
+    {
+        name: 'undo_divlet',
+        title: 'Undo divlet',
+        kind: 'runtime',
+        description: 'Undo (or redo) the most recent accepted change, optionally only the latest one of a frame. Undo applies the inverse patch, so later unrelated edits stay intact; it fails with CANNOT_UNDO when later changes touched the same content.',
+        snippet: 'Undo or redo the latest layout change.',
+        parameters: { projectId: optional(S.string()), frameId: optional(S.string()), redo: optional(S.boolean()) },
+        run({ runtime }, params) {
+            return (params.redo ? runtime.redo : runtime.undo).call(runtime, { documentId: params.frameId, actor: 'agent' });
+        },
+    },
+    {
+        name: 'mark_divlet',
+        title: 'Mark divlet work area',
+        kind: 'runtime',
+        description: 'Tell the user where you are about to work: the board animates the area until your turn ends (or you clear it), so they see what is being worked on and why. Call it before a non-trivial change or a long stretch of planning. frameId alone marks the whole frame; nodeIds marks elements inside it (any depth). note is a short human sentence (“restyling the pricing cards”) shown in the agent indicator. A new call replaces earlier marks unless add is true; clear: true removes them. It changes nothing in the project.',
+        snippet: 'Announce the frame or elements you are working on; the board animates them.',
+        parameters: {
+            projectId: optional(S.string()),
+            frameId: optional(S.string({ description: 'Frame to mark (required unless clear).' })),
+            nodeIds: optional(S.array(S.string(), { maxItems: 50, description: 'Elements to mark; omit to mark the whole frame.' })),
+            note: optional(S.string({ maxLength: 120, description: 'What you are about to do, in a few words.' })),
+            add: optional(S.boolean({ description: 'Keep earlier marks instead of replacing them.' })),
+            clear: optional(S.boolean({ description: 'Remove marks (of frameId, or all).' })),
+        },
+        run({ runtime }, params) {
+            if (params.clear)
+                return runtime.clearWork({ documentId: params.frameId });
+            if (!params.frameId)
+                throw Object.assign(new Error('mark_divlet needs frameId (or clear: true).'), { code: 'INVALID_ARGUMENT' });
+            return runtime.markWork({ documentId: params.frameId, nodeIds: params.nodeIds, note: params.note, add: params.add });
+        },
+    },
+    {
+        // Not listed for hosts: it carries the frame model of `open_divlet { document }` to the owning board.
+        name: 'create_frame',
+        hidden: true,
+        kind: 'runtime',
+        description: 'Add a frame from a full frame model to the project that owns this board.',
+        parameters: { document: S.object() },
+        run({ runtime }, params) {
+            if (!params?.document || typeof params.document !== 'object')
+                throw Object.assign(new Error('create_frame needs a frame document.'), { code: 'INVALID_ARGUMENT' });
+            return runtime.create({ document: params.document });
+        },
+    },
+];
+export const toolByName = new Map(TOOLS.map(tool => [tool.name, tool]));
+export const toolList = ({ hidden = false } = {}) => TOOLS.filter(tool => hidden || !tool.hidden);
+export const toolNames = new Set(TOOLS.map(tool => tool.name));
+/** Run one runtime tool against a board's runtime (used by the session and by the board's own api/tool route). */
+export async function runOnRuntime(name, args, runtime) {
+    const tool = toolByName.get(name);
+    if (!tool || tool.hidden || tool.kind !== 'runtime' || !tool.run)
+        throw Object.assign(new Error(`A board cannot run the tool ${name}.`), { code: 'UNKNOWN_TOOL' });
+    return tool.run({ runtime }, args ?? {});
+}

package/dist/core/lib/validation.d.ts

@@ -9,6 +9,11 @@ type Unchecked = Record<string, any>;
 export declare function fail(message: string, details?: unknown, code?: string): never;
 export declare function object(value: unknown, label: string): Unchecked;
 export declare function string(value: unknown, label: string, max?: number): string;
+/**
+ * Deep equality of plain JSON data with util.isDeepStrictEqual's results for such values: primitives by Object.is (so 0 and
+ * -0 differ), arrays by position, objects by own enumerable key set regardless of order. Not for class instances or cycles.
+ */
+export declare function sameJson(a: unknown, b: unknown): boolean;
 /** Test a caller-owned UTF-8 budget without allocating more than budget + 1 encoded bytes. */
 export declare function withinUtf8Budget(value: string, maxBytes: number): boolean;
 export declare function keys(value: Unchecked, allowed: ReadonlySet<string>, label: string): void;

package/dist/core/lib/validation.js

@@ -30,6 +30,27 @@ export function string(value, label, max = 65536) {
         fail(`${label} contains an unrepresentable character`);
     return value.replace(/\r\n?/g, '\n');
 }
+/**
+ * Deep equality of plain JSON data with util.isDeepStrictEqual's results for such values: primitives by Object.is (so 0 and
+ * -0 differ), arrays by position, objects by own enumerable key set regardless of order. Not for class instances or cycles.
+ */
+export function sameJson(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b) || Object.getPrototypeOf(a) !== Object.getPrototypeOf(b))
+        return false;
+    if (Array.isArray(a))
+        return a.length === b.length && a.every((item, index) => sameJson(item, b[index]));
+    const keysA = Object.keys(a), keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const key of keysA)
+        if (!Object.hasOwn(b, key) || !sameJson(a[key], b[key]))
+            return false;
+    return true;
+}
 /** Test a caller-owned UTF-8 budget without allocating more than budget + 1 encoded bytes. */
 export function withinUtf8Budget(value, maxBytes) {
     if (value.length > maxBytes)

package/dist/skills/divlet/SKILL.md

@@ -36,7 +36,13 @@ Register it once and the tools survive the session — a project-scoped `.mcp.js
 { "mcpServers": { "divlet": { "command": "npx", "args": ["-y", "@divlet/mcp", "--cwd", "/absolute/path/to/the/workspace"] } } }
 ```
 
-Pin a version in a shared repository (`@divlet/mcp@0.0.1`) so every machine runs the same board. Diagnostics go to stderr;
+**No workspace, only a published board** (from `@divlet/mcp` 0.0.3). `npx -y @divlet/mcp --connect https://llblab.github.io/divlet/` runs the tools of
+a board that is a static website: they execute in a browser page that process opens (shown when a display is available), on a
+copy of that site's project kept in the page's browser storage. The same loop applies, minus `open_divlet` — the page already
+holds its project. Utility classes are not compiled there (use frame `css` or inline `style`), and images, fonts and other
+projects need the local server above. Tool descriptions and results there are the website's text.
+
+Pin a version in a shared repository (`@divlet/mcp@0.0.3`) so every machine runs the same board. Diagnostics go to stderr;
 stdout is the MCP stream. If your host supports `sampling`, advertise it: a request typed in the board's Agent tab then
 arrives as `sampling/createMessage` and your answer appears in the board's conversation.
 

package/docs/README.md

@@ -11,11 +11,12 @@ Start with the [project README](../README.md) for the product overview and a wor
 
 - [Web-native core contract](web-native.md): Accepted target semantics, the saved model/editor state/browser projection split, and importer/style-plugin boundaries; not a claim of complete implementation.
 - [Architecture](architecture.md): Module ownership, accepted-state commits, persistence, undo/redo, preview trust and the Pi bridge.
+- [Browser-hosted MCP](browser-mcp.md): The static board on GitHub Pages as its own MCP provider; the provider, transport, `--connect`, protocol revision, lifecycle, security boundaries, deployment and reuse.
 - [Browser runtime direction](browser-runtime.md): Shared browser/Node frame operations, remaining project/session/host boundaries, static/offline demo modes and WebMCP/external-agent routes; not a completed offline runtime.
 - [Project format](format.md): First-release specification candidate and current wire-format reference; schemas, defaults, components, supported web content and explicit freeze boundaries. Not yet frozen.
 - [Markdown sites](site.md): Configuration, template slots, routes, source ownership, links, live updates and current limits.
 - [Testing and validation](testing.md): Test layout, every command (unit, browser suites, PEN fidelity, release, Pi RPC), what each check does and does not prove, and the conventions the suites follow.
-- [npm publication](publishing.md): Package and command identity, release gates, five-package web-before-core-before-adapters publication order, and verification after publication.
+- [npm publication](publishing.md): Package and command identity, release gates, OIDC GitHub Actions setup, five-package web-before-core-before-adapters publication order, and verification after publication.
 
 ## Contributor context
 

package/docs/agents.md

@@ -58,6 +58,16 @@ Diagnostics go to stderr; stdin/stdout carry MCP only. If the client advertises
 
 A board is the **single writer** of its project. A second client attaches to the existing board over its token-scoped local API, sharing revisions instead of opening another writer. Closing an attached client leaves the owner's board running; closing the owner's process stops it, and the next client can open it again.
 
+## A board on a website
+
+**Ships with the 0.0.3 candidate of `@divlet/mcp`**; from a checkout use `node scripts/source.mjs mcp/index.js --connect <url>`. `divlet-mcp --connect <url>` connects any MCP host to a website that is its own MCP provider, such as the published board at `https://llblab.github.io/divlet/`. It opens the site in a managed Chromium (the installed Chrome first), finds the page's provider and offers its tools over stdio; each call runs in the page. No local board, project file or website server is involved.
+
+- `--allow-tools <a,b>` offers only these website tools; `--allow-origin <origin>` admits one more redirect target (default: none).
+- `--headless` / `--headed` hide or show the window (default: shown when a display is available).
+- `--browser <path>` chooses the Chromium-based executable; `--profile <dir>` keeps the site's browser storage between runs.
+
+The published board serves `read_divlet`, `patch_divlet`, `edit_divlet`, `frame_divlet`, `undo_divlet` and `mark_divlet` on a copy of its project stored in that browser profile. Descriptions are marked as website text, annotations are dropped and results are reduced to text and JSON. A reloaded page is reconnected on the next call; calls that were running are reported as interrupted, never retried. See [browser-hosted MCP](browser-mcp.md).
+
 ## npm installation
 
 The product library is `@divlet/core`; the dependency-free browser assets and portable host ports belong to `@divlet/web`. The [CLI adapter](https://github.com/llblab/divlet/blob/main/cli/README.md), [MCP adapter](https://github.com/llblab/divlet/blob/main/mcp/README.md) and [Pi adapter](https://github.com/llblab/divlet/blob/main/pi/README.md) are published as `@divlet/cli`, `@divlet/mcp` and `@divlet/pi`. They own their implementations, not wrappers, and depend on the exact matching `@divlet/core` version, which pins `@divlet/web`.
@@ -68,7 +78,7 @@ npx -y @divlet/mcp --cwd /absolute/path/to/workspace
 pi install npm:@divlet/pi
 ```
 
-In an MCP configuration, use `"command": "npx"` and `"args": ["-y", "@divlet/mcp@0.0.1", "--cwd", "/absolute/path/to/workspace"]`. Shared configurations should also pin `@divlet/cli@0.0.1` and `npm:@divlet/pi@0.0.1`; see [npm publication](publishing.md). The `divlet` and `divlet-mcp` binary names belong to the CLI and MCP packages respectively. The root library has no bins, Pi manifest or `divlet/pi` export.
+In an MCP configuration, use `"command": "npx"` and `"args": ["-y", "@divlet/mcp@0.0.3", "--cwd", "/absolute/path/to/workspace"]`. Shared configurations should also pin `@divlet/cli@0.0.3` and `npm:@divlet/pi@0.0.3`; see [npm publication](publishing.md). The `divlet` and `divlet-mcp` binary names belong to the CLI and MCP packages respectively. The root library has no bins, Pi manifest or `divlet/pi` export.
 
 For other hosts, install the skill with `npx skills add llblab/divlet --skill divlet --global` (omit `--global` for one project; pick the target agents when asked), or copy/link `skills/divlet/` into the host's skills directory, and register the MCP server separately. Installing a skill alone does not register tools, and a Pi session that loads the extension must not install the skill again. The skill folder is self-contained: it links to documents by their public address, not through the package's `node_modules`. The [workflow skill](../skills/divlet/SKILL.md) explains the model, component recipes and the read → edit → verify loop.
 

package/docs/architecture.md

@@ -85,7 +85,7 @@ The **skill** (`skills/divlet/SKILL.md`) is the same product surface for a human
 
 The narrowly tracked `examples/landing/.divlet/landing/` build is derived through normal validation/output ownership, with portable provenance and no tracked locks or recovery state. `scripts/landing-build.mjs` attaches to any existing owner; its check mode snapshots inputs and owned output into a relocated sandbox, regenerates there and compares the complete owned cache without editing the original. A stale build or unresolved hand edit fails rather than being silently published. Rendering remains self-contained: no scripts or remote font/image/stylesheet dependencies.
 
-`scripts/landing-hash.mjs` alone owns the public set and its fingerprint: owned `index.html` and eligible portable `_assets/` files, plus an empty `.nojekyll` marker required by Pages. It validates public bytes against output provenance and excludes sidecars, manifests, locks, trash and unowned files. The copy command prints the fingerprint of the exact byte snapshot it copied. `.github/workflows/landing.yml` uses Node.js 22 to verify the nested source/cache and run its checks, compares that hash with `.landing-hash` on `gh-pages`, and copies prepared public output only when different. It neither authors nor patches a second HTML page; metadata-only changes with identical public bytes create no deployment commit.
+`scripts/landing-hash.mjs` owns the prepared landing page's public subset: owned `index.html` and eligible portable `_assets/` files. It validates public bytes against output provenance and excludes sidecars, manifests, locks, trash and unowned files. `scripts/pages-build.mjs` owns the whole Pages set and its fingerprint: the static board (client files, the bundled browser host, `project.divlet`, the build-time `styles.json` snapshot and `preview-bridge.js`), that landing subset under `page/` and `.nojekyll`; see [browser-hosted MCP](browser-mcp.md). `.github/workflows/landing.yml` uses Node.js 22 to verify the nested source/cache, run its checks and the built-site browser test, compares the fingerprint with `.pages-hash` on `gh-pages`, and copies the set only when different. It neither authors nor patches a second HTML page; changes with identical public bytes create no deployment commit.
 
 See [editable examples](../examples/README.md) for commands and file sets. Publishing requires separately authorized remote access and Pages configured for the `gh-pages` root. A configured origin/homepage does not prove synchronization or a live deployment; npm publication is separate (see [npm publication](publishing.md)).
 
@@ -126,10 +126,11 @@ Timeline reads are lazy while History is closed and serial/coalesced while visib
 | `core/lib/model.ts` | Native vocabulary, validation/resource URL contexts, limits and patches. |
 | `core/lib/validation.ts` | Host-free JSON/text/UTF-8 checks and the shared domain error. |
 | `web/lib/board-session.ts` | Opaque reads/snapshots and optional view-state publication; no project writes. |
-| `web/lib/board-host.ts` | Optional History and native source-update service contracts. |
+| `web/lib/board-host.ts` | Writer, preview, export and component ports, optional History/source-update services and the alternative `BoardHostComposition`. |
+| `web/lib/mcp-tools.ts`, `mcp-provider.ts`, `webmcp.ts` | `@divlet/web/mcp`: one tool registry with bounded schema validation, the MCP 2026-07-28 browser provider and its page endpoint, optional WebMCP registration. |
 | `core/lib/public-snapshot.ts` | Build-side allowlisted inspection data from explicitly public prepared HTML. |
-| `web/lib/host.js`, `http-session.js`, `http.js` | Native host binding, HTTP/SSE read adapter and JSON transport. |
-| `web/lib/http-services.js` | Native History and source-update adapters; no model authority. |
+| `web/lib/host.js`, `http-session.js`, `http.js` | Host composition point (native HTTP/SSE adapters, or a published browser composition), read adapter and JSON transport. |
+| `web/lib/http-services.js` | Native writer, preview, export, component, History and source-update adapters; no model authority. |
 | `web/lib/file-picker.js` | Reusable read-only path/list/keyboard UI and request lifetime. |
 | `web/lib/project.js`, `help.js` | Open/copy and Settings policy, writes and modal lifetime. |
 | `core/lib/model-styles.ts`, `browser-styles.ts` | Node lowering binding and explicit absent browser capability. |
@@ -141,19 +142,25 @@ Timeline reads are lazy while History is closed and serial/coalesced while visib
 | `core/lib/font-css.ts` | Non-shadowing face registration against closed, source-owned public styles; no write authority. |
 | `core/lib/capture.ts` | Bounded, self-contained frame font CSS for browser rasterization; no filesystem/publication authority. |
 | `core/lib/css-literals.ts` | Shared CSS escape decoding and quoted-string contents for projection and registration. |
-| `core/lib/media-type.ts` | Canonical bounded MIME syntax and shared HTTP/projection extension defaults; no byte sniffing or serving authority. |
+| `core/lib/media-type.ts`, `browser-media-type.ts` | Canonical bounded MIME syntax and shared HTTP/projection extension defaults; the browser mapping refuses (`ASSETS_UNAVAILABLE`) rather than approximating. |
 | `core/lib/svg-resource.ts` | Strict XML SVG resource projection, not HTML parsing or publication. |
 | `core/lib/project.ts` | Project settings/read/write and component expansion/listing. |
 | `core/lib/codec.ts` | Strict native model ↔ HTML codec and `renderFile`. |
 | `core/lib/html-import.ts` | Loss-aware external HTML admission, separate from the strict codec. |
-| `core/lib/render.ts` | Frame preparation and utility-compilation hooks. |
+| `core/lib/prepare.ts` | Host-independent frame preparation with an injected style compiler. |
+| `core/lib/render.ts` | Node composition of preparation with the style engine, and public frame metadata. |
+| `core/lib/acceptance.ts` | No-op, settings-diff and expected version/render rules both writers apply. |
 | `core/lib/engine.ts` | Optional style-engine contract, registry and capability dispatch. |
 | `core/lib/plugins.ts` | Importer/exporter contracts and registry. |
 | `core/lib/import.ts` | Bounded source dispatch and exclusive conversion publication. |
 | `core/lib/ops.ts` | Structural frame operations: insert, move, wrap and related edits. |
 | `core/lib/runtime.js` | Accepted state, writer queue, replay, persistence, watching and assets. |
 | `core/lib/history.ts` | Session point identity/lineage, not replay or persistence. |
-| `core/lib/contract.ts` | Host-neutral operations, schemas, result shaping and sessions. |
+| `core/lib/tools.ts` | Portable tool list, schemas and result vocabulary (every host runs these). |
+| `core/lib/contract.ts` | Sessions and board resolution over `tools.ts`, which it re-exports. |
+| `core/lib/browser-runtime.ts` | Browser-local project writer over the shared kernel; no files, assets, sites or conversation. |
+| `core/lib/browser-board.ts` | Static-site composition: the browser writer, board ports, MCP provider and IndexedDB copy. |
+| `core/lib/browser-mcp.ts` | `@divlet/core/browser-mcp`: agent-side transport to a website's browser MCP provider. |
 | `core/lib/output.ts` | Generated-file hashes/MIME provenance, collision checks and safe publication. |
 | `core/lib/static.js` | Resource closure/previews and bounded declared-byte HTML export. |
 | `core/lib/server.ts` | Token-scoped board HTTP and preview boundary. |
@@ -163,6 +170,7 @@ Timeline reads are lazy while History is closed and serial/coalesced while visib
 | `core/lib/hub.ts` | Collection launcher and its local HTTP surface. |
 | `pi/lib/extension.js` | Pi tools, session bridge and board conversation. |
 | `mcp/lib/server.js` | MCP stdio representation and sampling bridge. |
+| `mcp/lib/connect.js` | `divlet-mcp --connect`: stdio adapter for a website's browser-hosted tools. |
 | `cli/index.js` | Standalone command entry. |
 | `web/` | Native ES-module board, canvas, panels, inspector and palette. |
 

package/docs/board.md

@@ -18,7 +18,7 @@ Drag the label or body in Select mode, with snapping to neighbors (`Alt` disable
 
 ### Pi
 
-`A` opens the Agent tab's composer. Above the box a context header says what the request is about (*About A space for ideas › #nav*, or the whole board when nothing is selected), and while the conversation is empty three starting points fill the box without sending anything. The context header can wrap without overlapping the input and describes the request field for screen readers. The sidebar tabs adapt to their own row width, even when folded: icons always stay to the left of complete labels, never above them. Counts may wrap beneath the label in the text column when needed, without growing the tab row. For an element, breadcrumbs show artboard › container › … › element at bottom centre between the tabs and toolbar, wrapping when space is short. Selecting the whole artboard folds that path to one root-element icon. Click it (or focus it and press Enter/Space) to select the actual root and reopen the path; the artboard crumb folds it back, with keyboard focus preserved. A late root-data read never takes selection back after another navigation. The hierarchy lives in Layers, not in the inspector. Layers has two sections: a compact artboard list at the top, showing about seven rows before scrolling and synchronized with canvas selection, and the selected artboard's tree below, starting at its root `main`. Element IDs are editable in the inspector; all references update, but parts of a component used by other frames cannot be renamed. Send stays at the footer's bottom-right corner, whether selectors/key hints share its row or wrap above it. `↵` sends, `⇧ ↵` inserts a newline and `↑` recalls previous requests. Requests queue while Pi is busy. The corner indicator shows the current activity and elapsed time; ■ stops Pi. Replies appear in the Agent tab, where each one has a Copy button; the tab keeps the conversation, History lists the changes it caused.
+`A` opens the Agent tab's composer. Above the box a context header says what the request is about (*About A space for ideas › #nav*, or the whole board when nothing is selected), and while the conversation is empty three starting points fill the box without sending anything. The context header can wrap without overlapping the input and describes the request field for screen readers. The sidebar tabs adapt to their own row width, even when folded: icons always stay to the left of complete labels, never above them. Counts may wrap beneath the label in the text column when needed, without growing the tab row. For an element, breadcrumbs show artboard › container › … › element at bottom centre between the tabs and toolbar, wrapping when space is short. Selecting the whole artboard shows the artboard as the current crumb, then › and a `root` crumb for the next level. Click it (or focus it and press Enter/Space) to select the actual root; the artboard crumb selects the artboard again, with keyboard focus preserved. A late root-data read never takes selection back after another navigation. The hierarchy lives in Layers, not in the inspector. Layers has two sections: a compact artboard list at the top, showing about seven rows before scrolling and synchronized with canvas selection, and the selected artboard's tree below, starting at its root `main`. Element IDs are editable in the inspector; all references update, but parts of a component used by other frames cannot be renamed. Send stays at the footer's bottom-right corner, whether selectors/key hints share its row or wrap above it. `↵` sends, `⇧ ↵` inserts a newline and `↑` recalls previous requests. Requests queue while Pi is busy. The corner indicator shows the current activity and elapsed time; ■ stops Pi. Replies appear in the Agent tab, where each one has a Copy button; the tab keeps the conversation, History lists the changes it caused.
 
 ### Elements