@crouton-kit/capture 1.4.1 → 1.4.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.4.1",
+  "version": "1.4.10",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"
@@ -44,6 +44,8 @@
     "zod": "^4.3.5"
   },
   "dependencies": {
+    "@paulirish/trace_engine": "0.0.65",
+    "lighthouse": "13.4.1",
     "pixelmatch": "7.2.0",
     "pngjs": "7.0.0",
     "ws": "^8.19.0"

package/src/capture.ts

@@ -1,8 +1,8 @@
 /**
  * capture — browser automation and UI measurement over CDP.
  *
- * Root router: seven visible roots (session, page, tab, measure, motion,
- * cdp, lib) plus the hidden `__bridge-serve` and `__log-tail-serve`
+ * Root router: ten visible roots (session, page, tab, measure, motion, perf,
+ * heap, lighthouse, cdp, lib) plus the hidden `__bridge-serve` and `__log-tail-serve`
  * internals, all dispatched below. Root help is assembled from each branch's exported
  * `COMMAND_BLOCK` — the parent walks its children, it never hardcodes a
  * child's description. An unknown first token is a structured
@@ -19,11 +19,14 @@ import { COMMAND_BLOCK as PAGE_BLOCK } from './cdp/commands/page/index.js';
 import { COMMAND_BLOCK as TAB_BLOCK } from './cdp/commands/tab/index.js';
 import { COMMAND_BLOCK as MEASURE_BLOCK } from './cdp/commands/measure/index.js';
 import { COMMAND_BLOCK as MOTION_BLOCK } from './cdp/commands/motion/index.js';
+import { COMMAND_BLOCK as PERF_BLOCK } from './cdp/commands/perf/index.js';
+import { COMMAND_BLOCK as HEAP_BLOCK } from './cdp/commands/heap/index.js';
+import { COMMAND_BLOCK as LIGHTHOUSE_BLOCK } from './cdp/commands/lighthouse.js';
 import { COMMAND_BLOCK as CDP_BLOCK } from './cdp/commands/cdp.js';
 import { COMMAND_BLOCK as LIB_BLOCK } from './cdp/commands/lib.js';
 
-/** The seven visible root children, in help order. */
-const ROOTS = ['session', 'page', 'tab', 'measure', 'motion', 'cdp', 'lib'] as const;
+/** The ten visible root children, in help order. */
+const ROOTS = ['session', 'page', 'tab', 'measure', 'motion', 'perf', 'heap', 'lighthouse', 'cdp', 'lib'] as const;
 
 /**
  * Guessable former/legacy tokens with one unambiguous current destination —
@@ -35,6 +38,9 @@ const ROOTS = ['session', 'page', 'tab', 'measure', 'motion', 'cdp', 'lib'] as c
  */
 const GUESSABLE_HINTS: Readonly<Record<string, string>> = {
   screenshot: 'page shot',
+  trace: 'perf trace',
+  memory: 'heap census',
+  mock: 'tab mock start',
 };
 
 const ROOT_BLOCKS = [
@@ -43,6 +49,9 @@ const ROOT_BLOCKS = [
   TAB_BLOCK,
   MEASURE_BLOCK,
   MOTION_BLOCK,
+  PERF_BLOCK,
+  HEAP_BLOCK,
+  LIGHTHOUSE_BLOCK,
   CDP_BLOCK,
   LIB_BLOCK,
 ] as const;
@@ -52,17 +61,11 @@ function rootHelp(): string {
 
 ${ROOT_BLOCKS.join('\n\n')}
 
-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.
-
-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 — 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 —
-precedence: explicit flag > active session > env. \`session start\` adopts only an
-explicit --target.`;
+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.
+
+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 — 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 — precedence: explicit flag > active session > env. \`session start\` adopts only an explicit --target.`;
 }
 
 function printVersion(): void {
@@ -90,7 +93,7 @@ async function main(): Promise<void> {
     return;
   }
 
-  if (command === undefined || command === '-h') {
+  if (command === undefined || command === '-h' || command === '--help') {
     console.log(rootHelp());
     return;
   }
@@ -111,8 +114,8 @@ async function main(): Promise<void> {
     'invocation',
     'unknown_command',
     hint
-      ? `Unknown command ${command}; did you mean \`capture ${hint}\`? Expected one of the seven roots: session, page, tab, measure, motion, cdp, lib.`
-      : `Unknown command ${command}; expected one of the seven roots: session, page, tab, measure, motion, cdp, lib.`,
+      ? `Unknown command ${command}; did you mean \`capture ${hint}\`? Expected one of the ten roots: session, page, tab, measure, motion, perf, heap, lighthouse, cdp, lib.`
+      : `Unknown command ${command}; expected one of the ten roots: session, page, tab, measure, motion, perf, heap, lighthouse, cdp, lib.`,
   );
 }