decklight 0.1.0

package/docs/architecture.svg

@@ -0,0 +1,94 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 920 560" font-family="-apple-system, 'Segoe UI', Roboto, Helvetica, sans-serif">
+  <defs>
+    <marker id="arr" markerWidth="9" markerHeight="7" refX="8" refY="3.5" orient="auto">
+      <polygon points="0 0, 9 3.5, 0 7" fill="#8b90a3"/>
+    </marker>
+    <marker id="arrb" markerWidth="9" markerHeight="7" refX="8" refY="3.5" orient="auto">
+      <polygon points="0 0, 9 3.5, 0 7" fill="#7c9cff"/>
+    </marker>
+  </defs>
+
+  <rect x="0" y="0" width="920" height="560" rx="14" fill="#14161d"/>
+  <text x="460" y="34" text-anchor="middle" font-size="17" font-weight="700" fill="#e8eaf2">Decklight — how it's put together</text>
+
+  <!-- ── authoring column ─────────────────────────────────────────── -->
+  <rect x="40" y="70" width="230" height="86" rx="10" fill="#24335c" stroke="#46567f" stroke-width="1.5"/>
+  <text x="155" y="100" text-anchor="middle" font-size="14" font-weight="700" fill="#e8eaf2">deck.html</text>
+  <text x="155" y="120" text-anchor="middle" font-size="10.5" fill="#aeb4c6">sections · notes · inline casts</text>
+  <text x="155" y="136" text-anchor="middle" font-size="10.5" fill="#aeb4c6">one file, written by humans &amp; agents</text>
+
+  <rect x="40" y="186" width="230" height="72" rx="10" fill="#23444d" stroke="#3f6a76" stroke-width="1.5"/>
+  <text x="155" y="212" text-anchor="middle" font-size="13" font-weight="700" fill="#e8eaf2">theme.css — 61 shipped</text>
+  <text x="155" y="232" text-anchor="middle" font-size="10.5" fill="#aeb4c6">one token contract (~50 vars)</text>
+  <text x="155" y="246" text-anchor="middle" font-size="10.5" fill="#aeb4c6">+ runtime generator (⌃T)</text>
+
+  <!-- ── browser runtime ──────────────────────────────────────────── -->
+  <rect x="330" y="70" width="330" height="240" rx="12" fill="#191c26" stroke="#7c9cff" stroke-width="2"/>
+  <text x="495" y="96" text-anchor="middle" font-size="13.5" font-weight="700" fill="#7c9cff">browser runtime — zero dependencies</text>
+  <text x="495" y="112" text-anchor="middle" font-size="10" fill="#8b90a3">dist/decklight.js + decklight.css · works on file://</text>
+
+  <g font-size="10.5" fill="#dfe3ee">
+    <rect x="348" y="126" width="140" height="30" rx="6" fill="#252a3a"/><text x="418" y="145" text-anchor="middle">engine · builds · nav</text>
+    <rect x="500" y="126" width="142" height="30" rx="6" fill="#252a3a"/><text x="571" y="145" text-anchor="middle">themes · generator</text>
+    <rect x="348" y="164" width="140" height="30" rx="6" fill="#252a3a"/><text x="418" y="183" text-anchor="middle">terminal player</text>
+    <rect x="500" y="164" width="142" height="30" rx="6" fill="#252a3a"/><text x="571" y="183" text-anchor="middle">markdown · svg · code</text>
+    <rect x="348" y="202" width="140" height="30" rx="6" fill="#252a3a"/><text x="418" y="221" text-anchor="middle">narration · captions</text>
+    <rect x="500" y="202" width="142" height="30" rx="6" fill="#252a3a"/><text x="571" y="221" text-anchor="middle">speaker · overlays</text>
+    <rect x="348" y="240" width="294" height="30" rx="6" fill="#252a3a"/><text x="495" y="259" text-anchor="middle">quiz slides · transcript · debug log · edit mode</text>
+  </g>
+  <text x="495" y="296" text-anchor="middle" font-size="10" fill="#8b90a3">every feature verifiable by a headless render</text>
+
+  <!-- ── local servers ────────────────────────────────────────────── -->
+  <rect x="710" y="70" width="180" height="76" rx="10" fill="#274035" stroke="#43695a" stroke-width="1.5"/>
+  <text x="800" y="96" text-anchor="middle" font-size="13" font-weight="700" fill="#e8eaf2">decklight edit</text>
+  <text x="800" y="114" text-anchor="middle" font-size="10.5" fill="#aeb4c6">watches the file · SSE reload</text>
+  <text x="800" y="130" text-anchor="middle" font-size="10.5" fill="#aeb4c6">E saves notes back to disk</text>
+
+  <rect x="710" y="176" width="180" height="70" rx="10" fill="#4a3057" stroke="#75548a" stroke-width="1.5"/>
+  <text x="800" y="202" text-anchor="middle" font-size="13" font-weight="700" fill="#e8eaf2">decklight tts</text>
+  <text x="800" y="220" text-anchor="middle" font-size="10.5" fill="#aeb4c6">sentence cache · cost estimates</text>
+  <text x="800" y="236" text-anchor="middle" font-size="10.5" fill="#aeb4c6">localhost bridge</text>
+
+  <rect x="710" y="276" width="180" height="52" rx="10" fill="#20232e" stroke="#3a3f52" stroke-width="1.5" stroke-dasharray="5 4"/>
+  <text x="800" y="298" text-anchor="middle" font-size="12" font-weight="700" fill="#c9cede">Vertex AI · Gemini TTS</text>
+  <text x="800" y="316" text-anchor="middle" font-size="10" fill="#8b90a3">30 voices · styled delivery</text>
+
+  <!-- ── cli row ──────────────────────────────────────────────────── -->
+  <rect x="40" y="356" width="620" height="86" rx="10" fill="#52402a" stroke="#7d6544" stroke-width="1.5"/>
+  <text x="350" y="382" text-anchor="middle" font-size="13" font-weight="700" fill="#e8eaf2">CLI — node, the only place with native deps</text>
+  <g font-size="10.5" fill="#efe9dd">
+    <rect x="58" y="396" width="130" height="30" rx="6" fill="#453722"/><text x="123" y="415" text-anchor="middle">rec — real PTY casts</text>
+    <rect x="200" y="396" width="130" height="30" rx="6" fill="#453722"/><text x="265" y="415" text-anchor="middle">refresh — drift check</text>
+    <rect x="342" y="396" width="140" height="30" rx="6" fill="#453722"/><text x="412" y="415" text-anchor="middle">export — asciicast v2</text>
+    <rect x="494" y="396" width="148" height="30" rx="6" fill="#453722"/><text x="568" y="415" text-anchor="middle">bundle — one-file deck</text>
+  </g>
+
+  <!-- ── verification band ────────────────────────────────────────── -->
+  <rect x="40" y="470" width="850" height="60" rx="10" fill="#1c2620" stroke="#39584a" stroke-width="1.5"/>
+  <text x="465" y="494" text-anchor="middle" font-size="12.5" font-weight="700" fill="#9fd6b4">verification — SPEC.md is the contract</text>
+  <text x="465" y="514" text-anchor="middle" font-size="10.5" fill="#8fae9c">WCAG contrast gates · R1–R8 palette rules · headless render assertions · property tests across seeds · data-overflow guardrail</text>
+
+  <!-- ── arrows ───────────────────────────────────────────────────── -->
+  <line x1="270" y1="113" x2="324" y2="140" stroke="#8b90a3" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="270" y1="222" x2="324" y2="200" stroke="#8b90a3" stroke-width="1.5" marker-end="url(#arr)"/>
+  <text x="292" y="106" text-anchor="middle" font-size="9.5" fill="#8b90a3">loads</text>
+  <text x="288" y="242" text-anchor="middle" font-size="9.5" fill="#8b90a3">tokens</text>
+
+  <path d="M660 118 L704 106" stroke="#7c9cff" stroke-width="1.5" fill="none" marker-end="url(#arrb)"/>
+  <path d="M704 128 L660 140" stroke="#7c9cff" stroke-width="1.5" fill="none" marker-end="url(#arrb)"/>
+  <text x="683" y="98" text-anchor="middle" font-size="9.5" fill="#7c9cff">save notes</text>
+  <text x="682" y="152" text-anchor="middle" font-size="9.5" fill="#7c9cff">reload (SSE)</text>
+
+  <path d="M660 200 L704 206" stroke="#7c9cff" stroke-width="1.5" fill="none" marker-end="url(#arrb)"/>
+  <text x="682" y="192" text-anchor="middle" font-size="9.5" fill="#7c9cff">sentences</text>
+  <line x1="800" y1="246" x2="800" y2="270" stroke="#8b90a3" stroke-width="1.5" marker-end="url(#arr)"/>
+
+  <path d="M110 396 C90 320, 120 180, 148 160" stroke="#8b90a3" stroke-width="1.2" fill="none" marker-end="url(#arr)"/>
+  <text x="76" y="300" text-anchor="middle" font-size="9.5" fill="#8b90a3">casts</text>
+  <text x="76" y="313" text-anchor="middle" font-size="9.5" fill="#8b90a3">embed</text>
+
+  <line x1="465" y1="466" x2="465" y2="450" stroke="#5f8a72" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="300" y1="466" x2="300" y2="446" stroke="#5f8a72" stroke-width="1.5" marker-end="url(#arr)"/>
+  <line x1="640" y1="466" x2="640" y2="380" stroke="#5f8a72" stroke-width="1.5" marker-end="url(#arr)"/>
+  <text x="740" y="462" text-anchor="middle" font-size="9.5" fill="#5f8a72">gates themes, features, and tools alike</text>
+</svg>

package/docs/demo.svg

@@ -0,0 +1,124 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 540" width="960" height="540" role="img"
+     aria-label="A Decklight slide building in: title, bullets and a diagram step in one by one, then the theme cycles from indigo light to dark to warm parchment.">
+  <!-- Hand-authored animated demo (no JS — safe in <img>). One 14s loop:
+       0–43%   builds step in (title, subtitle, bullets, diagram draw)
+       47–51%  theme cycles to dark            (as if pressing .)
+       53–72%  generator toast (⌃T)
+       73–77%  theme cycles to warm parchment
+       97–100% content fades for the loop restart
+       Reduced motion: animations off → static, fully-built slide. -->
+  <style>
+    * { animation-duration: 14s; animation-timing-function: linear; animation-iteration-count: infinite; }
+    text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif; }
+    .mono { font-family: "SF Mono", SFMono-Regular, ui-monospace, Menlo, Consolas, monospace; }
+
+    .bg    { fill: #f6f6fa; animation-name: kBg; }
+    .ttl   { fill: #23268f; animation-name: kTtl; }
+    .ink   { fill: #2b2e44; animation-name: kInk; }
+    .mut   { fill: #7c8095; animation-name: kMut; }
+    .acc   { fill: #3438c9; animation-name: kAcc; }
+    .strk  { stroke: #9297cf; animation-name: kStrk; }
+    /* animation-name lists don't merge across rules: anything needing a
+       color animation AND a reveal/draw animation names both in ONE rule */
+    .nf1   { fill: #e4e5f7; stroke: #9297cf; animation-name: kF1, kStrk; }
+    .nf2   { fill: #dfeaf6; stroke: #9297cf; animation-name: kF2, kStrk; }
+    .nf3   { fill: #ece3f4; stroke: #9297cf; animation-name: kF3, kStrk; }
+
+    .rTitle { animation-name: kTtl, kInTitle; }
+    .rSub   { animation-name: kMut, kInSub; }
+    .rB1    { animation-name: kInB1; }
+    .rB2    { animation-name: kInB2; }
+    .rB3    { animation-name: kInB3; }
+    .rN1    { animation-name: kInN1; }
+    .rN2    { animation-name: kInN2; }
+    .rN3    { animation-name: kInN3; }
+    .rA1    { animation-name: kStrk, kDrawA1; }
+    .rA2    { animation-name: kStrk, kDrawA2; }
+    .rA1h   { animation-name: kAcc, kA1Head; }
+    .rA2h   { animation-name: kAcc, kA2Head; }
+    .toast  { animation-name: kToast; }
+    .pfill  { animation-name: kAcc, kProgress; transform-origin: 0 0; }
+
+    /* theme color cycle: A(indigo light) → B(night) → C(parchment) → A */
+    @keyframes kBg   { 0%,47% {fill:#f6f6fa} 51%,73% {fill:#131519} 77%,97% {fill:#faf7f2} 100% {fill:#f6f6fa} }
+    @keyframes kTtl  { 0%,47% {fill:#23268f} 51%,73% {fill:#e9edf4} 77%,97% {fill:#4d5527} 100% {fill:#23268f} }
+    @keyframes kInk  { 0%,47% {fill:#2b2e44} 51%,73% {fill:#c9d1dc} 77%,97% {fill:#2e2a24} 100% {fill:#2b2e44} }
+    @keyframes kMut  { 0%,47% {fill:#7c8095} 51%,73% {fill:#848da0} 77%,97% {fill:#8d8577} 100% {fill:#7c8095} }
+    @keyframes kAcc  { 0%,47% {fill:#3438c9} 51%,73% {fill:#8fbfe8} 77%,97% {fill:#75823f} 100% {fill:#3438c9} }
+    @keyframes kF1   { 0%,47% {fill:#e4e5f7} 51%,73% {fill:#232833} 77%,97% {fill:#e7e5d4} 100% {fill:#e4e5f7} }
+    @keyframes kF2   { 0%,47% {fill:#dfeaf6} 51%,73% {fill:#223028} 77%,97% {fill:#dfe6df} 100% {fill:#dfeaf6} }
+    @keyframes kF3   { 0%,47% {fill:#ece3f4} 51%,73% {fill:#2a2536} 77%,97% {fill:#ece2d8} 100% {fill:#ece3f4} }
+    @keyframes kStrk { 0%,47% {stroke:#9297cf} 51%,73% {stroke:#9db8cd} 77%,97% {stroke:#837e5a} 100% {stroke:#9297cf} }
+
+    /* builds (Keynote-style steps) */
+    @keyframes kInTitle { 0% {opacity:0; transform:translateY(14px)} 3.5% {opacity:1; transform:none} 96.5% {opacity:1} 100% {opacity:0} }
+    @keyframes kInSub   { 0%,4%  {opacity:0; transform:translateY(10px)} 7%  {opacity:1; transform:none} 96.5% {opacity:1} 100% {opacity:0} }
+    @keyframes kInB1    { 0%,9%  {opacity:0; transform:translateY(10px)} 12% {opacity:1; transform:none} 96.5% {opacity:1} 100% {opacity:0} }
+    @keyframes kInB2    { 0%,15% {opacity:0; transform:translateY(10px)} 18% {opacity:1; transform:none} 96.5% {opacity:1} 100% {opacity:0} }
+    @keyframes kInB3    { 0%,21% {opacity:0; transform:translateY(10px)} 24% {opacity:1; transform:none} 96.5% {opacity:1} 100% {opacity:0} }
+    @keyframes kInN1    { 0%,27% {opacity:0; transform:translateY(10px)} 30% {opacity:1; transform:none} 96.5% {opacity:1} 100% {opacity:0} }
+    @keyframes kInN2    { 0%,33.5% {opacity:0; transform:translateY(10px)} 36.5% {opacity:1; transform:none} 96.5% {opacity:1} 100% {opacity:0} }
+    @keyframes kInN3    { 0%,40% {opacity:0; transform:translateY(10px)} 43% {opacity:1; transform:none} 96.5% {opacity:1} 100% {opacity:0} }
+    @keyframes kDrawA1  { 0%,30% {opacity:0; stroke-dashoffset:1} 30.5% {opacity:1} 33.5% {stroke-dashoffset:0} 96.5% {opacity:1; stroke-dashoffset:0} 100% {opacity:0} }
+    @keyframes kDrawA2  { 0%,36.5% {opacity:0; stroke-dashoffset:1} 37% {opacity:1} 40% {stroke-dashoffset:0} 96.5% {opacity:1; stroke-dashoffset:0} 100% {opacity:0} }
+    @keyframes kA1Head  { 0%,33% {opacity:0} 34.5% {opacity:1} 96.5% {opacity:1} 100% {opacity:0} }
+    @keyframes kA2Head  { 0%,39.5% {opacity:0} 41% {opacity:1} 96.5% {opacity:1} 100% {opacity:0} }
+    @keyframes kToast   { 0%,52% {opacity:0; transform:translateY(8px)} 55% {opacity:1; transform:none} 69% {opacity:1; transform:none} 72% {opacity:0} 100% {opacity:0} }
+    @keyframes kProgress{ 0% {transform:scaleX(0.04)} 11% {transform:scaleX(0.04)} 12% {transform:scaleX(0.2)}
+                          17% {transform:scaleX(0.2)} 18% {transform:scaleX(0.36)} 23% {transform:scaleX(0.36)}
+                          24% {transform:scaleX(0.52)} 29% {transform:scaleX(0.52)} 30% {transform:scaleX(0.68)}
+                          36% {transform:scaleX(0.68)} 36.5% {transform:scaleX(0.84)} 42% {transform:scaleX(0.84)}
+                          43%,100% {transform:scaleX(1)} }
+
+    @media (prefers-reduced-motion: reduce) { * { animation: none !important; } }
+  </style>
+
+  <rect class="bg" width="960" height="540"/>
+
+  <!-- chrome -->
+  <text class="mut" x="912" y="38" font-size="15" text-anchor="end">12 / 40</text>
+  <rect class="mut" x="0" y="536" width="960" height="4" opacity="0.22"/>
+  <rect class="acc pfill" x="0" y="536" width="960" height="4"/>
+
+  <!-- pinned title + subtitle -->
+  <text class="ttl rTitle" x="480" y="96" font-size="44" font-weight="700" text-anchor="middle">Composing Agents</text>
+  <text class="mut rSub" x="480" y="132" font-size="19" text-anchor="middle">Patterns for multi-agent systems</text>
+
+  <!-- bullets (one data-build container in a real deck) -->
+  <g class="rB1">
+    <circle class="acc" cx="96" cy="238" r="5"/>
+    <text class="ink" x="120" y="246" font-size="22">Sequential — hand off step by step</text>
+  </g>
+  <g class="rB2">
+    <circle class="acc" cx="96" cy="308" r="5"/>
+    <text class="ink" x="120" y="316" font-size="22">Parallel — fan out, then aggregate</text>
+  </g>
+  <g class="rB3">
+    <circle class="acc" cx="96" cy="378" r="5"/>
+    <text class="ink" x="120" y="386" font-size="22">Supervisor — one agent routes the rest</text>
+  </g>
+
+  <!-- diagram (an inline SVG with data-build="draw" in a real deck) -->
+  <g class="rN1">
+    <rect class="nf1" x="620" y="180" width="240" height="62" rx="12" stroke-width="2"/>
+    <text class="ink" x="740" y="218" font-size="19" font-weight="600" text-anchor="middle">Intent Agent</text>
+  </g>
+  <line class="strk rA1" x1="740" y1="244" x2="740" y2="276" stroke-width="2.5" pathLength="1" stroke-dasharray="1"/>
+  <path class="acc rA1h" d="M 733 272 L 747 272 L 740 283 Z"/>
+  <g class="rN2">
+    <rect class="nf2" x="620" y="286" width="240" height="62" rx="12" stroke-width="2"/>
+    <text class="ink" x="740" y="324" font-size="19" font-weight="600" text-anchor="middle">Research Agent</text>
+  </g>
+  <line class="strk rA2" x1="740" y1="350" x2="740" y2="382" stroke-width="2.5" pathLength="1" stroke-dasharray="1"/>
+  <path class="acc rA2h" d="M 733 378 L 747 378 L 740 389 Z"/>
+  <g class="rN3">
+    <rect class="nf3" x="620" y="392" width="240" height="62" rx="12" stroke-width="2"/>
+    <text class="ink" x="740" y="430" font-size="19" font-weight="600" text-anchor="middle">Response Agent</text>
+  </g>
+
+  <!-- generator toast (⌃T) -->
+  <g class="toast">
+    <rect x="290" y="472" width="380" height="34" rx="17" fill="#333338" opacity="0.92"/>
+    <text class="mono" x="480" y="494" font-size="14" fill="#f2f2f4" text-anchor="middle">✨ gen-onyx-0b81 — ⌃T re-roll · ⌃⇧T save</text>
+  </g>
+</svg>

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "decklight",
+  "version": "0.1.0",
+  "description": "A presentation library designed to be authored by AI agents and humans alike: single-file decks, Keynote-style builds, theme-aware SVG diagrams, and truthful terminal recordings.",
+  "type": "module",
+  "main": "dist/decklight.js",
+  "bin": {
+    "decklight": "cli/decklight.mjs"
+  },
+  "files": [
+    "cli/",
+    "tools/",
+    "dist/",
+    "themes/",
+    "docs/",
+    "SPEC.md"
+  ],
+  "homepage": "https://decklight.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/decklight/decklight.git"
+  },
+  "bugs": "https://github.com/decklight/decklight/issues",
+  "keywords": [
+    "presentation",
+    "slides",
+    "deck",
+    "reveal",
+    "keynote",
+    "terminal",
+    "asciicast",
+    "tts",
+    "ai",
+    "agent"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --test 'test/*.test.mjs'",
+    "verify": "npm run build && node test/render.mjs && node test/contrast.mjs && node test/palette-rules.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "highlight.js": "^11.10.0",
+    "marked": "^15.0.0"
+  },
+  "optionalDependencies": {
+    "js-yaml": "^4.3.0",
+    "node-pty": "^1.1.0"
+  },
+  "license": "MIT"
+}

package/themes/README.md

@@ -0,0 +1,61 @@
+# Decklight themes
+
+61 themes, one contract. A theme is **a single CSS file that defines tokens on `.decklight`** — the
+runtime (`dist/decklight.css`) owns all structure; themes own only color, type, and mood. Link exactly
+one theme per deck:
+
+```html
+<link rel="stylesheet" href="decklight/dist/decklight.css">
+<link rel="stylesheet" href="decklight/themes/fjord.css">
+```
+
+Browse them: serve this directory (`python3 -m http.server`) and open [`gallery.html`](gallery.html).
+
+## The token contract (SPEC §5)
+
+Every theme must define **all** of these on `.decklight`:
+
+| Group | Tokens | Notes |
+|---|---|---|
+| Canvas | `--bg` `--bg-accent` `--fg` `--muted` | `--bg`/`--bg-accent` may be gradients |
+| Type | `--font-body` `--font-heading` `--font-mono` `--heading-color` `--heading-weight` `--link` | font stacks must degrade offline |
+| Accent | `--accent` `--accent-contrast` | contrast = text placed *on* the accent |
+| Blocks | `--block-bg` `--block-border` `--block-radius` `--shadow` | `--block-border` is a full border value |
+| Code | `--code-bg` `--code-fg` `--hl-keyword` `--hl-string` `--hl-number` `--hl-comment` `--hl-function` `--hl-type` `--hl-punct` | no separate highlighter themes — these are it |
+| Diagram | `--d-stroke` `--d-text` `--d-muted` `--d-accent` `--d-fill-1…6` | inline SVGs authored with `var(--d-*)` restyle across all themes |
+| Terminal | `--term-bg` `--term-fg` `--term-prompt` `--term-cursor` `--term-selection` + 16 × `--ansi-*` | the 16 ANSI names map recorded output to the theme |
+| Builds (optional) | `--build-duration` `--dim-opacity` `--term-chrome` | `--term-chrome: none` hides the window chrome |
+
+## Accessibility gate
+
+`node test/contrast.mjs` validates every theme (run from the repo root; part of `npm run verify`):
+
+- `--fg`/`--bg` ≥ 4.5 · `--muted`, `--heading-color`, `--link`, `--d-text` ≥ 3.0 (gradient canvases: **every stop** must pass)
+- `--code-fg` and all `--hl-*` ≥ 4.5 on `--code-bg` (`--hl-comment` ≥ 3.0)
+- `--term-fg`, `--term-prompt`, and **all 16** `--ansi-*` ≥ 3.0 on `--term-bg` — yes, including `--ansi-black` on dark terminals: recorded output must stay readable on a projector, so "black" is a visible gray
+- `--accent-contrast` ≥ 4.5 on `--accent`
+
+A PR that adds or edits a theme must keep the validator green.
+
+## Authoring a new theme
+
+1. Copy the closest existing theme (dark → `fjord`, light → `porcelain`, gradient → `aurora`).
+2. Rework **every** group — hue-rotating one palette produces a clone, not a theme. Decide the
+   personality first (one line, like the taglines below), then pick canvas → type → accent →
+   code mood → terminal mood in that order.
+3. Fonts: system stacks preferred. A Google-font `@import` is allowed if the stack degrades
+   gracefully offline (the import goes at the very top of the file).
+4. Optional `.decklight h1/h2` cosmetic rules (letter-spacing, text-transform, font-style) are the
+   only non-token CSS a theme should contain.
+5. Run `node test/contrast.mjs` and fix until green; check your theme's card in `gallery.html`.
+
+## The set
+
+**Dark (15):** aurora · graphite · obsidian · midnight · fjord · cosmos · ember · moss · velvet · carbon · synthwave · ink · eclipse · storm · ibm-modern
+**Light (16):** porcelain · paper · meadow · glacier · citrus · dune · orchid · harvest · coastal · linen · berry · slate · latte · peony · mint · sepia
+Plus the Classics, Old Machines, TV Series, and Movies packs (`packs.json` is the authoritative roster).
+
+Serif-headed: moss, velvet, porcelain, dune, peony, sepia. Gradient canvases:
+aurora, cosmos, synthwave, storm, coastal. Webfont-enhanced (all with offline fallbacks): carbon,
+synthwave, porcelain, paper, peony, mint. Deliberately corporate-safe:
+slate (and arguably graphite) — the rest have opinions.

package/themes/aliens.css

@@ -0,0 +1,84 @@
+/* ═══════════════════════════════════════════════════════════════
+   Decklight theme · aliens
+   dark · military phosphor, tracker green, amber warnings
+   Inspired by Aliens — the motion tracker and the Sulaco CRTs — palette kept canonical where possible,
+   every gated pair fitted to the WCAG contract.
+   Token contract: SPEC.md §5 — validated by test/contrast.mjs
+   ═══════════════════════════════════════════════════════════════ */
+
+.decklight {
+  /* ── canvas ─────────────────────────────── */
+  --bg: #0a0f0d;
+  --bg-accent: none;
+  --fg: #b8e0c8;
+  --muted: #6f9a80;
+
+  /* ── type ───────────────────────────────── */
+  --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --font-heading: "SF Mono", SFMono-Regular, ui-monospace, "Cascadia Code", Menlo, Consolas, monospace;
+  --font-mono: "SF Mono", SFMono-Regular, ui-monospace, "Cascadia Code", Menlo, Consolas, monospace;
+  --heading-color: #8fe8b0;
+  --heading-weight: 600;
+  --link: #e8c060;
+
+  /* ── accent ─────────────────────────────── */
+  --accent: #58d364;
+  --accent-contrast: #131313;
+
+  /* ── blocks ─────────────────────────────── */
+  --block-bg: #111c18;
+  --block-border: 1px solid #26302c;
+  --block-radius: 3px;
+  --shadow: 0 8px 26px rgba(0, 0, 0, 0.5);
+
+  /* ── code ───────────────────────────────── */
+  --code-bg: #0e1511;
+  --code-fg: #b8e8c8;
+  --hl-keyword: #8fe8b0;
+  --hl-string: #e8d080;
+  --hl-number: #e8a850;
+  --hl-comment: #557a64;
+  --hl-function: #7fd8d0;
+  --hl-type: #c8e890;
+  --hl-punct: #8fb89c;
+
+  /* ── diagram ────────────────────────────── */
+  --d-stroke: #6f9a80;
+  --d-text: #b8e0c8;
+  --d-muted: #6f9a80;
+  --d-accent: #e8b840;
+  --d-fill-1: #17201b;
+  --d-fill-2: #28251a;
+  --d-fill-3: #1b312a;
+  --d-fill-4: #172019;
+  --d-fill-5: #1a2827;
+  --d-fill-6: #22311b;
+
+  /* ── terminal ───────────────────────────── */
+  --term-bg: #080c0a;
+  --term-fg: #e6e6e2;
+  --term-prompt: #58d364;
+  --term-cursor: #58d364;
+  --term-selection: rgba(88, 211, 100, 0.28);
+  --ansi-black: #7a8a7a;
+  --ansi-red: #e08a6a;
+  --ansi-green: #6fd66f;
+  --ansi-yellow: #d6c258;
+  --ansi-blue: #7fb3d0;
+  --ansi-magenta: #c79ac0;
+  --ansi-cyan: #7fd0c0;
+  --ansi-white: #dfe8df;
+  --ansi-bright-black: #9ba79b;
+  --ansi-bright-red: #ebb29d;
+  --ansi-bright-green: #9fe49f;
+  --ansi-bright-yellow: #e2d489;
+  --ansi-bright-blue: #accee0;
+  --ansi-bright-magenta: #ddc1d9;
+  --ansi-bright-cyan: #ace0d6;
+  --ansi-bright-white: #f3f6f3;
+
+  /* ── builds ─────────────────────────────── */
+  --dim-opacity: 0.22;
+}
+
+.decklight h1, .decklight h2 { text-transform: uppercase; letter-spacing: 0.05em; }

package/themes/apple2.css

@@ -0,0 +1,126 @@
+/* ═══════════════════════════════════════════════════════════════
+   Decklight theme · apple2
+   dark · black glass, one green phosphor, mono display type
+   Inspired by the Apple ][ green phosphor CRT — palette kept canonical where possible,
+   every gated pair fitted to the WCAG contract.
+   rule-exception: R1 a single-phosphor monochrome display is the identity
+   rule-exception: R3 phosphor green burns bright by design
+   Token contract: SPEC.md §5 — validated by test/contrast.mjs
+   ═══════════════════════════════════════════════════════════════ */
+
+.decklight {
+  /* ── canvas ─────────────────────────────── */
+  --bg: #0c0f0c;
+  --bg-accent: none;
+  --fg: #7fe87f;
+  --muted: #4f9f5b;
+
+  /* ── type ───────────────────────────────── */
+  --font-body: "SF Mono", SFMono-Regular, ui-monospace, "Cascadia Code", Menlo, Consolas, monospace;
+  --font-heading: "SF Mono", SFMono-Regular, ui-monospace, "Cascadia Code", Menlo, Consolas, monospace;
+  --font-mono: "SF Mono", SFMono-Regular, ui-monospace, "Cascadia Code", Menlo, Consolas, monospace;
+  --heading-color: #8ff98f;
+  --heading-weight: 600;
+  --link: #a8ff9f;
+
+  /* ── accent ─────────────────────────────── */
+  --accent: #37d63d;
+  --accent-contrast: #131313;
+
+  /* ── blocks ─────────────────────────────── */
+  --block-bg: #141b14;
+  --block-border: 1px solid #273127;
+  --block-radius: 2px;
+  --shadow: 0 8px 26px rgba(0, 0, 0, 0.5);
+
+  /* ── code ───────────────────────────────── */
+  --code-bg: #101510;
+  --code-fg: #8ff98f;
+  --hl-keyword: #a8ff9f;
+  --hl-string: #5fd68f;
+  --hl-number: #d6d65f;
+  --hl-comment: #3f7a4a;
+  --hl-function: #7fe8b0;
+  --hl-type: #c8e87f;
+  --hl-punct: #6fbf7f;
+
+  /* ── diagram ────────────────────────────── */
+  --d-stroke: #4f9f5b;
+  --d-text: #7fe87f;
+  --d-muted: #4f9f5b;
+  --d-accent: #37d63d;
+  --d-fill-1: #182119;
+  --d-fill-2: #1d291a;
+  --d-fill-3: #1c3223;
+  --d-fill-4: #1c2118;
+  --d-fill-5: #1a2923;
+  --d-fill-6: #2b321c;
+
+  /* ── terminal ───────────────────────────── */
+  --term-bg: #0a0d0a;
+  --term-fg: #e6e6e2;
+  --term-prompt: #37d63d;
+  --term-cursor: #37d63d;
+  --term-selection: rgba(55, 214, 61, 0.28);
+  --ansi-black: #7a8a7a;
+  --ansi-red: #e08a6a;
+  --ansi-green: #6fd66f;
+  --ansi-yellow: #d6c258;
+  --ansi-blue: #7fb3d0;
+  --ansi-magenta: #c79ac0;
+  --ansi-cyan: #7fd0c0;
+  --ansi-white: #dfe8df;
+  --ansi-bright-black: #9ba79b;
+  --ansi-bright-red: #ebb29d;
+  --ansi-bright-green: #9fe49f;
+  --ansi-bright-yellow: #e2d489;
+  --ansi-bright-blue: #accee0;
+  --ansi-bright-magenta: #ddc1d9;
+  --ansi-bright-cyan: #ace0d6;
+  --ansi-bright-white: #f3f6f3;
+
+  /* ── builds ─────────────────────────────── */
+  --dim-opacity: 0.22;
+}
+
+.decklight h1, .decklight h2 { text-transform: uppercase; letter-spacing: 0.04em; }
+
+/* ── CRT character: the Monitor /// look ─────────────────────────────────────
+   Scanlines + phosphor bloom + a slow raster roll + the occasional horizontal
+   sync tear. Subtle by design; all motion sits out prefers-reduced-motion. */
+.decklight .terminal-screen {
+  position: relative;
+  overflow: hidden;
+  text-shadow: 0 0 5px rgba(90, 240, 110, 0.4);
+  animation: a2-tear 7s steps(1) infinite;
+}
+.decklight .terminal-screen::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  background: repeating-linear-gradient(0deg, rgba(0, 0, 0, 0.20) 0 1px, transparent 1px 3px);
+}
+.decklight .terminal-screen::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: -25%;
+  height: 22%;
+  pointer-events: none;
+  background: linear-gradient(180deg, transparent, rgba(130, 255, 150, 0.055), transparent);
+  animation: a2-roll 8s linear infinite;
+}
+@keyframes a2-roll { to { transform: translateY(560%); } }
+@keyframes a2-tear {
+  0%, 93.9% { transform: none; }
+  94% { transform: translateX(2px); }
+  94.7% { transform: translateX(-3px) skewX(0.5deg); }
+  95.4% { transform: translateX(1px); }
+  96%, 100% { transform: none; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .decklight .terminal-screen,
+  .decklight .terminal-screen::before { animation: none; }
+}

package/themes/aurora.css

@@ -0,0 +1,84 @@
+/* ═══════════════════════════════════════════════════════════════
+   Decklight theme · aurora
+   dark · Northern-lights gradient — teal glow over deep arctic navy
+   Token contract: SPEC.md §5 — all values validated by test/contrast.mjs
+   ═══════════════════════════════════════════════════════════════ */
+
+/* palette-rule exceptions (test/palette-rules.mjs):
+   rule-exception: R2 the borealis duotone canvas is the identity
+   ═══════════════════════════════════════════════════════════════ */
+
+.decklight {
+  /* ── canvas ─────────────────────────────── */
+  --bg: linear-gradient(160deg, #0a0f24 0%, #0d1f3c 55%, #0b2b38 100%);
+  --bg-accent: linear-gradient(135deg, #10306b 0%, #0d4a54 100%);
+  --fg: #e8eefc;
+  --muted: #9fb1d1;
+
+  /* ── type ───────────────────────────────── */
+  --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --font-heading: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --font-mono: "SF Mono", SFMono-Regular, ui-monospace, "Cascadia Code", Menlo, Consolas, monospace;
+  --heading-color: #fafafa;
+  --heading-weight: 800;
+  --link: #7cc7ff;
+
+  /* ── accent ─────────────────────────────── */
+  --accent: #5ae4bb;
+  --accent-contrast: #04261c;
+
+  /* ── blocks ─────────────────────────────── */
+  --block-bg: rgba(16, 32, 68, 0.55);
+  --block-border: 1px solid rgba(110, 231, 208, 0.25);
+  --block-radius: 14px;
+  --shadow: 0 12px 40px rgba(2, 8, 26, 0.55);
+
+  /* ── code ───────────────────────────────── */
+  --code-bg: #0a1430;
+  --code-fg: #dbe6ff;
+  --hl-keyword: #82aaff;
+  --hl-string: #7ee2b8;
+  --hl-number: #ffcb8b;
+  --hl-comment: #7d90b5;
+  --hl-function: #c9a2f5;
+  --hl-type: #6fd7e8;
+  --hl-punct: #a6b8d8;
+
+  /* ── diagram ────────────────────────────── */
+  --d-stroke: #6ee7d0;
+  --d-text: #e8eefc;
+  --d-muted: #8ba0c4;
+  --d-accent: #4ef0c0;
+  --d-fill-1: #12305c;
+  --d-fill-2: #0e4d5c;
+  --d-fill-3: #274060;
+  --d-fill-4: #1b3b53;
+  --d-fill-5: #16344a;
+  --d-fill-6: #232a55;
+
+  /* ── terminal ───────────────────────────── */
+  --term-bg: #071021;
+  --term-fg: #d6e4ff;
+  --term-prompt: #4ef0c0;
+  --term-cursor: #4ef0c0;
+  --term-selection: rgba(78, 240, 192, 0.28);
+  --ansi-black: #8494ad;
+  --ansi-red: #ff7b8a;
+  --ansi-green: #5fe8b0;
+  --ansi-yellow: #ffd479;
+  --ansi-blue: #7cb7ff;
+  --ansi-magenta: #c99bff;
+  --ansi-cyan: #6fe0e8;
+  --ansi-white: #dfe8f5;
+  --ansi-bright-black: #9fb1cc;
+  --ansi-bright-red: #ffa3ad;
+  --ansi-bright-green: #8ff5c8;
+  --ansi-bright-yellow: #ffe3a1;
+  --ansi-bright-blue: #a3cdff;
+  --ansi-bright-magenta: #ddbcff;
+  --ansi-bright-cyan: #a1ecf2;
+  --ansi-bright-white: #fafafa;
+
+  /* ── builds ─────────────────────────────── */
+  --dim-opacity: 0.3;
+}