mesurer-solid 0.1.2 → 0.1.3-beta.0

package/README.md

@@ -1,8 +1,8 @@
 # mesurer-solid
 
-Framework-agnostic UI measurement, annotation, inspection, and agent-ready visual context for browser applications.
+Framework-agnostic UI measurement, visual inspection, layout intent, and agent-ready rendered context for browser applications.
 
-The renderer is implemented privately in Solid 2, but consumers can use Solid 1/2, React, Vue, Svelte, vanilla DOM, or Electron renderer pages without providing Solid.
+Mesurer's private renderer uses Solid 2. Consumer applications can use Solid 1/2, React, Vue, Svelte, vanilla DOM, or Electron renderer pages without providing Solid.
 
 ## Install
 
@@ -14,166 +14,182 @@ bun add -d mesurer-solid
 npm install -D mesurer-solid
 ```
 
-Use the `beta` tag only when you intentionally want to test a prerelease:
+Use `mesurer-solid@beta` only when intentionally testing a prerelease.
 
-```bash
-bun add -d mesurer-solid@beta
-# or
-npm install -D mesurer-solid@beta
-```
+Prereleases through `0.1.0-beta.11` used the old scoped package name. Current releases use `mesurer-solid`.
 
-Prereleases through `0.1.0-beta.11` used the old scoped package name; current releases use `mesurer-solid`.
+## Where Mesurer code goes
 
-## Mount the base inspector
+Mesurer runs in the browser. Mount it once from a client/browser entry for the page you want to inspect.
 
-```ts
-import { mountMesurer } from "mesurer-solid"
+For local development in a Vite app, a clear setup is:
 
-const mesurer = mountMesurer()
+```text
+src/
+├── main.tsx
+└── dev/
+    └── mesurer.ts
 ```
 
-The base inspector contains Select, X-ray, Color Picker, Rulers, Text Inspector, Guides, Distance, Settings, the plugin host, and the low-level agent inspection API.
-
-## Add shared visual context
-
-Context and annotations are provided by removable `mesurer.context`:
+Create `src/dev/mesurer.ts`:
 
 ```ts
-import {
-  contextPlugin,
-  mountMesurer,
-} from "mesurer-solid"
+import { mountMesurer } from "mesurer-solid"
 
-const mesurer = mountMesurer({
-  agent: true,
-  plugins: [contextPlugin()],
+const mesurer = mountMesurer()
+
+import.meta.hot?.dispose(() => {
+  mesurer.dispose()
 })
 ```
 
-The human can select one or multiple elements, drag regions, place guides, create measurements/held distances, enable rulers/X-ray, and save annotation notes/baselines.
+Load it from the existing browser entry:
 
-The coding agent reads that same rendered state directly from the page. There is no Mesurer MCP, WebMCP, ACP, localhost feedback daemon, Send-to-agent callback, or chat/session routing.
+```ts
+if (import.meta.env.DEV) {
+  void import("./dev/mesurer")
+}
+```
 
-The agent contract is **context-first**: Mesurer visual operations should produce structured context the agent actually consumes.
+`import.meta.env.DEV` and `import.meta.hot` are Vite-specific. With another bundler, use its development flag and HMR lifecycle.
 
-```text
-human evidence OR agent-known affected target
-  → window.__MESURER__
-  → context() / select() / review()
-  → structured rendered evidence
-  → source edit
-  → render settles
-  → fresh context/review
-```
+Do not put `mountMesurer()` in build configuration, API/server routes, Node-only scripts, an Electron main process, or a shared SSR module that also runs on the server.
 
-## Preserve a live human instance
+Typical browser entry locations:
 
-Before injecting anything:
+| Application | Typical location |
+| --- | --- |
+| React + Vite | `src/main.tsx` |
+| Solid + Vite | `src/index.tsx`, `src/main.tsx`, or the project browser entry |
+| Vue + Vite | `src/main.ts` |
+| Svelte + Vite | `src/main.ts` |
+| Vanilla Vite | `src/main.ts` or `src/main.js` |
+| Electron | renderer entry such as `src/renderer.ts` or `src/renderer/main.tsx` |
+| SSR / metaframework | client-only module or lifecycle that never executes during SSR |
 
-```js
-const hasMesurer = Boolean(
-  window.__MESURER__ &&
-  window.__MESURER_INSTANCE__?.element?.isConnected
-)
+Put plugin setup in that same Mesurer module.
 
-if (hasMesurer) {
-  await window.__MESURER__.ready()
-}
-```
+## Base inspector
 
-If Mesurer already exists, reuse it and read existing human state before changing the selection. Injected Mesurer preserves a live instance by default. Deliberate replacement requires:
+```ts
+import { mountMesurer } from "mesurer-solid"
 
-```js
-window.__MESURER_CONFIG__ = { reuseExisting: false }
+const mesurer = mountMesurer()
 ```
 
-That option is for explicit test/tooling replacement, not normal agent attachment.
+The base inspector includes Select, X-ray, Color Picker, Rulers, Text Inspector, Guides, Distance, Settings, the plugin host, and the low-level inspection API.
 
-## Inject only when absent
+## Arrange
 
-```js
-import { readFile } from "node:fs/promises"
-import { fileURLToPath } from "node:url"
+Arrange is an optional first-party plugin for showing how selected rendered elements should be positioned without pretending to edit application source.
 
-const source = await readFile(
-  fileURLToPath(import.meta.resolve("mesurer-solid/inject-script")),
-  "utf8",
-)
+```ts
+import { mountMesurer } from "mesurer-solid"
+import { arrangePlugin } from "mesurer-solid/arrange"
 
-const hasMesurer = await browser.evaluate(() => Boolean(
-  window.__MESURER__ &&
-  window.__MESURER_INSTANCE__?.element?.isConnected
-))
+const mesurer = mountMesurer({
+  plugins: [arrangePlugin()],
+})
+```
 
-if (!hasMesurer) {
-  await browser.evaluate(source)
-}
+Select one or more page elements, click **Arrange**, and drag the selection. Hold **Shift** while dragging to lock movement to the dominant axis.
 
-await browser.evaluate(() => window.__MESURER__.ready())
-```
+Each completed drag records one persisted, undoable intent containing:
 
-Injection installs `contextPlugin()` by default. To deliberately inject only the low-level inspector:
+- target selector and fingerprint;
+- Before geometry;
+- Desired geometry;
+- previous and Desired visual offsets;
+- page scope;
+- creation time.
 
-```js
-window.__MESURER_CONFIG__ = { context: false }
-```
+Arrange only changes the temporary browser presentation. It does not write CSS, component source, templates, or application state.
 
-Screenshot capture remains opt-in for normal injection:
+### Arrange with a coding agent
 
-```js
-window.__MESURER_CONFIG__ = { screenshot: true }
-```
+For the full agent workflow, mount context and Arrange together:
 
-The first-party Chrome extension enables screenshot capture automatically.
+```ts
+import {
+  contextPlugin,
+  mountMesurer,
+} from "mesurer-solid"
+import { arrangePlugin } from "mesurer-solid/arrange"
 
-## Direct context API
+const mesurer = mountMesurer({
+  agent: true,
+  plugins: [
+    contextPlugin(),
+    arrangePlugin(),
+  ],
+})
+```
 
-With the context plugin loaded:
+The agent capability surface then includes `arrange: true` and can read saved intents:
 
 ```js
-window.__MESURER__.capabilities().capabilities
+const intents = await window.__MESURER__.arrangements()
+const intent = await window.__MESURER__.arrange(intents.at(-1).id)
 ```
 
-exposes:
+Arrange distinguishes three states:
 
 ```text
-context
-select
-annotations
-review
-capturePlan
+Before  → original presentation before the Arrange action
+Desired → human-arranged visual result
+Live    → real application result with Arrange preview removed
 ```
 
-There is no send/delivery capability or `sendContext()`.
-
-### Read the whole workspace
+The agent can reconstruct Before and Desired before editing source:
 
 ```js
-const workspace = await window.__MESURER__.context()
+await window.__MESURER__.showArrange(intent.id, "before")
+const beforePlan = await window.__MESURER__.arrangeCapturePlan(intent.id, "before")
+
+await window.__MESURER__.showArrange(intent.id, "desired")
+const desiredPlan = await window.__MESURER__.arrangeCapturePlan(intent.id, "desired")
 ```
 
-Workspace context includes page/viewport state, rulers/X-ray visibility, targets, guides, measurements, held distances, exact rects, box model, typography, appearance, layout, scroll size, and overflow.
+The outer browser harness owns screenshot bytes. Mesurer supplies the exact state and capture geometry, so the person does not need to export or attach Before/Desired screenshots manually.
 
-### Read the current human selection
+After source edits:
 
 ```js
-let selection = null
-try {
-  selection = await window.__MESURER__.context({ scope: "selection" })
-} catch {}
+await window.__MESURER__.stable()
+await window.__MESURER__.showArrange(intent.id, "live")
+const review = await window.__MESURER__.reviewArrange(intent.id)
 ```
 
-Selection context answers what the human is pointing at now. Preserve and consume it before programmatically changing selection.
+`reviewArrange()` reports exact Live-vs-Desired rectangle deltas and conservative target status.
+
+A drag is a visual specification, not a CSS prescription. If a person moves something `96px` right, the coding agent should determine the appropriate flex/grid/gap/margin/component change rather than blindly writing a `translateX(96px)` production transform.
 
-### Select exact rendered targets and get context back
+See the repository's [`docs/ARRANGE.md`](https://github.com/jhomra21/mesurer-solid/blob/main/docs/ARRANGE.md) for the full workflow.
 
-When an agent knows exactly which rendered element it wants to highlight/verify, it can select it itself:
+## Shared visual context
+
+Context and annotations are provided by the optional `mesurer.context` plugin:
+
+```ts
+import {
+  contextPlugin,
+  mountMesurer,
+} from "mesurer-solid"
+
+const mesurer = mountMesurer({
+  agent: true,
+  plugins: [contextPlugin()],
+})
+```
+
+Read the workspace or current human selection:
 
 ```js
-const context = await window.__MESURER__.select("#pricing-card")
+const workspace = await window.__MESURER__.context()
+const selection = await window.__MESURER__.context({ scope: "selection" })
 ```
 
-For several exact targets:
+Select exact rendered targets and get their context back:
 
 ```js
 const context = await window.__MESURER__.select([
@@ -182,94 +198,70 @@ const context = await window.__MESURER__.select([
 ])
 ```
 
-`select()`:
-
-1. enables Mesurer and switches to Select;
-2. visibly highlights those rendered elements;
-3. makes them the live selection;
-4. waits for the selection to settle;
-5. returns selection-scoped `MesurerContextV1`.
+Every selector must resolve to exactly one page target. Invalid, missing, or ambiguous selectors throw instead of guessing.
 
-The return value is intentional. Agents should consume it rather than treating the highlight as the end of the operation.
+`MesurerContextV1` includes rendered geometry, box model, typography, appearance, flex/grid layout, transforms, scroll/overflow, guides, measurements, distances, selected targets, and annotated regions.
 
-Every selector must resolve to exactly one element inside the page target. Invalid, missing, or ambiguous selectors throw. Refine the selector or ask the human to select the intended target rather than guessing.
+## Annotations and review
 
-This gives agents a clean post-edit verification pattern:
+A human annotation stores a note plus an immutable rendered baseline:
 
 ```js
-await window.__MESURER__.stable()
-
-const evidence = await window.__MESURER__.select([
-  changedSelectorA,
-  changedSelectorB,
-])
+const annotations = await window.__MESURER__.annotations()
+const context = await window.__MESURER__.context({
+  annotation: annotations[0].id,
+})
 ```
 
-The user sees what the agent changed, and the agent receives the exact rendered evidence in the same operation.
-
-## Multi-selection
-
-For every selected target, context contains selector/identity, rect, margin/padding/border, typography, appearance, layout, and scroll/overflow.
-
-Use existing `visualContext.distances` first, then `distance(selectorA, selectorB)` for selected pairs whose relationship is not already represented. Small multi-selections should expose useful pairwise pixel relationships rather than merely saying “3 elements selected.”
-
-## Saved annotations
+After a source change:
 
 ```js
-const annotations = await window.__MESURER__.annotations()
-
-for (const annotation of annotations) {
-  const context = await window.__MESURER__.context({ annotation: annotation.id })
-}
+await window.__MESURER__.stable()
+const review = await window.__MESURER__.review(annotationId)
 ```
 
-An annotation adds a durable note and immutable baseline. The note is human intent; geometry/computed styles/guides/distances/screenshots are supporting evidence.
-
-## Agent target-acquisition rule
+Review reports concrete pixel changes and missing evidence rather than relying on source assumptions.
 
-When Mesurer is available, agents should follow this order:
+## Agent integration
 
-1. existing relevant human selection/annotation → read it first;
-2. no relevant selection and intended target is ambiguous → ask the human to select it, then read selection context;
-3. no relevant selection and agent knows exact affected rendered targets → call `select()` and consume the returned context.
+The coding-agent contract is context-first and preserves existing human state:
 
-Do not ask the user to select something the agent can identify exactly itself. Do not guess when the target truly is ambiguous.
+```text
+human Arrange / annotation / selection
+  → window.__MESURER__
+  → structured rendered evidence
+  → source edit
+  → real render / HMR
+  → fresh Live review/context
+```
 
-## Verify the rendered fix
+There is no Mesurer MCP, WebMCP, ACP, localhost feedback daemon, Send-to-agent callback, or chat/session routing.
 
-After source edits and the real page update:
+Before injecting anything, reuse a live Mesurer instance if one is already present:
 
 ```js
-await window.__MESURER__.stable()
-```
-
-For a saved annotation:
+const hasMesurer = Boolean(
+  window.__MESURER__ &&
+  window.__MESURER_INSTANCE__?.element?.isConnected
+)
 
-```js
-const review = await window.__MESURER__.review(annotationId)
+if (hasMesurer) {
+  await window.__MESURER__.ready()
+}
 ```
 
-For a still-relevant human selection:
-
-```js
-const after = await window.__MESURER__.context({ scope: "selection" })
-```
+A live human instance may already contain the information the agent needs. Do not overwrite selection, Arrange history, guides, measurements, annotations, or screenshot preview state before reading it.
 
-When the agent knows the affected rendered targets:
+Install the portable Agent Skill with:
 
-```js
-const after = await window.__MESURER__.select([
-  changedSelectorA,
-  changedSelectorB,
-])
+```bash
+npx --yes --package=mesurer-solid mesurer-skill install
 ```
 
-For meaningful visual work, fresh Mesurer context/review is part of completion. Lint, typecheck, tests, and build are implementation checks, not rendered proof.
+For detailed agent rules, use [`AGENT_INTEGRATION.md`](./AGENT_INTEGRATION.md).
 
 ## Optional screenshot plugin
 
-Screenshot capture is a removable first-party plugin instead of permanent core state:
-
 ```ts
 import { mountMesurer } from "mesurer-solid"
 import { screenshotPlugin } from "mesurer-solid/screenshot"
@@ -284,98 +276,62 @@ const mesurer = mountMesurer({
 })
 ```
 
-The camera tool lets the user drag a viewport region. Mesurer captures the real visible page, converts CSS viewport coordinates to the captured bitmap scale so Retina/HiDPI crops remain exact, temporarily hides its control chrome from the pixels, then restores the previous inspector presentation.
-
-A successful capture can automatically copy PNG data to the clipboard and/or download a PNG according to persistent plugin settings. Those output operations are best-effort: if clipboard or download access is unavailable, the captured PNG is still kept for preview/viewer use and Mesurer reports the available result instead of discarding it.
-
-When `contextPlugin()` and/or `screenshotPlugin()` are mounted, Settings → General → Plugins exposes compact persisted controls for the human-facing plugin surface. Context can hide or restore its toolbar/annotation controls without removing the typed context service. Screenshot can hide or restore the camera tool and control automatic copy, automatic download, and whether measurement presentation is included in captured pixels.
-
-After capture, Mesurer shows a persistent draggable thumbnail. A new thumbnail starts in the bottom-right with an 8px viewport inset. Dragging preserves the existing viewport-clamping behavior, so the preview stays inside that safe boundary. The thumbnail can be dismissed, dragged around the viewport, right-clicked with the browser's native image context menu, or clicked to open a larger viewer. The viewer preserves native image right-click behavior and adds explicit Copy, Save, and Close controls. Escape or backdrop click closes the viewer without discarding the thumbnail. A short status message confirms whether the screenshot was copied, saved, captured, or could not complete an optional output.
-
-Normal browser hosts use `getDisplayMedia()` and reuse a live capture stream to avoid prompting for every region. The first-party Chrome extension uses `chrome.tabs.captureVisibleTab()` through its isolated-world extension bridge, so its screenshot path does not open the screen-share chooser and does not require a broad `<all_urls>` permission.
-
-Programmatic mounted users can get the typed `MesurerScreenshotService` from the plugin host with service id `screenshot`. `start()` opens region selection, `cancel()` closes it, `capture(rect)` captures an exact CSS-pixel viewport rectangle, `settings()` reads copy/download preferences, and `setSettings()` updates those persistent preferences.
+The human camera tool supports drag-region visible-tab capture, HiDPI/Retina-aware PNG cropping, copy/download settings, a draggable thumbnail, and a larger Copy/Save viewer.
 
-Screenshot does not claim the global `C` shortcut because the context workflow already uses `C` and `Shift+C`.
-
-## Clean screenshot evidence for agents
-
-The optional screenshot plugin is a human capture tool, not an agent-delivery channel. Agent verification can continue to let the existing browser harness own deterministic task screenshots while Mesurer plans a clean evidence frame:
+For coding-agent verification, the outer browser harness should normally own screenshot bytes. Mesurer supplies exact capture scope and can temporarily remove inspector presentation:
 
 ```js
 const plan = await window.__MESURER__.capturePlan({ scope: "selection" })
+
 await window.__MESURER__.prepareCapture()
 try {
-  // Capture the real viewport and optional focus crop through the harness.
+  // use the harness screenshot primitive
 } finally {
   await window.__MESURER__.finishCapture()
 }
 ```
 
-Use screenshots for visual composition and Mesurer context for exact numeric claims. A screenshot plugin image does not create a `screenshots` delivery capability on `window.__MESURER__` and does not replace context/select/review evidence.
-
-## Context UI
-
-With default `contextPlugin()` UI:
-
-| Action | Shortcut | What it does |
-| --- | --- | --- |
-| Copy Context | `C` | Copies current workspace context. |
-| Copy Selection | `Shift+C` | Copies context scoped to selected element(s) or region. |
-| Add Note | `N` | Creates a durable annotation baseline. |
-
-Those remain the three human context controls. `select()` is a programmatic agent/harness API, not another toolbar action.
-
-## Portable Agent Skill
-
-```bash
-npx --yes --package=mesurer-solid mesurer-skill install
-```
+## Public entry points
 
-The installer leaves:
+```ts
+import {
+  contextPlugin,
+  defineMesurerPlugin,
+  mountMesurer,
+} from "mesurer-solid"
 
-```text
-.agents/skills/mesurer-ui/
-├── SKILL.md
-└── assets/
-    └── inject-script.js
+import { arrangePlugin } from "mesurer-solid/arrange"
+import { createMesurerPluginHost } from "mesurer-solid/core"
+import { screenshotPlugin } from "mesurer-solid/screenshot"
 ```
 
-The skill teaches the context-first workflow, including when to consume human selection, when to ask for a selection, when to self-select changed targets, multi-selection reads, fresh post-edit verification, and the distinction between the optional human screenshot plugin and harness-owned agent screenshot evidence. See [`AGENT_INTEGRATION.md`](./AGENT_INTEGRATION.md).
-
-## Low-level agent API
-
-Regardless of the context plugin:
+The transport-neutral classic browser payload is:
 
 ```text
-ready / stable
-inspect / inspectAll / at
-distance / viewport / feedback
-describe / command / state
+mesurer-solid/inject-script
 ```
 
-Use low-level APIs for narrow measurement questions. Prefer `context()`, `select()`, and `review()` for normal visual work.
+## Supported hosts
 
-## Plugins
+Mesurer's renderer is bundled and isolated from the host framework. Supported host classes include:
 
-```ts
-import {
-  createMesurerPluginHost,
-  createMesurerRuntime,
-  defineMesurerPlugin,
-} from "mesurer-solid/core"
-```
+- Solid 1
+- Solid 2
+- React
+- Vue
+- Svelte
+- vanilla DOM applications
+- Electron renderer pages
 
-Plugins can contribute tools, commands, hooks, overlays, settings, state, services, history/persistence, renderer-owned UI, and lifecycle cleanup. Plugin-defined toggle settings can register through the plugin host and appear in the canonical General → Plugins Settings section without hard-coding the plugin into Mesurer's renderer.
+## More documentation
 
-## Public surface
+- [Getting started](https://github.com/jhomra21/mesurer-solid/blob/main/docs/GETTING_STARTED.md)
+- [Arrange](https://github.com/jhomra21/mesurer-solid/blob/main/docs/ARRANGE.md)
+- [Context workflow](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CONTEXT_WORKFLOW.md)
+- [Screenshots](https://github.com/jhomra21/mesurer-solid/blob/main/docs/SCREENSHOTS.md)
+- [Host isolation](https://github.com/jhomra21/mesurer-solid/blob/main/docs/HOST_ISOLATION.md)
+- [Agent integration](./AGENT_INTEGRATION.md)
 
-```text
-mesurer-solid
-mesurer-solid/core
-mesurer-solid/screenshot
-mesurer-solid/inject
-mesurer-solid/inject-script
-```
+## License
 
-MIT. Adapted from `ibelick/mesurer`; see `THIRD_PARTY_LICENSES.md`.
+MIT

package/dist/arrange.d.ts

@@ -0,0 +1,90 @@
+import type { MesurerPlugin } from "./core";
+export declare const MESURER_ARRANGE_ACTIVE_STATE_ID: string;
+export declare const MESURER_ARRANGE_PLUGIN_ID: string;
+export declare const MESURER_ARRANGE_SERVICE_ID: string;
+export declare const MESURER_ARRANGE_SETTINGS_STATE_ID: string;
+export declare const MESURER_ARRANGE_STATE_ID: string;
+export type ArrangeRect = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+export type ArrangeOffset = {
+    x: number;
+    y: number;
+};
+export type ArrangeElementFingerprint = {
+    tag: string;
+    id: string | null;
+    testId: string | null;
+    role: string | null;
+    ariaLabel: string | null;
+    classes: string[];
+    text: string | null;
+};
+export type ArrangeTarget = {
+    id: string;
+    selector: string;
+    fingerprint: ArrangeElementFingerprint;
+    before: ArrangeRect;
+    desired: ArrangeRect;
+    beforeOffset: ArrangeOffset;
+    desiredOffset: ArrangeOffset;
+};
+export type ArrangeIntent = {
+    id: string;
+    createdAt: number;
+    pageUrl: string;
+    targets: ArrangeTarget[];
+};
+export type ArrangePresentation = "before" | "desired" | "live";
+export type ArrangeReviewTarget = {
+    targetId: string;
+    selector: string;
+    desired: ArrangeRect;
+    current: ArrangeRect | null;
+    delta: ArrangeRect | null;
+    matched: boolean;
+};
+export type ArrangeReview = {
+    schema: "mesurer.arrange-review/v1";
+    arrangeId: string;
+    targetStatus: "connected" | "partial" | "stale";
+    tolerance: number;
+    matched: boolean;
+    targets: ArrangeReviewTarget[];
+};
+export type ArrangeCapturePlan = {
+    schema: "mesurer.arrange-capture/v1";
+    arrangeId: string;
+    state: ArrangePresentation;
+    chrome: "hide";
+    captures: Array<{
+        id: "viewport";
+        kind: "viewport";
+    } | {
+        id: "focus";
+        kind: "clip";
+        rect: ArrangeRect;
+    }>;
+};
+export type MesurerArrangeSettings = {
+    snapping: boolean;
+    elementEdges: boolean;
+    elementCenters: boolean;
+    guides: boolean;
+    preferXrayEdges: boolean;
+    snapLines: boolean;
+};
+export type MesurerArrangeService = {
+    active(): boolean;
+    intents(): ArrangeIntent[];
+    intent(id: string): ArrangeIntent | null;
+    show(id: string, state: ArrangePresentation): void;
+    showCurrent(): void;
+    capturePlan(id: string, state: ArrangePresentation): ArrangeCapturePlan;
+    review(id: string, tolerance?: number): ArrangeReview;
+    clear(): Promise<void>;
+};
+export declare const arrangePlugin: () => MesurerPlugin;