@multiplatform.one/node-graph 7.7.2

package/src/model/serialize.ts

@@ -0,0 +1,395 @@
+/**
+ * Serialization, design §4.6.
+ *
+ * Two properties carry the weight. `parseDocument` NEVER throws: a corrupt
+ * document renders an `EmptyState`, never a blank WebView, and on native there
+ * is no console to find the exception in. And the output is canonical —
+ * geometry rounded to 2 dp, document keys in a declared order, consumer payload
+ * keys sorted — so the same graph saved twice produces the same bytes and a
+ * change is a readable diff rather than a whole-file rewrite.
+ */
+
+import type {
+  DocumentProblem,
+  DocumentSchema,
+  EdgeKindDefs,
+  GraphDocument,
+  GraphEdgeOf,
+  GraphNodeOf,
+  JsonValue,
+  NodeKindDefs,
+  Result,
+  Size,
+  Viewport,
+  XY,
+} from "./document";
+
+export interface ParseOptions {
+  /**
+   * Drop nodes and edges whose kind the schema does not know, instead of
+   * refusing the document. For a read-only viewer that would rather show most
+   * of the graph than nothing. Edges left dangling by a dropped node are
+   * dropped with it — a graph with an edge pointing at nothing is not a
+   * partial render, it is a broken one.
+   */
+  readonly dropUnknownKinds?: boolean;
+}
+
+const documentVersion = 1;
+
+/**
+ * 2 dp via the decimal string, not `Math.round(v * 100) / 100`.
+ *
+ * The two disagree, and the disagreement is measured in `serialize.spec.ts`.
+ * 190.005 is stored as 190.00499999999999545; `toFixed` reads that and gives
+ * 190, while the multiply rounds a second time and gives 190.01. `toFixed`
+ * follows the number actually held, so the output depends only on the value and
+ * not on the arithmetic that produced it. Canonical output needs exactly that.
+ */
+function round2(value: number): number {
+  const rounded = Number(value.toFixed(2));
+  // -0 serializes as `-0` and compares equal to 0, so two structurally equal
+  // documents could differ by a sign that means nothing. Normalise it away.
+  return Object.is(rounded, -0) ? 0 : rounded;
+}
+
+function roundXY(value: XY): XY {
+  return { x: round2(value.x), y: round2(value.y) };
+}
+
+/** Consumer payloads have no declared key order, so canonical order is sorted. */
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value === null || typeof value !== "object") return value;
+  const source = value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const key of Object.keys(source).sort()) out[key] = canonical(source[key]);
+  return out;
+}
+
+/**
+ * Emits the document's own keys in a declared order and everything below them
+ * canonically. `JSON.stringify` walks insertion order, so the order below IS
+ * the format.
+ */
+export function serializeDocument<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  doc: GraphDocument<N, E>,
+): string {
+  const out: Record<string, unknown> = { version: doc.version };
+  out.nodes = doc.nodes.map((node) => {
+    const shaped: Record<string, unknown> = {
+      id: node.id,
+      kind: node.kind,
+      position: roundXY(node.position),
+      data: canonical(node.data),
+    };
+    if (node.size) {
+      shaped.size = { width: round2(node.size.width), height: round2(node.size.height) };
+    }
+    if (node.parent !== undefined) shaped.parent = node.parent;
+    if (node.locked !== undefined) shaped.locked = node.locked;
+    return shaped;
+  });
+  out.edges = doc.edges.map((edge) => {
+    const shaped: Record<string, unknown> = {
+      id: edge.id,
+      kind: edge.kind,
+      source: { node: edge.source.node, port: edge.source.port },
+      target: { node: edge.target.node, port: edge.target.port },
+      data: canonical(edge.data),
+    };
+    if (edge.label !== undefined) shaped.label = edge.label;
+    return shaped;
+  });
+  if (doc.viewport) {
+    out.viewport = {
+      x: round2(doc.viewport.x),
+      y: round2(doc.viewport.y),
+      zoom: round2(doc.viewport.zoom),
+    };
+  }
+  if (doc.meta) out.meta = canonical(doc.meta);
+  return JSON.stringify(out, null, 2);
+}
+
+interface Collector {
+  readonly problems: DocumentProblem[];
+}
+
+function fail(collector: Collector, path: string, code: string, message: string): void {
+  collector.problems.push({ path, code, message });
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readXY(value: unknown, path: string, collector: Collector): XY | undefined {
+  if (!isPlainObject(value)) {
+    fail(collector, path, "not-an-object", "expected an object with numeric x and y");
+    return undefined;
+  }
+  let ok = true;
+  for (const axis of ["x", "y"] as const) {
+    if (typeof value[axis] !== "number" || !Number.isFinite(value[axis])) {
+      fail(collector, `${path}.${axis}`, "not-a-finite-number", `expected a finite number`);
+      ok = false;
+    }
+  }
+  return ok ? { x: round2(value.x as number), y: round2(value.y as number) } : undefined;
+}
+
+function readSize(value: unknown, path: string, collector: Collector): Size | undefined {
+  if (!isPlainObject(value)) {
+    fail(collector, path, "not-an-object", "expected an object with numeric width and height");
+    return undefined;
+  }
+  let ok = true;
+  for (const axis of ["width", "height"] as const) {
+    if (typeof value[axis] !== "number" || !Number.isFinite(value[axis])) {
+      fail(collector, `${path}.${axis}`, "not-a-finite-number", `expected a finite number`);
+      ok = false;
+    }
+  }
+  return ok
+    ? { width: round2(value.width as number), height: round2(value.height as number) }
+    : undefined;
+}
+
+function readViewport(value: unknown, collector: Collector): Viewport | undefined {
+  const xy = readXY(value, "viewport", collector);
+  const zoom = isPlainObject(value) ? value.zoom : undefined;
+  if (typeof zoom !== "number" || !Number.isFinite(zoom)) {
+    fail(collector, "viewport.zoom", "not-a-finite-number", "expected a finite number");
+    return undefined;
+  }
+  return xy ? { ...xy, zoom: round2(zoom) } : undefined;
+}
+
+function readString(
+  source: Record<string, unknown>,
+  key: string,
+  path: string,
+  collector: Collector,
+): string | undefined {
+  const value = source[key];
+  if (typeof value !== "string" || value.length === 0) {
+    fail(collector, `${path}.${key}`, "not-a-non-empty-string", "expected a non-empty string");
+    return undefined;
+  }
+  return value;
+}
+
+function readPortRef(
+  value: unknown,
+  path: string,
+  collector: Collector,
+): { node: string; port: string } | undefined {
+  if (!isPlainObject(value)) {
+    fail(collector, path, "not-an-object", "expected { node, port }");
+    return undefined;
+  }
+  const node = readString(value, "node", path, collector);
+  const port = readString(value, "port", path, collector);
+  return node !== undefined && port !== undefined ? { node, port } : undefined;
+}
+
+/**
+ * Never throws. Every path out of this function is a `Result`, including the
+ * one where something below it does throw.
+ */
+export function parseDocument<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  raw: string | unknown,
+  schema: DocumentSchema<N, E>,
+  options: ParseOptions = {},
+): Result<GraphDocument<N, E>, readonly DocumentProblem[]> {
+  try {
+    return parseUnsafe<N, E>(raw, schema, options);
+  } catch (error) {
+    // A bug here must still not take the canvas down. It reports as a problem
+    // like any other and the caller renders an EmptyState.
+    return {
+      ok: false,
+      error: [
+        {
+          path: "",
+          code: "internal-error",
+          message: error instanceof Error ? error.message : String(error),
+        },
+      ],
+    };
+  }
+}
+
+function parseUnsafe<N extends NodeKindDefs, E extends EdgeKindDefs>(
+  raw: string | unknown,
+  schema: DocumentSchema<N, E>,
+  options: ParseOptions,
+): Result<GraphDocument<N, E>, readonly DocumentProblem[]> {
+  const collector: Collector = { problems: [] };
+  let value: unknown = raw;
+
+  if (typeof raw === "string") {
+    try {
+      value = JSON.parse(raw);
+    } catch (error) {
+      return {
+        ok: false,
+        error: [
+          {
+            path: "",
+            code: "invalid-json",
+            message: error instanceof Error ? error.message : "could not be parsed as JSON",
+          },
+        ],
+      };
+    }
+  }
+
+  if (!isPlainObject(value)) {
+    return {
+      ok: false,
+      error: [{ path: "", code: "not-an-object", message: "a document is a JSON object" }],
+    };
+  }
+
+  if (value.version !== documentVersion) {
+    fail(
+      collector,
+      "version",
+      "unsupported-version",
+      `expected version ${documentVersion}, got ${JSON.stringify(value.version)}`,
+    );
+  }
+
+  const nodeKinds = new Set(Object.keys(schema.nodes));
+  const edgeKinds = new Set(Object.keys(schema.edges));
+  const drop = options.dropUnknownKinds === true;
+
+  const nodes: GraphNodeOf<N>[] = [];
+  const nodeIds = new Set<string>();
+  if (!Array.isArray(value.nodes)) {
+    fail(collector, "nodes", "not-an-array", "expected an array of nodes");
+  } else {
+    value.nodes.forEach((entry, index) => {
+      const path = `nodes[${index}]`;
+      if (!isPlainObject(entry)) {
+        fail(collector, path, "not-an-object", "expected a node object");
+        return;
+      }
+      const id = readString(entry, "id", path, collector);
+      const kind = readString(entry, "kind", path, collector);
+      const position = readXY(entry.position, `${path}.position`, collector);
+      if (kind !== undefined && !nodeKinds.has(kind)) {
+        if (drop) return;
+        fail(
+          collector,
+          `${path}.kind`,
+          "unknown-node-kind",
+          `the schema has no node kind ${JSON.stringify(kind)}`,
+        );
+        return;
+      }
+      if (!("data" in entry)) {
+        fail(collector, `${path}.data`, "missing-field", "a node carries its kind's data");
+      }
+      if (id !== undefined && nodeIds.has(id)) {
+        fail(
+          collector,
+          `${path}.id`,
+          "duplicate-id",
+          `node id ${JSON.stringify(id)} is used twice`,
+        );
+      }
+      const size = "size" in entry ? readSize(entry.size, `${path}.size`, collector) : undefined;
+      if (id === undefined || kind === undefined || position === undefined) return;
+      nodeIds.add(id);
+      const node: Record<string, unknown> = { id, kind, position, data: entry.data };
+      if (size) node.size = size;
+      if (typeof entry.parent === "string") node.parent = entry.parent;
+      if (typeof entry.locked === "boolean") node.locked = entry.locked;
+      nodes.push(node as GraphNodeOf<N>);
+    });
+  }
+
+  const edges: GraphEdgeOf<E>[] = [];
+  const edgeIds = new Set<string>();
+  if (!Array.isArray(value.edges)) {
+    fail(collector, "edges", "not-an-array", "expected an array of edges");
+  } else {
+    value.edges.forEach((entry, index) => {
+      const path = `edges[${index}]`;
+      if (!isPlainObject(entry)) {
+        fail(collector, path, "not-an-object", "expected an edge object");
+        return;
+      }
+      const id = readString(entry, "id", path, collector);
+      const kind = readString(entry, "kind", path, collector);
+      const source = readPortRef(entry.source, `${path}.source`, collector);
+      const target = readPortRef(entry.target, `${path}.target`, collector);
+      if (kind !== undefined && !edgeKinds.has(kind)) {
+        if (drop) return;
+        fail(
+          collector,
+          `${path}.kind`,
+          "unknown-edge-kind",
+          `the schema has no edge kind ${JSON.stringify(kind)}`,
+        );
+        return;
+      }
+      if (!("data" in entry)) {
+        fail(collector, `${path}.data`, "missing-field", "an edge carries its kind's data");
+      }
+      if (id !== undefined && edgeIds.has(id)) {
+        fail(
+          collector,
+          `${path}.id`,
+          "duplicate-id",
+          `edge id ${JSON.stringify(id)} is used twice`,
+        );
+      }
+      for (const [end, ref] of [
+        ["source", source],
+        ["target", target],
+      ] as const) {
+        if (ref && !nodeIds.has(ref.node)) {
+          // Under dropUnknownKinds the node may have been dropped on purpose,
+          // so the edge goes with it instead of reporting.
+          if (drop) return;
+          fail(
+            collector,
+            `${path}.${end}.node`,
+            "dangling-edge-endpoint",
+            `no node ${JSON.stringify(ref.node)} in this document`,
+          );
+        }
+      }
+      if (id === undefined || kind === undefined || source === undefined || target === undefined) {
+        return;
+      }
+      edgeIds.add(id);
+      const edge: Record<string, unknown> = { id, kind, source, target, data: entry.data };
+      if (typeof entry.label === "string") edge.label = entry.label;
+      edges.push(edge as GraphEdgeOf<E>);
+    });
+  }
+
+  const viewport =
+    value.viewport === undefined ? undefined : readViewport(value.viewport, collector);
+
+  let meta: Readonly<Record<string, JsonValue>> | undefined;
+  if (value.meta !== undefined) {
+    if (!isPlainObject(value.meta)) {
+      fail(collector, "meta", "not-an-object", "meta is a JSON object");
+    } else {
+      meta = value.meta as Readonly<Record<string, JsonValue>>;
+    }
+  }
+
+  if (collector.problems.length > 0) return { ok: false, error: collector.problems };
+
+  const doc: Record<string, unknown> = { version: documentVersion, nodes, edges };
+  if (viewport) doc.viewport = viewport;
+  if (meta) doc.meta = meta;
+  return { ok: true, value: doc as unknown as GraphDocument<N, E> };
+}

package/src/native/DomOnlyStory.tsx

@@ -0,0 +1,72 @@
+/**
+ * What a DOM-only story draws on Hermes (milestone 6, task 6.8).
+ *
+ * Some stories in this package are about the DOM and nothing else: a `<span>`
+ * with a corrupted font stack, a `<style>` element, a React Flow `Handle` — a
+ * `div` — mounted OUTSIDE a canvas so the port can be seen off it. React Native
+ * answers a lowercase intrinsic it does not know with `View config getter
+ * callback for component "div" must be a function` and takes the whole tree
+ * down, so on the Kitchen Sink those stories were a red box. Measured on the
+ * iPhone 16e at MPO-211 and again on MPO-212's device pass.
+ *
+ * A red box is the worst of the three possible outcomes. It looks like a defect
+ * in the thing being demonstrated, it hides which stories actually work, and it
+ * teaches a reader nothing about where the answer IS. `FontProof` had already
+ * solved this by hand — it draws a sentence naming `NodeGraph → Diagnostics →
+ * Live`, where the probe that ran inside the WebView is rendered. This is that
+ * guard, extracted, so the next DOM-only story costs one decorator instead of
+ * twenty lines.
+ *
+ * `hasDomRealm` is a `document` check and not a `Platform.OS` check on purpose:
+ * `react-native` is an OPTIONAL peer of this package, and a story file must not
+ * be the thing that makes it required. It is also the more honest question —
+ * what these stories need is a DOM, and a DOM is exactly what is being tested
+ * for.
+ */
+
+import { SizableText, YStack } from "tamagui";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+
+/** True in a browser and inside the canvas's WebView; false on Hermes. */
+export const hasDomRealm = typeof globalThis.document !== "undefined";
+
+export interface DomOnlyStoryProps {
+  /** What this story needs a DOM for, in a clause. */
+  readonly needs: string;
+  /** Where the same thing CAN be read on device. A story title, not a URL. */
+  readonly readInstead?: string;
+}
+
+/**
+ * One line, not an error.
+ *
+ * Every style is a whole `knobProps.*` fragment spread (AGENTS.md); nothing here
+ * cherry-picks a resolved token and nothing here is a literal.
+ */
+export function DomOnlyStory({ needs, readInstead }: DomOnlyStoryProps) {
+  const { knobProps } = useResolvedKnobs();
+  return (
+    <YStack {...knobProps.gap} {...knobProps.panelPadding}>
+      <SizableText {...knobProps.body} {...knobProps.label}>
+        {`Web only — this story ${needs}, and there is no DOM on this side of the bridge.`}
+      </SizableText>
+      {readInstead ? (
+        <SizableText {...knobProps.body} {...knobProps.label} opacity={0.75}>
+          {`On device, read ${readInstead} instead.`}
+        </SizableText>
+      ) : null}
+    </YStack>
+  );
+}
+
+/**
+ * A Storybook decorator, so guarding a whole file is one line in its `meta`.
+ *
+ * It replaces the story rather than wrapping it: the point is that the tree
+ * below must never be constructed, and a wrapper that rendered its child and
+ * then apologised would still have thrown on the way.
+ */
+export function domOnlyStoryDecorator(props: DomOnlyStoryProps) {
+  return (Story: () => React.ReactElement) =>
+    hasDomRealm ? <Story /> : <DomOnlyStory {...props} />;
+}

package/src/native/GraphFallback.native.tsx

@@ -0,0 +1,123 @@
+/**
+ * What the user sees instead of a blank rectangle.
+ *
+ * Design 9.4 layer 4. The WebView failed, and the one thing worth knowing is
+ * HOW FAR it got: `script` means the bundle parsed and nothing else ran,
+ * `module` means the tree failed to evaluate, `flow` means React Flow mounted
+ * and never painted. Each sends a reader to a different layer, and a spinner
+ * that never resolves sends them nowhere.
+ *
+ * Built from `tamagui` and the real `useResolvedKnobs`, deliberately NOT from
+ * `@multiplatform.one/components`' `EmptyState`: components is an OPTIONAL
+ * peer, and a fallback that cannot render because its own dependency is absent
+ * is not a fallback. The rest of the native shell — toolbar, sheet, inspector —
+ * may use components freely.
+ *
+ * Every style comes from a whole `knobProps.*` fragment spread (AGENTS.md);
+ * nothing here cherry-picks a resolved token and nothing here is a literal.
+ */
+
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { Button, SizableText, YStack } from "tamagui";
+import type { BootStage } from "../dom/boot";
+
+export type GraphFallbackReason = "no-ready" | "no-dom-entry" | "module" | "render" | "runtime";
+
+export interface GraphFallbackProps {
+  /** Whether ANY event arrived from the canvas. A stage-less failure reads differently either way. */
+  readonly started?: boolean;
+  readonly reason: GraphFallbackReason;
+  /** The last stage the WebView stamped, or `null` if it never stamped one. */
+  readonly stage?: BootStage | null;
+  readonly message?: string;
+  /** The watchdog budget that ran out, so the reader knows what "did not finish" cost. */
+  readonly waitedMs?: number;
+  readonly onRetry?: () => void;
+}
+
+const reasonTitles: Record<GraphFallbackReason, string> = {
+  "no-ready": "The graph did not finish loading",
+  // Not a failure of the canvas — the canvas was never started. Design §9.3:
+  // the `'use dom'` entry is app-owned, and no app supplied one.
+  "no-dom-entry": "The graph has no DOM entry",
+  module: "The graph failed to load",
+  render: "The graph could not be drawn",
+  runtime: "The graph stopped",
+};
+
+/**
+ * `stage: null` gets its own sentence rather than the word "null".
+ *
+ * Nothing stamped at all means the script never executed, which is what a
+ * parse error looks like from out here — a different problem from stopping AT
+ * `script`, and the two must not read the same.
+ */
+export function graphFallbackDetail(
+  stage: BootStage | null | undefined,
+  started?: boolean,
+  reason?: GraphFallbackReason,
+  waitedMs?: number,
+): string {
+  // This one is not about how far boot got, because boot never began: no
+  // WebView was created at all. Saying "it never started" here would be true
+  // and useless, and would send the reader looking for a parse error.
+  if (reason === "no-dom-entry") {
+    return "No `'use dom'` entry was supplied, so no WebView was created.";
+  }
+  const waited = waitedMs ? ` after ${waitedMs} ms` : "";
+  if (stage) return `It reached "${stage}" and stopped there${waited}.`;
+  // Measured on the iPhone 16e simulator, and the reason this took an argument:
+  // the canvas reported a render error over the bridge — so it plainly HAD
+  // started — and this line still read "it never started", which sent the next
+  // reader looking for a parse error that was not there. The host only learns a
+  // stage from `ready`, so an error before that leaves the stage null while
+  // proving the script ran.
+  if (started) return `It started and reported a problem before it finished loading${waited}.`;
+  // WHY THIS NO LONGER NAMES A PARSE ERROR (MPO-211). It used to read "It never
+  // started, which usually means the bundle failed to parse." On emulator-5590,
+  // rebooted fresh, that is exactly what a reader saw — and nothing had failed
+  // to parse: the WebView was still starting, and Retry rendered the canvas at
+  // once. A watchdog cannot tell "dead" from "slow", so the line now says only
+  // what it knows and names the likelier of the two first.
+  return (
+    `Nothing came back from the WebView${waited}. ` +
+    "A slow cold start is the usual cause — Retry is often enough. " +
+    "A bundle that fails to parse looks identical from out here, and would " +
+    "still be silent on a retry."
+  );
+}
+
+export function GraphFallback({
+  message,
+  onRetry,
+  reason,
+  stage,
+  started,
+  waitedMs,
+}: GraphFallbackProps) {
+  const { knobProps } = useResolvedKnobs();
+
+  return (
+    <YStack
+      accessibilityRole="alert"
+      alignItems="center"
+      flex={1}
+      justifyContent="center"
+      {...knobProps.gap}
+      {...knobProps.panelPadding}
+    >
+      <SizableText {...knobProps.label} textAlign="center">
+        {reasonTitles[reason]}
+      </SizableText>
+      <SizableText {...knobProps.body} {...knobProps.label} textAlign="center">
+        {graphFallbackDetail(stage, started, reason, waitedMs)}
+      </SizableText>
+      {message ? (
+        <SizableText {...knobProps.body} {...knobProps.label} opacity={0.75} textAlign="center">
+          {message}
+        </SizableText>
+      ) : null}
+      {onRetry ? <Button onPress={onRetry}>Retry</Button> : null}
+    </YStack>
+  );
+}