@foldspace_npm/harness 0.1.16 → 0.1.18

package/recipes/upload-contacts/agent/views/uploader.ts

@@ -0,0 +1,394 @@
+// The import card from the production build. textContent only — never innerHTML
+// with file data. Styles go in `header`. The write runs only after Import.
+// Done is what finishes the card.
+
+import { importContacts } from "../api/contacts";
+import { contactName, outcomeFrom, parseContactsCsv, toDraft, type ImportOutcome, type ParsedContact } from "../contacts";
+import { renderFailure, type ApiFailure } from "../utils";
+import { brand } from "./brand";
+
+const CSS = `
+.fs-up{background:${brand.surface};border-radius:${brand.radius};padding:16px;font-family:${brand.font};
+  color:${brand.text};border:1px solid ${brand.border};width:100%;box-sizing:border-box}
+.fs-up *{box-sizing:border-box;margin:0}
+.fs-up-head{margin-bottom:16px}
+.fs-up-title{font-size:16px;font-weight:600;color:${brand.textStrong};margin-bottom:6px;display:flex;align-items:center;gap:6px}
+.fs-up-sub{font-size:12px;color:${brand.muted};line-height:1.4}
+.fs-up-icon{width:20px;height:20px;color:${brand.accent};flex-shrink:0}
+.fs-up-icon.is-ok{color:${brand.ok}}
+.fs-up-zone{border:2px dashed ${brand.border};border-radius:6px;padding:24px 16px;text-align:center;cursor:pointer;
+  background:rgba(96,165,250,.05)}
+.fs-up-zone:hover,.fs-up-zone.is-drag{border-color:${brand.accent};background:rgba(96,165,250,.1)}
+.fs-up-zone svg{width:40px;height:40px;margin:0 auto 12px;color:${brand.accent};display:block}
+.fs-up-zone-text{font-size:13px;color:${brand.text};margin-bottom:6px}
+.fs-up-hint{font-size:11px;color:${brand.faint}}
+.fs-up-file{display:none}
+.fs-up-sum{display:flex;gap:12px;margin-bottom:12px;padding:12px;background:rgba(30,41,59,.5);border-radius:6px;
+  flex-wrap:wrap;justify-content:center}
+.fs-up-stat{display:flex;flex-direction:column;gap:2px;flex:1;min-width:80px;align-items:center;text-align:center}
+.fs-up-num{font-size:24px;font-weight:600;color:${brand.textStrong}}
+.fs-up-num.is-ok{color:${brand.ok}}
+.fs-up-num.is-warn{color:${brand.warn}}
+.fs-up-label{font-size:11px;color:${brand.muted};text-transform:uppercase;letter-spacing:.5px}
+.fs-up-scroll{max-height:250px;overflow:auto;border:1px solid ${brand.border};border-radius:6px;margin-bottom:12px}
+.fs-up-table{width:100%;border-collapse:collapse;font-size:12px}
+.fs-up-table th{background:${brand.tableHead};padding:8px 10px;text-align:left;font-weight:600;color:${brand.muted};
+  text-transform:uppercase;font-size:10px;letter-spacing:.5px;border-bottom:1px solid ${brand.border}}
+.fs-up-table td{padding:8px 10px;border-bottom:1px solid ${brand.border};color:#E2E8F0}
+.fs-up-ready,.fs-up-invalid{display:inline-flex;align-items:center;padding:4px 8px;border-radius:12px;font-size:11px;font-weight:500}
+.fs-up-ready{background:rgba(52,211,153,.15);color:${brand.ok}}
+.fs-up-invalid{background:rgba(248,113,113,.15);color:${brand.bad}}
+.fs-up-actions{display:flex;gap:8px;justify-content:flex-end;margin-top:12px;flex-wrap:wrap}
+.fs-up-btn{padding:8px 16px;border-radius:6px;font-size:13px;font-weight:500;cursor:pointer;white-space:nowrap;font-family:inherit}
+.fs-up-primary{background:${brand.accent};color:${brand.textStrong};border:none}
+.fs-up-primary:hover{background:${brand.accentDeep}}
+.fs-up-primary:disabled{background:${brand.disabled};cursor:not-allowed}
+.fs-up-secondary{background:transparent;border:1px solid ${brand.border};color:${brand.text}}
+.fs-up-spin{display:inline-block;width:16px;height:16px;border:2px solid ${brand.border};border-top-color:${brand.accent};
+  border-radius:50%;animation:fs-up-spin .8s linear infinite}
+.fs-up-spin.is-lg{width:32px;height:32px;border-width:2px}
+@keyframes fs-up-spin{to{transform:rotate(360deg)}}
+.fs-up-wait{text-align:center;padding:40px}
+.fs-up-wait-text{margin-top:16px;color:${brand.muted};font-size:14px}
+.fs-up-section{margin-top:12px}
+.fs-up-section-title{font-size:13px;font-weight:600;color:${brand.text};margin-bottom:8px}
+.fs-up-list{max-height:200px;overflow:auto;font-size:12px;line-height:1.5;padding:8px;background:rgba(30,41,59,.3);border-radius:6px}
+.fs-up-item{padding:6px 0;border-bottom:1px solid rgba(52,66,86,.5);display:flex;flex-direction:column;gap:4px}
+.fs-up-name{color:#E2E8F0;font-weight:500}
+.fs-up-email{color:${brand.faint};font-size:11px}
+.fs-up-reason{color:${brand.warn};font-size:10px;font-style:italic}
+.fs-up-tag{background:rgba(96,165,250,.15);color:${brand.accent};padding:3px 8px;border-radius:10px;font-size:10px;font-weight:500}
+.fs-up-rule{height:1px;background:${brand.border};margin:12px 0}
+.fs-up-error{padding:10px;background:rgba(248,113,113,.1);border:1px solid rgba(248,113,113,.3);border-radius:6px;
+  color:${brand.bad};font-size:12px;line-height:1.4}
+`;
+
+const UPLOAD_PATH = "M7 16a4 4 0 01-.88-7.903A5 5 0 1115.9 6L16 6a5 5 0 011 9.9M15 13l-3-3m0 0l-3 3m3-3v12";
+const FILE_PATH = "M9 13h6m-3-3v6m5 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z";
+const REVIEW_PATH = "M9 5H7a2 2 0 00-2 2v12a2 2 0 002 2h10a2 2 0 002-2V7a2 2 0 00-2-2h-2M9 5a2 2 0 002 2h2a2 2 0 002-2M9 5a2 2 0 012-2h2a2 2 0 012 2m-6 9l2 2 4-4";
+const DONE_PATH = "M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z";
+const UPLOAD_COPY = "Upload a CSV file with your contacts. The file should include columns for firstName, lastName, and email (required). Optional columns: phone, title, accountName.";
+
+export type UploadHandlers = {
+  onCancel: () => void;
+  onEmpty: () => void;
+  onDone: (outcome: ImportOutcome) => void;
+  onFailed: (failure: ApiFailure) => void;
+};
+
+type CsvFile = { text: () => Promise<string> };
+
+function el(tag: string, className: string, text?: string): HTMLElement {
+  const node = document.createElement(tag);
+  node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+function button(className: string, text: string): HTMLButtonElement {
+  const node = el("button", className, text) as HTMLButtonElement;
+  node.type = "button";
+  return node;
+}
+
+function icon(className: string, pathD: string, strokeWidth = "2"): SVGElement | null {
+  if (typeof document.createElementNS !== "function") return null;
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("class", className);
+  svg.setAttribute("fill", "none");
+  svg.setAttribute("stroke", "currentColor");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  const path = document.createElementNS("http://www.w3.org/2000/svg", "path");
+  path.setAttribute("stroke-linecap", "round");
+  path.setAttribute("stroke-linejoin", "round");
+  path.setAttribute("stroke-width", strokeWidth);
+  path.setAttribute("d", pathD);
+  svg.appendChild(path);
+  return svg;
+}
+
+function toggleClass(node: HTMLElement, name: string, on: boolean): void {
+  const names = node.className.split(/\s+/).filter(Boolean);
+  const has = names.includes(name);
+  if (on && !has) node.className = [...names, name].join(" ");
+  if (!on && has) node.className = names.filter((item) => item !== name).join(" ");
+}
+
+// The production build's single-page app listened for this message and routed
+// on it. No other app does — on any other product this click does nothing.
+// Open a record with a navigation route instead (CLAUDE.md, "Product defaults").
+function go(path: string): void {
+  const top = window.top;
+  if (top && typeof top.postMessage === "function") {
+    top.postMessage({ type: "NAVIGATE", path }, "*");
+  }
+}
+
+function dash(value: string | null | undefined): string {
+  const text = value?.trim();
+  return text ? text : "-";
+}
+
+export function mountContactUpload(host: HTMLElement, header: HTMLElement, handlers: UploadHandlers): void {
+  const style = el("style", "");
+  style.textContent = CSS;
+  header.append(style);
+
+  let settled = false;
+  let busy = false;
+  let parsed: ParsedContact[] = [];
+
+  const report = (draw: () => void, send: () => void) => {
+    if (settled) return;
+    settled = true;
+    draw();
+    send();
+  };
+
+  const mount = (card: HTMLElement) => {
+    host.textContent = "";
+    host.append(card);
+  };
+
+  const heading = (title: string, subtitle: string, mark: SVGElement | null): HTMLElement => {
+    const head = el("div", "fs-up-head");
+    const row = el("div", "fs-up-title");
+    if (mark) row.append(mark);
+    row.append(el("span", "", title));
+    head.append(row, el("div", "fs-up-sub", subtitle));
+    return head;
+  };
+
+  const actions = (...nodes: HTMLElement[]): HTMLElement => {
+    const row = el("div", "fs-up-actions");
+    row.append(...nodes);
+    return row;
+  };
+
+  const stat = (label: string, value: string, tone?: "ok" | "warn"): HTMLElement => {
+    const node = el("div", "fs-up-stat");
+    node.append(el("div", "fs-up-label", label), el("div", tone ? `fs-up-num is-${tone}` : "fs-up-num", value));
+    return node;
+  };
+
+  const showUpload = () => {
+    const card = el("div", "fs-up");
+    card.append(heading("Import Contacts from CSV", UPLOAD_COPY, icon("fs-up-icon", UPLOAD_PATH)));
+
+    const zone = el("div", "fs-up-zone");
+    const mark = icon("", FILE_PATH, "1.5");
+    if (mark) zone.append(mark);
+    zone.append(el("div", "fs-up-zone-text", "Click to select a CSV file or drag and drop"));
+    zone.append(el("div", "fs-up-hint", "Supports: .csv files"));
+
+    const input = document.createElement("input");
+    input.type = "file";
+    input.className = "fs-up-file";
+    input.accept = ".csv";
+    zone.append(input);
+
+    const readFile = async (file: CsvFile | undefined) => {
+      if (settled || busy || !file) return;
+      const csv = await file.text();
+      parsed = parseContactsCsv(csv);
+      if (parsed.length === 0) {
+        report(
+          () => {
+            const empty = el("div", "fs-up");
+            empty.append(heading("Import Contacts from CSV", UPLOAD_COPY, icon("fs-up-icon", UPLOAD_PATH)));
+            empty.append(el("div", "fs-up-error", "The file had no contacts."));
+            mount(empty);
+          },
+          () => handlers.onEmpty(),
+        );
+        return;
+      }
+      showPreview();
+    };
+
+    zone.addEventListener("click", () => input.click());
+    input.addEventListener("click", (event) => {
+      if (typeof event.stopPropagation === "function") event.stopPropagation();
+    });
+    input.addEventListener("change", () => {
+      const file = input.files?.[0] as CsvFile | undefined;
+      void readFile(file);
+    });
+    zone.addEventListener("dragover", (event) => {
+      if (typeof event.preventDefault === "function") event.preventDefault();
+      toggleClass(zone, "is-drag", true);
+    });
+    zone.addEventListener("dragleave", () => toggleClass(zone, "is-drag", false));
+    zone.addEventListener("drop", (event) => {
+      if (typeof event.preventDefault === "function") event.preventDefault();
+      toggleClass(zone, "is-drag", false);
+      const transfer = "dataTransfer" in event ? event.dataTransfer : null;
+      const file = transfer?.files?.[0] as CsvFile | undefined;
+      void readFile(file);
+    });
+
+    const cancel = button("fs-up-btn fs-up-secondary", "Cancel");
+    cancel.addEventListener("click", () => {
+      report(() => mount(el("div", "fs-up")), () => handlers.onCancel());
+    });
+
+    card.append(zone, actions(cancel));
+    mount(card);
+  };
+
+  const showPreview = () => {
+    const ready = parsed.filter((row) => row.valid);
+    const skipped = parsed.length - ready.length;
+    const accounts = new Set(parsed.map((row) => row.accountName?.trim()).filter((name): name is string => Boolean(name)));
+
+    const card = el("div", "fs-up");
+    card.append(
+      heading(
+        "Review Contacts",
+        "Review the contacts below before importing. Invalid contacts will be skipped.",
+        icon("fs-up-icon", REVIEW_PATH),
+      ),
+    );
+
+    const summary = el("div", "fs-up-sum");
+    summary.append(stat("Total Contacts", String(parsed.length)));
+    summary.append(stat("Ready to Import", String(ready.length), "ok"));
+    if (skipped > 0) summary.append(stat("Will Be Skipped", String(skipped), "warn"));
+    summary.append(stat("Accounts", String(accounts.size)));
+    card.append(summary);
+
+    const table = el("table", "fs-up-table");
+    const head = document.createElement("thead");
+    const headRow = document.createElement("tr");
+    for (const label of ["Name", "Email", "Title", "Account", "Status"]) {
+      headRow.append(el("th", "", label));
+    }
+    head.append(headRow);
+    const body = document.createElement("tbody");
+    for (const row of parsed) {
+      const line = document.createElement("tr");
+      line.append(
+        el("td", "", contactName(row) || "-"),
+        el("td", "", dash(row.email)),
+        el("td", "", dash(row.title)),
+        el("td", "", dash(row.accountName)),
+      );
+      const status = document.createElement("td");
+      const badge = el("span", row.valid ? "fs-up-ready" : "fs-up-invalid", row.valid ? "Ready" : "Invalid");
+      if (!row.valid && row.reason) badge.title = row.reason;
+      status.append(badge);
+      line.append(status);
+      body.append(line);
+    }
+    table.append(head, body);
+    const scroll = el("div", "fs-up-scroll");
+    scroll.append(table);
+    card.append(scroll);
+
+    const back = button("fs-up-btn fs-up-secondary", "Back");
+    back.addEventListener("click", () => {
+      if (settled || busy) return;
+      parsed = [];
+      showUpload();
+    });
+    const confirm = button("fs-up-btn fs-up-primary", `Import ${ready.length} Contacts`);
+    confirm.disabled = ready.length === 0;
+    confirm.addEventListener("click", async () => {
+      if (settled || busy || ready.length === 0) return;
+      busy = true;
+      showImporting(ready.length);
+      const res = await importContacts(ready.map(toDraft));
+      if (!res.ok) {
+        report(
+          () => renderFailure(host, res, { notFound: "No import endpoint answered." }),
+          () => handlers.onFailed(res),
+        );
+        return;
+      }
+      showResults(outcomeFrom(parsed, res.data));
+    });
+    card.append(actions(back, confirm));
+    mount(card);
+  };
+
+  const showImporting = (count: number) => {
+    const card = el("div", "fs-up");
+    const row = el("div", "fs-up-title");
+    row.append(el("span", "fs-up-spin"), el("span", "", "Importing Contacts..."));
+    const head = el("div", "fs-up-head");
+    head.append(row, el("div", "fs-up-sub", "Please wait while we import your contacts. This may take a moment for large files."));
+    const wait = el("div", "fs-up-wait");
+    wait.append(el("div", "fs-up-spin is-lg"), el("div", "fs-up-wait-text", `Processing ${count} contacts...`));
+    card.append(head, wait);
+    mount(card);
+  };
+
+  const showResults = (outcome: ImportOutcome) => {
+    const created = outcome.rows.filter((row) => !row.reason);
+    const skipped = outcome.rows.filter((row) => row.reason);
+    const card = el("div", "fs-up");
+
+    if (outcome.created > 0) {
+      const noun = outcome.created === 1 ? "contact" : "contacts";
+      card.append(
+        heading(
+          "Import Complete",
+          `Successfully imported ${outcome.created} ${noun}.`,
+          icon("fs-up-icon is-ok", DONE_PATH),
+        ),
+      );
+    }
+
+    const summary = el("div", "fs-up-sum");
+    summary.append(stat("Imported", String(outcome.created), "ok"));
+    summary.append(stat("Skipped", String(outcome.skipped), "warn"));
+    card.append(summary);
+
+    if (created.length > 0) {
+      const section = el("div", "fs-up-section");
+      section.append(el("div", "fs-up-section-title", `Imported Contacts (${created.length})`));
+      const list = el("div", "fs-up-list");
+      for (const row of created) {
+        const item = el("div", "fs-up-item");
+        const who = el("div", "");
+        who.append(el("span", "fs-up-name", row.name), el("span", "fs-up-email", ` - ${dash(row.email)}`));
+        item.append(who);
+        const account = parsed.find((source) => source.email === row.email)?.accountName;
+        if (account) item.append(el("span", "fs-up-tag", account));
+        list.append(item);
+      }
+      section.append(list);
+      card.append(section);
+    }
+
+    if (skipped.length > 0) {
+      card.append(el("div", "fs-up-rule"));
+      const section = el("div", "fs-up-section");
+      section.append(el("div", "fs-up-section-title", `Skipped Contacts (${skipped.length})`));
+      const list = el("div", "fs-up-list");
+      for (const row of skipped) {
+        const item = el("div", "fs-up-item");
+        const who = el("div", "");
+        who.append(el("span", "fs-up-name", row.name), el("span", "fs-up-email", ` - ${dash(row.email)}`));
+        item.append(who, el("span", "fs-up-reason", row.reason ?? ""));
+        list.append(item);
+      }
+      section.append(list);
+      card.append(section);
+    }
+
+    const finish = () => report(() => {}, () => handlers.onDone(outcome));
+    const view = button("fs-up-btn fs-up-secondary", "View Contacts");
+    view.addEventListener("click", () => {
+      // callback first: a navigation that unloads the page must not lose it.
+      finish();
+      go("/__observe_me/contacts");
+    });
+    const done = button("fs-up-btn fs-up-primary", "Done");
+    done.addEventListener("click", finish);
+    card.append(actions(view, done));
+    mount(card);
+  };
+
+  showUpload();
+}

package/recipes/upload-contacts/fixtures/import.ok.json

@@ -0,0 +1,9 @@
+{
+  "created": 2,
+  "skipped": 0,
+  "createdContacts": [
+    { "name": "Dana Reyes", "email": "dana@example.com" },
+    { "name": "Sam Lee", "email": "sam@example.com" }
+  ],
+  "skippedContacts": []
+}

package/recipes/upload-contacts/recipe.json

@@ -0,0 +1,10 @@
+{
+  "title": "Upload contacts",
+  "level": "L4",
+  "family": "upload",
+  "kind": "action",
+  "action": "upload_contacts",
+  "entry": "agent/actions/upload_contacts.ts",
+  "outcome": "A CSV is previewed, then written only after the user confirms",
+  "provenBy": 1
+}

package/src/attach-preflight.mjs

@@ -39,6 +39,15 @@ export function guardAttachMode({
     if (characterization.status === "no-sdk") {
       return { ok: true, mode };
     }
+    // The bootstrap script is added on every new document, so after the tab
+    // navigates within the app the SDK on the page is OUR bootstrap, carrying
+    // the configured agent. That is the expected state, not a foreign SDK:
+    // refusing it made the agent vanish on every in-app navigation
+    // (Buildium, 2026-09-22). Only a page whose SDK belongs to someone else
+    // is a real mismatch.
+    if (characterization.status === "same-agent") {
+      return { ok: true, mode, reattached: true };
+    }
     return {
       ok: false,
       mode,

package/src/badge-core.mjs

@@ -0,0 +1,22 @@
+// Pure logic behind `foldspace badge`, unit-tested.
+
+export const BADGE_STATES = ["working", "ready", "label", "off"];
+
+/** What gets written into the page for a badge state, or throws on bad input. */
+export function badgePayload(state, text) {
+  const wanted = String(state || "").trim().toLowerCase();
+  if (!BADGE_STATES.includes(wanted)) {
+    throw new Error(`usage: foldspace badge <${BADGE_STATES.join("|")}> [--text "<what to show>"]`);
+  }
+  const payload = { state: wanted };
+  if (text !== undefined) {
+    if (wanted !== "working" && wanted !== "ready") {
+      throw new Error(`--text only applies to working or ready (got ${wanted}).`);
+    }
+    const clean = String(text).replace(/\s+/g, " ").trim();
+    if (!clean) throw new Error("--text is empty.");
+    if (clean.length > 160) throw new Error("--text is longer than 160 characters; keep it to one line.");
+    payload.text = clean;
+  }
+  return payload;
+}

package/src/cli-registry.mjs

@@ -241,9 +241,10 @@ export const CLI_COMMANDS = Object.freeze([
       ),
       value("--agent", "api-name", "Override the configured agent API name"),
       flag(
-        "--no-test-mode",
-        "Do not mark conversations as test traffic; use deliberately",
+        "--test-mode",
+        "Mark this session's conversations as test traffic, so they stay out of the dashboard; for an agent that already has real users",
       ),
+      flag("--no-test-mode", "Accepted for older instructions; test mode is already off by default"),
       flag("--no-badge", "Hide the visible Foldspace development badge"),
       flag(
         "--daemon",
@@ -261,7 +262,7 @@ export const CLI_COMMANDS = Object.freeze([
     effects: [
       "May reload and instrument matching target pages",
       "Refuses a Chrome that is not the profile inject launched",
-      "Test mode is enabled unless --no-test-mode is passed",
+      "Test mode is off unless --test-mode is passed: conversations appear in the dashboard",
       "Never directly invokes an action handler",
       "An empty local action registry is valid; named actions are not required",
       "Restores prepared pages when detached cleanly",
@@ -316,6 +317,34 @@ export const CLI_COMMANDS = Object.freeze([
     ],
     next: ["Record what you established in docs/app-profile.md", "Write the handler"],
   }),
+  Object.freeze({
+    name: "badge",
+    entry: "badge.mjs",
+    group: "verify",
+    summary: "Set the banner across the top of the test window: working, ready, label or off",
+    usage: 'foldspace badge <working|ready|label|off> [--text "<what to show>"]',
+    risk: "browser-session",
+    environment: "local-chrome",
+    environmentVariables: ["FOLDSPACE_PROJECT_DIR", "CDP_PORT"],
+    capabilities: ["browser.cdp", "page.evaluate"],
+    positionals: [
+      Object.freeze({
+        name: "state",
+        required: true,
+        description:
+          "working: the agent is building here, leave the window alone | ready: the human's turn | label: the small corner tag | off: remove it",
+      }),
+    ],
+    options: [
+      value("--text", "text", "working/ready: the line to show, e.g. the question to try (one line, up to 160 characters)"),
+    ],
+    prerequisites: ["foldspace attach is running (it draws the badge)"],
+    effects: [
+      "Writes one key to the test window's sessionStorage; touches nothing else on the page",
+      "The banner survives navigation inside the test window",
+    ],
+    next: ["Tell the human in chat what the banner says"],
+  }),
   Object.freeze({
     name: "deploy",
     // Foldspace-internal: it uploads to Foldspace's own storage, which no

package/src/keep-focus.mjs

@@ -0,0 +1,49 @@
+// The test Chrome must never steal the keyboard. Chrome raises its window when
+// a page navigates or reloads over CDP, and a customer typing somewhere else
+// then types into their live product (seen 2026-09-22). Nothing in CDP stops
+// that; on macOS the fix is to hand focus straight back to whatever app the
+// human was using. Elsewhere this is a no-op.
+
+import { execFile } from "node:child_process";
+
+const FRONT_APP_SCRIPT =
+  'tell application "System Events" to get bundle identifier of first application process whose frontmost is true';
+
+function osascript(script) {
+  return new Promise((resolve) => {
+    // 4s, not less: the first call wakes System Events, which alone can take
+    // over a second, and a timeout here silently leaves focus on Chrome.
+    execFile("osascript", ["-e", script], { timeout: 4000 }, (error, stdout) => {
+      resolve(error ? null : String(stdout).trim());
+    });
+  });
+}
+
+/** Bundle id of the app in front right now, or null (not macOS, or unknown). */
+export async function frontApp() {
+  if (process.platform !== "darwin") return null;
+  return osascript(FRONT_APP_SCRIPT);
+}
+
+/**
+ * Run `action` (which will make Chrome raise its window), then give focus back
+ * to the app that had it. If Chrome itself was in front, nothing to restore.
+ */
+export async function withoutStealingFocus(action, { front = frontApp, restore = restoreFront } = {}) {
+  const before = await front();
+  try {
+    return await action();
+  } finally {
+    if (before && !/google\.chrome|chromium/i.test(before)) await restore(before);
+  }
+}
+
+export async function restoreFront(bundleId) {
+  if (process.platform !== "darwin" || !bundleId) return;
+  // Twice, a beat apart: Chrome's activation lands after the navigation
+  // settles, so one immediate restore can be overtaken.
+  const script = `tell application id "${bundleId.replace(/"/g, "")}" to activate`;
+  await osascript(script);
+  await new Promise((resolve) => setTimeout(resolve, 400));
+  await osascript(script);
+}