@hajimism/dek 0.1.0

package/src/core/mv.ts

@@ -0,0 +1,293 @@
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename } from "node:path";
+import { deckPaths } from "./deck-paths.ts";
+import { DekError } from "./error.ts";
+import { escapeRegExp } from "./escape.ts";
+import { joinLines, sectionChunks, splitLines } from "./lines.ts";
+import { asResolvedDeck, type ResolvedDeck, requireSection, SLIDE_SIDECARS } from "./resolve.ts";
+import { Id } from "./schema.ts";
+import { deckLayouts, skeletonHtml } from "./skeleton.ts";
+import { skeletonRecord } from "./skeleton-record.ts";
+import { renameTableKeys } from "./toml-keys.ts";
+
+export function renameSection(dir: string, from: string, to: string): void;
+export function renameSection(source: ResolvedDeck, from: string, to: string): void;
+export function renameSection(input: string | ResolvedDeck, from: string, to: string): void {
+  if (!Id.safeParse(to).success) {
+    throw new DekError(`invalid id "${to}"`, { hint: "use [a-z0-9-] with at least one letter" });
+  }
+  const { deck } = asResolvedDeck(input);
+  const has = (slug: string): boolean => deck.deck.sections.some((entry) => entry.slug === slug);
+  if (!has(from) && has(to)) {
+    // script.md was edited first; only the files still carry the old id.
+    const steps = slideFileSteps(deck, from, to);
+    if (steps.length === 0 && !existsSync(deckPaths(deck.dir).slide(to, ".html"))) {
+      throw new DekError(`slide "${from}" not found`, {
+        path: deckPaths(deck.dir).slide(from, ".html"),
+        hint: "run `dekc lint` to see which slides have no section",
+      });
+    }
+    applySteps(steps);
+    return;
+  }
+  const section = requireSection(deck, from);
+  if (has(to)) {
+    throw new DekError(`section "${to}" already exists`, {
+      path: deck.scriptPath,
+      hint: "run `dekc ls`",
+    });
+  }
+
+  const source = readFileSync(deck.scriptPath, "utf8");
+  const lines = splitLines(source);
+  const headingIndex = section.line - 1;
+  const heading = lines[headingIndex];
+  if (heading === undefined) {
+    throw new DekError(`section "${from}" heading not found`, {
+      path: deck.scriptPath,
+      hint: "run `dekc ls`",
+    });
+  }
+  lines[headingIndex] = rewriteHeadingId(heading, from, to);
+  applySteps([
+    writeStep(deck.scriptPath, source, joinLines(source, lines)),
+    ...slideFileSteps(deck, from, to),
+  ]);
+}
+
+/**
+ * The steps that leave `slides/<to>.*` holding the slide and voice.toml pointing at it, from
+ * whichever files the author already moved. Each file is settled on its own: one that is only at
+ * `<from>` moves, one already at `<to>` stays, and a skeleton dek wrote gives way to the author's
+ * file on the other side, as the dev server writes one for any id the script names. Only two files
+ * the author wrote, one under each id, stop the rename; everything that could stop it is worked
+ * out before any file changes.
+ */
+function slideFileSteps(deck: ResolvedDeck["deck"], from: string, to: string): FileStep[] {
+  const paths = deckPaths(deck.dir);
+  const layouts = deckLayouts(deck.dir);
+  const record = skeletonRecord(deck.dir);
+  const read = (slug: string): SlideFile | undefined => {
+    const path = paths.slide(slug, ".html");
+    if (!existsSync(path)) {
+      return undefined;
+    }
+    const html = readFileSync(path, "utf8");
+    return { path, html, authored: !record.owns(html, skeletonHtml(deck.deck, slug, layouts)) };
+  };
+  const source = read(from);
+  const target = read(to);
+  if (source?.authored && target?.authored) {
+    throw bothHold(source.path, target.path, from, to);
+  }
+  for (const ext of SLIDE_SIDECARS) {
+    if (existsSync(paths.slide(from, ext)) && existsSync(paths.slide(to, ext))) {
+      throw bothHold(paths.slide(from, ext), paths.slide(to, ext), from, to);
+    }
+  }
+
+  const voice = planVoiceBeatKeys(deck.dir, from, to);
+  const steps: FileStep[] = [];
+  // The HTML that ends up at <to>: the author's, wherever it is; else whichever is there.
+  const toPath = paths.slide(to, ".html");
+  const kept = source && (source.authored || !target) ? source : target;
+  if (source && kept === source) {
+    steps.push(
+      target ? writeStep(toPath, target.html, source.html) : renameStep(source.path, toPath),
+    );
+  }
+  if (source && target) {
+    steps.push(removeStep(source.path, source.html));
+  }
+  if (kept) {
+    const next = relabel(kept.html, from, to);
+    if (next !== kept.html) {
+      steps.push(writeStep(toPath, kept.html, next));
+    }
+  }
+  for (const ext of SLIDE_SIDECARS) {
+    const sidecar = paths.slide(from, ext);
+    if (existsSync(sidecar)) {
+      steps.push(renameStep(sidecar, paths.slide(to, ext)));
+    }
+  }
+  if (voice) {
+    steps.push(writeStep(voice.path, voice.source, voice.next));
+  }
+  return steps;
+}
+
+/** A slide's HTML under one id, and whether the author wrote it rather than dek. */
+type SlideFile = { path: string; html: string; authored: boolean };
+
+/** A slide's own `data-slug`, pointed at its new id. */
+function relabel(html: string, from: string, to: string): string {
+  return html.replaceAll(`data-slug="${from}"`, `data-slug="${to}"`);
+}
+
+function bothHold(fromPath: string, toPath: string, from: string, to: string): DekError {
+  const fromName = `slides/${basename(fromPath)}`;
+  const toName = `slides/${basename(toPath)}`;
+  const what = fromPath.endsWith(".html") ? "hold a slide you wrote" : "exist";
+  return new DekError(`${fromName} and ${toName} both ${what}`, {
+    path: fromPath,
+    hint: `merge them into ${toName} and remove ${fromName}, then run \`dekc mv ${from} ${to}\` again`,
+  });
+}
+
+/** One file change `dekc mv` makes, with how to take it back. */
+type FileStep = { path: string; apply: () => void; undo: () => void };
+
+function writeStep(path: string, before: string, after: string): FileStep {
+  return {
+    path,
+    apply: () => writeFileSync(path, after),
+    undo: () => writeFileSync(path, before),
+  };
+}
+
+function removeStep(path: string, before: string): FileStep {
+  return { path, apply: () => unlinkSync(path), undo: () => writeFileSync(path, before) };
+}
+
+function renameStep(from: string, to: string): FileStep {
+  return { path: to, apply: () => renameSync(from, to), undo: () => renameSync(to, from) };
+}
+
+/** Applies every step, or none: a failure takes back the steps already applied. */
+function applySteps(steps: FileStep[]): void {
+  const done: FileStep[] = [];
+  try {
+    for (const step of steps) {
+      step.apply();
+      done.push(step);
+    }
+  } catch (error) {
+    const stuck: string[] = [];
+    for (const step of done.reverse()) {
+      try {
+        step.undo();
+      } catch {
+        stuck.push(step.path);
+      }
+    }
+    if (stuck.length > 0) {
+      throw new DekError(`dekc mv failed and could not restore ${stuck.join(", ")}`, {
+        cause: error,
+        hint: "check these files by hand",
+      });
+    }
+    throw error;
+  }
+}
+
+/**
+ * The voice.toml with its `[beats]` keys (`slug`, `"slug/beat"`) pointing at
+ * the renamed slide, or undefined when nothing changes. The rewrite is checked
+ * against the parsed file, so a layout it cannot rewrite stops the rename.
+ */
+function planVoiceBeatKeys(
+  deckDir: string,
+  from: string,
+  to: string,
+): { path: string; source: string; next: string } | undefined {
+  const path = deckPaths(deckDir).voiceToml;
+  if (!existsSync(path)) {
+    return undefined;
+  }
+  const source = readFileSync(path, "utf8");
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = Bun.TOML.parse(source) as Record<string, unknown>;
+  } catch {
+    // An unreadable voice.toml is the voice loader's to report, not mv's.
+    return undefined;
+  }
+  const beats = parsed.beats;
+  if (beats === null || typeof beats !== "object") {
+    return undefined;
+  }
+  const rename = (key: string): string | undefined => renameBeatKey(key, from, to);
+  const expected = {
+    ...parsed,
+    beats: Object.fromEntries(
+      Object.entries(beats).map(([key, value]) => [rename(key) ?? key, value]),
+    ),
+  };
+  const next = renameTableKeys(source, "beats", rename);
+  let actual: unknown;
+  try {
+    actual = Bun.TOML.parse(next);
+  } catch {
+    actual = undefined;
+  }
+  if (!Bun.deepEquals(actual, expected, true)) {
+    throw new DekError(`cannot rewrite the [beats] keys for "${from}" in voice.toml`, {
+      path,
+      hint: `write them as [beats."${from}/…"] tables or dotted keys, or rename them to "${to}" by hand`,
+    });
+  }
+  return next === source ? undefined : { path, source, next };
+}
+
+/** `slug` or `slug/beat` for the renamed slide, else undefined. */
+function renameBeatKey(key: string, from: string, to: string): string | undefined {
+  const slash = key.indexOf("/");
+  const slug = slash < 0 ? key : key.slice(0, slash);
+  return slug === from ? `${to}${slash < 0 ? "" : key.slice(slash)}` : undefined;
+}
+
+/** Where a moved section lands: right before one section, or right after it. */
+export type SectionPlace = { before: string } | { after: string };
+
+export function reorderSection(dir: string, slug: string, place: SectionPlace): void;
+export function reorderSection(source: ResolvedDeck, slug: string, place: SectionPlace): void;
+export function reorderSection(
+  input: string | ResolvedDeck,
+  slug: string,
+  place: SectionPlace,
+): void {
+  const target = "before" in place ? place.before : place.after;
+  const { deck } = asResolvedDeck(input);
+  const sections = deck.deck.sections;
+  const fromIndex = sections.findIndex((entry) => entry.slug === slug);
+  if (fromIndex < 0) {
+    requireSection(deck, slug);
+  }
+  const targetIndex = sections.findIndex((entry) => entry.slug === target);
+  if (targetIndex < 0) {
+    requireSection(deck, target);
+  }
+
+  const source = readFileSync(deck.scriptPath, "utf8");
+  const lines = splitLines(source);
+  const firstLine = sections[0]?.line;
+  if (firstLine === undefined) {
+    return;
+  }
+  const head = lines.slice(0, firstLine - 1);
+  const chunks = sectionChunks(
+    lines,
+    sections.map((section) => section.line),
+  );
+
+  const moved = chunks.splice(fromIndex, 1)[0];
+  if (!moved) {
+    return;
+  }
+  const remainingTarget = chunks.findIndex((_, index) => {
+    const original = index < fromIndex ? index : index + 1;
+    return original === targetIndex;
+  });
+  const insertAt = "before" in place ? remainingTarget : remainingTarget + 1;
+  chunks.splice(insertAt, 0, moved);
+  writeFileSync(deck.scriptPath, joinLines(source, [...head, ...chunks.flat()]));
+}
+
+function rewriteHeadingId(heading: string, from: string, to: string): string {
+  const attr = new RegExp(`\\{#${escapeRegExp(from)}\\}`);
+  if (attr.test(heading)) {
+    return heading.replace(attr, `{#${to}}`);
+  }
+  return `${heading} {#${to}}`;
+}

package/src/core/ogp.ts

@@ -0,0 +1,99 @@
+import { escapeAttr } from "./escape.ts";
+
+export type OgpImage = {
+  url: string;
+  width: number;
+  height: number;
+};
+
+export type OgpInput = {
+  title: string;
+  description?: string;
+  event?: string;
+  date?: string;
+  lang: string;
+  /** The page's own absolute URL; left out, the page has no og:url. */
+  url?: string;
+  image?: OgpImage;
+};
+
+/** The region Open Graph pairs with a bare language, as `og:locale` wants `ll_CC`. */
+const USUAL_REGION: Record<string, string> = {
+  ja: "JP",
+  en: "US",
+  zh: "CN",
+  ko: "KR",
+  de: "DE",
+  fr: "FR",
+  es: "ES",
+  it: "IT",
+  pt: "PT",
+  nl: "NL",
+  ru: "RU",
+};
+
+function ogLocale(lang: string): string | undefined {
+  const [language = "", ...rest] = lang.split("-");
+  const region = rest.find((part) => /^[A-Za-z]{2}$/.test(part));
+  const code = language.toLowerCase();
+  const country = region?.toUpperCase() ?? USUAL_REGION[code];
+  return country ? `${code}_${country}` : undefined;
+}
+
+/**
+ * What a link to the page shows when someone shares it: title, description, and, once the
+ * page knows where it is served from, its URL and a picture of the first slide. Crawlers only
+ * fetch an absolute og:image, so without a URL there is no image at all.
+ */
+export function ogpHead(input: OgpInput): string {
+  const description =
+    input.description ?? ([input.event, input.date].filter(Boolean).join(" · ") || undefined);
+  const locale = ogLocale(input.lang);
+  const tags: Array<[kind: "name" | "property", key: string, value: string | number]> = [];
+  if (description) {
+    tags.push(["name", "description", description]);
+  }
+  tags.push(["property", "og:type", "website"], ["property", "og:title", input.title]);
+  if (description) {
+    tags.push(["property", "og:description", description]);
+  }
+  if (locale) {
+    tags.push(["property", "og:locale", locale]);
+  }
+  if (input.url) {
+    tags.push(["property", "og:url", input.url]);
+  }
+  if (input.image) {
+    tags.push(
+      ["property", "og:image", input.image.url],
+      ["property", "og:image:width", input.image.width],
+      ["property", "og:image:height", input.image.height],
+      ["property", "og:image:alt", input.title],
+    );
+  }
+  tags.push(["name", "twitter:card", input.image ? "summary_large_image" : "summary"]);
+  const lines = tags.map(
+    ([kind, key, value]) => `<meta ${kind}="${key}" content="${escapeAttr(String(value))}">`,
+  );
+  if (input.url) {
+    lines.push(`<link rel="canonical" href="${escapeAttr(input.url)}">`);
+  }
+  return lines.join("\n  ");
+}
+
+/**
+ * The URL dist/ is served from, ending in a slash so a deck's file name joins onto it, or
+ * undefined when a crawler could not fetch it: not absolute http(s), or carrying a query.
+ */
+export function parsePublicUrl(value: string): string | undefined {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return undefined;
+  }
+  if ((url.protocol !== "https:" && url.protocol !== "http:") || url.search || url.hash) {
+    return undefined;
+  }
+  return url.href.endsWith("/") ? url.href : `${url.href}/`;
+}

package/src/core/optional.ts

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+export function walkUp<T>(startDir: string, visit: (dir: string) => T | undefined): T | undefined {
+  let dir = resolve(startDir);
+  while (true) {
+    const hit = visit(dir);
+    if (hit !== undefined) {
+      return hit;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return undefined;
+    }
+    dir = parent;
+  }
+}
+
+export function resolveBinFromAncestors(name: string, startDir: string): string | undefined {
+  return walkUp(startDir, (dir) => {
+    const bin = join(dir, "node_modules", ".bin", name);
+    return existsSync(bin) ? bin : undefined;
+  });
+}

package/src/core/overflow.ts

@@ -0,0 +1,220 @@
+import type { Box, MeasuredElement } from "./slide-measure.ts";
+
+export type Edge = "top" | "right" | "bottom" | "left";
+
+export const EDGES: Edge[] = ["top", "right", "bottom", "left"];
+
+export type Overflow = {
+  box: string;
+  text?: string;
+  /** Pixels past each edge it crosses. */
+  by: Partial<Record<Edge, number>>;
+  origin?: OverflowOrigin;
+  /** The ancestor that cuts the text off, when the edge is that ancestor's and not the frame's. */
+  clip?: string;
+};
+
+/** An overflow as measured: with the index of its element, which finds it again in a second measure. */
+type LocatedOverflow = Overflow & { element: number };
+
+/**
+ * What put an overflow past the edge, found by taking the page apart: the slide script's draw,
+ * the slide's own CSS, or neither, which leaves the content itself too big for the theme.
+ */
+export type OverflowOrigin = "script" | "slide" | "content";
+
+/** Whether `element` crosses an edge of the slide at all, whatever its parent does. */
+export function crossesEdge(
+  slide: Box,
+  element: Pick<MeasuredElement, "rect"> & {
+    opacity?: number;
+    decorative?: boolean;
+    clip?: MeasuredElement["clip"];
+  },
+): boolean {
+  return (
+    (element.opacity ?? 1) >= 0.01 &&
+    element.decorative !== true &&
+    Object.keys(overflowAmounts(slide, visibleRect(element))).length > 0
+  );
+}
+
+/** An element's box, less what an ancestor inside the slide cuts off. */
+function visibleRect({ rect, clip }: Pick<MeasuredElement, "rect" | "clip">): Box {
+  return clip
+    ? {
+        left: Math.max(rect.left, clip.rect.left),
+        top: Math.max(rect.top, clip.rect.top),
+        right: Math.min(rect.right, clip.rect.right),
+        bottom: Math.min(rect.bottom, clip.rect.bottom),
+      }
+    : rect;
+}
+
+function overflowAmounts(slide: Box, rect: Box): Partial<Record<Edge, number>> {
+  if (rect.right <= rect.left || rect.bottom <= rect.top) {
+    return {};
+  }
+  const past: Record<Edge, number> = {
+    top: slide.top - rect.top,
+    right: rect.right - slide.right,
+    bottom: rect.bottom - slide.bottom,
+    left: slide.left - rect.left,
+  };
+  const by: Partial<Record<Edge, number>> = {};
+  for (const edge of EDGES) {
+    // Sub-pixel layout rounding is not an overflow anyone can see.
+    if (past[edge] >= 1) {
+      by[edge] = Math.round(past[edge]);
+    }
+  }
+  return by;
+}
+
+/**
+ * The elements that cross an edge of the slide, each reported only for the
+ * edges its parent stays inside: a list that runs off the bottom is one
+ * finding, not one per item.
+ */
+export function findOverflows(
+  slide: Box,
+  elements: Array<
+    Pick<MeasuredElement, "box" | "parent" | "rect" | "text"> & {
+      opacity?: number;
+      decorative?: boolean;
+      clip?: MeasuredElement["clip"];
+    }
+  >,
+): LocatedOverflow[] {
+  // An invisible element, such as a beat before it shows, overflows nothing anyone sees, and
+  // decoration, such as a glow, may bleed off the slide as it likes. What an ancestor inside the
+  // slide cuts off is not past the frame; findClippedText says when that is text.
+  const amounts = elements.map((element) =>
+    (element.opacity ?? 1) < 0.01 || element.decorative === true
+      ? {}
+      : overflowAmounts(slide, visibleRect(element)),
+  );
+  const found: LocatedOverflow[] = [];
+  elements.forEach((element, index) => {
+    const parent = amounts[element.parent] ?? {};
+    const by: Partial<Record<Edge, number>> = {};
+    for (const edge of EDGES) {
+      const amount = amounts[index]?.[edge];
+      if (amount !== undefined && parent[edge] === undefined) {
+        by[edge] = amount;
+      }
+    }
+    if (Object.keys(by).length > 0) {
+      found.push({
+        box: element.box,
+        ...(element.text ? { text: element.text } : {}),
+        by,
+        element: index,
+      });
+    }
+  });
+  return found;
+}
+
+/**
+ * The texts an ancestor inside the slide cuts off, with `overflow: hidden` or the like: each by how
+ * far its lines run past what the ancestor shows. A truncation the author asked for, an ellipsis
+ * or a line clamp, is left alone, and so are decoration and text nobody sees.
+ */
+export function findClippedText(
+  elements: Array<
+    Pick<MeasuredElement, "box" | "text" | "textRects" | "opacity" | "decorative" | "clip">
+  >,
+): LocatedOverflow[] {
+  return elements.flatMap((element, index) => {
+    const { clip } = element;
+    if (!clip || clip.intended || element.decorative || element.opacity < 0.01) {
+      return [];
+    }
+    const lines = element.textRects.filter(
+      (rect) => rect.right > rect.left && rect.bottom > rect.top,
+    );
+    if (lines.length === 0) {
+      return [];
+    }
+    const text = {
+      left: Math.min(...lines.map((rect) => rect.left)),
+      top: Math.min(...lines.map((rect) => rect.top)),
+      right: Math.max(...lines.map((rect) => rect.right)),
+      bottom: Math.max(...lines.map((rect) => rect.bottom)),
+    };
+    const by = overflowAmounts(clip.rect, text);
+    return Object.keys(by).length === 0
+      ? []
+      : [
+          {
+            box: element.box,
+            ...(element.text ? { text: element.text } : {}),
+            by,
+            clip: clip.box,
+            element: index,
+          },
+        ];
+  });
+}
+
+/** One text as the page draws it, for finding which texts are drawn over which. */
+type TextBox = { rects: Box[]; opacity: number };
+
+/**
+ * The pairs of texts whose lines are drawn over each other, a folio or running head a
+ * pseudo-element draws included, first in the page first. Lines that only touch, as the words of
+ * one sentence set in two elements do, are not a collision: the lines must cross by a few pixels
+ * each way and share a fifth of the smaller one.
+ */
+export function findCollisions<T extends TextBox>(texts: T[]): Array<[T, T]> {
+  const MIN_CROSS = 4;
+  const MIN_SHARE = 0.2;
+  const area = (rect: Box): number => (rect.right - rect.left) * (rect.bottom - rect.top);
+  const crosses = (a: Box, b: Box): boolean => {
+    const width = Math.min(a.right, b.right) - Math.max(a.left, b.left);
+    const height = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
+    return (
+      width >= MIN_CROSS &&
+      height >= MIN_CROSS &&
+      width * height >= MIN_SHARE * Math.min(area(a), area(b))
+    );
+  };
+  const shown = texts.filter((text) => text.opacity >= 0.01 && text.rects.length > 0);
+  const found: Array<[T, T]> = [];
+  for (const [at, one] of shown.entries()) {
+    for (const other of shown.slice(at + 1)) {
+      if (one.rects.some((a) => other.rects.some((b) => crosses(a, b)))) {
+        found.push([one, other]);
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Whether two texts take one place, as the numbers a count-up stacks in one cell do: the box their
+ * lines span shares at least half of each. A callout laid over a label is far larger than the
+ * label, and takes no place of the label's.
+ */
+export function samePlace(a: Pick<TextBox, "rects">, b: Pick<TextBox, "rects">): boolean {
+  const span = ({ rects }: Pick<TextBox, "rects">): Box => ({
+    left: Math.min(...rects.map((rect) => rect.left)),
+    top: Math.min(...rects.map((rect) => rect.top)),
+    right: Math.max(...rects.map((rect) => rect.right)),
+    bottom: Math.max(...rects.map((rect) => rect.bottom)),
+  });
+  const area = (box: Box): number =>
+    Math.max(0, box.right - box.left) * Math.max(0, box.bottom - box.top);
+  const [one, other] = [span(a), span(b)];
+  const shared = area({
+    left: Math.max(one.left, other.left),
+    top: Math.max(one.top, other.top),
+    right: Math.min(one.right, other.right),
+    bottom: Math.min(one.bottom, other.bottom),
+  });
+  return shared >= 0.5 * Math.max(area(one), area(other));
+}
+
+/** Two texts drawn over each other: the one first in the page, and the one it collides with. */
+export type Collision = { box: string; text?: string; other: string; otherText?: string };

package/src/core/page-pool.ts

@@ -0,0 +1,53 @@
+/** The part of a Playwright page the pool drives. */
+type PoolPage = {
+  goto(url: string): Promise<unknown>;
+  close(): Promise<void>;
+};
+
+/**
+ * How many pages a worker renders at once. A new page costs Chromium about
+ * as much as rendering a slide on it, so pages are kept and reused; a few at
+ * a time keep the renderer busy without keeping a long deck alive at once.
+ */
+const PAGE_LANES = 4;
+
+/**
+ * Visits every item on a small set of reused pages and returns the results
+ * in item order. Each visit starts from about:blank, so what one slide's
+ * scripts left on `window` never reaches the next. After a visit fails, no
+ * lane takes another item; every page is closed and the first failure thrown.
+ */
+export async function visitInPages<P extends PoolPage, T, R>(
+  items: readonly T[],
+  openPage: () => Promise<P>,
+  visit: (page: P, item: T) => Promise<R>,
+  { lanes = PAGE_LANES }: { lanes?: number } = {},
+): Promise<R[]> {
+  const results = new Array<R>(items.length);
+  let next = 0;
+  let failed = false;
+  let failure: unknown;
+  const lane = async (): Promise<void> => {
+    let page: P | undefined;
+    try {
+      page = await openPage();
+      while (!failed && next < items.length) {
+        const index = next++;
+        await page.goto("about:blank");
+        results[index] = await visit(page, items[index] as T);
+      }
+    } catch (error) {
+      if (!failed) {
+        failed = true;
+        failure = error;
+      }
+    } finally {
+      await page?.close();
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(lanes, items.length) }, lane));
+  if (failed) {
+    throw failure;
+  }
+  return results;
+}