@multiplatform.one/node-graph 7.7.2

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

@@ -0,0 +1,161 @@
+/**
+ * Design §7.2 S10, the one snapping rule that is about the DOM.
+ *
+ * It lives here rather than in `interaction/snapChanges.spec.ts`, where the
+ * plan drafted it, for a mechanical reason: the claim is "one `<svg>` with at
+ * most two `<line>` children, inside the viewport transform", and only the
+ * component that renders it can be asked what it made. The other five wiring
+ * rules stay pure and stay there.
+ *
+ * The guides are mounted inside a real `<ReactFlow>` because `ViewportPortal`
+ * renders into the store's viewport node. A test that mounted the svg on its
+ * own would assert the markup and prove nothing about where it lands, which is
+ * the half of S10 that matters.
+ */
+
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { cleanup } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import type { SnapGuide } from "../interaction/snapAlignment";
+import {
+  SnapGuides,
+  snapGuideClassName,
+  snapGuidePadding,
+  snapGuidesBounds,
+  snapGuidesClassName,
+} from "./SnapGuides";
+import { ReactFlow, ReactFlowProvider } from "./xy";
+
+afterEach(cleanup);
+
+const xGuide: SnapGuide = {
+  axis: "x",
+  position: 300,
+  start: 0,
+  end: 450,
+  nodeId: "c",
+  movingLine: "start",
+  candidateLine: "start",
+};
+
+const yGuide: SnapGuide = {
+  axis: "y",
+  position: 200,
+  start: 10,
+  end: 620,
+  nodeId: "d",
+  movingLine: "center",
+  candidateLine: "end",
+};
+
+function mount(guides: readonly SnapGuide[], animated?: boolean) {
+  return renderWithProviders(
+    <ReactFlowProvider>
+      <ReactFlow nodes={[]} edges={[]} proOptions={{ hideAttribution: true }}>
+        <SnapGuides guides={guides} animated={animated} />
+      </ReactFlow>
+    </ReactFlowProvider>,
+  );
+}
+
+describe("SnapGuides", () => {
+  it("renders nothing at all when there is nothing to align to", () => {
+    const { container } = mount([]);
+    expect(container.querySelector(`.${snapGuidesClassName}`)).toBeNull();
+  });
+
+  it("renders ONE svg with one line for one guide", () => {
+    const { container } = mount([xGuide]);
+    expect(container.querySelectorAll(`.${snapGuidesClassName}`)).toHaveLength(1);
+    expect(container.querySelectorAll(`.${snapGuideClassName}`)).toHaveLength(1);
+  });
+
+  it("renders ONE svg with two lines for both axes, never a layer per guide", () => {
+    const { container } = mount([xGuide, yGuide]);
+    expect(container.querySelectorAll(`.${snapGuidesClassName}`)).toHaveLength(1);
+    expect(container.querySelectorAll(`.${snapGuideClassName}`)).toHaveLength(2);
+  });
+
+  it("puts the layer INSIDE the viewport, so pan and zoom carry it for free", () => {
+    const { container } = mount([xGuide]);
+    const viewport = container.querySelector(".react-flow__viewport");
+    expect(viewport).not.toBeNull();
+    expect(viewport?.querySelector(`.${snapGuidesClassName}`)).not.toBeNull();
+  });
+
+  it("draws a vertical line for an x guide and a horizontal one for a y guide", () => {
+    const { container } = mount([xGuide, yGuide]);
+    const box = snapGuidesBounds([xGuide, yGuide]);
+    if (!box) throw new Error("two guides have a box");
+    const [vertical, horizontal] = Array.from(container.querySelectorAll(`.${snapGuideClassName}`));
+    // Local coordinates: the layer is translated to `box`, so a line's numbers
+    // are its flow position minus the box origin.
+    expect([
+      vertical.getAttribute("x1"),
+      vertical.getAttribute("x2"),
+      vertical.getAttribute("y1"),
+      vertical.getAttribute("y2"),
+    ]).toEqual([`${300 - box.x}`, `${300 - box.x}`, `${0 - box.y}`, `${450 - box.y}`]);
+    expect([
+      horizontal.getAttribute("x1"),
+      horizontal.getAttribute("x2"),
+      horizontal.getAttribute("y1"),
+      horizontal.getAttribute("y2"),
+    ]).toEqual([`${10 - box.x}`, `${620 - box.x}`, `${200 - box.y}`, `${200 - box.y}`]);
+  });
+
+  it.each([[[xGuide]], [[yGuide]], [[xGuide, yGuide]]])(
+    "gives the layer a box that CONTAINS every line it draws",
+    (guides) => {
+      // The assertion that would have caught the invisible first version. It
+      // was `width={0} height={0}` with `overflow: visible`, drawing in flow
+      // coordinates: correct DOM, and nothing painted, because an outermost
+      // svg clips to its own viewport. Every other test in this file passed.
+      const { container } = mount(guides);
+      const svg = container.querySelector(`.${snapGuidesClassName}`);
+      if (!svg) throw new Error("a guide layer");
+      const width = Number(svg.getAttribute("width"));
+      const height = Number(svg.getAttribute("height"));
+      expect(width).toBeGreaterThan(0);
+      expect(height).toBeGreaterThan(0);
+      for (const line of Array.from(container.querySelectorAll(`.${snapGuideClassName}`))) {
+        for (const [attribute, extent] of [
+          ["x1", width],
+          ["x2", width],
+          ["y1", height],
+          ["y2", height],
+        ] as const) {
+          const value = Number(line.getAttribute(attribute));
+          expect(value).toBeGreaterThanOrEqual(0);
+          expect(value).toBeLessThanOrEqual(extent);
+        }
+      }
+    },
+  );
+
+  it("pads the box, so a centred stroke is not sliced in half by its own edge", () => {
+    const box = snapGuidesBounds([xGuide]);
+    expect(box).toEqual({
+      x: 300 - snapGuidePadding,
+      y: 0 - snapGuidePadding,
+      width: snapGuidePadding * 2,
+      height: 450 + snapGuidePadding * 2,
+    });
+  });
+
+  it("has no box for no guides", () => {
+    expect(snapGuidesBounds([])).toBeNull();
+  });
+
+  it("carries the animated flag, which is all motion settings get to change", () => {
+    const { container } = mount([xGuide], false);
+    expect(container.querySelector(`.${snapGuidesClassName}`)?.getAttribute("data-animated")).toBe(
+      "false",
+    );
+    cleanup();
+    const on = mount([xGuide], true);
+    expect(
+      on.container.querySelector(`.${snapGuidesClassName}`)?.getAttribute("data-animated"),
+    ).toBe("true");
+  });
+});

package/src/react-flow/SnapGuides.tsx

@@ -0,0 +1,113 @@
+/**
+ * The alignment guides, design §7.2 S10.
+ *
+ * ONE `<svg>` with at most two `<line>` children, inside React Flow's viewport
+ * transform, cleared the moment the drag ends. Never a div per guide: a guide
+ * is a hairline across the canvas, and a div layer would need its own width,
+ * its own transform, and its own rounding, all of which the viewport already
+ * did for us.
+ *
+ * **The svg is SIZED to its lines, and that is not cosmetic.** The first
+ * version was `width={0} height={0}` with `overflow: visible`, drawing in flow
+ * coordinates — structurally right, and INVISIBLE in Chrome. The DOM was
+ * correct (one svg, two lines, right coordinates, stroke resolved from the var
+ * layer) and nothing painted, because an outermost `<svg>` clips to its own
+ * viewport and a zero-sized viewport has nothing inside it. Measured on
+ * `NodeGraph/Snapping → ZoomThreshold` by forcing the stroke to 6 px and
+ * screenshotting: still nothing. So the layer takes the bounding box of the
+ * guides, plus a small pad for the stroke, and draws in LOCAL coordinates.
+ *
+ * `vector-effect: non-scaling-stroke` in `css/graph.css` is what keeps a
+ * hairline a hairline at 4x zoom rather than a 2 px bar.
+ */
+
+import type { SnapGuide } from "../interaction/snapAlignment";
+import { ViewportPortal } from "./xy";
+
+export const snapGuidesClassName = "mp-graph-guides";
+export const snapGuideClassName = "mp-graph-guide";
+
+/**
+ * Flow units of slack around the box. The stroke is centred on the line, so a
+ * box that ends exactly on it would clip half of it away; and at a pinched-out
+ * zoom the painted stroke is wider than the flow units it sits in.
+ */
+export const snapGuidePadding = 2;
+
+export interface SnapGuidesBox {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/** The padded box that holds every line. Exported because the spec asserts it. */
+export function snapGuidesBounds(guides: readonly SnapGuide[]): SnapGuidesBox | null {
+  if (guides.length === 0) return null;
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  for (const guide of guides) {
+    const [x1, y1, x2, y2] =
+      guide.axis === "x"
+        ? [guide.position, guide.start, guide.position, guide.end]
+        : [guide.start, guide.position, guide.end, guide.position];
+    minX = Math.min(minX, x1, x2);
+    maxX = Math.max(maxX, x1, x2);
+    minY = Math.min(minY, y1, y2);
+    maxY = Math.max(maxY, y1, y2);
+  }
+  return {
+    x: minX - snapGuidePadding,
+    y: minY - snapGuidePadding,
+    width: maxX - minX + snapGuidePadding * 2,
+    height: maxY - minY + snapGuidePadding * 2,
+  };
+}
+
+export interface SnapGuidesProps {
+  readonly guides: readonly SnapGuide[];
+  /**
+   * Design §7.2 S11: motion settings fade the guide, they do not turn snapping
+   * off. False under `animation: "none"` and under OS reduced motion.
+   */
+  readonly animated?: boolean;
+}
+
+export function SnapGuides({ guides, animated = true }: SnapGuidesProps) {
+  const box = snapGuidesBounds(guides);
+  if (!box) return null;
+  return (
+    <ViewportPortal>
+      <svg
+        className={snapGuidesClassName}
+        data-animated={animated ? "true" : "false"}
+        width={box.width}
+        height={box.height}
+        style={{
+          position: "absolute",
+          left: 0,
+          top: 0,
+          // The same mechanism React Flow moves its own nodes with, so the
+          // guide and the node it points at cannot round differently.
+          transform: `translate(${box.x}px, ${box.y}px)`,
+          overflow: "visible",
+          pointerEvents: "none",
+        }}
+      >
+        {guides.map((guide) => (
+          <line
+            key={guide.axis}
+            className={snapGuideClassName}
+            data-axis={guide.axis}
+            x1={(guide.axis === "x" ? guide.position : guide.start) - box.x}
+            x2={(guide.axis === "x" ? guide.position : guide.end) - box.x}
+            y1={(guide.axis === "x" ? guide.start : guide.position) - box.y}
+            y2={(guide.axis === "x" ? guide.end : guide.position) - box.y}
+          />
+        ))}
+      </svg>
+    </ViewportPortal>
+  );
+}

package/src/react-flow/demoControlBody.tsx

@@ -0,0 +1,96 @@
+/**
+ * Design §13.2's plain-div CONTROL condition, as a schema the DOM bundle can
+ * reach.
+ *
+ * The delta between this and `demoGraphSchema()` is the Tamagui cost, measured
+ * on the host in front of you instead of carried over from the web's ~10%. Same
+ * graph, same edges, same React Flow `Handle`s — only the node BODY changes,
+ * from the package's `GraphNode` frame to a bare styled `div`. The handles stay
+ * because removing them would change what React Flow itself does per node, and
+ * then the two cells would not be the same experiment.
+ *
+ * WHY IT IS HERE AND NOT IN THE STORY, which is where it was written.
+ *
+ * A `NodeKindSpec.render` is a `ComponentType`, so it cannot be JSON and cannot
+ * cross the bridge: the only string that crosses is `schemaId`, and the canvas
+ * resolves it inside the DOM bundle. `bench/Perf200.stories.tsx` runs on the
+ * Hermes side, so a schema built there is unreachable from the realm that has
+ * to render it. Measured on the iPhone 16e at m6: `Perf200 → Control` reported
+ * `render: no graph schema registered as "node-graph-demo-control"` and painted
+ * nothing, which left §13.2's mandated control condition unmeasurable on every
+ * device.
+ *
+ * Moving it into the package is only half the fix. The other half is that the
+ * app's `'use dom'` entry can now register MORE THAN ONE schema — see
+ * `NodeGraphDomRealmProps.schemas` — because an id-keyed lookup over a list is
+ * the thing that scales past the single special case the inner tree carried.
+ *
+ * The inline styles are deliberately dumb literals off the `currentColor`
+ * chain, with no token and no `useResolvedKnobs` anywhere in the subtree: a
+ * control that resolved tokens would be measuring a slice of the thing it is
+ * the control for.
+ */
+
+import type { GraphNodeRenderProps } from "../model/index";
+import { createGraphSchema, defaultRules } from "../model/index";
+import type { BuiltinEdgeData } from "../edges/edgeKinds";
+import { builtinEdgeKinds } from "../edges/edgeKinds";
+import type { DemoNodeData } from "./fixtures";
+import { demoControlSchemaId, demoSchemaShape } from "./fixtures";
+import { Handle, Position } from "./xy";
+
+export function DemoControlBody<TData>({
+  ports,
+  measure,
+  title,
+}: GraphNodeRenderProps<TData> & { readonly title: string }) {
+  return (
+    <div
+      style={{
+        width: measure?.width ?? 190,
+        minHeight: measure?.minHeight ?? 72,
+        boxSizing: "border-box",
+        border: "1px solid currentColor",
+        borderRadius: 8,
+        padding: 8,
+        font: "inherit",
+        opacity: 0.9,
+      }}
+    >
+      <div style={{ fontWeight: 600 }}>{title}</div>
+      {ports.map((port, index) => (
+        <Handle
+          key={port.id}
+          id={port.id}
+          type={port.direction === "out" ? "source" : "target"}
+          position={port.side === "right" ? Position.Right : Position.Left}
+          style={{ top: 24 + index * 20, width: 8, height: 8, borderRadius: "50%" }}
+        />
+      ))}
+    </div>
+  );
+}
+
+/**
+ * The same measures, ports and rules as the demo schema, with plain bodies.
+ *
+ * `demoSchemaShape()` rather than a second kind table, for the reason that
+ * module already gives: a second copy is a second thing to keep in step, and a
+ * control whose geometry drifted from the subject would measure two graphs.
+ */
+export function demoControlSchema() {
+  const shape = demoSchemaShape();
+  const body = (title: string) => (props: GraphNodeRenderProps<never>) => (
+    <DemoControlBody {...props} title={title} />
+  );
+  return createGraphSchema<DemoNodeData, BuiltinEdgeData>({
+    id: demoControlSchemaId,
+    nodes: {
+      source: { ...shape.nodes.source, render: body("Source") as never },
+      transform: { ...shape.nodes.transform, render: body("Transform") as never },
+      sink: { ...shape.nodes.sink, render: body("Sink") as never },
+    },
+    edges: builtinEdgeKinds,
+    rules: defaultRules,
+  });
+}

package/src/react-flow/demoNodeBody.tsx

@@ -0,0 +1,121 @@
+/**
+ * The node body the task-1.11 spec and the `NodeGraph/NodeGraph` story both
+ * mount.
+ *
+ * It is what a CONSUMER writes: a `NodeKindSpec.render` that composes the
+ * package's `GraphNode` frame and `GraphPort` disc. Keeping it here rather than
+ * inside the story is deliberate — the spec and the story then assert the same
+ * tree, so a story that renders cannot be a story that renders something else.
+ *
+ * Its own file, and its own NAME, because `demoNodeBody.tsx` beside a
+ * `demoNodeBody.ts` would be ONE module on macOS. See the note in
+ * `nodes/nodeMeasure.ts`.
+ */
+
+import type { GraphNodeRenderProps, PortSpec } from "../model/index";
+import { createGraphSchema, defaultRules } from "../model/index";
+import type { BuiltinEdgeData } from "../edges/edgeKinds";
+import { builtinEdgeKinds } from "../edges/edgeKinds";
+import { GraphNode } from "../nodes/GraphNode";
+import { GraphPort } from "../nodes/GraphPort";
+import type { GraphNodePort } from "../nodes/nodeMeasure";
+import type { DemoNodeData } from "./fixtures";
+import { demoSchemaShape } from "./fixtures";
+
+interface BodyProps<TData> extends GraphNodeRenderProps<TData> {
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly intent?: string;
+  readonly coarsePointer?: boolean;
+}
+
+function Body<TData>({
+  id,
+  title,
+  subtitle,
+  intent,
+  ports,
+  selected,
+  dragging,
+  renderMode,
+  coarsePointer,
+  measure,
+}: BodyProps<TData>) {
+  return (
+    <GraphNode
+      id={id}
+      title={title}
+      subtitle={subtitle}
+      intent={intent}
+      selected={selected}
+      dragging={dragging}
+      renderMode={renderMode}
+      coarsePointer={coarsePointer}
+      // The kind's own measure, so the painted frame is the width the canvas
+      // seeded React Flow with.
+      measure={measure}
+      // `PortSpec` is structurally the port the frame measures and labels; it
+      // adds `index`, `dataType` and `arity`, none of which paint.
+      ports={ports as readonly GraphNodePort[]}
+      renderPort={(port) => (
+        <GraphPort
+          id={port.id}
+          side={port.side}
+          direction={port.direction}
+          intent={intent}
+          coarsePointer={coarsePointer}
+        />
+      )}
+    />
+  );
+}
+
+export function DemoSourceBody(props: GraphNodeRenderProps<DemoNodeData["source"]>) {
+  return <Body {...props} title="Source" subtitle={`table: ${props.data.table}`} />;
+}
+
+export function DemoTransformBody(props: GraphNodeRenderProps<DemoNodeData["transform"]>) {
+  return <Body {...props} title="Transform" subtitle={props.data.expression} intent="accent" />;
+}
+
+export function DemoSinkBody(props: GraphNodeRenderProps<DemoNodeData["sink"]>) {
+  return <Body {...props} title="Sink" subtitle={`→ ${props.data.target}`} intent="success" />;
+}
+
+const bodies = {
+  source: DemoSourceBody,
+  transform: DemoTransformBody,
+  sink: DemoSinkBody,
+} as const;
+
+/** The fixture schema with real bodies wired in. */
+export function demoGraphSchema() {
+  const shape = demoSchemaShape();
+  return createGraphSchema<DemoNodeData, BuiltinEdgeData>({
+    id: shape.id,
+    nodes: {
+      source: { ...shape.nodes.source, render: bodies.source },
+      transform: { ...shape.nodes.transform, render: bodies.transform },
+      sink: { ...shape.nodes.sink, render: bodies.sink },
+    },
+    edges: builtinEdgeKinds,
+    rules: defaultRules,
+  });
+}
+
+/**
+ * Design §13.2's control condition, re-exported so `@multiplatform.one/node-graph/demo`
+ * serves BOTH schemas from one subpath.
+ *
+ * The app's `'use dom'` entry is the only module that can hand a schema to the
+ * canvas — a `render` is a component and cannot cross the bridge — and an entry
+ * that had to reach two subpaths to register two schemas would be an entry with
+ * a second way to get one of them wrong. It is a re-export rather than a second
+ * export map entry for the same reason `NodeGraphDomInner` imports this file
+ * statically: another `import()` in the DOM subtree makes Metro emit a shared
+ * `__common` chunk, and `expo export`'s html serializer then dies while exiting
+ * 0 (design §13.2).
+ */
+export { DemoControlBody, demoControlSchema } from "./demoControlBody";
+
+export type { PortSpec };

package/src/react-flow/fixtures.ts

@@ -0,0 +1,185 @@
+/**
+ * One schema and one document, shared by the two task-1.11 specs and the story.
+ *
+ * A fixture module rather than a copy in each file: the story is the thing a
+ * reviewer looks at, and a story that drifts from what the specs assert is a
+ * story that proves nothing about the code under test.
+ *
+ * `.ts`, no JSX, and no component values — `NodeKindSpec.render` is filled in
+ * by whoever mounts these, because the model half of the package must stay
+ * importable without React (design §3.1).
+ */
+
+import type { GraphDocument, GraphSchema, PortSpec } from "../model/index";
+import { createGraphSchema, defaultRules } from "../model/index";
+import type { BuiltinEdgeData } from "../edges/edgeKinds";
+import { builtinEdgeKinds } from "../edges/edgeKinds";
+
+export type DemoNodeData = {
+  readonly source: { readonly table: string };
+  readonly transform: { readonly expression: string };
+  readonly sink: { readonly target: string };
+};
+
+const out = (id: string, label: string): PortSpec => ({
+  id,
+  side: "right",
+  direction: "out",
+  label,
+});
+const into = (id: string, label: string): PortSpec => ({
+  id,
+  side: "left",
+  direction: "in",
+  label,
+});
+
+/** A stand-in `render`. `demoGraphSchema()` in demoNodeBody.tsx swaps in the real bodies. */
+const noRender = (() => null) as unknown as never;
+
+/**
+ * The schema WITHOUT its `render` components.
+ *
+ * Split out so `demoNodeBody.tsx` can supply real bodies over the same
+ * measures, ports and intents the model-only specs use. A second copy of the
+ * kind table is a second thing to keep in step.
+ */
+/**
+ * The id the package's OWN demo schema registers under.
+ *
+ * A named constant rather than a literal in two places, because it is the one
+ * string that crosses the bridge: `NodeGraphDomInner` matches on it to register
+ * this schema inside the DOM bundle, where a story cannot reach. See the note
+ * there — a schema's `render` is a component and cannot be JSON, so the only
+ * way a canvas gets one is a module the DOM bundle itself imports.
+ */
+export const demoGraphSchemaId = "node-graph-demo";
+
+/**
+ * The id the plain-div CONTROL schema registers under.
+ *
+ * Design §13.2 asks for a control condition in every measurement session so the
+ * Tamagui cost is measured rather than carried over from the web's ~10%. The
+ * control lived in `bench/Perf200.stories.tsx` until the m6 device pass, and a
+ * story runs on the Hermes side: only `schemaId` crosses the bridge, so on
+ * device the canvas looked the id up, missed, and reported
+ * `render: no graph schema registered as "node-graph-demo-control"`. The
+ * control condition was therefore unmeasurable on every device.
+ *
+ * It is a constant here, beside the schema it names, for the same reason the
+ * demo id is: it is a string two realms have to agree on.
+ */
+export const demoControlSchemaId = `${demoGraphSchemaId}-control`;
+
+export function demoSchemaShape() {
+  return {
+    id: demoGraphSchemaId,
+    nodes: {
+      source: {
+        kind: "source" as const,
+        ports: [out("rows", "rows")],
+        defaultData: { table: "orders" },
+        measure: { width: 190, minHeight: 72 },
+      },
+      transform: {
+        kind: "transform" as const,
+        ports: [into("in", "rows"), out("ok", "ok"), out("err", "error")],
+        defaultData: { expression: "row => row" },
+        measure: { width: 190, minHeight: 72 },
+        intent: "accent",
+      },
+      sink: {
+        kind: "sink" as const,
+        ports: [into("in", "rows")],
+        defaultData: { target: "warehouse" },
+        // 240 on purpose: it is not a value the default 172/190/216 table can
+        // produce at any size stop, so a `measure` that fails to reach the
+        // painted node is visible rather than coincidentally right.
+        measure: { width: 240, minHeight: 72 },
+        intent: "success",
+      },
+    },
+  };
+}
+
+export function demoSchema(): GraphSchema<DemoNodeData, BuiltinEdgeData> {
+  const shape = demoSchemaShape();
+  return createGraphSchema<DemoNodeData, BuiltinEdgeData>({
+    id: shape.id,
+    nodes: {
+      source: { ...shape.nodes.source, render: noRender },
+      transform: { ...shape.nodes.transform, render: noRender },
+      sink: { ...shape.nodes.sink, render: noRender },
+    },
+    edges: builtinEdgeKinds,
+    rules: defaultRules,
+  });
+}
+
+type Doc = GraphDocument<DemoNodeData, BuiltinEdgeData>;
+
+/** Three nodes, one edge. Small enough that a failing assertion names a node. */
+export function demoDocument(): Doc {
+  return {
+    version: 1,
+    nodes: [
+      { id: "a", kind: "source", position: { x: 0, y: 0 }, data: { table: "orders" } },
+      {
+        id: "b",
+        kind: "transform",
+        position: { x: 260, y: 0 },
+        data: { expression: "row => row" },
+      },
+      { id: "c", kind: "sink", position: { x: 520, y: 0 }, data: { target: "warehouse" } },
+    ],
+    edges: [
+      {
+        id: "a->b",
+        kind: "flow",
+        source: { node: "a", port: "rows" },
+        target: { node: "b", port: "in" },
+        data: {},
+      },
+    ],
+  };
+}
+
+/**
+ * Twelve nodes and all four edge kinds — the `Main` story's graph, per design
+ * §12.1 ("the default editor, 12 nodes, all four edge kinds").
+ */
+export function demoDocumentLarge(count = 12): Doc {
+  const kinds = ["source", "transform", "sink"] as const;
+  const nodes: Doc["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,
+      position: { x: (index % 4) * 280, y: Math.floor(index / 4) * 200 },
+      data,
+    } as Doc["nodes"][number];
+  });
+
+  const edgeKinds = ["flow", "data", "error", "conditional"] as const;
+  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: edgeKinds[edges.length % edgeKinds.length],
+      source: { node: from.id, port: sourcePort },
+      target: { node: to.id, port: "in" },
+      data: {},
+    } as Doc["edges"][number]);
+  }
+  return { version: 1, nodes, edges };
+}