@multiplatform.one/node-graph 7.7.2

package/src/layout/structuredCloneShim.spec.ts

@@ -0,0 +1,103 @@
+/**
+ * The shim dagre needs on Hermes and on a pre-15.4 WKWebView.
+ *
+ * `layout.spec.ts` proves the ENGINE works; these cases prove the shim is a
+ * real structural clone rather than a shallow copy that happens to satisfy
+ * dagre today, and that it never shadows a platform implementation.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cloneStructured, ensureStructuredClone } from "./structuredCloneShim";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("cloneStructured", () => {
+  it("returns primitives unchanged", () => {
+    for (const value of [1, "a", true, null, undefined, 0, Number.NaN]) {
+      expect(Object.is(cloneStructured(value), value)).toBe(true);
+    }
+  });
+
+  it("deep-copies a nested plain object rather than sharing it", () => {
+    const source = { a: { b: { c: 1 } }, list: [1, { d: 2 }] };
+    const copy = cloneStructured(source);
+    expect(copy).toEqual(source);
+    expect(copy.a).not.toBe(source.a);
+    expect(copy.list[1]).not.toBe(source.list[1]);
+    copy.a.b.c = 99;
+    expect(source.a.b.c).toBe(1);
+  });
+
+  it("copies the shape dagre actually clones: an id → x map", () => {
+    const positions = { n0: 12.5, n1: 44, n2: -3 };
+    const copy = cloneStructured(positions);
+    copy.n0 = 0;
+    expect(positions.n0).toBe(12.5);
+  });
+
+  it("preserves cycles instead of recursing forever", () => {
+    const source: { self?: unknown; n: number } = { n: 1 };
+    source.self = source;
+    const copy = cloneStructured(source);
+    expect(copy.self).toBe(copy);
+    expect(copy.n).toBe(1);
+  });
+
+  it("handles Map, Set, Date and RegExp", () => {
+    const source = {
+      map: new Map([["k", { v: 1 }]]),
+      set: new Set([1, 2]),
+      date: new Date(1_700_000_000_000),
+      re: /ab+c/gi,
+    };
+    const copy = cloneStructured(source);
+    expect(copy.map.get("k")).toEqual({ v: 1 });
+    expect(copy.map.get("k")).not.toBe(source.map.get("k"));
+    expect([...copy.set]).toEqual([1, 2]);
+    expect(copy.date.getTime()).toBe(1_700_000_000_000);
+    expect(copy.date).not.toBe(source.date);
+    expect(copy.re.source).toBe("ab+c");
+    expect(copy.re.flags).toBe("gi");
+  });
+
+  it("refuses a function rather than inventing a shallow copy", () => {
+    expect(() => cloneStructured(() => 1)).toThrow(TypeError);
+    expect(() => cloneStructured({ fn: () => 1 })).toThrow(TypeError);
+  });
+
+  it("refuses a class instance, matching DataCloneError's spirit", () => {
+    class Thing {
+      value = 1;
+    }
+    expect(() => cloneStructured(new Thing())).toThrow(/could not be cloned/);
+  });
+});
+
+describe("ensureStructuredClone", () => {
+  it("does not shadow a platform implementation", () => {
+    const platform = vi.fn((value: unknown) => value);
+    vi.stubGlobal("structuredClone", platform);
+    ensureStructuredClone();
+    expect(globalThis.structuredClone).toBe(platform);
+  });
+
+  it("installs the shim when the global is absent — the Hermes case", () => {
+    vi.stubGlobal("structuredClone", undefined);
+    ensureStructuredClone();
+    expect(typeof globalThis.structuredClone).toBe("function");
+    const source = { a: { b: 1 } };
+    const copy = globalThis.structuredClone(source);
+    expect(copy).toEqual(source);
+    expect(copy.a).not.toBe(source.a);
+  });
+
+  it("is idempotent", () => {
+    vi.stubGlobal("structuredClone", undefined);
+    ensureStructuredClone();
+    const first = globalThis.structuredClone;
+    ensureStructuredClone();
+    expect(globalThis.structuredClone).toBe(first);
+  });
+});

package/src/layout/structuredCloneShim.ts

@@ -0,0 +1,106 @@
+/**
+ * A guarded `structuredClone`, because dagre needs one and two of this
+ * package's three layout realms do not have it.
+ *
+ * FOUND BY RUNNING THE ARTEFACT, not by reading a changelog.
+ * `worker.generated.spec.ts` evaluates the bundled worker in a synthetic
+ * worker scope and drives a real layout through it; the first run came back
+ * `{"t":"error","message":"structuredClone is not defined"}`. dagre 3.1.1 calls
+ * it twice — once in `graphlib`'s JSON writer, and once on the POSITIONING hot
+ * path (`positionX`'s balance step), which every `layout()` call reaches.
+ *
+ * Where it is missing:
+ *
+ *  - **Hermes.** React Native 0.83.2 ships an implementation at
+ *    `src/private/webapis/structuredClone/structuredClone.js` and installs it
+ *    as a global from nowhere — nothing in `Libraries/Core` imports it. So the
+ *    `hermes-inline` runner, which design §8 makes a first-class runner and
+ *    not a fallback, would throw on the first tidy on device. That is the
+ *    failure this file exists to prevent, and it is exactly the kind that a
+ *    green web suite hides.
+ *  - **Older WebViews.** `structuredClone` is Safari 15.4 / iOS 15.4 and
+ *    Chrome 98. A WKWebView below that parses the worker fine and dies on the
+ *    first layout, which is the worst shape of failure this package has.
+ *
+ * WHAT IT CLONES. Only what dagre asks of it: plain objects, arrays, `Map`,
+ * `Set`, `Date`, `RegExp` and primitives, with cycles preserved. Not transfer
+ * lists, not `ArrayBuffer`, not `Blob`, not `Error`. A value outside that set
+ * throws, the way the real algorithm throws `DataCloneError` — inventing a
+ * silent shallow copy for a case dagre never produces would be a worse lie
+ * than a loud refusal.
+ *
+ * It installs on `globalThis` ONLY when the global is absent, so a real engine
+ * implementation always wins and nothing here shadows the platform.
+ */
+
+type CloneCache = Map<unknown, unknown>;
+
+function cloneInto(value: unknown, seen: CloneCache): unknown {
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "function") {
+      throw new TypeError("structuredClone: a function could not be cloned.");
+    }
+    return value;
+  }
+  const cached = seen.get(value);
+  if (cached !== undefined) return cached;
+
+  if (value instanceof Date) return new Date(value.getTime());
+  if (value instanceof RegExp) return new RegExp(value.source, value.flags);
+
+  if (Array.isArray(value)) {
+    const out: unknown[] = Array.from({ length: value.length });
+    seen.set(value, out);
+    for (let index = 0; index < value.length; index += 1) {
+      out[index] = cloneInto(value[index], seen);
+    }
+    return out;
+  }
+
+  if (value instanceof Map) {
+    const out = new Map<unknown, unknown>();
+    seen.set(value, out);
+    for (const [key, item] of value) out.set(cloneInto(key, seen), cloneInto(item, seen));
+    return out;
+  }
+
+  if (value instanceof Set) {
+    const out = new Set<unknown>();
+    seen.set(value, out);
+    for (const item of value) out.add(cloneInto(item, seen));
+    return out;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError(
+      `structuredClone: ${prototype?.constructor?.name ?? "object"} could not be cloned.`,
+    );
+  }
+
+  const out: Record<string, unknown> = {};
+  seen.set(value, out);
+  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+    out[key] = cloneInto(item, seen);
+  }
+  return out;
+}
+
+/** The shim itself, exported so a spec can drive it without touching a global. */
+export function cloneStructured<T>(value: T): T {
+  return cloneInto(value, new Map()) as T;
+}
+
+type CloneCapableGlobal = { structuredClone?: <T>(value: T) => T };
+
+/**
+ * Idempotent and cheap: one `typeof` on the happy path, which is every browser
+ * and every worker made this decade. Called at the top of `layoutWithDagre`
+ * rather than as a module side effect so nothing depends on import ORDER —
+ * a formatter that reorders two imports must not be able to break a runtime.
+ */
+export function ensureStructuredClone(): void {
+  const scope = globalThis as CloneCapableGlobal;
+  if (typeof scope.structuredClone === "function") return;
+  scope.structuredClone = cloneStructured;
+}

package/src/layout/types.ts

@@ -0,0 +1,112 @@
+/**
+ * The auto-layout contract, design §8. Types only — no dagre, no DOM, no
+ * React, no runtime at all.
+ *
+ * It is its own module because THREE realms read it: the canvas on the main
+ * thread, the generated worker bundle, and the Hermes-inline path on native.
+ * Putting the wire protocol beside the engine would have made the runner
+ * import the engine just to name a message.
+ *
+ * **elk is not here, and that is deliberate.** Design §8 describes an optional
+ * `@multiplatform.one/node-graph/layout-elk` entry, and the plan's decision D2
+ * gates it on a licence ruling that has NOT been made: elkjs is `EPL-2.0 OR
+ * GPL-3.0-or-later` against this repo's Apache-2.0. So `LayoutEngine` has one
+ * member, the subpath does not exist, and `worker.generated.spec.ts` asserts
+ * the token `elkjs` appears nowhere in the bundled worker. When the ruling
+ * lands, this union grows; until then a second engine cannot be added by
+ * accident.
+ */
+
+import type { EdgeId, NodeId, XY } from "../model/document";
+
+/** One member until decision D2 is ruled. See the module header. */
+export type LayoutEngine = "dagre";
+
+export type LayoutDirection = "TB" | "BT" | "LR" | "RL";
+
+/**
+ * A node as the engine sees it: a box and where it currently sits.
+ *
+ * `width` / `height` are the SEEDED measure (design §5), not a DOM read. The
+ * engine runs off the main thread and could not measure anything even if it
+ * wanted to, which is the same constraint that makes the seed load-bearing on
+ * first paint.
+ */
+export interface LayoutNodeInput {
+  readonly id: NodeId;
+  readonly width: number;
+  readonly height: number;
+  /** Top-left, the document's convention. Read for the anchor and for fixed nodes. */
+  readonly position: XY;
+}
+
+export interface LayoutEdgeInput {
+  readonly id: EdgeId;
+  readonly source: NodeId;
+  readonly target: NodeId;
+}
+
+export interface LayoutOptions {
+  readonly direction?: LayoutDirection;
+  /** Gap between nodes on the same rank. dagre's `nodesep`. */
+  readonly nodeSpacing?: number;
+  /** Gap between ranks. dagre's `ranksep`. */
+  readonly rankSpacing?: number;
+  /** Gap between edges entering the same node. dagre's `edgesep`. */
+  readonly edgeSpacing?: number;
+  /**
+   * Tidy only these. Every other node is FIXED: it keeps its position exactly,
+   * and it is absent from the graph handed to dagre rather than present as an
+   * obstacle — dagre has no notion of a fixed node, so leaving one in would
+   * have it ranked and moved like any other.
+   */
+  readonly subset?: readonly NodeId[];
+}
+
+export interface LayoutRequest {
+  readonly nodes: readonly LayoutNodeInput[];
+  readonly edges: readonly LayoutEdgeInput[];
+  readonly options?: LayoutOptions;
+}
+
+export interface LayoutResult {
+  /**
+   * EVERY input node id, moved or fixed. A fixed node maps to the position it
+   * came in with, so the result is a complete description of the arrangement
+   * and `setPositions` can be built from it without consulting the document —
+   * which matters because the result arrives from another thread, possibly
+   * after the document has moved on (see `generation`).
+   */
+  readonly positions: Readonly<Record<NodeId, XY>>;
+  /** The ids the engine actually laid out, in sorted order. */
+  readonly moved: readonly NodeId[];
+  readonly engine: LayoutEngine;
+  /** Wall-clock milliseconds inside the engine. Reported by the story. */
+  readonly ms: number;
+  /**
+   * Which runner produced it — stamped by the RUNNER, not by the engine.
+   *
+   * `layoutWithDagre` runs in three realms and cannot tell which one it is in,
+   * so the field is optional on the engine's own return and filled in on the
+   * main thread. Design §13.2 records it with every device run, because an
+   * accidental `inline` fallback has to be visible in the data rather than
+   * hidden inside a plausible-looking number.
+   */
+  readonly runner?: LayoutRunnerKind;
+}
+
+/**
+ * Design §8's four. `resolveRunner()` returns one of them and the canvas
+ * reports it in diagnostics, so an accidental `inline` on a platform that has
+ * `Worker` is visible in the data rather than hidden in a bad number.
+ */
+export type LayoutRunnerKind = "worker-blob" | "worker-url" | "hermes-inline" | "inline";
+
+export type LayoutWorkerRequest =
+  | { readonly t: "ping" }
+  | { readonly t: "layout"; readonly id: number; readonly request: LayoutRequest };
+
+export type LayoutWorkerResponse =
+  | { readonly t: "pong" }
+  | { readonly t: "result"; readonly id: number; readonly result: LayoutResult }
+  | { readonly t: "error"; readonly id: number; readonly message: string };

package/src/layout/worker.entry.ts

@@ -0,0 +1,74 @@
+/**
+ * The worker side of auto-layout, and the ROOT of the bundle
+ * `scripts/build-layout-worker.mjs` emits into `worker.generated.ts`.
+ *
+ * Two jobs, deliberately in one file:
+ *
+ *  - `runLayoutMessage` is the dispatch, and it is PURE. The inline and
+ *    Hermes-inline runners call it directly on their own thread, so all three
+ *    runners answer the same protocol with the same code rather than two
+ *    implementations that drift.
+ *  - The side effect at the bottom wires that dispatch to `self` — but ONLY
+ *    inside a real `WorkerGlobalScope`.
+ *
+ * That guard is the load-bearing line. `runner.ts` imports `runLayoutMessage`
+ * from here for its inline path, so this module is evaluated on the MAIN
+ * thread too, where `self` is `window` and `self.postMessage` is a real
+ * function. A `typeof self.postMessage === "function"` guard would therefore
+ * have passed on the main thread and installed a `message` listener on the
+ * window that answers every `postMessage` any library on the page makes.
+ * `instanceof WorkerGlobalScope` is false there and true in a worker, which is
+ * the distinction that actually matters.
+ *
+ * No `import.meta`, and none reachable: `verify-no-import-meta.mjs` walks this
+ * file, and `worker.generated.spec.ts` re-asserts it against the BUNDLED
+ * string, which is the artefact a WebView actually parses.
+ */
+
+import { layoutWithDagre } from "./dagre";
+import type { LayoutWorkerRequest, LayoutWorkerResponse } from "./types";
+
+/**
+ * A message in, a message out, or `undefined` for something this worker does
+ * not answer. Never throws: a throw inside a Worker surfaces as an `error`
+ * event with no line number in a WebView, so a failure is reported as data.
+ */
+export function runLayoutMessage(data: unknown): LayoutWorkerResponse | undefined {
+  const message = data as LayoutWorkerRequest | null | undefined;
+  if (!message || typeof message !== "object") return undefined;
+  if (message.t === "ping") return { t: "pong" };
+  if (message.t !== "layout") return undefined;
+  try {
+    return { t: "result", id: message.id, result: layoutWithDagre(message.request) };
+  } catch (error) {
+    return {
+      t: "error",
+      id: message.id,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+declare const WorkerGlobalScope: (abstract new () => unknown) | undefined;
+declare const self: {
+  readonly addEventListener: (
+    type: "message",
+    listener: (event: { readonly data: unknown }) => void,
+  ) => void;
+  readonly postMessage: (message: unknown) => void;
+};
+
+function inWorkerScope(): boolean {
+  return (
+    typeof WorkerGlobalScope !== "undefined" &&
+    typeof self !== "undefined" &&
+    self instanceof (WorkerGlobalScope as abstract new () => unknown)
+  );
+}
+
+if (inWorkerScope()) {
+  self.addEventListener("message", (event) => {
+    const response = runLayoutMessage(event.data);
+    if (response) self.postMessage(response);
+  });
+}

package/src/layout/worker.generated.spec.ts

@@ -0,0 +1,157 @@
+/**
+ * Task 4.2. The committed worker string is current, classic, clean, and RUNS.
+ *
+ * A checksum on its own only proves the file was not hand-edited. What the
+ * WebView actually needs is stronger: the string has to parse as a CLASSIC
+ * script (an `export` in it is a SyntaxError in a non-module worker), it has
+ * to carry no `import.meta` (design §9.4 layer 1 — a parse-time SyntaxError,
+ * so no guard and no try/catch ever runs), and it has to answer the protocol.
+ * So the last case here evaluates the artefact in a synthetic worker scope and
+ * drives a real layout through it.
+ *
+ * The bundler is re-run in a SUBPROCESS rather than imported. faces.spec.ts
+ * set that precedent for the same reason: a generator is Node tooling with a
+ * native dependency, and pulling esbuild into the vitest module graph to
+ * compute one hash is a much larger surface than spawning it.
+ */
+
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import vm from "node:vm";
+import { describe, expect, it } from "vitest";
+import { layoutWorkerBytes, layoutWorkerSha256, layoutWorkerSource } from "./worker.generated";
+import type { LayoutRequest, LayoutWorkerResponse } from "./types";
+
+const packageRoot = path.resolve(__dirname, "../..");
+
+function generator(...args: string[]): string {
+  return execFileSync(process.execPath, ["scripts/build-layout-worker.mjs", ...args], {
+    cwd: packageRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+describe("worker.generated", () => {
+  it("matches a fresh bundle: the committed sha256 is what the bundler emits today", () => {
+    expect(generator("--sha")).toBe(layoutWorkerSha256);
+  });
+
+  it("is byte-for-byte current, header and all", () => {
+    // `--check` compares the WHOLE emitted module, so a hand-edited comment or
+    // a stale byte count fails here even when the payload happens to match.
+    expect(() => generator("--check")).not.toThrow();
+  });
+
+  it("reports its own size honestly", () => {
+    expect(layoutWorkerBytes).toBe(Buffer.byteLength(layoutWorkerSource, "utf8"));
+  });
+
+  it("carries no `import.meta` token", () => {
+    expect(layoutWorkerSource).not.toContain("import.meta");
+  });
+
+  it("carries no `elkjs`, because decision D2 is unruled", () => {
+    // Not a style point. elkjs is `EPL-2.0 OR GPL-3.0-or-later` against this
+    // repo's Apache-2.0 and Clay has not ruled, and design §8 puts the 445 KB
+    // gz it would add behind exactly this assertion.
+    expect(layoutWorkerSource.toLowerCase()).not.toContain("elkjs");
+    expect(layoutWorkerSource.toLowerCase()).not.toContain("elk.bundled");
+  });
+
+  it("is a CLASSIC script: no top-level import or export survives", () => {
+    expect(layoutWorkerSource).not.toMatch(/(^|\n)\s*export\s/);
+    expect(layoutWorkerSource).not.toMatch(/(^|\n)\s*import\s/);
+    expect(layoutWorkerSource.startsWith('"use strict";(()=>{')).toBe(true);
+  });
+
+  it("bundles dagre in, so the worker needs nothing at runtime", () => {
+    expect(layoutWorkerSource).toContain("WorkerGlobalScope");
+    // dagre's own vocabulary. If the engine were external the bundle would be
+    // a few hundred bytes of wiring and this would miss.
+    expect(layoutWorkerSource).toContain("rankdir");
+    expect(layoutWorkerBytes).toBeGreaterThan(20_000);
+  });
+
+  describe("evaluated in a synthetic worker scope", () => {
+    /** Runs the artefact the way a blob Worker would, and returns its outbox. */
+    function boot() {
+      class FakeWorkerGlobalScope {}
+      const posted: LayoutWorkerResponse[] = [];
+      const listeners: ((event: { data: unknown }) => void)[] = [];
+      const scope = new FakeWorkerGlobalScope() as FakeWorkerGlobalScope & {
+        addEventListener: (type: string, listener: (event: { data: unknown }) => void) => void;
+        postMessage: (message: LayoutWorkerResponse) => void;
+      };
+      scope.addEventListener = (type, listener) => {
+        if (type === "message") listeners.push(listener);
+      };
+      scope.postMessage = (message) => {
+        posted.push(message);
+      };
+      const sandbox: Record<string, unknown> = {
+        WorkerGlobalScope: FakeWorkerGlobalScope,
+        self: scope,
+      };
+      sandbox.globalThis = sandbox;
+      vm.createContext(sandbox);
+      vm.runInContext(layoutWorkerSource, sandbox);
+      return {
+        posted,
+        send: (data: unknown) => {
+          for (const listener of listeners) listener({ data });
+        },
+        listeners,
+      };
+    }
+
+    it("installs exactly one message listener", () => {
+      expect(boot().listeners).toHaveLength(1);
+    });
+
+    it("answers `ping` with `pong`", () => {
+      const worker = boot();
+      worker.send({ t: "ping" });
+      expect(worker.posted).toHaveLength(1);
+      expect(worker.posted[0].t).toBe("pong");
+    });
+
+    it("lays a graph out and posts positions back", () => {
+      const worker = boot();
+      const request: LayoutRequest = {
+        nodes: [
+          { id: "a", width: 190, height: 72, position: { x: 0, y: 0 } },
+          { id: "b", width: 190, height: 72, position: { x: 0, y: 0 } },
+        ],
+        edges: [{ id: "a->b", source: "a", target: "b" }],
+      };
+      worker.send({ t: "layout", id: 7, request });
+      expect(worker.posted).toHaveLength(1);
+      const response = worker.posted[0];
+      expect(response.t).toBe("result");
+      if (response.t !== "result") return;
+      expect(response.id).toBe(7);
+      expect(response.result.engine).toBe("dagre");
+      expect(Object.keys(response.result.positions).sort()).toEqual(["a", "b"]);
+      expect(response.result.positions.b.y).toBeGreaterThan(response.result.positions.a.y);
+    });
+
+    it("reports a malformed request as an `error` message rather than throwing", () => {
+      // A throw inside a Worker arrives as an `error` event with no line
+      // number in a WebView, which is the least useful diagnostic there is.
+      const worker = boot();
+      worker.send({ t: "layout", id: 1, request: { nodes: null, edges: [] } });
+      expect(worker.posted).toHaveLength(1);
+      expect(worker.posted[0].t).toBe("error");
+    });
+
+    it("stays silent on a message it does not own", () => {
+      const worker = boot();
+      worker.send({ t: "something-else" });
+      worker.send(null);
+      worker.send("hello");
+      expect(worker.posted).toHaveLength(0);
+    });
+  });
+});