@vforsh/argus 0.1.20 → 0.1.21

package/dist/argus.js

@@ -5,15 +5,29 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
@@ -2130,7 +2144,7 @@ var {
 // package.json
 var package_default = {
   name: "@vforsh/argus",
-  version: "0.1.20",
+  version: "0.1.21",
   repository: {
     type: "git",
     url: "git+https://github.com/vforsh/argus.git",
@@ -6838,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) => {
@@ -9358,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);
@@ -9396,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,
@@ -9430,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);
@@ -9447,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
@@ -9481,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) {
@@ -9497,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
+    };
   }
 });
 
@@ -11905,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;
@@ -11980,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
   });
@@ -12034,6 +12204,7 @@ var createNetMockController = () => {
     lastError = null;
     const rule = {
       id: nextRuleId++,
+      scope: input.scope ?? "page",
       match: input.match,
       action: input.action,
       delayMs: input.delayMs,
@@ -12046,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,
@@ -12062,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)) {
@@ -12131,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,
@@ -17053,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);
@@ -17070,6 +17235,7 @@ var createWatcherHandle = async (options, watcherId) => {
       },
       reason: null
     });
+    netMockController.onTargetChanged();
     onIndicatorAttach(session, target);
   };
   const handleSourceDetach = (reason) => {
@@ -17097,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);
@@ -22101,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;
@@ -22108,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) => {
@@ -22296,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(", ")}]`;
 };
@@ -22415,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)" },
@@ -22441,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));
       }
     },
     {
@@ -22457,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));
       }
     },
     {
@@ -22471,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));
       }
     },
     {
@@ -22481,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));
       }
     }
   ]
@@ -22704,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(),
@@ -22717,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) => {
@@ -47417,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;
     }
@@ -47428,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})`);
   }
 });
 
@@ -47446,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;
@@ -48715,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 [];
@@ -48737,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)) => {