@storyshelf/core 0.6.2 → 0.7.0

package/dist/capture/isolate.mjs

@@ -0,0 +1,141 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capture/isolate.ts
+/**
+* Render one engine's stories, narrowing a crash down to the story that caused it.
+*
+* A render call that throws takes its whole slice with it, so the stories it had not reached yet are
+* re-rendered as two halves, and so on until a single story is left holding the crash. That story
+* gets one pass on its own (a fresh browser) before it is blamed: only a story that crashes alone is
+* failed, and its shard-mates still get captured. A crash that never yields a single screenshot is
+* treated as the environment being broken rather than any one story's fault, and rethrown for the
+* caller to fail the whole slice.
+*
+* A story counts as done only once every one of its viewports has a capture or a failure, so a
+* crash partway through a story's viewports renders it again rather than losing the rest.
+*/
+async function renderIsolating(stories, pass, options = {}) {
+	const { note } = options;
+	const state = newState(stories.length, options.viewportsOf);
+	const queue = stories.length > 0 ? [[...stories]] : [];
+	while (queue.length > 0) await step(state, queue, pass, note);
+	if (state.captures.length === 0 && state.crash !== void 0) throw state.crash;
+	return result(state, stories.length);
+}
+/** Render the next slice on the queue and deal with however it ended. */
+async function step(state, queue, pass, note) {
+	const slice = queue.shift() ?? [];
+	const outcome = await pass(slice);
+	absorb(state, outcome);
+	if (outcome.error !== void 0) split(state, slice, queue, note);
+	if (state.captures.length === 0 && state.passes >= state.blindBudget) {
+		queue.length = 0;
+		return;
+	}
+	if (state.passes >= MAX_PASSES) failRest(state, queue, note);
+}
+/**
+* Render passes one engine may spend narrowing crashes down before the stories still unrendered are
+* failed without another try. Localizing one crash costs about log2(stories) passes, so this leaves
+* room for a handful of bad stories without letting a shard of hundreds launch a browser per story.
+*/
+const MAX_PASSES = 48;
+/** A crash covers every viewport of the story it is blamed on. */
+const ALL_VIEWPORTS = "*";
+function newState(total, viewportsOf) {
+	return {
+		captures: [],
+		failures: [],
+		poisoned: [],
+		captured: /* @__PURE__ */ new Set(),
+		settled: /* @__PURE__ */ new Set(),
+		viewportsOf,
+		passes: 0,
+		blindBudget: Math.ceil(Math.log2(total + 1)) + 2
+	};
+}
+function result(state, renderCount) {
+	return {
+		captures: state.captures,
+		failures: state.failures,
+		renderCount,
+		poisoned: state.poisoned
+	};
+}
+/**
+* Take in what a pass produced, successful or not. A story rendered again after a crash yields its
+* already-settled viewports a second time; only the first of each is kept.
+*/
+function absorb(state, outcome) {
+	state.passes += 1;
+	for (const capture of outcome.captures) if (settle(state, capture.story.id, capture.viewportName)) state.captures.push(capture);
+	for (const failure of outcome.failures) if (settle(state, failure.storyId, failure.viewportName)) state.failures.push(failure);
+	if (outcome.error !== void 0) state.crash ??= outcome.error;
+}
+/** Record one `(story, viewport)` outcome; false when it was already in. */
+function settle(state, storyId, viewportName) {
+	const key = `${storyId}\u0000${viewportName}`;
+	if (state.settled.has(key) || state.captured.has(storyId)) return false;
+	state.settled.add(key);
+	return true;
+}
+/** Whether every viewport of the story has an outcome (or the story was failed as a whole). */
+function isDone(state, story) {
+	if (state.captured.has(story.id)) return true;
+	const names = state.viewportsOf?.(story);
+	const done = names ? names.every((name) => state.settled.has(`${story.id}\u0000${name}`)) : [...state.settled].some((key) => key.startsWith(`${story.id}\u0000`));
+	if (done) state.captured.add(story.id);
+	return done;
+}
+/**
+* Narrow a crashed slice down: queue the halves of what it left unfinished for another try. The
+* last story left gets a pass on its own first, and is blamed only if it crashes there too.
+*/
+function split(state, slice, queue, note) {
+	const rest = slice.filter((story) => !isDone(state, story));
+	const [first] = rest;
+	if (first === void 0) return;
+	if (rest.length === 1 && slice.length === 1) {
+		blame(state, first, note);
+		return;
+	}
+	const half = Math.ceil(rest.length / 2);
+	queue.push(...[rest.slice(0, half), rest.slice(half)].filter((part) => part.length > 0));
+	note?.("isolating", { stories: rest.length });
+}
+/** Fail one story for the crash and stop rendering it. */
+function blame(state, story, note) {
+	state.captured.add(story.id);
+	state.poisoned.push(story.id);
+	state.failures.push({
+		storyId: story.id,
+		viewportName: ALL_VIEWPORTS,
+		error: crashText(state.crash)
+	});
+	note?.("poisoned", { storyId: story.id });
+}
+/** Out of passes: fail what is left unrendered rather than keep launching browsers. */
+function failRest(state, queue, note) {
+	const rest = queue.flat().filter((story) => !isDone(state, story)).map((story) => story.id);
+	for (const storyId of new Set(rest)) {
+		state.captured.add(storyId);
+		state.failures.push({
+			storyId,
+			viewportName: ALL_VIEWPORTS,
+			error: `not rendered: ${crashText(state.crash)}`
+		});
+	}
+	queue.length = 0;
+	note?.("abandoned", {
+		stories: rest.length,
+		passes: state.passes
+	});
+}
+function crashText(crash) {
+	return `browser crashed: ${crash instanceof Error ? crash.message : String(crash)}`;
+}
+//#endregion
+export { renderIsolating };
+
+//# sourceMappingURL=isolate.mjs.map

package/dist/capture/isolate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"isolate.mjs","names":[],"sources":["../../src/capture/isolate.ts"],"sourcesContent":["/** Localizing a browser crash to the story that caused it, instead of failing every story with it. */\nimport type { RenderFailure, RenderedSnapshot } from \"../adapters/capture-runner.ts\";\nimport type { StoryEntry } from \"./adapter.ts\";\n\n/**\n * Render one engine's stories, narrowing a crash down to the story that caused it.\n *\n * A render call that throws takes its whole slice with it, so the stories it had not reached yet are\n * re-rendered as two halves, and so on until a single story is left holding the crash. That story\n * gets one pass on its own (a fresh browser) before it is blamed: only a story that crashes alone is\n * failed, and its shard-mates still get captured. A crash that never yields a single screenshot is\n * treated as the environment being broken rather than any one story's fault, and rethrown for the\n * caller to fail the whole slice.\n *\n * A story counts as done only once every one of its viewports has a capture or a failure, so a\n * crash partway through a story's viewports renders it again rather than losing the rest.\n */\nexport async function renderIsolating(\n  stories: readonly StoryEntry[],\n  pass: (slice: StoryEntry[]) => Promise<PassOutcome>,\n  options: IsolationOptions = {},\n): Promise<IsolatedResult> {\n  const { note } = options;\n  const state = newState(stories.length, options.viewportsOf);\n  const queue: StoryEntry[][] = stories.length > 0 ? [[...stories]] : [];\n  while (queue.length > 0) {\n    // oxlint-disable-next-line no-await-in-loop -- one browser at a time, like the render loop\n    await step(state, queue, pass, note);\n  }\n  if (state.captures.length === 0 && state.crash !== undefined) {\n    throw state.crash;\n  }\n  return result(state, stories.length);\n}\n\n/** Render the next slice on the queue and deal with however it ended. */\nasync function step(\n  state: IsolationState,\n  queue: StoryEntry[][],\n  pass: (slice: StoryEntry[]) => Promise<PassOutcome>,\n  note?: IsolationNote,\n): Promise<void> {\n  const slice = queue.shift() ?? [];\n  const outcome = await pass(slice);\n  absorb(state, outcome);\n  if (outcome.error !== undefined) {\n    split(state, slice, queue, note);\n  }\n  if (state.captures.length === 0 && state.passes >= state.blindBudget) {\n    // Not one screenshot yet: read that as the environment being broken, not a story's doing.\n    queue.length = 0;\n    return;\n  }\n  if (state.passes >= MAX_PASSES) {\n    failRest(state, queue, note);\n  }\n}\n\n/** What one render pass produced, whether it ran to the end or crashed partway. */\nexport interface PassOutcome {\n  /** Screenshots the pass took; on a crash, the ones it managed before dying. */\n  captures: RenderedSnapshot[];\n  failures: RenderFailure[];\n  /** Set when the render call threw outright, instead of reporting per-story failures. */\n  error?: unknown;\n}\n\n/** Everything the isolating loop produced for one engine. */\nexport interface IsolatedResult {\n  captures: RenderedSnapshot[];\n  failures: RenderFailure[];\n  /** Stories this engine was asked to render (retries are not counted twice). */\n  renderCount: number;\n  /** Stories blamed for a crash and failed on their own. */\n  poisoned: string[];\n}\n\n/** How {@link renderIsolating} reports and what it knows about the stories. */\nexport interface IsolationOptions {\n  note?: IsolationNote | undefined;\n  /**\n   * Names of the viewports a story is rendered at (as resolved for the pass). Without it, a story\n   * counts as done after its first capture or failure.\n   */\n  viewportsOf?: ((story: StoryEntry) => readonly string[]) | undefined;\n}\n\n/** Progress lines for the attempt log; the caller decides where they go. */\nexport type IsolationNote = (\n  event: \"isolating\" | \"poisoned\" | \"abandoned\",\n  fields: Record<string, unknown>,\n) => void;\n\n/**\n * Render passes one engine may spend narrowing crashes down before the stories still unrendered are\n * failed without another try. Localizing one crash costs about log2(stories) passes, so this leaves\n * room for a handful of bad stories without letting a shard of hundreds launch a browser per story.\n */\nconst MAX_PASSES = 48;\n\n/** A crash covers every viewport of the story it is blamed on. */\nconst ALL_VIEWPORTS = \"*\";\n\ninterface IsolationState {\n  captures: RenderedSnapshot[];\n  failures: RenderFailure[];\n  poisoned: string[];\n  /** Stories with every viewport captured or failed, or blamed as a whole. */\n  captured: Set<string>;\n  /** `(story, viewport)` pairs captured or failed so far. */\n  settled: Set<string>;\n  viewportsOf: ((story: StoryEntry) => readonly string[]) | undefined;\n  passes: number;\n  /**\n   * Crashing passes to allow before a slice that has produced nothing at all is given up on: enough\n   * to halve the slice down to a single story and still see a healthy half render.\n   */\n  blindBudget: number;\n  /** First crash seen, rethrown when not one story turned out to be at fault. */\n  crash?: unknown;\n}\n\nfunction newState(total: number, viewportsOf: IsolationState[\"viewportsOf\"]): IsolationState {\n  return {\n    captures: [],\n    failures: [],\n    poisoned: [],\n    captured: new Set(),\n    settled: new Set(),\n    viewportsOf,\n    passes: 0,\n    blindBudget: Math.ceil(Math.log2(total + 1)) + 2,\n  };\n}\n\nfunction result(state: IsolationState, renderCount: number): IsolatedResult {\n  return {\n    captures: state.captures,\n    failures: state.failures,\n    renderCount,\n    poisoned: state.poisoned,\n  };\n}\n\n/**\n * Take in what a pass produced, successful or not. A story rendered again after a crash yields its\n * already-settled viewports a second time; only the first of each is kept.\n */\nfunction absorb(state: IsolationState, outcome: PassOutcome): void {\n  state.passes += 1;\n  for (const capture of outcome.captures) {\n    if (settle(state, capture.story.id, capture.viewportName)) {\n      state.captures.push(capture);\n    }\n  }\n  for (const failure of outcome.failures) {\n    if (settle(state, failure.storyId, failure.viewportName)) {\n      state.failures.push(failure);\n    }\n  }\n  if (outcome.error !== undefined) {\n    state.crash ??= outcome.error;\n  }\n}\n\n/** Record one `(story, viewport)` outcome; false when it was already in. */\nfunction settle(state: IsolationState, storyId: string, viewportName: string): boolean {\n  const key = `${storyId}\\u0000${viewportName}`;\n  if (state.settled.has(key) || state.captured.has(storyId)) {\n    return false;\n  }\n  state.settled.add(key);\n  return true;\n}\n\n/** Whether every viewport of the story has an outcome (or the story was failed as a whole). */\nfunction isDone(state: IsolationState, story: StoryEntry): boolean {\n  if (state.captured.has(story.id)) {\n    return true;\n  }\n  const names = state.viewportsOf?.(story);\n  const done = names\n    ? names.every((name) => state.settled.has(`${story.id}\\u0000${name}`))\n    : [...state.settled].some((key) => key.startsWith(`${story.id}\\u0000`));\n  if (done) {\n    state.captured.add(story.id);\n  }\n  return done;\n}\n\n/**\n * Narrow a crashed slice down: queue the halves of what it left unfinished for another try. The\n * last story left gets a pass on its own first, and is blamed only if it crashes there too.\n */\nfunction split(\n  state: IsolationState,\n  slice: StoryEntry[],\n  queue: StoryEntry[][],\n  note?: IsolationNote,\n): void {\n  const rest = slice.filter((story) => !isDone(state, story));\n  const [first] = rest;\n  if (first === undefined) {\n    return;\n  }\n  if (rest.length === 1 && slice.length === 1) {\n    blame(state, first, note);\n    return;\n  }\n  const half = Math.ceil(rest.length / 2);\n  // Breadth first: the healthy half renders early, which is what tells a bad story apart from a\n  // broken browser (see `blindBudget`).\n  queue.push(...[rest.slice(0, half), rest.slice(half)].filter((part) => part.length > 0));\n  note?.(\"isolating\", { stories: rest.length });\n}\n\n/** Fail one story for the crash and stop rendering it. */\nfunction blame(state: IsolationState, story: StoryEntry, note?: IsolationNote): void {\n  state.captured.add(story.id);\n  state.poisoned.push(story.id);\n  state.failures.push({\n    storyId: story.id,\n    viewportName: ALL_VIEWPORTS,\n    error: crashText(state.crash),\n  });\n  note?.(\"poisoned\", { storyId: story.id });\n}\n\n/** Out of passes: fail what is left unrendered rather than keep launching browsers. */\nfunction failRest(state: IsolationState, queue: StoryEntry[][], note?: IsolationNote): void {\n  const rest = queue\n    .flat()\n    .filter((story) => !isDone(state, story))\n    .map((story) => story.id);\n  for (const storyId of new Set(rest)) {\n    state.captured.add(storyId);\n    state.failures.push({\n      storyId,\n      viewportName: ALL_VIEWPORTS,\n      error: `not rendered: ${crashText(state.crash)}`,\n    });\n  }\n  queue.length = 0;\n  note?.(\"abandoned\", { stories: rest.length, passes: state.passes });\n}\n\nfunction crashText(crash: unknown): string {\n  const message = crash instanceof Error ? crash.message : String(crash);\n  return `browser crashed: ${message}`;\n}\n"],"mappings":"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"}

package/dist/capture/job-lease.d.mts

@@ -0,0 +1,28 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/capture/job-lease.d.ts
+/** Progress lease for in-process capture jobs: the same expiry idea as a remote queue's visibility timeout. */
+/** What a running job calls to prove it is still making progress. */
+interface JobLease {
+  /** Record progress; pushes the expiry out by a full lease. */
+  touch(): void;
+}
+/**
+ * A lease renewed by progress rather than a timer.
+ *
+ * A timer heartbeat inside the same process would keep renewing even when the capture is hung, so
+ * liveness is reported by the job itself (every attempt-log line, i.e. each stage and render
+ * progress). If nothing is touched for `leaseMs`, {@link expired} resolves.
+ */
+declare class ProgressLease implements JobLease {
+  #private;
+  /** Resolves once, when no progress was seen for a full lease. Never resolves when disabled or stopped. */
+  readonly expired: Promise<true>;
+  constructor(leaseMs: number);
+  touch(): void;
+  /** Stop watching; idempotent. */
+  stop(): void;
+}
+//#endregion
+export { JobLease, ProgressLease };
+//# sourceMappingURL=job-lease.d.mts.map

package/dist/capture/job-lease.mjs

@@ -0,0 +1,57 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/capture/job-lease.ts
+/**
+* A lease renewed by progress rather than a timer.
+*
+* A timer heartbeat inside the same process would keep renewing even when the capture is hung, so
+* liveness is reported by the job itself (every attempt-log line, i.e. each stage and render
+* progress). If nothing is touched for `leaseMs`, {@link expired} resolves.
+*/
+var ProgressLease = class {
+	/** Resolves once, when no progress was seen for a full lease. Never resolves when disabled or stopped. */
+	expired;
+	#lastTouch = Date.now();
+	#timer;
+	#stopped = false;
+	#expire;
+	#leaseMs;
+	constructor(leaseMs) {
+		this.#leaseMs = leaseMs;
+		const { promise, resolve } = Promise.withResolvers();
+		this.expired = promise;
+		this.#expire = () => {
+			resolve(true);
+		};
+		if (leaseMs > 0) this.#arm(leaseMs);
+	}
+	touch() {
+		this.#lastTouch = Date.now();
+	}
+	/** Stop watching; idempotent. */
+	stop() {
+		this.#stopped = true;
+		clearTimeout(this.#timer);
+	}
+	#arm(delayMs) {
+		this.#timer = setTimeout(() => {
+			this.#check();
+		}, Math.max(1, delayMs));
+		this.#timer.unref();
+	}
+	#check() {
+		if (this.#stopped) return;
+		const idleMs = Date.now() - this.#lastTouch;
+		if (idleMs >= this.#leaseMs) {
+			this.#stopped = true;
+			this.#expire();
+			return;
+		}
+		this.#arm(this.#leaseMs - idleMs);
+	}
+};
+//#endregion
+export { ProgressLease };
+
+//# sourceMappingURL=job-lease.mjs.map

package/dist/capture/job-lease.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-lease.mjs","names":[],"sources":["../../src/capture/job-lease.ts"],"sourcesContent":["/** Progress lease for in-process capture jobs: the same expiry idea as a remote queue's visibility timeout. */\n\n/** What a running job calls to prove it is still making progress. */\nexport interface JobLease {\n  /** Record progress; pushes the expiry out by a full lease. */\n  touch(): void;\n}\n\n/**\n * A lease renewed by progress rather than a timer.\n *\n * A timer heartbeat inside the same process would keep renewing even when the capture is hung, so\n * liveness is reported by the job itself (every attempt-log line, i.e. each stage and render\n * progress). If nothing is touched for `leaseMs`, {@link expired} resolves.\n */\nexport class ProgressLease implements JobLease {\n  /** Resolves once, when no progress was seen for a full lease. Never resolves when disabled or stopped. */\n  readonly expired: Promise<true>;\n  #lastTouch = Date.now();\n  #timer: ReturnType<typeof setTimeout> | undefined;\n  #stopped = false;\n  readonly #expire: () => void;\n\n  readonly #leaseMs: number;\n\n  constructor(leaseMs: number) {\n    this.#leaseMs = leaseMs;\n    const { promise, resolve } = Promise.withResolvers<true>();\n    this.expired = promise;\n    this.#expire = (): void => {\n      resolve(true);\n    };\n    if (leaseMs > 0) {\n      this.#arm(leaseMs);\n    }\n  }\n\n  touch(): void {\n    this.#lastTouch = Date.now();\n  }\n\n  /** Stop watching; idempotent. */\n  stop(): void {\n    this.#stopped = true;\n    clearTimeout(this.#timer);\n  }\n\n  #arm(delayMs: number): void {\n    this.#timer = setTimeout(\n      () => {\n        this.#check();\n      },\n      Math.max(1, delayMs),\n    );\n    this.#timer.unref();\n  }\n\n  #check(): void {\n    if (this.#stopped) {\n      return;\n    }\n    const idleMs = Date.now() - this.#lastTouch;\n    if (idleMs >= this.#leaseMs) {\n      this.#stopped = true;\n      this.#expire();\n      return;\n    }\n    this.#arm(this.#leaseMs - idleMs);\n  }\n}\n"],"mappings":";;;;;;;;;;;AAeA,IAAa,gBAAb,MAA+C;;CAE7C;CACA,aAAa,KAAK,IAAI;CACtB;CACA,WAAW;CACX;CAEA;CAEA,YAAY,SAAiB;EAC3B,KAAK,WAAW;EAChB,MAAM,EAAE,SAAS,YAAY,QAAQ,cAAoB;EACzD,KAAK,UAAU;EACf,KAAK,gBAAsB;GACzB,QAAQ,IAAI;EACd;EACA,IAAI,UAAU,GACZ,KAAK,KAAK,OAAO;CAErB;CAEA,QAAc;EACZ,KAAK,aAAa,KAAK,IAAI;CAC7B;;CAGA,OAAa;EACX,KAAK,WAAW;EAChB,aAAa,KAAK,MAAM;CAC1B;CAEA,KAAK,SAAuB;EAC1B,KAAK,SAAS,iBACN;GACJ,KAAK,OAAO;EACd,GACA,KAAK,IAAI,GAAG,OAAO,CACrB;EACA,KAAK,OAAO,MAAM;CACpB;CAEA,SAAe;EACb,IAAI,KAAK,UACP;EAEF,MAAM,SAAS,KAAK,IAAI,IAAI,KAAK;EACjC,IAAI,UAAU,KAAK,UAAU;GAC3B,KAAK,WAAW;GAChB,KAAK,QAAQ;GACb;EACF;EACA,KAAK,KAAK,KAAK,WAAW,MAAM;CAClC;AACF"}

package/dist/capture/matrix.mjs

@@ -0,0 +1,298 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { TargetLaunchError } from "../adapters/capture-target.mjs";
+import { primaryTargetOf, resolveBrowsers } from "./browsers.mjs";
+import { isFlakyStory } from "./adapter.mjs";
+import { resolveStoryViewports } from "./storybook.mjs";
+import { storeScreenshot } from "../utils/screenshot-store.mjs";
+import { partitionAffectedStories } from "./affected.mjs";
+import { mirrorAttemptLog } from "./attempt-logger.mjs";
+import { assertScreenshotBuffer } from "./guards.mjs";
+import { renderIsolating } from "./isolate.mjs";
+import { renderInSlices } from "./token-chunks.mjs";
+import { currentImageEngine } from "@storyshelf/image";
+//#region src/capture/matrix.ts
+/** The browser loop: one partition + render pass per engine, sequentially. */
+/**
+* Capture every story on every engine, one engine at a time (browsers are
+* heavy; parallel launches would multiply memory). Each engine resolves its
+* own baselines, so affected capture inherits per engine.
+*/
+async function captureAcrossBrowsers(input) {
+	const result = {
+		captures: [],
+		failures: [],
+		inherited: [],
+		renderCount: 0
+	};
+	for (const browser of input.browsers) {
+		const pass = await captureOnBrowser(input, browser);
+		result.captures.push(...pass.captures);
+		result.failures.push(...pass.failures);
+		result.inherited.push(...pass.inherited);
+		result.renderCount += pass.renderCount;
+	}
+	return result;
+}
+/**
+* Affected-capture partitioning for every engine, without rendering: the plan stage of a sharded
+* capture decides what to render (and how to slice it) before any browser starts.
+*/
+async function partitionBrowsers(input) {
+	const { project, build } = input;
+	const work = [];
+	const inherited = [];
+	for (const browser of input.browsers) {
+		const partition = await partitionAffectedStories({
+			db: input.db,
+			tables: input.tables,
+			projectId: project.id,
+			branch: build.gitBranch,
+			defaultBranch: project.gitDefaultBranch,
+			stories: input.stories,
+			viewports: input.viewports,
+			browser,
+			affectedPaths: input.affectedPaths
+		});
+		work.push({
+			browser,
+			stories: partition.render
+		});
+		inherited.push(...tagged(partition.inherited, browser));
+	}
+	return {
+		work,
+		inherited
+	};
+}
+/**
+* Render explicit per-engine work (one shard's slice), engine by engine. Nothing is inherited here.
+*
+* A story that crashes the browser is narrowed down and failed on its own, so it does not take the
+* rest of the slice with it — see {@link renderIsolating}.
+*/
+async function renderWork(input, work) {
+	const result = {
+		captures: [],
+		failures: [],
+		inherited: [],
+		renderCount: 0
+	};
+	for (const engine of work) {
+		const mirror = mirrorAttemptLog(input.logger, input.recordLog, flakyDowngrade(input.stories));
+		try {
+			const pass = await isolatedPass(input, engine.browser, mirror, engine.stories, []);
+			result.captures.push(...pass.captures);
+			result.failures.push(...pass.failures);
+			result.renderCount += pass.renderCount;
+		} finally {
+			await mirror.flush();
+		}
+	}
+	return result;
+}
+/**
+* One engine's render, with a crashing story narrowed down and failed on its own rather than taking
+* the rest of the pass with it — see {@link renderIsolating}.
+*/
+async function isolatedPass(input, browser, mirror, toRender, inherited) {
+	const pass = await renderIsolating(toRender, async (slice) => await attemptPass(input, browser, mirror, slice), {
+		note: isolationNote(mirror, browser),
+		viewportsOf: (story) => resolveStoryViewports(story, input.viewports).map((viewport) => viewport.name)
+	});
+	return {
+		captures: fillEnvironment(pass.captures),
+		failures: pass.failures,
+		inherited,
+		renderCount: pass.renderCount
+	};
+}
+/** One render pass that never throws: a crash comes back beside whatever it captured first. */
+async function attemptPass(input, browser, mirror, stories) {
+	const spooled = [];
+	try {
+		const pass = await renderPass(input, browser, mirror, stories, [], spooled);
+		return {
+			captures: pass.captures,
+			failures: pass.failures
+		};
+	} catch (error) {
+		if (error instanceof TargetLaunchError) throw error;
+		mirror.log("warn", "render pass crashed, isolating the story at fault", {
+			browser,
+			stories: stories.length,
+			captured: spooled.length,
+			err: error instanceof Error ? error.message : String(error)
+		});
+		return {
+			captures: spooled,
+			failures: [],
+			error
+		};
+	}
+}
+/** Record how a crash was narrowed down on the attempt log. */
+function isolationNote(mirror, browser) {
+	return (event, fields) => {
+		if (event === "poisoned") {
+			mirror.log("error", "story crashed the browser on its own", {
+				browser,
+				...fields
+			});
+			return;
+		}
+		const message = event === "isolating" ? "retrying the stories a crash interrupted" : "giving up on the stories left after repeated crashes";
+		mirror.log("warn", message, {
+			browser,
+			...fields
+		});
+	};
+}
+/**
+* Give captures spooled before a crash the environment a later pass reported: every pass of an
+* engine runs on the same browser build and host, so the one fingerprint covers them all.
+*/
+function fillEnvironment(captures) {
+	const known = captures.find((capture) => capture.environment)?.environment;
+	if (!known) return captures;
+	for (const capture of captures) capture.environment ??= known;
+	return captures;
+}
+async function captureOnBrowser(input, browser) {
+	const mirror = mirrorAttemptLog(input.logger, input.recordLog, flakyDowngrade(input.stories));
+	try {
+		return await passOnBrowser(input, browser, mirror);
+	} finally {
+		await mirror.flush();
+	}
+}
+/**
+* Failures of flaky stories are non-blocking, so the attempt log shows them as
+* warnings (matching "flaky story failed (non-blocking)"), not errors.
+*/
+function flakyDowngrade(stories) {
+	const flaky = new Set(stories.filter((story) => isFlakyStory(story)).map((story) => story.id));
+	return (level, fields) => level === "error" && typeof fields?.["storyId"] === "string" && flaky.has(fields["storyId"]) ? "warn" : level;
+}
+async function passOnBrowser(input, browser, mirror) {
+	const { project, build } = input;
+	const partition = await partitionAffectedStories({
+		db: input.db,
+		tables: input.tables,
+		projectId: project.id,
+		branch: build.gitBranch,
+		defaultBranch: project.gitDefaultBranch,
+		stories: input.stories,
+		viewports: input.viewports,
+		browser,
+		affectedPaths: input.affectedPaths
+	});
+	mirror.log("info", "affected capture partitioned", {
+		browser,
+		rendered: partition.render.length,
+		inherited: partition.inherited.length,
+		total: input.stories.length
+	});
+	const inherited = tagged(partition.inherited, browser);
+	if (partition.render.length === 0) return {
+		captures: [],
+		failures: [],
+		inherited,
+		renderCount: 0
+	};
+	return await isolatedPass(input, browser, mirror, partition.render, inherited);
+}
+/**
+* One engine's render call. `spooled` may be supplied by the caller so that the screenshots taken
+* before a crash survive the throw (they stream in through `onCapture`).
+*/
+async function renderPass(input, browser, mirror, toRender, inherited, spooled = []) {
+	const expected = toRender.flatMap((story) => resolveStoryViewports(story, input.viewports)).length;
+	const rendered = await renderInSlices({
+		runner: input.runner,
+		request: renderRequest(input, browser, toRender, spooled, {
+			mirror,
+			expected
+		}),
+		browser,
+		storybookUrl: input.storybookUrl,
+		captureCount: (story) => resolveStoryViewports(story, input.viewports).length,
+		renderTimeoutMs: input.renderTimeoutMs
+	});
+	mirror.log("info", "render pass finished", {
+		browser,
+		captured: spooled.length + rendered.captures.length,
+		failed: rendered.failures.length,
+		expected,
+		imageEngine: currentImageEngine()
+	});
+	const { environment } = rendered;
+	return {
+		captures: withEnvironment([...spooled, ...tagged(rendered.captures, browser)], environment),
+		failures: tagged(rendered.failures, browser),
+		inherited,
+		renderCount: toRender.length
+	};
+}
+/** The render call for one engine; captures stream into `spooled` as they are taken. */
+function renderRequest(input, browser, stories, spooled, progress) {
+	const { project, build } = input;
+	return {
+		onCapture: async (capture) => {
+			spooled.push(await spoolCapture(input, browser, capture));
+			input.progress?.();
+			logProgress(progress, browser, spooled.length);
+		},
+		buildId: build.id,
+		runId: input.runId ?? build.id,
+		storybookDir: input.storybookDir,
+		stories,
+		viewports: input.viewports,
+		logger: progress.mirror.logger,
+		executePlay: project.executePlay ?? false,
+		playTimeoutMs: project.playTimeoutMs ?? 1e4,
+		runA11y: (project.runA11y ?? true) && browser === primaryTargetOf(resolveBrowsers(project)),
+		target: browser
+	};
+}
+/** Screenshots between progress lines on the attempt log. */
+const PROGRESS_EVERY = 10;
+/** Record "captured N/M" every few screenshots so a long render keeps showing movement. */
+function logProgress(progress, browser, captured) {
+	if (captured % PROGRESS_EVERY !== 0) return;
+	progress.mirror.log("info", `captured ${captured}/${progress.expected} screenshots`, {
+		browser,
+		captured,
+		expected: progress.expected
+	});
+}
+/**
+* Write a screenshot to storage the moment it is captured and keep only its
+* metadata, so memory holds the pages in flight rather than the whole build.
+*/
+async function spoolCapture(input, browser, capture) {
+	assertScreenshotBuffer(capture.screenshot);
+	const storedPath = await storeScreenshot(input.storage, input.project.id, capture.screenshot);
+	return {
+		...capture,
+		browser,
+		screenshot: EMPTY_SCREENSHOT,
+		stored: true,
+		storedPath
+	};
+}
+const EMPTY_SCREENSHOT = Buffer.alloc(0);
+/** Attach the render pass's environment to captures that carry none (a slice may have set its own). */
+function withEnvironment(captures, environment) {
+	if (environment) for (const capture of captures) capture.environment ??= environment;
+	return captures;
+}
+/** Copy each row with its engine (runners may reuse result objects across calls). */
+function tagged(rows, browser) {
+	return rows.map((row) => Object.assign({}, row, { browser }));
+}
+//#endregion
+export { captureAcrossBrowsers, partitionBrowsers, renderWork };
+
+//# sourceMappingURL=matrix.mjs.map

package/dist/capture/matrix.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.mjs","names":[],"sources":["../../src/capture/matrix.ts"],"sourcesContent":["/** The browser loop: one partition + render pass per engine, sequentially. */\nimport { currentImageEngine } from \"@storyshelf/image\";\nimport type { Logger } from \"pino\";\nimport type {\n  CaptureRunner,\n  CaptureTarget,\n  RenderFailure,\n  RenderedSnapshot,\n} from \"../adapters/capture-runner.ts\";\nimport { TargetLaunchError } from \"../adapters/capture-target.ts\";\nimport type { DatabaseAdapter } from \"../adapters/database.ts\";\nimport type { StorageAdapter } from \"../adapters/storage.ts\";\nimport type { AttemptLogRecorder } from \"../models/capture-attempt.ts\";\nimport type { Build } from \"../schema/build.ts\";\nimport type { CaptureLogLevel } from \"../schema/capture-attempt.ts\";\nimport type { Project } from \"../schema/project.ts\";\nimport { storeScreenshot } from \"../utils/screenshot-store.ts\";\nimport { isFlakyStory, type StoryEntry, type Viewport } from \"./adapter.ts\";\nimport { partitionAffectedStories, type InheritedStory } from \"./affected.ts\";\nimport { mirrorAttemptLog, type AttemptMirror } from \"./attempt-logger.ts\";\nimport { primaryTargetOf, resolveBrowsers } from \"./browsers.ts\";\nimport { assertScreenshotBuffer } from \"./guards.ts\";\nimport { renderIsolating, type IsolationNote, type PassOutcome } from \"./isolate.ts\";\nimport type { PipelineTables } from \"./pipeline.ts\";\nimport type { CaptureProgress } from \"./progress.ts\";\nimport type { RenderRequest } from \"./render.ts\";\nimport type { EngineWork } from \"./shard-plan.ts\";\nimport type { StorybookUrlSource } from \"./storybook-urls.ts\";\nimport { resolveStoryViewports } from \"./storybook.ts\";\nimport { renderInSlices } from \"./token-chunks.ts\";\n\n/** Inputs shared by every engine's pass. */\nexport interface MatrixInput {\n  db: DatabaseAdapter;\n  storage: StorageAdapter;\n  tables: PipelineTables;\n  runner: CaptureRunner;\n  build: Build;\n  project: Project;\n  stories: StoryEntry[];\n  viewports: Viewport[];\n  storybookDir: string;\n  browsers: readonly CaptureTarget[];\n  affectedPaths: string[] | null;\n  /** Explicit render budget; unset scales with the number of captures. */\n  renderTimeoutMs?: number | undefined;\n  logger: Logger | undefined;\n  /** Records the pass on the build attempt (partitioning, progress, failures). */\n  recordLog?: AttemptLogRecorder | undefined;\n  /** Called on every screenshot taken, so a long healthy render keeps its job's lease. */\n  progress?: CaptureProgress | undefined;\n  /**\n   * Handle for this job's render calls, so cancelling it reaches only them: the shard id when\n   * rendering a shard (sibling shards of one build render at once), the build id otherwise.\n   */\n  runId?: string | undefined;\n  /** Mints the signed URL for a `reach: \"url\"` target at the start of each pass. */\n  storybookUrl?: StorybookUrlSource | undefined;\n}\n\n/** Everything the passes produced, every row tagged with its engine. */\nexport interface MatrixResult {\n  captures: RenderedSnapshot[];\n  failures: RenderFailure[];\n  inherited: InheritedStory[];\n  /** Stories rendered, summed over engines. */\n  renderCount: number;\n}\n\n/**\n * Capture every story on every engine, one engine at a time (browsers are\n * heavy; parallel launches would multiply memory). Each engine resolves its\n * own baselines, so affected capture inherits per engine.\n */\nexport async function captureAcrossBrowsers(input: MatrixInput): Promise<MatrixResult> {\n  const result: MatrixResult = { captures: [], failures: [], inherited: [], renderCount: 0 };\n  for (const browser of input.browsers) {\n    // oxlint-disable-next-line no-await-in-loop -- engines run sequentially by design\n    const pass = await captureOnBrowser(input, browser);\n    result.captures.push(...pass.captures);\n    result.failures.push(...pass.failures);\n    result.inherited.push(...pass.inherited);\n    result.renderCount += pass.renderCount;\n  }\n  return result;\n}\n\n/** Which stories each engine renders and which inherit their baseline, decided before any render. */\nexport interface PartitionedWork {\n  work: EngineWork[];\n  inherited: InheritedStory[];\n}\n\n/**\n * Affected-capture partitioning for every engine, without rendering: the plan stage of a sharded\n * capture decides what to render (and how to slice it) before any browser starts.\n */\nexport async function partitionBrowsers(input: MatrixInput): Promise<PartitionedWork> {\n  const { project, build } = input;\n  const work: EngineWork[] = [];\n  const inherited: InheritedStory[] = [];\n  for (const browser of input.browsers) {\n    // oxlint-disable-next-line no-await-in-loop -- one engine at a time, like the render loop\n    const partition = await partitionAffectedStories({\n      db: input.db,\n      tables: input.tables,\n      projectId: project.id,\n      branch: build.gitBranch,\n      defaultBranch: project.gitDefaultBranch,\n      stories: input.stories,\n      viewports: input.viewports,\n      browser,\n      affectedPaths: input.affectedPaths,\n    });\n    work.push({ browser, stories: partition.render });\n    inherited.push(...tagged(partition.inherited, browser));\n  }\n  return { work, inherited };\n}\n\n/**\n * Render explicit per-engine work (one shard's slice), engine by engine. Nothing is inherited here.\n *\n * A story that crashes the browser is narrowed down and failed on its own, so it does not take the\n * rest of the slice with it — see {@link renderIsolating}.\n */\nexport async function renderWork(\n  input: MatrixInput,\n  work: readonly EngineWork[],\n): Promise<MatrixResult> {\n  const result: MatrixResult = { captures: [], failures: [], inherited: [], renderCount: 0 };\n  for (const engine of work) {\n    const mirror = mirrorAttemptLog(input.logger, input.recordLog, flakyDowngrade(input.stories));\n    try {\n      // oxlint-disable-next-line no-await-in-loop -- engines run sequentially by design\n      const pass = await isolatedPass(input, engine.browser, mirror, engine.stories, []);\n      result.captures.push(...pass.captures);\n      result.failures.push(...pass.failures);\n      result.renderCount += pass.renderCount;\n    } finally {\n      // oxlint-disable-next-line no-await-in-loop -- flush before the next engine starts\n      await mirror.flush();\n    }\n  }\n  return result;\n}\n\n/**\n * One engine's render, with a crashing story narrowed down and failed on its own rather than taking\n * the rest of the pass with it — see {@link renderIsolating}.\n */\nasync function isolatedPass(\n  input: MatrixInput,\n  browser: CaptureTarget,\n  mirror: AttemptMirror,\n  toRender: StoryEntry[],\n  inherited: InheritedStory[],\n): Promise<MatrixResult> {\n  const pass = await renderIsolating(\n    toRender,\n    async (slice) => await attemptPass(input, browser, mirror, slice),\n    {\n      note: isolationNote(mirror, browser),\n      viewportsOf: (story) =>\n        resolveStoryViewports(story, input.viewports).map((viewport) => viewport.name),\n    },\n  );\n  return {\n    captures: fillEnvironment(pass.captures),\n    failures: pass.failures,\n    inherited,\n    renderCount: pass.renderCount,\n  };\n}\n\n/** One render pass that never throws: a crash comes back beside whatever it captured first. */\nasync function attemptPass(\n  input: MatrixInput,\n  browser: CaptureTarget,\n  mirror: AttemptMirror,\n  stories: StoryEntry[],\n): Promise<PassOutcome> {\n  const spooled: RenderedSnapshot[] = [];\n  try {\n    const pass = await renderPass(input, browser, mirror, stories, [], spooled);\n    return { captures: pass.captures, failures: pass.failures };\n  } catch (error) {\n    // The browser never started: no story is at fault, so it is not isolated or retried.\n    if (error instanceof TargetLaunchError) {\n      throw error;\n    }\n    mirror.log(\"warn\", \"render pass crashed, isolating the story at fault\", {\n      browser,\n      stories: stories.length,\n      captured: spooled.length,\n      err: error instanceof Error ? error.message : String(error),\n    });\n    return { captures: spooled, failures: [], error };\n  }\n}\n\n/** Record how a crash was narrowed down on the attempt log. */\nfunction isolationNote(mirror: AttemptMirror, browser: CaptureTarget): IsolationNote {\n  return (event, fields) => {\n    if (event === \"poisoned\") {\n      mirror.log(\"error\", \"story crashed the browser on its own\", { browser, ...fields });\n      return;\n    }\n    const message =\n      event === \"isolating\"\n        ? \"retrying the stories a crash interrupted\"\n        : \"giving up on the stories left after repeated crashes\";\n    mirror.log(\"warn\", message, { browser, ...fields });\n  };\n}\n\n/**\n * Give captures spooled before a crash the environment a later pass reported: every pass of an\n * engine runs on the same browser build and host, so the one fingerprint covers them all.\n */\nfunction fillEnvironment(captures: RenderedSnapshot[]): RenderedSnapshot[] {\n  const known = captures.find((capture) => capture.environment)?.environment;\n  if (!known) {\n    return captures;\n  }\n  for (const capture of captures) {\n    capture.environment ??= known;\n  }\n  return captures;\n}\n\nasync function captureOnBrowser(input: MatrixInput, browser: CaptureTarget): Promise<MatrixResult> {\n  const mirror = mirrorAttemptLog(input.logger, input.recordLog, flakyDowngrade(input.stories));\n  try {\n    return await passOnBrowser(input, browser, mirror);\n  } finally {\n    await mirror.flush();\n  }\n}\n\n/**\n * Failures of flaky stories are non-blocking, so the attempt log shows them as\n * warnings (matching \"flaky story failed (non-blocking)\"), not errors.\n */\nfunction flakyDowngrade(\n  stories: StoryEntry[],\n): (level: CaptureLogLevel, fields?: Record<string, unknown>) => CaptureLogLevel {\n  const flaky = new Set(stories.filter((story) => isFlakyStory(story)).map((story) => story.id));\n  return (level, fields) =>\n    level === \"error\" && typeof fields?.[\"storyId\"] === \"string\" && flaky.has(fields[\"storyId\"])\n      ? \"warn\"\n      : level;\n}\n\nasync function passOnBrowser(\n  input: MatrixInput,\n  browser: CaptureTarget,\n  mirror: AttemptMirror,\n): Promise<MatrixResult> {\n  const { project, build } = input;\n  const partition = await partitionAffectedStories({\n    db: input.db,\n    tables: input.tables,\n    projectId: project.id,\n    branch: build.gitBranch,\n    defaultBranch: project.gitDefaultBranch,\n    stories: input.stories,\n    viewports: input.viewports,\n    browser,\n    affectedPaths: input.affectedPaths,\n  });\n  mirror.log(\"info\", \"affected capture partitioned\", {\n    browser,\n    rendered: partition.render.length,\n    inherited: partition.inherited.length,\n    total: input.stories.length,\n  });\n  const inherited = tagged(partition.inherited, browser);\n  if (partition.render.length === 0) {\n    return { captures: [], failures: [], inherited, renderCount: 0 };\n  }\n  return await isolatedPass(input, browser, mirror, partition.render, inherited);\n}\n\n/**\n * One engine's render call. `spooled` may be supplied by the caller so that the screenshots taken\n * before a crash survive the throw (they stream in through `onCapture`).\n */\nasync function renderPass(\n  input: MatrixInput,\n  browser: CaptureTarget,\n  mirror: AttemptMirror,\n  toRender: StoryEntry[],\n  inherited: InheritedStory[],\n  spooled: RenderedSnapshot[] = [],\n): Promise<MatrixResult> {\n  const expected = toRender.flatMap((story) =>\n    resolveStoryViewports(story, input.viewports),\n  ).length;\n  const rendered = await renderInSlices({\n    runner: input.runner,\n    request: renderRequest(input, browser, toRender, spooled, { mirror, expected }),\n    browser,\n    storybookUrl: input.storybookUrl,\n    captureCount: (story) => resolveStoryViewports(story, input.viewports).length,\n    renderTimeoutMs: input.renderTimeoutMs,\n  });\n  mirror.log(\"info\", \"render pass finished\", {\n    browser,\n    captured: spooled.length + rendered.captures.length,\n    failed: rendered.failures.length,\n    expected,\n    imageEngine: currentImageEngine(),\n  });\n  const { environment } = rendered;\n  return {\n    captures: withEnvironment([...spooled, ...tagged(rendered.captures, browser)], environment),\n    failures: tagged(rendered.failures, browser),\n    inherited,\n    renderCount: toRender.length,\n  };\n}\n\n/** The render call for one engine; captures stream into `spooled` as they are taken. */\nfunction renderRequest(\n  input: MatrixInput,\n  browser: CaptureTarget,\n  stories: StoryEntry[],\n  spooled: RenderedSnapshot[],\n  progress: { mirror: AttemptMirror; expected: number },\n): RenderRequest {\n  const { project, build } = input;\n  return {\n    onCapture: async (capture) => {\n      spooled.push(await spoolCapture(input, browser, capture));\n      input.progress?.();\n      logProgress(progress, browser, spooled.length);\n    },\n    buildId: build.id,\n    runId: input.runId ?? build.id,\n    storybookDir: input.storybookDir,\n    stories,\n    viewports: input.viewports,\n    logger: progress.mirror.logger,\n    executePlay: project.executePlay ?? false,\n    playTimeoutMs: project.playTimeoutMs ?? 10_000,\n    runA11y: (project.runA11y ?? true) && browser === primaryTargetOf(resolveBrowsers(project)),\n    target: browser,\n  };\n}\n\n/** Screenshots between progress lines on the attempt log. */\nconst PROGRESS_EVERY = 10;\n\n/** Record \"captured N/M\" every few screenshots so a long render keeps showing movement. */\nfunction logProgress(\n  progress: { mirror: AttemptMirror; expected: number },\n  browser: CaptureTarget,\n  captured: number,\n): void {\n  if (captured % PROGRESS_EVERY !== 0) return;\n  progress.mirror.log(\"info\", `captured ${captured}/${progress.expected} screenshots`, {\n    browser,\n    captured,\n    expected: progress.expected,\n  });\n}\n\n/**\n * Write a screenshot to storage the moment it is captured and keep only its\n * metadata, so memory holds the pages in flight rather than the whole build.\n */\nasync function spoolCapture(\n  input: MatrixInput,\n  browser: CaptureTarget,\n  capture: RenderedSnapshot,\n): Promise<RenderedSnapshot> {\n  assertScreenshotBuffer(capture.screenshot);\n  const storedPath = await storeScreenshot(input.storage, input.project.id, capture.screenshot);\n  return { ...capture, browser, screenshot: EMPTY_SCREENSHOT, stored: true, storedPath };\n}\n\nconst EMPTY_SCREENSHOT = Buffer.alloc(0);\n\n/** Attach the render pass's environment to captures that carry none (a slice may have set its own). */\nfunction withEnvironment(\n  captures: RenderedSnapshot[],\n  environment: RenderedSnapshot[\"environment\"],\n): RenderedSnapshot[] {\n  if (environment) {\n    for (const capture of captures) {\n      capture.environment ??= environment;\n    }\n  }\n  return captures;\n}\n\n/** Copy each row with its engine (runners may reuse result objects across calls). */\nfunction tagged<T extends { browser?: string | undefined }>(\n  rows: T[],\n  browser: CaptureTarget,\n): T[] {\n  return rows.map((row) => Object.assign({}, row, { browser }));\n}\n"],"mappings":"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"}

package/dist/capture/modes.d.mts

@@ -0,0 +1,25 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ModeMap } from "./adapter.mjs";
+//#region src/capture/modes.d.ts
+/** Upper bound on captures (global viewports + modes) per story. */
+declare const MAX_MODES_PER_STORY = 8;
+/**
+ * Baseline identity for a mode name: lower-case, URL/path-safe, stable under
+ * whitespace/case edits. Throws for names with no usable characters.
+ */
+declare function modeSlug(name: string): string;
+/** Keep only allow-listed modes; `null`/empty allowlist keeps all. */
+declare function filterModes(modes: ModeMap | undefined, allowlist: readonly string[] | null): ModeMap | undefined;
+/** Parse the project's JSON `modesAllowlist` column; `null` when unset/invalid. */
+declare function parseModesAllowlist(raw: string | null | undefined): string[] | null;
+/**
+ * Encode globals for Storybook's `globals` URL arg (`a:b;c.d:e`). Nested
+ * objects flatten to dot paths; booleans/null/undefined/hex colors use the
+ * `!`-prefixed forms Storybook parses. Plain strings pass through (Storybook
+ * only accepts `[a-zA-Z0-9 _-]` and silently drops anything else).
+ */
+declare function buildGlobalsParam(globals: Record<string, unknown>): string;
+//#endregion
+export { MAX_MODES_PER_STORY, buildGlobalsParam, filterModes, modeSlug, parseModesAllowlist };
+//# sourceMappingURL=modes.d.mts.map