@jobshimo/browser-link 0.25.1 → 0.26.0

package/dist/extension/flow-registry.js

@@ -0,0 +1,260 @@
+/**
+ * In-flight flow registry + per-tab flow history — the state behind the
+ * popup's Flows panel and behind `deps.shouldCancel` (see `flow.ts`).
+ *
+ * Extracted out of `background.ts` for the same reason `idle-policy.ts`,
+ * `reconnect-policy.ts` and `flow-recording-policy.ts` were: the service
+ * worker itself is untestable (it reaches for `chrome.*` at import time),
+ * while THIS is the part with rules worth pinning down — the lifecycle of a
+ * running flow, what a cancel does to an id nobody recognises, the 20-entry
+ * history cap, and above all WHAT A HISTORY ENTRY IS ALLOWED TO CONTAIN.
+ *
+ * PRIVACY CONTRACT (same rule as the persistent map, enforced by
+ * `toHistoryEntry` and asserted in the tests): a history entry holds UI
+ * STRUCTURE AND OUTCOMES ONLY — counts, durations, a step index, a step
+ * KIND. Never page text, never a selector, never typed input, never a
+ * failure message. Flow error strings routinely quote the page (a
+ * `find: multiple-matches` error carries candidate labels), which is
+ * exactly why the failure message is dropped here rather than trimmed: the
+ * operator needs to know WHICH STEP died, not what the page said.
+ *
+ * The history lives in `chrome.storage.session` (written by
+ * `background.ts`, read by the popup through the same runtime-message
+ * channel) and therefore dies with the browser session BY DESIGN. This is
+ * an operator view, not an audit log.
+ */
+/** How many completed flows are kept per tab. Small on purpose — this is a
+ * "what just happened on this tab" panel in a 320px-wide popup, not a log. */
+export const MAX_FLOW_HISTORY_PER_TAB = 20;
+/** `chrome.storage.session` key holding one tab's flow history. Keyed by
+ * the CHROME tab id (not the browser-link `tab_N` id) because the popup
+ * only ever knows the former, and a tab that reconnects under a new
+ * browser-link id is still the same tab to the human looking at it. */
+export function flowHistoryKey(tabId) {
+    return `flow-history:${tabId}`;
+}
+export function createFlowRegistry() {
+    const flows = new Map();
+    return {
+        register({ flowId, tabId, steps, title }) {
+            flows.set(flowId, {
+                flowId,
+                tabId,
+                title: title ?? '',
+                startedAt: Date.now(),
+                steps,
+                cancelled: false,
+                // Step 0 of N until the runner reports its first step — "not
+                // started yet" rather than a fake "step 1".
+                progress: { step: 0, steps },
+            });
+        },
+        get(flowId) {
+            return flows.get(flowId);
+        },
+        cancel(flowId) {
+            const entry = flows.get(flowId);
+            if (!entry || entry.cancelled)
+                return false;
+            entry.cancelled = true;
+            return true;
+        },
+        cancelForTab(tabId) {
+            let cancelled = 0;
+            for (const entry of flows.values()) {
+                if (entry.tabId !== tabId || entry.cancelled)
+                    continue;
+                entry.cancelled = true;
+                cancelled += 1;
+            }
+            return cancelled;
+        },
+        finish(flowId) {
+            const entry = flows.get(flowId);
+            flows.delete(flowId);
+            return entry;
+        },
+        listRunning(now) {
+            const views = [];
+            for (const entry of flows.values()) {
+                views.push({
+                    flowId: entry.flowId,
+                    tabId: entry.tabId,
+                    title: entry.title,
+                    // Clamped at 0: `now` is supplied by the caller and a clock that
+                    // stepped backwards should read "0s", never "-4s".
+                    elapsedMs: Math.max(0, now - entry.startedAt),
+                    steps: entry.steps,
+                    step: entry.progress.step,
+                    ...(entry.progress.iteration === undefined
+                        ? {}
+                        : { iteration: entry.progress.iteration }),
+                    ...(entry.progress.iterations === undefined
+                        ? {}
+                        : { iterations: entry.progress.iterations }),
+                    cancelling: entry.cancelled,
+                });
+            }
+            // Insertion order is start order (Map preserves it and a flow is
+            // registered exactly once), so the oldest — the one most likely to
+            // be the runaway — sits at the top of the panel.
+            return views;
+        },
+    };
+}
+/** Sum the completed iterations of every `repeat` step in a finished
+ * flow's results. Reads ONLY the numeric `iterations_completed` field off
+ * entries that carry one; everything else in a result entry is ignored, so
+ * nothing page-derived can reach the history. */
+function countIterations(results) {
+    let total;
+    for (const entry of results) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const value = entry.iterations_completed;
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            continue;
+        total = (total ?? 0) + value;
+    }
+    return total;
+}
+/**
+ * Reduce a finished flow to a history entry — the ONE place a `FlowResult`
+ * is allowed to turn into stored state, and therefore the one place the
+ * privacy contract has to hold. Nothing is copied across by spread: every
+ * field is named, typed and numeric/enum.
+ *
+ * `result === null` means the flow threw instead of returning (a detached
+ * debugger, a closed tab). That is a `failed` outcome with no step
+ * attribution, which is honest — the runner never got to report one.
+ */
+export function toHistoryEntry(entry, result, endedAt) {
+    const base = {
+        flowId: entry.flowId,
+        startedAt: entry.startedAt,
+        durationMs: Math.max(0, endedAt - entry.startedAt),
+        steps: entry.steps,
+    };
+    if (result === null) {
+        // No result to read, so fall back to the last progress report: the
+        // runner had announced step N, which means N-1 finished.
+        return { ...base, outcome: 'failed', stepsCompleted: Math.max(0, entry.progress.step - 1) };
+    }
+    if (!result.ok) {
+        return {
+            ...base,
+            outcome: 'failed',
+            stepsCompleted: result.steps_completed,
+            failedStep: result.failed_step,
+            // A fixed vocabulary from `stepKind()` ('click', 'wait_for',
+            // 'unknown', 'none'), never free text — see the privacy contract.
+            failedStepKind: result.step_kind,
+        };
+    }
+    const iterations = countIterations(result.results);
+    return {
+        ...base,
+        outcome: result.stopped_by === 'cancelled' ? 'cancelled' : 'completed',
+        stepsCompleted: result.steps_completed,
+        ...(iterations === undefined ? {} : { iterationsCompleted: iterations }),
+    };
+}
+/** Prepend a finished flow to a tab's history and enforce the cap. Newest
+ * first — the panel shows the most recent flow at the top, and the cap
+ * drops the oldest. Pure so the cap is testable without touching
+ * `chrome.storage`. */
+export function appendFlowHistory(existing, entry) {
+    return [entry, ...existing].slice(0, MAX_FLOW_HISTORY_PER_TAB);
+}
+/** Narrow whatever `chrome.storage.session` hands back into a history
+ * list. Storage is not a trusted, typed channel (an older extension
+ * version may have written a different shape, and the value survives a
+ * service-worker restart), so an entry that does not carry the required
+ * primitives is dropped rather than rendered as `undefined`. */
+export function parseFlowHistory(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const parsed = [];
+    for (const item of raw) {
+        if (typeof item !== 'object' || item === null)
+            continue;
+        const candidate = item;
+        if (typeof candidate.flowId !== 'string')
+            continue;
+        if (typeof candidate.startedAt !== 'number')
+            continue;
+        if (typeof candidate.durationMs !== 'number')
+            continue;
+        if (typeof candidate.steps !== 'number')
+            continue;
+        if (typeof candidate.stepsCompleted !== 'number')
+            continue;
+        if (candidate.outcome !== 'completed' &&
+            candidate.outcome !== 'cancelled' &&
+            candidate.outcome !== 'failed') {
+            continue;
+        }
+        parsed.push({
+            flowId: candidate.flowId,
+            startedAt: candidate.startedAt,
+            durationMs: candidate.durationMs,
+            outcome: candidate.outcome,
+            steps: candidate.steps,
+            stepsCompleted: candidate.stepsCompleted,
+            ...(typeof candidate.iterationsCompleted === 'number'
+                ? { iterationsCompleted: candidate.iterationsCompleted }
+                : {}),
+            ...(typeof candidate.failedStep === 'number' ? { failedStep: candidate.failedStep } : {}),
+            ...(typeof candidate.failedStepKind === 'string'
+                ? { failedStepKind: candidate.failedStepKind }
+                : {}),
+        });
+    }
+    return parsed.slice(0, MAX_FLOW_HISTORY_PER_TAB);
+}
+/** Compact duration for the popup: "0.4s" under a second, "12s" under a
+ * minute, "3m 07s" beyond. Seconds are zero-padded in the minute form so
+ * the column does not jitter as a flow runs. */
+export function formatFlowDuration(ms) {
+    const safe = ms > 0 ? ms : 0;
+    if (safe < 1000)
+        return `${(safe / 1000).toFixed(1)}s`;
+    const totalSeconds = Math.floor(safe / 1000);
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return `${minutes}m ${String(seconds).padStart(2, '0')}s`;
+}
+/** What the popup calls a flow's tab. The title is best-effort (it is
+ * captured asynchronously at flow start and can legitimately be empty on
+ * a blank or still-loading tab), so the Chrome tab id is the fallback —
+ * an unlabelled Stop button next to an unlabelled flow would be exactly
+ * the wrong thing to hand someone trying to stop the right one. */
+export function flowTabLabel(view) {
+    const trimmed = view.title.trim();
+    return trimmed.length > 0 ? trimmed : `Tab ${view.tabId}`;
+}
+/** The progress line for one running flow: "step 2/5" outside a repeat,
+ * "step 2/5 · iteration 12/50" inside one, "starting…" before the runner
+ * has reported its first step. */
+export function describeFlowProgress(view) {
+    if (view.step < 1)
+        return 'starting…';
+    const base = `step ${view.step}/${view.steps}`;
+    if (view.iteration === undefined || view.iterations === undefined)
+        return base;
+    return `${base} · iteration ${view.iteration}/${view.iterations}`;
+}
+/** The one-line summary for a finished flow: outcome, what it got through,
+ * and how long it took. Structure and counts only. */
+export function describeFlowHistoryEntry(entry) {
+    const progress = entry.iterationsCompleted === undefined
+        ? `${entry.stepsCompleted}/${entry.steps} steps`
+        : `${entry.stepsCompleted}/${entry.steps} steps · ${entry.iterationsCompleted} iterations`;
+    const failure = entry.outcome === 'failed' && entry.failedStep !== undefined
+        ? ` · failed at step ${entry.failedStep + 1}${entry.failedStepKind === undefined ? '' : ` (${entry.failedStepKind})`}`
+        : '';
+    return `${progress} · ${formatFlowDuration(entry.durationMs)}${failure}`;
+}
+//# sourceMappingURL=flow-registry.js.map

package/dist/extension/flow-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-registry.js","sourceRoot":"","sources":["../src/flow-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH;8EAC8E;AAC9E,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C;;;uEAGuE;AACvE,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,gBAAgB,KAAK,EAAE,CAAC;AACjC,CAAC;AAuFD,MAAM,UAAU,kBAAkB;IAChC,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;IAEnD,OAAO;QACL,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;YACtC,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE;gBAChB,MAAM;gBACN,KAAK;gBACL,KAAK,EAAE,KAAK,IAAI,EAAE;gBAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,KAAK;gBACL,SAAS,EAAE,KAAK;gBAChB,6DAA6D;gBAC7D,4CAA4C;gBAC5C,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE;aAC7B,CAAC,CAAC;QACL,CAAC;QAED,GAAG,CAAC,MAAM;YACR,OAAO,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;QAED,MAAM,CAAC,MAAM;YACX,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAChC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,SAAS;gBAAE,OAAO,KAAK,CAAC;YAC5C,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,YAAY,CAAC,KAAK;YAChB,IAAI,SAAS,GAAG,CAAC,CAAC;YAClB,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBACnC,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,IAAI,KAAK,CAAC,SAAS;oBAAE,SAAS;gBACvD,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC;gBACvB,SAAS,IAAI,CAAC,CAAC;YACjB,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,CAAC,MAAM;YACX,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;YAChC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACrB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,WAAW,CAAC,GAAG;YACb,MAAM,KAAK,GAAsB,EAAE,CAAC;YACpC,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBACnC,KAAK,CAAC,IAAI,CAAC;oBACT,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,iEAAiE;oBACjE,mDAAmD;oBACnD,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC;oBAC7C,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,IAAI;oBACzB,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,KAAK,SAAS;wBACxC,CAAC,CAAC,EAAE;wBACJ,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,CAAC;oBAC5C,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,KAAK,SAAS;wBACzC,CAAC,CAAC,EAAE;wBACJ,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;oBAC9C,UAAU,EAAE,KAAK,CAAC,SAAS;iBAC5B,CAAC,CAAC;YACL,CAAC;YACD,iEAAiE;YACjE,mEAAmE;YACnE,iDAAiD;YACjD,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;iDAGiD;AACjD,SAAS,eAAe,CAAC,OAA2B;IAClD,IAAI,KAAyB,CAAC;IAC9B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAC1D,MAAM,KAAK,GAAI,KAA4C,CAAC,oBAAoB,CAAC;QACjF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,SAAS;QACnE,KAAK,GAAG,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC;IAC/B,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAwB,EACxB,MAAyB,EACzB,OAAe;IAEf,MAAM,IAAI,GAAG;QACX,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC;QAClD,KAAK,EAAE,KAAK,CAAC,KAAK;KACnB,CAAC;IACF,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,mEAAmE;QACnE,yDAAyD;QACzD,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO;YACL,GAAG,IAAI;YACP,OAAO,EAAE,QAAQ;YACjB,cAAc,EAAE,MAAM,CAAC,eAAe;YACtC,UAAU,EAAE,MAAM,CAAC,WAAW;YAC9B,6DAA6D;YAC7D,kEAAkE;YAClE,cAAc,EAAE,MAAM,CAAC,SAAS;SACjC,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACnD,OAAO;QACL,GAAG,IAAI;QACP,OAAO,EAAE,MAAM,CAAC,UAAU,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW;QACtE,cAAc,EAAE,MAAM,CAAC,eAAe;QACtC,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,UAAU,EAAE,CAAC;KACzE,CAAC;AACJ,CAAC;AAED;;;uBAGuB;AACvB,MAAM,UAAU,iBAAiB,CAC/B,QAAqC,EACrC,KAAuB;IAEvB,OAAO,CAAC,KAAK,EAAE,GAAG,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,wBAAwB,CAAC,CAAC;AACjE,CAAC;AAED;;;;gEAIgE;AAChE,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,MAAM,GAAuB,EAAE,CAAC;IACtC,KAAK,MAAM,IAAI,IAAI,GAAyB,EAAE,CAAC;QAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,SAAS;QACxD,MAAM,SAAS,GAAG,IAAiC,CAAC;QACpD,IAAI,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ;YAAE,SAAS;QACnD,IAAI,OAAO,SAAS,CAAC,SAAS,KAAK,QAAQ;YAAE,SAAS;QACtD,IAAI,OAAO,SAAS,CAAC,UAAU,KAAK,QAAQ;YAAE,SAAS;QACvD,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ;YAAE,SAAS;QAClD,IAAI,OAAO,SAAS,CAAC,cAAc,KAAK,QAAQ;YAAE,SAAS;QAC3D,IACE,SAAS,CAAC,OAAO,KAAK,WAAW;YACjC,SAAS,CAAC,OAAO,KAAK,WAAW;YACjC,SAAS,CAAC,OAAO,KAAK,QAAQ,EAC9B,CAAC;YACD,SAAS;QACX,CAAC;QACD,MAAM,CAAC,IAAI,CAAC;YACV,MAAM,EAAE,SAAS,CAAC,MAAM;YACxB,SAAS,EAAE,SAAS,CAAC,SAAS;YAC9B,UAAU,EAAE,SAAS,CAAC,UAAU;YAChC,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,KAAK,EAAE,SAAS,CAAC,KAAK;YACtB,cAAc,EAAE,SAAS,CAAC,cAAc;YACxC,GAAG,CAAC,OAAO,SAAS,CAAC,mBAAmB,KAAK,QAAQ;gBACnD,CAAC,CAAC,EAAE,mBAAmB,EAAE,SAAS,CAAC,mBAAmB,EAAE;gBACxD,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,OAAO,SAAS,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzF,GAAG,CAAC,OAAO,SAAS,CAAC,cAAc,KAAK,QAAQ;gBAC9C,CAAC,CAAC,EAAE,cAAc,EAAE,SAAS,CAAC,cAAc,EAAE;gBAC9C,CAAC,CAAC,EAAE,CAAC;SACR,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,wBAAwB,CAAC,CAAC;AACnD,CAAC;AAED;;gDAEgD;AAChD,MAAM,UAAU,kBAAkB,CAAC,EAAU;IAC3C,MAAM,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,IAAI,GAAG,IAAI;QAAE,OAAO,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACvD,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAC7C,IAAI,YAAY,GAAG,EAAE;QAAE,OAAO,GAAG,YAAY,GAAG,CAAC;IACjD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,EAAE,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,YAAY,GAAG,EAAE,CAAC;IAClC,OAAO,GAAG,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;AAC5D,CAAC;AAED;;;;mEAImE;AACnE,MAAM,UAAU,YAAY,CAAC,IAAsC;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IAClC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC;AAC5D,CAAC;AAED;;kCAEkC;AAClC,MAAM,UAAU,oBAAoB,CAAC,IAAqB;IACxD,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC;QAAE,OAAO,WAAW,CAAC;IACtC,MAAM,IAAI,GAAG,QAAQ,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;IAC/C,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC/E,OAAO,GAAG,IAAI,gBAAgB,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;AACpE,CAAC;AAED;sDACsD;AACtD,MAAM,UAAU,wBAAwB,CAAC,KAAuB;IAC9D,MAAM,QAAQ,GACZ,KAAK,CAAC,mBAAmB,KAAK,SAAS;QACrC,CAAC,CAAC,GAAG,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,KAAK,QAAQ;QAChD,CAAC,CAAC,GAAG,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC,KAAK,YAAY,KAAK,CAAC,mBAAmB,aAAa,CAAC;IAC/F,MAAM,OAAO,GACX,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAC1D,CAAC,CAAC,qBAAqB,KAAK,CAAC,UAAU,GAAG,CAAC,GACvC,KAAK,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,cAAc,GACrE,EAAE;QACJ,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,GAAG,QAAQ,MAAM,kBAAkB,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,OAAO,EAAE,CAAC;AAC3E,CAAC"}

package/dist/extension/flow.d.ts

@@ -18,6 +18,18 @@
  * target — so nothing leaks across an iteration or across the repeat
  * boundary in either direction.
  *
+ * Cancellation is cooperative and lives entirely in this loop: the caller
+ * injects `deps.shouldCancel`, and the runner checks it before dispatching
+ * anything — at the top of every top-level step, at the top of every
+ * repeat iteration, and before every inner step of a repeat body. That is
+ * what makes the advertised worst-case latency ONE STEP real rather than
+ * aspirational, and it is why cancelling means "do not dispatch step N+1"
+ * instead of "interrupt whatever is in flight" (an in-flight CDP command
+ * cannot be un-sent). A cancelled flow is a SUCCESS carrying
+ * `stopped_by: 'cancelled'` and every result it collected — the actions
+ * really happened, so reporting them as an error, or dropping them, would
+ * both be lies.
+ *
  * Deliberately decoupled from any specific transport: every side effect
  * goes through the `FlowDeps` the caller injects. The concrete wiring —
  * `background.ts` in the extension, `cdp/transport.ts` on the server —
@@ -143,6 +155,11 @@ export interface WaitForStepResult {
     matched: boolean;
     elapsed_ms: number;
     checks: number;
+    /** `'timeout'` on a genuine non-match. `'cancelled'` when the poll loop
+     * was cut short by the flow's cancellation flag — a DIFFERENT outcome
+     * that the step executor must not report as a timeout failure, since the
+     * condition was never given its full budget. Both perform* implementations
+     * (`background.ts`, `cdp/transport.ts`) set this. */
     reason?: string;
 }
 /** Mirrors the standalone `browser.drag` tool's params exactly (minus
@@ -240,11 +257,20 @@ export interface RepeatStepResult {
     iterations_completed: number;
     /** `condition` — `while_found` stopped matching. `max_iterations` — the
      * bound was reached with the condition still true (or with no condition
-     * at all). A failing inner step does not produce a result at all: it
-     * fails the whole flow, like every other step. */
-    stopped_by: 'condition' | 'max_iterations';
-    /** Per-iteration list of the inner steps' compacted results. */
+     * at all). `cancelled` — `deps.shouldCancel()` went true and the loop
+     * stopped dispatching. A failing inner step does not produce a result at
+     * all: it fails the whole flow, like every other step. */
+    stopped_by: 'condition' | 'max_iterations' | 'cancelled';
+    /** Per-iteration list of the inner steps' compacted results. Holds
+     * COMPLETE iterations only, so `iterations_completed` never counts an
+     * iteration that stopped half-way. */
     iterations: unknown[][];
+    /** Present ONLY when a cancellation landed part-way through an
+     * iteration: the inner-step results of that INCOMPLETE iteration. Those
+     * steps really ran, so they are never discarded — they are just kept out
+     * of `iterations` / `iterations_completed` so those two keep meaning
+     * exactly "iterations that finished". */
+    partial_iteration?: unknown[];
 }
 export type FlowStep = {
     find: FindStepParams;
@@ -287,6 +313,45 @@ export interface FlowDeps {
      * `browser.drag` returns there. */
     performDrag(params: DragStepParams): Promise<ActionOutcome<DragStepResult>>;
     buildRecoverySnapshot(): Promise<unknown>;
+    /** Cooperative cancellation. Polled — never awaited — immediately before
+     * each dispatch point (see the module doc comment for the exact three).
+     * Returning `true` ends the flow cleanly with `stopped_by: 'cancelled'`.
+     *
+     * Optional so every existing caller and test keeps working unchanged: an
+     * absent `shouldCancel` means "this flow cannot be cancelled", which is
+     * exactly the pre-cancellation behaviour.
+     *
+     * MUST be cheap and synchronous — it runs once per step. The extension
+     * reads a boolean off its in-flight registry entry; the cdp-direct
+     * transport re-checks the cdp-direct gate, which is what makes
+     * `browser-link cdp revoke` a real kill switch on that path. */
+    shouldCancel?(): boolean;
+    /** Progress sink, called immediately BEFORE each step is dispatched (and
+     * before each repeat iteration), so a consumer polling it always sees
+     * the step that is currently running rather than the last one that
+     * finished. Optional, and never awaited — a throwing or slow consumer
+     * must not be able to affect the flow, so implementations do the
+     * cheapest possible thing (the extension assigns one object onto its
+     * registry entry).
+     *
+     * This is what the popup's "step 3/7" / "iteration 12/50" line reads. It
+     * lives here rather than being derived outside because only the runner
+     * knows which step it is about to dispatch. */
+    onProgress?(progress: FlowProgress): void;
+}
+/** Where a running flow is, right now. Indices are 1-BASED for display —
+ * this shape exists to be rendered ("step 3/7"), not to index an array. */
+export interface FlowProgress {
+    /** 1-based index of the top-level step about to be dispatched. */
+    step: number;
+    /** Total number of top-level steps in this flow. */
+    steps: number;
+    /** 1-based index of the repeat iteration about to run. Present only
+     * while a `repeat` step is executing. */
+    iteration?: number;
+    /** The running repeat's `max_iterations` — the upper bound, which is the
+     * only total a repeat has (a `while_found` repeat may stop earlier). */
+    iterations?: number;
 }
 export interface FlowSuccess {
     ok: true;
@@ -296,6 +361,12 @@ export interface FlowSuccess {
      * and `steps_completed` is therefore 0. Omitted on a real run, so an
      * existing consumer sees a byte-identical success shape. */
     dry_run?: true;
+    /** Present ONLY when `deps.shouldCancel()` ended the run. A cancelled
+     * flow is deliberately `ok: true`: every step in `results` really
+     * executed, and the ONE thing the caller must not be told is that the
+     * partial work did not happen. Omitted on an uncancelled run, so an
+     * existing consumer sees a byte-identical success shape. */
+    stopped_by?: 'cancelled';
 }
 export interface FlowFailure {
     ok: false;
@@ -326,6 +397,11 @@ export interface RunFlowOptions {
  * and a malformed entry must fail the flow cleanly rather than throw.
  *
  * With `options.dryRun`, the flow is validated and projected instead:
- * nothing is dispatched, and each entry describes what WOULD run.
+ * nothing is dispatched, and each entry describes what WOULD run. A dry
+ * run ignores `deps.shouldCancel` — there is nothing to stop.
+ *
+ * With `deps.shouldCancel`, the run can be stopped between steps. It then
+ * resolves as a SUCCESS carrying `stopped_by: 'cancelled'` and the results
+ * of everything that already ran.
  */
 export declare function runFlow(steps: readonly FlowStep[], deps: FlowDeps, options?: RunFlowOptions): Promise<FlowResult>;

package/dist/extension/flow.js

@@ -18,6 +18,18 @@
  * target — so nothing leaks across an iteration or across the repeat
  * boundary in either direction.
  *
+ * Cancellation is cooperative and lives entirely in this loop: the caller
+ * injects `deps.shouldCancel`, and the runner checks it before dispatching
+ * anything — at the top of every top-level step, at the top of every
+ * repeat iteration, and before every inner step of a repeat body. That is
+ * what makes the advertised worst-case latency ONE STEP real rather than
+ * aspirational, and it is why cancelling means "do not dispatch step N+1"
+ * instead of "interrupt whatever is in flight" (an in-flight CDP command
+ * cannot be un-sent). A cancelled flow is a SUCCESS carrying
+ * `stopped_by: 'cancelled'` and every result it collected — the actions
+ * really happened, so reporting them as an error, or dropping them, would
+ * both be lies.
+ *
  * Deliberately decoupled from any specific transport: every side effect
  * goes through the `FlowDeps` the caller injects. The concrete wiring —
  * `background.ts` in the extension, `cdp/transport.ts` on the server —
@@ -169,6 +181,9 @@ async function executeLeafStep(kind, stepRecord, state, deps) {
         if (!outcome.ok)
             return { ok: false, error: outcome.error + raceHint() };
         if (!outcome.result.matched) {
+            if (outcome.result.reason === 'cancelled') {
+                return { ok: false, error: 'wait_for: cancelled', cancelled: true };
+            }
             // No race hint here: a wait_for step IS the recommended remedy for
             // a navigation race — a plain timeout is a genuine non-match.
             return {
@@ -358,10 +373,20 @@ async function whileFoundStillMatches(selector, deps) {
     const outcome = await deps.performWaitFor({ selector, condition: 'visible', timeout_ms: 0 });
     if (!outcome.ok)
         return { ok: false, error: outcome.error };
+    // A cancellation that lands DURING the probe comes back as a non-match.
+    // Distinguishing it matters: reporting `stopped_by: 'condition'` would
+    // claim the page had drained when in fact the human hit Stop.
+    if (!outcome.result.matched && outcome.result.reason === 'cancelled') {
+        return { ok: true, matched: false, cancelled: true };
+    }
     return { ok: true, matched: outcome.result.matched };
 }
-/** Run one `repeat` step to completion. */
-async function executeRepeatStep(raw, deps) {
+/** Run one `repeat` step to completion.
+ *
+ * `position` is the enclosing step's place in the top-level sequence,
+ * carried in only so the per-iteration `onProgress` calls can report
+ * "step 2/5 · iteration 12/50" instead of losing the outer coordinate. */
+async function executeRepeatStep(raw, deps, position) {
     const normalized = normalizeRepeat(raw);
     if (!normalized.ok)
         return normalized;
@@ -381,12 +406,26 @@ async function executeRepeatStep(raw, deps) {
     }
     const iterations = [];
     let stoppedBy = 'max_iterations';
+    /** Inner results of an iteration that a cancellation cut short. Kept
+     * separate from `iterations` — see `RepeatStepResult.partial_iteration`. */
+    let partialIteration;
     for (let iter = 0; iter < maxIterations; iter++) {
+        // Checked BEFORE the while_found probe, so a cancelled repeat does not
+        // even spend a round trip discovering whether it should have run again.
+        if (deps.shouldCancel?.() === true) {
+            stoppedBy = 'cancelled';
+            break;
+        }
+        deps.onProgress?.({ ...position, iteration: iter + 1, iterations: maxIterations });
         if (whileFound !== undefined) {
             const probe = await whileFoundStillMatches(whileFound, deps);
             if (!probe.ok) {
                 return { ok: false, error: `repeat: while_found probe failed — ${probe.error}` };
             }
+            if (probe.cancelled === true) {
+                stoppedBy = 'cancelled';
+                break;
+            }
             if (!probe.matched) {
                 stoppedBy = 'condition';
                 break;
@@ -397,6 +436,15 @@ async function executeRepeatStep(raw, deps) {
         const state = { implicitTarget: undefined, lastSettleReason: undefined };
         const entries = [];
         for (let j = 0; j < innerSteps.length; j++) {
+            // Re-checked per INNER step, not just per iteration: one iteration
+            // can hold a 30s wait_for or a 30s sleep, so an iteration-only check
+            // would quietly turn the advertised "worst case one step" bound into
+            // "worst case one whole iteration".
+            if (deps.shouldCancel?.() === true) {
+                stoppedBy = 'cancelled';
+                partialIteration = entries;
+                break;
+            }
             const innerRaw = innerSteps[j];
             // Re-derived per iteration rather than trusted from normalizeRepeat:
             // same defense-in-depth every other step shape gets.
@@ -409,6 +457,14 @@ async function executeRepeatStep(raw, deps) {
             }
             const outcome = await executeLeafStep(innerKind, innerRaw, state, deps);
             if (!outcome.ok) {
+                // A step cut short mid-flight by the cancel flag is not a failure
+                // of that step — stop the loop the same way an iteration-boundary
+                // cancellation does, keeping whatever this iteration completed.
+                if (outcome.cancelled === true) {
+                    stoppedBy = 'cancelled';
+                    partialIteration = entries;
+                    break;
+                }
                 return {
                     ok: false,
                     error: `repeat: iteration ${iter}, step ${j} (${innerKind}) failed — ${outcome.error}`,
@@ -416,6 +472,8 @@ async function executeRepeatStep(raw, deps) {
             }
             entries.push(outcome.entry);
         }
+        if (stoppedBy === 'cancelled')
+            break;
         iterations.push(entries);
         if (iterationDelayMs > 0) {
             await new Promise((resolve) => {
@@ -427,8 +485,13 @@ async function executeRepeatStep(raw, deps) {
         iterations_completed: iterations.length,
         stopped_by: stoppedBy,
         iterations,
+        // Only when a cancellation actually interrupted an iteration mid-way;
+        // an empty array would still be noise, so it is omitted too.
+        ...(partialIteration !== undefined && partialIteration.length > 0
+            ? { partial_iteration: partialIteration }
+            : {}),
     };
-    return { ok: true, entry };
+    return { ok: true, entry, ...(stoppedBy === 'cancelled' ? { cancelled: true } : {}) };
 }
 /** Total step count INCLUDING a repeat's inner steps. A 20-step ceiling
  * that only counted the outer array would let a single repeat smuggle in
@@ -503,7 +566,12 @@ async function planFlow(steps, deps) {
  * and a malformed entry must fail the flow cleanly rather than throw.
  *
  * With `options.dryRun`, the flow is validated and projected instead:
- * nothing is dispatched, and each entry describes what WOULD run.
+ * nothing is dispatched, and each entry describes what WOULD run. A dry
+ * run ignores `deps.shouldCancel` — there is nothing to stop.
+ *
+ * With `deps.shouldCancel`, the run can be stopped between steps. It then
+ * resolves as a SUCCESS carrying `stopped_by: 'cancelled'` and the results
+ * of everything that already ran.
  */
 export async function runFlow(steps, deps, options = {}) {
     if (!Array.isArray(steps) || steps.length === 0) {
@@ -518,6 +586,14 @@ export async function runFlow(steps, deps, options = {}) {
     const results = [];
     const state = { implicitTarget: undefined, lastSettleReason: undefined };
     for (let i = 0; i < steps.length; i++) {
+        // Cancellation check #1 of 3 (the others are per repeat iteration and
+        // per inner repeat step). Deliberately BEFORE the step-shape check, so
+        // a cancelled flow stops rather than failing on a malformed step it
+        // was never going to dispatch anyway.
+        if (deps.shouldCancel?.() === true) {
+            return { ok: true, stopped_by: 'cancelled', steps_completed: results.length, results };
+        }
+        deps.onProgress?.({ step: i + 1, steps: steps.length });
         const raw = steps[i];
         const kind = stepKind(raw);
         if (!kind) {
@@ -525,7 +601,10 @@ export async function runFlow(steps, deps, options = {}) {
         }
         const stepRecord = raw;
         if (kind === 'repeat') {
-            const outcome = await executeRepeatStep(stepRecord.repeat, deps);
+            const outcome = await executeRepeatStep(stepRecord.repeat, deps, {
+                step: i + 1,
+                steps: steps.length,
+            });
             if (!outcome.ok) {
                 return withRecoverySnapshot(deps, i, kind, outcome.error, results.length);
             }
@@ -535,10 +614,22 @@ export async function runFlow(steps, deps, options = {}) {
             state.implicitTarget = undefined;
             state.lastSettleReason = undefined;
             results.push(outcome.entry);
+            // A repeat that stopped because of a cancellation ends the whole
+            // flow — its entry is already in `results`, so the iterations it DID
+            // complete are reported rather than thrown away.
+            if (outcome.cancelled === true) {
+                return { ok: true, stopped_by: 'cancelled', steps_completed: results.length, results };
+            }
             continue;
         }
         const outcome = await executeLeafStep(kind, stepRecord, state, deps);
         if (!outcome.ok) {
+            // Cut short mid-step by the cancel flag (a `wait_for` poll loop that
+            // honoured it): a cancellation, not a step failure — and therefore
+            // no recovery snapshot, since nothing went wrong with the page.
+            if (outcome.cancelled === true) {
+                return { ok: true, stopped_by: 'cancelled', steps_completed: results.length, results };
+            }
             return withRecoverySnapshot(deps, i, kind, outcome.error, results.length);
         }
         results.push(outcome.entry);