@weasel-js/labkit 1.3.0 → 1.4.0-pre.0

package/src/annotations/capture.ts

@@ -0,0 +1,237 @@
+import { asNodeId, renderSceneToPixels } from '@weasel-js/core';
+import { serializeSvg } from '@weasel-js/svg';
+import { createMarkDrawOne, type MarkDrawOptions, resolveMarkStyle } from './drawOne';
+import type { MarkScene } from './store';
+import { markSvgNodes } from './svgNodes';
+import type { AnnotationData, CaptureOptions, CaptureResult, CaptureSource } from './types';
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+
+/** Which of the two composition routes an export takes. */
+export type CapturePlan = 'svg-document' | 'raster-stack';
+
+/**
+ * Vector all the way through, or both sides rasterized and stacked.
+ *
+ * An SVG base is the only one that nests: the marks serialize beside the
+ * artifact's own markup and the whole document rasterizes once at the end. A
+ * raster base, or none at all, takes the renderer's own path instead — which
+ * is also what draws marks onto transparency for a target that declares no
+ * base.
+ */
+export function capturePlan(base: CaptureSource | undefined, format: 'png' | 'svg'): CapturePlan {
+  if (format === 'svg') return 'svg-document';
+  return base?.kind === 'svg' ? 'svg-document' : 'raster-stack';
+}
+
+/** Re-frame a base's own `<svg>` onto the content box, keeping its `viewBox`.
+ *  Parsed rather than string-spliced: a base whose declared width disagrees
+ *  with its viewBox would otherwise land at the wrong scale. */
+function nestBaseSvg(markup: string, w: number, h: number): string {
+  const doc = new DOMParser().parseFromString(markup, 'image/svg+xml');
+  const root = doc.documentElement;
+  if (doc.getElementsByTagName('parsererror').length > 0 || root.localName !== 'svg') {
+    throw new Error("[labkit] a target's `base()` returned markup that is not an <svg> document");
+  }
+  root.setAttribute('x', '0');
+  root.setAttribute('y', '0');
+  root.setAttribute('width', String(w));
+  root.setAttribute('height', String(h));
+  return new XMLSerializer().serializeToString(root);
+}
+
+/** A raster base as an `<image>` filling the content box. An external `src`
+ *  round-trips as a reference, so the export is only self-contained when it
+ *  is already a `data:` URI. */
+function embedRasterBase(
+  base: CaptureSource,
+  w: number,
+  h: number,
+  onWarn?: (m: string) => void,
+): string {
+  const href =
+    base.kind === 'canvas' ? base.canvas.toDataURL() : base.kind === 'image' ? base.src : '';
+  if (base.kind === 'image' && !href.startsWith('data:')) {
+    onWarn?.(`base image '${href}' is a reference, so this SVG is not self-contained`);
+  }
+  return serializeSvg([{ kind: 'image', href, x: 0, y: 0, width: w, height: h }], {
+    viewBox: { x: 0, y: 0, width: w, height: h },
+  });
+}
+
+/** Every mark on a scene, as SVG nodes, styled the way the pane styles them. */
+function markNodesOf(scene: MarkScene, draw: MarkDrawOptions) {
+  return [...scene.renderOrder()].flatMap((id) => {
+    const node = scene.get(asNodeId(String(id)));
+    if (!node) return [];
+    return markSvgNodes(
+      { pose: node.pose, data: node.data as AnnotationData },
+      draw.content,
+      resolveMarkStyle(node.data as AnnotationData, draw),
+    );
+  });
+}
+
+export interface ComposeSvgArgs {
+  base?: CaptureSource;
+  scene: MarkScene;
+  draw: MarkDrawOptions;
+  scale: number;
+  onWarn?: (message: string) => void;
+}
+
+/**
+ * The base and the marks in one SVG document.
+ *
+ * The outer `viewBox` is the content box, so marks — which are already in it —
+ * need no transform, and `width`/`height` carry the export scale. Both halves
+ * nest as child `<svg>` elements, which each establish their own viewport and
+ * so keep their own `viewBox` maths out of this function.
+ */
+export function composeCaptureSvg(args: ComposeSvgArgs): string {
+  const { base, scene, draw, scale, onWarn } = args;
+  const { w, h } = draw.content;
+  const baseXml =
+    base === undefined
+      ? ''
+      : base.kind === 'svg'
+        ? nestBaseSvg(base.markup, w, h)
+        : embedRasterBase(base, w, h, onWarn);
+  // No width/height on the marks document: a nested <svg> without them fills
+  // the outer viewport exactly, which is the alignment this relies on.
+  const marksXml = serializeSvg(markNodesOf(scene, draw), {
+    viewBox: { x: 0, y: 0, width: w, height: h },
+    onWarn,
+  });
+  const outW = Math.max(1, Math.round(w * scale));
+  const outH = Math.max(1, Math.round(h * scale));
+  return `<svg xmlns="${SVG_NS}" width="${outW}" height="${outH}" viewBox="0 0 ${w} ${h}">${baseXml}${marksXml}</svg>`;
+}
+
+function context2d(width: number, height: number): CanvasRenderingContext2D {
+  const canvas = document.createElement('canvas');
+  canvas.width = width;
+  canvas.height = height;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) throw new Error('[labkit] capture needs a 2D canvas context, and this one has none');
+  return ctx;
+}
+
+function toPngBlob(canvas: HTMLCanvasElement): Promise<Blob> {
+  return new Promise((resolve, reject) => {
+    let done: (b: Blob | null) => void;
+    try {
+      done = (blob) =>
+        blob ? resolve(blob) : reject(new Error('[labkit] the browser produced no PNG'));
+      canvas.toBlob(done, 'image/png');
+    } catch (err) {
+      // A base referencing an image from another origin taints the canvas and
+      // `toBlob` throws SecurityError. Name the cause: the DOM exception on
+      // its own sends people looking at labkit.
+      reject(
+        new Error(
+          '[labkit] the capture canvas is tainted, so it cannot be read back — a base referencing a cross-origin image does this. Embed it as a data: URI.',
+          { cause: err },
+        ),
+      );
+    }
+  });
+}
+
+function loadImage(src: string): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(new Error(`[labkit] a capture base failed to load: ${src}`));
+    img.src = src;
+  });
+}
+
+/** Rasterize a composed document by handing it to the browser's own SVG
+ *  renderer — one pass over base and marks together. */
+async function rasterizeSvg(svg: string, width: number, height: number): Promise<Blob> {
+  const url = URL.createObjectURL(new Blob([svg], { type: 'image/svg+xml;charset=utf-8' }));
+  try {
+    const img = await loadImage(url);
+    const ctx = context2d(width, height);
+    ctx.drawImage(img, 0, 0, width, height);
+    return await toPngBlob(ctx.canvas);
+  } finally {
+    URL.revokeObjectURL(url);
+  }
+}
+
+/** Base pixels, then mark pixels over them. The marks come from
+ *  `renderSceneToPixels` rather than a readback of the live surface, so a
+ *  capture neither depends on nor disturbs what is on screen. */
+async function stackRaster(
+  args: ComposeSvgArgs & { width: number; height: number },
+): Promise<Blob> {
+  const { base, scene, draw, scale, width, height } = args;
+  const ctx = context2d(width, height);
+  if (base?.kind === 'image') ctx.drawImage(await loadImage(base.src), 0, 0, width, height);
+  else if (base?.kind === 'canvas') ctx.drawImage(base.canvas, 0, 0, width, height);
+
+  const raster = renderSceneToPixels({
+    scene,
+    sourceRect: { x: 0, y: 0, width: draw.content.w, height: draw.content.h },
+    scale: { x: scale, y: scale },
+    drawOne: createMarkDrawOne(draw),
+  });
+  // Through a second canvas rather than `putImageData` on this one, which
+  // replaces pixels instead of compositing and would erase the base.
+  const marks = context2d(raster.width, raster.height);
+  marks.putImageData(
+    new ImageData(Uint8ClampedArray.from(raster.data), raster.width, raster.height),
+    0,
+    0,
+  );
+  ctx.drawImage(marks.canvas, 0, 0, width, height);
+  return toPngBlob(ctx.canvas);
+}
+
+/** What a capture needs about the target it is exporting. */
+export interface CaptureArgs {
+  target: string;
+  scene: MarkScene;
+  draw: MarkDrawOptions;
+  base?: () => CaptureSource | Promise<CaptureSource>;
+  onWarn?: (message: string) => void;
+}
+
+/** Export one target's picture with its marks on it. */
+export async function captureTarget(
+  args: CaptureArgs,
+  opts: CaptureOptions = {},
+): Promise<CaptureResult> {
+  const format = opts.format ?? 'png';
+  const scale = opts.scale ?? 2;
+  const { content } = args.draw;
+  const width = Math.max(1, Math.round(content.w * scale));
+  const height = Math.max(1, Math.round(content.h * scale));
+  const base = await args.base?.();
+  const compose: ComposeSvgArgs = {
+    base,
+    scene: args.scene,
+    draw: args.draw,
+    scale,
+    onWarn: args.onWarn,
+  };
+
+  if (capturePlan(base, format) === 'raster-stack') {
+    return {
+      target: args.target,
+      blob: await stackRaster({ ...compose, width, height }),
+      format,
+      width,
+      height,
+    };
+  }
+
+  const svg = composeCaptureSvg(compose);
+  const blob =
+    format === 'svg'
+      ? new Blob([svg], { type: 'image/svg+xml;charset=utf-8' })
+      : await rasterizeSvg(svg, width, height);
+  return { target: args.target, blob, format, width, height };
+}

package/src/annotations/drawOne.test.ts

@@ -0,0 +1,56 @@
+import type { SceneNode, View } from '@weasel-js/core';
+import { describe, expect, it } from 'vitest';
+import { createMarkDrawOne } from './drawOne';
+import type { WorldRect } from './frac';
+import type { AnnotationData } from './types';
+
+const CONTENT = { w: 100, h: 60 };
+const VIEW = { x: 0, y: 0, zoom: 1 } as unknown as View;
+
+const node = (data: Partial<AnnotationData>, pose: WorldRect) =>
+  ({
+    id: 'n1',
+    kind: 'leaf',
+    layer: 'marks',
+    pose,
+    data: { target: 'flat', kind: 'rect', ...data } as AnnotationData,
+  }) as unknown as SceneNode<AnnotationData, 'marks', WorldRect>;
+
+const strokeOf = (cmds: ReturnType<ReturnType<typeof createMarkDrawOne>>) => {
+  const first = cmds[0];
+  if (first?.kind !== 'path') throw new Error('expected a path command');
+  return first.stroke;
+};
+
+describe('the draw callback marks share between the screen and an export', () => {
+  it("paints a mark in its status's colour", () => {
+    const drawOne = createMarkDrawOne({
+      content: CONTENT,
+      config: {},
+      meaning: { statuses: [{ id: 'fixed', label: 'Fixed', color: '#30a46c' }] },
+    });
+    const n = node({ status: 'fixed' }, { x: 1, y: 2, width: 3, height: 4 });
+    expect(strokeOf(drawOne(n, n.pose, VIEW))?.paint).toEqual({ color: '#30a46c' });
+  });
+
+  it('dashes a mark whose position no longer describes the picture', () => {
+    const drawOne = createMarkDrawOne({
+      content: CONTENT,
+      positionDependsOn: ['angle'],
+      config: { angle: 30 },
+    });
+    const fresh = node({ seen: { angle: 30 } }, { x: 1, y: 2, width: 3, height: 4 });
+    const stale = node({ seen: { angle: 0 } }, { x: 1, y: 2, width: 3, height: 4 });
+    expect(strokeOf(drawOne(fresh, fresh.pose, VIEW))?.dash).toBeUndefined();
+    expect(strokeOf(drawOne(stale, stale.pose, VIEW))?.dash).toEqual([6, 4]);
+  });
+
+  it('draws at the pose the walk resolved, not the one the node was stored with', () => {
+    const drawOne = createMarkDrawOne({ content: CONTENT, config: {} });
+    const n = node({}, { x: 1, y: 2, width: 3, height: 4 });
+    const cmds = drawOne(n, { x: 50, y: 60, width: 10, height: 10 }, VIEW);
+    const first = cmds[0];
+    if (first?.kind !== 'path') throw new Error('expected a path command');
+    expect(JSON.stringify(first.path)).toContain('50');
+  });
+});

package/src/annotations/drawOne.ts

@@ -0,0 +1,47 @@
+import type { DrawCommand, SceneNode, View } from '@weasel-js/core';
+import type { WorldRect } from './frac';
+import { type MarkStyle, markCommands } from './paint';
+import { isStale } from './staleness';
+import type { AnnotationData, AnnotationMeaning } from './types';
+
+/** What resolving a mark's appearance needs beyond the mark itself. */
+export interface MarkDrawOptions {
+  /** The target's content box — the world a mark's geometry is in. */
+  content: { w: number; h: number };
+  /** The target's `positionDependsOn`, for staleness. */
+  positionDependsOn?: readonly string[];
+  /** The trial's config at the time of the draw. */
+  config: unknown;
+  /** The instrument's vocabulary, for a status's colour. */
+  meaning?: AnnotationMeaning;
+}
+
+/**
+ * How one mark is drawn — shared by the pane on screen and by an export.
+ *
+ * One function rather than two call sites building their own, because an
+ * export that resolves a status colour or a stale dash differently from the
+ * screen produces a picture nobody was looking at.
+ */
+export function createMarkDrawOne(
+  opts: MarkDrawOptions,
+): (
+  node: SceneNode<AnnotationData, 'marks', WorldRect>,
+  pose: WorldRect,
+  view: View,
+) => DrawCommand[] {
+  return (node, pose) =>
+    markCommands({ pose, data: node.data }, opts.content, resolveMarkStyle(node.data, opts));
+}
+
+/** How a mark looks, as opposed to where it is. Separate from the callback
+ *  above because an SVG export resolves the same appearance without ever
+ *  building a draw command. */
+export function resolveMarkStyle(data: AnnotationData, opts: MarkDrawOptions): MarkStyle {
+  return {
+    color: opts.meaning?.statuses?.find((s) => s.id === data.status)?.color,
+    // Read off the node rather than through the store's `isStale`, which
+    // wants a projected Annotation this path does not have.
+    stale: isStale(data.seen, opts.config, opts.positionDependsOn ?? []),
+  };
+}

package/src/annotations/frac.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import { fracContains, fracIntersects, fracToWorld, roundFrac, worldToFrac } from './frac';
+import type { FracRect } from './types';
+
+const CONTENT = { w: 256, h: 170 };
+
+describe('fraction ↔ world', () => {
+  it('scales a fraction onto the content box', () => {
+    expect(fracToWorld({ x: 0.25, y: 0.5, w: 0.5, h: 0.25 }, CONTENT)).toEqual({
+      x: 64,
+      y: 85,
+      width: 128,
+      height: 42.5,
+    });
+  });
+
+  it('round-trips', () => {
+    const f: FracRect = { x: 0.3322, y: 0.3581, w: 0.02, h: 0.0861 };
+    expect(roundFrac(worldToFrac(fracToWorld(f, CONTENT), CONTENT))).toEqual(f);
+  });
+
+  it('gives zeros, not NaN, for a content box with a zero side', () => {
+    // A pane measured before layout is 0×0. NaN here would propagate silently
+    // through every later comparison — a stale mark would neither hit-test nor
+    // report itself as broken.
+    const got = worldToFrac({ x: 10, y: 10, width: 5, height: 5 }, { w: 0, h: 0 });
+    expect(got).toEqual({ x: 0, y: 0, w: 0, h: 0 });
+    for (const v of Object.values(got)) expect(Number.isFinite(v)).toBe(true);
+  });
+
+  it('rounds to 4dp, so a stored diff shows meaning and not float noise', () => {
+    expect(roundFrac({ x: 0.333333333, y: 0.1, w: 0.66666666, h: 0.2 })).toEqual({
+      x: 0.3333,
+      y: 0.1,
+      w: 0.6667,
+      h: 0.2,
+    });
+  });
+});
+
+describe('fraction hit geometry', () => {
+  const box: FracRect = { x: 0.2, y: 0.2, w: 0.4, h: 0.4 };
+
+  it('contains a point inside and rejects one outside', () => {
+    expect(fracContains(box, { x: 0.3, y: 0.3 })).toBe(true);
+    expect(fracContains(box, { x: 0.9, y: 0.3 })).toBe(false);
+  });
+
+  it('widens the hit by the tolerance', () => {
+    expect(fracContains(box, { x: 0.18, y: 0.3 })).toBe(false);
+    expect(fracContains(box, { x: 0.18, y: 0.3 }, 0.05)).toBe(true);
+  });
+
+  it('intersects only a box that wholly contains it', () => {
+    expect(fracIntersects({ x: 0, y: 0, w: 1, h: 1 }, box)).toBe(true);
+    // Overlapping is not containing: a marquee takes what it encloses.
+    expect(fracIntersects({ x: 0.4, y: 0.4, w: 0.4, h: 0.4 }, box)).toBe(false);
+  });
+});

package/src/annotations/frac.ts

@@ -0,0 +1,66 @@
+import type { FracPoint, FracRect } from './types';
+
+/** A mark's box in its target's world: CSS pixels at zoom 1. Matches weasel's
+ *  default `RectPose`, which is what the scene stores. */
+export interface WorldRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Where a fraction lands on a content box of this size. */
+export function fracToWorld(f: FracRect, content: { w: number; h: number }): WorldRect {
+  return {
+    x: f.x * content.w,
+    y: f.y * content.h,
+    width: f.w * content.w,
+    height: f.h * content.h,
+  };
+}
+
+/** What fraction of the content box a world rect covers.
+ *
+ *  A pane measured before layout is 0×0, and dividing by that would seed every
+ *  stored position with `NaN` — which compares false against everything and so
+ *  fails silently rather than loudly. Zero sides give zeros. */
+export function worldToFrac(r: WorldRect, content: { w: number; h: number }): FracRect {
+  const sx = content.w === 0 ? 0 : 1 / content.w;
+  const sy = content.h === 0 ? 0 : 1 / content.h;
+  return { x: r.x * sx, y: r.y * sy, w: r.width * sx, h: r.height * sy };
+}
+
+const DP = 10_000;
+
+/** Snap to 4dp. Positions are diffed by humans in stored documents, so the
+ *  last digits of a float are noise that hides the change that matters. */
+export function roundFrac(f: FracRect): FracRect {
+  return {
+    x: Math.round(f.x * DP) / DP,
+    y: Math.round(f.y * DP) / DP,
+    w: Math.round(f.w * DP) / DP,
+    h: Math.round(f.h * DP) / DP,
+  };
+}
+
+/** Whether `pt` falls in `box`, widened by `tol` on every side so a hairline
+ *  mark stays reachable. */
+export function fracContains(box: FracRect, pt: FracPoint, tol = 0): boolean {
+  return (
+    pt.x >= box.x - tol &&
+    pt.x <= box.x + box.w + tol &&
+    pt.y >= box.y - tol &&
+    pt.y <= box.y + box.h + tol
+  );
+}
+
+/** Whether `outer` wholly encloses `inner`. A marquee takes what it encloses,
+ *  not what it grazes — brushing selection is a different gesture. */
+export function fracIntersects(outer: FracRect, inner: FracRect): boolean {
+  return (
+    inner.x >= outer.x &&
+    inner.y >= outer.y &&
+    inner.x + inner.w <= outer.x + outer.w &&
+    inner.y + inner.h <= outer.y + outer.h
+  );
+}

package/src/annotations/history.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Undo across targets. Each target's marks live in their own scene, and each
+ * scene owns its own undo stack — so "take back the last thing I did" is an
+ * ordering question labkit has to answer, not something a single scene knows.
+ */
+import { describe, expect, it } from 'vitest';
+import { createAnnotationStore } from './store';
+import type { AnnotationInit, AnnotationTargetInfo } from './types';
+
+const TARGETS: AnnotationTargetInfo[] = [
+  { id: 'left', content: { w: 200, h: 100 } },
+  { id: 'right', content: { w: 200, h: 100 } },
+];
+
+const MARK: Omit<AnnotationInit, 'target'> = {
+  kind: 'rect',
+  frac: { x: 0.1, y: 0.1, w: 0.2, h: 0.2 },
+};
+
+const store = () => createAnnotationStore({ targets: () => TARGETS });
+
+describe('undo across targets', () => {
+  it('takes back the last change wherever it was made', () => {
+    const s = store();
+    s.add({ ...MARK, target: 'left' });
+    s.add({ ...MARK, target: 'right' });
+    const third = s.add({ ...MARK, target: 'left' });
+
+    expect(s.undo()).toBe(true);
+    expect(s.get(third)).toBeUndefined();
+    expect(s.query({ target: 'right' })).toHaveLength(1);
+
+    // Now the most recent surviving change is on the *other* target.
+    expect(s.undo()).toBe(true);
+    expect(s.query({ target: 'right' })).toHaveLength(0);
+    expect(s.query({ target: 'left' })).toHaveLength(1);
+  });
+
+  it('redoes in the reverse order, and bottoms out', () => {
+    const s = store();
+    s.add({ ...MARK, target: 'left' });
+    s.add({ ...MARK, target: 'right' });
+
+    expect(s.canUndo()).toBe(true);
+    expect(s.canRedo()).toBe(false);
+    s.undo();
+    s.undo();
+    expect(s.canUndo()).toBe(false);
+    expect(s.undo()).toBe(false);
+    expect(s.query()).toHaveLength(0);
+
+    expect(s.redo()).toBe(true);
+    expect(s.query({ target: 'left' })).toHaveLength(1);
+    expect(s.redo()).toBe(true);
+    expect(s.query({ target: 'right' })).toHaveLength(1);
+    expect(s.canRedo()).toBe(false);
+  });
+
+  it('drops the redo stack when a new mark lands after an undo', () => {
+    const s = store();
+    s.add({ ...MARK, target: 'left' });
+    s.undo();
+    expect(s.canRedo()).toBe(true);
+    s.add({ ...MARK, target: 'right' });
+    expect(s.canRedo()).toBe(false);
+  });
+
+  it('follows an undo driven from inside a pane, not just its own', () => {
+    // A pane's own Cmd+Z calls scene.undo() directly. Tracking the ordering
+    // off the subscribe callback alone would read that as one more change and
+    // append to the undo stack, leaving redo dead.
+    const s = store();
+    s.add({ ...MARK, target: 'left' });
+    s.sceneFor('left').undo();
+
+    expect(s.query()).toHaveLength(0);
+    expect(s.canRedo()).toBe(true);
+    expect(s.canUndo()).toBe(false);
+    expect(s.redo()).toBe(true);
+    expect(s.query({ target: 'left' })).toHaveLength(1);
+  });
+});

package/src/annotations/history.ts

@@ -0,0 +1,118 @@
+import type { Scene } from '@weasel-js/core';
+
+/** What the ordering needs of a scene: its history depth, and the two moves. */
+export interface HistoryScene {
+  historyIndex(): number;
+  undo(): boolean;
+  redo(): boolean;
+  canUndo(): boolean;
+  canRedo(): boolean;
+}
+
+/**
+ * One undo ordering over several scenes.
+ *
+ * Each target's marks live in their own scene and each scene owns its own undo
+ * stack, so "take back the last thing I did" is a question no single scene can
+ * answer. This keeps the order changes arrived in.
+ *
+ * The order is maintained from each scene's `historyIndex()`, not from its
+ * subscribe callback: a scene notifies on ephemeral changes that are not
+ * history at all, and an undo driven from inside a pane's own keymap has to
+ * *move* this ordering rather than append to it.
+ */
+export class MarkHistory {
+  private readonly depth = new Map<string, number>();
+  private undoable: string[] = [];
+  private redoable: string[] = [];
+  /** Set while this class is driving, so a redo is not read as a new change. */
+  private replaying: 'undo' | 'redo' | null = null;
+
+  /** Start following `scene` under `target`. Idempotent per target. */
+  track(target: string, scene: HistoryScene): void {
+    if (this.depth.has(target)) return;
+    this.depth.set(target, scene.historyIndex());
+  }
+
+  /** Call on every notification from `target`'s scene. */
+  observe(target: string, scene: HistoryScene): void {
+    const now = scene.historyIndex();
+    const before = this.depth.get(target) ?? 0;
+    this.depth.set(target, now);
+    if (now > before) {
+      if (this.replaying === 'redo') {
+        drop(this.redoable, target);
+      } else {
+        // A change dropped whatever was redoable — weasel's own scene did the
+        // same to its stack.
+        this.redoable = [];
+      }
+      this.undoable.push(target);
+    } else if (now < before) {
+      drop(this.undoable, target);
+      this.redoable.push(target);
+    }
+  }
+
+  /** The target `undo` would act on, skipping any whose scene has nothing
+   *  left — a scene can drop entries this ordering still lists. */
+  private next(
+    stack: string[],
+    can: (s: HistoryScene) => boolean,
+    at: (t: string) => HistoryScene | undefined,
+  ): string | null {
+    for (let i = stack.length - 1; i >= 0; i--) {
+      const target = stack[i];
+      if (target === undefined) continue;
+      const scene = at(target);
+      if (scene && can(scene)) return target;
+    }
+    return null;
+  }
+
+  canUndo(at: (t: string) => HistoryScene | undefined): boolean {
+    return this.next(this.undoable, (s) => s.canUndo(), at) !== null;
+  }
+
+  canRedo(at: (t: string) => HistoryScene | undefined): boolean {
+    return this.next(this.redoable, (s) => s.canRedo(), at) !== null;
+  }
+
+  undo(at: (t: string) => HistoryScene | undefined): boolean {
+    const target = this.next(this.undoable, (s) => s.canUndo(), at);
+    const scene = target === null ? undefined : at(target);
+    if (!scene) return false;
+    this.replaying = 'undo';
+    try {
+      return scene.undo();
+    } finally {
+      this.replaying = null;
+    }
+  }
+
+  redo(at: (t: string) => HistoryScene | undefined): boolean {
+    const target = this.next(this.redoable, (s) => s.canRedo(), at);
+    const scene = target === null ? undefined : at(target);
+    if (!scene) return false;
+    this.replaying = 'redo';
+    try {
+      return scene.redo();
+    } finally {
+      this.replaying = null;
+    }
+  }
+}
+
+/** Remove the last occurrence of `value`, in place. */
+function drop(stack: string[], value: string): void {
+  for (let i = stack.length - 1; i >= 0; i--) {
+    if (stack[i] === value) {
+      stack.splice(i, 1);
+      return;
+    }
+  }
+}
+
+/** A `Scene` satisfies `HistoryScene`; this names the narrowing once. */
+export const asHistoryScene = (scene: Scene<never, never, never> | HistoryScene): HistoryScene =>
+  scene as HistoryScene;