@isothrum/editor 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "vitest";
+import { accessVlan, isTrunkPort, switchLans, switchPortLabel, trunkInterface, trunkStripes, vlanColor, vlanName, vlanOf } from "./vlans";
+import { cable, switchNode } from "@/test/lab";
+
+describe("VLAN names and colors", () => {
+  test("names a VLAN vlan<id>, and reads the number back from a LAN's name", () => {
+    expect(vlanName(10)).toBe("vlan10");
+    expect(["vlan10", "vlan0", "vlan", "vlan12345", "xvlan1"].map(vlanOf)).toEqual([10, 0, null, null, null]);
+  });
+
+  test("colors a VLAN by its tens, eight colors around", () => {
+    expect(vlanColor(10)).toBe("#2f9e44");
+    expect(vlanColor(14)).toBe(vlanColor(10));
+    expect(vlanColor(90)).toBe(vlanColor(10));
+    expect(vlanColor(-10)).toBe(vlanColor(10));
+  });
+
+  test("stripes a trunk with the colors of its VLANs, muted when it carries none", () => {
+    expect(trunkStripes([{ id: 10 }, { id: 20 }])).toBe("repeating-linear-gradient(135deg, #2f9e44 0px 5px, #1971c2 5px 10px)");
+    expect(trunkStripes([])).toBe("var(--muted)");
+  });
+
+  test("names a trunk's interface after its LAN, within Linux's limit", () => {
+    expect(["sw1", "a-very-long-lan-name", "abcdefghi-x"].map(trunkInterface)).toEqual(["sw1", "a-very-lon", "abcdefghi"]);
+  });
+});
+
+describe("switch ports", () => {
+  const sw = switchNode("sw1");
+
+  test("the T port and any port set to trunk are trunks", () => {
+    expect(["trunk", "p4"].map((h) => isTrunkPort(sw, h))).toEqual([true, true]);
+    expect(["p1", null, "eth0"].map((h) => isTrunkPort(sw, h))).toEqual([false, false, false]);
+  });
+
+  test("an access port is in its VLAN; a trunk, a free port or no port is in none", () => {
+    expect(["p1", "p3"].map((h) => accessVlan(sw, h))).toEqual([10, 20]);
+    expect(["p4", "p5", "trunk", "eth0", undefined].map((h) => accessVlan(sw, h))).toEqual([null, null, null, null, null]);
+  });
+
+  test("labels a port 1, 2… or T", () => {
+    expect(["p1", "p12", "trunk", "", null, undefined, "x"].map(switchPortLabel)).toEqual(["1", "12", "T", "", "", "", ""]);
+  });
+});
+
+describe("switchLans", () => {
+  const s1 = switchNode("s1", { name: "sw1", vlans: [{ id: 10, cidr: "10.10.10.0/24" }] });
+  const s2 = switchNode("s2", { name: "sw2", vlans: [{ id: 30, cidr: "10.10.30.0/24" }] });
+  const s3 = switchNode("s3", { name: "sw3", vlans: [{ id: 10, cidr: "10.10.10.0/24" }] });
+
+  test("switches cabled together are one LAN, named after the first", () => {
+    const lanOf = switchLans([s1, s2], [cable("c", "s2", "s1")]);
+    expect([lanOf("s1"), lanOf("s2")]).toEqual(["sw1", "sw1"]);
+  });
+
+  test("switches sharing a VLAN number are one LAN", () => {
+    expect(switchLans([s1, s3], [])("s3")).toBe("sw1");
+  });
+
+  test("a switch alone is its own LAN, and an unknown id has none", () => {
+    const lanOf = switchLans([s1, s2], []);
+    expect([lanOf("s2"), lanOf("nope")]).toEqual(["sw2", ""]);
+  });
+});

package/src/lib/tool/vlans.ts

@@ -0,0 +1,79 @@
+import { TRUNK, isSwitch, type CableEdge, type LabNode, type SwitchNode } from "./model";
+
+/** VLANs and switch ports. VLANs are lab-wide: `vlan10` is the same network on every switch. */
+
+export const vlanName = (id: number) => `vlan${String(id)}`;
+
+/** A VLAN's color, from its number, so `vlan10` has the same color on every switch and area. */
+const VLAN_COLORS = ["#7048e8", "#2f9e44", "#1971c2", "#e8590c", "#e03131", "#0c8599", "#c2255c", "#5c940d"];
+export function vlanColor(id: number): string {
+  return VLAN_COLORS[Math.abs(Math.round(id / 10)) % VLAN_COLORS.length];
+}
+
+/** A trunk port's look: striped with the colors of the VLANs it carries (muted when none). */
+export function trunkStripes(vlans: { id: number }[]): string {
+  if (!vlans.length) return "var(--muted)";
+  const stripes = vlans.map((v, i) => `${vlanColor(v.id)} ${String(i * 5)}px ${String((i + 1) * 5)}px`).join(", ");
+  return `repeating-linear-gradient(135deg, ${stripes})`;
+}
+
+/** The VLAN number in a LAN's name (`vlan10` -> 10), when the LAN is a VLAN. */
+export function vlanOf(lanName: string): number | null {
+  const m = /^vlan(\d{1,4})$/.exec(lanName);
+  return m ? Number(m[1]) : null;
+}
+
+/** The port a switch handle stands for: `p3` -> its index, `trunk` -> the trunk. */
+function switchPort(handle: string | null | undefined): number | typeof TRUNK | null {
+  if (handle === TRUNK) return TRUNK;
+  const m = handle ? /^p(\d+)$/.exec(handle) : null;
+  return m ? Number(m[1]) - 1 : null;
+}
+
+/** Whether a switch handle is a trunk: the T port, or any port set to "trunk". */
+export function isTrunkPort(sw: SwitchNode, handle: string | null | undefined): boolean {
+  const port = switchPort(handle);
+  return port === TRUNK || (typeof port === "number" && sw.data.ports[port] === TRUNK);
+}
+
+/** The VLAN of an access port, or null (a trunk, an unassigned port, not a port). */
+export function accessVlan(sw: SwitchNode, handle: string | null | undefined): number | null {
+  const port = switchPort(handle);
+  const mode = typeof port === "number" ? sw.data.ports[port] : null;
+  return typeof mode === "number" ? mode : null;
+}
+
+/** A port's label next to its cable: 1, 2… or T. */
+export function switchPortLabel(handle: string | null | undefined): string {
+  const p = switchPort(handle);
+  if (p === TRUNK) return "T";
+  return p === null ? "" : String(p + 1);
+}
+
+/**
+ * The LAN each switch's VLANs belong to in isoloom.yml: switches joined by a cable, or sharing a
+ * VLAN number (VLANs are lab-wide here), are one LAN, named after the first. Returns a switch's
+ * LAN name by its id.
+ */
+export function switchLans(nodes: LabNode[], edges: CableEdge[]): (switchId: string) => string {
+  const switches = nodes.filter(isSwitch);
+  const group = new Map(switches.map((s) => [s.id, s.id]));
+  const root = (id: string): string => {
+    const up = group.get(id);
+    return up === undefined || up === id ? id : root(up);
+  };
+  const unite = (a: string, b: string) => group.set(root(a), root(b));
+  for (const e of edges) if (group.has(e.source) && group.has(e.target)) unite(e.source, e.target);
+  const firstWith = new Map<number, string>();
+  for (const sw of switches) {
+    for (const v of sw.data.vlans) {
+      const other = firstWith.get(v.id);
+      if (other) unite(sw.id, other);
+      else firstWith.set(v.id, sw.id);
+    }
+  }
+  return (id: string) => switches.find((s) => root(s.id) === root(id))?.data.name ?? "";
+}
+
+/** The name Isoloom gives a trunk's interface: its LAN's, within Linux's limit (`sw1`, then `sw1.10`). */
+export const trunkInterface = (lan: string) => lan.slice(0, 10).replace(/-+$/, "");

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/model.ts

@@ -0,0 +1,13 @@
+/**
+ * The editor's lab model and conversions, with no React: a lab's nodes and cables, the topology the
+ * engine reads, and helpers to lay a topology out again. Used by hosts that work with labs outside
+ * the canvas (the website's MCP server builds and reads topologies with these).
+ */
+export * from "@/lib/tool/model";
+export { type Topology, type LaidOut, draftFromTopology } from "@/lib/tool/layout";
+export { toTopology } from "@/lib/tool/topology";
+export { PORT_PROTOCOLS, readPorts, portsText, type Service } from "@/lib/tool/ports";
+export { exampleLab, vlanExample } from "@/lib/tool/examples";
+export { planOf, ownFiles, type Engine, type Plan, type GeneratedFile } from "@/lib/tool/engine";
+export { groupByTarget, type Target, type TargetText } from "@/lib/tool/export-targets";
+export { canvasIssues, type IssueText } from "@/lib/tool/issues";

package/src/test/arbitrary.ts

@@ -0,0 +1,41 @@
+import fc from "fast-check";
+import { DESIGNS, type Draft, type LinkConditions } from "@/lib/tool/model";
+import { cable, lan, machine } from "./lab";
+
+/**
+ * fast-check generators for the editor model's property tests: the values the editor itself
+ * writes, so a property holds for every lab someone can draw.
+ */
+
+/** A positive number up to `max`, as a field edit keeps one (see `withCondition`). */
+const positive = (max: number) => fc.double({ min: 0, max, minExcluded: true, noNaN: true });
+
+/** Conditions as the editor writes them: a delay (a jitter only varies one), a loss up to 100%, a rate in whole kbit/s. */
+export const arbitraryConditions: fc.Arbitrary<LinkConditions> = fc.record(
+  { delay: positive(1e6), jitter: positive(1e6), loss: positive(100), rate: fc.integer({ min: 1, max: 10_000_000 }).map((kbit) => kbit / 1000) },
+  { requiredKeys: ["delay"] },
+);
+
+/** A node to draw: a LAN (with its conditions) or a machine. */
+const arbitraryNode = fc.record({ id: fc.stringMatching(/^[a-z][a-z0-9-]{0,7}$/), lan: fc.boolean(), tc: fc.option(arbitraryConditions, { nil: undefined }) });
+
+/** A cable between the `from`th and the `to`th node (modulo their count), with its ports and maybe conditions. */
+const arbitraryCable = fc.record({ from: fc.nat(), to: fc.nat(), aPort: fc.string(), bPort: fc.string(), tc: fc.option(arbitraryConditions, { nil: undefined }) });
+
+/** A lab as the editor draws one: LANs and machines, and cables between them, each colored for the canvas. */
+export const arbitraryLab: fc.Arbitrary<Draft> = fc
+  .record({
+    name: fc.string(),
+    design: fc.constantFrom(undefined, ...DESIGNS),
+    nodes: fc.uniqueArray(arbitraryNode, { selector: (n) => n.id, minLength: 1, maxLength: 6 }),
+    cables: fc.array(arbitraryCable, { maxLength: 8 }),
+  })
+  .map(({ name, design, nodes, cables }) => ({
+    name,
+    design,
+    nodes: nodes.map((n) => (n.lan ? lan(n.id, { tc: n.tc }) : machine(n.id))),
+    edges: cables.map((c, i) => {
+      const [source, target] = [nodes[c.from % nodes.length].id, nodes[c.to % nodes.length].id];
+      return cable(`c${String(i)}`, source, target, { aPort: c.aPort, bPort: c.bPort, tc: c.tc, color: "#000" });
+    }),
+  }));

package/src/test/engine.ts

@@ -0,0 +1,48 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * The engine the package ships (`wasm/`), loaded in Node for the tests: Isoloom itself, so the
+ * editor's model is checked against what Isoloom accepts, not against a copy of its rules.
+ */
+
+/** The engine's functions the tests call. */
+export interface TestEngine {
+  plan_json(topology: string): string;
+  choices_json(): string;
+}
+
+type EngineModule = TestEngine & { initSync(options: { module: Buffer }): unknown };
+
+function isEngineModule(mod: unknown): mod is EngineModule {
+  if (typeof mod !== "object" || mod === null) return false;
+  return ["initSync", "plan_json", "choices_json"].every((name) => typeof (mod as Record<string, unknown>)[name] === "function");
+}
+
+let loading: Promise<TestEngine> | null = null;
+
+/** The shipped engine, started once for the test file. */
+export function shippedEngine(): Promise<TestEngine> {
+  loading ??= (async () => {
+    const dir = join(process.cwd(), "wasm");
+    const mod: unknown = await import(pathToFileURL(join(dir, "isothrum_wasm.js")).href);
+    if (!isEngineModule(mod)) throw new Error("wasm/isothrum_wasm.js is not the Isothrum engine with choices_json");
+    mod.initSync({ module: readFileSync(join(dir, "isothrum_wasm_bg.wasm")) });
+    return mod;
+  })();
+  return loading;
+}
+
+/** What Isoloom's engine says of a topology: its problems, or the error that stopped it. */
+export interface Verdict {
+  ok: boolean;
+  error: string | null;
+  problems: string[];
+  isoloom_yml: string | null;
+}
+
+/** The engine's verdict on `topology`. */
+export async function verdict(topology: unknown): Promise<Verdict> {
+  return JSON.parse((await shippedEngine()).plan_json(JSON.stringify(topology))) as Verdict;
+}

package/src/test/lab.ts

@@ -0,0 +1,101 @@
+import type { CableData, CableEdge, LabNode, LanData, LanNode, MachineData, MachineNode, NoteNode, SwitchNode } from "@/lib/tool/model";
+import type { IssueText } from "@/lib/tool/issues";
+import { toTopology } from "@/lib/tool/topology";
+
+/**
+ * Builders for the editor model's tests: small labs, each node given only what the test is about.
+ * A node's name defaults to its id.
+ */
+
+type At = { x: number; y: number };
+
+/** A container machine (nginx), unless `data` says otherwise. */
+export function machine(id: string, data: Partial<MachineData> = {}, position: At = { x: 0, y: 0 }): MachineNode {
+  return {
+    id,
+    type: "machine",
+    position,
+    data: { name: id, kind: "container", icon: "container", image: "nginx:1.27-alpine", os: "", provision: "", ports: "", access: false, ...data },
+  };
+}
+
+/** An automatic router (the kind that is no machine). */
+export const autoRouter = (id: string, position: At = { x: 0, y: 0 }): MachineNode => machine(id, { kind: "router", icon: "router", image: "" }, position);
+
+/** A router you configure (FRR in a container): drawn with ports. */
+export const realRouter = (id: string, position: At = { x: 0, y: 0 }, data: Partial<MachineData> = {}): MachineNode =>
+  machine(id, { icon: "router", image: "frrouting/frr:v8.5.2", ...data }, position);
+
+/** A LAN area at `area` (400 by 300 at the origin by default). */
+export function lan(id: string, data: Partial<LanData> = {}, area: Partial<{ x: number; y: number; w: number; h: number }> = {}): LanNode {
+  const { x = 0, y = 0, w = 400, h = 300 } = area;
+  return { id, type: "lan", position: { x, y }, width: w, height: h, data: { name: id, cidr: "10.10.1.0/24", internet: true, ...data } };
+}
+
+/** A switch: vlan10 on ports 1 and 2, vlan20 on port 3, port 4 a trunk, the rest unassigned. */
+export function switchNode(id: string, data: Partial<SwitchNode["data"]> = {}, position: At = { x: 0, y: 0 }): SwitchNode {
+  return {
+    id,
+    type: "switch",
+    position,
+    data: {
+      name: id,
+      vlans: [
+        { id: 10, cidr: "10.10.10.0/24" },
+        { id: 20, cidr: "10.10.20.0/24" },
+      ],
+      ports: [10, 10, 20, "trunk", null, null, null, null],
+      ...data,
+    },
+  };
+}
+
+export const note = (id: string, position: At = { x: 0, y: 0 }): NoteNode => ({
+  id,
+  type: "note",
+  position,
+  width: 200,
+  height: 90,
+  data: { text: "remember", shape: "rect", color: "yellow" },
+});
+
+/** A cable's ends and labels: handles default to none, ports to eth0 on both ends. */
+type CableOptions = { sourceHandle?: string | null; targetHandle?: string | null } & Partial<CableData>;
+
+export function cable(id: string, source: string, target: string, options: CableOptions = {}): CableEdge {
+  const { sourceHandle = null, targetHandle = null, ...data } = options;
+  return { id, type: "cable", source, sourceHandle, target, targetHandle, data: { aPort: "eth0", bPort: "eth0", ...data } };
+}
+
+/** The node of `nodes` with id `id` (a test failure when there is none). */
+export function byId<T extends LabNode>(nodes: T[], id: string): T {
+  const found = nodes.find((n) => n.id === id);
+  if (!found) throw new Error(`no node ${id}`);
+  return found;
+}
+
+/** The canvas's findings in plain words, so tests can read them. */
+export const issueText: IssueText = {
+  vlanBlocks: (vlan, block, other, sw) => `${vlan}: ${block} vs ${other} on ${sw}`,
+  areaBlock: (lan, block, switches) => `area ${lan}: ${block} vs ${switches}`,
+  noName: { machine: "unnamed machine", lan: "unnamed lan", switch: "unnamed switch" },
+  sameName: { machine: (n) => `two machines ${n}`, lan: (n) => `two lans ${n}`, switch: (n) => `two switches ${n}` },
+  badPort: (m, entry) => `${m}: port ${entry}`,
+};
+
+/** A compiled lab: `toTopology`'s JSON, parsed. */
+export interface Compiled {
+  name: string;
+  nodes: Record<string, { kind: Record<string, unknown>; access: boolean; services: { port: number; protocol?: string }[]; networks: Record<string, number | null> }>;
+  networks: Record<string, { cidr: string; internet: boolean; tc?: unknown; switch?: string; vlan?: number }>;
+  links: { a: { node: string; port: string }; b: { node: string; port: string }; tc?: unknown }[];
+}
+
+/** The lab as the engine reads it. */
+export const compile = (nodes: LabNode[], edges: CableEdge[] = [], name = "lab"): Compiled => JSON.parse(toTopology(name, nodes, edges)) as Compiled;
+
+/** The networks the VLANs of a switch named sw1 become: `switchNode("sw1")`'s, and the VLAN example's. */
+export const sw1Networks: Compiled["networks"] = {
+  vlan10: { cidr: "10.10.10.0/24", internet: true, switch: "sw1", vlan: 10 },
+  vlan20: { cidr: "10.10.20.0/24", internet: true, switch: "sw1", vlan: 20 },
+};

package/styles/globals.css

@@ -0,0 +1,258 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "./theme.css";
+@plugin "@tailwindcss/typography";
+
+/* The unit tests and their helpers are never rendered: their strings aren't classes. */
+@source not "../src/**/*.test.ts";
+@source not "../src/test";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  /* Typography — font files are loaded in lib/fonts.ts */
+  --font-sans: var(--font-brand-sans), ui-sans-serif, system-ui, sans-serif;
+  --font-mono: var(--font-brand-mono), ui-monospace, SFMono-Regular, monospace;
+  --font-heading: var(--font-brand-heading, var(--font-brand-sans)), ui-sans-serif, system-ui, sans-serif;
+
+  /* Semantic colors — values live in theme.css */
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-surface: var(--surface);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-signal: var(--signal);
+  --color-signal-foreground: var(--signal-foreground);
+  --color-pastel-blue: var(--pastel-blue);
+  --color-pastel-green: var(--pastel-green);
+  --color-pastel-yellow: var(--pastel-yellow);
+  --color-pastel-violet: var(--pastel-violet);
+  --color-pastel-red: var(--pastel-red);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-link: var(--link);
+  --color-destructive: var(--destructive);
+  --color-success: var(--success);
+  --color-warning: var(--warning);
+  --color-info: var(--info);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+
+  /* Brand scale as utilities: bg-brand-50, text-brand-700, … */
+  --color-brand-50: var(--brand-50);
+  --color-brand-100: var(--brand-100);
+  --color-brand-200: var(--brand-200);
+  --color-brand-300: var(--brand-300);
+  --color-brand-400: var(--brand-400);
+  --color-brand-500: var(--brand-500);
+  --color-brand-600: var(--brand-600);
+  --color-brand-700: var(--brand-700);
+  --color-brand-800: var(--brand-800);
+  --color-brand-900: var(--brand-900);
+  --color-brand-950: var(--brand-950);
+
+  /* Radius scale, derived from --radius */
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+  html {
+    @apply font-sans;
+    font-feature-settings: var(--font-features);
+    text-rendering: optimizeLegibility;
+  }
+  h1,
+  h2,
+  h3,
+  h4 {
+    font-family: var(--font-heading);
+    letter-spacing: -0.02em;
+    text-wrap: balance;
+  }
+  ::selection {
+    background-color: color-mix(in oklab, var(--primary) 20%, transparent);
+  }
+  /* Stable scrollbar gutter to avoid CLS when content overflows */
+  html {
+    scrollbar-gutter: stable;
+  }
+}
+
+/*
+ * Map Tailwind Typography's palette onto the theme tokens so article text,
+ * links and quotes follow theme.css in both light and dark mode (no need for
+ * `dark:prose-invert`).
+ */
+.prose {
+  --tw-prose-body: color-mix(in oklab, var(--foreground) 85%, transparent);
+  --tw-prose-headings: var(--foreground);
+  --tw-prose-lead: var(--muted-foreground);
+  --tw-prose-links: var(--link);
+  --tw-prose-bold: var(--foreground);
+  --tw-prose-counters: var(--muted-foreground);
+  --tw-prose-bullets: var(--border);
+  --tw-prose-hr: var(--border);
+  --tw-prose-quotes: var(--foreground);
+  --tw-prose-quote-borders: var(--primary);
+  --tw-prose-captions: var(--muted-foreground);
+  --tw-prose-kbd: var(--foreground);
+  --tw-prose-code: var(--foreground);
+  --tw-prose-th-borders: var(--border);
+  --tw-prose-td-borders: var(--border);
+  --tw-prose-invert-body: var(--tw-prose-body);
+  --tw-prose-invert-headings: var(--tw-prose-headings);
+  --tw-prose-invert-lead: var(--tw-prose-lead);
+  --tw-prose-invert-links: var(--tw-prose-links);
+  --tw-prose-invert-bold: var(--tw-prose-bold);
+  --tw-prose-invert-counters: var(--tw-prose-counters);
+  --tw-prose-invert-bullets: var(--tw-prose-bullets);
+  --tw-prose-invert-hr: var(--tw-prose-hr);
+  --tw-prose-invert-quotes: var(--tw-prose-quotes);
+  --tw-prose-invert-quote-borders: var(--tw-prose-quote-borders);
+  --tw-prose-invert-captions: var(--tw-prose-captions);
+  --tw-prose-invert-code: var(--tw-prose-code);
+  --tw-prose-invert-th-borders: var(--tw-prose-th-borders);
+  --tw-prose-invert-td-borders: var(--tw-prose-td-borders);
+}
+.prose :where(a):not(:where([class~="not-prose"] *)) {
+  text-underline-offset: 3px;
+  text-decoration-thickness: 1px;
+  text-decoration-color: color-mix(in oklab, var(--link) 40%, transparent);
+  transition: text-decoration-color 150ms;
+}
+.prose :where(a):not(:where([class~="not-prose"] *)):hover {
+  text-decoration-color: var(--link);
+}
+
+/*
+ * Inline code styling. Tailwind Typography wraps inline `<code>` with
+ * literal backticks via ::before/::after — we remove those and replace
+ * the default look with a quiet background pill so file paths and command
+ * names visually pop from prose without competing with editorial links.
+ *
+ * `:not(pre code)` keeps fenced code blocks (`<pre><code>`) untouched so
+ * any syntax highlighter (e.g. Shiki via rehype-pretty-code) keeps its
+ * token colors and background.
+ */
+.prose :where(code):not(:where([class~="not-prose"] *, pre code)) {
+  background-color: var(--muted);
+  color: var(--foreground);
+  padding: 0.125rem 0.375rem;
+  border-radius: 0.25rem;
+  font-weight: 500;
+  font-size: 0.875em;
+  word-break: break-word;
+}
+.prose :where(code):not(:where([class~="not-prose"] *))::before,
+.prose :where(code):not(:where([class~="not-prose"] *))::after {
+  content: none;
+}
+
+/*
+ * Respect prefers-reduced-motion (WCAG 2.3.3): near-instantly resolve any
+ * animation/transition and disable smooth scrolling for users who opt out of
+ * motion. Applies site-wide to the theme-toggle icon swap, the reading-progress
+ * bar, tw-animate-css, and any future motion.
+ */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  ::before,
+  ::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* Long paths, URLs and inline code must wrap on phones (no horizontal page scroll). */
+.prose {
+  overflow-wrap: break-word;
+}
+.prose :where(code):not(:where(pre code)),
+.prose :where(a) {
+  overflow-wrap: anywhere;
+}
+.prose :where(table) {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+/*
+ * Mobile overflow guards. Grid items default to min-width:auto, so one long
+ * title, badge row or table can push a column past the viewport; long
+ * unbreakable strings (paths, URLs, registry keys) spill out of their box.
+ * Code blocks keep white-space:pre and still scroll inside their own box.
+ */
+@layer base {
+  body {
+    overflow-wrap: break-word;
+  }
+  .grid > * {
+    min-width: 0;
+  }
+}
+
+/* Cap the layout width with a token instead of the per-breakpoint default. */
+@utility container {
+  max-width: min(100%, var(--content-width)) !important;
+}
+
+/*
+ * Decorative backgrounds for marketing sections. Built only from tokens, so
+ * they follow theme.css and dark mode. Usage: <div className="bg-grid" />.
+ */
+/* The editor's canvas: a dot grid, so the site and the product share one surface. */
+@utility bg-grid {
+  background-image: radial-gradient(
+    circle at 1px 1px,
+    color-mix(in oklab, var(--foreground) 16%, transparent) 1px,
+    transparent 0
+  );
+  background-size: 22px 22px;
+  mask-image: radial-gradient(ellipse 70% 60% at 50% 0%, #000 40%, transparent 100%);
+}
+/* A soft white wash from the top, so the hero reads as light rather than flat. */
+@utility bg-glow {
+  background-image: radial-gradient(
+    ellipse 60% 50% at 50% 0%,
+    color-mix(in oklab, var(--background) 90%, transparent),
+    transparent
+  );
+}