@swmansion/argent 0.32.1-next.8 → 0.32.1-next.9

package/dist/cli-cmds.mjs

@@ -35821,7 +35821,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.32.1-next.8";
+    return "0.32.1-next.9";
   }
   return "0.0.0";
 }

package/dist/installer.mjs

@@ -16946,7 +16946,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.32.1-next.8";
+    return "0.32.1-next.9";
   }
   return "0.0.0";
 }

package/dist/tool-args.generated.d.ts

@@ -10,7 +10,7 @@ export interface ArgentToolArgs {
         minStableMs?: number;
     };
     "await-ui-element": {
-        /** Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, HarmonyOS id, or Chromium id; not Apple TV, whose tree it cannot read). */
+        /** Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, HarmonyOS id, or Chromium id). */
         udid: string;
         /** What to wait for. `exists`: the selector matches an element anywhere in the tree. `visible`: it matches one with a non-zero on-screen frame. `hidden`: it matches nothing, or only a zero-area element (e.g. a spinner that went away). `text`: the first visible match in reading order (topmost, then leftmost; the first match overall if none is visible) contains expectedText, or equals it with textMatch `equals`. Only that match is checked, so if a loose selector hits several elements, narrow it to the one holding the text. */
         condition: "exists" | "visible" | "hidden" | "text";

package/dist/tool-server.cjs

@@ -95983,7 +95983,7 @@ var require_lexer = __commonJS({
   "../../node_modules/yaml/dist/parse/lexer.js"(exports2) {
     "use strict";
     var cst = require_cst();
-    function isEmpty2(ch) {
+    function isEmpty(ch) {
       switch (ch) {
         case void 0:
         case " ":
@@ -96061,7 +96061,7 @@ var require_lexer = __commonJS({
         }
         if (ch === "-" || ch === ".") {
           const dt = this.buffer.substr(offset, 3);
-          if ((dt === "---" || dt === "...") && isEmpty2(this.buffer[offset + 3]))
+          if ((dt === "---" || dt === "...") && isEmpty(this.buffer[offset + 3]))
             return -1;
         }
         return offset;
@@ -96160,7 +96160,7 @@ var require_lexer = __commonJS({
           if (!this.atEnd && !this.hasChars(4))
             return this.setNext("line-start");
           const s = this.peek(3);
-          if ((s === "---" || s === "...") && isEmpty2(this.charAt(3))) {
+          if ((s === "---" || s === "...") && isEmpty(this.charAt(3))) {
             yield* this.pushCount(3);
             this.indentValue = 0;
             this.indentNext = 0;
@@ -96168,7 +96168,7 @@ var require_lexer = __commonJS({
           }
         }
         this.indentValue = yield* this.pushSpaces(false);
-        if (this.indentNext > this.indentValue && !isEmpty2(this.charAt(1)))
+        if (this.indentNext > this.indentValue && !isEmpty(this.charAt(1)))
           this.indentNext = this.indentValue;
         return yield* this.parseBlockStart();
       }
@@ -96176,7 +96176,7 @@ var require_lexer = __commonJS({
         const [ch0, ch1] = this.peek(2);
         if (!ch1 && !this.atEnd)
           return this.setNext("block-start");
-        if ((ch0 === "-" || ch0 === "?" || ch0 === ":") && isEmpty2(ch1)) {
+        if ((ch0 === "-" || ch0 === "?" || ch0 === ":") && isEmpty(ch1)) {
           const n = (yield* this.pushCount(1)) + (yield* this.pushSpaces(true));
           this.indentNext = this.indentValue + 1;
           this.indentValue += n;
@@ -96240,7 +96240,7 @@ var require_lexer = __commonJS({
         const line = this.getLine();
         if (line === null)
           return this.setNext("flow");
-        if (indent !== -1 && indent < this.indentNext && line[0] !== "#" || indent === 0 && (line.startsWith("---") || line.startsWith("...")) && isEmpty2(line[3])) {
+        if (indent !== -1 && indent < this.indentNext && line[0] !== "#" || indent === 0 && (line.startsWith("---") || line.startsWith("...")) && isEmpty(line[3])) {
           const atFlowEndMarker = indent === this.indentNext - 1 && this.flowLevel === 1 && (line[0] === "]" || line[0] === "}");
           if (!atFlowEndMarker) {
             this.flowLevel = 0;
@@ -96282,7 +96282,7 @@ var require_lexer = __commonJS({
             return yield* this.parseQuotedScalar();
           case ":": {
             const next = this.charAt(1);
-            if (this.flowKey || isEmpty2(next) || next === ",") {
+            if (this.flowKey || isEmpty(next) || next === ",") {
               this.flowKey = false;
               yield* this.pushCount(1);
               yield* this.pushSpaces(true);
@@ -96345,7 +96345,7 @@ var require_lexer = __commonJS({
           else if (ch !== "-")
             break;
         }
-        return yield* this.pushUntil((ch) => isEmpty2(ch) || ch === "#");
+        return yield* this.pushUntil((ch) => isEmpty(ch) || ch === "#");
       }
       *parseBlockScalar() {
         let nl = this.pos - 1;
@@ -96427,10 +96427,10 @@ var require_lexer = __commonJS({
         while (ch = this.buffer[++i]) {
           if (ch === ":") {
             const next = this.buffer[i + 1];
-            if (isEmpty2(next) || inFlow && flowIndicatorChars.has(next))
+            if (isEmpty(next) || inFlow && flowIndicatorChars.has(next))
               break;
             end = i;
-          } else if (isEmpty2(ch)) {
+          } else if (isEmpty(ch)) {
             let next = this.buffer[i + 1];
             if (ch === "\r") {
               if (next === "\n") {
@@ -96497,7 +96497,7 @@ var require_lexer = __commonJS({
             case ":": {
               const inFlow = this.flowLevel > 0;
               const ch1 = this.charAt(1);
-              if (isEmpty2(ch1) || inFlow && flowIndicatorChars.has(ch1)) {
+              if (isEmpty(ch1) || inFlow && flowIndicatorChars.has(ch1)) {
                 if (!inFlow)
                   this.indentNext = this.indentValue + 1;
                 else if (this.flowKey)
@@ -96516,7 +96516,7 @@ var require_lexer = __commonJS({
         if (this.charAt(1) === "<") {
           let i = this.pos + 2;
           let ch = this.buffer[i];
-          while (!isEmpty2(ch) && ch !== ">")
+          while (!isEmpty(ch) && ch !== ">")
             ch = this.buffer[++i];
           return yield* this.pushToIndex(ch === ">" ? i + 1 : i, false);
         } else {
@@ -101180,7 +101180,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.32.1-next.8";
+    return "0.32.1-next.9";
   }
   return "0.0.0";
 }
@@ -134618,6 +134618,9 @@ var tvControlBlueprint = {
           focusable: r.focusable ?? []
         };
       },
+      async hierarchy() {
+        return await sendAx("hierarchy", 1e4);
+      },
       async navigate(direction) {
         await sendJson(hidSock, `navigate ${direction}`);
       },
@@ -148442,6 +148445,107 @@ function describeNestedParamError(registry2, err, toolId, dispatchedArgs, author
 // ../tool-server/src/tools/await-ui-element/index.ts
 init_zod();
 init_device_info();
+
+// ../tool-server/src/tools/describe/platforms/tv-focus.ts
+function focusRoot() {
+  return { role: "AXGroup", frame: { x: 0, y: 0, width: 1, height: 1 }, children: [] };
+}
+var TV_FOCUS_WAIT_EMPTY_HINT = "The Apple TV reports nothing on screen: the app may be launching, or the screen has no text or focusable elements, which a screenshot can tell apart.";
+function isEmptyFocus(res) {
+  return res.focusable.length === 0 && !res.focused;
+}
+function splitTvLabel(label) {
+  const lines = (label ?? "").split("\n").map((l) => l.trim()).filter(Boolean);
+  return { name: lines[0], context: lines.slice(1) };
+}
+function frameOf(element) {
+  const f = element.frame;
+  if (!f) return { x: 0, y: 0, width: 0, height: 0 };
+  const onScreen2 = f.x < 1 && f.y < 1 && f.x + f.width > 0 && f.y + f.height > 0;
+  return onScreen2 ? f : { x: f.x, y: f.y, width: 0, height: 0 };
+}
+var FOCUSED_TRAIT = "focused";
+function toNode(element) {
+  const traits = [...element.traits ?? []];
+  if (element.isFocused) traits.push(FOCUSED_TRAIT);
+  const frame2 = frameOf(element);
+  const { name, context: context2 } = splitTvLabel(element.label);
+  return {
+    // Traits are what a selector's `role` matches, exactly as on a phone.
+    role: traits.length > 0 ? traits.join(",") : "element",
+    frame: frame2,
+    // The context stays selectable (a tab's "selected"), and a `text` condition
+    // that contains it still holds, but `equals` compares the name `describe` shows.
+    children: context2.map((label) => ({ role: "context", frame: frame2, children: [], label })),
+    ...name ? { label: name } : {},
+    ...context2.length > 0 && element.label ? { subtreeText: element.label } : {},
+    ...element.value ? { value: element.value } : {},
+    // The cursor. `format-tree` already renders this as [focused], and it is
+    // what makes "wait until focus lands on X" expressible.
+    ...element.isFocused ? { focused: true } : {}
+  };
+}
+function contentElements(hierarchy, focusText) {
+  const out = [];
+  const screen = hierarchy?.screenFrame;
+  const walk = (node2) => {
+    for (const child of node2.children ?? []) {
+      const text = child.label || child.value;
+      if (text && !focusText.has(text)) {
+        const f = child.frame;
+        out.push({
+          label: child.label,
+          value: child.value,
+          ...f && screen?.width && screen.height ? {
+            frame: {
+              x: f.x / screen.width,
+              y: f.y / screen.height,
+              width: f.width / screen.width,
+              height: f.height / screen.height
+            }
+          } : {}
+        });
+      }
+      walk(child);
+    }
+  };
+  if (hierarchy?.tree) walk(hierarchy.tree);
+  return out;
+}
+function tvFocusTree(res, hierarchy = null) {
+  const elements = [...res.focusable];
+  if (res.focused && !res.focusable.some((e) => e.isFocused)) {
+    elements.push({ ...res.focused, isFocused: true });
+  }
+  const focusText = /* @__PURE__ */ new Set();
+  for (const e of elements) {
+    if (e.label) focusText.add(e.label);
+    if (e.value) focusText.add(e.value);
+  }
+  const root = focusRoot();
+  root.children = [...elements, ...contentElements(hierarchy, focusText)].map(toNode);
+  if (root.children.length === 0) {
+    return { tree: root, source: "tv-focus", hint: TV_FOCUS_WAIT_EMPTY_HINT };
+  }
+  return (hierarchy?.nodeCount ?? 0) > TV_HIERARCHY_NODE_CAP ? { tree: root, source: "tv-focus", partial: true, hint: TV_HIERARCHY_CAPPED_HINT } : { tree: root, source: "tv-focus" };
+}
+var TV_HIERARCHY_NODE_CAP = 800;
+var TV_HIERARCHY_CAPPED_HINT = "The Apple TV hierarchy stopped at its 800-element cap, so text past it was not read.";
+function hasTvCursor(tree) {
+  return tree.children.some((n) => n.focused);
+}
+async function describeTvFocus(api) {
+  const res = await api.describe();
+  if (!api.hierarchy) return tvFocusTree(res);
+  const hierarchy = await api.hierarchy().catch(async () => {
+    await new Promise((r) => setTimeout(r, HIERARCHY_RETRY_MS));
+    return api.hierarchy();
+  });
+  return tvFocusTree(res, hierarchy);
+}
+var HIERARCHY_RETRY_MS = 30;
+
+// ../tool-server/src/tools/await-ui-element/index.ts
 init_adb();
 init_capability();
 
@@ -154201,6 +154305,11 @@ var capability23 = {
 function evaluateMatches(params, matches2) {
   return evaluateCondition(params.condition, params.expectedText, matches2, params.textMatch);
 }
+function cannotJudge(data, matches2, everMatched, condition) {
+  if (isBlindRead(data, everMatched)) return true;
+  if (data.partial !== true) return false;
+  return condition === "exists" ? matches2.length === 0 : !matches2.some(isVisible);
+}
 function appendDiagnostics(base, lastData) {
   if (!lastData) return base;
   const extras = [];
@@ -154236,7 +154345,7 @@ function timeoutNote(params, lastTree, fetchError, lastData) {
 }
 var zodSchema29 = external_exports.object({
   udid: external_exports.string().min(1).describe(
-    "Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, <flag:harmonyos>HarmonyOS id, </flag:harmonyos>or Chromium id; not Apple TV, whose tree it cannot read)."
+    "Target device id from `list-devices` (iOS UDID, Android serial, Vega serial, <flag:harmonyos>HarmonyOS id, </flag:harmonyos>or Chromium id)."
   ),
   condition: external_exports.enum(["exists", "visible", "hidden", "text"]).describe(
     "What to wait for. `exists`: the selector matches an element anywhere in the tree. `visible`: it matches one with a non-zero on-screen frame. `hidden`: it matches nothing, or only a zero-area element (e.g. a spinner that went away). `text`: the first visible match in reading order (topmost, then leftmost; the first match overall if none is visible) contains expectedText, or equals it with textMatch `equals`. Only that match is checked, so if a loose selector hits several elements, narrow it to the one holding the text."
@@ -154262,12 +154371,13 @@ var zodSchema29 = external_exports.object({
   path: ["expectedText"]
 });
 function createAwaitUiElementTool(registry2) {
-  async function fetchTree(device, params, services, isTvOs, androidIsTv, budgetMs) {
+  async function fetchTree(device, params, services, tvApi, androidIsTv, budgetMs) {
     if (device.platform === "ios" || device.platform === "ios-remote") {
       if (device.kind === "device") {
         return describeIosDevice(registry2, device);
       }
-      return describeIos(registry2, device, { bundleId: params.bundleId }, { isTvOs });
+      if (tvApi) return describeTvFocus(tvApi);
+      return describeIos(registry2, device, { bundleId: params.bundleId }, { isTvOs: false });
     }
     if (device.platform === "android") {
       return describeAndroid(registry2, device.id, void 0, androidIsTv);
@@ -154313,6 +154423,7 @@ Returns { success: boolean, elapsed: number, note?, cause? }. If the condition d
       else if (device.platform === "vega") await ensureDeps(vegaRequires);
       else if (device.platform === "harmony") await ensureDeps(harmonyRequires);
       const isTvOs = device.platform === "ios" && device.kind !== "device" && await isTvOsSimulator(device.id);
+      const tvApi = isTvOs ? await resolveTvApi(registry2, device.id) : null;
       const androidIsTv = device.platform === "android" && await isAndroidTv(device.id);
       const start2 = Date.now();
       const cancelled = () => ({
@@ -154327,14 +154438,14 @@ Returns { success: boolean, elapsed: number, note?, cause? }. If the condition d
       let everMatched = false;
       let lastTrustedReadAt;
       const poll = await pollDescribeTree({
-        fetchTree: (budgetMs) => fetchTree(device, params, services, isTvOs, androidIsTv, budgetMs),
+        fetchTree: (budgetMs) => fetchTree(device, params, services, tvApi, androidIsTv, budgetMs),
         timeoutMs,
         pollIntervalMs,
         signal,
         onSample: (data, nowMs) => {
           const matches2 = findAll(data.tree, selector);
           if (matches2.length > 0) everMatched = true;
-          const blind = isBlindRead(data, everMatched);
+          const blind = cannotJudge(data, matches2, everMatched, params.condition);
           if (!blind && !data.stale) lastTrustedReadAt = nowMs;
           if (!blind && evaluateMatches(params, matches2)) {
             const result = { success: true, elapsed: Date.now() - start2 };
@@ -154350,7 +154461,12 @@ Returns { success: boolean, elapsed: number, note?, cause? }. If the condition d
       });
       if (poll.aborted) return cancelled();
       if (poll.result) return poll.result;
-      const finalRead = poll.lastAttempt === "unsettled" ? "unsettled" : poll.lastAttempt === "tree" && poll.lastData !== null && !poll.lastData.stale && !isBlindRead(poll.lastData, everMatched) ? "trusted" : "untrusted";
+      const finalRead = poll.lastAttempt === "unsettled" ? "unsettled" : poll.lastAttempt === "tree" && poll.lastData !== null && !poll.lastData.stale && !cannotJudge(
+        poll.lastData,
+        findAll(poll.lastData.tree, selector),
+        everMatched,
+        params.condition
+      ) ? "trusted" : "untrusted";
       return {
         success: false,
         elapsed: Date.now() - start2,
@@ -154439,7 +154555,7 @@ Allowed tools, their args (? = optional) and targets. Positions and distances ar
   fold: posture? "closed"|"half-open"|"open", or angle? 0\u2013180, exactly one (later steps land on the new panel, whose coordinates differ)  [foldable ios sim/android emu]
   tv-remote: button (one button, or an array run as a path in one step), repeat?  [apple tv/android tv/vega]
     buttons: up/down/left/right/select/back/home/menu/playPause; rewind/fastForward/next/previous/volumeUp/volumeDown/mute on Android TV and Vega only
-  await-ui-element: condition: "exists"|"visible"|"hidden"|"text", selector: { text?, identifier?, role? }, expectedText? (for "text"), textMatch?, timeoutMs?, pollIntervalMs?  [all but apple tv]`,
+  await-ui-element: condition: "exists"|"visible"|"hidden"|"text", selector: { text?, identifier?, role? }, expectedText? (for "text"), textMatch?, timeoutMs?, pollIntervalMs?  [all]`,
     zodSchema: zodSchema30,
     alwaysLoad: true,
     searchHint: "batch sequence multiple gesture steps sequentially",
@@ -157162,21 +157278,12 @@ var EMPTY_RETRY_ATTEMPTS = 3;
 var EMPTY_RETRY_DELAY_MS = 600;
 var EMPTY_HINT2 = "No focusable elements after retrying and recycling the read path. The app is most likely still launching (splash / loading screen) or mid-transition \u2014 this is normal right after launch-app / restart-app. Wait ~2-3s and call describe again; a React Native app only exposes focus once its JS bundle has loaded. If it stays empty, take a screenshot to confirm what's actually on screen.";
 var ANDROID_FOCUS_EMPTY_HINT = "The Android TV focus engine reported no focusable elements \u2014 common on react-native-tvos screens that drive focus with RN's own engine (invisible to the OS accessibility tree). Falling back to the full UI tree below. `tv-remote` (direction/select) still moves focus on these screens even though the labels aren't enumerable, so you can drive blind + screenshot to confirm.";
-function isEmpty(res) {
-  return res.focusable.length === 0 && !res.focused;
-}
-function primaryLabel(label) {
-  if (!label) return "(no label)";
-  const firstLine5 = label.split("\n")[0]?.trim();
-  return firstLine5 && firstLine5.length ? firstLine5 : "(no label)";
-}
 function fmtElement(e) {
   const traits = e.traits?.length ? ` [${e.traits.join(",")}]` : "";
   const value = e.value ? ` = "${e.value}"` : "";
-  const label = primaryLabel(e.label);
-  const extraLines = (e.label ?? "").split("\n").slice(1).map((l) => l.trim()).filter(Boolean);
-  const context2 = extraLines.length ? ` (${extraLines.join(" \xB7 ")})` : "";
-  return `${label}${value}${traits}${context2}`;
+  const { name, context: context2 } = splitTvLabel(e.label);
+  const extra = context2.length ? ` (${context2.join(" \xB7 ")})` : "";
+  return `${name ?? "(no label)"}${value}${traits}${extra}`;
 }
 function renderFocusView(res) {
   const lines = [];
@@ -157197,16 +157304,16 @@ async function describeTv(registry2, device) {
   const api = await resolveTvApi(registry2, device.id);
   let res = await api.describe();
   if (device.platform !== "android") {
-    for (let attempt = 1; attempt < EMPTY_RETRY_ATTEMPTS && isEmpty(res); attempt++) {
+    for (let attempt = 1; attempt < EMPTY_RETRY_ATTEMPTS && isEmptyFocus(res); attempt++) {
       await sleep15(EMPTY_RETRY_DELAY_MS);
       res = await api.describe();
     }
   }
-  if (isEmpty(res) && device.platform !== "android") {
+  if (isEmptyFocus(res) && device.platform !== "android") {
     await api.recycleAx();
     res = await api.describe();
   }
-  if (isEmpty(res) && device.platform === "android") {
+  if (isEmptyFocus(res) && device.platform === "android") {
     const data = await describeAndroid(registry2, device.id, void 0, true);
     return {
       description: `${ANDROID_FOCUS_EMPTY_HINT}
@@ -157218,7 +157325,7 @@ ${formatDescribeTree(data.tree, {
       hint: ANDROID_FOCUS_EMPTY_HINT
     };
   }
-  const empty2 = isEmpty(res);
+  const empty2 = isEmptyFocus(res);
   const description = empty2 ? `${renderFocusView(res)}
 
 Note: ${EMPTY_HINT2}` : renderFocusView(res);
@@ -158332,6 +158439,10 @@ var AWAIT_SCREEN_IDLE_TOOL_ID = "await-screen-idle";
 var DEFAULT_TIMEOUT_MS4 = 3e3;
 var DEFAULT_POLL_INTERVAL_MS2 = 200;
 var DEFAULT_MIN_STABLE_MS = 250;
+var TV_NO_CURSOR_STABLE_MS = 1200;
+var DARK_TAIL_POLLS = 2;
+var DARK_TAIL_MAX_MS = 2e3;
+var TV_NO_CURSOR_NOTE = "no element holds focus on this screen, so a remote press may be lost";
 var capability29 = {
   apple: { simulator: true, device: true },
   appleRemote: { simulator: true },
@@ -158352,6 +158463,20 @@ function treeSignature(root) {
   for (const child of root.children) walk(child);
   return parts2.join("\n");
 }
+function unsettledNote(lastData, lastError, darkTailMs) {
+  if (lastError) return `last tree read failed: ${lastError}`;
+  if (darkTailMs !== void 0) {
+    return `the tree read stopped answering: nothing came back for the last ${darkTailMs}ms`;
+  }
+  if (!lastData) return void 0;
+  if (lastData.tree.children.length > 0) return void 0;
+  const parts2 = ["the screen reported no content"];
+  if (lastData.should_restart) {
+    parts2.push("the foreground app may need a restart for native inspection");
+  }
+  if (lastData.hint) parts2.push(lastData.hint);
+  return parts2.join("; ");
+}
 var zodSchema44 = external_exports.object({
   udid: external_exports.string().min(1).describe(
     "Target device id from `list-devices` (iOS UDID, Android serial, <flag:harmonyos>HarmonyOS id, </flag:harmonyos>or Chromium id)."
@@ -158365,12 +158490,13 @@ var zodSchema44 = external_exports.object({
   )
 }).strict();
 function createAwaitScreenIdleTool(registry2) {
-  function fetchTree(device, services, isTvOs, androidIsTv, budgetMs) {
+  function fetchTree(device, services, tvApi, androidIsTv, budgetMs) {
     if (device.platform === "ios" || device.platform === "ios-remote") {
       if (device.kind === "device") {
         return describeIosDevice(registry2, device);
       }
-      return describeIos(registry2, device, {}, { isTvOs });
+      if (tvApi) return describeTvFocus(tvApi);
+      return describeIos(registry2, device, {}, { isTvOs: false });
     }
     if (device.platform === "android") {
       return describeAndroid(registry2, device.id, void 0, androidIsTv);
@@ -158383,8 +158509,8 @@ function createAwaitScreenIdleTool(registry2) {
   return {
     id: AWAIT_SCREEN_IDLE_TOOL_ID,
     description: `Block until the screen has rendered content and stopped changing, or the timeout elapses. It polls the same element tree as \`describe\`.
-Use when a launch or navigation must finish rendering before you take a screenshot or tap.
-Returns { settled, waitedMs, polls<flag:harmonyos>, note?</flag:harmonyos> }. If the screen never goes still before timeoutMs, it returns settled=false instead of failing.<flag:harmonyos> A note on settled=true means the screen it settled on is not live: a suspended HarmonyOS panel settles instantly on its last frame, and taps land nowhere until it is woken.</flag:harmonyos>`,
+Use when a launch or navigation must finish rendering before a screenshot or tap.
+Returns { settled, waitedMs, polls, note? }. If the screen never goes still before timeoutMs, it returns settled=false instead of failing.<flag:harmonyos> A note on settled=true means the screen it settled on is not live: a suspended HarmonyOS panel settles instantly on its last frame, and taps land nowhere until it is woken.</flag:harmonyos>`,
     zodSchema: zodSchema44,
     searchHint: "wait until screen settles idle stable stops changing animation transition rendered ready before screenshot",
     readOnly: true,
@@ -158410,16 +158536,20 @@ Returns { settled, waitedMs, polls<flag:harmonyos>, note?</flag:harmonyos> }. If
       else if (device.platform === "android") await ensureDeps(androidRequires);
       else if (device.platform === "harmony") await ensureDeps(harmonyRequires);
       const isTvOs = device.platform === "ios" && device.kind !== "device" && await isTvOsSimulator(device.id);
+      const tvApi = isTvOs ? await resolveTvApi(registry2, device.id) : null;
       const androidIsTv = device.platform === "android" && await isAndroidTv(device.id);
       const minStableMs = params.minStableMs ?? DEFAULT_MIN_STABLE_MS;
+      const pollIntervalMs = params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS2;
       let stableSignature;
       let stableSince = 0;
+      let lastReadAt = 0;
       const poll = await pollDescribeTree({
-        fetchTree: (budgetMs) => fetchTree(device, services, isTvOs, androidIsTv, budgetMs),
+        fetchTree: (budgetMs) => fetchTree(device, services, tvApi, androidIsTv, budgetMs),
         timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS4,
-        pollIntervalMs: params.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS2,
+        pollIntervalMs,
         signal: ctx?.signal,
         onSample: (data, nowMs) => {
+          lastReadAt = nowMs;
           if (data.tree.children.length === 0) {
             stableSignature = void 0;
             stableSince = 0;
@@ -158427,7 +158557,8 @@ Returns { settled, waitedMs, polls<flag:harmonyos>, note?</flag:harmonyos> }. If
           }
           const signature = treeSignature(data.tree);
           if (signature === stableSignature) {
-            if (nowMs - stableSince >= minStableMs) return { done: true, result: true };
+            const requiredMs = tvApi && !hasTvCursor(data.tree) ? Math.max(minStableMs, TV_NO_CURSOR_STABLE_MS) : minStableMs;
+            if (nowMs - stableSince >= requiredMs) return { done: true, result: true };
           } else {
             stableSignature = signature;
             stableSince = nowMs;
@@ -158436,12 +158567,17 @@ Returns { settled, waitedMs, polls<flag:harmonyos>, note?</flag:harmonyos> }. If
           return { done: false };
         }
       });
-      const note = poll.result === true && poll.lastData?.stale ? poll.lastData.hint : void 0;
+      const settled = poll.result === true;
+      const darkTailMs = Date.now() - lastReadAt;
+      const hung = lastReadAt > 0 && darkTailMs > Math.min(DARK_TAIL_POLLS * pollIntervalMs, DARK_TAIL_MAX_MS);
+      const note = settled ? poll.lastData?.stale ? poll.lastData.hint : void 0 : unsettledNote(poll.lastData, poll.lastError, hung ? darkTailMs : void 0);
+      const populatedNoCursor = tvApi && poll.lastData?.tree.children.length && !hasTvCursor(poll.lastData.tree);
+      const cursorNote = populatedNoCursor ? TV_NO_CURSOR_NOTE : void 0;
       return {
-        settled: poll.result === true,
+        settled,
         waitedMs: poll.elapsedMs,
         polls: poll.polls,
-        ...note ? { note } : {}
+        ...note || cursorNote ? { note: note ?? cursorNote } : {}
       };
     }
   };

package/package.json

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

package/skills/argent-tv-interact/SKILL.md

@@ -15,9 +15,9 @@ description: Control and inspect TV apps via argent, Apple TV (tvOS), Android TV
 
 ## The navigation loop
 
-1. `describe`: find the cursor and your target (returns the focused element + all focusable ones, not a tap tree).
-2. `tv-remote`: move focus toward the target. Prefer **one** call with a path ending in `select`, e.g. `{button:["down","right","select"]}`; count rows/columns from the frames to build the path.
-3. `describe` again to confirm. On a miss, repeat.
+1. `describe`: find the cursor and your target.
+2. `tv-remote`: move focus toward the target. Prefer **one** call with a path ending in `select`, e.g. `{button:["down","right","select"]}`; count rows/columns from the list order.
+3. `describe` again to confirm, or on Apple TV `await-ui-element {condition:"exists", selector:{text:"X", role:"focused"}}`. On a miss, repeat.
 
 ## Tools
 
@@ -29,7 +29,7 @@ description: Control and inspect TV apps via argent, Apple TV (tvOS), Android TV
 
 ### Apple TV (tvOS simulator)
 
-- Boot like any iOS sim (`boot-device`); the AX + HID daemons auto-start on the first `describe` / `tv-remote` (first call may take a few seconds).
+- Boot like any iOS sim (`boot-device`); the first `describe` / `tv-remote` starts the AX + HID daemons (a few seconds).
 - Dev build: `open-url {udid, url:"<scheme>://expo-development-client/?url=http%3A%2F%2F<HOST_IP>%3A8081"}` (`<HOST_IP>` = your Mac's LAN IP, shown on the launcher).
 
 ### Android TV (leanback emulator)