mesurer-solid 0.1.0 → 0.1.1-beta.1

package/AGENT_INTEGRATION.md

@@ -28,10 +28,14 @@ The page is the shared state boundary. Mesurer never needs to know which chat, t
 
 ## Install the portable Agent Skill
 
+Use the stable package by default:
+
 ```bash
-npx --yes --package=mesurer-solid@beta mesurer-skill install
+npx --yes --package=mesurer-solid mesurer-skill install
 ```
 
+Use `mesurer-solid@beta` only when intentionally validating a prerelease.
+
 The installed skill is self-contained:
 
 ```text
@@ -41,7 +45,7 @@ The installed skill is self-contained:
     └── inject-script.js
 ```
 
-The skill defines the same context-first workflow described here.
+The skill defines the same context-first workflow described here, including the distinction between Mesurer's optional human screenshot plugin and screenshots owned by the agent's outer browser harness.
 
 ## Reuse a live human instance first
 
@@ -58,7 +62,7 @@ if (hasMesurer) {
 }
 ```
 
-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.
+If Mesurer exists, use that exact instance. The person may already have selected elements, placed guides, measured gaps, held distances, enabled rulers/X-ray, saved annotations, or kept a screenshot preview open. Read and preserve that state before changing it.
 
 The injector also reuses a live injected instance by default. Deliberate destructive replacement requires:
 
@@ -97,6 +101,14 @@ await browser.evaluate(() => window.__MESURER__.ready())
 
 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.
 
+Normal injection keeps screenshot capture disabled unless requested:
+
+```js
+window.__MESURER_CONFIG__ = { screenshot: true }
+```
+
+The first-party Chrome extension enables the screenshot plugin automatically because its human-facing camera tool can use the extension's visible-tab capture bridge.
+
 ## Capability contract
 
 After `ready()`:
@@ -123,7 +135,7 @@ Copy Selection
 Add Note
 ```
 
-There is no `send`, `screenshots`, or `sendContext` delivery capability.
+There is no `send`, `screenshots`, or `sendContext` **delivery capability**. The optional `mesurer.screenshot` plugin is a separate human capture tool/service and does not add image delivery to the context API.
 
 ## Context acquisition precedence
 
@@ -326,9 +338,32 @@ expected target/guide/measurement missing
 
 If the requested result remains numerically wrong, continue editing.
 
-## Screenshots complement context
+## Human screenshot plugin vs agent screenshot evidence
+
+Mesurer has two intentionally different screenshot paths.
+
+### Human capture tool
+
+The optional `mesurer.screenshot` plugin gives the person a camera tool inside Mesurer:
+
+```ts
+import { mountMeasurer } from "mesurer-solid"
+import { screenshotPlugin } from "mesurer-solid/screenshot"
+
+const mesurer = mountMeasurer({
+  plugins: [screenshotPlugin()],
+})
+```
+
+The user can drag a viewport region, capture a real HiDPI-aware PNG, optionally copy/download it, keep a persistent draggable thumbnail, and open a larger Copy/Save viewer. Normal browser hosts use `getDisplayMedia()`; the first-party Chrome extension uses `chrome.tabs.captureVisibleTab()` through its isolated-world bridge and therefore avoids the screen-share chooser.
 
-Mesurer supplies capture scope; the outer harness supplies real pixels:
+For advanced mounted integrations, the typed `MesurerScreenshotService` is available from the plugin host under service id `screenshot`. It is not part of `window.__MESURER__`'s context/delivery capability surface.
+
+Agents should preserve an existing human screenshot preview unless the task explicitly asks them to test, close, replace, or otherwise manipulate the screenshot feature.
+
+### Agent verification screenshot
+
+For coding-agent verification, the outer harness should normally continue to own screenshot bytes so the task can control the exact browser, viewport, timing, and artifact destination. Mesurer supplies clean capture scope/presentation:
 
 ```js
 const plan = await window.__MESURER__.capturePlan({ scope: "selection" })
@@ -348,6 +383,8 @@ Mesurer context → exact geometry, box model, styles, distances, overflow
 real screenshot → composition, hierarchy, clipping, color, visual judgment
 ```
 
+Do not replace exact Mesurer measurements with pixel estimates from either screenshot path.
+
 ## Source-mounted usage
 
 When Mesurer is intentionally mounted from application code:
@@ -367,7 +404,7 @@ The same API is available on `mesurer.agent` and, when configured, `window.__MES
 const context = await mesurer.agent.select("#target")
 ```
 
-No transport callback is involved.
+Screenshot capture can be composed independently with `screenshotPlugin()` when the host wants the human camera tool. No transport callback is involved.
 
 ## Low-level inspection
 
@@ -391,7 +428,7 @@ Prefer `context()`, `select()`, and `review()` for visual development because th
 A good harness-level visual completion loop is:
 
 ```text
-1. discover/reuse Mesurer
+1. discover/reuse Mesurer and preserve human state
 2. consume existing human context
 3. if target ambiguous, ask user to select
 4. otherwise select known affected rendered target(s) when needed
@@ -399,8 +436,10 @@ A good harness-level visual completion loop is:
 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
+9. optionally capture a real screenshot through the outer harness
 10. iterate until rendered evidence supports the claim
 ```
 
+When the task is specifically testing Mesurer's screenshot plugin, exercise its camera/preview/viewer path as the feature under test; otherwise do not substitute it for the harness's normal screenshot primitive.
+
 **Context is the output of the Mesurer step, not an optional side effect.**

package/README.md

@@ -6,13 +6,23 @@ The renderer is implemented privately in Solid 2, but consumers can use Solid 1/
 
 ## Install
 
+Stable releases use the `latest` dist-tag:
+
+```bash
+bun add -d mesurer-solid
+# or
+npm install -D mesurer-solid
+```
+
+Use the `beta` tag only when you intentionally want to test 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. New releases use `mesurer-solid`.
+Prereleases through `0.1.0-beta.11` used the old scoped package name; current releases use `mesurer-solid`.
 
 ## Mount the base inspector
 
@@ -108,6 +118,14 @@ Injection installs `contextPlugin()` by default. To deliberately inject only the
 window.__MESURER_CONFIG__ = { context: false }
 ```
 
+Screenshot capture remains opt-in for normal injection:
+
+```js
+window.__MESURER_CONFIG__ = { screenshot: true }
+```
+
+The first-party Chrome extension enables screenshot capture automatically.
+
 ## Direct context API
 
 With the context plugin loaded:
@@ -248,9 +266,41 @@ const after = await window.__MESURER__.select([
 
 For meaningful visual work, fresh Mesurer context/review is part of completion. Lint, typecheck, tests, and build are implementation checks, not rendered proof.
 
-## Clean screenshot evidence
+## Optional screenshot plugin
+
+Screenshot capture is a removable first-party plugin instead of permanent core state:
+
+```ts
+import { mountMeasurer } from "mesurer-solid"
+import { screenshotPlugin } from "mesurer-solid/screenshot"
+
+const mesurer = mountMeasurer({
+  plugins: [
+    screenshotPlugin({
+      copy: true,
+      download: false,
+    }),
+  ],
+})
+```
+
+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.
+
+Screenshot does not claim the global `C` shortcut because the context workflow already uses `C` and `Shift+C`.
+
+## Clean screenshot evidence for agents
 
-Mesurer plans the evidence frame; the existing browser harness takes the real screenshot:
+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:
 
 ```js
 const plan = await window.__MESURER__.capturePlan({ scope: "selection" })
@@ -262,7 +312,7 @@ try {
 }
 ```
 
-Use screenshots for visual composition and Mesurer context for exact numeric claims.
+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
 
@@ -279,7 +329,7 @@ Those remain the three human context controls. `select()` is a programmatic agen
 ## Portable Agent Skill
 
 ```bash
-npx --yes --package=mesurer-solid@beta mesurer-skill install
+npx --yes --package=mesurer-solid mesurer-skill install
 ```
 
 The installer leaves:
@@ -291,7 +341,7 @@ The installer leaves:
     └── inject-script.js
 ```
 
-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, and fresh post-edit verification. See [`AGENT_INTEGRATION.md`](./AGENT_INTEGRATION.md).
+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
 
@@ -316,13 +366,14 @@ import {
 } from "mesurer-solid/core"
 ```
 
-Plugins can contribute tools, commands, hooks, overlays, settings, state, services, history/persistence, renderer-owned UI, and lifecycle cleanup.
+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.
 
 ## Public surface
 
 ```text
 mesurer-solid
 mesurer-solid/core
+mesurer-solid/screenshot
 mesurer-solid/inject
 mesurer-solid/inject-script
 ```

package/dist/context-plugin.d.ts

@@ -2,8 +2,9 @@ import type { MesurerPlugin } from "./core";
 import { type MesurerAnnotation, type MesurerCapturePlanV1, type MesurerContextRequest, type MesurerContextV1, type MesurerReviewV1 } from "./context";
 export declare const MESURER_CONTEXT_PLUGIN_ID = "mesurer.context";
 export declare const MESURER_CONTEXT_SERVICE_ID = "context:v1";
+export declare const MESURER_CONTEXT_SETTINGS_STATE_ID = "mesurer.context.settings";
 export type MesurerContextPluginOptions = {
-    /** Render Copy Context, Copy Selection, Add Note, and annotation UI. Defaults to true. */
+    /** Initial human-facing Context UI state. The Settings toggle can change it at runtime. Defaults to true. */
     ui?: boolean;
 };
 export type MesurerContextService = {

package/dist/core.d.ts

@@ -2,8 +2,8 @@ export type Registration = {
     readonly dispose: () => void;
 };
 export type PluginId = string;
-type PluginScalar = string | number | boolean | null;
-type PluginValue = PluginScalar | PluginValue[] | {
+export type PluginScalar = string | number | boolean | null;
+export type PluginValue = PluginScalar | PluginValue[] | {
     [key: string]: PluginValue;
 };
 export type PluginStateSnapshot = {
@@ -23,12 +23,39 @@ export type ToolContribution = {
     };
     active?: () => boolean;
     disabled?: () => boolean;
+    hidden?: () => boolean;
 };
+export type SettingsToggleContribution = {
+    type: "toggle";
+    id: string;
+    label: string;
+    description?: string;
+    value(): boolean;
+    set(value: boolean): void | Promise<void>;
+    disabled?: () => boolean;
+};
+export type SettingsControlContribution = SettingsToggleContribution;
 export type SettingsContribution = {
     id: string;
     label: string;
     order?: number;
     builtin?: string;
+    controls?: SettingsControlContribution[];
+};
+export type SettingsControlDescription = {
+    type: "toggle";
+    id: string;
+    label: string;
+    description: string | undefined;
+    value: boolean;
+    disabled: boolean;
+};
+export type SettingsDescription = {
+    id: string;
+    label: string;
+    order?: number;
+    builtin?: string;
+    controls: SettingsControlDescription[];
 };
 export type OverlayContribution = {
     id: string;
@@ -50,6 +77,7 @@ export type MesurerPluginContext = {
         register<T extends PluginValue>(definition: StateSliceDefinition<T>): Registration;
         get<T extends PluginValue>(id: string): T | undefined;
         update<T extends PluginValue>(id: string, update: (value: T) => T): void;
+        subscribe(listener: () => void): Registration;
     };
     tool: {
         register(contribution: ToolContribution): Registration;
@@ -98,7 +126,7 @@ export type MesurerPluginDescription = {
         order?: number;
         builtin?: string;
     }>;
-    settings: SettingsContribution[];
+    settings: SettingsDescription[];
     overlays: OverlayContribution[];
     state: Array<{
         id: string;
@@ -151,4 +179,3 @@ export declare function createMesurerPluginHost(): MesurerPluginHost;
 export declare function createMesurerRuntime(options?: {
     plugins?: MesurerPlugin[];
 }): Promise<MesurerPluginHost>;
-export {};

package/dist/core.js

@@ -125,7 +125,13 @@ function i() {
 					return p.has(t.id) || p.set(t.id, t.initial), r;
 				},
 				get: k.get,
-				update: k.update
+				update: k.update,
+				subscribe(e) {
+					let t = i.on("changed", (t) => {
+						(t.reason === "state" || t.reason === "history") && e();
+					});
+					return n({ dispose: t });
+				}
 			},
 			tool: { register: (t) => n(_(o, e, t)) },
 			settings: { register: (t) => n(_(s, e, t)) },
@@ -203,8 +209,18 @@ function i() {
 					requires: e.requires ?? [],
 					provides: e.provides ?? []
 				})),
-				tools: I.tools().map(({ active: e, disabled: t, icon: n, ...r }) => r),
-				settings: I.settings(),
+				tools: I.tools().map(({ active: e, disabled: t, hidden: n, icon: r, ...i }) => i),
+				settings: I.settings().map(({ controls: e = [], ...t }) => ({
+					...t,
+					controls: e.map((e) => ({
+						type: e.type,
+						id: e.id,
+						label: e.label,
+						description: e.description,
+						value: e.value(),
+						disabled: e.disabled?.() ?? !1
+					}))
+				})),
 				overlays: I.overlays(),
 				state: [...f.values()].map(({ id: e, history: t, persist: n }) => ({
 					id: e,