@crouton-kit/capture 1.4.2 → 1.4.11

package/src/cdp/host/collectors/trace.ts

@@ -0,0 +1,108 @@
+import { performance } from 'node:perf_hooks';
+import type { CDPClient } from '../../client.js';
+import type { Collector, CollectorContext, DrainCause, DrainOutcome } from '../collector.js';
+
+const TRACE_CATEGORIES = 'devtools.timeline,disabled-by-default-devtools.timeline,disabled-by-default-devtools.timeline.frame,disabled-by-default-devtools.timeline.stack,loading,blink.user_timing';
+
+interface TraceEventParams { value?: unknown; }
+
+function eventArray(params: unknown): readonly object[] {
+  const value = (params as TraceEventParams | null)?.value;
+  return Array.isArray(value) ? value.filter((event): event is object => event !== null && typeof event === 'object') : [];
+}
+
+function navigationCount(events: readonly object[]): number {
+  return events.filter((event) => (event as { name?: unknown }).name === 'navigationStart').length;
+}
+
+/** Streams Chrome's Trace event batches into one DevTools-openable trace.json. */
+export class TraceCollector implements Collector<{ events: number; windowMs: number; navigations: number; categories: string }> {
+  readonly kind = 'trace' as const;
+  readonly claims = ['tracing'] as const;
+  private context: CollectorContext | undefined;
+  private writer: ReturnType<CollectorContext['openChunkFile']> | undefined;
+  private eventHandler: ((params: unknown) => void) | undefined;
+  private completeHandler: ((params: unknown) => void) | undefined;
+  private complete: Promise<void> | undefined;
+  private resolveComplete: (() => void) | undefined;
+  private startedAt = 0;
+  private events = 0;
+  private navigations = 0;
+  private first = true;
+  private closed = false;
+  private started = false;
+  private drainPromise: Promise<DrainOutcome<{ events: number; windowMs: number; navigations: number; categories: string }>> | undefined;
+
+  async start(ctx: CollectorContext): Promise<void> {
+    this.context = ctx;
+    this.writer = ctx.openChunkFile('trace.json');
+    this.writer.write('{"traceEvents":[');
+    this.eventHandler = (params) => {
+      if (this.closed) return;
+      const events = eventArray(params);
+      for (const event of events) {
+        this.writer!.write(`${this.first ? '' : ','}${JSON.stringify(event)}`);
+        this.first = false;
+      }
+      this.events += events.length;
+      this.navigations += navigationCount(events);
+    };
+    this.complete = new Promise(resolve => { this.resolveComplete = resolve; });
+    this.completeHandler = () => this.resolveComplete?.();
+    ctx.client.on('Tracing.dataCollected', this.eventHandler);
+    ctx.client.on('Tracing.tracingComplete', this.completeHandler);
+    try {
+      await ctx.client.send('Tracing.start', { transferMode: 'ReportEvents', categories: TRACE_CATEGORIES });
+      this.startedAt = performance.now();
+      this.started = true;
+    } catch (error) {
+      ctx.client.off('Tracing.dataCollected', this.eventHandler);
+      ctx.client.off('Tracing.tracingComplete', this.completeHandler);
+      this.writer.discard();
+      throw error;
+    }
+  }
+
+  closeAdmission(): void {
+    // A trace has no routed-work admission surface. Tracing.dataCollected must
+    // remain subscribed until tracingComplete drains Chrome's final batches.
+  }
+
+  async drain(cause: DrainCause): Promise<DrainOutcome<{ events: number; windowMs: number; navigations: number; categories: string }>> {
+    if (this.drainPromise) return this.drainPromise;
+    this.drainPromise = this.finish(cause);
+    return this.drainPromise;
+  }
+
+  private async finish(cause: DrainCause): Promise<DrainOutcome<{ events: number; windowMs: number; navigations: number; categories: string }>> {
+    const ctx = this.context!;
+    if (this.started && cause.clientUsable) {
+      try {
+        await ctx.client.send('Tracing.end');
+        await Promise.race([
+          this.complete!,
+          new Promise<void>((_, reject) => setTimeout(() => reject(new Error('Timed out waiting for Tracing.tracingComplete.')), 30_000)),
+        ]);
+      } catch (error) {
+        ctx.noteLoss('trace_drain_incomplete', { error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+    if (!cause.clientUsable) ctx.noteLoss('transport_lost');
+    this.closed = true;
+    ctx.client.off('Tracing.dataCollected', this.eventHandler!);
+    ctx.client.off('Tracing.tracingComplete', this.completeHandler!);
+    this.writer!.write(']}');
+    const bytes = this.writer!.commit();
+    return {
+      summary: { events: this.events, windowMs: this.startedAt ? performance.now() - this.startedAt : 0, navigations: this.navigations, categories: 'devtools-default' },
+      files: [{ name: 'trace.json', bytes }],
+    };
+  }
+
+  abandon(): void {
+    this.closed = true;
+    try { this.writer?.discard(); } catch {}
+  }
+}
+
+export { TRACE_CATEGORIES };

package/src/cdp/host/core.ts

@@ -0,0 +1,217 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { CDPClient } from '../client.js';
+import { appendNdjsonPrivate, ensurePrivateDir, openPrivateChunkWriter, readPrivateFile, removeArtifactTree, unlinkPrivateFile, writeJsonPrivate, type PidBirth } from '../../session/artifacts.js';
+import { processPidBirthProvider, sameBirth } from '../../session/artifacts.js';
+import { collectorKind } from './kinds.js';
+import { RetainedCollectorStartFailure, type CdpClaim, type ClaimReservation, type Collector, type CollectorContext, type CollectorKind, type Completion, type DispatchNotice, type DrainCause, type DrainOutcome, type TeardownOutcome } from './collector.js';
+
+export interface CollectorRow { id: string; kind: CollectorKind; dir: string; claims: readonly CdpClaim[]; startedAt: string; }
+export interface HostSnapshot { collectors: readonly CollectorRow[]; reservations: readonly ClaimReservation[]; }
+export interface HostIdentity { pid: number; birth: PidBirth; targetId: string; }
+
+interface LiveCollector { row: CollectorRow; collector: Collector; startedAt: string; losses: Array<{ reason: string; detail?: Record<string, unknown> }>; stopping: boolean; }
+
+export class CollectorHost {
+  private readonly live = new Map<string, LiveCollector>();
+  private readonly reservations = new Map<string, ClaimReservation>();
+  private readonly starting = new Map<string, readonly CdpClaim[]>();
+  private harClosing = false;
+  private clientUsable = true;
+
+  constructor(
+    readonly client: CDPClient,
+    readonly sessionDir: string,
+    readonly identity: HostIdentity,
+    private readonly publish: (snapshot: HostSnapshot) => void,
+    private readonly onEmpty: () => void,
+  ) {
+    client.onDisconnect(() => { void this.transportLost(); });
+  }
+
+  snapshot(): HostSnapshot { return { collectors: [...this.live.values()].map(item => item.row), reservations: [...this.reservations.values()] }; }
+
+  private changed(): void { this.publish(this.snapshot()); if (!this.live.size && !this.reservations.size) this.onEmpty(); }
+
+  private releaseDeadReservations(): void {
+    for (const [token, reservation] of this.reservations) {
+      const observed = processPidBirthProvider.read(reservation.pid);
+      if (observed.status === 'absent' || (observed.status === 'found' && !sameBirth(observed.identity, reservation.birth))) this.reservations.delete(token);
+    }
+  }
+
+  private refuseClaims(claims: readonly CdpClaim[], exclusive = false): void {
+    this.releaseDeadReservations();
+    const exclusiveReservation = [...this.reservations.values()].find(reservation => reservation.exclusive);
+    if (exclusiveReservation) throw new Error(`Target is held exclusively by reservation ${exclusiveReservation.holderLabel}.`);
+    if (exclusive) {
+      const collector = this.live.values().next().value as LiveCollector | undefined;
+      if (collector) throw new Error(`Target has live collector ${collector.row.id}.`);
+      const reservation = this.reservations.values().next().value as ClaimReservation | undefined;
+      if (reservation) throw new Error(`Target has reservation ${reservation.holderLabel}.`);
+      const starting = this.starting.keys().next().value as string | undefined;
+      if (starting) throw new Error(`Target has starting collector ${starting}.`);
+    }
+    for (const claim of claims) {
+      const collector = [...this.live.values()].find(value => value.row.claims.includes(claim));
+      if (collector) throw new Error(`Claim "${claim}" is held by collector ${collector.row.id}.`);
+      const reservation = [...this.reservations.values()].find(value => value.claims.includes(claim));
+      if (reservation) throw new Error(`Claim "${claim}" is held by reservation ${reservation.holderLabel}.`);
+      const starting = [...this.starting.entries()].find(([, held]) => held.includes(claim));
+      if (starting) throw new Error(`Claim "${claim}" is held by collector ${starting[0]}.`);
+    }
+  }
+
+  reserve(claims: readonly CdpClaim[], holderLabel: string, pid: number, birth: PidBirth, exclusive = false): ClaimReservation {
+    this.refuseClaims(claims, exclusive);
+    const reservation: ClaimReservation = { token: crypto.randomBytes(18).toString('hex'), claims: [...new Set(claims)], ...(exclusive ? { exclusive: true } : {}), holderLabel, pid, birth, reservedAt: new Date().toISOString() };
+    this.reservations.set(reservation.token, reservation);
+    this.changed();
+    return reservation;
+  }
+
+  releaseReservation(token: string): void { this.reservations.delete(token); this.changed(); }
+
+  async start(kind: CollectorKind, rawConfig: unknown): Promise<CollectorRow> {
+    const entry = collectorKind(kind);
+    const config = entry.parseConfig(rawConfig);
+    const collector = entry.create(config);
+    this.refuseClaims(collector.claims);
+    const id = `${entry.idPrefix}-${crypto.randomBytes(5).toString('hex')}`;
+    this.starting.set(id, collector.claims);
+    const dir = path.join(this.sessionDir, ...entry.idSegments, id);
+    try {
+      ensurePrivateDir(dir);
+      const startedAt = new Date().toISOString();
+      const row: CollectorRow = { id, kind, dir, claims: [...collector.claims], startedAt };
+      const live: LiveCollector = { row, collector, startedAt, losses: [], stopping: false };
+      const context: CollectorContext = {
+        client: this.client,
+        dir,
+        id,
+        targetId: this.identity.targetId,
+        config,
+        appendRecord: (file, record) => appendNdjsonPrivate(path.join(dir, file), record),
+        openChunkFile: file => openPrivateChunkWriter(path.join(dir, file)),
+        noteLoss: (reason, detail) => { live.losses.push({ reason, detail }); },
+      };
+      writeJsonPrivate(path.join(dir, 'collecting.json'), { kind, id, startedAt, hostPid: this.identity.pid, hostBirth: this.identity.birth });
+      await collector.start(context);
+      this.starting.delete(id);
+      this.live.set(id, live);
+      this.changed();
+      return row;
+    } catch (error) {
+      this.starting.delete(id);
+      if (!(error instanceof RetainedCollectorStartFailure)) removeArtifactTree(dir);
+      this.changed();
+      throw error;
+    }
+  }
+
+  private cutoff(items: Iterable<LiveCollector>): LiveCollector[] {
+    const selected = [...items].filter(item => !item.stopping);
+    for (const item of selected) item.stopping = true;
+    for (const item of selected) item.collector.closeAdmission();
+    return selected;
+  }
+
+  private finalizedFiles(dir: string): Array<{ name: string; bytes: number }> {
+    const files: Array<{ name: string; bytes: number }> = [];
+    const walk = (relative: string): void => {
+      for (const entry of fs.readdirSync(path.join(dir, relative), { withFileTypes: true })) {
+        const name = path.join(relative, entry.name);
+        if (entry.isDirectory()) walk(name);
+        else if (entry.isFile()) files.push({ name, bytes: readPrivateFile(path.join(dir, name)).length });
+      }
+    };
+    walk('');
+    return files;
+  }
+
+  private async drainOne(live: LiveCollector, cause: DrainCause): Promise<{ completion: Completion; outcome: DrainOutcome }> {
+    const outcome = await live.collector.drain(cause);
+    unlinkPrivateFile(path.join(live.row.dir, 'collecting.json'));
+    const files = this.finalizedFiles(live.row.dir);
+    const loss = live.losses[0];
+    const completion: Completion = loss || !cause.clientUsable ? 'partial' : 'complete';
+    const summary = outcome.summary && typeof outcome.summary === 'object' && !Array.isArray(outcome.summary) ? outcome.summary as Record<string, unknown> : { value: outcome.summary };
+    writeJsonPrivate(path.join(live.row.dir, 'meta.json'), {
+      id: live.row.id,
+      kind: live.row.kind,
+      completion,
+      ...(completion === 'partial' ? { reason: loss?.reason ?? 'transport_lost' } : {}),
+      startedAt: live.startedAt,
+      endedAt: new Date().toISOString(),
+      files,
+      summary,
+      ...summary,
+    });
+    this.live.delete(live.row.id);
+    this.changed();
+    return { completion, outcome: { ...outcome, files } };
+  }
+
+  async stop(id: string, trigger: DrainCause['trigger'] = 'explicit'): Promise<{ completion: Completion; summary: unknown; files: readonly { name: string; bytes: number }[] }> {
+    const live = this.live.get(id);
+    if (!live) throw new Error(`No live collector named ${id}.`);
+    this.cutoff([live]);
+    const drained = await this.drainOne(live, { trigger, clientUsable: this.clientUsable });
+    return { completion: drained.completion, summary: drained.outcome.summary, files: drained.outcome.files };
+  }
+
+  async teardown(trigger: DrainCause['trigger'] = 'session-stop'): Promise<TeardownOutcome[]> {
+    const stopping = this.cutoff(this.live.values());
+    const outcomes: TeardownOutcome[] = [];
+    for (const live of stopping) {
+      try {
+        const drained = await this.drainOne(live, { trigger, clientUsable: this.clientUsable });
+        outcomes.push({ status: 'drained', id: live.row.id, kind: live.row.kind, completion: drained.completion, dir: live.row.dir });
+      } catch (error) {
+        outcomes.push({ status: 'terminal', id: live.row.id, kind: live.row.kind, dir: live.row.dir, error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+    return outcomes;
+  }
+
+  private motionController(): Collector | undefined {
+    return [...this.live.values()].find(live => live.row.kind === 'motion')?.collector;
+  }
+
+  async control(message: unknown): Promise<unknown> {
+    if (!this.clientUsable) throw new Error('collector host CDP transport is unavailable');
+    const controller = this.motionController();
+    if (!controller?.control) throw new Error('no collector accepts this host control request');
+    return controller.control(message);
+  }
+
+  async dispatch(method: string, params: Record<string, unknown> = {}, annotation?: string, waitEvent?: string, timeoutMs?: number, observeDocumentResponse = false): Promise<unknown> {
+    if (!this.clientUsable) throw new Error('collector host CDP transport is unavailable');
+    const controller = this.motionController();
+    if (controller?.control) return controller.control({ type: 'cdp', method, params, annotation, waitEvent, timeoutMs, observeDocumentResponse });
+    const notice: DispatchNotice = { method, params, annotation, atPerformanceNowMs: performance.now() };
+    const callbacks = [...this.live.values()].flatMap(live => {
+      try { const callback = live.collector.onDispatch?.(notice); return callback ? [callback] : []; } catch { return []; }
+    });
+    try {
+      const result = await this.client.send(method, params);
+      const outcome = { ok: true, atPerformanceNowMs: performance.now() };
+      for (const callback of callbacks) callback(outcome);
+      return result;
+    } catch (error) {
+      const outcome = { ok: false, error: error instanceof Error ? error.message : String(error), atPerformanceNowMs: performance.now() };
+      for (const callback of callbacks) callback(outcome);
+      throw error;
+    }
+  }
+
+  private async transportLost(): Promise<void> {
+    if (!this.clientUsable) return;
+    this.clientUsable = false;
+    await this.teardown('transport-lost');
+  }
+
+  abandon(): void { for (const live of this.live.values()) live.collector.abandon(); }
+}

package/src/cdp/host/handle.ts

@@ -0,0 +1,47 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { collectorHostSocketPath } from '../bridge/spawn.js';
+import { assertUnderCaptureRoot, parseBirth, readPrivateFile, sameBirth, type PidBirth } from '../../session/artifacts.js';
+import { processPidBirthProvider } from '../../session/artifacts.js';
+import type { CollectorRow } from './core.js';
+import type { ClaimReservation } from './collector.js';
+
+export interface CollectorHostHandle {
+  pid: number;
+  birth: PidBirth;
+  socketPath: string;
+  targetId: string;
+  nonce: string;
+  startedAt: string;
+  collectors: readonly CollectorRow[];
+  reservations: readonly ClaimReservation[];
+}
+export type CollectorHostClassification = 'absent' | 'live' | 'dead' | 'malformed' | 'unknown';
+export interface ScannedCollectorHost { classification: CollectorHostClassification; handle: CollectorHostHandle | null; path: string; }
+
+export function collectorHostPath(sessionDir: string): string { return path.join(assertUnderCaptureRoot(sessionDir), '.collector-host.json'); }
+function parseHandle(raw: unknown, sessionDir: string): CollectorHostHandle | null {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  const value = raw as Record<string, unknown>;
+  const birth = parseBirth(value.birth);
+  if (!birth || !Number.isSafeInteger(value.pid) || (value.pid as number) <= 0 || typeof value.socketPath !== 'string' || value.socketPath !== collectorHostSocketPath(sessionDir) || typeof value.targetId !== 'string' || !value.targetId || typeof value.nonce !== 'string' || !/^[0-9a-f]{64}$/.test(value.nonce) || typeof value.startedAt !== 'string' || !Array.isArray(value.collectors) || !Array.isArray(value.reservations)) return null;
+  return value as unknown as CollectorHostHandle;
+}
+
+export function scanCollectorHost(sessionDir: string): ScannedCollectorHost {
+  const file = collectorHostPath(sessionDir);
+  let raw: unknown;
+  try { raw = JSON.parse(readPrivateFile(file).toString('utf8')); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { classification: 'absent', handle: null, path: file }; return { classification: 'malformed', handle: null, path: file }; }
+  const handle = parseHandle(raw, sessionDir);
+  if (!handle) return { classification: 'malformed', handle: null, path: file };
+  const read = processPidBirthProvider.read(handle.pid);
+  if (read.status === 'unknown') return { classification: 'unknown', handle, path: file };
+  if (read.status === 'found' && sameBirth(read.identity, handle.birth)) {
+    try {
+      if (!fs.lstatSync(handle.socketPath).isSocket()) return { classification: 'malformed', handle: null, path: file };
+    } catch { return { classification: 'malformed', handle: null, path: file }; }
+    return { classification: 'live', handle, path: file };
+  }
+  return { classification: 'dead', handle, path: file };
+}

package/src/cdp/host/held-client.ts

@@ -0,0 +1,91 @@
+import { sendHostRequest } from './client.js';
+
+const MARKABLE_EXACT_METHODS = new Set(['Input.insertText', 'Page.navigate']);
+
+function isMarkableActionMethod(method: string, params: Record<string, unknown>): boolean {
+  if (MARKABLE_EXACT_METHODS.has(method)) return true;
+  if (method === 'Input.dispatchMouseEvent') return params.type === 'mousePressed';
+  if (method === 'Input.dispatchKeyEvent') return params.type === 'keyDown' || params.type === 'rawKeyDown';
+  if (method === 'Input.dispatchTouchEvent') return params.type === 'touchStart';
+  return false;
+}
+
+export interface MotionHeldClientOptions {
+  socketPath: string;
+  nonce: string;
+  actionLabel: string;
+  timeoutMs?: number;
+}
+
+/** CDP-shaped client that routes a composed recording's commands through its session collector host. */
+export class MotionHeldClient {
+  private readonly defaultTimeoutMs: number;
+  private suppressNextMousePressMark = false;
+
+  constructor(private readonly options: MotionHeldClientOptions) {
+    this.defaultTimeoutMs = options.timeoutMs ?? 60_000;
+  }
+
+  suppressNextFocusClickMark(): void { this.suppressNextMousePressMark = true; }
+
+  async send(method: string, params: Record<string, unknown> = {}, timeoutMs?: number, _sessionId?: string): Promise<unknown> {
+    return (await this.dispatch(method, params, undefined, timeoutMs)).result;
+  }
+
+  async sendMarked(method: string, params: Record<string, unknown>, mark: string): Promise<unknown> {
+    return (await this.request(method, params, mark)).result;
+  }
+
+  async waitEvent(eventName: string, timeoutMs?: number): Promise<unknown> {
+    const response = await sendHostRequest(this.options.socketPath, {
+      type: 'cdp', nonce: this.options.nonce, waitEvent: eventName, timeoutMs: timeoutMs ?? this.defaultTimeoutMs,
+    }, (timeoutMs ?? this.defaultTimeoutMs) + 5_000);
+    if (!response.ok) throw new Error(`collector-host wait-event "${eventName}" failed: ${response.error}`);
+    return response.event;
+  }
+
+  async dispatch(method: string, params: Record<string, unknown> = {}, waitEvent?: string, timeoutMs?: number, observeDocumentResponse = false): Promise<{ result: unknown; event?: unknown; waitOutcome?: 'observed' | 'bounded-timeout'; documentResponse?: { status: number; url: string } }> {
+    const suppressMousePress = method === 'Input.dispatchMouseEvent' && params.type === 'mousePressed' && this.suppressNextMousePressMark;
+    if (suppressMousePress) this.suppressNextMousePressMark = false;
+    const annotation = !suppressMousePress && isMarkableActionMethod(method, params) ? this.options.actionLabel : undefined;
+    return this.request(method, params, annotation, waitEvent, timeoutMs, observeDocumentResponse);
+  }
+
+  async flushHar(): Promise<void> {
+    const response = await sendHostRequest(this.options.socketPath, { type: 'har-flush', nonce: this.options.nonce });
+    if (!response.ok) throw new Error(`collector host HAR flush failed: ${response.error}`);
+  }
+
+  async collectStyleSheetHeaders(): Promise<Array<{ styleSheetId: string; sourceURL: string }>> {
+    const result = await this.send('Capture.collectStyleSheetHeaders') as { headers?: unknown };
+    if (!Array.isArray(result?.headers)) throw new Error('collector host stylesheet-header collection returned an invalid response');
+    return result.headers.flatMap(header => {
+      const value = header as { styleSheetId?: unknown; sourceURL?: unknown };
+      return typeof value.styleSheetId === 'string' && typeof value.sourceURL === 'string' && value.sourceURL.length > 0
+        ? [{ styleSheetId: value.styleSheetId, sourceURL: value.sourceURL }]
+        : [];
+    });
+  }
+
+  on(_event: string, _handler: (params: unknown) => void): void {}
+  onDisconnect(_handler: () => void): void {}
+  close(): void {}
+
+  private async request(method: string, params: Record<string, unknown>, annotation?: string, waitEvent?: string, timeoutMs?: number, observeDocumentResponse = false): Promise<{ result: unknown; event?: unknown; waitOutcome?: 'observed' | 'bounded-timeout'; documentResponse?: { status: number; url: string } }> {
+    const response = await sendHostRequest(this.options.socketPath, {
+      type: 'cdp', nonce: this.options.nonce, method, params, annotation, waitEvent, timeoutMs: timeoutMs ?? this.defaultTimeoutMs, observeDocumentResponse,
+    }, (timeoutMs ?? this.defaultTimeoutMs) + 5_000);
+    if (!response.ok) throw new Error(`collector-host CDP call "${method}"${waitEvent ? ` with wait-event "${waitEvent}"` : ''} failed: ${response.error}`);
+    const documentResponse = response.documentResponse;
+    return {
+      result: response.result,
+      event: response.event,
+      waitOutcome: response.waitOutcome as 'observed' | 'bounded-timeout' | undefined,
+      documentResponse: documentResponse && typeof documentResponse === 'object' && typeof (documentResponse as { status?: unknown }).status === 'number' && typeof (documentResponse as { url?: unknown }).url === 'string'
+        ? documentResponse as { status: number; url: string }
+        : undefined,
+    };
+  }
+}
+
+export function isMotionHeldClient(client: unknown): client is MotionHeldClient { return client instanceof MotionHeldClient; }

package/src/cdp/host/kinds.ts

@@ -0,0 +1,97 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { HeapCollector, reconstructHeapSnapshot } from './collectors/heap.js';
+import { InterceptCollector, parseMockCollectorConfig } from './collectors/intercept.js';
+import { MotionCollector } from './collectors/motion.js';
+import { TraceCollector } from './collectors/trace.js';
+import type { CollectorKind, CollectorKindEntry, DrainOutcome } from './collector.js';
+
+function motionReconstruct(dir: string): DrainOutcome {
+  const framesDir = path.join(dir, 'frames');
+  const frames = fs.existsSync(framesDir) ? fs.readdirSync(framesDir).filter(name => name.endsWith('.png')).length : 0;
+  const bytes = (name: string): number => {
+    try { return fs.statSync(path.join(dir, name)).size; } catch { return 0; }
+  };
+  const files = ['events.jsonl', 'rects.jsonl', 'markers.json'].filter(name => fs.existsSync(path.join(dir, name))).map(name => ({ name, bytes: bytes(name) }));
+  return { summary: { frames, state: 'orphaned-finalized' }, files };
+}
+
+const motion: CollectorKindEntry = {
+  kind: 'motion',
+  idSegments: ['motion', 'recs'],
+  idPrefix: 'rec',
+  label: 'recording',
+  parseConfig(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw) || typeof (raw as { harId?: unknown }).harId !== 'string' || !(raw as { harId: string }).harId) {
+      throw new Error('motion config requires a session HAR recording id');
+    }
+    return raw;
+  },
+  create() { return new MotionCollector(); },
+  reconstruct: motionReconstruct,
+};
+
+const trace: CollectorKindEntry = {
+  kind: 'trace',
+  idSegments: ['perf', 'traces'],
+  idPrefix: 'trace',
+  label: 'trace',
+  parseConfig(raw) {
+    if (raw !== undefined && (raw === null || typeof raw !== 'object' || Array.isArray(raw))) throw new Error('trace config must be an object');
+    return raw ?? {};
+  },
+  create() { return new TraceCollector(); },
+  reconstruct(dir) {
+    const file = path.join(dir, 'trace.json');
+    const bytes = fs.existsSync(file) ? fs.statSync(file).size : 0;
+    return { summary: { events: 0, windowMs: 0, navigations: 0, categories: 'devtools-default' }, files: bytes ? [{ name: 'trace.json', bytes }] : [] };
+  },
+};
+
+const heap: CollectorKindEntry = {
+  kind: 'heap',
+  idSegments: ['heap', 'snapshots'],
+  idPrefix: 'heap',
+  label: 'heap snapshot',
+  parseConfig(raw) {
+    if (raw !== undefined && (raw === null || typeof raw !== 'object' || Array.isArray(raw))) throw new Error('heap snapshot config must be an object');
+    return raw ?? {};
+  },
+  create() { return new HeapCollector(); },
+  reconstruct: reconstructHeapSnapshot,
+};
+
+const unsupported = (kind: Exclude<CollectorKind, 'motion' | 'trace' | 'heap'>, idSegments: string[], idPrefix: string, label: string): CollectorKindEntry => ({
+  kind,
+  idSegments,
+  idPrefix,
+  label,
+  parseConfig(raw) { return raw; },
+  create() { throw new Error(`${kind} collector is not installed`); },
+  reconstruct(dir) { return { summary: {}, files: [] }; },
+});
+
+const intercept: CollectorKindEntry = {
+  kind: 'intercept',
+  idSegments: ['network', 'mocks'],
+  idPrefix: 'mock',
+  label: 'mock',
+  parseConfig: parseMockCollectorConfig,
+  create(config) { return new InterceptCollector(config as ReturnType<typeof parseMockCollectorConfig>); },
+  reconstruct(dir) {
+    const bytes = (name: string): number => {
+      try { return fs.statSync(path.join(dir, name)).size; } catch { return 0; }
+    };
+    const files = ['rules.json', 'interceptions.jsonl'].filter(name => fs.existsSync(path.join(dir, name))).map(name => ({ name, bytes: bytes(name) }));
+    return { summary: { state: 'orphaned-finalized' }, files };
+  },
+};
+
+export const COLLECTOR_KINDS: Record<CollectorKind, CollectorKindEntry> = {
+  motion,
+  trace,
+  heap,
+  intercept,
+};
+
+export function collectorKind(kind: CollectorKind): CollectorKindEntry { return COLLECTOR_KINDS[kind]; }