mesurer-solid 0.1.2 → 0.1.3-beta.0

package/dist/screenshot.js

@@ -2840,7 +2840,30 @@ var Gn = "mesurer:capture-bridge-ping", Kn = "mesurer:capture-bridge-request", q
 			command: Er,
 			icon: Ar,
 			active: C,
-			hidden: () => !w().toolEnabled
+			hidden: () => !w().toolEnabled,
+			menu: {
+				label: "Screenshot options",
+				items: [
+					{
+						id: "copy",
+						label: "Auto-copy",
+						checked: () => w().copy,
+						run: () => T({ copy: !w().copy })
+					},
+					{
+						id: "download",
+						label: "Auto-download",
+						checked: () => w().download,
+						run: () => T({ download: !w().download })
+					},
+					{
+						id: "measurements",
+						label: "Include measurements",
+						checked: () => w().includeMeasurements,
+						run: () => T({ includeMeasurements: !w().includeMeasurements })
+					}
+				]
+			}
 		}), t.settings.register({
 			id: "screenshot",
 			label: "Screenshot",
@@ -2885,7 +2908,7 @@ var Gn = "mesurer:capture-bridge-ping", Kn = "mesurer:capture-bridge-request", q
 			S = !0, y += 1, u.removeEventListener("pointerdown", L), u.removeEventListener("pointermove", R), u.removeEventListener("pointerup", z), u.removeEventListener("pointercancel", B), i.removeEventListener("keydown", V, !0), v && i.clearTimeout(v), ee.dispose(), O(), cr(i), a.finishCapture(), a.dispose(), o.dispose();
 		});
 	}
-}), Rr = "0.1.2", zr = wr, Br = xr, Vr = Sr, Hr = Cr, Ur = 4, Wr = dr, Gr = (e, t) => Xn(e, t), Kr = (e = /* @__PURE__ */ new Date()) => Zn(e), qr = (e, t, n, r) => Yn(e, t, n, r), Jr = (e, t, n) => Jn(e, t, n), Yr = (e, t) => ur(e, t), Xr = (e) => cr(e), Zr = (e = {}) => ({
+}), Rr = "0.1.3-beta.0", zr = wr, Br = xr, Vr = Sr, Hr = Cr, Ur = 4, Wr = dr, Gr = (e, t) => Xn(e, t), Kr = (e = /* @__PURE__ */ new Date()) => Zn(e), qr = (e, t, n, r) => Yn(e, t, n, r), Jr = (e, t, n) => Jn(e, t, n), Yr = (e, t) => ur(e, t), Xr = (e) => cr(e), Zr = (e = {}) => ({
 	...Lr(e),
 	version: Rr
 }), Qr = (e) => $n(e);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mesurer-solid",
-  "version": "0.1.2",
+  "version": "0.1.3-beta.0",
   "description": "Framework-agnostic UI measurement and inspection tools for browser apps and coding agents.",
   "license": "MIT",
   "type": "module",
@@ -15,6 +15,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./arrange": {
+      "types": "./dist/arrange.d.ts",
+      "import": "./dist/arrange.js"
+    },
     "./core": {
       "types": "./dist/core.d.ts",
       "import": "./dist/core.js"

package/skills/mesurer-ui/SKILL.md

@@ -1,35 +1,36 @@
 ---
 name: mesurer-ui
-description: Use Mesurer when implementing, reviewing, debugging, or fixing frontend UI in a browser. Load for visual alignment, spacing, sizing, layout, CSS, responsive work, design/Figma implementation, screenshots, pixel discrepancies, or human Mesurer selections/measurements/guides/annotations. Treat Mesurer context as the output of every meaningful visual inspection: consume existing human context before editing, acquire a selection when needed, and obtain fresh context again before claiming completion.
+description: Use Mesurer when implementing, reviewing, debugging, or fixing frontend UI in a browser. Load for visual alignment, spacing, sizing, layout, CSS, responsive work, design/Figma implementation, screenshots, pixel discrepancies, human Mesurer selections/measurements/guides/annotations, or Arrange intents. Consume existing human visual intent before editing and obtain fresh rendered evidence before claiming completion.
 ---
 
 # Mesurer UI workflow
 
-Mesurer is **shared visual state between the person reviewing a page and the coding agent editing it**. The page is the integration boundary.
+Mesurer is shared visual state between the person reviewing a page and the coding agent editing it. The rendered page is the integration boundary.
 
 There is no Mesurer MCP, WebMCP, ACP, chat-delivery daemon, session router, or Send-to-agent callback in the normal workflow. Use the browser/evaluation channel the harness already owns and read `window.__MESURER__` directly.
 
-The critical behavioral contract is:
+The central rule is:
 
-> **When Mesurer is available, expect structured context back.** Do not merely open, highlight, or inspect with Mesurer and then continue from memory. A meaningful visual step should produce `MesurerContextV1`, `MesurerReviewV1`, or an equally focused Mesurer measurement that the agent actually consumes.
+> A meaningful Mesurer step must return evidence the agent actually consumes.
+
+That evidence may be `MesurerContextV1`, `MesurerReviewV1`, an Arrange intent/review, or a focused low-level measurement. Do not merely draw a highlight and continue from memory.
 
 ```text
 human visual intent or agent UI change
-  → identify affected rendered targets
-  → Mesurer selection / annotation / workspace
-  → structured context comes back to the agent
-  → agent reasons from exact rendered evidence
-  → source edit
-  → render settles
-  → fresh Mesurer context/review comes back
-  → agent iterates until evidence supports completion
+  → preserve existing Mesurer state
+  → consume Arrange / annotation / selection evidence
+  → reason from exact rendered state
+  → edit normal source
+  → wait for the real render
+  → compare fresh rendered state with the human intent
+  → iterate until the evidence supports completion
 ```
 
-## 1. Preserve existing human state
+## 1. Reuse the live Mesurer instance
 
-Never reinject, dispose, or replace Mesurer just because this skill loaded. The person may already have selected elements, placed guides, measured gaps, held distances, enabled rulers/X-ray, created annotations, or kept a screenshot thumbnail/viewer open. That state is part of the user's message.
+Never reinject, dispose, or replace Mesurer just because this skill loaded. The person may already have selected elements, placed guides, measured gaps, held distances, enabled rulers/X-ray, created annotations, arranged elements into a desired layout, or kept a screenshot thumbnail/viewer open. That state is part of the user's message.
 
-Start by discovering the current page:
+Discover the current page first:
 
 ```js
 const hasMesurer = Boolean(
@@ -44,28 +45,28 @@ if (hasMesurer) {
 
 If Mesurer exists, use that exact instance. Do not evaluate the injector again and do not call `dispose()`.
 
-If Mesurer is absent, inject the packaged classic payload through the browser JavaScript-evaluation primitive the harness already owns. The installed skill contains `assets/inject-script.js`; in this repository the development artifact is `packages/mesurer/dist/inject-script.js`; an installed npm package exposes `mesurer-solid/inject-script`.
+If Mesurer is absent, inject the packaged classic payload through the JavaScript-evaluation primitive the harness already owns. The installed skill contains `assets/inject-script.js`; this repository builds `packages/mesurer/dist/inject-script.js`; the npm package exposes `mesurer-solid/inject-script`.
 
 Do not add Mesurer to application source, create another browser, create a second CDP connection, start a Mesurer server, or change the application build merely to inspect a page the harness already controls.
 
-The injector defaults to reusing a live injected instance. `window.__MESURER_CONFIG__ = { reuseExisting: false }` is an explicit destructive replacement option for tests/tooling. Do not use it while consuming human review state.
+The injector reuses a live injected instance by default. `window.__MESURER_CONFIG__ = { reuseExisting: false }` is an explicit destructive replacement option for tests/tooling. Do not use it while consuming human review state.
 
-Normal injection keeps the optional human screenshot plugin disabled. If the task explicitly needs that camera tool, configure it before the first injection:
+Normal injection keeps the optional human screenshot plugin disabled. If the task specifically needs that camera tool, configure it before first injection:
 
 ```js
 window.__MESURER_CONFIG__ = { screenshot: true }
 ```
 
-The first-party Chrome extension enables screenshot capture automatically. Do not replace/reinject a live instance merely to enable screenshots unless the user specifically asks for that change; preserve current review state first.
+Do not replace/reinject a live instance merely to enable screenshots. Preserve current human state first.
 
-After a first injection:
+After first injection or discovery:
 
 ```js
 await window.__MESURER__.ready()
 const capabilities = window.__MESURER__.capabilities()
 ```
 
-The context surface includes:
+The context-oriented surface includes:
 
 ```text
 context
@@ -75,15 +76,120 @@ review
 capturePlan
 ```
 
-`select` is an agent/harness primitive, not a human toolbar action. The visible context controls remain Copy Context, Copy Selection, and Add Note. The optional screenshot plugin is a separate camera tool/service; it does not create a screenshot-delivery capability on `window.__MESURER__`.
+When the first-party Arrange plugin is mounted, capabilities also reports:
+
+```text
+arrange
+```
+
+Arrange adds:
+
+```text
+arrangements
+arrange
+showArrange
+arrangeCapturePlan
+reviewArrange
+```
+
+The optional screenshot plugin remains a separate human tool/service. It is not a screenshot-delivery capability on `window.__MESURER__`.
+
+## 2. Consume Arrange before source edits
+
+Arrange represents explicit human layout intent. If `capabilities.capabilities.arrange` is true, inspect it before replacing the human selection or editing source:
+
+```js
+const arrangements = await window.__MESURER__.arrangements()
+```
+
+For a relevant intent:
+
+```js
+const intent = await window.__MESURER__.arrange(arrangeId)
+```
+
+An Arrange intent contains exact targets plus Before and Desired geometry. Treat Desired as the requested visual outcome, not as an implementation prescription.
+
+For example, a target moving `96px` right does **not** mean production code should receive `transform: translateX(96px)`. Inspect the surrounding layout and implement the appropriate source-level change: flex/grid alignment, gap, margin, sizing, placement, component structure, or another semantic layout rule.
+
+### Capture Before and Desired before HMR
+
+Arrange can reconstruct both states while the original source-rendered page is still present. If the harness can capture screenshots, capture both before editing source.
+
+```js
+await window.__MESURER__.showArrange(arrangeId, "before")
+const beforePlan = await window.__MESURER__.arrangeCapturePlan(arrangeId, "before")
+
+await window.__MESURER__.prepareCapture()
+try {
+  // Use the current browser harness screenshot primitive with beforePlan.
+} finally {
+  await window.__MESURER__.finishCapture()
+}
+
+await window.__MESURER__.showArrange(arrangeId, "desired")
+const desiredPlan = await window.__MESURER__.arrangeCapturePlan(arrangeId, "desired")
+
+await window.__MESURER__.prepareCapture()
+try {
+  // Capture the Desired state with the same harness.
+} finally {
+  await window.__MESURER__.finishCapture()
+}
+```
+
+The user should not need to export or attach these images. The coding harness already owns screenshot bytes; Mesurer owns the reproducible visual states and capture geometry.
+
+Retain:
+
+- the Arrange id;
+- target selectors/fingerprints;
+- Before geometry;
+- Desired geometry and offsets;
+- the Before screenshot when available;
+- the Desired screenshot when available.
+
+Do this **before** source changes or HMR can alter the baseline.
+
+### Verify the real implementation against Desired
+
+After source changes and a stable render, switch Arrange to Live. Live removes Arrange's temporary visual preview so the page shows only what the application source actually produces.
+
+```js
+await window.__MESURER__.stable()
+await window.__MESURER__.showArrange(arrangeId, "live")
+const review = await window.__MESURER__.reviewArrange(arrangeId)
+```
+
+`reviewArrange()` reports exact current-vs-Desired rectangle deltas and whether the targets match within tolerance. If it says the result is still off, continue editing.
+
+A typical loop is:
+
+```text
+Before       Desired      Live
+x 120   →    x 284        x 276
+                         remaining +8px
+
+edit source
+  ↓
+wait for stable render
+  ↓
+Live x 284
+  ↓
+matched ✓
+```
+
+If review reports `stale` or `partial`, do not silently transfer the intent to a different element. Resolve target identity conservatively or ask the user to reselect/rearrange if ambiguity remains.
 
-## 2. Context acquisition is mandatory for visual work
+Do not clear, overwrite, or discard a human Arrange intent merely to make validation pass.
 
-Use this precedence order whenever Mesurer is available.
+## 3. Acquire ordinary context in the right order
 
-### A. Existing human selection or annotation → consume it first
+After preserving any relevant Arrange intent, use this order for the rest of the visual evidence.
 
-Always preserve and read existing human evidence before changing selection yourself.
+### A. Existing human selection or annotation
+
+Read it before changing selection yourself:
 
 ```js
 const workspace = await window.__MESURER__.context()
@@ -97,7 +203,7 @@ try {
 }
 ```
 
-For each relevant annotation:
+For a relevant annotation:
 
 ```js
 const annotationContext = await window.__MESURER__.context({
@@ -105,31 +211,29 @@ const annotationContext = await window.__MESURER__.context({
 })
 ```
 
-Treat annotation notes as human intent. Treat selection, guides, distances, measurements, geometry, computed styles, and screenshots as evidence supporting that intent.
-
-Do not overwrite a meaningful human selection until you have read and retained its context in the current task.
+Treat annotation notes and Arrange Desired state as human intent. Treat selection, guides, distances, measurements, exact geometry, computed styles, and screenshots as evidence supporting that intent.
 
-### B. No relevant selection + target is ambiguous → ask the user to select it
+Do not overwrite a meaningful human selection until its context has been retained in the current task.
 
-If the user's request refers to something visually ambiguous and you cannot confidently identify the intended rendered element or region, do not guess.
+### B. No relevant selection and the target is ambiguous
 
-Ask the user to select the intended element(s) or drag the intended region with Mesurer. Once they do, immediately read:
+Ask the user to select the intended element(s) or region with Mesurer. Then immediately read:
 
 ```js
 const selection = await window.__MESURER__.context({ scope: "selection" })
 ```
 
-A selection is the answer to “what exactly do you mean?” Do not require the user to create an annotation unless a durable note/baseline would actually help.
+Do not guess merely to avoid asking for a selection.
 
-### C. No relevant selection + agent knows the exact rendered targets → select them yourself
+### C. The agent knows the exact rendered target
 
-When you know exactly which rendered elements correspond to the UI you are changing or just changed, use `select()` instead of asking the user to do unnecessary work.
+Select it yourself:
 
 ```js
 const context = await window.__MESURER__.select("#pricing-card")
 ```
 
-For several exact targets:
+For multiple targets:
 
 ```js
 const context = await window.__MESURER__.select([
@@ -138,19 +242,13 @@ const context = await window.__MESURER__.select([
 ])
 ```
 
-`select()` does three things as one visual operation:
-
-1. switches Mesurer to Select and visibly highlights the exact rendered targets;
-2. makes those elements the live Mesurer selection;
-3. **returns selection-scoped `MesurerContextV1` after the selection settles**.
+`select()` switches Mesurer to Select, visibly highlights the exact targets, makes them the live selection, waits for the selection to settle, and returns selection-scoped `MesurerContextV1`.
 
-Use the returned object. Do not call `select()` only for the highlight and ignore its context.
+Use the returned object. Do not call `select()` only for the highlight.
 
-`select()` is intentionally strict. Every selector must resolve to exactly one page target. Missing, invalid, or ambiguous selectors throw. Refine the selector or ask the user to select the intended target rather than guessing.
+Every supplied selector must resolve to exactly one page target. Missing, invalid, or ambiguous selectors throw. Refine the selector or ask the user to select the target rather than guessing.
 
-Prefer exact selectors already obtained from `context()`, `inspect()`, stable IDs/test IDs, or a uniquely identified rendered node. Do not use a broad selector such as `.card` when it matches many elements unless you intentionally refine each target.
-
-## 3. Understand the context you receive
+## 4. Read rendered context, not source assumptions
 
 `MesurerContextV1` is JSON-safe and uses `viewport-css-px` coordinates. Relevant fields include:
 
@@ -179,20 +277,20 @@ visualContext
   distances[]
 ```
 
-Mesurer's rendered values are the source of truth. Prefer them over estimating from screenshots or assuming CSS declarations equal browser output.
+Mesurer's rendered values are the source of truth. Prefer them over screenshot estimates or source-level assumptions.
 
 Examples:
 
 - left edges differ by `4px` → the targets are not aligned;
-- rendered horizontal gap is `37px` → do not claim `24px` merely because CSS contains `gap: 24px`;
-- width is `318px` → do not report `320px` from design intent until the browser actually measures it;
-- overflow flags are true → the rendered document/component is overflowing even if source math looked correct.
+- rendered gap is `37px` → do not claim `24px` because CSS contains `gap: 24px`;
+- rendered width is `318px` → do not report `320px` until the browser measures it;
+- overflow flags are true → the rendered component is overflowing even if source math looked correct.
 
-## 4. Multi-selection is relational context
+## 5. Treat multi-selection as relational evidence
 
-When several elements are selected, do not summarize them as “3 selected” or inspect only the first target. Their relationship is usually the point.
+When several elements are selected, inspect every relevant target and their relationships. Do not summarize the state as only “3 selected.”
 
-For every selected target, consume:
+For each target, consume:
 
 ```text
 selector / identity / text / accessibility
@@ -204,52 +302,39 @@ layout: display / position / flex / grid / gap / transform / overflow
 scroll/client dimensions and overflow flags
 ```
 
-Then recover the useful relationships between targets. Start with `selection.visualContext.distances`; for a pair not represented there, use the exact selectors returned by context:
+Start with `selection.visualContext.distances`; for a needed pair not represented there:
 
 ```js
 const pair = window.__MESURER__.distance(selectorA, selectorB)
 ```
 
-For a small selection, report all useful unique pair relationships. For a large repeated set, focus on adjacent/repeated/user-relevant relationships rather than generating useless O(n²) output.
+For a small selection, report useful unique pair relationships. For a large repeated set, focus on adjacent/repeated/user-relevant relationships rather than dumping O(n²) pairs.
 
-A valid read can look like:
+## 6. Preserve the baseline before editing
 
-```text
-Card A: 320 × 180
-Card B: 320 × 180
-Card C: 320 × 180
-A → B horizontal gap: 24px
-B → C horizontal gap: 24px
-A/B top-edge delta: 0px
-```
+If the human supplied selection, measurements, an annotation, or Arrange state, retain the relevant baseline before source changes or HMR can replace nodes.
 
-Only claim numbers you actually read.
-
-## 5. Before editing, retain the baseline you need
-
-If the human supplied a selection, workspace measurement, or annotation, capture its relevant context before source changes or HMR can replace nodes.
-
-For a durable human annotation:
+Annotation:
 
 ```js
 const before = await window.__MESURER__.context({ annotation: annotationId })
 ```
 
-For live selection:
+Live selection:
 
 ```js
 const before = await window.__MESURER__.context({ scope: "selection" })
 ```
 
-Store the needed selectors, dimensions, relationships, and intent inside the current agent task.
+Arrange: capture the intent plus Before/Desired states as described above.
 
-Do not mutate human guides, measurements, held distances, annotations, or screenshot preview/viewer state merely to make your implementation appear correct.
+Do not mutate human guides, measurements, held distances, annotations, Arrange history, or screenshot preview/viewer state merely to make the implementation appear correct.
 
-## 6. Edit the real implementation
+## 7. Edit the real implementation
 
-Make the smallest source change that addresses the rendered issue. Use the project's normal edit/build/dev-server workflow.
+Make the smallest source change that addresses the rendered issue. Use the project's normal source, build, and dev-server workflow.
 
-Mesurer does not own source edits, browser navigation, or the dev server. Do not create Mesurer-specific infrastructure.
+Mesurer does not own source edits, navigation, or the dev server. Do not create Mesurer-specific infrastructure for those jobs.
 
 After HMR/render:
 
@@ -257,33 +342,37 @@ After HMR/render:
 await window.__MESURER__.stable()
 ```
 
-## 7. Fresh context is part of completion
+## 8. Fresh rendered evidence is part of completion
 
-For meaningful visual work, do not stop at lint/typecheck/tests/build. Before finalizing, obtain **fresh Mesurer evidence for the affected rendered UI**.
+Lint, typecheck, tests, and build are implementation checks. They do not prove a visual result.
 
-Use the strongest available path.
+Use the strongest applicable completion path.
 
-### Human annotation exists
+### Arrange intent
 
 ```js
 await window.__MESURER__.stable()
-const review = await window.__MESURER__.review(annotationId)
+await window.__MESURER__.showArrange(arrangeId, "live")
+const review = await window.__MESURER__.reviewArrange(arrangeId)
 ```
 
-`review()` returns baseline, current context, target status, exact before/current/delta metrics, and missing evidence.
+Continue until the live source-rendered geometry matches Desired within the expected tolerance, and use a fresh screenshot when visual composition matters.
 
-### Human selection still represents the changed UI
+### Human annotation
 
 ```js
 await window.__MESURER__.stable()
-const after = await window.__MESURER__.context({ scope: "selection" })
+const review = await window.__MESURER__.review(annotationId)
 ```
 
-Re-check the same dimensions and relationships you recorded before editing.
+### Still-relevant human selection
 
-### Agent made the UI change and knows the affected rendered targets
+```js
+await window.__MESURER__.stable()
+const after = await window.__MESURER__.context({ scope: "selection" })
+```
 
-Proactively highlight them and get context back:
+### Agent-known changed targets
 
 ```js
 await window.__MESURER__.stable()
@@ -293,69 +382,48 @@ const after = await window.__MESURER__.select([
 ])
 ```
 
-This is the preferred completion path when there was no human selection. It leaves the changed UI visibly selected for the user and returns exact evidence to the agent in the same operation.
-
-### The affected target is now ambiguous
-
-Ask the user to select the intended result, then read the resulting selection context. Do not manufacture confidence from a guessed selector.
-
-A visual task is not complete merely because `select()` drew an outline. **Consume the returned context and reason from it.**
-
-## 8. Human screenshots and agent screenshot evidence are different paths
-
-Mesurer now has an optional first-party screenshot plugin for human capture, while coding-agent verification can continue to use the outer harness's screenshot primitive. Do not conflate the two.
-
-### Human screenshot plugin
+If target identity is ambiguous after the change, ask the user to select the intended result. Do not manufacture confidence from a guessed selector.
 
-When enabled, `mesurer.screenshot` adds a camera tool. The person drags a viewport region and Mesurer captures a real PNG with CSS-to-bitmap scaling so Retina/HiDPI crops remain accurate. It temporarily hides control chrome from the captured pixels and then restores the previous presentation.
+## 9. Human screenshots and agent screenshots are different paths
 
-The plugin supports persisted automatic copy/download preferences, best-effort clipboard/download outputs, a persistent draggable thumbnail with native image right-click behavior, click-to-open larger viewer with Copy/Save/Close controls, and short capture-status feedback.
+The optional `mesurer.screenshot` plugin gives the person a camera tool. It can copy/download a HiDPI-aware PNG and keep a draggable preview/viewer. Do not treat it as an agent-delivery transport or destroy a human preview unless the task explicitly requires it.
 
-Normal browser injection opts in before injection:
-
-```js
-window.__MESURER_CONFIG__ = { screenshot: true }
-```
-
-Source-mounted applications import `screenshotPlugin` from `mesurer-solid/screenshot`. Normal browsers use `getDisplayMedia()` and reuse a live capture stream; the first-party Chrome extension enables the plugin automatically and uses `chrome.tabs.captureVisibleTab()` through its isolated-world bridge, so its camera path does not open the screen-share chooser.
-
-The screenshot plugin is a human tool/service, not a chat or agent-delivery channel. Do not infer a `screenshots` capability on `window.__MESURER__`, and do not close or replace an existing human preview unless the task explicitly requires it.
-
-### Agent verification screenshots
-
-For ordinary coding-agent verification, use the current harness/browser's real screenshot primitive so the harness controls the exact viewport, timing, and artifact. Mesurer supplies geometry and clean capture scope/presentation:
+For normal coding-agent verification, the outer harness owns screenshot bytes. Mesurer supplies exact scope and clean presentation:
 
 ```js
 const plan = await window.__MESURER__.capturePlan({ scope: "selection" })
 await window.__MESURER__.prepareCapture()
 try {
-  // Use the current harness/browser's real screenshot primitive.
+  // Use the current harness/browser screenshot primitive.
 } finally {
   await window.__MESURER__.finishCapture()
 }
 ```
 
+Arrange follows the same ownership model through `arrangeCapturePlan()`. The important difference is that Arrange can deliberately present Before, Desired, or Live before the harness captures.
+
 Use both signals:
 
 ```text
-Mesurer context  → exact geometry, styles, distances, overflow
-real screenshot  → composition, hierarchy, clipping, color, visual judgment
+Mesurer context/review → exact geometry, styles, distances, overflow
+real screenshot          → composition, hierarchy, clipping, color, visual judgment
 ```
 
-Screenshots from either path do not replace exact Mesurer measurements; Mesurer numbers do not replace visual judgment. Only use the screenshot plugin itself as the automation target when the task is specifically to test or modify that feature.
+Screenshots do not replace exact Mesurer measurements, and Mesurer numbers do not replace visual judgment.
 
-## 9. HMR and stale-target rules
+## 10. HMR and stale-target rules
 
-Annotations keep the exact live node while it remains connected and rebind conservatively after DOM replacement. If an annotation reports `stale` or `partial`, do not silently transfer human intent to a different element.
+Annotations and Arrange intents rebind conservatively after DOM replacement. If review reports `stale` or `partial`, do not silently bind human intent to a different element.
 
-An unsaved selection can disappear when HMR replaces nodes. Preserve initial context before editing. After the render, use the original exact selectors when still valid, `select()` the known replacement targets when unambiguous, or ask the user to reselect when identity is uncertain.
+An unsaved selection can disappear when HMR replaces nodes. Preserve initial context before editing. After render, use original exact selectors when still valid, `select()` known replacement targets when unambiguous, or ask the user to reselect when identity is uncertain.
 
-## 10. Completion standard
+## 11. Completion standard
 
-A visual completion statement should be grounded in fresh rendered evidence, for example:
+A valid visual completion statement is grounded in fresh rendered evidence, for example:
 
 ```text
-- selected cards now measure 320px wide
+- Arrange Live now matches Desired within 1px
+- selected cards measure 320px wide
 - rendered horizontal gap is 24px
 - selected top edges differ by 0px
 - component horizontal overflow is false
@@ -372,13 +440,11 @@ tests passed
 build passed
 ```
 
-Those are implementation checks, not rendered proof.
-
-If Mesurer is available and you could identify the affected UI, finishing without fresh Mesurer context is a workflow failure.
+If Mesurer is available and the affected UI can be identified, finishing without fresh Mesurer evidence is a workflow failure.
 
-## 11. Low-level helpers
+## 12. Low-level helpers
 
-Use these for focused questions when scoped context/review is not enough:
+Use these only when scoped context/review is not enough:
 
 ```js
 await window.__MESURER__.ready()
@@ -392,24 +458,27 @@ await window.__MESURER__.state()
 await window.__MESURER__.stable()
 ```
 
-Prefer `context()`, `select()`, and `review()` for human-in-the-loop work because they preserve visual meaning and produce context that can be carried directly into the agent's reasoning.
+Prefer `arrangements()`, `context()`, `select()`, `reviewArrange()`, and `review()` for human-in-the-loop work because they preserve visual meaning and return evidence that can be carried directly into reasoning.
 
-## 12. Do not do these things
+## 13. Do not do these things
 
 - do not look for an MCP/WebMCP tool;
 - do not start a local feedback server;
 - do not discover chat/thread/session IDs;
 - do not route Mesurer through ACP or another delivery protocol;
 - do not recreate Send-to-agent;
-- do not treat the screenshot plugin as an agent-delivery transport;
+- do not treat screenshot capture as an agent-delivery transport;
 - do not create another browser/CDP connection when the harness already controls the page;
 - do not reinject over live human Mesurer state;
 - do not overwrite human selection before reading it;
+- do not clear or alter human Arrange history to make validation pass;
+- do not implement Arrange offsets as production transforms unless the source layout genuinely calls for that;
+- do not capture only Desired after source editing; preserve Before and Desired first when screenshot comparison matters;
 - do not close/destroy a human screenshot preview merely to clean up agent state;
 - do not use `select()` with a knowingly ambiguous selector;
 - do not ask the user to select something the agent can identify exactly itself;
-- do not guess when the intended target really is ambiguous—ask the user to select it;
-- do not ignore the context returned by `select()`;
+- do not guess when the intended target really is ambiguous;
+- do not ignore context returned by `select()`;
 - do not alter human measurements/guides to make validation pass;
 - do not infer exact geometry from screenshots when Mesurer reports the number;
 - do not claim visual completion from source/build output alone.
@@ -422,7 +491,8 @@ existing agent harness
 existing rendered page
   ↕
 window.__MESURER__
-  ↳ context() / select() / review()
+  ↳ arrangements() / context() / select()
+  ↳ reviewArrange() / review()
 ```
 
-**Context is the output.**
+**Rendered evidence is the output.**