mesurer-solid 0.1.8 → 0.1.9-beta.1

package/AGENT_INTEGRATION.md

@@ -10,7 +10,6 @@ The normal agent workflow requires no Mesurer MCP server, localhost daemon, Send
 npx --yes --package=mesurer-solid mesurer-skill install
 ```
 
-Use `mesurer-solid@beta` only when intentionally validating a prerelease.
 
 The installer writes a self-contained skill and injection artifact:
 
@@ -124,13 +123,15 @@ Use the high-level Context and saved-intent methods for normal UI work. The lowe
 | `distance(a, b)` | Measure two selector targets. |
 | `viewport()` | Read viewport/document dimensions, scrolling, device pixel ratio, and overflow. |
 | `feedback(selectors?)` | Read viewport data, inspected elements, plugin description, and plugin state together. |
-| `command(id, args?)` | Execute a registered Mesurer command. |
+| `command(id, args?)` | Execute a registered Mesurer command and return its JSON-safe result when present. |
 | `state()` | Read plugin state. |
 | `stable(frames?)` | Wait for fonts and rendering before measuring again. |
 | `textEdits()` / `textEdit(id)` | Read saved direct-text and typography intent. |
 
 Context adds `capabilities()`, `context()`, `contextText()`, `select()`, `annotations()`, `review()`, `capturePlan()`, `prepareCapture()`, and `finishCapture()`.
 
+These inspection methods accept general DOM elements, including SVG. `select()` and point inspection can return SVG targets, and Context preserves their selector, tag, and geometry. Arrange and direct text editing remain HTML-only mutation paths.
+
 Arrange adds `arrangements()`, `arrange()`, `showArrange()`, `arrangeCapturePlan()`, and `reviewArrange()`.
 
 Use `capabilities().capabilities` before calling optional Context, Arrange, or text-edit paths. The complete public list is in [Capabilities](../../docs/CAPABILITIES.md).
@@ -148,7 +149,7 @@ const context = await window.__MESURER__.select([
 
 Each selector must resolve to exactly one target. Missing or ambiguous selectors throw rather than binding to a guess.
 
-For multi-selection, inspect every selected target and the relevant pair relationships. Prefer `selection.visualContext.distances`; use `distance(a, b)` when a needed pair has no existing evidence.
+For multi-selection, inspect every selected target and the relevant pair relationships. Prefer `selection.visualContext.distances`; use `distance(a, b)` when a needed pair has no existing evidence. Box, guide, container, and diagonal semantics are defined in [Measurements and distance geometry](../../docs/MEASUREMENTS.md).
 
 ## Arrange intent
 
@@ -241,7 +242,7 @@ try {
 }
 ```
 
-The optional human `screenshot()` plugin from `mesurer-solid/plugins` is a separate camera workflow. It is not an agent delivery capability. Preserve an existing human preview unless the task is specifically about Screenshot behavior.
+The optional human `screenshot()` plugin from `mesurer-solid/plugins` is a separate camera workflow. It may use application-native, Chromium extension, or browser display capture internally, but none of those paths changes the agent contract above. Do not add or configure a host capture path only to collect coding-agent evidence. Preserve an existing human preview unless the task is specifically about Screenshot behavior.
 
 ## Optional human-to-Codex delivery
 
@@ -253,7 +254,7 @@ Delivery uses Codex's native durable queue. Mesurer queues once and keeps the qu
 
 The browser plugin connects lazily on the first Queue to Codex or thread-picker action. Page affinity and an explicit destination override persist per tab. If several registered threads are visible and the page has no saved destination, the user must choose one.
 
-The typed `codex:v1` service exposes `health()`, `listThreads()`, `useThread(thread)`, `delivery(deliveryId)`, and `send({ thread })`. Queue submission is single-flight. A matched completed turn may remove only the annotation ids sent with that delivery; interrupted, failed, ambiguous, or unreadable work keeps them.
+The typed `codex:v1` service exposes `health()`, `listThreads()`, `useThread(thread)`, `delivery(deliveryId)`, and canonical `queue(request?)`. `send(request?)` remains a compatibility alias. The generic plugin command is `codex.queue`; `codex.send` remains its compatibility alias. Queue submission is single-flight. A matched completed turn may remove only the annotation ids sent with that delivery; interrupted, failed, ambiguous, or unreadable work keeps them.
 
 Mesurer does not create new Codex threads. Create or open the thread in Codex and let `SessionStart` register it. Turn completion is transport lifecycle, not proof that the requested UI result is correct.
 

package/README.md

@@ -20,7 +20,6 @@ or:
 npm install -D mesurer-solid
 ```
 
-Use `mesurer-solid@beta` only when intentionally testing a prerelease.
 
 ## Usage
 
@@ -38,10 +37,12 @@ if (import.meta.env.DEV) {
 }
 ```
 
-For Vite, put this in the existing browser entry such as `src/main.tsx`, `src/main.ts`, or `src/index.tsx`. In Electron, use the renderer entry. In SSR applications, mount from a client-only module or lifecycle.
+For Vite, put this in the existing browser entry such as `src/main.tsx`, `src/main.ts`, or `src/index.tsx`. In Electron, use the renderer entry and keep privileged Electron work in preload/main. If preload exposes `window.__MESURER_HOST__.captureScreenshot`, Screenshot uses native capture automatically. Renderer configuration remains `screenshot()`; there is no Electron-specific Screenshot factory or provider option. In SSR applications, mount from a client-only module or lifecycle.
 
 `src/dev/mesurer.ts` is an optional organization pattern, not a required filename or directory. Do not mount Mesurer from `vite.config.ts`, server/API code, Node-only scripts, an Electron main process, or a module that also executes during SSR.
 
+The returned handle owns the mount. Await `mesurer.ready` when startup completion, initial rendered stability, or direct host access matters, call `mesurer.dispose()` for explicit cleanup, or pass `signal` when an existing lifecycle should own disposal.
+
 Full placement examples: [Getting started](https://github.com/jhomra21/mesurer-solid/blob/main/docs/GETTING_STARTED.md).
 
 ## First-party plugins
@@ -50,13 +51,14 @@ All public first-party plugin factories are exported from `mesurer-solid/plugins
 
 ```ts
 import { mountMesurer } from "mesurer-solid"
-import { arrange, context, screenshot } from "mesurer-solid/plugins"
+import { arrange, context, layoutGuides, screenshot } from "mesurer-solid/plugins"
 
 const mesurer = mountMesurer({
   agent: true,
   plugins: [
     context(),
     arrange(),
+    layoutGuides(),
     screenshot(),
   ],
 })
@@ -64,7 +66,11 @@ const mesurer = mountMesurer({
 
 The base inspector includes Select, X-ray, Rulers, Typography, Guides, Distance, Settings, plugin hosting, direct text editing, and the low-level inspection API. Native Color Picker is available only when the host exposes an operational `EyeDropper`.
 
-For explicit plugin composition, `mesurer-solid/plugins` also exports `select`, `xray`, `colorPicker`, `rulers`, `typography`, `guides`, `distance`, `settings`, `defaults`, and `compose`.
+`mesurer-solid/plugins` also exports the built-in factories for lower-level composition. Normal mounts already include the built-ins. Use `excludeBuiltins` with names such as `"xray"`, `"typography"`, and `"colorPicker"` when a mount should omit one.
+
+Resolve plugin-owned capabilities with `await mesurer.service<T>(serviceId)`. The helper waits for configured plugins to finish loading and keeps normal consumers on the mounted interface instead of requiring `pluginHost.service.get(...)`. Falsy registered values are returned unchanged.
+
+Advanced integrations may supply their own `pluginHost`. That host remains caller-owned; disposing or aborting the Mesurer mount does not dispose it. Use `onPluginHost` only when code needs the host before startup settles.
 
 | Entry | Purpose |
 | --- | --- |
@@ -77,27 +83,47 @@ For explicit plugin composition, `mesurer-solid/plugins` also exports `select`,
 | `mesurer-codex` | Run the optional loopback Codex queue companion |
 | `mesurer-codex-connect` | Start or reuse the matching Codex companion and register the current Codex session |
 
+Programmatic injection reuses an existing connected instance by default. Lifecycle-owning integrations can set `recoverDisconnected: true` in `MesurerInjectConfig` to remount Mesurer when page DOM replacement disconnects its host. The option defaults to `false`, so ordinary one-shot injection does not silently reappear after disposal.
+
 ## Features
 
-- Select one or many rendered elements and inspect exact geometry.
+- Select one or many rendered HTML or SVG elements and inspect exact geometry.
 - Measure distance and pairwise multi-selection spacing.
 - Use X-ray, guides, rulers, and persisted settings.
+- Add page-scoped columns, rows, or pixel grids with the optional `layoutGuides()` plugin. Guide edits participate in plugin undo/redo, and Context includes the current page's saved guides with their visibility state.
 - Inspect Typography and preview reversible direct copy/style changes.
 - Arrange selected UI into a Desired position without changing source.
-- Capture visible-tab regions through the optional Screenshot plugin.
+- Capture page regions through the optional Screenshot plugin. It selects native host capture, the Chromium extension adapter, or browser display capture internally.
 - Read selection, measurements, guides, annotations, layout, styles, and saved human intent through Context and agent APIs.
 - Keep saved annotations across same-tab reloads and conservatively rebind them to their original DOM targets; markers, cards, and ownership evidence stay attached through scrolling, repeated-note markers stay local, Add Note remains available while a note is open, and cards/composers occlude Select hover and selection chrome.
 - Extend the runtime with tools, settings, overlays, commands, hooks, state, and services.
 - Compact the toolbar to active controls without changing tool state or order.
+- Choose System, Light, or Dark appearance while keeping the same theme across isolated and document-backed Mesurer UI.
 
 Arrange is not a toolbar mode. It can be activated before a selection exists and enables Select automatically. Turning Arrange off leaves Select active; turning Select off exits Arrange.
 
+Toolbar dragging starts after the pointer crosses the drag threshold. Dragging from Settings, Guide, or plugin triggers closes the open menu or panel. Pointer activity inside menus, dialogs, form controls, editable regions, and sliders does not drag the toolbar.
+
+Select and agent point inspection use the same rendered hit-test path. They can target SVG and visible `pointer-events:none` descendants instead of collapsing those descendants to an interactive ancestor. Open shadow roots are traversed; closed shadow roots remain browser-owned boundaries. Context and annotations accept the same SVG targets. Arrange and direct text editing only mutate HTML elements.
+
+Persisted workspace evidence is page-scoped by route, including sorted query parameters. In-tab navigation swaps the current page workspace without carrying page-owned guides or selection state to another route. Toolbar placement remains tab-session UI and survives those route changes and reloads.
+
 Direct text editing respects native editing boundaries. Descendants of an editable ancestor remain native, while a nested `contenteditable="false"` boundary ends inherited editability and can become a Mesurer target when the normal direct-text rules pass. Mixed inline copy can target the exact direct text run before or after an inline child without flattening or recreating that child, and the host element keeps its native DOM APIs throughout the interaction.
 
 While direct text editing is active, Mesurer keeps one visible edit ring, keeps the selected dimensions pill and Typography separated by the same `2px` rendered gap when the card is below the source, and keeps Typography stationary during ordinary pointer movement. The selection-adjacent Add Note button is suppressed only for the active edit and returns when the editor closes; saved annotation markers and panels remain available.
 
 Mesurer previews text, styles, and Arrange transforms only while it still owns the value it applied. Host-authored changes take ownership and are preserved through undo/redo, Live review, cleanup, and disposal.
 
+## Appearance
+
+The default appearance is `"system"`. Users can change it under **Settings > General > Appearance**, or applications can choose the initial mode:
+
+```ts
+mountMesurer({ theme: "light" })
+```
+
+The setting accepts `"system"`, `"light"`, or `"dark"` and persists with the other Mesurer settings. System mode follows `prefers-color-scheme`.
+
 ## Shortcuts
 
 Global shortcuts are enabled by default. Turn them off from **Settings > General > Shortcuts** or pass `shortcutsEnabled: false` to `mountMesurer()`. Toolbar controls, editor-local keys, and Escape/cancel behavior remain available.
@@ -111,6 +137,7 @@ Global shortcuts are enabled by default. Turn them off from **Settings > General
 | `R` | Rulers |
 | `A` | Typography |
 | `G` | Guides |
+| `L` | Layout Guides when the plugin is enabled |
 | `H` / `V` | Horizontal / vertical guide orientation |
 | `Alt` / `Option` | Distance overlay |
 | `Cmd/Ctrl + ,` | Settings |
@@ -170,8 +197,10 @@ See [Queue Context feedback to Codex](https://github.com/jhomra21/mesurer-solid/
 - [Capabilities](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CAPABILITIES.md)
 - [Getting started](https://github.com/jhomra21/mesurer-solid/blob/main/docs/GETTING_STARTED.md)
 - [Direct text editing and Typography](https://github.com/jhomra21/mesurer-solid/blob/main/docs/TEXT_EDITING.md)
-- [Arrange](https://github.com/jhomra21/mesurer-solid/blob/main/docs/ARRANGE.md)
+- [Arrange](https://github.com/jhomra21/mesurer-solid/blob/main/docs/ARRANGE.md) and [Layout Guides](https://github.com/jhomra21/mesurer-solid/blob/main/docs/LAYOUT_GUIDES.md)
+- [Measurements and distance geometry](https://github.com/jhomra21/mesurer-solid/blob/main/docs/MEASUREMENTS.md)
 - [Screenshots](https://github.com/jhomra21/mesurer-solid/blob/main/docs/SCREENSHOTS.md)
+- [Electron renderer example](https://github.com/jhomra21/mesurer-solid/blob/main/examples/electron-renderer/README.md)
 - [Context workflow](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CONTEXT_WORKFLOW.md)
 - [Queue Context feedback to Codex](https://github.com/jhomra21/mesurer-solid/blob/main/docs/CODEX.md)
 - [Browser and agent integration](https://github.com/jhomra21/mesurer-solid/blob/main/docs/BROWSER_HARNESS.md)

package/dist/agent.d.ts

@@ -110,20 +110,20 @@ export type AgentViewportSnapshot = {
 export type AgentFeedbackSnapshot = {
     viewport: AgentViewportSnapshot;
     elements: AgentElementInspection[];
-    plugins: MesurerPluginDescription | undefined;
+    plugins: MesurerPluginDescription;
     pluginState: PluginStateSnapshot;
 };
 type AgentCommandArgs = Parameters<MesurerPluginHost["command"]["execute"]>[1];
 export type MesurerAgentHarness = {
     ready(): Promise<void>;
-    describe(): Promise<MesurerPluginDescription | undefined>;
+    describe(): Promise<MesurerPluginDescription>;
     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?: AgentCommandArgs): Promise<void>;
+    command(id: string, args?: AgentCommandArgs): ReturnType<MesurerPluginHost["command"]["execute"]>;
     state(): Promise<PluginStateSnapshot>;
     textEdits(): Promise<MesurerTextEditIntent[]>;
     textEdit(id: string): Promise<MesurerTextEditIntent>;

package/dist/codex-plugin.d.ts

@@ -11,14 +11,16 @@ export type MesurerCodexPluginOptions = {
     /** Remove annotations included in a delivery after Codex reports that turn finished. Defaults to true. */
     clearCompletedAnnotations?: boolean;
 };
-export type MesurerCodexSendRequest = {
-    /** Optional instruction for this send. */
+export type MesurerCodexQueueRequest = {
+    /** Optional instruction for this queue operation. */
     instruction?: string;
-    /** Send only these saved annotation ids. When omitted, all saved annotations are sent. */
+    /** Queue only these saved annotation ids. When omitted, all saved annotations are queued. */
     annotationIds?: string[];
-    /** Send to a particular bridge-visible Codex thread for this request. */
+    /** Queue to a particular bridge-visible Codex thread for this request. */
     thread?: string;
 };
+/** @deprecated Use `MesurerCodexQueueRequest`. */
+export type MesurerCodexSendRequest = MesurerCodexQueueRequest;
 export type MesurerCodexDeliveryStatus = "queued" | "working" | "completed" | "interrupted";
 export type MesurerCodexDispatchStatus = "persisting" | "persisted" | "resumed" | "already-loaded" | "unsupported" | "wake-failed" | "untracked" | "desktop-local" | "waiting-active" | "desktop-sent" | "desktop-opened" | "desktop-send-uncertain" | "desktop-wait-failed";
 export type MesurerCodexDelivery = {
@@ -35,7 +37,7 @@ export type MesurerCodexDelivery = {
     createdAt: number;
     updatedAt: number;
 };
-export type MesurerCodexSendResult = {
+export type MesurerCodexQueueResult = {
     thread: string;
     output: string;
     /** Mesurer currently delivers feedback as a queued Codex follow-up, never as an in-flight steer. */
@@ -52,6 +54,8 @@ export type MesurerCodexSendResult = {
     /** Exact saved annotations included in this queued request. */
     annotationIds: string[];
 };
+/** @deprecated Use `MesurerCodexQueueResult`. */
+export type MesurerCodexSendResult = MesurerCodexQueueResult;
 export type MesurerCodexHealth = {
     /** Current bridge default target. Null when the bridge has not been bound yet. */
     thread: string | null;
@@ -91,6 +95,8 @@ export type MesurerCodexService = {
      * Queue Context for the page-pinned/default target or one explicit bridge-visible thread.
      * This does not steer or interrupt an in-flight Codex turn.
      */
-    send(request?: MesurerCodexSendRequest): Promise<MesurerCodexSendResult>;
+    queue(request?: MesurerCodexQueueRequest): Promise<MesurerCodexQueueResult>;
+    /** @deprecated Use `queue()`; Mesurer delivery is durable queueing, not in-flight send/steer. */
+    send(request?: MesurerCodexQueueRequest): Promise<MesurerCodexQueueResult>;
 };
 export declare function codex(options?: MesurerCodexPluginOptions): MesurerPlugin;

package/dist/context-plugin.d.ts

@@ -11,7 +11,7 @@ export type MesurerContextService = {
     context(request?: MesurerContextRequest): Promise<MesurerContextV1>;
     contextText(request?: MesurerContextRequest): Promise<string>;
     copyContext(request?: MesurerContextRequest): Promise<void>;
-    select(selectors: string | string[]): Promise<MesurerContextV1>;
+    select(selectors: string | readonly string[]): Promise<MesurerContextV1>;
     annotations(): Promise<MesurerAnnotation[]>;
     /** Remove one saved annotation after a trusted workflow has completed it. */
     removeAnnotation(annotationId: string): Promise<void>;

package/dist/context.d.ts

@@ -147,6 +147,18 @@ export type MesurerContextGuide = {
     orientation: "vertical" | "horizontal";
     position: number;
 };
+export type MesurerContextLayoutGuide = {
+    id: string;
+    kind: "columns" | "rows" | "grid";
+    visible: boolean;
+    color: string;
+    opacity: number;
+    count: number;
+    size: number;
+    gutter: number;
+    offset: number;
+    align: "stretch" | "min" | "center" | "max";
+};
 export type MesurerContextMeasurement = {
     id: string;
     rect: MesurerContextRect;
@@ -209,6 +221,7 @@ export type MesurerContextV1 = {
     targets: MesurerContextTarget[];
     visualContext: {
         guides: MesurerContextGuide[];
+        layoutGuides: MesurerContextLayoutGuide[];
         measurements: MesurerContextMeasurement[];
         distances: MesurerContextDistance[];
     };
@@ -266,7 +279,7 @@ export type MesurerWorkspaceContextSource = {
             deltaX: number;
             deltaY: number;
             snapped?: boolean;
-            elementRef?: HTMLElement | null;
+            elementRef?: Element | null;
         }>;
         activeMeasurement: {
             id: string;
@@ -274,14 +287,14 @@ export type MesurerWorkspaceContextSource = {
             deltaX: number;
             deltaY: number;
             snapped?: boolean;
-            elementRef?: HTMLElement | null;
+            elementRef?: Element | null;
         } | null;
         heldDistances: Array<{
             id: string;
             rectA: MesurerContextRect;
             rectB: MesurerContextRect;
-            elementRefA?: HTMLElement | null;
-            elementRefB?: HTMLElement | null;
+            elementRefA?: Element | null;
+            elementRefB?: Element | null;
             horizontal: {
                 x1: number;
                 x2: number;
@@ -302,14 +315,14 @@ export type MesurerWorkspaceContextSource = {
         }>;
     } | null;
     currentSelection(): {
-        elements: HTMLElement[];
+        elements: Element[];
         region: MesurerContextRect | null;
     };
     annotations(): MesurerAnnotation[];
     annotation(id: string): (MesurerAnnotation & {
         resolvedTargets: Array<{
             target: MesurerAnnotationTarget;
-            element: HTMLElement | null;
+            element: Element | null;
         }>;
     }) | null;
     annotationRect(id: string): MesurerContextRect | null;
@@ -319,6 +332,7 @@ export declare function captureMesurerContext(options: {
     ownerDocument: Document;
     ownerWindow: Window;
     request?: MesurerContextRequest;
+    layoutGuides?: MesurerContextLayoutGuide[];
 }): MesurerContextV1;
 export declare function formatMesurerContext(context: MesurerContextV1): string;
 export declare function createMesurerCapturePlan(context: MesurerContextV1): MesurerCapturePlanV1;
@@ -327,5 +341,6 @@ export declare function reviewMesurerAnnotation(options: {
     ownerDocument: Document;
     ownerWindow: Window;
     annotationId: string;
+    layoutGuides?: MesurerContextLayoutGuide[];
 }): MesurerReviewV1;
 export declare function copyTextToClipboard(ownerDocument: Document, ownerWindow: Window, text: string): Promise<void>;

package/dist/core.d.ts

@@ -77,7 +77,7 @@ export type OverlayContribution = {
 };
 export type CommandHandler = (args: PluginValue | undefined, context: {
     source?: PluginValue;
-}) => void | Promise<void>;
+}) => void | PluginValue | Promise<void | PluginValue>;
 export type HookHandler = (event: PluginValue) => void | Promise<void>;
 export type StateSliceDefinition<T extends PluginValue = PluginValue> = {
     id: string;
@@ -103,7 +103,7 @@ export type MesurerPluginContext = {
     };
     command: {
         register(id: string, handler: CommandHandler): Registration;
-        execute(id: string, args?: PluginValue, source?: PluginValue): Promise<void>;
+        execute(id: string, args?: PluginValue, source?: PluginValue): Promise<PluginValue | undefined>;
     };
     hook: {
         on(name: string, handler: HookHandler): Registration;
@@ -120,8 +120,8 @@ export type MesurerPluginContext = {
 export type MesurerPlugin = {
     id: PluginId;
     version?: string;
-    requires?: string[];
-    provides?: string[];
+    requires?: readonly string[];
+    provides?: readonly string[];
     setup(context: MesurerPluginContext): void | Promise<void>;
 };
 export type MesurerPluginDescription = {
@@ -175,7 +175,7 @@ export type MesurerPluginHost = {
         get<T>(id: string): T | undefined;
     };
     command: {
-        execute(id: string, args?: PluginValue, source?: PluginValue): Promise<void>;
+        execute(id: string, args?: PluginValue, source?: PluginValue): Promise<PluginValue | undefined>;
     };
     hook: {
         emit(name: string, event: PluginValue): Promise<void>;
@@ -190,6 +190,7 @@ export type MesurerPluginHost = {
 };
 export declare const defineMesurerPlugin: <T extends MesurerPlugin>(plugin: T) => T;
 export declare function createMesurerPluginHost(): MesurerPluginHost;
-export declare function createMesurerRuntime(options?: {
-    plugins?: MesurerPlugin[];
-}): Promise<MesurerPluginHost>;
+export type MesurerRuntimeOptions = {
+    plugins?: readonly MesurerPlugin[];
+};
+export declare function createMesurerRuntime(options?: MesurerRuntimeOptions): Promise<MesurerPluginHost>;

package/dist/core.js

@@ -85,8 +85,10 @@ function i() {
 		if (!o) throw Error(`Unknown Mesurer command: ${e}`);
 		let s = t === 0, c = s ? x("history") : null;
 		t += 1;
+		let l;
 		try {
-			await o.handler(n, { source: a }), await i.emit("command", {
+			let t = await o.handler(n, { source: a });
+			t !== void 0 && (l = t), await i.emit("command", {
 				id: e,
 				args: n
 			});
@@ -97,6 +99,7 @@ function i() {
 			let e = x("history");
 			C(c, e) || (h.push(c), h.length > r && h.shift(), g.length = 0);
 		}
+		return l;
 	}, E = () => {
 		let e = h.pop();
 		return e ? (g.push(x("history")), g.length > r && g.shift(), S(e, "history"), _(void 0, "history"), !0) : !1;
@@ -223,8 +226,8 @@ function i() {
 				plugins: [...a.values()].map(({ plugin: e }) => ({
 					id: e.id,
 					version: e.version,
-					requires: e.requires ?? [],
-					provides: e.provides ?? []
+					requires: [...e.requires ?? []],
+					provides: [...e.provides ?? []]
 				})),
 				tools: z.tools().map(({ active: e, disabled: t, hidden: n, icon: r, menu: i, ...a }) => a),
 				settings: z.settings().map(({ controls: e = [], ...t }) => ({
@@ -258,15 +261,24 @@ function i() {
 	return z;
 }
 //#endregion
+//#region ../mesurer-core/dist/runtime.js
+async function a(e = {}) {
+	let t = i();
+	try {
+		for (let n of e.plugins ?? []) await t.load(n);
+		return t;
+	} catch (e) {
+		throw t.dispose(), e;
+	}
+}
+//#endregion
 //#region src/core.ts
-var a = (e) => e;
-function o() {
+var o = (e) => e;
+function s() {
 	return i();
 }
-async function s(e = {}) {
-	let t = o();
-	for (let n of e.plugins ?? []) await t.load(n);
-	return t;
+async function c(e = {}) {
+	return a(e);
 }
 //#endregion
-export { o as createMesurerPluginHost, s as createMesurerRuntime, a as defineMesurerPlugin };
+export { s as createMesurerPluginHost, c as createMesurerRuntime, o as defineMesurerPlugin };

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 import { type MesurerAgentHarness, type MesurerTextEditIntent } from "./agent";
-import type { ArrangeCapturePlan, ArrangeIntent, ArrangePresentation, ArrangeReview } from "./arrange";
+import { type ArrangeCapturePlan, type ArrangeIntent, type ArrangePresentation, type ArrangeReview } from "./arrange";
 import type { MesurerAnnotation, MesurerCapturePlanV1, MesurerContextRequest, MesurerContextV1, MesurerReviewV1 } from "./context";
 import type { MesurerPlugin, MesurerPluginDescription, MesurerPluginHost } from "./core";
 import { type MesurerHostLayerMode } from "./host-layer";
 export type ColorPickerFormat = "hex" | "rgb" | "hsl" | "oklch";
+export type MesurerTheme = "system" | "light" | "dark";
+/** Public built-in names, aligned with the factories exported by `mesurer-solid/plugins`. */
+export type MesurerBuiltin = "select" | "xray" | "colorPicker" | "rulers" | "typography" | "guides" | "distance" | "settings";
+/** @deprecated Internal compatibility ids used by the older `excludePlugins` option. */
 export type MesurerBuiltinPluginId = "select" | "xray" | "color-picker" | "rulers" | "text-inspector" | "guides" | "distance" | "settings";
 export type LinePattern = "solid" | "dashed" | "dotted";
 export type LineStyle = {
@@ -80,6 +84,7 @@ export type MesurerStoredSettings = {
     multiMeasureEnabled?: boolean;
     persistOnReload?: boolean;
     shortcutsEnabled?: boolean;
+    theme?: MesurerTheme;
     guideStyle?: Partial<GuideStyle>;
     selectionSpacingStyle?: Partial<SelectionSpacingStyle>;
     rulerSettings?: Partial<RulerSettings>;
@@ -106,6 +111,7 @@ export type MesurerPersistence = {
     saveWorkspace(workspace: MesurerStoredWorkspace): void;
     clearWorkspace(): void;
     clearSettings(): void;
+    setPageKey?(pageKey: string): void;
     subscribe?: (listener: (snapshot: MesurerPersistenceSnapshot | null, source?: {
         settings?: boolean;
         workspace?: boolean;
@@ -122,6 +128,7 @@ export type MesurerOptions = {
     hoverHighlightEnabled?: boolean;
     persistOnReload?: boolean;
     shortcutsEnabled?: boolean;
+    theme?: MesurerTheme;
     persistKey?: string;
     persistence?: MesurerPersistence;
     onPersistenceError?: (cause: unknown) => void;
@@ -139,10 +146,19 @@ export type MesurerOptions = {
      * Omitted first-party plugins remain toggleable in Settings from the same canonical
      * registry; callers never maintain a separate availability or Settings list.
      */
-    plugins?: MesurerPlugin[];
-    excludePlugins?: MesurerBuiltinPluginId[];
+    plugins?: readonly MesurerPlugin[];
+    /** Built-in tools to omit from this mount. Names match the public plugin factories. */
+    excludeBuiltins?: readonly MesurerBuiltin[];
+    /** @deprecated Use `excludeBuiltins`. This compatibility option uses internal built-in ids. */
+    excludePlugins?: readonly MesurerBuiltinPluginId[];
+    /**
+     * Advanced: supply a plugin host owned outside this mount.
+     * The caller remains responsible for disposing the supplied host.
+     */
     pluginHost?: MesurerPluginHost;
+    /** Advanced: receive the live host before configured plugin setup settles. */
     onPluginHost?: (host: MesurerPluginHost) => void;
+    /** @deprecated Await `mounted.ready` instead. */
     onPluginsReady?: (host: MesurerPluginHost) => void;
     onPluginError?: (cause: unknown, pluginId: string) => void;
 };
@@ -151,7 +167,16 @@ export type MountMesurerOptions = MesurerOptions & {
     isolate?: boolean;
     shadowMode?: ShadowRootMode;
     topLayer?: boolean;
+    /**
+     * Expose the browser agent API on the owning Window. The mounted handle always
+     * exposes `agent`; this option controls only the global bridge.
+     */
     agent?: boolean | AgentBridgeOptions;
+    /**
+     * Dispose this mount when the signal aborts.
+     * A caller-supplied pluginHost keeps its separate lifecycle.
+     */
+    signal?: AbortSignal;
 };
 export type MesurerAgentCapabilities = {
     protocol: "mesurer.agent/v1";
@@ -170,7 +195,7 @@ export type MesurerContextHarness = {
     capabilities(): MesurerAgentCapabilities;
     context(request?: MesurerContextRequest): Promise<MesurerContextV1>;
     contextText(request?: MesurerContextRequest): Promise<string>;
-    select(selectors: string | string[]): Promise<MesurerContextV1>;
+    select(selectors: string | readonly string[]): Promise<MesurerContextV1>;
     annotations(): Promise<MesurerAnnotation[]>;
     review(annotationId?: string): Promise<MesurerReviewV1 | MesurerReviewV1[]>;
     capturePlan(request?: MesurerContextRequest): Promise<MesurerCapturePlanV1>;
@@ -186,16 +211,19 @@ export type MesurerArrangeHarness = {
 };
 export type MesurerBrowserAgent = MesurerAgentHarness & MesurerContextHarness & MesurerArrangeHarness;
 export type MountedMesurer = {
-    element: HTMLDivElement;
-    root: HTMLDivElement | ShadowRoot;
+    readonly element: HTMLDivElement;
+    readonly root: HTMLDivElement | ShadowRoot;
     readonly hostLayer: MesurerHostLayerMode;
+    /** @deprecated Await `ready` when direct plugin-host access is required. */
     readonly pluginHost: MesurerPluginHost | undefined;
-    readonly ready: Promise<void>;
+    /** Resolves to the live plugin host after startup and initial rendered state settle. */
+    readonly ready: Promise<MesurerPluginHost>;
     readonly agent: MesurerBrowserAgent;
+    service<T>(id: string): Promise<T>;
     context(request?: MesurerContextRequest): Promise<MesurerContextV1>;
     contextText(request?: MesurerContextRequest): Promise<string>;
     copyContext(request?: MesurerContextRequest): Promise<void>;
-    select(selectors: string | string[]): Promise<MesurerContextV1>;
+    select(selectors: string | readonly string[]): Promise<MesurerContextV1>;
     annotations(): Promise<MesurerAnnotation[]>;
     review(annotationId?: string): Promise<MesurerReviewV1 | MesurerReviewV1[]>;
     capturePlan(request?: MesurerContextRequest): Promise<MesurerCapturePlanV1>;
@@ -209,7 +237,7 @@ export type MountedMesurer = {
     textEdits(): Promise<MesurerTextEditIntent[]>;
     textEdit(id: string): Promise<MesurerTextEditIntent>;
     bringToFront(): void;
-    describe(): MesurerPluginDescription | undefined;
+    describe(): Promise<MesurerPluginDescription>;
     dispose(): void;
 };
 export declare function mountMesurer(options?: MountMesurerOptions): MountedMesurer;
@@ -224,7 +252,7 @@ export { MESURER_VERSION } from "./version";
 export type { AgentDistance, AgentEdges, AgentElementInspection, AgentFeedbackSnapshot, AgentRect, AgentViewportSnapshot, CreateMesurerAgentHarnessOptions, MesurerAgentHarness, MesurerTextEditIntent, MesurerTextEditService, MesurerTextStyleChange, MesurerTextStyleProperty, } from "./agent";
 export type { ArrangeCapturePlan, ArrangeIntent, ArrangeOffset, ArrangePresentation, ArrangeRect, ArrangeReview, ArrangeReviewTarget, ArrangeTarget, MesurerArrangeService, } from "./arrange";
 export { captureMesurerContext, copyTextToClipboard, createMesurerCapturePlan, formatMesurerContext, reviewMesurerAnnotation, } from "./context";
-export type { MesurerAnnotation, MesurerAnnotationBaseline, MesurerAnnotationTarget, MesurerCapturePlanV1, MesurerContextDistance, MesurerContextEdges, MesurerContextGuide, MesurerContextMeasurement, MesurerContextRect, MesurerContextRequest, MesurerContextTarget, MesurerContextV1, MesurerElementFingerprint, MesurerElementInspection, MesurerReviewChange, MesurerReviewMetricChange, MesurerReviewPresenceChange, MesurerReviewV1, } from "./context";
+export type { MesurerAnnotation, MesurerAnnotationBaseline, MesurerAnnotationTarget, MesurerCapturePlanV1, MesurerContextDistance, MesurerContextEdges, MesurerContextGuide, MesurerContextLayoutGuide, MesurerContextMeasurement, MesurerContextRect, MesurerContextRequest, MesurerContextTarget, MesurerContextV1, MesurerElementFingerprint, MesurerElementInspection, MesurerReviewChange, MesurerReviewMetricChange, MesurerReviewPresenceChange, MesurerReviewV1, } from "./context";
 export { createMesurerPluginHost, createMesurerRuntime, defineMesurerPlugin } from "./core";
 export type { CommandHandler as MesurerCommandHandler, MesurerPlugin, MesurerPluginContext, MesurerPluginDescription, MesurerPluginHost, OverlayContribution, Registration as MesurerRegistration, SettingsContribution, StateSliceDefinition, ToolContribution, } from "./core";
 export type { MesurerHostLayerMode } from "./host-layer";