@divlet/core 0.0.2 → 0.0.3

package/AGENTS.md

@@ -45,17 +45,18 @@ divlet is a local browser layout board for agents. It edits validated static HTM
 - **Embedded-resource target:** Project-owned file-asset bytes belong in the native `.divlet`, with only disposable materialization under `.divlet/<project>/assets/` beside generated pages. A canonical sibling `assets/` folder or a cache-only copy is not the target. The declared hierarchical `assets` tree owns reusable names/paths; explicit references materialize those files, while literal Data URLs at use sites remain inline. Never automatically extract inline URLs or rename declared keys merely to deduplicate bytes. Implement storage/reference validation, byte budgets and all resource consumers coherently before claiming this capability; preserve existing resources until conversion retains their bytes. Preserve the existing bounded local-resource import model; resource identifiers never authorize executable content or unrequested network fetches.
 - **Public demo data:** Never use `runtime.info()` as a public snapshot template: it includes private paths and session/editor state. Project inspection data only from explicitly curated public prepared content, with an allowlisted state shape and deliberate presentation geometry. Keep prepared HTML as rendering authority; metadata omission/model validity do not establish provenance, content secrecy, reference closure or whole-UI read-only enforcement.
 - **One authored landing:** Each example owns its folder. The canonical English onboarding/demo source belongs at `examples/landing/landing.divlet`; its `index` frame generates `examples/landing/.divlet/landing/index.html`. Keep identity, commands and release status consistent with the root README. Do not maintain a second hand-authored HTML site or marketing tree in core code. Other bundled examples may remain importer/site/layout scenarios, not duplicate landing sources. Any composition that seeds workspaces from this template must create an independently owned validated copy, never edit the installed master; explicit paths and no-demo creation remain authoritative.
-- **The landing build is derived, tracked and selectively published:** the named `examples/landing/.divlet/landing/` build is an explicit exception to ignoring generated project output, not permission to hand-edit it or commit arbitrary caches. Regenerate through normal validation and output ownership; a fresh checkout must rebuild safely, with portable provenance where required. Never track locks, recovery trash or session capabilities. CI publishes the prepared portable HTML/CSS/resource set to the `gh-pages` root, not a raw cache-directory copy: sidecars, ownership metadata, trash and editor/private payloads are not public artifacts. `scripts/landing-hash.mjs` owns both the published file set and its fingerprint; unchanged public bytes mean no deployment commit. Check source/build freshness in a relocated sandbox, preserve self-contained rendering and relative URLs, and do not mistake this architecture for authorization to push or deploy. Keep the canonical source/assets in the npm example payload, but exclude this cache; the Pages public set adds only its required `.nojekyll` marker and fingerprint record, not editor metadata.
+- **The landing build is derived, tracked and selectively published:** the named `examples/landing/.divlet/landing/` build is an explicit exception to ignoring generated project output, not permission to hand-edit it or commit arbitrary caches. Regenerate through normal validation and output ownership; a fresh checkout must rebuild safely, with portable provenance where required. Never track locks, recovery trash or session capabilities. CI publishes the prepared portable HTML/CSS/resource set to the `gh-pages` root, not a raw cache-directory copy: sidecars, ownership metadata, trash and editor/private payloads are not public artifacts. `scripts/pages-build.mjs` owns the Pages set (the static board plus this page under `page/`) and its fingerprint, and `scripts/landing-hash.mjs` owns the prepared page's subset; unchanged public bytes mean no deployment commit. Check source/build freshness in a relocated sandbox, preserve self-contained rendering and relative URLs, and do not mistake this architecture for authorization to push or deploy. Keep the canonical source/assets in the npm example payload, but exclude this cache; the Pages public set adds the static board's own files, its `.nojekyll` marker and fingerprint record, never editor metadata or private payloads.
 - **The inspector is one vertical flow:** Section summaries are the only section-navigation controls; do not duplicate them in horizontal tabs, floating jump bars or reorder strips. Keep sections in their owning panels' stable order and remember open/closed state as a local preference, not project content. Text alignment belongs beside text colour, size and weight in Appearance; Layout owns container and item alignment. The read-only measured X/Y/W/H and overflow block is the final section, after metadata. Use native keyboard-accessible disclosure controls, unobstructed vertical scrolling and whole label/control units that reflow at narrow widths; minimal chrome must not remove access to properties.
 - **A block header names the block:** A section's caption says what the section is ("Artboards", "Elements"), not which item is selected — the selection is already lit in the list or tree it belongs to, and repeating its name costs the width a narrow panel needs. Detail about the current choice belongs on the row, in a tooltip, or in the empty state, never in the header.
 - **One slot, one occupant:** When a host can do something another cannot, the control replaces the affordance it stands in for rather than stacking beside it — the composer's footer is either the key hints (a host that can only answer prompts) or the model/thinking selectors (a host that owns the session), never both. Pi users are assumed to know the shortcuts; the selectors carry their tips, and `?` still lists every key. Send remains the footer's bottom-right action when either occupant wraps: use its own auto margin and bottom alignment, not a preceding flex spacer.
 - **Entry points say what they are:** The root `@divlet/core` package's entry is the product library, with named public subpaths such as `./runtime`, `./contract`, `./model`, `./boards`, `./plugins`, `./engine` and the shared `./skill` resource. It has no bins, Pi manifest/peer requirements or `./pi` export. Each adapter package owns its `dist/index.js` entry, exports and relevant bin or `pi.extensions`; host-specific keywords and dependencies stay there. A folder-scanning Pi installation targets the built `pi` package, never the repository root. Source execution uses the `divlet-source` export condition; `scripts/source.mjs` propagates it through `NODE_OPTIONS` to children. The npm workspace includes `.`, `web`, `cli`, `mcp`, `pi` and `plugins/*`. The root remains the `@divlet/core` library manifest, not a private wrapper. `web/package.json` owns `@divlet/web` directly; its DOM-only build compiles public ports and copies native browser assets only to `web/dist/`, never into the core tarball. Development runs sources; `dist/` is publishing output only.
+- **Browser-hosted MCP:** a static site may be its own MCP provider ([browser-hosted MCP](docs/browser-mcp.md)). `@divlet/web/mcp` owns the page side (one tool registry for MCP and WebMCP, MCP 2026-07-28 only, no host calls); `core/lib/browser-mcp.ts` owns the agent-side transport and `mcp/lib/connect.js` its stdio adapter. Expose no binding or callable route to the page, treat everything it returns (descriptions, annotations, results, errors) as untrusted website text, bind a connection to one origin and provider instance, and never retry a call interrupted by a reload. The static board composition (`core/lib/browser-board.ts`) runs the shared contract tools on `BrowserRuntime`; keep its parity vectors with the Node writer green and report Node-only capabilities as absent, never emulated.
 - **Host capabilities are advertised, not assumed:** anything only one host can do (the Pi extension can change the session's model and thinking level; an MCP client cannot) is published as data in the board state (`agent.controls`), turned into a control when present and **absent** when not — never a disabled control, never a guessed value. The board stores no session setting as project content, asks only for values the host listed, and shows what the host reported applying. The host is the authority; the board is a view.
 - **Scope discipline:** Preserve unrelated work. Do not publish, tag or deploy without explicit authorization.
 
 ## Interface rules
 
-- **Chrome layout:** Islands stay in place: DIVLET button and search (top left, separate pills), the three tabs (bottom left, separate pills that join the sidebar when it opens) and the toolbar (bottom right) with the inspector attached above it. The sidebar (Layers / History of changes / Agent conversation) is one homogeneous surface: no horizontal border dividers, nested darker areas instead. Breadcrumbs sit bottom centre only (wrapping when narrow; sidebars cover them on phones). A single selected artboard folds the path to an accessible root-element icon; activating it selects the actual root and opens the path, while the artboard crumb folds it again. Keep keyboard focus in that path across folding/unfolding and refuse late root reads after a newer navigation. Select-root belongs here, not the artboard/inspector action menus; Rename is likewise absent from those menus, with direct name editing, R and palette access retained. A tab both switches and, when already open, folds the sidebar. Tab density follows the tab row's own width, not pane visibility: icons always stay to the left of complete text labels, never stacked above them. Counters may wrap within the text column when needed; folding must not reset that layout or change the tab row height. The composer's context header has intrinsic height and a real gap before the input, including when it wraps.
+- **Chrome layout:** Islands stay in place: DIVLET button and search (top left, separate pills), the three tabs (bottom left, separate pills that join the sidebar when it opens) and the toolbar (bottom right) with the inspector attached above it. The sidebar (Layers / History of changes / Agent conversation) is one homogeneous surface: no horizontal border dividers, nested darker areas instead. Breadcrumbs sit bottom centre only (wrapping when narrow; sidebars cover them on phones). The artboard crumb is never hidden. With a single artboard selected it is the current crumb, followed by a separator and a `root` crumb — the one exception to ending at the selection, previewing the next level; activating it selects the actual root, and the artboard crumb selects the artboard again. Keep keyboard focus in the path across these changes and refuse late root reads after a newer navigation. Select-root belongs here, not the artboard/inspector action menus; Rename is likewise absent from those menus, with direct name editing, R and palette access retained. A tab both switches and, when already open, folds the sidebar. Tab density follows the tab row's own width, not pane visibility: icons always stay to the left of complete text labels, never stacked above them. Counters may wrap within the text column when needed; folding must not reset that layout or change the tab row height. The composer's context header has intrinsic height and a real gap before the input, including when it wraps.
 - **One filesystem browser:** `web/lib/file-picker.js` owns the reusable path field, parent navigation, listing rows, keyboard navigation and latest-read/disposal guards. Open/copy and Settings compose it instead of maintaining separate browsers. Inject the read-only listing; keep confirmation, relative-output conversion, project writes and modal lifetime in the owning workflow. Reuse it for equivalent filesystem choices, not for resource galleries with different admission semantics.
 - **Two homes, at most, for an action:** Keep one natural control location plus the general indexes (shortcuts, command palette/search, agent tools), never duplicated interface controls. Before adding one, name its homes and search for existing affordances; move or merge rather than copy. Closing the left sidebar is the active tab (or `L`/`H`), not a separate panel/corner close button.
 - **UX stability:** Errors, statuses and progress never move controls: messages render after the controls they concern, progress is drawn on the element that is working, action buttons keep a stable size. The Agent activity plaque is a five-column, three-row grid: indicator at the start, activity text across the upper rows, time in the footer and Stop in the bottom-right cell; do not squeeze them back into one flex row. While busy and the entire left sidebar is folded, move that same plaque above the tabs at the remembered sidebar width, never clone it or add a second Stop. In this floating form, put the spinner in the bottom-left cell, vertically centred with the timer and Stop in the footer, and let the description span the full width above; the open-panel indicator stays in its original upper cell. Tabs stay put; long floating activity scrolls inside its bounded text area, and phone sheets clear the measured footer. Idle and expanded browsing show no floating plaque.

package/BACKLOG.md

@@ -45,8 +45,9 @@ Checkpoint: managed HTML edits map back to the correct native objects through gu
 
 The user authorized incremental implementation of the [browser runtime direction](docs/browser-runtime.md). Scope: shared portable semantics, a capability-truthful static demo and separately proven browser-agent connectivity; not unrelated product/assets work, a wholesale rewrite or additional format-freeze prerequisites. Continue through independently validated checkpoints. No publication, deployment or Service-Worker-as-public-MCP assumption.
 
-- [ ] **BROWSER-DEMO — Prove a static-hosted, capability-truthful board demonstration.** Next provide a semantic prepared-preview path and hide/refuse mutation affordances using actual host capabilities rather than synthesizing HTTP routes. Compose the existing allowlisted public-page producer and read-session/snapshot seam with browser-local selection/observations, absent native History/source-update services and the real board UI under a repository prefix, without Node API/SSE rescue. Audit project/codec/assets/tool-schema dependencies only as needed; standalone-frame and opaque snapshot proofs do not establish whole-project acceptance, component expansion or rendering/resource support. Keep onboarding readable and the demo opt-in; no second authored landing or recursive editor iframe. Verify clipboard actions, private-project non-upload, accurate absent capabilities, first visit versus offline reload, versioned cache updates and startup/bundle cost. Offline editing additionally needs persistence/failure/download/reopen and multi-tab ownership evidence; do not infer it from a read-only demo.
-- [ ] **BROWSER-AGENT — Validate browser-native tools and external-agent transport separately.** Inspect WebMCP support and demonstrate real tool registration/call/refusal/cancellation with a participating browser agent before adopting an adapter. The Community Group draft and a property probe are not interoperability proof. For ordinary external MCP clients, prototype only an explicitly paired local/extension bridge with origin/document/project/session capabilities and browser network-policy checks; no default cloud relay, wildcard CORS, localhost probing or Service-Worker-as-public-server claim. Preserve the existing operation vocabulary and authenticated preview boundary.
+- [ ] **BROWSER-DEMO — Finish the static board beyond its first deployment.** The Pages build runs the real board on `BrowserRuntime` with absent native capabilities, IndexedDB persistence and Chromium evidence (`web/tests/pages.mjs`); see [browser-hosted MCP](docs/browser-mcp.md). Still open: deployment itself (maintainer-authorized push to `main`), offline reload with a versioned Service Worker cache, startup/bundle cost measurement (the host bundle carries parse5/PostCSS), multi-tab ownership of one browser copy, and an explicit reset-to-published control. Utility compilation, embedded assets and fonts in the browser need a browser style-engine composition and a portable WHATWG MIME/base64 slice with the Node decoder's exact canonicalization; until then they stay refused or reported, never approximated.
+- [ ] **BROWSER-WRITER — Share one writer orchestration between Node and the browser.** `BrowserRuntime` mirrors `runtime.js` step for step over shared kernel modules and is held to it by `core/tests/browser-runtime.test.js`. Extract the accepted-state/history orchestration so both hosts run one implementation with persistence, publication and site hooks injected, then keep the parity vectors as regression evidence.
+- [ ] **BROWSER-AGENT — Prove WebMCP with a participating browser agent; extend the browser MCP surface only with evidence.** The provider, transport and `--connect` adapter are implemented and tested against the official SDK; WebMCP registration is tested only against a draft-shaped stand-in because no available Chromium ships `document.modelContext`. Still open: a real WebMCP agent calling, refusing and cancelling a tool; a native Pi `/connect` (no stdio hop); page-driven `notifications/tools/list_changed` through `subscriptions/listen`; attaching to an already running user browser. Resources, prompts, multi-round-trip input and tasks are not planned until a provider needs them.
 - [ ] **BROWSER-NODE22-COLD — Capture a reliable reproduction of a pre-model package-reader refusal.** One default-parallel focused run on Node 22.19 raised `ERR_INVALID_PACKAGE_CONFIG` for the valid repository manifest during the new cold-source import, before model execution. An isolated import, serial 125-check run, three controlled parallel runs and the full 569-check parallel unit suite passed; that does not establish the cause or a fix. Retain `artifacts/browser-model-portability-first-failure.log` and diagnostic logs. If it recurs, capture manifest identity/read/descriptor diagnostics and compare the unchanged baseline; do not add retry-until-green, weaken the cold-provider assertion or claim proven flakiness. Further causal work is gated on reproduction in a frozen checkout rather than repeated unchanged reruns; concurrent manifest edits occurred in this shared checkout and must be excluded before attributing the failure to Node or the model.
 
 ## P1 — onboarding template initialization
@@ -83,6 +84,4 @@ Complete the remaining migration under `strict` + `erasableSyntaxOnly`, preservi
 
 ## Gated
 
-- [ ] **NPM-CI — Finish the first trusted CI publication.** Three pre-publication runs exposed two test preconditions (initial dock measurement and font-dependent paired-row width) and the project picker's fixed-width primary button. Those are corrected; the button regression now forces wider fonts and preserves the exact control-position assertion. All publisher jobs remained skipped. The maintainer authorized replacement of the failed `v0.0.2` tag only after refreshed no-consumed-release-state checks. Complete a correlated successful CI run, five registry-integrity/installed-host checks and GitHub Release. Preserve original failed-run evidence; npm bindings are not verified until actual OIDC publication. See [publishing](docs/publishing.md#github-actions-publishing).
-- [ ] **RELEASE-GIT — Complete GitHub release delivery only when separately authorized.** Verify origin/permissions, remote history, automation and the intended `v0.0.1` target against the published npm candidate (`ea62291`, manifest in ignored `artifacts/releases/0.0.1-flat/`). Preserve immutable published bytes and local history; do not force-rewrite main or move a consumed release tag. Pushing the prepared source/cache changes can trigger Pages, so that deployment consequence also needs explicit authorization. See [publication](docs/publishing.md).
 - [ ] **LOCAL-PI — Refresh a legacy checkout installation only with operator approval.** Use the built top-level `pi/` package, never the root or removed `packages/pi`/`adapters/pi` paths. Coordinate local dependency refresh and reload with the session owner; do not restart active owners or discard their History as an installation shortcut.

package/CHANGELOG.md

@@ -2,11 +2,20 @@
 
 Implemented product outcomes live here. Contributor constraints are in [AGENTS.md](AGENTS.md), current contracts in [docs/](docs/README.md), and remaining work in [BACKLOG.md](BACKLOG.md).
 
-## 0.0.2 — candidate
+## 0.0.3 — candidate
+
+- **The board runs as a static site that is its own MCP provider.** `scripts/pages-build.mjs` builds the GitHub Pages set: the real board client with a bundled browser host that opens the canonical landing project in the visitor's browser, keeps the visitor's copy in IndexedDB until the publication changes, and exposes `read_divlet`, `patch_divlet`, `edit_divlet`, `frame_divlet`, `undo_divlet` and `mark_divlet` through the page's MCP provider (and WebMCP when a browser offers it). A first visit reads the landing expanded at the window's width, with live updates, one step from the board. Native-only affordances (opening files, save-as, build output, image/font upload, the board conversation) are absent there; Copy/Download HTML and "Download project file" run in the page. The Pages workflow tests the built set in Chromium and publishes it only when its fingerprint changes. Not yet deployed.
+- **`divlet-mcp --connect <url>`** connects any MCP host to such a website: the site opens in a managed, isolated Chromium and its tools run in the page. Both MCP eras are answered on stdio; website descriptions are marked as website text, annotations are dropped, results are reduced to text and JSON, cross-origin redirects are refused and a reloaded page is reconnected explicitly.
+- **Reusable browser MCP layers.** `@divlet/web/mcp` (one tool registry with bounded JSON Schema validation, an MCP 2026-07-28 browser provider with a versioned page endpoint, optional WebMCP registration) and `@divlet/core/browser-mcp` (the agent-side transport, also as an SDK-shaped `Transport`). The official MCP TypeScript SDK client interoperates with both.
+- **A browser-local project writer.** `BrowserRuntime` runs the shared contract tools over the shared kernel; shared vectors require identical models, pages, refusals, history and serialized projects to the Node runtime. `project`, `codec`, `diff`, `ops`, frame preparation, acceptance rules and the tool list no longer reach Node built-ins; embedded asset decoding refuses explicitly in browser builds.
+- Breadcrumbs keep the selected artboard visible as the current crumb, followed by › and a `root` step into its root element, instead of folding the path to a lone icon.
+- The board reaches its host through writer, preview, export and component ports; a complete alternative composition can replace the native HTTP routes without fallback.
+
+## 0.0.2 — 2026-11-13
 
 - Fixed Landing CI to resolve workspace sources in a fresh checkout, without depending on a previously generated web build. Browser activity checks now take their initial tab baseline after the newly visible toolbar reports its measured height, and paired typography checks use content width instead of a host-specific font-width assumption. Exact geometry assertions remain unchanged.
 - Project-picker action buttons reserve intrinsic space for all state labels, keeping controls fixed through loading/errors across host fonts and narrow layouts.
-- Added a manually dispatched `Release` GitHub Actions workflow with npm Trusted Publishing/OIDC, frozen five-package archives, serial web/core/adapter publication and registry-install verification through CLI/MCP and an isolated real Pi host. Preparation and verification have no publish token; uncertain or prior publication attempts block automatic replay. The first live CI publication is pending verification; this candidate does not freeze the native project format.
+- Added a manually dispatched `Release` GitHub Actions workflow with npm Trusted Publishing/OIDC, frozen five-package archives, serial web/core/adapter publication and registry-install verification through CLI/MCP and an isolated real Pi host. Preparation and verification have no publish token; uncertain or prior publication attempts block automatic replay. The first live CI release verified all five registry integrities and actual installed CLI/MCP/Pi behavior without a stored npm token. The native project format remains a pre-freeze draft.
 
 ## 0.0.1 — 2026-11-13
 

package/README.md

@@ -6,7 +6,7 @@ A local layout board for coding agents. Work with real HTML in live artboards, r
 
 [Quick start](#quick-start) · [Connect an agent](#connect-an-agent) · [Board guide](docs/board.md) · [Documentation](docs/README.md)
 
-> **0.0.2 · release candidate.** CI publication is being verified; 0.0.1 remains the last confirmed npm release until that completes. The native project format remains a pre-freeze draft; keep backups because future versions may require explicit conversion.
+> **0.0.3 · release candidate.** CI publication is being verified; 0.0.2 remains the last confirmed npm release until that completes. The native project format remains a pre-freeze draft; keep backups because future versions may require explicit conversion.
 
 ## Real pages, not pictures of pages
 
@@ -22,7 +22,7 @@ Requires **Node.js 22.19 or later**. Pi is optional.
 Open a standalone board:
 
 ```bash
-npx -y @divlet/cli@0.0.2 /absolute/path/to/workspace
+npx -y @divlet/cli@0.0.3 /absolute/path/to/workspace
 ```
 
 Or run from a source checkout:
@@ -35,7 +35,7 @@ npm start -- /absolute/path/to/workspace
 
 Open the URL printed in the terminal. An empty workspace gets `project.divlet` with a starter artboard; an existing project opens directly, and a folder with several projects opens the launcher.
 
-`npm run demo` opens the real onboarding page, [examples/landing/landing.divlet](examples/landing/landing.divlet). Its tracked, derived cache supplies GitHub Pages; see [editing and rebuilding the landing](examples/README.md). `npm run demo:site` opens the Markdown handbook in `examples/handbook/`; `examples/studio/` holds a separate layout scenario. Pencil import remains supported, but no authored PEN demo is bundled.
+`npm run demo` opens the real onboarding page, [examples/landing/landing.divlet](examples/landing/landing.divlet). On GitHub Pages the same project opens in the real board running entirely in your browser, which is also an MCP provider for agents ([browser-hosted MCP](docs/browser-mcp.md)); see [editing and rebuilding the landing](examples/README.md). `npm run demo:site` opens the Markdown handbook in `examples/handbook/`; `examples/studio/` holds a separate layout scenario. Pencil import remains supported, but no authored PEN demo is bundled.
 
 **First moves:** `V` selects, `P` lets the page behave normally, `L` opens Layers and `H` opens History. `Ctrl K` finds commands; `?` shows shortcuts. See the [board guide](docs/board.md) for direct editing, the inspector and touch controls.
 
@@ -46,7 +46,7 @@ Open the URL printed in the terminal. An empty workspace gets `project.divlet` w
 Install the Pi adapter:
 
 ```bash
-pi install npm:@divlet/pi@0.0.2
+pi install npm:@divlet/pi@0.0.3
 ```
 
 For checkout development, load the source adapter for a one-off session instead (no build needed):
@@ -84,7 +84,7 @@ Drop `--global` to install into the current project only. Skip this step under P
   "mcpServers": {
     "divlet": {
       "command": "npx",
-      "args": ["-y", "@divlet/mcp@0.0.2", "--cwd", "/absolute/path/to/workspace"]
+      "args": ["-y", "@divlet/mcp@0.0.3", "--cwd", "/absolute/path/to/workspace"]
     }
   }
 }
@@ -92,6 +92,16 @@ Drop `--global` to install into the current project only. Skip this step under P
 
 Call `open_divlet` and open its returned URL. No Pi installation is needed. Clients that support **sampling** can also answer requests typed in the board's Agent tab.
 
+### A board on a website
+
+The [Pages board](https://llblab.github.io/divlet/) is a static site that is its own MCP provider: register it by URL and the tools run in a browser page, on that site's project, with no server deployed for it. `--connect` ships with the 0.0.3 candidate of `@divlet/mcp`; until its publication is verified, run it from a checkout (`node scripts/source.mjs mcp/index.js --connect <url>`).
+
+```bash
+npx -y @divlet/mcp@0.0.3 --connect https://llblab.github.io/divlet/
+```
+
+The page opens in a managed browser window (headless without a display). Edits persist in that browser profile until the publication changes; utility compilation, images, fonts and opening other projects stay with the local server. Website descriptions and results are treated as website text, and redirects to other origins are refused. See [browser-hosted MCP](docs/browser-mcp.md) for the protocol, security boundaries and how to make another static app a provider.
+
 [Agent integration guide](docs/agents.md) → Alternative Pi installation, MCP options, the workflow skill and JavaScript entry points.
 
 <details>
@@ -110,7 +120,7 @@ npx -y @divlet/mcp --cwd ./workspace
 npm install -g @divlet/cli @divlet/mcp
 ```
 
-For Pi, run `pi install npm:@divlet/pi@0.0.2`. Shared setups should pin `@divlet/cli@0.0.2`, `@divlet/mcp@0.0.2` and `npm:@divlet/pi@0.0.2`. The root package has no commands or Pi manifest; there is no wrapper layer.
+For Pi, run `pi install npm:@divlet/pi@0.0.3`. Shared setups should pin `@divlet/cli@0.0.3`, `@divlet/mcp@0.0.3` and `npm:@divlet/pi@0.0.3`. The root package has no commands or Pi manifest; there is no wrapper layer.
 
 See [npm publication](docs/publishing.md) for version pinning, package identity and release gates.
 

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

@@ -0,0 +1,18 @@
+export declare const SETTINGS_FIELDS: readonly ["name", "tokens", "css", "metadata", "outputDir", "assets"];
+export declare const sameDocument: (a: any, b: any) => boolean;
+export declare const sameSettings: (a: any, b: any) => boolean;
+export declare const settingsPatch: (from: any, to: any) => Record<string, unknown>;
+/**
+ * A caller that names the state it read gets a refusal instead of silently overwriting a change it
+ * never saw (AGENTS.md, "Validated commits"). Omitted means the caller accepted whatever is current.
+ */
+export declare function assertExpectedVersion(expected: unknown, target: {
+    version: number;
+}, what?: string): void;
+/** The rendered page a gesture was made against; a dependent re-render advances it without a version bump. */
+export declare function assertExpectedRender(expected: unknown, entry: {
+    render: number;
+    document: {
+        version: number;
+    };
+}): void;

package/dist/core/lib/acceptance.js

@@ -0,0 +1,29 @@
+/*
+ * Owns: the host-independent acceptance rules every project writer applies — what counts as an unchanged frame or project,
+ * project-field diffs for history, and the expected version/render guards. Excludes: state, persistence and scheduling.
+ * The Node runtime and the browser runtime both import these, so a revision or no-op decision cannot differ between hosts.
+ */
+import { DivletError } from "./model.js";
+import { diffValue } from "./diff.js";
+import { sameJson } from "./validation.js";
+export const SETTINGS_FIELDS = ['name', 'tokens', 'css', 'metadata', 'outputDir', 'assets'];
+export const sameDocument = (a, b) => sameJson({ ...a, version: 0 }, { ...b, version: 0 });
+export const sameSettings = (a, b) => SETTINGS_FIELDS.every(key => sameJson(a[key], b[key]));
+export const settingsPatch = (from, to) => Object.fromEntries(SETTINGS_FIELDS.map(key => [key, diffValue(from[key], to[key])]).filter(([, value]) => value !== undefined));
+/**
+ * A caller that names the state it read gets a refusal instead of silently overwriting a change it
+ * never saw (AGENTS.md, "Validated commits"). Omitted means the caller accepted whatever is current.
+ */
+export function assertExpectedVersion(expected, target, what = 'frame') {
+    if (expected === undefined)
+        return;
+    if (!Number.isInteger(expected) || expected !== target.version)
+        throw new DivletError('REVISION_CONFLICT', `Expected ${what} version ${target.version}; received ${expected}. Read it again and rebuild the change.`, { actualVersion: target.version });
+}
+/** The rendered page a gesture was made against; a dependent re-render advances it without a version bump. */
+export function assertExpectedRender(expected, entry) {
+    if (expected === undefined)
+        return;
+    if (!Number.isInteger(expected) || expected !== entry.render)
+        throw new DivletError('RENDER_CONFLICT', `Expected frame render ${entry.render}; received ${expected}. The page changed since it was read; reload the frame and repeat the change.`, { actualRender: entry.render, actualVersion: entry.document.version });
+}

package/dist/core/lib/assets.js

@@ -104,7 +104,7 @@ function readTree(input, deletions) {
             if (paths.has(portable))
                 fail(`Asset paths alias on a portable filesystem: ${relative}.`);
             paths.add(portable);
-            encodedBytes += Buffer.byteLength(name) + (typeof value === 'string' ? value.length : 0);
+            encodedBytes += new TextEncoder().encode(name).byteLength + (typeof value === 'string' ? value.length : 0);
             if (encodedBytes > ASSET_LIMITS.encodedBytes)
                 fail('Assets exceed the encoded-byte limit.');
             if (value === null && deletions)

package/dist/core/lib/browser-board.d.ts

@@ -0,0 +1,41 @@
+import { BrowserRuntime } from './browser-runtime.ts';
+import type { FrameCompiler } from './prepare.ts';
+/** Build-time compiled CSS, keyed by the token set it was compiled for (see `scripts/pages-build.mjs`). */
+export interface StyleSnapshot {
+    readonly entries: ReadonlyArray<{
+        readonly tokens: Record<string, string>;
+        readonly candidates: readonly string[];
+        readonly css: string;
+    }>;
+}
+export interface BrowserBoardOptions {
+    readonly projectUrl: URL;
+    readonly stylesUrl: URL;
+    readonly storageKey: string;
+    readonly file: string;
+    readonly version: string;
+    /** The static preview bridge script (`previewBridgeScript()` output), served by the same site. */
+    readonly bridgeUrl: URL;
+    /** The frame a first visit opens as a readable page (absent: the board fits all frames). */
+    readonly entryFrame?: string;
+    readonly target?: object;
+}
+/**
+ * The browser host compiles no utilities: it serves the build-time stylesheet for the frame's token set, and reports a class
+ * as unknown when neither that build nor the frame's own CSS mentions it, so new utilities are diagnosed instead of dropped.
+ */
+export declare function snapshotCompiler(snapshot: StyleSnapshot): FrameCompiler;
+/**
+ * The preview page of one frame: the rendered HTML, a meta CSP and the static preview bridge with its arguments in a meta tag.
+ * A blob preview inherits the board page's CSP, so the bridge is a same-site script file rather than an inline script.
+ */
+export declare function previewDocument(html: string, id: string, render: number, bridge: string, bridgeUrl: string): string;
+/** The static bridge file: the trusted serialized preview bridge, started with the arguments its page carries. */
+export declare function previewBridgeScript(bridgeSource: string): string;
+/** Start the browser host and publish the board composition; resolves once the board can start. */
+export declare function startBrowserBoard(options: BrowserBoardOptions): Promise<{
+    runtime: BrowserRuntime;
+    restored: boolean;
+    webmcp: string[];
+    base: string;
+}>;

package/dist/core/lib/browser-board.js

@@ -0,0 +1,203 @@
+/*
+ * Owns: the static-site composition of the real board — one browser-local copy of a published project, the board's host ports
+ * over the browser writer, and the same contract tools exposed to agents through the page's browser MCP provider (and WebMCP
+ * when the browser has it). Excludes: the board UI itself (`@divlet/web`), any network service and the Node host's file,
+ * output, asset, font, site and conversation capabilities, which are absent here rather than emulated.
+ *
+ * Storage policy: the visitor's copy lives in this origin's IndexedDB, keyed by `storageKey` and tied to the fingerprint of the
+ * published source it started from. When the publication changes, the copy starts again from the new source. Nothing is
+ * uploaded; a private project is never fetched or paired.
+ */
+import { BrowserRuntime } from "./browser-runtime.js";
+import { inputSchema, forAgent } from "./tools.js";
+import { sameJson } from "./validation.js";
+import { createBrowserMcpProvider, exposeBrowserMcp, defineTools, registerWebMcpTools } from '@divlet/web/mcp';
+const HOST_KEY = Symbol.for('divlet.board-host/1');
+const READ_ONLY = new Set(['read_divlet']);
+/**
+ * The browser host compiles no utilities: it serves the build-time stylesheet for the frame's token set, and reports a class
+ * as unknown when neither that build nor the frame's own CSS mentions it, so new utilities are diagnosed instead of dropped.
+ */
+export function snapshotCompiler(snapshot) {
+    const pick = (tokens) => snapshot.entries.find(entry => sameJson(entry.tokens, tokens)) ?? snapshot.entries[0];
+    return {
+        compile: tokens => pick(tokens)?.css ?? '',
+        unknown: ({ tokens, css, byNode }) => {
+            const known = new Set(pick(tokens)?.candidates ?? []);
+            const out = {};
+            for (const [id, className] of Object.entries(byNode)) {
+                const dead = className.split(/\s+/).filter(name => name && !known.has(name) && !css.includes(`.${name}`));
+                if (dead.length)
+                    out[id] = dead;
+            }
+            return out;
+        },
+    };
+}
+async function fingerprint(text) {
+    const bytes = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text)));
+    return [...bytes].map(byte => byte.toString(16).padStart(2, '0')).join('');
+}
+function browserStore(name = 'divlet-browser') {
+    const open = () => new Promise((resolve, reject) => {
+        const request = globalThis.indexedDB.open(name, 1);
+        request.onupgradeneeded = () => request.result.createObjectStore('projects');
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    });
+    let db = null;
+    const handle = () => (db ??= open());
+    return {
+        async get(key) {
+            try {
+                const store = (await handle()).transaction('projects').objectStore('projects');
+                return await new Promise((resolve, reject) => { const request = store.get(key); request.onsuccess = () => resolve(request.result); request.onerror = () => reject(request.error); });
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async put(key, value) {
+            const tx = (await handle()).transaction('projects', 'readwrite');
+            tx.objectStore('projects').put(value, key);
+            await new Promise((resolve, reject) => { tx.oncomplete = () => resolve(); tx.onerror = () => reject(tx.error); tx.onabort = () => reject(tx.error); });
+        },
+        async delete(key) {
+            const tx = (await handle()).transaction('projects', 'readwrite');
+            tx.objectStore('projects').delete(key);
+            await new Promise((resolve, reject) => { tx.oncomplete = () => resolve(); tx.onerror = () => reject(tx.error); });
+        },
+    };
+}
+const escapeAttribute = (value) => value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+/**
+ * The preview page of one frame: the rendered HTML, a meta CSP and the static preview bridge with its arguments in a meta tag.
+ * A blob preview inherits the board page's CSP, so the bridge is a same-site script file rather than an inline script.
+ */
+export function previewDocument(html, id, render, bridge, bridgeUrl) {
+    const token = /^[a-f0-9-]{36}$/i.test(bridge) ? bridge : '';
+    // A path may legally contain CSP separators; encode them so the bridge address cannot add or end a directive.
+    const source = bridgeUrl.replace(/[;,\s'"]/g, character => `%${character.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`);
+    const csp = `default-src 'none'; img-src data: https: blob:; media-src data: https:; style-src 'unsafe-inline'; font-src data: https:; script-src ${source}; connect-src 'none'; base-uri 'none'; form-action 'none'`;
+    const meta = `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(csp)}"><meta name="divlet-bridge" content="${escapeAttribute(JSON.stringify({ id, render, token }))}">`;
+    return html.replace(/<head([^>]*)>/i, `<head$1>${meta}`).replace(/<\/body>(\s*<\/html>\s*)?$/i, `<script src="${escapeAttribute(source)}"></script></body>$1`);
+}
+/** The static bridge file: the trusted serialized preview bridge, started with the arguments its page carries. */
+export function previewBridgeScript(bridgeSource) {
+    return `(()=>{const m=document.querySelector('meta[name="divlet-bridge"]');if(!m)return;const a=JSON.parse(m.content);(${bridgeSource})(a.id,a.render,a.token,false,false);})();\n`;
+}
+/** Start the browser host and publish the board composition; resolves once the board can start. */
+export async function startBrowserBoard(options) {
+    const target = options.target ?? globalThis;
+    const [published, styles] = await Promise.all([
+        fetch(options.projectUrl, { credentials: 'omit' }).then(response => { if (!response.ok)
+            throw new Error(`The project could not be loaded (${response.status}).`); return response.text(); }),
+        fetch(options.stylesUrl, { credentials: 'omit' }).then(response => { if (!response.ok)
+            throw new Error(`The project styles could not be loaded (${response.status}).`); return response.json(); }),
+    ]);
+    const base = await fingerprint(published);
+    const store = browserStore();
+    const stored = await store.get(options.storageKey);
+    const compiler = snapshotCompiler(styles);
+    const persist = (text) => store.put(options.storageKey, { base, text, savedAt: new Date().toISOString() });
+    const open = (source) => BrowserRuntime.open({ source, file: options.file, projectId: `browser-${base.slice(0, 16)}`, compiler, persist, capabilities: { browser: true, assets: false, export: false } });
+    let runtime;
+    let restored = false;
+    if (stored?.base === base && typeof stored.text === 'string') {
+        try {
+            runtime = await open(stored.text);
+            restored = true;
+        }
+        catch {
+            await store.delete(options.storageKey).catch(() => { });
+            runtime = await open(published);
+        }
+    }
+    else {
+        if (stored)
+            await store.delete(options.storageKey).catch(() => { });
+        runtime = await open(published);
+    }
+    runtime.url = new URL('./', globalThis.location.href).href;
+    /* ---- the board's ports ---------------------------------------------------------------------------- */
+    const copy = (value) => structuredClone(value);
+    const previews = new Map();
+    const composition = Object.freeze({
+        label: 'browser',
+        readSession: Object.freeze({
+            readState: async () => copy(runtime.info()),
+            readFrame: async (id) => copy(runtime.read({ view: 'document', documentId: id })),
+            subscribe(listener) {
+                let active = true;
+                queueMicrotask(() => { if (active)
+                    listener({ type: 'connection', status: 'connected' }); });
+                const stop = runtime.subscribe((type, value) => { if (active)
+                    listener({ type, value: copy(value) }); });
+                return () => { active = false; stop(); };
+            },
+        }),
+        writer: Object.freeze({
+            patch: async (body) => copy(await runtime.patch({ ...body, actor: 'user' })),
+            edit: async (body) => copy(await runtime.edit({ ...body, actor: 'user' })),
+            undo: async () => copy(await runtime.undo({ actor: 'user' })),
+            redo: async () => copy(await runtime.redo({ actor: 'user' })),
+            createArtboard: async (body) => copy(await runtime.createArtboard({ ...body, actor: 'user' })),
+            deleteArtboard: async (body) => copy(await runtime.removeDocument({ ...body, actor: 'user' })),
+        }),
+        previews: Object.freeze({
+            frameUrl(id, { bridge }) {
+                const rendered = runtime.render(id);
+                const url = URL.createObjectURL(new Blob([previewDocument(rendered.html, id, rendered.render, bridge, options.bridgeUrl.href)], { type: 'text/html' }));
+                if (!previews.has(id))
+                    previews.set(id, new Set());
+                previews.get(id).add(url);
+                return url;
+            },
+            readRender: async (id) => copy(runtime.render(id)),
+            release(id, url) { if (previews.get(id)?.delete(url))
+                URL.revokeObjectURL(url); },
+        }),
+        components: Object.freeze({ list: async () => ({ components: copy(runtime.components()) }) }),
+        exports: Object.freeze({
+            page: async (id) => copy(runtime.exportDocument(id)),
+            project: async () => ({ text: runtime.source(), fileName: options.file }),
+        }),
+        historyService: Object.freeze({
+            readRecent: async () => copy(runtime.readHistory({ limit: 100 })),
+            navigate: async (target) => copy(await runtime.navigateHistory({ ...target, actor: 'user' })),
+        }),
+        // Selection and measurements are shared with the browser writer, so an agent reads what the visitor selected and sees.
+        shareSelection: async (selection) => copy(runtime.setSelection(copy(selection))),
+        publishObservations: async (report) => copy(runtime.setObservations(copy(report))),
+        ...(options.entryFrame && runtime.documents.has(options.entryFrame) ? { initialView: Object.freeze({ expand: options.entryFrame, title: 'Edit on the board' }) } : {}),
+    });
+    Object.defineProperty(target, HOST_KEY, { value: composition, configurable: false, enumerable: false, writable: false });
+    /* ---- the agent surface: the same contract tools ------------------------------------------------- */
+    let running = 0;
+    const tools = runtime.tools().map(tool => ({
+        name: tool.name,
+        ...(tool.title ? { title: tool.title } : {}),
+        description: tool.description,
+        inputSchema: inputSchema(tool),
+        annotations: READ_ONLY.has(tool.name) ? { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } : { readOnlyHint: false, destructiveHint: tool.name !== 'mark_divlet', openWorldHint: false },
+        async execute(args) {
+            running++;
+            runtime.setAgent({ connected: true, busy: true, activity: tool.title ?? tool.name, queued: running - 1 });
+            try {
+                return forAgent(await runtime.callTool(tool.name, args));
+            }
+            finally {
+                running--;
+                runtime.setAgent(running ? { busy: true, queued: running - 1 } : { busy: false });
+            }
+        },
+    }));
+    const registry = defineTools(tools);
+    const provider = createBrowserMcpProvider({
+        name: 'divlet', title: 'divlet in the browser', version: options.version, tools: registry,
+        instructions: `divlet is a layout board for agents. This page holds a browser-local copy of the ${options.file} project (HTML/SVG/CSS frames), stored only in this browser. Read the project with read_divlet, then change it with patch_divlet or edit_divlet using the versions you read; frame_divlet adds or removes frames and undo_divlet reverts. The visitor watches every change live. Utility classes are not compiled here: style with the frame css or inline style. Files, fonts, embedded assets and opening other projects need the local divlet host (npx -y @divlet/mcp).`,
+    });
+    exposeBrowserMcp(provider, target);
+    const webmcp = await registerWebMcpTools(registry);
+    return { runtime, restored, webmcp: webmcp.registered, base };
+}

package/dist/core/lib/browser-mcp.d.ts

@@ -0,0 +1,131 @@
+export declare const PROTOCOL_VERSION = "2026-07-28";
+/** The page surface this module drives (a Playwright `Page`, typed locally so core needs no Playwright types). */
+interface PageLike {
+    goto(url: string, options?: {
+        waitUntil?: 'load' | 'domcontentloaded';
+        timeout?: number;
+    }): Promise<unknown>;
+    url(): string;
+    evaluate<R, A>(fn: (arg: A) => R | Promise<R>, arg: A): Promise<R>;
+    waitForFunction<A>(fn: (arg: A) => unknown, arg: A, options?: {
+        timeout?: number;
+        polling?: 'raf' | number;
+    }): Promise<unknown>;
+    waitForLoadState(state?: 'load' | 'domcontentloaded', options?: {
+        timeout?: number;
+    }): Promise<void>;
+    mainFrame(): unknown;
+    on(event: string, listener: (...args: any[]) => void): unknown;
+    off(event: string, listener: (...args: any[]) => void): unknown;
+    close(): Promise<void>;
+    isClosed(): boolean;
+    bringToFront?(): Promise<void>;
+}
+interface ContextLike {
+    newPage(): Promise<PageLike>;
+    close(): Promise<void>;
+    on(event: string, listener: (...args: any[]) => void): unknown;
+}
+interface BrowserLike {
+    newContext(options?: Record<string, unknown>): Promise<ContextLike>;
+    close(): Promise<void>;
+    on(event: string, listener: (...args: any[]) => void): unknown;
+}
+export type ConnectionState = 'connecting' | 'ready' | 'stale' | 'closed';
+export interface ToolInfo {
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly annotations?: Record<string, unknown>;
+}
+export interface BrowserMcpOptions {
+    /** Origins besides the URL's own that the page may redirect to. Default: none — a redirect elsewhere fails. */
+    readonly allowedOrigins?: readonly string[];
+    /** Which website-supplied tools the agent may call. Default: all listed tools (the URL itself is the user's explicit choice). */
+    readonly allowTools?: readonly string[] | ((tool: ToolInfo) => boolean);
+    readonly timeoutMs?: number;
+    readonly readyTimeoutMs?: number;
+    readonly maxMessageBytes?: number;
+    readonly maxPending?: number;
+    readonly maxTools?: number;
+    readonly headless?: boolean;
+    /** Reuse a caller-owned browser (a new isolated context is still created) or a caller-owned context. */
+    readonly browser?: BrowserLike;
+    readonly context?: ContextLike;
+    /** A Chromium executable or Playwright channel to launch; by default the system Chrome, then Playwright's Chromium. */
+    readonly executablePath?: string;
+    readonly channel?: string;
+    /** Opt-in persistent profile directory (so the site's IndexedDB survives restarts). Default: an ephemeral context. */
+    readonly userDataDir?: string;
+    readonly clientInfo?: {
+        name: string;
+        version: string;
+    };
+    readonly onEvent?: (event: BrowserMcpEvent) => void;
+}
+export type BrowserMcpEvent = {
+    type: 'ready';
+    origin: string;
+    instance: string;
+    tools: number;
+} | {
+    type: 'stale';
+    reason: string;
+} | {
+    type: 'closed';
+    reason: string;
+} | {
+    type: 'warning';
+    message: string;
+};
+/** A local failure of this side (never a JSON-RPC error from the page). */
+export declare class BrowserMcpError extends Error {
+    readonly code: string;
+    readonly data?: unknown;
+    constructor(code: string, message: string, data?: unknown);
+}
+/** A JSON-RPC error the page returned. */
+export declare class BrowserMcpRemoteError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+export interface CallOptions {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+export interface BrowserMcpConnection {
+    readonly url: string;
+    readonly origin: string;
+    readonly state: ConnectionState;
+    /** The provider's `server/discover` result for the current instance (untrusted, page-supplied). */
+    readonly discovery: Record<string, unknown> | null;
+    /** Tools of the current provider instance that the trust policy allows. Descriptions are untrusted, page-supplied text. */
+    readonly tools: readonly ToolInfo[];
+    /** Send one MCP request; per-request `_meta` is attached. Resolves with the result object. */
+    request(method: string, params?: Record<string, unknown>, options?: CallOptions): Promise<Record<string, unknown>>;
+    /** `tools/call` for an allowed tool. Resolves with the MCP `CallToolResult`. */
+    callTool(name: string, args?: Record<string, unknown>, options?: CallOptions): Promise<Record<string, unknown>>;
+    /** Re-discover after a reload (or navigate back to the URL when the page is gone from it); refreshes the tool list. */
+    reconnect(): Promise<void>;
+    close(): Promise<void>;
+    /** The managed page, for an embedding harness that shows or screenshots it. */
+    readonly page: PageLike;
+}
+/** Open `url` and connect to its browser MCP provider. */
+export declare function connectBrowserMcp(url: string, options?: BrowserMcpOptions): Promise<BrowserMcpConnection>;
+/**
+ * An SDK-shaped `Transport` (start/send/close/onmessage/onclose/onerror) over one connection, for an MCP client library that
+ * accepts custom transports. It carries messages as they are; the client attaches its own per-request `_meta`. When the
+ * provider goes stale or closes, the transport closes, so the client rejects its pending requests and must connect again.
+ */
+export declare function browserMcpTransport(connection: BrowserMcpConnection): {
+    onmessage: ((message: unknown) => void) | undefined;
+    onclose: (() => void) | undefined;
+    onerror: ((error: Error) => void) | undefined;
+    start(): Promise<void>;
+    send(message: unknown): Promise<void>;
+    close(): Promise<void>;
+};
+export {};