genshin-persona 4.2.0 → 4.3.1

package/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "displayName": "Genshin Persona",
   "description": "Speaks as the Genshin Impact character whose birthday is nearest to today: an answer opens with one spoken line in the character's voice and the rest is plain, a joke or a hello is spoken whole, and every line is read aloud in the character's own cloned voice as the reply is written.",
   "author": { "name": "Esposter", "url": "https://github.com/Esposter" },
-  "homepage": "https://esposter.com/docs/infra/claude-interface/persona-plugin",
+  "homepage": "https://github.com/Esposter/Esposter/tree/main/openspec/specs/infra/claude-interface/persona-plugin",
   "repository": "https://github.com/Esposter/Esposter",
   "license": "Apache-2.0",
   "keywords": ["genshin", "genshin-impact", "output-style", "persona", "text-to-speech", "voice-cloning"],

package/README.md

@@ -52,7 +52,7 @@ Spoken lines stay silent until the `voice` verb has set the engine up, once, wit
 node "<plugin root>/scripts/genshin.mjs" voice ja     # or: /genshin-voice ja
 ```
 
-It installs the engine's runtime and weights — about a gigabyte, once — into the plugin's own state directory under `~/.claude/genshin-persona`, and ends by speaking one sentence as the session's character; replies are read aloud from the next reply on, by the plugin's own hooks module, with nothing written into your settings. Each character is read in a clone of their own voice, conditioned on one line of their performance fetched from the community wiki the first time they are picked; nothing lifted from the game ships with the plugin. How the engine runs, which device it settles on and why, and what it does when it cannot speak is the [spoken replies](https://esposter.com/docs/infra/claude-interface/spoken-replies) page.
+It installs the engine's runtime and weights — about a gigabyte, once — into the plugin's own state directory under `~/.claude/genshin-persona`, and ends by speaking one sentence as the session's character; replies are read aloud from the next reply on, by the plugin's own hooks module, with nothing written into your settings. Each character is read in a clone of their own voice, conditioned on one line of their performance fetched from the community wiki the first time they are picked; nothing lifted from the game ships with the plugin. How the engine runs, which device it settles on and why, and what it does when it cannot speak is the [spoken replies](https://github.com/Esposter/Esposter/blob/main/openspec/specs/infra/claude-interface/spoken-replies/design.md) page.
 
 A [TypeSafe](https://typesafe.ai) API key, given as an option, turns the pick over to lore — one typed decision over the whole roster, weighing the date, the season's festivals and your moment — instead of the nearest birthday. The key is sensitive, and the variable the SDK itself reads, `TYPESAFE_API_KEY`, is honoured when the option is empty:
 
@@ -62,7 +62,7 @@ claude plugin install genshin-persona@esposter --config typesafe_key=<key>
 
 ## <a name="documentation">📖 Documentation</a>
 
-We highly recommend you take a look at the [documentation](https://esposter.com/docs/infra/claude-interface/persona-plugin) to level up.
+We highly recommend you take a look at the [documentation](https://github.com/Esposter/Esposter/tree/main/openspec/specs/infra/claude-interface/persona-plugin) to level up.
 
 ### Command reference
 
@@ -75,21 +75,22 @@ node "<plugin root>/scripts/genshin.mjs" <verb> [argument]
 
 A `<name>` is a character's, matched whole and ignoring case, in English or as the interface language spells it. A `[language]` is one the `language` verb lists, typed in English or in its own words. A verb given a name the roster has no character by, or an argument outside its set, prints why and exits 1; a verb with no argument where one is optional reports instead of changing anything.
 
-| Verb       | Argument                 | What it does                                                                                                                                                                                                                         |
-| :--------- | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `today`    | —                        | Prints the card of this session's character; from a shell, of the pinned character, else of a fresh pick. A pin naming nobody in the roster is reported and ignored.                                                                 |
-| `roster`   | —                        | Every playable character, one line each: name, title, element, region, birthday and the patch that introduced them.                                                                                                                  |
-| `use`      | `<name>`                 | Speaks as one character for this session alone, from that reply on; other sessions and the next start are untouched. From a shell, where no session is running, exits 1.                                                             |
-| `pin`      | `<name>`                 | Fixes one character for every session until unpinned, and for this session from that reply on.                                                                                                                                       |
-| `unpin`    | —                        | Removes the pin; the pick decides again from the next session, and for this session from that reply on.                                                                                                                              |
-| `voice`    | `[en \| ja \| ko \| zh]` | Sets up spoken lines in that dub — installing the engine's runtime and weights on the first run, about a gigabyte — and ends by speaking one sentence; replies are read from the next reply on. With no dub, reports what is set up. |
-| `mute`     | —                        | Stops replies' spoken lines being read aloud. The pick and the card are unaffected.                                                                                                                                                  |
-| `unmute`   | —                        | Lets replies' spoken lines be read aloud again.                                                                                                                                                                                      |
-| `volume`   | `<0–100>`                | Sets how loud replies are spoken, as a whole number, from the next reply on; `0` is silence the engine is not woken for.                                                                                                             |
-| `language` | `[language]`             | Sets the interface language — every word the plugin writes — and carries the reply language with it. With none, reports what is set and lists the languages on offer.                                                                |
-| `reply`    | `[language]`             | Sets the language replies are written in, on its own. With none, reports what is set and whether it was set or cascaded from the interface language.                                                                                 |
-| `status`   | —                        | Reports every setting at once and where each value came from. Changes nothing.                                                                                                                                                       |
-| `teardown` | —                        | Removes what `voice` installed: the runtime, the weights, the cached clips and the dub. The picks, the pin and the languages stay; `voice` brings spoken lines back.                                                                 |
+| Verb       | Argument                 | What it does                                                                                                                                                                                                                                                                                                                              |
+| :--------- | :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `today`    | —                        | Prints the card of this session's character; from a shell, of the pinned character, else of a fresh pick. A pin naming nobody in the roster is reported and ignored.                                                                                                                                                                      |
+| `roster`   | —                        | Every playable character, one line each: name, title, element, region, birthday and the patch that introduced them.                                                                                                                                                                                                                       |
+| `use`      | `<name>`                 | Speaks as one character for this session alone, from that reply on; other sessions and the next start are untouched. From a shell, where no session is running, exits 1.                                                                                                                                                                  |
+| `pin`      | `<name>`                 | Fixes one character for every session until unpinned, and for this session from that reply on.                                                                                                                                                                                                                                            |
+| `unpin`    | —                        | Removes the pin; the pick decides again from the next session, and for this session from that reply on.                                                                                                                                                                                                                                   |
+| `voice`    | `[en \| ja \| ko \| zh]` | Sets up spoken lines in that dub — installing the engine's runtime and weights on the first run, about a gigabyte — and ends by speaking one sentence; replies are read from the next reply on. With no dub, reports what is set up.                                                                                                      |
+| `mute`     | —                        | Stops replies' spoken lines being read aloud. The pick and the card are unaffected.                                                                                                                                                                                                                                                       |
+| `unmute`   | —                        | Lets replies' spoken lines be read aloud again.                                                                                                                                                                                                                                                                                           |
+| `volume`   | `<0–100>`                | Sets how loud replies are spoken, as a whole number, from the next reply on; `0` is silence the engine is not woken for.                                                                                                                                                                                                                  |
+| `language` | `[language]`             | Sets the interface language — every word the plugin writes — and carries the reply language with it. With none, reports what is set and lists the languages on offer.                                                                                                                                                                     |
+| `reply`    | `[language]`             | Sets the language replies are written in, on its own. With none, reports what is set and whether it was set or cascaded from the interface language.                                                                                                                                                                                      |
+| `status`   | —                        | Reports every setting at once and where each value came from. Changes nothing.                                                                                                                                                                                                                                                            |
+| `teardown` | —                        | Removes what `voice` installed — the runtime, the weights, the cached clips and the dub — and the viewer’s setup. The picks, the pin and the languages stay; `voice` brings spoken lines back.                                                                                                                                            |
+| `viewer`   | `[address] [model]`      | Shows each spoken line as a bubble on a Live2DViewerEX model and sounds it there, the stock player as the fallback; with none, reports what is set. `viewer motions <attention                                                       \| turnEnd> <group:motion>` maps a motion to a moment, and a tap on the model replays the last line. |
 
 Four more are the authoring queues of one more skill, `genshin-author` — script-only and on no menu:
 
@@ -102,23 +103,23 @@ Four more are the authoring queues of one more skill, `genshin-author` — scrip
 
 ### What it ships
 
-| Component                              | Role                                                                                                                                                                                                                                          |
-| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `hooks/hooks.json`                     | A session-start hook that picks the character, greets you with its name, what the pick weighed and who is close, and prints its card as context, and the hooks module beside it.                                                              |
-| `mod/`                                 | The hooks module: the spinner's verbs and the prompt hint's tips of this session's character, the spoken replies, and one slash command per verb.                                                                                             |
-| `types/index.d.ts`                     | The state the hooks module publishes — the session's character and its colour — which other plugins draw by.                                                                                                                                  |
-| `output-styles/in-character.md`        | The standing rules, forced on while the plugin is enabled: a blockquote line is the character's spoken line, the ask decides how much of a reply that is, and the rest is plain.                                                              |
-| `skills/genshin/SKILL.md`              | The model's route from a request in words to one of the verbs; hidden from the menu.                                                                                                                                                          |
-| `skills/genshin-author/SKILL.md`       | How a persona card and its spinner verbs are written, the command that prints a character's own lines to write from, and the two queues.                                                                                                      |
-| `src/personaCards/`                    | Authored persona cards, one typed module per character, in our words: how the character speaks for the model, their spinner verbs for you, and the reference line only where an ear chose one.                                                |
-| `src/generated/PersonaReferenceMap.ts` | The measured reference line and its likeness per character, one generated map written by the repository's reference selection and never by hand.                                                                                              |
-| `runtime/`                             | The manifest and lockfile of the speech engine's runtime, which the `voice` verb installs into the state directory rather than the plugin carrying it.                                                                                        |
-| `src/localizations/`                   | One authored module per language for the words the data package does not carry: the base Teyvat verbs, each character's spinner gerunds, and every line the verbs print.                                                                      |
-| `scripts/`                             | The session-start hook, the commands' script, the character and spinner the hooks module reads, the status line a person can name in their settings, and the resident synthesizer, each an `.mjs` that registers `tsx` before its TypeScript. |
+| Component                              | Role                                                                                                                                                                                                                                                                                                                                                                       |
+| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hooks/hooks.json`                     | Three hooks, and the hooks module beside them. A `SessionStart` hook picks the character, greets you with its name, what the pick weighed and who is close, and prints its card as context. A `Notification` hook sends the viewer the motion mapped to attention wanted. A `Stop` hook sends the viewer the motion mapped to the end of a turn and clears its expression. |
+| `mod/`                                 | The hooks module: the spinner's verbs and the prompt hint's tips of this session's character, the spoken replies, and one slash command per verb.                                                                                                                                                                                                                          |
+| `types/index.d.ts`                     | The state the hooks module publishes — the session's character and its colour — which other plugins draw by.                                                                                                                                                                                                                                                               |
+| `output-styles/in-character.md`        | The standing rules, forced on while the plugin is enabled: a blockquote line is the character's spoken line, the ask decides how much of a reply that is, and the rest is plain.                                                                                                                                                                                           |
+| `skills/genshin/SKILL.md`              | The model's route from a request in words to one of the verbs; hidden from the menu.                                                                                                                                                                                                                                                                                       |
+| `skills/genshin-author/SKILL.md`       | How a persona card and its spinner verbs are written, the command that prints a character's own lines to write from, and the two queues.                                                                                                                                                                                                                                   |
+| `src/personaCards/`                    | Authored persona cards, one typed module per character, in our words: how the character speaks for the model, their spinner verbs for you, and the reference line only where an ear chose one.                                                                                                                                                                             |
+| `src/generated/PersonaReferenceMap.ts` | The measured reference line and its likeness per character, one generated map written by the repository's reference selection and never by hand.                                                                                                                                                                                                                           |
+| `runtime/`                             | The manifest and lockfile of the speech engine's runtime, which the `voice` verb installs into the state directory rather than the plugin carrying it.                                                                                                                                                                                                                     |
+| `src/localizations/`                   | One authored module per language for the words the data package does not carry: the base Teyvat verbs, each character's spinner gerunds, and every line the verbs print.                                                                                                                                                                                                   |
+| `scripts/`                             | The session-start hook, the commands' script, the character and spinner the hooks module reads, the status line a person can name in their settings, and the resident synthesizer, each an `.mjs` that registers `tsx` before its TypeScript.                                                                                                                              |
 
 ### Spinner and prompt hint
 
-Nothing to set up: the hooks module turns the spinner's words into the session's character's verbs and the prompt hint into one of their lines under their name, a new one each turn, names the character among the labels at the right of the prompt's footer, and publishes the character's colour, which [`genshin-mods`](https://github.com/Esposter/Esposter/tree/main/packages/genshin-mods) draws its band in. Each session draws its own character, and a switch shows at once. Why each is shaped as it is: the [persona plugin](https://esposter.com/docs/infra/claude-interface/persona-plugin) page.
+Nothing to set up: the hooks module turns the spinner's words into the session's character's verbs and the prompt hint into one of their lines under their name, a new one each turn, names the character among the labels at the right of the prompt's footer, and publishes the character's colour, which [`genshin-mods`](https://github.com/Esposter/Esposter/tree/main/packages/genshin-mods) draws its band in. Each session draws its own character, and a switch shows at once. Why each is shaped as it is: the [persona plugin](https://github.com/Esposter/Esposter/tree/main/openspec/specs/infra/claude-interface/persona-plugin) page.
 
 The plugin writes nothing into your settings, so your own status line stays yours. To have it show the character's nameplate, the name in their colour on a badge of that colour's tone, point it at the script the plugin ships:
 
@@ -136,7 +137,7 @@ node "<plugin root>/scripts/genshin.mjs" reply english       # labels in one lan
 node "<plugin root>/scripts/genshin.mjs" status              # every setting, and where each value came from
 ```
 
-The languages on offer are the data package's, so `language` with no argument lists them, each in its own words beside the word you type for it, and either resolves. What arrives localized for nothing and what is written by hand per language is the [persona plugin](https://esposter.com/docs/infra/claude-interface/persona-plugin) page's.
+The languages on offer are the data package's, so `language` with no argument lists them, each in its own words beside the word you type for it, and either resolves. What arrives localized for nothing and what is written by hand per language is the [persona plugin](https://github.com/Esposter/Esposter/tree/main/openspec/specs/infra/claude-interface/persona-plugin) page's.
 
 ### How the character is picked
 
@@ -158,7 +159,7 @@ A reply to an ask of the assistant opens with one blockquote line in the charact
 node "<plugin root>/scripts/genshin.mjs" volume 60     # or: /genshin-volume 60
 ```
 
-`teardown` removes the runtime, the weights, the cached clips and the dub, and spoken lines stay silent until `voice` sets them up again.
+`teardown` removes the runtime, the weights, the cached clips, the dub and the viewer, and spoken lines stay silent until `voice` sets them up again.
 
 ### Commands
 
@@ -170,7 +171,7 @@ pnpm lint:fix     # auto-fix lint
 pnpm typecheck    # type check
 ```
 
-The plugin holds no image, audio or text from the game: the character data arrives through its MIT-licensed dependency, and every persona card is written in our own words.
+The plugin holds no image or audio from the game. Its game text, the character lines and the game's strings in fifteen languages, is committed as generated slices; the character data arrives through its MIT-licensed dependency, and every persona card is written in our own words.
 
 ## <a name="license">⚖️ License</a>
 

package/hooks/hooks.json

@@ -1,6 +1,14 @@
 {
   "hooks": {
-    "SessionStart": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pick.mjs\"" }] }]
+    "Notification": [
+      { "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/react.mjs\" attention" }] }
+    ],
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pick.mjs\"" }] }
+    ],
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/react.mjs\" turnEnd" }] }
+    ]
   },
   "modules": ["../mod/register.ts"]
 }

package/mod/VerbDescriptionMap.ts

@@ -11,11 +11,13 @@ export const VerbDescriptionMap: Partial<Record<GenshinVerb, string>> = {
   [GenshinVerb.Roster]: "Every playable character, one line each.",
   [GenshinVerb.Status]: "Reports every setting the plugin holds and where each came from. Changes nothing.",
   [GenshinVerb.Teardown]:
-    "Removes the voice's runtime, weights, references and dub; the picks, the pin and the languages stay.",
+    "Removes the voice's runtime, weights, references and dub, and the viewer; the picks, the pin and the languages stay.",
   [GenshinVerb.Today]: "The card of this session's character.",
   [GenshinVerb.Unmute]: "Lets replies' spoken lines be read aloud again.",
   [GenshinVerb.Unpin]: "Removes the pin; the pick decides again, for this session from this reply on.",
   [GenshinVerb.Use]: "Speaks as one character for this session alone, from this reply on.",
+  [GenshinVerb.Viewer]:
+    "Shows replies' spoken lines on a Live2DViewerEX model and maps its motions to the terminal's moments; given nothing, reports the viewer on file.",
   [GenshinVerb.Voice]:
     "Sets up spoken replies in the character's own cloned voice, or switches the dub (en, ja, ko or zh); given nothing, reports what is installed.",
   [GenshinVerb.Volume]: "Sets how loud replies are spoken, as a whole number from 0 to 100.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genshin-persona",
-  "version": "4.2.0",
+  "version": "4.3.1",
   "description": "A Claude Code plugin that speaks as the Genshin Impact character whose birthday is nearest: an answer opens with one spoken line in the character's voice and the rest is plain, a joke or a hello is spoken whole, and every line is read aloud in the character's own cloned voice as the reply is written.",
   "keywords": [
     "claude-code",
@@ -12,7 +12,7 @@
     "text-to-speech",
     "voice-cloning"
   ],
-  "homepage": "https://esposter.com/docs/infra/claude-interface/persona-plugin",
+  "homepage": "https://github.com/Esposter/Esposter/tree/main/openspec/specs/infra/claude-interface/persona-plugin",
   "bugs": {
     "url": "https://github.com/Esposter/Esposter/issues"
   },
@@ -47,8 +47,6 @@
     "access": "public"
   },
   "scripts": {
-    "format": "oxfmt",
-    "format:check": "oxfmt --check",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "test": "vitest",
@@ -56,14 +54,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@typesafe-ai/sdk": "^0.6.0",
+    "@typesafe-ai/sdk": "^0.7.0",
     "@wasm-audio-decoders/ogg-vorbis": "^0.1.20",
     "citty": "^0.2.2",
     "genshin-db": "^5.2.14",
     "tsx": "^4.23.15"
   },
   "engines": {
-    "node": ">=26.11.1"
+    "node": ">=26.12.0"
   },
-  "gitHead": "fef4971cf6a621a2c1850f32fcec19ee4ec0de99"
+  "gitHead": "777a39636b789c13af33ed13370246ccf6dbaf31"
 }

package/scripts/pick.ts

@@ -2,6 +2,7 @@ import { deliverWarmRequest } from "#src/services/deliverWarmRequest";
 import { formatLoreChart } from "#src/services/formatLoreChart";
 import { formatUpcomingBirthdays } from "#src/services/formatUpcomingBirthdays";
 import { getCard } from "#src/services/getCard";
+import { getLoreRates } from "#src/services/getLoreRates";
 import { getSessionStartOutput } from "#src/services/getSessionStartOutput";
 import { readInterfaceLanguage } from "#src/services/readInterfaceLanguage";
 import { readLocalization } from "#src/services/readLocalization";
@@ -28,16 +29,17 @@ if (pick) {
   const localization = await readLocalization(language);
   const personaCard = await readPersonaCard(character.name);
   const card = getCard(character, today, localization, personaCard);
+  const loreRates = loreResponse ? getLoreRates(loreResponse, roster) : [];
   // What the welcome says under the note: why the tier fell through when it did, the tier's leaning when it chose
   // And who is close when it did not, and the voice once one is set up
   const remarks = [
     loreFailure && localization.strings.lorePickUnanswered(loreFailure),
     loreResponse
-      ? formatLoreChart(loreResponse, roster, localization)
+      ? formatLoreChart(loreRates, localization)
       : formatUpcomingBirthdays(roster, today, character.name, localization),
     readVoiceRemark(localization.strings),
   ];
   // The warm waits for no more than a synthesizer's bind
   await deliverWarmRequest(character.name, personaCard);
-  console.log(getSessionStartOutput(card, remarks, readReplyLanguage() ?? language, language));
+  console.log(getSessionStartOutput(card, remarks, readReplyLanguage() ?? language, language, loreRates));
 }

package/scripts/react.mjs

@@ -0,0 +1,5 @@
+// Node strips types and takes no `enum`, so the entry registers tsx before it loads its TypeScript
+import { register } from "tsx/esm/api";
+
+register();
+await import("#scripts/react");

package/scripts/react.ts

@@ -0,0 +1,34 @@
+import { checkIsViewerMoment } from "#src/services/checkIsViewerMoment";
+import { connectViewer } from "#src/services/connectViewer";
+import { getViewerReaction } from "#src/services/getViewerReaction";
+import { readViewerConfiguration } from "#src/services/readViewerConfiguration";
+import { runHookCommand } from "#src/services/runHookCommand";
+import { defineCommand } from "citty";
+
+// The Notification and Stop hooks, each naming its moment on the command line: the model is sent what the reader
+// Mapped to that moment, and nothing with no viewer on file, so a machine without one only pays this file check. A
+// Hook leaves as soon as it has sent, so the connection is closed behind its last message
+await runHookCommand(
+  defineCommand({
+    args: {
+      moment: {
+        default: "",
+        description: "The moment the hook reaches the model at",
+        required: false,
+        type: "positional",
+      },
+    },
+    meta: { description: "Send the viewer the reaction to the hook's moment", name: "react" },
+    run: async ({ args }) => {
+      const moment = checkIsViewerMoment(args.moment) ? args.moment : undefined;
+      const configuration = readViewerConfiguration();
+      if (!moment || !configuration) return;
+      const link = await connectViewer(configuration.address);
+      if (!link) return;
+      const reaction = getViewerReaction(moment, configuration.motions);
+      if (reaction.motion) link.motion(configuration.modelId, reaction.motion);
+      if (reaction.isExpressionCleared) link.expressionClear(configuration.modelId);
+      link.close();
+    },
+  }),
+);

package/scripts/spinner.ts

@@ -3,15 +3,14 @@ import { readInterfaceLanguage } from "#src/services/readInterfaceLanguage";
 import { readPersonaCard } from "#src/services/readPersonaCard";
 import { readRoster } from "#src/services/readRoster";
 import { readSpinner } from "#src/services/readSpinner";
-import { registerQuietExit } from "#src/services/registerQuietExit";
-import { defineCommand, runMain } from "citty";
+import { runHookCommand } from "#src/services/runHookCommand";
+import { defineCommand } from "citty";
 
 // The session's spinner for the hooks module, as JSON: its verbs and the character's lines under their name. Run off
 // The session start's own path, since the lines cost the data package or the wiki. The character arrives as the
 // English name, which is the identity, and the roster it is looked up in is the interface language's — so the label
 // Is the name that language spells them by
-registerQuietExit();
-await runMain(
+await runHookCommand(
   defineCommand({
     args: {
       name: {

package/scripts/voice.ts

@@ -2,35 +2,52 @@ import type { AudioPlayer } from "#src/models/AudioPlayer";
 import type { PcmClip } from "#src/models/PcmClip";
 import type { SpeakerTensors } from "#src/models/SpeakerTensors";
 import type { SpeechRequest } from "#src/models/SpeechRequest";
+import type { ViewerCaption } from "#src/models/ViewerCaption";
 
 import { VoiceRequestType } from "#src/models/VoiceRequestType";
 import { VoiceStatus } from "#src/models/VoiceStatus";
+import { connectViewer } from "#src/services/connectViewer";
 import {
   MAX_VOLUME,
   MESSAGE_DISPLAY_HOOK_TIMEOUT_MS,
   MODELS_DIRECTORY,
   RUNTIME_MANIFEST_PATH,
+  VIEWER_SOUND_FORM,
   VOICE_IDLE_TIMEOUT_MS,
   VOICE_STATUS_SEPARATOR,
 } from "#src/services/constants";
 import { createAudioPlayer } from "#src/services/createAudioPlayer";
 import { createClipDecoder } from "#src/services/createClipDecoder";
+import { createReadingPlayer } from "#src/services/createReadingPlayer";
 import { createReplyQueue } from "#src/services/createReplyQueue";
+import { createViewerOpener } from "#src/services/createViewerOpener";
+import { createViewerPlayer } from "#src/services/createViewerPlayer";
 import { createVoiceSynthesizer } from "#src/services/createVoiceSynthesizer";
+import { getViewerFrameColor } from "#src/services/getViewerFrameColor";
 import { getWavBytes } from "#src/services/getWavBytes";
 import { listenVoiceSocket } from "#src/services/listenVoiceSocket";
 import { parseVoiceRequest } from "#src/services/parseVoiceRequest";
 import { readReferenceClip } from "#src/services/readReferenceClip";
+import { readViewerConfiguration } from "#src/services/readViewerConfiguration";
 import { readVoiceDevice } from "#src/services/readVoiceDevice";
 import { readVoiceRuntime } from "#src/services/readVoiceRuntime";
 import { writeVoiceDevice } from "#src/services/writeVoiceDevice";
 import { writeVoiceLog } from "#src/services/writeVoiceLog";
 import { createServer } from "node:net";
 
+// The viewer a reading is shown on, when a `viewer` address is on file: connected at a reading's start and held until
+// The synthesizer exits, since a tap on the model plays the last line again over the same connection
+const viewerOpener = createViewerOpener({
+  connect: connectViewer,
+  createPlayer: createViewerPlayer,
+  readConfiguration: readViewerConfiguration,
+});
 // The address is bound before the engine loads, so a second hook finds it taken rather than loading a second engine;
-// Every failure is logged, since the hooks stay silent on its behalf
+// Every failure is logged, since the hooks stay silent on its behalf. The viewer is disposed too, so its last clip
+// Does not outlive the process
 const exit = (message: string) => {
   writeVoiceLog(message);
+  viewerOpener.dispose();
   process.exit(1);
 };
 process.on("uncaughtException", (error) => {
@@ -45,6 +62,7 @@ if (!(await listenVoiceSocket(server))) process.exit(0);
 // Nothing between the bind and the connection handler below yields to the event loop: a hook connecting in such a gap
 // Is accepted by nobody and waits for an answer that never comes, so every load is started here and awaited later
 const idleTimer = setTimeout(() => {
+  viewerOpener.dispose();
   process.exit(0);
 }, VOICE_IDLE_TIMEOUT_MS);
 const runtime = readVoiceRuntime(RUNTIME_MANIFEST_PATH);
@@ -84,39 +102,40 @@ const speak = async (request: SpeechRequest, player: AudioPlayer | undefined, ch
   }
 
   const gain = request.volume / MAX_VOLUME;
-  const play = async ({ play: playAudio }: AudioPlayer, clip: PcmClip) => {
+  const color = getViewerFrameColor(request.name);
+  // The caption is the line and the clip's own length, which is what a viewer shows and paces the next clip by
+  const play = async ({ play: playAudio }: AudioPlayer, clip: PcmClip, line: string) => {
     const audio = getWavBytes({ ...clip, samples: clip.samples.map((sample) => sample * gain) });
-    const playerFailure = await playAudio(audio);
+    const caption: ViewerCaption = {
+      color,
+      durationMs: Math.round((clip.samples.length / clip.sampleRate) * 1000),
+      text: line,
+    };
+    const playerFailure = await playAudio(audio, caption);
     if (playerFailure) writeVoiceLog(`the player did not play: ${playerFailure}`);
   };
   let playback: Promise<void> = Promise.resolve();
-  for (const [lineIndex, line] of request.lines.entries()) {
-    let isSpoken = false;
-    // Each chunk plays as it is vocoded, and a line that stops short is cut where it stood; leaving this loop early
-    // Ends the generation behind it
-    const label = `reply ${request.messageId}, line ${lineIndex + 1}`;
+  for (const line of request.lines) {
     // oxlint-disable-next-line no-await-in-loop -- One device: lines synthesize and play back one after another
-    for await (const clip of synthesizer.streamSpeech(line, speaker, label, checkIsSuperseded)) {
-      isSpoken = true;
-      if (synthesizer.device !== settledDevice) {
-        settledDevice = synthesizer.device;
-        writeVoiceDevice(settledDevice);
-      }
-
-      if (!player) continue;
-
-      // oxlint-disable-next-line no-await-in-loop -- One device: chunks play back one after another
+    const clip = await synthesizer.synthesize(line, speaker);
+    if (!clip) {
+      // oxlint-disable-next-line no-await-in-loop -- The reading ends at a line the engine could not speak
       await playback;
-      if (checkIsSuperseded()) return VoiceStatus.Superseded;
-
-      playback = play(player, clip);
+      return VoiceStatus.Error;
     }
 
-    if (!isSpoken) {
-      // oxlint-disable-next-line no-await-in-loop -- One device: lines synthesize and play back one after another
-      await playback;
-      return VoiceStatus.Error;
+    if (synthesizer.device !== settledDevice) {
+      settledDevice = synthesizer.device;
+      writeVoiceDevice(settledDevice);
     }
+
+    if (!player) continue;
+
+    // oxlint-disable-next-line no-await-in-loop -- One device: a line plays once the one before it has
+    await playback;
+    if (checkIsSuperseded()) return VoiceStatus.Superseded;
+
+    playback = play(player, clip, line);
   }
 
   await playback;
@@ -126,8 +145,13 @@ const speak = async (request: SpeechRequest, player: AudioPlayer | undefined, ch
 // In front of the first sound. A request that throws is dropped and keeps the engine
 const queue = createReplyQueue(async (request: SpeechRequest, checkIsSuperseded: () => boolean) => {
   const isSpoken = request.type === VoiceRequestType.Speak && request.lines.length > 0;
-  const player = isSpoken ? createAudioPlayer() : undefined;
+  // A viewer on file carries the reading, with the stock player behind it; with none, the reading is the stock player's
+  const viewer = isSpoken ? await viewerOpener.open() : undefined;
+  let player: AudioPlayer | undefined;
+  if (isSpoken)
+    player = viewer ? createReadingPlayer(viewer, createAudioPlayer, VIEWER_SOUND_FORM) : createAudioPlayer();
   const [outcome] = await Promise.allSettled([speak(request, player, checkIsSuperseded)]);
+  if (outcome?.status === "fulfilled" && outcome.value === VoiceStatus.Superseded) player?.stop?.();
   await player?.close();
   if (outcome?.status === "fulfilled") return outcome.value;
 
@@ -141,6 +165,7 @@ const handleLine = (line: string): Promise<VoiceStatus> => {
   idleTimer.refresh();
   if (request.type === VoiceRequestType.Stop) {
     setImmediate(() => {
+      viewerOpener.dispose();
       process.exit(0);
     });
     return Promise.resolve(VoiceStatus.Ok);

package/skills/genshin-author/SKILL.md

@@ -69,7 +69,7 @@ The value is the line's file stem on the community wiki — the title after `VO_
 pnpm ai:voice-match --check
 ```
 
-The full reasoning — how a reference is chosen and what its likeness number is worth — is the [reference selection](https://esposter.com/docs/infra/claude-interface/reference-selection) page's. **The generated values are measured, not heard**; correcting one by ear is a welcome edit, and the card is where that correction goes — never the generated map, which the next run overwrites. A session tempted to re-derive a reference by taste runs the measurement instead.
+The full reasoning — how a reference is chosen and what its likeness number is worth — is the [reference selection](https://github.com/Esposter/Esposter/blob/main/openspec/specs/infra/claude-interface/reference-selection/design.md) page's. **The generated values are measured, not heard**; correcting one by ear is a welcome edit, and the card is where that correction goes — never the generated map, which the next run overwrites. A session tempted to re-derive a reference by taste runs the measurement instead.
 
 ## The spinner verbs