@crouton-kit/capture 1.4.12 → 1.4.14

package/README.md

@@ -46,7 +46,7 @@ Both still do things capture does not. Playwright MCP is cross-browser — the s
 
 ## See it
 
-Eight short clips. Every overlay is real: the text is extracted from the command's actual stdout, the boxes are drawn at the coordinates the command printed, and the inset images are files a command actually wrote.
+Eleven short clips. Every overlay is real: the text is extracted from the command's actual stdout, the boxes are drawn at the coordinates the command printed, and the inset images are files a command actually wrote.
 
 Each player below contains the full clip. Use its controls to play, pause, scrub, or fullscreen.
 
@@ -118,6 +118,30 @@ No storage-state dance and no separate automation profile. Attach over `--port`,
 
 `capture session start --target <tab-id> --port 9860` · [full clip, 30s](demo/8-live-session.mp4)
 
+### 9. The cards paint first. Then one image moves them 400 pixels.
+
+<video src="https://github.com/user-attachments/assets/3257f961-a9b4-4e20-b23e-4da86622ae31" controls muted playsinline></video>
+
+Record the load once, then ask it different questions. `perf vitals` reads the largest paint off the trace — nearly all of it one image's load, named by element and URL — and lists the shifts that image caused. `perf insights` returns the element each shift moved, with the rectangle it was in before and after: `old_rect [28,99,1224,174]` → `new_rect [28,499,1224,174]`. Then `measure explain` measures that same element on the settled page and prints `x=28 y=499.75 w=1224 h=172.64`. The trace engine and the DOM agree on where the KPI row ended up.
+
+`capture perf insights <trace> --name CLSCulprits --full` · [full clip, 24s](demo/9-perf-vitals.mp4)
+
+### 10. The panels are closed. The browser is still holding all five.
+
+<video src="https://github.com/user-attachments/assets/20cccb4d-9715-4dfc-a5ec-60772b2e26e9" controls muted playsinline></video>
+
+A console opens and closes five session panels. The deck ends empty and the page reports zero open — but two heap snapshots disagree. `heap diff` lists ten detached nodes still reachable and names each one by the constructor that built it: `<div class="panel" id="session-1">`. `heap census` puts 1,049,008 retained bytes behind one of them, and `heap retainers` walks the edge keeping it alive — a `ClosedSession` object holding the panel on its `element` property.
+
+`capture heap retainers <snap> --node <node-id>` · [full clip, 24s](demo/10-heap-detached.mp4)
+
+### 11. The API never answered. The dashboard didn't change by one pixel.
+
+<video src="https://github.com/user-attachments/assets/bb29c58d-c9bb-4640-8756-d649925499d3" controls muted playsinline></video>
+
+The agent reads `$518.40` off a revenue dashboard, installs one rule document that fails the metrics API, and reloads. The skeletons shimmer, the cards fill, and the page shows `$518.40` again. `measure diff --pixels` reports **0 changed pixels across 1280×800**, while the HAR for that one URL carries both loads side by side: `200 · 56 bytes`, then `response incomplete: failed`. Mocking the route is the setup. The measurement is what shows the failure left nothing on screen to see.
+
+`capture tab mock start --rules <rules.json>` · [full clip, 26s](demo/11-mock-silent-failure.mp4)
+
 ## Quick start
 
 Needs Node and a Chrome. `capture tab launch` starts a headless browser that capture owns and reaps — it looks for `$CAPTURE_BROWSER`, then a `~/.cache/puppeteer` Chrome, then a system Chrome. If a CDP-enabled browser is already running, capture can attach to that instead.

package/bin/capture

@@ -10512,7 +10512,7 @@ function validateHarAppendBatch(value, source) {
   return { entries, incompleteLifecycles };
 }
 function captureVersion() {
-  const version = "1.4.12";
+  const version = "1.4.14";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function token() {
@@ -12614,7 +12614,7 @@ function wallTime(value) {
   }
 }
 function captureVersion2() {
-  const version = "1.4.12";
+  const version = "1.4.14";
   return typeof version === "string" && version.length > 0 ? version : "development";
 }
 function deepFreeze(value) {
@@ -16091,7 +16091,7 @@ var init_commands = __esm({
     };
     SESSION_TAB_ATTACH_TIMEOUT_MS = 5e3;
     COMMAND_BLOCK = `<command name="session">
-the artifact container \u2014 a session records HAR and bundles every artifact; it may open or adopt a tab, and once it has one, every command auto-targets it
+the work's evidence bundle \u2014 \`start\` opens or adopts a tab, records its network traffic (HAR) and external logs, and collects every artifact into one directory; while running, every command auto-targets its tab
 use when collecting or reading the traffic, logs, and artifacts of scoped work against one page
 </command>`;
     START_USAGE = `capture session start [--url <url> | --target <tab-id>] [--hold] [--port <n>] [--artifact-dir <path>] \u2014 open or adopt a tab, record HAR, and set the active capture context.
@@ -230686,7 +230686,7 @@ var init_tab = __esm({
     init_network();
     init_mock();
     COMMAND_BLOCK3 = `<command name="tab">
-browser and tab plumbing \u2014 the existence of a browser capture owns, endpoint/tab discovery, tab lifecycle, and the conditions the tab's network runs under (connectivity, mocked responses)
+browser and tab plumbing \u2014 launch or quit a browser capture owns, discover endpoints and tabs, open/close/reset tabs, and set the tab's network conditions (throttling, offline, mocked responses)
 use when starting, finding, opening, closing, or resetting a browser tab, or changing its network conditions
 </command>`;
     TAB_USAGE = `<command name="tab" description="browser and tab lifecycle">
@@ -243961,8 +243961,8 @@ var init_measure = __esm({
     init_map_ax2();
     init_map_paint();
     COMMAND_BLOCK6 = `<command name="measure">
-the settled-snapshot substrate \u2014 static facts at one moment; \`snap\` writes the substrate, every other leaf is a read-only query over it
-use for static rendered-page facts from a settled snapshot: layout, content, cascade provenance, targetability, and snapshot diffs
+static page measurement \u2014 \`snap\` waits for the page to settle, then records its layout, styles, text, and accessibility into one artifact; every other leaf answers questions from that artifact without re-driving the browser
+use when a claim depends on what is rendered right now: element geometry, overflow, clipping, stacking, computed style and where it came from, text and contrast, focus order, scroll containers, paint coverage, or the difference between two snapshots
 </command>`;
     MEASURE_USAGE = `<command name="measure" description="enriched snapshot substrate and read-only queries">
 <model>\`snap\` drives the page (or a base snapshot) and writes one settled artifact directory; every other leaf below reads that artifact and never re-drives the browser unless its target is a URL, which first creates a snapshot. Findings exit 0 \u2014 a report, not a failure. \`--gate\` (exit 2 on findings or changes) is accepted only by check and diff.</model>
@@ -245996,8 +245996,8 @@ var init_motion2 = __esm({
     init_jank2();
     init_response2();
     COMMAND_BLOCK7 = `<command name="motion">
-the screencast-recording substrate \u2014 what changed on screen across frames; \`rec\` writes the recording, every other leaf is a read-only query over it
-use for per-element frame geometry, changed regions, and input-to-settle timing; use \`perf\` instead for trace-event timing
+screen recording \u2014 \`rec\` screencasts the tab through an interaction; every other leaf answers what moved, where, and how long it took from that recording's frames
+use when a claim depends on change over time: element motion across frames, which screen regions changed, layout shifts and long tasks, or the time from an input to a settled screen; for trace-event timing use \`perf\` instead
 </command>`;
     MOTION_USAGE = `<command name="motion" description="recording lifecycle and read-only queries over a finalized recording">
 <model>\`rec\` drives and records the browser, one-shot or composed across intervening commands; every other leaf below reads the finalized recording artifact. Findings exit 0 \u2014 a report, not a failure; input and precondition errors exit 1. No leaf accepts --gate.</model>
@@ -265772,8 +265772,8 @@ var init_perf = __esm({
     init_vitals();
     init_insights2();
     COMMAND_BLOCK8 = `<command name="perf">
-the Chrome performance-trace substrate \u2014 \`trace\` records one, \`vitals\` and \`insights\` are read-only queries over it
-use for Core Web Vitals and DevTools insights over a page load or one interaction, timed from trace events
+Chrome performance tracing \u2014 \`trace\` records a DevTools performance trace over a page load or an interaction; \`vitals\` and \`insights\` read it back without re-running anything
+use when a claim depends on runtime performance: LCP, INP, and CLS with attribution, or DevTools' computed insights such as render-blocking requests, forced reflow, and layout-shift culprits
 </command>`;
     HELP7 = `<command name="perf" description="the Chrome performance-trace substrate">
 <model>\`trace\` drives (and records) the browser, one-shot or composed across intervening commands; the other leaves are cheap reads over the finalized trace artifact. Findings exit 0 \u2014 a report, not a failure; input/precondition errors exit 1. No leaf accepts --gate.</model>
@@ -266726,8 +266726,8 @@ var init_heap2 = __esm({
     init_retainers();
     init_diff4();
     COMMAND_BLOCK9 = `<command name="heap">
-the tab's JavaScript heap \u2014 \`snapshot\` records the heap as a V8 snapshot, every other leaf is a read-only graph query over it
-use for JavaScript-heap retention: constructor totals, retained sizes, retaining paths, duplicate strings, and before/after comparison
+JavaScript memory \u2014 \`snapshot\` writes the tab's V8 heap snapshot; every other leaf queries that object graph without touching the browser
+use when a claim depends on memory: what the heap holds per constructor, which objects exist, what keeps one alive, duplicated strings, or what grew between two snapshots when hunting a leak
 </command>`;
     HELP13 = `<command name="heap" description="the V8 heap-snapshot substrate">
 <model>\`snapshot\` drives the browser; every other leaf is a read of the finalized snapshot artifact and never touches Chrome. Retained sizes are dominator-subtree sums of Chrome's own self_size. Findings exit 0; input/precondition errors exit 1. No leaf accepts --gate.</model>
@@ -267060,7 +267060,7 @@ var init_lighthouse = __esm({
     init_lifecycle();
     init_render();
     COMMAND_BLOCK10 = `<command name="lighthouse">
-a third-party scored diagnostic report \u2014 capture runs Lighthouse against a URL and stores its report unmodified
+Google Lighthouse audits \u2014 capture runs Lighthouse against a URL and stores its scored report unmodified
 use for one Lighthouse report's audited accessibility, SEO, performance, or best-practices conditions, categories, scores, and audits
 </command>`;
     HELP14 = `capture lighthouse <url> [--categories <list>] [--preset mobile|desktop] [--limit <N>] [--out <path>] \u2014 run Lighthouse's third-party scored diagnostic sweep against a URL and store its report
@@ -267289,14 +267289,14 @@ function rootHelp() {
 
 ${ROOT_BLOCKS.join("\n\n")}
 
-Selecting a noun: session, page, and tab address the live browser context; measure, motion, perf, and heap each own a distinct recorded substrate; lighthouse, cdp, and lib are respectively third-party audit, raw protocol, and local-library surfaces. Use a substrate noun when its recorded artifact is the source of the facts you need.
+Selecting a noun: session, page, and tab address the live browser; measure, motion, perf, and heap each record once and then answer many questions from that recording \u2014 a settled snapshot, a screencast, a performance trace, a heap snapshot; lighthouse, cdp, and lib are third-party audit, raw protocol, and local-library surfaces. Record with the noun whose artifact holds the facts you need, then query it.
 
 I/O contract: flags and positionals on input; one rendered prose block on stdout. --json mirrors the same result as JSON, but the rendered block is the contract. stderr carries in-flight diagnostics only. --artifact-dir <path> selects the root for a session bundle (\`session start\`) or a sessionless artifact-producing leaf's one-shot bundle; leaf help states when it writes one. --out always names one caller-owned file, never a bundle directory.
 
 A CDP-enabled browser must be running; \`capture tab list\` is the probe, and \`capture tab launch\` starts one capture owns and reaps when nothing is (never hand-roll a detached browser \u2014 nothing reaps that). Capture never signals a browser it did not start, so attaching to your own with --port is unchanged. CDP_PORT / CDP_TARGET pin the browser + tab for target-selecting commands \u2014 precedence: explicit flag > active session > env. \`session start\` adopts only an explicit --target.`;
 }
 function printVersion() {
-  const declared = "1.4.12";
+  const declared = "1.4.14";
   if (declared) {
     console.log(declared);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.4.12",
+  "version": "1.4.14",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"

package/src/capture.ts

@@ -61,7 +61,7 @@ function rootHelp(): string {
 
 ${ROOT_BLOCKS.join('\n\n')}
 
-Selecting a noun: session, page, and tab address the live browser context; measure, motion, perf, and heap each own a distinct recorded substrate; lighthouse, cdp, and lib are respectively third-party audit, raw protocol, and local-library surfaces. Use a substrate noun when its recorded artifact is the source of the facts you need.
+Selecting a noun: session, page, and tab address the live browser; measure, motion, perf, and heap each record once and then answer many questions from that recording — a settled snapshot, a screencast, a performance trace, a heap snapshot; lighthouse, cdp, and lib are third-party audit, raw protocol, and local-library surfaces. Record with the noun whose artifact holds the facts you need, then query it.
 
 I/O contract: flags and positionals on input; one rendered prose block on stdout. --json mirrors the same result as JSON, but the rendered block is the contract. stderr carries in-flight diagnostics only. --artifact-dir <path> selects the root for a session bundle (\`session start\`) or a sessionless artifact-producing leaf's one-shot bundle; leaf help states when it writes one. --out always names one caller-owned file, never a bundle directory.
 

package/src/cdp/commands/heap/index.ts

@@ -7,8 +7,8 @@ import { cmdHeapRetainers } from './retainers.js';
 import { cmdHeapDiff } from './diff.js';
 
 export const COMMAND_BLOCK = `<command name="heap">
-the tab's JavaScript heap — \`snapshot\` records the heap as a V8 snapshot, every other leaf is a read-only graph query over it
-use for JavaScript-heap retention: constructor totals, retained sizes, retaining paths, duplicate strings, and before/after comparison
+JavaScript memory — \`snapshot\` writes the tab's V8 heap snapshot; every other leaf queries that object graph without touching the browser
+use when a claim depends on memory: what the heap holds per constructor, which objects exist, what keeps one alive, duplicated strings, or what grew between two snapshots when hunting a leak
 </command>`;
 
 const HELP = `<command name="heap" description="the V8 heap-snapshot substrate">

package/src/cdp/commands/lighthouse.ts

@@ -16,7 +16,7 @@ import { stopAndReapCollectorHostAtSessionStop } from '../host/lifecycle.js';
 import { capped, emitResult, fact, formatArtifactList, line, lineList, text, type FactLine, type JsonValue, type RenderableResult } from '../../output/render.js';
 
 export const COMMAND_BLOCK = `<command name="lighthouse">
-a third-party scored diagnostic report — capture runs Lighthouse against a URL and stores its report unmodified
+Google Lighthouse audits — capture runs Lighthouse against a URL and stores its scored report unmodified
 use for one Lighthouse report's audited accessibility, SEO, performance, or best-practices conditions, categories, scores, and audits
 </command>`;
 

package/src/cdp/commands/measure/index.ts

@@ -24,8 +24,8 @@ import { cmdMeasureMapPaint } from './map-paint.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="measure">
-the settled-snapshot substrate — static facts at one moment; \`snap\` writes the substrate, every other leaf is a read-only query over it
-use for static rendered-page facts from a settled snapshot: layout, content, cascade provenance, targetability, and snapshot diffs
+static page measurement — \`snap\` waits for the page to settle, then records its layout, styles, text, and accessibility into one artifact; every other leaf answers questions from that artifact without re-driving the browser
+use when a claim depends on what is rendered right now: element geometry, overflow, clipping, stacking, computed style and where it came from, text and contrast, focus order, scroll containers, paint coverage, or the difference between two snapshots
 </command>`;
 
 export const MEASURE_USAGE = `<command name="measure" description="enriched snapshot substrate and read-only queries">

package/src/cdp/commands/motion/index.ts

@@ -16,8 +16,8 @@ import { cmdMotionResponse } from './response.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="motion">
-the screencast-recording substrate — what changed on screen across frames; \`rec\` writes the recording, every other leaf is a read-only query over it
-use for per-element frame geometry, changed regions, and input-to-settle timing; use \`perf\` instead for trace-event timing
+screen recording — \`rec\` screencasts the tab through an interaction; every other leaf answers what moved, where, and how long it took from that recording's frames
+use when a claim depends on change over time: element motion across frames, which screen regions changed, layout shifts and long tasks, or the time from an input to a settled screen; for trace-event timing use \`perf\` instead
 </command>`;
 
 export const MOTION_USAGE = `<command name="motion" description="recording lifecycle and read-only queries over a finalized recording">

package/src/cdp/commands/perf/index.ts

@@ -5,8 +5,8 @@ import { cmdPerfVitals } from './vitals.js';
 import { cmdPerfInsights } from './insights.js';
 
 export const COMMAND_BLOCK = `<command name="perf">
-the Chrome performance-trace substrate — \`trace\` records one, \`vitals\` and \`insights\` are read-only queries over it
-use for Core Web Vitals and DevTools insights over a page load or one interaction, timed from trace events
+Chrome performance tracing — \`trace\` records a DevTools performance trace over a page load or an interaction; \`vitals\` and \`insights\` read it back without re-running anything
+use when a claim depends on runtime performance: LCP, INP, and CLS with attribution, or DevTools' computed insights such as render-blocking requests, forced reflow, and layout-shift culprits
 </command>`;
 
 const HELP = `<command name="perf" description="the Chrome performance-trace substrate">

package/src/cdp/commands/tab/index.ts

@@ -21,7 +21,7 @@ import { tabMockMain } from './mock/index.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="tab">
-browser and tab plumbing — the existence of a browser capture owns, endpoint/tab discovery, tab lifecycle, and the conditions the tab's network runs under (connectivity, mocked responses)
+browser and tab plumbing — launch or quit a browser capture owns, discover endpoints and tabs, open/close/reset tabs, and set the tab's network conditions (throttling, offline, mocked responses)
 use when starting, finding, opening, closing, or resetting a browser tab, or changing its network conditions
 </command>`;
 

package/src/session/commands.ts

@@ -383,7 +383,7 @@ export async function waitForPageLoad(
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="session">
-the artifact container — a session records HAR and bundles every artifact; it may open or adopt a tab, and once it has one, every command auto-targets it
+the work's evidence bundle — \`start\` opens or adopts a tab, records its network traffic (HAR) and external logs, and collects every artifact into one directory; while running, every command auto-targets its tab
 use when collecting or reading the traffic, logs, and artifacts of scoped work against one page
 </command>`;