@wenathlan/foundry 2.0.94 → 2.0.118

package/package.json

@@ -1,18 +1,26 @@
 {
   "name": "@wenathlan/foundry",
-  "version": "2.0.94",
+  "version": "2.0.118",
   "description": "foundry is the e2b and docker clone interface of the wenathlan family: it drives sandboxes and images while the engine lives in saddle, and ships the documentation set and the tests directory as one package",
   "type": "module",
-  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wenathlan/devthink"
+  },
   "license": "GPL-3.0-only",
   "author": "Wenathlan",
   "sideEffects": false,
   "scripts": {
     "dev": "vite --host",
     "build": "vite build",
-    "start": "vite preview --host",
+    "check": "tsc --noEmit",
+    "lint": "biome check .",
     "preview": "vite preview --host",
-    "check": "tsc --noEmit"
+    "restore:entry": "node -e \"const{readFileSync}=require('node:fs');const{execSync}=require('node:child_process');const script=/script[^>]*App\\.tsx/;const triad=/family=Inter[\\s\\S]*Geist\\+Mono/;const face=(h)=>script.test(h)&&triad.test(h);if(face(readFileSync('index.html','utf8'))){console.log('index.html already rides the source face');process.exit(0)}if(!face(execSync('git show HEAD:./index.html',{encoding:'utf8'}))){console.error('refusing: HEAD index.html is not the canonical source face yet (script App.tsx + the font triad) - land the source-face fix first; nothing was touched');process.exit(1)}execSync('git checkout -- index.html',{stdio:'inherit'});console.log('index.html restored from HEAD (the source face)')\"",
+    "start": "vite preview --host",
+    "test": "node --test \"tests/*.test.ts\"",
+    "test:watch": "node --test --watch \"tests/*.test.ts\"",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@hono/node-server": "^2.1.3",
@@ -35,7 +43,22 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=26.8.1 <27"
+    "bare": "^1.18.0",
+    "bun": "^1.4.2",
+    "chrome": "^16.0.912",
+    "cnpm": "^9.4.0",
+    "corepack": "^0.35.0",
+    "deno": "^2.9.5",
+    "ecmascript": "^5.0.0",
+    "firefox": ">=0.8.0",
+    "iojs": "^1.0.0",
+    "node": "^26.8.2",
+    "npm": "^12.1.0",
+    "pnpm": "^12.6.0",
+    "teleport": ">=0.2.0",
+    "typescript": "^5.8.0",
+    "vscode": "^1.118.0",
+    "yarn": "^4.17.1"
   },
   "publishConfig": {
     "access": "public"
@@ -46,6 +69,7 @@
     "@capacitor/cli": "^8.5.2",
     "@capacitor/core": "^8.5.2",
     "@capacitor/ios": "^8.5.2",
+    "@fluentui/react-icons": "^2.0.344",
     "@hookform/resolvers": "^5.9.1",
     "@libsql/client": "^0.18.0",
     "@opencode-ai/sdk": "^1.18.34",
@@ -129,5 +153,10 @@
     "yaml": "^2.9.1",
     "zod": "^4.6.5"
   },
-  "packageManager": "pnpm@12.3.4"
+  "packageManager": "pnpm@12.3.4",
+  "pnpm": {
+    "neverBuiltDependencies": [
+      "ssh2"
+    ]
+  }
 }

package/tests/artifact.test.ts

@@ -0,0 +1,106 @@
+// # artifact.test — the checksum engine of the /artifacts page, runnable
+// with the node built-in runner (no dependencies, no install):
+//   node --test tests/artifact.test.ts
+// The seal is the proof: fnv-1a (32-bit) over the canonical identity string,
+// rendered as 8 hex, byte-stable in node and in the browser — pinned here
+// against the canonical FNV-1a vectors.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  type Artifact,
+  artifactIdentity,
+  artifactLine,
+  fnv1a,
+  fnv1aHex,
+  manifest,
+  sealArtifact,
+  seedArtifacts,
+  utf8Bytes,
+  verifyArtifact,
+} from "../artifact.ts";
+
+describe("fnv-1a", () => {
+  it("answers the canonical vectors", () => {
+    assert.equal(fnv1a(""), 0x811c9dc5);
+    assert.equal(fnv1a("a"), 0xe40c292c);
+    assert.equal(fnv1a("foobar"), 0xbf9cf968);
+  });
+
+  it("renders the 8-hex digest zero-padded", () => {
+    assert.equal(fnv1aHex(""), "811c9dc5");
+    assert.equal(fnv1aHex("a"), "e40c292c");
+    assert.match(fnv1aHex("any identity"), /^[0-9a-f]{8}$/);
+  });
+
+  it("encodes utf-8 bytes (the multibyte path stays byte-exact)", () => {
+    assert.deepEqual(utf8Bytes("a"), [0x61]);
+    assert.deepEqual(utf8Bytes("ã"), [0xc3, 0xa3]);
+    assert.deepEqual(utf8Bytes("★"), [0xe2, 0x98, 0x85]);
+    assert.deepEqual(utf8Bytes("𝄞"), [0xf0, 0x9d, 0x84, 0x9e]);
+    assert.equal(fnv1a("ã"), fnv1a("ã")); // stable across calls
+    assert.notEqual(fnv1a("ã"), fnv1a("a"));
+  });
+
+  it("differs for differing identities (spot check over 24 inputs)", () => {
+    const digests = new Set<string>();
+    for (let i = 0; i < 24; i++) digests.add(fnv1aHex(`artifact-${i}`));
+    assert.ok(digests.size >= 23, `too many collisions: ${digests.size}`);
+  });
+});
+
+describe("the seal", () => {
+  it("builds the canonical identity string", () => {
+    assert.equal(artifactIdentity("base", "tzst", 4096, "rev-1"), "base · .tzst · 4096 · rev-1");
+    assert.equal(artifactIdentity("runtime", "targz", 10, ""), "runtime · .tar.gz · 10 · ");
+  });
+
+  it("seals the same artifact twice byte-equal (deterministic)", () => {
+    const a = sealArtifact("base-01", "tzst", 40_000_000, "rev-2026-02-14");
+    const b = sealArtifact("base-01", "tzst", 40_000_000, "rev-2026-02-14");
+    assert.deepEqual(a, b);
+  });
+
+  it("seals differing payloads into differing checksums", () => {
+    const a = sealArtifact("base-01", "tzst", 40_000_000, "rev-1");
+    const b = sealArtifact("base-01", "tzst", 40_000_000, "rev-2");
+    assert.notEqual(a.checksum, b.checksum);
+  });
+
+  it("derives the id from the checksum", () => {
+    const artifact = sealArtifact("pack-09", "tarxz", 1_000_000);
+    assert.equal(artifact.id, `art-${artifact.checksum}`);
+  });
+
+  it("re-verifies a sealed artifact (the seal is the proof)", () => {
+    const artifact = sealArtifact("tool-02", "targz", 88_000_000, "rev-x");
+    assert.equal(verifyArtifact(artifact), true);
+    const tampered: Artifact = { ...artifact, checksum: "deadbeef" };
+    assert.equal(verifyArtifact(tampered), false);
+  });
+});
+
+describe("the packaging line", () => {
+  it("replays the same line from the same seed", () => {
+    assert.deepEqual(seedArtifacts(804613), seedArtifacts(804613));
+  });
+
+  it("seals one artifact per herd format", () => {
+    const line = seedArtifacts(804613);
+    assert.equal(line.length, 3);
+    assert.deepEqual(
+      line.map((artifact) => artifact.format),
+      ["tzst", "targz", "tarxz"],
+    );
+  });
+
+  it("renders the manifest line and joins the manifest", () => {
+    const line = seedArtifacts(804613);
+    const rendered = artifactLine(line[0]);
+    assert.match(rendered, /^base-\w+\.tzst · [\d,]+ b · fnv-1a [0-9a-f]{8}$/);
+    assert.equal(manifest(line), line.map((artifact) => artifactLine(artifact)).join("\n"));
+  });
+
+  it("answers an empty manifest for an empty line", () => {
+    assert.equal(manifest([]), "");
+  });
+});

package/tests/design.test.ts

@@ -0,0 +1,177 @@
+// # design.test — the design contract of the foundry surface, runnable with
+// the node built-in runner (no dependencies, no install):
+//   node --test tests/design.test.ts
+// The file reads the shipped sources (css, entry face, brand mark, app
+// identity) and pins the family laws of the reform wave: no banned hue, no
+// pill, no transition:all, the trylle type triad, the source-face entry,
+// the azul identity under the windows hands and the honest page set of the
+// application identity.
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { describe, it } from "node:test";
+
+function read(path: string): string {
+  return readFileSync(new URL(path, import.meta.url), "utf8");
+}
+
+const CSS = read("../Sol/sol.css");
+const ENTRY = read("../index.html");
+const MARK = read("../Sol/shell/BrandMark.tsx");
+const SHELL = read("../Sol/shell/Shell.tsx");
+const TOML = read("../devthink.toml");
+const SOL = read("../Sol/Sol.tsx");
+
+const BANNED = [/3b82f6/i, /2563eb/i, /f97316/i];
+
+/** strips the windows pin keyframe — the one sanctioned scale(0) entrance —
+ * so the floor law can be asserted on everything else. */
+function cssWithoutPinIntro(source: string): string {
+  return source.replace(/@keyframes dtPopIntro \{[\s\S]*?\n\}/, "");
+}
+
+describe("design contract", () => {
+  it("ships no banned hue in the stylesheet, the entry or the mark", () => {
+    for (const source of [CSS, ENTRY, MARK]) {
+      for (const banned of BANNED) {
+        assert.ok(!banned.test(source), `banned hue ${banned} found`);
+      }
+    }
+  });
+
+  it("keeps the azul identity and the windows accent in their lanes", () => {
+    assert.match(CSS, /--sol-primary: #4d8edd/, "the azul identity token stands");
+    assert.match(CSS, /--win-accent: #4cc2ff/, "the windows accent governs focus and the bar cta");
+    assert.match(CSS, /--win-accent: #0067c0/, "the light theme follows the windows light law");
+    assert.match(MARK, /#2fb8b5/, "the drawn mark keeps its têmpera story");
+  });
+
+  it("retires the abandoned pipeline blue and the molten amber identities", () => {
+    assert.ok(!/1e6ff2/i.test(CSS + ENTRY), "the pipeline blue is gone");
+    assert.ok(!/d97706|b45309|f59e0b/i.test(CSS + ENTRY), "the molten amber is gone");
+  });
+
+  it("wears the têmpera identity on the icons and the manifest", () => {
+    const FAVICON = read("../favicon.svg");
+    const ICON = read("../icon.svg");
+    const MANIFEST = read("../manifest.webmanifest");
+    for (const [name, source] of [
+      ["favicon.svg", FAVICON],
+      ["icon.svg", ICON],
+    ] as const) {
+      assert.ok(!/1e6ff2|1447a8/.test(source), `${name} still rides the pipeline blue`);
+    }
+    assert.match(ICON, /#2fb8b5|#4fd6d2|#1f7d7b/, "the icon rides the têmpera family");
+    assert.match(FAVICON, /#2fb8b5/, "the favicon rides the têmpera family");
+    assert.match(MANIFEST, /"theme_color": "#2fb8b5"/, "the manifest theme color is the têmpera");
+    assert.match(MANIFEST, /"background_color": "#0a1210"/, "the manifest background is the fornalha base");
+    assert.match(ENTRY, /theme-color" content="#0a0a0b"/, "the entry theme color is the trylle canvas");
+  });
+
+  it("keeps the pill out of the stylesheet (no 999px, no stadium radius)", () => {
+    assert.ok(!CSS.includes("999px"), "the pill radius is retired");
+    assert.ok(!CSS.includes("--r-pill"), "no pill token survives");
+  });
+
+  it("never ships transition: all", () => {
+    assert.ok(!/transition:\s*all/.test(CSS), "transition: all is a reprovação");
+  });
+
+  it("never enters from scale(0) outside the windows pin law", () => {
+    // the ONE sanctioned scale(0) entrance is the dtPopIntro pin bounce —
+    // the windows recipe (0 → 1.125 → 0.725 → 1); everything else floors
+    assert.ok(/@keyframes dtPopIntro/.test(CSS), "the windows pin entrance stands");
+    assert.ok(!/scale\(0\)/.test(cssWithoutPinIntro(CSS)), "scale(0) outside dtPopIntro is a reprovação");
+  });
+
+  it("declares the trylle type triad (Inter Variable surfaces, Geist Mono numbers)", () => {
+    assert.match(CSS, /"Inter Variable"/);
+    assert.match(CSS, /"Geist Mono Variable"/);
+    assert.match(ENTRY, /family=Inter/);
+    assert.match(ENTRY, /Geist\+Mono/);
+  });
+
+  it("keeps the entry on the source face (./App.tsx, no hashed ghosts)", () => {
+    assert.match(ENTRY, /script[^>]*\.\/App\.tsx/);
+    assert.ok(!/-[0-9a-f]{8}\.(js|css)/.test(ENTRY), "no hashed bundle rides the entry");
+    assert.match(ENTRY, /href="\.\/favicon\.svg"/);
+  });
+
+  it("guards the reduced-motion stop on every layer", () => {
+    const blocks = CSS.match(/@media \(prefers-reduced-motion: reduce\)/g) ?? [];
+    assert.ok(blocks.length >= 4, `expected the hard stop on every layer, found ${blocks.length}`);
+  });
+
+  it("wears the windows hands on the shell (press law, pin entrance, resize, inactive)", () => {
+    assert.match(CSS, /dtPopIntro/, "the pin entrance keyframe stands");
+    assert.match(SHELL, /RESIZE_EDGES/, "the eight resize handles mount");
+    assert.match(CSS, /win-rz\[data-edge="se"\]/, "the resize handles ride the frame edges");
+    assert.match(CSS, /grayscale\(80%\)/, "the inactive window law stands");
+    assert.match(CSS, /rgb\(232 17 35\)/, "the close caption wears the windows red");
+  });
+
+  it("declares the honest page set (home, sandboxes, images, artifacts, notfound)", () => {
+    assert.match(TOML, /pages = \["home", "sandboxes", "images", "artifacts", "notfound"\]/);
+    for (const route of ['"/sandboxes"', '"/images"', '"/artifacts"', '"/404"']) {
+      assert.ok(SOL.includes(`path=${route}`), `route ${route} must mount`);
+    }
+  });
+
+  it("mounts the flow law (intro and onboarding open the route table)", () => {
+    assert.match(SOL, /path="\/intro"/);
+    assert.match(SOL, /path="\/onboarding"/);
+    assert.ok(SOL.indexOf('"/intro"') < SOL.indexOf('"/"'), "the entry flow opens the route table");
+  });
+
+  it("carries the flow contract sources (the entry gate behind the home anchor)", () => {
+    const GATE = read("../Sol/home/entrygate.tsx");
+    const HOME = read("../Sol/home/home.tsx");
+    const INTRO = read("../Sol/intro/intro.tsx");
+    const ONBOARDING = read("../Sol/onboarding/onboarding.tsx");
+    assert.match(GATE, /navigate\("\/intro"/, "an unseen intro navigates to the splash");
+    assert.match(GATE, /navigate\("\/onboarding"/, "an unseen onboarding navigates to the walk");
+    assert.match(HOME, /EntryGate/, "the home anchor consults the gate");
+    assert.match(INTRO, /markIntroSeen/, "the intro marks introseen");
+    assert.match(INTRO, /\/onboarding/, "the intro hands DIRECTLY to the walk");
+    assert.match(ONBOARDING, /markOnboardingSeen/, "the onboarding marks onboardingseen");
+  });
+
+  it("catalogues the seen state on the database, not just the browser", () => {
+    const PRISMA = read("../schema.prisma");
+    const DB = read("../db.ts");
+    const STATE = read("../onboardingstate.ts");
+    assert.match(PRISMA, /model OnboardingState \{/, "the prisma model stands");
+    assert.match(PRISMA, /introseen\s+Boolean/);
+    assert.match(PRISMA, /onboardingseen\s+Boolean/);
+    assert.match(DB, /onboarding_states/, "the sqlite mirror exists");
+    assert.match(DB, /getOnboardingState/, "the reader accessor exists");
+    assert.match(DB, /setOnboardingStage/, "the writer accessor exists");
+    assert.doesNotMatch(DB, /["']\s*\+\s*(visitor|stage)\b/, "no concatenated sql rides the accessors");
+    assert.match(STATE, /foundry\.onboarding\.seen/, "the localStorage cache mirrors the db");
+    assert.match(STATE, /\/api\/v1\/onboarding/, "the accessor rides the platform route");
+  });
+
+  it("keeps tabular numerals on the platform numbers", () => {
+    assert.match(CSS, /font-variant-numeric:\s*tabular-nums/);
+  });
+
+  it("rests the title-bar mark on the landing (logo discipline)", () => {
+    assert.match(CSS, /data-landing/);
+    assert.ok(SHELL.includes("data-landing"), "the shell carries the landing attribute");
+  });
+
+  it("runs the family flow signature inside the mark strokes", () => {
+    assert.match(MARK, /fdMarkFlow/, "the flow layer exists on the foundry mark");
+    assert.match(MARK, /fdm-flow/, "the flow gradient is declared");
+    assert.match(
+      MARK,
+      /prefers-reduced-motion: reduce[\s\S]*\.fdMarkFlow \{ opacity: 0/,
+      "the flow hard-stops on reduced motion",
+    );
+  });
+
+  it("links the family row from the one table (zero drift between chrome and landing)", () => {
+    assert.match(SHELL, /from "\.\.\/\.\.\/family"/, "the shell reads family.ts");
+    const HOME = read("../Sol/home/home.tsx");
+    assert.match(HOME, /familyrow/, "the landing footer reads the same table");
+  });
+});

package/tests/family.test.ts

@@ -0,0 +1,104 @@
+// # family.test — the family table the chrome rides, runnable with the node
+// built-in runner (no dependencies, no install):
+//   node --test tests/family.test.ts
+// Every test watches the promise the row makes: the nine siblings beside
+// foundry are listed once, every slug resolves through the familyurl
+// contract into a climb-one-level url, every member carries the spec §12
+// accent with its own dot ink, and no accent ever collides with the banned
+// palette.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { FAMILY_ACCENTS, FAMILY_SLUGS, familyAccentOf, familyrow } from "../family.ts";
+import { familyurl } from "../familyurl.ts";
+
+const BANNED = new Set(["#3b82f6", "#2563eb", "#f97316"]);
+
+describe("family table", () => {
+  it("lists the nine siblings beside foundry, never foundry itself", () => {
+    assert.deepEqual(FAMILY_SLUGS, [
+      "devthink",
+      "cadria",
+      "stealthhead",
+      "debonair",
+      "argan",
+      "saddle",
+      "forge",
+      "vault",
+      "getry",
+    ]);
+    assert.ok(!FAMILY_SLUGS.includes("foundry"));
+  });
+
+  it("answers an accent for every listed sibling", () => {
+    for (const slug of FAMILY_SLUGS) {
+      const member = FAMILY_ACCENTS[slug];
+      assert.ok(member, `${slug} must carry an accent`);
+      assert.equal(member.slug, slug);
+      assert.match(member.accent, /^#[0-9a-fA-F]{6}$/);
+      assert.match(member.dotInk, /^#[0-9a-fA-F]{6}$/);
+    }
+    assert.deepEqual(Object.keys(FAMILY_ACCENTS).sort(), [
+      "argan",
+      "cadria",
+      "debonair",
+      "devthink",
+      "forge",
+      "foundry",
+      "getry",
+      "saddle",
+      "stealthhead",
+      "vault",
+    ]);
+  });
+
+  it("keeps the spec §12 accents stable, verbatim", () => {
+    assert.equal(FAMILY_ACCENTS.devthink.accent, "#F59E0B");
+    assert.equal(FAMILY_ACCENTS.argan.accent, "#34d8a8");
+    assert.equal(FAMILY_ACCENTS.cadria.accent, "#f472b6");
+    assert.equal(FAMILY_ACCENTS.debonair.accent, "#d9962e");
+    assert.equal(FAMILY_ACCENTS.forge.accent, "#a2cb3a");
+    assert.equal(FAMILY_ACCENTS.foundry.accent, "#2fb8b5");
+    assert.equal(FAMILY_ACCENTS.getry.accent, "#8b5cf6");
+    assert.equal(FAMILY_ACCENTS.saddle.accent, "#e86f2d");
+    assert.equal(FAMILY_ACCENTS.stealthhead.accent, "#e8563f");
+    assert.equal(FAMILY_ACCENTS.vault.accent, "#a3d7e6");
+  });
+
+  it("keeps the spec accent-ink column stable", () => {
+    assert.equal(FAMILY_ACCENTS.forge.dotInk, "#161d03");
+    assert.equal(FAMILY_ACCENTS.foundry.dotInk, "#03211f");
+    assert.equal(FAMILY_ACCENTS.vault.dotInk, "#072330");
+  });
+
+  it("resolves every member through the familyurl contract", () => {
+    for (const slug of FAMILY_SLUGS) {
+      assert.equal(familyurl(slug), `../${slug}/`);
+    }
+  });
+
+  it("never ships a banned hue in the row or the table", () => {
+    for (const member of [...familyrow(), ...Object.values(FAMILY_ACCENTS)]) {
+      assert.ok(!BANNED.has(member.accent.toLowerCase()), `${member.slug} rides a banned accent`);
+    }
+  });
+
+  it("builds the rail row in slug order without gaps", () => {
+    const row = familyrow();
+    assert.equal(row.length, FAMILY_SLUGS.length);
+    assert.deepEqual(
+      row.map((member) => member.slug),
+      [...FAMILY_SLUGS],
+    );
+  });
+
+  it("answers familyAccentOf for the house and falls back for unknowns", () => {
+    assert.equal(familyAccentOf("foundry")?.accent, "#2fb8b5");
+    assert.equal(familyAccentOf("forge")?.accent, "#a2cb3a");
+    assert.equal(familyAccentOf("nope"), undefined);
+  });
+
+  it("keeps the familyurl contract on the climb-one-level shape", () => {
+    assert.equal(familyurl("cadria"), "../cadria/");
+    assert.equal(familyurl("/cadria/"), "../cadria/");
+  });
+});

package/tests/imagestore.test.ts

@@ -0,0 +1,109 @@
+// # imagestore.test — the herd format engine of the /images page, runnable
+// with the node built-in runner (no dependencies, no install):
+//   node --test tests/imagestore.test.ts
+// The three real clone formats (.tzst / .tar.gz / .tar.xz), the honest
+// conversion plans (always through the tar layer) and the size estimates.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  convertPlan,
+  estimateSize,
+  FORMATS,
+  formatBytes,
+  formatFromExt,
+  formatOf,
+  pourOrder,
+  seedImages,
+} from "../imagestore.ts";
+
+describe("the formats", () => {
+  it("answers the three real clone formats in floor order", () => {
+    assert.deepEqual(
+      FORMATS.map((format) => format.ext),
+      [".tzst", ".tar.gz", ".tar.xz"],
+    );
+    assert.deepEqual(pourOrder(), FORMATS);
+  });
+
+  it("resolves formats by id and by extension", () => {
+    assert.equal(formatOf("tzst")?.ext, ".tzst");
+    assert.equal(formatOf("tarxz")?.label, "the release herd");
+    assert.equal(formatFromExt(".tar.gz")?.id, "targz");
+    assert.equal(formatFromExt(".TAR.GZ")?.id, "targz");
+    assert.equal(formatOf("nope"), undefined);
+    assert.equal(formatFromExt(".zip"), undefined);
+  });
+});
+
+describe("the conversion plan", () => {
+  it("always goes through the tar layer, never a direct recompress", () => {
+    const plan = convertPlan("tzst", "tarxz");
+    assert.equal(plan.from.id, "tzst");
+    assert.equal(plan.to.id, "tarxz");
+    assert.match(plan.steps[0], /unpack the \.tzst layer down to the tar stream/);
+    assert.match(plan.steps[1], /recompress the tar stream into \.tar\.xz/);
+    assert.match(plan.steps[2], /checksum/);
+  });
+
+  it("answers a one-line no-op plan for the same format", () => {
+    const plan = convertPlan("targz", "targz");
+    assert.equal(plan.steps.length, 1);
+    assert.match(plan.steps[0], /no conversion/);
+  });
+
+  it("builds a plan for every ordered pair of distinct formats", () => {
+    for (const from of FORMATS) {
+      for (const to of FORMATS) {
+        const plan = convertPlan(from.id, to.id);
+        assert.ok(plan.steps.length >= 1);
+        if (from.id !== to.id) assert.equal(plan.steps.length, 3);
+      }
+    }
+  });
+});
+
+describe("the estimates", () => {
+  it("orders the compress shares: xz smallest, gzip the middle", () => {
+    const bytes = 1_000_000_000;
+    const tzst = estimateSize(bytes, "tzst");
+    const targz = estimateSize(bytes, "targz");
+    const tarxz = estimateSize(bytes, "tarxz");
+    assert.ok(tarxz < tzst, "xz rides smaller than zstd");
+    assert.ok(tzst < targz, "zstd rides smaller than gzip");
+    assert.ok(tarxz > 0 && targz < bytes);
+  });
+
+  it("answers zero for empty and negative streams", () => {
+    assert.equal(estimateSize(0, "tzst"), 0);
+    assert.equal(estimateSize(-5, "tarxz"), 0);
+  });
+
+  it("scales linearly with the stream size", () => {
+    assert.equal(estimateSize(2_000_000, "tzst"), estimateSize(1_000_000, "tzst") * 2);
+  });
+});
+
+describe("the shelf", () => {
+  it("replays the same shelf from the same seed", () => {
+    assert.deepEqual(seedImages(314159, 6), seedImages(314159, 6));
+  });
+
+  it("shelves unique ids on real formats with positive sizes", () => {
+    const shelf = seedImages(8, 12);
+    assert.equal(new Set(shelf.map((image) => image.id)).size, 12);
+    for (const image of shelf) {
+      assert.ok(FORMATS.some((format) => format.id === image.format));
+      assert.ok(image.tarBytes > 0);
+    }
+  });
+});
+
+describe("the byte counts", () => {
+  it("renders the tabular human units", () => {
+    assert.equal(formatBytes(512), "512 B");
+    assert.equal(formatBytes(1024), "1.0 KB");
+    assert.equal(formatBytes(1_500_000), "1.4 MB");
+    assert.equal(formatBytes(2_300_000_000), "2.1 GB");
+    assert.equal(formatBytes(0), "0 B");
+  });
+});

package/tests/sandbox.test.ts

@@ -0,0 +1,162 @@
+// # sandbox.test — the sandbox state machine of the /sandboxes page,
+// runnable with the node built-in runner (no dependencies, no install):
+//   node --test tests/sandbox.test.ts
+// The machine never lies: the ladder is cold → warm → hot with the cooling
+// paths back, every refusal is an honest string, the herd replays from the
+// seed and the census counts exactly.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  canTransition,
+  drive,
+  herdCensus,
+  mulberry32,
+  refusalFor,
+  SANDBOX_STATES,
+  type Sandbox,
+  seedHerd,
+  step,
+} from "../sandbox.ts";
+
+/** one hand-built sandbox */
+function boxOf(patch: Partial<Sandbox>): Sandbox {
+  return { id: "fdy-test-01", name: "sandbox-test", state: "cold", image: "base.tzst", boots: 0, steps: 0, ...patch };
+}
+
+describe("the machine", () => {
+  it("keeps the three-state ladder cold → warm → hot", () => {
+    assert.deepEqual(SANDBOX_STATES, ["cold", "warm", "hot"]);
+  });
+
+  it("allows the boot path and the cooling paths", () => {
+    assert.equal(canTransition("cold", "warm"), true);
+    assert.equal(canTransition("warm", "hot"), true);
+    assert.equal(canTransition("warm", "cold"), true);
+    assert.equal(canTransition("hot", "warm"), true);
+    assert.equal(canTransition("hot", "cold"), true);
+  });
+
+  it("refuses the impossible moves", () => {
+    assert.equal(canTransition("cold", "hot"), false);
+    assert.equal(canTransition("cold", "cold"), false);
+    assert.equal(canTransition("hot", "hot"), false);
+  });
+
+  it("answers honest refusals with the reason", () => {
+    assert.match(refusalFor("cold", "hot"), /warm it first/);
+    assert.match(refusalFor("warm", "warm"), /already warm/);
+    assert.match(refusalFor("hot", "hot"), /already hot/);
+  });
+});
+
+describe("drive", () => {
+  it("warms a cold sandbox and counts the boot", () => {
+    const box = boxOf({});
+    const answer = drive(box, "warm");
+    assert.equal(answer.refusal, undefined);
+    assert.equal(answer.sandbox.state, "warm");
+    assert.equal(answer.sandbox.boots, 1);
+    assert.equal(answer.sandbox.steps, 0);
+  });
+
+  it("refuses to warm an already warm sandbox (no double boot)", () => {
+    const box = boxOf({ state: "warm", boots: 2 });
+    const answer = drive(box, "warm");
+    assert.match(answer.refusal ?? "", /already warm/);
+    assert.equal(answer.sandbox.boots, 2);
+  });
+
+  it("heats a warm sandbox into hot", () => {
+    const answer = drive(boxOf({ state: "warm" }), "heat");
+    assert.equal(answer.sandbox.state, "hot");
+  });
+
+  it("cools a hot sandbox back to warm (working set kept)", () => {
+    const box = boxOf({ state: "hot", boots: 3, steps: 12 });
+    const answer = drive(box, "cool");
+    assert.equal(answer.sandbox.state, "warm");
+    assert.equal(answer.sandbox.boots, 3);
+  });
+
+  it("freezes back to cold and tears the working set down", () => {
+    const box = boxOf({ state: "hot", boots: 3, steps: 12 });
+    const answer = drive(box, "freeze");
+    assert.equal(answer.sandbox.state, "cold");
+    assert.equal(answer.sandbox.boots, 0);
+    assert.equal(answer.sandbox.steps, 0);
+  });
+
+  it("never mutates the input sandbox", () => {
+    const box = boxOf({ state: "warm" });
+    const frozen = JSON.parse(JSON.stringify(box)) as Sandbox;
+    drive(box, "heat");
+    drive(box, "freeze");
+    assert.deepEqual(box, frozen);
+  });
+});
+
+describe("step", () => {
+  it("counts a step only on a hot sandbox", () => {
+    const hot = boxOf({ state: "hot", steps: 5 });
+    assert.equal(step(hot).sandbox.steps, 6);
+  });
+
+  it("refuses steps on cold and warm with the honest line", () => {
+    assert.match(step(boxOf({ state: "cold" })).refusal ?? "", /heat it first/);
+    assert.match(step(boxOf({ state: "warm" })).refusal ?? "", /only a hot sandbox/);
+  });
+});
+
+describe("the rehearsal herd", () => {
+  it("replays the same herd from the same seed", () => {
+    assert.deepEqual(seedHerd(620221, 7), seedHerd(620221, 7));
+  });
+
+  it("herds unique ids with valid states and images", () => {
+    const herd = seedHerd(9, 30);
+    assert.equal(new Set(herd.map((box) => box.id)).size, 30);
+    for (const box of herd) {
+      assert.ok(SANDBOX_STATES.includes(box.state));
+      assert.match(box.image, /\.(tzst|tar\.gz|tar\.xz)$/);
+      assert.ok(box.boots >= 0 && box.steps >= 0);
+    }
+  });
+
+  it("keeps cold boxes honest: no boots, no steps", () => {
+    for (const box of seedHerd(1234, 60).filter((entry) => entry.state === "cold")) {
+      assert.equal(box.boots, 0);
+      assert.equal(box.steps, 0);
+    }
+  });
+});
+
+describe("the census", () => {
+  it("counts the ladder exactly and derives the warm share", () => {
+    const herd = [
+      boxOf({ id: "a", state: "cold" }),
+      boxOf({ id: "b", state: "warm" }),
+      boxOf({ id: "c", state: "warm" }),
+      boxOf({ id: "d", state: "hot" }),
+    ];
+    const census = herdCensus(herd);
+    assert.equal(census.total, 4);
+    assert.equal(census.byState.cold, 1);
+    assert.equal(census.byState.warm, 2);
+    assert.equal(census.byState.hot, 1);
+    assert.equal(census.warmShare, 0.75);
+  });
+
+  it("answers zero shares on an empty room", () => {
+    const census = herdCensus([]);
+    assert.equal(census.total, 0);
+    assert.equal(census.warmShare, 0);
+  });
+});
+
+describe("prng", () => {
+  it("mulberry32 is deterministic across calls", () => {
+    const a = mulberry32(620221);
+    const b = mulberry32(620221);
+    for (let i = 0; i < 16; i++) assert.equal(a(), b());
+  });
+});