@broberg/lens-daemon 0.1.25 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@broberg/lens-daemon",
-  "version": "0.1.25",
+  "version": "0.1.28",
   "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.33.5",
     "turndown": "^7.2.4",
     "zod": "^3.23.8",
-    "@broberg/lens-svg": "0.1.0",
-    "@broberg/lens-engine": "0.13.1"
+    "@broberg/lens-engine": "0.14.0",
+    "@broberg/lens-svg": "0.1.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.10.6",

package/src/flow-store.ts

@@ -122,6 +122,15 @@ export async function recordFlowRun(
     storedDownloads.push({ ...meta, ...(key ? { key } : {}) });
   }
 
+  // F009.133 — shapes can run to hundreds of KB; the row keeps counts + the key.
+  let networkShapes: { requests: number; websockets: number; other_hosts: number; caps_hit: string[]; key: string } | null = null;
+  if (result.network_shapes) {
+    const key = artifactKeys.flowNetworkShapes(projectSlug, id);
+    await storage.put(key, Buffer.from(JSON.stringify(result.network_shapes, null, 1)), 'application/json');
+    const n = result.network_shapes;
+    networkShapes = { requests: n.requests.length, websockets: n.websockets.length, other_hosts: n.other_hosts.length, caps_hit: n.caps_hit, key };
+  }
+
   const row: LensFlowRunRow = {
     id,
     project_slug: projectSlug,
@@ -173,6 +182,7 @@ export async function recordFlowRun(
       ...(result.not_listening ? { not_listening: result.not_listening } : {}),
       // F009.128 — always written when the run reported it, empty included.
       ...(result.downloads ? { downloads: storedDownloads } : {}),
+      ...(networkShapes ? { network_shapes: networkShapes } : {}),
     }),
   };
 

package/src/flow.ts

@@ -24,6 +24,7 @@ import {
   type Target,
 } from '@broberg/lens-engine';
 import { withPage, type LensEngine } from './browser.ts';
+import { collectNetworkShapes, type NetworkShapesOptions, type NetworkShapesReport } from './network-shapes.ts';
 import { deadline, defaultPopupOf, prepareExtension, seedExtensionStorage, SIMULATED_ACCESS_NOTE } from './extension-flow.ts';
 import { authPrepare, fetchMintJson, persistStorageState, persistTarget, type AuthConfig, type AuthEnv } from './auth/index.ts';
 import { takeShot, settleForShot } from './capture.ts';
@@ -185,6 +186,9 @@ export interface Flow {
    *  standing in for the toolbar click (activeTab) a headless run cannot make;
    *  the original build is never written, and the report says it was simulated. */
   extension?: FlowExtension;
+  /** F009.133 — record the SHAPE (never a value) of every call the page makes:
+   *  fetch/xhr request + response bodies and WebSocket frames. */
+  network_shapes?: true | NetworkShapesOptions;
   steps: FlowStep[];
 }
 
@@ -403,6 +407,8 @@ export async function finishDownloads(pending: Promise<void>[], downloads: FlowD
 }
 
 export interface FlowResult {
+  /** F009.133 — present when flow.network_shapes was asked for. */
+  network_shapes?: NetworkShapesReport;
   /** F009.128 — files the run downloaded. Always present on a finished run. */
   downloads?: FlowDownload[];
   /** F009.131 — set when auth.persist was asked for: whether the renewed login was
@@ -545,6 +551,18 @@ export function parseFlow(input: unknown): Flow {
   }
   persistTarget(f.auth as AuthConfig | undefined); // F009.131 — refuse a persist that cannot be honoured
   validateAndNormalizeSteps(f.steps);
+  // F009.133 — refused when malformed, for the same reason as extension above.
+  let networkShapes: true | NetworkShapesOptions | undefined;
+  if (f.network_shapes !== undefined) {
+    const n = f.network_shapes as unknown;
+    const strings = (v: unknown) => v === undefined || (Array.isArray(v) && v.every((x) => typeof x === 'string' && x.length > 0));
+    if (n === true) networkShapes = true;
+    else if (n && typeof n === 'object' && !Array.isArray(n) && Object.keys(n).every((k) => k === 'hosts' || k === 'reveal') && strings((n as NetworkShapesOptions).hosts) && strings((n as NetworkShapesOptions).reveal)) {
+      networkShapes = n as NetworkShapesOptions;
+    } else {
+      throw new Error('flow.network_shapes must be true or {hosts?: ["<host>"], reveal?: ["<key>"]}');
+    }
+  }
   if (!extension && usesPopup(f.steps as FlowStep[])) {
     throw new Error('openPopup / in:"popup" need flow.extension — there is no extension loaded to open a popup from');
   }
@@ -556,6 +574,7 @@ export function parseFlow(input: unknown): Flow {
     ...(f.wait_for_build !== undefined ? { wait_for_build: f.wait_for_build } : {}),
     ...(f.eject_grace_ms !== undefined ? { eject_grace_ms: f.eject_grace_ms } : {}),
     ...(extension ? { extension } : {}),
+    ...(networkShapes ? { network_shapes: networkShapes } : {}),
     steps: f.steps as FlowStep[],
   };
 }
@@ -3028,6 +3047,9 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
   // 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[] = [];
+  // F009.133 — the collector lives on the main context; read out before it closes.
+  const shapesRef: { c: ReturnType<typeof collectNetworkShapes> | null } = { c: null };
+  let networkShapesReport: NetworkShapesReport | undefined;
   const persistPath = persistTarget(flow.auth);
   let authPersisted: FlowResult['auth_persisted'] = persistPath ? { ok: false, reason: 'the run ended before the login could be saved' } : undefined;
   const pendingDownloads: Promise<void>[] = [];
@@ -3160,6 +3182,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
       },
       async (page, context, ext) => {
         videoPage = page;
+        if (flow.network_shapes) shapesRef.c = collectNetworkShapes(context, flow.network_shapes === true ? {} : flow.network_shapes);
         collectFailures(page);
         watchRequests(context);
         watchDownloads(context);
@@ -3286,6 +3309,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
         // Bounded: a download that never finishes must not hang the run. Whatever is
         // still unfinished is reported as such, never dropped.
         await finishDownloads(pendingDownloads, downloads, DOWNLOAD_FINISH_MS);
+        if (shapesRef.c) networkShapesReport = await shapesRef.c.finish();
         // F009.131 — after the last step, pass or fail, while the context is open.
         if (persistPath) {
           try {
@@ -3301,8 +3325,10 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     reason = reason ?? (err instanceof Error ? err.message : String(err));
     // Keep the recording even on a crash — watching HOW it broke is the whole point.
     const video = await readVideo();
+    // F009.133 — what was collected before the crash is still in memory; say it.
+    if (shapesRef.c && !networkShapesReport) networkShapesReport = await shapesRef.c.finish();
     await prepared?.cleanup();
-    return { downloads, ...(authPersisted ? { auth_persisted: authPersisted } : {}), ...(extensionInfo ? { extension: extensionInfo } : {}), name: flow.name, status: 'error', steps: results.sort((a, b) => a.index - b.index), failed_at: firstFailedAt, reason: leadWithRedirect(reason, firstRedirect), duration_ms: Date.now() - startedAt, video, build: observedBuild, final_url: finalUrl, redirected: firstRedirect, password_in_url: passwordInUrl(finalUrl, filledPasswords), not_listening: notListening[0] ?? null, reduced_motion: opts.reducedMotion ?? 'reduce' };
+    return { downloads, ...(networkShapesReport ? { network_shapes: networkShapesReport } : {}), ...(authPersisted ? { auth_persisted: authPersisted } : {}), ...(extensionInfo ? { extension: extensionInfo } : {}), name: flow.name, status: 'error', steps: results.sort((a, b) => a.index - b.index), failed_at: firstFailedAt, reason: leadWithRedirect(reason, firstRedirect), duration_ms: Date.now() - startedAt, video, build: observedBuild, final_url: finalUrl, redirected: firstRedirect, password_in_url: passwordInUrl(finalUrl, filledPasswords), not_listening: notListening[0] ?? null, reduced_motion: opts.reducedMotion ?? 'reduce' };
   }
 
   const video = await readVideo();
@@ -3357,6 +3383,7 @@ export async function runFlow(flow: Flow, env: AuthEnv, opts: RunFlowOptions = {
     reduced_motion: opts.reducedMotion ?? 'reduce',
     ...(authPersisted ? { auth_persisted: authPersisted } : {}),
     ...(extensionInfo ? { extension: extensionInfo } : {}),
+    ...(networkShapesReport ? { network_shapes: networkShapesReport } : {}),
     downloads,
   };
 }

package/src/frames.ts

@@ -49,6 +49,11 @@ export async function cutFrames(
   bin = 'ffmpeg',
 ): Promise<CutResult> {
   const fps = opts.fps ?? 4;
+  // fps is pasted into an ffmpeg filter string: a non-number there is a second
+  // filter (H4, 2026-10-21 — drawtext=textfile=… drew a file into a frame).
+  if (typeof fps !== 'number' || !Number.isFinite(fps) || fps <= 0 || fps > 120) {
+    throw new Error(`cutFrames: fps must be a number above 0 and at most 120 — got ${JSON.stringify(fps)}`);
+  }
   if (!(await ffmpegAvailable(bin))) {
     return { frames: [], unavailable: `${bin} is not installed — video kept, no stills` };
   }

package/src/http.ts

@@ -31,9 +31,12 @@ import {
 import { drainUploads, uploadStats } from './artifact-uploads.ts';
 import { backfillFromDisk } from './artifact-backfill.ts';
 import { artifactContentType } from './storage.ts';
+import { localRequestGuard } from './local-guard.ts';
 
 export function createLensRouter(deps: LensDeps): Hono {
   const r = new Hono();
+  // Security sweep 2026-10-21 (H1–H4): loopback Host + JSON writes only. First.
+  r.use('*', localRequestGuard(deps.port));
   // lens F001.5 — the daemon's sandbox is injected, never copied (sandbox.ts).
   if (deps.resolveSandboxedPath) setSandboxResolver(deps.resolveSandboxedPath);
   // lens F001.5 — the routes that used to be registered one by one in the

package/src/local-guard.ts

@@ -0,0 +1,41 @@
+// Security sweep 2026-10-21, high findings H1–H4: the daemon on 127.0.0.1 took
+// a call from anyone who could make a browser send one — a DNS-rebound page
+// (it never checked Host) or any site's "simple" text/plain POST (it parsed JSON
+// whatever the content type). Through that door a page could read any file
+// (/lens/artifact), drive the owner's logged-in profile, mint a secret to its
+// own URL, or approve a baseline.
+//
+// Two rules close it without a token, because a browser cannot break either:
+//   · Host must name this loopback daemon — a rebound page sends its own name.
+//   · A write (POST/PUT/PATCH/DELETE) must be application/json — a cross-site
+//     page cannot send that without a CORS preflight, and the preflight is only
+//     granted to the daemon shell's own allowlisted origins.
+// Lens' own Chromium visiting a hostile page is the same case as any browser.
+//
+// A non-browser caller (curl, an MCP client, the cardmem SPA via CORS) already
+// sends both, so nothing legitimate changes.
+
+import type { MiddlewareHandler } from 'hono';
+
+const WRITE = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+export function localRequestGuard(port: number): MiddlewareHandler {
+  const hosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
+  return async (c, next) => {
+    // A server request carries Host; Bun builds c.req.url from it, so the URL's
+    // host is the same value when the header is not on the Request object.
+    const host = (c.req.header('host') ?? new URL(c.req.url).host).toLowerCase();
+    if (!hosts.has(host)) {
+      return c.json({ ok: false, error: `lens daemon: refused Host "${host}" — only this machine's loopback address may call it` }, 421);
+    }
+    if (WRITE.has(c.req.method)) {
+      const type = (c.req.header('content-type') ?? '').split(';')[0]!.trim().toLowerCase();
+      // A body-less DELETE (the MCP session close) carries no content type.
+      const empty = c.req.method === 'DELETE' && !c.req.header('content-length') && !type;
+      if (type !== 'application/json' && !empty) {
+        return c.json({ ok: false, error: 'lens daemon: a write must be Content-Type: application/json' }, 415);
+      }
+    }
+    await next();
+  };
+}

package/src/mcp.ts

@@ -9,6 +9,7 @@
 
 import { Hono } from 'hono';
 import { MANUSCRIPT_VERBS, STEP_TYPES } from './flow.ts';
+import { localRequestGuard } from './local-guard.ts';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
@@ -361,6 +362,11 @@ export const TOOLS = [
                 'F255.7 — do not start until the app is serving the build under test. A commit sha waits for THAT build; true waits for any change from the build live at run start. Polls GET /api/health for a `build` field (the fleet contract), from the runner with no-store, requiring 3 consecutive matching reads so a fleet mid-rollout cannot end the wait early. Fails loudly if the app exposes no marker. Use it right after a deploy — otherwise a green run may be verifying the build you just replaced.',
             },
             auth: authSchema,
+            network_shapes: {
+              type: ['boolean', 'object'],
+              description:
+                'F009.133 — true or {hosts?:["<host>"], reveal?:["<key>"]}: record the SHAPE (keys, types, string lengths — never a value) of every fetch/xhr call to the page\'s own host (+ hosts): method, path, query keys, status, request-body and response-body shape (JSON, Google )]}\' chunks, SSE, form, SignalR), plus every WebSocket frame. Other hosts are only counted. reveal keeps the value of those named keys (e.g. "rpcids", "target"). The report lands as an artifact; findings.network_shapes carries counts + url.',
+            },
             extension: {
               type: 'object',
               required: ['path'],
@@ -541,6 +547,7 @@ async function dispatch(deps: LensDeps, name: string, args: any): Promise<unknow
 
 export function createLensMcpRouter(deps: LensDeps): Hono {
   const router = new Hono();
+  router.use('*', localRequestGuard(deps.port));
   router.all('/', async (c) => {
     const server = new Server(
       { name: 'cardmem-lens', version: '0.1.0' },

package/src/network-shapes.ts

@@ -0,0 +1,344 @@
+// F009.133 — the SHAPE of every call a page makes, never a value.
+//
+// components builds data readers for AI chat services and needs to know which
+// call carries a conversation and what its request and answer look like. The
+// conversation itself must not leave the run, so bodies are read here, reduced
+// to a shape in memory, and only the shape is kept. The one exception is a key
+// the caller NAMES in `reveal` (Gemini's `rpcids`, SignalR's `target`): those
+// are protocol identifiers, and the identifier is the answer being asked for.
+import type { BrowserContext, Page, Request, Response, WebSocket } from 'playwright';
+
+export type Shape = string | Shape[] | { [k: string]: Shape };
+
+export interface NetworkShapesOptions {
+  /** Hosts shaped besides the page's own (e.g. a chat service's WebSocket host). */
+  hosts?: string[];
+  /** Keys whose string VALUE is kept (query, form and JSON object keys alike). */
+  reveal?: string[];
+}
+
+export interface ShapedRequest {
+  method: string;
+  /** origin + path; the query is in `query` as keys + shapes. */
+  url: string;
+  query?: Record<string, Shape>;
+  status: number;
+  content_type: string;
+  request_shape?: Shape;
+  response_shape?: Shape;
+  /** Identical calls (same method, url, shapes, status) are merged. */
+  count: number;
+}
+
+export interface FrameShapes {
+  frames: number;
+  shapes: { shape: Shape; count: number }[];
+}
+
+export interface ShapedSocket {
+  url: string;
+  sent: FrameShapes;
+  received: FrameShapes;
+}
+
+export interface NetworkShapesReport {
+  page_hosts: string[];
+  requests: ShapedRequest[];
+  websockets: ShapedSocket[];
+  /** Calls to hosts outside scope: counted, never read. */
+  other_hosts: { host: string; count: number }[];
+  /** Every cap that was hit, named. Empty means nothing was cut. */
+  caps_hit: string[];
+}
+
+const MAX_DEPTH = 24;
+const MAX_KEYS = 200;
+const MAX_ITEMS = 50;
+const MAX_TUPLE = 40;
+const MAX_ANY_OF = 6;
+const MAX_REVEAL_CHARS = 120;
+export const MAX_BODY_BYTES = 8 * 1024 * 1024;
+export const MAX_REQUESTS = 400;
+export const MAX_FRAME_SHAPES = 60;
+const BODY_SETTLE_MS = 5_000;
+
+const isPlainObject = (v: Shape): v is { [k: string]: Shape } => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+function tryJson(s: string): { ok: true; value: unknown } | { ok: false } {
+  const t = s.trim();
+  if (!(t.startsWith('{') || t.startsWith('['))) return { ok: false };
+  try {
+    return { ok: true, value: JSON.parse(t) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/** Merge two shapes of the same position into one. Pure. */
+export function mergeShapes(a: Shape, b: Shape): Shape {
+  const ja = JSON.stringify(a);
+  if (ja === JSON.stringify(b)) return a;
+  if (typeof a === 'string' && typeof b === 'string' && a.startsWith('string(') && b.startsWith('string(')) return 'string';
+  if (isPlainObject(a) && isPlainObject(b) && !('anyOf' in a) && !('anyOf' in b)) {
+    const aArr = 'array' in a && 'item' in a;
+    const bArr = 'array' in b && 'item' in b;
+    if (aArr && bArr) {
+      return { array: a.array === b.array ? a.array! : 'varies', item: a.item === 'null' && b.item !== 'null' ? b.item! : mergeShapes(a.item!, b.item!) };
+    }
+    if (!aArr && !bArr && !('tuple' in a) && !('tuple' in b) && !('json' in a) && !('json' in b)) {
+      const out: { [k: string]: Shape } = {};
+      for (const k of new Set([...Object.keys(a), ...Object.keys(b)])) {
+        out[k] = k in a && k in b ? mergeShapes(a[k]!, b[k]!) : k in a ? `${flat(a[k]!)} | absent` : `${flat(b[k]!)} | absent`;
+      }
+      return out;
+    }
+  }
+  const alts = [...(isPlainObject(a) && Array.isArray(a.anyOf) ? a.anyOf : [a]), ...(isPlainObject(b) && Array.isArray(b.anyOf) ? b.anyOf : [b])];
+  const uniq: Shape[] = [];
+  for (const s of alts) if (!uniq.some((u) => JSON.stringify(u) === JSON.stringify(s))) uniq.push(s);
+  return uniq.length > MAX_ANY_OF ? { anyOf: [...uniq.slice(0, MAX_ANY_OF), `… ${uniq.length - MAX_ANY_OF} more`] } : { anyOf: uniq };
+}
+
+const flat = (s: Shape): string => (typeof s === 'string' ? s : 'object');
+
+/**
+ * The shape of a parsed JSON value. Strings keep only their length — unless their
+ * key is in `reveal` — and a string that is itself JSON gets its own shape (Google
+ * nests JSON inside JSON strings). Arrays whose items share a shape become
+ * {array, item}; mixed positional arrays (Google's tuples) become {array, tuple}.
+ */
+export function shapeOf(v: unknown, reveal: ReadonlySet<string> = new Set(), depth = 0, key?: string): Shape {
+  if (depth > MAX_DEPTH) return '…depth';
+  if (v === null) return 'null';
+  if (typeof v === 'number') return 'number';
+  if (typeof v === 'boolean') return 'boolean';
+  if (typeof v === 'string') {
+    if (key !== undefined && reveal.has(key) && v.length <= MAX_REVEAL_CHARS) return { value: v };
+    const j = tryJson(v);
+    if (j.ok) return { string: String(v.length), json: shapeOf(j.value, reveal, depth + 1) };
+    return `string(${v.length})`;
+  }
+  if (Array.isArray(v)) {
+    if (v.length === 0) return { array: '0', item: 'null' };
+    const items = v.slice(0, MAX_ITEMS).map((x) => shapeOf(x, reveal, depth + 1));
+    const allSame = items.every((s) => JSON.stringify(s) === JSON.stringify(items[0]));
+    const allObjects = items.every((s) => isPlainObject(s) && !('array' in s) && !('tuple' in s) && !('json' in s) && !('value' in s));
+    if (allSame || allObjects) return { array: String(v.length), item: items.reduce((m, s) => mergeShapes(m, s)) };
+    if (v.length <= MAX_TUPLE) return { array: String(v.length), tuple: items };
+    return { array: String(v.length), item: items.reduce((m, s) => mergeShapes(m, s)) };
+  }
+  if (typeof v === 'object') {
+    const out: { [k: string]: Shape } = {};
+    const keys = Object.keys(v as object);
+    for (const k of keys.slice(0, MAX_KEYS)) out[k] = shapeOf((v as Record<string, unknown>)[k], reveal, depth + 1, k);
+    if (keys.length > MAX_KEYS) out['…'] = `${keys.length - MAX_KEYS} more keys`;
+    return out;
+  }
+  return typeof v;
+}
+
+/** A single form/query value: JSON when it parses (tRPC `input`, Google `f.req`). */
+function shapeParam(k: string, v: string, reveal: ReadonlySet<string>): Shape {
+  if (reveal.has(k) && v.length <= MAX_REVEAL_CHARS) return { value: v };
+  const j = tryJson(v);
+  return j.ok ? { string: String(v.length), json: shapeOf(j.value, reveal) } : `string(${v.length})`;
+}
+
+export function shapeParams(params: URLSearchParams, reveal: ReadonlySet<string>): Record<string, Shape> {
+  const out: Record<string, Shape> = {};
+  for (const [k, v] of params) {
+    const s = shapeParam(k, v, reveal);
+    out[k] = k in out ? mergeShapes(out[k]!, s) : s;
+  }
+  return out;
+}
+
+const shapeList = (values: unknown[], reveal: ReadonlySet<string>): Shape => shapeOf(values, reveal);
+
+/**
+ * The shape of a body as it travels: JSON; Google's `)]}'` guard followed by
+ * length-prefixed chunks; text/event-stream `data:` lines; form-urlencoded;
+ * SignalR's \x1e-separated JSON messages. Anything else is its length only.
+ */
+export function shapeBody(text: string, contentType = '', reveal: ReadonlySet<string> = new Set()): Shape {
+  const ct = contentType.toLowerCase();
+  const t = text.trim();
+  if (t === '') return 'empty';
+  if (t.startsWith(")]}'")) {
+    const parsed: unknown[] = [];
+    let other = 0;
+    for (const line of t.slice(4).split('\n')) {
+      const l = line.trim();
+      if (!l || /^\d+$/.test(l)) continue;
+      const j = tryJson(l);
+      if (j.ok) parsed.push(j.value);
+      else other++;
+    }
+    return { format: 'google-chunked', chunks: String(parsed.length), ...(other ? { unparsed_lines: String(other) } : {}), shape: shapeList(parsed, reveal) };
+  }
+  if (ct.includes('event-stream') || /^(data|event|id|retry):/m.test(t.slice(0, 200))) {
+    const data: unknown[] = [];
+    const events: Record<string, number> = {};
+    let raw = 0;
+    for (const line of t.split('\n')) {
+      if (line.startsWith('event:')) {
+        const name = line.slice(6).trim().slice(0, 40);
+        events[name] = (events[name] ?? 0) + 1;
+      } else if (line.startsWith('data:')) {
+        const j = tryJson(line.slice(5));
+        if (j.ok) data.push(j.value);
+        else raw++;
+      }
+    }
+    return { format: 'sse', ...(Object.keys(events).length ? { events: Object.fromEntries(Object.entries(events).map(([k, n]) => [k, String(n)])) } : {}), ...(raw ? { non_json_data: String(raw) } : {}), shape: shapeList(data, reveal) };
+  }
+  if (t.includes('\x1e')) {
+    const msgs: unknown[] = [];
+    let other = 0;
+    for (const part of t.split('\x1e')) {
+      if (!part.trim()) continue;
+      const j = tryJson(part);
+      if (j.ok) msgs.push(j.value);
+      else other++;
+    }
+    return { format: 'signalr', messages: String(msgs.length), ...(other ? { unparsed: String(other) } : {}), shape: shapeList(msgs, reveal) };
+  }
+  const j = tryJson(t);
+  if (j.ok) return shapeOf(j.value, reveal);
+  if (ct.includes('x-www-form-urlencoded') || /^[\w.%-]+=[^\s]*(&[\w.%-]+=[^\s]*)*$/.test(t)) {
+    return { format: 'form', fields: shapeParams(new URLSearchParams(t), reveal) };
+  }
+  if (ct.includes('multipart')) return `multipart(${t.length})`;
+  return `text(${t.length})`;
+}
+
+function hostOf(u: string): string | null {
+  try {
+    const url = new URL(u);
+    return url.protocol === 'http:' || url.protocol === 'https:' || url.protocol === 'ws:' || url.protocol === 'wss:' ? url.host : null;
+  } catch {
+    return null;
+  }
+}
+
+const CALL_TYPES = new Set(['fetch', 'xhr', 'eventsource']);
+
+/**
+ * Attach to a flow's browser context. `finish()` waits (bounded) for bodies still
+ * being read and returns the report. Never throws into the run: an unreadable
+ * body is recorded as such.
+ */
+export function collectNetworkShapes(context: BrowserContext, opts: NetworkShapesOptions = {}) {
+  const reveal = new Set(opts.reveal ?? []);
+  const extraHosts = new Set(opts.hosts ?? []);
+  const pageHosts = new Set<string>();
+  const merged = new Map<string, ShapedRequest>();
+  const other = new Map<string, number>();
+  const sockets: ShapedSocket[] = [];
+  const caps = new Set<string>();
+  const pending: Promise<void>[] = [];
+
+  const inScope = (host: string, pageUrl: string | null): boolean => {
+    const ph = pageUrl ? hostOf(pageUrl) : null;
+    if (ph) pageHosts.add(ph);
+    return host === ph || extraHosts.has(host);
+  };
+  const pageUrlOf = (req: Request): string | null => {
+    try {
+      return req.frame().page().url();
+    } catch {
+      return null;
+    }
+  };
+  const countOther = (host: string): void => {
+    other.set(host, (other.get(host) ?? 0) + 1);
+  };
+
+  const onResponse = async (resp: Response): Promise<void> => {
+    const req = resp.request();
+    if (!CALL_TYPES.has(req.resourceType())) return;
+    const host = hostOf(req.url());
+    if (!host) return;
+    if (!inScope(host, pageUrlOf(req))) return countOther(host);
+    const u = new URL(req.url());
+    const headers = resp.headers();
+    const contentType = (headers['content-type'] ?? '').split(';')[0]!.trim();
+    const entry: ShapedRequest = { method: req.method(), url: `${u.origin}${u.pathname}`, status: resp.status(), content_type: contentType, count: 1 };
+    if (u.search) entry.query = shapeParams(u.searchParams, reveal);
+    const post = req.postData();
+    if (post !== null) entry.request_shape = post.length > MAX_BODY_BYTES ? `too large (${post.length} bytes, cap ${MAX_BODY_BYTES})` : shapeBody(post, req.headers()['content-type'] ?? '', reveal);
+    const len = Number(headers['content-length'] ?? NaN);
+    if (Number.isFinite(len) && len > MAX_BODY_BYTES) {
+      entry.response_shape = `too large (${len} bytes, cap ${MAX_BODY_BYTES})`;
+      caps.add(`response body > ${MAX_BODY_BYTES} bytes not read`);
+    } else {
+      try {
+        const body = await resp.text();
+        entry.response_shape = body.length > MAX_BODY_BYTES ? `too large (${body.length} chars)` : shapeBody(body, contentType, reveal);
+      } catch (err) {
+        entry.response_shape = `body not readable (${err instanceof Error ? err.message.split('\n')[0] : String(err)})`;
+      }
+    }
+    const { count: _c, ...rest } = entry;
+    const key = JSON.stringify(rest);
+    const seen = merged.get(key);
+    if (seen) seen.count++;
+    else if (merged.size >= MAX_REQUESTS) {
+      caps.add(`more than ${MAX_REQUESTS} distinct calls — the rest are counted under other_hosts as "<host> (over cap)"`);
+      countOther(`${host} (over cap)`);
+    } else merged.set(key, entry);
+  };
+
+  const addFrame = (fs: FrameShapes, payload: string | Buffer) => {
+    fs.frames++;
+    const shape: Shape = typeof payload === 'string' ? shapeBody(payload, '', reveal) : `binary(${payload.length})`;
+    const k = JSON.stringify(shape);
+    const hit = fs.shapes.find((s) => JSON.stringify(s.shape) === k);
+    if (hit) hit.count++;
+    else if (fs.shapes.length >= MAX_FRAME_SHAPES) caps.add(`more than ${MAX_FRAME_SHAPES} distinct frame shapes on one socket`);
+    else fs.shapes.push({ shape, count: 1 });
+  };
+  const onSocket = (page: Page) => (ws: WebSocket) => {
+    const host = hostOf(ws.url());
+    if (!host) return;
+    if (!inScope(host, page.url())) return countOther(host);
+    const u = new URL(ws.url());
+    const s: ShapedSocket = { url: `${u.protocol}//${u.host}${u.pathname}`, sent: { frames: 0, shapes: [] }, received: { frames: 0, shapes: [] } };
+    sockets.push(s);
+    ws.on('framesent', (f) => addFrame(s.sent, f.payload));
+    ws.on('framereceived', (f) => addFrame(s.received, f.payload));
+  };
+
+  const hooked = new WeakSet<Page>();
+  const hookPage = (p: Page) => {
+    if (hooked.has(p)) return;
+    hooked.add(p);
+    p.on('websocket', onSocket(p));
+  };
+  for (const p of context.pages()) hookPage(p);
+  context.on('page', hookPage);
+  context.on('response', (resp) => {
+    pending.push(onResponse(resp).catch(() => {}));
+  });
+
+  return {
+    async finish(): Promise<NetworkShapesReport> {
+      let timedOut = false;
+      await Promise.race([
+        Promise.allSettled(pending),
+        new Promise((r) => setTimeout(() => {
+          timedOut = true;
+          r(undefined);
+        }, BODY_SETTLE_MS)),
+      ]);
+      if (timedOut) caps.add(`some bodies were still being read after ${BODY_SETTLE_MS} ms and are missing`);
+      return {
+        page_hosts: [...pageHosts],
+        requests: [...merged.values()],
+        websockets: sockets,
+        other_hosts: [...other].map(([host, count]) => ({ host, count })).sort((a, b) => b.count - a.count),
+        caps_hit: [...caps],
+      };
+    },
+  };
+}

package/src/record-run.ts

@@ -85,6 +85,13 @@ export async function runRecord(raw: RecordRequest, deps: RecordDeps) {
     seed_tabs?: { session: string; channel?: string; label?: string }[];
   };
   if (!body.url) return { ok: false as const, status: 400, error: 'url required' };
+  // Both reach an ffmpeg filter string. 0 = no stills (burst), never a string.
+  for (const k of ['fps', 'burst_fps'] as const) {
+    const v = body[k];
+    if (v !== undefined && (typeof v !== 'number' || !Number.isFinite(v) || v < 0 || v > 120)) {
+      return { ok: false as const, status: 400, error: `${k} must be a number from 0 to 120` };
+    }
+  }
   const project = body.project ?? 'lens';
   try {
     let auth = body.auth as AuthConfig | undefined;
@@ -311,7 +318,8 @@ export async function runRecord(raw: RecordRequest, deps: RecordDeps) {
       const vid = nodePath.join(dir, 'run.webm');
       await writeFile(vid, result.video);
       const cuts: { t: number; file: string; near?: number }[] = [];
-      const sparse = await cutFrames(vid, nodePath.join(dir, 'sparse'), { fps: body.fps ?? 2 });
+      // fps 0 = no timeline stills (the documented off switch), not an ffmpeg call.
+      const sparse = body.fps === 0 ? { frames: [] } : await cutFrames(vid, nodePath.join(dir, 'sparse'), { fps: body.fps ?? 2 });
       if (sparse.unavailable) framesUnavailable = sparse.unavailable;
       cuts.push(...sparse.frames.map((f) => ({ t: f.t, file: f.file })));
       const burstFps = body.burst_fps ?? 12;

package/src/service.ts

@@ -675,6 +675,11 @@ function parseFindingsJson(raw: string | null | undefined, port?: number): Recor
     if (port !== undefined && Array.isArray(v.downloads)) {
       v.downloads = v.downloads.map(({ key, ...d }: { key?: string }) => (key ? { ...d, url: artifactUrl(port, key) } : d));
     }
+    // F009.133 — same for the network-shapes JSON.
+    if (port !== undefined && v.network_shapes && typeof v.network_shapes.key === 'string') {
+      const { key, ...rest } = v.network_shapes;
+      v.network_shapes = { ...rest, url: artifactUrl(port, key) };
+    }
     return v as Record<string, unknown>;
   } catch {
     return null;

package/src/storage.ts

@@ -18,7 +18,7 @@
 
 import { S3Client } from 'bun';
 import { mkdir, readFile, writeFile, rm } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, resolve, sep } from 'node:path';
 
 export interface LensStorage {
   readonly backend: 'local' | 'tigris';
@@ -31,8 +31,15 @@ class LocalDirStorage implements LensStorage {
   readonly backend = 'local' as const;
   constructor(private readonly root: string) {}
 
+  /** A key is a path INSIDE the store, never a way out of it (H2, 2026-10-21:
+   *  `../../.ssh/id_rsa` was served by /lens/artifact). */
   private path(key: string): string {
-    return join(this.root, key);
+    const root = resolve(this.root);
+    const p = resolve(root, key);
+    if (isAbsolute(key) || (p !== root && !p.startsWith(root + sep))) {
+      throw new Error(`lens storage: key escapes the artifact store: ${JSON.stringify(key)}`);
+    }
+    return p;
   }
 
   async put(key: string, bytes: Buffer): Promise<void> {
@@ -119,6 +126,8 @@ export const artifactKeys = {
   // F255.5 — the whole driven run as a video, alongside its step stills.
   flowVideo: (project: string, flowRunId: string) => `${project}/flows/${flowRunId}/run.webm`,
   // F009.128 — a file the run downloaded. Numbered so two files with one name both survive.
+  // F009.133 — the run's network shapes (one JSON per run).
+  flowNetworkShapes: (project: string, flowRunId: string) => `${project}/flows/${flowRunId}/network-shapes.json`,
   flowDownload: (project: string, flowRunId: string, n: number, name: string) =>
     `${project}/flows/${flowRunId}/download-${n}-${name.replace(/[^\w.-]+/g, '_').slice(0, 120)}`,
   // F074.63 — a vector export (PDF). Its own prefix, not runs/: an export is not