@elabs-ai/components-flow 4.0.0 → 4.2.0

package/src/legend/legend.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
 import { Legend } from "./legend";
 
 const meta = {
@@ -10,6 +11,8 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+// ── Categorical (variant omitted — unchanged since before "scale" existed) ──
+
 /** Default legend with a title and token-based color references. */
 export const Default: Story = {
   args: {
@@ -54,3 +57,126 @@ export const SingleItem: Story = {
     items: [{ label: "Active node", color: "var(--primary)" }],
   },
 };
+
+// ── Continuous scale (`variant="scale"`) ─────────────────────────────────────
+
+/**
+ * Width ramp, default `ticks="minmax"` — min/max sample strokes drawn at the
+ * exact widths `computeEdgeWeightScale` (RM-043) would assign those weights,
+ * so the legend can never drift from a real flow's weighted edges.
+ */
+export const ScaleWidth: Story = {
+  args: {
+    variant: "scale",
+    kind: "width",
+    domain: [2, 48],
+  },
+  play: async ({ canvas }) => {
+    const group = await canvas.findByRole("group", {
+      name: "Edge width scale, 2 to 48, minimum to maximum",
+    });
+    await waitFor(async () => {
+      expect(await canvas.findByText("2")).toBeInTheDocument();
+      expect(await canvas.findByText("48")).toBeInTheDocument();
+    });
+
+    // One tab stop for the whole reading key, not one per tick.
+    group.focus();
+    await expect(group).toHaveFocus();
+  },
+};
+
+/** `ticks="minmedmax"` adds the domain midpoint as a third sample stroke. */
+export const ScaleWidthMinMedMax: Story = {
+  args: {
+    variant: "scale",
+    kind: "width",
+    domain: [2, 48],
+    ticks: "minmedmax",
+  },
+  play: async ({ canvas }) => {
+    await waitFor(async () => {
+      expect(await canvas.findByText("2")).toBeInTheDocument();
+      expect(await canvas.findByText("25")).toBeInTheDocument();
+      expect(await canvas.findByText("48")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Colour ramp — always a fixed 5-stop gradient built from
+ * `--flow-edge-weak`/`--flow-edge-strong`, labelled at every stop via
+ * `format`. Colour alone never carries the ordering (WCAG 1.4.1); the five
+ * numbered ticks are the required second channel.
+ */
+export const ScaleColor: Story = {
+  args: {
+    variant: "scale",
+    kind: "color",
+    domain: [0, 100],
+    format: (value: number) => `${value}%`,
+  },
+  play: async ({ canvas }) => {
+    await canvas.findByRole("group", {
+      name: "Edge color scale, 0% to 100%, minimum to maximum",
+    });
+    await waitFor(() => {
+      expect(canvas.getByText("0%")).toBeInTheDocument();
+      expect(canvas.getByText("25%")).toBeInTheDocument();
+      expect(canvas.getByText("50%")).toBeInTheDocument();
+      expect(canvas.getByText("75%")).toBeInTheDocument();
+      expect(canvas.getByText("100%")).toBeInTheDocument();
+    });
+  },
+};
+
+/**
+ * Zero-width domain (`min === max`) — every sample collapses onto one value.
+ * Must render without crashing and without a duplicate React key warning.
+ */
+export const ScaleWidthZeroDomain: Story = {
+  args: {
+    variant: "scale",
+    kind: "width",
+    domain: [10, 10],
+    ticks: "minmedmax",
+  },
+  play: async ({ canvas }) => {
+    await waitFor(async () => {
+      expect(await canvas.findAllByText("10")).toHaveLength(3);
+    });
+  },
+};
+
+/** Domain spanning several orders of magnitude. */
+export const ScaleColorWideRange: Story = {
+  args: {
+    variant: "scale",
+    kind: "color",
+    domain: [1, 1_000_000],
+  },
+  play: async ({ canvas }) => {
+    await waitFor(async () => {
+      expect(await canvas.findByText("1")).toBeInTheDocument();
+      expect(await canvas.findByText("1,000,000")).toBeInTheDocument();
+    });
+  },
+};
+
+/** A verbose custom `format` must truncate rather than break the layout. */
+export const ScaleWidthLongLabels: Story = {
+  args: {
+    variant: "scale",
+    kind: "width",
+    domain: [2, 48],
+    ticks: "minmedmax",
+    format: (value: number) => `${value.toFixed(2)} transactions processed per hour on average`,
+  },
+  play: async ({ canvas }) => {
+    await waitFor(async () => {
+      expect(
+        await canvas.findByText("2.00 transactions processed per hour on average"),
+      ).toBeInTheDocument();
+    });
+  },
+};

package/src/legend/legend.test.tsx

@@ -1,5 +1,7 @@
+import { LocaleProvider } from "@elabs-ai/components-ui";
 import { cleanup, render, screen } from "@testing-library/react";
 import { afterEach, describe, expect, it } from "vitest";
+import { computeEdgeWeightScale, type WeightedEdgeLike } from "../flow-weighted-edge/weight-scale";
 import { Legend } from "./legend";
 
 afterEach(cleanup);
@@ -43,4 +45,182 @@ describe("Legend", () => {
     const list = screen.queryByRole("list");
     expect(list).toBeInTheDocument();
   });
+
+  // Same cases as above, but explicitly passing `variant="categorical"` — the
+  // additive prop must be a true no-op, not merely an omission that happens
+  // to work.
+  it('renders identically with variant="categorical" made explicit', () => {
+    render(<Legend variant="categorical" items={items} title="Legend Title" />);
+    expect(screen.getByText("Legend Title")).toBeInTheDocument();
+    expect(screen.getByText("Source")).toBeInTheDocument();
+    expect(screen.getByText("Target")).toBeInTheDocument();
+  });
+});
+
+describe('Legend variant="scale", kind="width"', () => {
+  it("draws min/max sample strokes at exactly computeEdgeWeightScale's widths for that domain (#219)", () => {
+    const { container } = render(<Legend variant="scale" kind="width" domain={[2, 48]} />);
+    const expected = computeEdgeWeightScale([
+      { id: "0", data: { weight: 2 } },
+      { id: "1", data: { weight: 48 } },
+    ] satisfies WeightedEdgeLike[]);
+
+    const lines = container.querySelectorAll("line");
+    expect(lines).toHaveLength(2);
+    expect(Number(lines[0]!.getAttribute("stroke-width"))).toBeCloseTo(expected.get("0")!, 5);
+    expect(Number(lines[1]!.getAttribute("stroke-width"))).toBeCloseTo(expected.get("1")!, 5);
+  });
+
+  it('adds the domain midpoint as a third stroke under ticks="minmedmax", matching computeEdgeWeightScale for 2/25/48', () => {
+    const { container } = render(
+      <Legend variant="scale" kind="width" domain={[2, 48]} ticks="minmedmax" />,
+    );
+    const expected = computeEdgeWeightScale([
+      { id: "0", data: { weight: 2 } },
+      { id: "1", data: { weight: 25 } },
+      { id: "2", data: { weight: 48 } },
+    ] satisfies WeightedEdgeLike[]);
+
+    const lines = container.querySelectorAll("line");
+    expect(lines).toHaveLength(3);
+    expect(Number(lines[0]!.getAttribute("stroke-width"))).toBeCloseTo(expected.get("0")!, 5);
+    expect(Number(lines[1]!.getAttribute("stroke-width"))).toBeCloseTo(expected.get("1")!, 5);
+    expect(Number(lines[2]!.getAttribute("stroke-width"))).toBeCloseTo(expected.get("2")!, 5);
+  });
+
+  it("renders formatted min/max tick labels with tabular-nums", () => {
+    render(<Legend variant="scale" kind="width" domain={[2, 48]} />);
+    expect(screen.getByText("2")).toHaveClass("tabular-nums");
+    expect(screen.getByText("48")).toHaveClass("tabular-nums");
+  });
+
+  it("applies a caller-supplied format function to every tick", () => {
+    render(
+      <Legend
+        variant="scale"
+        kind="width"
+        domain={[2, 48]}
+        ticks="minmedmax"
+        format={(v) => `${v} evt/s`}
+      />,
+    );
+    expect(screen.getByText("2 evt/s")).toBeInTheDocument();
+    expect(screen.getByText("25 evt/s")).toBeInTheDocument();
+    expect(screen.getByText("48 evt/s")).toBeInTheDocument();
+  });
+
+  it("keeps the smallest tick's stroke at the readable floor (default 1.5px), never thinner", () => {
+    const { container } = render(<Legend variant="scale" kind="width" domain={[2, 1000]} />);
+    const lines = container.querySelectorAll("line");
+    const widths = Array.from(lines).map((l) => Number(l.getAttribute("stroke-width")));
+    expect(Math.min(...widths)).toBeCloseTo(1.5, 5);
+  });
+
+  it("handles a zero-width domain (min === max) without crashing, all samples at the midpoint width", () => {
+    const { container } = render(
+      <Legend variant="scale" kind="width" domain={[10, 10]} ticks="minmedmax" />,
+    );
+    const lines = container.querySelectorAll("line");
+    expect(lines).toHaveLength(3);
+    const widths = Array.from(lines).map((l) => Number(l.getAttribute("stroke-width")));
+    // computeEdgeWeightScale's own zero-variance behavior: the midpoint of
+    // the default [1.5, 8] output range.
+    for (const w of widths) expect(w).toBeCloseTo(4.75, 5);
+    expect(screen.getAllByText("10")).toHaveLength(3);
+  });
+
+  it("is a single keyboard tab stop with an aria-label summarizing the domain", () => {
+    render(<Legend variant="scale" kind="width" domain={[2, 48]} ticks="minmedmax" />);
+    const group = screen.getByRole("group", {
+      name: "Edge width scale, 2 to 48, minimum to maximum",
+    });
+    expect(group).toHaveAttribute("tabindex", "0");
+    // No descendant of the legend is itself a tab stop — one Tab reaches the
+    // whole reading key, not one per tick.
+    const innerTabbables = group.querySelectorAll(
+      "button, a[href], input, select, textarea, [tabindex]",
+    );
+    expect(innerTabbables).toHaveLength(0);
+  });
+
+  it("does not render the categorical <ul> item list", () => {
+    const { container } = render(<Legend variant="scale" kind="width" domain={[2, 48]} />);
+    expect(container.querySelector("ul")).toBeNull();
+  });
+});
+
+describe('Legend variant="scale", kind="color"', () => {
+  it("renders a 5-stop gradient using the flow-edge-weak/strong tokens", () => {
+    const { container } = render(<Legend variant="scale" kind="color" domain={[0, 100]} />);
+    const bar = container.querySelector("[aria-hidden='true'][style*='linear-gradient']");
+    expect(bar).not.toBeNull();
+    const backgroundImage = (bar as HTMLElement).style.backgroundImage;
+    expect(backgroundImage).toContain("var(--flow-edge-weak)");
+    expect(backgroundImage).toContain("var(--flow-edge-strong)");
+    // 5 explicit percentage stops: 0, 25, 50, 75, 100.
+    for (const pct of ["0%", "25%", "50%", "75%", "100%"]) {
+      expect(backgroundImage).toContain(pct);
+    }
+  });
+
+  it("labels every one of the 5 stops via the caller's format function — colour is never the only channel (#387-style, WCAG 1.4.1)", () => {
+    render(<Legend variant="scale" kind="color" domain={[0, 100]} format={(v) => `${v}%`} />);
+    for (const label of ["0%", "25%", "50%", "75%", "100%"]) {
+      expect(screen.getByText(label)).toBeInTheDocument();
+    }
+  });
+
+  it("uses the default locale number format when none is supplied", () => {
+    render(<Legend variant="scale" kind="color" domain={[0, 1000]} />);
+    expect(screen.getByText("0")).toBeInTheDocument();
+    expect(screen.getByText("250")).toBeInTheDocument();
+    expect(screen.getByText("500")).toBeInTheDocument();
+    expect(screen.getByText("750")).toBeInTheDocument();
+    expect(screen.getByText("1,000")).toBeInTheDocument();
+  });
+
+  it("handles a domain spanning several orders of magnitude", () => {
+    render(<Legend variant="scale" kind="color" domain={[1, 1_000_000]} />);
+    expect(screen.getByText("1")).toBeInTheDocument();
+    expect(screen.getByText("1,000,000")).toBeInTheDocument();
+  });
+
+  it("handles a zero-width domain (min === max) — all 5 stop labels equal, no crash", () => {
+    render(<Legend variant="scale" kind="color" domain={[10, 10]} />);
+    expect(screen.getAllByText("10")).toHaveLength(5);
+  });
+
+  it("truncates a very long formatted label instead of breaking layout", () => {
+    render(
+      <Legend
+        variant="scale"
+        kind="color"
+        domain={[0, 1]}
+        format={(v) => `${v} — a very long description of what this stop means in context`}
+      />,
+    );
+    const label = screen.getByText(
+      "0 — a very long description of what this stop means in context",
+    );
+    expect(label).toHaveClass("truncate");
+    expect(label).toHaveClass("min-w-0");
+  });
+
+  it("is a single keyboard tab stop with an aria-label summarizing the domain", () => {
+    render(<Legend variant="scale" kind="color" domain={[0, 100]} />);
+    const group = screen.getByRole("group", {
+      name: "Edge color scale, 0 to 100, minimum to maximum",
+    });
+    expect(group).toHaveAttribute("tabindex", "0");
+  });
+
+  it("formats the default tick label with the active LocaleProvider locale, not the host locale", () => {
+    render(
+      <LocaleProvider locale="de-DE">
+        <Legend variant="scale" kind="color" domain={[0, 1000]} />
+      </LocaleProvider>,
+    );
+    // de-DE groups thousands with a period, never a comma.
+    expect(screen.getByText("1.000")).toBeInTheDocument();
+  });
 });

package/src/legend/legend.tsx

@@ -1,4 +1,6 @@
+import { useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { computeEdgeWeightScale, type WeightedEdgeLike } from "../flow-weighted-edge/weight-scale";
 
 export interface LegendItem {
   label: string;
@@ -6,14 +8,67 @@ export interface LegendItem {
   color: string;
 }
 
-export interface LegendProps {
+/**
+ * Categorical legend props — a swatch-and-label list. This is the shape
+ * `Legend` renders when `variant` is omitted, byte-for-byte unchanged from
+ * before the `"scale"` variant existed.
+ */
+export interface LegendCategoricalProps {
+  variant?: "categorical";
   items: LegendItem[];
   title?: string;
   className?: string;
 }
 
-/** Small legend mapping colors/types to labels for a canvas or chart. */
-export function Legend({ items, title, className }: LegendProps) {
+/**
+ * Continuous scale legend — a reading key that explains a WIDTH or COLOR
+ * encoding as a *range*, not a set of discrete categories (e.g.
+ * `FlowWeightedEdge`'s `data.weight` → stroke width, `data.value` → stroke
+ * color). `kind: "width"` reuses `computeEdgeWeightScale` — the exact pure
+ * scale `FlowWeightedEdge` calls — so the sample strokes drawn here can never
+ * drift from the widths a real flow's edges render for the same weights.
+ */
+export interface LegendScaleProps {
+  variant: "scale";
+  /** Which continuous encoding this legend explains. */
+  kind: "width" | "color";
+  /** `[min, max]` of the underlying value the ramp represents. */
+  domain: [number, number];
+  /**
+   * Formats a domain value for display at a tick.
+   * @default the active `LocaleProvider` locale's `formatNumber` (host locale
+   * when no provider is mounted) — never a hardcoded `toLocaleString()`.
+   */
+  format?: (value: number) => string;
+  /**
+   * Sample count for `kind: "width"`: `"minmax"` draws a min/max pair of
+   * sample strokes, `"minmedmax"` adds the domain midpoint as a third
+   * sample. `kind: "color"` always renders a fixed 5-stop gradient
+   * regardless of this prop — five stops is what makes a 2-endpoint color
+   * ramp legible as an ordered scale (see the color-ramp a11y note below),
+   * independent of how many width samples are shown.
+   * @default "minmax"
+   */
+  ticks?: "minmax" | "minmedmax";
+  title?: string;
+  className?: string;
+}
+
+export type LegendProps = LegendCategoricalProps | LegendScaleProps;
+
+/**
+ * Small legend mapping colors/types to labels for a canvas or chart
+ * (`variant: "categorical"`, the default), or — via `variant="scale"` — a
+ * continuous width/color ramp with a domain, tick marks and formatting.
+ */
+export function Legend(props: LegendProps) {
+  if (props.variant === "scale") {
+    return <LegendScale {...props} />;
+  }
+  return <LegendCategorical {...props} />;
+}
+
+function LegendCategorical({ items, title, className }: LegendCategoricalProps) {
   return (
     <div
       className={cn(
@@ -37,3 +92,167 @@ export function Legend({ items, title, className }: LegendProps) {
     </div>
   );
 }
+
+/**
+ * Width-ramp sample: a tick value plus the stroke width `computeEdgeWeightScale`
+ * assigns it. The "edges" fed to the scale are exactly the requested tick
+ * values, so the group's own min/max always equal the domain — the returned
+ * widths are byte-identical to what `computeEdgeWeightScale` would compute for
+ * real edges carrying these same weights (no duplicated min-max math).
+ */
+function computeWidthSamples(
+  domain: [number, number],
+  ticks: "minmax" | "minmedmax",
+): { value: number; width: number }[] {
+  const [min, max] = domain;
+  const values = ticks === "minmedmax" ? [min, (min + max) / 2, max] : [min, max];
+  const likeEdges: WeightedEdgeLike[] = values.map((weight, index) => ({
+    id: String(index),
+    data: { weight },
+  }));
+  const widths = computeEdgeWeightScale(likeEdges);
+  return values.map((value, index) => ({ value, width: widths.get(String(index)) ?? 0 }));
+}
+
+/** Fractions along the domain the color ramp samples — fixed at 5 stops (see `LegendScaleProps.ticks`). */
+const COLOR_STOP_FRACTIONS = [0, 0.25, 0.5, 0.75, 1] as const;
+
+function scaleKindLabel(kind: "width" | "color"): string {
+  return kind === "width" ? "width" : "color";
+}
+
+function LegendScale({
+  kind,
+  domain,
+  format,
+  ticks = "minmax",
+  title,
+  className,
+}: LegendScaleProps) {
+  // The active `LocaleProvider` locale, not a hardcoded `toLocaleString()` —
+  // otherwise a `de-DE`-configured app still reads the domain ticks in the
+  // browser's host locale.
+  const { formatNumber } = useLocale();
+  const format_ = format ?? formatNumber;
+  const [min, max] = domain;
+  // e.g. "Edge width scale, 2 to 48, minimum to maximum" — a single accessible
+  // name for the whole reading key, since it is one keyboard tab stop, not one
+  // per tick.
+  const ariaLabel = `Edge ${scaleKindLabel(kind)} scale, ${format_(min)} to ${format_(max)}, minimum to maximum`;
+
+  return (
+    <div
+      aria-label={ariaLabel}
+      className={cn(
+        "flex flex-col gap-2 rounded-lg bg-surface-elevated/90 p-3 shadow-ring-sm backdrop-blur",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        className,
+      )}
+      role="group"
+      tabIndex={0}
+    >
+      {title ? <div className="text-body font-medium text-foreground">{title}</div> : null}
+      {kind === "width" ? (
+        <LegendScaleWidth domain={domain} format={format_} ticks={ticks} />
+      ) : (
+        <LegendScaleColor domain={domain} format={format_} />
+      )}
+    </div>
+  );
+}
+
+function LegendScaleWidth({
+  domain,
+  format,
+  ticks,
+}: {
+  domain: [number, number];
+  format: (value: number) => string;
+  ticks: "minmax" | "minmedmax";
+}) {
+  const samples = computeWidthSamples(domain, ticks);
+  return (
+    <div className="flex flex-col gap-2">
+      {samples.map((sample, index) => (
+        // Index disambiguates a zero-width domain, where every sample shares
+        // the same value (and therefore the same width).
+        <div key={`${index}-${sample.value}`} className="flex items-center gap-3">
+          {/* The thin end of the ramp (default floor 1.5px) is the weakest mark
+              in the system — `--flow-edge` is the same token a real, unweighted
+              edge draws, and `strokeLinecap="round"` keeps that floor width from
+              disappearing into a hairline. */}
+          <svg aria-hidden="true" className="shrink-0" height={16} overflow="visible" width={40}>
+            <line
+              stroke="var(--flow-edge)"
+              strokeLinecap="round"
+              strokeWidth={sample.width}
+              x1={2}
+              x2={38}
+              y1={8}
+              y2={8}
+            />
+          </svg>
+          <span className="min-w-0 truncate text-meta tabular-nums text-muted-foreground">
+            {format(sample.value)}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function LegendScaleColor({
+  domain,
+  format,
+}: {
+  domain: [number, number];
+  format: (value: number) => string;
+}) {
+  const [min, max] = domain;
+  const span = max - min;
+  const stops = COLOR_STOP_FRACTIONS.map((fraction) => ({
+    fraction,
+    value: min + fraction * span,
+  }));
+  // Explicit 5-stop `color-mix` gradient (interpolated `in oklch`, matching how
+  // the `--flow-edge-weak`/`--flow-edge-strong` tokens themselves are authored)
+  // rather than a bare 2-color `linear-gradient`, so the ramp's perceptual
+  // steps match the token authoring space instead of the browser's default
+  // sRGB gradient interpolation.
+  const gradient = `linear-gradient(to right, ${stops
+    .map(({ fraction }) => {
+      const percent = Math.round(fraction * 100);
+      return `color-mix(in oklch, var(--flow-edge-strong) ${percent}%, var(--flow-edge-weak)) ${percent}%`;
+    })
+    .join(", ")})`;
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      {/*
+        WCAG 1.4.1 — this gradient alone cannot carry the ordering, so the
+        numbered ticks below are the required second channel, not decoration.
+      */}
+      <div
+        aria-hidden="true"
+        className="h-3 w-full rounded-full"
+        style={{ backgroundImage: gradient }}
+      />
+      <div className="flex justify-between gap-1">
+        {stops.map((stop, index) => (
+          <span
+            // Index disambiguates a zero-width domain, where every stop shares
+            // the same formatted value.
+            key={`${index}-${stop.value}`}
+            className={cn(
+              "min-w-0 truncate text-meta tabular-nums text-muted-foreground",
+              index === 0 && "text-start",
+              index === stops.length - 1 && "text-end",
+            )}
+          >
+            {format(stop.value)}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/templates-flow-workspace.stories.tsx

@@ -4,7 +4,7 @@
  * single source of truth: `pnpm gen:templates` derives the consumer template
  * source (`docs/playbooks/templates/flow-workspace.tsx`) from it.
  * Remember `import "@xyflow/react/dist/style.css"` is wired in Storybook preview.
- * Verify across all three themes with globals=theme:<slug>.
+ * Verify across every theme with globals=theme:<slug>.
  */
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { useState } from "react";

package/src/testing/canvas-framing.test.ts

@@ -0,0 +1,107 @@
+/**
+ * The one property of {@link waitForSettledCanvas} that is testable outside a browser:
+ * a canvas that is still MOVING is not settled, even when it measures as still.
+ *
+ * jsdom reports every box as 0×0, so the rect half of `canvasSignature` is constant here
+ * by construction — which is precisely the shape of the CI failure this locks. Two polls
+ * taken close enough together read the identical signature while the node-position
+ * transition is mid-flight (on a loaded runner, "close enough together" means inside one
+ * rendered frame), and the framing assertions then measure a picture in which React Flow
+ * has already drawn every edge at its final coordinate while the node elements, and with
+ * them the handle dots, are still sliding towards it — nine edges reported hanging up to
+ * 142 px off their dots on a canvas that is correct a fifth of a second later.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { waitForSettledCanvas } from "./canvas-framing";
+
+type AnimationCapableElement = { getAnimations: () => Animation[] };
+
+/** A canvas whose nodes already hold distinct laid-out positions. */
+function canvasWithLaidOutNodes(): HTMLElement {
+  const canvas = document.createElement("div");
+  for (const [id, x] of [
+    ["a", 0],
+    ["b", 240],
+  ] as const) {
+    const node = document.createElement("div");
+    node.className = "react-flow__node";
+    node.setAttribute("data-id", id);
+    node.style.transform = `translate(${x}px, 0px)`;
+    canvas.append(node);
+  }
+  document.body.append(canvas);
+  return canvas;
+}
+
+/** A finite, still-running animation whose end this test controls. */
+function pendingAnimation(): { animation: Animation; finish: () => void } {
+  let finish = () => {};
+  const finished = new Promise<void>((resolve) => {
+    finish = () => resolve();
+  });
+  return {
+    animation: {
+      playState: "running",
+      effect: { getTiming: () => ({ iterations: 1 }) },
+      finished,
+    } as unknown as Animation,
+    finish,
+  };
+}
+
+function stubAnimations(read: () => Animation[]) {
+  (Element.prototype as unknown as AnimationCapableElement).getAnimations = read;
+}
+
+afterEach(() => {
+  delete (Element.prototype as unknown as Partial<AnimationCapableElement>).getAnimations;
+  document.body.innerHTML = "";
+});
+
+describe("waitForSettledCanvas", () => {
+  it("does not settle while a finite animation is still running", async () => {
+    const canvas = canvasWithLaidOutNodes();
+    const { animation, finish } = pendingAnimation();
+    let running: Animation[] = [animation];
+    stubAnimations(() => running);
+
+    let settled = false;
+    const wait = waitForSettledCanvas(canvas, { timeout: 4_000, interval: 10 }).then(() => {
+      settled = true;
+    });
+
+    // Long enough for many polls: under the old two-identical-polls rule this canvas —
+    // whose signature never changes in jsdom — settled on the second one.
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    expect(settled).toBe(false);
+
+    running = [];
+    finish();
+    await wait;
+    expect(settled).toBe(true);
+  });
+
+  it("settles once nothing is animating", async () => {
+    const canvas = canvasWithLaidOutNodes();
+    stubAnimations(() => []);
+    await expect(
+      waitForSettledCanvas(canvas, { timeout: 4_000, interval: 10 }),
+    ).resolves.toBeUndefined();
+  });
+
+  it("throws, naming the reason, when the nodes never take distinct positions", async () => {
+    const canvas = document.createElement("div");
+    for (const id of ["a", "b"]) {
+      const node = document.createElement("div");
+      node.className = "react-flow__node";
+      node.setAttribute("data-id", id);
+      node.style.transform = "translate(0px, 0px)";
+      canvas.append(node);
+    }
+    document.body.append(canvas);
+    stubAnimations(() => []);
+    await expect(waitForSettledCanvas(canvas, { timeout: 120, interval: 10 })).rejects.toThrow(
+      /layout has not run/,
+    );
+  });
+});