Release 0.1.37 [auto-version-bump]

.gitea/workflows/publish.yaml

@@ -25,6 +25,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
+          node --version
           python3 scripts/bump-version.py --check
           scripts/check-frontend.sh
 

Dockerfile

@@ -3,6 +3,7 @@ FROM nginxinc/nginx-unprivileged:1.27-alpine
 ARG FRONTEND_VERSION
 RUN test -n "$FRONTEND_VERSION"
 COPY index.html /usr/share/nginx/html/index.html
+COPY voice.js /usr/share/nginx/html/voice.js
 COPY nginx/default.conf /etc/nginx/conf.d/default.conf
 USER root
 RUN sed -i "s/__FRONTEND_VERSION__/${FRONTEND_VERSION}/g" /usr/share/nginx/html/index.html

README.md

@@ -2,9 +2,25 @@
 
 This repository contains the static Swedish web client for the AI-driven life simulator. The intended deployment is a small Nginx pod in the `ai-spel` namespace. The existing Rust service remains authoritative for accounts, game state, and all `/api/...` routes.
 
-Players provide a character biography, not a world description. The client asks the backend to create a biography-based starting place. It does not preview a person the player may meet; encounters belong to later world exploration.
+After login, character creation and play use one dialogue history and one text input. The player writes a free biography, receives a temporary AI draft, can request revisions, and approves it by writing `godkänn`. The player then receives a proposed start world and place based on the biography. That draft can also be revised in dialogue and is saved only after a second explicit `godkänn`. Drafts stay in the browser until approval and are lost if the page is reloaded first. The backend creates the character and initializes the world only after their respective approvals.
 
-Place descriptions are available as text with separate visual, sound, smell, air/temperature, touch/surface, and spatial-orientation cues so important scene information does not depend on sight. The current product has no image input or image interpretation flow; these cues are generated as part of the place proposal.
+During play the UI has no persistent location, task, inventory, economy, status, or purchase panels. The player asks for information or writes an action in the same input. Rust validates state changes; the AI can only propose a typed intent. A direct request to travel may establish a new place and an encounter when Rust commits that movement.
+
+If the player asks to find or approach someone and no NPC is present, the direct dialogue scene may propose one person and an opening line. Rust creates that NPC only for the explicit request and commits the first exchange idempotently; a later turn continues the saved conversation. Clear requests about the current location are answered from its saved facts without asking the player to restate what they want to inspect.
+
+The separate `/admin` route provides an authenticated operations view for player search/profile/trace, YAML prompt assets, generated Luau rules with validation results, runtime debug logging, and the append-only audit log. All privileged data comes from the Rust `/api/admin/...` API; the browser never connects directly to PostgreSQL. Backend endpoints require `accounts.is_admin=true`. The Driftloggar view lets an administrator switch `debug=true` on or off without restarting pods; the setting is stored in PostgreSQL and propagated to running replicas. Verbose pod logs include request, AI-call, validation, and commit metadata but never raw player text, prompts, model responses, sessions, or secrets. Full protected prompt/provider exchanges remain in the audited player trace.
+
+The game is text- and dialogue-based and uses no images. Place descriptions include sound, smell, air/temperature, touch/surface, and spatial-orientation cues. Visible details may also be described in words, but are never required to understand the scene or play. The transcript is screen-reader announced, and Enter submits the input while Shift+Enter inserts a newline; no separate send button is required.
+
+Voice output uses the browser's Swedish speech synthesis for all player-facing game dialogue, onboarding, account responses, character and world creation, gameplay replies, in-game errors, and microphone disclosures. The `/admin` route is excluded. The first unauthenticated visit automatically reads an introduction that explains the game, how to create an account, and how to play; the introduction stays visible as text and can be replayed with `Läs introduktionen igen`. New game replies are read automatically and the transcript remains available to screen readers and as text. Returning players hear the latest saved game reply when they reopen the game. Voice settings can change the Swedish voice and speaking rate, but cannot disable automatic speech. These preferences are stored in browser `localStorage`. If the browser lacks speech synthesis or blocks playback, the same content remains available as text and the introduction can be started again with its replay button.
+
+The microphone button beside the text field uses Web Speech API when available and sends only its final Swedish transcript through the same submission path as typed text. Before its first use, the client explains that the browser may process audio through a provider-selected service; the game itself does not receive or store recordings, while the final transcript is saved as ordinary dialogue. Writing `röstinställningar` or saying `röstkommando alternativ` opens temporary voice controls in the dialogue. The player can select an available Swedish voice and speaking rate and enable or disable short audio cues. Voice preferences are stored in browser `localStorage`.
+
+When a character or NPC is created, its saved voice identity is masculine, feminine, or neutral. The biography prompt only assigns masculine/feminine when the character is explicitly described that way; otherwise it uses neutral. Speech synthesis applies a stable, subtly varied pitch/rate profile per character, so a character keeps the same sound across visits. Narration always uses neutral pitch. The browser's selected Swedish voice still determines the underlying voice, so the exact sound depends on installed system voices.
+
+System voice commands require the prefix `röstkommando`: `upprepa`, `avbryt`, `hjälp`, `alternativ`, or `paus`. Without the prefix, the same words remain ordinary dialogue. Speech recognition and synthesis are browser-dependent; release acceptance must record which real iPhone/Safari/VoiceOver and Android/Chrome/TalkBack combinations were actually checked.
+
+On iPhone and iPad, Safari may require a direct tap or key press before it permits speech output. The frontend primes speech silently on the first player gesture and then reads game replies automatically. If the first-visit introduction did not play, use **Läs introduktionen igen**; if a game reply does not start, a **Läs senaste repliken** button appears in the dialogue, with the same action also available in voice settings. The introduction is only marked as heard after the browser reports that speech actually started. The speech queue avoids an immediate `cancel()` followed by `speak()`, which older WebKit releases can drop.
 
 The browser and API stay on the same public origin, `https://ai-spel.k3s.k0.nu`. The ingress routes `/` to this frontend service and routes `/api`, `/version`, and `/health` to the Rust service. That keeps the current server-side session cookie same-origin and avoids browser CORS configuration.
 
@@ -14,6 +30,6 @@ The browser and API stay on the same public origin, `https://ai-spel.k3s.k0.nu`.
 
 CI needs repository Action secrets named `HARBOR_USERNAME` and `HARBOR_PASSWORD`. The Harbor pull secret `harbor-pull` is already present in the Kubernetes namespace. Argo CD uses the existing `ai-spel` project and Harbor OCI credentials.
 
-The first Argo Application is described in `deploy/argocd/application.yaml`. The backend ingress must be switched to the frontend Service before public traffic uses this pod. That cutover is intentionally coordinated with a backend release so the API routes and login session remain on the same host.
+The first Argo Application is described in `deploy/argocd/application.yaml`. The backend ingress routes `/api`, `/version`, and health checks to Rust while serving the static client at `/`. Both services share the same origin so the session cookie remains same-origin.
 
 Builds, checks, and runtime verification happen in the pipeline and Kubernetes. Do not run the app, tests, container images, or binaries locally.

VERSION

@@ -1 +1 @@
-0.1.21
+0.1.37

deploy/helm/ai-spel-frontend/Chart.yaml

@@ -2,5 +2,5 @@ apiVersion: v2
 name: ai-spel-frontend
 description: Static web frontend for the Swedish life simulator
 type: application
-version: 0.1.21
+version: 0.1.37
-appVersion: "0.1.21"
+appVersion: "0.1.37"

scripts/check-frontend.sh

@@ -3,23 +3,65 @@ set -euo pipefail
 
 test -s index.html
 grep -q '<html lang="sv">' index.html
-grep -q '<h1>En värld du formar</h1>' index.html
 grep -q 'id="frontend-version">__FRONTEND_VERSION__' index.html
 grep -q "request('/version')" index.html
-grep -q 'id="api-version"' index.html
 grep -Fq "credentials: 'same-origin'" index.html
-grep -q 'Köp på platsen' index.html
+grep -q 'id="dialogue" aria-label="Dialoghistorik" role="log" aria-live="polite"' index.html
-grep -q 'Platsens sinnesintryck' index.html
+grep -q 'id="message" name="message"' index.html
-grep -q 'Orientering i rummet' index.html
+grep -q 'id="auth-intro"' index.html
-grep -q "'sense-sound', 'sound'" index.html
+grep -q 'Skapa konto med ett användarnamn och ett lösenord på minst tolv tecken' index.html
-grep -q 'id="world-heading" tabindex="-1"' index.html
+grep -q 'id="auth-repeat-intro"' index.html
-grep -q "document.querySelector('#world-heading').focus()" index.html
+grep -q 'function playFirstVisitIntroduction' index.html
-grep -q "request('/api/purchases'" index.html
+grep -q 'id="auth-voice-status" role="status" aria-live="polite"' index.html
+grep -q 'activateFromUserGesture' index.html
+grep -q 'function showSpeechRecovery' index.html
+grep -q "retry.textContent = 'Läs senaste repliken'" index.html
+grep -q "location.pathname !== '/admin'" index.html
+grep -q "if (options.speak !== false && location.pathname !== '/admin')" index.html
+grep -q 'id="microphone" aria-pressed="false"' index.html
+grep -q 'id="voice-status" role="status" aria-live="polite"' index.html
+grep -q "window.GameVoice.createVoiceController" index.html
+grep -q 'Jag förstår – starta mikrofonen' index.html
+grep -q 'supportsRecognition' voice.js
+grep -q 'characterVoiceProfile' voice.js
+grep -q 'WebKit versions before Safari 27' voice.js
+grep -q "voiceIdentity: speakingNpc.voice_identity" index.html
+grep -q "role: 'narrator', voiceIdentity: 'neutral'" index.html
+grep -q 'COPY voice.js /usr/share/nginx/html/voice.js' Dockerfile
+grep -q "SpeechRecognition || win.webkitSpeechRecognition" voice.js
+grep -q "submitMessage(text, 'voice')" index.html
+grep -q 'Spelets repliker läses alltid upp' index.html
+grep -q "event.key === 'Enter' && !event.shiftKey" index.html
+grep -q "request('/api/character/draft'" index.html
+grep -q "request('/api/world/draft'" index.html
+grep -q "request('/api/dialogue'" index.html
+grep -q "request('/api/presence/heartbeat'" index.html
+grep -q "request('/api/players/nearby'" index.html
+grep -q "request('/api/player/messages'" index.html
+grep -q "Säg till Robin" index.html
+grep -q "result.intent === 'move' || result.intent === 'meet'" index.html
+grep -q 'dialogue_temporarily_unavailable:' index.html
+grep -q 'id="admin-view"' index.html
+grep -q '/api/admin/players?' index.html
+grep -q "request('/api/admin/prompts'" index.html
+grep -q "request('/api/admin/rules'" index.html
+grep -q "request('/api/admin/settings/logging'" index.html
+grep -q 'data-admin-view="logging"' index.html
+grep -q '/api/admin/audit?limit=200' index.html
+grep -q 'entry.data.external_call' index.html
+grep -q 'Externt tjänsteanrop' index.html
 grep -q "request('/api/world/start'" index.html
-if grep -Eq 'world/draft|npc_name|Person du kan möta|Beskriv vad du vill börja med' index.html; then
+grep -q "request('/api/character'" index.html
-  echo 'The start flow must not ask for a world description or preview a person.' >&2
+grep -q 'location = /healthz' nginx/default.conf
+if grep -Eq 'id="(new-character|world-setup|shop|buy-offer|balance|inventory|place-heading|npc-heading)"|Platsens sinnesintryck|Ekonomi och ägodelar|Köp på platsen|id="status"|id="logout"' index.html; then
+  echo 'The active player UI must not contain permanent data panels, forms, or action buttons.' >&2
   exit 1
 fi
-grep -q 'location = /healthz' nginx/default.conf
+if sed -n '/<section id="play"/,/^    <\/section>/p' index.html | grep '<button' | grep -v 'id="microphone"' >/dev/null; then
+  echo 'Only the microphone control may appear beside the game text input.' >&2
+  exit 1
+fi
+
+node --test tests/voice.test.cjs
 
 echo 'Frontend source checks passed.'

tests/voice.test.cjs

@@ -0,0 +1,246 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const test = require('node:test');
+const vm = require('node:vm');
+
+const source = fs.readFileSync(path.join(__dirname, '..', 'voice.js'), 'utf8');
+const apiWindow = {};
+vm.runInNewContext(source, {window: apiWindow, globalThis: apiWindow, Promise, String, Math, Object});
+const GameVoice = apiWindow.GameVoice;
+
+function makeHarness({supported = true, tts = true, onTranscript = () => Promise.resolve()} = {}) {
+  const recognitions = [];
+  const utterances = [];
+  const states = [];
+  const timers = new Map();
+  const timerDelays = new Map();
+  let timerId = 0;
+  class Recognition {
+    constructor() { recognitions.push(this); }
+    start() { this.started = true; }
+    stop() { this.stopped = true; }
+    abort() { this.aborted = true; }
+  }
+  class Utterance {
+    constructor(text) { this.text = text; utterances.push(this); }
+  }
+  const synthesis = tts ? {
+    spoken: [], cancelled: 0,
+    getVoices: () => [{name: 'Svensk', lang: 'sv-SE'}],
+    speak(utterance) { this.spoken.push(utterance); },
+    cancel() { this.cancelled += 1; },
+  } : undefined;
+  const window = {
+    setTimeout(callback, delay = 0) { const id = ++timerId; timers.set(id, callback); timerDelays.set(id, delay); return id; },
+    clearTimeout(id) { timers.delete(id); timerDelays.delete(id); },
+    speechSynthesis: synthesis,
+    SpeechSynthesisUtterance: tts ? Utterance : undefined,
+    SpeechRecognition: supported ? Recognition : undefined,
+  };
+  vm.runInNewContext(source, {window, globalThis: window, Promise, String, Math, Object});
+  const controller = window.GameVoice.createVoiceController({
+    window,
+    onState: (state, message) => states.push({state, message}),
+    onTranscript,
+  });
+  return {
+    controller, recognitions, utterances, synthesis, states, timers,
+    runTimer(delay) {
+      const match = [...timerDelays.entries()].find(([, value]) => value === delay);
+      if (!match) throw new Error(`No timer found with delay ${delay}`);
+      timers.get(match[0])();
+    },
+  };
+}
+
+test('recognition is single-shot Swedish and sends only final transcript once', async () => {
+  const received = [];
+  const h = makeHarness({onTranscript: text => { received.push(text); }});
+  assert.equal(h.controller.startListening(), true);
+  const recognition = h.recognitions[0];
+  assert.equal(recognition.lang, 'sv-SE');
+  assert.equal(recognition.continuous, false);
+  assert.equal(recognition.interimResults, false);
+  recognition.onresult({resultIndex: 0, results: [{isFinal: false, 0: {transcript: 'delvis'}}]});
+  recognition.onresult({resultIndex: 0, results: [{isFinal: true, 0: {transcript: '  Hej världen  '}}]});
+  recognition.onresult({resultIndex: 0, results: [{isFinal: true, 0: {transcript: 'dubblett'}}]});
+  await Promise.resolve(); await Promise.resolve();
+  assert.deepEqual(received, ['Hej världen']);
+  assert.equal(h.controller.getState(), 'IDLE');
+});
+
+test('second microphone activation stops the active recognition session', () => {
+  const h = makeHarness();
+  h.controller.startListening();
+  h.controller.startListening();
+  assert.equal(h.recognitions.length, 1);
+  assert.equal(h.recognitions[0].aborted, true);
+  assert.equal(h.controller.getState(), 'IDLE');
+});
+
+test('unsupported recognition stays recoverable and leaves text input available', () => {
+  const h = makeHarness({supported: false});
+  assert.equal(h.controller.startListening(), false);
+  assert.equal(h.controller.getState(), 'IDLE');
+  assert.match(h.states.at(-1).message, /skriva/);
+});
+
+test('permission errors reset state and a later session can start', () => {
+  const h = makeHarness();
+  h.controller.startListening();
+  h.recognitions[0].onerror({error: 'not-allowed'});
+  assert.equal(h.controller.getState(), 'IDLE');
+  assert.match(h.states.at(-1).message, /behörighet nekades/);
+  assert.equal(h.controller.startListening(), true);
+  assert.equal(h.recognitions.length, 2);
+});
+
+test('late recognition results after cancellation are ignored', () => {
+  let delivered = 0;
+  const h = makeHarness({onTranscript: () => { delivered += 1; }});
+  h.controller.startListening();
+  const old = h.recognitions[0];
+  h.controller.stopListening();
+  old.onresult({resultIndex: 0, results: [{isFinal: true, 0: {transcript: 'för sent'}}]});
+  assert.equal(delivered, 0);
+});
+
+test('recognition watchdog closes a session that never ends and permits retry', () => {
+  const h = makeHarness();
+  h.controller.startListening();
+  const watchdog = [...h.timers.values()][0];
+  watchdog();
+  assert.equal(h.controller.getState(), 'IDLE');
+  assert.match(h.states.at(-1).message, /en minut/);
+  assert.equal(h.controller.startListening(), true);
+  assert.equal(h.recognitions.length, 2);
+});
+
+test('TTS selects Swedish fallback, applies rate, and cancellation invalidates callbacks', () => {
+  const h = makeHarness();
+  h.controller.update({mode: 'game-voice', rate: 1.4});
+  assert.equal(h.controller.speak('Hej.'), true);
+  const first = h.utterances[0];
+  assert.equal(first.lang, 'sv-SE');
+  assert.equal(first.rate, 1.4);
+  assert.equal(first.voice.name, 'Svensk');
+  h.controller.cancelSpeech();
+  first.onend();
+  assert.equal(h.controller.getState(), 'IDLE');
+});
+
+test('iOS user gesture primes speech silently and idle speech is not cancelled before speak', () => {
+  const h = makeHarness();
+  assert.equal(h.controller.activateFromUserGesture(), true);
+  assert.equal(h.synthesis.spoken[0].text, ' ');
+  assert.equal(h.synthesis.spoken[0].volume, 0);
+  const cancelledBeforeReply = h.synthesis.cancelled;
+  assert.equal(h.controller.speak('Ett svar efter nätverksanropet'), true);
+  assert.equal(h.synthesis.spoken.at(-1).text, 'Ett svar efter nätverksanropet');
+  assert.equal(h.synthesis.cancelled, cancelledBeforeReply);
+});
+
+test('replacing active speech waits one event-loop turn after WebKit cancel', () => {
+  const h = makeHarness();
+  h.controller.speak('Första repliken');
+  const cancelledBeforeReplace = h.synthesis.cancelled;
+  h.controller.speak('Nästa replik');
+  assert.equal(h.synthesis.cancelled, cancelledBeforeReplace + 1);
+  assert.notEqual(h.synthesis.spoken.at(-1).text, 'Nästa replik');
+  h.runTimer(100);
+  assert.equal(h.synthesis.spoken.at(-1).text, 'Nästa replik');
+});
+
+test('speech start timeout tells the player how to recover when mobile playback is blocked', () => {
+  const h = makeHarness();
+  h.controller.speak('En replik');
+  const cancelledBeforeTimeout = h.synthesis.cancelled;
+  h.runTimer(4000);
+  assert.match(h.states.at(-1).message, /Tryck på Läs senaste repliken/);
+  assert.equal(h.synthesis.cancelled, cancelledBeforeTimeout + 1);
+  const cancelledBeforeRetry = h.synthesis.cancelled;
+  h.controller.speak('Manuell återläsning');
+  assert.equal(h.synthesis.spoken.at(-1).text, 'Manuell återläsning');
+  assert.equal(h.synthesis.cancelled, cancelledBeforeRetry);
+});
+
+test('character voice identity gives stable distinct masculine, feminine, and neutral timbres', () => {
+  const profile = GameVoice.characterVoiceProfile;
+  const masculine = profile('masculine', 'character-1');
+  const feminine = profile('feminine', 'character-1');
+  const neutral = profile('neutral', 'character-1');
+  assert.equal(profile('masculine', 'character-1').pitch, masculine.pitch);
+  assert.ok(masculine.pitch < neutral.pitch);
+  assert.ok(neutral.pitch < feminine.pitch);
+  assert.notEqual(profile('masculine', 'character-2').pitch, masculine.pitch);
+});
+
+test('narrator uses neutral pitch while character replies use their saved voice identity', () => {
+  const h = makeHarness();
+  h.controller.update({mode: 'game-voice'});
+  h.controller.speak('Berättarröst', {role: 'narrator', voiceIdentity: 'feminine', characterId: 'narrator'});
+  h.controller.speak('NPC-replik', {voiceIdentity: 'masculine', characterId: 'npc-1'});
+  h.runTimer(100);
+  assert.equal(h.utterances[0].pitch, 1);
+  assert.ok(h.utterances[1].pitch < 1);
+});
+
+test('TTS and microphone are mutually exclusive', () => {
+  const h = makeHarness();
+  h.controller.update({mode: 'game-voice'});
+  h.controller.startListening();
+  h.controller.speak('Svar');
+  assert.equal(h.recognitions[0].aborted, true);
+  assert.equal(h.controller.getState(), 'SPEAKING');
+});
+
+test('game speech stays automatic even with legacy text-only settings and gracefully degrades without synthesis', () => {
+  const screenReader = makeHarness();
+  screenReader.controller.update({mode: 'text-only', autoSpeak: false});
+  assert.equal(screenReader.controller.speak('dialog'), true);
+  assert.equal(screenReader.synthesis.spoken[0].text, 'dialog');
+  const noTts = makeHarness({tts: false});
+  noTts.controller.update({mode: 'game-voice'});
+  assert.equal(noTts.controller.speak('dialog'), false);
+});
+
+test('system commands require an explicit prefix; ordinary dialogue words are untouched', () => {
+  const global = {};
+  vm.runInNewContext(source, {window: global, globalThis: global, Promise, String, Math, Object});
+  assert.equal(GameVoice.parseVoiceCommand('upprepa'), null);
+  assert.equal(GameVoice.parseVoiceCommand('hjälp'), null);
+  assert.equal(GameVoice.parseVoiceCommand('röstkommando upprepa.' ).command, 'repeat');
+  assert.equal(GameVoice.parseVoiceCommand('röstkommando alternativ').command, 'settings');
+  assert.equal(GameVoice.parseVoiceCommand('röstinställningar').command, 'settings');
+  assert.equal(GameVoice.parseVoiceCommand('röstinställningar', {requirePrefix: true}), null);
+  assert.equal(GameVoice.parseVoiceCommand('röstkommando alternativ', {requirePrefix: true}).command, 'settings');
+});
+
+test('settings survive reload and invalid storage falls back to accessible defaults', () => {
+  const global = {};
+  vm.runInNewContext(source, {window: global, globalThis: global, Promise, String, Math, Object});
+  const values = new Map();
+  const storage = {getItem: key => values.get(key) || null, setItem: (key, value) => values.set(key, value)};
+  const defaults = GameVoice.loadSettings(storage, 'new-player');
+  assert.equal(defaults.mode, 'game-voice');
+  assert.equal(defaults.autoSpeak, true);
+  values.set('voice-v1', JSON.stringify({mode: 'text-only', autoSpeak: false, rate: 1.4, voiceName: 'Svensk', soundSignals: false}));
+  const migrated = GameVoice.loadSettings(storage, 'voice-v2', 'voice-v1');
+  assert.equal(migrated.mode, 'game-voice');
+  assert.equal(migrated.autoSpeak, true);
+  assert.equal(migrated.rate, 1.4);
+  assert.equal(migrated.voiceName, 'Svensk');
+  assert.equal(migrated.soundSignals, false);
+  const requested = {...GameVoice.DEFAULT_SETTINGS, mode: 'game-voice', autoSpeak: true, rate: 1.5, voiceName: 'Svensk'};
+  assert.equal(GameVoice.saveSettings(storage, 'voice', requested), true);
+  const loaded = GameVoice.loadSettings(storage, 'voice');
+  assert.equal(loaded.mode, 'game-voice');
+  assert.equal(loaded.autoSpeak, true);
+  assert.equal(loaded.rate, 1.5);
+  assert.equal(loaded.voiceName, 'Svensk');
+  values.set('voice', '{trasig');
+  assert.equal(GameVoice.loadSettings(storage, 'voice').mode, 'game-voice');
+  assert.equal(GameVoice.loadSettings(storage, 'voice').autoSpeak, true);
+  assert.equal(GameVoice.saveSettings({setItem() { throw new Error('blocked'); }}, 'voice', requested), false);
+});

voice.js

@@ -0,0 +1,307 @@
+/* Browser voice adapters. Kept independent of the game submission and API layer. */
+(function exposeVoice(root) {
+  const DEFAULT_SETTINGS = Object.freeze({
+    mode: 'game-voice',
+    autoSpeak: true,
+    language: 'sv-SE',
+    rate: 1,
+    voiceName: '',
+    speakerProfiles: {},
+    autoStop: true,
+    soundSignals: true,
+  });
+
+  function parseVoiceCommand(text, options = {}) {
+    const value = String(text || '').trim();
+    if (/^röstinställningar[.!]?$/i.test(value)) return options.requirePrefix ? null : {command: 'settings'};
+    const match = value.match(/^röstkommando\s+(.+?)[.!]?$/i);
+    if (!match) return null;
+    const command = match[1].trim().replace(/[.!?]+$/, '').toLocaleLowerCase('sv-SE');
+    const aliases = {
+      upprepa: 'repeat', 'läs igen': 'repeat',
+      avbryt: 'stop', stopp: 'stop', paus: 'stop',
+      hjälp: 'help', alternativ: 'settings', inställningar: 'settings', röstinställningar: 'settings',
+    };
+    return {command: aliases[command] || 'unknown'};
+  }
+
+  function loadSettings(storage, key, legacyKey) {
+    try {
+      const current = storage.getItem(key);
+      if (!current && legacyKey) {
+        const legacy = JSON.parse(storage.getItem(legacyKey) || '{}');
+        const migrated = {
+          ...DEFAULT_SETTINGS,
+          rate: legacy.rate,
+          voiceName: legacy.voiceName,
+          speakerProfiles: legacy.speakerProfiles,
+          soundSignals: legacy.soundSignals,
+        };
+        saveSettings(storage, key, migrated);
+        return migrated;
+      }
+      const stored = JSON.parse(current || '{}');
+      const settings = {...DEFAULT_SETTINGS, ...stored};
+      // Game dialogue is always spoken. These assignments also migrate older
+      // local settings that allowed text-only or screen-reader-only playback.
+      settings.mode = 'game-voice';
+      settings.autoSpeak = true;
+      settings.rate = Math.min(2, Math.max(0.5, Number(settings.rate) || 1));
+      settings.voiceName = typeof settings.voiceName === 'string' ? settings.voiceName : '';
+      settings.speakerProfiles = settings.speakerProfiles && typeof settings.speakerProfiles === 'object' ? settings.speakerProfiles : {};
+      settings.soundSignals = settings.soundSignals !== false;
+      return settings;
+    } catch (_) { return {...DEFAULT_SETTINGS}; }
+  }
+
+  function saveSettings(storage, key, settings) {
+    try { storage.setItem(key, JSON.stringify(settings)); return true; }
+    catch (_) { return false; }
+  }
+
+  function characterVoiceProfile(voiceIdentity, characterId = '') {
+    const identity = ['masculine', 'feminine', 'neutral'].includes(voiceIdentity) ? voiceIdentity : 'neutral';
+    let hash = 2166136261;
+    for (const char of String(characterId)) hash = Math.imul(hash ^ char.charCodeAt(0), 16777619) >>> 0;
+    const variation = (hash % 1000) / 1000;
+    if (identity === 'masculine') return {pitch: 0.88 + variation * 0.08, rate: 0.96 + variation * 0.04};
+    if (identity === 'feminine') return {pitch: 1.06 + variation * 0.08, rate: 0.98 + variation * 0.04};
+    return {pitch: 0.98 + variation * 0.04, rate: 1};
+  }
+
+  function createVoiceController(options = {}) {
+    const win = options.window || root;
+    const onState = options.onState || (() => {});
+    const onTranscript = options.onTranscript || (() => {});
+    const settings = {...DEFAULT_SETTINGS, ...(options.settings || {})};
+    let state = 'IDLE';
+    let generation = 0;
+    let recognition = null;
+    let speechTimer = null;
+    let speechStartTimer = null;
+    let listeningTimer = null;
+    let currentUtterance = null;
+    let speechPrimed = false;
+
+    function setState(next, message = '') {
+      state = next;
+      onState(next, message);
+    }
+
+    function cancelSpeech() {
+      generation += 1;
+      if (speechTimer !== null) win.clearTimeout(speechTimer);
+      if (speechStartTimer !== null) win.clearTimeout(speechStartTimer);
+      speechTimer = null;
+      speechStartTimer = null;
+      const wasQueued = currentUtterance !== null;
+      currentUtterance = null;
+      // WebKit versions before Safari 27 can discard a speak() queued in the
+      // same turn as cancel(). Do not clear an already-empty native queue.
+      if (wasQueued) {
+        try { win.speechSynthesis?.cancel(); } catch (_) { /* Best effort. */ }
+      }
+      if (!recognition) setState('IDLE');
+    }
+
+    function activateFromUserGesture() {
+      if (!win.speechSynthesis || !win.SpeechSynthesisUtterance) return false;
+      if (speechPrimed) return true;
+      // iOS Safari requires speech output to be initiated by a user gesture.
+      // Prime its speech channel silently on the first trusted tap/key press so
+      // later game replies can be spoken after the API response arrives.
+      try {
+        const primer = new win.SpeechSynthesisUtterance(' ');
+        primer.volume = 0;
+        win.speechSynthesis.speak(primer);
+        speechPrimed = true;
+        return true;
+      } catch (_) { return false; }
+    }
+
+    function finishRecognition(token, message = '') {
+      if (token !== generation) return;
+      if (listeningTimer !== null) win.clearTimeout(listeningTimer);
+      listeningTimer = null;
+      recognition = null;
+      generation += 1;
+      if (message) setState('ERROR', message);
+      setState('IDLE', message);
+    }
+
+    function stopListening() {
+      if (!recognition) return;
+      const old = recognition;
+      recognition = null;
+      generation += 1;
+      if (listeningTimer !== null) win.clearTimeout(listeningTimer);
+      listeningTimer = null;
+      try { old.abort(); } catch (_) { try { old.stop(); } catch (_) { /* Already stopped. */ } }
+      setState('IDLE', 'Mikrofonen är avstängd.');
+    }
+
+    function startListening() {
+      if (recognition) { stopListening(); return true; }
+      const Recognition = win.SpeechRecognition || win.webkitSpeechRecognition;
+      if (!Recognition) {
+        setState('ERROR', 'Taligenkänning stöds inte här. Du kan fortfarande skriva.');
+        setState('IDLE', 'Taligenkänning stöds inte här. Du kan fortfarande skriva.');
+        return false;
+      }
+      cancelSpeech();
+      const token = ++generation;
+      let instance;
+      try { instance = new Recognition(); }
+      catch (_) { setState('IDLE', 'Mikrofonen kunde inte startas. Kontrollera behörigheten och försök igen.'); return false; }
+      recognition = instance;
+      instance.lang = settings.language || 'sv-SE';
+      instance.continuous = false;
+      instance.interimResults = false;
+      let delivered = false;
+      instance.onresult = event => {
+        if (token !== generation || delivered) return;
+        const result = event.results?.[event.resultIndex ?? 0];
+        if (!result?.isFinal) return;
+        const text = String(result[0]?.transcript || '').trim();
+        if (!text) { finishRecognition(token, 'Inget tal kunde identifieras. Försök igen eller skriv.'); return; }
+        delivered = true;
+        if (listeningTimer !== null) win.clearTimeout(listeningTimer);
+        listeningTimer = null;
+        setState('PROCESSING', 'Tal identifierat.');
+        Promise.resolve().then(() => onTranscript(text)).then(
+          () => finishRecognition(token),
+          () => finishRecognition(token, 'Meddelandet kunde inte skickas. Du kan försöka igen eller skriva.')
+        );
+      };
+      instance.onerror = event => {
+        if (token !== generation) return;
+        const messages = {
+          'not-allowed': 'Mikrofonbehörighet nekades. Tillåt mikrofonen i webbläsaren eller skriv i stället.',
+          'service-not-allowed': 'Taligenkänning är inte tillgänglig. Du kan skriva i stället.',
+          'audio-capture': 'Ingen mikrofon hittades. Anslut en mikrofon eller skriv i stället.',
+          'no-speech': 'Inget tal hördes. Tryck på mikrofonen och försök igen.',
+          network: 'Taligenkänningens nätverkstjänst svarar inte. Försök igen eller skriv.',
+          aborted: 'Taligenkänningen avbröts. Du kan starta den igen.',
+        };
+        finishRecognition(token, messages[event.error] || 'Taligenkänningen avslutades oväntat. Försök igen eller skriv.');
+      };
+      instance.onend = () => {
+        if (token !== generation || delivered || state === 'PROCESSING') return;
+        finishRecognition(token, 'Mikrofonen avslutades. Tryck för att försöka igen eller skriv.');
+      };
+      setState('LISTENING', 'Lyssnar. Tryck på mikrofonen igen för att avsluta.');
+      listeningTimer = win.setTimeout(() => {
+        if (token !== generation) return;
+        try { instance.abort(); } catch (_) { /* Recognition may already have stopped. */ }
+        finishRecognition(token, 'Mikrofonen stängdes efter en minut. Tryck för att försöka igen eller skriv.');
+      }, 60000);
+      try { instance.start(); }
+      catch (_) { finishRecognition(token, 'Mikrofonen kunde inte startas. Kontrollera behörigheten och försök igen.'); return false; }
+      return true;
+    }
+
+    function availableVoices() {
+      try { return win.speechSynthesis?.getVoices?.() || []; } catch (_) { return []; }
+    }
+
+    function speak(text, voiceOptions = {}) {
+      if (!text || !win.speechSynthesis || !win.SpeechSynthesisUtterance) return false;
+      stopListening();
+      const hadQueuedUtterance = currentUtterance !== null;
+      if (hadQueuedUtterance) cancelSpeech();
+      const token = ++generation;
+      let utterance;
+      try { utterance = new win.SpeechSynthesisUtterance(text); }
+      catch (_) { setState('IDLE', 'Talsyntesen kunde inte startas. Dialogen finns kvar som text.'); return false; }
+      utterance.lang = settings.language || 'sv-SE';
+      const profile = voiceOptions.characterId ? settings.speakerProfiles?.[voiceOptions.characterId] || {} : {};
+      const identityProfile = characterVoiceProfile(voiceOptions.voiceIdentity, voiceOptions.characterId);
+      const isNarrator = voiceOptions.role === 'narrator';
+      const configuredRate = Number(voiceOptions.rate ?? profile.rate ?? settings.rate) || 1;
+      utterance.rate = Math.min(2, Math.max(0.5, configuredRate * (isNarrator || voiceOptions.rate != null || profile.rate != null ? 1 : identityProfile.rate)));
+      utterance.pitch = isNarrator ? 1 : Math.min(2, Math.max(0, Number(voiceOptions.pitch ?? profile.pitch ?? identityProfile.pitch) || 1));
+      const requestedName = voiceOptions.voiceName || profile.voiceName || settings.voiceName;
+      const voices = availableVoices();
+      utterance.voice = voices.find(voice => voice.name === requestedName)
+        || voices.find(voice => /^sv(-|$)/i.test(voice.lang))
+        || null;
+      utterance.onstart = () => {
+        if (token !== generation) return;
+        if (speechStartTimer !== null) win.clearTimeout(speechStartTimer);
+        speechStartTimer = null;
+        if (typeof voiceOptions.onStart === 'function') voiceOptions.onStart();
+      };
+      utterance.onend = () => {
+        if (token !== generation) return;
+        if (speechTimer !== null) win.clearTimeout(speechTimer);
+        if (speechStartTimer !== null) win.clearTimeout(speechStartTimer);
+        speechTimer = null;
+        speechStartTimer = null;
+        currentUtterance = null;
+        setState('IDLE');
+      };
+      utterance.onerror = () => {
+        if (token !== generation) return;
+        if (speechTimer !== null) win.clearTimeout(speechTimer);
+        if (speechStartTimer !== null) win.clearTimeout(speechStartTimer);
+        speechTimer = null;
+        speechStartTimer = null;
+        currentUtterance = null;
+        generation += 1;
+        setState('IDLE', 'Uppläsningen avbröts. Dialogen finns kvar som text.');
+      };
+      setState('SPEAKING', 'Läser upp dialog.');
+      currentUtterance = utterance;
+      speechStartTimer = win.setTimeout(() => {
+        if (token !== generation || currentUtterance !== utterance) return;
+        speechStartTimer = null;
+        generation += 1;
+        currentUtterance = null;
+        if (speechTimer !== null) win.clearTimeout(speechTimer);
+        speechTimer = null;
+        // Drop a blocked native utterance now. A player retry can then call
+        // speak() directly from its button gesture instead of following a
+        // same-turn cancel() that older WebKit versions may discard.
+        try { win.speechSynthesis.cancel(); } catch (_) { /* Best effort. */ }
+        setState('IDLE', 'Uppläsningen startade inte. Tryck på Läs senaste repliken för att starta ljudet.');
+      }, 4000);
+      speechTimer = win.setTimeout(() => {
+        if (token !== generation) return;
+        generation += 1;
+        try { win.speechSynthesis.cancel(); } catch (_) { /* Best effort. */ }
+        currentUtterance = null;
+        if (speechStartTimer !== null) win.clearTimeout(speechStartTimer);
+        speechStartTimer = null;
+        speechTimer = null;
+        setState('IDLE', 'Uppläsningen avslutades. Dialogen finns kvar som text.');
+      }, Math.max(30000, Math.min(180000, String(text).length * 180)));
+      const enqueue = () => {
+        if (token !== generation) return;
+        try { win.speechSynthesis.speak(utterance); }
+        catch (_) {
+          currentUtterance = null;
+          cancelSpeech();
+          setState('IDLE', 'Talsyntesen kunde inte startas. Dialogen finns kvar som text.');
+        }
+      };
+      try {
+        // Give WebKit one event-loop turn to finish cancel() before replacing
+        // speech that was actively playing. Normal replies enqueue immediately.
+        if (hadQueuedUtterance) win.setTimeout(enqueue, 100);
+        else enqueue();
+      }
+      catch (_) { cancelSpeech(); setState('IDLE', 'Talsyntesen kunde inte startas. Dialogen finns kvar som text.'); return false; }
+      return true;
+    }
+
+    function update(patch) { Object.assign(settings, patch); return {...settings}; }
+    function stopAll() { stopListening(); cancelSpeech(); }
+    function getState() { return state; }
+    function getSettings() { return {...settings}; }
+    function getVoices() { return availableVoices(); }
+    function supportsRecognition() { return Boolean(win.SpeechRecognition || win.webkitSpeechRecognition); }
+    return {startListening, stopListening, speak, cancelSpeech, stopAll, activateFromUserGesture, update, getState, getSettings, getVoices, supportsRecognition};
+  }
+
+  root.GameVoice = {createVoiceController, DEFAULT_SETTINGS, parseVoiceCommand, loadSettings, saveSettings, characterVoiceProfile};
+})(typeof window !== 'undefined' ? window : globalThis);