mesurer-solid 0.1.9-beta.0 → 0.1.9-beta.2

package/README.md

@@ -41,6 +41,8 @@ For Vite, put this in the existing browser entry such as `src/main.tsx`, `src/ma
 
 `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
@@ -62,11 +64,13 @@ 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`.
+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`. A successful native sample is copied to the clipboard using `colorPickerClickFormat`.
+
+`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.
 
-For explicit plugin composition, `mesurer-solid/plugins` also exports `select`, `xray`, `colorPicker`, `rulers`, `typography`, `guides`, `distance`, `settings`, `defaults`, and `compose`.
+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.
 
-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 API instead of requiring `pluginHost.service.get(...)`.
+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 |
 | --- | --- |
@@ -83,7 +87,7 @@ Programmatic injection reuses an existing connected instance by default. Lifecyc
 
 ## Features
 
-- Select one or many rendered HTML or SVG elements and inspect exact geometry.
+- Select one or many rendered HTML or SVG elements and inspect exact geometry. Turning Select off clears the current element and Guide selection.
 - 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.

package/dist/agent.d.ts

@@ -110,13 +110,13 @@ 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;

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/core.d.ts

@@ -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 = {
@@ -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

@@ -226,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 }) => ({
@@ -261,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

@@ -5,6 +5,9 @@ import type { MesurerPlugin, MesurerPluginDescription, MesurerPluginHost } from
 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 = {
@@ -143,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;
 };
@@ -155,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";
@@ -174,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>;
@@ -190,17 +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>;
@@ -214,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;