@multiplatform.one/node-graph 7.7.2

package/src/dom/importGraph.spec.ts

@@ -0,0 +1,287 @@
+/**
+ * The DOM subtree's import boundary (design §9.4 layer 2, MPO-211 task 2.2).
+ *
+ * `import.meta` in a dependency is a PARSE error in the classic script a DOM
+ * component's WebView runs, so the script never executes, so no error boundary
+ * is reachable, so the canvas is a blank rectangle. The static ban in
+ * `scripts/verify-no-import-meta.mjs` catches the token; this catches the
+ * REACH — the canvas must not be able to arrive at `frappe-ui`, `frappe`,
+ * `utils`, `components` or anything else outside the allowed nine in the first
+ * place. Native chrome lives on the Hermes side and may use `components`
+ * freely; only the canvas is constrained.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const srcRoot = path.resolve(here, "..");
+const packageRoot = path.resolve(srcRoot, "..");
+
+/**
+ * design §9.4 layer 2. `@tamagui/*` is a prefix; everything else is exact.
+ *
+ * `expo` is the TENTH, and it was not in the design's list because the design
+ * wrote that list before the entry existed. `NodeGraphDom.ts` imports
+ * `useDOMImperativeHandle` from `expo/dom`, which is what makes the six
+ * imperative methods of §9.1 reachable from the native side at all. It cannot
+ * be dynamic — the hook has to run in the component body — and it cannot be
+ * dropped without dropping `fitView`/`relayout`/`zoomTo`/`centerOn`/
+ * `setSelection`/`exportViewport`. It is also the one external here that the
+ * DOM bundler itself provides rather than bundling, so it carries none of the
+ * reach this boundary exists to refuse. Widened deliberately, once, with the
+ * design amended to match; anything else still fails.
+ *
+ * `@xyflow/system` is the ELEVENTH, widened for task 3.4. It is not a new
+ * library in the bundle: `@xyflow/react` imports it internally, pins it
+ * exactly, and cannot run without it, so it was already inside every DOM
+ * bundle this boundary has ever passed. What changed is that `xy.ts` now names
+ * it, because `getHandlePosition` — the function that turns a handle's measured
+ * box into the point an edge is drawn to, and therefore the whole subject of
+ * design §7.1 H2 — is not re-exported by `@xyflow/react`. EXACT and not a
+ * `@xyflow/` prefix: react and system are the two halves of one library, and a
+ * prefix would silently admit whatever else that scope publishes next.
+ */
+const allowedExact = new Set([
+  "@dagrejs/dagre",
+  "@multiplatform.one/platform",
+  "@multiplatform.one/theme",
+  "@xyflow/react",
+  "@xyflow/system",
+  "expo",
+  "react",
+  "react-dom",
+  "tamagui",
+  "zustand",
+]);
+const allowedPrefixes = ["@tamagui/"];
+
+/** @returns the package specifier an external import belongs to, e.g. `@tamagui/web`. */
+function packageOf(specifier: string): string {
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]!;
+}
+
+function isAllowed(specifier: string): boolean {
+  const pkg = packageOf(specifier);
+  if (allowedExact.has(pkg)) return true;
+  return allowedPrefixes.some((prefix) => pkg.startsWith(prefix));
+}
+
+const importRe =
+  /(?:^|\n)\s*(?:import|export)\s[^;]*?from\s*["']([^"']+)["']|(?:^|\n)\s*import\s*["']([^"']+)["']/g;
+
+/** `await import("./x")` and `import("./x")`. Bare specifier only, no expressions. */
+const dynamicImportRe = /\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
+
+/**
+ * Every specifier that puts a module in the DOM BUNDLE — static and dynamic
+ * alike.
+ *
+ * The dynamic ones are not optional here, and reading them as optional is how
+ * this spec passed while guarding almost nothing. `NodeGraphDom.ts` reaches the
+ * entire canvas through one `await import("./NodeGraphDomInner")` (design §9.4
+ * layer 3), so a static-only walk visited 12 model and wire modules and never
+ * saw `NodeGraphDomInner`, `NodeGraphWeb`, `xy.ts` or anything they pull. The
+ * tree this boundary exists to constrain was the exact tree it could not see.
+ *
+ * Layer 3's dynamic import buys CATCHABILITY — a module-eval throw becomes a
+ * reportable `lastError.phase === "module"` instead of a fatal — and nothing
+ * else. Under Metro it compiles to a `require`, so the module is in the bundle
+ * either way, and an `import.meta` inside it is still a parse error that blanks
+ * the WebView before any boundary runs. Bundling is what this walk models, so
+ * bundling is what it must follow.
+ */
+function staticImports(source: string): string[] {
+  const found: string[] = [];
+  for (const match of source.matchAll(importRe)) {
+    const specifier = match[1] ?? match[2];
+    if (specifier) found.push(specifier);
+  }
+  for (const match of source.matchAll(dynamicImportRe)) {
+    const specifier = match[1];
+    if (specifier) found.push(specifier);
+  }
+  return found;
+}
+
+const extensions = [".ts", ".tsx", ".native.ts", ".native.tsx", ".js", ".jsx"];
+
+function resolveRelative(fromFile: string, specifier: string): string | null {
+  const base = path.resolve(path.dirname(fromFile), specifier);
+  for (const candidate of [
+    base,
+    ...extensions.map((ext) => `${base}${ext}`),
+    ...extensions.map((ext) => path.join(base, `index${ext}`)),
+  ]) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) return candidate;
+  }
+  return null;
+}
+
+interface Walk {
+  readonly externals: Map<string, string[]>;
+  readonly visited: string[];
+  readonly unresolved: string[];
+}
+
+/** Walks static imports transitively from `roots`, staying inside `src/`. */
+function walk(roots: readonly string[]): Walk {
+  const externals = new Map<string, string[]>();
+  const visited: string[] = [];
+  const unresolved: string[] = [];
+  const queue = [...roots];
+  const seen = new Set<string>(roots);
+  while (queue.length > 0) {
+    const file = queue.pop()!;
+    visited.push(file);
+    const source = fs.readFileSync(file, "utf8");
+    for (const specifier of staticImports(source)) {
+      if (specifier.startsWith(".")) {
+        const resolved = resolveRelative(file, specifier);
+        if (!resolved) {
+          unresolved.push(`${path.relative(packageRoot, file)} -> ${specifier}`);
+          continue;
+        }
+        if (seen.has(resolved)) continue;
+        seen.add(resolved);
+        queue.push(resolved);
+        continue;
+      }
+      if (specifier.startsWith("node:")) {
+        // A node: builtin inside the DOM subtree cannot run in a WebView at all,
+        // so it is a harder failure than a disallowed package, not a softer one.
+        const users = externals.get(specifier) ?? [];
+        users.push(path.relative(packageRoot, file));
+        externals.set(specifier, users);
+        continue;
+      }
+      const users = externals.get(packageOf(specifier)) ?? [];
+      users.push(path.relative(packageRoot, file));
+      externals.set(packageOf(specifier), users);
+    }
+  }
+  return { externals, visited, unresolved };
+}
+
+function filesUnder(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...filesUnder(full));
+      continue;
+    }
+    if (!/\.(tsx?|jsx?)$/.test(entry.name)) continue;
+    if (/\.(spec|test|stories)\./.test(entry.name)) continue;
+    out.push(full);
+  }
+  return out;
+}
+
+/** The entry `package.json` promises on every condition, per design §3.1. */
+function domEntry(): string {
+  const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+  const target = pkg.exports?.["./dom"];
+  const declared = typeof target === "string" ? target : target?.source;
+  return path.resolve(packageRoot, declared ?? "./src/dom/NodeGraphDom.ts");
+}
+
+describe("the DOM subtree's import boundary", () => {
+  it("keeps every external inside the allowed eleven of design 9.4", (ctx) => {
+    const entry = domEntry();
+    const roots = fs.existsSync(entry) ? [entry] : filesUnder(path.join(srcRoot, "dom"));
+    if (roots.length === 0) {
+      ctx.skip(
+        `nothing to walk yet: ${path.relative(packageRoot, entry)} lands in task 2.4 and src/dom holds no other module. This turns itself on the moment it does.`,
+      );
+      return;
+    }
+    const { externals, visited, unresolved } = walk(roots);
+    expect(unresolved, "every relative import inside src/ must resolve").toEqual([]);
+    // The walk has to ARRIVE at the canvas, or the rest of this test is theatre.
+    // These three sit behind the entry's dynamic import; a static-only walk
+    // reaches none of them and still reports green.
+    const relative = visited.map((file) => path.relative(packageRoot, file));
+    for (const required of [
+      // The shell is the entry's only import, and the canvas hangs off it. If
+      // the walk stopped at the directive it would guard one `createElement`.
+      "src/dom/NodeGraphDomShell.ts",
+      "src/dom/NodeGraphDomInner.tsx",
+      "src/react-flow/NodeGraphWeb.tsx",
+      "src/react-flow/xy.ts",
+    ]) {
+      expect(relative, `the walk must reach ${required}`).toContain(required);
+    }
+    const refused = [...externals.entries()].filter(([specifier]) => !isAllowed(specifier));
+    expect(
+      refused.map(([specifier, users]) => `${specifier} (from ${users.join(", ")})`),
+      "only @multiplatform.one/theme, @multiplatform.one/platform, tamagui, @tamagui/*, @xyflow/react, @xyflow/system, react, react-dom, @dagrejs/dagre, zustand and expo/dom may be reached from the DOM entry",
+    ).toEqual([]);
+  });
+
+  it("refuses a reach into @multiplatform.one/frappe-ui", () => {
+    // The falsification, run as a spec instead of by hand, so it cannot rot:
+    // the walker is pointed at a real module that reaches frappe-ui.
+    expect(isAllowed("@multiplatform.one/frappe-ui")).toBe(false);
+    expect(isAllowed("@multiplatform.one/frappe-ui/dist/x")).toBe(false);
+    for (const refused of [
+      "@multiplatform.one/components",
+      "@multiplatform.one/forms",
+      "@multiplatform.one/frappe",
+      "@multiplatform.one/backoffice",
+      "@multiplatform.one/rich-text",
+      "@multiplatform.one/utils",
+    ]) {
+      expect(isAllowed(refused), `${refused} must be refused`).toBe(false);
+    }
+  });
+
+  it("allows exactly the eleven, and @tamagui by prefix", () => {
+    for (const allowed of [
+      "@multiplatform.one/theme",
+      "@multiplatform.one/platform",
+      "tamagui",
+      "@tamagui/web",
+      "@tamagui/core",
+      "@xyflow/react",
+      "@xyflow/system",
+      "react",
+      "react-dom",
+      "react/jsx-runtime",
+      "@dagrejs/dagre",
+      "zustand",
+      "zustand/middleware",
+      "expo/dom",
+    ]) {
+      expect(isAllowed(allowed), `${allowed} must be allowed`).toBe(true);
+    }
+    // The widening is `expo` and nothing near it. A sibling Expo package that
+    // WOULD pull real code into the bundle stays refused.
+    for (const refused of ["expo-haptics", "expo-font", "expo-asset", "expo-router"]) {
+      expect(isAllowed(refused), `${refused} must be refused`).toBe(false);
+    }
+    // `@xyflow/system` is EXACT, not a prefix widening. Whatever that scope
+    // publishes next does not ride in on it.
+    for (const refused of ["@xyflow/svelte", "@xyflow/minimap"]) {
+      expect(isAllowed(refused), `${refused} must be refused`).toBe(false);
+    }
+  });
+
+  it("walks transitively, not one level", () => {
+    // Proven on the package's own tree: src/index.ts reaches @xyflow/react only
+    // through src/react-flow/xy.ts, so a one-level walk would miss it.
+    const { externals, visited } = walk([path.join(srcRoot, "index.ts")]);
+    expect(visited.length).toBeGreaterThan(3);
+    expect(externals.has("@xyflow/react")).toBe(true);
+    expect(
+      staticImports(fs.readFileSync(path.join(srcRoot, "index.ts"), "utf8")).some((s) =>
+        s.startsWith("@xyflow"),
+      ),
+      "src/index.ts must not import @xyflow directly, or this proves nothing",
+    ).toBe(false);
+  });
+});

package/src/dom/schemaRegistry.spec.tsx

@@ -0,0 +1,182 @@
+/**
+ * The m6 device pass's first defect: an entry that could supply ONE schema.
+ *
+ * `render: no graph schema registered as "node-graph-demo-control"` on the
+ * iPhone 16e, with a canvas that painted nothing. Only `schemaId` crosses the
+ * bridge — a `render` is a `ComponentType` and cannot be JSON — so the schema
+ * has to be resolved inside the DOM bundle, and the entry could hand the shell
+ * exactly one. Design §13.2 mandates the plain-div control condition in every
+ * measurement session, so one schema per entry meant the Tamagui cost on device
+ * stayed carried over from web rather than measured.
+ *
+ * These are the resolution rules, stated as behaviour rather than as a shape:
+ * the list is keyed BY ID, a non-matching schema is never substituted, a miss
+ * still reports what is missing, and the process-wide registry still wins so the
+ * two mechanisms compose.
+ *
+ * `NodeGraphDomInner` is rendered directly rather than through the shell: the
+ * shell reaches the inner tree through a dynamic `import()` and mounts
+ * `expo/dom`, and neither is what is under test here.
+ */
+
+import { cleanup, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { knobEnvelopeSchemaVersion } from "../knobs/envelope";
+import { clearGraphSchemas, registerGraphSchema } from "../model/index";
+import type { GraphSchema } from "../model/index";
+import { demoControlSchema } from "../react-flow/demoControlBody";
+import { demoGraphSchema } from "../react-flow/demoNodeBody";
+import { demoControlSchemaId, demoGraphSchemaId } from "../react-flow/fixtures";
+import { NodeGraphDomInner } from "./NodeGraphDomInner";
+import type { GraphCommands } from "./NodeGraphDomShell";
+import { decodeGraphEvent } from "./wire";
+import type { GraphEventWire } from "./wire";
+
+afterEach(() => {
+  cleanup();
+  clearGraphSchemas();
+});
+
+type AnySchema = GraphSchema<never, never>;
+
+/**
+ * The same erasure `registerGraphSchema` and the shell both perform.
+ *
+ * A schema's type parameters describe the app's own node data, and the registry
+ * is keyed by a string: the erasure happens once at that boundary in the
+ * product code, and once here so the spec crosses it the same way.
+ */
+function erased(schema: unknown): AnySchema {
+  return schema as AnySchema;
+}
+
+const envelopeJson = JSON.stringify({
+  schemaVersion: knobEnvelopeSchemaVersion,
+  knobs: {},
+  intent: null,
+  surface: { size: "md", density: "comfortable" },
+  scheme: "light",
+  themeName: "light",
+  prefersReducedMotion: true,
+  vars: {},
+  fonts: [],
+  pixelRatio: 1,
+  revision: 1,
+});
+
+/** One node of the demo schema's own `source` kind, so both schemas accept it. */
+const documentJson = JSON.stringify({
+  version: 1,
+  nodes: [{ id: "n0", kind: "source", position: { x: 0, y: 0 }, data: { table: "orders" } }],
+  edges: [],
+});
+
+function mount(schemaId: string, realm: { schema?: AnySchema; schemas?: readonly AnySchema[] }) {
+  const events: GraphEventWire[] = [];
+  const commands: { current: GraphCommands | null } = { current: null };
+  render(
+    <NodeGraphDomInner
+      commands={commands}
+      documentJson={documentJson}
+      envelopeJson={envelopeJson}
+      onEvent={async (json) => {
+        events.push(decodeGraphEvent(json));
+      }}
+      optionsJson="{}"
+      rev={1}
+      schema={realm.schema as never}
+      schemas={realm.schemas as never}
+      schemaId={schemaId}
+    />,
+  );
+  return {
+    events,
+    /** The `{ t: "error", phase: "render" }` message, or null. */
+    problem: () => {
+      const failure = events.find((event) => event.t === "error" && event.phase === "render");
+      return failure?.t === "error" ? failure.message : null;
+    },
+  };
+}
+
+describe("the DOM entry's schema registry", () => {
+  it("resolves the CONTROL schema when the entry registered both", async () => {
+    const harness = mount(demoControlSchemaId, {
+      schemas: [erased(demoGraphSchema()), erased(demoControlSchema())],
+    });
+    await waitFor(() => expect(harness.events.length).toBeGreaterThan(0));
+    // `null` is the whole assertion: the m6 device defect WAS this string.
+    expect(harness.problem(), "no graph schema registered as …").toBeNull();
+  });
+
+  it("resolves the DEMO schema from the same list — one entry, two canvases", async () => {
+    const harness = mount(demoGraphSchemaId, {
+      schemas: [erased(demoGraphSchema()), erased(demoControlSchema())],
+    });
+    await waitFor(() => expect(harness.events.length).toBeGreaterThan(0));
+    expect(harness.problem()).toBeNull();
+  });
+
+  /**
+   * The rule that makes the list safe. Taking "the first one" would paint the
+   * wrong node bodies and report nothing at all, which is a debugging session
+   * with no thread to pull; a refusal that names the missing id is one line.
+   */
+  it("never substitutes a schema whose id does not match", async () => {
+    const harness = mount("node-graph-something-else", {
+      schemas: [erased(demoGraphSchema()), erased(demoControlSchema())],
+    });
+    await waitFor(() => expect(harness.problem()).not.toBeNull());
+    expect(harness.problem()).toMatch(/no graph schema registered as "node-graph-something-else"/);
+  });
+
+  /** And the refusal names the mechanism that would have fixed it. */
+  it("names `schemas` in the refusal, because that is the fix for more than one", async () => {
+    const harness = mount("node-graph-absent", { schema: erased(demoGraphSchema()) });
+    await waitFor(() => expect(harness.problem()).not.toBeNull());
+    expect(harness.problem()).toMatch(/schemas/);
+  });
+
+  /**
+   * The two mechanisms compose. An app that would rather import a registration
+   * module than thread a prop still wins, so adding `schemas` took nothing
+   * away.
+   */
+  it("still prefers the process-wide registry over the entry's list", async () => {
+    const registered = { ...demoControlSchema(), nodes: { ...demoControlSchema().nodes } };
+    const render_ = vi.fn(() => null);
+    registerGraphSchema({
+      ...registered,
+      nodes: {
+        ...registered.nodes,
+        source: { ...registered.nodes.source, render: render_ as never },
+      },
+    } as never);
+    const harness = mount(demoControlSchemaId, {
+      schemas: [erased(demoControlSchema())],
+    });
+    await waitFor(() => expect(render_).toHaveBeenCalled());
+    expect(harness.problem()).toBeNull();
+  });
+});
+
+describe("the control schema", () => {
+  /**
+   * The id is the one string two realms have to agree on. A rename on one side
+   * is the exact failure this whole commit exists to fix, and it is silent.
+   */
+  it("registers under the id the constant names", () => {
+    expect(demoControlSchema().id).toBe(demoControlSchemaId);
+    expect(demoControlSchemaId).toBe("node-graph-demo-control");
+  });
+
+  /** Same geometry as the subject, or the two cells are two experiments. */
+  it("carries the demo schema's measures, so the delta is the node body alone", () => {
+    const control = demoControlSchema();
+    const demo = demoGraphSchema();
+    for (const kind of ["source", "transform", "sink"] as const) {
+      expect(control.nodes[kind].measure).toEqual(demo.nodes[kind].measure);
+      expect(control.nodes[kind].ports).toEqual(demo.nodes[kind].ports);
+    }
+  });
+});