@multiplatform.one/node-graph 7.7.2

package/src/knobs/useKnobEnvelope.ts

@@ -0,0 +1,152 @@
+/**
+ * Host side of the knob envelope: read the real knob stack, hand back the
+ * inputs that reproduce it. Design: docs/design/node-graph-editor.md 6.1.
+ */
+
+import { useEffect, useRef, useState } from "react";
+import { useThemeName } from "tamagui";
+import {
+  type Knobs,
+  SurfaceContext,
+  defaultKnobs,
+  useIntentContext,
+  usePresetContext,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
+import type { GraphCssVarsOptions } from "../theme/graphVars";
+import { useGraphCssVars } from "../theme/GraphVarsStyle";
+import {
+  type GraphFontRef,
+  type KnobEnvelope,
+  type KnobEnvelopeBody,
+  knobEnvelopeIdentity,
+  knobEnvelopeSchemaVersion,
+} from "./envelope";
+
+export interface UseKnobEnvelopeOptions {
+  /** `props.knobs` — merged last, on top of the whole Preset chain. */
+  readonly knobs?: Partial<Knobs>;
+  /**
+   * The name the host mounted `<Preset preset=…>` with. Not readable from
+   * context (see `KnobEnvelope.presetName`), so a host under a named preset
+   * has to say so or the DOM side loses that preset's `intents` map.
+   */
+  readonly presetName?: string;
+  /** Overrides the ambient `IntentContext` when the graph itself carries an intent. */
+  readonly intent?: string | null;
+  readonly fonts?: readonly GraphFontRef[];
+  /**
+   * Pointer class the graph is painted for, threaded into the var layer so the
+   * handle HIT region gets the 44 px floor on touch.
+   */
+  readonly pointer?: GraphCssVarsOptions["pointer"];
+  /**
+   * The `--xy-*` / `--mpo-graph-*` layer. Built from `graphCssVars` against the
+   * live theme by default; pass your own only to override the whole layer.
+   */
+  readonly vars?: Readonly<Record<string, string>>;
+}
+
+/**
+ * `prefers-reduced-motion: reduce`, read the way the theme package reads it.
+ *
+ * A copy rather than an import: `usePrefersReducedMotion` is module-private in
+ * `useResolvedKnobs.ts:22` and is not exported from `@multiplatform.one/theme`.
+ * The value has to be resolved HOST-side because a WKWebView's `matchMedia`
+ * does not see the iOS setting.
+ */
+function useHostPrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return false;
+    return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  });
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const query = window.matchMedia("(prefers-reduced-motion: reduce)");
+    const handler = () => setReduced(query.matches);
+    handler();
+    if (typeof query.addEventListener === "function") {
+      query.addEventListener("change", handler);
+      return () => query.removeEventListener("change", handler);
+    }
+    if (typeof query.addListener === "function") {
+      query.addListener(handler);
+      return () => query.removeListener?.(handler);
+    }
+  }, []);
+  return reduced;
+}
+
+/** Drop keys whose value is `undefined` so a spread cannot erase a default. */
+function definedOnly<T extends object>(value: T): Partial<T> {
+  const out: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item !== undefined) out[key] = item;
+  }
+  return out as Partial<T>;
+}
+
+const emptyFonts: readonly GraphFontRef[] = [];
+
+/**
+ * Build the envelope from the live knob stack.
+ *
+ * The knob merge is deliberately the SAME expression `useResolvedKnobs` uses
+ * for its base (`{...presetCtx.preset.knobs, ...presetCtx.overrides}`,
+ * useResolvedKnobs.ts:131-133) — anything cleverer is a second resolver to keep
+ * in step. It is then completed against `defaultKnobs`, because `JSON.stringify`
+ * DROPS a key whose value is `undefined`: without the completion an optional
+ * knob (`cornerSmoothing`, `pageTitleScale`) would arrive absent on the far
+ * side and the rehydrating `<Preset>`'s own base would show through the gap.
+ */
+export function useKnobEnvelope(options?: UseKnobEnvelopeOptions): KnobEnvelope {
+  const presetCtx = usePresetContext();
+  const contextIntent = useIntentContext();
+  const surfaceCtx = SurfaceContext.useStyledContext();
+  const themeName = (useThemeName() as string | undefined) ?? "";
+  const prefersReducedMotion = useHostPrefersReducedMotion();
+  // The var layer is canvas CHROME, so it resolves with the ambient intent and
+  // no component: a node's own paint comes from `useGraphNodeKnobs`, not from
+  // a `--xy-*` variable (design 6.2 — the `--xy-node-*` family is allowlisted
+  // out precisely because it never binds to a Tamagui node).
+  const chromeKnobs = useResolvedKnobs();
+  const builtVars = useGraphCssVars(chromeKnobs, { pointer: options?.pointer });
+
+  const merged: Knobs = {
+    ...defaultKnobs,
+    ...definedOnly(
+      presetCtx ? { ...presetCtx.preset.knobs, ...presetCtx.overrides } : defaultKnobs,
+    ),
+    ...definedOnly(options?.knobs ?? {}),
+  };
+
+  const body: KnobEnvelopeBody = {
+    schemaVersion: knobEnvelopeSchemaVersion,
+    knobs: merged,
+    presetName: options?.presetName,
+    intent: options?.intent !== undefined ? options.intent : contextIntent,
+    surface: { size: surfaceCtx?.size ?? "unset", density: surfaceCtx?.density ?? "unset" },
+    scheme: themeName.startsWith("dark") ? "dark" : "light",
+    themeName,
+    prefersReducedMotion,
+    vars: options?.vars ?? builtVars,
+    fonts: options?.fonts ?? emptyFonts,
+    pixelRatio:
+      typeof window !== "undefined" && typeof window.devicePixelRatio === "number"
+        ? window.devicePixelRatio
+        : 1,
+  };
+
+  const identity = knobEnvelopeIdentity(body);
+  const state = useRef<{ identity: string; envelope: KnobEnvelope } | null>(null);
+  if (!state.current || state.current.identity !== identity) {
+    // Derived from this render's own inputs, so the ref write is pure in the
+    // sense React cares about: a re-render with the same inputs produces the
+    // same envelope, identity included.
+    state.current = {
+      identity,
+      envelope: { ...body, revision: (state.current?.envelope.revision ?? 0) + 1 },
+    };
+  }
+  return state.current.envelope;
+}

package/src/layout/AutoLayout.stories.tsx

@@ -0,0 +1,338 @@
+/**
+ * `NodeGraph/AutoLayout` — design §8, and the place tasks 4.3 and 4.4 are
+ * carried out by hand.
+ *
+ * MILESTONE 6 REBUILT IT AS A SIBLING. Every control on this page used to be a
+ * `children` of `<NodeGraph>` — Tidy, Undo, Redo, the runner readout — and
+ * `NodeGraph.native.tsx` accepts children and IGNORES them by written contract.
+ * So on the iPhone 16e simulator and both emulators this story painted twelve
+ * scrambled nodes and offered no way to lay them out, `layoutRunner` read
+ * `none` on every host, and MPO-213's device criterion could not be attempted
+ * at all. Nothing threw; the canvas looked fine.
+ *
+ * The toolbar is now OUTSIDE the canvas and drives it through `graphRef`, which
+ * is design §9.1's imperative handle and the same eleven commands on both
+ * platforms. The runner and the engine milliseconds come back on the wire as
+ * `{ t: "layoutResult" }` rather than being read out of a context that only
+ * exists inside the canvas.
+ *
+ *  - `Main` prints the RESOLVED RUNNER and the engine ms. On web that must read
+ *    `worker-blob`, and inside the Kitchen Sink's WebView it must read
+ *    `worker-blob` TOO — see the correction below. An `inline` reading on a
+ *    platform that has `Worker` is a FAILURE, not a slower pass (design §13.2),
+ *    and the readout paints it as one rather than showing a word nobody looks
+ *    twice at. A relayout that REJECTS is painted as a failure as well, because
+ *    before milestone 6's device pass it was painted as nothing at all.
+ *  - `Undo` is task 4.4: tidy, undo, and the graph returns exactly. The
+ *    positions are printed as a checksum so "exactly" is checkable instead of
+ *    eyeballed. WEB ONLY, because the checksum reads every node's CSS transform
+ *    and the nodes are inside the WebView; the device half of 4.4 is the Undo
+ *    button working at all, which the toolbar now allows.
+ *  - `Large200` is the 200-node graph the "a relayout never blocks a frame"
+ *    measurement is taken on. It parks a `window.__mpoAutoLayout` handle for
+ *    browser automation to drive.
+ *
+ * The handle is story-only. Nothing in the package reads it.
+ */
+
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Button, SizableText, XStack, YStack } from "tamagui";
+import type { GraphEventWire } from "../dom/wire";
+import type { BuiltinEdgeData } from "../edges/edgeKinds";
+import type { GraphDocument } from "../model/index";
+import { GraphToolbar } from "../native/GraphToolbar";
+import { hasDomRealm } from "../native/DomOnlyStory";
+import { NodeGraph } from "../NodeGraph";
+import { demoGraphSchema } from "../react-flow/demoNodeBody";
+import type { DemoNodeData } from "../react-flow/fixtures";
+import type { NodeGraphHandle } from "../react-flow/graphHandle";
+import { Background, Controls, reactFlowNodeSelector } from "../react-flow/xy";
+
+type Doc = GraphDocument<DemoNodeData, BuiltinEdgeData>;
+
+const schema = demoGraphSchema();
+
+const meta: Meta<typeof NodeGraph> = {
+  title: "NodeGraph/AutoLayout",
+  component: NodeGraph,
+  parameters: {
+    status: { type: "beta" },
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Off-thread auto-layout (design 8). dagre is bundled into a committed string and instantiated as a classic blob-URL Worker whose liveness is PROBED with a ping and a 500 ms timeout. The device answer is worker-blob, not hermes-inline: milestone 6 moved relayout onto the imperative handle, which is implemented inside the canvas, and on native the canvas paints in a WebView — which has a real Worker. hermes-inline stays a first-class runner for a caller on the Hermes side; nothing here is one. The arriving positions land as ONE setPositions command inside startTransition, so one undo restores the whole prior arrangement. The toolbar is a SIBLING of the canvas driving it through the imperative handle, because native drops children — which is why layoutRunner read `none` on every device until milestone 6. elkjs is not here: decision D2 is unruled.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof NodeGraph>;
+
+/**
+ * A graph nobody would keep. Every node is on a diagonal with the edges
+ * crossing, so a tidy that did nothing would be obvious at a glance.
+ */
+function scrambled(count: number): Doc {
+  const kinds = ["source", "transform", "sink"] as const;
+  const nodes = Array.from({ length: count }, (_, index) => {
+    const kind = kinds[index % kinds.length];
+    const data =
+      kind === "source"
+        ? { table: `orders_${index}` }
+        : kind === "transform"
+          ? { expression: `row => row.${index}` }
+          : { target: `warehouse_${index}` };
+    return {
+      id: `n${index}`,
+      kind,
+      // A deterministic scatter: no Math.random, so two sessions compare.
+      position: { x: ((index * 137) % 900) - 200, y: ((index * 211) % 700) - 150 },
+      data,
+    };
+  }) as Doc["nodes"];
+
+  const edges: Doc["edges"][number][] = [];
+  for (let index = 0; index + 1 < count; index += 1) {
+    const from = nodes[index];
+    const to = nodes[index + 1];
+    const sourcePort = from.kind === "source" ? "rows" : from.kind === "transform" ? "ok" : null;
+    if (!sourcePort) continue;
+    edges.push({
+      id: `${from.id}->${to.id}`,
+      kind: (["flow", "data", "error", "conditional"] as const)[edges.length % 4],
+      source: { node: from.id, port: sourcePort },
+      target: { node: to.id, port: "in" },
+      data: {},
+    } as Doc["edges"][number]);
+  }
+  return { version: 1, nodes, edges };
+}
+
+/** What the last `{ t: "layoutResult" }` said. */
+interface LayoutReading {
+  readonly runner: string;
+  readonly ms: number;
+  readonly nodeCount: number;
+  /** Set when the engine REJECTED — see the `layoutResult` note in `wire.ts`. */
+  readonly error?: string;
+}
+
+/**
+ * The whole page: a sibling toolbar, a readout fed by the wire, and a canvas.
+ *
+ * `hasWorker` is read on the HOST side, which is the right side: the claim
+ * design §13.2 makes is about the platform the canvas runs on, and on native
+ * the host and the WebView disagree — Hermes has no `Worker` and the WebView
+ * does. So the failing case is stated per platform rather than as one boolean:
+ * `inline` is a failure when the realm that produced it had a `Worker` to use,
+ * and `hermes-inline` is a first-class pass.
+ *
+ * THE DEVICE ANSWER IS `worker-blob`, corrected after the m6 device pass. This
+ * story used to say `hermes-inline`, and that was a reading of design §8's
+ * "native runs inline on the Hermes JS thread" — true of the realm it names,
+ * and never tested, because until milestone 6 nothing on a phone could ask for
+ * a layout at all and `layoutRunner` read `none` everywhere. Milestone 6 put
+ * `relayout` on the imperative handle, which is implemented inside the canvas,
+ * and on native the canvas paints in a WebView: a WebView has a real `Worker`,
+ * so the probe resolves `worker-blob`. Measured on the iPhone 16e:
+ * `worker-blob · engine 6.0 ms` at 12 nodes, `31.8 ms` at 200. The probe did
+ * its job; the failing case §13.2 guards against is `inline` WITH a `Worker`,
+ * which did not occur.
+ */
+function AutoLayoutPage({
+  count,
+  showChecksum = false,
+  parkHandle = false,
+  fitView = false,
+}: {
+  readonly count: number;
+  readonly showChecksum?: boolean;
+  readonly parkHandle?: boolean;
+  readonly fitView?: boolean;
+}) {
+  const graph = useRef<NodeGraphHandle>(null);
+  const [reading, setReading] = useState<LayoutReading | null>(null);
+  const [pending, setPending] = useState(false);
+  const [checksum, setChecksum] = useState<string | null>(null);
+  const document = useMemo(() => scrambled(count), [count]);
+
+  const onGraphEvent = useCallback((event: GraphEventWire) => {
+    if (event.t !== "layoutResult") return;
+    setPending(false);
+    setReading({
+      runner: event.runner,
+      ms: event.ms,
+      nodeCount: event.nodeCount,
+      error: event.error,
+    });
+    // A rejected relayout laid nothing out, so there is nothing to fit and the
+    // fit would only hide the failure by moving the graph.
+    if (event.error) return;
+    /*
+      Re-fit once a tidy has settled — STORY behaviour, not package behaviour.
+
+      The engine deliberately anchors the tidied box where the old one was
+      (design §8: a tidy that teleports the graph reads as a crash), so a graph
+      that was scattered over 900 units comes back tidy and half off-screen. In
+      a real editor that is right, because the user is looking at a place they
+      chose. In a story nobody chose anything, so the demo fits the result — and
+      it does it through the same handle the buttons use, which is the only door
+      a native sibling has.
+    */
+    graph.current?.fitView();
+  }, []);
+
+  const tidy = useCallback(() => {
+    setPending(true);
+    graph.current?.relayout();
+  }, []);
+
+  /**
+   * React Flow places a node with a CSS TRANSFORM, never with a layout offset.
+   * The first version of this read `offsetLeft` / `offsetTop`, which are 0 for
+   * every node at every arrangement — so the checksum was constant and the
+   * story "passed" without measuring anything. Caught in Chrome, not here.
+   *
+   * WEB ONLY, and honestly so: on device the nodes are inside the WebView and a
+   * Hermes-side `querySelectorAll` has nothing to walk.
+   */
+  const stamp = useCallback(() => {
+    if (!hasDomRealm) {
+      setChecksum("no DOM on this side of the bridge");
+      return;
+    }
+    const nodes = globalThis.document.querySelectorAll<HTMLElement>(reactFlowNodeSelector);
+    let total = 0;
+    for (const node of nodes) {
+      const match = /translate\(([-\d.]+)px,\s*([-\d.]+)px\)/.exec(node.style.transform ?? "");
+      if (!match) continue;
+      total += Number(match[1]) + Number(match[2]) * 3;
+    }
+    setChecksum(`${nodes.length} nodes / ${Math.round(total)}`);
+  }, []);
+
+  /**
+   * The handle browser automation drives for the §13.2 measurement.
+   *
+   * A story-only escape hatch, and it is here rather than in the package
+   * because nothing in the package should be reachable from `window`. It now
+   * hangs off `graphRef`, so it reaches the canvas the same way the buttons do.
+   */
+  useEffect(() => {
+    if (!parkHandle) return;
+    (globalThis as unknown as { __mpoAutoLayout?: unknown }).__mpoAutoLayout = {
+      relayout: () => graph.current?.relayout(),
+      fitView: () => graph.current?.fitView(),
+      reading: () => reading,
+    };
+    return () => {
+      delete (globalThis as unknown as { __mpoAutoLayout?: unknown }).__mpoAutoLayout;
+    };
+  }, [parkHandle, reading]);
+
+  // `inline` where a `Worker` exists is a failed measurement, not a slow one.
+  const wrongRunner = reading?.runner === "inline" && typeof globalThis.Worker === "function";
+
+  return (
+    <YStack width="100%" height={640} padding="$3" gap="$2">
+      <SizableText size="$2" opacity={0.7}>
+        Press Tidy. The readout is the assertion: `worker-blob` on web AND on device — the relayout
+        runs inside the canvas, and on native the canvas is a WebView, which has a real Worker.
+        `inline` on a platform that has Worker is a failed run, not a slow one.
+      </SizableText>
+      {/* OUTSIDE the canvas. On native a child of <NodeGraph> is dropped, which
+          is why this page had no Tidy button on any device until milestone 6. */}
+      <XStack gap="$3" alignItems="center" flexWrap="wrap">
+        <GraphToolbar
+          mode="pan"
+          onModeChange={() => undefined}
+          onFitView={() => graph.current?.fitView()}
+          onTidy={tidy}
+          onUndo={() => graph.current?.undo()}
+          onRedo={() => graph.current?.redo()}
+          busy={pending}
+        />
+        {showChecksum ? (
+          <>
+            <Button size="$2" onPress={stamp}>
+              Stamp positions
+            </Button>
+            <SizableText size="$2" opacity={0.7}>
+              {checksum === null ? "no stamp yet" : `checksum ${checksum}`}
+            </SizableText>
+          </>
+        ) : null}
+      </XStack>
+      <XStack gap="$3" alignItems="center" flexWrap="wrap">
+        <SizableText size="$2" theme={wrongRunner ? "red" : undefined} fontFamily="$mono">
+          {`runner ${reading?.runner ?? "not run yet"}`}
+        </SizableText>
+        {wrongRunner ? (
+          <SizableText size="$2" theme="red">
+            FAILED — this platform has Worker, so `inline` is not a valid measurement
+          </SizableText>
+        ) : null}
+        {/*
+          A REJECTED relayout, which until the m6 device pass answered with
+          nothing at all: the readout sat on "laying out…" forever and that was
+          indistinguishable from a Tidy that never reached the canvas.
+        */}
+        {reading?.error ? (
+          <SizableText size="$2" theme="red">
+            {`FAILED — the engine rejected: ${reading.error}`}
+          </SizableText>
+        ) : null}
+        <SizableText size="$2" opacity={0.7} fontFamily="$mono">
+          {reading === null ? "engine —" : `engine ${reading.ms.toFixed(1)} ms`}
+        </SizableText>
+        <SizableText size="$2" opacity={0.7} fontFamily="$mono">
+          {`${reading?.nodeCount ?? count} nodes`}
+        </SizableText>
+        {pending ? (
+          <SizableText size="$2" opacity={0.7}>
+            laying out…
+          </SizableText>
+        ) : null}
+      </XStack>
+      <YStack flex={1}>
+        <NodeGraph
+          schema={schema}
+          defaultDocument={document}
+          fitView={fitView}
+          graphRef={graph}
+          onGraphEvent={onGraphEvent}
+        >
+          {/*
+            React Flow's own chrome, and the ONE thing that is still legitimately
+            a child: `Background` and `Controls` are React Flow components, they
+            paint inside the pane, and on native the canvas mounts its own chrome
+            from options. Rendered as `null` there rather than passed and dropped,
+            so the milestone-6 warning stays meaningful — a warning that fired on
+            correct code is a warning people learn to ignore.
+          */}
+          {hasDomRealm ? (
+            <>
+              <Background />
+              <Controls />
+            </>
+          ) : null}
+        </NodeGraph>
+      </YStack>
+    </YStack>
+  );
+}
+
+export const Main: Story = {
+  render: () => <AutoLayoutPage count={12} />,
+};
+
+export const Undo: Story = {
+  render: () => <AutoLayoutPage count={12} showChecksum />,
+};
+
+export const Large200: Story = {
+  render: () => <AutoLayoutPage count={200} parkHandle fitView />,
+};

package/src/layout/dagre.ts

@@ -0,0 +1,149 @@
+/**
+ * The dagre adapter: pure, headless, and the only engine in the package.
+ *
+ * Pure so it can run in three realms that share nothing — the main thread, a
+ * classic Worker built from `worker.generated.ts`, and the Hermes JS thread on
+ * native. Headless is not a claim, it is asserted: `layout.spec.ts` stubs
+ * `document` and `window` to `undefined` for every case, because a stray DOM
+ * reach here would surface as a runtime error inside a Worker, which is the
+ * least debuggable place in this package.
+ *
+ * Three things this file is responsible for that dagre is not:
+ *
+ *  - **Centres to top-left.** dagre reports a node's CENTRE. Documents and
+ *    React Flow both hold top-left. Converting at the boundary is why nothing
+ *    downstream has to know dagre's convention.
+ *  - **Determinism.** dagre's own result depends on insertion order, so nodes
+ *    and edges are sorted by id before they go in. Without that, two
+ *    structurally equal documents that were BUILT differently lay out
+ *    differently, and the "same input twice" assertion would pass while the
+ *    real property failed.
+ *  - **The anchor.** A tidy that teleports the graph to the origin looks like
+ *    a crash. The laid-out bounding box's top-left is translated back onto the
+ *    top-left the moved set already occupied, so the arrangement changes and
+ *    the location does not.
+ *
+ * Design §8. Licence: dagre is MIT, compatible with this repo's Apache-2.0 —
+ * unlike elkjs, whose `EPL-2.0 OR GPL-3.0-or-later` is decision D2 and is
+ * still unruled, which is why there is no second engine here.
+ */
+
+import { Graph, layout as runDagre } from "@dagrejs/dagre";
+import type { NodeId, XY } from "../model/document";
+import { ensureStructuredClone } from "./structuredCloneShim";
+import type { LayoutNodeInput, LayoutRequest, LayoutResult } from "./types";
+
+/** dagre's own defaults are 50 / 50; these are tuned for the node measures. */
+export const defaultLayoutSpacing = {
+  direction: "TB",
+  nodeSpacing: 60,
+  rankSpacing: 90,
+  edgeSpacing: 20,
+} as const;
+
+/**
+ * `performance` where it exists, `Date` otherwise.
+ *
+ * Both are present in a Worker and on Hermes, but neither is guaranteed by the
+ * type system in a file that must not assume a realm, and a timing helper is
+ * the last place worth throwing from.
+ */
+function now(): number {
+  return typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+}
+
+/** 2 dp, matching `serializeDocument`, so a laid-out document diffs clean. */
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+function byId<T extends { readonly id: string }>(a: T, b: T): number {
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+function minPoint(points: readonly XY[]): XY {
+  let x = Number.POSITIVE_INFINITY;
+  let y = Number.POSITIVE_INFINITY;
+  for (const point of points) {
+    if (point.x < x) x = point.x;
+    if (point.y < y) y = point.y;
+  }
+  return { x, y };
+}
+
+export function layoutWithDagre(request: LayoutRequest): LayoutResult {
+  // dagre 3.1.1 calls `structuredClone` on the positioning hot path, and
+  // neither Hermes nor a pre-15.4 WKWebView has one. See the shim's header:
+  // this was found by running the bundled worker, not by reading a changelog.
+  ensureStructuredClone();
+  const started = now();
+  const options = request.options ?? {};
+  const nodes = [...request.nodes].sort(byId);
+
+  // A subset id that names no node is dropped rather than refused: the caller
+  // is usually a live selection, and a node deleted between the click and the
+  // request is not an error worth failing a tidy over.
+  const wanted = options.subset ? new Set(options.subset) : undefined;
+  const moving: LayoutNodeInput[] = wanted ? nodes.filter((node) => wanted.has(node.id)) : nodes;
+  const movingIds = new Set(moving.map((node) => node.id));
+
+  const positions: Record<NodeId, XY> = {};
+  for (const node of nodes) positions[node.id] = node.position;
+
+  if (moving.length === 0) {
+    return { positions, moved: [], engine: "dagre", ms: now() - started };
+  }
+
+  const graph = new Graph({ multigraph: true, compound: false, directed: true });
+  graph.setGraph({
+    rankdir: options.direction ?? defaultLayoutSpacing.direction,
+    nodesep: options.nodeSpacing ?? defaultLayoutSpacing.nodeSpacing,
+    ranksep: options.rankSpacing ?? defaultLayoutSpacing.rankSpacing,
+    edgesep: options.edgeSpacing ?? defaultLayoutSpacing.edgeSpacing,
+    marginx: 0,
+    marginy: 0,
+  });
+  graph.setDefaultEdgeLabel(() => ({}));
+
+  for (const node of moving) graph.setNode(node.id, { width: node.width, height: node.height });
+  // Only edges with BOTH ends in the moving set. An edge to a fixed node would
+  // otherwise reintroduce that node as a rank participant, which is the exact
+  // thing `subset` promises not to do.
+  for (const edge of [...request.edges].sort(byId)) {
+    if (!movingIds.has(edge.source) || !movingIds.has(edge.target)) continue;
+    graph.setEdge(edge.source, edge.target, {}, edge.id);
+  }
+
+  runDagre(graph);
+
+  const laid: Record<NodeId, XY> = {};
+  for (const node of moving) {
+    const out = graph.node(node.id) as { x?: number; y?: number } | undefined;
+    laid[node.id] =
+      out && Number.isFinite(out.x) && Number.isFinite(out.y)
+        ? // Centre → top-left.
+          { x: (out.x as number) - node.width / 2, y: (out.y as number) - node.height / 2 }
+        : node.position;
+  }
+
+  const before = minPoint(moving.map((node) => node.position));
+  const after = minPoint(moving.map((node) => laid[node.id]));
+  const shiftX = before.x - after.x;
+  const shiftY = before.y - after.y;
+
+  for (const node of moving) {
+    positions[node.id] = {
+      x: round2(laid[node.id].x + shiftX),
+      y: round2(laid[node.id].y + shiftY),
+    };
+  }
+
+  return {
+    positions,
+    moved: moving.map((node) => node.id),
+    engine: "dagre",
+    ms: now() - started,
+  };
+}