mesurer-solid 0.1.8-beta.0 → 0.1.8-beta.2

package/AGENT_INTEGRATION.md

@@ -2,9 +2,9 @@
 
 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.
 
-The normal agent workflow requires no Mesurer MCP server, localhost daemon, Send-to-agent callback, or harness-specific transport. The optional `codex()` plugin is a separate human convenience path for explicitly sending Context feedback to Codex threads that a local Codex process or the user has registered with the loopback companion; it does not replace the browser-state contract described here.
+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 explicitly sending Context feedback to Codex threads that a local Codex process or the user has registered with the loopback companion; it does not replace the browser-state contract described here.
 
-## Install the Agent Skill
+## Install the agent skill
 
 ```bash
 npx --yes --package=mesurer-solid mesurer-skill install
@@ -18,9 +18,20 @@ The installer writes a self-contained skill and injection artifact:
 .agents/skills/mesurer-ui/
 ├── SKILL.md
 └── assets/
-    └── inject-script.js
+    ├── inject-script.js
+    ├── codex-connect.mjs
+    ├── codex-lifecycle.mjs
+    └── codex-bridge.mjs
 ```
 
+## Know the available capabilities
+
+The base inspector includes Select, X-ray, Rulers, Typography, Guides, Distance, and Settings. Native Color Picker appears only when the browser exposes a working `EyeDropper`.
+
+First-party plugins add Context, Arrange, Screenshot, and optional Codex delivery. 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.
+
 ## Reuse a live instance
 
 Before injecting anything, check whether Mesurer is already connected:
@@ -48,9 +59,9 @@ Do not replace a live instance while consuming human review state.
 
 ## Inject only when absent
 
-Use the browser, Electron, WebView, Playwright, CDP, or other evaluation channel the harness already owns. With the installed skill, evaluate `.agents/skills/mesurer-ui/assets/inject-script.js`. With the npm package installed, read `mesurer-solid/inject-script`.
+Use the browser, Electron, WebView, Playwright, CDP, or other evaluation channel the browser controller already provides. With the installed skill, evaluate `.agents/skills/mesurer-ui/assets/inject-script.js`. With the npm package installed, read `mesurer-solid/inject-script`.
 
-Do not mutate application source or create another browser connection merely to get Mesurer into a page the harness can already evaluate.
+Do not mutate application source or create another browser connection merely to get Mesurer into a page the browser controller can already evaluate.
 
 The optional human Screenshot plugin remains disabled during normal agent injection unless configured before first injection:
 
@@ -60,7 +71,7 @@ window.__MESURER_CONFIG__ = { screenshot: true }
 
 ## Inventory human intent
 
-For a broad request such as “check Mesurer,” collect all relevant state before editing source:
+For a broad request such as "check Mesurer," collect all relevant state before editing source:
 
 ```js
 const capabilities = window.__MESURER__.capabilities().capabilities
@@ -99,6 +110,31 @@ const textEditIntents = await Promise.all(
 
 Treat annotation notes, Arrange Desired geometry, and text/style Desired state as intent. Treat selection, measurements, distances, geometry, and computed styles as rendered evidence.
 
+## Agent API reference
+
+Use the high-level Context and saved-intent methods for normal UI work. The lower-level methods are useful when you need a direct element lookup, point lookup, plugin command, or one combined state snapshot.
+
+| Method | Use it for |
+| --- | --- |
+| `ready()` | Wait for Mesurer to finish loading. |
+| `describe()` | Read loaded plugins and their tools, settings, overlays, state, commands, hooks, and services. |
+| `inspect(selector, index?)` | Inspect one matching rendered element. |
+| `inspectAll(selector, limit?)` | Inspect several matches without changing selection. |
+| `at(x, y)` | Inspect the page element at viewport coordinates. |
+| `distance(a, b)` | Measure two selector targets. |
+| `viewport()` | Read viewport/document dimensions, scrolling, device pixel ratio, and overflow. |
+| `feedback(selectors?)` | Read viewport data, inspected elements, plugin description, and plugin state together. |
+| `command(id, args?)` | Execute a registered Mesurer command. |
+| `state()` | Read plugin state. |
+| `stable(frames?)` | Wait for fonts and rendering before measuring again. |
+| `textEdits()` / `textEdit(id)` | Read saved direct-text and typography intent. |
+
+Context adds `capabilities()`, `context()`, `contextText()`, `select()`, `annotations()`, `review()`, `capturePlan()`, `prepareCapture()`, and `finishCapture()`.
+
+Arrange adds `arrangements()`, `arrange()`, `showArrange()`, `arrangeCapturePlan()`, and `reviewArrange()`.
+
+Use `capabilities().capabilities` before calling optional Context, Arrange, or text-edit paths. The complete public list is in [Capabilities](../../docs/CAPABILITIES.md).
+
 ## Select exact targets
 
 Do not overwrite a meaningful human selection until its context has been retained. When there is no relevant human selection and the exact targets are known:
@@ -149,9 +185,9 @@ Native editing stays native. Mesurer does not intercept form controls or descend
 
 The editing UI exposes direct B/I/U, Font, Size, Weight, rendered-page colors, custom color, and a separate Text/H1/H2/H3 semantic preset popup. Missing heading levels are not invented.
 
-If Typography was already explicitly selected, the direct-edit session suppresses the older hover/pinned Typography surface so the field has one live card. The normal surface returns when editing ends.
+If Typography was already explicitly selected, the direct-edit session suppresses the older hover/pinned Typography UI so the field has one live card. The normal Typography UI returns when editing ends.
 
-Direct edit also owns the field's visible selection lane. The duplicate ordinary selected border is paint-suppressed, the selected dimensions pill remains available, and the Typography card stays source-relative without reacting to ordinary pointer movement. The selection-adjacent Add Note button is intentionally hidden during the active edit and returns afterward. Existing saved annotation state remains available throughout.
+Direct edit also owns the field's visible selection lane. The duplicate ordinary selected border is paint-suppressed, the selected dimensions pill remains available, and the Typography card stays source-relative without reacting to ordinary pointer movement. The selection-adjacent Add Note button is hidden only during the active edit and returns afterward. Existing saved annotation state remains available throughout.
 
 Read durable intent through:
 
@@ -176,6 +212,12 @@ A saved annotation carries target-bound intent and an immutable baseline:
 const context = await window.__MESURER__.context({ annotation: annotationId })
 ```
 
+Saved annotation UI is source-linked presentation, not the durable state itself. Saved annotations survive a same-tab reload and conservatively rebind through their stored selector/fingerprint identity; ambiguous targets remain unresolved rather than attaching to a different element. Add Note, its composer, saved markers and panels, and the ownership edge move with their target through window and nested scrolling. A saved panel keeps its target-relative page point and may leave the viewport with its source. Several notes on one target keep separate nearby markers, and Add Note remains available while an existing note is open.
+
+Do not infer that an annotation disappeared because its card or marker is currently offscreen. Read `annotations()` and annotation-scoped `context()` instead. When a note is highlighted, the temporary ownership emphasis uses one exact target boundary rather than a second fill, glow, or rounded frame.
+
+Context cards are Mesurer inspector UI. Live Select hover and selection evidence must paint underneath the composer and saved panels, including when the outer Mesurer host is in the browser top layer. Agents should treat the cards as interaction boundaries rather than attempting to select page content through them.
+
 After source changes:
 
 ```js
@@ -187,13 +229,13 @@ const review = await window.__MESURER__.review(annotationId)
 
 ## Screenshots
 
-For ordinary coding-agent evidence, the outer harness owns screenshot bytes while Mesurer prepares capture presentation:
+For ordinary coding-agent evidence, the browser controller owns screenshot bytes while Mesurer prepares capture presentation:
 
 ```js
 const plan = await window.__MESURER__.capturePlan({ annotation: annotationId })
 await window.__MESURER__.prepareCapture()
 try {
-  // harness screenshot
+  // browser-controller screenshot
 } finally {
   await window.__MESURER__.finishCapture()
 }
@@ -203,11 +245,19 @@ The optional human `screenshot()` plugin from `mesurer-solid/plugins` is a separ
 
 ## Optional human-to-Codex delivery
 
-A source-mounted page may opt into `codex()` from `mesurer-solid/plugins` alongside `context()`. This is not an agent integration requirement and does not add a generic send capability to `window.__MESURER__`.
+A page can mount `codex()` next to `context()` for explicit human-triggered delivery. This is optional and does not add a generic send method to `window.__MESURER__`.
+
+For local Codex projects, the trusted `SessionStart` connector starts or reuses the packaged loopback companion and registers the current session with its project directory. Browser code cannot register arbitrary sessions or start the local process.
+
+Delivery uses Codex's native durable queue. Mesurer queues once and keeps the queued-submission id. Desktop delivery opens the existing `codex://threads/<threadId>` destination and lets Codex's queue watcher run the item when the thread can accept it. CLI/TUI sessions use the same queued item and may resume a cold `notLoaded` thread through the shared daemon. Mesurer never calls `turn/steer`, never deletes and resends an existing queue item during recovery, and does not use the Desktop app-tools pipe as a second delivery path.
+
+The browser plugin connects lazily on the first Queue to Codex or thread-picker action. Page affinity and an explicit destination override persist per tab. If several registered threads are visible and the page has no saved destination, the user must choose one.
+
+The typed `codex:v1` service exposes `health()`, `listThreads()`, `useThread(thread)`, `delivery(deliveryId)`, and `send({ thread })`. Queue submission is single-flight. A matched completed turn may remove only the annotation ids sent with that delivery; interrupted, failed, ambiguous, or unreadable work keeps them.
 
-When the current Codex thread starts `mesurer-codex`, the companion reads Codex's `CODEX_THREAD_ID`, registers that thread, and makes it the default destination. That means a Codex session that starts or uses Mesurer can route later human Context feedback back to the same thread without copying an id by hand. A normal shell may still select the initial session explicitly with `mesurer-codex --thread <SESSION>`.
+Mesurer does not create new Codex threads. Create or open the thread in Codex and let `SessionStart` register it. Turn completion is transport lifecycle, not proof that the requested UI result is correct.
 
-A different or newly-created Codex thread can join an already-running bridge with `mesurer-codex --register-current`. Registration is accepted only from a local process without a browser Origin. The bridge keeps previously registered threads; the `codex:v1` service can inspect them with `health()`, switch the default with `useThread(thread)`, or send one message to another registered destination with `send({ thread })`. Mesurer does not create or resume Codex threads itself. See [Send Context feedback to Codex](../../docs/CODEX.md).
+See [Queue Context feedback to Codex](../../docs/CODEX.md) for setup, routing, recovery, privacy, and failure behavior.
 
 ## Revalidate after source edits
 
@@ -231,4 +281,4 @@ Do not clear human history merely to expose Live state, and do not reinject just
 
 A meaningful Mesurer call should affect the work. If exact geometry is available, use it instead of estimating pixels from a screenshot. If the user already encoded intent in Arrange, text editing, annotations, or selection, consume it before asking them to repeat it.
 
-The repository's packaged [`mesurer-ui` skill](./skills/mesurer-ui/SKILL.md) carries the operational version of this contract for coding agents. [Browser and agent integration](../../docs/BROWSER_HARNESS.md) documents the outer harness boundary.
+The repository's packaged [`mesurer-ui` skill](./skills/mesurer-ui/SKILL.md) carries the operational version of this contract for coding agents. [Browser and agent integration](../../docs/BROWSER_HARNESS.md) documents the browser-control boundary.

package/README.md

@@ -64,13 +64,14 @@ For explicit plugin composition, `mesurer-solid/plugins` also exports `select`,
 
 | Entry | Purpose |
 | --- | --- |
-| `mesurer-solid` | Mount API, public domain types, and agent surface |
+| `mesurer-solid` | Mount API, public domain types, and agent API |
 | `mesurer-solid/plugins` | All first-party plugin factories and plugin-specific contracts |
 | `mesurer-solid/core` | Lower-level framework-neutral public contracts |
 | `mesurer-solid/inject` | Programmatic browser injection |
 | `mesurer-solid/inject-script` | Built classic injection artifact |
 | `mesurer-skill` | Install the portable coding-agent skill |
 | `mesurer-codex` | Run the optional loopback Codex queue companion |
+| `mesurer-codex-connect` | Start or reuse the matching Codex companion and register the current Codex session |
 
 ## Features
 
@@ -81,6 +82,7 @@ For explicit plugin composition, `mesurer-solid/plugins` also exports `select`,
 - Arrange selected UI into a Desired position without changing source.
 - Capture visible-tab regions through the optional Screenshot plugin.
 - 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.
 
@@ -94,7 +96,7 @@ Mesurer previews text, styles, and Arrange transforms only while it still owns t
 
 ## Shortcuts
 
-Global shortcuts are enabled by default. Turn them off from **Settings → General → Shortcuts** or pass `shortcutsEnabled: false` to `mountMesurer()`. Toolbar controls, editor-local keys, and Escape/cancel behavior remain available.
+Global shortcuts are enabled by default. Turn them off from **Settings > General > Shortcuts** or pass `shortcutsEnabled: false` to `mountMesurer()`. Toolbar controls, editor-local keys, and Escape/cancel behavior remain available.
 
 | Shortcut | Action |
 | --- | --- |
@@ -118,7 +120,7 @@ Plugin shortcuts are active only when their plugin is mounted and enabled.
 
 ## Agent integration
 
-Enable `agent: true` to expose rendered state through the mounted API and `window.__MESURER__`.
+Enable `agent: true` to expose the full browser agent object through `mesurer.agent` and `window.__MESURER__`. The mounted instance also mirrors the high-level Context, Arrange, and text-intent methods.
 
 ```ts
 const workspace = await mesurer.context()
@@ -135,21 +137,9 @@ The skill preserves existing human state, reads Arrange/text/annotation intent b
 
 See [Agent integration](https://github.com/jhomra21/mesurer-solid/blob/main/packages/mesurer/AGENT_INTEGRATION.md).
 
-### Optional Send to Codex
+### Optional Queue to Codex
 
-When Codex starts the loopback companion itself, `mesurer-codex` reads `CODEX_THREAD_ID`, so Mesurer feedback naturally routes back to that same Codex CLI/App thread:
-
-```bash
-bunx mesurer-codex
-```
-
-A normal shell can still choose the initial thread explicitly:
-
-```bash
-bunx mesurer-codex --thread <SESSION>
-```
-
-Mount the optional transport next to Context:
+Mount `codex()` next to Context when a person should be able to queue the current review to Codex:
 
 ```ts
 import { mountMesurer } from "mesurer-solid"
@@ -160,27 +150,27 @@ mountMesurer({
 })
 ```
 
-A different or newly-created Codex thread can register itself with the running bridge and become the active target:
+The trusted Codex `SessionStart` integration normally starts or reuses the local companion and registers the current thread. It can also be run directly:
 
 ```bash
-bunx mesurer-codex --register-current
+bunx mesurer-codex-connect
 ```
 
-The bridge remembers registered threads. `codex:v1` exposes `health()`, `useThread(thread)`, and `send({ thread })` for switching or one-off routing among those registered destinations. Browser pages cannot register arbitrary Codex sessions themselves.
-
-This uses Codex's own queued-user-message command. It does not replace the normal browser-harness agent workflow, and it does not resume or take ownership of a target Codex thread.
+**Queue to Codex** writes one item to Codex's native durable queue and tracks that delivery through Queued, Working, Finished, or Interrupted. It does not create threads or invoke Steer. A Mesurer page keeps its selected destination across a same-tab reload.
 
-See [Send Context feedback to Codex](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CODEX.md).
+Saved annotations included in a delivery are removed only after the exact matched turn completes. Interrupted, failed, or uncertain deliveries keep them. Set `codex({ clearCompletedAnnotations: false })` to retain completed notes.
 
+See [Queue Context feedback to Codex](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CODEX.md) for thread discovery, Desktop and CLI/TUI behavior, lifecycle recovery, permissions, and the typed `codex:v1` service.
 ## Documentation
 
+- [Capabilities](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CAPABILITIES.md)
 - [Getting started](https://github.com/jhomra21/mesurer-solid/blob/main/docs/GETTING_STARTED.md)
 - [Direct text editing and Typography](https://github.com/jhomra21/mesurer-solid/blob/main/docs/TEXT_EDITING.md)
 - [Arrange](https://github.com/jhomra21/mesurer-solid/blob/main/docs/ARRANGE.md)
 - [Screenshots](https://github.com/jhomra21/mesurer-solid/blob/main/docs/SCREENSHOTS.md)
 - [Context workflow](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CONTEXT_WORKFLOW.md)
-- [Send Context feedback to Codex](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CODEX.md)
-- [Browser harness](https://github.com/jhomra21/mesurer-solid/blob/main/docs/BROWSER_HARNESS.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)