From 8e1ab25773b87cc370f529366443900777fa1856 Mon Sep 17 00:00:00 2001
From: ring-wdr <akswnd55@gmail.com>
Date: Thu, 26 Mar 2026 19:36:45 +0900
Subject: [PATCH 1/3] Restore post-rc3 CLI contracts for search and interaction
 flows

This commit lands the contract fixes that were validated against the
browser-backed harness and the manual 4310 scenario set. It wires
`node search --limit` through the CLI/runtime boundary, restores
structured truncation metadata, and makes `interact type` /
`interact press` honor `--target-text` and `--role` instead of
silently falling back or failing on selector-only assumptions.

Constraint: Must preserve the published click/source contracts while extending type/press targeting
Constraint: `.omx/` and PERF_VALIDATION.md are local-only and intentionally excluded
Rejected: Patch only the runtime search response | CLI still ignored --limit and invalid limit 0 still succeeded
Rejected: Add null-target guards only | would mask the missing targeting support instead of fixing it
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep the browser-backed harness aligned with the manual PR-check scenario set whenever interaction contracts change
Tested: npm run build; npm test; npm run test:integration; manual 4310 session open/search/source/click/type/press validation
Not-tested: Cross-platform manual interaction behavior outside the local Chromium-backed open-session path
---
 README.md                           |  10 +-
 docs/workflows.md                   |   7 +-
 scripts/run-integration-harness.mjs | 158 ++++++++++++++++++++++++++++
 src/cli.js                          | 122 +++++++++++++++++----
 src/runtime-script.js               |  25 ++++-
 src/server.js                       |  90 +++++++++++-----
 test/run-tests.js                   |  54 ++++++++++
 7 files changed, 405 insertions(+), 61 deletions(-)

diff --git a/README.md b/README.md
index 0bf384c..7cb7d92 100644
--- a/README.md
+++ b/README.md
@@ -159,13 +159,14 @@ rdt profiler export --session demo --compress
 - Use built-in `interact` commands before reaching for external Playwright helper scripts.
 - Current supported actions:
   - `rdt interact click --session <name> (--selector <css> | --text <value> | --role <role>) [--nth <index>] [--strict] [--delivery auto|playwright|dom]`
-  - `rdt interact type --session <name> --selector <css> --text <value>`
-  - `rdt interact press --session <name> --key <name> [--selector <css>]`
+  - `rdt interact type --session <name> (--selector <css> | --target-text <label> | --role <role>) [--nth <index>] [--strict] --text <value>`
+  - `rdt interact press --session <name> --key <name> [--selector <css> | --target-text <label> | --role <role>] [--nth <index>] [--strict]`
   - `rdt interact wait --session <name> --ms <n>`
 - These commands execute through the same Playwright session that owns the current `rdt` browser page.
 - `interact click` can resolve targets by CSS selector, visible text, or ARIA role.
+- `interact type` and targeted `interact press` can resolve controls by CSS selector, label text, or ARIA role.
 - `--nth` selects one match from a broader result set, and `--strict` requires exactly one match.
-- Responses now include `targetingStrategy`, `matchCount`, and `resolvedNth` alongside the delivery metadata.
+- Responses now include `targetingStrategy`, `targetingResolution`, `matchCount`, and `resolvedNth` alongside the delivery metadata.
 - `interact click` defaults to `--delivery auto`.
 - In `auto`, profiler-active clicks fall back to DOM dispatch and report `requestedDelivery`, `effectiveDelivery`, `profilerActive`, and `fallbackApplied`.
 - Use `--delivery playwright` to force Playwright pointer input, or `--delivery dom` to force DOM dispatch.
@@ -281,7 +282,8 @@ Use `node pick` when the agent knows the visible element but not the component n
 - `source reveal --structured` returns `status`, `available`, `mode`, `reason`, and `source` so automation can distinguish unavailable source data from a successful source payload.
 - `source reveal` without `--structured` preserves the raw legacy behavior and may return literal `null`.
 - `dom` is the first host element summary used for CLI highlight and DOM-oriented inspection.
-- `node search --structured` wraps search results in `{ items, query, snapshotId, matchCount, runtimeWarnings }`.
+- `node search --structured` wraps search results in `{ items, query, snapshotId, matchCount, returnedCount, truncated, runtimeWarnings }`.
+- `node search --limit <n>` trims the returned items to the requested count while preserving the full `matchCount`.
 - When `node search --structured` returns `matchCount: 0`, `runtimeWarnings` explains that the component may be absent from the current snapshot rather than absent from the codebase.
 - Profiler summary fields are commit-oriented CLI metrics, not the full DevTools profiler session schema.
 - `profiler summary` and exported summaries explicitly report:
diff --git a/docs/workflows.md b/docs/workflows.md
index 868fc5c..c1c5fa5 100644
--- a/docs/workflows.md
+++ b/docs/workflows.md
@@ -48,7 +48,7 @@ rdt source reveal <nodeId> --session demo --snapshot <snapshotId> --structured
 ```
 
 - `tree stats` is the lightweight summary path when `tree get --format json` is too heavy.
-- `node search --structured` keeps the default array-returning behavior opt-in while adding `matchCount` and `runtimeWarnings`.
+- `node search --structured` keeps the default array-returning behavior opt-in while adding `matchCount`, `returnedCount`, `truncated`, and `runtimeWarnings`.
 - `source reveal --structured` returns availability metadata instead of only raw `null`.
 
 Recovery flow:
@@ -79,13 +79,14 @@ Built-in interactions keep the investigation inside the same session instead of
 
 ```bash
 rdt interact click --session demo --role button --nth 0 --delivery auto
-rdt interact type --session demo --selector 'input[name="query"]' --text hello
+rdt interact type --session demo --target-text 'Filter inventory' --text hello
 rdt interact wait --session demo --ms 500
 ```
 
 - `interact click --delivery auto` uses Playwright pointer input by default.
 - When the profiler is active, `auto` may fall back to DOM dispatch and reports the applied delivery in the response payload.
 - Use one targeting mode per click: `--selector`, `--text`, or `--role`.
+- `interact type` and targeted `interact press` accept `--selector`, `--target-text`, or `--role`.
 - Add `--nth` to choose one match from a broader result set, or `--strict` to require exactly one match.
 
 After interaction, verify the app settled by collecting a fresh tree or reading profiler output instead of assuming the UI state changed correctly.
@@ -94,7 +95,7 @@ After interaction, verify the app settled by collecting a fresh tree or reading
 
 ```bash
 rdt profiler start --session demo
-rdt interact type --session demo --selector 'input[name="query"]' --text hello
+rdt interact type --session demo --target-text 'Filter inventory' --text hello
 rdt profiler stop --session demo
 rdt profiler summary --session demo
 rdt profiler ranked <commitId> --session demo --limit 10
diff --git a/scripts/run-integration-harness.mjs b/scripts/run-integration-harness.mjs
index 3b0cd4d..388b745 100644
--- a/scripts/run-integration-harness.mjs
+++ b/scripts/run-integration-harness.mjs
@@ -345,6 +345,33 @@ async function main() {
     );
     ensure(Array.isArray(searchPayload.items) && searchPayload.matchCount >= 1, "node-search-structured did not return any App matches");
 
+    const limitedSearchPayload = parseJsonResult(
+      "node-search-limit",
+      await runRdt([
+        "node",
+        "search",
+        "ResultRow",
+        "--session",
+        sessionName,
+        "--snapshot",
+        statsPayload.snapshotId,
+        "--structured",
+        "--limit",
+        "5",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(Array.isArray(limitedSearchPayload.items) && limitedSearchPayload.items.length === 5, "node-search-limit did not truncate items to 5");
+    ensure(limitedSearchPayload.returnedCount === 5, "node-search-limit did not report returnedCount 5");
+    ensure(limitedSearchPayload.matchCount > limitedSearchPayload.returnedCount, "node-search-limit did not report a truncated result set");
+    ensure(limitedSearchPayload.truncated === true, "node-search-limit did not report truncated=true");
+    ensure(
+      Array.isArray(limitedSearchPayload.runtimeWarnings)
+        && limitedSearchPayload.runtimeWarnings.some((warning) => warning.includes("--limit 5")),
+      "node-search-limit did not report the limit warning",
+    );
+
     const zeroMatchPayload = parseJsonResult(
       "node-search-zero-match",
       await runRdt([
@@ -362,6 +389,21 @@ async function main() {
     );
     ensure(zeroMatchPayload.matchCount === 0, "node-search-zero-match did not return matchCount 0");
     ensure(Array.isArray(zeroMatchPayload.runtimeWarnings) && zeroMatchPayload.runtimeWarnings.length > 0, "node-search-zero-match did not return runtimeWarnings");
+
+    const invalidSearchLimitResult = await runRdt([
+      "node",
+      "search",
+      "ResultRow",
+      "--session",
+      sessionName,
+      "--structured",
+      "--limit",
+      "0",
+      "--format",
+      "json",
+    ]);
+    ensure(invalidSearchLimitResult.code !== 0, "node-search-invalid-limit unexpectedly succeeded");
+    ensure(invalidSearchLimitResult.stderr.includes("--limit"), "node-search-invalid-limit did not explain the limit failure");
     logScenarioOk("tree-stats-and-structured-search");
 
     const appNodeId = searchPayload.items[0]?.id;
@@ -488,6 +530,122 @@ async function main() {
       "profiler-stop",
       await runRdt(["profiler", "stop", "--session", sessionName, "--format", "json"]),
     );
+
+    const targetTextType = parseJsonResult(
+      "type-target-text",
+      await runRdt([
+        "interact",
+        "type",
+        "--session",
+        sessionName,
+        "--target-text",
+        "Filter inventory",
+        "--text",
+        "billing",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(targetTextType.targetingStrategy === "target-text", "type-target-text did not use target-text targeting");
+    ensure(targetTextType.targetingResolution === "label-control", "type-target-text did not resolve through label-control");
+    ensure(targetTextType.target?.tagName === "input", "type-target-text did not resolve to an input");
+    ensure(targetTextType.textLength === 7, "type-target-text did not report the expected text length");
+
+    const targetTextPress = parseJsonResult(
+      "press-target-text",
+      await runRdt([
+        "interact",
+        "press",
+        "--session",
+        sessionName,
+        "--key",
+        "Enter",
+        "--target-text",
+        "Filter inventory",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(targetTextPress.targetingStrategy === "target-text", "press-target-text did not use target-text targeting");
+    ensure(targetTextPress.targetingResolution === "label-control", "press-target-text did not resolve through label-control");
+    ensure(targetTextPress.target?.tagName === "input", "press-target-text did not resolve to an input");
+
+    const roleType = parseJsonResult(
+      "type-role-targeting",
+      await runRdt([
+        "interact",
+        "type",
+        "--session",
+        sessionName,
+        "--role",
+        "textbox",
+        "--strict",
+        "--text",
+        "analytics",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(roleType.action === "type", "type-role-targeting did not report type action");
+    ensure(roleType.targetingStrategy === "role", "type-role-targeting did not use role targeting");
+    ensure(roleType.strict === true, "type-role-targeting did not report strict=true");
+
+    const rolePress = parseJsonResult(
+      "press-role-targeting",
+      await runRdt([
+        "interact",
+        "press",
+        "--session",
+        sessionName,
+        "--key",
+        "Enter",
+        "--role",
+        "textbox",
+        "--strict",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(rolePress.action === "press", "press-role-targeting did not report press action");
+    ensure(rolePress.targetingStrategy === "role", "press-role-targeting did not use role targeting");
+    ensure(rolePress.strict === true, "press-role-targeting did not report strict=true");
+    ensure(rolePress.effectiveDelivery === "keyboard", "press-role-targeting did not use keyboard delivery");
+
+    const invalidClickResult = await runRdt([
+      "interact",
+      "click",
+      "--session",
+      sessionName,
+      "--selector",
+      "button.counter",
+      "--text",
+      "Count is",
+    ]);
+    ensure(invalidClickResult.code !== 0, "invalid-click-targeting unexpectedly succeeded");
+    ensure(invalidClickResult.stderr.includes("Use exactly one"), "invalid-click-targeting did not explain the conflicting target failure");
+
+    const invalidTypeResult = await runRdt([
+      "interact",
+      "type",
+      "--session",
+      sessionName,
+      "--text",
+      "hello",
+    ]);
+    ensure(invalidTypeResult.code !== 0, "invalid-type-targeting unexpectedly succeeded");
+    ensure(invalidTypeResult.stderr.includes("Missing type target"), "invalid-type-targeting did not explain the missing target failure");
+
+    const invalidPressResult = await runRdt([
+      "interact",
+      "press",
+      "--session",
+      sessionName,
+      "--key",
+      "Enter",
+      "--strict",
+    ]);
+    ensure(invalidPressResult.code !== 0, "invalid-press-targeting unexpectedly succeeded");
+    ensure(invalidPressResult.stderr.includes("Missing press target"), "invalid-press-targeting did not explain the missing target failure");
     logScenarioOk("click-targeting-and-delivery");
   } finally {
     await closeSession(sessionName);
diff --git a/src/cli.js b/src/cli.js
index 0f98f6b..e196d46 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -96,27 +96,108 @@ function normalizeStructuredFlag(options) {
   return Boolean(options.structured);
 }
 
-function collectClickTargetingPayload(options) {
-  const targetingKeys = ["selector", "text", "role"].filter((key) => options[key] !== undefined && options[key] !== null);
-  ensure(targetingKeys.length > 0, "Missing click target. Use one of --selector, --text, or --role for `rdt interact click`.", {
-    code: "missing-click-target",
-  });
-  ensure(targetingKeys.length === 1, "Use exactly one of --selector, --text, or --role for `rdt interact click`.", {
-    code: "conflicting-click-target",
+function normalizePositiveIntegerOption(value, message, code) {
+  const numeric = Number(value);
+  ensure(Number.isInteger(numeric) && numeric > 0, message, { code });
+  return numeric;
+}
+
+function formatTargetOptions(targetKeys) {
+  return targetKeys.map((key) => `--${key.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`)}`).join(", ");
+}
+
+function collectTargetingPayload(options, config) {
+  const {
+    command,
+    targetKeys,
+    requireTarget = false,
+    missingCode,
+    conflictingCode,
+    invalidCode,
+  } = config;
+
+  const targetingKeys = targetKeys.filter((key) => options[key] !== undefined && options[key] !== null);
+  const targetOptions = formatTargetOptions(targetKeys);
+  const hasTargetingModifiers = Boolean(options.strict) || options.nth !== undefined;
+
+  if (requireTarget || hasTargetingModifiers) {
+    ensure(targetingKeys.length > 0, `Missing ${command} target. Use one of ${targetOptions} for \`rdt interact ${command}\`.`, {
+      code: missingCode,
+    });
+  }
+
+  if (targetingKeys.length === 0) {
+    return {};
+  }
+
+  ensure(targetingKeys.length === 1, `Use exactly one of ${targetOptions} for \`rdt interact ${command}\`.`, {
+    code: conflictingCode,
   });
-  ensure(!(options.strict && options.nth !== undefined), "Do not combine --strict with --nth for `rdt interact click`.", {
-    code: "invalid-click-targeting",
+  ensure(!(options.strict && options.nth !== undefined), `Do not combine --strict with --nth for \`rdt interact ${command}\`.`, {
+    code: invalidCode,
   });
 
   return {
-    selector: options.selector ? String(options.selector) : undefined,
-    text: options.text !== undefined ? String(options.text) : undefined,
-    role: options.role ? String(options.role) : undefined,
+    selector: targetKeys.includes("selector") && options.selector ? String(options.selector) : undefined,
+    text: targetKeys.includes("text") && options.text !== undefined ? String(options.text) : undefined,
+    targetText: targetKeys.includes("targetText") && options.targetText !== undefined ? String(options.targetText) : undefined,
+    role: targetKeys.includes("role") && options.role ? String(options.role) : undefined,
     nth: options.nth !== undefined ? Number(options.nth) : undefined,
     strict: Boolean(options.strict),
   };
 }
 
+function collectClickTargetingPayload(options) {
+  return collectTargetingPayload(options, {
+    command: "click",
+    targetKeys: ["selector", "text", "role"],
+    requireTarget: true,
+    missingCode: "missing-click-target",
+    conflictingCode: "conflicting-click-target",
+    invalidCode: "invalid-click-targeting",
+  });
+}
+
+function collectTypeTargetingPayload(options) {
+  return collectTargetingPayload(options, {
+    command: "type",
+    targetKeys: ["selector", "targetText", "role"],
+    requireTarget: true,
+    missingCode: "missing-type-target",
+    conflictingCode: "conflicting-type-target",
+    invalidCode: "invalid-type-targeting",
+  });
+}
+
+function collectPressTargetingPayload(options) {
+  return collectTargetingPayload(options, {
+    command: "press",
+    targetKeys: ["selector", "targetText", "role"],
+    requireTarget: false,
+    missingCode: "missing-press-target",
+    conflictingCode: "conflicting-press-target",
+    invalidCode: "invalid-press-targeting",
+  });
+}
+
+function collectNodeSearchPayload(query, options) {
+  const payload = {
+    query,
+    structured: normalizeStructuredFlag(options),
+    ...collectSnapshotPayload(options),
+  };
+
+  if (options.limit !== undefined) {
+    payload.limit = normalizePositiveIntegerOption(
+      options.limit,
+      "Invalid --limit for `rdt node search`. Expected a positive integer.",
+      "invalid-search-limit",
+    );
+  }
+
+  return payload;
+}
+
 function resolveCommitId(positionals, options, message) {
   const commitId = positionals[0] ? String(positionals[0]) : (options.commit ? String(options.commit) : null);
   ensure(commitId, message, { code: "missing-commit-id" });
@@ -342,11 +423,7 @@ async function handleNodeCommand(command, positionals, options) {
   if (command === "search") {
     const query = positionals.join(" ");
     ensure(query, "Missing query for `rdt node search`.", { code: "missing-query" });
-    const response = await requestSession(options.session, "node.search", {
-      query,
-      structured: normalizeStructuredFlag(options),
-      ...collectSnapshotPayload(options),
-    });
+    const response = await requestSession(options.session, "node.search", collectNodeSearchPayload(query, options));
     await writeStdout(response.result, resolveFormat(options));
     return;
   }
@@ -387,10 +464,9 @@ async function handleInteractCommand(command, options) {
   }
 
   if (command === "type") {
-    ensure(options.selector, "Missing required option --selector for `rdt interact type`.", { code: "missing-selector" });
     ensure(options.text !== undefined, "Missing required option --text for `rdt interact type`.", { code: "missing-text" });
     const response = await requestSession(options.session, "interact.type", {
-      selector: String(options.selector),
+      ...collectTypeTargetingPayload(options),
       text: String(options.text),
       timeoutMs: options.timeoutMs ?? undefined,
     });
@@ -402,7 +478,7 @@ async function handleInteractCommand(command, options) {
     ensure(options.key, "Missing required option --key for `rdt interact press`.", { code: "missing-key" });
     const response = await requestSession(options.session, "interact.press", {
       key: String(options.key),
-      selector: options.selector ? String(options.selector) : undefined,
+      ...collectPressTargetingPayload(options),
       timeoutMs: options.timeoutMs ?? undefined,
     });
     await writeStdout(response.result, resolveFormat(options));
@@ -819,12 +895,12 @@ Usage:
   rdt tree get --session <name> [--format json|yaml|pretty]
   rdt tree stats --session <name> [--top <n>] [--format json|yaml|pretty]
   rdt node inspect <id> --session <name> [--snapshot <id>] [--commit <id>]
-  rdt node search <query> --session <name> [--snapshot <id>] [--structured]
+  rdt node search <query> --session <name> [--snapshot <id>] [--structured] [--limit <n>]
   rdt node highlight <id> --session <name> [--snapshot <id>]
   rdt node pick --session <name> [--timeout-ms 30000]
   rdt interact click --session <name> (--selector <css> | --text <value> | --role <role>) [--nth <index>] [--strict] [--delivery auto|playwright|dom] [--timeout-ms <ms>]
-  rdt interact type --session <name> --selector <css> --text <value> [--timeout-ms <ms>]
-  rdt interact press --session <name> --key <name> [--selector <css>] [--timeout-ms <ms>]
+  rdt interact type --session <name> (--selector <css> | --target-text <label> | --role <role>) [--nth <index>] [--strict] --text <value> [--timeout-ms <ms>]
+  rdt interact press --session <name> --key <name> [--selector <css> | --target-text <label> | --role <role>] [--nth <index>] [--strict] [--timeout-ms <ms>]
   rdt interact wait --session <name> --ms <n>
   rdt profiler start --session <name> [--profile-id <id>]
   rdt profiler stop --session <name>
diff --git a/src/runtime-script.js b/src/runtime-script.js
index 27610e1..226403a 100644
--- a/src/runtime-script.js
+++ b/src/runtime-script.js
@@ -1069,12 +1069,21 @@ export function runtimeBootstrap() {
     return details;
   }
 
-  function searchNodes(query, snapshotId, preferredEngine, structured) {
+  function searchNodes(query, snapshotId, preferredEngine, structured, limit) {
     const snapshot = resolveSnapshot(snapshotId, true, preferredEngine);
     if (snapshot?.__rdtError) {
       return snapshot;
     }
 
+    const normalizedLimit = limit == null ? null : Number(limit);
+    if (limit != null && (!Number.isInteger(normalizedLimit) || normalizedLimit <= 0)) {
+      return createRuntimeError(
+        "invalid-search-limit",
+        `Invalid search limit: ${limit}. Expected a positive integer.`,
+        { limit },
+      );
+    }
+
     if (!snapshot) {
       return structured
         ? {
@@ -1082,6 +1091,8 @@ export function runtimeBootstrap() {
             query: String(query || ""),
             snapshotId: null,
             matchCount: 0,
+            returnedCount: 0,
+            truncated: false,
             runtimeWarnings: [],
           }
         : [];
@@ -1095,9 +1106,10 @@ export function runtimeBootstrap() {
       snapshotId: snapshot.snapshotId,
       engine: snapshot.selectedEngine || buildEngineMetadata(preferredEngine).selectedEngine,
     }));
+    const returnedItems = normalizedLimit == null ? items : items.slice(0, normalizedLimit);
 
     if (!structured) {
-      return items;
+      return returnedItems;
     }
 
     const runtimeWarnings = items.length === 0
@@ -1106,12 +1118,19 @@ export function runtimeBootstrap() {
           "Do not treat a zero-match snapshot search as proof that the component is absent from the codebase.",
         ]
       : [];
+    if (normalizedLimit != null && items.length > returnedItems.length) {
+      runtimeWarnings.push(
+        `Search matched ${items.length} components; returning the first ${returnedItems.length} because --limit ${normalizedLimit} was requested.`,
+      );
+    }
 
     return {
-      items,
+      items: returnedItems,
       query: String(query || ""),
       snapshotId: snapshot.snapshotId,
       matchCount: items.length,
+      returnedCount: returnedItems.length,
+      truncated: returnedItems.length < items.length,
       runtimeWarnings,
     };
   }
diff --git a/src/server.js b/src/server.js
index 9738ec6..eb8450d 100644
--- a/src/server.js
+++ b/src/server.js
@@ -237,6 +237,15 @@ function normalizeClickNth(value) {
   });
 }
 
+function hasInteractTarget(payload, command) {
+  return Boolean(
+    payload.selector
+      || payload.role
+      || payload.targetText !== undefined
+      || (command === "click" && payload.text !== undefined),
+  );
+}
+
 function parseServerArgv(argv) {
   const options = {};
 
@@ -712,18 +721,28 @@ class SessionServer {
     };
   }
 
-  buildClickLocator(page, payload) {
+  buildInteractLocator(page, payload, command) {
     if (payload.selector) {
       return {
         locator: page.locator(String(payload.selector)),
         targetingStrategy: "selector",
+        targetingResolution: "css-selector",
       };
     }
 
-    if (payload.text !== undefined) {
+    if (command === "click" && payload.text !== undefined) {
       return {
         locator: page.getByText(String(payload.text)),
         targetingStrategy: "text",
+        targetingResolution: "visible-text",
+      };
+    }
+
+    if (command !== "click" && payload.targetText !== undefined) {
+      return {
+        locator: page.getByLabel(String(payload.targetText)),
+        targetingStrategy: "target-text",
+        targetingResolution: "label-control",
       };
     }
 
@@ -731,38 +750,53 @@ class SessionServer {
       return {
         locator: page.getByRole(String(payload.role)),
         targetingStrategy: "role",
+        targetingResolution: "aria-role",
       };
     }
 
-    throw new CliError("Missing interact click target.", {
-      code: "missing-click-target",
+    throw new CliError(`Missing interact ${command} target.`, {
+      code: `missing-${command}-target`,
     });
   }
 
-  async resolveClickTarget(page, payload, timeoutMs) {
-    const { locator, targetingStrategy } = this.buildClickLocator(page, payload);
+  async resolveInteractTarget(page, payload, timeoutMs, command, { allowUntargeted = false } = {}) {
+    if (!hasInteractTarget(payload, command)) {
+      if (allowUntargeted) {
+        return {
+          locator: null,
+          targetingStrategy: null,
+          targetingResolution: null,
+          matchCount: null,
+          resolvedNth: null,
+          strict: false,
+        };
+      }
+    }
+
+    const { locator, targetingStrategy, targetingResolution } = this.buildInteractLocator(page, payload, command);
     await locator.first().waitFor({ state: "attached", timeout: timeoutMs });
 
     const matchCount = await locator.count();
     const strict = Boolean(payload.strict);
     if (strict && matchCount !== 1) {
       throw new CliError(
-        `Strict interact click expected exactly one match for ${targetingStrategy}, but found ${matchCount}.`,
-        { code: "interact-click-strict-mismatch" },
+        `Strict interact ${command} expected exactly one match for ${targetingStrategy}, but found ${matchCount}.`,
+        { code: `interact-${command}-strict-mismatch` },
       );
     }
 
     const resolvedNth = strict ? 0 : normalizeClickNth(payload.nth);
     if (resolvedNth >= matchCount) {
       throw new CliError(
-        `Interact click match index ${resolvedNth} is out of range for ${targetingStrategy} with ${matchCount} matches.`,
-        { code: "interact-click-index-out-of-range" },
+        `Interact ${command} match index ${resolvedNth} is out of range for ${targetingStrategy} with ${matchCount} matches.`,
+        { code: `interact-${command}-index-out-of-range` },
       );
     }
 
     return {
       locator: locator.nth(resolvedNth),
       targetingStrategy,
+      targetingResolution,
       matchCount,
       resolvedNth,
       strict,
@@ -788,23 +822,21 @@ class SessionServer {
 
     const selector = payload.selector ? String(payload.selector) : null;
     const text = payload.text !== undefined ? String(payload.text) : null;
+    const targetText = payload.targetText !== undefined ? String(payload.targetText) : null;
     const role = payload.role ? String(payload.role) : null;
-    let locator = selector ? page.locator(selector).first() : null;
-    let targetingStrategy = selector ? "selector" : null;
-    let matchCount = locator ? 1 : null;
-    let resolvedNth = null;
-    let strict = false;
-
-    if (command === "click") {
-      const clickTarget = await this.resolveClickTarget(page, payload, timeoutMs);
-      locator = clickTarget.locator;
-      targetingStrategy = clickTarget.targetingStrategy;
-      matchCount = clickTarget.matchCount;
-      resolvedNth = clickTarget.resolvedNth;
-      strict = clickTarget.strict;
-    } else if (locator) {
-      await locator.waitFor({ state: "attached", timeout: timeoutMs });
-    }
+    const resolvedTarget = await this.resolveInteractTarget(
+      page,
+      payload,
+      timeoutMs,
+      command,
+      { allowUntargeted: command === "press" },
+    );
+    let locator = resolvedTarget.locator;
+    let targetingStrategy = resolvedTarget.targetingStrategy;
+    let targetingResolution = resolvedTarget.targetingResolution;
+    let matchCount = resolvedTarget.matchCount;
+    let resolvedNth = resolvedTarget.resolvedNth;
+    let strict = resolvedTarget.strict;
 
     const target = locator
       ? await locator.evaluate((element) => ({
@@ -867,11 +899,13 @@ class SessionServer {
       profilerActive,
       fallbackApplied,
       targetingStrategy,
+      targetingResolution,
       matchCount,
       resolvedNth,
       strict,
       selector,
       textQuery: text,
+      targetText,
       role,
       target,
       key: payload.key ? String(payload.key) : null,
@@ -952,8 +986,8 @@ class SessionServer {
       case "node.search":
         await this.ensureReactDetected();
         return unwrapRuntimeResult(await this.page.evaluate(
-          ({ query, snapshotId, preferredEngine, structured }) => {
-            return window.__RDT_CLI_RUNTIME__.searchNodes(query, snapshotId, preferredEngine, structured);
+          ({ query, snapshotId, preferredEngine, structured, limit }) => {
+            return window.__RDT_CLI_RUNTIME__.searchNodes(query, snapshotId, preferredEngine, structured, limit);
           },
           { ...payload, preferredEngine: this.enginePreference },
         ));
diff --git a/test/run-tests.js b/test/run-tests.js
index 76fc195..6379cae 100644
--- a/test/run-tests.js
+++ b/test/run-tests.js
@@ -238,6 +238,22 @@ run("parseArgv preserves node search structured flag", () => {
   assert.equal(parsed.options.structured, true);
 });
 
+run("parseArgv preserves node search limit option", () => {
+  const parsed = parseArgv([
+    "node",
+    "search",
+    "ResultRow",
+    "--session",
+    "app",
+    "--structured",
+    "--limit",
+    "5",
+  ]);
+
+  assert.deepEqual(parsed.positionals, ["node", "search", "ResultRow"]);
+  assert.equal(parsed.options.limit, 5);
+});
+
 run("normalizeCliPositionals maps doctor alias to session doctor", () => {
   const parsed = parseArgv(["doctor", "--session", "app"]);
   const normalized = normalizeCliPositionals(parsed.positionals);
@@ -265,6 +281,44 @@ run("parseArgv preserves interact type options", () => {
   assert.equal(parsed.options.text, "abc");
 });
 
+run("parseArgv preserves interact type target-text options", () => {
+  const parsed = parseArgv([
+    "interact",
+    "type",
+    "--session",
+    "app",
+    "--target-text",
+    "Filter inventory",
+    "--text",
+    "billing",
+    "--strict",
+  ]);
+
+  assert.deepEqual(parsed.positionals, ["interact", "type"]);
+  assert.equal(parsed.options.targetText, "Filter inventory");
+  assert.equal(parsed.options.text, "billing");
+  assert.equal(parsed.options.strict, true);
+});
+
+run("parseArgv preserves interact press role options", () => {
+  const parsed = parseArgv([
+    "interact",
+    "press",
+    "--session",
+    "app",
+    "--key",
+    "Enter",
+    "--role",
+    "textbox",
+    "--strict",
+  ]);
+
+  assert.deepEqual(parsed.positionals, ["interact", "press"]);
+  assert.equal(parsed.options.key, "Enter");
+  assert.equal(parsed.options.role, "textbox");
+  assert.equal(parsed.options.strict, true);
+});
+
 run("parseArgv preserves profiler compare options", () => {
   const parsed = parseArgv([
     "profiler",

From e268dc5a0e91429a185b996b3a06387ce9147c20 Mon Sep 17 00:00:00 2001
From: ring-wdr <akswnd55@gmail.com>
Date: Thu, 26 Mar 2026 19:38:23 +0900
Subject: [PATCH 2/3] Clarify untargeted press compatibility without widening
 the API surface

The remaining risk after the contract-restoration pass was not a
broken code path but an ambiguous one: untargeted `interact press`
was still supported for compatibility, yet its response copy implied
selector-based targeting and it was not locked by explicit harness
coverage. This commit makes that compatibility behavior explicit in
responses, help text, and docs while adding regression checks for
page-level press and invalid strict/nth usage without a target.

Constraint: Keep untargeted press backward compatible instead of making press target-only
Constraint: Follow the existing public response shape rather than inventing new target sentinel values
Rejected: Require a target for every press action | higher safety, but a breaking change to an existing compatibility path
Rejected: Leave untargeted press undocumented | keeps the risk of future accidental regression and misleading output
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If untargeted press is ever removed, update help/docs/harness in the same change and treat it as a breaking CLI contract change
Tested: npm run build; npm test; npm run test:integration
Not-tested: Manual untargeted press behavior on non-Chromium browsers or non-open transports
---
 README.md                           |  2 ++
 docs/workflows.md                   |  2 ++
 scripts/run-integration-harness.mjs | 35 +++++++++++++++++++++++++++++
 src/cli.js                          |  4 ++++
 src/server.js                       |  8 ++++++-
 5 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7cb7d92..4704b0a 100644
--- a/README.md
+++ b/README.md
@@ -165,7 +165,9 @@ rdt profiler export --session demo --compress
 - These commands execute through the same Playwright session that owns the current `rdt` browser page.
 - `interact click` can resolve targets by CSS selector, visible text, or ARIA role.
 - `interact type` and targeted `interact press` can resolve controls by CSS selector, label text, or ARIA role.
+- `interact press` without a target remains a page-level keyboard action for compatibility; use a target when focus ambiguity would make the result nondeterministic.
 - `--nth` selects one match from a broader result set, and `--strict` requires exactly one match.
+- For `interact type` and targeted `interact press`, `--strict` and `--nth` only make sense when one of `--selector`, `--target-text`, or `--role` is present.
 - Responses now include `targetingStrategy`, `targetingResolution`, `matchCount`, and `resolvedNth` alongside the delivery metadata.
 - `interact click` defaults to `--delivery auto`.
 - In `auto`, profiler-active clicks fall back to DOM dispatch and report `requestedDelivery`, `effectiveDelivery`, `profilerActive`, and `fallbackApplied`.
diff --git a/docs/workflows.md b/docs/workflows.md
index c1c5fa5..3471106 100644
--- a/docs/workflows.md
+++ b/docs/workflows.md
@@ -87,7 +87,9 @@ rdt interact wait --session demo --ms 500
 - When the profiler is active, `auto` may fall back to DOM dispatch and reports the applied delivery in the response payload.
 - Use one targeting mode per click: `--selector`, `--text`, or `--role`.
 - `interact type` and targeted `interact press` accept `--selector`, `--target-text`, or `--role`.
+- `interact press --key <name>` without a target remains a page-level keyboard action and depends on the browser's current focus state.
 - Add `--nth` to choose one match from a broader result set, or `--strict` to require exactly one match.
+- For `interact type` and targeted `interact press`, `--strict` and `--nth` require an explicit target.
 
 After interaction, verify the app settled by collecting a fresh tree or reading profiler output instead of assuming the UI state changed correctly.
 
diff --git a/scripts/run-integration-harness.mjs b/scripts/run-integration-harness.mjs
index 388b745..c1e6d0a 100644
--- a/scripts/run-integration-harness.mjs
+++ b/scripts/run-integration-harness.mjs
@@ -611,6 +611,28 @@ async function main() {
     ensure(rolePress.strict === true, "press-role-targeting did not report strict=true");
     ensure(rolePress.effectiveDelivery === "keyboard", "press-role-targeting did not use keyboard delivery");
 
+    const untargetedPress = parseJsonResult(
+      "press-page-keyboard",
+      await runRdt([
+        "interact",
+        "press",
+        "--session",
+        sessionName,
+        "--key",
+        "Escape",
+        "--format",
+        "json",
+      ]),
+    );
+    ensure(untargetedPress.action === "press", "press-page-keyboard did not report press action");
+    ensure(untargetedPress.targetingStrategy === null, "press-page-keyboard unexpectedly reported a targetingStrategy");
+    ensure(untargetedPress.target === null, "press-page-keyboard unexpectedly resolved a target");
+    ensure(
+      Array.isArray(untargetedPress.runtimeWarnings)
+        && untargetedPress.runtimeWarnings.some((warning) => warning.includes("active page keyboard focus")),
+      "press-page-keyboard did not warn about page-level keyboard focus",
+    );
+
     const invalidClickResult = await runRdt([
       "interact",
       "click",
@@ -646,6 +668,19 @@ async function main() {
     ]);
     ensure(invalidPressResult.code !== 0, "invalid-press-targeting unexpectedly succeeded");
     ensure(invalidPressResult.stderr.includes("Missing press target"), "invalid-press-targeting did not explain the missing target failure");
+
+    const invalidPressNthResult = await runRdt([
+      "interact",
+      "press",
+      "--session",
+      sessionName,
+      "--key",
+      "Enter",
+      "--nth",
+      "0",
+    ]);
+    ensure(invalidPressNthResult.code !== 0, "invalid-press-nth-targeting unexpectedly succeeded");
+    ensure(invalidPressNthResult.stderr.includes("Missing press target"), "invalid-press-nth-targeting did not explain the missing target failure");
     logScenarioOk("click-targeting-and-delivery");
   } finally {
     await closeSession(sessionName);
diff --git a/src/cli.js b/src/cli.js
index e196d46..3aa93f6 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -913,6 +913,10 @@ Usage:
   rdt profiler export --session <name> [--output file.jsonl] [--compress]
   rdt source reveal <id> --session <name> [--snapshot <id>] [--structured]
 
+Interaction notes:
+  - interact press without --selector/--target-text/--role sends a page-level keyboard press to the active browser focus
+  - --strict and --nth require an explicit target for interact type/press
+
 Snapshot behavior:
   - tree get returns snapshotId
   - node ids are scoped to that snapshot
diff --git a/src/server.js b/src/server.js
index eb8450d..3d4a0df 100644
--- a/src/server.js
+++ b/src/server.js
@@ -838,6 +838,7 @@ class SessionServer {
     let resolvedNth = resolvedTarget.resolvedNth;
     let strict = resolvedTarget.strict;
 
+    const targetedAction = Boolean(locator);
     const target = locator
       ? await locator.evaluate((element) => ({
           tagName: element.tagName.toLowerCase(),
@@ -882,10 +883,15 @@ class SessionServer {
     if (command === "click" && requestedDelivery === "dom" && !profilerActive) {
       runtimeWarnings.push("Click delivery was forced to DOM dispatch even though profiler fallback was not required.");
     }
+    if (command === "press" && !targetedAction) {
+      runtimeWarnings.push("Untargeted press dispatches to the active page keyboard focus; supply --selector, --target-text, or --role when element targeting matters.");
+    }
 
     const limitations = command === "click"
       ? ["interact click resolves a single locator match; without --strict, broader match sets may still require caller verification"]
-      : ["selector-based interaction targets the first matching element only"];
+      : targetedAction
+        ? ["interact type/press resolves a single locator match; without --strict, broader match sets may still require caller verification"]
+        : ["untargeted press uses the page keyboard directly and depends on the current browser focus state"];
 
     return {
       observationLevel: "observed",

From ec8d961c85e303c9c03c1290581c15c5417fb3e8 Mon Sep 17 00:00:00 2001
From: ring-wdr <akswnd55@gmail.com>
Date: Thu, 26 Mar 2026 19:48:21 +0900
Subject: [PATCH 3/3] Promote the CLI surface from prerelease to 0.2.0

The search and interaction contracts are now validated through unit,
integration, docs-build, pack, and publish dry-run lanes, so this
version bump marks the first stable cut after the rc series. The bug
report template is updated alongside the package metadata so the
reported version examples match the released channel.

Constraint: Publish workflow requires the GitHub release tag to match package.json exactly
Constraint: Stable versions publish to the npm latest tag instead of next
Rejected: Keep shipping rc builds | the CLI contracts are now stable enough to make the next stable line the source of truth
Rejected: Bump only package.json | would leave package-lock and issue template inconsistent with the release line
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Future stable releases should update package metadata, release tag, and user-facing version examples in the same change
Tested: npm run build; npm test; npm run test:integration; npm run docs:build; npm pack --dry-run; npm publish --dry-run
Not-tested: End-to-end npm publish from GitHub release until the release is actually created from main
---
 .github/ISSUE_TEMPLATE/bug_report.yml | 2 +-
 package-lock.json                     | 4 ++--
 package.json                          | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index e06d79d..3786dda 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -13,7 +13,7 @@ body:
     attributes:
       label: react-devtool-cli version
       description: Output of `rdt --version`
-      placeholder: 0.1.34
+      placeholder: 0.2.0
     validations:
       required: true
   - type: textarea
diff --git a/package-lock.json b/package-lock.json
index 07b6639..88f4a73 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "react-devtool-cli",
-  "version": "0.1.35-rc.3",
+  "version": "0.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "react-devtool-cli",
-      "version": "0.1.35-rc.3",
+      "version": "0.2.0",
       "license": "MIT",
       "dependencies": {
         "playwright": "1.58.2"
diff --git a/package.json b/package.json
index a29bb7d..023bfd2 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "react-devtool-cli",
-  "version": "0.1.35-rc.3",
+  "version": "0.2.0",
   "description": "Agent-first CLI for React component tree inspection, snapshot-aware node debugging, and profiler analysis through a Playwright-managed browser session.",
   "license": "MIT",
   "type": "module",