@broberg/lens-daemon 0.1.6 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "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",
@@ -16,7 +16,7 @@
     "turndown": "^7.2.4",
     "zod": "^3.23.8",
     "@broberg/lens-svg": "0.1.0",
-    "@broberg/lens-engine": "0.10.2"
+    "@broberg/lens-engine": "0.11.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",

package/src/flow-store.ts

@@ -17,6 +17,8 @@ export interface StoredFlowStep {
   index: number;
   type: string;
   label: string;
+  /** F009.122 — the named browser the step ran in; absent = the default one. */
+  browser?: string;
   status: 'pass' | 'fail' | 'skip';
   testid: string | null;
   detail: string | null;
@@ -82,6 +84,8 @@ export async function recordFlowRun(
       index: s.index,
       type: s.type,
       label: s.label,
+      // F009.122 — third-place rule: a field only flow.ts knows reaches nobody.
+      ...(s.browser ? { browser: s.browser } : {}),
       status: s.status,
       testid: s.testid,
       detail: s.detail,

package/src/flow.ts

@@ -233,6 +233,8 @@ export interface FlowStepResult {
   index: number;
   type: string;
   label: string;
+  /** F009.122 — the named browser this step ran in. Absent = the default one. */
+  browser?: string;
   status: 'pass' | 'fail' | 'skip';
   testid: string | null;
   detail: string | null;
@@ -449,7 +451,12 @@ function isValidTarget(t: unknown): boolean {
  *  FlowStep union above; flow-step-fields.test.ts reads the union from source and
  *  fails if the two drift. An unknown field is REFUSED: `inspect` with a guessed
  *  `selector` used to run a whole-page dump in silence (cardmem, flow b62ffca3). */
-const SHARED_STEP_FIELDS = ['type', 'label', 'timeout', 'timeout_ms'];
+const SHARED_STEP_FIELDS = ['type', 'label', 'timeout', 'timeout_ms', 'browser'];
+
+/** F009.122 — a step may name the browser it runs in. Each name is its own browser
+ *  context (own cookies + storage), opened on first use and kept open for the rest
+ *  of the run, so two people can be driven at the same time. `main` is the default. */
+const BROWSER_NAME = /^[a-z][a-z0-9_-]{0,23}$/;
 const TARGETED = ['testid', 'target'];
 export const STEP_FIELDS: Record<string, string[]> = {
   goto: ['path'],
@@ -484,7 +491,7 @@ export const STEP_FIELDS: Record<string, string[]> = {
   loop: ['data', 'steps', 'parallel'],
 };
 
-function validateAndNormalizeSteps(steps: unknown[], depth = 0): void {
+function validateAndNormalizeSteps(steps: unknown[], depth = 0, inParallel = false): void {
   if (depth > 3) throw new Error('flow loops nested too deep (max 3)');
   for (const [index, raw] of steps.entries()) {
     const s = raw as FlowStep & Record<string, unknown>;
@@ -518,13 +525,29 @@ function validateAndNormalizeSteps(steps: unknown[], depth = 0): void {
     if (s.type === 'loop') {
       if (!Array.isArray((s as { data?: unknown }).data)) throw new Error('loop step requires data[]');
       if (!Array.isArray((s as { steps?: unknown }).steps)) throw new Error('loop step requires steps[]');
-      validateAndNormalizeSteps((s as { steps: unknown[] }).steps, depth + 1);
+      const par = (s as { parallel?: unknown }).parallel;
+      validateAndNormalizeSteps((s as { steps: unknown[] }).steps, depth + 1, inParallel || (typeof par === 'number' && par > 1));
     }
     // F213.3 — control-flow + composite verbs.
     if (s.type === 'conditional') {
       if (typeof (s as { present?: unknown }).present !== 'boolean') throw new Error('conditional step requires a boolean present');
       if (!Array.isArray((s as { steps?: unknown }).steps)) throw new Error('conditional step requires steps[]');
-      validateAndNormalizeSteps((s as { steps: unknown[] }).steps, depth + 1);
+      validateAndNormalizeSteps((s as { steps: unknown[] }).steps, depth + 1, inParallel);
+    }
+    // F009.122 — the browser a step runs in. Refused where it cannot mean anything:
+    // a loop/conditional is not run in a browser (its children are), and a parallel
+    // loop iteration already owns a context of its own.
+    if ('browser' in s) {
+      const b = (s as { browser?: unknown }).browser;
+      if (typeof b !== 'string' || !BROWSER_NAME.test(b)) {
+        throw new Error(`step ${index} (${s.type}): browser must be a lowercase name like "anna" or "b" (${BROWSER_NAME}), got ${JSON.stringify(b)}`);
+      }
+      if (s.type === 'loop' || s.type === 'conditional') {
+        throw new Error(`step ${index} (${s.type}): browser goes on the steps inside a ${s.type}, not on the ${s.type} itself`);
+      }
+      if (inParallel) {
+        throw new Error(`step ${index} (${s.type}): browser is not allowed inside a parallel loop — each iteration already runs in its own browser`);
+      }
     }
     if (s.type === 'autocomplete') {
       if (typeof (s as { value?: unknown }).value !== 'string') throw new Error('autocomplete step requires a string value');
@@ -815,7 +838,13 @@ function parseStepBlock(lines: IndentLine[], start: number, minIndent: number):
       i = nextJ;
       continue;
     }
-    steps.push(parseManuscriptStep(body));
+    // 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]! }));
+    } else {
+      steps.push(parseManuscriptStep(body));
+    }
     i++;
   }
   return [steps, i];
@@ -2379,12 +2408,60 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         skipFill(s.steps, idx, vars, detail);
         idx += flattenCount(s.steps);
       } else {
-        record({ index: idx, type: s.type, label: s.label ?? describe(s), status: 'skip', testid: testidOf(s), detail, screenshot: null });
+        const b = (s as { browser?: string }).browser;
+        record({ index: idx, type: s.type, label: s.label ?? describe(s), ...(b ? { browser: b } : {}), status: 'skip', testid: testidOf(s), detail, screenshot: null });
         idx += 1;
       }
     }
   };
 
+  // ── F009.122 · named browsers ────────────────────────────────────────────
+  // Each name gets its own context through the SAME withPage the default browser
+  // uses (same auth, storage seed, viewport, engine), held open until the run ends.
+  // The steps stay sequential; the browsers are concurrent — that is what lets
+  // «A types, then B sees it» be measured with B's own timeout.
+  const browsers = new Map<string, { page: Promise<Page>; release: () => void; closed: Promise<unknown> }>();
+  const pageFor = (name: string, main: Page): Promise<Page> => {
+    if (name === 'main') return Promise.resolve(main);
+    const open = browsers.get(name);
+    if (open) return open.page;
+    let release!: () => void;
+    const held = new Promise<void>((r) => (release = r));
+    let resolvePage!: (p: Page) => void;
+    let rejectPage!: (e: unknown) => void;
+    const pagePromise = new Promise<Page>((res, rej) => {
+      resolvePage = res;
+      rejectPage = rej;
+    });
+    const closed = withPage(
+      { prepareContext: prepare, seedStorage, viewport: opts.viewport, engine: opts.engine, locale: opts.locale, timezone: opts.timezone, reducedMotion: opts.reducedMotion },
+      async (p) => {
+        collectFailures(p);
+        resolvePage(p);
+        await held;
+      },
+    ).catch((err) => rejectPage(err));
+    browsers.set(name, { page: pagePromise, release, closed });
+    return pagePromise;
+  };
+  const closeBrowsers = async () => {
+    for (const b of browsers.values()) b.release();
+    await Promise.all([...browsers.values()].map((b) => b.closed));
+    browsers.clear();
+  };
+  // Where each browser's page landed is that browser's own fact. Swapped on every
+  // change of browser, so a goto in B can neither move A's ejection baseline nor
+  // reset A's navigation clock.
+  let currentBrowser = 'main';
+  const navStates = new Map<string, { urlAtLoad: string | null; navActionPending: boolean; onWrongPage: string | null; lastNavAt: number }>();
+  const switchBrowser = (name: string) => {
+    if (name === currentBrowser) return;
+    navStates.set(currentBrowser, { urlAtLoad, navActionPending, onWrongPage, lastNavAt });
+    const next = navStates.get(name) ?? { urlAtLoad: null, navActionPending: false, onWrongPage: null, lastNavAt: Date.now() };
+    ({ urlAtLoad, navActionPending, onWrongPage, lastNavAt } = next);
+    currentBrowser = name;
+  };
+
   // Run a step-list on `page` starting at `startIndex`. Returns whether a
   // non-loop step failed (so the caller can stop THIS sequence).
   async function runSeq(page: Page, steps: FlowStep[], vars: Record<string, unknown>, startIndex: number): Promise<{ failedHere: boolean }> {
@@ -2459,6 +2536,11 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       const i = idx;
       idx += 1;
       const label = step.label ?? describe(step);
+      // F009.122 — which browser this step runs in. `sp` is the page every line
+      // below acts on; the loop's own `page` is the default browser.
+      const browserName = (step as { browser?: string }).browser ?? 'main';
+      const onBrowser = browserName !== 'main' ? { browser: browserName } : {};
+      let sp: Page = page;
       if (i < from) {
         record({ index: i, type: step.type, label, status: 'skip', testid: testidOf(step), detail: 'resumed past', screenshot: null });
         continue;
@@ -2474,7 +2556,9 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       // matter most, and a sink scoped to the try is unreachable from the catch.
       const sink: CriticSink = { critic: null };
       try {
-        const out = await execStep(page, step, base, vars, opts.critic ?? 'off', opts.localPath, sink, filledPasswords, notListening, opts.secretRoot);
+        switchBrowser(browserName);
+        sp = await pageFor(browserName, page);
+        const out = await execStep(sp, step, base, vars, opts.critic ?? 'off', opts.localPath, sink, filledPasswords, notListening, opts.secretRoot);
         const obj = out !== null && !Buffer.isBuffer(out) && typeof out === 'object' ? out : null;
         const inspect = obj && '__inspect' in obj ? (obj as { __inspect: string }).__inspect : null;
         const via = obj && '__via' in obj ? (obj as { __via: string }).__via : null;
@@ -2496,7 +2580,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         // would call that an ejection on every single run.
         if (formsAVerdict(step.type)) formedAVerdict = true;
         if (NAVIGATES_BY_DESIGN.has(step.type)) {
-          urlAtLoad = safeUrl(page) ?? urlAtLoad;
+          urlAtLoad = safeUrl(sp) ?? urlAtLoad;
           // A goto is already settled — Playwright waited for it. Any OTHER
           // navigating action may commit after it returns, so it leaves a note
           // saying "one URL change after this is mine". See classifyUrlChange.
@@ -2506,7 +2590,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
           // under it, that opinion is void — and `page.url()` is a synchronous
           // read of state Playwright already holds, so this costs nothing and
           // adds no polling (the tax AC4 forbids).
-          const verdict = classifyUrlChange({ loaded: urlAtLoad, current: safeUrl(page) ?? urlAtLoad, navActionPending });
+          const verdict = classifyUrlChange({ loaded: urlAtLoad, current: safeUrl(sp) ?? urlAtLoad, navActionPending });
           if (verdict.kind === 'flow-navigation') {
             urlAtLoad = verdict.rebaseTo;
             navActionPending = false;
@@ -2525,6 +2609,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
           index: i,
           type: step.type,
           label,
+          ...onBrowser,
           status: 'pass',
           ...navOffset,
           ms_step_duration: Date.now() - stepStartedAt,
@@ -2547,7 +2632,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         const msg = err instanceof Error ? err.message : String(err);
         let shot: Buffer | null = null;
         try {
-          shot = (await takeShot(page, 'viewport', null, 5000)).screenshot;
+          shot = (await takeShot(sp, 'viewport', null, 5000)).screenshot;
         } catch {
           // page may be in a bad state — a missing failure shot is acceptable
         }
@@ -2581,6 +2666,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
           index: i,
           type: step.type,
           label,
+          ...onBrowser,
           // Still 'fail' — a broken probe is never less than a failure.
           status: 'fail',
           // F213.11 — on the FAILING step above all: a lost write is exactly where
@@ -2688,7 +2774,15 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
             // cookie read failed — leave authReach null rather than invent a verdict
           }
         }
-        const r = await runSeq(page, flow.steps, {}, 0);
+        let r: { failedHere: boolean };
+        try {
+          r = await runSeq(page, flow.steps, {}, 0);
+        } finally {
+          // F009.122 — the named browsers close with the run, before the default one,
+          // and the end-of-run checks below are about the DEFAULT browser's page.
+          await closeBrowsers();
+          switchBrowser('main');
+        }
         if (r.failedHere) aborted = true; // a TOP-LEVEL step failed → flow aborts
         // ── F213.10 · the window, and why it has to exist at all ──────────────
         //

package/src/mcp.ts

@@ -321,7 +321,7 @@ export const TOOLS = [
       // A hand-written list in a tool description is the only thing most callers
       // ever read, and ours had drifted to 9 of 26: three repos reported an
       // existing verb as missing because of it.
-      `Run an E2E manuscript flow: drive a site step-by-step in one authed page. Steps (${[...STEP_TYPES].length}): ${[...STEP_TYPES].join(' / ')}. testid-anchored steps use [data-testid]; a fill can take valueFrom:{path}|{env} instead of value to type a password without it ever appearing in the run (F009.121, password inputs only); fillSelector/clickSelector use a raw CSS selector + optional cross-origin frame chain to reach a 3rd-party iframe a testid can\'t (e.g. Stripe PCI card fields), and waitForUrl asserts the redirect back to our origin. Stops + pins a screenshot on the first failing step. Returns a per-step report with screenshot_url per step. This is full End-to-End — it can create users, submit forms, complete a Stripe test payment, etc. (set mutates:true for write flows). Scoped to the project slug.`,
+      `Run an E2E manuscript flow: drive a site step-by-step in one authed page — or several: any step may carry browser:"<name>" to run in its own browser (own cookies + storage), opened on first use and kept open beside the default one, so two users can be driven at once (F009.122). Steps (${[...STEP_TYPES].length}): ${[...STEP_TYPES].join(' / ')}. testid-anchored steps use [data-testid]; a fill can take valueFrom:{path}|{env} instead of value to type a password without it ever appearing in the run (F009.121, password inputs only); fillSelector/clickSelector use a raw CSS selector + optional cross-origin frame chain to reach a 3rd-party iframe a testid can\'t (e.g. Stripe PCI card fields), and waitForUrl asserts the redirect back to our origin. Stops + pins a screenshot on the first failing step. Returns a per-step report with screenshot_url per step. This is full End-to-End — it can create users, submit forms, complete a Stripe test payment, etc. (set mutates:true for write flows). Scoped to the project slug.`,
     inputSchema: {
       type: 'object',
       required: ['project', 'flow'],
@@ -373,7 +373,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]" · "- upload [input-testid] = <fixture>" · "- assert: <js>" · "- screenshot label" · frame-aware "- fillSelector <css> = <value> @frame <iframe>" and "- clickSelector <css> @frame <iframe>" · "- waitForUrl <substring>". 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]" · "- upload [input-testid] = <fixture>" · "- 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'],

package/src/service.ts

@@ -682,6 +682,8 @@ export function flowRunView(row: LensFlowRunRow, port: number) {
     type: s.type,
     label: s.label,
     status: s.status,
+    // F009.122 — which named browser ran the step. Absent = the default one.
+    ...(s.browser ? { browser: s.browser } : {}),
     testid: s.testid,
     detail: s.detail,
     ...(s.fault ? { fault: s.fault } : {}),