mesurer-solid 0.2.1-beta.9 → 0.2.2-beta.0

package/AGENT_INTEGRATION.md

@@ -1,13 +1,13 @@
 # Mesurer agent integration
 
-Mesurer's agent integration is the rendered page itself. The coding agent reads `window.__MESURER__` through the browser control it already has, consumes human visual intent, edits normal application source, and verifies the real Live result.
+Mesurer's agent integration is the rendered page itself. This guide matches `mesurer-solid@0.2.1` stable. The coding agent reads `window.__MESURER__` through the browser control it already has, consumes human visual intent, edits normal application source, and verifies the real Live result.
 
-The normal agent workflow requires no Mesurer MCP server, localhost daemon, Send-to-agent callback, or browser-tool-specific transport. The optional `codex()` plugin is a separate human convenience path for sending Context feedback through the native host's Codex transport; it does not replace the browser-state contract described here.
+The normal agent workflow requires no Mesurer MCP server, Send-to-agent callback, or special browser transport. The optional `codex()` plugin is a separate human convenience path for sending Context feedback into local Codex threads; it does not replace the browser-state contract described here. In Electron it can use the native preload bridge. In an ordinary browser it can use the local Mesurer Codex Bridge companion on loopback. Neither path is the Mesurer Solid ChatGPT/Codex agent plugin.
 
 ## Install the agent skill
 
 ```bash
-npx --yes --package=mesurer-solid mesurer-skill install
+npx --yes --package=mesurer-solid@latest mesurer-skill install
 ```
 
 
@@ -18,16 +18,27 @@ The installer writes a self-contained skill and injection artifact:
 ├── SKILL.md
 └── assets/
     ├── mediabunny-vendor.js
-    └── inject-script.js
+    ├── inject-script.js
+    ├── codex-bridge.mjs
+    ├── codex-connect.mjs
+    └── codex-lifecycle.mjs
 ```
 
 ## Know the available capabilities
 
-The base inspector includes Select, X-ray, Rulers, Typography, Guides, Distance, and Settings. Color Picker uses application-local host capture when available and otherwise uses a working browser `EyeDropper`.
+The base inspector includes Select, X-ray, Color Picker, Rulers, Typography, Guides, Distance, and Settings. Color Picker uses application-local host capture when available and otherwise uses a working browser `EyeDropper`.
 
-First-party plugins add Context, Edit, Screenshot, Recording, and optional Codex delivery. Recording is a human video-capture workflow with a typed `recording:v1` service; it is not the normal coding-agent evidence channel. Edit movement preserves the existing Arrange agent method names for compatibility. The complete public map, including the low-level inspection methods and plugin host, is in [Capabilities](../../docs/CAPABILITIES.md).
+First-party plugins add Context, Edit, Layout Guides, Screenshot, Recording, and optional Codex delivery. Recording is a human video-capture workflow with a typed `recording:v1` service; it is not the normal coding-agent evidence channel. Edit movement preserves the existing Arrange agent method names for compatibility. The complete public map, including the low-level inspection methods and plugin host, is in [Capabilities](../../docs/CAPABILITIES.md).
 
-For normal coding-agent work, use `window.__MESURER__`. Use `window.__MESURER_INSTANCE__` only when the task requires mounted-instance or plugin-host operations.
+Rulers, ordinary Guides, and Layout Guides remain available while the human is in Edit; X-ray, Color Picker, Typography, Screenshot, and Recording remain Select-lane tools. For normal coding-agent work, use `window.__MESURER__`. Use `window.__MESURER_INSTANCE__` only when the task requires mounted-instance or plugin-host operations.
+
+## Use the visible Mesurer UI when it is the best interface
+
+Mesurer does not require an agent-specific transport for ordinary interaction. A browser or computer-use harness can click and drag the live Mesurer interface exactly as a person can. Use that path for exploratory visual work, mode/tool changes, Guides/Layout Guides, Edit movement, Typography, Screenshot, Recording, Settings, and other inspector UI.
+
+Use `window.__MESURER__` when the answer is better represented as exact structured evidence: selectors, geometry, distances, computed styles, Context, saved intent, or review deltas.
+
+Stable Mesurer-owned automation hooks are documented in [Browser and agent integration](../../docs/BROWSER_HARNESS.md). The optional local ChatGPT/Codex plugin adds semantic MCP shortcuts over this same contract; it does not replace browser control. See [ChatGPT and Codex plugin](../../docs/CHATGPT_CODEX_PLUGIN.md).
 
 ## Reuse a live instance
 
@@ -246,17 +257,15 @@ The optional human `screenshot()` plugin from `mesurer-solid/plugins` is a separ
 
 ## Optional human-to-Codex delivery
 
-The first-party `codex()` plugin starts enabled when the native host capability exists. Browser-only hosts list it in Settings but start with it off. It is a human-triggered delivery path and does not add a generic send method to `window.__MESURER__`.
-
-Native hosts expose `window.__MESURER_HOST__.codexBridge(request)`. Electron main can install `installMesurerCodexHost()`, and a bundled preload can expose `createMesurerCodexPreloadBridge()`. Turning Codex on waits for a native lease and transport readiness. Turning it off waits for lease release before Mesurer removes the plugin. Shared sessions use Codex's existing local app-server. When the host inherits both `CODEX_THREAD_ID` and `CODEX_APP_TOOLS_PIPE_PATH` from Codex Desktop, Mesurer exposes only that exact Desktop thread, queues once through Codex's native queue command, and wakes the same thread with `codex://threads/<id>`. The app-tools pipe is an ownership signal only and is never opened. There is no Mesurer Codex daemon, localhost listener, marketplace plugin, or Codex SessionStart/SessionEnd hook.
+The first-party `codex()` plugin is Mesurer's **Settings -> Codex** feature. It is not the OpenAI Mesurer Solid agent plugin.
 
-Shared delivery exposes currently loaded Codex threads. Desktop fallback exposes only the exact inherited current thread and refuses any other destination. Page affinity and explicit destination overrides remain fail-closed.
+Electron hosts with `window.__MESURER_HOST__.codexBridge(request)` can use the in-process native bridge and start Codex enabled. Browser hosts still show Codex in Settings but start with it off. When enabled, the browser plugin talks to the local Mesurer Codex Bridge companion at `127.0.0.1:47365`, verifies its versioned capabilities before use, and reconnects automatically when a compatible helper appears. Missing, outdated, or conflicting helpers remain explicit fail-closed states.
 
-Shared delivery calls `thread/queue/add` directly. Desktop current-thread delivery uses the native queue command only for that exact inherited thread. Mesurer never calls `turn/steer`, never creates a thread, and never reconstructs a second user-message queue. The typed `codex:v1` service exposes `health()`, `listThreads()`, `useThread(thread)`, `delivery(deliveryId)`, and canonical `queue(request?)`. `send(request?)` remains a compatibility alias.
+The optional local **Mesurer Codex Bridge** helper can be installed into Codex so SessionStart starts or reuses the loopback companion and registers the current local Codex session; SessionEnd unregisters that ownership. Compatible protocol/capability versions are reused across checkouts even when their source hashes differ. An incompatible helper is replaced only when it proves it is idle, and an ownerless helper remains alive until queued/working Mesurer deliveries become terminal. Non-terminal delivery receipts are retained across long restarts without an age TTL; only terminal history is TTL-pruned. The npm package also exposes `mesurer-codex` and `mesurer-codex-connect` for diagnostics.
 
-Shared queue submission is single-flight while Mesurer tracks lifecycle. Desktop current-thread delivery keeps its durable queued receipt visible without blocking a later explicit queue action. A matched completed turn may remove only the annotation ids sent with that delivery; interrupted, failed, ambiguous, or unreadable work keeps them. Turn completion is transport state, not proof that the requested UI result is correct.
+Both renderer transports expose the same `codex:v1` service. Shared sessions queue through Codex's local app-server. Exact Desktop-current-thread delivery can use one durable Codex queue operation plus the native `codex://threads/<id>` wake. The private app-tools pipe is never opened.
 
-See [Queue Context feedback to Codex](../../docs/CODEX.md) for host wiring, routing, recovery, privacy, and failure behavior.
+Browser companion state and the native Electron bridge are local-machine transports only. Neither is a hosted Mesurer relay, and neither changes how coding agents consume `window.__MESURER__`. Turning the human Codex plugin off cleans only resources owned by that Mesurer renderer: browser polling/tools or the Electron renderer lease. It does not stop shared Codex infrastructure.
 
 ## Revalidate after source edits
 

package/README.md

@@ -4,6 +4,8 @@ Framework-agnostic UI inspection, measurement, visual intent, and agent-readable
 
 Mesurer Solid ships its own isolated Solid 2 renderer. Host applications can use Solid 1 or 2, React, Vue, Svelte, vanilla DOM, or an Electron renderer without providing Solid.
 
+**Current stable:** `mesurer-solid@0.2.1` on the `latest` dist-tag.
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/jhomra21/mesurer-solid/main/docs/assets/readme/hero-multi-spacing.png" alt="Mesurer Solid measuring spacing between selected elements" width="100%">
 </p>
@@ -16,13 +18,13 @@ Mesurer Solid ships its own isolated Solid 2 renderer. Host applications can use
 ## Installation
 
 ```bash
-bun add -d mesurer-solid
+bun add -d mesurer-solid@latest
 ```
 
 or:
 
 ```bash
-npm install -D mesurer-solid
+npm install -D mesurer-solid@latest
 ```
 
 
@@ -42,7 +44,7 @@ if (import.meta.env.DEV) {
 }
 ```
 
-For Vite, put this in the existing browser entry such as `src/main.tsx`, `src/main.ts`, or `src/index.tsx`. In Electron, use the renderer entry and keep privileged Electron work in preload/main. If preload exposes `window.__MESURER_HOST__.captureScreenshot`, Screenshot uses native capture and Color Picker samples the current application window through that same capability. If preload exposes `window.__MESURER_HOST__.codexBridge`, Codex starts enabled and waits for a native activation lease before it becomes available. Browser-only hosts list Codex in Settings but start with it off. Renderer configuration remains runtime-neutral. In SSR applications, mount from a client-only module or lifecycle.
+For Vite, put this in the existing browser entry such as `src/main.tsx`, `src/main.ts`, or `src/index.tsx`. In Electron, use the renderer entry and keep privileged Electron work in preload/main. If preload exposes `window.__MESURER_HOST__.captureScreenshot`, Screenshot uses native capture and Color Picker samples the current application window through that same capability. If preload exposes `window.__MESURER_HOST__.codexBridge`, Codex starts enabled and uses the native transport. Browser-only hosts still list Codex in Settings, start with it off, and connect through a verified local Mesurer Codex Bridge companion when enabled. Missing, outdated, and conflicting companions are explicit fail-closed states, and the browser reconnects automatically when a compatible helper appears. Renderer configuration remains runtime-neutral. In SSR applications, mount from a client-only module or lifecycle.
 
 `src/dev/mesurer.ts` is an optional organization pattern, not a required filename or directory. Do not mount Mesurer from `vite.config.ts`, server/API code, Node-only scripts, an Electron main process, or a module that also executes during SSR.
 
@@ -70,7 +72,7 @@ const mesurer = mountMesurer({
 })
 ```
 
-The base inspector includes Select, X-ray, Rulers, Typography, Guides, Distance, Settings, plugin hosting, direct text editing, and the low-level inspection API. First-party Recording uses MediaBunny for encoded video, trim, resize, and WebM/MP4 export; its capture adapters only acquire pixels. Electron apps should import `mesurer-solid/electron` once from the main-process entrypoint before creating BrowserWindows; Mesurer then owns its narrow Recording preload/IPC automatically, so the app does not add Recording code to its own preload. The toolbar groups those controls into Select and Edit. Typography stays read-only in Select; Edit owns movement and direct text/style changes. Color Picker uses application-local capture when `window.__MESURER_HOST__.captureScreenshot` is available; other supported browser hosts use an operational `EyeDropper`. A successful sample is copied to the clipboard using `colorPickerClickFormat`.
+The base inspector includes Select, X-ray, Color Picker, Rulers, Typography, Guides, Distance, Settings, plugin hosting, direct text editing, and the low-level inspection API. First-party Recording uses MediaBunny for encoded video, trim, resize, and WebM/MP4 export; its capture adapters only acquire pixels. Electron apps should import `mesurer-solid/electron` once from the main-process entrypoint before creating BrowserWindows; Mesurer then owns its narrow Recording preload/IPC automatically, so the app does not add Recording code to its own preload. The toolbar groups those controls into Select and Edit. Typography stays read-only in Select; Edit owns movement and direct text/style changes. Color Picker uses application-local capture when `window.__MESURER_HOST__.captureScreenshot` is available; other supported browser hosts use an operational `EyeDropper`. A successful sample is copied to the clipboard using `colorPickerClickFormat`.
 
 `mesurer-solid/plugins` also exports the built-in factories for lower-level composition. Normal mounts already include the built-ins. Use `excludeBuiltins` with names such as `"xray"`, `"typography"`, and `"colorPicker"` when a mount should omit one.
 
@@ -103,15 +105,15 @@ Programmatic injection reuses an existing connected instance by default. Lifecyc
 - Add page-scoped columns, rows, or pixel grids with the optional `layoutGuides()` plugin. Guide edits participate in plugin undo/redo, and Context includes the current page's saved guides with their visibility state.
 - Inspect rendered typography in Select. Edit previews reversible direct copy and style changes.
 - Use Edit to move selected UI and change direct text, typography, and text color without changing source.
-- Capture page regions through the optional Screenshot plugin. It selects native host capture, the Chromium extension adapter, or browser display capture internally.
-- Record selected regions through the optional Recording plugin. Browser and extension/native-host APIs only acquire the stream; MediaBunny owns encoding, inspection, trim, resize, and WebM/MP4 export.
+- Capture page regions through the optional Screenshot plugin. It selects native host capture, the Chromium extension adapter, or browser display capture internally, and flattens transparent native captures against the renderer backdrop before preview, copy, or save.
+- Record adjustable selected regions through the optional Recording plugin at 60 fps by default or 120 fps when selected and supported. Browser, extension, and Electron APIs only acquire the stream; MediaBunny owns encoding, inspection, trim, 1×/2×/3× resize, and WebM/MP4 export.
 - Read selection, measurements, guides, annotations, layout, styles, and saved human intent through Context and agent APIs.
 - Keep saved annotations across same-tab reloads and conservatively rebind them to their original DOM targets; markers, cards, and ownership evidence stay attached through scrolling, repeated-note markers stay local, Add Note remains available while a note is open, and cards/composers occlude Select hover and selection chrome.
 - Extend the runtime with tools, settings, overlays, commands, hooks, state, and services.
 - Compact the toolbar to active controls without changing tool state or order.
 - Choose System, Light, or Dark appearance while keeping the same theme across isolated and document-backed Mesurer UI.
 
-Use `1` for Select and `2` for Edit. Select contains inspection tools. Edit owns movement and direct text/style changes. Context and Codex remain visible in both modes. The grouped toolbar changes modes in 150 ms. `Shift+A` still enters Edit as a compatibility shortcut.
+Use `1` for Select and `2` for Edit. Select owns X-ray, Color Picker, Typography, Screenshot, and Recording. Edit owns movement and direct text/style changes. Rulers, Guides, and Layout Guides remain usable in both modes; Context and Codex remain visible in both modes. The grouped toolbar changes modes in 150 ms. `Shift+A` still enters Edit as a compatibility shortcut.
 
 Toolbar dragging starts after the pointer crosses the drag threshold. Dragging from Settings, Guide, or plugin triggers closes the open menu or panel. Pointer activity inside menus, dialogs, form controls, editable regions, and sliders does not drag the toolbar.
 
@@ -156,6 +158,7 @@ Global shortcuts are enabled by default. Turn them off from **Settings > General
 | `Cmd/Ctrl + ,` | Settings |
 | `Shift + A` | Edit compatibility shortcut |
 | `Shift + S` | Screenshot |
+| `Shift + R` | Recording |
 | `C` | Copy Context |
 | `Shift + C` | Copy Selection |
 | `N` | Add Note |
@@ -174,7 +177,7 @@ const selected = await mesurer.select("#pricing-card")
 Install the portable Agent Skill with:
 
 ```bash
-npx --yes --package=mesurer-solid mesurer-skill install
+npx --yes --package=mesurer-solid@latest mesurer-skill install
 ```
 
 The skill preserves existing human state, reads Edit movement, text, and annotation intent before source changes, and verifies the real Live result after implementation.
@@ -183,9 +186,9 @@ See [Agent integration](https://github.com/jhomra21/mesurer-solid/blob/main/pack
 
 ### Queue to Codex
 
-Codex starts enabled when the native host capability exists and remains toggleable under **Settings -> Plugins**. Browser-only hosts list it but start with it off.
+Codex is Mesurer's own local delivery integration and is separate from the Mesurer Solid ChatGPT/Codex agent plugin. Browser-only hosts list it in **Settings -> Plugins**, start with it off, and use the local Mesurer Codex Bridge companion when enabled. A missing helper leaves the plugin enabled with an unavailable/retry state instead of producing an Electron-preload error.
 
-Native applications install `installMesurerCodexHost()` in Electron main and expose `createMesurerCodexPreloadBridge()` from a bundled preload. The bridge runs in the native host process. Each enabled renderer owns a native lease. Settings waits for activation readiness before committing ON and waits for lease release before committing OFF. Shared sessions use Codex's local app-server directly. An inherited Codex Desktop thread uses one native queue operation and one `codex://threads/<id>` wake. Mesurer never opens the private Desktop app-tools pipe or starts a second Mesurer process.
+Native applications can install `installMesurerCodexHost()` in Electron main and expose `createMesurerCodexPreloadBridge()` from a bundled preload. That path uses an in-process native bridge and renderer-scoped lease instead of loopback HTTP. Both transports expose the same `codex:v1` service and **Queue to Codex** UI.
 
 **Queue to Codex** remains one runtime-neutral API. Shared delivery tracks Queued, Working, Finished, or Interrupted through the shared app-server. Desktop current-thread delivery keeps the durable queued submission and wake result visible without fabricating private Desktop lifecycle state. It does not create threads or invoke Steer.
 
@@ -201,12 +204,15 @@ See [Queue Context feedback to Codex](https://github.com/jhomra21/mesurer-solid/
 - [Edit](https://github.com/jhomra21/mesurer-solid/blob/main/docs/EDIT.md) and [Layout Guides](https://github.com/jhomra21/mesurer-solid/blob/main/docs/LAYOUT_GUIDES.md)
 - [Measurements and distance geometry](https://github.com/jhomra21/mesurer-solid/blob/main/docs/MEASUREMENTS.md)
 - [Screenshots](https://github.com/jhomra21/mesurer-solid/blob/main/docs/SCREENSHOTS.md)
+- [Recording](https://github.com/jhomra21/mesurer-solid/blob/main/docs/RECORDING.md)
 - [Electron renderer example](https://github.com/jhomra21/mesurer-solid/blob/main/examples/electron-renderer/README.md)
 - [Context workflow](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CONTEXT_WORKFLOW.md)
 - [Queue Context feedback to Codex](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CODEX.md)
 - [Browser and agent integration](https://github.com/jhomra21/mesurer-solid/blob/main/docs/BROWSER_HARNESS.md)
 - [Host isolation](https://github.com/jhomra21/mesurer-solid/blob/main/docs/HOST_ISOLATION.md)
 - [Trusted Types](https://github.com/jhomra21/mesurer-solid/blob/main/docs/TRUSTED_TYPES.md)
+- [Browser extension](https://github.com/jhomra21/mesurer-solid/blob/main/extension/README.md)
+- [Upstream parity](https://github.com/jhomra21/mesurer-solid/blob/main/docs/UPSTREAM_PARITY.md)
 
 Mesurer Solid is a source-first Solid port and extension of [Mesurer](https://github.com/ibelick/mesurer). Upstream adoption and deliberate differences are tracked in [Upstream parity](https://github.com/jhomra21/mesurer-solid/blob/main/docs/UPSTREAM_PARITY.md).