@multiplatform.one/node-graph 7.7.2

package/src/nodes/GraphNode.stories.tsx

@@ -0,0 +1,451 @@
+/**
+ * `NodeGraph/GraphNode` — the node alone, off canvas (design §12.1).
+ *
+ * Off canvas still means inside a `ReactFlowProvider`: `useUpdateNodeInternals`
+ * reads the React Flow store, and a node that cannot report a port change is
+ * not the node that ships. The provider is the whole canvas this story needs.
+ *
+ * `FontProof` is task 2.5: design 6.3's corrupted-first-family control, live.
+ */
+
+import { Preset, Surface, fontCategoryStacks } from "@multiplatform.one/theme";
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { type ReactNode, useEffect, useRef, useState } from "react";
+import { SizableText, Theme, XStack, YStack } from "tamagui";
+import { hasDomRealm } from "../native/DomOnlyStory";
+import { ReactFlowProvider } from "../react-flow/xy";
+import { GraphFaces } from "../theme/GraphFaces";
+import type { GraphFaceStatus } from "../theme/GraphFaces";
+import { corruptFirstFamily, probeRenderedFamily } from "../theme/faces";
+import type { FaceProbe } from "../theme/faces";
+import { GraphNode } from "./GraphNode";
+import type { GraphNodePort } from "./nodeMeasure";
+
+const oneIn: GraphNodePort[] = [{ id: "in", side: "left", direction: "in", label: "source" }];
+
+const inOut: GraphNodePort[] = [
+  { id: "in", side: "left", direction: "in", label: "records" },
+  { id: "out", side: "right", direction: "out", label: "result" },
+];
+
+const fourPorts: GraphNodePort[] = [
+  { id: "rows", side: "left", direction: "in", label: "rows" },
+  { id: "schema", side: "left", direction: "in", label: "schema" },
+  { id: "ok", side: "right", direction: "out", label: "ok" },
+  { id: "err", side: "right", direction: "out", label: "error" },
+];
+
+const meta: Meta<typeof GraphNode> = {
+  title: "NodeGraph/GraphNode",
+  component: GraphNode,
+  parameters: {
+    status: { type: "beta" },
+    docs: {
+      description: {
+        component:
+          "The Tamagui node body, resolved through the real useResolvedKnobs stack (Preset / Surface / Intent). Width rides the per-kind measure table rather than the control-height ladder; radius is CONTAINER-CAP so a corner never clips a child; the frame is never overflow:hidden, because handles overhang it. This is where the knob fuzz for MPO-191 runs.",
+      },
+    },
+  },
+  argTypes: {
+    title: { control: "text" },
+    subtitle: { control: "text" },
+    intent: { control: "select", options: [undefined, "accent", "error", "warning", "success"] },
+    selected: { control: "boolean" },
+    dragging: { control: "boolean" },
+    coarsePointer: {
+      control: "boolean",
+      description: "Touch surface — widens the port pitch to 44",
+    },
+    renderMode: { control: "inline-radio", options: ["detail", "overview"] },
+  },
+  decorators: [
+    (Story) => (
+      <ReactFlowProvider>
+        <YStack padding="$4">
+          <Story />
+        </YStack>
+      </ReactFlowProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof GraphNode>;
+
+export const Main: Story = {
+  args: {
+    id: "transform",
+    title: "Transform",
+    subtitle: "Maps each row through the mapping expression",
+    ports: inOut,
+  },
+};
+
+export const Intents: Story = {
+  render: () => (
+    <XStack gap="$5" flexWrap="wrap">
+      {[undefined, "accent", "error", "warning", "success"].map((intent) => (
+        <YStack key={intent ?? "default"} gap="$2">
+          <SizableText size="$2" opacity={0.6}>
+            {intent ?? "no intent"}
+          </SizableText>
+          <GraphNode
+            id={`intent-${intent ?? "default"}`}
+            title="Validate"
+            subtitle="Rejects rows that fail the schema"
+            intent={intent}
+            ports={inOut}
+          />
+        </YStack>
+      ))}
+    </XStack>
+  ),
+};
+
+export const Ports: Story = {
+  render: () => (
+    <XStack gap="$5" alignItems="flex-start" flexWrap="wrap">
+      {(
+        [
+          ["none", []],
+          ["one in", oneIn],
+          ["in and out", inOut],
+          ["four, two a side", fourPorts],
+        ] as const
+      ).map(([label, ports]) => (
+        <YStack key={label} gap="$2">
+          <SizableText size="$2" opacity={0.6}>
+            {label}
+          </SizableText>
+          <GraphNode id={`ports-${label}`} title="Join" ports={ports} />
+        </YStack>
+      ))}
+    </XStack>
+  ),
+};
+
+/**
+ * §7.1 H6 made visible. The magenta marker is positioned to overhang the
+ * frame the way a port's painted disc and its 44pt `::after` region will. If
+ * the frame ever becomes `overflow: hidden`, half of it disappears here before
+ * any spec runs.
+ */
+export const Overflow: Story = {
+  render: () => (
+    <XStack gap="$8" alignItems="flex-start">
+      {(["small", "medium", "large", "full"] as const).map((borderRadius) => (
+        <Preset key={borderRadius} cascade={false} overrides={{ borderRadius }}>
+          <YStack gap="$2">
+            <SizableText size="$2" opacity={0.6}>
+              borderRadius: {borderRadius}
+            </SizableText>
+            <GraphNode id={`overflow-${borderRadius}`} title="Overhang" ports={inOut}>
+              <YStack
+                position="absolute"
+                left={-10}
+                top={16}
+                width={20}
+                height={20}
+                borderRadius={9999}
+                backgroundColor="$color10"
+              />
+            </GraphNode>
+          </YStack>
+        </Preset>
+      ))}
+    </XStack>
+  ),
+};
+
+/**
+ * Seed `MPO-191-graphnode`, 3 combos, both schemes — the exact combos
+ * `node scripts/knob-fuzz.mjs MPO-191-graphnode 3` prints, so the verdicts
+ * posted on MPO-191 and this page are the same subject.
+ */
+const fuzzCombos = [
+  {
+    label: "combo 1",
+    knobs: {
+      fillStyle: "filled",
+      borderRadius: "medium",
+      borderWidth: "none",
+      elevation: "none",
+      space: "large",
+      size: "medium",
+      textAccent: "medium",
+      headingFont: "geometric",
+      bodyFont: "sans-serif",
+      fontWeight: "bold",
+      animation: "tooltip",
+    },
+  },
+  {
+    label: "combo 2",
+    knobs: {
+      fillStyle: "filled",
+      borderRadius: "none",
+      borderWidth: "none",
+      elevation: "small",
+      space: "small",
+      size: "small",
+      textAccent: "medium",
+      headingFont: "rounded",
+      bodyFont: "cursive",
+      fontWeight: "regular",
+      animation: "none",
+    },
+  },
+  {
+    label: "combo 3",
+    knobs: {
+      fillStyle: "filled",
+      borderRadius: "full",
+      borderWidth: "small",
+      elevation: "large",
+      space: "medium",
+      size: "large",
+      textAccent: "high",
+      headingFont: "mono",
+      bodyFont: "serif",
+      fontWeight: "bold",
+      animation: "bouncy",
+    },
+  },
+] as const;
+
+function FuzzColumn({ scheme, children }: { scheme: "light" | "dark"; children: ReactNode }) {
+  return (
+    <Theme name={scheme}>
+      <YStack gap="$4" padding="$4" backgroundColor="$background" borderRadius="$4">
+        <SizableText size="$2" opacity={0.6}>
+          {scheme}
+        </SizableText>
+        {children}
+      </YStack>
+    </Theme>
+  );
+}
+
+export const KnobFuzz: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Seed MPO-191-graphnode, 3 combos, light and dark. Measure the GraphNode FRAME against knob-laws.md § Radius › GraphNode frame (CONTAINER-CAP), § Size › GraphNode frame (remap to the measure table) and § Elevation › GraphNode frame (declared honour). Measuring an inset against the frame's row is the false FAIL the procedure warns about.",
+      },
+    },
+  },
+  render: () => (
+    <XStack gap="$5" alignItems="flex-start" flexWrap="wrap">
+      {(["light", "dark"] as const).map((scheme) => (
+        <FuzzColumn key={scheme} scheme={scheme}>
+          {fuzzCombos.map((combo) => (
+            <Preset key={combo.label} cascade={false} overrides={combo.knobs}>
+              <Surface size="medium" density="comfortable">
+                <YStack gap="$2">
+                  <SizableText size="$1" opacity={0.6}>
+                    {combo.label}
+                  </SizableText>
+                  <GraphNode
+                    id={`fuzz-${scheme}-${combo.label}`}
+                    title="Aggregate"
+                    subtitle="Groups rows by the key expression"
+                    ports={fourPorts}
+                  />
+                </YStack>
+              </Surface>
+            </Preset>
+          ))}
+        </FuzzColumn>
+      ))}
+    </XStack>
+  ),
+};
+
+// ── FontProof (task 2.5) ─────────────────────────────────────────────────────
+
+/**
+ * One probe row: what was measured, and whether the first family painted.
+ *
+ * Rendered as text on purpose. This story is read off a SCREENSHOT — on the
+ * iOS simulator and an Android emulator at tasks 2.7 and 2.8, where there is no
+ * console to open — so every number the control produces has to be legible in
+ * the picture.
+ */
+function ProbeRow({ label, probe }: { label: string; probe: FaceProbe | null }) {
+  if (!probe) {
+    return (
+      <SizableText size="$2" fontFamily="$mono">
+        {label}: measuring…
+      </SizableText>
+    );
+  }
+  const verdict = !probe.conclusive
+    ? "INCONCLUSIVE"
+    : probe.matched
+      ? "MATCHED — first family painted"
+      : "MISS — first family never painted";
+  return (
+    <YStack gap="$1">
+      <SizableText size="$2" fontFamily="$mono">
+        {label}: {verdict}
+      </SizableText>
+      <SizableText size="$1" fontFamily="$mono" opacity={0.7}>
+        stack {probe.widthStack.toFixed(2)}px · first-corrupted{" "}
+        {probe.widthFirstCorrupted.toFixed(2)}px
+      </SizableText>
+      <SizableText size="$1" fontFamily="$mono" opacity={0.5}>
+        {probe.stack}
+      </SizableText>
+    </YStack>
+  );
+}
+
+/**
+ * The corrupted-first-family control, live, with its own negative case beside
+ * it.
+ *
+ * Two targets, and the second is the point. A single MATCHED row proves nothing
+ * on its own — the gate's probe produced one of those while Inter had not
+ * rendered at all. So the story also probes a span whose first family is
+ * ALREADY absent, and shows the control reporting MISS for it. Two rows,
+ * opposite verdicts, same probe: that is the evidence.
+ *
+ * `assetUris` points at the URLs `apps/storybook` serves from
+ * `apps/storybook/public/fonts` (`staticDirs: ["../public"]`), so the web run
+ * exercises design §6.3's PRIMARY mechanism and the face table below says
+ * `asset` rather than `inline`. The preview head registers Inter from the same
+ * file, which is why the real cascade matches here even before `GraphFaces`
+ * mounts; the device runs at 2.7/2.8 are where the base64 path carries it
+ * alone.
+ */
+/**
+ * Whether this story is running somewhere the probe can run at all.
+ *
+ * A module constant, not a per-render check: it is the PLATFORM, and a value
+ * that could change between renders would put the hooks below in danger.
+ */
+/**
+ * The same check `DomOnlyStory` exports, imported rather than restated (task
+ * 6.8). It was declared here first, and a second copy is how two stories end up
+ * disagreeing about what "has a DOM" means.
+ */
+const hasDom = hasDomRealm;
+
+function FontProofPanel() {
+  const hostRef = useRef<HTMLDivElement | null>(null);
+  const [real, setReal] = useState<FaceProbe | null>(null);
+  const [absent, setAbsent] = useState<FaceProbe | null>(null);
+  const [statuses, setStatuses] = useState<readonly GraphFaceStatus[]>([]);
+
+  useEffect(() => {
+    if (!hasDom) return;
+    let live = true;
+    const run = async () => {
+      // The faces have to be resolved before a width means anything.
+      await document.fonts.ready;
+      if (!live) return;
+      const host = hostRef.current;
+      if (!host) return;
+      const title = host.querySelector("[data-graph-node-title]");
+      const control = host.querySelector("[data-font-proof-absent]");
+      if (title) setReal(probeRenderedFamily(title));
+      if (control) setAbsent(probeRenderedFamily(control));
+    };
+    void run();
+    return () => {
+      live = false;
+    };
+  }, []);
+
+  const controlStack = corruptFirstFamily(fontCategoryStacks["sans-serif"]);
+
+  /**
+   * NATIVE STOPS HERE, and it is not a limitation of the story — it is the
+   * measurement being meaningless (MPO-211).
+   *
+   * Two things below are DOM and nothing else: the `<span>` negative control,
+   * and `probeRenderedFamily`, which measures on a `<canvas>` context against
+   * an element's computed style. React Native answers a lowercase intrinsic it
+   * does not know with `View config getter callback for component "span" must
+   * be a function` and takes the whole tree down — measured on the iPhone 16e,
+   * where the Kitchen Sink showed a red box for this story.
+   *
+   * Guarding it would be pointless if the answer were simply unavailable on
+   * device, and it is not: the probe runs INSIDE the WebView, on the canvas's
+   * way to `ready`, and `NodeGraph/Diagnostics` → `Live` renders the result.
+   * That is the story AC-3's DOM half is read from, so this one says so
+   * instead of pretending.
+   */
+  if (!hasDom) {
+    return (
+      <YStack gap="$4" maxWidth={560}>
+        <GraphNode
+          id="font-proof"
+          title="Transform"
+          subtitle="Maps each row through the mapping expression"
+          ports={inOut}
+        />
+        <YStack gap="$2" padding="$3" backgroundColor="$background" borderRadius="$4">
+          <SizableText size="$2" fontFamily="$mono">
+            probe not run — there is no DOM here
+          </SizableText>
+          <SizableText size="$1" opacity={0.7}>
+            The node above is the real Tamagui body, resolved through the real knob stack. The
+            corrupted-first-family control needs a document and a canvas measurer, so on device it
+            runs inside the WebView instead and its result arrives on the canvas&apos;s ready event.
+          </SizableText>
+          <SizableText size="$1" opacity={0.7}>
+            Read it at NodeGraph → Diagnostics → Live.
+          </SizableText>
+        </YStack>
+      </YStack>
+    );
+  }
+
+  return (
+    <YStack ref={hostRef as never} gap="$4">
+      <GraphFaces
+        assetUris={{
+          "inter-400": "/fonts/inter-400.woff2",
+          "inter-700": "/fonts/inter-700.woff2",
+        }}
+        onStatus={setStatuses}
+      />
+      <GraphNode
+        id="font-proof"
+        title="Transform"
+        subtitle="Maps each row through the mapping expression"
+        ports={inOut}
+      />
+      {/* The negative control. Its first family is absent by construction. */}
+      <span data-font-proof-absent="" style={{ fontFamily: controlStack, fontSize: 16 }}>
+        AaBbGgQqRrWw0123456789
+      </span>
+      <YStack gap="$3" padding="$3" backgroundColor="$background" borderRadius="$4">
+        <ProbeRow label="GraphNode title (real cascade)" probe={real} />
+        <ProbeRow label="control, first family absent" probe={absent} />
+        <YStack gap="$1">
+          {statuses.map((status) => (
+            <SizableText key={status.id} size="$1" fontFamily="$mono" opacity={0.7}>
+              {status.id} · {status.family} {status.weight} · delivered by {status.source}
+            </SizableText>
+          ))}
+        </YStack>
+      </YStack>
+    </YStack>
+  );
+}
+
+export const FontProof: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Design 6.3's corrupted-first-family control, live. The first row probes the GraphNode title through the real knob cascade and must read MATCHED; the second probes a span whose first family is already absent and must read MISS. Equal widths mean the first family never rendered — the gate's probe compared against a wholly bogus family and could not tell that apart from the second family rendering. The face table says which of the two mechanisms of 6.3 delivered each face. WEB ONLY: the control is a span and a canvas measurer, so on device this story says where the on-device probe is read instead — NodeGraph → Diagnostics → Live, which renders the probe the canvas ran inside its own WebView.",
+      },
+    },
+  },
+  render: () => <FontProofPanel />,
+};

package/src/nodes/GraphNode.tsx

@@ -0,0 +1,240 @@
+/**
+ * The Tamagui node body.
+ *
+ * Knobs reach it through the REAL `useResolvedKnobs` — the resolver with its
+ * Preset / Surface / Intent context stack, not the pure functions — which is
+ * what MPO-191 AC-3 asks for. Every style comes from a whole `knobProps.*`
+ * fragment spread (AGENTS.md); nothing here cherry-picks a resolved token.
+ *
+ * Two things this component must NOT do, both from design §7.1:
+ *  - clip. The frame is never `overflow: hidden`, because handles sit at the
+ *    node edge under `translate(±50%)` and a clipping frame eats half the dot
+ *    and most of the 44pt hit region.
+ *  - re-measure the world on a knob flip. `useUpdateNodeInternals` fires for
+ *    ONE node when its own `ports` identity changes — a port added or removed
+ *    changes `handleBounds` with no size change for React Flow's per-node
+ *    ResizeObserver to see. A knob flip DOES change height, the observer does
+ *    catch that (measured, design §5), and firing 200 updates on top of it
+ *    would stack a second forced-layout storm on the observer's.
+ */
+
+import { type ReactNode, useEffect, useRef } from "react";
+import { useGraphNodeKnobs } from "../knobs/graphKnobs";
+import { SizableText, XStack, YStack } from "tamagui";
+import { useUpdateNodeInternals } from "../react-flow/xy";
+import { paintedPortSize } from "./handleGeometry";
+import { detailOpacity, isOverview } from "./lod";
+import type { GraphRenderMode } from "./lod";
+import {
+  containerRadiusPx,
+  type GraphNodeMeasure,
+  type GraphNodePort,
+  type GraphNodeSizeKnob,
+  graphNodeMinHeight,
+  graphNodeWidth,
+  portSpacing,
+} from "./nodeMeasure";
+
+export interface GraphNodeProps {
+  /** Node id. React Flow addresses `updateNodeInternals` by it. */
+  readonly id: string;
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly ports?: readonly GraphNodePort[];
+  /** Semantic intent — reaches the resolver, never a colour prop. */
+  readonly intent?: string;
+  readonly selected?: boolean;
+  readonly dragging?: boolean;
+  /** `NodeKindSpec.measure`; falls back to the per-kind default table. */
+  readonly measure?: Partial<GraphNodeMeasure>;
+  /**
+   * "overview" below `overviewZoom` (design §5). Children FADE, they never
+   * unmount, so the box keeps the same height in both modes and React Flow's
+   * ResizeObserver has nothing to chase.
+   */
+  readonly renderMode?: GraphRenderMode;
+  /** true on a touch surface — widens the port pitch to the press floor. */
+  readonly coarsePointer?: boolean;
+  /** Rendered inside each port row. Task 1.9 puts the painted disc here. */
+  readonly renderPort?: (port: GraphNodePort) => ReactNode;
+  readonly children?: ReactNode;
+}
+
+/**
+ * Fire `updateNodeInternals` for this node when, and only when, its `ports`
+ * array identity changes. Never on mount: React Flow measures a fresh node
+ * itself, so a mount-time call is a redundant forced layout.
+ */
+function usePortInternals(id: string, ports: readonly GraphNodePort[] | undefined) {
+  const updateNodeInternals = useUpdateNodeInternals();
+  const first = useRef(true);
+  useEffect(() => {
+    if (first.current) {
+      first.current = false;
+      return;
+    }
+    updateNodeInternals(id);
+  }, [id, ports, updateNodeInternals]);
+}
+
+export function GraphNode({
+  id,
+  title,
+  subtitle,
+  ports,
+  intent,
+  selected = false,
+  dragging = false,
+  measure,
+  renderMode = "detail",
+  coarsePointer = false,
+  renderPort,
+  children,
+}: GraphNodeProps) {
+  // `useGraphNodeKnobs`, not `useResolvedKnobs` directly: it is task 1.6's ONE
+  // node knob call site, so a §11 law gets added in one place rather than per
+  // node kind. It resolves through the same real Preset / Surface / Intent
+  // stack, which is what `KnobEnvelopeProvider` rebuilds inside the WebView —
+  // so this component needs no native branch (design §6.1).
+  const { knobProps, control } = useGraphNodeKnobs({ intent, selected, dragging });
+
+  usePortInternals(id, ports);
+
+  const size = knobProps.size as GraphNodeSizeKnob;
+  const portSpacingPx = portSpacing({ coarsePointer });
+  // The dot straddles the row's edge, so half of it lands inside the row. The
+  // label clears the whole diameter rather than the half it strictly needs, so
+  // the gutter still reads as a gutter at the `large` stop.
+  const portGutterPx = paintedPortSize(size);
+  const width = graphNodeWidth({ size, measure });
+  const minHeight = graphNodeMinHeight({ size, ports: ports ?? [], portSpacingPx, measure });
+  // The px the frame paints, read off the SAME fragment it is styled from.
+  const radiusPx = containerRadiusPx(knobProps.containerRadius.borderRadius);
+  const overview = isOverview(renderMode);
+  // ZERO, never `display: none` and never an unmount. Children at opacity 0
+  // are still laid out and still hold the box open, so the node's height is
+  // the same number in both modes and React Flow's per-node ResizeObserver has
+  // nothing to chase across a zoom tick. Design §5, and it is the invariant
+  // `lod.spec.tsx` exists for.
+  const fade = detailOpacity(renderMode);
+
+  return (
+    <YStack
+      data-graph-node={id}
+      data-graph-node-radius={String(radiusPx)}
+      data-graph-node-width={String(width)}
+      data-graph-node-render-mode={renderMode}
+      data-graph-node-port-spacing={String(portSpacingPx)}
+      {...knobProps.surface}
+      {...knobProps.containerRadius}
+      {...knobProps.panelPadding}
+      {...knobProps.gap}
+      {...knobProps.elevationChrome}
+      hoverStyle={{ ...control.hoverKnobProps }}
+      pressStyle={{ ...control.pressKnobProps }}
+      focusVisibleStyle={{ ...control.focusVisibleKnobProps }}
+      width={width}
+      minHeight={minHeight}
+      // The containing block for its own ports. React Flow positions every
+      // Handle absolutely, so a `static` frame hands them to whatever ancestor
+      // happens to be positioned — off canvas, that is the document, and the
+      // discs pile up in the page corner instead of on the node edge.
+      position="relative"
+      // §7.1 H6. Handles overhang the frame; a clipping node eats them.
+      overflow="visible"
+      opacity={dragging ? 0.85 : 1}
+      transition={knobProps.transition}
+    >
+      <XStack {...knobProps.gap} alignItems="center" justifyContent="space-between">
+        {/*
+          `label` ALONE, and deliberately not `{...knobProps.heading}` before
+          it. Measured in the MPO-191 knob fuzz: `label` carries
+          `fontFamily: bodyFontValue` (resolveKnobs.ts:648-652) and `heading`
+          carries the heading family, so spreading heading first and label
+          second made the title paint the BODY face while the source read as if
+          it painted the heading one. The rendered result was right — design §11
+          declares this ink honours `bodyFont` — but only by spread order, and a
+          reorder would have flipped a documented law silently. One fragment,
+          one law. `GraphNode.spec.tsx` pins that `headingFont` does not move it.
+        */}
+        <SizableText {...knobProps.label} numberOfLines={1} data-graph-node-title="">
+          {title}
+        </SizableText>
+        {selected ? <YStack data-graph-node-selected="" /> : null}
+      </XStack>
+
+      {subtitle ? (
+        <SizableText
+          {...knobProps.body}
+          {...knobProps.label}
+          numberOfLines={2}
+          // 0.75 is the subtitle's own de-emphasis in detail; overview
+          // multiplies it to zero rather than replacing it, so the two laws
+          // compose instead of one silently overriding the other.
+          opacity={0.75 * fade}
+        >
+          {subtitle}
+        </SizableText>
+      ) : null}
+
+      {ports?.length ? (
+        <YStack
+          data-graph-node-ports=""
+          gap={0}
+          opacity={fade}
+          // An invisible 44 px press target is a trap. The ports stay MOUNTED
+          // (the box depends on them) but stop taking a pointer while nothing
+          // is drawn there for the user to aim at.
+          pointerEvents={overview ? "none" : "auto"}
+        >
+          {ports.map((port) => (
+            <XStack
+              key={port.id}
+              data-graph-node-port-row={port.id}
+              data-graph-node-port-side={port.side}
+              height={portSpacingPx}
+              alignItems="center"
+              justifyContent={port.side === "right" ? "flex-end" : "flex-start"}
+              // Each row is the containing block for ITS OWN port. React Flow
+              // places a handle at `top: 50%` of the nearest positioned
+              // ancestor, so with only the frame positioned every left port on
+              // a six-port node lands on the same pixel — seen in the Crowded
+              // story before this line existed. Per-row makes the pitch real.
+              position="relative"
+              // The row is where the port's painted disc overhangs the frame.
+              overflow="visible"
+            >
+              {renderPort?.(port)}
+              <SizableText
+                {...knobProps.body}
+                {...knobProps.label}
+                numberOfLines={1}
+                paddingLeft={port.side === "right" ? 0 : portGutterPx}
+                paddingRight={port.side === "right" ? portGutterPx : 0}
+              >
+                {port.label ?? port.id}
+              </SizableText>
+            </XStack>
+          ))}
+        </YStack>
+      ) : null}
+
+      {/*
+        Wrapped, and the wrapper is present in BOTH modes. Rendering
+        `{children}` bare and switching it off in overview is what the previous
+        version did, and an unmount collapses the box — which is the one thing
+        design §5 forbids, because React Flow's observer then reports a new
+        height and every edge attached to this node moves.
+      */}
+      {children ? (
+        <YStack
+          data-graph-node-children=""
+          opacity={fade}
+          pointerEvents={overview ? "none" : "auto"}
+        >
+          {children}
+        </YStack>
+      ) : null}
+    </YStack>
+  );
+}