@multiplatform.one/node-graph 7.7.2

package/src/knobs/envelope.spec.tsx

@@ -0,0 +1,371 @@
+/**
+ * MPO-191 AC-3, mechanised.
+ *
+ * The claim is that a Tamagui node inside the WebView resolves knobs through
+ * the REAL stack — `<Preset>` / `<Surface>` / `IntentContext` /
+ * `useResolvedKnobs` — and lands on the same answer the host would. A
+ * screenshot cannot prove that; two trees and a deep-equal can.
+ *
+ * The comparison is against the ORIGINAL CONTEXT, not against a second
+ * envelope. Comparing envelope to envelope would pass for a knob that stops
+ * crossing entirely, because both sides would lose it together. This way any
+ * knob mpo adds later breaks this spec the day it is added, which is the point.
+ *
+ * The crossing is a real `JSON.stringify` / `JSON.parse`, so a value that
+ * cannot survive the bridge (an `undefined`, a function, a `Map`) fails here
+ * rather than on a phone.
+ */
+
+import type { ReactNode } from "react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import {
+  IntentContext,
+  Preset,
+  type PresetDefinition,
+  type Knobs,
+  type ResolvedKnobs,
+  Surface,
+  type SurfaceDensity,
+  type SurfaceSizeIntent,
+  defaultKnobs,
+  registerPreset,
+  useResolvedKnobs,
+} from "@multiplatform.one/theme";
+import { beforeAll, describe, expect, it } from "vitest";
+import {
+  type KnobEnvelope,
+  knobEnvelopeSchemaVersion,
+  parseKnobEnvelope,
+  serializeKnobEnvelope,
+  stableStringify,
+} from "./envelope";
+import { KnobEnvelopeProvider } from "./KnobEnvelopeProvider";
+import { useKnobEnvelope } from "./useKnobEnvelope";
+
+// ── The named preset, whose `intents` map is what `presetName` exists to carry ──
+
+/**
+ * Deliberately unlike `defaultIntents`. `defaultIntents.error` carries
+ * `textAccent: "high"` and component overrides for Button/Input only, so a
+ * GraphNode under it resolves with its base knobs; this one moves knobs a
+ * GraphNode actually reads. If `presetName` failed to cross, the rehydrated
+ * tree would silently fall back to `defaultIntents` and paint the wrong node.
+ */
+const graphFuzzPreset: PresetDefinition = {
+  theme: "" as PresetDefinition["theme"],
+  knobs: { ...defaultKnobs, borderRadius: "small", elevation: "none" },
+  intents: {
+    error: {
+      textAccent: "low",
+      GraphNode: { borderRadius: "full", elevation: "large", borderWidth: "large" },
+    },
+  },
+  tints: [],
+};
+
+beforeAll(() => {
+  registerPreset("graphFuzz", graphFuzzPreset);
+});
+
+// ── Seeded knob sweep ────────────────────────────────────────────────────────
+
+/** mulberry32 — a named, reproducible PRNG, so a failure is re-runnable. */
+function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function seedFrom(label: string): number {
+  let hash = 2166136261;
+  for (let index = 0; index < label.length; index += 1) {
+    hash ^= label.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0;
+}
+
+const knobVocabulary = {
+  fillStyle: ["filled", "outlined"],
+  borderRadius: ["none", "small", "medium", "large", "full"],
+  cornerSmoothing: ["round", "smooth"],
+  borderWidth: ["none", "small", "medium", "large"],
+  elevation: ["none", "small", "medium", "large"],
+  space: ["small", "medium", "large"],
+  size: ["small", "medium", "large"],
+  density: ["comfortable", "compact"],
+  textAccent: ["low", "medium", "high"],
+  headingFont: ["sans-serif", "serif", "mono", "slab", "rounded"],
+  bodyFont: ["sans-serif", "serif", "mono", "condensed"],
+  fontWeight: ["regular", "bold"],
+  pageTitleScale: ["moderate", "display"],
+  animation: ["none", "quick", "bouncy", "lazy", "snappy"],
+} as const;
+
+const surfaceSizes: readonly (SurfaceSizeIntent | undefined)[] = [
+  undefined,
+  "small",
+  "medium",
+  "large",
+];
+const surfaceDensities: readonly (SurfaceDensity | undefined)[] = [
+  undefined,
+  "compact",
+  "comfortable",
+];
+const intents: readonly (string | null)[] = [null, "accent", "error", "warning", "success"];
+
+interface Combo {
+  readonly knobs: Partial<Knobs>;
+  readonly surfaceSize: SurfaceSizeIntent | undefined;
+  readonly surfaceDensity: SurfaceDensity | undefined;
+  readonly intent: string | null;
+}
+
+function pick<T>(rand: () => number, values: readonly T[]): T {
+  return values[Math.floor(rand() * values.length)] as T;
+}
+
+function seededCombos(label: string, count: number): Combo[] {
+  const rand = mulberry32(seedFrom(label));
+  const combos: Combo[] = [];
+  for (let index = 0; index < count; index += 1) {
+    const knobs: Record<string, unknown> = {};
+    for (const [key, values] of Object.entries(knobVocabulary)) {
+      knobs[key] = pick(rand, values as readonly unknown[]);
+    }
+    combos.push({
+      knobs: knobs as Partial<Knobs>,
+      surfaceSize: pick(rand, surfaceSizes),
+      surfaceDensity: pick(rand, surfaceDensities),
+      intent: pick(rand, intents),
+    });
+  }
+  return combos;
+}
+
+// ── The crossing ─────────────────────────────────────────────────────────────
+
+interface Capture {
+  envelope?: KnobEnvelope;
+  resolved?: ResolvedKnobs;
+}
+
+function HostProbe({
+  capture,
+  presetName,
+  intent,
+}: {
+  capture: Capture;
+  presetName?: string;
+  intent?: string;
+}) {
+  capture.envelope = useKnobEnvelope({ presetName });
+  capture.resolved = useResolvedKnobs({ component: "GraphNode", intent });
+  return null;
+}
+
+function DomProbe({ capture, intent }: { capture: Capture; intent?: string }) {
+  capture.resolved = useResolvedKnobs({ component: "GraphNode", intent });
+  return null;
+}
+
+interface CrossOptions {
+  readonly knobs?: Partial<Knobs>;
+  readonly presetName?: string;
+  /** Passed to `useKnobEnvelope`; omit to prove the fallback to `defaultIntents`. */
+  readonly carryPresetName?: boolean;
+  readonly surfaceSize?: SurfaceSizeIntent;
+  readonly surfaceDensity?: SurfaceDensity;
+  readonly contextIntent?: string | null;
+  /** Explicit `useResolvedKnobs({ intent })` on both sides; omit to lean on context. */
+  readonly resolveIntent?: string;
+}
+
+interface Crossing {
+  readonly host: ResolvedKnobs;
+  readonly rehydrated: ResolvedKnobs;
+  readonly envelope: KnobEnvelope;
+}
+
+function cross(options: CrossOptions): Crossing {
+  const hostCapture: Capture = {};
+  const tree: ReactNode = (
+    <Preset preset={options.presetName} overrides={options.knobs}>
+      <Surface size={options.surfaceSize} density={options.surfaceDensity}>
+        <IntentContext.Provider value={options.contextIntent ?? null}>
+          <HostProbe
+            capture={hostCapture}
+            presetName={options.carryPresetName === false ? undefined : options.presetName}
+            intent={options.resolveIntent}
+          />
+        </IntentContext.Provider>
+      </Surface>
+    </Preset>
+  );
+  const hostRender = renderWithProviders(tree);
+  const host = hostCapture.resolved;
+  const envelope = hostCapture.envelope;
+  if (!host || !envelope) throw new Error("host tree never rendered the probe");
+  hostRender.unmount();
+
+  // The real bridge: text in, text out.
+  const crossed = parseKnobEnvelope(serializeKnobEnvelope(envelope));
+
+  const domCapture: Capture = {};
+  const domRender = renderWithProviders(
+    <KnobEnvelopeProvider envelope={crossed}>
+      <DomProbe capture={domCapture} intent={options.resolveIntent} />
+    </KnobEnvelopeProvider>,
+  );
+  const rehydrated = domCapture.resolved;
+  if (!rehydrated) throw new Error("rehydrated tree never rendered the probe");
+  domRender.unmount();
+
+  return { host, rehydrated, envelope: crossed };
+}
+
+// ── Specs ────────────────────────────────────────────────────────────────────
+
+describe("the knob envelope crosses the stack (MPO-191 AC-3)", () => {
+  it("resolves identically for the design's own host tree", () => {
+    const { host, rehydrated } = cross({
+      knobs: { borderRadius: "large", elevation: "medium", space: "large", animation: "bouncy" },
+      surfaceSize: "small",
+      surfaceDensity: "compact",
+      contextIntent: "error",
+      resolveIntent: "error",
+    });
+    expect(rehydrated).toEqual(host);
+  });
+
+  const combos = seededCombos("MPO-191-envelope", 24);
+
+  it.each(combos.map((combo, index) => [index, combo] as const))(
+    "resolves identically for seeded combo %i",
+    (_index, combo) => {
+      const { host, rehydrated } = cross({
+        knobs: combo.knobs,
+        surfaceSize: combo.surfaceSize,
+        surfaceDensity: combo.surfaceDensity,
+        contextIntent: combo.intent,
+        resolveIntent: combo.intent ?? undefined,
+      });
+      expect(rehydrated).toEqual(host);
+    },
+  );
+
+  it("resolves identically when the intent comes only from context", () => {
+    const { host, rehydrated } = cross({
+      knobs: { borderRadius: "full", textAccent: "low" },
+      surfaceSize: "medium",
+      contextIntent: "warning",
+    });
+    expect(rehydrated).toEqual(host);
+  });
+
+  it("carries a NAMED preset's own intents across, which is what presetName is for", () => {
+    const { host, rehydrated, envelope } = cross({
+      presetName: "graphFuzz",
+      surfaceSize: "large",
+      contextIntent: "error",
+      resolveIntent: "error",
+    });
+    expect(envelope.presetName).toBe("graphFuzz");
+    expect(rehydrated).toEqual(host);
+
+    // And the override is live rather than inert: "warning" has no entry in
+    // graphFuzz's intents map, so if the GraphNode override were doing nothing
+    // these two would be identical and the test above would prove nothing.
+    const control = cross({
+      presetName: "graphFuzz",
+      surfaceSize: "large",
+      contextIntent: "warning",
+      resolveIntent: "warning",
+    });
+    expect(host.knobProps.borderRadius).not.toEqual(control.host.knobProps.borderRadius);
+    expect(control.rehydrated).toEqual(control.host);
+  });
+
+  it("LOSES that intent override when presetName does not cross", () => {
+    const { host, rehydrated } = cross({
+      presetName: "graphFuzz",
+      carryPresetName: false,
+      surfaceSize: "large",
+      contextIntent: "error",
+      resolveIntent: "error",
+    });
+    // Falsification: without the name the rehydrated tree falls back to
+    // `defaultIntents`, which has no GraphNode override, so the two diverge.
+    expect(rehydrated).not.toEqual(host);
+  });
+});
+
+describe("the envelope itself", () => {
+  it("keeps `unset` surface axes instead of coercing them", () => {
+    const capture: Capture = {};
+    const render = renderWithProviders(
+      <Preset overrides={{ size: "large" }}>
+        <HostProbe capture={capture} />
+      </Preset>,
+    );
+    expect(capture.envelope?.surface).toEqual({ size: "unset", density: "unset" });
+    render.unmount();
+  });
+
+  it("completes optional knobs so JSON cannot drop them", () => {
+    const capture: Capture = {};
+    const render = renderWithProviders(
+      <Preset overrides={{ borderRadius: "small" }}>
+        <HostProbe capture={capture} />
+      </Preset>,
+    );
+    const knobs = capture.envelope?.knobs as Knobs;
+    expect(knobs.cornerSmoothing).toBeDefined();
+    expect(knobs.pageTitleScale).toBeDefined();
+    const roundTripped = JSON.parse(JSON.stringify(knobs)) as Knobs;
+    expect(Object.keys(roundTripped).sort()).toEqual(Object.keys(knobs).sort());
+    render.unmount();
+  });
+
+  it("bumps `revision` only when an input changes", () => {
+    const capture: Capture = {};
+    const render = renderWithProviders(
+      <Preset overrides={{ borderRadius: "small" }}>
+        <HostProbe capture={capture} />
+      </Preset>,
+    );
+    const first = capture.envelope as KnobEnvelope;
+    render.rerender(
+      <Preset overrides={{ borderRadius: "small" }}>
+        <HostProbe capture={capture} />
+      </Preset>,
+    );
+    expect(capture.envelope?.revision).toBe(first.revision);
+    expect(capture.envelope).toBe(first);
+    render.rerender(
+      <Preset overrides={{ borderRadius: "large" }}>
+        <HostProbe capture={capture} />
+      </Preset>,
+    );
+    expect(capture.envelope?.revision).toBe(first.revision + 1);
+    render.unmount();
+  });
+
+  it("refuses an envelope from a different schema version", () => {
+    expect(() =>
+      parseKnobEnvelope(JSON.stringify({ schemaVersion: knobEnvelopeSchemaVersion + 1 })),
+    ).toThrow(/schemaVersion/);
+  });
+
+  it("stringifies stably regardless of key insertion order", () => {
+    expect(stableStringify({ a: 1, b: { d: 2, c: 3 } })).toBe(
+      stableStringify({ b: { c: 3, d: 2 }, a: 1 }),
+    );
+    expect(stableStringify({ a: 1, b: undefined })).toBe(stableStringify({ a: 1 }));
+  });
+});

package/src/knobs/envelope.ts

@@ -0,0 +1,130 @@
+/**
+ * The knob ENVELOPE: the inputs to the knob stack, serialized.
+ *
+ * MPO-191 AC-3 asks for the real `useResolvedKnobs` with its Preset / Surface /
+ * Intent context stack, not the pure `resolveKnobs` function. React context does
+ * not cross a WebView, so what crosses is the INPUTS to that stack, never the
+ * resolved outputs — the DOM side rebuilds the stack out of the theme package's
+ * own components and resolves for itself. One code path: the web host is the
+ * degenerate case where the envelope never leaves the process.
+ *
+ * Design: docs/design/node-graph-editor.md section 6.1.
+ */
+
+import type { Animation, Knobs, SurfaceDensity, SurfaceSize } from "@multiplatform.one/theme";
+
+/**
+ * `unset` is part of the surface vocabulary, and dropping it changes what
+ * resolves.
+ *
+ * Design 6.1 types the envelope's surface as `{ size: SurfaceSize; density:
+ * SurfaceDensity }`, but `SurfaceContext`'s default is `{ size: "unset",
+ * density: "unset" }` (Surface.tsx:23-26) and `applySurfaceToKnobs`
+ * (useResolvedKnobs.ts:44-70) SKIPS an `unset` axis entirely. Coercing a host
+ * that sits under no `<Surface>` to "medium" would then step `knobs.size` down
+ * from `large`, and the rehydrated tree would resolve differently from the host
+ * it copied. So the envelope carries the third value.
+ */
+export type GraphSurfaceSize = SurfaceSize | "unset";
+export type GraphSurfaceDensity = SurfaceDensity | "unset";
+
+/** A face the DOM side has to register itself, because WKWebView cannot see an expo-font registration. */
+export interface GraphFontRef {
+  readonly family: string;
+  /** Asset URL or `data:` URI the WebView can fetch. */
+  readonly src: string;
+  readonly weight?: number;
+  readonly style?: "normal" | "italic";
+}
+
+/** Bumped when the envelope's shape changes in a way the DOM side must refuse. */
+export const knobEnvelopeSchemaVersion = 1;
+
+export interface KnobEnvelope {
+  readonly schemaVersion: typeof knobEnvelopeSchemaVersion;
+  /** Fully merged host knobs: preset.knobs + every Preset override in the chain + props.knobs. */
+  readonly knobs: Knobs;
+  /**
+   * REQUIRED when the host is under a NAMED preset. Without it the DOM side
+   * loses that preset's `intents` map: `useResolvedKnobs.ts:139` reads
+   * `presetCtx?.preset.intents[intent] ?? defaultIntents[intent]`, so a
+   * rehydrated tree with no name falls back to the defaults and a
+   * preset-specific intent override vanishes inside the WebView.
+   *
+   * It is a PROP, not a context read, because `PresetContextValue`
+   * (PresetContext.ts:7-10) carries `{ preset, overrides }` and no name — the
+   * name genuinely cannot be recovered from the context. The host passes the
+   * name it mounted `<Preset preset=…>` with, or `useTheme()`'s active preset.
+   */
+  readonly presetName?: string;
+  readonly intent: string | null;
+  readonly surface: { readonly size: GraphSurfaceSize; readonly density: GraphSurfaceDensity };
+  readonly scheme: "light" | "dark";
+  readonly themeName: string;
+  /**
+   * Resolved HOST-side. `usePrefersReducedMotion` (useResolvedKnobs.ts:22-41)
+   * reads `window.matchMedia`, which inside a WKWebView does not see the iOS
+   * setting.
+   */
+  readonly prefersReducedMotion: boolean;
+  /** The `--xy-*` / `--mpo-graph-*` layer, built host-side by `graphCssVars`. */
+  readonly vars: Readonly<Record<string, string>>;
+  readonly fonts: readonly GraphFontRef[];
+  readonly pixelRatio: number;
+  /** Bumped on any change above, so the DOM side memoises cheaply. */
+  readonly revision: number;
+}
+
+/** Everything except `revision` — two envelopes with the same identity are the same envelope. */
+export type KnobEnvelopeBody = Omit<KnobEnvelope, "revision">;
+
+/**
+ * Deterministic JSON. `JSON.stringify` preserves INSERTION order, and the host
+ * knobs are built by spreading, so `{...defaults, ...overrides}` and
+ * `{...overrides, ...defaults}` stringify differently while being the same
+ * object. A revision that bumps on key order alone would re-emit the whole var
+ * sheet on every unrelated render.
+ */
+export function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, item]) => item !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`);
+  return `{${entries.join(",")}}`;
+}
+
+/** Stable identity of an envelope's inputs, ignoring `revision`. */
+export function knobEnvelopeIdentity(body: KnobEnvelopeBody): string {
+  return stableStringify(body);
+}
+
+export function serializeKnobEnvelope(envelope: KnobEnvelope): string {
+  return JSON.stringify(envelope);
+}
+
+/**
+ * Parse an envelope that crossed the bridge.
+ *
+ * A version mismatch throws rather than rendering: a DOM bundle older than its
+ * host would otherwise resolve against a knob set it does not understand and
+ * paint something plausible but wrong, which is the failure that takes longest
+ * to find.
+ */
+export function parseKnobEnvelope(text: string): KnobEnvelope {
+  const parsed = JSON.parse(text) as KnobEnvelope;
+  if (parsed?.schemaVersion !== knobEnvelopeSchemaVersion) {
+    throw new Error(
+      `knob envelope schemaVersion ${String(parsed?.schemaVersion)} is not ${knobEnvelopeSchemaVersion} — ` +
+        "the DOM bundle and its native host are out of step; rebuild the app rather than rendering against a knob set it cannot read.",
+    );
+  }
+  return parsed;
+}
+
+/** `animation: "none"` forced in, idempotent against the resolver's own reduced-motion branch. */
+export function knobsForEnvelope(envelope: KnobEnvelope): Knobs {
+  if (!envelope.prefersReducedMotion) return envelope.knobs;
+  return { ...envelope.knobs, animation: "none" as Animation };
+}

package/src/knobs/envelopeTheme.spec.ts

@@ -0,0 +1,58 @@
+/**
+ * `envelope.themeName` does not cross the bridge (MPO-211 task 2.7).
+ *
+ * The host and the canvas are two different Tamagui BUILDS with two different
+ * theme tables — the app's config knows `light_blue`, the DOM bundle's knows
+ * whatever `@multiplatform.one/theme` created — and Tamagui throws
+ * `Missing theme.` rather than degrading on a name it cannot find. Measured on
+ * the iPhone 16e simulator: the canvas died at exactly that, caught by the DOM
+ * entry's error boundary and reported as `render: Missing theme.`
+ *
+ * Design 6.1 assumed the name crossed. It does not. `scheme` does, and is what
+ * the fallback keeps.
+ */
+
+import { describe, expect, it } from "vitest";
+import { resolveEnvelopeThemeName } from "./KnobEnvelopeProvider";
+
+const themes = { light: {}, dark: {}, light_blue: {} };
+
+describe("resolveEnvelopeThemeName", () => {
+  it("keeps a name the local table has", () => {
+    expect(resolveEnvelopeThemeName({ scheme: "light", themeName: "light_blue" }, themes)).toBe(
+      "light_blue",
+    );
+  });
+
+  /** The case that took the canvas down. */
+  it("falls back to the scheme when the local table has no such name", () => {
+    expect(resolveEnvelopeThemeName({ scheme: "dark", themeName: "dark_orange" }, themes)).toBe(
+      "dark",
+    );
+  });
+
+  it("inherits rather than guessing when the table has neither", () => {
+    expect(resolveEnvelopeThemeName({ scheme: "dark", themeName: "dark_orange" }, { a: {} })).toBe(
+      undefined,
+    );
+  });
+
+  /**
+   * On web there is no config, because the graph renders inside the app's own
+   * provider and that provider owns the table. Nothing changes for the platform
+   * that already worked.
+   */
+  it("passes the host's name straight through when no table is given", () => {
+    expect(resolveEnvelopeThemeName({ scheme: "light", themeName: "anything_at_all" })).toBe(
+      "anything_at_all",
+    );
+    expect(resolveEnvelopeThemeName({ scheme: "light", themeName: "" })).toBe(undefined);
+  });
+
+  /** An inherited `toString` is not a theme. */
+  it("does not treat a prototype key as a theme", () => {
+    expect(resolveEnvelopeThemeName({ scheme: "light", themeName: "toString" }, themes)).toBe(
+      "light",
+    );
+  });
+});

package/src/knobs/graphKnobs.ts

@@ -0,0 +1,36 @@
+/**
+ * The ONE place a graph node reads knobs.
+ *
+ * Nodes read knobs the way every other catalog component does — the real
+ * `useResolvedKnobs` with its Preset / Surface / Intent stack — and the
+ * GraphNode-specific laws in design section 11 (the width ladder, the
+ * CONTAINER-CAP radius, the port-spacing floor) land on top of the resolver's
+ * fragments in task 1.8. This module exists from task 1.6 so there is exactly
+ * one call site to add them to, rather than a hook per node kind.
+ *
+ * Consumers spread whole `knobProps.*` fragments (AGENTS.md "Knobs system") and
+ * never cherry-pick a resolved token.
+ */
+
+import { type ResolvedKnobs, useResolvedKnobs } from "@multiplatform.one/theme";
+
+export interface UseGraphNodeKnobsOptions {
+  /** A registered intent name — "accent" | "error" | "warning" | "success". */
+  readonly intent?: string;
+  readonly selected?: boolean;
+  readonly dragging?: boolean;
+}
+
+export interface GraphNodeKnobs extends ResolvedKnobs {
+  readonly selected: boolean;
+  readonly dragging: boolean;
+}
+
+export function useGraphNodeKnobs(options?: UseGraphNodeKnobsOptions): GraphNodeKnobs {
+  const resolved = useResolvedKnobs({ component: "GraphNode", intent: options?.intent });
+  return {
+    ...resolved,
+    selected: options?.selected ?? false,
+    dragging: options?.dragging ?? false,
+  };
+}