@crouton-kit/capture 1.3.7 → 1.3.8

package/src/output/selector.ts

@@ -0,0 +1,185 @@
+/**
+ * Selector helpers — map a query leaf's `--selector`/`--element` input
+ * string to the stored per-element records a snapshot's collector files
+ * carry. Pure lookups over an already-read array; this module never reads
+ * an artifact file itself (see `src/output/artifact.ts` for that).
+ *
+ * Contract this module fixes for upstream collector writers: any collector
+ * file that indexes elements (`geometry.json` first and foremost — see the
+ * contract note at the top of `artifact.ts`) should shape each element's
+ * record to satisfy {@link ElementRecord} — a stable `id`, and whichever of
+ * `selector`/`backendNodeId`/`axId`/`axName`/`text` it has facts for — so a
+ * query leaf's selector lookup works the same way regardless of which
+ * collector file it pulled the array from.
+ */
+
+// ============================================================================
+// Element records
+// ============================================================================
+
+export interface ElementRecord {
+  /** Stable per-snapshot element id (e.g. `el-14`) collectors key off of. */
+  readonly id: string;
+  /** The collector-computed CSS-ish selector string for this element
+   * (e.g. `.message-card:nth-child(4)`), when known. */
+  readonly selector?: string;
+  readonly backendNodeId?: number;
+  /** Accessibility node id, when the element has a non-ignored AX node. */
+  readonly axId?: string;
+  /** Accessibility computed name, when known. */
+  readonly axName?: string;
+  /** Text content associated with the element, when known. */
+  readonly text?: string;
+  readonly [key: string]: unknown;
+}
+
+// ============================================================================
+// Direct lookups
+// ============================================================================
+
+/** Elements whose stored `selector` exactly equals `selector`. */
+export function findBySelector(elements: readonly ElementRecord[], selector: string): ElementRecord[] {
+  return elements.filter((e) => e.selector === selector);
+}
+
+/** The element with this `backendNodeId`, if any. */
+export function findByBackendNodeId(elements: readonly ElementRecord[], backendNodeId: number): ElementRecord | undefined {
+  return elements.find((e) => e.backendNodeId === backendNodeId);
+}
+
+/** The element with this exact `axId`, if any. */
+export function findByAxId(elements: readonly ElementRecord[], axId: string): ElementRecord | undefined {
+  return elements.find((e) => e.axId === axId);
+}
+
+/** Elements whose `axName` matches `name` — exact (case-insensitive) by
+ * default, or a case-insensitive substring match with `{ exact: false }`. */
+export function findByAxName(
+  elements: readonly ElementRecord[],
+  name: string,
+  opts: { exact?: boolean } = {},
+): ElementRecord[] {
+  const exact = opts.exact ?? true;
+  const needle = name.toLowerCase();
+  return elements.filter((e) => {
+    if (e.axName === undefined) return false;
+    const hay = e.axName.toLowerCase();
+    return exact ? hay === needle : hay.includes(needle);
+  });
+}
+
+/** Elements whose `text` matches `needle` — case-insensitive substring by
+ * default, or an exact (case-insensitive) match with `{ exact: true }`. */
+export function findByText(
+  elements: readonly ElementRecord[],
+  needle: string,
+  opts: { exact?: boolean } = {},
+): ElementRecord[] {
+  const exact = opts.exact ?? false;
+  const target = needle.toLowerCase();
+  return elements.filter((e) => {
+    if (e.text === undefined) return false;
+    const hay = e.text.toLowerCase();
+    return exact ? hay === target : hay.includes(target);
+  });
+}
+
+// ============================================================================
+// Selector-input grammar
+// ============================================================================
+
+export type SelectorInputKind = 'backend' | 'axid' | 'ax' | 'text' | 'css';
+
+export interface ParsedSelectorInput {
+  readonly kind: SelectorInputKind;
+  readonly value: string;
+}
+
+/**
+ * Parses a `--selector`/`--element` input string into its lookup kind:
+ *  - `backend:1234` — backend node id
+ *  - `axid:<id>`    — accessibility node id
+ *  - `ax:<name>`    — accessibility name (substring)
+ *  - `text:<needle>`— text content (substring)
+ *  - anything else  — a CSS-ish selector, matched exactly against the
+ *    collector's stored `selector` string (the form every design sample
+ *    uses, e.g. `--selector ".toast-container"`)
+ */
+export function parseSelectorInput(input: string): ParsedSelectorInput {
+  const prefixes: Array<[string, SelectorInputKind]> = [
+    ['backend:', 'backend'],
+    ['axid:', 'axid'],
+    ['ax:', 'ax'],
+    ['text:', 'text'],
+  ];
+  for (const [prefix, kind] of prefixes) {
+    if (input.startsWith(prefix)) {
+      return { kind, value: input.slice(prefix.length) };
+    }
+  }
+  return { kind: 'css', value: input };
+}
+
+/**
+ * Resolves a `--selector`/`--element` input string to every matching
+ * element record, dispatching on {@link parseSelectorInput}'s grammar. This
+ * is the one entry point query leaves should call for user-supplied
+ * selector input rather than picking a `findBy*` helper themselves.
+ */
+export function resolveSelectorInput(elements: readonly ElementRecord[], input: string): ElementRecord[] {
+  const parsed = parseSelectorInput(input);
+  switch (parsed.kind) {
+    case 'backend': {
+      const id = Number(parsed.value);
+      if (!Number.isFinite(id)) return [];
+      const found = findByBackendNodeId(elements, id);
+      return found ? [found] : [];
+    }
+    case 'axid': {
+      const found = findByAxId(elements, parsed.value);
+      return found ? [found] : [];
+    }
+    case 'ax':
+      return findByAxName(elements, parsed.value, { exact: false });
+    case 'text':
+      return findByText(elements, parsed.value, { exact: false });
+    case 'css':
+      return findBySelector(elements, parsed.value);
+  }
+}
+
+// ============================================================================
+// Recovery hints
+// ============================================================================
+
+export interface SelectorHints {
+  readonly selectors: readonly string[];
+  readonly axNames: readonly string[];
+  readonly texts: readonly string[];
+}
+
+function uniqueTruncated(values: readonly (string | undefined)[], limit: number): string[] {
+  const seen = new Set<string>();
+  for (const v of values) {
+    if (v === undefined) continue;
+    seen.add(v);
+    if (seen.size >= limit) break;
+  }
+  return [...seen];
+}
+
+/**
+ * Example selector/AX-name/text values present in `elements`, for a query
+ * leaf to embed in a "missing selector" structured recovery error (per the
+ * design: "missing selector returns a structured recovery error listing
+ * available selector forms"). This module only gathers the raw examples —
+ * the calling leaf renders them through `src/output/render.ts`'s `data()`
+ * so untrusted DOM/AX/text content is escaped before it reaches output.
+ */
+export function selectorHints(elements: readonly ElementRecord[], limit = 10): SelectorHints {
+  return {
+    selectors: uniqueTruncated(elements.map((e) => e.selector), limit),
+    axNames: uniqueTruncated(elements.map((e) => e.axName), limit),
+    texts: uniqueTruncated(elements.map((e) => e.text), limit),
+  };
+}

package/src/session/artifacts.ts

@@ -0,0 +1,229 @@
+/**
+ * Secure artifact filesystem — the one place every session/oneshot artifact
+ * writer (screenshots, HAR, snapshot substrate, recordings) goes through.
+ *
+ * Contract: directories are created `0700`, files are created `0600`,
+ * writes are atomic (temp file + rename) and never follow a symlink planted
+ * at the destination, and every helper refuses to operate outside
+ * `CAPTURE_ROOT`. Downstream units (snapshot collectors, the recorder
+ * bridge, motion query leaves) write ALL artifacts through these helpers
+ * instead of ad-hoc `fs.writeFile`/`fs.mkdirSync`.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+/** The one canonical session/oneshot root. Every artifact lives under here. */
+export const CAPTURE_ROOT = path.join(os.tmpdir(), 'capture-sessions');
+
+/** Owner rwx only. */
+export const DIR_MODE = 0o700;
+/** Owner rw only. */
+export const FILE_MODE = 0o600;
+
+// ============================================================================
+// Meta.json contracts — the shape session stop() reads back out of
+// measure/snaps/*/meta.json and motion/recs/*/meta.json to build the bundle
+// manifest's `snaps`/`recs` arrays. Later units (U06 snapshot orchestrator,
+// U13/U14 recorder) write meta.json in this shape.
+// ============================================================================
+
+export interface SnapMeta {
+  id: string;
+  url: string | null;
+  viewport: string | null;
+  settled: boolean;
+  capturedAt: string;
+}
+
+export interface RecMeta {
+  id: string;
+  action: string | null;
+  frames: number;
+  durationMs: number;
+  state: string;
+}
+
+// ============================================================================
+// Path boundary
+// ============================================================================
+
+/**
+ * Resolves `targetPath` to an absolute path and throws unless it is
+ * strictly under `CAPTURE_ROOT`. Every write/cleanup helper below routes
+ * through this so a caller can never be tricked (or mistaken) into writing
+ * or deleting outside the capture artifact tree.
+ */
+export function assertUnderCaptureRoot(targetPath: string): string {
+  const resolved = path.resolve(targetPath);
+  const root = path.resolve(CAPTURE_ROOT);
+  const rel = path.relative(root, resolved);
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`artifact path escapes capture root ${root}: ${targetPath}`);
+  }
+  return resolved;
+}
+
+// ============================================================================
+// Directories
+// ============================================================================
+
+/** Creates (or re-secures) one path segment as a private, non-symlink dir. */
+function ensureSegmentPrivate(dirPath: string): void {
+  let st: fs.Stats;
+  try {
+    st = fs.lstatSync(dirPath);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+    fs.mkdirSync(dirPath, { mode: DIR_MODE });
+    // mkdir's mode is masked by umask; enforce explicitly.
+    fs.chmodSync(dirPath, DIR_MODE);
+    return;
+  }
+  if (st.isSymbolicLink()) {
+    throw new Error(`refusing to use a symlinked artifact directory: ${dirPath}`);
+  }
+  if (!st.isDirectory()) {
+    throw new Error(`artifact path exists and is not a directory: ${dirPath}`);
+  }
+  fs.chmodSync(dirPath, DIR_MODE);
+}
+
+/**
+ * Ensures `dirPath` and every missing ancestor up to (and including)
+ * `CAPTURE_ROOT` exist as private (`0700`), non-symlink directories.
+ * Existing directories in the chain are re-chmod'd to `0700` rather than
+ * trusted. Returns the resolved absolute path. Throws if `dirPath` is not
+ * under `CAPTURE_ROOT`, or if any path segment is a symlink or a
+ * non-directory.
+ */
+export function ensurePrivateDir(dirPath: string): string {
+  const resolved = assertUnderCaptureRoot(dirPath);
+  const root = path.resolve(CAPTURE_ROOT);
+
+  ensureSegmentPrivate(root);
+  const rel = path.relative(root, resolved);
+  let current = root;
+  for (const part of rel.split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    ensureSegmentPrivate(current);
+  }
+  return resolved;
+}
+
+// ============================================================================
+// Atomic, no-symlink-follow writes
+// ============================================================================
+
+function refuseExistingSymlink(resolved: string): void {
+  try {
+    const st = fs.lstatSync(resolved);
+    if (st.isSymbolicLink()) {
+      throw new Error(`refusing to write through a symlink: ${resolved}`);
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+  }
+}
+
+/**
+ * Writes `data` to `filePath` as a private (`0600`) file, atomically:
+ * writes to a uniquely-named temp file in the same directory (opened with
+ * `O_NOFOLLOW`, so a pre-planted symlink at the temp name can't be written
+ * through) and renames it over the destination. `rename(2)` replaces
+ * whatever is at the destination — including a symlink — without ever
+ * following it, so a symlink swapped in at `filePath` between calls is
+ * unlinked, never written through. Ensures the parent directory exists
+ * (and is private) first. This is the one primitive every other write
+ * helper in this module is built on.
+ */
+export function writePrivateFile(filePath: string, data: string | Buffer): void {
+  const resolved = assertUnderCaptureRoot(filePath);
+  const dir = path.dirname(resolved);
+  ensurePrivateDir(dir);
+  refuseExistingSymlink(resolved);
+
+  const tmpPath = path.join(dir, `.${path.basename(resolved)}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`);
+  const fd = fs.openSync(
+    tmpPath,
+    fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW,
+    FILE_MODE,
+  );
+  try {
+    fs.writeSync(fd, data);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.chmodSync(tmpPath, FILE_MODE);
+  fs.renameSync(tmpPath, resolved);
+}
+
+/** Writes `value` as pretty-printed JSON through {@link writePrivateFile}. */
+export function writeJsonPrivate(filePath: string, value: unknown): void {
+  writePrivateFile(filePath, JSON.stringify(value, null, 2));
+}
+
+/**
+ * Writes `records` as a complete newline-delimited JSON file (one JSON
+ * value per line), replacing any existing content atomically. For
+ * incremental line-at-a-time appends (e.g. a live recorder streaming
+ * frames/events), use {@link appendNdjsonPrivate} instead.
+ */
+export function writeNdjsonPrivate(filePath: string, records: unknown[]): void {
+  const body = records.map((record) => JSON.stringify(record)).join('\n') + (records.length ? '\n' : '');
+  writePrivateFile(filePath, body);
+}
+
+/**
+ * Appends one record as a single NDJSON line to `filePath`, creating it
+ * (private, `0600`) if absent. Not atomic across the whole file the way
+ * {@link writePrivateFile} is — it's the incremental-write counterpart used
+ * while a recording is live — but still refuses to append through a
+ * symlink and enforces the private mode on every call.
+ */
+export function appendNdjsonPrivate(filePath: string, record: unknown): void {
+  const resolved = assertUnderCaptureRoot(filePath);
+  const dir = path.dirname(resolved);
+  ensurePrivateDir(dir);
+  refuseExistingSymlink(resolved);
+
+  const line = JSON.stringify(record) + '\n';
+  const fd = fs.openSync(
+    resolved,
+    fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND | fs.constants.O_NOFOLLOW,
+    FILE_MODE,
+  );
+  try {
+    fs.writeSync(fd, line);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.chmodSync(resolved, FILE_MODE);
+}
+
+/**
+ * Writes binary artifact data (PNG crops, `video.webm`, ...) through
+ * {@link writePrivateFile}. A distinct named export for call-site clarity;
+ * behavior is identical to passing a `Buffer` to `writePrivateFile`.
+ */
+export function writeBinaryPrivate(filePath: string, data: Buffer): void {
+  writePrivateFile(filePath, data);
+}
+
+// ============================================================================
+// Cleanup
+// ============================================================================
+
+/**
+ * Recursively removes the artifact tree at `targetPath` (a one-shot
+ * session dir, an active session's `measure/snaps/{id}`, a
+ * `motion/recs/{id}`, ...). Refuses any path that is not strictly under
+ * `CAPTURE_ROOT` (including `CAPTURE_ROOT` itself). If `targetPath` is
+ * itself a symlink, only the symlink is unlinked — its target is never
+ * traversed or deleted.
+ */
+export function removeArtifactTree(targetPath: string): void {
+  const resolved = assertUnderCaptureRoot(targetPath);
+  fs.rmSync(resolved, { recursive: true, force: true });
+}

package/src/session/commands.ts

@@ -1,6 +1,5 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import * as os from 'os';
 import { spawn } from 'child_process';
 import {
   createHarRecording,
@@ -14,8 +13,14 @@ import {
 } from '../session-context.js';
 import { expandEqualsFlags } from '../cdp/args.js';
 import { startBridge, stopBridge } from '../cdp/bridge/spawn.js';
-
-const CAPTURE_ROOT = path.join(os.tmpdir(), 'capture-sessions');
+import {
+  CAPTURE_ROOT,
+  FILE_MODE,
+  ensurePrivateDir,
+  writeJsonPrivate,
+  type SnapMeta,
+  type RecMeta,
+} from './artifacts.js';
 
 interface LogPid {
   pid: number;
@@ -48,12 +53,90 @@ interface BundleManifest {
   a11y: Array<{ name: string; path: string }>;
   logs: Array<{ name: string; path: string; lines: number }>;
   other: Array<{ name: string; path: string }>;
+  /** `measure snap` artifacts collected from `measure/snaps/{id}/meta.json`. */
+  snaps: Array<{ id: string; path: string; url: string | null; viewport: string | null; settled: boolean; capturedAt: string }>;
+  /** `motion rec` artifacts collected from `motion/recs/{id}/meta.json`. */
+  recs: Array<{ id: string; path: string; action: string | null; frames: number; durationMs: number; state: string }>;
 }
 
 function sessionDir(id: string): string {
   return path.join(CAPTURE_ROOT, id);
 }
 
+/** One-shot artifact session outside an active session — see `createOneshotSession`. */
+export interface OneshotSession {
+  /** `oneshot-{id}`; also the dir name under `CAPTURE_ROOT`. */
+  id: string;
+  /** `{CAPTURE_ROOT}/oneshot-{id}` */
+  dir: string;
+  kind: 'measure' | 'motion';
+  /** `{dir}/measure/snaps` or `{dir}/motion/recs`, already created private. */
+  artifactsDir: string;
+}
+
+/**
+ * Creates the ephemeral artifact dir a URL-target `measure`/`motion` leaf
+ * writes into when there is no active session: `oneshot-{id}/measure/snaps`
+ * or `oneshot-{id}/motion/recs` under `CAPTURE_ROOT`. Holds only the one
+ * subtree the caller needs — no HAR, no held bridge, no `.session.json` —
+ * and is never registered as the active session. It is not bundled/torn
+ * down by `session stop`; it accumulates under `/tmp` the same as any other
+ * session dir until the OS reaps `/tmp`.
+ */
+export function createOneshotSession(kind: 'measure' | 'motion'): OneshotSession {
+  const id = `oneshot-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const dir = sessionDir(id);
+  const artifactsDir = kind === 'measure'
+    ? path.join(dir, 'measure', 'snaps')
+    : path.join(dir, 'motion', 'recs');
+  ensurePrivateDir(artifactsDir);
+  return { id, dir, kind, artifactsDir };
+}
+
+/** Reads one `measure/snaps/{id}/meta.json` and shapes it into a manifest `snaps[]` entry. */
+function readSnapMeta(snapDir: string, fallbackId: string): BundleManifest['snaps'][number] {
+  const meta = JSON.parse(fs.readFileSync(path.join(snapDir, 'meta.json'), 'utf-8')) as Partial<SnapMeta>;
+  return {
+    id: meta.id ?? fallbackId,
+    path: snapDir,
+    url: meta.url ?? null,
+    viewport: meta.viewport ?? null,
+    settled: meta.settled ?? false,
+    capturedAt: meta.capturedAt ?? '',
+  };
+}
+
+/** Reads one `motion/recs/{id}/meta.json` and shapes it into a manifest `recs[]` entry. */
+function readRecMeta(recDir: string, fallbackId: string): BundleManifest['recs'][number] {
+  const meta = JSON.parse(fs.readFileSync(path.join(recDir, 'meta.json'), 'utf-8')) as Partial<RecMeta>;
+  return {
+    id: meta.id ?? fallbackId,
+    path: recDir,
+    action: meta.action ?? null,
+    frames: meta.frames ?? 0,
+    durationMs: meta.durationMs ?? 0,
+    state: meta.state ?? 'unknown',
+  };
+}
+
+/** Collects finalized snapshots under `{session.dir}/measure/snaps/{id}/meta.json`. */
+function collectSnaps(dir: string): BundleManifest['snaps'] {
+  const snapsRoot = path.join(dir, 'measure', 'snaps');
+  if (!fs.existsSync(snapsRoot)) return [];
+  return fs.readdirSync(snapsRoot)
+    .filter((name) => fs.existsSync(path.join(snapsRoot, name, 'meta.json')))
+    .map((name) => readSnapMeta(path.join(snapsRoot, name), name));
+}
+
+/** Collects finalized recordings under `{session.dir}/motion/recs/{id}/meta.json`. */
+function collectRecs(dir: string): BundleManifest['recs'] {
+  const recsRoot = path.join(dir, 'motion', 'recs');
+  if (!fs.existsSync(recsRoot)) return [];
+  return fs.readdirSync(recsRoot)
+    .filter((name) => fs.existsSync(path.join(recsRoot, name, 'meta.json')))
+    .map((name) => readRecMeta(path.join(recsRoot, name), name));
+}
+
 function sessionMetaPath(id: string): string {
   return path.join(sessionDir(id), '.session.json');
 }
@@ -98,7 +181,8 @@ Sub-commands:
                                    --hold keeps one CDP browser connection open for the session
   stop  <session-id>              Finalize and bundle artifacts (screenshots, HAR, a11y, logs)
   list                            List active and stopped sessions
-  view  <id> [--filter section]   View bundle manifest; section = screenshots|har|a11y|logs
+  view  <id> [--filter section]   View bundle manifest; section = screenshots|har|a11y|logs|measure|motion
+                                   measure -> manifest.snaps, motion -> manifest.recs
 
 Why sessions: once started, every subsequent capture command auto-fills
 --target (the tab) and --har (the recording). No manual flag threading.
@@ -149,8 +233,8 @@ async function start(rawArgs: string[]): Promise<void> {
 
   const id = generateId();
   const dir = sessionDir(id);
-  fs.mkdirSync(path.join(dir, 'shots'), { recursive: true });
-  fs.mkdirSync(path.join(dir, 'a11y'), { recursive: true });
+  ensurePrivateDir(path.join(dir, 'shots'));
+  ensurePrivateDir(path.join(dir, 'a11y'));
 
   // Start HAR recording directly
   let harId: string | null = null;
@@ -246,7 +330,7 @@ async function start(rawArgs: string[]): Promise<void> {
     bridgeSocket,
     bridgePid,
   };
-  fs.writeFileSync(sessionMetaPath(id), JSON.stringify(session, null, 2));
+  writeJsonPrivate(sessionMetaPath(id), session);
 
   // Set as active session for auto-defaults
   setActiveSession({
@@ -322,10 +406,11 @@ export function logCommand(rawArgs: string[]): void {
   name = name ?? path.basename(resolved, path.extname(resolved));
 
   const logsDir = path.join(session.dir, 'logs');
-  fs.mkdirSync(logsDir, { recursive: true });
+  ensurePrivateDir(logsDir);
 
   const destPath = path.join(logsDir, `${name}.log`);
-  const outFd = fs.openSync(destPath, 'a');
+  const outFd = fs.openSync(destPath, 'a', FILE_MODE);
+  fs.chmodSync(destPath, FILE_MODE);
 
   const child = spawn(
     'sh',
@@ -337,7 +422,7 @@ export function logCommand(rawArgs: string[]): void {
 
   const pid = child.pid!;
   session.logPids.push({ pid, name, sourcePath: resolved });
-  fs.writeFileSync(sessionMetaPath(session.id), JSON.stringify(session, null, 2));
+  writeJsonPrivate(sessionMetaPath(session.id), session);
 
   console.log(JSON.stringify({ name, sourcePath: resolved, destPath, pid }, null, 2));
 }
@@ -391,7 +476,7 @@ async function stop(args: string[]): Promise<void> {
       const harData = readHarRecording(session.harId);
       if (harData) {
         const harPath = path.join(session.dir, 'har.json');
-        fs.writeFileSync(harPath, JSON.stringify(harData, null, 2));
+        writeJsonPrivate(harPath, harData);
         har = { id: session.harId, path: harPath, entryCount: harData.log.entries.length };
         // Clean up the HAR recording
         try { deleteHarRecording(session.harId); } catch { /* best effort */ }
@@ -414,8 +499,12 @@ async function stop(args: string[]): Promise<void> {
         })
     : [];
 
+  // Collect measure snapshots and motion recordings
+  const snaps = collectSnaps(session.dir);
+  const recs = collectRecs(session.dir);
+
   // Collect anything else dropped in the session dir
-  const knownDirs = new Set(['shots', 'a11y', 'logs']);
+  const knownDirs = new Set(['shots', 'a11y', 'logs', 'measure', 'motion']);
   const knownFiles = new Set(['.session.json', 'har.json', 'bundle.json', 'bridge.sock']);
   const other = fs.readdirSync(session.dir)
     .filter((f) => !knownDirs.has(f) && !knownFiles.has(f))
@@ -435,10 +524,12 @@ async function stop(args: string[]): Promise<void> {
     a11y,
     logs,
     other,
+    snaps,
+    recs,
   };
 
   const bundlePath = path.join(session.dir, 'bundle.json');
-  fs.writeFileSync(bundlePath, JSON.stringify(manifest, null, 2));
+  writeJsonPrivate(bundlePath, manifest);
 
   console.log(JSON.stringify({
     bundlePath,
@@ -449,6 +540,8 @@ async function stop(args: string[]): Promise<void> {
       a11ySnapshots: a11y.length,
       logFiles: logs.length,
       otherFiles: other.length,
+      snaps: snaps.length,
+      recs: recs.length,
     },
   }, null, 2));
 
@@ -473,11 +566,21 @@ function list(): void {
   console.log(JSON.stringify(sessions, null, 2));
 }
 
+// `session view --filter <name>` reads a manifest section by the same key
+// name for most sections (screenshots|har|a11y|logs|other), but `measure`
+// and `motion` are the query-facing filter names for the `snaps`/`recs`
+// manifest keys (matching the `measure`/`motion` command branches, not the
+// artifact-file naming), so they need an explicit alias.
+const VIEW_FILTER_ALIASES: Record<string, keyof BundleManifest> = {
+  measure: 'snaps',
+  motion: 'recs',
+};
+
 function view(rawArgs: string[]): void {
   const args = expandEqualsFlags(rawArgs);
   const id = args[0];
   if (!id) {
-    console.error('Usage: capture session view <session-id> [--filter screenshots|har|a11y]');
+    console.error('Usage: capture session view <session-id> [--filter screenshots|har|a11y|logs|other|measure|motion]');
     process.exit(1);
   }
 
@@ -493,7 +596,8 @@ function view(rawArgs: string[]): void {
 
   const filter = args.find((_, i) => args[i - 1] === '--filter');
   if (filter) {
-    const section = manifest[filter as keyof BundleManifest];
+    const key = VIEW_FILTER_ALIASES[filter] ?? (filter as keyof BundleManifest);
+    const section = manifest[key];
     console.log(JSON.stringify(section, null, 2));
   } else {
     console.log(JSON.stringify(manifest, null, 2));