@swmansion/argent 0.19.1-next.5 → 0.19.1-next.6

package/dist/tool-server.cjs

@@ -143904,13 +143904,16 @@ async function appendStepToFlow(session, step) {
     if (session.persist === "host") {
       const flowFile = await appendStep(session.filePath, step);
       session.flow = parseFlow(flowFile);
-      return { flowFile, savedTo: session.filePath };
+      return { savedTo: session.filePath, stepCount: session.flow.steps.length };
     }
     session.flow.steps.push(step);
     try {
       validateFlow(session.flow);
       const flowFile = serializeFlow(session.flow);
-      return { flowFile, savedTo: clientFileDirective(session.filePath, flowFile) };
+      return {
+        savedTo: clientFileDirective(session.filePath, flowFile),
+        stepCount: session.flow.steps.length
+      };
     } catch (err) {
       session.flow.steps.pop();
       throw err;
@@ -143964,7 +143967,9 @@ executionPrerequisite instead. Use flow-add-echo to add labels. Call
 flow-finish-recording when done.
 
 If a recorded step turns out to be wrong, you can edit the .yaml file directly
-to remove or reorder steps.`,
+to remove or reorder steps. Against a remote client, only after
+flow-finish-recording: the in-memory copy is authoritative there, and every
+write serializes it over your edit.`,
   zodSchema: zodSchema61,
   fileInputs: fileInputs2,
   services: () => ({}),
@@ -144022,10 +144027,141 @@ to remove or reorder steps.`,
 
 // ../tool-server/src/tools/flows/flow-add-step.ts
 init_zod();
-var fs44 = __toESM(require("node:fs/promises"));
+var fs45 = __toESM(require("node:fs/promises"));
 var path32 = __toESM(require("node:path"));
 init_src();
 
+// ../tool-server/src/tools/flows/flow-finish-recording.ts
+init_zod();
+var fs44 = __toESM(require("node:fs/promises"));
+function selectorLabel(sel) {
+  return JSON.stringify(selectorToYaml(sel));
+}
+function textConditionLabel(sel, expectedText, textMatch) {
+  const selector = selectorLabel(sel);
+  const expected = expectedText ?? "";
+  return textMatch === "matches" ? `text ${selector} matches /${expected}/` : textMatch === "equals" ? `text ${selector} == ${JSON.stringify(expected)}` : `text ${selector} contains ${JSON.stringify(expected)}`;
+}
+var zodSchema62 = external_exports.object({
+  name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
+  project_root: external_exports.string().describe(
+    "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording to finish."
+  )
+});
+var flowFinishRecordingTool = {
+  id: "flow-finish-recording",
+  interaction: {
+    // Name the flow: other recordings stay live across this call, so an
+    // unqualified "Finishing flow recording" would not identify which one.
+    startedMsg: ({ params }) => `Finishing recording of flow ${params.name}`,
+    // `params.name` rather than the basename of `result.path`: the two are the
+    // same string on every branch — `assertSafeFlowName` admits no dots or
+    // separators, so `getFlowPath` produces `<name>.yaml` and nothing else —
+    // and this spelling matches the two formatters either side of it.
+    completedMsg: ({ params }) => `Saved recorded flow ${params.name}`,
+    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to finish recording of flow ${params.name}: ${failureSignal2.error_code}`
+  },
+  description: `Finish recording the flow named by \`name\` + \`project_root\`, leaving recordings under any other key untouched. Returns { message, path, executionPrerequisite, steps, summary, flowFile, savedTo } - a summary of all recorded steps plus the final YAML. Use when you have added all desired steps and want to finalize the flow file. Fails if that flow has no recording in progress.
+You can still edit the .yaml file directly afterwards to remove or reorder steps.`,
+  zodSchema: zodSchema62,
+  services: () => ({}),
+  async execute(_services, params) {
+    const { filePath, flowFile, savedTo, flow, summary } = await withFlowFileLock(
+      params.project_root,
+      params.name,
+      async () => {
+        const session = await requireRecordingSession(params.project_root, params.name);
+        const filePath2 = session.filePath;
+        let flowFile2;
+        let savedTo2;
+        if (session.persist === "client") {
+          flowFile2 = serializeFlow(session.flow);
+          savedTo2 = clientFileDirective(filePath2, flowFile2);
+        } else {
+          flowFile2 = await fs44.readFile(filePath2, "utf8");
+          savedTo2 = filePath2;
+        }
+        const flow2 = parseFlow(flowFile2);
+        const summary2 = summarizeSteps(flow2);
+        clearRecordingSession(session);
+        return { filePath: filePath2, flowFile: flowFile2, savedTo: savedTo2, flow: flow2, summary: summary2 };
+      }
+    );
+    return {
+      message: `Finished recording "${params.name}" flow (${flow.steps.length} steps)`,
+      path: filePath,
+      executionPrerequisite: flow.executionPrerequisite,
+      steps: flow.steps.length,
+      summary,
+      flowFile,
+      savedTo
+    };
+  }
+};
+function renderToolArgs(args) {
+  try {
+    return `${JSON.stringify(args)}`;
+  } catch {
+    return "[cyclic args]";
+  }
+}
+function delayLabel(step) {
+  if (!step.delayMs) return "";
+  const ms = Number(step.delayMs);
+  return Number.isFinite(ms) && ms >= 1 ? ` (after ${ms}ms)` : "";
+}
+function summarizeSteps(flow) {
+  return flow.steps.map((step, i) => summarizeStep(step, i + 1));
+}
+function summarizeStep(step, n) {
+  switch (step.kind) {
+    case "echo":
+      return `${n}. echo: ${step.message}`;
+    case "launch":
+      return `${n}. launch: ${typeof step.app === "string" ? step.app : JSON.stringify(step.app)}`;
+    case "run":
+      return `${n}. run: ${step.flow}`;
+    case "tap":
+    case "long-press": {
+      const target = step.selector ? selectorLabel(step.selector) : `(${step.x}, ${step.y})`;
+      const times = step.kind === "tap" && step.times !== void 0 && step.times > 1 ? ` \xD7${step.times}` : "";
+      const held = step.kind === "long-press" && step.duration !== void 0 ? ` for ${step.duration}ms` : "";
+      return `${n}. ${step.kind}: ${target}${times}${held}`;
+    }
+    case "type":
+      return `${n}. type: ${selectorLabel(step.into)} \u2190 "${step.text}"`;
+    case "await":
+    case "assert": {
+      const tail = step.condition === "text" ? textConditionLabel(step.selector, step.expectedText, step.textMatch) : `${step.condition} ${selectorLabel(step.selector)}`;
+      return `${n}. ${step.kind}: ${tail}`;
+    }
+    case "wait":
+      return `${n}. wait: ${step.ms}ms`;
+    case "when": {
+      const cond = step.condition.kind === "platform" ? `platform ${step.condition.platform}` : step.condition.condition === "text" ? textConditionLabel(
+        step.condition.selector,
+        step.condition.expectedText,
+        step.condition.textMatch
+      ) : `${step.condition.condition} ${selectorLabel(step.condition.selector)}`;
+      const count2 = step.steps.length;
+      return `${n}. when: ${cond} (${count2} step${count2 === 1 ? "" : "s"})`;
+    }
+    case "scroll-to":
+      return `${n}. scroll-to: ${selectorLabel(step.target)} (${step.direction})`;
+    case "pinch":
+      return `${n}. pinch: scale ${step.scale}${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
+    case "rotate":
+      return `${n}. rotate: by ${step.by}\xB0${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
+    case "snapshot":
+      return `${n}. snapshot: ${step.name}`;
+    case "idle":
+      return `${n}. await: screen idle`;
+    case "tool":
+    default:
+      return `${n}. tool: ${step.name} ${renderToolArgs(step.args)}${delayLabel(step)}`;
+  }
+}
+
 // ../tool-server/src/tools/flows/flow-device.ts
 init_src();
 var DEVICE_BIND_KEYS = ["udid", "device_id", "device"];
@@ -144585,7 +144721,7 @@ async function fetchFlowTree(registry2, device) {
 }
 
 // ../tool-server/src/tools/flows/flow-add-step.ts
-var zodSchema62 = external_exports.object({
+var zodSchema63 = external_exports.object({
   name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
   project_root: external_exports.string().describe(
     "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording this step belongs to."
@@ -144702,7 +144838,7 @@ async function captureRunTarget(session, args) {
   }
   try {
     assertSafeFlowName(name);
-    const realFlowPath = await fs44.realpath(session.filePath);
+    const realFlowPath = await fs45.realpath(session.filePath);
     const flowsDir = path32.dirname(realFlowPath);
     const fragPath = path32.join(flowsDir, `${name}.yaml`);
     const projectRoot = args.project_root;
@@ -144718,10 +144854,10 @@ async function captureRunTarget(session, args) {
         warning: `kept the raw flow-execute step \u2014 no sibling is named "${name}.yaml" (this filesystem matched it case-insensitively to "${spelling.actual}"), so a run: ${name} step would name a flow no case-sensitive checkout can find \u2014 ${recovery}`
       };
     }
-    parseFlow(await fs44.readFile(fragPath, "utf8"));
+    parseFlow(await fs45.readFile(fragPath, "utf8"));
     let executedPath;
     try {
-      executedPath = await fs44.realpath(path32.join(flowsDirFor(projectRoot), `${name}.yaml`));
+      executedPath = await fs45.realpath(path32.join(flowsDirFor(projectRoot), `${name}.yaml`));
     } catch {
       executedPath = void 0;
     }
@@ -144730,7 +144866,7 @@ async function captureRunTarget(session, args) {
         warning: `kept the raw flow-execute step \u2014 could not verify which file the live flow-execute ran ("${name}" has no canonical file in project_root's flows dir to compare the sibling against)`
       };
     }
-    if (executedPath !== await fs44.realpath(fragPath)) {
+    if (executedPath !== await fs45.realpath(fragPath)) {
       return {
         warning: `kept the raw flow-execute step \u2014 project_root "${projectRoot}" resolves "${name}" to "${executedPath}", not the recording's sibling "${fragPath}", so "${name}.yaml" beside the recording's real file is not the file the live flow-execute ran and a run: ${name} step would replay a different flow than the one that just ran`
       };
@@ -144752,9 +144888,10 @@ function createFlowAddStepTool(registry2) {
       completedMsg: ({ params }) => `Added ${params.command} step to flow ${params.name}`,
       failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to add ${params.command} step to flow ${params.name}: ${failureSignal2.error_code}`
     },
-    description: `Execute a tool call and record it as a step in the flow named by \`name\` + \`project_root\` (the recording must already be open \u2014 see flow-start-recording). Use when recording a flow and you want to run and capture each action. A coordinate \`gesture-tap\` is recorded as a portable \`tap: { selector }\` step when the tapped element has stable text/identifier (otherwise coordinates are kept with a warning); a \`restart-app\` is recorded as a \`launch\` step (record one FIRST to make the flow a self-contained e2e flow; restart-app has no chromium support, so a chromium flow records as a fragment \u2014 add the \`launch: { chromium: <app path> }\` line to the YAML afterward, deleting the executionPrerequisite line if one was recorded: a flow that starts with a launch must not declare it). Returns { message, toolResult, flowFile, savedTo } on success. If it fails an error is returned and nothing is recorded.
-If a step was recorded by mistake, edit the .yaml file directly to remove it.`,
-    zodSchema: zodSchema62,
+    description: `Execute a tool call and record it as a step in the flow named by \`name\` + \`project_root\` (the recording must already be open \u2014 see flow-start-recording). Use when recording a flow and you want to run and capture each action. A coordinate \`gesture-tap\` is recorded as a portable \`tap: { selector }\` step when the tapped element has stable text/identifier (otherwise coordinates are kept with a warning); a \`restart-app\` is recorded as a \`launch\` step (record one FIRST to make the flow a self-contained e2e flow; restart-app has no chromium support, so a chromium flow records as a fragment \u2014 add the \`launch: { chromium: <app path> }\` line to the YAML afterward, deleting the executionPrerequisite line if one was recorded: a flow that starts with a launch must not declare it).
+Returns { message, toolResult, stepCount, recorded, savedTo } on success. If it fails an error is returned and nothing is recorded.
+If a step was recorded by mistake, edit the .yaml to remove it \u2014 against a remote client, only after \`flow-finish-recording\`: the in-memory copy is authoritative there, and every write serializes it over your edit.`,
+    zodSchema: zodSchema63,
     services: () => ({}),
     async execute(_services, params, ctx) {
       const session = await requireRecordingSession(params.project_root, params.name);
@@ -144795,11 +144932,15 @@ If a step was recorded by mistake, edit the .yaml file directly to remove it.`,
           delayMs: params.delayMs
         };
       }
-      const { flowFile, savedTo } = await appendStepToFlow(session, step);
+      const { savedTo, stepCount } = await appendStepToFlow(session, step);
       return {
         message: `Step added to "${params.name}" flow${warning ? ` \u2014 ${warning}` : ""}`,
         toolResult,
-        flowFile,
+        stepCount,
+        recorded: summarizeStep(step, stepCount),
+        // Host mode: a path. Client mode: the directive that carries the YAML
+        // to the client, which IS the persistence mechanism there — the one
+        // place the full file still has to travel per step.
         savedTo
       };
     }
@@ -144808,7 +144949,7 @@ If a step was recorded by mistake, edit the .yaml file directly to remove it.`,
 
 // ../tool-server/src/tools/flows/flow-insert-echo.ts
 init_zod();
-var zodSchema63 = external_exports.object({
+var zodSchema64 = external_exports.object({
   name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
   project_root: external_exports.string().describe(
     "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording this echo belongs to."
@@ -144826,145 +144967,23 @@ var flowInsertEchoTool = {
   },
   description: `Record an echo step in the flow named by \`name\` + \`project_root\`. Echo steps print a message when the flow is replayed \u2014 useful as labels between tool calls.
 Use when you want to annotate a recorded flow with a human-readable label or checkpoint message.
-Returns { message, flowFile, savedTo }. Fails if that flow has no recording in progress.`,
-  zodSchema: zodSchema63,
+Returns { message, stepCount, savedTo }. Fails if that flow has no recording in progress.`,
+  zodSchema: zodSchema64,
   services: () => ({}),
   async execute(_services, params) {
     const session = await requireRecordingSession(params.project_root, params.name);
-    const { flowFile, savedTo } = await appendStepToFlow(session, {
+    const { savedTo, stepCount } = await appendStepToFlow(session, {
       kind: "echo",
       message: params.message
     });
     return {
       message: `Echo added to "${params.name}" flow`,
-      flowFile,
+      stepCount,
       savedTo
     };
   }
 };
 
-// ../tool-server/src/tools/flows/flow-finish-recording.ts
-init_zod();
-var fs45 = __toESM(require("node:fs/promises"));
-function selectorLabel(sel) {
-  return JSON.stringify(selectorToYaml(sel));
-}
-function textConditionLabel(sel, expectedText, textMatch) {
-  const selector = selectorLabel(sel);
-  const expected = expectedText ?? "";
-  return textMatch === "matches" ? `text ${selector} matches /${expected}/` : textMatch === "equals" ? `text ${selector} == ${JSON.stringify(expected)}` : `text ${selector} contains ${JSON.stringify(expected)}`;
-}
-var zodSchema64 = external_exports.object({
-  name: external_exports.string().describe("Name of the flow being recorded \u2014 the one passed to flow-start-recording."),
-  project_root: external_exports.string().describe(
-    "Absolute path to the project root of the flow being recorded \u2014 the same value passed to flow-start-recording. Together with `name` it identifies which recording to finish."
-  )
-});
-var flowFinishRecordingTool = {
-  id: "flow-finish-recording",
-  interaction: {
-    // Name the flow: other recordings stay live across this call, so an
-    // unqualified "Finishing flow recording" would not identify which one.
-    startedMsg: ({ params }) => `Finishing recording of flow ${params.name}`,
-    // `params.name` rather than the basename of `result.path`: the two are the
-    // same string on every branch — `assertSafeFlowName` admits no dots or
-    // separators, so `getFlowPath` produces `<name>.yaml` and nothing else —
-    // and this spelling matches the two formatters either side of it.
-    completedMsg: ({ params }) => `Saved recorded flow ${params.name}`,
-    failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to finish recording of flow ${params.name}: ${failureSignal2.error_code}`
-  },
-  description: `Finish recording the flow named by \`name\` + \`project_root\`, leaving recordings under any other key untouched. Returns { message, path, executionPrerequisite, steps, summary, flowFile, savedTo } - a summary of all recorded steps plus the final YAML. Use when you have added all desired steps and want to finalize the flow file. Fails if that flow has no recording in progress.
-You can still edit the .yaml file directly afterwards to remove or reorder steps.`,
-  zodSchema: zodSchema64,
-  services: () => ({}),
-  async execute(_services, params) {
-    const { filePath, flowFile, savedTo, flow, summary } = await withFlowFileLock(
-      params.project_root,
-      params.name,
-      async () => {
-        const session = await requireRecordingSession(params.project_root, params.name);
-        const filePath2 = session.filePath;
-        let flowFile2;
-        let savedTo2;
-        if (session.persist === "client") {
-          flowFile2 = serializeFlow(session.flow);
-          savedTo2 = clientFileDirective(filePath2, flowFile2);
-        } else {
-          flowFile2 = await fs45.readFile(filePath2, "utf8");
-          savedTo2 = filePath2;
-        }
-        const flow2 = parseFlow(flowFile2);
-        const summary2 = summarizeSteps(flow2);
-        clearRecordingSession(session);
-        return { filePath: filePath2, flowFile: flowFile2, savedTo: savedTo2, flow: flow2, summary: summary2 };
-      }
-    );
-    return {
-      message: `Finished recording "${params.name}" flow (${flow.steps.length} steps)`,
-      path: filePath,
-      executionPrerequisite: flow.executionPrerequisite,
-      steps: flow.steps.length,
-      summary,
-      flowFile,
-      savedTo
-    };
-  }
-};
-function renderToolArgs(args) {
-  try {
-    return `${JSON.stringify(args)}`;
-  } catch {
-    return "[cyclic args]";
-  }
-}
-function summarizeSteps(flow) {
-  return flow.steps.map((step, i) => {
-    const n = i + 1;
-    switch (step.kind) {
-      case "echo":
-        return `${n}. echo: ${step.message}`;
-      case "launch":
-        return `${n}. launch: ${typeof step.app === "string" ? step.app : JSON.stringify(step.app)}`;
-      case "run":
-        return `${n}. run: ${step.flow}`;
-      case "tap":
-      case "long-press":
-        return `${n}. ${step.kind}: ${step.selector ? selectorLabel(step.selector) : `(${step.x}, ${step.y})`}`;
-      case "type":
-        return `${n}. type: ${selectorLabel(step.into)} \u2190 "${step.text}"`;
-      case "await":
-      case "assert": {
-        const tail = step.condition === "text" ? textConditionLabel(step.selector, step.expectedText, step.textMatch) : `${step.condition} ${selectorLabel(step.selector)}`;
-        return `${n}. ${step.kind}: ${tail}`;
-      }
-      case "wait":
-        return `${n}. wait: ${step.ms}ms`;
-      case "when": {
-        const cond = step.condition.kind === "platform" ? `platform ${step.condition.platform}` : step.condition.condition === "text" ? textConditionLabel(
-          step.condition.selector,
-          step.condition.expectedText,
-          step.condition.textMatch
-        ) : `${step.condition.condition} ${selectorLabel(step.condition.selector)}`;
-        const count2 = step.steps.length;
-        return `${n}. when: ${cond} (${count2} step${count2 === 1 ? "" : "s"})`;
-      }
-      case "scroll-to":
-        return `${n}. scroll-to: ${selectorLabel(step.target)} (${step.direction})`;
-      case "pinch":
-        return `${n}. pinch: scale ${step.scale}${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
-      case "rotate":
-        return `${n}. rotate: by ${step.by}\xB0${step.selector ? ` on ${selectorLabel(step.selector)}` : ""}`;
-      case "snapshot":
-        return `${n}. snapshot: ${step.name}`;
-      case "idle":
-        return `${n}. await: screen idle`;
-      case "tool":
-      default:
-        return `${n}. tool: ${step.name} ${renderToolArgs(step.args)}`;
-    }
-  });
-}
-
 // ../tool-server/src/tools/flows/flow-run.ts
 init_zod();
 var fs49 = __toESM(require("node:fs/promises"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.19.1-next.5",
+  "version": "0.19.1-next.6",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",

package/skills/argent-create-flow/references/live-authoring.md

@@ -28,7 +28,7 @@ Obey these lifecycle rules:
 3. Give concurrent recordings separate devices. Their files are isolated, but their live device actions are not.
 4. Treat `flow-start-recording` as destructive. It always truncates the named YAML, including a finished or committed flow. `restarted` reports only a displaced live take.
 5. If a call says the recording is inactive, do not restart under that name. The completed take can still be on disk. Copy it aside or record under a fresh name.
-6. Inspect `toolResult`, `message`, and `flowFile` after each call. A call that errors records nothing, but a call that returns normally while reporting an unmet condition **does** append the step, and `message` says the step was added either way. `await-ui-element` is the case that turns up in practice (see [Live waits and checks](#live-waits-and-checks)).
+6. Inspect `toolResult`, `message`, and `recorded` after each call. A call that errors records nothing, but a call that returns normally while reporting an unmet condition **does** append the step, and `message` says the step was added either way. `await-ui-element` is the case that turns up in practice (see [Live waits and checks](#live-waits-and-checks)). Only `flow-start-recording` and `flow-finish-recording` return the whole YAML as `flowFile`. A step call returns `recorded` — one summary line for the step it appended — plus a running `stepCount`. Read `recorded`: the recorder does not always store the tool call you made, and that line is where a rewrite shows up. To see the whole file mid-recording, read it at `savedTo`. A `savedTo` that comes back `null` means the write failed on your side. The step is still in the recording, so continue: the next step rewrites the whole file, and `flow-finish-recording` returns `flowFile` regardless.
 7. Edit or reorder the YAML only after `flow-finish-recording`. An active remote recording can overwrite mid-recording edits.
 
 ## Start in the correct order
@@ -76,7 +76,7 @@ For every action:
 1. **Discover without mutation.** Use `describe`, iOS native discovery, `debugger-component-tree`, or `screenshot`. Do not record discovery or `debugger-*` calls: `port` is not a device-bind key, so a recorded one replays against whatever Metro owns that port.
 2. **Choose a durable target.** Prefer a stable id, then stable text or an accessibility label. On iOS, use native discovery for ids that trimmed accessibility output omits.
 3. **Add an echo.** Name the current state, action, and expected outcome before the action can fail.
-4. **Execute through `flow-add-step`.** Inspect the result and returned YAML immediately.
+4. **Execute through `flow-add-step`.** Inspect the result and the `recorded` line immediately.
 5. **Verify immediately.** Record outcome checks when their states first appear. After navigation, prove identity then readiness: record the identity check live, and add the readiness gate during polish.
 
 ### Record identity, then readiness, after every navigation
@@ -99,7 +99,7 @@ Without step 1, `hidden` also passes for a typo or an element that never existed
 
 ### Taps
 
-`flow-add-step` cannot receive a flow selector directly. Discover the element first, then record `gesture-tap` at its frame center; the live coordinates are transport for the gesture, not a final locator. The recorder reads the pre-tap tree and derives the selector in a fixed order — `id`, then `text`, then `role` — giving three outcomes. Read the returned flow file after every tap, because only two of them warn:
+`flow-add-step` cannot receive a flow selector directly. Discover the element first, then record `gesture-tap` at its frame center; the live coordinates are transport for the gesture, not a final locator. The recorder reads the pre-tap tree and derives the selector in a fixed order — `id`, then `text`, then `role` — giving three outcomes. Read the `recorded` line after every tap, because only two of them warn. It names the derived form — a selector map, or the kept point:
 
 1. **`tap: { id: ... }` or `tap: { text: ... }`** — the good case.
 2. **`tap: { role: ... }`, appended with no warning.** An icon-only button with neither id nor visible label lands here. `role` matches as a case-insensitive substring, so a replay screen holding a second control of that role can win the [ranking](flow-yaml.md#the-runner-tree-is-not-the-discovery-tree) and the tap reports a pass on the wrong control.