@vforsh/argus 0.1.19 → 0.1.21

package/dist/argus.js

@@ -2144,7 +2144,7 @@ var {
 // package.json
 var package_default = {
   name: "@vforsh/argus",
-  version: "0.1.19",
+  version: "0.1.21",
   repository: {
     type: "git",
     url: "git+https://github.com/vforsh/argus.git",
@@ -2180,7 +2180,7 @@ var package_default = {
   scripts: {
     clean: "node ../../scripts/clean-dist.mjs",
     build: "npm run clean && tsc -b && bun run bundle",
-    bundle: "bun build dist/bin.js --outfile dist/argus.js --target node --external esbuild && node ../../scripts/copy-argus-skill.mjs",
+    bundle: "bun build dist/bin.js --outfile dist/argus.js --target node --external esbuild && node ../../scripts/copy-argus-skill.mjs && node ../../scripts/copy-argus-extension.mjs",
     typecheck: "tsc -b --pretty false",
     "chrome:start": "bun src/bin.ts chrome start"
   }
@@ -6852,6 +6852,9 @@ function validateAddRequest(body) {
   if (payload.times !== undefined && (!Number.isInteger(payload.times) || payload.times < 1)) {
     return "times must be an integer >= 1";
   }
+  if (payload.scope !== undefined && payload.scope !== "page" && payload.scope !== "selected") {
+    return "scope must be one of: page, selected";
+  }
   return null;
 }
 var validateMatch = (match) => {
@@ -9372,10 +9375,12 @@ var route29 = defineJsonRoute({
 });
 
 // ../argus-watcher/dist/cdp/keyboard.js
-var buildKeyMap = () => {
-  const map = new Map;
+var buildKeyMaps = () => {
+  const byKey = new Map;
+  const byCode = new Map;
   const put = (lookup, def) => {
-    map.set(lookup.toLowerCase(), def);
+    byKey.set(lookup.toLowerCase(), def);
+    byCode.set(def.code.toLowerCase(), def);
   };
   for (let i = 0;i < 26; i++) {
     const lower = String.fromCharCode(97 + i);
@@ -9410,11 +9415,14 @@ var buildKeyMap = () => {
     const name = `F${i}`;
     put(name, { key: name, code: name, keyCode: 111 + i });
   }
-  return map;
+  return { byKey, byCode };
 };
-var KEY_MAP = buildKeyMap();
+var KEY_MAPS = buildKeyMaps();
 var resolveKeyDefinition = (key) => {
-  return KEY_MAP.get(key.toLowerCase());
+  return KEY_MAPS.byKey.get(key.toLowerCase());
+};
+var resolveCodeDefinition = (code) => {
+  return KEY_MAPS.byCode.get(code.toLowerCase());
 };
 var MODIFIER_BITS = {
   alt: 1,
@@ -9444,8 +9452,61 @@ var parseModifiers = (input) => {
   }
   return mask;
 };
+var resolveKeyboardEvent = (options) => {
+  const modifiers = options.modifiers ?? 0;
+  const keyInput = normalizeOptionalString(options.key);
+  const codeInput = normalizeOptionalString(options.code);
+  if (!keyInput && !codeInput) {
+    throw new Error("key or code is required");
+  }
+  const keyDef = keyInput ? resolveKeyDefinition(keyInput) : undefined;
+  const codeDef = codeInput ? resolveCodeDefinition(codeInput) : undefined;
+  const baseDef = codeDef ?? keyDef;
+  if (!baseDef) {
+    if (codeInput && !keyInput) {
+      throw new Error(`Unknown code: "${codeInput}"`);
+    }
+    throw new Error(`Unknown key: "${keyInput}"`);
+  }
+  const key = resolveEventKey(keyInput, baseDef, modifiers);
+  const text = resolveEventText(key, baseDef);
+  const event = {
+    key,
+    code: codeInput ?? baseDef.code,
+    keyCode: baseDef.keyCode,
+    modifiers,
+    altKey: (modifiers & MODIFIER_BITS.alt) !== 0,
+    ctrlKey: (modifiers & MODIFIER_BITS.ctrl) !== 0,
+    metaKey: (modifiers & MODIFIER_BITS.meta) !== 0,
+    shiftKey: (modifiers & MODIFIER_BITS.shift) !== 0
+  };
+  if (text !== undefined) {
+    event.text = text;
+  }
+  return event;
+};
+var normalizeOptionalString = (value) => {
+  const normalized = value?.trim();
+  return normalized ? normalized : undefined;
+};
+var resolveEventKey = (keyInput, def, modifiers) => {
+  const semanticKey = keyInput ?? def.key;
+  if (isSingleLetter(semanticKey)) {
+    return isShift(modifiers) ? semanticKey.toUpperCase() : semanticKey.toLowerCase();
+  }
+  return semanticKey;
+};
+var resolveEventText = (key, def) => {
+  if (key.length === 1) {
+    return key;
+  }
+  return def.text;
+};
+var isSingleLetter = (value) => /^[a-z]$/i.test(value);
+var isShift = (modifiers) => (modifiers & MODIFIER_BITS.shift) !== 0;
 var dispatchKeydown = async (session, options) => {
-  const { key, selector, modifiers = 0 } = options;
+  const { selector } = options;
+  const event = resolveKeyboardEvent(options);
   let focused = false;
   if (selector) {
     const { allNodeIds, nodeIds } = await resolveDomSelectorMatches(session, selector, false);
@@ -9461,31 +9522,23 @@ var dispatchKeydown = async (session, options) => {
     await session.sendAndWait("DOM.focus", { nodeId });
     focused = true;
   }
-  const def = resolveKeyDefinition(key);
-  if (!def) {
-    throw new Error(`Unknown key: "${key}"`);
-  }
-  let text = def.text;
-  if (text && text.length === 1 && (modifiers & 8) !== 0) {
-    text = text.toUpperCase();
-  }
-  const isPrintable = text != null && text !== "\r";
+  const isPrintable = event.text != null && event.text !== "\r";
   const baseParams = {
-    code: def.code,
-    key: def.key,
-    windowsVirtualKeyCode: def.keyCode,
-    nativeVirtualKeyCode: def.keyCode,
-    modifiers
+    code: event.code,
+    key: event.key,
+    windowsVirtualKeyCode: event.keyCode,
+    nativeVirtualKeyCode: event.keyCode,
+    modifiers: event.modifiers
   };
   if (isPrintable) {
-    await session.sendAndWait("Input.dispatchKeyEvent", { ...baseParams, type: "keyDown", text });
-    await session.sendAndWait("Input.dispatchKeyEvent", { ...baseParams, type: "char", text });
+    await session.sendAndWait("Input.dispatchKeyEvent", { ...baseParams, type: "keyDown", text: event.text });
+    await session.sendAndWait("Input.dispatchKeyEvent", { ...baseParams, type: "char", text: event.text });
     await session.sendAndWait("Input.dispatchKeyEvent", { ...baseParams, type: "keyUp" });
   } else {
-    await session.sendAndWait("Input.dispatchKeyEvent", { ...baseParams, type: "rawKeyDown", text: def.text });
+    await session.sendAndWait("Input.dispatchKeyEvent", { ...baseParams, type: "rawKeyDown", text: event.text });
     await session.sendAndWait("Input.dispatchKeyEvent", { ...baseParams, type: "keyUp" });
   }
-  return { key: def.key, modifiers, focused };
+  return { key: event.key, code: event.code, modifiers: event.modifiers, focused, event };
 };
 
 // ../argus-watcher/dist/http/routes/postDomKeydown.js
@@ -9495,12 +9548,23 @@ var route30 = defineJsonRoute({
   parseBody: true,
   endpoint: "dom/keydown",
   validate: (payload) => {
-    if (!payload.key || typeof payload.key !== "string") {
-      return "key is required";
+    const hasKey = typeof payload.key === "string" && payload.key.trim() !== "";
+    const hasCode = typeof payload.code === "string" && payload.code.trim() !== "";
+    if (payload.key != null && !hasKey) {
+      return "key must be a non-empty string";
+    }
+    if (payload.code != null && !hasCode) {
+      return "code must be a non-empty string";
+    }
+    if (!hasKey && !hasCode) {
+      return "key or code is required";
     }
     if (payload.selector != null && (typeof payload.selector !== "string" || payload.selector.trim() === "")) {
       return "selector must be a non-empty string";
     }
+    if (payload.modifiers != null && typeof payload.modifiers !== "string") {
+      return "modifiers must be a string";
+    }
     try {
       parseModifiers(payload.modifiers);
     } catch (error) {
@@ -9511,10 +9575,18 @@ var route30 = defineJsonRoute({
   handle: async ({ ctx, body: payload }) => {
     const result = await dispatchKeydown(ctx.cdpSession, {
       key: payload.key,
+      code: payload.code,
       selector: payload.selector,
       modifiers: parseModifiers(payload.modifiers)
     });
-    return { ok: true, key: result.key, modifiers: result.modifiers, focused: result.focused };
+    return {
+      ok: true,
+      key: result.key,
+      code: result.code,
+      modifiers: result.modifiers,
+      focused: result.focused,
+      event: result.event
+    };
   }
 });
 
@@ -11919,73 +11991,169 @@ var createThrottleController = () => {
   return { getStatus, setDesired, clearDesired, onAttach };
 };
 
-// ../argus-watcher/dist/net/NetMockController.js
-var createNetMockController = () => {
-  let session = null;
-  let bound = false;
-  let enabled = false;
-  let lastError = null;
-  let nextRuleId = 1;
-  const rules = [];
-  const hasActiveRules = () => rules.some(isRuleActive);
-  const recordError = (error) => {
-    lastError = { message: error instanceof Error ? error.message : String(error) };
-    const code = error?.code;
-    if (typeof code === "string") {
-      lastError.code = code;
+// ../argus-watcher/dist/net/NetMockInterception.js
+var PAGE_TARGET = { key: "page", sessionId: null };
+
+class NetMockInterception {
+  onPaused;
+  onError;
+  binding = null;
+  bound = false;
+  enabledTargets = new Map;
+  reconcileTail = Promise.resolve();
+  constructor(onPaused, onError) {
+    this.onPaused = onPaused;
+    this.onError = onError;
+  }
+  bind(binding) {
+    this.binding = binding;
+    if (this.bound) {
+      return;
     }
-  };
-  const enableInterception = async () => {
-    if (!session || !session.isAttached()) {
-      enabled = false;
-      return false;
+    this.bound = true;
+    binding.pageSession.onEvent("Fetch.requestPaused", (params, meta) => {
+      const request = parsePausedRequest(params, meta);
+      if (request) {
+        this.onPaused(request);
+      }
+    });
+  }
+  get enabled() {
+    return this.enabledTargets.size > 0;
+  }
+  matchesScope(scope, request) {
+    if (scope === "page") {
+      return request.sessionId === null;
     }
-    try {
-      await session.sendAndWait("Fetch.enable", { patterns: [{ urlPattern: "*", requestStage: "Request" }] });
-      enabled = true;
-      return true;
-    } catch (error) {
-      enabled = false;
-      recordError(error);
+    const selected = this.binding?.getSelectedTarget() ?? null;
+    if (selected?.sessionId) {
+      return request.sessionId === selected.sessionId;
+    }
+    if (request.sessionId !== null) {
       return false;
     }
-  };
-  const disableInterception = async () => {
-    if (!enabled) {
+    const selectedFrameId = selected?.frameId ?? null;
+    const selectedIsChildFrame = selectedFrameId !== null && selectedFrameId !== selected?.topFrameId;
+    return !selectedIsChildFrame || request.frameId === selectedFrameId;
+  }
+  async sendRequestCommand(request, method, params) {
+    await this.sendCommand({ key: request.sessionId ? `session:${request.sessionId}` : "page", sessionId: request.sessionId }, method, params);
+  }
+  reconcile(scopes, reset = false) {
+    const requestedScopes = new Set(scopes);
+    const operation = this.reconcileTail.then(() => this.applyReconcile(requestedScopes, reset));
+    this.reconcileTail = operation.then(() => {
       return;
-    }
-    enabled = false;
-    if (!session || !session.isAttached()) {
+    }, () => {
       return;
+    });
+    return operation;
+  }
+  async applyReconcile(scopes, reset) {
+    if (reset) {
+      this.enabledTargets.clear();
+    }
+    const session = this.binding?.pageSession;
+    if (!session?.isAttached()) {
+      this.enabledTargets.clear();
+      return false;
+    }
+    const desiredTargets = this.getDesiredTargets(scopes);
+    for (const [key, target] of this.enabledTargets) {
+      if (!desiredTargets.has(key)) {
+        await this.sendCommand(target, "Fetch.disable");
+        this.enabledTargets.delete(key);
+      }
+    }
+    for (const [key, target] of desiredTargets) {
+      if (this.enabledTargets.has(key)) {
+        continue;
+      }
+      const enabled = await this.sendCommand(target, "Fetch.enable", { patterns: [{ urlPattern: "*", requestStage: "Request" }] });
+      if (enabled) {
+        this.enabledTargets.set(key, target);
+      }
+    }
+    return this.enabled;
+  }
+  onDetach() {
+    this.enabledTargets.clear();
+  }
+  getDesiredTargets(scopes) {
+    const targets = new Map;
+    if (scopes.has("page")) {
+      targets.set(PAGE_TARGET.key, PAGE_TARGET);
+    }
+    if (!scopes.has("selected")) {
+      return targets;
+    }
+    const sessionId = this.binding?.getSelectedTarget()?.sessionId ?? null;
+    const selectedTarget = sessionId ? { key: `session:${sessionId}`, sessionId } : PAGE_TARGET;
+    targets.set(selectedTarget.key, selectedTarget);
+    return targets;
+  }
+  async sendCommand(target, method, params = {}) {
+    const session = this.binding?.pageSession;
+    if (!session?.isAttached()) {
+      return false;
     }
     try {
-      await session.sendAndWait("Fetch.disable");
+      await session.sendAndWait(method, params, target.sessionId ? { sessionId: target.sessionId } : undefined);
+      return true;
     } catch (error) {
-      recordError(error);
+      if (!isBenignInterceptionError(error)) {
+        this.onError(error);
+      }
+      return false;
     }
+  }
+}
+var parsePausedRequest = (params, meta) => {
+  const paused = params;
+  const requestId = paused?.requestId;
+  if (typeof requestId !== "string" || requestId === "") {
+    return null;
+  }
+  return {
+    requestId,
+    url: paused.request?.url ?? "",
+    method: paused.request?.method ?? "GET",
+    resourceType: paused.resourceType ?? "",
+    frameId: paused.frameId ?? null,
+    sessionId: meta.sessionId ?? null,
+    headers: paused.request?.headers ?? {}
   };
-  const bind = (nextSession) => {
-    session = nextSession;
-    if (bound) {
-      return;
+};
+var isBenignInterceptionError = (error) => {
+  const code = error?.code;
+  if (code === "cdp_not_attached") {
+    return true;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("Invalid InterceptionId") || message.includes("Inspected target navigated or closed") || message.includes("Session with given id not found") || message.includes("No target with given id");
+};
+
+// ../argus-watcher/dist/net/NetMockController.js
+var createNetMockController = () => {
+  let lastError = null;
+  let nextRuleId = 1;
+  const rules = [];
+  const recordError = (error) => {
+    lastError = { message: error instanceof Error ? error.message : String(error) };
+    const code = error?.code;
+    if (typeof code === "string") {
+      lastError.code = code;
     }
-    bound = true;
-    nextSession.onEvent("Fetch.requestPaused", (params) => {
-      handleRequestPaused(params);
-    });
   };
-  const handleRequestPaused = async (params) => {
-    const paused = params;
-    const requestId = paused?.requestId;
-    if (typeof requestId !== "string" || requestId === "") {
-      return;
-    }
-    const url = paused.request?.url ?? "";
-    const method = paused.request?.method ?? "GET";
-    const resourceType = paused.resourceType ?? "";
-    const rule = rules.find((candidate) => ruleMatches(candidate, url, method, resourceType));
+  const interception = new NetMockInterception((request) => void handleRequestPaused(request), recordError);
+  const bind = (binding) => {
+    interception.bind(binding);
+    interception.reconcile(getActiveScopes(rules));
+  };
+  const handleRequestPaused = async (paused) => {
+    const rule = rules.find((candidate) => interception.matchesScope(candidate.scope ?? "page", paused) && ruleMatches(candidate, paused.url, paused.method, paused.resourceType));
     if (!rule) {
-      await sendAction("Fetch.continueRequest", { requestId });
+      await sendAction(paused, "Fetch.continueRequest", { requestId: paused.requestId });
       return;
     }
     rule.hits += 1;
@@ -11994,53 +12162,41 @@ var createNetMockController = () => {
     }
     const action = rule.action;
     if (action.kind === "block") {
-      await sendAction("Fetch.failRequest", { requestId, errorReason: "BlockedByClient" });
+      await sendAction(paused, "Fetch.failRequest", { requestId: paused.requestId, errorReason: "BlockedByClient" });
       return;
     }
     if (action.kind === "fail") {
-      await sendAction("Fetch.failRequest", { requestId, errorReason: action.reason });
+      await sendAction(paused, "Fetch.failRequest", { requestId: paused.requestId, errorReason: action.reason });
       return;
     }
     if (action.kind === "fulfill") {
-      const fulfillParams = { requestId, responseCode: action.status };
+      const fulfillParams = { requestId: paused.requestId, responseCode: action.status };
       if (action.headers && action.headers.length > 0) {
         fulfillParams.responseHeaders = action.headers;
       }
       if (action.bodyBase64 != null) {
         fulfillParams.body = action.bodyBase64;
       }
-      await sendAction("Fetch.fulfillRequest", fulfillParams);
+      await sendAction(paused, "Fetch.fulfillRequest", fulfillParams);
       return;
     }
-    const continueParams = { requestId };
+    const continueParams = { requestId: paused.requestId };
     if (action.rewriteHost) {
-      const rewritten = rewriteUrlHost(url, action.rewriteHost);
+      const rewritten = rewriteUrlHost(paused.url, action.rewriteHost);
       if (rewritten) {
         continueParams.url = rewritten;
       }
     }
     if (action.setHeaders && action.setHeaders.length > 0) {
-      continueParams.headers = mergeHeaders(paused.request?.headers ?? {}, action.setHeaders);
-    }
-    await sendAction("Fetch.continueRequest", continueParams);
-  };
-  const sendAction = async (cdpMethod, params) => {
-    if (!session || !session.isAttached()) {
-      return;
-    }
-    try {
-      await session.sendAndWait(cdpMethod, params);
-    } catch (error) {
-      if (isBenignInterceptionError(error)) {
-        return;
-      }
-      recordError(error);
+      continueParams.headers = mergeHeaders(paused.headers, action.setHeaders);
     }
+    await sendAction(paused, "Fetch.continueRequest", continueParams);
   };
+  const sendAction = async (request, cdpMethod, params) => interception.sendRequestCommand(request, cdpMethod, params);
   const getStatus = (ctx) => ({
     ok: true,
     attached: ctx.attached,
-    enabled,
+    enabled: interception.enabled,
     rules: rules.map(toPublicRule),
     lastError
   });
@@ -12048,6 +12204,7 @@ var createNetMockController = () => {
     lastError = null;
     const rule = {
       id: nextRuleId++,
+      scope: input.scope ?? "page",
       match: input.match,
       action: input.action,
       delayMs: input.delayMs,
@@ -12060,7 +12217,7 @@ var createNetMockController = () => {
     if (!attached) {
       return { ok: true, attached: false, enabled: false, rule: toPublicRule(rule) };
     }
-    const applied = enabled || await enableInterception();
+    const applied = await interception.reconcile(getActiveScopes(rules));
     return {
       ok: true,
       attached: true,
@@ -12076,32 +12233,33 @@ var createNetMockController = () => {
       rules.splice(index, 1);
     }
     if (rules.length === 0) {
-      await disableInterception();
+      await interception.reconcile(new Set);
+    } else {
+      await interception.reconcile(getActiveScopes(rules));
     }
-    return { ok: true, removed, enabled };
+    return { ok: true, removed, enabled: interception.enabled };
   };
   const clearRules = async () => {
     const removed = rules.length;
     rules.length = 0;
-    await disableInterception();
-    return { ok: true, removed, enabled };
+    await interception.reconcile(new Set);
+    return { ok: true, removed, enabled: interception.enabled };
   };
-  const onAttach = async (nextSession) => {
-    session = nextSession;
-    enabled = false;
-    if (!hasActiveRules()) {
-      return;
-    }
-    const applied = await enableInterception();
+  const onAttach = async () => {
+    const applied = await interception.reconcile(getActiveScopes(rules), true);
     if (!applied && lastError) {
       console.warn(`[NetMock] Failed to re-enable interception on attach: ${lastError.message}`);
     }
   };
+  const onTargetChanged = async () => {
+    await interception.reconcile(getActiveScopes(rules));
+  };
   const onDetach = () => {
-    enabled = false;
+    interception.onDetach();
   };
-  return { bind, getStatus, addRule, removeRule, clearRules, onAttach, onDetach };
+  return { bind, getStatus, addRule, removeRule, clearRules, onAttach, onTargetChanged, onDetach };
 };
+var getActiveScopes = (rules) => new Set(rules.filter(isRuleActive).map((rule) => rule.scope ?? "page"));
 var isRuleActive = (rule) => rule.times == null || rule.hits < rule.times;
 var ruleMatches = (rule, url, method, resourceType) => {
   if (!isRuleActive(rule)) {
@@ -12145,16 +12303,9 @@ var mergeHeaders = (original, overrides) => {
   }
   return [...merged.values()];
 };
-var isBenignInterceptionError = (error) => {
-  const code = error?.code;
-  if (code === "cdp_not_attached") {
-    return true;
-  }
-  const message = error instanceof Error ? error.message : String(error);
-  return message.includes("Invalid InterceptionId") || message.includes("Inspected target navigated or closed");
-};
 var toPublicRule = (rule) => ({
   id: rule.id,
+  scope: rule.scope ?? "page",
   match: rule.match,
   action: rule.action,
   delayMs: rule.delayMs,
@@ -17067,7 +17218,7 @@ var createWatcherHandle = async (options, watcherId) => {
     await emulationController.onAttach(session);
     await throttleController.onAttach(session);
     await visibilityController.onAttach(sourceHandle.pageSession ?? session);
-    await netMockController.onAttach(sourceHandle.pageSession ?? session);
+    await netMockController.onAttach();
     await networkCapture?.onAttached();
     onIndicatorAttach(session, target);
     await maybeInjectOnAttach(session, target);
@@ -17084,6 +17235,7 @@ var createWatcherHandle = async (options, watcherId) => {
       },
       reason: null
     });
+    netMockController.onTargetChanged();
     onIndicatorAttach(session, target);
   };
   const handleSourceDetach = (reason) => {
@@ -17111,7 +17263,18 @@ var createWatcherHandle = async (options, watcherId) => {
       indicatorController?.setRecording(recording);
     }
   });
-  netMockController.bind(sourceHandle.pageSession ?? sourceHandle.session);
+  netMockController.bind({
+    pageSession: sourceHandle.pageSession ?? sourceHandle.session,
+    getSelectedTarget: () => {
+      const context = sourceHandle.getNetFilterContext?.() ?? null;
+      const frameId = context?.selectedFrameId ?? null;
+      return {
+        frameId,
+        topFrameId: context?.topFrameId ?? null,
+        sessionId: frameId ? sourceHandle.getFrameSessionId?.(frameId) ?? null : null
+      };
+    }
+  });
   const dialogSession = sourceHandle.pageSession ?? sourceHandle.session;
   dialogSession.onEvent("Page.javascriptDialogOpening", (params) => {
     const dialog = parseDialogStatus(params);
@@ -22115,6 +22278,10 @@ var buildAddRequest = async (options, output) => {
   if (!action) {
     return null;
   }
+  const scope = resolveMockScope(options, output);
+  if (!scope) {
+    return null;
+  }
   const match = { url: urlPattern };
   if (options.method) {
     match.method = options.method;
@@ -22122,7 +22289,21 @@ var buildAddRequest = async (options, output) => {
   if (options.resourceType) {
     match.resourceType = options.resourceType;
   }
-  return { match, action, delayMs, times };
+  return { scope, match, action, delayMs, times };
+};
+var resolveMockScope = (options, output) => {
+  if (options.scope && options.frame) {
+    output.writeWarn("Cannot combine --scope and --frame. Use one or the other.");
+    process.exitCode = 2;
+    return null;
+  }
+  const value = (options.scope ?? options.frame ?? "page").trim().toLowerCase();
+  if (value === "page" || value === "selected") {
+    return value;
+  }
+  output.writeWarn(`Invalid mock scope: ${value}. Expected page or selected.`);
+  process.exitCode = 2;
+  return null;
 };
 var buildAction = async (options, responseHeaders, requestHeaders, delayMs, output) => {
   const invalid = (message) => {
@@ -22310,6 +22491,9 @@ var describeRule = (rule) => {
   if (rule.times != null) {
     extras.push(`times ${Math.min(rule.hits, rule.times)}/${rule.times}`);
   }
+  if (rule.scope === "selected") {
+    extras.push("scope selected");
+  }
   extras.push(`hits ${rule.hits}`);
   return `#${rule.id}  ${match} → ${describeAction(rule.action)} [${extras.join(", ")}]`;
 };
@@ -22429,6 +22613,8 @@ var netMockCommand = {
         { flags: "--url <pattern>", description: "URL wildcard pattern; substring match when it contains no *" },
         { flags: "--method <method>", description: "Only match this HTTP method" },
         { flags: "--resource-type <type>", description: "Only match this CDP resource type (Fetch, XHR, Document, ...)" },
+        { flags: "--scope <scope>", description: "Intercept the top-level page or currently selected target (page|selected)" },
+        { flags: "--frame <frame>", description: "Alias for --scope; accepts page or selected" },
         { flags: "--block", description: "Abort matching requests as BlockedByClient" },
         { flags: "--fail <reason>", description: "Abort with a network error (TimedOut, ConnectionRefused, ...)" },
         { flags: "--status <code>", description: "Stub a response with this HTTP status (default 200 when a body is given)" },
@@ -22455,12 +22641,13 @@ var netMockCommand = {
         'argus net mock add app --url "*/analytics/*" --block',
         'argus net mock add app --url "*/api/save" --fail ConnectionRefused --times 1',
         'argus net mock add app --url "*/api/config" --status 200 --body-file ./fixtures/config.json',
+        'argus net mock add extension --scope selected --url "*/api/config" --status 200 --body-file ./fixtures/config.json',
         `argus net mock add app --url "*/game/init" --status 500 --body '{"error":"maintenance"}'`,
         'argus net mock add app --url "*/api/*" --delay 2s --method POST',
         'argus net mock add app --url "cdn.prod.com" --rewrite-host localhost:3000'
       ],
       action: async (id, options) => {
-        await runNetMockAdd(id, options);
+        await runNetMockAdd(id, resolveNetMockAddOptions(options));
       }
     },
     {
@@ -22471,7 +22658,7 @@ var netMockCommand = {
       options: [jsonOption],
       examples: ["argus net mock ls app", "argus net mock ls app --json"],
       action: async (id, options) => {
-        await runNetMockList(id, options);
+        await runNetMockList(id, resolveCommandOptions(options));
       }
     },
     {
@@ -22485,7 +22672,7 @@ var netMockCommand = {
       options: [jsonOption],
       examples: ["argus net mock rm 2 app", "argus net mock rm 2 app --json"],
       action: async (rule, id, options) => {
-        await runNetMockRemove(id, rule, options);
+        await runNetMockRemove(id, rule, resolveCommandOptions(options));
       }
     },
     {
@@ -22495,7 +22682,7 @@ var netMockCommand = {
       options: [jsonOption],
       examples: ["argus net mock clear app", "argus net mock clear app --json"],
       action: async (id, options) => {
-        await runNetMockClear(id, options);
+        await runNetMockClear(id, resolveCommandOptions(options));
       }
     }
   ]
@@ -22718,8 +22905,8 @@ Examples:
     ]
   }
 ];
-var resolveCommandOptions = (value) => {
-  const fallback = parseNetArgv(process.argv.slice(2));
+var resolveCommandOptions = (value, argv = process.argv.slice(2)) => {
+  const fallback = parseNetArgv(argv);
   if (value && typeof value === "object" && "opts" in value && typeof value.opts === "function") {
     return {
       ...value.opts(),
@@ -22731,6 +22918,16 @@ var resolveCommandOptions = (value) => {
     ...fallback
   };
 };
+var resolveNetMockAddOptions = (value, argv = process.argv.slice(2)) => {
+  const resolved = resolveCommandOptions(value, argv);
+  for (const key of ["method", "status", "resourceType"]) {
+    const option = resolved[key];
+    if (Array.isArray(option)) {
+      resolved[key] = option.at(-1);
+    }
+  }
+  return resolved;
+};
 var parseNetArgv = (argv) => {
   const parsed = {};
   const readValue = (flag) => {
@@ -47431,10 +47628,34 @@ var domCommands = [
 ];
 
 // dist/commands/domKeydown.js
+var normalizeOptionalString2 = (value) => {
+  const normalized = value?.trim();
+  return normalized ? normalized : undefined;
+};
+var mergeModifierOptions = (options) => {
+  const modifiers = new Set;
+  for (const part of (options.modifiers ?? "").split(",")) {
+    const name = part.trim().toLowerCase();
+    if (name) {
+      modifiers.add(name);
+    }
+  }
+  if (options.shift)
+    modifiers.add("shift");
+  if (options.ctrl)
+    modifiers.add("ctrl");
+  if (options.alt)
+    modifiers.add("alt");
+  if (options.meta || options.cmd)
+    modifiers.add("meta");
+  return modifiers.size > 0 ? Array.from(modifiers).join(",") : undefined;
+};
 var runDomKeydown = defineWatcherCommand({
   build: (_args, options, output) => {
-    if (!options.key || options.key.trim() === "") {
-      output.writeWarn("--key is required");
+    const key = normalizeOptionalString2(options.key);
+    const code = normalizeOptionalString2(options.code);
+    if (!key && !code) {
+      output.writeWarn("--key or --code is required");
       process.exitCode = 2;
       return null;
     }
@@ -47442,15 +47663,20 @@ var runDomKeydown = defineWatcherCommand({
       path: "/dom/keydown",
       method: "POST",
       body: {
-        key: options.key,
+        key,
+        code,
         selector: options.selector,
-        modifiers: options.modifiers
+        modifiers: mergeModifierOptions(options)
       },
       timeoutMs: 30000
     };
   },
-  formatHuman: (response, { output }) => {
-    output.writeHuman(`Dispatched keydown: ${response.key}`);
+  formatHuman: (response, { options, output }) => {
+    if (options.printEvent) {
+      output.writeHuman(`Dispatched keydown event: ${JSON.stringify(response.event)}`);
+      return;
+    }
+    output.writeHuman(`Dispatched keydown: ${response.key} (code=${response.code})`);
   }
 });
 
@@ -47460,13 +47686,26 @@ var keydownCommand = {
   description: "Dispatch a keyboard event to the connected page",
   arguments: [{ flags: "[id]", description: "Watcher id to query" }],
   options: [
-    { flags: "--key <name>", description: "Key name (e.g. Enter, a, ArrowUp)", required: true },
+    { flags: "--key <name>", description: "KeyboardEvent.key value (e.g. Enter, a, ArrowUp)" },
+    { flags: "--code <code>", description: "KeyboardEvent.code value (e.g. KeyG, Digit1)" },
     { flags: "--selector <css>", description: "Focus element before dispatching" },
     { flags: "--testid <id>", description: `Shorthand for --selector "[data-testid='<id>']"` },
     { flags: "--modifiers <list>", description: "Comma-separated modifiers: shift,ctrl,alt,meta" },
+    { flags: "--shift", description: "Shortcut for --modifiers shift" },
+    { flags: "--ctrl", description: "Shortcut for --modifiers ctrl" },
+    { flags: "--alt", description: "Shortcut for --modifiers alt" },
+    { flags: "--meta", description: "Shortcut for --modifiers meta" },
+    { flags: "--cmd", description: "Alias for --meta" },
+    { flags: "--print-event", description: "Print resolved key/code/modifier event details" },
     { flags: "--json", description: "Output JSON for automation" }
   ],
-  examples: ["argus keydown app --key Enter", 'argus keydown app --key a --selector "#input"', "argus keydown app --key a --modifiers shift,ctrl"],
+  examples: [
+    "argus keydown app --key Enter",
+    "argus keydown app --key G",
+    "argus keydown app --code KeyG",
+    'argus keydown app --key a --selector "#input"',
+    "argus keydown app --key a --shift --ctrl"
+  ],
   action: async (id, options) => {
     if (!resolveTestId(options))
       return;
@@ -48729,7 +48968,7 @@ var extractPlugin = (mod) => {
     return null;
   return plugin;
 };
-var normalizeOptionalString = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
+var normalizeOptionalString3 = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
 var normalizeCommands = (value) => {
   if (!Array.isArray(value))
     return [];
@@ -48751,11 +48990,11 @@ var createLoadedEntry = (entry, plugin, url) => ({
   alias: entry.alias,
   status: "loaded",
   name: plugin.name,
-  version: normalizeOptionalString(plugin.version),
-  description: normalizeOptionalString(plugin.description),
+  version: normalizeOptionalString3(plugin.version),
+  description: normalizeOptionalString3(plugin.description),
   commands: normalizeCommands(plugin.commands),
-  homepage: normalizeOptionalString(plugin.homepage),
-  minArgusVersion: normalizeOptionalString(plugin.minArgusVersion),
+  homepage: normalizeOptionalString3(plugin.homepage),
+  minArgusVersion: normalizeOptionalString3(plugin.minArgusVersion),
   url
 });
 var registerPlugins = async (program2, argv = process.argv.slice(2)) => {
@@ -49110,9 +49349,63 @@ var pluginCommands = [
   }
 ];
 
-// dist/commands/extension/nativeHost.js
+// dist/commands/extension/install.js
+import { spawn as spawn3 } from "node:child_process";
+
+// dist/commands/extension/extensionId.js
+var ARGUS_EXTENSION_ID = "ibhecpfiodfmkpflcnnkkgnjifheefhb";
+
+// dist/commands/extension/extensionPath.js
 import fs17 from "node:fs";
 import path22 from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+var runExtensionPath = (options) => {
+  const output = createOutput(options);
+  const extensionDir = resolveExtensionDir();
+  if (!extensionDir) {
+    const message = `Packaged Argus extension not found. Checked:
+${resolveExtensionCandidates().join(`
+`)}`;
+    if (options.json) {
+      output.writeJson({ ok: false, error: { message } });
+    } else {
+      console.error(message);
+    }
+    process.exitCode = 2;
+    return;
+  }
+  if (options.json) {
+    output.writeJson({ ok: true, path: extensionDir });
+    return;
+  }
+  output.writeHuman(extensionDir);
+};
+var resolveExtensionDir = () => {
+  for (const candidate of resolveExtensionCandidates()) {
+    if (isLoadableExtensionDir(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+};
+var isLoadableExtensionDir = (dir) => {
+  return fs17.existsSync(path22.join(dir, "manifest.json")) && fs17.existsSync(path22.join(dir, "dist", "background", "service-worker.js"));
+};
+var resolveExtensionCandidates = () => {
+  const moduleDir = path22.dirname(fileURLToPath2(import.meta.url));
+  const candidates = [
+    path22.resolve(moduleDir, "extension"),
+    path22.resolve(moduleDir, "..", "..", "extension"),
+    path22.resolve(moduleDir, "..", "extension"),
+    path22.resolve(moduleDir, "..", "..", "..", "argus-extension"),
+    path22.resolve(moduleDir, "..", "..", "..", "..", "argus-extension")
+  ];
+  return [...new Set(candidates)];
+};
+
+// dist/commands/extension/nativeHost.js
+import fs18 from "node:fs";
+import path23 from "node:path";
 import os8 from "node:os";
 import { execSync } from "node:child_process";
 var BRIDGE_HOST_NAME = "com.vforsh.argus.bridge";
@@ -49122,21 +49415,21 @@ var HOST_NAMES = [BRIDGE_HOST_NAME, CONTROL_HOST_NAME];
 var getManifestDir = (platform) => {
   switch (platform) {
     case "darwin":
-      return path22.join(os8.homedir(), "Library/Application Support/Google/Chrome/NativeMessagingHosts");
+      return path23.join(os8.homedir(), "Library/Application Support/Google/Chrome/NativeMessagingHosts");
     case "linux":
-      return path22.join(os8.homedir(), ".config/google-chrome/NativeMessagingHosts");
+      return path23.join(os8.homedir(), ".config/google-chrome/NativeMessagingHosts");
     case "win32":
-      return path22.join(process.env.LOCALAPPDATA ?? os8.homedir(), "Google/Chrome/User Data/NativeMessagingHosts");
+      return path23.join(process.env.LOCALAPPDATA ?? os8.homedir(), "Google/Chrome/User Data/NativeMessagingHosts");
     default:
       throw new Error(`Unsupported platform: ${platform}`);
   }
 };
 var getManifestPath = (platform, hostName = BRIDGE_HOST_NAME) => {
-  return path22.join(getManifestDir(platform), `${hostName}.json`);
+  return path23.join(getManifestDir(platform), `${hostName}.json`);
 };
 var getWrapperPath = (platform, hostName = BRIDGE_HOST_NAME) => {
   const filename = hostName === CONTROL_HOST_NAME ? "argus-native-control-host.sh" : "argus-native-host.sh";
-  return path22.join(getManifestDir(platform), filename);
+  return path23.join(getManifestDir(platform), filename);
 };
 var getPlatform = () => {
   const platform = os8.platform();
@@ -49148,8 +49441,8 @@ var getPlatform = () => {
 var findArgusExecutable = () => {
   try {
     const npmGlobalPrefix = execSync("npm config get prefix", { encoding: "utf8" }).trim();
-    const globalBinPath = path22.join(npmGlobalPrefix, "bin", "argus");
-    if (fs17.existsSync(globalBinPath)) {
+    const globalBinPath = path23.join(npmGlobalPrefix, "bin", "argus");
+    if (fs18.existsSync(globalBinPath)) {
       return globalBinPath;
     }
   } catch {}
@@ -49162,7 +49455,7 @@ var findArgusExecutable = () => {
   throw new Error("Could not find argus executable. Please install argus globally (npm install -g @vforsh/argus) or ensure it is in your PATH.");
 };
 var findNodePath = () => {
-  return fs17.realpathSync(process.execPath);
+  return fs18.realpathSync(process.execPath);
 };
 var createManifest = (extensionId, executablePath, hostName = BRIDGE_HOST_NAME) => {
   return {
@@ -49180,16 +49473,16 @@ var createWrapperScript = (platform, executablePath, hostName = BRIDGE_HOST_NAME
   const script = `#!/bin/bash
 exec "${nodePath}" "${executablePath}" ${args}
 `;
-  fs17.writeFileSync(wrapperPath, script, { mode: 493 });
+  fs18.writeFileSync(wrapperPath, script, { mode: 493 });
   return wrapperPath;
 };
 var installNativeHosts = (platform, extensionId, executablePath) => {
-  fs17.mkdirSync(getManifestDir(platform), { recursive: true });
+  fs18.mkdirSync(getManifestDir(platform), { recursive: true });
   return HOST_NAMES.map((hostName) => {
     const wrapperPath = createWrapperScript(platform, executablePath, hostName);
     const manifestPath = getManifestPath(platform, hostName);
     const manifest = createManifest(extensionId, wrapperPath, hostName);
-    fs17.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+    fs18.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
     registerWindowsNativeHost(platform, hostName, manifestPath);
     return { hostName, manifestPath, wrapperPath };
   });
@@ -49209,8 +49502,8 @@ var removeNativeHosts = (platform) => {
 var inspectNativeHost = (platform, hostName) => {
   const manifestPath = getManifestPath(platform, hostName);
   const wrapperPath = getWrapperPath(platform, hostName);
-  const manifestExists = fs17.existsSync(manifestPath);
-  const wrapperExists = fs17.existsSync(wrapperPath);
+  const manifestExists = fs18.existsSync(manifestPath);
+  const wrapperExists = fs18.existsSync(wrapperPath);
   const wrapperExecutable = wrapperExists && isWrapperExecutable(wrapperPath);
   const manifest = manifestExists ? readManifest(manifestPath) : null;
   const manifestValid = Boolean(manifest && manifest.name === hostName && manifest.type === "stdio" && Array.isArray(manifest.allowed_origins));
@@ -49231,7 +49524,7 @@ var inspectNativeHost = (platform, hostName) => {
 };
 var readManifest = (manifestPath) => {
   try {
-    const content = fs17.readFileSync(manifestPath, "utf8");
+    const content = fs18.readFileSync(manifestPath, "utf8");
     return JSON.parse(content);
   } catch {
     return null;
@@ -49239,7 +49532,7 @@ var readManifest = (manifestPath) => {
 };
 var isWrapperExecutable = (wrapperPath) => {
   try {
-    fs17.accessSync(wrapperPath, fs17.constants.X_OK);
+    fs18.accessSync(wrapperPath, fs18.constants.X_OK);
     return true;
   } catch {
     return false;
@@ -49260,10 +49553,10 @@ var extractExtensionId = (origin) => {
   return match?.[1] ?? null;
 };
 var removeFileIfExists = (filePath) => {
-  if (!fs17.existsSync(filePath)) {
+  if (!fs18.existsSync(filePath)) {
     return false;
   }
-  fs17.unlinkSync(filePath);
+  fs18.unlinkSync(filePath);
   return true;
 };
 var registerWindowsNativeHost = (platform, hostName, manifestPath) => {
@@ -49283,10 +49576,145 @@ var unregisterWindowsNativeHost = (platform, hostName) => {
   } catch {}
 };
 
+// dist/commands/extension/install.js
+var DEFAULT_TIMEOUT_SECONDS = 120;
+var POLL_INTERVAL_MS = 700;
+var runExtensionInstall = async (options) => {
+  const output = createOutput(options);
+  let platform;
+  try {
+    platform = getPlatform();
+  } catch (error) {
+    return fail(output, error.message);
+  }
+  const extensionDir = resolveExtensionDir();
+  if (!extensionDir) {
+    return fail(output, "Packaged Argus extension not found. Build the CLI (npm run build:packages) or run from a built checkout.");
+  }
+  let executablePath;
+  try {
+    executablePath = findArgusExecutable();
+  } catch (error) {
+    return fail(output, error.message);
+  }
+  let hosts;
+  try {
+    hosts = installNativeHosts(platform, ARGUS_EXTENSION_ID, executablePath);
+  } catch (error) {
+    return fail(output, `Failed to install native hosts: ${error.message}`);
+  }
+  await pruneRegistry();
+  let connected = await isControlConnected();
+  const shouldOpen = options.open !== false && !connected;
+  const opened = shouldOpen ? openExtensionsPage() : false;
+  if (!output.json) {
+    printSummary(output, { extensionDir, hosts, connected, opened, shouldOpen });
+  }
+  const shouldWait = options.wait !== false && !connected;
+  if (shouldWait) {
+    connected = await waitForControl(parseTimeoutMs2(options.timeout), output);
+  }
+  if (output.json) {
+    output.writeJson({ success: true, extensionId: ARGUS_EXTENSION_ID, extensionPath: extensionDir, hosts, connected });
+    if (!connected && shouldWait) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+  printResult(output, connected, shouldWait);
+};
+var isControlConnected = async () => {
+  const { registry: registry2 } = await readRegistry();
+  return Boolean(registry2.watchers[CONTROL_WATCHER_ID]);
+};
+var openExtensionsPage = () => {
+  const chromeBin = resolveChromeBin();
+  if (!chromeBin) {
+    return false;
+  }
+  try {
+    const child = spawn3(chromeBin, ["chrome://extensions/"], { stdio: "ignore", detached: true });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+};
+var waitForControl = async (timeoutMs, output) => {
+  if (!output.json) {
+    output.writeHuman(`Waiting for the extension to connect (up to ${Math.round(timeoutMs / 1000)}s)...`);
+  }
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isControlConnected()) {
+      return true;
+    }
+    await delay7(POLL_INTERVAL_MS);
+  }
+  return isControlConnected();
+};
+var printSummary = (output, info) => {
+  output.writeHuman("");
+  output.writeHuman("Argus extension setup");
+  output.writeHuman("");
+  output.writeHuman(`  Native hosts:  installed (${info.hosts.map((host) => host.hostName).join(", ")})`);
+  output.writeHuman(`  Extension ID:  ${ARGUS_EXTENSION_ID}`);
+  output.writeHuman(`  Load unpacked: ${info.extensionDir}`);
+  output.writeHuman("");
+  if (info.connected) {
+    return;
+  }
+  if (info.opened) {
+    output.writeHuman('Opened chrome://extensions. Click "Load unpacked" and select the folder above.');
+  } else if (info.shouldOpen) {
+    output.writeHuman('Open chrome://extensions, then click "Load unpacked" and select the folder above.');
+  } else {
+    output.writeHuman('Open chrome://extensions and "Load unpacked" the folder above.');
+  }
+  output.writeHuman('(Enable Developer mode if the "Load unpacked" button is hidden.)');
+  output.writeHuman("");
+};
+var printResult = (output, connected, waited) => {
+  if (connected) {
+    output.writeHuman("Extension connected.");
+    output.writeHuman("");
+    output.writeHuman("Try it:");
+    output.writeHuman("  argus ext tabs");
+    output.writeHuman("");
+    return;
+  }
+  if (waited) {
+    output.writeHuman("Extension did not connect yet.");
+    output.writeHuman("  - If it is already loaded, open its popup or reload it in chrome://extensions.");
+    output.writeHuman("  - Then check `argus extension status` and `argus ext doctor`.");
+    output.writeHuman("");
+    process.exitCode = 1;
+    return;
+  }
+  output.writeHuman("Once loaded, verify with `argus ext tabs`.");
+  output.writeHuman("");
+};
+var parseTimeoutMs2 = (value) => {
+  const seconds = value ? Number.parseInt(value, 10) : DEFAULT_TIMEOUT_SECONDS;
+  if (!Number.isFinite(seconds) || seconds < 5) {
+    return DEFAULT_TIMEOUT_SECONDS * 1000;
+  }
+  return seconds * 1000;
+};
+var fail = (output, message) => {
+  if (output.json) {
+    output.writeJson({ success: false, error: { message } });
+  } else {
+    console.error(message);
+  }
+  process.exitCode = 1;
+};
+var delay7 = (ms3) => new Promise((resolve2) => setTimeout(resolve2, ms3));
+
 // dist/commands/extension/setup.js
 var runExtensionSetup = async (options) => {
   const output = createOutput(options);
-  const { extensionId } = options;
+  const extensionId = options.extensionId ?? ARGUS_EXTENSION_ID;
   let platform;
   try {
     platform = getPlatform();
@@ -49342,9 +49770,11 @@ var runExtensionSetup = async (options) => {
     }
     output.writeHuman("");
     output.writeHuman("Next steps:");
-    output.writeHuman("  1. Reload the extension in chrome://extensions");
+    output.writeHuman("  1. Load the unpacked extension from `argus extension path` (if not already loaded)");
     output.writeHuman("  2. Run `argus ext tabs` or open the extension popup and attach a tab");
     output.writeHuman("");
+    output.writeHuman("Tip: `argus extension install` does this end-to-end and waits for the extension to connect.");
+    output.writeHuman("");
   }
 };
 
@@ -49733,7 +50163,7 @@ var waitForTabWatcher = async (controlWatcher, selector, tab, watcherId) => {
       if (watcher) {
         const status = await fetchStatus(watcher);
         if (!status || !statusMatchesTabWatcher(status, latestTab ?? tab, latestTab?.watcherId === explicitWatcherId)) {
-          await delay7(WATCHER_POLL_INTERVAL_MS);
+          await delay8(WATCHER_POLL_INTERVAL_MS);
           continue;
         }
         return { ok: true, watcher, status, tab: latestTab ?? tab };
@@ -49743,7 +50173,7 @@ var waitForTabWatcher = async (controlWatcher, selector, tab, watcherId) => {
     if (lastResult.ok) {
       return lastResult;
     }
-    await delay7(WATCHER_POLL_INTERVAL_MS);
+    await delay8(WATCHER_POLL_INTERVAL_MS);
   }
   return lastResult;
 };
@@ -49797,7 +50227,7 @@ var targetMatchesTab = (target, tab) => {
   }
   return Boolean(target.title && target.title === tab.title && target.url === tab.url);
 };
-var delay7 = (ms3) => new Promise((resolve2) => setTimeout(resolve2, ms3));
+var delay8 = (ms3) => new Promise((resolve2) => setTimeout(resolve2, ms3));
 var formatError6 = (error) => error instanceof Error ? error.message : String(error);
 
 // dist/commands/extension/show.js
@@ -50176,19 +50606,19 @@ var waitForSelectedTarget = async (watcher, target, options = {}) => {
     const [status, targets] = await Promise.all([fetchWatcherStatus(watcher), fetchExtensionTargets(watcher)]);
     if (!status.ok) {
       lastError = status.error;
-      await delay8(intervalMs);
+      await delay9(intervalMs);
       continue;
     }
     if (!targets.ok) {
       lastError = targets.error;
-      await delay8(intervalMs);
+      await delay9(intervalMs);
       continue;
     }
     const selected = targets.targets.find((entry) => entry.id === target.id && entry.attached === true);
     if (selected && statusMatchesTarget(status.status, selected) && status.status.targetReady !== false) {
       return { ok: true, status: status.status, target: selected };
     }
-    await delay8(intervalMs);
+    await delay9(intervalMs);
   }
   return { ok: false, error: lastError };
 };
@@ -50334,7 +50764,7 @@ var originOf = (url) => {
   }
 };
 var shortenId = (id) => id.length > 18 ? `${id.slice(0, 14)}...` : id;
-var delay8 = (ms3) => new Promise((resolve2) => setTimeout(resolve2, ms3));
+var delay9 = (ms3) => new Promise((resolve2) => setTimeout(resolve2, ms3));
 var formatError8 = (error) => error instanceof Error ? error.message : String(error);
 
 // dist/commands/extension/use.js
@@ -50750,22 +51180,43 @@ var extensionCommands = [
     description: "Browser extension management",
     subcommands: [
       {
-        name: "setup <extensionId>",
-        description: "Install native messaging host for the browser extension",
+        name: "install",
+        description: "Set up the extension end-to-end: install hosts, open chrome://extensions, wait for connect",
+        options: [
+          { flags: "--no-open", description: "Do not open chrome://extensions automatically" },
+          { flags: "--no-wait", description: "Do not wait for the extension to connect" },
+          { flags: "--timeout <seconds>", description: "Seconds to wait for the extension to connect (default 120)" },
+          jsonOption2
+        ],
+        examples: ["argus extension install", "argus extension install --no-open", "argus extension install --no-wait --json"],
+        action: async (options) => {
+          await runExtensionInstall(options);
+        }
+      },
+      {
+        name: "setup [extensionId]",
+        description: "Install native messaging host (uses the pinned extension ID by default)",
         options: [jsonOption2],
         configure: (command) => {
           command.addHelpText("after", `
-To get your extension ID:
-  1. Open chrome://extensions
-  2. Enable Developer mode
-  3. Load argus-extension as unpacked
-  4. Copy the ID from the extension card
+The Argus extension pins a stable ID, so no argument is needed.
+Prefer \`argus extension install\` for the guided, end-to-end flow.
+Pass an explicit id only when loading a differently-keyed build.
 `);
         },
         action: async (extensionId, options) => {
           await runExtensionSetup({ extensionId, ...options });
         }
       },
+      {
+        name: "path",
+        description: 'Print the path to the unpacked extension for chrome://extensions "Load unpacked"',
+        options: [jsonOption2],
+        examples: ["argus extension path", "argus extension path --json"],
+        action: (options) => {
+          runExtensionPath(options);
+        }
+      },
       {
         name: "remove",
         description: "Uninstall native messaging host",
@@ -50923,9 +51374,9 @@ same sticky shown+focused lock as \`argus page show <watcherId>\`.
 ];
 
 // dist/commands/skill.js
-import fs18 from "node:fs";
-import path23 from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import fs19 from "node:fs";
+import path24 from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 var SKILL_PATH_PARTS = ["skill", "argus", "SKILL.md"];
 var runSkill = (options) => {
   const output = createOutput(options);
@@ -50950,18 +51401,18 @@ ${resolveArgusSkillCandidates().join(`
 };
 var resolveArgusSkillPath = () => {
   for (const candidate of resolveArgusSkillCandidates()) {
-    if (fs18.existsSync(candidate)) {
+    if (fs19.existsSync(candidate)) {
       return candidate;
     }
   }
   return null;
 };
 var resolveArgusSkillCandidates = () => {
-  const moduleDir = path23.dirname(fileURLToPath2(import.meta.url));
+  const moduleDir = path24.dirname(fileURLToPath3(import.meta.url));
   return [
-    path23.resolve(moduleDir, ...SKILL_PATH_PARTS),
-    path23.resolve(moduleDir, "..", ...SKILL_PATH_PARTS),
-    path23.resolve(moduleDir, "..", "..", "..", "..", ...SKILL_PATH_PARTS)
+    path24.resolve(moduleDir, ...SKILL_PATH_PARTS),
+    path24.resolve(moduleDir, "..", ...SKILL_PATH_PARTS),
+    path24.resolve(moduleDir, "..", "..", "..", "..", ...SKILL_PATH_PARTS)
   ];
 };