opensteer 0.9.4 → 0.9.6

package/dist/cli/bin.cjs

@@ -2598,10 +2598,8 @@ var init_cdp_dom_snapshot = __esm({
 });
 
 // ../browser-core/src/cdp-visual-stability.ts
-var DEFAULT_VISUAL_STABILITY_SETTLE_MS;
 var init_cdp_visual_stability = __esm({
   "../browser-core/src/cdp-visual-stability.ts"() {
-    DEFAULT_VISUAL_STABILITY_SETTLE_MS = 750;
   }
 });
 
@@ -6679,7 +6677,7 @@ function assertValidSemanticOperationInput(name, input) {
     }
   );
 }
-var opensteerComputerAnnotationNames, opensteerExposedSemanticOperationNames, opensteerPackageRunnableSemanticOperationNames, snapshotModeSchema, viewportSchema, opensteerBrowserLaunchOptionsSchema, attachBrowserOptionsSchema, opensteerBrowserOptionsSchema, opensteerBrowserContextOptionsSchema, targetByElementSchema2, targetByPersistSchema2, targetBySelectorSchema2, opensteerTargetInputSchema, opensteerResolvedTargetSchema, opensteerActionResultSchema, opensteerSnapshotCounterSchema, opensteerSessionStateSchema, opensteerOpenInputSchema, opensteerPageListInputSchema, opensteerPageListOutputSchema, opensteerPageNewInputSchema, opensteerPageActivateInputSchema, opensteerPageCloseInputSchema, opensteerPageCloseOutputSchema, opensteerPageGotoInputSchema, opensteerPageEvaluateInputSchema, opensteerPageEvaluateOutputSchema, opensteerAddInitScriptInputSchema, opensteerAddInitScriptOutputSchema, opensteerCapturedScriptSchema, opensteerCaptureScriptsInputSchema, opensteerCaptureScriptsOutputSchema, opensteerPageSnapshotInputSchema, opensteerPageSnapshotOutputSchema, opensteerComputerMouseButtonSchema, opensteerComputerKeyModifierSchema, opensteerDomClickInputSchema, opensteerDomHoverInputSchema, opensteerDomInputInputSchema, opensteerDomScrollInputSchema, opensteerExtractSchemaSchema, opensteerDomExtractInputSchema, jsonValueSchema2, opensteerDomExtractOutputSchema, opensteerSessionCloseInputSchema, opensteerSessionCloseOutputSchema, opensteerComputerAnnotationSchema, opensteerComputerClickActionSchema, opensteerComputerMoveActionSchema, opensteerComputerScrollActionSchema, opensteerComputerTypeActionSchema, opensteerComputerKeyActionSchema, opensteerComputerDragActionSchema, opensteerComputerScreenshotActionSchema, opensteerComputerWaitActionSchema, opensteerComputerActionSchema, opensteerComputerScreenshotOptionsSchema, opensteerComputerExecuteInputSchema, opensteerComputerTracePointSchema, opensteerComputerTraceEnrichmentSchema, opensteerComputerExecuteTimingSchema, opensteerComputerDisplayScaleSchema, opensteerComputerExecuteOutputSchema, opensteerSemanticOperationSpecificationsBase, exposedSemanticOperationNameSet, opensteerSemanticOperationSpecificationsInternal, opensteerSemanticOperationSpecifications, opensteerSemanticOperationSpecificationMap, semanticRestBasePath, opensteerSemanticRestEndpoints;
+var opensteerComputerAnnotationNames, opensteerExposedSemanticOperationNames, opensteerPackageRunnableSemanticOperationNames, snapshotModeSchema, viewportSchema, opensteerBrowserLaunchOptionsSchema, attachBrowserOptionsSchema, opensteerBrowserOptionsSchema, opensteerBrowserContextOptionsSchema, targetByElementSchema2, targetByPersistSchema2, targetBySelectorSchema2, opensteerTargetInputSchema, opensteerResolvedTargetSchema, opensteerActionResultSchema, opensteerSnapshotCounterSchema, opensteerSessionStateSchema, opensteerOpenInputSchema, opensteerPageListInputSchema, opensteerPageListOutputSchema, opensteerPageNewInputSchema, opensteerPageActivateInputSchema, opensteerPageCloseInputSchema, opensteerPageCloseOutputSchema, opensteerPageGotoInputSchema, opensteerPageEvaluateInputSchema, opensteerPageEvaluateOutputSchema, opensteerAddInitScriptInputSchema, opensteerAddInitScriptOutputSchema, opensteerCapturedScriptSchema, opensteerCaptureScriptsInputSchema, opensteerCaptureScriptsOutputSchema, opensteerPageSnapshotInputSchema, opensteerPageSnapshotOutputSchema, opensteerComputerMouseButtonSchema, opensteerComputerKeyModifierSchema, opensteerDomClickInputSchema, opensteerDomHoverInputSchema, opensteerDomInputInputSchema, opensteerDomScrollInputSchema, opensteerExtractTemplateSchema, opensteerDomExtractInputSchema, jsonValueSchema2, opensteerDomExtractOutputSchema, opensteerSessionCloseInputSchema, opensteerSessionCloseOutputSchema, opensteerComputerAnnotationSchema, opensteerComputerClickActionSchema, opensteerComputerMoveActionSchema, opensteerComputerScrollActionSchema, opensteerComputerTypeActionSchema, opensteerComputerKeyActionSchema, opensteerComputerDragActionSchema, opensteerComputerScreenshotActionSchema, opensteerComputerWaitActionSchema, opensteerComputerActionSchema, opensteerComputerScreenshotOptionsSchema, opensteerComputerExecuteInputSchema, opensteerComputerTracePointSchema, opensteerComputerTraceEnrichmentSchema, opensteerComputerExecuteTimingSchema, opensteerComputerDisplayScaleSchema, opensteerComputerExecuteOutputSchema, opensteerSemanticOperationSpecificationsBase, exposedSemanticOperationNameSet, opensteerSemanticOperationSpecificationsInternal, opensteerSemanticOperationSpecifications, opensteerSemanticOperationSpecificationMap, semanticRestBasePath, opensteerSemanticRestEndpoints;
 var init_semantic = __esm({
   "../protocol/src/semantic.ts"() {
     init_json2();
@@ -7261,10 +7259,10 @@ var init_semantic = __esm({
         required: ["target", "direction", "amount"]
       }
     );
-    opensteerExtractSchemaSchema = objectSchema(
+    opensteerExtractTemplateSchema = objectSchema(
       {},
       {
-        title: "OpensteerExtractSchema",
+        title: "OpensteerExtractTemplate",
         additionalProperties: true
       }
     );
@@ -7272,13 +7270,13 @@ var init_semantic = __esm({
       ...objectSchema(
         {
           persist: stringSchema(),
-          schema: opensteerExtractSchemaSchema
+          template: opensteerExtractTemplateSchema
         },
         {
           title: "OpensteerDomExtractInput"
         }
       ),
-      anyOf: [defineSchema({ required: ["persist"] }), defineSchema({ required: ["schema"] })]
+      anyOf: [defineSchema({ required: ["persist"] }), defineSchema({ required: ["template"] })]
     });
     jsonValueSchema2 = recordSchema({}, { title: "JsonValueRecord" });
     opensteerDomExtractOutputSchema = objectSchema(
@@ -10413,7 +10411,8 @@ function normalizeOpensteerEngineName(value, source = "engine") {
   if (normalized === "playwright" || normalized === "abp") {
     return normalized;
   }
-  throw new Error(
+  throw new OpensteerProtocolError(
+    "invalid-argument",
     `${source} must be one of ${OPENSTEER_ENGINE_NAMES.join(", ")}; received "${value}".`
   );
 }
@@ -10422,7 +10421,8 @@ function assertSupportedEngineOptions(input) {
     return;
   }
   if (typeof input.browser === "object" && input.browser !== null && input.browser.mode === "attach") {
-    throw new Error(
+    throw new OpensteerProtocolError(
+      "invalid-argument",
       'ABP engine does not support browser.mode="attach". Use the Playwright engine for attach flows.'
     );
   }
@@ -10430,7 +10430,8 @@ function assertSupportedEngineOptions(input) {
   if (unsupportedContextOptionNames.length === 0) {
     return;
   }
-  throw new Error(
+  throw new OpensteerProtocolError(
+    "invalid-argument",
     `ABP engine does not support ${unsupportedContextOptionNames.join(", ")}. Supported ABP context options: context.viewport.`
   );
 }
@@ -10488,6 +10489,7 @@ function stripWindowSizeArgs(args) {
 var OPENSTEER_ENGINE_NAMES, DEFAULT_OPENSTEER_ENGINE;
 var init_engine_selection = __esm({
   "../runtime-core/src/internal/engine-selection.ts"() {
+    init_src2();
     OPENSTEER_ENGINE_NAMES = ["playwright", "abp"];
     DEFAULT_OPENSTEER_ENGINE = "playwright";
   }
@@ -11472,7 +11474,8 @@ function assertProviderSupportsEngine(provider, engine) {
     return;
   }
   if (provider === "cloud") {
-    throw new Error(
+    throw new OpensteerProtocolError(
+      "invalid-argument",
       "ABP is not supported for provider=cloud. Cloud provider currently requires Playwright."
     );
   }
@@ -11482,7 +11485,8 @@ function normalizeOpensteerProviderMode(value, source = "OPENSTEER_PROVIDER") {
   if (normalized === OPENSTEER_PROVIDER_MODES[0] || normalized === OPENSTEER_PROVIDER_MODES[1]) {
     return normalized;
   }
-  throw new Error(
+  throw new OpensteerProtocolError(
+    "invalid-argument",
     `${source} must be one of ${OPENSTEER_PROVIDER_MODES.join(", ")}; received "${value}".`
   );
 }
@@ -11507,6 +11511,7 @@ function resolveOpensteerProvider(input = {}) {
 var OPENSTEER_PROVIDER_MODES;
 var init_config = __esm({
   "src/provider/config.ts"() {
+    init_src2();
     OPENSTEER_PROVIDER_MODES = ["local", "cloud"];
   }
 });
@@ -11968,12 +11973,60 @@ function wrapCloudFetchError(error, input) {
   wrapped.name = error.name;
   return wrapped;
 }
-var CLOUD_CLOSE_TIMEOUT_MS, CLOUD_CLOSE_POLL_INTERVAL_MS, OpensteerCloudClient;
+async function createCloudRequestError(response, input) {
+  const payload = await readCloudErrorPayload(response);
+  return new OpensteerCloudRequestError({
+    statusCode: response.status,
+    method: input.method,
+    pathname: input.pathname,
+    url: input.url,
+    message: payload?.error ?? `${input.method} ${input.pathname} failed with ${String(response.status)}.`,
+    ...payload?.code === void 0 ? {} : { code: payload.code },
+    ...payload?.details === void 0 ? {} : { details: payload.details }
+  });
+}
+async function readCloudErrorPayload(response) {
+  try {
+    return asCloudErrorPayload(await response.json());
+  } catch {
+    return void 0;
+  }
+}
+function asCloudErrorPayload(value) {
+  if (value === null || typeof value !== "object") {
+    return void 0;
+  }
+  const payload = value;
+  return {
+    ...typeof payload.error === "string" ? { error: payload.error } : {},
+    ...typeof payload.code === "string" ? { code: payload.code } : {},
+    ..."details" in payload ? { details: payload.details } : {}
+  };
+}
+var CLOUD_CLOSE_TIMEOUT_MS, CLOUD_CLOSE_POLL_INTERVAL_MS, OpensteerCloudRequestError, OpensteerCloudClient;
 var init_client = __esm({
   "src/cloud/client.ts"() {
     init_profile_sync();
     CLOUD_CLOSE_TIMEOUT_MS = 6e4;
     CLOUD_CLOSE_POLL_INTERVAL_MS = 250;
+    OpensteerCloudRequestError = class extends Error {
+      statusCode;
+      code;
+      details;
+      method;
+      pathname;
+      url;
+      constructor(args) {
+        super(args.message);
+        this.name = "OpensteerCloudRequestError";
+        this.statusCode = args.statusCode;
+        this.code = args.code;
+        this.details = args.details;
+        this.method = args.method;
+        this.pathname = args.pathname;
+        this.url = args.url;
+      }
+    };
     OpensteerCloudClient = class {
       constructor(config) {
         this.config = config;
@@ -12149,7 +12202,11 @@ var init_client = __esm({
           });
         }
         if (!response.ok) {
-          throw new Error(`${init.method} ${pathname} failed with ${String(response.status)}.`);
+          throw await createCloudRequestError(response, {
+            method: init.method,
+            pathname,
+            url
+          });
         }
         return response;
       }
@@ -12220,7 +12277,7 @@ var init_package = __esm({
   "../runtime-core/package.json"() {
     package_default2 = {
       name: "@opensteer/runtime-core",
-      version: "0.2.3",
+      version: "0.2.5",
       description: "Shared semantic runtime for Opensteer local and cloud execution.",
       license: "MIT",
       type: "module",
@@ -12372,7 +12429,7 @@ var init_errors3 = __esm({
 function defaultPolicy() {
   return DEFAULT_POLICY;
 }
-var DEFAULT_TIMEOUTS, DEFAULT_SETTLE_DELAYS, defaultSnapshotSettleObserver, DOM_ACTION_VISUAL_STABILITY_PROFILES, DEFAULT_DOM_ACTION_VISUAL_STABILITY_PROFILE, NAVIGATION_VISUAL_STABILITY_PROFILE, NAVIGATION_POST_LOAD_CAPTURE_WINDOW_MS, defaultDomActionSettleObserver, defaultNavigationSettleObserver, DEFAULT_SETTLE_OBSERVERS, defaultTimeoutPolicy, defaultSettlePolicy, defaultRetryPolicy, defaultFallbackPolicy, DEFAULT_POLICY;
+var DEFAULT_TIMEOUTS, DEFAULT_SETTLE_DELAYS, DOM_ACTION_VISUAL_STABILITY_PROFILES, DEFAULT_DOM_ACTION_VISUAL_STABILITY_PROFILE, NAVIGATION_VISUAL_STABILITY_PROFILE, NAVIGATION_POST_LOAD_CAPTURE_WINDOW_MS, defaultDomActionSettleObserver, defaultNavigationSettleObserver, DEFAULT_SETTLE_OBSERVERS, defaultTimeoutPolicy, defaultSettlePolicy, defaultRetryPolicy, defaultFallbackPolicy, DEFAULT_POLICY;
 var init_defaults = __esm({
   "../runtime-core/src/policy/defaults.ts"() {
     init_src();
@@ -12401,21 +12458,6 @@ var init_defaults = __esm({
       "dom-action": 100,
       snapshot: 0
     };
-    defaultSnapshotSettleObserver = {
-      async settle(input) {
-        if (input.trigger !== "snapshot") {
-          return false;
-        }
-        await input.engine.waitForVisualStability({
-          pageRef: input.pageRef,
-          ...input.remainingMs === void 0 ? {} : { timeoutMs: input.remainingMs },
-          settleMs: DEFAULT_VISUAL_STABILITY_SETTLE_MS,
-          scope: "visible-frames"
-        });
-        return true;
-      }
-    };
-    Object.freeze(defaultSnapshotSettleObserver);
     DOM_ACTION_VISUAL_STABILITY_PROFILES = {
       "dom.click": { settleMs: 750, scope: "visible-frames", timeoutMs: 7e3 },
       "dom.input": { settleMs: 750, scope: "visible-frames", timeoutMs: 7e3 },
@@ -12468,6 +12510,7 @@ var init_defaults = __esm({
           return false;
         }
         try {
+          const startedAt = Date.now();
           await input.engine.waitForPostLoadQuiet({
             pageRef: input.pageRef,
             timeoutMs: effectiveTimeout,
@@ -12475,9 +12518,13 @@ var init_defaults = __esm({
             captureWindowMs: Math.min(NAVIGATION_POST_LOAD_CAPTURE_WINDOW_MS, effectiveTimeout),
             signal: input.signal
           });
+          const visualTimeout = Math.max(0, effectiveTimeout - (Date.now() - startedAt));
+          if (visualTimeout <= 0) {
+            return true;
+          }
           await input.engine.waitForVisualStability({
             pageRef: input.pageRef,
-            timeoutMs: effectiveTimeout,
+            timeoutMs: visualTimeout,
             settleMs: profile.settleMs,
             scope: profile.scope
           });
@@ -12489,7 +12536,6 @@ var init_defaults = __esm({
     };
     Object.freeze(defaultNavigationSettleObserver);
     DEFAULT_SETTLE_OBSERVERS = Object.freeze([
-      defaultSnapshotSettleObserver,
       defaultDomActionSettleObserver,
       defaultNavigationSettleObserver
     ]);
@@ -12977,6 +13023,9 @@ function buildClauseSelector(node, clause) {
   if (!clause || typeof clause !== "object") {
     return "";
   }
+  if (clause.kind === "text") {
+    return "";
+  }
   if (clause.kind === "position") {
     if (clause.axis === "nthOfType") {
       return `:nth-of-type(${Math.max(1, Number(node.position?.nthOfType || 1))})`;
@@ -13092,7 +13141,7 @@ function resolveExtractedValueInContext(normalizedValue, options) {
 function stripPositionClauses(nodes) {
   return (nodes || []).map((node) => ({
     ...node,
-    match: (node.match || []).filter((clause) => clause.kind !== "position")
+    match: (node.match || []).filter((clause) => clause.kind !== "position" && clause.kind !== "text")
   }));
 }
 function dedupeSelectors(selectors) {
@@ -13680,9 +13729,17 @@ function resolveDomPathInScope(index, domPath, scope) {
   if (!candidates.length) {
     return null;
   }
+  const lastNode = domPath[domPath.length - 1];
+  const textClauses = lastNode?.match.filter((c) => c.kind === "text") ?? [];
   let fallback = null;
   for (const selector of candidates) {
-    const matches = querySelectorAllInScope(index, selector, scope);
+    let matches = querySelectorAllInScope(index, selector, scope);
+    if (textClauses.length > 0 && matches.length > 1) {
+      const filtered = matches.filter((node) => matchesTextClauses(node, textClauses));
+      if (filtered.length > 0) {
+        matches = filtered;
+      }
+    }
     if (matches.length === 1) {
       return {
         node: matches[0],
@@ -13702,6 +13759,10 @@ function resolveDomPathInScope(index, domPath, scope) {
   }
   return fallback;
 }
+function matchesTextClauses(node, clauses) {
+  const text = (node.textContent ?? "").replace(/\s+/g, " ").trim();
+  return clauses.every((clause) => text.includes(clause.value));
+}
 function queryAllDomPathInScope(index, domPath, scope) {
   const selectors = buildPathCandidates(domPath);
   for (const selector of selectors) {
@@ -13860,7 +13921,13 @@ function clonePathNode(node) {
   };
 }
 function cloneMatchClause(clause) {
-  return clause.kind === "position" ? { kind: "position", axis: clause.axis } : {
+  if (clause.kind === "position") {
+    return { kind: "position", axis: clause.axis };
+  }
+  if (clause.kind === "text") {
+    return { kind: "text", value: clause.value };
+  }
+  return {
     kind: "attr",
     key: clause.key,
     ...clause.op === void 0 ? {} : { op: clause.op },
@@ -13915,6 +13982,13 @@ function normalizeMatch(rawMatch, attrs, position, tag) {
           op,
           ...value === void 0 ? {} : { value }
         });
+        continue;
+      }
+      if (record.kind === "text") {
+        const textValue = typeof record.value === "string" ? record.value.trim() : "";
+        if (textValue) {
+          push({ kind: "text", value: textValue.slice(0, 80) });
+        }
       }
     }
   }
@@ -14329,7 +14403,7 @@ var init_executor = __esm({
     init_action_boundary2();
     init_policy();
     init_bridge();
-    MAX_DOM_ACTION_ATTEMPTS = 3;
+    MAX_DOM_ACTION_ATTEMPTS = 2;
     DEFAULT_SCROLL_OPTIONS = {
       block: "center",
       inline: "center"
@@ -14816,11 +14890,12 @@ var init_executor = __esm({
         throw this.createActionabilityError(
           operation,
           "obscured",
-          `hit test resolved ${hit.nodeRef} outside the target subtree rooted at ${resolved.nodeRef}`,
+          `target is obscured by ${assessment.blockingDescription ?? "another element"} at the click point`,
           {
             ...details,
             hitRelation: assessment.relation,
             ...assessment.ambiguous === void 0 ? {} : { hitAmbiguous: assessment.ambiguous },
+            ...assessment.blockingDescription === void 0 ? {} : { blockingDescription: assessment.blockingDescription },
             ...assessment.canonicalTarget === void 0 ? {} : {
               canonicalNodeRef: assessment.canonicalTarget.nodeRef,
               canonicalDocumentRef: assessment.canonicalTarget.documentRef,
@@ -14834,8 +14909,7 @@ var init_executor = __esm({
             hitMissingFromSnapshot: !resolved.snapshot.nodes.some(
               (node) => node.nodeRef === hit.nodeRef
             )
-          },
-          true
+          }
         );
       }
       async resolveActionablePointerTarget(session, operation, resolved) {
@@ -15026,7 +15100,12 @@ var init_runtime = __esm({
         });
       }
       async buildPath(input) {
-        return sanitizeReplayElementPath(await this.requireBridge().buildReplayPath(input.locator));
+        return sanitizeReplayElementPath(
+          await this.requireBridge().buildReplayPath(
+            input.locator,
+            input.enableTextMatch ? { enableTextMatch: true } : void 0
+          )
+        );
       }
       async resolveTarget(input) {
         return this.withSnapshotSession((session) => this.resolveTargetWithSession(session, input));
@@ -15246,7 +15325,7 @@ var init_runtime = __esm({
         if (resolvedByLocator) {
           const { snapshot, node } = resolvedByLocator;
           const anchor = await this.buildAnchorFromSnapshotNode(session, snapshot, node);
-          const replayPath = await this.tryBuildPathFromNode(snapshot, node);
+          const replayPath = await this.tryBuildPathFromNode(snapshot, node, { enableTextMatch: true });
           return this.createResolvedTarget("live", snapshot, node, anchor, {
             ...target.persist === void 0 ? {} : { persist: target.persist },
             ...replayPath === void 0 ? {} : { replayPath }
@@ -15264,11 +15343,12 @@ var init_runtime = __esm({
         const { snapshot, node } = resolved;
         const anchor = await this.buildAnchorFromSnapshotNode(session, snapshot, node);
         const writeDescriptor = descriptorWriter ?? ((input) => this.descriptors.write(input));
-        const replayPath = await this.tryBuildPathFromNode(snapshot, node);
+        const enableTextMatch = method !== "extract";
+        const replayPath = await this.tryBuildPathFromNode(snapshot, node, { enableTextMatch });
         const descriptor = target.persist === void 0 ? void 0 : await writeDescriptor({
           method,
           persist: target.persist,
-          path: replayPath ?? await this.buildPathForNode(snapshot, node),
+          path: replayPath ?? await this.buildPathForNode(snapshot, node, { enableTextMatch }),
           sourceUrl: snapshot.url
         });
         return this.createResolvedTarget("selector", snapshot, node, anchor, {
@@ -15368,7 +15448,7 @@ var init_runtime = __esm({
             `Unable to resolve structural anchor "${buildPathSelectorHint(anchor)}" in the current session`
           );
         }
-        const replayPath = await this.tryBuildPathFromNode(context.snapshot, target.node);
+        const replayPath = await this.tryBuildPathFromNode(context.snapshot, target.node, { enableTextMatch: true });
         return this.createResolvedTarget(source, context.snapshot, target.node, anchor, {
           ...persist === void 0 ? {} : { persist },
           ...replayPath === void 0 ? {} : { replayPath }
@@ -15539,19 +15619,20 @@ var init_runtime = __esm({
         }
         return this.bridge;
       }
-      async buildPathForNode(snapshot, node) {
+      async buildPathForNode(snapshot, node, options) {
         if (node.nodeRef === void 0) {
           throw new Error(
             `snapshot node ${String(node.snapshotNodeId)} does not expose a live node reference`
           );
         }
         return this.buildPath({
-          locator: createNodeLocator(snapshot.documentRef, snapshot.documentEpoch, node.nodeRef)
+          locator: createNodeLocator(snapshot.documentRef, snapshot.documentEpoch, node.nodeRef),
+          ...options?.enableTextMatch ? { enableTextMatch: true } : {}
         });
       }
-      async tryBuildPathFromNode(snapshot, node) {
+      async tryBuildPathFromNode(snapshot, node, options) {
         try {
-          return await this.buildPathForNode(snapshot, node);
+          return await this.buildPathForNode(snapshot, node, options);
         } catch {
           return void 0;
         }
@@ -17121,6 +17202,9 @@ function relaxPathForSingleSample(path24, mode) {
         }
         return !isLast;
       }
+      if (clause.kind === "text") {
+        return false;
+      }
       const key = String(clause.key || "").trim().toLowerCase();
       if (!key || !shouldKeepAttrForSingleSample(key)) {
         return false;
@@ -17223,9 +17307,11 @@ function buildNodeStructure(node) {
     }
     structuralAttrs[key] = value;
   }
-  const matchClauses = (node.match || []).map(
-    (clause) => clause.kind === "position" ? `position:${clause.axis}` : `attr:${String(clause.key || "").trim().toLowerCase()}`
-  ).sort();
+  const matchClauses = (node.match || []).map((clause) => {
+    if (clause.kind === "position") return `position:${clause.axis}`;
+    if (clause.kind === "text") return `text:${clause.value}`;
+    return `attr:${String(clause.key || "").trim().toLowerCase()}`;
+  }).sort();
   return {
     tag,
     attrs: structuralAttrs,
@@ -17631,6 +17717,9 @@ function mergeMatchByMajority(matchLists, attrs, threshold, positionFlags = {
       });
       continue;
     }
+    if (clause.kind === "text") {
+      continue;
+    }
     if (clause.axis === "nthOfType") {
       if (positionFlags.hasNthOfType) {
         merged.push({ kind: "position", axis: "nthOfType" });
@@ -17809,9 +17898,9 @@ var init_extraction_consolidation = __esm({
     CLUSTER_FALLBACK_PREFIX = "variant";
   }
 });
-function assertValidOpensteerExtractionSchemaRoot(schema) {
-  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
-    throw new Error("Invalid extraction schema: expected a JSON object at the top level.");
+function assertValidOpensteerExtractionTemplateRoot(template) {
+  if (!template || typeof template !== "object" || Array.isArray(template)) {
+    throw new Error("Invalid extraction template: expected a JSON object at the top level.");
   }
 }
 function isPersistedOpensteerExtractionValueNode2(value) {
@@ -17833,12 +17922,12 @@ function isPersistedOpensteerExtractionArrayNode2(value) {
   return "$array" in value;
 }
 async function compileOpensteerExtractionFieldTargets(options) {
-  assertValidOpensteerExtractionSchemaRoot(options.schema);
+  assertValidOpensteerExtractionTemplateRoot(options.template);
   const fields = [];
-  await collectFieldTargetsFromSchemaObject({
+  await collectFieldTargetsFromTemplateObject({
     dom: options.dom,
     pageRef: options.pageRef,
-    value: options.schema,
+    value: options.template,
     path: "",
     fields,
     insideArray: false
@@ -17890,13 +17979,13 @@ function createOpensteerExtractionDescriptorStore(options) {
   }
   return new MemoryOpensteerExtractionDescriptorStore(namespace);
 }
-async function collectFieldTargetsFromSchemaObject(options) {
+async function collectFieldTargetsFromTemplateObject(options) {
   for (const [key, childValue] of Object.entries(options.value)) {
     const normalizedKey = normalizeKey(key);
     if (!normalizedKey) {
       continue;
     }
-    await collectFieldTargetsFromSchemaValue({
+    await collectFieldTargetsFromTemplateValue({
       dom: options.dom,
       pageRef: options.pageRef,
       value: childValue,
@@ -17906,8 +17995,8 @@ async function collectFieldTargetsFromSchemaObject(options) {
     });
   }
 }
-async function collectFieldTargetsFromSchemaValue(options) {
-  const normalizedField = normalizeSchemaField(options.value);
+async function collectFieldTargetsFromTemplateValue(options) {
+  const normalizedField = normalizeTemplateField(options.value);
   if (normalizedField !== null) {
     options.fields.push(
       await compileFieldTarget({
@@ -17922,12 +18011,12 @@ async function collectFieldTargetsFromSchemaValue(options) {
   if (Array.isArray(options.value)) {
     if (options.insideArray) {
       throw new Error(
-        `Nested arrays are not supported in extraction schema at "${labelForPath(options.path)}".`
+        `Nested arrays are not supported in extraction template at "${labelForPath(options.path)}".`
       );
     }
     if (options.value.length === 0) {
       throw new Error(
-        `Extraction array "${labelForPath(options.path)}" must include at least one representative item.`
+        `Extraction array "${labelForPath(options.path)}" must include at least one representative template item.`
       );
     }
     for (let index = 0; index < options.value.length; index += 1) {
@@ -17938,7 +18027,7 @@ async function collectFieldTargetsFromSchemaValue(options) {
         );
       }
       const fieldCountBeforeItem = options.fields.length;
-      await collectFieldTargetsFromSchemaObject({
+      await collectFieldTargetsFromTemplateObject({
         dom: options.dom,
         pageRef: options.pageRef,
         value: itemValue,
@@ -17949,7 +18038,7 @@ async function collectFieldTargetsFromSchemaValue(options) {
       const itemFields = options.fields.slice(fieldCountBeforeItem);
       if (!itemFields.some((field) => !("source" in field))) {
         throw new Error(
-          `Extraction array "${labelForPath(options.path)}" item ${String(index)} must include at least one element- or selector-backed field.`
+          `Extraction array "${labelForPath(options.path)}" item ${String(index)} must include at least one element number or selector field.`
         );
       }
     }
@@ -17957,10 +18046,10 @@ async function collectFieldTargetsFromSchemaValue(options) {
   }
   if (!options.value || typeof options.value !== "object") {
     throw new Error(
-      `Invalid extraction schema value at "${labelForPath(options.path)}": expected an object, array, or field descriptor.`
+      `Invalid extraction template value at "${labelForPath(options.path)}": expected an object, array, or field descriptor.`
     );
   }
-  await collectFieldTargetsFromSchemaObject({
+  await collectFieldTargetsFromTemplateObject({
     dom: options.dom,
     pageRef: options.pageRef,
     value: options.value,
@@ -17992,7 +18081,7 @@ async function compileFieldTarget(options) {
     path: await resolveSelectorFieldPath({
       dom: options.dom,
       pageRef: options.pageRef,
-      selector: `[c="${String(options.field.element)}"]`
+      selector: `[c="${String(options.field.c)}"]`
     }),
     ...options.field.attribute === void 0 ? {} : { attribute: options.field.attribute }
   };
@@ -18293,24 +18382,29 @@ function countNonNullLeaves(value) {
   }
   return Object.values(value).reduce((sum, item) => sum + countNonNullLeaves(item), 0);
 }
-function normalizeSchemaField(value) {
+function normalizeTemplateField(value) {
+  if (typeof value === "number") {
+    return {
+      c: normalizeExtractionCounter(value)
+    };
+  }
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return null;
   }
   const raw = value;
-  const hasElement = raw.element !== void 0;
+  const hasCounter = raw.c !== void 0 || raw.element !== void 0;
   const hasSelector = raw.selector !== void 0;
   const hasSource = raw.source !== void 0;
-  const targetCount = Number(hasElement) + Number(hasSelector) + Number(hasSource);
+  const targetCount = Number(hasCounter) + Number(hasSelector) + Number(hasSource);
   if (targetCount === 0) {
     return null;
   }
   if (targetCount !== 1) {
     throw new Error(
-      "Extraction field descriptors must specify exactly one of element, selector, or source."
+      "Extraction field descriptors must specify exactly one of c/element, selector, or source."
     );
   }
-  const attribute = raw.attribute === void 0 ? void 0 : normalizeNonEmptyString2("attribute", raw.attribute);
+  const attribute = raw.attr !== void 0 ? normalizeNonEmptyString2("attr", raw.attr) : raw.attribute === void 0 ? void 0 : normalizeNonEmptyString2("attribute", raw.attribute);
   if (hasSource) {
     if (raw.source !== "current_url") {
       throw new Error(`Unsupported extraction source "${String(raw.source)}".`);
@@ -18325,17 +18419,20 @@ function normalizeSchemaField(value) {
       ...attribute === void 0 ? {} : { attribute }
     };
   }
-  const element = Number(raw.element);
-  if (!Number.isInteger(element) || element < 1) {
-    throw new Error(
-      `Extraction field element must be a positive integer, received ${String(raw.element)}.`
-    );
-  }
   return {
-    element,
+    c: normalizeExtractionCounter(raw.c ?? raw.element),
     ...attribute === void 0 ? {} : { attribute }
   };
 }
+function normalizeExtractionCounter(value) {
+  const counter = Number(value);
+  if (!Number.isInteger(counter) || counter < 1) {
+    throw new Error(
+      `Extraction element number must be a positive integer, received ${String(value)}.`
+    );
+  }
+  return counter;
+}
 function normalizeNamespace(namespace) {
   const normalized = String(namespace ?? "default").trim();
   return normalized.length === 0 ? "default" : normalized;
@@ -18366,7 +18463,7 @@ function parseExtractionDescriptorRecord(record) {
       kind: "dom-extraction",
       persist: raw.persist,
       root,
-      ...typeof raw.schemaHash === "string" ? { schemaHash: raw.schemaHash } : {},
+      ...typeof raw.templateHash === "string" ? { templateHash: raw.templateHash } : typeof raw.schemaHash === "string" ? { templateHash: raw.schemaHash } : {},
       ...typeof raw.sourceUrl === "string" ? { sourceUrl: raw.sourceUrl } : {}
     }
   };
@@ -18475,7 +18572,7 @@ var init_extraction2 = __esm({
           kind: "dom-extraction",
           persist: input.persist,
           root: input.root,
-          ...input.schemaHash === void 0 ? {} : { schemaHash: input.schemaHash },
+          ...input.templateHash === void 0 ? {} : { templateHash: input.templateHash },
           ...input.sourceUrl === void 0 ? {} : { sourceUrl: input.sourceUrl }
         };
         const key = persistKey(this.namespace, input.persist);
@@ -18524,7 +18621,7 @@ var init_extraction2 = __esm({
           kind: "dom-extraction",
           persist: input.persist,
           root: input.root,
-          ...input.schemaHash === void 0 ? {} : { schemaHash: input.schemaHash },
+          ...input.templateHash === void 0 ? {} : { templateHash: input.templateHash },
           ...input.sourceUrl === void 0 ? {} : { sourceUrl: input.sourceUrl }
         };
         const key = persistKey(this.namespace, input.persist);
@@ -18701,19 +18798,260 @@ function truncateValue(value, max) {
   }
   return `${head}${TRUNCATION_SUFFIX}`;
 }
+function takeValueWithinSerializedLengthFromEnd(value, max) {
+  let serializedLength = 0;
+  const chars = [];
+  for (let index = value.length - 1; index >= 0; index -= 1) {
+    const char = value[index];
+    let nextLength = 1;
+    if (char === "&") {
+      nextLength = 5;
+    } else if (char === "<" || char === ">") {
+      nextLength = 4;
+    } else if (char === '"') {
+      nextLength = 6;
+    }
+    if (serializedLength + nextLength > max) {
+      break;
+    }
+    chars.push(char);
+    serializedLength += nextLength;
+  }
+  return chars.reverse().join("");
+}
+function truncateValueInMiddle(value, headMax, tailMax, marker = MIDDLE_TRUNCATION_MARKER) {
+  const markerLength = getSerializedLength(marker);
+  const max = headMax + markerLength + tailMax;
+  if (getSerializedLength(value) <= max) {
+    return value;
+  }
+  const head = takeValueWithinSerializedLength(value, headMax).replace(/\s+$/u, "");
+  const tail = takeValueWithinSerializedLengthFromEnd(value, tailMax).replace(/^\s+/u, "");
+  if (head.length === 0) {
+    return tail.length === 0 ? marker : `${marker}${tail}`;
+  }
+  if (tail.length === 0) {
+    return `${head}${marker}`;
+  }
+  return `${head}${marker}${tail}`;
+}
 function getAttrLimit(attr) {
-  if (URL_ATTRS.has(attr)) {
-    return URL_ATTR_MAX;
+  if (attr === "srcset") {
+    return SRCSET_ATTR_MAX;
   }
   if (TEXT_ATTRS.has(attr)) {
     return TEXT_ATTR_MAX;
   }
   return void 0;
 }
+function shouldBoundAttr(attr) {
+  return MIDDLE_TRUNCATED_URL_ATTRS.has(attr) || getAttrLimit(attr) !== void 0;
+}
 function setBoundedAttr(el, attr, value) {
+  if (MIDDLE_TRUNCATED_URL_ATTRS.has(attr)) {
+    el.attr(
+      attr,
+      truncateValueInMiddle(value, MIDDLE_TRUNCATION_HEAD_MAX, MIDDLE_TRUNCATION_TAIL_MAX)
+    );
+    return;
+  }
   const limit = getAttrLimit(attr);
+  if (attr === "srcset" && limit !== void 0) {
+    el.attr(attr, truncateSrcsetValue(value, limit));
+    return;
+  }
   el.attr(attr, limit === void 0 ? value : truncateValue(value, limit));
 }
+function truncateSrcsetValue(value, max) {
+  if (getSerializedLength(value) <= max) {
+    return value;
+  }
+  const candidates = parseSrcsetCandidates2(value);
+  if (candidates.length === 0) {
+    return truncateValueInMiddle(value, SRCSET_FALLBACK_HEAD_MAX, SRCSET_FALLBACK_TAIL_MAX);
+  }
+  for (const [headMax, tailMax, includeBest] of [
+    [SRCSET_CANDIDATE_HEAD_MAX, SRCSET_CANDIDATE_TAIL_MAX, true],
+    [SRCSET_COMPACT_CANDIDATE_HEAD_MAX, SRCSET_COMPACT_CANDIDATE_TAIL_MAX, true],
+    [SRCSET_COMPACT_CANDIDATE_HEAD_MAX, SRCSET_COMPACT_CANDIDATE_TAIL_MAX, false]
+  ]) {
+    const compact = buildTruncatedSrcsetValue(candidates, headMax, tailMax, includeBest);
+    if (getSerializedLength(compact) <= max) {
+      return compact;
+    }
+  }
+  return truncateValueInMiddle(value, SRCSET_FALLBACK_HEAD_MAX, SRCSET_FALLBACK_TAIL_MAX);
+}
+function buildTruncatedSrcsetValue(candidates, headMax, tailMax, includeBest) {
+  const kept = getPreferredSrcsetCandidateIndices(candidates, includeBest);
+  const parts = [];
+  let previousIndex;
+  for (const candidateIndex of kept) {
+    if (previousIndex !== void 0 && candidateIndex - previousIndex > 1) {
+      parts.push(MIDDLE_TRUNCATION_MARKER);
+    }
+    parts.push(formatSrcsetCandidate(candidates[candidateIndex], headMax, tailMax));
+    previousIndex = candidateIndex;
+  }
+  return parts.join(", ");
+}
+function getPreferredSrcsetCandidateIndices(candidates, includeBest) {
+  if (candidates.length === 0) {
+    return [];
+  }
+  const kept = /* @__PURE__ */ new Set([0, candidates.length - 1]);
+  if (includeBest) {
+    kept.add(pickBestSrcsetCandidateIndex(candidates));
+  }
+  return [...kept].filter((index) => index >= 0 && index < candidates.length).sort((a, b) => a - b);
+}
+function pickBestSrcsetCandidateIndex(candidates) {
+  let bestWidthIndex = -1;
+  let bestWidth = -1;
+  let bestDensityIndex = -1;
+  let bestDensity = -1;
+  for (let index = 0; index < candidates.length; index += 1) {
+    const candidate = candidates[index];
+    if (typeof candidate.width === "number" && Number.isFinite(candidate.width) && candidate.width > bestWidth) {
+      bestWidth = candidate.width;
+      bestWidthIndex = index;
+    }
+    if (typeof candidate.density === "number" && Number.isFinite(candidate.density) && candidate.density > bestDensity) {
+      bestDensity = candidate.density;
+      bestDensityIndex = index;
+    }
+  }
+  if (bestWidthIndex >= 0) {
+    return bestWidthIndex;
+  }
+  if (bestDensityIndex >= 0) {
+    return bestDensityIndex;
+  }
+  return candidates.length - 1;
+}
+function formatSrcsetCandidate(candidate, headMax, tailMax) {
+  const url = truncateValueInMiddle(candidate.url, headMax, tailMax);
+  return candidate.descriptorText ? `${url} ${candidate.descriptorText}` : url;
+}
+function parseSrcsetCandidates2(raw) {
+  const text = raw.trim();
+  if (!text) {
+    return [];
+  }
+  const out = [];
+  let index = 0;
+  while (index < text.length) {
+    index = skipSrcsetSeparators(text, index);
+    if (index >= text.length) {
+      break;
+    }
+    const urlToken = readSrcsetUrlToken(text, index);
+    index = urlToken.nextIndex;
+    const url = urlToken.value.trim();
+    if (!url) {
+      continue;
+    }
+    index = skipSrcsetWhitespace(text, index);
+    const descriptors = [];
+    while (index < text.length && text[index] !== ",") {
+      const descriptorToken = readSrcsetDescriptorToken(text, index);
+      if (!descriptorToken.value) {
+        index = descriptorToken.nextIndex;
+        continue;
+      }
+      descriptors.push(descriptorToken.value);
+      index = descriptorToken.nextIndex;
+      index = skipSrcsetWhitespace(text, index);
+    }
+    if (index < text.length && text[index] === ",") {
+      index += 1;
+    }
+    let width = null;
+    let density = null;
+    for (const descriptor of descriptors) {
+      const token = descriptor.trim().toLowerCase();
+      if (!token) {
+        continue;
+      }
+      const widthMatch = token.match(/^(\d+)w$/);
+      if (widthMatch) {
+        const parsed = Number.parseInt(widthMatch[1], 10);
+        if (Number.isFinite(parsed)) {
+          width = parsed;
+        }
+        continue;
+      }
+      const densityMatch = token.match(/^(\d*\.?\d+)x$/);
+      if (densityMatch) {
+        const parsed = Number.parseFloat(densityMatch[1]);
+        if (Number.isFinite(parsed)) {
+          density = parsed;
+        }
+      }
+    }
+    out.push({
+      url,
+      descriptorText: descriptors.join(" "),
+      width,
+      density
+    });
+  }
+  return out;
+}
+function skipSrcsetWhitespace(value, index) {
+  let cursor = index;
+  while (cursor < value.length && /\s/u.test(value[cursor])) {
+    cursor += 1;
+  }
+  return cursor;
+}
+function skipSrcsetSeparators(value, index) {
+  let cursor = skipSrcsetWhitespace(value, index);
+  while (cursor < value.length && value[cursor] === ",") {
+    cursor += 1;
+    cursor = skipSrcsetWhitespace(value, cursor);
+  }
+  return cursor;
+}
+function readSrcsetUrlToken(value, index) {
+  let cursor = index;
+  let out = "";
+  const isDataUrl = value.slice(index, index + 5).toLowerCase().startsWith("data:");
+  while (cursor < value.length) {
+    const char = value[cursor];
+    if (/\s/u.test(char)) {
+      break;
+    }
+    if (char === "," && !isDataUrl) {
+      break;
+    }
+    out += char;
+    cursor += 1;
+  }
+  if (isDataUrl && out.endsWith(",") && cursor < value.length) {
+    out = out.slice(0, -1);
+  }
+  return {
+    value: out,
+    nextIndex: cursor
+  };
+}
+function readSrcsetDescriptorToken(value, index) {
+  let cursor = skipSrcsetWhitespace(value, index);
+  let out = "";
+  while (cursor < value.length) {
+    const char = value[cursor];
+    if (char === "," || /\s/u.test(char)) {
+      break;
+    }
+    out += char;
+    cursor += 1;
+  }
+  return {
+    value: out.trim(),
+    nextIndex: cursor
+  };
+}
 function removeNoise($) {
   for (const tag of STRIP_TAGS) {
     $(tag).remove();
@@ -18738,46 +19076,76 @@ function markInlineSelfHiddenFallback($) {
   });
 }
 function pruneSelfHiddenNodes($) {
-  const nodes = [];
-  $(`[${OPENSTEER_SELF_HIDDEN_ATTR}]`).each(function collectSelfHiddenNodes() {
-    nodes.push($(this));
-  });
-  nodes.sort((left, right) => right.parents().length - left.parents().length);
-  for (const el of nodes) {
-    if (!el[0]) {
+  for (const node of getElementsInReverseDocumentOrder($)) {
+    if (node.attribs?.[OPENSTEER_SELF_HIDDEN_ATTR] === void 0) {
       continue;
     }
+    const el = $(node);
     el.contents().each(function removeSelfHiddenText() {
       if (this.type === "text") {
         $(this).remove();
       }
     });
-    if (el.children().length === 0) {
+    if (!hasElementChildren(node)) {
       el.remove();
     }
   }
 }
-function hasDirectText($, el) {
-  return el.contents().filter(function hasDirectNodeText() {
-    return this.type === "text" && $(this).text().trim() !== "";
-  }).length > 0;
-}
-function hasTextDeep(el) {
-  return el.text().trim().length > 0;
+function getChildNodes(node) {
+  return node?.children ?? [];
 }
-function hasActionLabel(attrs) {
-  return typeof attrs["aria-label"] === "string" && attrs["aria-label"].trim() !== "" || typeof attrs["aria-labelledby"] === "string" && attrs["aria-labelledby"].trim() !== "" || typeof attrs["aria-describedby"] === "string" && attrs["aria-describedby"].trim() !== "" || typeof attrs.title === "string" && attrs.title.trim() !== "" || typeof attrs.placeholder === "string" && attrs.placeholder.trim() !== "" || typeof attrs.value === "string" && attrs.value.trim() !== "";
+function isElementLikeNode(node) {
+  return node?.type === "tag" || node?.type === "script" || node?.type === "style";
 }
-function unwrapActionNode($, el) {
-  if (hasTextDeep(el)) {
-    if (el.prev().length > 0) {
-      el.before(" ");
+function hasDirectText(node) {
+  if (!node) {
+    return false;
+  }
+  for (const child of getChildNodes(node)) {
+    if (child.type === "text" && (child.data || "").trim() !== "") {
+      return true;
     }
-    if (el.next().length > 0) {
-      el.after(" ");
+  }
+  return false;
+}
+function hasElementChildren(node) {
+  if (!node) {
+    return false;
+  }
+  for (const child of getChildNodes(node)) {
+    if (isElementLikeNode(child)) {
+      return true;
     }
   }
-  el.replaceWith(el.contents());
+  return false;
+}
+function hasTextDeepNode(node) {
+  if (!node) {
+    return false;
+  }
+  if (node.type === "text") {
+    return (node.data || "").trim() !== "";
+  }
+  for (const child of getChildNodes(node)) {
+    if (hasTextDeepNode(child)) {
+      return true;
+    }
+  }
+  return false;
+}
+function hasActionLabel(attrs) {
+  return typeof attrs["aria-label"] === "string" && attrs["aria-label"].trim() !== "" || typeof attrs["aria-labelledby"] === "string" && attrs["aria-labelledby"].trim() !== "" || typeof attrs["aria-describedby"] === "string" && attrs["aria-describedby"].trim() !== "" || typeof attrs.title === "string" && attrs.title.trim() !== "" || typeof attrs.placeholder === "string" && attrs.placeholder.trim() !== "" || typeof attrs.value === "string" && attrs.value.trim() !== "";
+}
+function unwrapActionNode($, el) {
+  if (hasTextDeepNode(el[0])) {
+    if (el.prev().length > 0) {
+      el.before(" ");
+    }
+    if (el.next().length > 0) {
+      el.after(" ");
+    }
+  }
+  el.replaceWith(el.contents());
 }
 function stripToAttrs(el, keep) {
   const attrs = el.attr() || {};
@@ -18790,7 +19158,7 @@ function stripToAttrs(el, keep) {
     if (typeof value !== "string") {
       continue;
     }
-    if (getAttrLimit(attr) !== void 0) {
+    if (shouldBoundAttr(attr)) {
       setBoundedAttr(el, attr, value);
     }
   }
@@ -18808,6 +19176,9 @@ function restoreBoundedAttr(el, attr, value) {
 function deduplicateImages(html) {
   const seen = /* @__PURE__ */ new Set();
   return html.replace(/<img\b([^>]*)>/gi, (full, attrContent) => {
+    if (/\bc\s*=/.test(attrContent)) {
+      return full;
+    }
     const srcMatch = attrContent.match(/\bsrc\s*=\s*(["']?)(.*?)\1/);
     const srcsetMatch = attrContent.match(/\bsrcset\s*=\s*(["'])(.*?)\1/);
     let src = null;
@@ -18826,59 +19197,155 @@ function deduplicateImages(html) {
     return full;
   });
 }
-function isPreservedImageElement($, el) {
-  const tag = (el[0]?.tagName || "").toLowerCase();
+function hasAttribute2(node, attr) {
+  return node?.attribs?.[attr] !== void 0;
+}
+function hasPictureAncestor(node) {
+  let current = node?.parent;
+  while (current) {
+    if (isElementLikeNode(current) && (current.tagName || "").toLowerCase() === "picture") {
+      return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+function pictureHasPreservedDescendant(node) {
+  if (!node) {
+    return false;
+  }
+  for (const child of getChildNodes(node)) {
+    if (!isElementLikeNode(child)) {
+      continue;
+    }
+    const tag = (child.tagName || "").toLowerCase();
+    if (tag === "img") {
+      return true;
+    }
+    if (tag === "source" && typeof child.attribs?.src === "string" && child.attribs.src.trim() !== "") {
+      return true;
+    }
+    if (tag === "source" && typeof child.attribs?.srcset === "string" && child.attribs.srcset.trim() !== "") {
+      return true;
+    }
+    if (pictureHasPreservedDescendant(child)) {
+      return true;
+    }
+  }
+  return false;
+}
+function isPreservedImageElement(node) {
+  const tag = (node?.tagName || "").toLowerCase();
   if (tag === "img") {
     return true;
   }
   if (tag === "picture") {
-    const hasImg = el.find("img").length > 0;
-    const hasSource = el.find("source[src], source[srcset]").length > 0;
-    return hasImg || hasSource;
+    return pictureHasPreservedDescendant(node);
   }
   if (tag === "source") {
-    const inPicture = el.parents("picture").length > 0;
-    const hasSrc = el.attr("src") != null && el.attr("src").trim() !== "" || el.attr("srcset") != null && el.attr("srcset").trim() !== "";
+    const inPicture = hasPictureAncestor(node);
+    const hasSrc = typeof node?.attribs?.src === "string" && node.attribs.src.trim() !== "" || typeof node?.attribs?.srcset === "string" && node.attribs.srcset.trim() !== "";
     return inPicture && hasSrc;
   }
   return false;
 }
+function getElementsInReverseDocumentOrder($) {
+  return $.root().find("*").toArray().reverse().filter((node) => node.type === "tag");
+}
+function getNodeDepth(node) {
+  let depth = 0;
+  let current = node.parent;
+  while (current) {
+    depth++;
+    current = current.parent;
+  }
+  return depth;
+}
+function getElementsByDepthDescending($) {
+  const elements = $.root().find("*").toArray().filter((node) => node.type === "tag");
+  const depths = /* @__PURE__ */ new Map();
+  for (const el of elements) {
+    depths.set(el, getNodeDepth(el));
+  }
+  return elements.sort((a, b) => (depths.get(b) ?? 0) - (depths.get(a) ?? 0));
+}
 function flattenExtractionTree($) {
-  const flatten = (root) => {
-    root.find("*").each(function flattenNode() {
-      const el = $(this);
-      const node = el[0];
-      if (!node) {
-        return;
-      }
-      const tag = (node.tagName || "").toLowerCase();
-      if (ROOT_TAGS.has(tag) || isBoundaryTag(tag)) {
-        return;
-      }
-      if (isPreservedImageElement($, el)) {
-        return;
-      }
-      if (tag === "a") {
-        el.children().each(function flattenAnchorChild() {
-          flatten($(this));
-        });
-        return;
-      }
-      const hasText = hasDirectText($, el);
-      if (hasText) {
-        return;
-      }
-      if (el.children().length === 0) {
-        el.remove();
-        return;
+  for (const node of getElementsInReverseDocumentOrder($)) {
+    const el = $(node);
+    const tag = (node.tagName || "").toLowerCase();
+    if (ROOT_TAGS.has(tag) || isBoundaryTag(tag) || isPreservedImageElement(node)) {
+      continue;
+    }
+    if (tag === "a" || hasDirectText(node)) {
+      continue;
+    }
+    if (!hasElementChildren(node)) {
+      el.remove();
+      continue;
+    }
+    el.replaceWith(el.contents());
+  }
+}
+function hasMarkedAncestor(el, attr) {
+  let current = el[0]?.parent;
+  while (current) {
+    if (!isElementLikeNode(current)) {
+      return false;
+    }
+    if (current.attribs?.[attr] !== void 0) {
+      return true;
+    }
+    current = current.parent;
+  }
+  return false;
+}
+function isIndicatorImage(node) {
+  return (node?.tagName || "").toLowerCase() === "img" && (hasAttribute2(node, "alt") || hasAttribute2(node, "src") || hasAttribute2(node, "srcset"));
+}
+function isIndicatorPictureSource(node) {
+  return (node?.tagName || "").toLowerCase() === "source" && hasPictureAncestor(node) && (hasAttribute2(node, "src") || hasAttribute2(node, "srcset"));
+}
+function isSemanticIndicator(node) {
+  const tag = (node?.tagName || "").toLowerCase();
+  if (tag === "svg") {
+    return true;
+  }
+  return hasAttribute2(node, "aria-label") || hasAttribute2(node, "title") || hasAttribute2(node, "data-icon") || node?.attribs?.role === "img";
+}
+function findIndicatorDescendant(root) {
+  if (!root) {
+    return void 0;
+  }
+  let firstImage;
+  let firstSource;
+  let firstSemantic;
+  const visit = (node) => {
+    if (!isElementLikeNode(node)) {
+      return false;
+    }
+    if (isIndicatorImage(node)) {
+      firstImage = node;
+      return true;
+    }
+    if (firstSource === void 0 && isIndicatorPictureSource(node)) {
+      firstSource = node;
+    }
+    if (firstSemantic === void 0 && isSemanticIndicator(node)) {
+      firstSemantic = node;
+    }
+    for (const child of getChildNodes(node)) {
+      if (visit(child)) {
+        return true;
       }
-      el.children().each(function flattenChild() {
-        flatten($(this));
-      });
-      el.replaceWith(el.contents());
-    });
+    }
+    return false;
   };
-  flatten($.root());
+  for (const child of getChildNodes(root)) {
+    if (visit(child)) {
+      return firstImage;
+    }
+  }
+  return firstImage ?? firstSource ?? firstSemantic;
 }
 function serializeForExtraction($, root) {
   const lines = [];
@@ -18947,7 +19414,7 @@ function serializeForExtraction($, root) {
     lines.push(`${"  ".repeat(depth)}</${tagName}>`);
   }
   traverse(root, 0);
-  return lines.join("\n");
+  return lines.map((l) => l.trim()).filter((l) => l.length > 0).join("");
 }
 function isClickable($, el, context) {
   if (context.hasPreMarked) {
@@ -19039,7 +19506,11 @@ function cleanForExtraction(html) {
     }
   });
   flattenExtractionTree($clean);
-  return deduplicateImages(serializeForExtraction($clean, $clean.root()[0]));
+  const root = $clean.root()[0];
+  if (root === void 0) {
+    return "";
+  }
+  return deduplicateImages(serializeForExtraction($clean, root));
 }
 function cleanForAction(html) {
   if (!html.trim()) {
@@ -19065,22 +19536,12 @@ function cleanForAction(html) {
   $(`[${clickableMark}]`).each(function markIndicators() {
     const el = $(this);
     const wrapperAttrs = el.attr() || {};
-    if (hasTextDeep(el) || hasActionLabel(wrapperAttrs)) {
+    if (hasTextDeepNode(el[0]) || hasActionLabel(wrapperAttrs)) {
       return;
     }
-    const imageIndicator = el.find("img[alt], img[src], img[srcset]").first();
-    if (imageIndicator.length) {
-      imageIndicator.attr(indicatorMark, "1");
-      return;
-    }
-    const pictureSourceIndicator = el.find("picture source[src], picture source[srcset]").first();
-    if (pictureSourceIndicator.length) {
-      pictureSourceIndicator.attr(indicatorMark, "1");
-      return;
-    }
-    const semanticIndicator = el.find('[aria-label], [title], [data-icon], [role="img"], svg').first();
-    if (semanticIndicator.length) {
-      semanticIndicator.attr(indicatorMark, "1");
+    const indicatorNode = findIndicatorDescendant(el[0]);
+    if (indicatorNode !== void 0) {
+      $(indicatorNode).attr(indicatorMark, "1");
     }
   });
   $(`[${clickableMark}]`).each(function removeEmptyClickable() {
@@ -19090,7 +19551,7 @@ function cleanForAction(html) {
     if (NATIVE_INTERACTIVE_TAGS.has(tag) || tag === "a") {
       return;
     }
-    if (el.children().length > 0 || hasDirectText($, el)) {
+    if (hasElementChildren(node) || hasDirectText(node)) {
       return;
     }
     const wrapperAttrs = el.attr() || {};
@@ -19116,46 +19577,31 @@ function cleanForAction(html) {
       current = ancestor.parent();
     }
   });
-  let changed = true;
-  while (changed) {
-    changed = false;
-    const nodes = [];
-    $("*").each(function collectNodes() {
-      nodes.push($(this));
-    });
-    nodes.sort((left, right) => right.parents().length - left.parents().length);
-    for (const el of nodes) {
-      const node = el[0];
-      if (!node) {
-        continue;
-      }
-      const tag = (node.tagName || "").toLowerCase();
-      if (ROOT_TAGS.has(tag) || isBoundaryTag(tag)) {
-        continue;
-      }
-      if (el.attr(clickableMark) !== void 0 || el.attr(indicatorMark) !== void 0) {
-        continue;
-      }
-      const insideClickable = el.parents(`[${clickableMark}]`).length > 0;
-      const preserveBranch = el.attr(branchMark) !== void 0;
-      const hasContent = el.children().length > 0 || hasDirectText($, el);
-      if (insideClickable || preserveBranch) {
-        if (!hasContent) {
-          el.remove();
-        } else {
-          unwrapActionNode($, el);
-        }
-        changed = true;
-        continue;
-      }
+  for (const node of getElementsByDepthDescending($)) {
+    const el = $(node);
+    const tag = (node.tagName || "").toLowerCase();
+    if (ROOT_TAGS.has(tag) || isBoundaryTag(tag)) {
+      continue;
+    }
+    if (el.attr(clickableMark) !== void 0 || el.attr(indicatorMark) !== void 0) {
+      continue;
+    }
+    const insideClickable = hasMarkedAncestor(el, clickableMark);
+    const preserveBranch = el.attr(branchMark) !== void 0;
+    const hasContent = hasElementChildren(node) || hasDirectText(node);
+    if (insideClickable || preserveBranch) {
       if (!hasContent) {
         el.remove();
-        changed = true;
-        continue;
+      } else {
+        unwrapActionNode($, el);
       }
-      unwrapActionNode($, el);
-      changed = true;
+      continue;
+    }
+    if (!hasContent) {
+      el.remove();
+      continue;
     }
+    unwrapActionNode($, el);
   }
   $.root().find("*").contents().each(function normalizeActionTextNodes() {
     if (this.type !== "text") {
@@ -19235,21 +19681,7 @@ function cleanForAction(html) {
       OPENSTEER_SPARSE_COUNTER_ATTR
     ]);
     if (clickable) {
-      for (const attr of [
-        "href",
-        "role",
-        "type",
-        "title",
-        "placeholder",
-        "value",
-        "aria-label",
-        "aria-labelledby",
-        "aria-describedby",
-        "aria-expanded",
-        "aria-pressed",
-        "aria-selected",
-        "aria-haspopup"
-      ]) {
+      for (const attr of ["href", "role", "type", "title", "placeholder", "value", "aria-label"]) {
         keep.add(attr);
       }
     }
@@ -19273,16 +19705,25 @@ function cleanForAction(html) {
   });
   return compactHtml(deduplicateImages($.html()));
 }
-var STRIP_TAGS, TEXT_ATTR_MAX, URL_ATTR_MAX, URL_ATTRS, TEXT_ATTRS, TRUNCATION_SUFFIX, NOISE_SELECTORS, VOID_TAGS2;
+var STRIP_TAGS, TEXT_ATTR_MAX, SRCSET_ATTR_MAX, MIDDLE_TRUNCATED_URL_ATTRS, TEXT_ATTRS, TRUNCATION_SUFFIX, MIDDLE_TRUNCATION_MARKER, MIDDLE_TRUNCATION_HEAD_MAX, MIDDLE_TRUNCATION_TAIL_MAX, SRCSET_CANDIDATE_HEAD_MAX, SRCSET_CANDIDATE_TAIL_MAX, SRCSET_COMPACT_CANDIDATE_HEAD_MAX, SRCSET_COMPACT_CANDIDATE_TAIL_MAX, SRCSET_FALLBACK_HEAD_MAX, SRCSET_FALLBACK_TAIL_MAX, NOISE_SELECTORS, VOID_TAGS2;
 var init_cleaner = __esm({
   "../runtime-core/src/sdk/snapshot/cleaner.ts"() {
     init_constants();
     STRIP_TAGS = /* @__PURE__ */ new Set(["script", "style", "noscript", "meta", "link", "template"]);
     TEXT_ATTR_MAX = 150;
-    URL_ATTR_MAX = 500;
-    URL_ATTRS = /* @__PURE__ */ new Set(["href", "src", "srcset"]);
+    SRCSET_ATTR_MAX = 160;
+    MIDDLE_TRUNCATED_URL_ATTRS = /* @__PURE__ */ new Set(["href", "src"]);
     TEXT_ATTRS = /* @__PURE__ */ new Set(["alt", "title", "aria-label", "placeholder", "value"]);
-    TRUNCATION_SUFFIX = " [truncated]";
+    TRUNCATION_SUFFIX = "...";
+    MIDDLE_TRUNCATION_MARKER = "...";
+    MIDDLE_TRUNCATION_HEAD_MAX = 40;
+    MIDDLE_TRUNCATION_TAIL_MAX = 20;
+    SRCSET_CANDIDATE_HEAD_MAX = 36;
+    SRCSET_CANDIDATE_TAIL_MAX = 12;
+    SRCSET_COMPACT_CANDIDATE_HEAD_MAX = 20;
+    SRCSET_COMPACT_CANDIDATE_TAIL_MAX = 8;
+    SRCSET_FALLBACK_HEAD_MAX = 56;
+    SRCSET_FALLBACK_TAIL_MAX = 20;
     NOISE_SELECTORS = [
       `[${OPENSTEER_HIDDEN_ATTR}]`,
       "[hidden]",
@@ -19821,9 +20262,9 @@ function renderNode(snapshot, node, nodesById, snapshotsByDocumentRef, snapshotI
   const snapshotAttributes = normalizeNodeAttributes(node.attributes);
   const authoredAttributes = stripInternalSnapshotAttributes(snapshotAttributes);
   const attributes = [...authoredAttributes];
-  const subtreeHidden = hasAttribute2(snapshotAttributes, OPENSTEER_HIDDEN_ATTR) || isLikelySubtreeHidden(node);
-  const selfHidden = !subtreeHidden && (hasAttribute2(snapshotAttributes, OPENSTEER_SELF_HIDDEN_ATTR) || isLikelySelfHidden(node, nodesById));
-  const interactive = !subtreeHidden && !selfHidden && (hasAttribute2(snapshotAttributes, OPENSTEER_INTERACTIVE_ATTR) || isLikelyInteractive(tagName, node, authoredAttributes));
+  const subtreeHidden = hasAttribute3(snapshotAttributes, OPENSTEER_HIDDEN_ATTR) || isLikelySubtreeHidden(node);
+  const selfHidden = !subtreeHidden && (hasAttribute3(snapshotAttributes, OPENSTEER_SELF_HIDDEN_ATTR) || isLikelySelfHidden(node, nodesById));
+  const interactive = !subtreeHidden && !selfHidden && (hasAttribute3(snapshotAttributes, OPENSTEER_INTERACTIVE_ATTR) || isLikelyInteractive(tagName, node, authoredAttributes));
   if (interactive) {
     attributes.push({ name: OPENSTEER_INTERACTIVE_ATTR, value: "1" });
   }
@@ -20141,7 +20582,7 @@ function parseOpacity(value) {
   const parsed = Number.parseFloat(value);
   return Number.isFinite(parsed) ? parsed : Number.NaN;
 }
-function hasAttribute2(attributes, name) {
+function hasAttribute3(attributes, name) {
   const normalizedName = name.toLowerCase();
   return attributes.some((attribute) => attribute.name.toLowerCase() === normalizedName);
 }
@@ -23471,12 +23912,12 @@ var init_runtime3 = __esm({
             async (timeout) => {
               let descriptor2;
               let data;
-              if (input.schema !== void 0) {
-                assertValidOpensteerExtractionSchemaRoot(input.schema);
+              if (input.template !== void 0) {
+                assertValidOpensteerExtractionTemplateRoot(input.template);
                 const fieldTargets = await timeout.runStep(
                   () => compileOpensteerExtractionFieldTargets({
                     pageRef,
-                    schema: input.schema,
+                    template: input.template,
                     dom: this.requireDom()
                   })
                 );
@@ -23508,7 +23949,7 @@ var init_runtime3 = __esm({
                     () => descriptors.write({
                       persist,
                       root: payload,
-                      schemaHash: canonicalJsonString(input.schema),
+                      templateHash: canonicalJsonString(input.template),
                       sourceUrl: pageInfo.url
                     })
                   );
@@ -23568,7 +24009,7 @@ var init_runtime3 = __esm({
             artifacts,
             data: {
               ...input.persist === void 0 ? {} : { persist: input.persist },
-              ...descriptor?.payload.schemaHash === void 0 ? {} : { schemaHash: descriptor.payload.schemaHash },
+              ...descriptor?.payload.templateHash === void 0 ? {} : { templateHash: descriptor.payload.templateHash },
               data: output.data
             },
             context: buildRuntimeTraceContext({
@@ -29171,8 +29612,29 @@ function assertSupportedCloudBrowserMode(browser) {
   }
 }
 function isMissingCloudSessionError(error) {
+  if (error instanceof OpensteerCloudRequestError) {
+    return error.statusCode === 404 && (error.code === void 0 || error.code === "CLOUD_SESSION_NOT_FOUND");
+  }
   return error instanceof Error && /\b404\b/.test(error.message);
 }
+function isRecoverableCloudSessionError(error) {
+  if (!(error instanceof OpensteerCloudRequestError)) {
+    return false;
+  }
+  if (error.statusCode === 404) {
+    return error.code === void 0 || error.code === "CLOUD_SESSION_NOT_FOUND";
+  }
+  return error.statusCode === 409 && error.code === "CLOUD_SESSION_STALE";
+}
+function isBootstrapRecoveryOperation(operation) {
+  return operation === "session.open" || operation === "instrumentation.route" || operation === "instrumentation.intercept-script";
+}
+function isReusableCloudSessionState(session) {
+  if (session.status === "closing" || session.status === "closed" || session.status === "failed") {
+    return false;
+  }
+  return !(typeof session.expiresAt === "number" && session.expiresAt <= Date.now() + CLOUD_SESSION_REUSE_EXPIRY_SKEW_MS);
+}
 function isLoopbackBaseUrl(baseUrl) {
   let url;
   try {
@@ -29182,7 +29644,7 @@ function isLoopbackBaseUrl(baseUrl) {
   }
   return url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "::1" || url.hostname === "[::1]";
 }
-var TEMPORARY_CLOUD_WORKSPACE_PREFIX, CloudSessionProxy;
+var TEMPORARY_CLOUD_WORKSPACE_PREFIX, CLOUD_SESSION_REUSE_EXPIRY_SKEW_MS, CloudSessionProxy;
 var init_session_proxy = __esm({
   "src/cloud/session-proxy.ts"() {
     init_src3();
@@ -29192,8 +29654,10 @@ var init_session_proxy = __esm({
     init_policy2();
     init_semantic_rest_client();
     init_automation_client();
+    init_client();
     init_workspace_sync();
     TEMPORARY_CLOUD_WORKSPACE_PREFIX = "opensteer-cloud-workspace-";
+    CLOUD_SESSION_REUSE_EXPIRY_SKEW_MS = 1e4;
     CloudSessionProxy = class {
       rootPath;
       workspace;
@@ -29207,6 +29671,8 @@ var init_session_proxy = __esm({
       automation;
       workspaceStore;
       syncWorkspaceOnClose = false;
+      liveSessionStateEstablished = false;
+      storedInstrumentation = [];
       constructor(cloud, options = {}) {
         this.cloud = cloud;
         this.workspace = options.workspace;
@@ -29236,15 +29702,12 @@ var init_session_proxy = __esm({
         if (this.client === void 0 && this.sessionId === void 0 && persisted !== void 0 && await this.isReusableCloudSession(persisted.sessionId)) {
           this.bindClient(persisted);
         }
-        if (this.automation) {
-          try {
-            const sessionInfo = await this.automation.getSessionInfo();
-            return {
-              ...sessionInfo,
-              ...this.workspace === void 0 ? {} : { workspace: this.workspace }
-            };
-          } catch {
-          }
+        const sessionInfo = this.automation ? await this.automation.getSessionInfo().catch(() => void 0) : void 0;
+        if (sessionInfo !== void 0) {
+          return {
+            ...sessionInfo,
+            ...this.workspace === void 0 ? {} : { workspace: this.workspace }
+          };
         }
         return {
           provider: {
@@ -29356,12 +29819,26 @@ var init_session_proxy = __esm({
         return this.invokeSemanticOperation("session.cookies", input);
       }
       async route(input) {
-        await this.ensureSession();
-        return this.requireAutomation().route(input);
+        const registration = await this.invokeBootstrapInstrumentationOperation(
+          "instrumentation.route",
+          (automation) => automation.route(input)
+        );
+        this.storedInstrumentation.push({
+          kind: "route",
+          input
+        });
+        return registration;
       }
       async interceptScript(input) {
-        await this.ensureSession();
-        return this.requireAutomation().interceptScript(input);
+        const registration = await this.invokeBootstrapInstrumentationOperation(
+          "instrumentation.intercept-script",
+          (automation) => automation.interceptScript(input)
+        );
+        this.storedInstrumentation.push({
+          kind: "intercept-script",
+          input
+        });
+        return registration;
       }
       async getStorageSnapshot(input = {}) {
         return this.invokeSemanticOperation("session.storage", input);
@@ -29409,6 +29886,8 @@ var init_session_proxy = __esm({
           this.client = void 0;
           this.sessionId = void 0;
           this.semanticGrant = void 0;
+          this.liveSessionStateEstablished = false;
+          this.storedInstrumentation.length = 0;
           if (this.cleanupRootOnClose) {
             await promises.rm(this.rootPath, { recursive: true, force: true }).catch(() => void 0);
           }
@@ -29436,6 +29915,8 @@ var init_session_proxy = __esm({
         this.automation = void 0;
         this.sessionId = void 0;
         this.semanticGrant = void 0;
+        this.liveSessionStateEstablished = false;
+        this.storedInstrumentation.length = 0;
         if (syncError !== void 0) {
           throw syncError;
         }
@@ -29483,6 +29964,7 @@ var init_session_proxy = __esm({
         };
         await this.writePersistedSession(record);
         this.bindClient(record, session.initialGrants?.semantic);
+        await this.restoreStoredInstrumentation();
       }
       async syncWorkspaceToCloud() {
         if (this.workspace === void 0) {
@@ -29494,6 +29976,7 @@ var init_session_proxy = __esm({
       bindClient(record, initialSemanticGrant) {
         this.sessionId = record.sessionId;
         this.semanticGrant = initialSemanticGrant?.kind === "semantic" ? initialSemanticGrant : void 0;
+        this.liveSessionStateEstablished = false;
         this.client = new OpensteerSemanticRestClient({
           getBaseUrl: async () => (await this.ensureSemanticGrant()).url,
           getAuthorizationHeader: async () => `Bearer ${(await this.ensureSemanticGrant()).token}`,
@@ -29501,6 +29984,19 @@ var init_session_proxy = __esm({
         });
         this.automation = new OpensteerCloudAutomationClient(this.cloud, record.sessionId);
       }
+      async restoreStoredInstrumentation() {
+        if (this.storedInstrumentation.length === 0) {
+          return;
+        }
+        const automation = this.requireAutomation();
+        for (const registration of this.storedInstrumentation) {
+          if (registration.kind === "route") {
+            await automation.route(registration.input);
+          } else {
+            await automation.interceptScript(registration.input);
+          }
+        }
+      }
       async ensureWorkspaceStore() {
         if (this.workspaceStore !== void 0) {
           return this.workspaceStore;
@@ -29523,13 +30019,22 @@ var init_session_proxy = __esm({
       async clearPersistedSession() {
         await clearPersistedSessionRecord(this.rootPath, "cloud").catch(() => void 0);
       }
+      async invalidateSession() {
+        await this.automation?.close().catch(() => void 0);
+        this.automation = void 0;
+        this.client = void 0;
+        this.sessionId = void 0;
+        this.semanticGrant = void 0;
+        this.liveSessionStateEstablished = false;
+        await this.clearPersistedSession();
+      }
       async isReusableCloudSession(sessionId, timeout) {
         try {
           const session = await this.cloud.getSession(sessionId, {
             signal: timeout?.signal,
             timeoutMs: timeout?.remainingMs()
           });
-          return session.status !== "closed" && session.status !== "failed";
+          return isReusableCloudSessionState(session);
         } catch (error) {
           if (isMissingCloudSessionError(error)) {
             return false;
@@ -29578,26 +30083,79 @@ var init_session_proxy = __esm({
         try {
           await this.ensureSemanticGrant(true);
           return true;
-        } catch {
+        } catch (refreshError) {
+          if (await this.resetStaleSession(refreshError)) {
+            throw refreshError;
+          }
           return false;
         }
       }
       async invokeSemanticOperation(operation, input, sessionInit = {}) {
-        return this.runOperationWithPolicy(operation, async (timeout) => {
+        return this.runOperationWithSessionRecovery(operation, async (timeout) => {
           await this.ensureSession(sessionInit, timeout);
           await this.ensureSemanticGrant(false, timeout);
-          return this.requireClient().invoke(operation, input, {
+          const output = await this.requireClient().invoke(operation, input, {
             signal: timeout.signal,
             timeoutMs: timeout.remainingMs()
           });
+          this.noteSuccessfulLiveOperation(operation);
+          return output;
         });
       }
       async invokeAutomationOperation(operation, invoke, sessionInit = {}) {
-        return this.runOperationWithPolicy(operation, async (timeout) => {
+        return this.runOperationWithSessionRecovery(operation, async (timeout) => {
           await this.ensureSession(sessionInit, timeout);
-          return invoke(this.requireAutomation());
+          const output = await invoke(this.requireAutomation());
+          this.noteSuccessfulLiveOperation(operation);
+          return output;
         });
       }
+      async invokeBootstrapInstrumentationOperation(operation, invoke) {
+        let recovered = false;
+        while (true) {
+          try {
+            await this.ensureSession();
+            return await invoke(this.requireAutomation());
+          } catch (error) {
+            const stale = await this.resetStaleSession(error);
+            if (!stale || recovered || !this.canRecoverWithFreshSession(operation)) {
+              throw error;
+            }
+            recovered = true;
+          }
+        }
+      }
+      async runOperationWithSessionRecovery(operation, invoke) {
+        return this.runOperationWithPolicy(operation, async (timeout) => {
+          let recovered = false;
+          while (true) {
+            try {
+              return await invoke(timeout);
+            } catch (error) {
+              const stale = await this.resetStaleSession(error);
+              if (!stale || recovered || !this.canRecoverWithFreshSession(operation)) {
+                throw error;
+              }
+              recovered = true;
+            }
+          }
+        });
+      }
+      async resetStaleSession(error) {
+        if (!isRecoverableCloudSessionError(error)) {
+          return false;
+        }
+        await this.invalidateSession();
+        return true;
+      }
+      canRecoverWithFreshSession(operation) {
+        return !this.liveSessionStateEstablished && isBootstrapRecoveryOperation(operation);
+      }
+      noteSuccessfulLiveOperation(operation) {
+        if (operation === "session.open" || operation === "page.list" || operation === "page.new" || operation === "page.activate" || operation === "page.close" || operation === "page.goto" || operation === "page.evaluate" || operation === "page.add-init-script" || operation === "page.snapshot" || operation === "dom.click" || operation === "dom.hover" || operation === "dom.input" || operation === "dom.scroll" || operation === "dom.extract" || operation === "network.query" || operation === "network.detail" || operation === "interaction.capture" || operation === "interaction.get" || operation === "interaction.diff" || operation === "interaction.replay" || operation === "scripts.capture" || operation === "artifact.read" || operation === "scripts.beautify" || operation === "scripts.deobfuscate" || operation === "scripts.sandbox" || operation === "captcha.solve" || operation === "session.cookies" || operation === "session.storage" || operation === "session.state" || operation === "session.fetch" || operation === "computer.execute") {
+          this.liveSessionStateEstablished = true;
+        }
+      }
       async runOperationWithPolicy(operation, invoke) {
         return runWithPolicyTimeout(this.policy.timeout, { operation }, invoke);
       }
@@ -29912,14 +30470,85 @@ var init_session_control = __esm({
   }
 });
 
+// src/internal/errors.ts
+function normalizeThrownOpensteerError2(error, fallbackMessage) {
+  if (isOpensteerProtocolError(error)) {
+    return toOpensteerError(error);
+  }
+  if (isBrowserCoreError(error)) {
+    return createOpensteerError(error.code, error.message, {
+      retriable: error.retriable,
+      ...error.details === void 0 ? {} : { details: error.details }
+    });
+  }
+  if (error instanceof OpensteerAttachAmbiguousError) {
+    return createOpensteerError("conflict", error.message, {
+      details: {
+        candidates: error.candidates,
+        code: error.code,
+        name: error.name
+      }
+    });
+  }
+  if (error instanceof Error && "opensteerError" in error && typeof error.opensteerError === "object" && error.opensteerError !== null) {
+    const oe = error.opensteerError;
+    return createOpensteerError(oe.code, oe.message, {
+      retriable: oe.retriable,
+      ...oe.capability === void 0 ? {} : { capability: oe.capability },
+      ...oe.details === void 0 ? {} : { details: oe.details }
+    });
+  }
+  if (error instanceof Error) {
+    return createOpensteerError("operation-failed", error.message, {
+      details: {
+        name: error.name
+      }
+    });
+  }
+  return createOpensteerError("internal", fallbackMessage, {
+    details: {
+      value: error
+    }
+  });
+}
+var init_errors5 = __esm({
+  "src/internal/errors.ts"() {
+    init_src();
+    init_src2();
+    init_cdp_discovery();
+  }
+});
+
 // src/sdk/opensteer.ts
 var opensteer_exports = {};
 __export(opensteer_exports, {
   Opensteer: () => Opensteer
 });
+function createSdkProtocolError(error, fallbackMessage) {
+  const normalized = normalizeThrownOpensteerError2(error, fallbackMessage);
+  return new OpensteerProtocolError(normalized.code, normalized.message, {
+    cause: error,
+    retriable: normalized.retriable,
+    ...normalized.capability === void 0 ? {} : { capability: normalized.capability },
+    ...normalized.details === void 0 ? {} : { details: normalized.details }
+  });
+}
+async function wrapSdkError(operation, fn) {
+  try {
+    return await fn();
+  } catch (error) {
+    if (isOpensteerProtocolError(error)) {
+      throw error;
+    }
+    throw createSdkProtocolError(error, `${operation} failed`);
+  }
+}
 function createUnsupportedBrowserController() {
   const fail = async () => {
-    throw new Error("browser.* helpers are only available in local mode.");
+    throw new OpensteerProtocolError(
+      "unsupported-operation",
+      "browser.* helpers are only available in local mode."
+    );
   };
   return {
     status: fail,
@@ -29932,7 +30561,10 @@ function normalizeTargetOptions(input) {
   const hasElement = input.element !== void 0;
   const hasSelector = input.selector !== void 0;
   if (hasElement && hasSelector) {
-    throw new Error("Specify exactly one of element, selector, or persist.");
+    throw new OpensteerProtocolError(
+      "invalid-argument",
+      "Specify exactly one of element, selector, or persist."
+    );
   }
   if (hasElement) {
     return {
@@ -29955,7 +30587,10 @@ function normalizeTargetOptions(input) {
     };
   }
   if (input.persist === void 0) {
-    throw new Error("Specify exactly one of element, selector, or persist.");
+    throw new OpensteerProtocolError(
+      "invalid-argument",
+      "Specify exactly one of element, selector, or persist."
+    );
   }
   return {
     target: {
@@ -30017,8 +30652,10 @@ function delay5(ms) {
 var SessionCookieJar, Opensteer;
 var init_opensteer = __esm({
   "src/sdk/opensteer.ts"() {
+    init_src2();
     init_browser_manager();
     init_env();
+    init_errors5();
     init_runtime_resolution();
     SessionCookieJar = class {
       domain;
@@ -30049,205 +30686,257 @@ var init_opensteer = __esm({
       dom;
       network;
       constructor(options = {}) {
-        const environment = resolveOpensteerEnvironment(options.rootDir);
-        const { provider, engineName, ...runtimeOptions } = options;
-        const runtimeConfig = resolveOpensteerRuntimeConfig({
-          ...provider === void 0 ? {} : { provider },
-          environment
-        });
-        if (runtimeConfig.provider.mode === "cloud") {
-          this.browserManager = void 0;
-          this.runtime = createOpensteerSemanticRuntime({
-            ...provider === void 0 ? {} : { provider },
-            ...engineName === void 0 ? {} : { engine: engineName },
-            environment,
-            runtimeOptions
-          });
-          this.browser = createUnsupportedBrowserController();
-        } else {
-          this.browserManager = new OpensteerBrowserManager({
-            ...runtimeOptions.rootDir === void 0 ? {} : { rootDir: runtimeOptions.rootDir },
-            ...runtimeOptions.rootPath === void 0 ? {} : { rootPath: runtimeOptions.rootPath },
-            ...runtimeOptions.workspace === void 0 ? {} : { workspace: runtimeOptions.workspace },
-            ...engineName === void 0 ? {} : { engineName },
-            environment,
-            ...runtimeOptions.browser === void 0 ? {} : { browser: runtimeOptions.browser },
-            ...runtimeOptions.launch === void 0 ? {} : { launch: runtimeOptions.launch },
-            ...runtimeOptions.context === void 0 ? {} : { context: runtimeOptions.context }
-          });
-          this.runtime = createOpensteerSemanticRuntime({
+        try {
+          const environment = resolveOpensteerEnvironment(options.rootDir);
+          const { provider, engineName, ...runtimeOptions } = options;
+          const runtimeConfig = resolveOpensteerRuntimeConfig({
             ...provider === void 0 ? {} : { provider },
-            ...engineName === void 0 ? {} : { engine: engineName },
-            environment,
-            runtimeOptions: {
-              ...runtimeOptions,
-              rootPath: this.browserManager.rootPath,
-              cleanupRootOnClose: this.browserManager.cleanupRootOnDisconnect
-            }
+            environment
           });
-          this.browser = {
-            status: () => this.browserManager.status(),
-            clone: (input) => this.browserManager.clonePersistentBrowser(input),
-            reset: () => this.browserManager.reset(),
-            delete: () => this.browserManager.delete()
+          if (runtimeConfig.provider.mode === "cloud") {
+            this.browserManager = void 0;
+            this.runtime = createOpensteerSemanticRuntime({
+              ...provider === void 0 ? {} : { provider },
+              ...engineName === void 0 ? {} : { engine: engineName },
+              environment,
+              runtimeOptions
+            });
+            this.browser = createUnsupportedBrowserController();
+          } else {
+            this.browserManager = new OpensteerBrowserManager({
+              ...runtimeOptions.rootDir === void 0 ? {} : { rootDir: runtimeOptions.rootDir },
+              ...runtimeOptions.rootPath === void 0 ? {} : { rootPath: runtimeOptions.rootPath },
+              ...runtimeOptions.workspace === void 0 ? {} : { workspace: runtimeOptions.workspace },
+              ...engineName === void 0 ? {} : { engineName },
+              environment,
+              ...runtimeOptions.browser === void 0 ? {} : { browser: runtimeOptions.browser },
+              ...runtimeOptions.launch === void 0 ? {} : { launch: runtimeOptions.launch },
+              ...runtimeOptions.context === void 0 ? {} : { context: runtimeOptions.context }
+            });
+            this.runtime = createOpensteerSemanticRuntime({
+              ...provider === void 0 ? {} : { provider },
+              ...engineName === void 0 ? {} : { engine: engineName },
+              environment,
+              runtimeOptions: {
+                ...runtimeOptions,
+                rootPath: this.browserManager.rootPath,
+                cleanupRootOnClose: this.browserManager.cleanupRootOnDisconnect
+              }
+            });
+            this.browser = {
+              status: () => wrapSdkError("browser.status", () => this.browserManager.status()),
+              clone: (input) => wrapSdkError("browser.clone", () => this.browserManager.clonePersistentBrowser(input)),
+              reset: () => wrapSdkError("browser.reset", () => this.browserManager.reset()),
+              delete: () => wrapSdkError("browser.delete", () => this.browserManager.delete())
+            };
+          }
+          this.dom = {
+            click: (input) => this.click(input),
+            hover: (input) => this.hover(input),
+            input: (input) => this.input(input),
+            scroll: (input) => this.scroll(input)
+          };
+          this.network = {
+            query: (input = {}) => wrapSdkError("network.query", () => this.runtime.queryNetwork(input)),
+            detail: (recordId, options2) => wrapSdkError(
+              "network.detail",
+              () => this.runtime.getNetworkDetail({ recordId, ...options2 })
+            )
           };
+        } catch (error) {
+          if (isOpensteerProtocolError(error)) {
+            throw error;
+          }
+          throw createSdkProtocolError(error, "Failed to initialize Opensteer");
         }
-        this.dom = {
-          click: (input) => this.click(input),
-          hover: (input) => this.hover(input),
-          input: (input) => this.input(input),
-          scroll: (input) => this.scroll(input)
-        };
-        this.network = {
-          query: (input = {}) => this.runtime.queryNetwork(input),
-          detail: (recordId, options2) => this.runtime.getNetworkDetail({ recordId, ...options2 })
-        };
       }
       async open(input = {}) {
-        return this.runtime.open(typeof input === "string" ? { url: input } : input);
+        return wrapSdkError(
+          "session.open",
+          () => this.runtime.open(typeof input === "string" ? { url: input } : input)
+        );
       }
       async info() {
-        return this.runtime.info();
+        return wrapSdkError("session.info", () => this.runtime.info());
       }
       async listPages(input = {}) {
-        return this.runtime.listPages(input);
+        return wrapSdkError("page.list", () => this.runtime.listPages(input));
       }
       async newPage(input = {}) {
-        return this.runtime.newPage(input);
+        return wrapSdkError("page.new", () => this.runtime.newPage(input));
       }
       async activatePage(input) {
-        return this.runtime.activatePage(input);
+        return wrapSdkError("page.activate", () => this.runtime.activatePage(input));
       }
       async closePage(input = {}) {
-        return this.runtime.closePage(input);
+        return wrapSdkError("page.close", () => this.runtime.closePage(input));
       }
       async goto(url, options = {}) {
-        return this.runtime.goto({
-          url,
-          ...options
-        });
+        return wrapSdkError(
+          "page.goto",
+          () => this.runtime.goto({
+            url,
+            ...options
+          })
+        );
       }
       async evaluate(input) {
-        const normalized = typeof input === "string" ? {
-          script: input
-        } : input;
-        return (await this.runtime.evaluate(normalized)).value;
+        return wrapSdkError("page.evaluate", async () => {
+          const normalized = typeof input === "string" ? {
+            script: input
+          } : input;
+          return (await this.runtime.evaluate(normalized)).value;
+        });
       }
       async addInitScript(input) {
-        return this.runtime.addInitScript(
-          typeof input === "string" ? {
-            script: input
-          } : input
+        return wrapSdkError(
+          "page.addInitScript",
+          () => this.runtime.addInitScript(
+            typeof input === "string" ? {
+              script: input
+            } : input
+          )
         );
       }
       async click(input) {
-        const { button, clickCount, modifiers, ...target } = input;
-        return this.runtime.click({
-          ...normalizeTargetOptions(target),
-          ...button === void 0 ? {} : { button },
-          ...clickCount === void 0 ? {} : { clickCount },
-          ...modifiers === void 0 ? {} : { modifiers }
+        return wrapSdkError("dom.click", () => {
+          const { button, clickCount, modifiers, ...target } = input;
+          return this.runtime.click({
+            ...normalizeTargetOptions(target),
+            ...button === void 0 ? {} : { button },
+            ...clickCount === void 0 ? {} : { clickCount },
+            ...modifiers === void 0 ? {} : { modifiers }
+          });
         });
       }
       async hover(input) {
-        return this.runtime.hover(normalizeTargetOptions(input));
+        return wrapSdkError("dom.hover", () => this.runtime.hover(normalizeTargetOptions(input)));
       }
       async input(input) {
-        return this.runtime.input({
-          ...normalizeTargetOptions(input),
-          text: input.text,
-          ...input.pressEnter === void 0 ? {} : { pressEnter: input.pressEnter }
-        });
+        return wrapSdkError(
+          "dom.input",
+          () => this.runtime.input({
+            ...normalizeTargetOptions(input),
+            text: input.text,
+            ...input.pressEnter === void 0 ? {} : { pressEnter: input.pressEnter }
+          })
+        );
       }
       async scroll(input) {
-        return this.runtime.scroll({
-          ...normalizeTargetOptions(input),
-          direction: input.direction,
-          amount: input.amount
-        });
+        return wrapSdkError(
+          "dom.scroll",
+          () => this.runtime.scroll({
+            ...normalizeTargetOptions(input),
+            direction: input.direction,
+            amount: input.amount
+          })
+        );
       }
       async extract(input) {
-        return (await this.runtime.extract(input)).data;
+        return wrapSdkError("extract", async () => (await this.runtime.extract(input)).data);
       }
       async waitForPage(input = {}) {
-        const baseline = new Set((await this.runtime.listPages()).pages.map((page) => page.pageRef));
-        const timeoutAt = Date.now() + (input.timeoutMs ?? 3e4);
-        const pollIntervalMs = input.pollIntervalMs ?? 100;
-        while (true) {
-          const match = (await this.runtime.listPages()).pages.find((page) => {
-            if (baseline.has(page.pageRef)) {
-              return false;
-            }
-            if (input.openerPageRef !== void 0 && page.openerPageRef !== input.openerPageRef) {
-              return false;
+        return wrapSdkError("page.waitForPage", async () => {
+          const baseline = new Set((await this.runtime.listPages()).pages.map((page) => page.pageRef));
+          const timeoutAt = Date.now() + (input.timeoutMs ?? 3e4);
+          const pollIntervalMs = input.pollIntervalMs ?? 100;
+          while (true) {
+            const match = (await this.runtime.listPages()).pages.find((page) => {
+              if (baseline.has(page.pageRef)) {
+                return false;
+              }
+              if (input.openerPageRef !== void 0 && page.openerPageRef !== input.openerPageRef) {
+                return false;
+              }
+              if (input.urlIncludes !== void 0 && !page.url.includes(input.urlIncludes)) {
+                return false;
+              }
+              return true;
+            });
+            if (match !== void 0) {
+              return match;
             }
-            if (input.urlIncludes !== void 0 && !page.url.includes(input.urlIncludes)) {
-              return false;
+            if (Date.now() >= timeoutAt) {
+              throw new OpensteerProtocolError("timeout", "waitForPage timed out");
             }
-            return true;
-          });
-          if (match !== void 0) {
-            return match;
-          }
-          if (Date.now() >= timeoutAt) {
-            throw new Error("waitForPage timed out");
+            await delay5(pollIntervalMs);
           }
-          await delay5(pollIntervalMs);
-        }
-      }
-      async snapshot(mode = "action") {
-        return (await this.runtime.snapshot({ mode })).html;
+        });
       }
       async cookies(domain) {
-        return new SessionCookieJar(
-          await this.runtime.getCookies(domain === void 0 ? {} : { domain })
+        return wrapSdkError(
+          "session.cookies",
+          async () => new SessionCookieJar(await this.runtime.getCookies(domain === void 0 ? {} : { domain }))
         );
       }
       async storage(domain, type = "local") {
-        const snapshot = await this.runtime.getStorageSnapshot(domain === void 0 ? {} : { domain });
-        const domainSnapshot = pickStorageDomainSnapshot(snapshot, domain);
-        if (domainSnapshot === void 0) {
-          return {};
-        }
-        const entries = type === "local" ? domainSnapshot.localStorage : domainSnapshot.sessionStorage;
-        return Object.fromEntries(entries.map((entry) => [entry.key, entry.value]));
+        return wrapSdkError("session.storage", async () => {
+          const snapshot = await this.runtime.getStorageSnapshot(
+            domain === void 0 ? {} : { domain }
+          );
+          const domainSnapshot = pickStorageDomainSnapshot(snapshot, domain);
+          if (domainSnapshot === void 0) {
+            return {};
+          }
+          const entries = type === "local" ? domainSnapshot.localStorage : domainSnapshot.sessionStorage;
+          return Object.fromEntries(entries.map((entry) => [entry.key, entry.value]));
+        });
       }
       async state(domain) {
-        return this.runtime.getBrowserState(domain === void 0 ? {} : { domain });
+        return wrapSdkError(
+          "session.state",
+          () => this.runtime.getBrowserState(domain === void 0 ? {} : { domain })
+        );
       }
       async fetch(url, options = {}) {
-        const input = buildFetchInput(url, options);
-        const result = await this.runtime.fetch(input);
-        if (result.response === void 0) {
-          throw new Error(result.note ?? `session.fetch did not produce a response for ${url}`);
-        }
-        return toResponse(result.response);
+        return wrapSdkError("session.fetch", async () => {
+          const input = buildFetchInput(url, options);
+          const result = await this.runtime.fetch(input);
+          if (result.response === void 0) {
+            throw new OpensteerProtocolError(
+              "operation-failed",
+              result.note ?? `session.fetch did not produce a response for ${url}`
+            );
+          }
+          return toResponse(result.response);
+        });
       }
       async computerExecute(input) {
-        return this.runtime.computerExecute(input);
+        return wrapSdkError("session.computerExecute", () => this.runtime.computerExecute(input));
       }
       async route(input) {
-        return this.requireOwnedInstrumentationRuntime("route").route(input);
+        return wrapSdkError(
+          "session.route",
+          () => this.requireOwnedInstrumentationRuntime("route").route(input)
+        );
       }
       async interceptScript(input) {
-        return this.requireOwnedInstrumentationRuntime("interceptScript").interceptScript(input);
+        return wrapSdkError(
+          "session.interceptScript",
+          () => this.requireOwnedInstrumentationRuntime("interceptScript").interceptScript(input)
+        );
       }
       async close() {
-        if (this.browserManager === void 0 || this.browserManager.mode === "temporary") {
-          return this.runtime.close();
-        }
-        const output = await this.runtime.close();
-        await this.browserManager.close();
-        return output;
+        return wrapSdkError("session.close", async () => {
+          if (this.browserManager === void 0 || this.browserManager.mode === "temporary") {
+            return this.runtime.close();
+          }
+          const output = await this.runtime.close();
+          await this.browserManager.close();
+          return output;
+        });
       }
       async disconnect() {
-        await this.runtime.disconnect();
+        return wrapSdkError("session.disconnect", () => this.runtime.disconnect());
       }
       requireOwnedInstrumentationRuntime(method) {
         if (typeof this.runtime.route === "function" && typeof this.runtime.interceptScript === "function") {
           return this.runtime;
         }
-        throw new Error(`${method}() is not available for this session runtime.`);
+        throw new OpensteerProtocolError(
+          "unsupported-operation",
+          `${method}() is not available for this session runtime.`
+        );
       }
     };
   }
@@ -30255,7 +30944,7 @@ var init_opensteer = __esm({
 
 // package.json
 var package_default = {
-  version: "0.9.4"};
+  version: "0.9.6"};
 
 // src/cli/bin.ts
 init_browser_manager();
@@ -30270,6 +30959,110 @@ async function loadCliEnvironment(cwd) {
   loadEnvironment(cwd);
 }
 
+// src/cli/errors.ts
+init_src();
+init_src2();
+var CliError = class extends Error {
+  type;
+  usage;
+  constructor(type, message, usage) {
+    super(message);
+    this.name = "CliError";
+    this.type = type;
+    this.usage = usage;
+  }
+  format() {
+    return this.usage === void 0 ? this.message : `${this.message}
+Usage: ${this.usage}`;
+  }
+};
+function isCliError(value) {
+  return value instanceof CliError;
+}
+function formatCliErrorOutput(error) {
+  if (isCliError(error)) {
+    return {
+      success: false,
+      error: error.format(),
+      type: error.type
+    };
+  }
+  if (isOpensteerProtocolError(error)) {
+    return {
+      success: false,
+      error: error.message,
+      code: error.code,
+      retriable: error.retriable
+    };
+  }
+  if (isBrowserCoreError(error)) {
+    return {
+      success: false,
+      error: error.message,
+      code: error.code,
+      retriable: error.retriable
+    };
+  }
+  if (error instanceof Error && "opensteerError" in error) {
+    const oe = error.opensteerError;
+    return {
+      success: false,
+      error: oe.message,
+      code: oe.code,
+      retriable: oe.retriable
+    };
+  }
+  if (error instanceof SyntaxError) {
+    return {
+      success: false,
+      error: error.message,
+      type: "invalid_value"
+    };
+  }
+  return {
+    success: false,
+    error: error instanceof Error ? error.message : String(error)
+  };
+}
+function emitWarning(warning) {
+  process.stderr.write(`${JSON.stringify({ warning })}
+`);
+}
+var CLI_USAGE_HINTS = {
+  "session.open": "opensteer open <url> [--workspace <id>]",
+  "page.goto": "opensteer goto <url>",
+  "page.evaluate": "opensteer evaluate <script>",
+  "page.add-init-script": "opensteer init-script <script>",
+  "dom.click": "opensteer click <element> --persist <key>",
+  "dom.hover": "opensteer hover <element> --persist <key>",
+  "dom.input": "opensteer input <element> <text> --persist <key>",
+  "dom.scroll": "opensteer scroll <direction> <amount> --persist <key>",
+  "dom.extract": "opensteer extract <template> --persist <key>",
+  "network.detail": "opensteer network detail <recordId>",
+  "session.fetch": "opensteer fetch <url>",
+  "captcha.solve": "opensteer captcha solve --provider <name> --api-key <key>",
+  "scripts.capture": "opensteer scripts capture",
+  "scripts.beautify": "opensteer scripts beautify <artifactId>",
+  "scripts.deobfuscate": "opensteer scripts deobfuscate <artifactId>",
+  "scripts.sandbox": "opensteer scripts sandbox <artifactId>",
+  "interaction.capture": "opensteer interaction capture",
+  "interaction.get": "opensteer interaction get <traceId>",
+  "interaction.replay": "opensteer interaction replay <traceId>",
+  "interaction.diff": "opensteer interaction diff <leftTraceId> <rightTraceId>",
+  "artifact.read": "opensteer artifact read <artifactId>",
+  "computer.click": "opensteer computer click <x> <y>",
+  "computer.type": "opensteer computer type <text>",
+  "computer.key": "opensteer computer key <key>",
+  "computer.scroll": "opensteer computer scroll <x> <y> --dx <n> --dy <n>",
+  "computer.move": "opensteer computer move <x> <y>",
+  "computer.drag": "opensteer computer drag <x1> <y1> <x2> <y2>",
+  "computer.screenshot": "opensteer computer screenshot",
+  exec: "opensteer exec <expression>",
+  record: "opensteer record --url <url> --workspace <id>",
+  "browser.inspect": "opensteer browser inspect <endpoint>",
+  "browser.clone": "opensteer browser clone --source-user-data-dir <path>"
+};
+
 // src/cli/help.ts
 function getHelpText() {
   return `Opensteer CLI
@@ -30288,11 +31081,11 @@ Navigation:
 
 DOM:
   snapshot [action|extraction]
-  click <element> [--button left|middle|right] [--persist <key>] [--capture-network <label>]
-  hover <element> [--persist <key>] [--capture-network <label>]
-  input <element> <text> [--press-enter] [--persist <key>] [--capture-network <label>]
-  scroll <direction> <amount> [--element <n>] [--persist <key>] [--capture-network <label>]
-  extract <schema> [--persist <key>]
+  click <element> --persist <key> [--button left|middle|right] [--capture-network <label>]
+  hover <element> --persist <key> [--capture-network <label>]
+  input <element> <text> --persist <key> [--press-enter] [--capture-network <label>]
+  scroll <direction> <amount> --persist <key> [--element <n>] [--capture-network <label>]
+  extract <template> --persist <key>
   evaluate <script>
   init-script <script>
 
@@ -30531,7 +31324,7 @@ function parseCommandLine(argv) {
     const key = token.slice(2, separator === -1 ? void 0 : separator);
     const spec = CLI_OPTION_SPECS[key];
     if (spec === void 0) {
-      throw new Error(`Unknown option: --${key}.`);
+      throw new CliError("unknown_option", `Unknown option: --${key}.`);
     }
     if (separator !== -1) {
       rawOptions.set(key, [...rawOptions.get(key) ?? [], token.slice(separator + 1)]);
@@ -30560,7 +31353,8 @@ function parseCommandLine(argv) {
       continue;
     }
     if (next === void 0 || next.startsWith("--")) {
-      throw new Error(
+      throw new CliError(
+        "missing_arguments",
         `Option "--${key}" requires a value.${next?.startsWith("--") === true ? ` Use "--${key}=<value>" when the value begins with "--".` : ``}`
       );
     }
@@ -30606,10 +31400,14 @@ function parseCommandLine(argv) {
   const autoLocalView = readOptionalBoolean(rawOptions, "auto");
   const noAutoLocalView = readOptionalBoolean(rawOptions, "no-auto");
   if (autoLocalView === true && noAutoLocalView === true) {
-    throw new Error('Options "--auto" and "--no-auto" cannot be combined.');
+    throw new CliError("invalid_option", 'Options "--auto" and "--no-auto" cannot be combined.');
   }
   if (command[0] !== "view" && (autoLocalView !== void 0 || noAutoLocalView !== void 0)) {
-    throw new Error('Options "--auto" and "--no-auto" are only supported with "view".');
+    throw new CliError(
+      "invalid_option",
+      'Options "--auto" and "--no-auto" are only supported with "view".',
+      "opensteer view --auto"
+    );
   }
   const global = readOptionalBoolean(rawOptions, "global");
   const yes = readOptionalBoolean(rawOptions, "yes");
@@ -30665,7 +31463,7 @@ function parseKeyValueList(values) {
     values.map((entry) => {
       const separator = entry.indexOf("=");
       if (separator <= 0) {
-        throw new Error(`Expected NAME=VALUE, received "${entry}".`);
+        throw new CliError("invalid_value", `Expected NAME=VALUE, received "${entry}".`);
       }
       return [entry.slice(0, separator), entry.slice(separator + 1)];
     })
@@ -30696,7 +31494,7 @@ function readOptionalBoolean(options, name) {
   if (value === "false") {
     return false;
   }
-  throw new Error(`Option "--${name}" must be true or false.`);
+  throw new CliError("invalid_value", `Option "--${name}" must be true or false.`);
 }
 function readOptionalNumber(options, name) {
   const value = readSingle(options, name);
@@ -30705,13 +31503,20 @@ function readOptionalNumber(options, name) {
   }
   const parsed = Number(value);
   if (!Number.isFinite(parsed)) {
-    throw new Error(`Option "--${name}" must be a number.`);
+    throw new CliError("invalid_value", `Option "--${name}" must be a number.`);
   }
   return parsed;
 }
 function readJsonValue(options, name) {
   const value = readSingle(options, name);
-  return value === void 0 ? void 0 : JSON.parse(value);
+  if (value === void 0) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new CliError("invalid_value", `Option "--${name}" contains invalid JSON.`);
+  }
 }
 function readJsonObject(options, name) {
   const parsed = readJsonValue(options, name);
@@ -30719,7 +31524,7 @@ function readJsonObject(options, name) {
     return void 0;
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`Option "--${name}" must be a JSON object.`);
+    throw new CliError("invalid_value", `Option "--${name}" must be a JSON object.`);
   }
   return parsed;
 }
@@ -30729,7 +31534,7 @@ function readJsonArray(options, name) {
     return void 0;
   }
   if (!Array.isArray(parsed)) {
-    throw new Error(`Option "--${name}" must be a JSON array.`);
+    throw new CliError("invalid_value", `Option "--${name}" must be a JSON array.`);
   }
   return parsed;
 }
@@ -30749,7 +31554,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "session.open": {
       const url = parsed.rest[0];
       if (url === void 0) {
-        throw new Error("open requires a URL.");
+        throw new CliError("missing_arguments", "open requires a URL.", CLI_USAGE_HINTS[operation]);
       }
       return {
         url,
@@ -30782,7 +31587,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "page.goto": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("goto requires a URL.");
+        throw new CliError("missing_arguments", "goto requires a URL.", CLI_USAGE_HINTS[operation]);
       }
       const captureNetwork = readSingle(parsed.rawOptions, "capture-network");
       return {
@@ -30794,14 +31599,14 @@ async function buildOperationInput(operation, parsed, runtime) {
       return parsed.rest[0] === void 0 ? {} : { mode: parsed.rest[0] };
     case "page.evaluate":
       if (parsed.rest[0] === void 0) {
-        throw new Error("evaluate requires a script.");
+        throw new CliError("missing_arguments", "evaluate requires a script.", CLI_USAGE_HINTS[operation]);
       }
       return {
         script: joinRest(parsed.rest, 0)
       };
     case "page.add-init-script":
       if (parsed.rest[0] === void 0) {
-        throw new Error("init-script requires a script.");
+        throw new CliError("missing_arguments", "init-script requires a script.", CLI_USAGE_HINTS[operation]);
       }
       return {
         script: joinRest(parsed.rest, 0)
@@ -30817,7 +31622,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       return buildElementTargetInput(parsed, "hover");
     case "dom.input": {
       if (parsed.rest[1] === void 0) {
-        throw new Error("input requires an element number and text.");
+        throw new CliError("missing_arguments", "input requires an element number and text.", CLI_USAGE_HINTS[operation]);
       }
       const pressEnter = readOptionalBoolean(parsed.rawOptions, "press-enter");
       return {
@@ -30842,18 +31647,18 @@ async function buildOperationInput(operation, parsed, runtime) {
         },
         direction,
         amount,
-        ...persist === void 0 ? {} : { persist },
+        persist,
         ...captureNetwork === void 0 ? {} : { captureNetwork }
       };
     }
     case "dom.extract": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("extract requires a schema.");
+        throw new CliError("missing_arguments", "extract requires a template.", CLI_USAGE_HINTS[operation]);
       }
-      const persist = readExtractPersistKey(parsed);
+      const persist = readPersistKey(parsed, "extract");
       return {
-        schema: parseRequiredJsonObjectArgument(joinRest(parsed.rest, 0), "extract schema"),
-        ...persist === void 0 ? {} : { persist }
+        persist,
+        template: parseRequiredJsonObjectArgument(joinRest(parsed.rest, 0), "extract template")
       };
     }
     case "network.query": {
@@ -30884,7 +31689,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "network.detail": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("network detail requires a record id.");
+        throw new CliError("missing_arguments", "network detail requires a record id.", CLI_USAGE_HINTS[operation]);
       }
       const probeFlag = readOptionalBoolean(parsed.rawOptions, "probe");
       return {
@@ -30895,7 +31700,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "session.fetch": {
       const url = parsed.rest[0];
       if (url === void 0) {
-        throw new Error("fetch requires a URL.");
+        throw new CliError("missing_arguments", "fetch requires a URL.", CLI_USAGE_HINTS[operation]);
       }
       const bodyJson = readJsonValue(parsed.rawOptions, "body");
       const bodyText = readSingle(parsed.rawOptions, "body-text");
@@ -30903,7 +31708,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       const query = parseKeyValueList(parsed.rawOptions.get("query"));
       const headers = parseKeyValueList(parsed.rawOptions.get("header"));
       if (bodyJson !== void 0 && bodyText !== void 0) {
-        throw new Error('Use either "--body" or "--body-text", not both.');
+        throw new CliError("invalid_option", 'Use either "--body" or "--body-text", not both.');
       }
       const transport = readSingle(parsed.rawOptions, "transport");
       const cookies = readOptionalBoolean(parsed.rawOptions, "cookies");
@@ -30934,7 +31739,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       const siteKey = readSingle(parsed.rawOptions, "site-key");
       const pageUrl = readSingle(parsed.rawOptions, "page-url");
       if (provider === void 0 || apiKey === void 0) {
-        throw new Error('captcha solve requires "--provider" and "--api-key".');
+        throw new CliError("missing_arguments", 'captcha solve requires "--provider" and "--api-key".', CLI_USAGE_HINTS[operation]);
       }
       return {
         provider: readCaptchaProvider(provider),
@@ -30964,7 +31769,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "scripts.beautify":
     case "scripts.deobfuscate": {
       if (parsed.rest[0] === void 0) {
-        throw new Error(`${parsed.command.join(" ")} requires an artifact id.`);
+        throw new CliError("missing_arguments", `${parsed.command.join(" ")} requires an artifact id.`, CLI_USAGE_HINTS[operation]);
       }
       const persist = readOptionalBoolean(parsed.rawOptions, "persist");
       return {
@@ -30974,7 +31779,7 @@ async function buildOperationInput(operation, parsed, runtime) {
     }
     case "scripts.sandbox":
       if (parsed.rest[0] === void 0) {
-        throw new Error("scripts sandbox requires an artifact id.");
+        throw new CliError("missing_arguments", "scripts sandbox requires an artifact id.", CLI_USAGE_HINTS[operation]);
       }
       {
         const fidelity = readSingle(parsed.rawOptions, "fidelity");
@@ -31023,14 +31828,14 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "interaction.get":
     case "interaction.replay":
       if (parsed.rest[0] === void 0) {
-        throw new Error(`${parsed.command.join(" ")} requires a trace id.`);
+        throw new CliError("missing_arguments", `${parsed.command.join(" ")} requires a trace id.`, CLI_USAGE_HINTS[operation]);
       }
       return {
         traceId: parsed.rest[0]
       };
     case "interaction.diff":
       if (parsed.rest[0] === void 0 || parsed.rest[1] === void 0) {
-        throw new Error("interaction diff requires two trace ids.");
+        throw new CliError("missing_arguments", "interaction diff requires two trace ids.", CLI_USAGE_HINTS[operation]);
       }
       return {
         leftTraceId: parsed.rest[0],
@@ -31038,7 +31843,7 @@ async function buildOperationInput(operation, parsed, runtime) {
       };
     case "artifact.read":
       if (parsed.rest[0] === void 0) {
-        throw new Error("artifact read requires an artifact id.");
+        throw new CliError("missing_arguments", "artifact read requires an artifact id.", CLI_USAGE_HINTS[operation]);
       }
       return {
         artifactId: parsed.rest[0]
@@ -31046,7 +31851,8 @@ async function buildOperationInput(operation, parsed, runtime) {
     case "session.close":
       return {};
     default:
-      throw new Error(
+      throw new CliError(
+        "unsupported_operation",
         `${operation} does not have a direct CLI input shape. Use a supported command or the SDK.`
       );
   }
@@ -31063,7 +31869,7 @@ function buildElementTargetInput(parsed, verb) {
       kind: "element",
       element
     },
-    ...persist === void 0 ? {} : { persist },
+    persist,
     ...captureNetwork === void 0 ? {} : { captureNetwork }
   };
 }
@@ -31093,7 +31899,7 @@ function buildComputerExecuteInput(parsed) {
     }
     case "type":
       if (parsed.rest[0] === void 0) {
-        throw new Error("computer type requires text.");
+        throw new CliError("missing_arguments", "computer type requires text.");
       }
       return {
         action: {
@@ -31104,7 +31910,7 @@ function buildComputerExecuteInput(parsed) {
       };
     case "key": {
       if (parsed.rest[0] === void 0) {
-        throw new Error("computer key requires a key.");
+        throw new CliError("missing_arguments", "computer key requires a key.");
       }
       const modifiers = readKeyModifiers(readSingle(parsed.rawOptions, "modifiers"));
       return {
@@ -31120,7 +31926,7 @@ function buildComputerExecuteInput(parsed) {
       const dx = readOptionalNumber(parsed.rawOptions, "dx");
       const dy = readOptionalNumber(parsed.rawOptions, "dy");
       if (dx === void 0 || dy === void 0) {
-        throw new Error('computer scroll requires "--dx" and "--dy".');
+        throw new CliError("missing_arguments", 'computer scroll requires "--dx" and "--dy".');
       }
       return {
         action: {
@@ -31175,49 +31981,50 @@ function buildComputerExecuteInput(parsed) {
         }
       };
     default:
-      throw new Error(`Unknown computer command: ${parsed.command.join(" ")}`);
+      throw new CliError("unknown_command", `Unknown computer command: ${parsed.command.join(" ")}`);
   }
 }
 async function resolvePageRefByIndex(runtime, index) {
   const pages = (await runtime.listPages({})).pages;
   const page = pages[index - 1];
   if (page === void 0) {
-    throw new Error(`tab ${String(index)} does not exist.`);
+    throw new CliError("invalid_value", `tab ${String(index)} does not exist.`);
   }
   return page.pageRef;
 }
 function readRequiredPositiveInteger(value, message) {
   const parsed = readRequiredNumber(value, message);
   if (!Number.isInteger(parsed) || parsed < 1) {
-    throw new Error(message);
+    throw new CliError("missing_arguments", message);
   }
   return parsed;
 }
 function readRequiredNumber(value, message) {
   if (value === void 0) {
-    throw new Error(message);
+    throw new CliError("missing_arguments", message);
   }
   const parsed = Number(value);
   if (!Number.isFinite(parsed)) {
-    throw new Error(message);
+    throw new CliError("missing_arguments", message);
   }
   return parsed;
 }
 function readSingleDirection(value) {
   if (value === void 0 || !SCROLL_DIRECTIONS.has(value)) {
-    throw new Error("scroll requires a direction: up, down, left, or right.");
+    throw new CliError("missing_arguments", "scroll requires a direction: up, down, left, or right.");
   }
   return value;
 }
 function readClickButton(value) {
   if (value === void 0 || !CLICK_BUTTONS.has(value)) {
-    throw new Error('Expected "--button" to be one of: left, middle, right.');
+    throw new CliError("invalid_value", 'Expected "--button" to be one of: left, middle, right.');
   }
   return value;
 }
 function readFetchTransport(value) {
   if (value === void 0 || !FETCH_TRANSPORTS.has(value)) {
-    throw new Error(
+    throw new CliError(
+      "invalid_value",
       'Expected "--transport" to be one of: auto, direct, matched-tls, context, page.'
     );
   }
@@ -31225,31 +32032,31 @@ function readFetchTransport(value) {
 }
 function readCaptchaProvider(value) {
   if (value === void 0 || !CAPTCHA_PROVIDERS.has(value)) {
-    throw new Error('Expected "--provider" to be one of: 2captcha, capsolver.');
+    throw new CliError("invalid_value", 'Expected "--provider" to be one of: 2captcha, capsolver.');
   }
   return value;
 }
 function readCaptchaType(value) {
   if (value === void 0 || !CAPTCHA_TYPES.has(value)) {
-    throw new Error('Expected "--type" to be one of: recaptcha-v2, hcaptcha, turnstile.');
+    throw new CliError("invalid_value", 'Expected "--type" to be one of: recaptcha-v2, hcaptcha, turnstile.');
   }
   return value;
 }
 function readSandboxFidelity(value) {
   if (value === void 0 || !SANDBOX_FIDELITIES.has(value)) {
-    throw new Error('Expected "--fidelity" to be one of: minimal, standard, full.');
+    throw new CliError("invalid_value", 'Expected "--fidelity" to be one of: minimal, standard, full.');
   }
   return value;
 }
 function readSandboxClockMode(value) {
   if (value === void 0 || !SANDBOX_CLOCK_MODES.has(value)) {
-    throw new Error('Expected "--clock" to be one of: real, manual.');
+    throw new CliError("invalid_value", 'Expected "--clock" to be one of: real, manual.');
   }
   return value;
 }
 function readScreenshotFormat(value) {
   if (value === void 0 || !SCREENSHOT_FORMATS.has(value)) {
-    throw new Error('Expected "--format" to be one of: png, jpeg, webp.');
+    throw new CliError("invalid_value", 'Expected "--format" to be one of: png, jpeg, webp.');
   }
   return value;
 }
@@ -31260,7 +32067,7 @@ function readKeyModifiers(value) {
   }
   for (const modifier of modifiers) {
     if (!KEY_MODIFIERS.has(modifier)) {
-      throw new Error('Expected "--modifiers" to contain only: Shift, Control, Alt, Meta.');
+      throw new CliError("invalid_value", 'Expected "--modifiers" to contain only: Shift, Control, Alt, Meta.');
     }
   }
   return [...new Set(modifiers)];
@@ -31268,30 +32075,22 @@ function readKeyModifiers(value) {
 function readPersistKey(parsed, verb) {
   const value = readSingle(parsed.rawOptions, "persist");
   if (value === void 0) {
-    return void 0;
-  }
-  if (value === "true" || value === "false") {
-    throw new Error(`${verb} requires "--persist <key>" when using --persist.`);
-  }
-  if (verb === "scroll" && readOptionalNumber(parsed.rawOptions, "element") === void 0) {
-    throw new Error('scroll requires "--element <n>" when using "--persist <key>".');
-  }
-  return value;
-}
-function readExtractPersistKey(parsed) {
-  const value = readSingle(parsed.rawOptions, "persist");
-  if (value === void 0) {
-    return void 0;
+    throw new CliError("missing_arguments", `${verb} requires "--persist <key>".`);
   }
   if (value === "true" || value === "false") {
-    throw new Error('extract requires "--persist <key>" when using --persist.');
+    throw new CliError("missing_arguments", `${verb} requires "--persist <key>".`);
   }
   return value;
 }
 function parseRequiredJsonObjectArgument(value, label) {
-  const parsed = JSON.parse(value);
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new CliError("invalid_value", `${label} contains invalid JSON.`);
+  }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(`${label} must be a JSON object.`);
+    throw new CliError("invalid_value", `${label} must be a JSON object.`);
   }
   return parsed;
 }
@@ -34269,7 +35068,7 @@ async function handleViewCommand(parsed, options = {}) {
     return;
   }
   if (subcommand !== void 0) {
-    throw new Error(`Unknown view command: view ${subcommand}`);
+    throw new CliError("unknown_command", `Unknown view command: view ${subcommand}`);
   }
   if (parsed.options.localViewMode !== void 0) {
     const preference = await setLocalViewMode(parsed.options.localViewMode);
@@ -34317,7 +35116,10 @@ async function resolveWorkspaceSessionId(input) {
 }
 function assertNoViewPreferenceFlag(parsed) {
   if (parsed.options.localViewMode !== void 0) {
-    throw new Error("View preference flags cannot be combined with this subcommand.");
+    throw new CliError(
+      "invalid_option",
+      "View preference flags cannot be combined with this subcommand."
+    );
   }
 }
 function writeViewOutput(parsed, value) {
@@ -34402,10 +35204,10 @@ async function main() {
   }
   const operation = resolveOperation(parsed.command);
   if (!operation) {
-    throw new Error(`Unknown command: ${parsed.command.join(" ")}`);
+    throw new CliError("unknown_command", `Unknown command: ${parsed.command.join(" ")}`);
   }
   if (parsed.options.workspace === void 0) {
-    throw new Error('Stateful commands require "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError("missing_workspace", 'Stateful commands require "--workspace <id>" or OPENSTEER_WORKSPACE.');
   }
   const { engineName, provider, runtimeProvider } = resolveCliRuntimeSelection(parsed);
   if (operation === "session.close") {
@@ -34427,24 +35229,39 @@ async function main() {
   let renderOperation = operation;
   try {
     const input = await buildOperationInput(operation, parsed, runtime);
-    result = await dispatchSemanticOperation(runtime, operation, input);
+    const rawResult = await dispatchSemanticOperation(runtime, operation, input);
     if (parsed.command[0] === "tab" && operation !== "page.list") {
       renderOperation = "page.list";
       result = await runtime.listPages({});
+    } else {
+      result = rawResult;
+    }
+    let warning;
+    if (result !== null && typeof result === "object" && "warning" in result) {
+      const { warning: w, ...rest } = result;
+      if (typeof w === "string") {
+        warning = w;
+        result = rest;
+      }
     }
     process4__default.default.stdout.write(renderOperationOutput(renderOperation, result, input));
+    if (warning !== void 0) {
+      emitWarning(warning);
+    }
   } finally {
     await runtime.disconnect().catch(() => void 0);
   }
 }
 async function handleExecCommand(parsed) {
   if (parsed.options.workspace === void 0) {
-    throw new Error('exec requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError("missing_workspace", 'exec requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
   }
   const expression = parsed.rest.join(" ");
   if (!expression) {
-    throw new Error(
-      `exec requires an expression. Example: exec "await this.evaluate('document.title')"`
+    throw new CliError(
+      "missing_arguments",
+      "exec requires an expression.",
+      "opensteer exec <expression>"
     );
   }
   const { engineName, runtimeProvider } = resolveCliRuntimeSelection(parsed);
@@ -34480,8 +35297,10 @@ async function handleBrowserCommand(parsed) {
   if (subcommand === "inspect") {
     const endpoint = parsed.options.attachEndpoint ?? parsed.rest[0];
     if (!endpoint) {
-      throw new Error(
-        'browser inspect requires "--attach-endpoint <url>" or a positional endpoint.'
+      throw new CliError(
+        "missing_arguments",
+        'browser inspect requires "--attach-endpoint <url>" or a positional endpoint.',
+        "opensteer browser inspect <endpoint>"
       );
     }
     const result = await inspectCdpEndpoint({
@@ -34494,7 +35313,8 @@ async function handleBrowserCommand(parsed) {
     return;
   }
   if (parsed.options.workspace === void 0) {
-    throw new Error(
+    throw new CliError(
+      "missing_workspace",
       'Browser workspace commands require "--workspace <id>" or OPENSTEER_WORKSPACE.'
     );
   }
@@ -34517,7 +35337,11 @@ async function handleBrowserCommand(parsed) {
     case "clone": {
       const sourceUserDataDir = parsed.options.sourceUserDataDir;
       if (!sourceUserDataDir) {
-        throw new Error('browser clone requires "--source-user-data-dir <path>".');
+        throw new CliError(
+          "missing_arguments",
+          'browser clone requires "--source-user-data-dir <path>".',
+          "opensteer browser clone --source-user-data-dir <path>"
+        );
       }
       const result = await manager.clonePersistentBrowser({
         sourceUserDataDir,
@@ -34540,7 +35364,7 @@ async function handleBrowserCommand(parsed) {
       return;
     }
     default:
-      throw new Error(`Unknown browser command: ${parsed.command.join(" ")}`);
+      throw new CliError("unknown_command", `Unknown browser command: ${parsed.command.join(" ")}`);
   }
 }
 async function handleCloseCommand(parsed, engineName, providerMode, runtimeProvider) {
@@ -34573,23 +35397,27 @@ async function handleCloseCommand(parsed, engineName, providerMode, runtimeProvi
 }
 async function handleRecordCommandEntry(parsed) {
   if (parsed.options.workspace === void 0) {
-    throw new Error('record requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
+    throw new CliError("missing_workspace", 'record requires "--workspace <id>" or OPENSTEER_WORKSPACE.');
   }
   const url = parsed.options.url ?? parsed.rest[0];
   if (url === void 0) {
-    throw new Error('record requires "--url <value>" or a positional URL.');
+    throw new CliError(
+      "missing_arguments",
+      'record requires "--url <value>" or a positional URL.',
+      "opensteer record --url <url> --workspace <id>"
+    );
   }
   const provider = resolveCliProvider(parsed);
   assertCloudCliOptionsMatchProvider(parsed, provider.mode);
   const engineName = resolveCliEngineName(parsed);
   if (engineName !== "playwright") {
-    throw new Error("record requires engine=playwright.");
+    throw new CliError("config_conflict", "record requires engine=playwright.");
   }
   const rootDir = process4__default.default.cwd();
   const recordBrowser = parsed.options.browser;
   if (provider.mode === "cloud") {
     if (typeof recordBrowser === "object") {
-      throw new Error('record does not support browser.mode="attach".');
+      throw new CliError("config_conflict", 'record does not support browser.mode="attach".');
     }
     const runtimeProvider = buildCliRuntimeProvider(parsed, provider.mode);
     const runtimeConfig = resolveOpensteerRuntimeConfig({
@@ -34609,10 +35437,10 @@ async function handleRecordCommandEntry(parsed) {
     return;
   }
   if (parsed.options.launch?.headless === true) {
-    throw new Error('record requires a headed browser. Remove "--headless true".');
+    throw new CliError("config_conflict", 'record requires a headed browser. Remove "--headless true".');
   }
   if (typeof recordBrowser === "object") {
-    throw new Error('record does not support browser.mode="attach".');
+    throw new CliError("config_conflict", 'record does not support browser.mode="attach".');
   }
   const launch = {
     ...parsed.options.launch ?? {},
@@ -34681,7 +35509,7 @@ function resolveCliBootstrapAction(argv) {
 }
 function buildCliBrowserProfile(parsed) {
   if (parsed.options.cloudProfileReuseIfActive === true && parsed.options.cloudProfileId === void 0) {
-    throw new Error('"--cloud-profile-reuse-if-active" requires "--cloud-profile-id <id>".');
+    throw new CliError("invalid_option", '"--cloud-profile-reuse-if-active" requires "--cloud-profile-id <id>".');
   }
   return parsed.options.cloudProfileId === void 0 ? void 0 : {
     profileId: parsed.options.cloudProfileId,
@@ -34742,7 +35570,8 @@ function buildCliRuntimeProvider(parsed, providerMode) {
 }
 function assertCloudCliOptionsMatchProvider(parsed, providerMode) {
   if (providerMode !== "cloud" && (parsed.options.cloudBaseUrl !== void 0 || parsed.options.cloudApiKey !== void 0 || parsed.options.cloudAppBaseUrl !== void 0 || parsed.options.cloudProfileId !== void 0 || parsed.options.cloudProfileReuseIfActive === true)) {
-    throw new Error(
+    throw new CliError(
+      "config_conflict",
       'Cloud-specific options require provider=cloud. Set "--provider cloud" or OPENSTEER_PROVIDER=cloud.'
     );
   }
@@ -34776,17 +35605,7 @@ function printVersion() {
 `);
 }
 main().catch((error) => {
-  const payload = error instanceof Error ? {
-    error: {
-      name: error.name,
-      message: error.message
-    }
-  } : {
-    error: {
-      name: "Error",
-      message: String(error)
-    }
-  };
+  const payload = formatCliErrorOutput(error);
   process4__default.default.stderr.write(`${JSON.stringify(payload)}
 `);
   process4__default.default.exitCode = 1;