decklight 0.1.0

package/themes/star-wars.css

@@ -0,0 +1,85 @@
+/* ═══════════════════════════════════════════════════════════════
+   Decklight theme · star-wars
+   dark · deep space black, crawl yellow, saber blue
+   Inspired by Star Wars — the opening crawl — palette kept canonical where possible,
+   every gated pair fitted to the WCAG contract.
+   rule-exception: R3 the canonical crawl yellow (#ffe81f) is the identity
+   Token contract: SPEC.md §5 — validated by test/contrast.mjs
+   ═══════════════════════════════════════════════════════════════ */
+
+.decklight {
+  /* ── canvas ─────────────────────────────── */
+  --bg: #0a0a10;
+  --bg-accent: none;
+  --fg: #e6e2d2;
+  --muted: #98948a;
+
+  /* ── 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: #ffe81f;
+  --heading-weight: 800;
+  --link: #f0d860;
+
+  /* ── accent ─────────────────────────────── */
+  --accent: #e8c825;
+  --accent-contrast: #131313;
+
+  /* ── blocks ─────────────────────────────── */
+  --block-bg: #11111d;
+  --block-border: 1px solid #262631;
+  --block-radius: 4px;
+  --shadow: 0 8px 26px rgba(0, 0, 0, 0.5);
+
+  /* ── code ───────────────────────────────── */
+  --code-bg: #10101a;
+  --code-fg: #e8e4d8;
+  --hl-keyword: #f0d860;
+  --hl-string: #7fc8f0;
+  --hl-number: #f0a860;
+  --hl-comment: #70706a;
+  --hl-function: #8fd08f;
+  --hl-type: #e88a80;
+  --hl-punct: #b8b4a8;
+
+  /* ── diagram ────────────────────────────── */
+  --d-stroke: #98948a;
+  --d-text: #e6e2d2;
+  --d-muted: #98948a;
+  --d-accent: #4fb8f0;
+  --d-fill-1: #211f18;
+  --d-fill-2: #1a2129;
+  --d-fill-3: #311c1c;
+  --d-fill-4: #182118;
+  --d-fill-5: #1a1d29;
+  --d-fill-6: #31281c;
+
+  /* ── terminal ───────────────────────────── */
+  --term-bg: #08080e;
+  --term-fg: #e6e6e2;
+  --term-prompt: #e8c825;
+  --term-cursor: #e8c825;
+  --term-selection: rgba(232, 200, 37, 0.28);
+  --ansi-black: #9f9b89;
+  --ansi-red: #d97963;
+  --ansi-green: #63d973;
+  --ansi-yellow: #d9c763;
+  --ansi-blue: #638ed9;
+  --ansi-magenta: #cb63d9;
+  --ansi-cyan: #63d9d5;
+  --ansi-white: #e3e2de;
+  --ansi-bright-black: #b4b2a7;
+  --ansi-bright-red: #eaa08f;
+  --ansi-bright-green: #8fea9b;
+  --ansi-bright-yellow: #eadd8f;
+  --ansi-bright-blue: #8fb0ea;
+  --ansi-bright-magenta: #e08fea;
+  --ansi-bright-cyan: #8feae7;
+  --ansi-bright-white: #f3f3f2;
+
+  /* ── builds ─────────────────────────────── */
+  --dim-opacity: 0.3;
+}
+
+.decklight h1, .decklight h2 { text-transform: uppercase; letter-spacing: 0.04em; }

package/themes/storm.css

@@ -0,0 +1,80 @@
+/* ═══════════════════════════════════════════════════════════════
+   Decklight theme · storm
+   dark · Squall-line slate with one bolt of electric yellow
+   Token contract: SPEC.md §5 — all values validated by test/contrast.mjs
+   ═══════════════════════════════════════════════════════════════ */
+
+.decklight {
+  /* ── canvas ─────────────────────────────── */
+  --bg: linear-gradient(165deg, #1a2030 0%, #29313f 55%, #343c49 100%);
+  --bg-accent: linear-gradient(165deg, #253349 0%, #34455f 100%);
+  --fg: #e6ebf4;
+  --muted: #a6b2c8;
+
+  /* ── 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: #8ec1f0;
+
+  /* ── accent ─────────────────────────────── */
+  --accent: #e4c459;
+  --accent-contrast: #241c00;
+
+  /* ── blocks ─────────────────────────────── */
+  --block-bg: rgba(30, 40, 60, 0.6);
+  --block-border: 1px solid rgba(142, 193, 240, 0.22);
+  --block-radius: 10px;
+  --shadow: 0 12px 36px rgba(6, 10, 18, 0.55);
+
+  /* ── code ───────────────────────────────── */
+  --code-bg: #161d2b;
+  --code-fg: #dfe6f2;
+  --hl-keyword: #8ec1f0;
+  --hl-string: #9cdea4;
+  --hl-number: #f7ce46;
+  --hl-comment: #8593ab;
+  --hl-function: #a8b8f0;
+  --hl-type: #8fd8dd;
+  --hl-punct: #a9b5ca;
+
+  /* ── diagram ────────────────────────────── */
+  --d-stroke: #6b7f9e;
+  --d-text: #e6ebf4;
+  --d-muted: #93a2ba;
+  --d-accent: #ffd23e;
+  --d-fill-1: #22304a;
+  --d-fill-2: #283a54;
+  --d-fill-3: #2c3350;
+  --d-fill-4: #1f3a55;
+  --d-fill-5: #2e3d58;
+  --d-fill-6: #26364e;
+
+  /* ── terminal ───────────────────────────── */
+  --term-bg: #121826;
+  --term-fg: #dae2ef;
+  --term-prompt: #ffd23e;
+  --term-cursor: #ffd23e;
+  --term-selection: rgba(255, 210, 62, 0.24);
+  --ansi-black: #8593a8;
+  --ansi-red: #f28293;
+  --ansi-green: #8fd39a;
+  --ansi-yellow: #ffd23e;
+  --ansi-blue: #82aede;
+  --ansi-magenta: #bfa2dd;
+  --ansi-cyan: #7fd2d8;
+  --ansi-white: #e2e8f2;
+  --ansi-bright-black: #9dabc0;
+  --ansi-bright-red: #f7a7b4;
+  --ansi-bright-green: #aee5b8;
+  --ansi-bright-yellow: #ffe07a;
+  --ansi-bright-blue: #a6c6ea;
+  --ansi-bright-magenta: #d5bfec;
+  --ansi-bright-cyan: #a5e3e8;
+  --ansi-bright-white: #fafafa;
+
+  /* ── builds ─────────────────────────────── */
+  --dim-opacity: 0.3;
+}

package/themes/stranger-things.css

@@ -0,0 +1,84 @@
+/* ═══════════════════════════════════════════════════════════════
+   Decklight theme · stranger-things
+   dark · upside-down black, title red, a serif that means business
+   Inspired by Stranger Things — the red title in the dark — 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: #0d0a0e;
+  --bg-accent: none;
+  --fg: #e8dfd8;
+  --muted: #9a8d88;
+
+  /* ── type ───────────────────────────────── */
+  --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --font-heading: "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif;
+  --font-mono: "SF Mono", SFMono-Regular, ui-monospace, "Cascadia Code", Menlo, Consolas, monospace;
+  --heading-color: #e2242e;
+  --heading-weight: 700;
+  --link: #ef6a5e;
+
+  /* ── accent ─────────────────────────────── */
+  --accent: #c42832;
+  --accent-contrast: #fbfbfa;
+
+  /* ── blocks ─────────────────────────────── */
+  --block-bg: #18121b;
+  --block-border: 1px solid #2d2530;
+  --block-radius: 4px;
+  --shadow: 0 8px 26px rgba(0, 0, 0, 0.5);
+
+  /* ── code ───────────────────────────────── */
+  --code-bg: #141014;
+  --code-fg: #e8e0da;
+  --hl-keyword: #ee7c72;
+  --hl-string: #cab988;
+  --hl-number: #e8a860;
+  --hl-comment: #7a6f6c;
+  --hl-function: #a8b8e0;
+  --hl-type: #d8c0a0;
+  --hl-punct: #b0a8a4;
+
+  /* ── diagram ────────────────────────────── */
+  --d-stroke: #9a8d88;
+  --d-text: #e8dfd8;
+  --d-muted: #9a8d88;
+  --d-accent: #c42832;
+  --d-fill-1: #201718;
+  --d-fill-2: #281e19;
+  --d-fill-3: #1b1e30;
+  --d-fill-4: #201d17;
+  --d-fill-5: #231928;
+  --d-fill-6: #1b2930;
+
+  /* ── terminal ───────────────────────────── */
+  --term-bg: #0a080b;
+  --term-fg: #e6e6e2;
+  --term-prompt: #c42832;
+  --term-cursor: #c42832;
+  --term-selection: rgba(196, 40, 50, 0.28);
+  --ansi-black: #9f898b;
+  --ansi-red: #ce866e;
+  --ansi-green: #6ece81;
+  --ansi-yellow: #cec66e;
+  --ansi-blue: #6e8bce;
+  --ansi-magenta: #c96ece;
+  --ansi-cyan: #6ecbce;
+  --ansi-white: #e3dede;
+  --ansi-bright-black: #b4a7a8;
+  --ansi-bright-red: #e3a997;
+  --ansi-bright-green: #97e3a5;
+  --ansi-bright-yellow: #e3dc97;
+  --ansi-bright-blue: #97aee3;
+  --ansi-bright-magenta: #df97e3;
+  --ansi-bright-cyan: #97e1e3;
+  --ansi-bright-white: #f3f2f2;
+
+  /* ── builds ─────────────────────────────── */
+  --dim-opacity: 0.25;
+}
+
+.decklight h1, .decklight h2 { text-transform: uppercase; letter-spacing: 0.08em; }

package/themes/synthwave.css

@@ -0,0 +1,90 @@
+@import url('https://fonts.googleapis.com/css2?family=Orbitron:wght@600;800&display=swap');
+
+/* ═══════════════════════════════════════════════════════════════
+   Decklight theme · synthwave
+   dark · Retro-future horizon — neon pink and cyan over violet dusk
+   Token contract: SPEC.md §5 — all values validated by test/contrast.mjs
+   ═══════════════════════════════════════════════════════════════ */
+
+/* palette-rule exceptions (test/palette-rules.mjs):
+   rule-exception: R3 neon is the identity — the accent stays hot
+   rule-exception: R2 the neon-sunset duotone canvas is the identity
+   ═══════════════════════════════════════════════════════════════ */
+
+.decklight {
+  /* ── canvas ─────────────────────────────── */
+  --bg: linear-gradient(180deg, #160a2e 0%, #2b1055 62%, #45156b 100%);
+  --bg-accent: linear-gradient(180deg, #45156b 0%, #7a1f5c 100%);
+  --fg: #f2e7ff;
+  --muted: #c0a8e0;
+
+  /* ── type ───────────────────────────────── */
+  --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --font-heading: Orbitron, "Avenir Next", Avenir, Futura, "Century Gothic", "Segoe UI", sans-serif;
+  --font-mono: "SF Mono", SFMono-Regular, ui-monospace, "Cascadia Code", Menlo, Consolas, monospace;
+  --heading-color: #29f3ff;
+  --heading-weight: 800;
+  --link: #63c9ff;
+
+  /* ── accent ─────────────────────────────── */
+  --accent: #ff2ea6;
+  --accent-contrast: #330014;
+
+  /* ── blocks ─────────────────────────────── */
+  --block-bg: rgba(38, 12, 72, 0.6);
+  --block-border: 1px solid rgba(41, 243, 255, 0.3);
+  --block-radius: 10px;
+  --shadow: 0 0 32px rgba(255, 46, 166, 0.25);
+
+  /* ── code ───────────────────────────────── */
+  --code-bg: #170933;
+  --code-fg: #eee2ff;
+  --hl-keyword: #ff7ec8;
+  --hl-string: #7df5d8;
+  --hl-number: #ffd166;
+  --hl-comment: #8f7cb8;
+  --hl-function: #63c9ff;
+  --hl-type: #c79bff;
+  --hl-punct: #bda8dd;
+
+  /* ── diagram ────────────────────────────── */
+  --d-stroke: #b03fd0;
+  --d-text: #f2e7ff;
+  --d-muted: #ab93d0;
+  --d-accent: #29f3ff;
+  --d-fill-1: #2a0f52;
+  --d-fill-2: #3c1160;
+  --d-fill-3: #221650;
+  --d-fill-4: #4a1258;
+  --d-fill-5: #321a68;
+  --d-fill-6: #3d0f4e;
+
+  /* ── terminal ───────────────────────────── */
+  --term-bg: #120726;
+  --term-fg: #e8dcfc;
+  --term-prompt: #29f3ff;
+  --term-cursor: #ff2ea6;
+  --term-selection: rgba(41, 243, 255, 0.25);
+  --ansi-black: #8d7cb0;
+  --ansi-red: #ff6e9c;
+  --ansi-green: #6ef2c2;
+  --ansi-yellow: #ffd166;
+  --ansi-blue: #7ab5ff;
+  --ansi-magenta: #e08aff;
+  --ansi-cyan: #54e6f5;
+  --ansi-white: #ecdff8;
+  --ansi-bright-black: #a894cc;
+  --ansi-bright-red: #ff9ebd;
+  --ansi-bright-green: #9af8d6;
+  --ansi-bright-yellow: #ffe08c;
+  --ansi-bright-blue: #a3ccff;
+  --ansi-bright-magenta: #ecacff;
+  --ansi-bright-cyan: #8ff0fa;
+  --ansi-bright-white: #fafafa;
+
+  /* ── builds ─────────────────────────────── */
+  --dim-opacity: 0.3;
+  --build-duration: 420ms;
+}
+
+.decklight h1, .decklight h2 { letter-spacing: 0.06em; text-transform: uppercase; }

package/themes/terminator.css

@@ -0,0 +1,84 @@
+/* ═══════════════════════════════════════════════════════════════
+   Decklight theme · terminator
+   dark · gunmetal chrome, target-lock red, cold machine grays
+   Inspired by The Terminator — chrome endoskeleton, HUD red — 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: linear-gradient(180deg, #16181d 0%, #0d0e12 100%);
+  --bg-accent: none;
+  --fg: #dde1e8;
+  --muted: #8f95a0;
+
+  /* ── 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: #e04248;
+  --heading-weight: 800;
+  --link: #ef7a74;
+
+  /* ── accent ─────────────────────────────── */
+  --accent: #c42f38;
+  --accent-contrast: #fbfbfa;
+
+  /* ── blocks ─────────────────────────────── */
+  --block-bg: #1e212a;
+  --block-border: 1px solid #31353f;
+  --block-radius: 3px;
+  --shadow: 0 8px 26px rgba(0, 0, 0, 0.5);
+
+  /* ── code ───────────────────────────────── */
+  --code-bg: #101318;
+  --code-fg: #dfe3ea;
+  --hl-keyword: #e78186;
+  --hl-string: #a4b8cc;
+  --hl-number: #e2a866;
+  --hl-comment: #6a707a;
+  --hl-function: #8fb8e0;
+  --hl-type: #c3c9dd;
+  --hl-punct: #a0a6b0;
+
+  /* ── diagram ────────────────────────────── */
+  --d-stroke: #8f95a0;
+  --d-text: #dde1e8;
+  --d-muted: #8f95a0;
+  --d-accent: #d55159;
+  --d-fill-1: #22272f;
+  --d-fill-2: #382425;
+  --d-fill-3: #253841;
+  --d-fill-4: #22222f;
+  --d-fill-5: #382e24;
+  --d-fill-6: #254141;
+
+  /* ── terminal ───────────────────────────── */
+  --term-bg: #0b0d11;
+  --term-fg: #e6e6e2;
+  --term-prompt: #c42f38;
+  --term-cursor: #c42f38;
+  --term-selection: rgba(196, 47, 56, 0.28);
+  --ansi-black: #9f898a;
+  --ansi-red: #cb8872;
+  --ansi-green: #72cb83;
+  --ansi-yellow: #cbc372;
+  --ansi-blue: #728dcb;
+  --ansi-magenta: #c672cb;
+  --ansi-cyan: #72c8cb;
+  --ansi-white: #e3dede;
+  --ansi-bright-black: #b4a7a8;
+  --ansi-bright-red: #e0ab99;
+  --ansi-bright-green: #99e0a7;
+  --ansi-bright-yellow: #e0da99;
+  --ansi-bright-blue: #99afe0;
+  --ansi-bright-magenta: #dd99e0;
+  --ansi-bright-cyan: #99dee0;
+  --ansi-bright-white: #f3f2f2;
+
+  /* ── builds ─────────────────────────────── */
+  --dim-opacity: 0.25;
+}
+
+.decklight h1, .decklight h2 { text-transform: uppercase; letter-spacing: 0.03em; }

package/themes/velvet.css

@@ -0,0 +1,80 @@
+/* ═══════════════════════════════════════════════════════════════
+   Decklight theme · velvet
+   dark · Plum velvet and rose gold — an opera box after dark
+   Token contract: SPEC.md §5 — all values validated by test/contrast.mjs
+   ═══════════════════════════════════════════════════════════════ */
+
+.decklight {
+  /* ── canvas ─────────────────────────────── */
+  --bg: #221126;
+  --bg-accent: linear-gradient(150deg, #2f1533 0%, #221126 70%);
+  --fg: #f2e6ee;
+  --muted: #c6aac0;
+
+  /* ── type ───────────────────────────────── */
+  --font-body: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --font-heading: "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, serif;
+  --font-mono: "SF Mono", SFMono-Regular, ui-monospace, "Cascadia Code", Menlo, Consolas, monospace;
+  --heading-color: #f3cdb8;
+  --heading-weight: 700;
+  --link: #e8a4c8;
+
+  /* ── accent ─────────────────────────────── */
+  --accent: #e8b4bc;
+  --accent-contrast: #3a0e1c;
+
+  /* ── blocks ─────────────────────────────── */
+  --block-bg: #2c1731;
+  --block-border: 1px solid #46264c;
+  --block-radius: 14px;
+  --shadow: 0 12px 36px rgba(12, 3, 14, 0.6);
+
+  /* ── code ───────────────────────────────── */
+  --code-bg: #1a0d1e;
+  --code-fg: #ecdfe8;
+  --hl-keyword: #e8a4c8;
+  --hl-string: #c9c98a;
+  --hl-number: #f0b890;
+  --hl-comment: #9d86a0;
+  --hl-function: #a8b8f0;
+  --hl-type: #d0a8e8;
+  --hl-punct: #c0a8ba;
+
+  /* ── diagram ────────────────────────────── */
+  --d-stroke: #96608f;
+  --d-text: #f2e6ee;
+  --d-muted: #b299ad;
+  --d-accent: #e8b4bc;
+  --d-fill-1: #331a3a;
+  --d-fill-2: #3e1c3a;
+  --d-fill-3: #2c1f42;
+  --d-fill-4: #421f30;
+  --d-fill-5: #38224a;
+  --d-fill-6: #2e1836;
+
+  /* ── terminal ───────────────────────────── */
+  --term-bg: #160a19;
+  --term-fg: #e8dbe4;
+  --term-prompt: #e8b4bc;
+  --term-cursor: #e8b4bc;
+  --term-selection: rgba(232, 180, 188, 0.26);
+  --ansi-black: #9c86a0;
+  --ansi-red: #f28299;
+  --ansi-green: #a2d68f;
+  --ansi-yellow: #ecc687;
+  --ansi-blue: #9badf0;
+  --ansi-magenta: #d79be8;
+  --ansi-cyan: #93d5d0;
+  --ansi-white: #eee2ea;
+  --ansi-bright-black: #b29cb8;
+  --ansi-bright-red: #f8a8ba;
+  --ansi-bright-green: #bfe5ae;
+  --ansi-bright-yellow: #f5d8a8;
+  --ansi-bright-blue: #b8c5f5;
+  --ansi-bright-magenta: #e5baf2;
+  --ansi-bright-cyan: #b2e5e0;
+  --ansi-bright-white: #fdf8fc;
+
+  /* ── builds ─────────────────────────────── */
+  --dim-opacity: 0.3;
+}

package/tools/gemini-tts.mjs

@@ -0,0 +1,140 @@
+// Shared Gemini TTS synthesis (Vertex AI) — used by tools/voiceover.mjs
+// (batch pre-render) and tools/voiceover-server.mjs (live bridge for the
+// player). generateContent with responseModalities AUDIO returns base64 raw
+// PCM (audio/L16, 24 kHz mono); we wrap a WAV header so both afconvert and
+// the browser's <audio> can read it. Auth is ADC via gcloud; the model id /
+// location pair is probed once (GA vs -preview, global vs us-central1) and
+// cached for the synth's lifetime.
+
+import { execFileSync } from 'node:child_process';
+
+// The prebuilt voice roster (docs' flavor words) — the player shows this
+// same list, keep the two in sync (engine.js GEMINI_VOICES).
+export const GEMINI_VOICES = [
+  ['Zephyr', 'bright'], ['Puck', 'upbeat'], ['Charon', 'informative'],
+  ['Kore', 'firm'], ['Fenrir', 'excitable'], ['Leda', 'youthful'],
+  ['Orus', 'firm'], ['Aoede', 'breezy'], ['Callirrhoe', 'easy-going'],
+  ['Autonoe', 'bright'], ['Enceladus', 'breathy'], ['Iapetus', 'clear'],
+  ['Umbriel', 'easy-going'], ['Algieba', 'smooth'], ['Despina', 'smooth'],
+  ['Erinome', 'clear'], ['Algenib', 'gravelly'], ['Rasalgethi', 'informative'],
+  ['Laomedeia', 'upbeat'], ['Achernar', 'soft'], ['Alnilam', 'firm'],
+  ['Schedar', 'even'], ['Gacrux', 'mature'], ['Pulcherrima', 'forward'],
+  ['Achird', 'friendly'], ['Zubenelgenubi', 'casual'], ['Vindemiatrix', 'gentle'],
+  ['Sadachbia', 'lively'], ['Sadaltager', 'knowledgeable'], ['Sulafat', 'warm'],
+];
+
+function gcloudToken() {
+  return execFileSync('gcloud', ['auth', 'application-default', 'print-access-token'],
+    { encoding: 'utf8' }).trim();
+}
+
+// Published Vertex AI list prices (USD per 1M tokens) — the API returns
+// token counts in usageMetadata, never dollars, so cost is an ESTIMATE.
+const PRICES = [
+  [/flash/i, { input: 0.50, output: 10.00 }],
+  [/./, { input: 1.00, output: 20.00 }], // gemini-2.5-pro-tts
+];
+function estimateCost(model, usage) {
+  const p = PRICES.find(([re]) => re.test(model))[1];
+  return ((usage.promptTokenCount ?? 0) * p.input + (usage.candidatesTokenCount ?? 0) * p.output) / 1e6;
+}
+
+function wavFromPcm(pcm, rate) {
+  const h = Buffer.alloc(44);
+  h.write('RIFF', 0); h.writeUInt32LE(36 + pcm.length, 4); h.write('WAVE', 8);
+  h.write('fmt ', 12); h.writeUInt32LE(16, 16); h.writeUInt16LE(1, 20); h.writeUInt16LE(1, 22);
+  h.writeUInt32LE(rate, 24); h.writeUInt32LE(rate * 2, 28); h.writeUInt16LE(2, 32); h.writeUInt16LE(16, 34);
+  h.write('data', 36); h.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([h, pcm]);
+}
+
+/**
+ * Compose the steering prompt in the DOCUMENTED shape: one directive
+ * clause ending in a colon, fused to the content ("Say cheerfully: …").
+ * Free-form styles are normalized — multi-sentence personas collapse into
+ * a single clause (periods → semicolons) and anything not already phrased
+ * as a speech directive gets wrapped in one — because instruction-looking
+ * text is steering, but content-looking text ("You're a friendly senior
+ * engineer…") can stochastically be read aloud, especially when the
+ * instruction dwarfs a short sentence.
+ */
+export function styledPrompt(style, text) {
+  const s = (style ?? '').trim();
+  if (!s) return text;
+  const clause = s
+    .replace(/\s+/g, ' ')
+    .replace(/[.!?;:\s]+$/, '')   // drop trailing punctuation
+    .replace(/\.\s+/g, '; ');     // fuse sentences into one clause
+  const directive = /^(read|say|speak|narrate|deliver|announce|whisper|shout|recite|tell)\b/i.test(clause)
+    ? clause
+    : `Say this in the following style — ${clause}`;
+  return `${directive}: ${text}`;
+}
+
+/**
+ * Returns async (text, { voice, style }) → { wav: Buffer, usage } where
+ * usage = { model, promptTokens, audioTokens, cost } (cost is an estimate
+ * from published list prices — the API only reports token counts).
+ * `style` steers delivery via styledPrompt() — never spoken content.
+ */
+export function createSynth({ project, ttsModel, location } = {}) {
+  if (!project) throw new Error('Gemini TTS needs a GCP project — pass { project } (CLI: --project <id> or set GOOGLE_CLOUD_PROJECT)');
+  let token = null;
+  let route = null;
+
+  async function call(text, voice, model, loc) {
+    const host = loc === 'global' ? 'aiplatform.googleapis.com' : `${loc}-aiplatform.googleapis.com`;
+    const url = `https://${host}/v1/projects/${project}/locations/${loc}/publishers/google/models/${model}:generateContent`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({
+        contents: [{ role: 'user', parts: [{ text }] }],
+        generationConfig: {
+          responseModalities: ['AUDIO'],
+          speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: voice } } },
+        },
+      }),
+    });
+    if (!res.ok) { const e = new Error(`${res.status} ${(await res.text()).slice(0, 200)}`); e.status = res.status; throw e; }
+    const json = await res.json();
+    const data = json.candidates?.[0]?.content?.parts?.find((p) => p.inlineData)?.inlineData;
+    if (!data) throw new Error('no audio in response');
+    const rate = Number(/rate=(\d+)/.exec(data.mimeType)?.[1] ?? 24000);
+    const um = json.usageMetadata ?? {};
+    return {
+      wav: wavFromPcm(Buffer.from(data.data, 'base64'), rate),
+      usage: {
+        model,
+        promptTokens: um.promptTokenCount ?? 0,
+        audioTokens: um.candidatesTokenCount ?? 0,
+        cost: estimateCost(model, um),
+      },
+    };
+  }
+
+  return async function synth(text, { voice = 'Alnilam', style = '' } = {}) {
+    token ??= gcloudToken();
+    const prompt = styledPrompt(style, text);
+    const routes = route ? [route]
+      : [ttsModel ?? 'gemini-2.5-pro-tts', 'gemini-2.5-pro-preview-tts']
+        .flatMap((m) => [location ?? 'global', 'us-central1'].map((l) => ({ model: m, location: l })))
+        .filter((r, i, a) => a.findIndex((x) => x.model === r.model && x.location === r.location) === i);
+    let lastErr;
+    for (const r of routes) {
+      for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+          const out = await call(prompt, voice, r.model, r.location);
+          route ??= r;
+          return out;
+        } catch (e) {
+          lastErr = e;
+          if (e.status === 429) { await new Promise((ok) => setTimeout(ok, 15000 * (attempt + 1))); continue; }
+          if (e.status === 401) { token = gcloudToken(); continue; }
+          break; // 404/400 → next route
+        }
+      }
+    }
+    throw lastErr;
+  };
+}