@multiplatform.one/node-graph 7.7.2

package/src/react-flow/ConnectionPuck.tsx

@@ -0,0 +1,175 @@
+/**
+ * The connection puck (design §7.4, task 3.5).
+ *
+ * The native spike named this the hardest touch item, verbatim: the finger
+ * occludes the port it is aiming at. So during a connection drag ONE overlay,
+ * pinned to the top of the canvas, says what the drag is currently over. One
+ * div, updated on move, no per-node cost.
+ *
+ * COUNTER-SCALED, and the mechanism is placement rather than arithmetic. React
+ * Flow renders `<ReactFlow>`'s children as siblings of `.react-flow__viewport`,
+ * not inside it, so nothing here rides the pan/zoom matrix and the puck is the
+ * same physical size at zoom 0.25 and at zoom 2. Applying a `scale(1/zoom)` on
+ * top of that would counter a transform that was never applied and shrink the
+ * puck as the user zoomed IN. `ConnectionPuck.spec.tsx` measures the rendered
+ * size at both extremes rather than trusting either story.
+ *
+ * The candidate it names is filtered through `legalTargets`. `connectionRadius`
+ * is the 44 px hit diameter (task 3.4 H5), so React Flow will snap the drag
+ * onto whatever handle is nearest, including one the schema refuses. Naming a
+ * target the drop will then reject is worse than naming nothing.
+ */
+
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { SizableText, XStack } from "tamagui";
+import { isLegalTarget } from "../interaction/legalTargets";
+import type {
+  EdgeKindDefs,
+  GraphDocument,
+  GraphSchema,
+  NodeKindDefs,
+  PortRef,
+  PortSpec,
+} from "../model/index";
+import { resolvePorts } from "../model/index";
+import { useStore } from "./xy";
+
+export interface ConnectionPuckProps<N extends NodeKindDefs, E extends EdgeKindDefs> {
+  readonly document: GraphDocument<N, E>;
+  readonly schema: GraphSchema<N, E>;
+  /**
+   * Names a node for the puck. Defaults to the node id, which is the only name
+   * the MODEL has: a node's human title lives in the consumer's own `render`,
+   * and this package cannot reach into it.
+   */
+  readonly nodeLabel?: (nodeId: string) => string | undefined;
+  /** Semantic intent, reaches the resolver, never a colour prop. */
+  readonly intent?: string;
+}
+
+/** Separator that cannot occur in a node id or a port id, so the key round-trips. */
+const keySeparator = "\u0000";
+
+function portOf<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  document: GraphDocument<N, E>,
+  schema: GraphSchema<N, E>,
+  ref: PortRef,
+): PortSpec | undefined {
+  const node = document.nodes.find((candidate) => candidate.id === ref.node);
+  if (!node) return undefined;
+  return resolvePorts(schema, node).find((candidate) => candidate.id === ref.port);
+}
+
+function splitKey(key: string): PortRef {
+  const at = key.indexOf(keySeparator);
+  return { node: key.slice(0, at), port: key.slice(at + 1) };
+}
+
+export interface ConnectionPuckLabel {
+  /** What the puck says. */
+  readonly text: string;
+  /** Whether a LEGAL candidate is under the pointer right now. */
+  readonly legal: boolean;
+  /** `node:port` of that candidate, or `""`. What the device screenshot reads. */
+  readonly target: string;
+}
+
+/**
+ * What the puck should say, as a pure function.
+ *
+ * Split out of the component because everything interesting here is a
+ * DECISION — is this candidate legal, and if not what is still worth saying —
+ * and a decision asserted through a rendered DOM is a decision asserted
+ * through three layers of Tamagui. The component keeps only the two store
+ * reads.
+ */
+export function connectionPuckLabel<N extends NodeKindDefs, E extends EdgeKindDefs>(opts: {
+  readonly document: GraphDocument<N, E>;
+  readonly schema: GraphSchema<N, E>;
+  /** null when no connection is in progress. */
+  readonly source: PortRef | null;
+  /** null when the drag is over open canvas. */
+  readonly candidate: PortRef | null;
+  readonly nodeLabel?: (nodeId: string) => string | undefined;
+}): ConnectionPuckLabel | null {
+  const { document, schema, source, candidate, nodeLabel } = opts;
+  if (!source) return null;
+  const legal = candidate ? isLegalTarget({ document, schema, source, target: candidate }) : false;
+  const name = (ref: PortRef) => {
+    const spec = portOf(document, schema, ref);
+    return `${nodeLabel?.(ref.node) ?? ref.node} / ${spec?.label ?? ref.port}`;
+  };
+  return {
+    legal,
+    target: legal && candidate ? `${candidate.node}:${candidate.port}` : "",
+    // An illegal candidate falls back to naming the SOURCE rather than going
+    // blank: a puck that disappears the moment the finger drifts over a
+    // refused port reads as a broken overlay, not as a refusal.
+    text: legal && candidate ? name(candidate) : `from ${name(source)}`,
+  };
+}
+
+export function ConnectionPuck<N extends NodeKindDefs, E extends EdgeKindDefs>({
+  document,
+  schema,
+  nodeLabel,
+  intent,
+}: ConnectionPuckProps<N, E>) {
+  const { knobProps } = useResolvedKnobs({ component: "ConnectionPuck", intent });
+
+  // Two STRINGS, not the connection object. The store hands back a fresh
+  // object on every pointer tick, so selecting it whole would re-render this
+  // component on every frame of a pan as well as a connect. A string compares
+  // by value, which is what makes zustand's shallow check bite.
+  const fromKey = useStore((state) =>
+    state.connection.inProgress
+      ? `${state.connection.fromHandle.nodeId}${keySeparator}${state.connection.fromHandle.id ?? ""}`
+      : null,
+  );
+  const toKey = useStore((state) =>
+    state.connection.inProgress && state.connection.toHandle
+      ? `${state.connection.toHandle.nodeId}${keySeparator}${state.connection.toHandle.id ?? ""}`
+      : null,
+  );
+
+  const label = connectionPuckLabel({
+    document,
+    schema,
+    source: fromKey ? splitKey(fromKey) : null,
+    candidate: toKey ? splitKey(toKey) : null,
+    nodeLabel,
+  });
+  if (!label) return null;
+
+  return (
+    <XStack
+      // React Flow's children are siblings of the viewport, so `absolute` here
+      // is against the CANVAS and the puck stays put while the graph moves
+      // underneath it.
+      position="absolute"
+      top="$3"
+      left="50%"
+      transform="translateX(-50%)"
+      zIndex={5}
+      pointerEvents="none"
+      data-graph-connection-puck=""
+      data-graph-puck-target={label.target}
+      data-graph-puck-legal={String(label.legal)}
+      {...knobProps.elevatedSurface}
+      {...knobProps.containerRadius}
+      {...knobProps.panelPadding}
+      {...knobProps.gap}
+      {...knobProps.elevationChrome}
+      alignItems="center"
+      // Dimmed while nothing legal is under the pointer. The puck is still
+      // saying something true, what you are dragging, just not the thing the
+      // user is looking for.
+      opacity={label.legal ? 1 : 0.7}
+      transition={knobProps.transition}
+    >
+      <SizableText {...knobProps.label} numberOfLines={1}>
+        {label.text}
+      </SizableText>
+    </XStack>
+  );
+}

package/src/react-flow/GraphActions.tsx

@@ -0,0 +1,64 @@
+/**
+ * The canvas's own actions, published to whatever a consumer renders inside it.
+ *
+ * `NodeGraphWeb` mounts the controller; a toolbar, a Tidy button or an Undo
+ * button is a `children` of the canvas, which is BELOW that. Without a channel
+ * the only way to reach `relayout()` would be for every consumer to call
+ * `useGraphController` themselves and mount `ReactFlow` by hand, which is
+ * exactly the composition the package exists to do once.
+ *
+ * A context rather than a ref prop: `canUndo`, `layoutPending` and
+ * `layoutRunner` all change, and a button that reads them has to re-render
+ * when they do. A ref would hand out stale booleans.
+ *
+ * Deliberately NOT merged into `GraphHostProvider`. That context is read by
+ * every node body on every render at 200 nodes; putting `layoutPending` in it
+ * would re-render the whole graph each time a tidy starts and finishes.
+ */
+
+import { createContext, useContext } from "react";
+import type { ReactNode } from "react";
+import type { LayoutRunnerKind } from "../diagnostics/types";
+import type { LayoutResult } from "../layout/types";
+import type { GraphRelayoutOptions } from "./useGraphController";
+
+export interface GraphActions {
+  /** Tidy. ONE undoable command, design §8. */
+  readonly relayout: (options?: GraphRelayoutOptions) => Promise<LayoutResult | null>;
+  readonly undo: () => void;
+  readonly redo: () => void;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  /** `none` until the first relayout has resolved a runner. */
+  readonly layoutRunner: LayoutRunnerKind;
+  readonly lastLayoutMs: number | null;
+  readonly layoutPending: boolean;
+  readonly nodeCount: number;
+}
+
+const GraphActionsContext = createContext<GraphActions | null>(null);
+
+export function GraphActionsProvider({
+  value,
+  children,
+}: {
+  readonly value: GraphActions;
+  readonly children: ReactNode;
+}) {
+  return <GraphActionsContext.Provider value={value}>{children}</GraphActionsContext.Provider>;
+}
+
+/**
+ * Throws outside the canvas, on purpose. A silent `null` here would surface as
+ * a Tidy button that does nothing, which is the hardest kind of bug to see in
+ * a story.
+ */
+export function useGraphActions(): GraphActions {
+  const value = useContext(GraphActionsContext);
+  if (!value) {
+    throw new Error(
+      "useGraphActions must be called inside <NodeGraph> — pass the toolbar as its children.",
+    );
+  }
+  return value;
+}

package/src/react-flow/GraphCommandBridge.spec.tsx

@@ -0,0 +1,130 @@
+/**
+ * A relayout ALWAYS answers, and what a freshly recreated WebView carries.
+ *
+ * The m6 device pass could not separate two explanations for Android's Tidy
+ * never answering: "relayout is broken on Android" and "relayout is broken on a
+ * Retry-recreated canvas". Both emulators had come up through the watchdog +
+ * Retry path and iOS never did, so the run had no control condition.
+ *
+ * Reading the layout path answers half of it and the answer is NO. Nothing on
+ * the DOM side survives a WebView recreation, because the whole JS REALM is
+ * destroyed with it:
+ *
+ *  - `layout/runner.ts`'s `cached` runner promise is module scope, so a new
+ *    realm re-evaluates the module and re-probes from scratch. `resetLayoutRunner`
+ *    exists as the escape hatch and no host needs it for this.
+ *  - the Worker's blob URL is minted by `URL.createObjectURL` in the realm that
+ *    spawns it and dies with that realm's `URL` registry.
+ *  - the schema registry is module scope in the DOM bundle, re-populated by the
+ *    entry's own module eval on every boot.
+ *
+ * The native side is where the bug was, and it was the imperative ref rather
+ * than anything about layout: see `native/graphHandleRemount.spec.tsx`.
+ *
+ * What IS wrong here, and is fixed by this file's subject, is that a relayout
+ * which REJECTS answered with nothing. `layout()` rejects when the blob Worker
+ * cannot be constructed or dies mid-flight — both realm-local, so both are
+ * exactly what a recreated WebView can hit — and the bridge only had a `.then`.
+ * The rejection went to `unhandledrejection`, was reported as a non-fatal
+ * `runtime` error (correctly), and no `layoutResult` crossed. A toolbar stuck
+ * on "laying out…" is then indistinguishable from a Tidy that never arrived,
+ * which is the exact ambiguity the device run got stuck in.
+ */
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import type { GraphEventWire } from "../dom/wire";
+import { GraphActionsProvider } from "./GraphActions";
+import type { GraphActions } from "./GraphActions";
+import { GraphCommandBridge } from "./GraphCommandBridge";
+import type { GraphCommands } from "./graphHandle";
+import { ReactFlowProvider } from "./xy";
+
+afterEach(cleanup);
+
+function harness(relayout: GraphActions["relayout"]) {
+  const events: GraphEventWire[] = [];
+  const commands: { current: GraphCommands | null } = { current: null };
+  const actions: GraphActions = {
+    relayout,
+    undo: () => undefined,
+    redo: () => undefined,
+    canUndo: false,
+    canRedo: false,
+    layoutRunner: "worker-blob",
+    lastLayoutMs: null,
+    layoutPending: false,
+    nodeCount: 200,
+  };
+  renderWithProviders(
+    <ReactFlowProvider>
+      <GraphActionsProvider value={actions}>
+        <GraphCommandBridge
+          commands={commands}
+          culling
+          emit={(event) => events.push(event)}
+          host="react-flow-dom"
+          rootRef={{ current: null }}
+        />
+      </GraphActionsProvider>
+    </ReactFlowProvider>,
+  );
+  return { commands, events, layouts: () => events.filter((event) => event.t === "layoutResult") };
+}
+
+describe("relayout over the wire", () => {
+  it("answers with the runner and the engine ms when the engine ran", async () => {
+    const view = harness(() =>
+      Promise.resolve({ runner: "worker-blob" as const, ms: 31.8, positions: {} } as never),
+    );
+    view.commands.current?.relayout();
+    await waitFor(() => expect(view.layouts()).toHaveLength(1));
+    const [result] = view.layouts();
+    expect(result).toMatchObject({ runner: "worker-blob", ms: 31.8, nodeCount: 200 });
+    expect(result?.t === "layoutResult" && result.error).toBeUndefined();
+  });
+
+  /**
+   * The one this file exists for. A rejection has to CROSS, or the readout and
+   * a dead bridge look the same on a phone with no console.
+   */
+  it("answers when the engine REJECTS, instead of leaving the toolbar to wait", async () => {
+    const view = harness(() =>
+      Promise.reject(new Error("the layout worker raised an error event")),
+    );
+    view.commands.current?.relayout();
+    await waitFor(() => expect(view.layouts()).toHaveLength(1));
+    const [result] = view.layouts();
+    expect(result).toMatchObject({
+      runner: "none",
+      ms: 0,
+      nodeCount: 200,
+      error: "the layout worker raised an error event",
+    });
+  });
+
+  /**
+   * `none` and 0, never an invented runner or a plausible millisecond count. A
+   * failed tidy that reads `worker-blob · 0.0 ms` is a failed tidy nobody
+   * notices.
+   */
+  it("does not dress a rejection up as a fast layout", async () => {
+    const view = harness(() => Promise.reject(new Error("boom")));
+    view.commands.current?.relayout();
+    await waitFor(() => expect(view.layouts()).toHaveLength(1));
+    const [result] = view.layouts();
+    expect(result?.t === "layoutResult" && result.runner).toBe("none");
+    expect(result?.t === "layoutResult" && result.ms).toBe(0);
+  });
+
+  /** An empty graph is `null`, and `none` is honest there: no engine ran. */
+  it("reports `none` with no error for a graph there was nothing to lay out", async () => {
+    const view = harness(() => Promise.resolve(null));
+    view.commands.current?.relayout();
+    await waitFor(() => expect(view.layouts()).toHaveLength(1));
+    const [result] = view.layouts();
+    expect(result).toMatchObject({ runner: "none", ms: 0 });
+    expect(result?.t === "layoutResult" && result.error).toBeUndefined();
+  });
+});

package/src/react-flow/GraphCommandBridge.tsx

@@ -0,0 +1,288 @@
+/**
+ * The one place the imperative handle is IMPLEMENTED, for both realms.
+ *
+ * Milestone 6's rule (design §9.1): on native a consumer cannot put React
+ * children inside the canvas, so a control is either a native SIBLING driving
+ * the canvas through the handle, or it is rendered inside the DOM bundle from
+ * serializable options. That makes the handle load-bearing rather than
+ * decorative, and a handle implemented twice — once for the WebView and once
+ * for the web — is two implementations that drift. `NodeGraphWeb` mounts this
+ * and publishes the result through `graphRef`; `NodeGraphDomInner` mounts the
+ * same component and lets the shell forward it across the bridge.
+ *
+ * It is a CHILD of `ReactFlow` because `useReactFlow()` throws outside the
+ * provider the canvas mounts itself, and a child of `GraphActionsProvider`
+ * because `relayout` / `undo` / `redo` live on the controller. It renders
+ * `null`: nothing here paints.
+ *
+ * THE SAMPLER LIVES HERE TOO, and that is the milestone-6 change that unblocks
+ * every device frame number. `Perf200` used to own it, as a CHILD of
+ * `<NodeGraph>` — which native drops — so `window.__mpoPerf200` appeared zero
+ * times in the emitted www.bundle and no device run was possible at all. The
+ * sampler has to run in the realm that PAINTS: the host RN view's frame clock
+ * keeps ticking while the WebView is stalled, so it measures the wrong thing by
+ * construction.
+ */
+
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import type { FrameRun } from "../bench/frameSampler";
+import {
+  createDomTransformProbe,
+  createFrameSampler,
+  gestureWindow,
+  reportRun,
+} from "../bench/frameSampler";
+import type { GraphEventWire, PerfReportWire } from "../dom/wire";
+import type { GraphCommandSlot } from "./graphHandle";
+import { useGraphActions } from "./GraphActions";
+import {
+  reactFlowNodeSelector,
+  reactFlowPaneSelector,
+  reactFlowViewportSelector,
+  useReactFlow,
+} from "./xy";
+
+export interface GraphCommandBridgeProps {
+  /** Filled once React Flow is reachable, emptied on unmount. */
+  readonly commands: GraphCommandSlot;
+  /** The single channel. `onEvent` on the DOM side; a story collector on web. */
+  readonly emit: (event: GraphEventWire) => void;
+  /** `react-flow-dom` or `react-flow-web`. Recorded on every perf report. */
+  readonly host: string;
+  /** Whether `onlyRenderVisibleElements` is on, recorded on every perf report. */
+  readonly culling: boolean;
+  /** The canvas root, so two canvases on one page do not measure each other. */
+  readonly rootRef: { current: HTMLElement | null };
+  /** The DOM realm stamps its boot record here. Web passes nothing. */
+  readonly onMounted?: () => void;
+}
+
+/**
+ * A rejected run crosses the bridge too.
+ *
+ * `reportRun` discards a run where nothing moved (design §13.2, and the
+ * reactflow spike lost a whole round of measurements to a silently reset touch
+ * emulation). On a phone a Stop that produced nothing and a Stop that never
+ * reached the canvas look identical, so the rejection is reported as a
+ * rejection rather than as silence.
+ */
+function toWire(
+  run: FrameRun,
+  label: string,
+  context: { host: string; culling: boolean; nodeCount: number; layoutRunner: string },
+): PerfReportWire {
+  const result = reportRun(run, { ...context, label });
+  if (!result.ok) {
+    return {
+      ok: false,
+      reason: result.error.reason,
+      message: result.error.message,
+      label,
+      nodeCount: run.nodeCount || context.nodeCount,
+      culling: context.culling,
+      layoutRunner: context.layoutRunner,
+      didMove: run.didMove,
+      durationMs: run.stoppedAt - run.startedAt,
+      stats: run.stats,
+      // Carried on a REJECTION too: a run discarded for `didMove` still says
+      // how many gestures were bracketed, which is what tells an operator
+      // whether the marks were the thing that went wrong.
+      gesture: gestureWindow(run),
+      reportJson: "",
+    };
+  }
+  return {
+    ok: true,
+    label,
+    nodeCount: result.value.nodeCount,
+    culling: result.value.culling,
+    layoutRunner: result.value.layoutRunner ?? context.layoutRunner,
+    didMove: true,
+    durationMs: result.value.durationMs,
+    stats: result.value.stats,
+    gesture: result.value.gesture,
+    reportJson: JSON.stringify(result.value),
+  };
+}
+
+export function GraphCommandBridge({
+  commands,
+  culling,
+  emit,
+  host,
+  onMounted,
+  rootRef,
+}: GraphCommandBridgeProps) {
+  const flow = useReactFlow();
+  const actions = useGraphActions();
+
+  // Read through a ref so the command object below is built ONCE. A relayout
+  // flips `layoutPending` twice, and rebuilding the whole handle on each flip
+  // would hand the shell a new object mid-gesture.
+  const latest = useRef({ actions, culling, host });
+  latest.current = { actions, culling, host };
+
+  const probe = useMemo(
+    () =>
+      createDomTransformProbe({
+        viewport: reactFlowViewportSelector,
+        node: reactFlowNodeSelector,
+        root: rootRef.current ?? undefined,
+      }),
+    [rootRef],
+  );
+
+  const countNodes = useCallback(() => {
+    const root = rootRef.current ?? globalThis.document;
+    return root?.querySelectorAll(reactFlowNodeSelector).length ?? 0;
+  }, [rootRef]);
+
+  const sampler = useMemo(
+    () => createFrameSampler({ probeTransform: probe, countNodes }),
+    [countNodes, probe],
+  );
+
+  useEffect(() => {
+    onMounted?.();
+    commands.current = {
+      fitView: () => {
+        void flow.fitView();
+      },
+      /**
+       * It was a NO-OP and the comment said so: milestone 4 would fill it in,
+       * and milestone 4 built the engine and never came back. `layoutRunner`
+       * therefore read `none` on every device — not because the probe failed,
+       * but because nothing on a phone could ask for a layout.
+       */
+      relayout: () => {
+        void latest.current.actions
+          .relayout()
+          .then((result) => {
+            emit({
+              t: "layoutResult",
+              // `none` is honest for an empty graph: no engine ran, so no runner
+              // produced anything, and inventing one would be a reading.
+              runner: result?.runner ?? "none",
+              ms: result?.ms ?? 0,
+              nodeCount: latest.current.actions.nodeCount,
+            });
+          })
+          /**
+           * A REJECTION ANSWERS TOO, and this is the second way the m6 Android
+           * Tidy could have gone silent.
+           *
+           * `layout()` rejects when the blob Worker cannot be constructed or
+           * dies mid-flight, and both are realm-local: a Retry-recreated
+           * WebView builds a new blob URL and a new Worker, and either can
+           * fail on its own. With only a `.then` the rejection went to
+           * `unhandledrejection` — reported as a non-fatal `runtime` error,
+           * correctly — and no `layoutResult` ever crossed. The toolbar then
+           * sits on "laying out…" forever, which from the outside is
+           * identical to a Tidy that never reached the canvas at all.
+           *
+           * `runner: "none"` and `ms: 0` because inventing either would read
+           * as a successful tidy; the message is what says otherwise.
+           */
+          .catch((error: unknown) => {
+            emit({
+              t: "layoutResult",
+              runner: "none",
+              ms: 0,
+              nodeCount: latest.current.actions.nodeCount,
+              error: error instanceof Error ? error.message : String(error),
+            });
+          });
+      },
+      zoomTo: (zoom) => {
+        void flow.zoomTo(zoom);
+      },
+      centerOn: (nodeId) => {
+        void flow.fitView({ nodes: [{ id: nodeId }], duration: 200 });
+      },
+      setSelection: (ids) => {
+        const wanted = new Set(ids);
+        flow.setNodes((nodes) => nodes.map((node) => ({ ...node, selected: wanted.has(node.id) })));
+        emit({ t: "selection", ids: [...wanted] });
+      },
+      exportViewport: () => {
+        emit({ t: "viewport", viewport: flow.getViewport() });
+      },
+      undo: () => latest.current.actions.undo(),
+      redo: () => latest.current.actions.redo(),
+      perfStart: () => sampler.start(),
+      perfMark: (label) => {
+        sampler.mark(label);
+      },
+      setViewport: (x, y, zoom) => {
+        // No `duration`: an animated move is still moving when the sampler
+        // starts, and the first frames of every run would measure the seek.
+        void flow.setViewport({ x, y, zoom });
+      },
+      /**
+       * Synthesised pinch, design §13.2. Dispatched on the PANE, because that
+       * is the element d3-zoom binds its touch listener to.
+       *
+       * It moved in here from the Perf200 story in milestone 6 for the reason
+       * everything else did: the pane exists only in the realm the canvas
+       * paints in, and on native that realm is the WebView. A story on the
+       * Hermes side has no pane to dispatch on.
+       */
+      synthPinch: (scale, steps) => {
+        const root = rootRef.current ?? globalThis.document;
+        const pane = root?.querySelector<HTMLElement>(reactFlowPaneSelector);
+        if (!pane) return;
+        // A desktop Chrome with no touch emulation has no `Touch` constructor
+        // at all. Returning is honest: "the pinch did nothing" and "the browser
+        // has no touch" are different findings and only one is a bug. The
+        // caller learns which from the perf run's own `didMove`.
+        if (typeof Touch !== "function" || typeof TouchEvent !== "function") return;
+        const box = pane.getBoundingClientRect();
+        const cx = box.left + box.width / 2;
+        const cy = box.top + box.height / 2;
+        const point = (id: number, x: number, y: number) =>
+          new Touch({ identifier: id, target: pane, clientX: x, clientY: y });
+        const send = (type: string, points: Touch[]) => {
+          pane.dispatchEvent(
+            new TouchEvent(type, {
+              bubbles: true,
+              cancelable: true,
+              touches: points,
+              targetTouches: points,
+              changedTouches: points,
+            }),
+          );
+        };
+        const spread = 60;
+        const total = Math.max(1, Math.round(steps));
+        send("touchstart", [point(1, cx - spread, cy), point(2, cx + spread, cy)]);
+        let step = 0;
+        const advance = () => {
+          step += 1;
+          const factor = 1 + (scale - 1) * (step / total);
+          const half = spread * factor;
+          send("touchmove", [point(1, cx - half, cy), point(2, cx + half, cy)]);
+          if (step < total) globalThis.requestAnimationFrame(advance);
+          else send("touchend", []);
+        };
+        globalThis.requestAnimationFrame(advance);
+      },
+      perfStop: (label) => {
+        const run = sampler.stop();
+        emit({
+          t: "perfReport",
+          report: toWire(run, label, {
+            culling: latest.current.culling,
+            host: latest.current.host,
+            layoutRunner: latest.current.actions.layoutRunner,
+            nodeCount: latest.current.actions.nodeCount,
+          }),
+        });
+      },
+    };
+    return () => {
+      commands.current = null;
+    };
+  }, [commands, emit, flow, onMounted, rootRef, sampler]);
+
+  return null;
+}