mesurer-solid 0.1.0-beta.11

package/AGENT_INTEGRATION.md

@@ -0,0 +1,189 @@
+# Mesurer agent integration
+
+Mesurer uses standards and a browser contract instead of harness-specific integrations.
+
+```text
+Agent Skill            window.__MESURER__             ACP
+how/when to use it     visual context + validation    standardized delivery
+       \                       |                       /
+        \______________________|______________________/
+                               |
+                         any capable harness
+```
+
+There is no required OpenCode, Pi, Cursor, Codex, or other Mesurer adapter package.
+
+## 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:
+
+```text
+.agents/skills/mesurer-ui/
+├── SKILL.md
+└── assets/
+    └── 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.
+
+## Default browser integration: inject
+
+**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.
+
+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.
+
+When `mesurer-solid` is already installed as a project/tooling dependency, the equivalent package path is the `/inject-script` export:
+
+```js
+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()`);
+```
+
+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:
+
+```js
+window.__MESURER_CONFIG__ = { context: false };
+```
+
+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.
+
+## Discover the browser contract
+
+Wait for plugin setup before reading dynamic capabilities:
+
+```js
+if (window.__MESURER__) {
+  await window.__MESURER__.ready()
+  window.__MESURER__.capabilities()
+}
+```
+
+`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.
+
+### Human-in-the-loop context
+
+With the plugin loaded:
+
+```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 })
+```
+
+`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.
+
+### Revalidate after edits
+
+```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()` 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.
+
+### Clean screenshots
+
+The outer harness owns real browser screenshots. The context plugin defines the evidence frame:
+
+```js
+const plan = await window.__MESURER__.capturePlan({ annotation: annotationId })
+await window.__MESURER__.prepareCapture()
+try {
+  // harness screenshot: current viewport
+  // close-up when present: plan.captures.find(c => c.id === "focus")
+} 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 screenshots together with structured context. Screenshots are strong visual evidence; Mesurer geometry is stronger evidence for exact spacing/alignment claims.
+
+## Source-mounted integrations
+
+When Mesurer is mounted from application code, explicitly install the same plugin:
+
+```ts
+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.
+
+## 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);
+```
+
+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`.
+
+## Existing low-level API
+
+These JSON-safe primitives remain available whether or not `mesurer.context` is loaded:
+
+```js
+window.__MESURER__.inspect(".selector")
+window.__MESURER__.inspectAll(".selector")
+window.__MESURER__.at(x, y)
+window.__MESURER__.distance(".a", ".b")
+window.__MESURER__.viewport()
+await window.__MESURER__.feedback([".selector"])
+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 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.
+
+## Ownership boundary
+
+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.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jhomra21
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# mesurer-solid
+
+Framework-agnostic UI measurement, annotation, inspection, and agent-ready visual 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.
+
+## Install
+
+```bash
+bun add -d mesurer-solid@beta
+# or
+npm install -D mesurer-solid@beta
+```
+
+> **Package rename:** prereleases through `0.1.0-beta.11` were published as `@jhomra21/mesurer-solid`. New releases use the canonical unscoped package name `mesurer-solid`. The API is unchanged; update dependency and import specifiers to the new name.
+
+## Mount the base inspector
+
+```ts
+import { mountMeasurer } from "mesurer-solid";
+
+const mesurer = mountMeasurer();
+```
+
+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.
+
+## Enable context, copy actions, and annotations
+
+Context and annotation features are provided by the removable `mesurer.context` plugin. Source-mounted applications opt in explicitly:
+
+```ts
+import {
+  contextPlugin,
+  mountMeasurer,
+} from "mesurer-solid";
+
+const mesurer = mountMeasurer({
+  agent: true,
+  plugins: [contextPlugin()],
+});
+```
+
+With the default `contextPlugin()` UI enabled, Mesurer adds these controls to the existing draggable toolbar:
+
+| Action | Shortcut | What it does |
+| --- | --- | --- |
+| Copy Context | `C` | Copies the current workspace context. |
+| Copy Selection | `Shift+C` | Copies context scoped to the selected element(s) or dragged region. |
+| Add Note | `N` | Creates an annotation for the current element selection or dragged region. |
+| Send selection | `Cmd/Ctrl+Enter` | Appears only when `sendContext` is configured and sends scoped context through the host callback. |
+
+### Annotating elements, multi-selection, and regions
+
+For one element, select it and use the floating annotation button, **Add Note** in the toolbar, or `N`.
+
+For multiple elements, Shift-select the elements you want to annotate. The floating annotation button starts on the first selected element and follows the selected element currently under the pointer. The composer shows the selected-element count, and the saved annotation keeps **all** selected targets in its context rather than only the element that hosted the button.
+
+Saved annotation markers can be clicked to reopen their note panel. The note composer and saved annotation panels can both be dragged by their header, while the underlying selection remains intact. Saved panels also show how many elements the note applies to.
+
+For an arbitrary dragged region with no element target, use **Add Note** in the toolbar or `N`. Region-only notes are fully supported even though the small floating annotation button is element-selection focused.
+
+### Use the same context programmatically
+
+`contextPlugin()` provides the `context:v1` service and owns annotation state, Copy Context/Copy Selection/Add Note UI, shortcuts, review/capture behavior, optional delivery callbacks, and cleanup.
+
+```ts
+const workspace = await mesurer.context();
+const selected = await mesurer.context({ scope: "selection" });
+const annotation = await mesurer.context({ annotation: annotationId });
+await mesurer.copyContext({ annotation: annotationId });
+```
+
+A scoped context includes `regions`, the viewport rectangles the person actually selected or annotated. That keeps arbitrary-area feedback useful even when no DOM element is inside the region, and gives screenshot planning the same focus area the structured context uses.
+
+After a source edit/HMR cycle:
+
+```ts
+const review = await mesurer.review(annotationId);
+```
+
+Review uses stable annotation target IDs, conservatively rebinds replaced DOM, and reports relevant baseline evidence that disappears with `kind: "missing"`.
+
+### Context without visible UI
+
+If a host wants the context/review APIs but not the Copy/Add Note toolbar controls or annotation UI, keep the plugin and disable only its UI:
+
+```ts
+const mesurer = mountMeasurer({
+  agent: true,
+  plugins: [contextPlugin({ ui: false })],
+});
+```
+
+Remove the complete feature through the same plugin host used by every extension:
+
+```ts
+mesurer.pluginHost?.remove("mesurer.context");
+console.log(mesurer.agent.capabilities().capabilities.context); // false
+```
+
+The mounted/browser convenience methods resolve `context:v1`; they do not maintain a second hidden context implementation.
+
+## Coding-agent browser API
+
+With `agent: true` and the context plugin loaded, wait for plugin initialization before reading dynamic capabilities:
+
+```js
+await window.__MESURER__.ready()
+window.__MESURER__.capabilities()
+await window.__MESURER__.annotations()
+await window.__MESURER__.context({ annotation: annotationId })
+await window.__MESURER__.stable()
+await window.__MESURER__.review(annotationId)
+```
+
+The original low-level inspection API remains available regardless of the context plugin:
+
+```text
+inspect / inspectAll / at
+distance / viewport / feedback
+describe / command / state / stable
+```
+
+## Inject into an existing harness
+
+Do not create another browser or change application source just for Mesurer when the harness already has a page JavaScript-evaluation primitive.
+
+```js
+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()`);
+```
+
+Injection installs `contextPlugin()` **by default**, so Copy Context, Copy Selection, Add Note, annotation markers, and the context/review APIs are available without extra configuration. To inject only the base/low-level inspector:
+
+```js
+window.__MESURER_CONFIG__ = { context: false };
+```
+
+See [`AGENT_INTEGRATION.md`](./AGENT_INTEGRATION.md).
+
+## Clean screenshot evidence
+
+The context plugin does not own a screenshot engine. It prepares the actual page so the outer harness can capture real pixels:
+
+```js
+const plan = await window.__MESURER__.capturePlan({ annotation: annotationId })
+await window.__MESURER__.prepareCapture()
+try {
+  // Capture the real viewport and optional focus crop.
+} finally {
+  await window.__MESURER__.finishCapture()
+}
+```
+
+The focus crop includes scoped `regions`, so element-free area annotations still get close-up evidence. Capture mode hides Mesurer controls while preserving guides, rulers, measurements, distances, annotation/selection markers, and pixel labels.
+
+## Optional host delivery
+
+Screenshot and direct-send capabilities belong to the plugin configuration rather than core mount options:
+
+```ts
+const mesurer = mountMeasurer({
+  agent: true,
+  plugins: [
+    contextPlugin({
+      evidenceProvider: async ({ context, plan }) => {
+        // Use the host/harness real screenshot primitive.
+        return [];
+      },
+      sendContext: async ({ context, text, images }) => {
+        // Deliver with the ACP client/session already owned by the host.
+      },
+    }),
+  ],
+});
+```
+
+Without `sendContext`, the plugin does not render a Send control.
+
+## Portable Agent Skill
+
+There are no Mesurer packages for individual harnesses. The npm package ships one canonical `mesurer-ui` Agent Skill:
+
+```bash
+npx --yes --package=mesurer-solid@beta mesurer-skill install
+```
+
+The transient installer leaves a self-contained skill at `.agents/skills/mesurer-ui/`, including `assets/inject-script.js`. An Agent-Skills-compatible harness can therefore discover the workflow and inject Mesurer through its existing browser evaluation channel without keeping the npm package installed in the application.
+
+## ACP
+
+Mesurer does not discover agents, manage processes, or choose sessions. The ACP client/harness that already owns a target session sends Mesurer output.
+
+```ts
+import { toAcpContentBlocks } from "mesurer-solid";
+
+const blocks = toAcpContentBlocks(context, images);
+```
+
+The result is one context text block plus optional labeled image blocks. If image prompts are unavailable, send the text block only. Copy Context remains the universal fallback.
+
+## Plugins
+
+```ts
+import {
+  createMesurerPluginHost,
+  createMesurerRuntime,
+  defineMesurerPlugin,
+} from "mesurer-solid/core";
+```
+
+Plugins can contribute tools, commands, hooks, overlays, settings, state, services, history/persistence, renderer-owned UI, and lifecycle cleanup. Built-ins can be excluded/replaced without forking the renderer. Plugin tools render through the same canonical toolbar button path as built-ins; programmatic built-in commands use the owning renderer instance rather than toolbar DOM labels or synthetic keyboard events.
+
+## Public surface
+
+```text
+mesurer-solid
+mesurer-solid/core
+mesurer-solid/inject
+mesurer-solid/inject-script
+```
+
+The package is self-contained. Private core/DOM/renderer workspaces and the internal Solid runtime must not leak into the published consumer surface.
+
+MIT. Adapted from `ibelick/mesurer`; see `THIRD_PARTY_LICENSES.md`.

package/THIRD_PARTY_LICENSES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+## Mesurer
+
+Portions of this package are adapted from [`ibelick/mesurer`](https://github.com/ibelick/mesurer), including framework-neutral measurement/runtime logic and the user-facing visual design system ported to Solid JSX.
+
+Mesurer is licensed under the MIT License:
+
+> MIT License
+>
+> Copyright (c) 2026 Julien Thibeaut
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy
+> of this software and associated documentation files (the "Software"), to deal
+> in the Software without restriction, including without limitation the rights
+> to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+> copies of the Software, and to permit persons to whom the Software is
+> furnished to do so, subject to the following conditions:
+>
+> The above copyright notice and this permission notice shall be included in all
+> copies or substantial portions of the Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+> IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+> FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+> AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+> LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+> SOFTWARE.

package/dist/agent.d.ts

@@ -0,0 +1,113 @@
+import type { MesurerPluginDescription, MesurerPluginHost } from "./core";
+export type AgentRect = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+};
+export type AgentEdges = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+export type AgentElementInspection = {
+    selector: string;
+    tag: string;
+    id: string | null;
+    classes: string[];
+    text: string;
+    role: string | null;
+    ariaLabel: string | null;
+    rect: AgentRect;
+    margin: AgentEdges;
+    padding: AgentEdges;
+    border: AgentEdges;
+    typography: {
+        fontFamily: string;
+        fontSize: string;
+        fontWeight: string;
+        lineHeight: string;
+        letterSpacing: string;
+        textAlign: string;
+        color: string;
+    };
+    appearance: {
+        backgroundColor: string;
+        borderColor: string;
+        borderRadius: string;
+        boxShadow: string;
+        opacity: string;
+    };
+    layout: {
+        display: string;
+        position: string;
+        zIndex: string;
+        overflowX: string;
+        overflowY: string;
+        flexDirection: string;
+        alignItems: string;
+        justifyContent: string;
+        gap: string;
+        gridTemplateColumns: string;
+        gridTemplateRows: string;
+        transform: string;
+    };
+    scroll: {
+        clientWidth: number;
+        clientHeight: number;
+        scrollWidth: number;
+        scrollHeight: number;
+        overflowsX: boolean;
+        overflowsY: boolean;
+    };
+};
+export type AgentDistance = {
+    a: AgentElementInspection;
+    b: AgentElementInspection;
+    horizontalGap: number;
+    verticalGap: number;
+    centerDeltaX: number;
+    centerDeltaY: number;
+};
+export type AgentViewportSnapshot = {
+    width: number;
+    height: number;
+    devicePixelRatio: number;
+    scrollX: number;
+    scrollY: number;
+    documentWidth: number;
+    documentHeight: number;
+    horizontalOverflow: boolean;
+    verticalOverflow: boolean;
+};
+export type AgentFeedbackSnapshot = {
+    viewport: AgentViewportSnapshot;
+    elements: AgentElementInspection[];
+    plugins: MesurerPluginDescription | undefined;
+    pluginState: Record<string, unknown>;
+};
+export type MesurerAgentHarness = {
+    ready(): Promise<void>;
+    describe(): Promise<MesurerPluginDescription | undefined>;
+    inspect(selector: string, index?: number): AgentElementInspection | null;
+    inspectAll(selector: string, limit?: number): AgentElementInspection[];
+    at(x: number, y: number): AgentElementInspection | null;
+    distance(a: string, b: string): AgentDistance | null;
+    viewport(): AgentViewportSnapshot;
+    feedback(selectors?: string[]): Promise<AgentFeedbackSnapshot>;
+    command(id: string, args?: unknown): Promise<void>;
+    state(): Promise<Record<string, unknown>>;
+    stable(frames?: number): Promise<void>;
+};
+export type CreateMesurerAgentHarnessOptions = {
+    ownerDocument: Document;
+    root?: ParentNode;
+    getPluginHost: () => MesurerPluginHost | undefined;
+    waitForPluginHost: () => Promise<MesurerPluginHost>;
+};
+export declare function createMesurerAgentHarness(options: CreateMesurerAgentHarnessOptions): MesurerAgentHarness;

package/dist/context-contract-parity.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/context-plugin.d.ts

@@ -0,0 +1,27 @@
+import type { MesurerPlugin } from "./core";
+import { type MesurerAnnotation, type MesurerCapturePlanV1, type MesurerContextRequest, type MesurerContextSender, type MesurerContextV1, type MesurerEvidenceProvider, type MesurerReviewV1 } from "./context";
+export declare const MESURER_CONTEXT_PLUGIN_ID = "mesurer.context";
+export declare const MESURER_CONTEXT_SERVICE_ID = "context:v1";
+export type MesurerContextPluginOptions = {
+    /** Render Copy Context, Copy Selection, Add Note, annotation markers, and optional Send controls. Defaults to true. */
+    ui?: boolean;
+    /** Optional screenshot provider owned by the browser/harness. */
+    evidenceProvider?: MesurerEvidenceProvider;
+    /** Optional direct handoff callback, normally backed by an ACP client outside Mesurer. */
+    sendContext?: MesurerContextSender;
+    sendLabel?: string;
+};
+export type MesurerContextService = {
+    context(request?: MesurerContextRequest): Promise<MesurerContextV1>;
+    contextText(request?: MesurerContextRequest): Promise<string>;
+    copyContext(request?: MesurerContextRequest): Promise<void>;
+    annotations(): Promise<MesurerAnnotation[]>;
+    review(annotationId?: string): Promise<MesurerReviewV1 | MesurerReviewV1[]>;
+    capturePlan(request?: MesurerContextRequest): Promise<MesurerCapturePlanV1>;
+    prepareCapture(): Promise<void>;
+    finishCapture(): Promise<void>;
+    sendContext(request?: MesurerContextRequest): Promise<void>;
+    readonly screenshots: boolean;
+    readonly send: boolean;
+};
+export declare function contextPlugin(options?: MesurerContextPluginOptions): MesurerPlugin;