@swmansion/argent 0.14.1-next.7 → 0.14.1-next.8

package/dist/cli-cmds.mjs

@@ -7289,11 +7289,15 @@ function isScalarType(type) {
 }
 function coerceScalar(raw, type, field) {
   if (type === "number") {
+    if (raw.trim() === "")
+      throw new FlagParseException(`--${field} expected a number, got "${raw}"`);
     const n2 = Number(raw);
     if (Number.isNaN(n2)) throw new FlagParseException(`--${field} expected a number, got "${raw}"`);
     return n2;
   }
   if (type === "integer") {
+    if (raw.trim() === "")
+      throw new FlagParseException(`--${field} expected an integer, got "${raw}"`);
     const n2 = Number(raw);
     if (!Number.isInteger(n2))
       throw new FlagParseException(`--${field} expected an integer, got "${raw}"`);
@@ -7322,6 +7326,7 @@ function parseFlags(argv, schema) {
   let helpRequested = false;
   let rawArgs = null;
   const seenArrayFields = /* @__PURE__ */ new Set();
+  const jsonFields = /* @__PURE__ */ new Set();
   function takeNext(i2, flag) {
     if (i2 + 1 >= argv.length) {
       throw new FlagParseException(`--${flag} requires a value`);
@@ -7360,7 +7365,13 @@ function parseFlags(argv, schema) {
     if (flag.endsWith("-json")) {
       const fieldName = flag.slice(0, -"-json".length);
       const { value: value2, nextIndex: nextIndex2 } = inlineValue !== void 0 ? { value: inlineValue, nextIndex: i2 } : takeNext(i2, flag);
+      if (seenArrayFields.has(fieldName)) {
+        throw new FlagParseException(
+          `--${fieldName} and --${flag} cannot be mixed for the same field; pass it entirely as --${flag} '<json>' or --args '<json>'`
+        );
+      }
       args[fieldName] = parseJsonOrThrow(value2, `--${flag}`);
+      jsonFields.add(fieldName);
       i2 = nextIndex2;
       continue;
     }
@@ -7392,6 +7403,11 @@ function parseFlags(argv, schema) {
         );
       }
       const { value: value2, nextIndex: nextIndex2 } = inlineValue !== void 0 ? { value: inlineValue, nextIndex: i2 } : takeNext(i2, flag);
+      if (jsonFields.has(flag)) {
+        throw new FlagParseException(
+          `--${flag} and --${flag}-json cannot be mixed for the same field; pass it entirely as --${flag}-json '<json>' or --args '<json>'`
+        );
+      }
       const coerced = coerceScalar(value2, itemType, flag);
       if (!seenArrayFields.has(flag)) {
         args[flag] = [coerced];

package/dist/tool-server.cjs

@@ -111642,6 +111642,9 @@ Booted/ready devices are listed first. Platforms whose CLI is unavailable are si
 // ../tool-server/src/utils/variant-proposals.ts
 init_src();
 var MAX_COMMENT_LENGTH = 2e3;
+var MAX_PENDING_OUTCOMES = 32;
+var MAX_MATCH_VALUE_LENGTH = 200;
+var MAX_ANNOTATIONS = 200;
 function slug(s) {
   return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
 }
@@ -111695,6 +111698,18 @@ var VariantProposalStore = class {
   waitersList = [];
   /** Frozen result of the current round once the user submits. */
   lastOutcome = null;
+  /**
+   * Completed outcomes that finished with no `await_user_selection` parked to
+   * receive them directly (submitSelection's "no waiter" branch), queued in
+   * completion order. `autoRollIfCompleted` rolls into a fresh round on the
+   * very next `propose_variant` regardless of whether the outcome was ever
+   * retrieved — so this queue, unlike `lastOutcome`/`completed`/`consumed`
+   * (which describe only the CURRENT round), survives `reset()` and is
+   * drained first by `awaitSelection`, oldest first. Without it, a human's
+   * already-submitted selection is destroyed the moment the next
+   * `propose_variant` call rolls the round out from under it.
+   */
+  pendingOutcomes = [];
   /** Begin a fresh round, discarding the previous one's proposals/selections. */
   reset() {
     const superseded = this.waitersList.filter((w) => !w.settled);
@@ -111750,11 +111765,11 @@ var VariantProposalStore = class {
       });
     }
   }
-  autoRollIfConsumed() {
-    if (this.completed && this.consumed) this.reset();
+  autoRollIfCompleted() {
+    if (this.completed) this.reset();
   }
   proposeVariant(input) {
-    this.autoRollIfConsumed();
+    this.autoRollIfCompleted();
     if (input.udid && input.udid.trim()) this.device = input.udid.trim();
     const match = input.match ?? { by: "text", value: input.element };
     const key = `${match.by}:${match.value.trim().toLowerCase()}`;
@@ -111817,7 +111832,10 @@ var VariantProposalStore = class {
    */
   setCliSession(active, agents = []) {
     const transitioned = this.cliSession !== active;
-    if (transitioned && active && (this.completed || this.proposals.length > 0)) this.reset();
+    if (transitioned) {
+      if (this.completed || this.proposals.length > 0) this.reset();
+      this.pendingOutcomes = [];
+    }
     this.cliSession = active;
     this.lensAgents = active ? agents.map((a) => ({ ...a })) : [];
     this.lensAgentChoice = null;
@@ -111882,30 +111900,51 @@ var VariantProposalStore = class {
   }
   /** Called by the preview UI when the human presses "Complete selection". */
   submitSelection(input) {
-    const cleanAnnotations = (input.annotations ?? []).filter((a) => a && typeof a.comment === "string" && a.comment.trim()).map((a) => ({
+    const cleanAnnotations = (input.annotations ?? []).filter((a) => a && typeof a.comment === "string" && a.comment.trim()).slice(0, MAX_ANNOTATIONS).map((a) => ({
       target: String(a.target ?? "").slice(0, 200) || "(element)",
-      match: a.match,
+      // Cap the matcher value too — it is caller-supplied and, unlike the
+      // comment, was previously ingested uncapped.
+      match: {
+        by: a.match?.by ?? "text",
+        value: String(a.match?.value ?? "").slice(0, MAX_MATCH_VALUE_LENGTH)
+      },
       comment: a.comment.trim().slice(0, MAX_COMMENT_LENGTH)
     }));
     if (this.proposals.length === 0 && cleanAnnotations.length === 0) {
       throw new Error("Nothing to submit \u2014 no proposals and no comments.");
     }
-    this.submitted = input.selections.filter((s) => this.proposals.some((p) => p.id === s.elementId)).map(
-      (s) => s.comment === void 0 ? s : { ...s, comment: s.comment.slice(0, MAX_COMMENT_LENGTH) }
-    );
+    const seenElementIds = /* @__PURE__ */ new Set();
+    this.submitted = input.selections.filter((s) => this.proposals.some((p) => p.id === s.elementId)).filter((s) => {
+      if (seenElementIds.has(s.elementId)) return false;
+      seenElementIds.add(s.elementId);
+      return true;
+    }).map((s) => {
+      const capped = s.comment === void 0 ? s : { ...s, comment: s.comment.slice(0, MAX_COMMENT_LENGTH) };
+      return capped.variantId == null ? capped : { ...capped, variantId: capped.variantId.slice(0, MAX_MATCH_VALUE_LENGTH) };
+    });
     this.submittedAnnotations = cleanAnnotations;
     this.globalComment = (input.globalComment ?? "").trim().slice(0, MAX_COMMENT_LENGTH);
+    const wasResubmit = this.completed;
     this.completed = true;
-    this.consumed = false;
+    if (!wasResubmit) this.consumed = false;
     this.lastOutcome = this.buildOutcome();
     const round2 = this.round;
     const toSettle = this.waitersList.filter((w) => !w.settled && w.round === round2);
     this.waitersList = this.waitersList.filter((w) => w.round !== round2 || w.settled);
-    if (toSettle.length > 0) this.consumed = true;
-    if (this.cliSession) this.consumed = true;
-    for (const w of toSettle) {
-      w.settled = true;
-      w.settle(this.lastOutcome);
+    if (toSettle.length > 0) {
+      this.consumed = true;
+      for (const w of toSettle) {
+        w.settled = true;
+        w.settle(this.lastOutcome);
+      }
+    } else if (this.cliSession) {
+      this.consumed = true;
+    } else if (!this.consumed) {
+      this.pendingOutcomes = this.pendingOutcomes.filter((o) => o.round !== round2);
+      this.pendingOutcomes.push(this.lastOutcome);
+      if (this.pendingOutcomes.length > MAX_PENDING_OUTCOMES) {
+        this.pendingOutcomes.shift();
+      }
     }
     this.events.emit("changed");
     this.events.emit("selectionSubmitted");
@@ -111969,16 +112008,23 @@ var VariantProposalStore = class {
    * round is superseded), so concurrent / re-entrant awaits never strand.
    */
   awaitSelection(opts) {
+    if (opts.signal?.aborted) {
+      const err = new Error("await_user_selection aborted (client disconnected)");
+      err.name = "AbortError";
+      return Promise.reject(err);
+    }
+    if (this.pendingOutcomes.length > 0) {
+      const outcome = this.pendingOutcomes.shift();
+      if (outcome.round === this.round) this.consumed = true;
+      const morePending = this.pendingOutcomes.length > 0 || outcome.round !== this.round && this.proposals.length > 0;
+      return Promise.resolve(morePending ? { ...outcome, morePending: true } : outcome);
+    }
     if (this.completed && this.consumed) {
       return Promise.resolve({
         status: "no_proposals",
         message: "The previous selection round was already returned. Call propose_variant to stage new variants before awaiting again."
       });
     }
-    if (this.completed && !this.consumed) {
-      this.consumed = true;
-      return Promise.resolve(this.lastOutcome ?? this.buildOutcome());
-    }
     if (this.proposals.length === 0) {
       return Promise.resolve({
         status: "no_proposals",
@@ -112027,10 +112073,7 @@ var VariantProposalStore = class {
       this.waitersList.push(waiter);
       this.events.emit("changed");
       this.events.emit("awaitParked");
-      if (opts.signal) {
-        if (opts.signal.aborted) return onAbort();
-        opts.signal.addEventListener("abort", onAbort, { once: true });
-      }
+      if (opts.signal) opts.signal.addEventListener("abort", onAbort, { once: true });
     });
   }
 };
@@ -112910,6 +112953,13 @@ function descendantText(parsed, maxChars = 120) {
   const stack = [parsed];
   while (stack.length > 0) {
     const x = stack.pop();
+    if (attrIsTrue(x.attrs, "password")) {
+      if (!seen.has("[password]")) {
+        seen.add("[password]");
+        parts.push("[password]");
+      }
+      continue;
+    }
     for (const k of ["text", "content-desc"]) {
       const v = (x.attrs[k] ?? "").trim();
       if (v && !seen.has(v)) {
@@ -113001,6 +113051,9 @@ function computeNodeOutput(parsed, scrollClip, outputs, opts) {
   }
   const interactive = isInteractive(attrs);
   let label = labelOf(attrs);
+  if (attrIsTrue(attrs, "password")) {
+    label = "[password]";
+  }
   if (cls.endsWith(".ImageView") && !interactive && !label) {
     return keptChildren;
   }
@@ -113015,6 +113068,9 @@ function computeNodeOutput(parsed, scrollClip, outputs, opts) {
   if (interactive && bounds && keptChildren.length === 1) {
     const c = keptChildren[0];
     if (c.clickable && c.pixelBounds && rectsEqual(c.pixelBounds, bounds)) {
+      if (!c.label && label) c.label = label;
+      const rid = attrs["resource-id"];
+      if (!c.identifier && rid) c.identifier = rid;
       return [c];
     }
   }
@@ -113024,9 +113080,6 @@ function computeNodeOutput(parsed, scrollClip, outputs, opts) {
       (c) => !(c.role === "StaticText" && c.label && lower.includes(c.label.toLowerCase()) && !c.clickable)
     );
   }
-  if (attrIsTrue(attrs, "password")) {
-    label = "[password]";
-  }
   const node = makeUiNode(attrs, deriveUiAutomatorRole(cls), bounds, label, keptChildren);
   if (hiddenInScroll > 0) node.scrollHidden = hiddenInScroll;
   return [node];
@@ -113065,7 +113118,7 @@ function finalizeUiNode(n, children, sw, sh) {
     };
   } else {
     if (children.length === 0) return null;
-    if (children.length === 1) return children[0];
+    if (children.length === 1 && !n.label && !n.identifier) return children[0];
     const x1 = Math.min(...children.map((c) => c.frame.x));
     const y1 = Math.min(...children.map((c) => c.frame.y));
     const x2 = Math.max(...children.map((c) => c.frame.x + c.frame.width));
@@ -115430,7 +115483,7 @@ var LogFileWriter = class {
     const sourceFile = sourceUrl ? cleanSourceUrl(sourceUrl) ?? void 0 : void 0;
     const source = sourceFile !== void 0 && sourceLine !== void 0 ? `${sourceFile}:${sourceLine}` : "-";
     const flatMessage = entry.message.replace(/\n/g, " ");
-    const levelDisplay = LEVEL_DISPLAY[entry.level] ?? entry.level.toUpperCase().padEnd(5).slice(0, 5);
+    const levelDisplay = LEVEL_DISPLAY[entry.level] ?? entry.level.toUpperCase().padEnd(5);
     const line = `[L:${entry.id}] ${entry.timestamp} ${levelDisplay} ${source} | ${flatMessage}
 `;
     if (this.ready && this.fd !== null) {
@@ -115543,6 +115596,13 @@ function parseFlatLine(line) {
   };
 }
 
+// ../tool-server/src/utils/debugger/console-timestamp.ts
+var MAX_TIMESTAMP_MS = 864e13;
+function consoleTimestampToIso(rawTimestampMs) {
+  const usable = Number.isFinite(rawTimestampMs) && Math.abs(rawTimestampMs) <= MAX_TIMESTAMP_MS;
+  return new Date(usable ? rawTimestampMs : Date.now()).toISOString();
+}
+
 // ../tool-server/src/blueprints/chromium-js-runtime-debugger.ts
 var CHROMIUM_JS_RUNTIME_DEBUGGER_NAMESPACE = "ChromiumJsRuntimeDebugger";
 function chromiumJsRuntimeDebuggerRef(device) {
@@ -115669,7 +115729,7 @@ var chromiumJsRuntimeDebuggerBlueprint = {
       };
       logWriter.write({
         id: entry.id,
-        timestamp: new Date(ts).toISOString(),
+        timestamp: consoleTimestampToIso(ts),
         level: entry.level,
         message: entry.message,
         stackTrace: entry.stackTrace
@@ -117132,7 +117192,7 @@ var jsRuntimeDebuggerBlueprint = {
       };
       logWriter.write({
         id: entry.id,
-        timestamp: new Date(entry.timestamp * 1e3).toISOString(),
+        timestamp: consoleTimestampToIso(entry.timestamp),
         level: entry.level,
         message: entry.message,
         stackTrace: entry.stackTrace
@@ -122513,8 +122573,21 @@ function makeComponentTreeScript(opts) {
   return `(async function() {
   var REQUEST_ID = ${requestId};
   var TRACK_SKIPPED = ${trackSkipped};
+  // Deliver errors through the SAME binding channel as the success path. The
+  // consumer (evaluateWithBinding) runs Runtime.evaluate WITHOUT returnByValue/
+  // awaitPromise, so the IIFE's return value is discarded \u2014 a 'return' here never
+  // settles the promise and the tool hangs until the 15s binding timeout. Route
+  // every error through __argent_callback with result = JSON.stringify({ error }),
+  // matching the shape the tool parses (response.result \u2192 JSON.parse \u2192 .error).
+  function __argent_fail(msg) {
+    __argent_callback(JSON.stringify({ requestId: REQUEST_ID, result: JSON.stringify({ error: msg }) }));
+  }
+  // Route any UNEXPECTED throw (outside the named guards below) through the same
+  // binding, so a crash still settles immediately instead of hanging to the 15s
+  // binding timeout. Mirrors inspect-at-point.ts's top-level try/catch.
+  try {
   var hook = window.__REACT_DEVTOOLS_GLOBAL_HOOK__;
-  if (!hook) return JSON.stringify({ error: 'No DevTools hook' });
+  if (!hook) { __argent_fail('No DevTools hook'); return; }
   // Collect fiber roots across ALL renderers. A single React renderer id is not
   // safe to assume: secondary reconcilers (e.g. react-native-skia) frequently
   // register first and own renderer id 1, whose roots contain only that library's
@@ -122532,7 +122605,7 @@ function makeComponentTreeScript(opts) {
     var _legacy = hook.getFiberRoots(1);
     if (_legacy) _legacy.forEach(function(_rt) { _allRoots.push(_rt); });
   }
-  if (_allRoots.length === 0) return JSON.stringify({ error: 'No fiber roots' });
+  if (_allRoots.length === 0) { __argent_fail('No fiber roots'); return; }
   // Pick the mounted root with the largest fiber subtree \u2014 i.e. the real app UI.
   var root = _allRoots[0];
   var _bestSize = -1;
@@ -122562,7 +122635,7 @@ function makeComponentTreeScript(opts) {
         try { var m = __r(i); if (m && m.UIManager) { UIManagerMod = m.UIManager; break; } } catch(e) {}
       }
     }
-    if (!UIManagerMod) return JSON.stringify({ error: 'Could not find UIManager' });
+    if (!UIManagerMod) { __argent_fail('Could not find UIManager'); return; }
   }
 
   var SKIP = new Set([
@@ -122910,6 +122983,9 @@ function makeComponentTreeScript(opts) {
     result.skippedCounts = skippedCounts;
   }
   __argent_callback(JSON.stringify({ requestId: REQUEST_ID, result: JSON.stringify(result) }));
+  } catch (e) {
+    __argent_fail('Component-tree script crashed: ' + (e && e.message ? e.message : String(e)));
+  }
 })()`;
 }
 
@@ -131110,7 +131186,7 @@ function enrich(input) {
 }
 
 // ../tool-server/src/utils/react-profiler/pipeline/03-tag.ts
-var ANIMATED_PATTERN = /(Animated|Animation|Transition|Motion)/i;
+var ANIMATED_PATTERN = /(?<![A-Z0-9])(Animated|Animation|Transition|Motion)(?=[A-Z0-9_(.]|$)/;
 var RECYCLER_CHILD_PATTERN = /(ListItem|CellItem|Cell|Row|Item)$/i;
 var RECYCLER_PARENT_PATTERN = /^(FlatList|SectionList|VirtualizedList|FlashList|RecyclerListView)/i;
 function tag(input) {
@@ -135202,8 +135278,9 @@ async function renderHangStacksAndroid(opts, target) {
     return `_Invalid hang_index ${opts.hangIndex}. There are ${hangRows.length} hangs (0-indexed)._`;
   }
   const hang = hangRows[opts.hangIndex];
-  const startNs = hang.ts_ns;
-  const endNs = hang.ts_ns + hang.dur_ns;
+  const startNs = Number(hang.ts_ns);
+  const durNs = Number(hang.dur_ns);
+  const endNs = startNs + durNs;
   const [stateRows, sampleRows] = await Promise.all([
     runTpQuery({
       tracePath: opts.tracePath,
@@ -135224,18 +135301,22 @@ async function renderHangStacksAndroid(opts, target) {
       }
     }).catch(() => [])
   ]);
-  const durationMs = Math.round(hang.dur_ns / 1e6);
+  const durationMs = Math.round(durNs / 1e6);
+  const stateBreakdown = stateRows.map((r) => ({
+    state: r.state,
+    blockedFunction: r.blocked_function,
+    durationMs: Math.round(Number(r.total_dur_ns) / 1e6)
+  }));
   const lines = [
     `## Hang #${opts.hangIndex} \u2014 ${hang.kind} (${durationMs}ms)` + (hang.reason ? ` \u2014 reason: \`${hang.reason}\`` : ""),
     ""
   ];
-  if (stateRows.length > 0) {
+  if (stateBreakdown.length > 0) {
     lines.push("### Main-thread State Breakdown", "");
     lines.push("| State | Blocked on | Duration |", "|---|---|---|");
-    for (const row of stateRows) {
-      const ms = Math.round(row.total_dur_ns / 1e6);
+    for (const entry of stateBreakdown) {
       lines.push(
-        `| ${row.state} | ${row.blocked_function ? `\`${row.blocked_function}\`` : "\u2014"} | ${ms}ms |`
+        `| ${entry.state} | ${entry.blockedFunction ? `\`${entry.blockedFunction}\`` : "\u2014"} | ${entry.durationMs}ms |`
       );
     }
     lines.push("");
@@ -135258,13 +135339,7 @@ async function renderHangStacksAndroid(opts, target) {
       lines.push("```");
     }
   } else {
-    const blocking = summarizeHangBlocking(
-      stateRows.map((r) => ({
-        state: r.state,
-        blockedFunction: r.blocked_function,
-        durationMs: Math.round(r.total_dur_ns / 1e6)
-      }))
-    );
+    const blocking = summarizeHangBlocking(stateBreakdown);
     lines.push("### Main-thread Samples During Hang", "");
     if (blocking && blocking.kind === "blocked") {
       lines.push(
@@ -135274,7 +135349,7 @@ async function renderHangStacksAndroid(opts, target) {
       lines.push(
         `_No usable on-CPU stack samples were captured during this hang, even though the main thread was on-CPU (state \`${blocking.dominantState}\`, executing) for most of the window \u2014 the sampler could not unwind a call stack (commonly stripped or missing frame symbols). This is genuine main-thread CPU work, not a wait; see the state breakdown above._`
       );
-    } else if (stateRows.length > 0) {
+    } else if (stateBreakdown.length > 0) {
       lines.push(
         `_No on-CPU stack samples were captured during this hang. The main thread spent the window off-CPU or runnable-but-not-scheduled, so there is no CPU call stack to show; see the state breakdown above._`
       );
@@ -135405,8 +135480,12 @@ function cpuRowsToAggregatorRows(rows, traceStartNs) {
       timestampsNs: [],
       callChains: [{ chain: [dominant], count: row.sample_count }],
       precomputedBursts: parseBurstWindows(row.burst_windows, traceStartMs),
-      firstMs: Math.round((row.first_ts_ns - traceStartNs) / 1e6),
-      lastMs: Math.round((row.last_ts_ns - traceStartNs) / 1e6),
+      // first/last_ts_ns are absolute CLOCK_MONOTONIC ns: they exceed 2^53 after
+      // ~104 days of device uptime, so the WASM decoder hands them back as bigint
+      // (see readCell). traceStartNs is already a plain Number, so coerce here to
+      // avoid "Cannot mix BigInt and other types" — values stay integral.
+      firstMs: Math.round((Number(row.first_ts_ns) - traceStartNs) / 1e6),
+      lastMs: Math.round((Number(row.last_ts_ns) - traceStartNs) / 1e6),
       sampleCount: row.sample_count
     });
   }
@@ -135414,16 +135493,16 @@ function cpuRowsToAggregatorRows(rows, traceStartNs) {
 }
 function hangRowsToBottlenecks(rows, traceStartNs) {
   return rows.map((row) => {
-    const durationMs = Math.round(row.dur_ns / 1e6);
-    const startNs = row.ts_ns - traceStartNs;
+    const durNs = Number(row.dur_ns);
+    const startNs = Number(row.ts_ns) - traceStartNs;
     return {
       type: "ui_hang",
       platform: "android",
       hangType: row.kind,
-      durationMs,
+      durationMs: Math.round(durNs / 1e6),
       startTimeFormatted: formatTraceTime(startNs),
       startNs,
-      endNs: startNs + row.dur_ns,
+      endNs: startNs + durNs,
       suspectedFunctions: [],
       appCallChains: [],
       severity: classifyAndroidHangSeverity(row),
@@ -135473,7 +135552,7 @@ function formatTraceTime(ns) {
 function classifyAndroidHangSeverity(row) {
   if (row.kind === "anr") return "RED";
   if (row.reason === "App Deadline Missed") return "RED";
-  const durationMs = row.dur_ns / 1e6;
+  const durationMs = Number(row.dur_ns) / 1e6;
   if (durationMs > 500) return "RED";
   return "YELLOW";
 }
@@ -140825,11 +140904,14 @@ It parks until the user presses "Complete selection" in the Argent Lens window (
 that opens automatically on the user's screen), then returns their choices and any comments.
 
 Returns one of:
-  \u2022 { status: "completed", selections: [{ element, chosenVariant, comment? }], unselected,
-      annotations: [{ target, match, comment }], globalComment }
-        \u2014 the user is done; apply chosenVariant for each element (skip ones in \`unselected\`).
-        \`annotations\` are free-form comments the user pinned to specific on-screen elements via
-        the inspector \u2014 treat each as a change request for that element.
+  \u2022 { status: "completed", round, selections: [{ element, chosenVariant, comment? }], unselected,
+      annotations: [{ target, match, comment }], globalComment, morePending? }
+        \u2014 the user finished this round; apply chosenVariant for each element (skip ones in
+        \`unselected\`). \`annotations\` are free-form comments the user pinned to specific on-screen
+        elements via the inspector \u2014 treat each as a change request for that element.
+        If \`morePending\` is true, another already-decided round or a freshly-staged round is
+        still waiting \u2014 call await_user_selection AGAIN (repeat until you get a completed result
+        without \`morePending\`, a \`pending\`, or \`no_proposals\`); do not stop on this result alone.
   \u2022 { status: "pending", message, proposedElements } \u2014 timeoutSeconds elapsed with no submission.
         Expected, not an error: the proposals are still live; call await_user_selection AGAIN.
   \u2022 { status: "no_proposals" } \u2014 you called this before propose_variant.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.14.1-next.7",
+  "version": "0.14.1-next.8",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {