@broberg/lens-daemon 0.1.41 → 0.1.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "description": "The Lens module of the cardmem daemon (flows, critic, coverage, capture sessions, the /lens/* routes and the cardmem-lens MCP) as a package. The daemon mounts createLensRouter(deps) + createLensMcpRouter(deps). Bun runtime.",
   "type": "module",
   "license": "MIT",
@@ -15,8 +15,8 @@
     "sharp": "^0.35.5",
     "turndown": "^7.2.4",
     "zod": "^3.23.8",
-    "@broberg/lens-engine": "0.14.1",
-    "@broberg/lens-svg": "0.1.1"
+    "@broberg/lens-svg": "0.1.1",
+    "@broberg/lens-engine": "0.14.1"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",

package/src/flow-store.ts

@@ -20,7 +20,7 @@ export interface StoredFlowStep {
   /** F009.122 — the named browser the step ran in; absent = the default one. */
   browser?: string;
   /** F009.125 — the step ran in the extension popup. */
-  in?: 'popup';
+  in?: 'popup' | 'opened';
   status: 'pass' | 'fail' | 'skip';
   testid: string | null;
   detail: string | null;

package/src/flow.ts

@@ -167,6 +167,10 @@ export type FlowStep =
   // then put the page under test back in front so the extension sees it as the active
   // tab (measured). `path` defaults to the manifest's action.default_popup.
   | { type: 'openPopup'; path?: string; label?: string; timeout?: number }
+  // F009.139 — take over a window the PAGE opened (window.open / target=_blank: an
+  // OAuth dialog), and wait for it to close again. Steps with in:"opened" run in it.
+  | { type: 'waitForPopup'; label?: string; timeout?: number }
+  | { type: 'waitForPopupClose'; label?: string; timeout?: number }
   // F009.126 — pass when the run made a matching request (page, popup, any page in the
   // run's browser). `url` is a substring, or a regex with match:"regex" (a path like
   // "/api/clips" would otherwise read as a /pattern/flags literal). Fails listing what WAS seen.
@@ -296,7 +300,7 @@ export interface FlowStepResult {
   /** F009.122 — the named browser this step ran in. Absent = the default one. */
   browser?: string;
   /** F009.125 — present when the step ran in the extension popup. */
-  in?: 'popup';
+  in?: 'popup' | 'opened';
   status: 'pass' | 'fail' | 'skip';
   testid: string | null;
   detail: string | null;
@@ -512,6 +516,8 @@ export const STEP_TYPES = new Set([
   'openPopup',
   // F009.126 — assert a request the run made
   'expectRequest',
+  // F009.139 — follow a window the page opened
+  'waitForPopup', 'waitForPopupClose',
 ]);
 
 /** Validate + normalise an untrusted flow (HTTP/MCP boundary). Throws on the
@@ -751,6 +757,8 @@ export const STEP_FIELDS: Record<string, string[]> = {
   conditional: ['testid', 'present', 'steps'],
   loop: ['data', 'steps', 'parallel'],
   openPopup: ['path'],
+  waitForPopup: [],
+  waitForPopupClose: [],
   expectRequest: ['url', 'match', 'method', 'status'],
 };
 
@@ -815,17 +823,22 @@ function validateAndNormalizeSteps(steps: unknown[], depth = 0, inParallel = fal
     // F009.125 — `in: "popup"` runs a step in the extension popup an earlier
     // openPopup opened. Refused where it cannot mean anything, the same way
     // `browser` is: the popup lives in the main browser only.
+    // F009.139 — `in: "opened"` runs a step in the window the page opened, taken
+    // over by an earlier waitForPopup. Same refusals as in:"popup".
     if ('in' in s) {
       const where = (s as { in?: unknown }).in;
-      if (where !== 'popup') throw new Error(`step ${index} (${s.type}): in must be "popup", got ${JSON.stringify(where)}`);
-      if (s.type === 'loop' || s.type === 'conditional' || s.type === 'openPopup') {
-        throw new Error(`step ${index} (${s.type}): in:"popup" goes on the steps that act in the popup, not on a ${s.type}`);
+      if (where !== 'popup' && where !== 'opened') throw new Error(`step ${index} (${s.type}): in must be "popup" or "opened", got ${JSON.stringify(where)}`);
+      if (s.type === 'loop' || s.type === 'conditional' || s.type === 'openPopup' || s.type === 'waitForPopup' || s.type === 'waitForPopupClose') {
+        throw new Error(`step ${index} (${s.type}): in:"${where}" goes on the steps that act in that window, not on a ${s.type}`);
       }
       const b = (s as { browser?: unknown }).browser;
       if (b !== undefined && b !== 'main') {
-        throw new Error(`step ${index} (${s.type}): in:"popup" and browser:${JSON.stringify(b)} cannot be combined — the extension is loaded in the main browser only`);
+        throw new Error(`step ${index} (${s.type}): in:"${where}" and browser:${JSON.stringify(b)} cannot be combined — it lives in the main browser only`);
       }
-      if (inParallel) throw new Error(`step ${index} (${s.type}): in:"popup" is not allowed inside a parallel loop`);
+      if (inParallel) throw new Error(`step ${index} (${s.type}): in:"${where}" is not allowed inside a parallel loop`);
+    }
+    if ((s.type === 'waitForPopup' || s.type === 'waitForPopupClose') && (('browser' in s && s.browser !== 'main') || inParallel)) {
+      throw new Error(`step ${index} (${s.type}): follows a window of the main browser only`);
     }
     if (s.type === 'openPopup') {
       const pth = (s as { path?: unknown }).path;
@@ -1165,7 +1178,8 @@ function parseStepBlock(lines: IndentLine[], start: number, minIndent: number):
     // F009.122 — `- in <name>: <step>` runs the step in that named browser.
     const inM = body.match(/^in\s+([^\s:]+)\s*:\s*(.+)$/);
     if (inM) {
-      steps.push(Object.assign(parseManuscriptStep(inM[2]!), { browser: inM[1]! }));
+      // F009.139 — `- in opened: <step>` is the window the page opened, not a browser.
+      steps.push(Object.assign(parseManuscriptStep(inM[2]!), inM[1] === 'opened' ? { in: 'opened' as const } : { browser: inM[1]! }));
     } else {
       steps.push(parseManuscriptStep(body));
     }
@@ -1233,6 +1247,7 @@ export const MANUSCRIPT_VERBS = [
   'expectText', 'expectVisible', 'expectEditable', 'expectAbsent', 'expectTopmost',
   'fillSelector', 'clickSelector',
   'inspect', 'assert', 'screenshot', 'capture',
+  'waitForPopup', 'waitForPopupClose',
 ] as const;
 
 function parseManuscriptStep(s: string): FlowStep {
@@ -1412,7 +1427,13 @@ function parseManuscriptStep(s: string): FlowStep {
       };
     }
     case 'inspect': {
-      const [, frame] = splitFrame(s);
+      const [head, frame] = splitFrame(s);
+      // F009.138 — `inspect html [testid]` is the flow step's html form (F389.2):
+      // the built screen's outerHTML, for cardmem_check_mockup_fidelity.
+      if (/^inspect\s+html\b/i.test(head)) {
+        const m = head.match(/\[([^\]]+)\]/);
+        return { type: 'inspect', html: true, ...(m ? { testid: m[1]!.trim() } : {}), ...(frame ? { frame } : {}) };
+      }
       return { type: 'inspect', ...(frame ? { frame } : {}) };
     }
     case 'assert':
@@ -1420,6 +1441,9 @@ function parseManuscriptStep(s: string): FlowStep {
     case 'screenshot':
       return { type: 'screenshot', label: s.replace(/^screenshot\s*/i, '').trim() || undefined };
     // F255.7 — `waitForBuild <sha>` or bare `waitForBuild` (any change from the live build).
+    // F009.139 — `- waitForPopup` / `- waitForPopupClose`.
+    case 'waitforpopup': return { type: 'waitForPopup' };
+    case 'waitforpopupclose': return { type: 'waitForPopupClose' };
     case 'waitforbuild': {
       const sha = s.replace(/^waitforbuild\s*/i, '').trim();
       return { type: 'waitForBuild', ...(sha ? { sha } : {}) };
@@ -1632,6 +1656,8 @@ function describe(step: FlowStep): string {
     case 'conditional': return `${step.present ? 'if' : 'unless'} [${step.testid}]`;
     case 'loop': return 'loop';
     case 'openPopup': return `openPopup ${step.path ?? '(manifest popup)'}`;
+    case 'waitForPopup': return 'waitForPopup';
+    case 'waitForPopupClose': return 'waitForPopupClose';
     case 'expectRequest': return `expectRequest ${step.method ? `${step.method.toUpperCase()} ` : ''}${step.url}${step.status ? ` → ${step.status}` : ''}`;
     case 'waitForBuild': return `waitForBuild${step.sha ? ` ${step.sha.slice(0, 8)}` : ' (changed)'}`;
     // F255.4 — show the offset in the step label so a positioned click is
@@ -2626,6 +2652,9 @@ async function execStep(page: Page, step: FlowStep, base: string, vars: Record<s
       throw new Error('loop steps are flattened before execution');
     case 'openPopup':
       throw new Error('openPopup steps are handled by runSeq, never execStep');
+    case 'waitForPopup':
+    case 'waitForPopupClose':
+      throw new Error(`${step.type} steps are handled by runSeq, never execStep`);
     case 'expectRequest':
       throw new Error('expectRequest steps are handled by runSeq, never execStep');
   }
@@ -2968,6 +2997,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       const onBrowser = {
         ...(browserName !== 'main' ? { browser: browserName } : {}),
         ...((step as { in?: string }).in === 'popup' ? { in: 'popup' as const } : {}),
+        ...((step as { in?: string }).in === 'opened' ? { in: 'opened' as const } : {}),
       };
       let sp: Page = page;
       if (i < from) {
@@ -2994,9 +3024,18 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
           // Keep the page under test the extension's active tab while the popup is driven.
           await extCtx.main.bringToFront();
         }
+        if ((step as { in?: string }).in === 'opened') {
+          if (!openedWin.page) throw new Error('in:"opened" before any waitForPopup step — take over the opened window first');
+          if (openedWin.page.isClosed()) throw new Error('the opened window has closed — steps after waitForPopupClose run in the opener (drop in:"opened")');
+          sp = openedWin.page;
+        }
         const out =
           step.type === 'openPopup'
             ? await openPopup(step)
+            : step.type === 'waitForPopup'
+            ? await waitForPopup(step)
+            : step.type === 'waitForPopupClose'
+            ? await waitForPopupClose(step)
             : step.type === 'expectRequest'
             ? await expectRequest(step, vars)
             : await execStep(sp, step, base, vars, opts.critic ?? 'off', opts.localPath, sink, filledPasswords, notListening, opts.secretRoot, mailCtx);
@@ -3165,6 +3204,39 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     extCtx.popup = popup;
     return null;
   };
+  // F009.139 — every window a page of the run's main browser opens, in order, from
+  // the first step on: a popup can open DURING the click, before any wait runs.
+  const openedWin: { seen: Page[]; taken: number; page: Page | null; arrived: (() => void) | null } = { seen: [], taken: 0, page: null, arrived: null };
+  const watchOpened = (context: BrowserContext): void => {
+    context.on('page', (p) => {
+      void p.opener().then((op) => {
+        if (!op) return; // a page Lens itself opened (openPopup, a new tab) — not the page's doing
+        openedWin.seen.push(p);
+        openedWin.arrived?.();
+      });
+    });
+  };
+  const waitForPopup = async (step: Extract<FlowStep, { type: 'waitForPopup' }>): Promise<null> => {
+    const timeout = step.timeout ?? 15_000;
+    if (openedWin.seen.length <= openedWin.taken) {
+      await new Promise<void>((resolve, reject) => {
+        const t = setTimeout(() => { openedWin.arrived = null; reject(new Error(`no window was opened within ${timeout} ms`)); }, timeout);
+        openedWin.arrived = () => { clearTimeout(t); openedWin.arrived = null; resolve(); };
+      });
+    }
+    const p = openedWin.seen[openedWin.seen.length - 1]!;
+    openedWin.taken = openedWin.seen.length;
+    openedWin.page = p;
+    collectFailures(p);
+    await p.waitForLoadState('domcontentloaded', { timeout });
+    return null;
+  };
+  const waitForPopupClose = async (step: Extract<FlowStep, { type: 'waitForPopupClose' }>): Promise<null> => {
+    if (!openedWin.page) throw new Error('waitForPopupClose before any waitForPopup step');
+    if (openedWin.page.isClosed()) return null;
+    await openedWin.page.waitForEvent('close', { timeout: step.timeout ?? 15_000 });
+    return null;
+  };
   // F009.128 — files the run downloads. A download is awaited before the context
   // closes; otherwise the bytes die with the browser and the report says nothing.
   const downloads: FlowDownload[] = [];
@@ -3314,6 +3386,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         collectFailures(page);
         watchRequests(context);
         watchDownloads(context);
+        watchOpened(context);
         if (ext && flow.extension && prepared) {
           extCtx = { context, id: ext.id, main: page, popup: null };
           const mint = flow.extension.storage_local_mint;

package/src/mcp.ts

@@ -405,7 +405,7 @@ export const TOOLS = [
   {
     name: 'lens_run_manuscript',
     description:
-      `Compile a human-readable markdown manuscript (fmc-automation style: "# flow: name", "base: <url>", then one "- <verb> …" per line) into a flow and run it E2E. VERBS (${MANUSCRIPT_VERBS.length}, this is the complete list): ${MANUSCRIPT_VERBS.join(' / ')}. Shapes: "- goto /x" · "- fill [testid] = value" · a PASSWORD without plaintext: "- fill [testid] from file <path>" (absolute, or relative to local_path) or "- fill [testid] from env <NAME>" (F009.121 — password inputs only; the value never appears in the run, the report or a screenshot) · "- click [testid]" · "- press Enter" (global) or "- press Enter [testid]" (on a focused element) · "- expectText [testid] ~ text" · "- drag [source] -> [target]" or "- drag [node] by 120,-40" (a canvas offset; both move in 10 mousemoves so React Flow / d3-drag nodes really move — "steps N" to change, F009.123) · "- upload [input-testid] = <fixture>" · an input with NO testid, also inside an open shadow root: "- uploadSelector <css> = <fixture>[, <fixture>]" (F009.136; fixtures repo-relative to local_path or data:) · a CODE FROM MAIL: "- fill [testid] from mail to jam@jams.party subject ~ Jam match /\\b\\d{6}\\b/" (F009.137 — waits ≤60 s for a mail received after the step started, read through mail-mcp; only the test mailbox webhouse.developer@gmail.com / jam@jams.party; the mail is deleted after the run, report carries mail {consumed, cleaned}; the code never appears in the report) · "- assert: <js>" · "- screenshot label" · frame-aware "- fillSelector <css> = <value> @frame <iframe>" and "- clickSelector <css> @frame <iframe>" · "- waitForUrl <substring>". TWO BROWSERS AT ONCE (F009.122): prefix a step with "in <name>:" — "- in b: goto /" · "- in b: expectText [note] == Hej" — and it runs in its own browser (own cookies + storage), open alongside the default one for the rest of the run; steps without the prefix run in the default browser. Click modifiers: "- click [testid] via enter" (F255.1, for Angular/MDC buttons a mouse click does not activate) and "- click [testid] @ 50%,28%" (F255.4, aim at a point inside a canvas/3D surface). A field that already HOLDS a value may no longer render an input — a combobox typically swaps to its selected state, so "fill" times out there while "press ArrowDown" / "press Enter" still drive it (fd-sundhed, 2026-08-21). The authoring shortcut — write prose, not JSON.`,
+      `Compile a human-readable markdown manuscript (fmc-automation style: "# flow: name", "base: <url>", then one "- <verb> …" per line) into a flow and run it E2E. VERBS (${MANUSCRIPT_VERBS.length}, this is the complete list): ${MANUSCRIPT_VERBS.join(' / ')}. Shapes: "- goto /x" · "- fill [testid] = value" · a PASSWORD without plaintext: "- fill [testid] from file <path>" (absolute, or relative to local_path) or "- fill [testid] from env <NAME>" (F009.121 — password inputs only; the value never appears in the run, the report or a screenshot) · "- click [testid]" · "- press Enter" (global) or "- press Enter [testid]" (on a focused element) · "- expectText [testid] ~ text" · "- drag [source] -> [target]" or "- drag [node] by 120,-40" (a canvas offset; both move in 10 mousemoves so React Flow / d3-drag nodes really move — "steps N" to change, F009.123) · "- upload [input-testid] = <fixture>" · an input with NO testid, also inside an open shadow root: "- uploadSelector <css> = <fixture>[, <fixture>]" (F009.136; fixtures repo-relative to local_path or data:) · a CODE FROM MAIL: "- fill [testid] from mail to jam@jams.party subject ~ Jam match /\\b\\d{6}\\b/" (F009.137 — waits ≤60 s for a mail received after the step started, read through mail-mcp; only the test mailbox webhouse.developer@gmail.com / jam@jams.party; the mail is deleted after the run, report carries mail {consumed, cleaned}; the code never appears in the report) · the BUILT SCREEN'S HTML after the click path: "- inspect html [testid]" (or "- inspect html" for the whole body) — the step detail is that outerHTML, for cardmem_check_mockup_fidelity's built_html (F009.138) · a WINDOW THE PAGE OPENS (window.open / target=_blank — an OAuth dialog like «Continue with Facebook/Google»): "- waitForPopup" takes it over (also one opened by the click just before), "- in opened: <step>" acts in it, "- waitForPopupClose" waits for it to close; steps without the prefix stay in the opener (F009.139) · "- assert: <js>" · "- screenshot label" · frame-aware "- fillSelector <css> = <value> @frame <iframe>" and "- clickSelector <css> @frame <iframe>" · "- waitForUrl <substring>". TWO BROWSERS AT ONCE (F009.122): prefix a step with "in <name>:" — "- in b: goto /" · "- in b: expectText [note] == Hej" — and it runs in its own browser (own cookies + storage), open alongside the default one for the rest of the run; steps without the prefix run in the default browser. Click modifiers: "- click [testid] via enter" (F255.1, for Angular/MDC buttons a mouse click does not activate) and "- click [testid] @ 50%,28%" (F255.4, aim at a point inside a canvas/3D surface). A field that already HOLDS a value may no longer render an input — a combobox typically swaps to its selected state, so "fill" times out there while "press ArrowDown" / "press Enter" still drive it (fd-sundhed, 2026-08-21). The authoring shortcut — write prose, not JSON.`,
     inputSchema: {
       type: 'object',
       required: ['project', 'manuscript'],