@isothrum/editor 0.0.0-stage → 0.1.0

package/src/lib/tool/create.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "vitest";
+import { lanBelow, newLan, newMachine, newNote, newSwitch, twoVlans, usedThirds } from "./create";
+import { LAN_BEHAVIOR, LAN_H, LAN_W } from "./model";
+import { PRESETS, type Preset } from "./presets";
+import { lan, machine } from "@/test/lab";
+
+/** The built-in device with this id. */
+const preset = (id: string): Preset => {
+  const p = PRESETS.find((x) => x.id === id);
+  if (!p) throw new Error(`no preset ${id}`);
+  return p;
+};
+
+describe("newMachine", () => {
+  test("names a machine after its device, with the first free number", () => {
+    expect(newMachine(preset("web"), { x: 0, y: 0 }, [machine("a", { name: "web1" })]).data.name).toBe("web2");
+  });
+
+  test("gives a VM a provisioning script of its own: a shell script, PowerShell on Windows", () => {
+    expect(newMachine(preset("linux-vm"), { x: 0, y: 0 }, []).data.provision).toBe("provision/vm1.sh");
+    expect(newMachine(preset("windows-vm"), { x: 0, y: 0 }, []).data.provision).toBe("provision/win1.ps1");
+  });
+
+  test("gives the access VM and containers no provisioning", () => {
+    expect(newMachine(preset("workstation"), { x: 0, y: 0 }, []).data.provision).toBe("");
+    expect(newMachine(preset("container"), { x: 0, y: 0 }, []).data.provision).toBe("");
+  });
+
+  test("places the machine where it is told, under a new id", () => {
+    const m = newMachine(preset("web"), { x: 5, y: 7 }, []);
+    expect(m.position).toEqual({ x: 5, y: 7 });
+    expect(m.id).toMatch(/^m-/);
+  });
+});
+
+describe("LANs", () => {
+  test("usedThirds reads the third number of each LAN's 10.10.<n>.0/24", () => {
+    expect(usedThirds([lan("a", { cidr: "10.10.3.0/24" }), lan("b", { cidr: "192.168.1.0/24" }), machine("m")])).toEqual(new Set([3]));
+  });
+
+  test("a new LAN takes the next free block and name, centered where it is placed", () => {
+    const l = newLan({ x: 500, y: 400 }, [lan("lan1", { cidr: "10.10.1.0/24" }), lan("x", { name: "x", cidr: "10.10.3.0/24" })]);
+    expect(l.data).toEqual({ name: "lan2", cidr: "10.10.2.0/24", internet: true });
+    expect(l).toMatchObject({ ...LAN_BEHAVIOR, position: { x: 500 - LAN_W / 2, y: 400 - LAN_H / 2 }, width: LAN_W, height: LAN_H });
+  });
+
+  test("a LAN below a device puts the device on its top edge, toward the right", () => {
+    const l = lanBelow({ x: 1000, y: 100 }, [], { name: "vlan10" }, { w: 600, h: 300 });
+    expect(l).toMatchObject({ position: { x: 1000 - 600 * 0.74, y: 100 }, width: 600, height: 300, data: { name: "vlan10", cidr: "10.10.1.0/24" } });
+  });
+});
+
+describe("switches and notes", () => {
+  test("a new switch has vlan10 on ports 1–4 and vlan20 on ports 5–8", () => {
+    expect(twoVlans().ports).toEqual([10, 10, 10, 10, 20, 20, 20, 20]);
+    expect(twoVlans().vlans.map((v) => v.cidr)).toEqual(["10.10.10.0/24", "10.10.20.0/24"]);
+  });
+
+  test("a new switch is centered on the point and takes the next free name", () => {
+    const sw = newSwitch({ x: 200, y: 100 }, [machine("a", { name: "sw1" })]);
+    expect(sw).toMatchObject({ type: "switch", position: { x: 30, y: 60 }, data: { name: "sw2" } });
+  });
+
+  test("a new note is empty text, selected, at the point", () => {
+    expect(newNote({ x: 1, y: 2 })).toMatchObject({ type: "note", position: { x: 1, y: 2 }, selected: true, data: { text: "", shape: "text", color: "yellow" } });
+  });
+});

package/src/lib/tool/create.ts

@@ -0,0 +1,83 @@
+import type { XYPosition } from "@xyflow/react";
+import { LAN_BEHAVIOR, LAN_H, LAN_W, freeName, isLan, uid, type LabNode, type LanData, type LanNode, type MachineData, type MachineNode, type NoteNode, type SwitchNode } from "./model";
+import type { Preset } from "./presets";
+
+/** New nodes, as the toolbar places them. */
+
+export function newNote(position: XYPosition): NoteNode {
+  return { id: uid("n"), type: "note", position, width: 200, height: 90, selected: true, data: { text: "", shape: "text", color: "yellow" } };
+}
+
+/** vlan10 and vlan20: a new switch's VLANs (ports 1–4 and 5–8, both on the trunk). */
+export function twoVlans(): SwitchNode["data"] {
+  return {
+    name: "",
+    vlans: [
+      { id: 10, cidr: "10.10.10.0/24" },
+      { id: 20, cidr: "10.10.20.0/24" },
+    ],
+    ports: [10, 10, 10, 10, 20, 20, 20, 20],
+  };
+}
+
+/** A new switch with vlan10 on ports 1–4, vlan20 on ports 5–8, both on the trunk. */
+export function newSwitch(center: XYPosition, nodes: LabNode[]): SwitchNode {
+  return {
+    id: uid("s"),
+    type: "switch",
+    position: { x: center.x - 170, y: center.y - 40 },
+    data: { ...twoVlans(), name: freeName("sw", nodes) },
+  };
+}
+
+export function newMachine(preset: Preset, position: XYPosition, nodes: LabNode[]): MachineNode {
+  const name = freeName(preset.prefix, nodes);
+  const data: MachineData = { ...preset.data, name };
+  // Isoloom needs a VM's provisioning steps, except on the access machine (the runner supplies it).
+  if (data.kind === "vm" && !data.access && !data.provision) {
+    data.provision = `provision/${name}.${data.os.startsWith("windows") ? "ps1" : "sh"}`;
+  }
+  return { id: uid("m"), type: "machine", position, data };
+}
+
+/** The third number of each LAN's 10.10.<n>.0/24 block. */
+export function usedThirds(nodes: LabNode[]): Set<number> {
+  return new Set(
+    nodes
+      .filter(isLan)
+      .map((n) => /^10\.10\.(\d+)\./.exec(n.data.cidr)?.[1])
+      .filter(Boolean)
+      .map(Number),
+  );
+}
+
+/** A new LAN centered on `center`, with the next free 10.10.<n>.0/24. */
+export function newLan(center: XYPosition, nodes: LabNode[]): LanNode {
+  const used = usedThirds(nodes);
+  let third = 1;
+  while (used.has(third)) third++;
+  return {
+    ...LAN_BEHAVIOR,
+    id: uid("l"),
+    type: "lan",
+    position: { x: center.x - LAN_W / 2, y: center.y - LAN_H / 2 },
+    width: LAN_W,
+    height: LAN_H,
+    data: { name: freeName("lan", nodes), cidr: `10.10.${String(third)}.0/24`, internet: true },
+  };
+}
+
+/**
+ * A LAN that hangs under a device placed at `center` (a router or a switch): the device sits on
+ * its top edge, toward the right, so the LAN's label (top left) stays clear and clickable.
+ */
+export function lanBelow(center: XYPosition, nodes: LabNode[], data?: Partial<LanData>, size = { w: LAN_W, h: LAN_H }): LanNode {
+  const lan = newLan({ x: center.x, y: center.y + size.h / 2 }, nodes);
+  return {
+    ...lan,
+    width: size.w,
+    height: size.h,
+    position: { x: center.x - size.w * 0.74, y: center.y },
+    data: { ...lan.data, ...data },
+  };
+}

package/src/lib/tool/desktop.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test, vi } from "vitest";
+import { type Invoke, desktop, machineStatus, runningServices, runsOnVms } from "./desktop";
+
+describe("desktop", () => {
+  test("has no commands in a browser, or without a window", () => {
+    expect(desktop()).toBeNull();
+    vi.stubGlobal("window", {});
+    expect(desktop()).toBeNull();
+  });
+
+  test("gives the desktop app's invoke when the window has one", () => {
+    const invoke: Invoke = () => Promise.reject(new Error("unused"));
+    vi.stubGlobal("window", { __TAURI__: { core: { invoke } } });
+    expect(desktop()).toBe(invoke);
+  });
+});
+
+describe("runsOnVms", () => {
+  const plan = (paths: string[]) => ({ files: paths.map((path) => ({ path })) });
+
+  test("a lab with VM nodes that Isoloom generates for Docker runs on Docker", () => {
+    expect(runsOnVms(true, plan([".isoloom/docker/compose.yml", ".isoloom/vagrant/Vagrantfile"]))).toBe(false);
+  });
+
+  test("a lab whose VMs have no container form runs on VMs", () => {
+    expect(runsOnVms(true, plan([".isoloom/hybrid/Vagrantfile"]))).toBe(true);
+    expect(runsOnVms(true, null)).toBe(true);
+  });
+
+  test("a lab without VM nodes never needs VMs", () => {
+    expect(runsOnVms(false, plan([]))).toBe(false);
+  });
+});
+
+describe("machineStatus", () => {
+  test("a running machine is up, unless its check says unhealthy or starting", () => {
+    expect(machineStatus({ state: "running", health: "" })).toBe("up");
+    expect(machineStatus({ state: "running", health: "unhealthy" })).toBe("unhealthy");
+    expect(machineStatus({ state: "running", health: "starting" })).toBe("starting");
+  });
+
+  test("a machine being created or restarting is starting", () => {
+    expect([machineStatus({ state: "created", health: "" }), machineStatus({ state: "restarting", health: "" })]).toEqual(["starting", "starting"]);
+  });
+
+  test("a machine that exited, or isn't there, is down", () => {
+    expect([machineStatus({ state: "exited", health: "" }), machineStatus(undefined)]).toEqual(["down", "down"]);
+  });
+});
+
+describe("runningServices", () => {
+  test("counts the running services of docker compose ps, one JSON object per line", () => {
+    expect(runningServices('{"State":"running"}\n x \n{"State":"exited"}\n\n{"State":"running"}')).toBe(2);
+  });
+
+  test("counts none in empty output", () => {
+    expect(runningServices("")).toBe(0);
+  });
+});

package/src/lib/tool/desktop.ts

@@ -0,0 +1,99 @@
+/**
+ * The desktop app's commands (Isothrum desktop loads this editor in its window and exposes them
+ * on `window.__TAURI__`). In a browser there is no such object, and the desktop-only controls
+ * (Run, Stop, Capture) stay hidden.
+ */
+export type Invoke = <T>(command: string, args?: Record<string, unknown>) => Promise<T>;
+
+interface TauriWindow {
+  __TAURI__?: { core?: { invoke?: Invoke } };
+}
+
+export function desktop(): Invoke | null {
+  if (typeof window === "undefined") return null;
+  const tauri = (window as unknown as TauriWindow).__TAURI__;
+  return tauri?.core?.invoke ?? null;
+}
+
+/**
+ * Whether the desktop app runs the lab on VMs (with Vagrant): it runs it on Docker whenever Isoloom
+ * generates its Docker files, which a machine drawn as a Linux VM has (its OS and steps build a
+ * container); only a lab with a machine that is a VM only (Windows, a playbook step) needs VMs.
+ */
+export function runsOnVms(hasVmNodes: boolean, plan: { files: { path: string }[] } | null): boolean {
+  return hasVmNodes && !(plan?.files.some((f) => f.path === ".isoloom/docker/compose.yml") ?? false);
+}
+
+/** One machine now (desktop: `lab_live`): Docker's state, and its health when it has a check. */
+export interface MachineLive {
+  state: string;
+  health: string;
+}
+/** One machine's port on one network now: up, down, or unknown (stopped, or a Cisco OS's). */
+interface PortLive {
+  machine: string;
+  network: string;
+  up: boolean | null;
+  interface: string | null;
+}
+/** The running lab now. `probed`: the ports were read from the machines (not inferred). */
+export interface LabLive {
+  machines: Record<string, MachineLive>;
+  ports: PortLive[];
+  probed: boolean;
+}
+
+/** A machine at a glance: up, on its way (starting, restarting), unhealthy, or down. */
+export type Status = "up" | "starting" | "unhealthy" | "down";
+
+export function machineStatus(m: MachineLive | undefined): Status {
+  if (!m) return "down";
+  if (m.state === "restarting" || m.state === "created") return "starting";
+  if (m.state !== "running") return "down";
+  if (m.health === "unhealthy") return "unhealthy";
+  return m.health === "starting" ? "starting" : "up";
+}
+
+/** A link cut while the lab runs: `machine`'s port on `network`, down. */
+export interface SuspendedLink {
+  network: string;
+  machine: string;
+}
+
+/** A machine saved as an image (desktop: `docker commit`). */
+export interface Snapshot {
+  id: string;
+  machine: string;
+  image: string;
+  label: string;
+  created: number;
+  in_use: boolean;
+}
+
+export interface DesktopInfo {
+  version: string;
+  docker: boolean;
+  vagrant?: boolean;
+  wireshark: boolean;
+  live_capture: boolean;
+  labs: string;
+}
+
+/** A line of `docker compose ps --format json` (nothing in particular when it isn't one). */
+function serviceLine(line: string): { State?: string } {
+  try {
+    return JSON.parse(line) as { State?: string };
+  } catch {
+    return {};
+  }
+}
+
+/** `docker compose ps --format json`: one JSON object per line. */
+export function runningServices(ps: string): number {
+  return ps
+    .split("\n")
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map(serviceLine)
+    .filter((s) => s.State === "running").length;
+}

package/src/lib/tool/draft.test.ts

@@ -0,0 +1,150 @@
+import fc from "fast-check";
+import { describe, expect, test } from "vitest";
+import { decodeLab, encodeLab, isDesign, normalizeDraft, plainDraft, storedEdges, storedNodes } from "./draft";
+import { LAN_BEHAVIOR, cleanName, type CableEdge, type Draft } from "./model";
+import { arbitraryLab } from "@/test/arbitrary";
+import { autoRouter, cable, lan, machine } from "@/test/lab";
+
+/** A lab with UI state on it: a selected, measured machine, a selected cable with conditions. */
+const lab = (): Draft => ({
+  name: "office-lab",
+  nodes: [{ ...lan("office"), ...LAN_BEHAVIOR }, { ...machine("web"), selected: true, dragging: false, measured: { width: 120, height: 116 } }, autoRouter("r")],
+  edges: [{ ...cable("c1", "web", "office", { sourceHandle: "top", tc: { delay: 5 }, color: "#000" }), selected: true }],
+});
+
+test("isDesign knows the canvas's two looks", () => {
+  expect([isDesign("sketch"), isDesign("business"), isDesign("neon"), isDesign(undefined)]).toEqual([true, true, false, false]);
+});
+
+describe("what a lab keeps", () => {
+  test("stored nodes keep the lab only: id, type, position, data, size", () => {
+    expect(storedNodes(lab().nodes)[1]).toEqual({ id: "web", type: "machine", position: { x: 0, y: 0 }, data: machine("web").data, width: undefined, height: undefined });
+  });
+
+  test("stored cables keep their ends and their data, or the data they are given", () => {
+    const [e] = storedEdges(lab().edges, () => undefined);
+    expect(e).toEqual({ id: "c1", type: "cable", source: "web", sourceHandle: "top", target: "office", targetHandle: null, data: undefined });
+  });
+
+  test("a plain draft has no selection, drag or measured size", () => {
+    const plain = plainDraft(lab());
+    expect(plain.nodes.some((n) => "selected" in n || "dragging" in n || "measured" in n)).toBe(false);
+    expect(plain.edges.some((e) => "selected" in e)).toBe(false);
+  });
+});
+
+describe("normalizeDraft", () => {
+  test("refuses what has no lists of nodes and edges", () => {
+    for (const bad of [null, 1, "x", [], {}, { nodes: [], edges: {} }]) expect(normalizeDraft(bad)).toBeNull();
+  });
+
+  test("is null, not an error, for a null node or cable", () => {
+    expect(normalizeDraft({ name: "x", nodes: [null], edges: [] })).toBeNull();
+    expect(normalizeDraft({ name: "x", nodes: [], edges: [null] })).toBeNull();
+  });
+
+  test("refuses a node without its id, position or data, a cable without its ends, or a name that isn't text", () => {
+    const m = machine("m");
+    for (const bad of [{ ...m, id: 1 }, { ...m, position: null }, { ...m, data: undefined }]) expect(normalizeDraft({ name: "x", nodes: [bad], edges: [] })).toBeNull();
+    for (const bad of [{ id: "c", source: "m" }, { id: "c", target: "m" }, { source: "m", target: "m" }]) expect(normalizeDraft({ name: "x", nodes: [m], edges: [bad] })).toBeNull();
+    expect(normalizeDraft({ name: 5, nodes: [], edges: [] })).toBeNull();
+  });
+
+  test("makes LANs frames again and moves cables onto today's handles", () => {
+    const stored = { name: "x", nodes: [lan("office"), autoRouter("r")], edges: [cable("c", "r", "office", { sourceHandle: "left" })] };
+    const d = normalizeDraft(stored);
+    expect(d?.nodes[0]).toMatchObject(LAN_BEHAVIOR);
+    expect(d?.edges[0].sourceHandle).toBe("port");
+  });
+
+  test("names a stored machine's OS and Cisco OS as Isoloom does now", () => {
+    const vm = machine("pc", { kind: "vm", os: "ubuntu-24.04" });
+    const sw = machine("sw", { appliance: "cisco-viosl2" as never });
+    const d = normalizeDraft({ name: "x", nodes: [vm, sw], edges: [] });
+    expect(d?.nodes.map((n) => n.data)).toMatchObject([{ os: "ubuntu@24.04" }, { appliance: "cisco-vios-l2" }]);
+  });
+});
+
+describe("normalizeDraft, for anything stored", () => {
+  /** Something stored as a node or a cable: any of their fields, each of any JSON value or a likely one. */
+  const ids = fc.constantFrom("a", "b");
+  const field = <T>(likely: fc.Arbitrary<T>) => fc.oneof(likely, fc.jsonValue());
+  const nodeish = fc.record(
+    { id: field(ids), type: field(fc.constantFrom("machine", "lan", "switch", "note")), position: field(fc.constant({ x: 0, y: 0 })), data: field(fc.constant({ icon: "router" })) },
+    { requiredKeys: [] },
+  );
+  const cableish = fc.record({ id: field(ids), source: field(ids), target: field(ids), sourceHandle: fc.jsonValue(), data: fc.jsonValue() }, { requiredKeys: [] });
+  const stored = fc.oneof(fc.jsonValue(), fc.record({ name: field(fc.string()), nodes: fc.array(field(nodeish)), edges: fc.array(field(cableish)) }));
+
+  test("never throws: it is a draft or null", () => {
+    fc.assert(
+      fc.property(stored, (v) => {
+        expect(() => normalizeDraft(v)).not.toThrow();
+      }),
+    );
+  });
+
+  test("opens any lab the editor draws, as storage keeps it", () => {
+    fc.assert(
+      fc.property(arbitraryLab, (drawn) => {
+        expect(normalizeDraft(JSON.parse(JSON.stringify(drawn)))?.nodes.map((n) => n.id)).toEqual(drawn.nodes.map((n) => n.id));
+      }),
+    );
+  });
+});
+
+describe("a lab in a link", () => {
+  test("is base64url, which a link carries as it is", async () => {
+    expect(await encodeLab(lab())).toMatch(/^[A-Za-z0-9_-]+$/);
+  });
+
+  test("comes back with its nodes, cables and ports", async () => {
+    const d = await decodeLab(await encodeLab(lab()));
+    expect(d?.nodes.map((n) => n.id)).toEqual(["office", "web", "r"]);
+    expect(d?.edges[0]).toMatchObject({ source: "web", sourceHandle: "top", target: "office", data: { aPort: "eth0", bPort: "eth0" } });
+  });
+
+  test("comes back with its machines' OS as Isoloom names it now", async () => {
+    const old = { ...lab(), nodes: [machine("pc", { kind: "vm", os: "debian-12" })], edges: [] };
+    expect((await decodeLab(await encodeLab(old)))?.nodes[0].data).toMatchObject({ os: "debian@12" });
+  });
+
+  test("keeps the cables' conditions", async () => {
+    const d = await decodeLab(await encodeLab(lab()));
+    expect(d?.edges[0].data?.tc).toEqual({ delay: 5 });
+  });
+
+  test("leaves the UI state and the cables' drawing color behind", async () => {
+    const d = await decodeLab(await encodeLab(lab()));
+    expect(d?.nodes[1]).not.toHaveProperty("selected");
+    expect(d?.edges[0].data).toEqual({ aPort: "eth0", bPort: "eth0", tc: { delay: 5 } });
+  });
+
+  test("carries the look only when it isn't the default sketch", async () => {
+    expect((await decodeLab(await encodeLab({ ...lab(), design: "business" })))?.design).toBe("business");
+    expect((await decodeLab(await encodeLab({ ...lab(), design: "sketch" })))?.design).toBeUndefined();
+  });
+
+  test("cleans the lab's name, or calls it shared-lab", async () => {
+    expect((await decodeLab(await encodeLab({ ...lab(), name: "My Lab!" })))?.name).toBe("mylab");
+    expect((await decodeLab(await encodeLab({ ...lab(), name: "" })))?.name).toBe("shared-lab");
+  });
+
+  test("is nothing when the code isn't a lab", async () => {
+    for (const code of ["", "abc", "!!"]) expect(await decodeLab(code)).toBeNull();
+  });
+});
+
+describe("any lab in a link", () => {
+  test("comes back with its name, look, nodes and cables: their ends, ports and conditions", async () => {
+    await fc.assert(
+      fc.asyncProperty(arbitraryLab, async (drawn) => {
+        const d = await decodeLab(await encodeLab(drawn));
+        expect([d?.name, d?.design]).toEqual([cleanName(drawn.name) || "shared-lab", drawn.design === "business" ? "business" : undefined]);
+        expect(d?.nodes.map((n) => [n.id, n.type, n.position, n.data])).toEqual(drawn.nodes.map((n) => [n.id, n.type, n.position, n.data]));
+        const ends = (e: CableEdge) => [e.id, e.source, e.target, { aPort: e.data?.aPort, bPort: e.data?.bPort, tc: e.data?.tc }];
+        expect(d?.edges.map((e) => [e.id, e.source, e.target, e.data])).toEqual(drawn.edges.map(ends));
+      }),
+    );
+  });
+});

package/src/lib/tool/draft.ts

@@ -0,0 +1,109 @@
+import { migrateEdges } from "./cables";
+import { DESIGNS, LAN_BEHAVIOR, cleanName, type CableEdge, type Design, type Draft, type LabNode } from "./model";
+import { currentMachine } from "./os";
+
+/** A lab as it is kept: in storage, in a saved project, or in a share link. */
+
+/** Whether `v` is one of the canvas's looks. */
+export const isDesign = (v: unknown): v is Design => DESIGNS.some((d) => d === v);
+
+/** A lab's nodes and cables as stored: the lab only, no UI state. */
+export function storedNodes(nodes: LabNode[]): Pick<LabNode, "id" | "type" | "position" | "data" | "width" | "height">[] {
+  return nodes.map(({ id, type, position, data, width, height }) => ({ id, type, position, data, width, height }));
+}
+
+export function storedEdges(edges: CableEdge[], data: (e: CableEdge) => CableEdge["data"] = (e) => e.data): CableEdge[] {
+  return edges.map((e) => ({ id: e.id, type: e.type, source: e.source, sourceHandle: e.sourceHandle, target: e.target, targetHandle: e.targetHandle, data: data(e) }));
+}
+
+/** LANs behave as frames again, machines name their OS as Isoloom does, and cables move onto today's handles. */
+function current(nodes: LabNode[], edges: CableEdge[]): { nodes: LabNode[]; edges: CableEdge[] } {
+  const withBehavior = nodes.map((n): LabNode => {
+    if (n.type === "lan") return { ...n, ...LAN_BEHAVIOR };
+    return n.type === "machine" ? { ...n, data: currentMachine(n.data) } : n;
+  });
+  return { nodes: withBehavior, edges: migrateEdges(edges, withBehavior) };
+}
+
+/** Whether `v` is a JSON object: not null, not a list. */
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** Whether a stored node has what the editor reads of every node: an id, a position and its data. */
+const isNode = (v: unknown): v is LabNode => isRecord(v) && typeof v.id === "string" && isRecord(v.position) && isRecord(v.data);
+
+/** Whether a stored cable has what the editor reads of every cable: an id and its two ends. */
+const isCable = (v: unknown): v is CableEdge => isRecord(v) && typeof v.id === "string" && typeof v.source === "string" && typeof v.target === "string";
+
+/** Whether a parsed value has the shape of a draft: a name (if any) in text, lists of nodes and cables. */
+function hasLists(d: unknown): d is { name?: string; nodes: LabNode[]; edges: CableEdge[]; design?: unknown } {
+  if (!isRecord(d)) return false;
+  const { name, nodes, edges } = d;
+  if (name !== undefined && typeof name !== "string") return false;
+  return Array.isArray(nodes) && Array.isArray(edges) && nodes.every(isNode) && edges.every(isCable);
+}
+
+/**
+ * A draft from storage or a saved project, made current: LAN behavior, machines' OS names, today's cable handles.
+ * Null when it isn't a lab's shape (a node or a cable that isn't one, as a damaged store holds).
+ */
+export function normalizeDraft(d: unknown): Draft | null {
+  if (!hasLists(d)) return null;
+  return { ...(d as Draft), ...current(d.nodes, d.edges) };
+}
+
+/** A draft without what is only UI state (selection, drag, measured sizes): what a save keeps. */
+export function plainDraft(d: Draft): Draft {
+  return {
+    ...d,
+    nodes: d.nodes.map((n) => {
+      const c = { ...n };
+      delete c.selected;
+      delete c.dragging;
+      delete c.measured;
+      return c;
+    }),
+    edges: d.edges.map((e) => {
+      const c = { ...e };
+      delete c.selected;
+      return c;
+    }),
+  };
+}
+
+/** Base64url without padding, as a link carries it. */
+function toBase64Url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * A lab in a link: its JSON, deflated, in base64url, after `#lab=`. The part after `#` never
+ * reaches a server, so a shared lab stays as private as the editor (the link is the only copy).
+ */
+export async function encodeLab(draft: Draft): Promise<string> {
+  const plain = {
+    name: draft.name,
+    // The look goes with the link, so the reader sees the diagram as it was drawn.
+    ...(draft.design && draft.design !== "sketch" ? { design: draft.design } : {}),
+    nodes: storedNodes(draft.nodes),
+    // A cable keeps its ports and conditions; its color is only drawing, worked out again.
+    edges: storedEdges(draft.edges, (e) => (e.data ? { aPort: e.data.aPort, bPort: e.data.bPort, tc: e.data.tc } : e.data)),
+  };
+  const stream = new Blob([JSON.stringify(plain)]).stream().pipeThrough(new CompressionStream("deflate-raw"));
+  return toBase64Url(new Uint8Array(await new Response(stream).arrayBuffer()));
+}
+
+export async function decodeLab(code: string): Promise<Draft | null> {
+  try {
+    const bin = atob(code.replace(/-/g, "+").replace(/_/g, "/"));
+    const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0));
+    const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("deflate-raw"));
+    const d: unknown = JSON.parse(await new Response(stream).text());
+    if (!hasLists(d)) return null;
+    const design = isDesign(d.design) ? d.design : undefined;
+    return { name: cleanName(d.name ?? "") || "shared-lab", ...current(d.nodes, d.edges), design };
+  } catch {
+    return null;
+  }
+}

package/src/lib/tool/engine.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "vitest";
+import { type Engine, ownFiles, planOf } from "./engine";
+
+/** An engine whose plan is `plan` (a function, to fail like a crash). */
+function fakeEngine(plan: () => string, files = "[]"): Engine {
+  return {
+    default: () => Promise.resolve(),
+    plan_json: plan,
+    bundle: () => new Uint8Array(),
+    own_files_json: () => files,
+    bundle_target: () => new Uint8Array(),
+  };
+}
+
+const failed = (e: string) => `engine failed: ${e}`;
+
+describe("planOf", () => {
+  test("reads the engine's plan", () => {
+    const plan = { ok: true, error: null, isoloom_yml: "name: lab\n", problems: [], files: [], skipped: [], addresses: { web: [["office", "10.10.1.10"]] } };
+    expect(planOf(fakeEngine(() => JSON.stringify(plan)), "{}", failed)).toEqual(plan);
+  });
+
+  test("gives no isoloom.yml when the engine leaves it out", () => {
+    const plan = { ok: false, error: "bad", problems: ["x"], files: [], skipped: [], addresses: {} };
+    expect(planOf(fakeEngine(() => JSON.stringify(plan)), "{}", failed).isoloom_yml).toBeNull();
+  });
+
+  test("turns an engine crash into a failed plan, in the editor's words", () => {
+    const crash = fakeEngine(() => {
+      throw new Error("unreachable");
+    });
+    expect(planOf(crash, "{}", failed)).toEqual({ ok: false, error: "engine failed: Error: unreachable", isoloom_yml: null, problems: [], files: [], skipped: [], addresses: {} });
+  });
+});
+
+test("ownFiles reads the lab's own files from the engine", () => {
+  const files = [{ path: "provision/db.sh", contents: "#!/bin/sh\n" }];
+  expect(ownFiles(fakeEngine(() => "{}", JSON.stringify(files)), "{}")).toEqual(files);
+});

package/src/lib/tool/engine.ts

@@ -0,0 +1,58 @@
+import type { Addresses } from "./router-ports";
+
+/**
+ * The engine's JavaScript surface, from `public/wasm/isothrum_wasm.js` (built from
+ * `crates/isothrum-wasm`). Everything runs in the browser: nothing is sent to a server.
+ */
+export interface Engine {
+  default: () => Promise<unknown>;
+  plan_json: (topology: string) => string;
+  bundle: (topology: string) => Uint8Array;
+  /** The lab's own files (provisioning starters, appliance configurations), as JSON. */
+  own_files_json: (topology: string) => string;
+  bundle_target: (topology: string, targetDir: string) => Uint8Array;
+}
+
+export interface GeneratedFile {
+  path: string;
+  contents: string;
+}
+
+/** What the engine makes of a lab: isoloom.yml and every target's files, or what is wrong. */
+export interface Plan {
+  ok: boolean;
+  error: string | null;
+  isoloom_yml: string | null;
+  problems: string[];
+  files: GeneratedFile[];
+  skipped: string[];
+  addresses: Addresses;
+}
+
+/** Served from `public/wasm/`; loaded at runtime, not bundled. */
+const ENGINE_URL: string = "/wasm/isothrum_wasm.js";
+
+/** Loads and starts the engine. */
+export async function loadEngine(): Promise<Engine> {
+  const m = (await import(/* webpackIgnore: true */ /* turbopackIgnore: true */ ENGINE_URL)) as Engine;
+  await m.default();
+  return m;
+}
+
+/** The plan as the engine writes it: isoloom.yml may be left out when there is none. */
+type RawPlan = Omit<Plan, "isoloom_yml"> & { isoloom_yml?: string | null };
+
+/** The engine's plan for a topology; an engine crash becomes a plan with `error` (from `failed`). */
+export function planOf(engine: Engine, topology: string, failed: (error: string) => string): Plan {
+  try {
+    const raw = JSON.parse(engine.plan_json(topology)) as RawPlan;
+    return { ...raw, isoloom_yml: raw.isoloom_yml ?? null };
+  } catch (e) {
+    return { ok: false, error: failed(String(e)), isoloom_yml: null, problems: [], files: [], skipped: [], addresses: {} };
+  }
+}
+
+/** The lab's own files (provisioning starters, appliance configurations). */
+export function ownFiles(engine: Engine, topology: string): GeneratedFile[] {
+  return JSON.parse(engine.own_files_json(topology)) as GeneratedFile[];
+}