@elizaos/shared 2.0.0-beta.1 → 2.0.3-beta.2

package/utils/tts-debug.js

@@ -0,0 +1,73 @@
+/// <reference types="vite/client" />
+/**
+ * TTS pipeline tracing (opt-in). Prefix: `[eliza][tts]`.
+ * Never pass secrets in `detail`. With debug on, `preview` fields may contain
+ * user-visible spoken text — disable in shared logs / production.
+ *
+ * Playback phases (browser console): `play:web-audio:start|end` (ElevenLabs /
+ * cloud MP3), `speakBrowser:enter`, `play:browser:web-speech:enqueued`,
+ * `play:browser:speechSynthesis:start|end|error`, `play:talkmode:dispatch|speak-failed`,
+ * `play:browser:no-synth`. Server logs: `server:cloud-tts:*` (includes optional
+ * `messageId`, `clipSegment`, `hearingFull` when the client sends
+ * `x-elizaos-tts-*` headers on `/api/tts/cloud`), ChatView: `chat:*`.
+ *
+ * Enable with:
+ * - **Node / API:** `ELIZA_TTS_DEBUG=1` (or `true`, `yes`, `on`) — logs appear in the API
+ *   terminal / `[api]` aggregator only for **server** routes (e.g. `server:cloud-tts:*`).
+ * - **Renderer (WebView / browser):** same env is mirrored via Vite `define` in
+ *   `apps/app/vite.config.ts` when you start dev with `ELIZA_TTS_DEBUG=1`. Those lines
+ *   go to the **renderer** JavaScript console (Electrobun: Web Inspector on the window),
+ *   not `LOG_LEVEL` on the API process alone.
+ */
+function ttsDebugEnabled() {
+    const truthy = (raw) => {
+        if (raw == null)
+            return false;
+        const v = String(raw).trim().toLowerCase();
+        return v === "1" || v === "true" || v === "yes" || v === "on";
+    };
+    if (typeof process !== "undefined" && process.env) {
+        if (truthy(process.env.ELIZA_TTS_DEBUG))
+            return true;
+    }
+    try {
+        // Use static `import.meta.env.*` so Vite `define` can replace ELIZA_TTS_DEBUG at build time.
+        if (truthy(String(import.meta.env.ELIZA_TTS_DEBUG ?? "")))
+            return true;
+        if (truthy(String(import.meta.env.VITE_ELIZA_TTS_DEBUG ?? "")))
+            return true;
+    }
+    catch {
+        /* no import.meta */
+    }
+    return false;
+}
+/** Same predicate as `ttsDebug` — use to attach optional debug headers / task metadata. */
+export function isTtsDebugEnabled() {
+    return ttsDebugEnabled();
+}
+const DEFAULT_PREVIEW_MAX = 160;
+/**
+ * Single-line preview of text for TTS debug logs (avoids huge console lines).
+ * Enable `ELIZA_TTS_DEBUG` only when you accept that spoken lines may appear in logs.
+ */
+export function ttsDebugTextPreview(text, maxChars = DEFAULT_PREVIEW_MAX) {
+    const singleLine = text.replace(/\r?\n/g, "↵ ").replace(/\s+/g, " ").trim();
+    if (singleLine.length <= maxChars)
+        return singleLine;
+    return `${singleLine.slice(0, maxChars)}…`;
+}
+/**
+ * Sink for TTS debug output. Set by the host app (e.g. pino on the server,
+ * Web Inspector in the renderer). Null disables debug output.
+ */
+let _ttsSink = null;
+export function setTtsDebugSink(sink) {
+    _ttsSink = sink;
+}
+export function ttsDebug(phase, detail) {
+    if (!ttsDebugEnabled() || !_ttsSink)
+        return;
+    _ttsSink(phase, detail);
+}
+//# sourceMappingURL=tts-debug.js.map

package/utils/tts-debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tts-debug.js","sourceRoot":"","sources":["../../src/utils/tts-debug.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAErC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,SAAS,eAAe;IACtB,MAAM,MAAM,GAAG,CAAC,GAA8B,EAAW,EAAE;QACzD,IAAI,GAAG,IAAI,IAAI;YAAE,OAAO,KAAK,CAAC;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI,CAAC;IAChE,CAAC,CAAC;IAEF,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAClD,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;YAAE,OAAO,IAAI,CAAC;IACvD,CAAC;IAED,IAAI,CAAC;QACH,6FAA6F;QAC7F,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACvE,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,oBAAoB;IACtB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,iBAAiB;IAC/B,OAAO,eAAe,EAAE,CAAC;AAC3B,CAAC;AAED,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,WAAmB,mBAAmB;IAEtC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5E,IAAI,UAAU,CAAC,MAAM,IAAI,QAAQ;QAAE,OAAO,UAAU,CAAC;IACrD,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,IAAI,QAAQ,GAED,IAAI,CAAC;AAEhB,MAAM,UAAU,eAAe,CAC7B,IAAwE;IAExE,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,KAAa,EACb,MAAgC;IAEhC,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,QAAQ;QAAE,OAAO;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAC1B,CAAC"}

package/view-hero-art.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Branded hero-image generator for plugin **views**.
+ *
+ * A view is a mini-app contributed by a plugin (`Plugin.views`). Each one is
+ * served a square hero image at `/api/views/<id>/hero`. Real heroes live in the
+ * plugin at `assets/hero.<ext>`; when a plugin ships none, the agent serves a
+ * generated SVG produced here so the catalog never shows a broken or ugly tile.
+ *
+ * The composition is intentionally **no-blue-dominant** (the app surface forbids
+ * blue accents — orange/jewel tones only) and **deterministic**: the same input
+ * always yields byte-identical output, so `scripts/generate-view-heroes.mjs`
+ * (which commits real heroes into plugins) and the runtime fallback render the
+ * exact same art. This is the single source of truth for that art — the script
+ * and the agent both import `renderViewHeroSvg` from here.
+ *
+ * Pure string generation only: no Node APIs, so this module stays importable
+ * from the runtime-agnostic `@elizaos/shared` barrel (browser + server).
+ */
+export interface ViewHeroFrameInput {
+    /** Stable slug used to namespace SVG gradient/filter ids. */
+    id: string;
+    /** Accent hue (0–359). Keep out of the pure-blue band for the app surface. */
+    hue: number;
+    /** Inline SVG markup for the centered line-icon glyph. */
+    iconSvg: string;
+    /** Display label rendered along the bottom. */
+    label: string;
+}
+/**
+ * Render the full branded hero SVG. Shared chrome (defs, background, depth
+ * blobs, faint grid, accent arc, bottom label + vignette) with the icon glyph
+ * slotted in. Output is deterministic and byte-identical for identical input.
+ */
+export declare function renderViewHeroSvg({ id, hue, iconSvg, label, }: ViewHeroFrameInput): string;
+/**
+ * Hand-drawn vector line-icons, centered at (0,0) spanning roughly -150..150.
+ * Each inherits stroke styling from the parent <g>; fills are set explicitly
+ * where a filled glyph reads better. Keyed names map to the catalog below.
+ */
+export declare const VIEW_HERO_ICONS: {
+    readonly modelTester: "    <rect x=\"-110\" y=\"-110\" width=\"220\" height=\"220\" rx=\"28\"/>\n    <rect x=\"-58\" y=\"-58\" width=\"116\" height=\"116\" rx=\"14\"/>\n    <line x1=\"-110\" y1=\"-66\" x2=\"-150\" y2=\"-66\"/>\n    <line x1=\"-110\" y1=\"0\" x2=\"-150\" y2=\"0\"/>\n    <line x1=\"-110\" y1=\"66\" x2=\"-150\" y2=\"66\"/>\n    <line x1=\"110\" y1=\"-66\" x2=\"150\" y2=\"-66\"/>\n    <line x1=\"110\" y1=\"0\" x2=\"150\" y2=\"0\"/>\n    <line x1=\"110\" y1=\"66\" x2=\"150\" y2=\"66\"/>\n    <line x1=\"-66\" y1=\"-110\" x2=\"-66\" y2=\"-150\"/>\n    <line x1=\"0\" y1=\"-110\" x2=\"0\" y2=\"-150\"/>\n    <line x1=\"66\" y1=\"-110\" x2=\"66\" y2=\"-150\"/>\n    <line x1=\"-66\" y1=\"110\" x2=\"-66\" y2=\"150\"/>\n    <line x1=\"0\" y1=\"110\" x2=\"0\" y2=\"150\"/>\n    <line x1=\"66\" y1=\"110\" x2=\"66\" y2=\"150\"/>\n    <circle cx=\"0\" cy=\"0\" r=\"14\" stroke-width=\"0\" fill=\"currentColor\"/>";
+    readonly views: "    <rect x=\"-150\" y=\"-150\" width=\"130\" height=\"130\" rx=\"18\"/>\n    <rect x=\"20\" y=\"-150\" width=\"130\" height=\"130\" rx=\"18\"/>\n    <rect x=\"-150\" y=\"20\" width=\"130\" height=\"130\" rx=\"18\"/>\n    <rect x=\"20\" y=\"20\" width=\"130\" height=\"130\" rx=\"18\"/>";
+    readonly focus: "    <path d=\"M0 -150 L130 -100 L130 24 C130 110 70 152 0 175 C-70 152 -130 110 -130 24 L-130 -100 Z\"/>\n    <circle cx=\"0\" cy=\"-2\" r=\"34\"/>\n    <line x1=\"-92\" y1=\"-96\" x2=\"96\" y2=\"120\"/>";
+    readonly calendar: "    <rect x=\"-140\" y=\"-118\" width=\"280\" height=\"248\" rx=\"24\"/>\n    <line x1=\"-140\" y1=\"-52\" x2=\"140\" y2=\"-52\"/>\n    <line x1=\"-78\" y1=\"-150\" x2=\"-78\" y2=\"-92\"/>\n    <line x1=\"78\" y1=\"-150\" x2=\"78\" y2=\"-92\"/>\n    <circle cx=\"-66\" cy=\"6\" r=\"11\" stroke-width=\"0\" fill=\"currentColor\"/>\n    <circle cx=\"0\" cy=\"6\" r=\"11\" stroke-width=\"0\" fill=\"currentColor\"/>\n    <circle cx=\"66\" cy=\"6\" r=\"11\" stroke-width=\"0\" fill=\"currentColor\"/>\n    <circle cx=\"-66\" cy=\"72\" r=\"11\" stroke-width=\"0\" fill=\"currentColor\"/>\n    <circle cx=\"0\" cy=\"72\" r=\"11\" stroke-width=\"0\" fill=\"currentColor\"/>";
+    readonly headphones: "    <path d=\"M-140 30 V-10 A140 140 0 0 1 140 -10 V30\"/>\n    <rect x=\"-160\" y=\"26\" width=\"58\" height=\"110\" rx=\"26\" fill=\"currentColor\" stroke-width=\"0\"/>\n    <rect x=\"102\" y=\"26\" width=\"58\" height=\"110\" rx=\"26\" fill=\"currentColor\" stroke-width=\"0\"/>\n    <rect x=\"-160\" y=\"26\" width=\"58\" height=\"110\" rx=\"26\"/>\n    <rect x=\"102\" y=\"26\" width=\"58\" height=\"110\" rx=\"26\"/>";
+    readonly glasses: "    <circle cx=\"-86\" cy=\"20\" r=\"68\"/>\n    <circle cx=\"86\" cy=\"20\" r=\"68\"/>\n    <path d=\"M-18 20 Q0 -2 18 20\"/>\n    <line x1=\"-154\" y1=\"-12\" x2=\"-180\" y2=\"-44\"/>\n    <line x1=\"154\" y1=\"-12\" x2=\"180\" y2=\"-44\"/>";
+    readonly finances: "    <polyline points=\"-150,-150 -150,150 150,150\"/>\n    <polyline points=\"-118,86 -50,-2 6,52 76,-62 132,-104\" fill=\"none\"/>\n    <circle cx=\"-50\" cy=\"-2\" r=\"13\" stroke-width=\"0\" fill=\"currentColor\"/>\n    <circle cx=\"76\" cy=\"-62\" r=\"13\" stroke-width=\"0\" fill=\"currentColor\"/>\n    <circle cx=\"132\" cy=\"-104\" r=\"13\" stroke-width=\"0\" fill=\"currentColor\"/>";
+    readonly goals: "    <circle cx=\"0\" cy=\"0\" r=\"150\"/>\n    <circle cx=\"0\" cy=\"0\" r=\"92\"/>\n    <circle cx=\"0\" cy=\"0\" r=\"34\"/>\n    <circle cx=\"0\" cy=\"0\" r=\"9\" stroke-width=\"0\" fill=\"currentColor\"/>";
+    readonly health: "    <path d=\"M0 150 C-180 18 -120 -120 0 -52 C120 -120 180 18 0 150 Z\"/>\n    <polyline points=\"-150,-10 -64,-10 -28,-58 14,52 48,-10 150,-10\" fill=\"none\"/>";
+    readonly inbox: "    <path d=\"M-150 -40 L-110 -130 H110 L150 -40 V120 A20 20 0 0 1 130 140 H-130 A20 20 0 0 1 -150 120 Z\"/>\n    <path d=\"M-150 -40 H-44 L-10 24 H10 L44 -40 H150\"/>";
+    readonly messages: "    <path d=\"M-150 -120 H150 A24 24 0 0 1 174 -96 V60 A24 24 0 0 1 150 84 H-30 L-100 150 V84 H-150 A24 24 0 0 1 -174 60 V-96 A24 24 0 0 1 -150 -120 Z\"/>\n    <line x1=\"-100\" y1=\"-44\" x2=\"100\" y2=\"-44\"/>\n    <line x1=\"-100\" y1=\"16\" x2=\"40\" y2=\"16\"/>";
+    readonly socialAlpha: "    <polyline points=\"-150,80 -54,-22 6,38 150,-110\" fill=\"none\"/>\n    <polyline points=\"92,-110 150,-110 150,-52\" fill=\"none\"/>\n    <circle cx=\"-110\" cy=\"128\" r=\"26\"/>\n    <circle cx=\"0\" cy=\"128\" r=\"26\"/>\n    <circle cx=\"110\" cy=\"128\" r=\"26\"/>";
+    readonly todos: "    <rect x=\"-150\" y=\"-150\" width=\"300\" height=\"300\" rx=\"36\"/>\n    <polyline points=\"-92,-6 -36,52 92,-78\" fill=\"none\"/>";
+    readonly vectorBrowser: "    <line x1=\"-110\" y1=\"-96\" x2=\"0\" y2=\"0\"/>\n    <line x1=\"120\" y1=\"-110\" x2=\"0\" y2=\"0\"/>\n    <line x1=\"-130\" y1=\"86\" x2=\"0\" y2=\"0\"/>\n    <line x1=\"110\" y1=\"104\" x2=\"0\" y2=\"0\"/>\n    <circle cx=\"0\" cy=\"0\" r=\"30\" fill=\"currentColor\" stroke-width=\"0\"/>\n    <circle cx=\"0\" cy=\"0\" r=\"30\"/>\n    <circle cx=\"-110\" cy=\"-96\" r=\"22\"/>\n    <circle cx=\"120\" cy=\"-110\" r=\"22\"/>\n    <circle cx=\"-130\" cy=\"86\" r=\"22\"/>\n    <circle cx=\"110\" cy=\"104\" r=\"22\"/>";
+};
+export type ViewHeroIconKind = keyof typeof VIEW_HERO_ICONS;
+/** Deterministically pick a non-blue accent hue for an arbitrary view key. */
+export declare function hueForViewKey(key: string): number;
+export interface ViewHeroSource {
+    id?: string;
+    label: string;
+    /** Lucide icon name declared by the view, used as a keyword hint. */
+    icon?: string;
+    tags?: readonly string[];
+}
+/** Pick the best-matching icon glyph for a view, defaulting to the grid. */
+export declare function pickViewHeroIcon(source: ViewHeroSource): ViewHeroIconKind;
+/**
+ * High-level entry point: render a branded hero SVG for a view, choosing the
+ * accent hue and icon glyph automatically from the view's metadata. Used by the
+ * agent's hero fallback and by view scaffolding/icon-regeneration so a generated
+ * hero looks the same everywhere.
+ */
+export declare function generateViewHeroSvgFor(source: ViewHeroSource): string;
+//# sourceMappingURL=view-hero-art.d.ts.map

package/view-hero-art.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-hero-art.d.ts","sourceRoot":"","sources":["../src/view-hero-art.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AA0DH,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,EAAE,EACF,GAAG,EACH,OAAO,EACP,KAAK,GACN,EAAE,kBAAkB,GAAG,MAAM,CAuE7B;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;CAsGlB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,eAAe,CAAC;AAmB5D,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGjD;AAyDD,MAAM,WAAW,cAAc;IAC7B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,CAazE;AAWD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAQrE"}

package/view-hero-art.js

@@ -0,0 +1,360 @@
+/**
+ * Branded hero-image generator for plugin **views**.
+ *
+ * A view is a mini-app contributed by a plugin (`Plugin.views`). Each one is
+ * served a square hero image at `/api/views/<id>/hero`. Real heroes live in the
+ * plugin at `assets/hero.<ext>`; when a plugin ships none, the agent serves a
+ * generated SVG produced here so the catalog never shows a broken or ugly tile.
+ *
+ * The composition is intentionally **no-blue-dominant** (the app surface forbids
+ * blue accents — orange/jewel tones only) and **deterministic**: the same input
+ * always yields byte-identical output, so `scripts/generate-view-heroes.mjs`
+ * (which commits real heroes into plugins) and the runtime fallback render the
+ * exact same art. This is the single source of truth for that art — the script
+ * and the agent both import `renderViewHeroSvg` from here.
+ *
+ * Pure string generation only: no Node APIs, so this module stays importable
+ * from the runtime-agnostic `@elizaos/shared` barrel (browser + server).
+ */
+const W = 1024;
+const CX = W / 2;
+/**
+ * Convert an HSL triple to a hex color string. Deterministic, no rounding
+ * surprises across runs.
+ */
+function hsl(h, s, l) {
+    const sN = s / 100;
+    const lN = l / 100;
+    const c = (1 - Math.abs(2 * lN - 1)) * sN;
+    const hp = (((h % 360) + 360) % 360) / 60;
+    const x = c * (1 - Math.abs((hp % 2) - 1));
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    if (hp >= 0 && hp < 1)
+        [r, g, b] = [c, x, 0];
+    else if (hp < 2)
+        [r, g, b] = [x, c, 0];
+    else if (hp < 3)
+        [r, g, b] = [0, c, x];
+    else if (hp < 4)
+        [r, g, b] = [0, x, c];
+    else if (hp < 5)
+        [r, g, b] = [x, 0, c];
+    else
+        [r, g, b] = [c, 0, x];
+    const m = lN - c / 2;
+    const toHex = (v) => Math.round((v + m) * 255)
+        .toString(16)
+        .padStart(2, "0");
+    return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+/**
+ * A palette derived from a single accent hue, kept in a dark, modern register.
+ * Background tones are deep neutrals shifted slightly toward the accent so each
+ * card reads distinct without ever looking like a flat blue panel.
+ */
+function palette(hue) {
+    return {
+        bgTop: hsl(hue, 32, 12),
+        bgBottom: hsl(hue + 14, 40, 7),
+        blobA: hsl(hue, 70, 52),
+        blobB: hsl(hue + 28, 66, 46),
+        accent: hsl(hue, 82, 60),
+        accentSoft: hsl(hue, 70, 70),
+        line: hsl(hue, 30, 88),
+    };
+}
+/**
+ * Render the full branded hero SVG. Shared chrome (defs, background, depth
+ * blobs, faint grid, accent arc, bottom label + vignette) with the icon glyph
+ * slotted in. Output is deterministic and byte-identical for identical input.
+ */
+export function renderViewHeroSvg({ id, hue, iconSvg, label, }) {
+    const p = palette(hue);
+    const safeLabel = escapeXml(label);
+    // Two large blurred blobs placed off-center for asymmetric depth, plus a thin
+    // accent arc sweeping behind the icon.
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${W}" width="${W}" height="${W}" role="img" aria-label="${safeLabel}">
+  <defs>
+    <linearGradient id="bg-${id}" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="${p.bgTop}"/>
+      <stop offset="1" stop-color="${p.bgBottom}"/>
+    </linearGradient>
+    <radialGradient id="blobA-${id}" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="${p.blobA}" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="${p.blobA}" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="blobB-${id}" cx="0.5" cy="0.5" r="0.5">
+      <stop offset="0" stop-color="${p.blobB}" stop-opacity="0.5"/>
+      <stop offset="1" stop-color="${p.blobB}" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="vig-${id}" cx="0.5" cy="0.42" r="0.75">
+      <stop offset="0" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="0.72" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.5"/>
+    </radialGradient>
+    <linearGradient id="label-${id}" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#000000" stop-opacity="0"/>
+      <stop offset="1" stop-color="#000000" stop-opacity="0.55"/>
+    </linearGradient>
+    <filter id="soft-${id}" x="-30%" y="-30%" width="160%" height="160%">
+      <feGaussianBlur stdDeviation="46"/>
+    </filter>
+    <filter id="iglow-${id}" x="-40%" y="-40%" width="180%" height="180%">
+      <feDropShadow dx="0" dy="0" stdDeviation="14" flood-color="${p.accent}" flood-opacity="0.45"/>
+    </filter>
+  </defs>
+
+  <rect width="${W}" height="${W}" fill="url(#bg-${id})"/>
+
+  <g opacity="0.9">
+    <circle cx="232" cy="220" r="300" fill="url(#blobA-${id})" filter="url(#soft-${id})"/>
+    <circle cx="840" cy="800" r="340" fill="url(#blobB-${id})" filter="url(#soft-${id})"/>
+  </g>
+
+  <g stroke="${p.line}" stroke-width="1.4" opacity="0.06">
+    <line x1="0" y1="256" x2="${W}" y2="256"/>
+    <line x1="0" y1="512" x2="${W}" y2="512"/>
+    <line x1="0" y1="768" x2="${W}" y2="768"/>
+    <line x1="256" y1="0" x2="256" y2="${W}"/>
+    <line x1="512" y1="0" x2="512" y2="${W}"/>
+    <line x1="768" y1="0" x2="768" y2="${W}"/>
+  </g>
+
+  <g opacity="0.5">
+    <path d="M120 470 A 400 400 0 0 1 904 470" fill="none" stroke="${p.accent}" stroke-width="3" opacity="0.35"/>
+  </g>
+
+  <g transform="translate(${CX} 432)" filter="url(#iglow-${id})"
+     color="${p.line}" stroke="${p.line}" stroke-width="20"
+     stroke-linecap="round" stroke-linejoin="round" fill="none">
+${iconSvg}
+  </g>
+
+  <rect x="0" y="784" width="${W}" height="240" fill="url(#label-${id})"/>
+  <text x="${CX}" y="892" text-anchor="middle"
+        font-family="system-ui, -apple-system, Segoe UI, Roboto, sans-serif"
+        font-size="76" font-weight="600" letter-spacing="0.5"
+        fill="${p.line}">${safeLabel}</text>
+  <rect x="${CX - 52}" y="924" width="104" height="6" rx="3" fill="${p.accent}"/>
+
+  <rect width="${W}" height="${W}" fill="url(#vig-${id})"/>
+</svg>`;
+}
+/**
+ * Hand-drawn vector line-icons, centered at (0,0) spanning roughly -150..150.
+ * Each inherits stroke styling from the parent <g>; fills are set explicitly
+ * where a filled glyph reads better. Keyed names map to the catalog below.
+ */
+export const VIEW_HERO_ICONS = {
+    // cpu / chip with a beaker spark — Model Tester
+    modelTester: `    <rect x="-110" y="-110" width="220" height="220" rx="28"/>
+    <rect x="-58" y="-58" width="116" height="116" rx="14"/>
+    <line x1="-110" y1="-66" x2="-150" y2="-66"/>
+    <line x1="-110" y1="0" x2="-150" y2="0"/>
+    <line x1="-110" y1="66" x2="-150" y2="66"/>
+    <line x1="110" y1="-66" x2="150" y2="-66"/>
+    <line x1="110" y1="0" x2="150" y2="0"/>
+    <line x1="110" y1="66" x2="150" y2="66"/>
+    <line x1="-66" y1="-110" x2="-66" y2="-150"/>
+    <line x1="0" y1="-110" x2="0" y2="-150"/>
+    <line x1="66" y1="-110" x2="66" y2="-150"/>
+    <line x1="-66" y1="110" x2="-66" y2="150"/>
+    <line x1="0" y1="110" x2="0" y2="150"/>
+    <line x1="66" y1="110" x2="66" y2="150"/>
+    <circle cx="0" cy="0" r="14" stroke-width="0" fill="currentColor"/>`,
+    // overlapping panels — Views (layout grid)
+    views: `    <rect x="-150" y="-150" width="130" height="130" rx="18"/>
+    <rect x="20" y="-150" width="130" height="130" rx="18"/>
+    <rect x="-150" y="20" width="130" height="130" rx="18"/>
+    <rect x="20" y="20" width="130" height="130" rx="18"/>`,
+    // shield with an eye-off slash — Focus / blocker
+    focus: `    <path d="M0 -150 L130 -100 L130 24 C130 110 70 152 0 175 C-70 152 -130 110 -130 24 L-130 -100 Z"/>
+    <circle cx="0" cy="-2" r="34"/>
+    <line x1="-92" y1="-96" x2="96" y2="120"/>`,
+    // calendar grid — Calendar
+    calendar: `    <rect x="-140" y="-118" width="280" height="248" rx="24"/>
+    <line x1="-140" y1="-52" x2="140" y2="-52"/>
+    <line x1="-78" y1="-150" x2="-78" y2="-92"/>
+    <line x1="78" y1="-150" x2="78" y2="-92"/>
+    <circle cx="-66" cy="6" r="11" stroke-width="0" fill="currentColor"/>
+    <circle cx="0" cy="6" r="11" stroke-width="0" fill="currentColor"/>
+    <circle cx="66" cy="6" r="11" stroke-width="0" fill="currentColor"/>
+    <circle cx="-66" cy="72" r="11" stroke-width="0" fill="currentColor"/>
+    <circle cx="0" cy="72" r="11" stroke-width="0" fill="currentColor"/>`,
+    // headphones — Facewear
+    headphones: `    <path d="M-140 30 V-10 A140 140 0 0 1 140 -10 V30"/>
+    <rect x="-160" y="26" width="58" height="110" rx="26" fill="currentColor" stroke-width="0"/>
+    <rect x="102" y="26" width="58" height="110" rx="26" fill="currentColor" stroke-width="0"/>
+    <rect x="-160" y="26" width="58" height="110" rx="26"/>
+    <rect x="102" y="26" width="58" height="110" rx="26"/>`,
+    // glasses — Smartglasses
+    glasses: `    <circle cx="-86" cy="20" r="68"/>
+    <circle cx="86" cy="20" r="68"/>
+    <path d="M-18 20 Q0 -2 18 20"/>
+    <line x1="-154" y1="-12" x2="-180" y2="-44"/>
+    <line x1="154" y1="-12" x2="180" y2="-44"/>`,
+    // line chart rising with axis — Finances
+    finances: `    <polyline points="-150,-150 -150,150 150,150"/>
+    <polyline points="-118,86 -50,-2 6,52 76,-62 132,-104" fill="none"/>
+    <circle cx="-50" cy="-2" r="13" stroke-width="0" fill="currentColor"/>
+    <circle cx="76" cy="-62" r="13" stroke-width="0" fill="currentColor"/>
+    <circle cx="132" cy="-104" r="13" stroke-width="0" fill="currentColor"/>`,
+    // target with center dot and a flag — Goals
+    goals: `    <circle cx="0" cy="0" r="150"/>
+    <circle cx="0" cy="0" r="92"/>
+    <circle cx="0" cy="0" r="34"/>
+    <circle cx="0" cy="0" r="9" stroke-width="0" fill="currentColor"/>`,
+    // heart with a pulse line through it — Health
+    health: `    <path d="M0 150 C-180 18 -120 -120 0 -52 C120 -120 180 18 0 150 Z"/>
+    <polyline points="-150,-10 -64,-10 -28,-58 14,52 48,-10 150,-10" fill="none"/>`,
+    // inbox tray — Inbox
+    inbox: `    <path d="M-150 -40 L-110 -130 H110 L150 -40 V120 A20 20 0 0 1 130 140 H-130 A20 20 0 0 1 -150 120 Z"/>
+    <path d="M-150 -40 H-44 L-10 24 H10 L44 -40 H150"/>`,
+    // chat bubble with lines — Messages
+    messages: `    <path d="M-150 -120 H150 A24 24 0 0 1 174 -96 V60 A24 24 0 0 1 150 84 H-30 L-100 150 V84 H-150 A24 24 0 0 1 -174 60 V-96 A24 24 0 0 1 -150 -120 Z"/>
+    <line x1="-100" y1="-44" x2="100" y2="-44"/>
+    <line x1="-100" y1="16" x2="40" y2="16"/>`,
+    // trending up arrow over people dots — Social Alpha
+    socialAlpha: `    <polyline points="-150,80 -54,-22 6,38 150,-110" fill="none"/>
+    <polyline points="92,-110 150,-110 150,-52" fill="none"/>
+    <circle cx="-110" cy="128" r="26"/>
+    <circle cx="0" cy="128" r="26"/>
+    <circle cx="110" cy="128" r="26"/>`,
+    // checklist square — Todos
+    todos: `    <rect x="-150" y="-150" width="300" height="300" rx="36"/>
+    <polyline points="-92,-6 -36,52 92,-78" fill="none"/>`,
+    // network graph nodes — Vector Browser / Relationships
+    vectorBrowser: `    <line x1="-110" y1="-96" x2="0" y2="0"/>
+    <line x1="120" y1="-110" x2="0" y2="0"/>
+    <line x1="-130" y1="86" x2="0" y2="0"/>
+    <line x1="110" y1="104" x2="0" y2="0"/>
+    <circle cx="0" cy="0" r="30" fill="currentColor" stroke-width="0"/>
+    <circle cx="0" cy="0" r="30"/>
+    <circle cx="-110" cy="-96" r="22"/>
+    <circle cx="120" cy="-110" r="22"/>
+    <circle cx="-130" cy="86" r="22"/>
+    <circle cx="110" cy="104" r="22"/>`,
+};
+/**
+ * Curated, non-blue accent hues spread across warm/jewel tones. Deliberately
+ * excludes the pure-blue band (~200–250) so a generated hero never reads as a
+ * flat blue panel on the app surface.
+ */
+const VIEW_HERO_HUES = [
+    12, 25, 38, 52, 96, 130, 150, 168, 190, 270, 286, 300, 332, 348,
+];
+function hashString(value) {
+    let hash = 0;
+    for (let index = 0; index < value.length; index += 1) {
+        hash = (hash * 31 + value.charCodeAt(index)) | 0;
+    }
+    return Math.abs(hash);
+}
+/** Deterministically pick a non-blue accent hue for an arbitrary view key. */
+export function hueForViewKey(key) {
+    const trimmed = key.trim() || "view";
+    return VIEW_HERO_HUES[hashString(trimmed) % VIEW_HERO_HUES.length];
+}
+/**
+ * Keyword → icon-glyph rules, checked in order. The first rule whose keyword is
+ * present in the view's id/label/tags/Lucide-icon name wins; otherwise the
+ * generic overlapping-panels glyph is used.
+ */
+const ICON_KEYWORD_RULES = [
+    ["calendar", ["calendar", "schedule", "event", "agenda"]],
+    ["health", ["health", "fitness", "heart", "wellness", "medical"]],
+    [
+        "finances",
+        [
+            "finance",
+            "wallet",
+            "money",
+            "payment",
+            "budget",
+            "bank",
+            "trade",
+            "invest",
+        ],
+    ],
+    ["goals", ["goal", "target", "objective", "habit", "routine"]],
+    ["inbox", ["inbox", "mail", "email"]],
+    ["messages", ["message", "chat", "dm", "conversation", "sms"]],
+    [
+        "socialAlpha",
+        ["social", "leaderboard", "trust", "alpha", "feed", "follow"],
+    ],
+    ["todos", ["todo", "task", "checklist", "todos"]],
+    [
+        "vectorBrowser",
+        [
+            "vector",
+            "graph",
+            "relationship",
+            "network",
+            "entity",
+            "embedding",
+            "people",
+            "contact",
+        ],
+    ],
+    [
+        "focus",
+        ["focus", "block", "shield", "guard", "screen-time", "screentime"],
+    ],
+    [
+        "headphones",
+        ["headphone", "audio", "facewear", "wear", "sound", "voice"],
+    ],
+    ["glasses", ["glass", "smartglass", "xr", "spatial", "vision"]],
+    ["modelTester", ["model", "test", "chip", "cpu", "bench", "eval", "train"]],
+];
+/** Pick the best-matching icon glyph for a view, defaulting to the grid. */
+export function pickViewHeroIcon(source) {
+    const haystack = [
+        source.id ?? "",
+        source.label,
+        source.icon ?? "",
+        ...(source.tags ?? []),
+    ]
+        .join(" ")
+        .toLowerCase();
+    for (const [icon, keywords] of ICON_KEYWORD_RULES) {
+        if (keywords.some((keyword) => haystack.includes(keyword)))
+            return icon;
+    }
+    return "views";
+}
+/** Lowercase slug safe to embed in SVG element ids. */
+function slugifyViewId(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "view";
+}
+/**
+ * High-level entry point: render a branded hero SVG for a view, choosing the
+ * accent hue and icon glyph automatically from the view's metadata. Used by the
+ * agent's hero fallback and by view scaffolding/icon-regeneration so a generated
+ * hero looks the same everywhere.
+ */
+export function generateViewHeroSvgFor(source) {
+    const slug = slugifyViewId(source.id ?? source.label);
+    return renderViewHeroSvg({
+        id: slug,
+        hue: hueForViewKey(source.id ?? source.label),
+        iconSvg: VIEW_HERO_ICONS[pickViewHeroIcon(source)],
+        label: source.label,
+    });
+}
+//# sourceMappingURL=view-hero-art.js.map

package/view-hero-art.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-hero-art.js","sourceRoot":"","sources":["../src/view-hero-art.ts"],"names":[],"mappings":"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"}

package/voice/first-sentence-snip.d.ts

@@ -0,0 +1,68 @@
+/**
+ * First-sentence snip helper for the TTS first-line cache.
+ *
+ * Pure, deterministic, no I/O. Both the local runtime and the Eliza Cloud
+ * `/api/v1/voice/tts` route call into this module so that byte-equal sentence
+ * text on either side maps to byte-equal cache keys.
+ *
+ * Algorithm summary (see R4 §2 in `.swarm/research/R4-tts-cache.md`):
+ *   1. Trim leading whitespace.
+ *   2. Walk char-by-char, tracking quote depth (skip terminators inside
+ *      `"..."`/`'...'`/`“...”`), decimal context (digit-`.`-digit isn't a
+ *      boundary), and abbreviation context (e.g. `Mr.`, `e.g.`, `U.S.`).
+ *   3. First surviving terminator (`.`/`!`/`?`/`…`/`。`/`！`/`？`) or `\n`
+ *      ends the sentence. Consume any contiguous run of terminators that
+ *      follow (so `"Wait..."` stays intact).
+ *   4. If no terminator and no newline → null (don't cache unterminated text).
+ *   5. Apply ≤10-word filter on the normalised form. If wordCount > 10,
+ *      return null (don't cache).
+ *
+ * `FIRST_SENTENCE_SNIP_VERSION` is part of the cache key — bumping it
+ * invalidates every existing cached entry.
+ */
+/**
+ * Cache-key algorithm version. Bump when the snip/normalise logic changes
+ * in a way that would produce different keys for the same input. Local and
+ * cloud caches re-key off this constant, so a bump rolls the entire cache.
+ */
+export declare const FIRST_SENTENCE_SNIP_VERSION: "1";
+export type FirstSentenceSnipVersion = typeof FIRST_SENTENCE_SNIP_VERSION;
+/**
+ * Maximum word count (Unicode-aware) for a cacheable first-sentence snip.
+ * Beyond this the bytes won't repeat often enough to amortise the cache.
+ */
+export declare const FIRST_SENTENCE_MAX_WORDS: 10;
+/**
+ * Unicode-aware word count. Hyphenated words and apostrophe-internal words
+ * count as one (e.g. "twenty-three" → 1, "it's" → 1). Dotted acronyms with
+ * single-letter segments (e.g. "U.S.", "U.S.A.") count as one word. Decimal
+ * numbers like "3.14" count as one word.
+ */
+export declare function wordCount(s: string): number;
+/**
+ * Normalise a snip for cache-key purposes. NFC + lower-case + collapse
+ * whitespace + strip trailing terminators/whitespace. Apostrophes preserved.
+ */
+export declare function normalizeForKey(snip: string): string;
+export interface FirstSentenceSnipResult {
+    /** Raw snip including the terminator run, exactly as it appeared. */
+    raw: string;
+    /** Normalised form for cache-key hashing (`normalizeForKey(raw)`). */
+    normalized: string;
+    /** Unicode-aware word count over `normalized`. Always ≤ 10. */
+    wordCount: number;
+    /** End-exclusive offset into the original input where the snip ends. */
+    endOffset: number;
+}
+/**
+ * Attempt to snip the first sentence from `text`. Returns `null` if:
+ *   - input is empty / whitespace only
+ *   - no sentence-terminator found
+ *   - normalised snip has > 10 words
+ *   - normalised snip is empty after stripping terminators
+ *
+ * Otherwise returns a `FirstSentenceSnipResult` carrying the raw and
+ * normalised forms plus the word count.
+ */
+export declare function firstSentenceSnip(text: string): FirstSentenceSnipResult | null;
+//# sourceMappingURL=first-sentence-snip.d.ts.map

package/voice/first-sentence-snip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"first-sentence-snip.d.ts","sourceRoot":"","sources":["../../src/voice/first-sentence-snip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAG,GAAY,CAAC;AACxD,MAAM,MAAM,wBAAwB,GAAG,OAAO,2BAA2B,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAG,EAAW,CAAC;AAuMpD;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAU3C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASpD;AAED,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,GACX,uBAAuB,GAAG,IAAI,CAyBhC"}