@storyshelf/core 0.6.2 → 0.7.0

package/dist/capture/fingerprint.mjs

@@ -0,0 +1,83 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { sha256 } from "../utils/hash.mjs";
+import { SIZING_DEFAULTS } from "./sizing.mjs";
+//#region src/capture/fingerprint.ts
+/** Build the fingerprint of one capture. Missing environment fields stay `null` (runner did not report them). */
+function buildFingerprint(engine, viewport, environment) {
+	return {
+		engine,
+		browserVersion: environment?.browserVersion ?? null,
+		platform: environment?.platform ?? null,
+		deviceScaleFactor: environment?.deviceScaleFactor ?? null,
+		fontsHash: environment?.fontsHash ?? null,
+		viewport: {
+			width: viewport.width,
+			height: viewport.height
+		},
+		sizing: SIZING_DEFAULTS
+	};
+}
+/** Stable hash of a fingerprint: the value stored as `infraHash`. */
+function fingerprintHash(fingerprint) {
+	return sha256(JSON.stringify([
+		fingerprint.engine,
+		fingerprint.browserVersion,
+		fingerprint.platform,
+		fingerprint.deviceScaleFactor,
+		fingerprint.fontsHash,
+		fingerprint.viewport.width,
+		fingerprint.viewport.height,
+		fingerprint.sizing
+	]));
+}
+/** The components whose change is an environment migration. Viewport is not one (see below). */
+const ENVIRONMENT_FIELDS = [
+	"engine",
+	"browserVersion",
+	"platform",
+	"deviceScaleFactor",
+	"fontsHash"
+];
+/**
+* Names of the environment components that differ; `["unknown"]` when the earlier fingerprint was
+* not recorded. A component one side did not report (`null`: a runner that does not report it, a
+* capture spooled before a browser crash, a failed `fc-list`) is unknown, not changed. Viewport is
+* never a change here: its size comes from story parameters (the PR's own code), so a new size must
+* be reviewed, and it diffs on its own as a dimension change.
+*/
+function changedFields(from, to) {
+	if (!from) return ["unknown"];
+	return [...ENVIRONMENT_FIELDS.filter((key) => known(from[key]) && known(to[key]) && from[key] !== to[key]), ...JSON.stringify(from.sizing) === JSON.stringify(to.sizing) ? [] : ["sizing"]];
+}
+function known(value) {
+	return value !== null && value !== void 0;
+}
+/**
+* The fingerprint to store on a baseline: the capture's, with any component it did not report kept
+* from the baseline's earlier fingerprint, so an unknown component never overwrites a known one.
+*/
+function mergeFingerprint(earlier, now) {
+	return {
+		...now,
+		browserVersion: now.browserVersion ?? earlier?.browserVersion ?? null,
+		platform: now.platform ?? earlier?.platform ?? null,
+		deviceScaleFactor: now.deviceScaleFactor ?? earlier?.deviceScaleFactor ?? null,
+		fontsHash: now.fontsHash ?? earlier?.fontsHash ?? null
+	};
+}
+/** Parse a stored fingerprint; null for a missing or malformed value. */
+function parseFingerprint(raw) {
+	if (!raw) return null;
+	try {
+		const value = JSON.parse(raw);
+		return typeof value.engine === "string" && value.viewport ? value : null;
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { buildFingerprint, changedFields, fingerprintHash, mergeFingerprint, parseFingerprint };
+
+//# sourceMappingURL=fingerprint.mjs.map

package/dist/capture/fingerprint.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.mjs","names":[],"sources":["../../src/capture/fingerprint.ts"],"sourcesContent":["/** Capture fingerprint: everything that changes pixels without a code change (ADR 0005 phase 4). */\nimport type { CaptureEnvironment } from \"../adapters/capture-runner.ts\";\nimport { sha256 } from \"../utils/hash.ts\";\nimport type { Viewport } from \"./adapter.ts\";\nimport { SIZING_DEFAULTS } from \"./sizing.ts\";\n\n/** The components behind a snapshot's `infraHash`, kept so a mismatch can say what changed. */\nexport interface Fingerprint {\n  engine: string;\n  browserVersion: string | null;\n  platform: string | null;\n  deviceScaleFactor: number | null;\n  fontsHash: string | null;\n  viewport: { width: number; height: number };\n  sizing: typeof SIZING_DEFAULTS;\n}\n\n/** Build the fingerprint of one capture. Missing environment fields stay `null` (runner did not report them). */\nexport function buildFingerprint(\n  engine: string,\n  viewport: Viewport,\n  environment: CaptureEnvironment | undefined,\n): Fingerprint {\n  return {\n    engine,\n    browserVersion: environment?.browserVersion ?? null,\n    platform: environment?.platform ?? null,\n    deviceScaleFactor: environment?.deviceScaleFactor ?? null,\n    fontsHash: environment?.fontsHash ?? null,\n    viewport: { width: viewport.width, height: viewport.height },\n    sizing: SIZING_DEFAULTS,\n  };\n}\n\n/** Stable hash of a fingerprint: the value stored as `infraHash`. */\nexport function fingerprintHash(fingerprint: Fingerprint): string {\n  return sha256(\n    JSON.stringify([\n      fingerprint.engine,\n      fingerprint.browserVersion,\n      fingerprint.platform,\n      fingerprint.deviceScaleFactor,\n      fingerprint.fontsHash,\n      fingerprint.viewport.width,\n      fingerprint.viewport.height,\n      fingerprint.sizing,\n    ]),\n  );\n}\n\n/** The components whose change is an environment migration. Viewport is not one (see below). */\nconst ENVIRONMENT_FIELDS = [\n  \"engine\",\n  \"browserVersion\",\n  \"platform\",\n  \"deviceScaleFactor\",\n  \"fontsHash\",\n] as const;\n\n/**\n * Names of the environment components that differ; `[\"unknown\"]` when the earlier fingerprint was\n * not recorded. A component one side did not report (`null`: a runner that does not report it, a\n * capture spooled before a browser crash, a failed `fc-list`) is unknown, not changed. Viewport is\n * never a change here: its size comes from story parameters (the PR's own code), so a new size must\n * be reviewed, and it diffs on its own as a dimension change.\n */\nexport function changedFields(from: Fingerprint | null, to: Fingerprint): string[] {\n  if (!from) {\n    return [\"unknown\"];\n  }\n  return [\n    ...ENVIRONMENT_FIELDS.filter(\n      (key) => known(from[key]) && known(to[key]) && from[key] !== to[key],\n    ),\n    ...(JSON.stringify(from.sizing) === JSON.stringify(to.sizing) ? [] : [\"sizing\"]),\n  ];\n}\n\nfunction known(value: unknown): boolean {\n  return value !== null && value !== undefined;\n}\n\n/**\n * The fingerprint to store on a baseline: the capture's, with any component it did not report kept\n * from the baseline's earlier fingerprint, so an unknown component never overwrites a known one.\n */\nexport function mergeFingerprint(earlier: Fingerprint | null, now: Fingerprint): Fingerprint {\n  return {\n    ...now,\n    browserVersion: now.browserVersion ?? earlier?.browserVersion ?? null,\n    platform: now.platform ?? earlier?.platform ?? null,\n    deviceScaleFactor: now.deviceScaleFactor ?? earlier?.deviceScaleFactor ?? null,\n    fontsHash: now.fontsHash ?? earlier?.fontsHash ?? null,\n  };\n}\n\n/** Parse a stored fingerprint; null for a missing or malformed value. */\nexport function parseFingerprint(raw: string | null | undefined): Fingerprint | null {\n  if (!raw) {\n    return null;\n  }\n  try {\n    const value = JSON.parse(raw) as Partial<Fingerprint>;\n    return typeof value.engine === \"string\" && value.viewport ? (value as Fingerprint) : null;\n  } catch {\n    return null;\n  }\n}\n\n/** What a migrated snapshot records: which components changed, and the before and after. */\nexport interface EnvironmentChange {\n  changed: string[];\n  from: Fingerprint | null;\n  to: Fingerprint;\n}\n"],"mappings":";;;;;;;AAkBA,SAAgB,iBACd,QACA,UACA,aACa;CACb,OAAO;EACL;EACA,gBAAgB,aAAa,kBAAkB;EAC/C,UAAU,aAAa,YAAY;EACnC,mBAAmB,aAAa,qBAAqB;EACrD,WAAW,aAAa,aAAa;EACrC,UAAU;GAAE,OAAO,SAAS;GAAO,QAAQ,SAAS;EAAO;EAC3D,QAAQ;CACV;AACF;;AAGA,SAAgB,gBAAgB,aAAkC;CAChE,OAAO,OACL,KAAK,UAAU;EACb,YAAY;EACZ,YAAY;EACZ,YAAY;EACZ,YAAY;EACZ,YAAY;EACZ,YAAY,SAAS;EACrB,YAAY,SAAS;EACrB,YAAY;CACd,CAAC,CACH;AACF;;AAGA,MAAM,qBAAqB;CACzB;CACA;CACA;CACA;CACA;AACF;;;;;;;;AASA,SAAgB,cAAc,MAA0B,IAA2B;CACjF,IAAI,CAAC,MACH,OAAO,CAAC,SAAS;CAEnB,OAAO,CACL,GAAG,mBAAmB,QACnB,QAAQ,MAAM,KAAK,IAAI,KAAK,MAAM,GAAG,IAAI,KAAK,KAAK,SAAS,GAAG,IAClE,GACA,GAAI,KAAK,UAAU,KAAK,MAAM,MAAM,KAAK,UAAU,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,CAChF;AACF;AAEA,SAAS,MAAM,OAAyB;CACtC,OAAO,UAAU,QAAQ,UAAU,KAAA;AACrC;;;;;AAMA,SAAgB,iBAAiB,SAA6B,KAA+B;CAC3F,OAAO;EACL,GAAG;EACH,gBAAgB,IAAI,kBAAkB,SAAS,kBAAkB;EACjE,UAAU,IAAI,YAAY,SAAS,YAAY;EAC/C,mBAAmB,IAAI,qBAAqB,SAAS,qBAAqB;EAC1E,WAAW,IAAI,aAAa,SAAS,aAAa;CACpD;AACF;;AAGA,SAAgB,iBAAiB,KAAoD;CACnF,IAAI,CAAC,KACH,OAAO;CAET,IAAI;EACF,MAAM,QAAQ,KAAK,MAAM,GAAG;EAC5B,OAAO,OAAO,MAAM,WAAW,YAAY,MAAM,WAAY,QAAwB;CACvF,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/capture/forked/channel.d.mts

@@ -0,0 +1,25 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ChildMessage, ParentMessage } from "./protocol.mjs";
+//#region src/capture/forked/channel.d.ts
+/** How the parent sees the capture child (`child_process.fork` adapts to this). */
+interface ChildProcessHandle {
+  send(message: ParentMessage): void;
+  onMessage(listener: (message: unknown) => void): void;
+  /** Fires once when the child ends; `code` is null when it was killed by a signal. */
+  onExit(listener: (info: {
+    code: number | null;
+    signal: string | null;
+  }) => void): void;
+  /** Stop the child: SIGTERM, escalating to SIGKILL; `force` goes straight to SIGKILL (a hung child ignores SIGTERM). */
+  kill(force?: boolean): void;
+}
+/** How the child sees its parent (`process.send` / `process.on("message")` adapt to this). */
+interface ParentPort {
+  send(message: ChildMessage): void;
+  onMessage(listener: (message: unknown) => void): void;
+  onDisconnect(listener: () => void): void;
+}
+//#endregion
+export { ChildProcessHandle, ParentPort };
+//# sourceMappingURL=channel.d.mts.map

package/dist/capture/forked/child.d.mts

@@ -0,0 +1,34 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { Logger } from "../../logger.mjs";
+import { CaptureHandlerOptions } from "../consumer/capture-handler.mjs";
+import { CaptureConsumerOptions } from "../consumer/types.mjs";
+import { ChildMessage } from "./protocol.mjs";
+//#region src/capture/forked/child.d.ts
+/** Handler options minus the shard hand-out, which the child wires to the database queue. */
+type CaptureChildOptions = Omit<CaptureHandlerOptions, "enqueue" | "logger"> & Pick<CaptureConsumerOptions, "images" | "compare"> & {
+  logger?: Logger;
+  /** Retries stamped on shard jobs (default: the parent's `testing.retries`, handed down in the environment). */
+  retries?: number;
+};
+/** The slice of `process` the child uses; injectable so the lifecycle is testable. */
+interface ChildHost {
+  /** Present only in a forked process with an IPC channel. */
+  send?: (message: ChildMessage) => unknown;
+  on(event: "message" | "disconnect" | "SIGTERM" | "SIGINT", listener: (message?: unknown) => void): unknown;
+  env: Record<string, string | undefined>;
+  exit(code: number): void;
+}
+/**
+ * Run pushed jobs until the parent stops the child.
+ *
+ * - `SIGTERM` / `SIGINT`: let the runs in flight finish, then exit 0.
+ * - Parent gone (`disconnect`): nobody can receive results, so exit at once. Whatever was running
+ *   loses its lease with the parent and is redelivered to another consumer.
+ *
+ * @throws When not running as a forked child (no IPC channel), or when the image engine cannot load.
+ */
+declare function runCaptureChild(options: CaptureChildOptions, host?: ChildHost): Promise<void>;
+//#endregion
+export { CaptureChildOptions, ChildHost, runCaptureChild };
+//# sourceMappingURL=child.d.mts.map

package/dist/capture/forked/child.mjs

@@ -0,0 +1,202 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { createShelfLogger } from "../../logger.mjs";
+import { createNotifyEnqueuer } from "../build-state/notify-job.mjs";
+import { createBuildStatePublisher } from "../build-state/publisher.mjs";
+import "../db-queue/types.mjs";
+import { createDatabaseCaptureQueue } from "../db-queue/index.mjs";
+import { createCaptureHandler, originOf } from "../consumer/capture-handler.mjs";
+import { applyImageSettings, ensureImageEngine } from "../consumer/startup.mjs";
+import "./fork.mjs";
+import { isParentMessage } from "./protocol.mjs";
+//#region src/capture/forked/child.ts
+/**
+* Entry helper for a forked capture child (`testing.workerEntry`). The app is the consumer: it
+* polls the database queue, holds the slots and the lease, and pushes each leased job here over
+* process IPC. The child runs the whole capture pipeline for the job it is given and reports
+* `progress`, then `done` or `failed`. It never reads the queue (ADR 0006, decision 5); the only
+* thing it writes there is the shard jobs a big build fans out into, which it inserts itself.
+*
+* ```ts
+* // capture-worker.ts — the module named by `testing.workerEntry`
+* import { runCaptureChild } from "@storyshelf/core/capture";
+* await runCaptureChild({ db, storage, runner, scratchDir });
+* ```
+*/
+/**
+* Run pushed jobs until the parent stops the child.
+*
+* - `SIGTERM` / `SIGINT`: let the runs in flight finish, then exit 0.
+* - Parent gone (`disconnect`): nobody can receive results, so exit at once. Whatever was running
+*   loses its lease with the parent and is redelivered to another consumer.
+*
+* @throws When not running as a forked child (no IPC channel), or when the image engine cannot load.
+*/
+async function runCaptureChild(options, host = processHost()) {
+	const { send } = host;
+	if (!send) throw new Error("runCaptureChild must run in a forked process; set testing.workerEntry");
+	const logger = options.logger ?? createShelfLogger();
+	applyImageSettings(options.images, options.compare);
+	await ensureImageEngine(logger);
+	await wireHost(host, new CaptureChild(buildHandler(options, host.env, logger), logger, (message) => {
+		send.call(host, message);
+	}));
+	host.exit(0);
+}
+/** Feed the parent's messages to the child; resolves once a signal asked it to stop and it drained. */
+async function wireHost(host, child) {
+	const stopped = Promise.withResolvers();
+	const settle = () => {
+		stopped.resolve(null);
+	};
+	const drain = () => {
+		child.drain().then(settle, settle);
+	};
+	host.on("message", (message) => {
+		child.onMessage(message);
+	});
+	host.on("SIGTERM", drain);
+	host.on("SIGINT", drain);
+	host.on("disconnect", () => {
+		host.exit(0);
+	});
+	await stopped.promise;
+}
+/** The capture handler over the app's own adapters; shard jobs go straight onto the database queue. */
+function buildHandler(options, env, logger) {
+	const maxRetries = options.retries ?? positiveInt(env["STORYSHELF_CAPTURE_RETRIES"], 0) ?? 2;
+	const queue = createDatabaseCaptureQueue(options.db, {
+		retries: maxRetries,
+		logger: logger.child({ component: "child-queue" })
+	});
+	return createCaptureHandler({
+		db: options.db,
+		storage: options.storage,
+		runner: options.runner,
+		scratchDir: options.scratchDir,
+		notifiers: options.notifiers,
+		config: options.config,
+		buildState: options.buildState ?? notifyJobsPublisher(options, queue, logger),
+		design: options.design,
+		secret: options.secret,
+		viewports: options.viewports,
+		shardSize: options.shardSize ?? positiveInt(env["STORYSHELF_CAPTURE_SHARD_SIZE"]),
+		maxRetries,
+		enqueue: async (job) => {
+			await queue.enqueue(job);
+		},
+		logger
+	});
+}
+/** Publisher that queues one `notify` job per git channel on the database queue. */
+function notifyJobsPublisher(options, queue, logger) {
+	return createBuildStatePublisher({
+		deps: {
+			db: options.db,
+			storage: options.storage,
+			notifiers: options.notifiers ?? [],
+			secret: options.secret,
+			config: options.config ?? {},
+			publicOrigin: originOf(options),
+			flags: () => ({
+				testing: true,
+				review: false
+			}),
+			logger
+		},
+		enqueue: createNotifyEnqueuer({ db: options.db }, queue)
+	});
+}
+/** One run per pushed job; the parent decides what runs, how many at once, and when it ends. */
+var CaptureChild = class {
+	#handler;
+	#logger;
+	#send;
+	#running = /* @__PURE__ */ new Map();
+	constructor(handler, logger, send) {
+		this.#handler = handler;
+		this.#logger = logger;
+		this.#send = send;
+	}
+	onMessage(message) {
+		if (!isParentMessage(message)) return;
+		if (message.type === "run") {
+			this.#start(message.runId, message.job);
+			return;
+		}
+		const run = this.#running.get(message.runId);
+		if (run) this.#handler.cancel?.(run.job).catch(ignore);
+	}
+	/** Resolves once every run in flight has finished. */
+	async drain() {
+		while (this.#running.size > 0) await Promise.allSettled([...this.#running.values()].map(async (run) => {
+			await run.done;
+		}));
+	}
+	#start(runId, job) {
+		const done = this.#execute(runId, job).finally(() => {
+			this.#running.delete(runId);
+		});
+		this.#running.set(runId, {
+			job,
+			done
+		});
+	}
+	async #execute(runId, job) {
+		try {
+			await this.#handler.run(job, {
+				logger: this.#logger.child({
+					buildId: job.buildId,
+					jobId: job.jobId,
+					runId
+				}),
+				touch: throttled(() => {
+					this.#send({
+						type: "progress",
+						runId
+					});
+				})
+			});
+			this.#send({
+				type: "done",
+				runId
+			});
+		} catch (error) {
+			this.#send({
+				type: "failed",
+				runId,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}
+};
+/** At most one progress message per second per run: a capture logs far more often than a lease needs. */
+const PROGRESS_INTERVAL_MS = 1e3;
+function throttled(report) {
+	let last = 0;
+	return () => {
+		const now = Date.now();
+		if (now - last >= PROGRESS_INTERVAL_MS) {
+			last = now;
+			report();
+		}
+	};
+}
+function ignore() {}
+function positiveInt(value, min = 1) {
+	const parsed = Number(value);
+	return value !== void 0 && Number.isInteger(parsed) && parsed >= min ? parsed : void 0;
+}
+function processHost() {
+	return {
+		send: process.send ? (message) => process.send?.(message) : void 0,
+		on: (event, listener) => process.on(event, listener),
+		env: process.env,
+		exit: (code) => process.exit(code)
+	};
+}
+//#endregion
+export { runCaptureChild };
+
+//# sourceMappingURL=child.mjs.map

package/dist/capture/forked/child.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"child.mjs","names":[],"sources":["../../../src/capture/forked/child.ts"],"sourcesContent":["/**\n * Entry helper for a forked capture child (`testing.workerEntry`). The app is the consumer: it\n * polls the database queue, holds the slots and the lease, and pushes each leased job here over\n * process IPC. The child runs the whole capture pipeline for the job it is given and reports\n * `progress`, then `done` or `failed`. It never reads the queue (ADR 0006, decision 5); the only\n * thing it writes there is the shard jobs a big build fans out into, which it inserts itself.\n *\n * ```ts\n * // capture-worker.ts — the module named by `testing.workerEntry`\n * import { runCaptureChild } from \"@storyshelf/core/capture\";\n * await runCaptureChild({ db, storage, runner, scratchDir });\n * ```\n */\nimport { createShelfLogger, type Logger } from \"../../logger.ts\";\nimport { createNotifyEnqueuer } from \"../build-state/notify-job.ts\";\nimport { createBuildStatePublisher } from \"../build-state/publisher.ts\";\nimport type { BuildStatePublisher } from \"../build-state/types.ts\";\nimport {\n  createCaptureHandler,\n  originOf,\n  type CaptureHandlerOptions,\n} from \"../consumer/capture-handler.ts\";\nimport { applyImageSettings, ensureImageEngine } from \"../consumer/startup.ts\";\nimport type { CaptureConsumerOptions, ConsumerJob, KindHandler } from \"../consumer/types.ts\";\nimport { createDatabaseCaptureQueue, DEFAULT_RETRIES } from \"../db-queue/index.ts\";\nimport { CAPTURE_RETRIES_ENV, CAPTURE_SHARD_SIZE_ENV } from \"./fork.ts\";\nimport { isParentMessage, type ChildMessage } from \"./protocol.ts\";\n\n/** Handler options minus the shard hand-out, which the child wires to the database queue. */\nexport type CaptureChildOptions = Omit<CaptureHandlerOptions, \"enqueue\" | \"logger\"> &\n  Pick<CaptureConsumerOptions, \"images\" | \"compare\"> & {\n    logger?: Logger;\n    /** Retries stamped on shard jobs (default: the parent's `testing.retries`, handed down in the environment). */\n    retries?: number;\n  };\n\n/** The slice of `process` the child uses; injectable so the lifecycle is testable. */\nexport interface ChildHost {\n  /** Present only in a forked process with an IPC channel. */\n  send?: (message: ChildMessage) => unknown;\n  on(\n    event: \"message\" | \"disconnect\" | \"SIGTERM\" | \"SIGINT\",\n    listener: (message?: unknown) => void,\n  ): unknown;\n  env: Record<string, string | undefined>;\n  exit(code: number): void;\n}\n\n/**\n * Run pushed jobs until the parent stops the child.\n *\n * - `SIGTERM` / `SIGINT`: let the runs in flight finish, then exit 0.\n * - Parent gone (`disconnect`): nobody can receive results, so exit at once. Whatever was running\n *   loses its lease with the parent and is redelivered to another consumer.\n *\n * @throws When not running as a forked child (no IPC channel), or when the image engine cannot load.\n */\nexport async function runCaptureChild(\n  options: CaptureChildOptions,\n  host: ChildHost = processHost(),\n): Promise<void> {\n  const { send } = host;\n  if (!send) {\n    throw new Error(\"runCaptureChild must run in a forked process; set testing.workerEntry\");\n  }\n  const logger = options.logger ?? createShelfLogger();\n  applyImageSettings(options.images, options.compare);\n  await ensureImageEngine(logger);\n  const child = new CaptureChild(buildHandler(options, host.env, logger), logger, (message) => {\n    send.call(host, message);\n  });\n  const stopped = wireHost(host, child);\n  await stopped;\n  host.exit(0);\n}\n\n/** Feed the parent's messages to the child; resolves once a signal asked it to stop and it drained. */\nasync function wireHost(host: ChildHost, child: CaptureChild): Promise<void> {\n  const stopped = Promise.withResolvers<null>();\n  const settle = (): void => {\n    stopped.resolve(null);\n  };\n  const drain = (): void => {\n    child.drain().then(settle, settle);\n  };\n  host.on(\"message\", (message) => {\n    child.onMessage(message);\n  });\n  host.on(\"SIGTERM\", drain);\n  host.on(\"SIGINT\", drain);\n  host.on(\"disconnect\", () => {\n    host.exit(0);\n  });\n  await stopped.promise;\n}\n\n/** The capture handler over the app's own adapters; shard jobs go straight onto the database queue. */\nfunction buildHandler(\n  options: CaptureChildOptions,\n  env: Record<string, string | undefined>,\n  logger: Logger,\n): KindHandler {\n  const maxRetries = options.retries ?? positiveInt(env[CAPTURE_RETRIES_ENV], 0) ?? DEFAULT_RETRIES;\n  const queue = createDatabaseCaptureQueue(options.db, {\n    retries: maxRetries,\n    logger: logger.child({ component: \"child-queue\" }),\n  });\n  return createCaptureHandler({\n    db: options.db,\n    storage: options.storage,\n    runner: options.runner,\n    scratchDir: options.scratchDir,\n    notifiers: options.notifiers,\n    config: options.config,\n    // The parent's consumer runs `notify` jobs, so the child hands state deliveries to the queue.\n    buildState: options.buildState ?? notifyJobsPublisher(options, queue, logger),\n    design: options.design,\n    secret: options.secret,\n    viewports: options.viewports,\n    shardSize: options.shardSize ?? positiveInt(env[CAPTURE_SHARD_SIZE_ENV]),\n    maxRetries,\n    enqueue: async (job) => {\n      await queue.enqueue(job);\n    },\n    logger,\n  });\n}\n\n/** Publisher that queues one `notify` job per git channel on the database queue. */\nfunction notifyJobsPublisher(\n  options: CaptureChildOptions,\n  queue: ReturnType<typeof createDatabaseCaptureQueue>,\n  logger: Logger,\n): BuildStatePublisher {\n  return createBuildStatePublisher({\n    deps: {\n      db: options.db,\n      storage: options.storage,\n      notifiers: options.notifiers ?? [],\n      secret: options.secret,\n      config: options.config ?? {},\n      publicOrigin: originOf(options),\n      flags: () => ({ testing: true, review: false }),\n      logger,\n    },\n    enqueue: createNotifyEnqueuer({ db: options.db }, queue),\n  });\n}\n\n/** One run per pushed job; the parent decides what runs, how many at once, and when it ends. */\nclass CaptureChild {\n  readonly #handler: KindHandler;\n  readonly #logger: Logger;\n  readonly #send: (message: ChildMessage) => void;\n  readonly #running = new Map<string, { job: ConsumerJob; done: Promise<void> }>();\n\n  constructor(handler: KindHandler, logger: Logger, send: (message: ChildMessage) => void) {\n    this.#handler = handler;\n    this.#logger = logger;\n    this.#send = send;\n  }\n\n  onMessage(message: unknown): void {\n    if (!isParentMessage(message)) {\n      return;\n    }\n    if (message.type === \"run\") {\n      this.#start(message.runId, message.job);\n      return;\n    }\n    const run = this.#running.get(message.runId);\n    if (run) {\n      this.#handler.cancel?.(run.job).catch(ignore);\n    }\n  }\n\n  /** Resolves once every run in flight has finished. */\n  async drain(): Promise<void> {\n    while (this.#running.size > 0) {\n      // oxlint-disable-next-line no-await-in-loop -- runs started while draining join the drain\n      await Promise.allSettled(\n        [...this.#running.values()].map(async (run) => {\n          await run.done;\n        }),\n      );\n    }\n  }\n\n  #start(runId: string, job: ConsumerJob): void {\n    const done = this.#execute(runId, job).finally(() => {\n      this.#running.delete(runId);\n    });\n    this.#running.set(runId, { job, done });\n  }\n\n  async #execute(runId: string, job: ConsumerJob): Promise<void> {\n    try {\n      await this.#handler.run(job, {\n        logger: this.#logger.child({ buildId: job.buildId, jobId: job.jobId, runId }),\n        touch: throttled(() => {\n          this.#send({ type: \"progress\", runId });\n        }),\n      });\n      this.#send({ type: \"done\", runId });\n    } catch (error) {\n      this.#send({\n        type: \"failed\",\n        runId,\n        error: error instanceof Error ? error.message : String(error),\n      });\n    }\n  }\n}\n\n/** At most one progress message per second per run: a capture logs far more often than a lease needs. */\nconst PROGRESS_INTERVAL_MS = 1000;\n\nfunction throttled(report: () => void): () => void {\n  let last = 0;\n  return () => {\n    const now = Date.now();\n    if (now - last >= PROGRESS_INTERVAL_MS) {\n      last = now;\n      report();\n    }\n  };\n}\n\nfunction ignore(): void {}\n\nfunction positiveInt(value: string | undefined, min = 1): number | undefined {\n  const parsed = Number(value);\n  return value !== undefined && Number.isInteger(parsed) && parsed >= min ? parsed : undefined;\n}\n\nfunction processHost(): ChildHost {\n  return {\n    send: process.send ? (message) => process.send?.(message) : undefined,\n    on: (event, listener) => process.on(event as never, listener as never),\n    env: process.env,\n    // A forked child has to end its own process once the runs have drained.\n    // oxlint-disable-next-line unicorn/no-process-exit\n    exit: (code) => process.exit(code),\n  };\n}\n"],"mappings":"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"}

package/dist/capture/forked/crash-tracker.mjs

@@ -0,0 +1,23 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capture/forked/crash-tracker.ts
+/** Counts child crashes inside a sliding window, to tell a flaky child from a crash loop. */
+var CrashTracker = class {
+	#limit;
+	#windowMs;
+	#times = [];
+	constructor(limit, windowMs) {
+		this.#limit = limit;
+		this.#windowMs = windowMs;
+	}
+	/** Record a crash; true when this one reaches the limit within the window. */
+	record(now = Date.now()) {
+		this.#times = [...this.#times.filter((time) => now - time < this.#windowMs), now];
+		return this.#times.length >= this.#limit;
+	}
+};
+//#endregion
+export { CrashTracker };
+
+//# sourceMappingURL=crash-tracker.mjs.map

package/dist/capture/forked/crash-tracker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"crash-tracker.mjs","names":[],"sources":["../../../src/capture/forked/crash-tracker.ts"],"sourcesContent":["/** Counts child crashes inside a sliding window, to tell a flaky child from a crash loop. */\nexport class CrashTracker {\n  readonly #limit: number;\n  readonly #windowMs: number;\n  #times: number[] = [];\n\n  constructor(limit: number, windowMs: number) {\n    this.#limit = limit;\n    this.#windowMs = windowMs;\n  }\n\n  /** Record a crash; true when this one reaches the limit within the window. */\n  record(now: number = Date.now()): boolean {\n    this.#times = [...this.#times.filter((time) => now - time < this.#windowMs), now];\n    return this.#times.length >= this.#limit;\n  }\n}\n"],"mappings":";;;;;AACA,IAAa,eAAb,MAA0B;CACxB;CACA;CACA,SAAmB,CAAC;CAEpB,YAAY,OAAe,UAAkB;EAC3C,KAAK,SAAS;EACd,KAAK,YAAY;CACnB;;CAGA,OAAO,MAAc,KAAK,IAAI,GAAY;EACxC,KAAK,SAAS,CAAC,GAAG,KAAK,OAAO,QAAQ,SAAS,MAAM,OAAO,KAAK,SAAS,GAAG,GAAG;EAChF,OAAO,KAAK,OAAO,UAAU,KAAK;CACpC;AACF"}

package/dist/capture/forked/decision.d.mts

@@ -0,0 +1,26 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/capture/forked/decision.d.ts
+/** Whether a capture child is worth forking on this host (ADR 0005 phase 3 fallback rules). */
+/** What the decision looks at. */
+interface ForkHost {
+  cpus: number;
+  memoryBytes: number;
+  /** `child_process.fork` exists and works in this runtime. */
+  canFork: boolean;
+}
+/** Outcome: fork a child, or stay in-process and say why. */
+type ForkDecision = {
+  mode: "fork";
+} | {
+  mode: "in-process";
+  reason: string;
+};
+/** Smallest host that still gains from a second process: below this the child only costs memory. */
+declare const FORK_MIN_CPUS = 2;
+declare const FORK_MIN_MEMORY_BYTES: number;
+/** Pick the capture process model for a host. */
+declare function decideCaptureProcess(host: ForkHost): ForkDecision;
+//#endregion
+export { FORK_MIN_CPUS, FORK_MIN_MEMORY_BYTES, ForkDecision, ForkHost, decideCaptureProcess };
+//# sourceMappingURL=decision.d.mts.map

package/dist/capture/forked/decision.mjs

@@ -0,0 +1,27 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capture/forked/decision.ts
+/** Smallest host that still gains from a second process: below this the child only costs memory. */
+const FORK_MIN_CPUS = 2;
+const FORK_MIN_MEMORY_BYTES = 2 * 1024 ** 3;
+/** Pick the capture process model for a host. */
+function decideCaptureProcess(host) {
+	if (!host.canFork) return {
+		mode: "in-process",
+		reason: "child processes are unavailable in this runtime"
+	};
+	if (host.cpus < 2) return {
+		mode: "in-process",
+		reason: `only ${host.cpus} CPU available`
+	};
+	if (host.memoryBytes < FORK_MIN_MEMORY_BYTES) return {
+		mode: "in-process",
+		reason: "not enough memory for a second process"
+	};
+	return { mode: "fork" };
+}
+//#endregion
+export { FORK_MIN_CPUS, FORK_MIN_MEMORY_BYTES, decideCaptureProcess };
+
+//# sourceMappingURL=decision.mjs.map

package/dist/capture/forked/decision.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.mjs","names":[],"sources":["../../../src/capture/forked/decision.ts"],"sourcesContent":["/** Whether a capture child is worth forking on this host (ADR 0005 phase 3 fallback rules). */\n\n/** What the decision looks at. */\nexport interface ForkHost {\n  cpus: number;\n  memoryBytes: number;\n  /** `child_process.fork` exists and works in this runtime. */\n  canFork: boolean;\n}\n\n/** Outcome: fork a child, or stay in-process and say why. */\nexport type ForkDecision = { mode: \"fork\" } | { mode: \"in-process\"; reason: string };\n\n/** Smallest host that still gains from a second process: below this the child only costs memory. */\nexport const FORK_MIN_CPUS = 2;\nexport const FORK_MIN_MEMORY_BYTES = 2 * 1024 ** 3;\n\n/** Pick the capture process model for a host. */\nexport function decideCaptureProcess(host: ForkHost): ForkDecision {\n  if (!host.canFork) {\n    return { mode: \"in-process\", reason: \"child processes are unavailable in this runtime\" };\n  }\n  if (host.cpus < FORK_MIN_CPUS) {\n    return { mode: \"in-process\", reason: `only ${host.cpus} CPU available` };\n  }\n  if (host.memoryBytes < FORK_MIN_MEMORY_BYTES) {\n    return { mode: \"in-process\", reason: \"not enough memory for a second process\" };\n  }\n  return { mode: \"fork\" };\n}\n"],"mappings":";;;;;AAcA,MAAa,gBAAgB;AAC7B,MAAa,wBAAwB,IAAI,QAAQ;;AAGjD,SAAgB,qBAAqB,MAA8B;CACjE,IAAI,CAAC,KAAK,SACR,OAAO;EAAE,MAAM;EAAc,QAAQ;CAAkD;CAEzF,IAAI,KAAK,OAAA,GACP,OAAO;EAAE,MAAM;EAAc,QAAQ,QAAQ,KAAK,KAAK;CAAgB;CAEzE,IAAI,KAAK,cAAc,uBACrB,OAAO;EAAE,MAAM;EAAc,QAAQ;CAAyC;CAEhF,OAAO,EAAE,MAAM,OAAO;AACxB"}

package/dist/capture/forked/exit.mjs

@@ -0,0 +1,12 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capture/forked/exit.ts
+/** `signal SIGKILL` or `code 1`. */
+function describeExit(info) {
+	return info.signal ? `signal ${info.signal}` : `code ${info.code}`;
+}
+//#endregion
+export { describeExit };
+
+//# sourceMappingURL=exit.mjs.map

package/dist/capture/forked/exit.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"exit.mjs","names":[],"sources":["../../../src/capture/forked/exit.ts"],"sourcesContent":["/** How a capture child ended, as a phrase for logs and failure messages. */\n\n/** An exit as `child_process` reports it: a code, or the signal that killed the child. */\nexport interface ChildExit {\n  code: number | null;\n  signal: string | null;\n}\n\n/** `signal SIGKILL` or `code 1`. */\nexport function describeExit(info: ChildExit): string {\n  return info.signal ? `signal ${info.signal}` : `code ${info.code}`;\n}\n"],"mappings":";;;;;AASA,SAAgB,aAAa,MAAyB;CACpD,OAAO,KAAK,SAAS,UAAU,KAAK,WAAW,QAAQ,KAAK;AAC9D"}

package/dist/capture/forked/fork.d.mts

@@ -0,0 +1,31 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ChildProcessHandle } from "./channel.mjs";
+//#region src/capture/forked/fork.d.ts
+/** Environment variable the forked child sees; set to this value so a module can tell it is the child. */
+declare const CAPTURE_WORKER_ROLE = "capture-worker";
+/** Environment variable carrying the parent's `testing.retries` to the child, which stamps it on the shard jobs it queues. */
+declare const CAPTURE_RETRIES_ENV = "STORYSHELF_CAPTURE_RETRIES";
+/** Environment variable carrying the parent's `testing.shardSize` to the child, which plans big builds with it. */
+declare const CAPTURE_SHARD_SIZE_ENV = "STORYSHELF_CAPTURE_SHARD_SIZE";
+/** Whether this runtime can fork a capture child. */
+declare function canForkCaptureChild(): boolean;
+/** Options for {@link forkCaptureChild}. */
+interface ForkOptions {
+  /** Module to run in the child (`testing.workerEntry`); absolute path or `file:` URL. */
+  entry: string;
+  /** Extra environment for the child, on top of this process's. */
+  env?: Record<string, string>;
+}
+/**
+ * Fork the capture child with an IPC channel and wrap it as a {@link ChildProcessHandle}.
+ *
+ * The channel is also the lifeline: if this process dies the child sees `disconnect` and exits.
+ * An `exit` hook kills the child too, for parents that stop without a graceful teardown.
+ *
+ * @throws When the runtime cannot fork, or the fork itself throws.
+ */
+declare function forkCaptureChild(options: ForkOptions): ChildProcessHandle;
+//#endregion
+export { CAPTURE_RETRIES_ENV, CAPTURE_SHARD_SIZE_ENV, CAPTURE_WORKER_ROLE, ForkOptions, canForkCaptureChild, forkCaptureChild };
+//# sourceMappingURL=fork.d.mts.map

package/dist/capture/forked/fork.mjs

@@ -0,0 +1,93 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capture/forked/fork.ts
+/** Environment variable the forked child sees; set to this value so a module can tell it is the child. */
+const CAPTURE_WORKER_ROLE = "capture-worker";
+/** Environment variable carrying the parent's `testing.retries` to the child, which stamps it on the shard jobs it queues. */
+const CAPTURE_RETRIES_ENV = "STORYSHELF_CAPTURE_RETRIES";
+/** Environment variable carrying the parent's `testing.shardSize` to the child, which plans big builds with it. */
+const CAPTURE_SHARD_SIZE_ENV = "STORYSHELF_CAPTURE_SHARD_SIZE";
+/** Grace between SIGTERM and SIGKILL when the parent stops a child. */
+const KILL_ESCALATION_MS = 3e4;
+/** `node:child_process`, or undefined where the runtime has none (edge, browsers). Loaded synchronously. */
+function childProcessModule() {
+	const getBuiltin = process.getBuiltinModule;
+	return typeof getBuiltin === "function" ? getBuiltin.call(process, "node:child_process") : void 0;
+}
+/** Whether this runtime can fork a capture child. */
+function canForkCaptureChild() {
+	return typeof childProcessModule()?.fork === "function";
+}
+/**
+* Fork the capture child with an IPC channel and wrap it as a {@link ChildProcessHandle}.
+*
+* The channel is also the lifeline: if this process dies the child sees `disconnect` and exits.
+* An `exit` hook kills the child too, for parents that stop without a graceful teardown.
+*
+* @throws When the runtime cannot fork, or the fork itself throws.
+*/
+function forkCaptureChild(options) {
+	const childProcess = childProcessModule();
+	if (!childProcess) throw new Error("child processes are not available in this runtime");
+	const child = childProcess.fork(options.entry, [], {
+		env: {
+			...process.env,
+			...options.env,
+			STORYSHELF_ROLE: CAPTURE_WORKER_ROLE
+		},
+		serialization: "json",
+		stdio: [
+			"inherit",
+			"inherit",
+			"inherit",
+			"ipc"
+		]
+	});
+	const stopOnExit = () => {
+		child.kill("SIGKILL");
+	};
+	process.once("exit", stopOnExit);
+	return wrap(child, stopOnExit);
+}
+function wrap(child, stopOnExit) {
+	return {
+		send: (message) => {
+			if (child.connected) child.send(message);
+		},
+		onMessage: (listener) => {
+			child.on("message", listener);
+		},
+		onExit: (listener) => {
+			let reported = false;
+			const report = (code, signal) => {
+				if (!reported) {
+					reported = true;
+					process.off("exit", stopOnExit);
+					listener({
+						code,
+						signal
+					});
+				}
+			};
+			child.once("exit", report);
+			child.once("error", () => {
+				report(1, null);
+			});
+		},
+		kill: (force) => {
+			if (force) {
+				child.kill("SIGKILL");
+				return;
+			}
+			child.kill("SIGTERM");
+			setTimeout(() => {
+				if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+			}, KILL_ESCALATION_MS).unref();
+		}
+	};
+}
+//#endregion
+export { CAPTURE_RETRIES_ENV, CAPTURE_SHARD_SIZE_ENV, CAPTURE_WORKER_ROLE, canForkCaptureChild, forkCaptureChild };
+
+//# sourceMappingURL=fork.mjs.map

package/dist/capture/forked/fork.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork.mjs","names":[],"sources":["../../../src/capture/forked/fork.ts"],"sourcesContent":["/** The real `child_process.fork` behind {@link ChildProcessHandle}. */\nimport type { ChildProcess } from \"node:child_process\";\nimport type { ChildProcessHandle } from \"./channel.ts\";\nimport type { ParentMessage } from \"./protocol.ts\";\n\n/** Environment variable the forked child sees; set to this value so a module can tell it is the child. */\nexport const CAPTURE_WORKER_ROLE = \"capture-worker\";\n\n/** Environment variable carrying the parent's `testing.retries` to the child, which stamps it on the shard jobs it queues. */\nexport const CAPTURE_RETRIES_ENV = \"STORYSHELF_CAPTURE_RETRIES\";\n\n/** Environment variable carrying the parent's `testing.shardSize` to the child, which plans big builds with it. */\nexport const CAPTURE_SHARD_SIZE_ENV = \"STORYSHELF_CAPTURE_SHARD_SIZE\";\n\n/** Grace between SIGTERM and SIGKILL when the parent stops a child. */\nconst KILL_ESCALATION_MS = 30_000;\n\ntype ChildProcessModule = typeof import(\"node:child_process\");\n\n/** `node:child_process`, or undefined where the runtime has none (edge, browsers). Loaded synchronously. */\nfunction childProcessModule(): ChildProcessModule | undefined {\n  const getBuiltin = (process as { getBuiltinModule?: (id: string) => unknown }).getBuiltinModule;\n  return typeof getBuiltin === \"function\"\n    ? (getBuiltin.call(process, \"node:child_process\") as ChildProcessModule | undefined)\n    : undefined;\n}\n\n/** Whether this runtime can fork a capture child. */\nexport function canForkCaptureChild(): boolean {\n  return typeof childProcessModule()?.fork === \"function\";\n}\n\n/** Options for {@link forkCaptureChild}. */\nexport interface ForkOptions {\n  /** Module to run in the child (`testing.workerEntry`); absolute path or `file:` URL. */\n  entry: string;\n  /** Extra environment for the child, on top of this process's. */\n  env?: Record<string, string>;\n}\n\n/**\n * Fork the capture child with an IPC channel and wrap it as a {@link ChildProcessHandle}.\n *\n * The channel is also the lifeline: if this process dies the child sees `disconnect` and exits.\n * An `exit` hook kills the child too, for parents that stop without a graceful teardown.\n *\n * @throws When the runtime cannot fork, or the fork itself throws.\n */\nexport function forkCaptureChild(options: ForkOptions): ChildProcessHandle {\n  const childProcess = childProcessModule();\n  if (!childProcess) {\n    throw new Error(\"child processes are not available in this runtime\");\n  }\n  const child = childProcess.fork(options.entry, [], {\n    env: { ...process.env, ...options.env, STORYSHELF_ROLE: CAPTURE_WORKER_ROLE },\n    serialization: \"json\",\n    stdio: [\"inherit\", \"inherit\", \"inherit\", \"ipc\"],\n  });\n  const stopOnExit = (): void => {\n    child.kill(\"SIGKILL\");\n  };\n  process.once(\"exit\", stopOnExit);\n  return wrap(child, stopOnExit);\n}\n\nfunction wrap(child: ChildProcess, stopOnExit: () => void): ChildProcessHandle {\n  return {\n    send: (message: ParentMessage): void => {\n      if (child.connected) {\n        child.send(message);\n      }\n    },\n    onMessage: (listener) => {\n      child.on(\"message\", listener);\n    },\n    onExit: (listener) => {\n      let reported = false;\n      const report = (code: number | null, signal: string | null): void => {\n        if (!reported) {\n          reported = true;\n          process.off(\"exit\", stopOnExit);\n          listener({ code, signal });\n        }\n      };\n      child.once(\"exit\", report);\n      // A child that never started emits `error` and no `exit`.\n      child.once(\"error\", () => {\n        report(1, null);\n      });\n    },\n    kill: (force) => {\n      if (force) {\n        child.kill(\"SIGKILL\");\n        return;\n      }\n      child.kill(\"SIGTERM\");\n      setTimeout(() => {\n        if (child.exitCode === null && child.signalCode === null) {\n          child.kill(\"SIGKILL\");\n        }\n      }, KILL_ESCALATION_MS).unref();\n    },\n  };\n}\n"],"mappings":";;;;;AAMA,MAAa,sBAAsB;;AAGnC,MAAa,sBAAsB;;AAGnC,MAAa,yBAAyB;;AAGtC,MAAM,qBAAqB;;AAK3B,SAAS,qBAAqD;CAC5D,MAAM,aAAc,QAA2D;CAC/E,OAAO,OAAO,eAAe,aACxB,WAAW,KAAK,SAAS,oBAAoB,IAC9C,KAAA;AACN;;AAGA,SAAgB,sBAA+B;CAC7C,OAAO,OAAO,mBAAmB,CAAC,EAAE,SAAS;AAC/C;;;;;;;;;AAkBA,SAAgB,iBAAiB,SAA0C;CACzE,MAAM,eAAe,mBAAmB;CACxC,IAAI,CAAC,cACH,MAAM,IAAI,MAAM,mDAAmD;CAErE,MAAM,QAAQ,aAAa,KAAK,QAAQ,OAAO,CAAC,GAAG;EACjD,KAAK;GAAE,GAAG,QAAQ;GAAK,GAAG,QAAQ;GAAK,iBAAiB;EAAoB;EAC5E,eAAe;EACf,OAAO;GAAC;GAAW;GAAW;GAAW;EAAK;CAChD,CAAC;CACD,MAAM,mBAAyB;EAC7B,MAAM,KAAK,SAAS;CACtB;CACA,QAAQ,KAAK,QAAQ,UAAU;CAC/B,OAAO,KAAK,OAAO,UAAU;AAC/B;AAEA,SAAS,KAAK,OAAqB,YAA4C;CAC7E,OAAO;EACL,OAAO,YAAiC;GACtC,IAAI,MAAM,WACR,MAAM,KAAK,OAAO;EAEtB;EACA,YAAY,aAAa;GACvB,MAAM,GAAG,WAAW,QAAQ;EAC9B;EACA,SAAS,aAAa;GACpB,IAAI,WAAW;GACf,MAAM,UAAU,MAAqB,WAAgC;IACnE,IAAI,CAAC,UAAU;KACb,WAAW;KACX,QAAQ,IAAI,QAAQ,UAAU;KAC9B,SAAS;MAAE;MAAM;KAAO,CAAC;IAC3B;GACF;GACA,MAAM,KAAK,QAAQ,MAAM;GAEzB,MAAM,KAAK,eAAe;IACxB,OAAO,GAAG,IAAI;GAChB,CAAC;EACH;EACA,OAAO,UAAU;GACf,IAAI,OAAO;IACT,MAAM,KAAK,SAAS;IACpB;GACF;GACA,MAAM,KAAK,SAAS;GACpB,iBAAiB;IACf,IAAI,MAAM,aAAa,QAAQ,MAAM,eAAe,MAClD,MAAM,KAAK,SAAS;GAExB,GAAG,kBAAkB,CAAC,CAAC,MAAM;EAC/B;CACF;AACF"}