mesurer-solid 0.2.1 → 0.2.2-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mesurer-solid",
-  "version": "0.2.1",
+  "version": "0.2.2-beta.0",
   "description": "Framework-agnostic UI measurement and inspection tools for browser apps and coding agents.",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,9 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "mesurer-skill": "scripts/install-skill.mjs"
+    "mesurer-skill": "scripts/install-skill.mjs",
+    "mesurer-codex": "scripts/codex-bridge.mjs",
+    "mesurer-codex-connect": "scripts/codex-connect.mjs"
   },
   "exports": {
     ".": {
@@ -58,7 +60,11 @@
     "dist",
     "skills",
     "plugins/codex",
+    "codex",
     "scripts/install-skill.mjs",
+    "scripts/codex-bridge.mjs",
+    "scripts/codex-connect.mjs",
+    "scripts/codex-lifecycle.mjs",
     "README.md",
     "AGENT_INTEGRATION.md",
     "LICENSE",

package/plugins/codex/bridge.d.ts

@@ -17,6 +17,7 @@ export type CodexBridgeRequest = {
   message?: string;
   deliveryId?: string;
   queuedSubmissionId?: string;
+  clientUserMessageId?: string;
 };
 
 export type CodexBridgeOptions = {
@@ -57,6 +58,7 @@ export type CodexBridgeResponse = {
   status?: "queued" | "working" | "completed" | "interrupted";
   turnId?: string | null;
   queuedSubmissionId?: string | null;
+  clientUserMessageId?: string | null;
   dispatch?: "persisted" | "desktop-opened" | "desktop-wake-failed" | null;
   dispatchError?: string | null;
   createdAt?: number;

package/plugins/codex/bridge.mjs

@@ -19,8 +19,6 @@ const MAX_DISCOVERED_THREADS = 10;
 
 const TURN_HISTORY_LIMIT = 100;
 
-const DELIVERY_TTL_MS = 24 * 60 * 60_000;
-
 const TERMINAL_DELIVERY_TTL_MS = 10 * 60_000;
 
 const DELIVERY_TURN_START_SKEW_MS = 5_000;
@@ -678,6 +676,7 @@ const publicDelivery = (delivery) => ({
   status: delivery.status,
   turnId: delivery.turnId,
   queuedSubmissionId: delivery.queuedSubmissionId,
+  clientUserMessageId: delivery.clientUserMessageId,
   dispatch: delivery.dispatch,
   dispatchError: delivery.dispatchError,
   createdAt: delivery.createdAt,
@@ -692,6 +691,7 @@ const persistedDelivery = (delivery) => ({
   status: delivery.status,
   turnId: delivery.turnId,
   queuedSubmissionId: delivery.queuedSubmissionId,
+  clientUserMessageId: delivery.clientUserMessageId,
   transport: delivery.transport,
   dispatch: delivery.dispatch,
   dispatchError: delivery.dispatchError,
@@ -699,21 +699,28 @@ const persistedDelivery = (delivery) => ({
   updatedAt: delivery.updatedAt,
 });
 
+const deliveryIsTerminal = (delivery) =>
+  delivery.status === "completed" || delivery.status === "interrupted";
+
 const pruneDeliveries = () => {
   const now = Date.now();
 
   for (const [id, delivery] of deliveries) {
-    const terminal = delivery.status === "completed" || delivery.status === "interrupted";
-    const ttl = terminal ? TERMINAL_DELIVERY_TTL_MS : DELIVERY_TTL_MS;
+    if (!deliveryIsTerminal(delivery)) continue;
 
-    if (now - delivery.updatedAt > ttl) deliveries.delete(id);
+    if (now - delivery.updatedAt > TERMINAL_DELIVERY_TTL_MS) {
+      deliveries.delete(id);
+    }
   }
 
   if (deliveries.size <= MAX_DELIVERIES) return;
 
-  const oldest = [...deliveries.values()].sort((left, right) => left.updatedAt - right.updatedAt);
+  const terminal = [...deliveries.values()]
+    .filter(deliveryIsTerminal)
+    .sort((left, right) => left.updatedAt - right.updatedAt);
 
-  for (const delivery of oldest.slice(0, deliveries.size - MAX_DELIVERIES)) {
+  for (const delivery of terminal) {
+    if (deliveries.size <= MAX_DELIVERIES) break;
     deliveries.delete(delivery.id);
   }
 };
@@ -760,6 +767,7 @@ const loadDeliveries = async (options) => {
         status,
         turnId: normalizeString(value?.turnId),
         queuedSubmissionId: normalizeString(value?.queuedSubmissionId),
+        clientUserMessageId: normalizeString(value?.clientUserMessageId),
         transport: value?.transport === "desktop-queue" ? "desktop-queue" : "shared-app-server",
         dispatch: value?.transport === "desktop-queue"
           ? normalizeString(value?.dispatch) ?? "persisted"
@@ -797,22 +805,86 @@ const ensureDeliveriesLoaded = (options) => {
 
 const hashMessage = (message) => createHash("sha256").update(message).digest("hex");
 
-const turnUserMessages = (turn) => {
+const turnUserMessageEntries = (turn) => {
   if (!Array.isArray(turn?.items)) return [];
 
   return turn.items.flatMap((item) => {
     if (item?.type !== "userMessage" || !Array.isArray(item.content)) return [];
 
-    const text = item.content
+    const message = item.content
       .filter((input) => input?.type === "text")
       .map((input) => String(input.text ?? ""))
       .join("\n")
       .trim();
 
-    return text ? [text] : [];
+    if (!message) return [];
+
+    return [{
+      message,
+      clientUserMessageId: normalizeString(item.clientId),
+    }];
   });
 };
 
+const turnUserMessages = (turn) =>
+  turnUserMessageEntries(turn).map((entry) => entry.message);
+
+const deliveryStateFromTurn = (turn) => {
+  const turnId = normalizeString(turn?.id);
+  const ended = turn?.completedAt != null && Number.isFinite(Number(turn.completedAt));
+  let status = null;
+
+  if (turn?.status === "inProgress") status = "working";
+
+  if (turn?.status === "interrupted" && !ended) status = "working";
+
+  if (turn?.status === "completed") status = "completed";
+
+  if ((turn?.status === "interrupted" && ended) || turn?.status === "failed") {
+    status = "interrupted";
+  }
+
+  if (!turnId || !status) return null;
+
+  return {
+    turnId,
+    status,
+    dispatchError: turn?.status === "failed"
+      ? normalizeString(turn?.error?.message) ?? "Codex turn failed."
+      : null,
+    createdAt: Number.isFinite(Number(turn?.startedAt))
+      ? Number(turn.startedAt) * 1_000
+      : null,
+    updatedAt: Number.isFinite(Number(turn?.completedAt))
+      ? Number(turn.completedAt) * 1_000
+      : null,
+  };
+};
+
+const historicalDeliveryMatch = (turns, identity) => {
+  const expectedClientId = normalizeString(identity?.clientUserMessageId);
+  const expectedMessage = normalizeString(identity?.message);
+
+  if (!expectedClientId && !expectedMessage) return null;
+  const expectedHash = expectedMessage ? hashMessage(expectedMessage) : null;
+  const matches = [];
+
+  for (const turn of turns) {
+    for (const entry of turnUserMessageEntries(turn)) {
+      if (expectedClientId && entry.clientUserMessageId !== expectedClientId) continue;
+
+      if (expectedHash && hashMessage(entry.message) !== expectedHash) continue;
+
+      matches.push({ turn, entry });
+    }
+  }
+
+  if (matches.length !== 1) return null;
+  const state = deliveryStateFromTurn(matches[0].turn);
+
+  return state ? { ...matches[0], state } : null;
+};
+
 const readTurnHistory = async (thread, options) => {
   try {
     const result = await daemonRequest(
@@ -869,36 +941,20 @@ const reconcileDelivery = async (delivery, options) => {
 
   if (!turn) return;
 
-  const turnId = normalizeString(turn.id);
-  const ended = turn.completedAt != null && Number.isFinite(Number(turn.completedAt));
-  let nextStatus = null;
-
-  if (turn.status === "inProgress") nextStatus = "working";
-
-  if (turn.status === "interrupted" && !ended) nextStatus = "working";
-
-  if (turn.status === "completed") nextStatus = "completed";
-
-  if ((turn.status === "interrupted" && ended) || turn.status === "failed") {
-    nextStatus = "interrupted";
-  }
-
-  if (!turnId || !nextStatus) return;
+  const state = deliveryStateFromTurn(turn);
 
-  const failed = turn.status === "failed";
+  if (!state) return;
 
-  const failureMessage = normalizeString(turn?.error?.message) ?? "Codex turn failed.";
-
-  const changed = delivery.turnId !== turnId
-    || delivery.status !== nextStatus
-    || (failed && delivery.dispatchError !== failureMessage);
+  const changed = delivery.turnId !== state.turnId
+    || delivery.status !== state.status
+    || (state.dispatchError && delivery.dispatchError !== state.dispatchError);
 
   if (!changed) return;
 
-  delivery.turnId = turnId;
-  delivery.status = nextStatus;
+  delivery.turnId = state.turnId;
+  delivery.status = state.status;
 
-  if (failed) delivery.dispatchError = failureMessage;
+  if (state.dispatchError) delivery.dispatchError = state.dispatchError;
 
   delivery.updatedAt = Date.now();
   await persistDeliveries(options);
@@ -1054,6 +1110,8 @@ const queueMessage = async (request, options) => {
     await validateLoadedThread(thread, options);
   }
 
+  const clientUserMessageId = randomUUID();
+
   const result = await daemonRequest(
     "thread/queue/add",
     {
@@ -1063,7 +1121,7 @@ const queueMessage = async (request, options) => {
         text: message,
         textElements: [],
       }],
-      clientUserMessageId: randomUUID(),
+      clientUserMessageId,
     },
     options,
     true,
@@ -1085,6 +1143,7 @@ const queueMessage = async (request, options) => {
     status: "queued",
     turnId: null,
     queuedSubmissionId,
+    clientUserMessageId,
     transport: "shared-app-server",
     dispatch: "persisted",
     dispatchError: null,
@@ -1144,6 +1203,7 @@ const queueDesktopMessage = async (request, desktop, options) => {
     status: "queued",
     turnId: null,
     queuedSubmissionId: queued.queuedSubmissionId,
+    clientUserMessageId: null,
     transport: "desktop-queue",
     dispatch,
     dispatchError,
@@ -1151,6 +1211,35 @@ const queueDesktopMessage = async (request, desktop, options) => {
     updatedAt: now,
   };
 
+  try {
+    const lookup = await queueLookup(thread, queued.queuedSubmissionId, options);
+
+    if (lookup.submission) {
+      delivery.clientUserMessageId = normalizeString(lookup.submission.clientUserMessageId);
+    }
+  } catch {
+    // Desktop queue delivery already succeeded; identity enrichment is best-effort.
+  }
+
+  if (!delivery.clientUserMessageId) {
+    try {
+      const turns = await readTurnHistory(thread, options);
+      const historical = historicalDeliveryMatch(turns, { message });
+
+      if (historical) {
+        delivery.clientUserMessageId = historical.entry.clientUserMessageId;
+        delivery.turnId = historical.state.turnId;
+        delivery.status = historical.state.status;
+
+        if (historical.state.dispatchError) {
+          delivery.dispatchError = historical.state.dispatchError;
+        }
+      }
+    } catch {
+      // The durable queue receipt remains valid even if history is not reachable yet.
+    }
+  }
+
   pruneDeliveries();
   deliveries.set(delivery.id, delivery);
   await persistDeliveries(options);
@@ -1185,6 +1274,8 @@ const restoreDelivery = async (request, options, desktop = null) => {
   const deliveryId = normalizeString(request.deliveryId);
   const thread = normalizeString(request.thread);
   const queuedSubmissionId = normalizeString(request.queuedSubmissionId);
+  const clientUserMessageId = normalizeString(request.clientUserMessageId);
+  const recoveryMessage = normalizeString(request.message);
 
   if (!deliveryId || !thread) {
     throw new Error("deliveryId and thread are required.");
@@ -1197,6 +1288,16 @@ const restoreDelivery = async (request, options, desktop = null) => {
       throw new Error(`Codex delivery ${deliveryId} belongs to a different thread.`);
     }
 
+    if (clientUserMessageId && existing.clientUserMessageId
+      && clientUserMessageId !== existing.clientUserMessageId) {
+      throw new Error("Codex delivery client-message identity does not match the persisted delivery.");
+    }
+
+    if (clientUserMessageId && !existing.clientUserMessageId) {
+      existing.clientUserMessageId = clientUserMessageId;
+      await persistDeliveries(options);
+    }
+
     await reconcileDelivery(existing, options).catch(() => undefined);
 
     return {
@@ -1206,36 +1307,97 @@ const restoreDelivery = async (request, options, desktop = null) => {
     };
   }
 
-  if (desktop) {
-    validateDesktopThread(thread, desktop);
+  if (desktop) validateDesktopThread(thread, desktop);
+  else await validateLoadedThread(thread, options);
+
+  let lookup = { submission: null, ambiguous: false };
+
+  try {
+    lookup = await queueLookup(thread, queuedSubmissionId, options);
+  } catch (cause) {
+    if (!desktop) throw cause;
+  }
+
+  if (lookup.submission) {
+    const message = queuedMessage(lookup.submission);
+    const queuedClientUserMessageId = normalizeString(lookup.submission.clientUserMessageId);
+
+    if (!message) {
+      throw new Error("The queued Codex submission is not a single text message and cannot be restored safely.");
+    }
+
+    if (clientUserMessageId && queuedClientUserMessageId
+      && clientUserMessageId !== queuedClientUserMessageId) {
+      throw new Error("Codex queued submission client-message identity does not match Mesurer state.");
+    }
+
+    if (recoveryMessage && hashMessage(recoveryMessage) !== hashMessage(message)) {
+      throw new Error("Codex queued submission text does not match the saved Mesurer feedback.");
+    }
+
+    const now = Date.now();
+
+    const delivery = {
+      id: deliveryId,
+      thread,
+      message,
+      messageHash: hashMessage(message),
+      status: "queued",
+      turnId: null,
+      queuedSubmissionId: normalizeString(lookup.submission.id) ?? queuedSubmissionId,
+      clientUserMessageId: queuedClientUserMessageId ?? clientUserMessageId,
+      transport: desktop ? "desktop-queue" : "shared-app-server",
+      dispatch: desktop ? "desktop-opened" : "persisted",
+      dispatchError: null,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    pruneDeliveries();
+    deliveries.set(delivery.id, delivery);
+    await persistDeliveries(options);
+
+    return {
+      ok: true,
+      restored: true,
+      ...publicDelivery(delivery),
+    };
+  }
 
+  if (lookup.ambiguous) {
     throw new Error(
-      "Codex Desktop delivery state is unavailable. Mesurer will not requeue the message without its original delivery record.",
+      "Multiple queued Codex submissions exist for this thread; an exact queuedSubmissionId is required to restore the delivery safely.",
     );
   }
 
-  await validateLoadedThread(thread, options);
+  let turns;
 
-  const lookup = await queueLookup(thread, queuedSubmissionId, options);
-
-  if (!lookup.submission) {
-    if (lookup.ambiguous) {
+  try {
+    turns = await readTurnHistory(thread, options);
+  } catch (cause) {
+    if (desktop) {
       throw new Error(
-        "Multiple queued Codex submissions exist for this thread; an exact queuedSubmissionId is required to restore the delivery safely.",
+        "Codex Desktop delivery state is unavailable and turn history could not be read safely.",
+        { cause },
       );
     }
 
-    if (queuedSubmissionId) {
-      throw new Error(`Codex queued submission is not available: ${queuedSubmissionId}`);
-    }
-
-    throw new Error("No queued Codex submission is available to restore for this thread.");
+    throw cause;
   }
 
-  const message = queuedMessage(lookup.submission);
+  const historical = historicalDeliveryMatch(turns, {
+    clientUserMessageId,
+    message: recoveryMessage,
+  });
+
+  if (!historical) {
+    if (queuedSubmissionId) {
+      throw new Error(
+        `Codex queued submission is not available and no unique matching turn exists in history: ${queuedSubmissionId}`,
+      );
+    }
 
-  if (!message) {
-    throw new Error("The queued Codex submission is not a single text message and cannot be restored safely.");
+    throw new Error("No queued Codex submission or unique matching turn is available to restore for this thread.");
   }
 
   const now = Date.now();
@@ -1243,16 +1405,17 @@ const restoreDelivery = async (request, options, desktop = null) => {
   const delivery = {
     id: deliveryId,
     thread,
-    message,
-    messageHash: hashMessage(message),
-    status: "queued",
-    turnId: null,
-    queuedSubmissionId: normalizeString(lookup.submission.id),
-    transport: "shared-app-server",
-    dispatch: "persisted",
-    dispatchError: null,
-    createdAt: now,
-    updatedAt: now,
+    message: historical.entry.message,
+    messageHash: hashMessage(historical.entry.message),
+    status: historical.state.status,
+    turnId: historical.state.turnId,
+    queuedSubmissionId,
+    clientUserMessageId: historical.entry.clientUserMessageId ?? clientUserMessageId,
+    transport: desktop ? "desktop-queue" : "shared-app-server",
+    dispatch: desktop ? "desktop-opened" : "persisted",
+    dispatchError: historical.state.dispatchError,
+    createdAt: historical.state.createdAt ?? now,
+    updatedAt: historical.state.updatedAt ?? now,
   };
 
   pruneDeliveries();

package/scripts/codex-bridge.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../codex/codex-bridge.mjs";

package/scripts/codex-connect.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../codex/codex-connect.mjs";

package/scripts/codex-lifecycle.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../codex/codex-lifecycle.mjs";

package/scripts/install-skill.mjs

@@ -15,6 +15,9 @@ if (command !== "install") {
   const source = new URL("../skills/mesurer-ui/", import.meta.url);
   const injector = new URL("../dist/inject-script.js", import.meta.url);
   const mediaBunnyVendor = new URL("../dist/mediabunny-vendor.js", import.meta.url);
+  const codexBridge = new URL("../codex/codex-bridge.mjs", import.meta.url);
+  const codexConnect = new URL("../codex/codex-connect.mjs", import.meta.url);
+  const codexLifecycle = new URL("../codex/codex-lifecycle.mjs", import.meta.url);
   const destination = resolve(process.cwd(), ".agents/skills/mesurer-ui");
   const assets = resolve(destination, "assets");
 
@@ -24,6 +27,9 @@ if (command !== "install") {
   } else if (!existsSync(injector) || !existsSync(mediaBunnyVendor)) {
     console.error("Mesurer injector assets are missing. Reinstall mesurer-solid and retry.");
     process.exitCode = 1;
+  } else if (!existsSync(codexBridge) || !existsSync(codexConnect) || !existsSync(codexLifecycle)) {
+    console.error("Mesurer Codex companion assets are missing. Reinstall mesurer-solid and retry.");
+    process.exitCode = 1;
   } else {
     if (force) rmSync(destination, { recursive: true, force: true });
     mkdirSync(resolve(destination, ".."), { recursive: true });
@@ -31,6 +37,9 @@ if (command !== "install") {
     mkdirSync(assets, { recursive: true });
     cpSync(injector, resolve(assets, "inject-script.js"));
     cpSync(mediaBunnyVendor, resolve(assets, "mediabunny-vendor.js"));
-    console.log(`Installed Mesurer Agent Skill and injector assets at ${destination}`);
+    cpSync(codexBridge, resolve(assets, "codex-bridge.mjs"));
+    cpSync(codexConnect, resolve(assets, "codex-connect.mjs"));
+    cpSync(codexLifecycle, resolve(assets, "codex-lifecycle.mjs"));
+    console.log(`Installed Mesurer Agent Skill and local Codex companion assets at ${destination}`);
   }
 }

package/skills/mesurer-ui/SKILL.md

@@ -5,19 +5,19 @@ description: Use Mesurer for frontend UI implementation, review, debugging, layo
 
 # Mesurer UI workflow
 
-Mesurer is shared visual state between the person reviewing a page and the coding agent editing it. The rendered page is the integration boundary.
+Mesurer is shared visual state between the person reviewing a page and the coding agent editing it. This skill matches `mesurer-solid@0.2.1` stable. The rendered page is the integration boundary.
 
-The normal coding-agent workflow requires no Mesurer MCP server, chat-delivery daemon, or Send-to-agent callback. Use the browser/evaluation channel the browser controller already provides and read `window.__MESURER__` directly. The first-party `codex()` plugin is a separate human-initiated convenience for routing Context feedback through the application's native Codex host capability.
+The normal coding-agent workflow requires no Mesurer MCP server or Send-to-agent callback. Use the browser/evaluation channel the browser controller already provides and read `window.__MESURER__` directly. The first-party `codex()` plugin is a separate human-initiated **Settings -> Codex** convenience for routing Context feedback into local Codex threads. Do not confuse it with the Mesurer Solid ChatGPT/Codex agent plugin.
 
-Do not add a second Mesurer process for Codex delivery. Native applications expose the narrow `window.__MESURER_HOST__.codexBridge(request)` capability. The enabled plugin owns a renderer-scoped native lease; disabling it releases that lease without stopping Codex's shared daemon. Shared sessions use Codex's local app-server. When the native host inherited both `CODEX_THREAD_ID` and `CODEX_APP_TOOLS_PIPE_PATH` from Codex Desktop, Mesurer may queue only to that exact thread and wake it through `codex://threads/<id>`. Treat the app-tools pipe as an ownership signal only. Never connect to, proxy, or invoke it. A Desktop-bundled Codex executable must never start the shared daemon.
+For Settings -> Codex, Electron hosts can expose the narrow `window.__MESURER_HOST__.codexBridge(request)` capability. Ordinary browser hosts use the local Mesurer Codex Bridge companion on loopback when that feature is enabled. Do not start or install that companion merely to let an agent inspect Mesurer; it exists only for human-triggered Codex delivery. Neither transport may connect to Codex Desktop's private app-tools pipe. A Desktop-bundled Codex executable must never start the shared daemon.
 
 A meaningful Mesurer step must return evidence the agent actually uses.
 
 ## Know the available capabilities
 
-The base inspector has Select, X-ray, Rulers, Typography, Guides, Distance, and Settings. Color Picker uses application-local host capture when available and otherwise uses a working browser `EyeDropper`; a successful sample copies the configured format to the clipboard.
+The base inspector has Select, X-ray, Color Picker, Rulers, Typography, Guides, Distance, and Settings. Color Picker uses application-local host capture when available and otherwise uses a working browser `EyeDropper`; a successful sample copies the configured format to the clipboard.
 
-Optional first-party plugins add Context, Edit, Layout Guides, Screenshot, Recording, and Codex delivery. Context carries annotations and structured evidence. Edit carries Before/Desired/Live movement intent through the existing Arrange compatibility APIs. Layout Guides carries page-scoped column/row/grid intent and exposes saved guides through Context with each guide's `visible` flag. Screenshot and Recording are human capture workflows; Recording exposes the typed `recording:v1` service when application code needs its lifecycle. Codex is an optional human queue transport, not the normal agent protocol.
+Optional first-party plugins add Context, Edit, Layout Guides, Screenshot, Recording, and Codex delivery. Rulers, ordinary Guides, and Layout Guides remain usable while Edit is active; X-ray, Color Picker, Typography, Screenshot, and Recording stay in the Select lane. Context carries annotations and structured evidence. Edit carries Before/Desired/Live movement intent through the existing Arrange compatibility APIs. Layout Guides carries page-scoped column/row/grid intent and exposes saved guides through Context with each guide's `visible` flag. Screenshot and Recording are human capture workflows; Recording exposes the typed `recording:v1` service when application code needs its lifecycle. Codex is an optional human queue transport, not the normal agent protocol.
 
 The JSON-safe `window.__MESURER__` object exposes the full agent API. Lifecycle and discovery methods are `ready()`, `capabilities()`, `describe()`, `state()`, and `stable()`. Inspection methods are `inspect()`, `inspectAll()`, `at()`, `distance()`, `viewport()`, and `feedback()`. `command()` runs registered Mesurer commands.
 
@@ -27,6 +27,28 @@ Select, point inspection, and Context can target general DOM elements, including
 
 Human Select lifecycle is explicit. Invoking Select clears the current element and Guide selection before toggling the tool. Holding Shift while clicking rendered targets adds or removes them from the human multi-selection. Do not expect hidden selection state to return after Select is turned off or after an off-state reload.
 
+## Prefer the visible Mesurer UI
+
+When the coding harness already has browser or computer-use controls, treat Mesurer exactly like any other UI in that page. Do not route ordinary interaction through MCP just because the plugin includes MCP shortcuts.
+
+Prefer the visible controls when the task is visual or exploratory:
+
+- click Select/Edit and the toolbar tools;
+- turn X-ray, Rulers, ordinary Guides, and Layout Guides on or off;
+- open Typography and Settings;
+- drag Edit targets and direct-edit text;
+- draw and adjust Screenshot or Recording regions;
+- play, trim, resize, export, dismiss, and otherwise review captured media;
+- use the actual page and Mesurer overlays to compare visual variations.
+
+Use accessible roles and labels first. When a browser harness needs a stable automation hook, Mesurer exposes `[data-mesurer-island="true"]`, `[data-mesurer-builtin="<id>"]`, and `[data-mesurer-tool-id="<id>"]` on its inspector shell and toolbar controls. These identify Mesurer UI; they are not inspected-page targets.
+
+Use `window.__MESURER__` for exact evidence that is better represented as data than as clicks: Context, geometry, distances, rendered styles, saved annotations, Edit Before/Desired/Live intent, text intent, and review. Do not estimate a numeric spacing value from a screenshot when Mesurer can report it.
+
+The optional local Mesurer MCP exposes the same division of responsibility. `use_mesurer_tool` invokes a visible toolbar button; `set_mesurer_plugin` drives a visible Settings switch; and `inspect_ui`, `measure_ui`, `get_ui_context`, `select_ui`, `get_saved_ui_intent`, and `review_ui` are structured shortcuts. The MCP deliberately does not mirror the generic Mesurer command bus. If the normal browser harness already controls the right page, keep using that browser instead of launching a second MCP-owned browser.
+
+For visual alternatives, keep each experiment reversible. Use Edit or the page's normal controls to create a variation, capture it with the existing browser screenshot facility or the human Screenshot tool when that feature itself is under review, then restore or switch presentation before trying the next variation. Once the user chooses a direction, implement it in application source and verify the resulting Live render.
+
 ## Reuse the live instance
 
 Never reinject, dispose, or replace Mesurer just because this skill loaded. A person may already have selected elements, guides, measurements, annotations, Edit movement intent, text/style Desired intent, plugin state, a screenshot preview, or a recording preview open.