mesurer-solid 0.1.0-beta.12 → 0.1.0

package/AGENT_INTEGRATION.md

@@ -1,27 +1,38 @@
 # Mesurer agent integration
 
-Mesurer uses standards and a browser contract instead of harness-specific integrations.
+Mesurer's agent integration is deliberately direct: **the agent reads and manipulates Mesurer through the same rendered page it is already controlling**.
+
+There is no Mesurer MCP, WebMCP, ACP, localhost feedback daemon, Send-to-agent callback, chat/session bridge, or harness-specific Mesurer adapter.
+
+The central contract is stronger than “Mesurer is available”:
+
+> **A Mesurer visual operation should return structured context to the harness.** The agent should consume existing human context before editing and obtain fresh Mesurer context/review for the affected rendered UI before claiming completion.
 
 ```text
-Agent Skill            window.__MESURER__             ACP
-how/when to use it     visual context + validation    standardized delivery
-       \                       |                       /
-        \______________________|______________________/
-                               |
-                         any capable harness
+human selection / annotation OR agent-known changed target
+        ↓
+real page + window.__MESURER__
+        ↓
+context() / select() / review()
+        ↓ structured rendered evidence
+agent reasoning + source edit
+        ↓
+normal render/HMR
+        ↓
+fresh context() / select() / review()
+        ↓
+validated result
 ```
 
-There is no required OpenCode, Pi, Cursor, Codex, or other Mesurer adapter package.
+The page is the shared state boundary. Mesurer never needs to know which chat, thread, model, or agent is using it.
 
 ## Install the portable Agent Skill
 
-The npm package ships one canonical `mesurer-ui` Agent Skill:
-
 ```bash
 npx --yes --package=mesurer-solid@beta mesurer-skill install
 ```
 
-Use `--force` only when intentionally replacing an existing local copy. The install is self-contained: it writes the skill plus the exact packaged classic injector to:
+The installed skill is self-contained:
 
 ```text
 .agents/skills/mesurer-ui/
@@ -30,144 +41,337 @@ Use `--force` only when intentionally replacing an existing local copy. The inst
     └── inject-script.js
 ```
 
-The skill teaches agents to use Mesurer for frontend visual work, consume human annotations before editing, and revalidate the rendered result after HMR instead of treating typecheck/build success as visual completion.
+The skill defines the same context-first workflow described here.
+
+## Reuse a live human instance first
+
+Before injecting anything:
+
+```js
+const hasMesurer = Boolean(
+  window.__MESURER__ &&
+  window.__MESURER_INSTANCE__?.element?.isConnected
+)
+
+if (hasMesurer) {
+  await window.__MESURER__.ready()
+}
+```
+
+If Mesurer exists, use that exact instance. The person may already have selected elements, placed guides, measured gaps, held distances, enabled rulers/X-ray, or saved annotations. Read that state before changing it.
+
+The injector also reuses a live injected instance by default. Deliberate destructive replacement requires:
+
+```js
+window.__MESURER_CONFIG__ = { reuseExisting: false }
+```
 
-## Default browser integration: inject
+Do not use that while consuming human review state.
 
-**Default host-project mutation budget: zero.** If the existing browser, Electron, WebView, or automation harness can execute JavaScript in the target renderer, reuse that channel.
+## Inject only when absent
 
-When the Agent Skill is installed, read `.agents/skills/mesurer-ui/assets/inject-script.js` and evaluate those bytes in the page. No project dependency is required after the transient installer exits.
+Default host-project mutation budget is zero. Reuse the browser, Electron, WebView, Playwright, CDP, or other evaluation channel the harness already owns.
 
-When `mesurer-solid` is already installed as a project/tooling dependency, the equivalent package path is the `/inject-script` export:
+With the installed skill, evaluate `.agents/skills/mesurer-ui/assets/inject-script.js`. With the npm package installed, use `mesurer-solid/inject-script`.
 
 ```js
-import { readFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
+import { readFile } from "node:fs/promises"
+import { fileURLToPath } from "node:url"
 
 const source = await readFile(
   fileURLToPath(import.meta.resolve("mesurer-solid/inject-script")),
   "utf8",
-);
+)
 
-await browser.evaluate(source);
-await browser.evaluate(`window.__MESURER__.ready()`);
+const alreadyPresent = await browser.evaluate(() => Boolean(
+  window.__MESURER__ &&
+  window.__MESURER_INSTANCE__?.element?.isConnected
+))
+
+if (!alreadyPresent) {
+  await browser.evaluate(source)
+}
+
+await browser.evaluate(() => window.__MESURER__.ready())
 ```
 
-Both routes evaluate the same built injector artifact. The injection entry points install the removable `mesurer.context` plugin by default. A harness that deliberately wants only the low-level inspector can set:
+Do not create a second browser/CDP connection, Mesurer server, special app build, or source mutation merely to inspect a page the harness already controls.
+
+## Capability contract
+
+After `ready()`:
 
 ```js
-window.__MESURER_CONFIG__ = { context: false };
+window.__MESURER__.capabilities()
+```
+
+The context-oriented capability surface is:
+
+```text
+context
+select
+annotations
+review
+capturePlan
+```
+
+`select` is an agent/harness operation; it does not add a human context-toolbar button. Human context controls remain:
+
+```text
+Copy Context
+Copy Selection
+Add Note
 ```
 
-Do not create another Chromium instance, another CDP connection, a Mesurer-specific server, a special application build, or source changes merely to inspect an app that the harness can already evaluate.
+There is no `send`, `screenshots`, or `sendContext` delivery capability.
+
+## Context acquisition precedence
 
-## Discover the browser contract
+Harnesses should follow this order.
 
-Wait for plugin setup before reading dynamic capabilities:
+### 1. Existing human evidence exists → read it first
 
 ```js
-if (window.__MESURER__) {
-  await window.__MESURER__.ready()
-  window.__MESURER__.capabilities()
-}
+const workspace = await window.__MESURER__.context()
+const annotations = await window.__MESURER__.annotations()
+
+let selection = null
+try {
+  selection = await window.__MESURER__.context({ scope: "selection" })
+} catch {}
+```
+
+For relevant annotations:
+
+```js
+const context = await window.__MESURER__.context({
+  annotation: annotation.id,
+})
+```
+
+Do not overwrite a meaningful live human selection until its context has been consumed and retained by the current agent task.
+
+### 2. No relevant selection and intended target is ambiguous → ask the user
+
+When the user's visual reference cannot be mapped confidently to exact rendered elements or a region, ask the person to select the intended element(s) or drag the intended region in Mesurer.
+
+Then read:
+
+```js
+const context = await window.__MESURER__.context({ scope: "selection" })
+```
+
+Do not guess merely to avoid asking for a selection.
+
+### 3. No relevant selection and agent knows exact target(s) → use `select()`
+
+If the harness knows exactly which rendered elements correspond to the change, it should select them itself:
+
+```js
+const context = await window.__MESURER__.select("#pricing-card")
+```
+
+or:
+
+```js
+const context = await window.__MESURER__.select([
+  "#pricing-card",
+  "#pricing-cta",
+])
+```
+
+`select()` is deliberately context-returning. In one operation it:
+
+1. switches Mesurer to Select;
+2. visibly highlights the exact rendered targets;
+3. makes them the live selection;
+4. waits for the selection to settle;
+5. returns selection-scoped `MesurerContextV1`.
+
+The return value is the point. A harness should not call `select()` only for visual highlighting and then ignore the context.
+
+Every supplied selector must resolve to exactly one target inside Mesurer's page target. Invalid, missing, or ambiguous selectors throw. Refine the selector or ask the user to select the intended target rather than guessing.
+
+This makes a useful post-edit pattern trivial:
+
+```js
+await window.__MESURER__.stable()
+
+const evidence = await window.__MESURER__.select([
+  changedSelectorA,
+  changedSelectorB,
+])
+
+// `evidence` is the exact rendered result the agent should reason from.
+```
+
+## What context contains
+
+`MesurerContextV1` is JSON-safe and uses `viewport-css-px` coordinates:
+
+```text
+schema / id / createdAt
+scope
+page
+viewport / DPR / scroll
+coordinateSpace
+regions
+visualState
+  rulersVisible
+  xrayVisible
+targets[]
+  ref
+  inspection.selector
+  inspection.rect
+  margin / padding / border
+  typography
+  appearance
+  layout
+  scroll / overflow
+visualContext
+  guides[]
+  measurements[]
+  distances[]
+```
+
+Prefer these rendered numbers over screenshot estimates or source-level assumptions.
+
+## Multi-selection is relational
+
+When several targets are selected, consume every target's complete inspection and the relevant relationships between them.
+
+Use existing `visualContext.distances` first. For a needed pair not represented there:
+
+```js
+const pair = window.__MESURER__.distance(selectorA, selectorB)
+```
+
+A small selection can produce evidence such as:
+
+```text
+Card A width: 320px
+Card B width: 320px
+A → B horizontal gap: 24px
+A/B top-edge delta: 0px
+```
+
+For large repeated sets, focus on adjacent/repeated/user-relevant relationships instead of dumping all O(n²) pairs.
+
+## Context is required before and after meaningful visual edits
+
+### Before editing
+
+If the user supplied visual evidence, retain it before HMR can replace nodes:
+
+```js
+const before = await window.__MESURER__.context({ scope: "selection" })
+```
+
+or:
+
+```js
+const before = await window.__MESURER__.context({ annotation: annotationId })
+```
+
+### After editing
+
+First wait for the actual rendered page:
+
+```js
+await window.__MESURER__.stable()
 ```
 
-`capabilities().capabilities.context` reflects whether the `context:v1` plugin service is currently present. Removing `mesurer.context` switches the context/review/capture capabilities off dynamically while the original inspection API keeps working.
+Then obtain fresh evidence using the strongest path.
 
-### Human-in-the-loop context
+Human annotation:
 
-With the plugin loaded:
+```js
+const review = await window.__MESURER__.review(annotationId)
+```
+
+Still-relevant human selection:
 
 ```js
-await window.__MESURER__.annotations()
-await window.__MESURER__.context({ annotation: annotationId })
-await window.__MESURER__.context({ scope: "selection" })
-await window.__MESURER__.context()
-await window.__MESURER__.contextText({ annotation: annotationId })
+const after = await window.__MESURER__.context({ scope: "selection" })
 ```
 
-`context()` combines the human's selected elements or dragged region and note with exact DOM inspection and relevant guides, measurements, and held distances. Scoped contexts expose their requested viewport rectangles in `regions`, so a region-only note remains useful even when no DOM element sits inside it. Transient hover/drag state is excluded.
+Agent knows exact changed rendered targets:
+
+```js
+const after = await window.__MESURER__.select([
+  changedSelectorA,
+  changedSelectorB,
+])
+```
 
-### Revalidate after edits
+Target identity is ambiguous after the change: ask the user to select the intended result and then read selection context.
+
+For meaningful visual work, lint/typecheck/tests/build are not enough. If Mesurer is available and the changed UI can be identified, a harness should not report completion without fresh Mesurer evidence for that UI.
+
+## Annotation review
 
 ```js
 await window.__MESURER__.stable()
 const review = await window.__MESURER__.review(annotationId)
 ```
 
-Annotations retain exact live DOM identity while the original node remains connected. After DOM replacement/HMR, rebinding is deliberately conservative: strong IDs are preferred, and weaker fingerprints must resolve uniquely. Ambiguous or incompatible replacements are reported stale instead of silently attaching the note to another element.
+`review()` compares the human baseline against fresh context and reports exact pixel changes/missing evidence:
+
+```text
+gap: 37px → 24px
+left-edge mismatch: 4px → 0px
+width: 318px → 320px
+expected target/guide/measurement missing
+```
 
-`review()` matches targets by stable annotation target IDs rather than regenerated selectors. Relevant baseline evidence that genuinely disappears is reported with `kind: "missing"` instead of being silently omitted.
+If the requested result remains numerically wrong, continue editing.
 
-### Clean screenshots
+## Screenshots complement context
 
-The outer harness owns real browser screenshots. The context plugin defines the evidence frame:
+Mesurer supplies capture scope; the outer harness supplies real pixels:
 
 ```js
-const plan = await window.__MESURER__.capturePlan({ annotation: annotationId })
+const plan = await window.__MESURER__.capturePlan({ scope: "selection" })
+
 await window.__MESURER__.prepareCapture()
 try {
-  // harness screenshot: current viewport
-  // close-up when present: plan.captures.find(c => c.id === "focus")
+  // use the harness's real screenshot primitive
 } finally {
   await window.__MESURER__.finishCapture()
 }
 ```
 
-Capture planning includes the scoped `regions`, so an arbitrary whitespace/alignment annotation can still produce a focused close-up. Capture mode hides toolbars, settings, comment editors, and action panels while preserving rulers, guides, selection/annotation markers, measurements, distance overlays, and pixel labels.
+Use the signals together:
 
-Use screenshots together with structured context. Screenshots are strong visual evidence; Mesurer geometry is stronger evidence for exact spacing/alignment claims.
+```text
+Mesurer context → exact geometry, box model, styles, distances, overflow
+real screenshot → composition, hierarchy, clipping, color, visual judgment
+```
 
-## Source-mounted integrations
+## Source-mounted usage
 
-When Mesurer is mounted from application code, explicitly install the same plugin:
+When Mesurer is intentionally mounted from application code:
 
 ```ts
-import {
-  contextPlugin,
-  mountMeasurer,
-} from "mesurer-solid";
+import { contextPlugin, mountMeasurer } from "mesurer-solid"
 
 const mesurer = mountMeasurer({
   agent: true,
   plugins: [contextPlugin()],
-});
-```
-
-Browser/harness delivery capabilities are plugin options:
-
-```ts
-contextPlugin({
-  evidenceProvider: async ({ context, plan }) => [],
-  sendContext: async ({ context, text, images }) => {
-    // Send using the ACP session already owned by the host.
-  },
 })
 ```
 
-Remove the complete extension through the normal plugin host:
-
-```ts
-mesurer.pluginHost?.remove("mesurer.context");
-```
-
-The context UI, annotation runtime, shortcuts, service, and listeners are disposed together.
+The same API is available on `mesurer.agent` and, when configured, `window.__MESURER__`:
 
-## ACP delivery
-
-Mesurer does not own an ACP process or session. The ACP client/harness that already owns the session sends Mesurer output.
-
-```ts
-import { toAcpContentBlocks } from "mesurer-solid";
-
-const blocks = toAcpContentBlocks(context, images);
+```js
+const context = await mesurer.agent.select("#target")
 ```
 
-The result is one context text block plus optional labeled image blocks. The calling ACP client is responsible for session selection, capability negotiation, and `session/prompt`.
+No transport callback is involved.
 
-## Existing low-level API
+## Low-level inspection
 
-These JSON-safe primitives remain available whether or not `mesurer.context` is loaded:
+These remain useful for focused queries:
 
 ```js
 window.__MESURER__.inspect(".selector")
@@ -180,10 +384,23 @@ await window.__MESURER__.state()
 await window.__MESURER__.stable()
 ```
 
-When an agent is mounted with a scoped root, `inspect`, `inspectAll`, `distance`, and `at` all respect that root. A document-level hit test is never returned by `at()` unless the hit element belongs to the configured root.
+Prefer `context()`, `select()`, and `review()` for visual development because they provide context that directly carries human intent or agent-selected affected UI into reasoning.
+
+## Harness completion rule
 
-Prefer scoped `context()` and `review()` for normal human-in-the-loop visual development when the context plugin is available; use the low-level primitives for narrower measurement questions.
+A good harness-level visual completion loop is:
 
-## Ownership boundary
+```text
+1. discover/reuse Mesurer
+2. consume existing human context
+3. if target ambiguous, ask user to select
+4. otherwise select known affected rendered target(s) when needed
+5. consume returned context
+6. edit normal source
+7. wait for stable render
+8. get fresh review/context; use select() for known changed targets
+9. optionally capture real screenshot
+10. iterate until rendered evidence supports the claim
+```
 
-The base Mesurer runtime owns measurement, inspection, plugin composition, and the low-level browser API. `mesurer.context` owns annotations, context formatting/capture/review behavior, and its UI. The outer harness owns navigation, clicks, typing, screenshots, tabs/windows, authentication, browser lifetime, source editing, dev servers, and ACP session/process ownership.
+**Context is the output of the Mesurer step, not an optional side effect.**