@wenathlan/stealthhead 2.0.94 → 2.0.117

package/README.md

@@ -15,3 +15,18 @@ pnpm install
 pnpm dev
 ```
 
+## The family contract (wave 7-a)
+
+- `family.ts` — the one table of the spec §12 accents (argan jade, cadria rosa, debonair latão, forge lime-brasa, foundry têmpera, getry violeta, saddle ember, vault gelo) and the sibling slugs in rail order; the chrome rail foot and the landing footer both render it, and `tests/family.test.ts` pins it (8 cases).
+- `familyurl.ts` — the relative sibling-link contract (`"../" + slug + "/"`, verbatim body); `familyurl(slug)` survives any mount point without trusting a build constant.
+- `tests/design.test.ts` — 12 design-contract cases: the coral `#f4694f` as the one signal (stylesheet alias and mark story alike), the windows accent `#4cc2ff` on focus and the chrome, zero banned hue (`#3B82F6` / `#2563EB` / `#F97316`), zero pill (no `999px`, no `--r-pill`), zero `transition: all`, zero `scale(0)` entries, the trylle font pair (Inter Variable reading, Geist Mono detail), the source-face entry, the reduced-motion hard stop, tabular numerals, the landing logo discipline (`data-landing`), the sticky-footer law and the honest page set of `devthink.toml`.
+
+## Entry face and `restore:entry`
+
+`index.html` is kept permanently on the SOURCE face: `./App.tsx` script, `./favicon.svg`, `./manifest.webmanifest` and the font triad `<link>`. The Vite build emits hashed bundles (`index-*.js`, `index-*.css`, `favicon-*.svg`, `manifest-*.webmanifest`…) beside it for the pages workflow — every family is barred by `.gitignore`, so the tree keeps the source face only. After a local build, run:
+
+```bash
+npm run restore:entry
+```
+
+The script is a GUARD, not a blind checkout: if the working tree already rides the source face it is a no-op; if `HEAD` still carries a pre-triad (hashed or triad-less) face it REFUSES with exit 1 — it never revives a stale face over the fix. Land the source-face commit first, and from then on the guard restores the canonical face after any local build.

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@wenathlan/stealthhead",
-  "version": "2.0.94",
+  "version": "2.0.117",
   "repository": {
     "type": "git",
     "url": "https://github.com/wenathlan/devthink"
   },
-  "description": "stealthhead is the FPS game platform of the wenathlan family: it imports versawase from cadria and audio from debonair via the published library, with no engine file of its own — only game logics (match, ranking, weapons, world). The envelope distributes the documentation set and the tests directory as one package.",
+  "description": "stealthhead is the FPS game platform of the wenathlan family: it imports versawase from cadria and audio from debonair via the published library, with no engine file of its own \u2014 only game logics (match, ranking, weapons, world). The envelope distributes the documentation set and the tests directory as one package.",
   "keywords": [
     "stealthhead",
     "fps",
@@ -16,6 +16,24 @@
     "documentation"
   ],
   "license": "GPL-3.0-only",
+  "engines": {
+    "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"
+  },
   "type": "module",
   "scripts": {
     "dev": "vite --host",
@@ -23,7 +41,9 @@
     "start": "vite preview --host",
     "preview": "vite preview --host",
     "check": "tsc --noEmit",
-    "test": "vitest run"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "restore:entry": "node -e \"const{readFileSync}=require('node:fs');const{execSync}=require('node:child_process');const script=/script[^>]*App\\.tsx/;const triad=/family=Bricolage\\+Grotesque[\\s\\S]*Outfit[\\s\\S]*JetBrains\\+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)')\""
   },
   "dependencies": {
     "@hono/node-server": "^2.1.3",

package/tests/design.test.ts

@@ -0,0 +1,160 @@
+// # design.test — the design contract of the stealthhead surface, runnable
+//   with the vitest runner:
+//   npm test
+// The file reads the shipped sources (stylesheet, entry face, brand mark,
+// app identity, route anchor, icons) and pins the family laws of the reform
+// wave: no banned hue, no pill, no all-properties transition, no zero-scale
+// entry (the windows dtPopIntro bounce excepted), the trylle font stacks,
+// the source-face entry, the reduced-motion stop, tabular numerals, the
+// sticky-footer law, the honest page set of the application identity, the
+// first-run flow contract (the entry gate, the shared onboarding state, the
+// db mirror) and the trylle-canvas/windows-hands foundation.
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+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 SHELL = read("../Sol/shell/Shell.tsx");
+const MARK = read("../Sol/shell/BrandMark.tsx");
+const TOML = read("../devthink.toml");
+const SOL = read("../Sol/Sol.tsx");
+const FAVICON = read("../favicon.svg");
+const ICON = read("../icon.svg");
+const MANIFEST = read("../manifest.webmanifest");
+
+const BANNED = [/3b82f6/i, /2563eb/i, /f97316/i];
+
+describe("design contract", () => {
+  it("ships no banned hue in the stylesheet, the entry, the mark or the icons", () => {
+    for (const source of [CSS, ENTRY, MARK, FAVICON, ICON, MANIFEST]) {
+      for (const banned of BANNED) {
+        expect(banned.test(source), `banned hue ${banned} found`).toBe(false);
+      }
+    }
+  });
+
+  it("carries the stealthhead coral #f4694f as the identity accent and the windows accent on the chrome", () => {
+    expect(CSS).toMatch(/--sh-accent: #f4694f/);
+    expect(MARK).toMatch(/#f4694f/);
+    // the windows hands: focus and the chrome speak the windows accent
+    expect(CSS).toMatch(/--win-accent: #4cc2ff/);
+    expect(CSS).toMatch(/outline: 2px solid var\(--win-accent\)/);
+  });
+
+  it("keeps the pill out of the stylesheet (no 999px, no stadium radius)", () => {
+    expect(CSS.includes("999px"), "the pill radius is retired").toBe(false);
+    expect(CSS.includes("--r-pill"), "no pill token survives").toBe(false);
+  });
+
+  it("never ships an all-properties transition", () => {
+    expect(/transition:\s*all/.test(CSS), "transition: all is a reprovação").toBe(false);
+  });
+
+  it("never enters an element from zero scale (the windows dtPopIntro bounce excepted)", () => {
+    const sansPopIntro = CSS.replace(/@keyframes dtPopIntro \{[\s\S]*?\n\}/g, "");
+    expect(
+      /scale\(0\)/.test(sansPopIntro),
+      "scale(0) entries are a reprovação (the dtPopIntro bounce of the windows recipe excepted)",
+    ).toBe(false);
+  });
+
+  it("declares the trylle font stacks (Inter reading, Geist Mono detail) and the 13px body", () => {
+    expect(CSS).toMatch(/--font-sans: "Inter Variable"/);
+    expect(CSS).toMatch(/--font-mono: "Geist Mono Variable"/);
+    expect(ENTRY).toMatch(/family=Inter/);
+    expect(ENTRY).toMatch(/Geist\+Mono/);
+    expect(CSS).toMatch(/font-size: 13px/);
+    expect(CSS).toMatch(/font-weight: 450/);
+  });
+
+  it("keeps the entry on the source face (./App.tsx, canonical assets, no hashed ghosts)", () => {
+    expect(ENTRY).toMatch(/script[^>]*\.\/App\.tsx/);
+    expect(/-[0-9a-f]{8}\.(js|css)/.test(ENTRY), "no hashed bundle rides the entry").toBe(false);
+    expect(ENTRY).toMatch(/href="\.\/favicon\.svg"/);
+    expect(ENTRY).toMatch(/href="\.\/manifest\.webmanifest"/);
+  });
+
+  it("guards the reduced-motion stop on every layer (the hard stop last)", () => {
+    const blocks = CSS.match(/@media \(prefers-reduced-motion: reduce\)/g) ?? [];
+    expect(blocks.length >= 4, `expected the hard stop on every layer, found ${blocks.length}`).toBe(true);
+    const hardStopAt = CSS.lastIndexOf("@media (prefers-reduced-motion: reduce)");
+    expect(CSS.slice(hardStopAt)).toMatch(/0\.01ms !important/);
+    expect(CSS.slice(hardStopAt + 1)).not.toMatch(/@media/);
+  });
+
+  it("keeps tabular numerals on the platform numbers", () => {
+    expect(CSS).toMatch(/font-variant-numeric:\s*tabular-nums/);
+  });
+
+  it("rests the title-bar mark on the landing (logo discipline)", () => {
+    expect(CSS).toMatch(/data-landing/);
+    expect(SHELL).toMatch(/data-landing/);
+  });
+
+  it("pins the footer to the window floor (the sticky-footer law)", () => {
+    expect(CSS).toMatch(/\.winapp__stage > main\.shell \{[^}]*flex-direction: column/);
+    expect(CSS).toMatch(/\.shquad \{[^}]*margin-top: auto/s);
+  });
+
+  it("declares the honest page set (home, match, ranking, weapons, world, notfound)", () => {
+    expect(TOML).toMatch(/pages = \["home", "match", "ranking", "weapons", "world", "notfound"\]/);
+    for (const route of ['"/match"', '"/ranking"', '"/weapons"', '"/world"', '"/404"']) {
+      expect(SOL.includes(`path=${route}`), `route ${route} must mount`).toBe(true);
+    }
+  });
+
+  it("keeps the entry flow mounted (intro, onboarding) before the fundamentals", () => {
+    expect(SOL).toMatch(/path="\/intro"/);
+    expect(SOL).toMatch(/path="\/onboarding"/);
+    expect(SOL.indexOf('"/intro"')).toBeLessThan(SOL.indexOf('"/"'));
+  });
+
+  it("carries the flow contract sources (the entry gate behind the home anchor, the shared state module)", () => {
+    const GATE = read("../Sol/home/entrygate.tsx");
+    const STATE = read("../onboardingstate.ts");
+    const HOME = read("../Sol/home/home.tsx");
+    const ONBOARDING = read("../Sol/onboarding/onboarding.tsx");
+    expect(GATE).toMatch(/navigate\("\/intro"/);
+    expect(GATE).toMatch(/navigate\("\/onboarding"/);
+    expect(HOME).toMatch(/EntryGate/);
+    expect(ONBOARDING).toMatch(/markOnboardingStage/);
+    expect(STATE).toMatch(/stealthhead\.onboarding\.seen/);
+    expect(STATE).toMatch(/\/api\/v1\/onboarding/);
+  });
+
+  it("catalogues the first-run state in the db layer (prisma model + sqlite mirror)", () => {
+    const PRISMA = read("../schema.prisma");
+    const DB = read("../db.ts");
+    expect(PRISMA).toMatch(/model OnboardingState \{/);
+    expect(PRISMA).toMatch(/introseen\s+Boolean\s+@default\(false\)/);
+    expect(PRISMA).toMatch(/onboardingseen\s+Boolean\s+@default\(false\)/);
+    expect(DB).toMatch(/create table if not exists onboardingstate/);
+    expect(DB).toMatch(/getonboardingstate/);
+    expect(DB).toMatch(/setonboardingstage/);
+  });
+
+  it("wears the windows hands on the chrome (resize handles, inactive law, red close, dtPopIntro)", () => {
+    expect(CSS).toMatch(/winapp__rz\[data-edge="se"\]/);
+    expect(CSS).toMatch(/grayscale\(80%\)/);
+    expect(CSS).toMatch(/rgb\(232, 17, 35\)/);
+    expect(CSS).toMatch(/rgb\(139, 10, 20\)/);
+    expect(CSS).toMatch(/@keyframes dtPopIntro/);
+    expect(SHELL).toMatch(/data-inactive/);
+    expect(SHELL).toMatch(/winapp__rz/);
+  });
+
+  it("rides the trylle foundation (canvas, surfaces, hairlines, linear shadow ladder)", () => {
+    expect(CSS).toMatch(/--sol-canvas: #0a0a0b/);
+    expect(CSS).toMatch(/--sol-canvas-deep: #060607/);
+    expect(CSS).toMatch(/--sol-ink: #fafafa/);
+    expect(CSS).toMatch(/--sol-surface-8: #484848/);
+    expect(CSS).toMatch(/color-mix\(in oklab, var\(--sol-ink\) 5%, transparent\)/);
+    expect(CSS).toMatch(/0 96px 96px -48px/);
+    expect(CSS).toMatch(/cubic-bezier\(0\.22, 1, 0\.36, 1\)/);
+    expect(CSS).toMatch(/--sol-micro: 150ms/);
+  });
+});

package/tests/family.test.ts

@@ -0,0 +1,81 @@
+// # family.test — the family table the chrome rides, runnable with the
+// vitest runner:
+//   npm test
+// Every test watches the promise the row makes: the eight siblings beside
+// stealthhead 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 "vitest";
+import { FAMILY_ACCENTS, FAMILY_SLUGS, familyrow } from "../family.ts";
+import { familyurl } from "../familyurl.ts";
+
+const BANNED = new Set(["#3b82f6", "#2563eb", "#f97316"]);
+
+describe("family table", () => {
+  it("lists the eight siblings beside stealthhead, never stealthhead itself", () => {
+    assert.deepEqual(FAMILY_SLUGS, ["argan", "cadria", "debonair", "forge", "foundry", "getry", "saddle", "vault"]);
+    assert.ok(!FAMILY_SLUGS.includes("stealthhead"));
+    assert.ok(!FAMILY_SLUGS.includes("devthink"));
+  });
+
+  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-f]{6}$/);
+      assert.match(member.dotInk, /^#[0-9a-f]{6}$/);
+    }
+    // the table holds exactly the siblings — no orphan accents
+    assert.deepEqual(Object.keys(FAMILY_ACCENTS).sort(), [...FAMILY_SLUGS].sort());
+  });
+
+  it("resolves every member through the familyurl contract", () => {
+    for (const slug of FAMILY_SLUGS) {
+      assert.equal(familyurl(slug), `../${slug}/`);
+    }
+  });
+
+  it("strips decorative slashes and normalizes the slug", () => {
+    assert.equal(familyurl("/cadria/"), "../cadria/");
+    assert.equal(familyurl("  getry  "), "../  getry  /");
+  });
+
+  it("keeps the spec §12 accents stable", () => {
+    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.vault.accent, "#a3d7e6");
+  });
+
+  it("never ships a banned hue in the row", () => {
+    for (const member of familyrow()) {
+      assert.ok(!BANNED.has(member.accent), `${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("keeps every dot ink readable on its own accent (the ink is darker)", () => {
+    for (const member of familyrow()) {
+      const lum = (hex: string): number => {
+        const channel = (offset: number) => Number.parseInt(hex.slice(offset, offset + 2), 16) / 255;
+        return 0.2126 * channel(1) + 0.7152 * channel(3) + 0.0722 * channel(5);
+      };
+      assert.ok(lum(member.dotInk) < lum(member.accent), `${member.slug} dot ink must be darker than its accent`);
+    }
+  });
+});

package/tests/onboardingstate.test.ts

@@ -0,0 +1,62 @@
+// # onboardingstate.test — the pure contract of the seen flags: the host
+//   validation of the platform base (https only, public hosts only) and the
+//   seen-wins stage merge the accessor and the pages share. runnable with
+//   vitest: pnpm vitest run tests/onboardingstate.test.ts
+import assert from "node:assert/strict";
+import { describe, it } from "vitest";
+import { hostallowed, mergeStage } from "../onboardingstate.ts";
+
+describe("onboarding state", () => {
+  it("accepts public https bases", () => {
+    assert.equal(hostallowed("https://gateway.wenathlan.dev"), true);
+    assert.equal(hostallowed("https://gateway.wenathlan.dev/"), true);
+    assert.equal(hostallowed("https://stealthhead.example.com:8443"), true);
+  });
+
+  it("refuses plaintext, localhost, loopback and every private or reserved range", () => {
+    const refused = [
+      "http://gateway.wenathlan.dev",
+      "https://localhost",
+      "https://localhost:8787",
+      "https://app.localhost",
+      "https://box.local",
+      "https://service.internal",
+      "https://127.0.0.1",
+      "https://0.0.0.0",
+      "https://10.0.0.9",
+      "https://172.16.0.1",
+      "https://172.31.255.255",
+      "https://192.168.1.4",
+      "https://169.254.10.10",
+      "https://100.64.0.1",
+      "https://192.0.2.7",
+      "https://198.51.100.7",
+      "https://203.0.113.9",
+      "https://[::1]",
+      "https://[::ffff:127.0.0.1]",
+      "https://[fd00::1]",
+      "https://[fe80::1]",
+      "not a url",
+      "",
+    ];
+    for (const base of refused) assert.equal(hostallowed(base), false, base);
+  });
+
+  it("merges stages seen-wins — a stage never unsees", () => {
+    const fresh = { introseen: false, onboardingseen: false };
+    assert.deepEqual(mergeStage(fresh, "intro"), { introseen: true, onboardingseen: false });
+    assert.deepEqual(mergeStage(fresh, "onboarding"), { introseen: false, onboardingseen: true });
+    const half = { introseen: true, onboardingseen: false };
+    assert.deepEqual(mergeStage(half, "onboarding"), { introseen: true, onboardingseen: true });
+    assert.deepEqual(mergeStage(mergeStage(half, "onboarding"), "intro"), {
+      introseen: true,
+      onboardingseen: true,
+    });
+  });
+
+  it("never mutates the state it merges", () => {
+    const state = { introseen: false, onboardingseen: false };
+    mergeStage(state, "intro");
+    assert.deepEqual(state, { introseen: false, onboardingseen: false });
+  });
+});