@storyshelf/core 0.6.2 → 0.8.0

package/dist/capture/scratch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch.mjs","names":[],"sources":["../../src/capture/scratch.ts"],"sourcesContent":["/** Per-build scratch directories: where they live, removing them, and sweeping crash leftovers. */\nimport { readdir, rm, rmdir, stat } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type { Logger } from \"../logger.ts\";\n\n/**\n * Subtree of `scratchDir` that holds extracted Storybooks.\n *\n * `scratchDir` is often also the local storage root (dev server, generated servers), where\n * `<project>/builds/<build>/...` holds screenshots and published statics. Keeping scratch in its\n * own subtree means removing it can never touch a storage key.\n */\nexport const SCRATCH_DIRNAME = \".storyshelf-scratch\";\n\n/** Scratch dirs untouched for this long are assumed orphaned by a crash (no capture runs this long). */\nexport const SCRATCH_MAX_AGE_MS = 6 * 60 * 60 * 1000;\n\n/** Directory inside a build's scratch directory that holds one subdirectory per shard. */\nconst SHARDS_DIRNAME = \"shards\";\n\n/** Directory inside a build's scratch directory for the build's own job, apart from its shards. */\nconst JOB_DIRNAME = \"job\";\n\n/** Scratch directory owned by one build: `<scratchDir>/.storyshelf-scratch/<projectId>/<buildId>`. */\nexport function buildScratchDir(scratchDir: string, projectId: string, buildId: string): string {\n  return join(scratchDir, SCRATCH_DIRNAME, projectId, buildId);\n}\n\n/** Scratch directory of the build's own job (plan or whole build): `<build>/job`, beside `shards/`. */\nexport function jobScratchDir(scratchDir: string, projectId: string, buildId: string): string {\n  return join(buildScratchDir(scratchDir, projectId, buildId), JOB_DIRNAME);\n}\n\n/** Scratch directory of one shard of a build, inside the build's: shards of a build can share a host. */\nexport function shardScratchDir(\n  scratchDir: string,\n  projectId: string,\n  buildId: string,\n  shardId: string,\n): string {\n  return join(buildScratchDir(scratchDir, projectId, buildId), SHARDS_DIRNAME, shardId);\n}\n\n/**\n * Remove one shard's scratch directory, leaving the build's other shards alone, then the build's\n * directories if that left them empty: whichever shard finishes last tidies up. Best effort.\n */\nexport async function removeShardScratch(\n  scratchDir: string,\n  projectId: string,\n  buildId: string,\n  shardId: string,\n  logger?: Logger,\n): Promise<void> {\n  try {\n    await rm(shardScratchDir(scratchDir, projectId, buildId, shardId), {\n      recursive: true,\n      force: true,\n    });\n    await pruneBuildScratch(scratchDir, projectId, buildId);\n  } catch (error) {\n    logger?.warn({ err: error, buildId, shardId }, \"failed to remove shard scratch directory\");\n  }\n}\n\n/**\n * Remove the scratch of the build's own job (the plan, or the whole build when it is not sharded)\n * and the build directory too if nothing else is left in it.\n *\n * Shards live in their own `shards/` directory beside `job/`, so this can never reach one: the plan\n * hands its shards to the queue before it cleans up, and a worker may already be extracting.\n */\nexport async function removeJobScratch(\n  scratchDir: string,\n  projectId: string,\n  buildId: string,\n  logger?: Logger,\n): Promise<void> {\n  try {\n    await rm(jobScratchDir(scratchDir, projectId, buildId), { recursive: true, force: true });\n    await pruneBuildScratch(scratchDir, projectId, buildId);\n  } catch (error) {\n    logger?.warn({ err: error, buildId }, \"failed to remove job scratch directory\");\n  }\n}\n\n/**\n * Remove the build's scratch directories that are empty, and nothing that is not. A shard that is\n * still running (a redelivered duplicate of one that already finished) keeps its directory; its own\n * cleanup, or the boot sweep, removes it later. `rmdir` fails on a non-empty directory, which is\n * the point.\n */\nexport async function pruneBuildScratch(\n  scratchDir: string,\n  projectId: string,\n  buildId: string,\n): Promise<void> {\n  const buildDir = buildScratchDir(scratchDir, projectId, buildId);\n  await rmdir(join(buildDir, SHARDS_DIRNAME)).catch(ignore);\n  await rmdir(buildDir).catch(ignore);\n}\n\n/** Remove a build's scratch directory. Best effort: a failure is logged, never thrown. */\nexport async function removeBuildScratch(\n  scratchDir: string,\n  projectId: string,\n  buildId: string,\n  logger?: Logger,\n): Promise<void> {\n  try {\n    await rm(buildScratchDir(scratchDir, projectId, buildId), { recursive: true, force: true });\n  } catch (error) {\n    logger?.warn({ err: error, buildId }, \"failed to remove build scratch directory\");\n  }\n}\n\n/** Options for {@link sweepOrphanedScratch}. */\nexport interface ScratchSweepOptions {\n  /** Remove build scratch dirs not modified for this long (default {@link SCRATCH_MAX_AGE_MS}). */\n  maxAgeMs?: number;\n  /** Clock override for tests. */\n  now?: number;\n  logger?: Logger;\n}\n\n/**\n * Boot-time sweep for scratch dirs a crash left behind. Age-gated rather than wholesale so a\n * second process sharing the same `scratchDir` (server plus worker) keeps its live captures.\n *\n * @returns How many build scratch directories were removed.\n */\nexport async function sweepOrphanedScratch(\n  scratchDir: string,\n  options: ScratchSweepOptions = {},\n): Promise<number> {\n  const root = join(scratchDir, SCRATCH_DIRNAME);\n  const cutoff = (options.now ?? Date.now()) - (options.maxAgeMs ?? SCRATCH_MAX_AGE_MS);\n  const projects = await readdir(root).catch(() => [] as string[]);\n  const removed = await Promise.all(\n    projects.map(async (projectId) => await sweepProject(join(root, projectId), cutoff)),\n  );\n  const total = removed.reduce((sum, count) => sum + count, 0);\n  if (total > 0) {\n    options.logger?.info({ removed: total }, \"removed orphaned capture scratch directories\");\n  }\n  return total;\n}\n\nasync function sweepProject(projectDir: string, cutoff: number): Promise<number> {\n  const builds = await readdir(projectDir).catch(() => [] as string[]);\n  const results = await Promise.all(\n    builds.map(async (buildId) => await sweepBuild(join(projectDir, buildId), cutoff)),\n  );\n  // Drop the project dir once empty; `rmdir` semantics via a non-recursive remove that fails if not.\n  if ((await readdir(projectDir).catch(() => [\"x\"])).length === 0) {\n    await rm(projectDir, { recursive: true, force: true }).catch(ignore);\n  }\n  return results.filter(Boolean).length;\n}\n\nasync function sweepBuild(buildDir: string, cutoff: number): Promise<boolean> {\n  try {\n    if ((await stat(buildDir)).mtimeMs >= cutoff) {\n      return false;\n    }\n    await rm(buildDir, { recursive: true, force: true });\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nfunction ignore(): void {}\n"],"mappings":"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"}

package/dist/capture/shard-plan.mjs

@@ -0,0 +1,127 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+// src/capture/shard-plan.ts
+/**
+* Split the work into shards of about `size` captures, keeping a story's engines together so
+* a newly enabled engine can still bootstrap from its counterpart in the same shard.
+*
+* Returns `[]` when sharding is off or the build is too small to be worth it (up to twice the
+* shard size runs as one shard, exactly as before).
+*
+* Without timings the slices are contiguous runs of stories in their original order. Given
+* `weightOf`, the stories are packed longest-first into shards of equal capture capacity and the
+* shards come back heaviest first, so the slow work starts early and no shard straggles.
+*
+* @param work - Per-engine render lists, primary engine first.
+* @param capturesOf - Captures one story produces on one engine (its viewport count).
+* @param size - Target captures per shard; undefined or below 1 turns sharding off.
+* @param weightOf - What a story cost last time, in milliseconds; unknown for a story returns undefined.
+*/
+function planShards(work, capturesOf, size, weightOf) {
+	if (!size || !worthSharding(work, capturesOf, size)) return [];
+	const costs = storyCosts(work, capturesOf);
+	const weights = weightOf ? weighted(costs, weightOf) : void 0;
+	return (weights ? packLongestFirst(costs, weights, size) : sliceByCost(costs, size)).map((ids) => restrictTo(work, new Set(ids)));
+}
+/**
+* Whether {@link planShards} would split this work at all: sharding is on (`size` of at least 1)
+* and the work is more than twice the shard size. Lets the plan stage skip work only an ordering needs.
+*/
+function worthSharding(work, capturesOf, size) {
+	return size !== void 0 && size >= 1 && totalCaptures(work, capturesOf) > size * 2;
+}
+/** Total captures the work produces. */
+function totalCaptures(work, capturesOf) {
+	return [...storyCosts(work, capturesOf).values()].reduce((sum, cost) => sum + cost, 0);
+}
+/** Captures per story id, summed over the engines that render it, in first-seen order. */
+function storyCosts(work, capturesOf) {
+	const costs = /* @__PURE__ */ new Map();
+	for (const engine of work) for (const story of engine.stories) costs.set(story.id, (costs.get(story.id) ?? 0) + capturesOf(story));
+	return costs;
+}
+/**
+* What each story is expected to cost in milliseconds. A story nothing is known about is priced at
+* the average cost of one capture, so a new story is treated as ordinary rather than free.
+*/
+function weighted(costs, weightOf) {
+	const known = [...costs.keys()].flatMap((id) => {
+		const weight = weightOf(id);
+		return typeof weight === "number" && weight > 0 ? [[id, weight]] : [];
+	});
+	if (known.length === 0) return;
+	const knownCaptures = known.reduce((sum, [id]) => sum + (costs.get(id) ?? 0), 0);
+	const perCapture = known.reduce((sum, [, weight]) => sum + weight, 0) / Math.max(knownCaptures, 1);
+	const weights = new Map(known);
+	for (const [id, captures] of costs) if (!weights.has(id)) weights.set(id, perCapture * captures);
+	return weights;
+}
+/**
+* Longest-processing-time packing: the dearest stories are placed first, each into the shard that
+* has the least work so far and still has room for its captures. Shards come back heaviest first.
+*/
+function packLongestFirst(costs, weights, size) {
+	const count = Math.max(1, Math.ceil(sumOf(costs) / size));
+	const bins = Array.from({ length: count }, newBin);
+	for (const id of byWeightDescending(costs, weights)) {
+		const captures = costs.get(id) ?? 0;
+		const bin = binFor(bins, captures, size);
+		bin.ids.push(id);
+		bin.captures += captures;
+		bin.weight += weights.get(id) ?? 0;
+	}
+	return bins.filter((bin) => bin.ids.length > 0).toSorted((left, right) => right.weight - left.weight).map((bin) => bin.ids);
+}
+/** Story ids dearest first; equal cost keeps the order they were planned in. */
+function byWeightDescending(costs, weights) {
+	return [...costs.keys()].toSorted((left, right) => (weights.get(right) ?? 0) - (weights.get(left) ?? 0));
+}
+function newBin() {
+	return {
+		ids: [],
+		captures: 0,
+		weight: 0
+	};
+}
+/**
+* The shard with the least work that still has room for `captures`. When none has room the last
+* stories did not fit anywhere, so a shard is added: one more beats overfilling one, just as an
+* oversized story gets a shard of its own when there are no timings.
+*/
+function binFor(bins, captures, size) {
+	const [lightest] = bins.filter((bin) => bin.captures + captures <= size).toSorted((left, right) => left.weight - right.weight);
+	if (lightest) return lightest;
+	const fresh = newBin();
+	bins.push(fresh);
+	return fresh;
+}
+function sumOf(costs) {
+	return [...costs.values()].reduce((sum, cost) => sum + cost, 0);
+}
+/** Contiguous runs of ids whose cost stays within `size` (a single oversized story gets its own). */
+function sliceByCost(costs, size) {
+	const slices = [];
+	for (const id of costs.keys()) {
+		const cost = costs.get(id) ?? 0;
+		const last = slices.at(-1);
+		if (last && last.used + cost <= size) {
+			last.ids.push(id);
+			last.used += cost;
+		} else slices.push({
+			ids: [id],
+			used: cost
+		});
+	}
+	return slices.map((slice) => slice.ids);
+}
+/** The work restricted to some stories; engines left with nothing to render are dropped. */
+function restrictTo(work, ids) {
+	return work.map((engine) => ({
+		browser: engine.browser,
+		stories: engine.stories.filter((story) => ids.has(story.id))
+	})).filter((engine) => engine.stories.length > 0);
+}
+export { planShards, totalCaptures, worthSharding };
+
+//# sourceMappingURL=shard-plan.mjs.map

package/dist/capture/shard-plan.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"shard-plan.mjs","names":[],"sources":["../../src/capture/shard-plan.ts"],"sourcesContent":["/** Splitting a build's render work into shards (ADR 0005 phase 5). Pure: no I/O, no clock. */\nimport type { CaptureTarget } from \"../adapters/capture-runner.ts\";\nimport type { StoryEntry, Viewport } from \"./adapter.ts\";\n\n/** What one engine has to render this build (after affected-capture partitioning). */\nexport interface EngineWork {\n  browser: CaptureTarget;\n  stories: StoryEntry[];\n}\n\n/** One render shard: a slice of stories, with the engines each of them is rendered on. */\nexport interface ShardPayload {\n  /** Engines of the slice, primary first; each lists only the stories it renders. */\n  browsers: EngineWork[];\n  /** Viewports the stories resolve against. */\n  viewports: Viewport[];\n  /** Engines with no baseline yet when the plan was made (fixed at plan time, not per shard). */\n  fresh: string[];\n}\n\n/** Settings of the plan itself, kept on the plan row. */\nexport interface PlanPayload {\n  browsers: string[];\n  fresh: string[];\n  /** Captures per shard the plan aimed for. */\n  shardSize: number;\n  /** Captures (story x viewport x engine) the plan covers. */\n  total: number;\n}\n\n/** Outcome of one render shard, kept on its row. */\nexport interface ShardResult {\n  failedStoryIds: string[];\n  flakyStoryIds: string[];\n  a11yStoryIds: string[];\n  captured: number;\n  durationMs: number;\n}\n\n/** Outcome of the plan stage: every story of the build, and stories whose inherited snapshot failed. */\nexport interface PlanResult {\n  storyIds: string[];\n  failedStoryIds: string[];\n}\n\n/**\n * Split the work into shards of about `size` captures, keeping a story's engines together so\n * a newly enabled engine can still bootstrap from its counterpart in the same shard.\n *\n * Returns `[]` when sharding is off or the build is too small to be worth it (up to twice the\n * shard size runs as one shard, exactly as before).\n *\n * Without timings the slices are contiguous runs of stories in their original order. Given\n * `weightOf`, the stories are packed longest-first into shards of equal capture capacity and the\n * shards come back heaviest first, so the slow work starts early and no shard straggles.\n *\n * @param work - Per-engine render lists, primary engine first.\n * @param capturesOf - Captures one story produces on one engine (its viewport count).\n * @param size - Target captures per shard; undefined or below 1 turns sharding off.\n * @param weightOf - What a story cost last time, in milliseconds; unknown for a story returns undefined.\n */\nexport function planShards(\n  work: readonly EngineWork[],\n  capturesOf: (story: StoryEntry) => number,\n  size: number | undefined,\n  weightOf?: (storyId: string) => number | undefined,\n): EngineWork[][] {\n  if (!size || !worthSharding(work, capturesOf, size)) {\n    return [];\n  }\n  const costs = storyCosts(work, capturesOf);\n  const weights = weightOf ? weighted(costs, weightOf) : undefined;\n  const slices = weights ? packLongestFirst(costs, weights, size) : sliceByCost(costs, size);\n  return slices.map((ids) => restrictTo(work, new Set(ids)));\n}\n\n/**\n * Whether {@link planShards} would split this work at all: sharding is on (`size` of at least 1)\n * and the work is more than twice the shard size. Lets the plan stage skip work only an ordering needs.\n */\nexport function worthSharding(\n  work: readonly EngineWork[],\n  capturesOf: (story: StoryEntry) => number,\n  size: number | undefined,\n): boolean {\n  return size !== undefined && size >= 1 && totalCaptures(work, capturesOf) > size * 2;\n}\n\n/** Total captures the work produces. */\nexport function totalCaptures(\n  work: readonly EngineWork[],\n  capturesOf: (story: StoryEntry) => number,\n): number {\n  return [...storyCosts(work, capturesOf).values()].reduce((sum, cost) => sum + cost, 0);\n}\n\n/** Captures per story id, summed over the engines that render it, in first-seen order. */\nfunction storyCosts(\n  work: readonly EngineWork[],\n  capturesOf: (story: StoryEntry) => number,\n): Map<string, number> {\n  const costs = new Map<string, number>();\n  for (const engine of work) {\n    for (const story of engine.stories) {\n      costs.set(story.id, (costs.get(story.id) ?? 0) + capturesOf(story));\n    }\n  }\n  return costs;\n}\n\n/**\n * What each story is expected to cost in milliseconds. A story nothing is known about is priced at\n * the average cost of one capture, so a new story is treated as ordinary rather than free.\n */\nfunction weighted(\n  costs: Map<string, number>,\n  weightOf: (storyId: string) => number | undefined,\n): Map<string, number> | undefined {\n  const known = [...costs.keys()].flatMap((id) => {\n    const weight = weightOf(id);\n    return typeof weight === \"number\" && weight > 0 ? [[id, weight] as const] : [];\n  });\n  if (known.length === 0) {\n    return undefined;\n  }\n  const knownCaptures = known.reduce((sum, [id]) => sum + (costs.get(id) ?? 0), 0);\n  const perCapture =\n    known.reduce((sum, [, weight]) => sum + weight, 0) / Math.max(knownCaptures, 1);\n  const weights = new Map(known);\n  for (const [id, captures] of costs) {\n    if (!weights.has(id)) {\n      weights.set(id, perCapture * captures);\n    }\n  }\n  return weights;\n}\n\n/**\n * Longest-processing-time packing: the dearest stories are placed first, each into the shard that\n * has the least work so far and still has room for its captures. Shards come back heaviest first.\n */\nfunction packLongestFirst(\n  costs: Map<string, number>,\n  weights: Map<string, number>,\n  size: number,\n): string[][] {\n  const count = Math.max(1, Math.ceil(sumOf(costs) / size));\n  const bins: Bin[] = Array.from({ length: count }, newBin);\n  for (const id of byWeightDescending(costs, weights)) {\n    const captures = costs.get(id) ?? 0;\n    const bin = binFor(bins, captures, size);\n    bin.ids.push(id);\n    bin.captures += captures;\n    bin.weight += weights.get(id) ?? 0;\n  }\n  return bins\n    .filter((bin) => bin.ids.length > 0)\n    .toSorted((left, right) => right.weight - left.weight)\n    .map((bin) => bin.ids);\n}\n\n/** Story ids dearest first; equal cost keeps the order they were planned in. */\nfunction byWeightDescending(costs: Map<string, number>, weights: Map<string, number>): string[] {\n  return [...costs.keys()].toSorted(\n    (left, right) => (weights.get(right) ?? 0) - (weights.get(left) ?? 0),\n  );\n}\n\n/** One shard being filled: the stories in it, their captures and what they are expected to cost. */\ninterface Bin {\n  ids: string[];\n  captures: number;\n  weight: number;\n}\n\nfunction newBin(): Bin {\n  return { ids: [], captures: 0, weight: 0 };\n}\n\n/**\n * The shard with the least work that still has room for `captures`. When none has room the last\n * stories did not fit anywhere, so a shard is added: one more beats overfilling one, just as an\n * oversized story gets a shard of its own when there are no timings.\n */\nfunction binFor(bins: Bin[], captures: number, size: number): Bin {\n  const withRoom = bins.filter((bin) => bin.captures + captures <= size);\n  const [lightest] = withRoom.toSorted((left, right) => left.weight - right.weight);\n  if (lightest) {\n    return lightest;\n  }\n  const fresh = newBin();\n  bins.push(fresh);\n  return fresh;\n}\n\nfunction sumOf(costs: Map<string, number>): number {\n  return [...costs.values()].reduce((sum, cost) => sum + cost, 0);\n}\n\n/** Contiguous runs of ids whose cost stays within `size` (a single oversized story gets its own). */\nfunction sliceByCost(costs: Map<string, number>, size: number): string[][] {\n  const slices: { ids: string[]; used: number }[] = [];\n  for (const id of costs.keys()) {\n    const cost = costs.get(id) ?? 0;\n    const last = slices.at(-1);\n    if (last && last.used + cost <= size) {\n      last.ids.push(id);\n      last.used += cost;\n    } else {\n      slices.push({ ids: [id], used: cost });\n    }\n  }\n  return slices.map((slice) => slice.ids);\n}\n\n/** The work restricted to some stories; engines left with nothing to render are dropped. */\nfunction restrictTo(work: readonly EngineWork[], ids: ReadonlySet<string>): EngineWork[] {\n  return work\n    .map((engine) => ({\n      browser: engine.browser,\n      stories: engine.stories.filter((story) => ids.has(story.id)),\n    }))\n    .filter((engine) => engine.stories.length > 0);\n}\n"],"mappings":"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"}

package/dist/capture/shards/context.mjs

@@ -0,0 +1,51 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { storybookUrlSource } from "../storybook-urls.mjs";
+// src/capture/shards/context.ts
+/** A capture context for the persist and finalize steps of one stage. */
+function contextOf(target, parts) {
+	const { options } = target;
+	return {
+		db: options.db,
+		tables: options.tables,
+		storage: options.storage,
+		project: target.project,
+		build: target.build,
+		viewports: parts.viewports,
+		browsers: parts.browsers,
+		captures: parts.captures ?? [],
+		inherited: parts.inherited ?? [],
+		...parts.freshBrowsers ? { freshBrowsers: parts.freshBrowsers } : {},
+		progress: parts.progress,
+		...options.logger ? { logger: options.logger } : {},
+		...options.secret ? { secret: options.secret } : {}
+	};
+}
+/** The matrix input for rendering `stories` from `storybookDir` on `browsers`. */
+function matrixInputOf(target, parts) {
+	const { options } = target;
+	return {
+		db: options.db,
+		storage: options.storage,
+		tables: options.tables,
+		runner: options.runner,
+		build: target.build,
+		project: target.project,
+		stories: parts.stories,
+		viewports: parts.viewports,
+		storybookDir: parts.storybookDir,
+		browsers: parts.browsers,
+		affectedPaths: parts.affectedPaths,
+		renderTimeoutMs: options.renderTimeoutMs,
+		storybookUrl: storybookUrlSource(options, target),
+		logger: parts.logger ?? options.logger,
+		recordLog: parts.recordLog,
+		progress: parts.progress,
+		runId: parts.runId,
+		shardIndex: parts.shardIndex
+	};
+}
+export { contextOf, matrixInputOf };
+
+//# sourceMappingURL=context.mjs.map

package/dist/capture/shards/context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.mjs","names":[],"sources":["../../../src/capture/shards/context.ts"],"sourcesContent":["/** What every stage of a sharded capture works against. */\nimport type { Logger } from \"pino\";\nimport type { CaptureTarget } from \"../../adapters/capture-runner.ts\";\nimport type { Build } from \"../../schema/build.ts\";\nimport type { Project } from \"../../schema/project.ts\";\nimport type { Viewport } from \"../adapter.ts\";\nimport type { MatrixInput } from \"../matrix.ts\";\nimport type { CaptureJobOptions } from \"../orchestrator.ts\";\nimport type { CaptureContext } from \"../pipeline.ts\";\nimport type { CaptureProgress } from \"../progress.ts\";\nimport { storybookUrlSource } from \"../storybook-urls.ts\";\n\n/** The build being captured and the adapters to capture it with. */\nexport interface ShardTarget {\n  options: CaptureJobOptions;\n  build: Build;\n  project: Project;\n}\n\n/** A capture context for the persist and finalize steps of one stage. */\nexport function contextOf(\n  target: ShardTarget,\n  parts: {\n    viewports: Viewport[];\n    browsers: CaptureTarget[];\n    captures?: CaptureContext[\"captures\"];\n    inherited?: NonNullable<CaptureContext[\"inherited\"]>;\n    freshBrowsers?: ReadonlySet<string>;\n    progress?: CaptureProgress | undefined;\n  },\n): CaptureContext {\n  const { options } = target;\n  return {\n    db: options.db,\n    tables: options.tables,\n    storage: options.storage,\n    project: target.project,\n    build: target.build,\n    viewports: parts.viewports,\n    browsers: parts.browsers,\n    captures: parts.captures ?? [],\n    inherited: parts.inherited ?? [],\n    ...(parts.freshBrowsers ? { freshBrowsers: parts.freshBrowsers } : {}),\n    progress: parts.progress,\n    ...(options.logger ? { logger: options.logger } : {}),\n    ...(options.secret ? { secret: options.secret } : {}),\n  };\n}\n\n/** The matrix input for rendering `stories` from `storybookDir` on `browsers`. */\nexport function matrixInputOf(\n  target: ShardTarget,\n  parts: {\n    stories: MatrixInput[\"stories\"];\n    viewports: Viewport[];\n    browsers: CaptureTarget[];\n    storybookDir: string;\n    affectedPaths: string[] | null;\n    logger?: Logger | undefined;\n    recordLog?: MatrixInput[\"recordLog\"];\n    progress?: CaptureProgress | undefined;\n    runId?: string | undefined;\n    shardIndex?: number | undefined;\n  },\n): MatrixInput {\n  const { options } = target;\n  return {\n    db: options.db,\n    storage: options.storage,\n    tables: options.tables,\n    runner: options.runner,\n    build: target.build,\n    project: target.project,\n    stories: parts.stories,\n    viewports: parts.viewports,\n    storybookDir: parts.storybookDir,\n    browsers: parts.browsers,\n    affectedPaths: parts.affectedPaths,\n    renderTimeoutMs: options.renderTimeoutMs,\n    storybookUrl: storybookUrlSource(options, target),\n    logger: parts.logger ?? options.logger,\n    recordLog: parts.recordLog,\n    progress: parts.progress,\n    runId: parts.runId,\n    shardIndex: parts.shardIndex,\n  };\n}\n"],"mappings":";;;;;;AAoBA,SAAgB,UACd,QACA,OAQgB;CAChB,MAAM,EAAE,YAAY;CACpB,OAAO;EACL,IAAI,QAAQ;EACZ,QAAQ,QAAQ;EAChB,SAAS,QAAQ;EACjB,SAAS,OAAO;EAChB,OAAO,OAAO;EACd,WAAW,MAAM;EACjB,UAAU,MAAM;EAChB,UAAU,MAAM,YAAY,CAAC;EAC7B,WAAW,MAAM,aAAa,CAAC;EAC/B,GAAI,MAAM,gBAAgB,EAAE,eAAe,MAAM,cAAc,IAAI,CAAC;EACpE,UAAU,MAAM;EAChB,GAAI,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;EACnD,GAAI,QAAQ,SAAS,EAAE,QAAQ,QAAQ,OAAO,IAAI,CAAC;CACrD;AACF;;AAGA,SAAgB,cACd,QACA,OAYa;CACb,MAAM,EAAE,YAAY;CACpB,OAAO;EACL,IAAI,QAAQ;EACZ,SAAS,QAAQ;EACjB,QAAQ,QAAQ;EAChB,QAAQ,QAAQ;EAChB,OAAO,OAAO;EACd,SAAS,OAAO;EAChB,SAAS,MAAM;EACf,WAAW,MAAM;EACjB,cAAc,MAAM;EACpB,UAAU,MAAM;EAChB,eAAe,MAAM;EACrB,iBAAiB,QAAQ;EACzB,cAAc,mBAAmB,SAAS,MAAM;EAChD,QAAQ,MAAM,UAAU,QAAQ;EAChC,WAAW,MAAM;EACjB,UAAU,MAAM;EAChB,OAAO,MAAM;EACb,YAAY,MAAM;CACpB;AACF"}

package/dist/capture/shards/execute.mjs

@@ -0,0 +1,175 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { classifyFailures } from "../failure-sets.mjs";
+import { renderWork } from "../matrix.mjs";
+import { SnapshotModel } from "../../models/snapshot.mjs";
+import { persistRendered } from "../pipeline.mjs";
+import { removeShardScratch } from "../scratch.mjs";
+import { CaptureShardModel } from "../../models/capture-shard.mjs";
+import { contextOf, matrixInputOf } from "./context.mjs";
+import { extractStorybookToScratch } from "../statics.mjs";
+import { loadTarget } from "../target.mjs";
+import { reduceBuild } from "./reduce.mjs";
+// src/capture/shards/execute.ts
+/** The render stage: one shard of a sharded capture, run by whichever worker picked up its job. */
+/**
+* Render and persist one shard, record its outcome, and, if it was the last one, finalize the build.
+*
+* Safe to run twice: a shard already done is not rendered again, and a rerun of an interrupted one
+* starts from a clean slate for its stories. A redelivered shard that is already done still tries
+* to finalize the build, in case the run that finished it died or failed before it could.
+*/
+async function executeCaptureShard(input, options) {
+	const picked = await pickShard(input, options);
+	if ("status" in picked) return picked;
+	const final = input.final !== false;
+	if (picked.shard.status === "done") return await reduceFinished(picked.target, input, final);
+	await runShard(picked.target, picked.shard, input, final);
+	return await reduceRendered(picked.target, input, final);
+}
+/** The shard is done: if it was the last one, this run finalizes the build. */
+async function reduceRendered(target, input, final) {
+	const summary = await reduceBuild(target, final);
+	if (!summary) return {
+		status: "rendered",
+		finalized: false
+	};
+	await input.onFinalized?.(summary);
+	return {
+		status: "rendered",
+		finalized: true,
+		summary
+	};
+}
+/** A redelivered shard that an earlier run finished: finalize the build if nobody has. */
+async function reduceFinished(target, input, final) {
+	const summary = await reduceBuild(target, final);
+	if (!summary) return {
+		status: "skipped",
+		reason: "shard already finished"
+	};
+	await input.onFinalized?.(summary);
+	return {
+		status: "reduced",
+		summary
+	};
+}
+/** Run the shard; a failure is recorded on its row (and, if final, reduces the build) then rethrown. */
+async function runShard(target, shard, input, final) {
+	const shards = new CaptureShardModel(target.options.db);
+	await shards.markRunning(shard.id);
+	input.progress?.();
+	try {
+		await renderShard(target, shard, input.progress);
+	} catch (error) {
+		await recordFailure(shards, shard, error, final);
+		if (final) await finalizeAfterFailure(target, input, error);
+		throw error;
+	}
+}
+/**
+* The shard failed for good: if it was the last one open, it ends the build, and only then does
+* this run report it. A failure here is logged, not thrown: the shard's own error is the news.
+*/
+async function finalizeAfterFailure(target, input, error) {
+	try {
+		const summary = await reduceBuild(target, true);
+		if (summary) await input.onFinalized?.(summary, error);
+	} catch (reduceError) {
+		target.options.logger?.error({
+			err: reduceError,
+			buildId: target.build.id
+		}, "finalizing after a failed shard failed");
+	}
+}
+/** The shard to run and what to run it against, or why there is nothing to do. */
+async function pickShard(input, options) {
+	const shard = await new CaptureShardModel(options.db).get(input.shard);
+	if (shard?.kind !== "render") return {
+		status: "skipped",
+		reason: "shard no longer exists"
+	};
+	const { build, project } = await loadTarget(options, input.buildId);
+	if (build.status !== "capturing") return {
+		status: "skipped",
+		reason: shard.status === "done" ? "shard already finished" : `build is ${build.status}`
+	};
+	return {
+		target: {
+			options,
+			build,
+			project
+		},
+		shard
+	};
+}
+async function recordFailure(shards, shard, error, final) {
+	const message = error instanceof Error ? error.message : String(error);
+	await (final ? shards.fail(shard.id, message) : shards.retry(shard.id, message));
+}
+async function renderShard(target, shard, progress) {
+	const { options, build, project } = target;
+	const payload = JSON.parse(shard.payload ?? "{}");
+	const started = performance.now();
+	const storybookDir = await extractStorybookToScratch(options.storage, options.scratchDir, project.id, build.id, shard.id, options.limits);
+	progress?.();
+	try {
+		const result = await renderAndPersist(target, payload, {
+			storybookDir,
+			runId: shard.id,
+			shardIndex: shard.ordinal,
+			progress
+		});
+		const durationMs = Math.round(performance.now() - started);
+		await new CaptureShardModel(options.db).complete(shard.id, JSON.stringify({
+			...result,
+			durationMs
+		}));
+	} finally {
+		await removeShardScratch(options.scratchDir, project.id, build.id, shard.id, options.logger);
+	}
+}
+async function renderAndPersist(target, payload, run) {
+	const stories = payload.browsers.flatMap((engine) => engine.stories);
+	const browsers = payload.browsers.map((engine) => engine.browser);
+	const rendered = await renderWork(matrixInputOf(target, {
+		stories,
+		viewports: payload.viewports,
+		browsers,
+		storybookDir: run.storybookDir,
+		affectedPaths: null,
+		progress: run.progress,
+		runId: run.runId,
+		shardIndex: run.shardIndex
+	}), payload.browsers);
+	const failures = classifyFailures(stories, rendered.failures);
+	await clearEarlierRun(target, payload);
+	const persisted = await persistRendered(contextOf(target, {
+		viewports: payload.viewports,
+		browsers,
+		captures: rendered.captures,
+		freshBrowsers: new Set(payload.fresh),
+		progress: run.progress
+	}), failures.blocking, failures.flaky, failures.a11y);
+	return {
+		failedStoryIds: [...persisted.failed],
+		flakyStoryIds: [...persisted.flaky],
+		a11yStoryIds: [...persisted.a11y],
+		captured: rendered.captures.length
+	};
+}
+/**
+* Drop what an interrupted earlier run of this shard persisted: the rendered rows of the
+* (story, engine) pairs it is about to write. The plan's inherited rows stay, including those of
+* these stories on engines or viewports this shard does not render.
+*/
+async function clearEarlierRun(target, payload) {
+	await new SnapshotModel(target.options.db, target.options.tables).removeRendered(target.build.id, payload.browsers.map((engine) => ({
+		browser: engine.browser,
+		storyIds: new Set(engine.stories.map((story) => story.id))
+	})));
+}
+export { executeCaptureShard };
+
+//# sourceMappingURL=execute.mjs.map

package/dist/capture/shards/execute.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.mjs","names":[],"sources":["../../../src/capture/shards/execute.ts"],"sourcesContent":["/** The render stage: one shard of a sharded capture, run by whichever worker picked up its job. */\nimport { CaptureShardModel } from \"../../models/capture-shard.ts\";\nimport { SnapshotModel } from \"../../models/snapshot.ts\";\nimport type { CaptureShard } from \"../../schema/capture-shard.ts\";\nimport { classifyFailures } from \"../failure-sets.ts\";\nimport { renderWork } from \"../matrix.ts\";\nimport type { CaptureJobOptions } from \"../orchestrator.ts\";\nimport { persistRendered } from \"../pipeline.ts\";\nimport type { CaptureProgress } from \"../progress.ts\";\nimport { removeShardScratch } from \"../scratch.ts\";\nimport type { ShardPayload, ShardResult } from \"../shard-plan.ts\";\nimport { extractStorybookToScratch } from \"../statics.ts\";\nimport { loadTarget } from \"../target.ts\";\nimport { contextOf, matrixInputOf, type ShardTarget } from \"./context.ts\";\nimport { reduceBuild, type FinalSummary } from \"./reduce.ts\";\n\n/** A shard job being run. */\nexport interface ShardRunInput {\n  buildId: string;\n  shard: string;\n  reqId?: string | undefined;\n  /**\n   * Whether a failure now is the last word. A queue that redelivers failed jobs passes false until\n   * its retries are used up, so a shard that will be retried does not end the build.\n   */\n  final?: boolean | undefined;\n  /** Reports render and persist progress to the job's lease (see `leaseProgress`). */\n  progress?: CaptureProgress | undefined;\n  /**\n   * Called once by the run that finalized the build, and by no other, with the summary and, when\n   * the shard that ended the build failed, its error. The caller closes the plan's attempt here.\n   */\n  onFinalized?: ((summary: FinalSummary, error?: unknown) => Promise<void>) | undefined;\n}\n\n/** How a shard run ended. */\nexport type ShardOutcome =\n  | { status: \"skipped\"; reason: string }\n  | { status: \"rendered\"; finalized: false }\n  | { status: \"rendered\"; finalized: true; summary: FinalSummary }\n  /** The shard was already done, but the build was not: this run finalized it. */\n  | { status: \"reduced\"; summary: FinalSummary };\n\n/**\n * Render and persist one shard, record its outcome, and, if it was the last one, finalize the build.\n *\n * Safe to run twice: a shard already done is not rendered again, and a rerun of an interrupted one\n * starts from a clean slate for its stories. A redelivered shard that is already done still tries\n * to finalize the build, in case the run that finished it died or failed before it could.\n */\nexport async function executeCaptureShard(\n  input: ShardRunInput,\n  options: CaptureJobOptions,\n): Promise<ShardOutcome> {\n  const picked = await pickShard(input, options);\n  if (\"status\" in picked) {\n    return picked;\n  }\n  const final = input.final !== false;\n  if (picked.shard.status === \"done\") {\n    return await reduceFinished(picked.target, input, final);\n  }\n  await runShard(picked.target, picked.shard, input, final);\n  return await reduceRendered(picked.target, input, final);\n}\n\n/** The shard is done: if it was the last one, this run finalizes the build. */\nasync function reduceRendered(\n  target: ShardTarget,\n  input: ShardRunInput,\n  final: boolean,\n): Promise<ShardOutcome> {\n  const summary = await reduceBuild(target, final);\n  if (!summary) {\n    return { status: \"rendered\", finalized: false };\n  }\n  await input.onFinalized?.(summary);\n  return { status: \"rendered\", finalized: true, summary };\n}\n\n/** A redelivered shard that an earlier run finished: finalize the build if nobody has. */\nasync function reduceFinished(\n  target: ShardTarget,\n  input: ShardRunInput,\n  final: boolean,\n): Promise<ShardOutcome> {\n  const summary = await reduceBuild(target, final);\n  if (!summary) {\n    return { status: \"skipped\", reason: \"shard already finished\" };\n  }\n  await input.onFinalized?.(summary);\n  return { status: \"reduced\", summary };\n}\n\n/** Run the shard; a failure is recorded on its row (and, if final, reduces the build) then rethrown. */\nasync function runShard(\n  target: ShardTarget,\n  shard: CaptureShard,\n  input: ShardRunInput,\n  final: boolean,\n): Promise<void> {\n  const shards = new CaptureShardModel(target.options.db);\n  await shards.markRunning(shard.id);\n  input.progress?.();\n  try {\n    await renderShard(target, shard, input.progress);\n  } catch (error) {\n    await recordFailure(shards, shard, error, final);\n    if (final) {\n      await finalizeAfterFailure(target, input, error);\n    }\n    throw error;\n  }\n}\n\n/**\n * The shard failed for good: if it was the last one open, it ends the build, and only then does\n * this run report it. A failure here is logged, not thrown: the shard's own error is the news.\n */\nasync function finalizeAfterFailure(\n  target: ShardTarget,\n  input: ShardRunInput,\n  error: unknown,\n): Promise<void> {\n  try {\n    const summary = await reduceBuild(target, true);\n    if (summary) {\n      await input.onFinalized?.(summary, error);\n    }\n  } catch (reduceError) {\n    target.options.logger?.error(\n      { err: reduceError, buildId: target.build.id },\n      \"finalizing after a failed shard failed\",\n    );\n  }\n}\n\n/** The shard to run and what to run it against, or why there is nothing to do. */\nasync function pickShard(\n  input: ShardRunInput,\n  options: CaptureJobOptions,\n): Promise<\n  { target: ShardTarget; shard: CaptureShard } | Extract<ShardOutcome, { status: \"skipped\" }>\n> {\n  const shard = await new CaptureShardModel(options.db).get(input.shard);\n  if (shard?.kind !== \"render\") {\n    return { status: \"skipped\", reason: \"shard no longer exists\" };\n  }\n  const { build, project } = await loadTarget(options, input.buildId);\n  if (build.status !== \"capturing\") {\n    const reason = shard.status === \"done\" ? \"shard already finished\" : `build is ${build.status}`;\n    return { status: \"skipped\", reason };\n  }\n  return { target: { options, build, project }, shard };\n}\n\nasync function recordFailure(\n  shards: CaptureShardModel,\n  shard: CaptureShard,\n  error: unknown,\n  final: boolean,\n): Promise<void> {\n  const message = error instanceof Error ? error.message : String(error);\n  await (final ? shards.fail(shard.id, message) : shards.retry(shard.id, message));\n}\n\nasync function renderShard(\n  target: ShardTarget,\n  shard: CaptureShard,\n  progress: CaptureProgress | undefined,\n): Promise<void> {\n  const { options, build, project } = target;\n  const payload = JSON.parse(shard.payload ?? \"{}\") as ShardPayload;\n  const started = performance.now();\n  const storybookDir = await extractStorybookToScratch(\n    options.storage,\n    options.scratchDir,\n    project.id,\n    build.id,\n    shard.id,\n    options.limits,\n  );\n  progress?.();\n  try {\n    const result = await renderAndPersist(target, payload, {\n      storybookDir,\n      runId: shard.id,\n      shardIndex: shard.ordinal,\n      progress,\n    });\n    const durationMs = Math.round(performance.now() - started);\n    await new CaptureShardModel(options.db).complete(\n      shard.id,\n      JSON.stringify({ ...result, durationMs } satisfies ShardResult),\n    );\n  } finally {\n    await removeShardScratch(options.scratchDir, project.id, build.id, shard.id, options.logger);\n  }\n}\n\nasync function renderAndPersist(\n  target: ShardTarget,\n  payload: ShardPayload,\n  run: {\n    storybookDir: string;\n    runId: string;\n    shardIndex: number;\n    progress: CaptureProgress | undefined;\n  },\n): Promise<Omit<ShardResult, \"durationMs\">> {\n  const stories = payload.browsers.flatMap((engine) => engine.stories);\n  const browsers = payload.browsers.map((engine) => engine.browser);\n  const rendered = await renderWork(\n    matrixInputOf(target, {\n      stories,\n      viewports: payload.viewports,\n      browsers,\n      storybookDir: run.storybookDir,\n      affectedPaths: null,\n      progress: run.progress,\n      runId: run.runId,\n      shardIndex: run.shardIndex,\n    }),\n    payload.browsers,\n  );\n  const failures = classifyFailures(stories, rendered.failures);\n  await clearEarlierRun(target, payload);\n  const persisted = await persistRendered(\n    contextOf(target, {\n      viewports: payload.viewports,\n      browsers,\n      captures: rendered.captures,\n      freshBrowsers: new Set(payload.fresh),\n      progress: run.progress,\n    }),\n    failures.blocking,\n    failures.flaky,\n    failures.a11y,\n  );\n  return {\n    failedStoryIds: [...persisted.failed],\n    flakyStoryIds: [...persisted.flaky],\n    a11yStoryIds: [...persisted.a11y],\n    captured: rendered.captures.length,\n  };\n}\n\n/**\n * Drop what an interrupted earlier run of this shard persisted: the rendered rows of the\n * (story, engine) pairs it is about to write. The plan's inherited rows stay, including those of\n * these stories on engines or viewports this shard does not render.\n */\nasync function clearEarlierRun(target: ShardTarget, payload: ShardPayload): Promise<void> {\n  await new SnapshotModel(target.options.db, target.options.tables).removeRendered(\n    target.build.id,\n    payload.browsers.map((engine) => ({\n      browser: engine.browser,\n      storyIds: new Set(engine.stories.map((story) => story.id)),\n    })),\n  );\n}\n"],"mappings":"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"}

package/dist/capture/shards/fan-out.mjs

@@ -0,0 +1,125 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { CaptureAttemptModel, emitAttemptLog } from "../../models/capture-attempt.mjs";
+import { resolveStoryViewports } from "../storybook.mjs";
+import { affectedPathsFor } from "../affected.mjs";
+import { partitionBrowsers } from "../matrix.mjs";
+import { SnapshotModel } from "../../models/snapshot.mjs";
+import { freshBrowsersOf, persistInherited } from "../pipeline.mjs";
+import { CaptureShardModel } from "../../models/capture-shard.mjs";
+import { planShards, worthSharding } from "../shard-plan.mjs";
+import { contextOf, matrixInputOf } from "./context.mjs";
+import { storyDurations } from "./history.mjs";
+// src/capture/shards/fan-out.ts
+/**
+* The plan stage. When sharding is on and the build is big enough, decide what to render, record
+* the plan and its shards, and hand the shards to the queue; otherwise return null and the caller
+* renders the build in one piece as it always has.
+*
+* Inherited snapshots (affected capture) are written here, since nothing renders for them.
+*/
+async function fanOutCapture(args) {
+	const { options } = args;
+	if (!options.shardSize || !options.enqueue) return null;
+	const matrix = matrixInputOf(args, {
+		stories: args.stories,
+		viewports: args.viewports,
+		browsers: args.browsers,
+		storybookDir: "",
+		affectedPaths: affectedPathsFor(args.build),
+		logger: args.logger,
+		recordLog: args.input.recordLog,
+		progress: args.input.progress
+	});
+	const partition = await partitionBrowsers(matrix);
+	const capturesOf = (story) => resolveStoryViewports(story, args.viewports).length;
+	return worthSharding(partition.work, capturesOf, options.shardSize) ? await planAndCommit(args, partition, capturesOf) : null;
+}
+async function planAndCommit(args, partition, capturesOf) {
+	const durations = await storyDurations(args);
+	const slices = planShards(partition.work, capturesOf, args.options.shardSize, (storyId) => durations.get(storyId));
+	return slices.length === 0 ? null : await commitPlan({
+		...args,
+		timed: durations.size > 0
+	}, slices, partition);
+}
+async function commitPlan(args, slices, partition) {
+	await supersedeEarlierRuns(args);
+	const ctx = contextOf(args, {
+		viewports: args.viewports,
+		browsers: args.browsers,
+		inherited: partition.inherited,
+		progress: args.input.progress
+	});
+	const failedInherits = await persistInherited(ctx);
+	const storyIds = /* @__PURE__ */ new Set([...partition.work.flatMap((engine) => engine.stories.map((story) => story.id)), ...partition.inherited.map((inherited) => inherited.story.id)]);
+	const fresh = [...await freshBrowsersOf(ctx)];
+	const failed = /* @__PURE__ */ new Set([...failedInherits, ...args.testFailed ?? []]);
+	const rows = await recordPlan(args, slices, {
+		fresh,
+		storyIds,
+		failed
+	});
+	await handOut(args, rows);
+	await emitAttemptLog(args.input.recordLog, args.logger, "info", "capture planned", {
+		shards: rows.length,
+		stories: storyIds.size,
+		ordering: args.timed ? "longest-first" : "by-capture-count"
+	});
+	return {
+		storyCount: storyIds.size,
+		failedCount: failed.size,
+		shards: rows.length
+	};
+}
+/**
+* A new plan of a build (recovery requeue, retry, a redelivered plan job) starts clean: the
+* snapshots an earlier plan or its shards wrote are dropped, so inherited rows are not doubled,
+* and the attempts it left open are closed, since only the newest plan's attempt is ever closed.
+*/
+async function supersedeEarlierRuns(args) {
+	const { db, tables } = args.options;
+	await new SnapshotModel(db, tables).removeForBuild(args.build.id);
+	await new CaptureAttemptModel(db, tables).closeOthers(args.build.id, args.input.attempt?.id ?? null, "superseded by a new capture plan");
+}
+async function recordPlan(args, slices, plan) {
+	const shards = new CaptureShardModel(args.options.db);
+	await shards.clearBuild(args.build.id);
+	const settings = {
+		browsers: args.browsers,
+		fresh: plan.fresh,
+		shardSize: args.options.shardSize ?? 0,
+		total: slices.length
+	};
+	const result = {
+		storyIds: [...plan.storyIds],
+		failedStoryIds: [...plan.failed]
+	};
+	return await shards.createPlan(args.project.id, args.build.id, {
+		attemptId: args.input.attempt?.id ?? null,
+		payload: JSON.stringify(settings),
+		result: JSON.stringify(result)
+	}, slices.map((browsers) => ({ payload: shardPayload(args, browsers, plan.fresh) })));
+}
+function shardPayload(args, browsers, fresh) {
+	const payload = {
+		browsers,
+		viewports: args.viewports,
+		fresh
+	};
+	return JSON.stringify(payload);
+}
+/** Enqueue every shard in order; the caller marks the build failed if the queue refuses one. */
+async function handOut(args, rows) {
+	const { enqueue } = args.options;
+	for (const row of rows) await enqueue?.({
+		buildId: args.build.id,
+		shard: row.id,
+		reqId: args.input.reqId,
+		traceparent: args.input.traceparent
+	});
+}
+export { fanOutCapture };
+
+//# sourceMappingURL=fan-out.mjs.map

package/dist/capture/shards/fan-out.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fan-out.mjs","names":[],"sources":["../../../src/capture/shards/fan-out.ts"],"sourcesContent":["/** The plan stage: decide what to render, record it as shards, and hand the shards to the queue. */\nimport type { Logger } from \"pino\";\nimport type { CaptureTarget } from \"../../adapters/capture-runner.ts\";\nimport { CaptureAttemptModel, emitAttemptLog } from \"../../models/capture-attempt.ts\";\nimport { CaptureShardModel } from \"../../models/capture-shard.ts\";\nimport { SnapshotModel } from \"../../models/snapshot.ts\";\nimport type { CaptureShard } from \"../../schema/capture-shard.ts\";\nimport type { Viewport } from \"../adapter.ts\";\nimport { affectedPathsFor, type InheritedStory } from \"../affected.ts\";\nimport { partitionBrowsers, type MatrixInput } from \"../matrix.ts\";\nimport type { CaptureJobInput, CaptureSummary } from \"../orchestrator.ts\";\nimport { freshBrowsersOf, persistInherited } from \"../pipeline.ts\";\nimport {\n  planShards,\n  worthSharding,\n  type EngineWork,\n  type PlanPayload,\n  type PlanResult,\n  type ShardPayload,\n} from \"../shard-plan.ts\";\nimport { resolveStoryViewports } from \"../storybook.ts\";\nimport { contextOf, matrixInputOf, type ShardTarget } from \"./context.ts\";\nimport { storyDurations } from \"./history.ts\";\n\n/** Inputs for {@link fanOutCapture}: the plan stage's view of the build. */\nexport interface FanOutInput extends ShardTarget {\n  input: CaptureJobInput;\n  stories: MatrixInput[\"stories\"];\n  viewports: Viewport[];\n  browsers: CaptureTarget[];\n  logger: Logger | undefined;\n  /** Test entries that failed in the plan stage (ADR 0004, decision 10): they fail the build. */\n  testFailed?: ReadonlySet<string> | undefined;\n  /** Set by the plan stage: whether past timings were available to order the shards by. */\n  timed?: boolean;\n}\n\n/**\n * The plan stage. When sharding is on and the build is big enough, decide what to render, record\n * the plan and its shards, and hand the shards to the queue; otherwise return null and the caller\n * renders the build in one piece as it always has.\n *\n * Inherited snapshots (affected capture) are written here, since nothing renders for them.\n */\nexport async function fanOutCapture(args: FanOutInput): Promise<CaptureSummary | null> {\n  const { options } = args;\n  if (!options.shardSize || !options.enqueue) {\n    return null;\n  }\n  const matrix = matrixInputOf(args, {\n    stories: args.stories,\n    viewports: args.viewports,\n    browsers: args.browsers,\n    storybookDir: \"\",\n    affectedPaths: affectedPathsFor(args.build),\n    logger: args.logger,\n    recordLog: args.input.recordLog,\n    progress: args.input.progress,\n  });\n  const partition = await partitionBrowsers(matrix);\n  const capturesOf = (story: MatrixInput[\"stories\"][number]): number =>\n    resolveStoryViewports(story, args.viewports).length;\n  // Past timings only order the shards: not worth a lookup for a build that runs in one piece.\n  return worthSharding(partition.work, capturesOf, options.shardSize)\n    ? await planAndCommit(args, partition, capturesOf)\n    : null;\n}\n\nasync function planAndCommit(\n  args: FanOutInput,\n  partition: { work: EngineWork[]; inherited: InheritedStory[] },\n  capturesOf: (story: MatrixInput[\"stories\"][number]) => number,\n): Promise<CaptureSummary | null> {\n  const durations = await storyDurations(args);\n  const slices = planShards(partition.work, capturesOf, args.options.shardSize, (storyId) =>\n    durations.get(storyId),\n  );\n  return slices.length === 0\n    ? null\n    : await commitPlan({ ...args, timed: durations.size > 0 }, slices, partition);\n}\n\nasync function commitPlan(\n  args: FanOutInput,\n  slices: EngineWork[][],\n  partition: { work: EngineWork[]; inherited: InheritedStory[] },\n): Promise<CaptureSummary> {\n  await supersedeEarlierRuns(args);\n  const ctx = contextOf(args, {\n    viewports: args.viewports,\n    browsers: args.browsers,\n    inherited: partition.inherited,\n    progress: args.input.progress,\n  });\n  const failedInherits = await persistInherited(ctx);\n  const storyIds = new Set([\n    ...partition.work.flatMap((engine) => engine.stories.map((story) => story.id)),\n    ...partition.inherited.map((inherited) => inherited.story.id),\n  ]);\n  const fresh = [...(await freshBrowsersOf(ctx))];\n  const failed = new Set([...failedInherits, ...(args.testFailed ?? [])]);\n  const rows = await recordPlan(args, slices, { fresh, storyIds, failed });\n  await handOut(args, rows);\n  await emitAttemptLog(args.input.recordLog, args.logger, \"info\", \"capture planned\", {\n    shards: rows.length,\n    stories: storyIds.size,\n    ordering: args.timed ? \"longest-first\" : \"by-capture-count\",\n  });\n  return { storyCount: storyIds.size, failedCount: failed.size, shards: rows.length };\n}\n\n/**\n * A new plan of a build (recovery requeue, retry, a redelivered plan job) starts clean: the\n * snapshots an earlier plan or its shards wrote are dropped, so inherited rows are not doubled,\n * and the attempts it left open are closed, since only the newest plan's attempt is ever closed.\n */\nasync function supersedeEarlierRuns(args: FanOutInput): Promise<void> {\n  const { db, tables } = args.options;\n  await new SnapshotModel(db, tables).removeForBuild(args.build.id);\n  await new CaptureAttemptModel(db, tables).closeOthers(\n    args.build.id,\n    args.input.attempt?.id ?? null,\n    \"superseded by a new capture plan\",\n  );\n}\n\nasync function recordPlan(\n  args: FanOutInput,\n  slices: EngineWork[][],\n  plan: { fresh: string[]; storyIds: Set<string>; failed: ReadonlySet<string> },\n): Promise<CaptureShard[]> {\n  const shards = new CaptureShardModel(args.options.db);\n  await shards.clearBuild(args.build.id);\n  const settings: PlanPayload = {\n    browsers: args.browsers,\n    fresh: plan.fresh,\n    shardSize: args.options.shardSize ?? 0,\n    total: slices.length,\n  };\n  const result: PlanResult = { storyIds: [...plan.storyIds], failedStoryIds: [...plan.failed] };\n  return await shards.createPlan(\n    args.project.id,\n    args.build.id,\n    {\n      attemptId: args.input.attempt?.id ?? null,\n      payload: JSON.stringify(settings),\n      result: JSON.stringify(result),\n    },\n    slices.map((browsers) => ({ payload: shardPayload(args, browsers, plan.fresh) })),\n  );\n}\n\nfunction shardPayload(args: FanOutInput, browsers: EngineWork[], fresh: string[]): string {\n  const payload: ShardPayload = { browsers, viewports: args.viewports, fresh };\n  return JSON.stringify(payload);\n}\n\n/** Enqueue every shard in order; the caller marks the build failed if the queue refuses one. */\nasync function handOut(args: FanOutInput, rows: CaptureShard[]): Promise<void> {\n  const { enqueue } = args.options;\n  for (const row of rows) {\n    // oxlint-disable-next-line no-await-in-loop -- shards are queued in plan order\n    await enqueue?.({\n      buildId: args.build.id,\n      shard: row.id,\n      reqId: args.input.reqId,\n      traceparent: args.input.traceparent,\n    });\n  }\n}\n"],"mappings":"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"}

package/dist/capture/shards/history.mjs

@@ -0,0 +1,34 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { BuildModel } from "../../models/build.mjs";
+import { SnapshotModel } from "../../models/snapshot.mjs";
+// src/capture/shards/history.ts
+/** What the project's recent builds say a story costs, so a plan can order its work by it. */
+/**
+* Milliseconds each story cost, taken from the newest build of this project whose snapshots carry
+* timings. Older builds are a fair guide: story render cost moves with the story, not the build.
+*
+* Returns an empty map when nothing has been timed yet — a fresh project, a runner that reports no
+* durations, or a retention purge that took the timed builds with it — and the plan then falls back
+* to slicing by capture count alone.
+*/
+async function storyDurations(target) {
+	const { options, project, build } = target;
+	const builds = new BuildModel(options.db, options.tables);
+	const snapshots = new SnapshotModel(options.db, options.tables);
+	const recent = (await builds.list(project.id, { limit: BUILDS_SCANNED + 1 })).filter((candidate) => candidate.id !== build.id).slice(0, BUILDS_SCANNED);
+	for (const candidate of recent) {
+		const timings = await snapshots.durationsByStory(candidate.id);
+		if (timings.size > 0) return timings;
+	}
+	return /* @__PURE__ */ new Map();
+}
+/**
+* Recent builds to look through for timings. More than a couple is wasted work: a build that
+* rendered nothing (everything inherited) carries none, but several in a row do not happen.
+*/
+const BUILDS_SCANNED = 3;
+export { storyDurations };
+
+//# sourceMappingURL=history.mjs.map

package/dist/capture/shards/history.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.mjs","names":[],"sources":["../../../src/capture/shards/history.ts"],"sourcesContent":["/** What the project's recent builds say a story costs, so a plan can order its work by it. */\nimport { BuildModel } from \"../../models/build.ts\";\nimport { SnapshotModel } from \"../../models/snapshot.ts\";\nimport type { ShardTarget } from \"./context.ts\";\n\n/**\n * Milliseconds each story cost, taken from the newest build of this project whose snapshots carry\n * timings. Older builds are a fair guide: story render cost moves with the story, not the build.\n *\n * Returns an empty map when nothing has been timed yet — a fresh project, a runner that reports no\n * durations, or a retention purge that took the timed builds with it — and the plan then falls back\n * to slicing by capture count alone.\n */\nexport async function storyDurations(target: ShardTarget): Promise<Map<string, number>> {\n  const { options, project, build } = target;\n  const builds = new BuildModel(options.db, options.tables);\n  const snapshots = new SnapshotModel(options.db, options.tables);\n  // One extra in case the build being planned is among the newest.\n  const recent = (await builds.list(project.id, { limit: BUILDS_SCANNED + 1 }))\n    .filter((candidate) => candidate.id !== build.id)\n    .slice(0, BUILDS_SCANNED);\n  for (const candidate of recent) {\n    // oxlint-disable-next-line no-await-in-loop -- stops at the first build that carries timings\n    const timings = await snapshots.durationsByStory(candidate.id);\n    if (timings.size > 0) {\n      return timings;\n    }\n  }\n  return new Map();\n}\n\n/**\n * Recent builds to look through for timings. More than a couple is wasted work: a build that\n * rendered nothing (everything inherited) carries none, but several in a row do not happen.\n */\nconst BUILDS_SCANNED = 3;\n"],"mappings":";;;;;;;;;;;;;;;AAaA,eAAsB,eAAe,QAAmD;CACtF,MAAM,EAAE,SAAS,SAAS,UAAU;CACpC,MAAM,SAAS,IAAI,WAAW,QAAQ,IAAI,QAAQ,MAAM;CACxD,MAAM,YAAY,IAAI,cAAc,QAAQ,IAAI,QAAQ,MAAM;CAE9D,MAAM,UAAU,MAAM,OAAO,KAAK,QAAQ,IAAI,EAAE,OAAO,iBAAiB,EAAE,CAAC,EAAA,CACxE,QAAQ,cAAc,UAAU,OAAO,MAAM,EAAE,CAAC,CAChD,MAAM,GAAG,cAAc;CAC1B,KAAK,MAAM,aAAa,QAAQ;EAE9B,MAAM,UAAU,MAAM,UAAU,iBAAiB,UAAU,EAAE;EAC7D,IAAI,QAAQ,OAAO,GACjB,OAAO;CAEX;CACA,uBAAO,IAAI,IAAI;AACjB;;;;;AAMA,MAAM,iBAAiB"}