narrarium-astro-reader 0.1.21 → 0.1.23

package/README.md

@@ -28,6 +28,8 @@ npx narrarium-astro-reader reader --book-root .. --package-name my-book-reader
 - live search across canon, chapters, and scenes
 - character, location, faction, item, secret, and timeline indexes
 - canon mention popups, backlinks, and asset rendering for book, entity, chapter, and scene art
+- a Full read chapter mode that opens an immersive browser-fullscreen reading view with continuous prose, auto-hiding minimal previous/jump/next navigation, a small ghost hint for rediscovering controls, and canon popups still available
+- dismissible Read Aloud controls that can be reopened from a subtle masthead speaker button and stay out of the way during Full read mode
 - automatic EPUB export to `public/downloads/book.epub`
 - live watcher for book markdown, canon, and assets during `npm run dev`
 - `npm run doctor` for broken references, spoiler thresholds, asset metadata, and stale `plot.md`, `resumes/`, or `state/`
@@ -43,6 +45,7 @@ In public mode:
 - secrets stay hidden from the public atlas and nav
 - direct canon pages fall back to teaser or locked views when `known_from` or `reveal_in` say a dossier is not safe yet
 - search, canon popups, and backlinks follow the same thresholds
+- chapter and scene prose should keep canon names as plain text; the reader upgrades visible mentions into canon popups and also rewrites legacy internal canon links at runtime
 
 If you want an author-only or spoiler-friendly deployment, enable full canon mode:
 

package/cli-dist/lib/canon-mentions.d.ts

@@ -0,0 +1,8 @@
+export type CanonMentionEntry = {
+    id: string;
+    href: string;
+};
+export declare function buildCanonHrefIndex(entries: CanonMentionEntry[]): Map<string, string>;
+export declare function resolveCanonEntryIdFromHref(href: string, entries: CanonMentionEntry[]): string | null;
+export declare function normalizeCanonEntityHref(href: string): string | null;
+//# sourceMappingURL=canon-mentions.d.ts.map

package/cli-dist/lib/canon-mentions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canon-mentions.d.ts","sourceRoot":"","sources":["../../src/lib/canon-mentions.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAarF;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAAE,GAAG,MAAM,GAAG,IAAI,CAOrG;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyCpE"}

package/cli-dist/lib/canon-mentions.js

@@ -0,0 +1,86 @@
+export function buildCanonHrefIndex(entries) {
+    const index = new Map();
+    for (const entry of entries) {
+        const normalizedHref = normalizeCanonEntityHref(entry.href);
+        if (!normalizedHref) {
+            continue;
+        }
+        index.set(normalizedHref, entry.id);
+    }
+    return index;
+}
+export function resolveCanonEntryIdFromHref(href, entries) {
+    const normalizedHref = normalizeCanonEntityHref(href);
+    if (!normalizedHref) {
+        return null;
+    }
+    return buildCanonHrefIndex(entries).get(normalizedHref) ?? null;
+}
+export function normalizeCanonEntityHref(href) {
+    const strippedOrigin = href
+        .trim()
+        .replace(/^[a-z]+:\/\/[^/]+/i, "")
+        .split(/[?#]/, 1)[0]
+        .replace(/\\/g, "/");
+    if (!strippedOrigin) {
+        return null;
+    }
+    const segments = strippedOrigin
+        .split("/")
+        .filter(Boolean)
+        .filter((segment) => segment !== "." && segment !== "..");
+    for (let index = 0; index < segments.length; index += 1) {
+        const current = segments[index]?.toLowerCase();
+        if (!current) {
+            continue;
+        }
+        if (current === "timelines" && segments[index + 1]?.toLowerCase() === "events") {
+            const slug = normalizeSlugSegment(segments[index + 2]);
+            if (slug) {
+                return `timeline/${slug}/`;
+            }
+            continue;
+        }
+        const section = normalizeCanonSection(current);
+        if (!section) {
+            continue;
+        }
+        const slug = normalizeSlugSegment(segments[index + 1]);
+        if (slug) {
+            return `${section}/${slug}/`;
+        }
+    }
+    return null;
+}
+function normalizeCanonSection(segment) {
+    switch (segment.toLowerCase()) {
+        case "character":
+        case "characters":
+            return "characters";
+        case "location":
+        case "locations":
+            return "locations";
+        case "faction":
+        case "factions":
+            return "factions";
+        case "item":
+        case "items":
+            return "items";
+        case "secret":
+        case "secrets":
+            return "secrets";
+        case "timeline":
+        case "timeline-event":
+            return "timeline";
+        default:
+            return null;
+    }
+}
+function normalizeSlugSegment(segment) {
+    if (!segment) {
+        return null;
+    }
+    const normalized = segment.replace(/\.md$/i, "").trim().toLowerCase();
+    return /^[a-z0-9-]+$/.test(normalized) ? normalized : null;
+}
+//# sourceMappingURL=canon-mentions.js.map

package/cli-dist/lib/canon-mentions.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "narrarium-astro-reader",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "type": "module",
   "description": "Astro reader and scaffolding CLI for Narrarium book repositories.",
   "license": "MIT",
@@ -50,7 +50,7 @@
     "test": "npm run build:cli && node --test test/**/*.test.mjs"
   },
   "dependencies": {
-    "narrarium": "^0.1.21",
+    "narrarium": "^0.1.23",
     "astro": "^5.14.1",
     "chokidar": "^4.0.3",
     "marked": "^16.3.0"

package/src/components/ReaderRuntime.astro

@@ -121,7 +121,10 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
       <p class="eyebrow">Read Aloud</p>
       <p class="tts-player__title" data-tts-title>Ready</p>
     </div>
-    <span class="chip" data-tts-badge>Browser voice</span>
+    <div class="tts-player__top-actions">
+      <span class="chip" data-tts-badge>Browser voice</span>
+      <button type="button" class="icon-btn" data-tts-close aria-label="Hide read aloud controls">x</button>
+    </div>
   </div>
   <p class="tts-player__label" data-tts-label>Choose a chapter or scene to start reading aloud.</p>
   <div class="tts-player__controls">
@@ -144,7 +147,9 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
 <script type="application/json" id="canon-glossary-data" set:html={glossaryJson}></script>
 <script type="application/json" id="reader-chapter-data" set:html={chaptersJson}></script>
 
-<script is:inline>
+<script>
+  import { buildCanonHrefIndex, normalizeCanonEntityHref } from "../lib/canon-mentions.js";
+
   const themeStorageKey = "narrarium-reader-theme";
   const canonModeStorageKey = "narrarium-reader-canon";
   const progressStorageKey = "narrarium-reader-progress";
@@ -154,6 +159,7 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
   const ttsVoiceStorageKey = "narrarium-reader-tts-voice";
   const ttsRateStorageKey = "narrarium-reader-tts-rate";
   const ttsProgressStorageKey = "narrarium-reader-tts-progress";
+  const ttsPlayerDismissedStorageKey = "narrarium-reader-tts-player-dismissed";
   const glossaryDataElement = document.getElementById("canon-glossary-data");
   const chapterDataElement = document.getElementById("reader-chapter-data");
   const glossaryEntries = glossaryDataElement ? JSON.parse(glossaryDataElement.textContent || "[]") : [];
@@ -354,6 +360,7 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
     const limit = getSelectedSpoilerLimit();
     const visibleEntries = glossaryEntries.filter((entry) => isEntryVisible(entry, limit));
     const glossaryById = new Map(visibleEntries.map((entry) => [entry.id, entry]));
+    const hrefIndex = buildCanonHrefIndex(visibleEntries);
     const termMap = new Map();
 
     for (const entry of visibleEntries) {
@@ -368,15 +375,15 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
     }
 
     const terms = [...termMap.keys()].sort((left, right) => right.length - left.length);
-    if (terms.length === 0) return;
-
-    const pattern = new RegExp(`(^|[^\\p{L}\\p{N}])(${terms.map(escapeRegex).join("|")})(?=$|[^\\p{L}\\p{N}])`, "giu");
+    const pattern = terms.length > 0
+      ? new RegExp(`(^|[^\\p{L}\\p{N}])(${terms.map(escapeRegex).join("|")})(?=$|[^\\p{L}\\p{N}])`, "giu")
+      : null;
 
-    enhanceCanonRoot(document, pattern, termMap);
-    initializeCanonOverlay(pattern, termMap, glossaryById, limit);
+    enhanceCanonRoot(document, pattern, termMap, hrefIndex);
+    initializeCanonOverlay(pattern, termMap, hrefIndex, glossaryById, limit);
   }
 
-  function enhanceCanonRoot(root, pattern, termMap) {
+  function enhanceCanonRoot(root, pattern, termMap, hrefIndex) {
     const containers = root instanceof Document
       ? root.querySelectorAll(".prose p, .prose li, .prose blockquote")
       : root.matches?.(".prose")
@@ -385,7 +392,11 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
 
     containers.forEach((container) => {
       if (container.dataset.canonEnhanced === "true") return;
+      rewriteLegacyCanonLinks(container, hrefIndex);
       container.dataset.canonEnhanced = "true";
+      if (!pattern) {
+        return;
+      }
       const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
       const textNodes = [];
       while (walker.nextNode()) {
@@ -430,12 +441,7 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
       }
 
       if (entryId) {
-        const button = document.createElement("button");
-        button.type = "button";
-        button.className = "canon-mention";
-        button.dataset.canonId = entryId;
-        button.textContent = term;
-        fragment.append(button);
+        fragment.append(createCanonMentionButton(entryId, term));
       } else {
         fragment.append(term);
       }
@@ -450,7 +456,33 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
     textNode.replaceWith(fragment);
   }
 
-  function initializeCanonOverlay(pattern, termMap, glossaryById, limit) {
+  function rewriteLegacyCanonLinks(container, hrefIndex) {
+    container.querySelectorAll("a[href]").forEach((anchor) => {
+      if (!(anchor instanceof HTMLAnchorElement) || anchor.closest("[data-no-canon]")) {
+        return;
+      }
+
+      const normalizedHref = normalizeCanonEntityHref(anchor.getAttribute("href") || "");
+      if (!normalizedHref) {
+        return;
+      }
+
+      const label = anchor.textContent || "";
+      const entryId = hrefIndex.get(normalizedHref);
+      anchor.replaceWith(entryId ? createCanonMentionButton(entryId, label) : document.createTextNode(label));
+    });
+  }
+
+  function createCanonMentionButton(entryId, label) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "canon-mention";
+    button.dataset.canonId = entryId;
+    button.textContent = label;
+    return button;
+  }
+
+  function initializeCanonOverlay(pattern, termMap, hrefIndex, glossaryById, limit) {
     const overlay = document.querySelector("[data-canon-overlay]");
     if (!overlay || overlay.dataset.bound === "true") return;
     overlay.dataset.bound = "true";
@@ -482,7 +514,7 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
         link.href = entry.href;
         link.hidden = !revealed;
         body.innerHTML = revealed ? entry.bodyHtml || "" : "";
-        enhanceCanonRoot(body, pattern, termMap);
+        enhanceCanonRoot(body, pattern, termMap, hrefIndex);
         metadata.replaceChildren(...(entry.metadataEntries || []).map((item) => {
           const row = document.createElement("div");
           row.className = "meta-row";
@@ -629,12 +661,12 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
     const player = document.querySelector("[data-tts-player]");
     const roots = [...document.querySelectorAll("[data-tts-root]")];
     const triggers = [...document.querySelectorAll("[data-tts-trigger]")];
+    const panelToggle = document.querySelector("[data-tts-panel-toggle]");
     if (!(player instanceof HTMLElement) || roots.length === 0) {
       return;
     }
 
     document.body.classList.add("tts-enabled");
-    player.hidden = false;
     triggers.forEach((trigger) => {
       if (trigger instanceof HTMLElement) {
         trigger.hidden = false;
@@ -646,12 +678,17 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
       return;
     }
 
+    if (panelToggle instanceof HTMLButtonElement) {
+      panelToggle.hidden = false;
+    }
+
     const titleElement = player.querySelector("[data-tts-title]");
     const labelElement = player.querySelector("[data-tts-label]");
     const badgeElement = player.querySelector("[data-tts-badge]");
     const statusElement = player.querySelector("[data-tts-status]");
     const playToggle = player.querySelector("[data-tts-play-toggle]");
     const stopButton = player.querySelector("[data-tts-stop]");
+    const closeButton = player.querySelector("[data-tts-close]");
     const voiceSelect = player.querySelector("[data-tts-voice]");
     const rateInput = player.querySelector("[data-tts-rate]");
 
@@ -662,6 +699,7 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
       !(statusElement instanceof HTMLElement) ||
       !(playToggle instanceof HTMLButtonElement) ||
       !(stopButton instanceof HTMLButtonElement) ||
+      !(closeButton instanceof HTMLButtonElement) ||
       !(voiceSelect instanceof HTMLSelectElement) ||
       !(rateInput instanceof HTMLInputElement)
     ) {
@@ -681,14 +719,19 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
       runId: 0,
       speaking: false,
       paused: false,
+      focusMode: document.body.classList.contains("is-focus-mode"),
+      dismissed: readStorage(ttsPlayerDismissedStorageKey) === "true",
       titleElement,
       labelElement,
       badgeElement,
       statusElement,
       playToggle,
       stopButton,
+      closeButton,
       voiceSelect,
       rateInput,
+      player,
+      panelToggle,
     };
 
     const savedProgress = readJson(ttsProgressStorageKey);
@@ -711,10 +754,24 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
       window.speechSynthesis.onvoiceschanged = () => populateVoiceOptions(state);
     }
 
+    if (panelToggle instanceof HTMLButtonElement) {
+      panelToggle.addEventListener("click", () => {
+        if (state.player.hidden) {
+          showTtsPlayer(state, { persistDismissed: false });
+          updateTtsUi(state);
+          return;
+        }
+
+        hideTtsPlayer(state, { persistDismissed: true });
+      });
+    }
+
     window.addEventListener("beforeunload", () => {
       state.runId += 1;
       state.speech.cancel();
     });
+
+    hideTtsPlayer(state, { persistDismissed: false });
   }
 
   function buildTtsScopes(roots) {
@@ -855,6 +912,7 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
 
       trigger.dataset.defaultLabel = trigger.textContent || "Read aloud";
       trigger.addEventListener("click", () => {
+        showTtsPlayer(state, { persistDismissed: false });
         const scopeId = trigger.dataset.ttsTrigger || "chapter";
         startTtsScope(state, scopeId);
         updateTtsTriggerButtons(triggers, state);
@@ -864,6 +922,7 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
 
   function bindTtsPlayerControls(state) {
     state.playToggle.addEventListener("click", () => {
+      showTtsPlayer(state, { persistDismissed: false });
       if (state.speech.speaking && !state.speech.paused) {
         state.speech.pause();
         state.paused = true;
@@ -886,6 +945,10 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
       updateTtsUi(state);
     });
 
+    state.closeButton.addEventListener("click", () => {
+      hideTtsPlayer(state, { persistDismissed: true });
+    });
+
     state.voiceSelect.addEventListener("change", () => {
       state.voiceUri = state.voiceSelect.value;
       writeStorage(ttsVoiceStorageKey, state.voiceUri);
@@ -909,6 +972,7 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
     window.addEventListener("narrarium:tts-start", (event) => {
       const detail = event instanceof CustomEvent ? event.detail || {} : {};
       const scopeId = typeof detail.scopeId === "string" ? detail.scopeId : "chapter";
+      showTtsPlayer(state, { persistDismissed: false });
       startTtsScope(state, scopeId, { fromStart: Boolean(detail.fromStart) });
       updateTtsTriggerButtons(state.triggers, state);
     });
@@ -918,6 +982,15 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
       stopTts(state, detail.keepProgress !== false);
       updateTtsUi(state);
     });
+
+    window.addEventListener("narrarium:focus-mode-change", (event) => {
+      const detail = event instanceof CustomEvent ? event.detail || {} : {};
+      state.focusMode = Boolean(detail.enabled);
+      if (state.focusMode) {
+        hideTtsPlayer(state, { persistDismissed: false });
+      }
+      syncTtsPanelToggle(state);
+    });
   }
 
   function populateVoiceOptions(state) {
@@ -1128,6 +1201,41 @@ const chaptersJson = JSON.stringify(chapters).replace(/</g, "\\u003c");
     updateTtsTriggerButtons(state.triggers, state);
   }
 
+  function showTtsPlayer(state, options) {
+    if (state.focusMode) {
+      return;
+    }
+
+    state.dismissed = false;
+    state.player.hidden = false;
+    syncTtsPanelToggle(state);
+    if (options?.persistDismissed === false) {
+      removeStorage(ttsPlayerDismissedStorageKey);
+    } else {
+      writeStorage(ttsPlayerDismissedStorageKey, "false");
+    }
+  }
+
+  function hideTtsPlayer(state, options) {
+    state.player.hidden = true;
+    state.dismissed = true;
+    syncTtsPanelToggle(state);
+    if (options?.persistDismissed) {
+      writeStorage(ttsPlayerDismissedStorageKey, "true");
+    }
+  }
+
+  function syncTtsPanelToggle(state) {
+    if (!(state.panelToggle instanceof HTMLButtonElement)) {
+      return;
+    }
+
+    const expanded = !state.player.hidden && !state.focusMode;
+    state.panelToggle.setAttribute("aria-pressed", expanded ? "true" : "false");
+    state.panelToggle.setAttribute("aria-label", expanded ? "Hide read aloud controls" : "Open read aloud controls");
+    state.panelToggle.textContent = expanded ? "🔈" : "🔊";
+  }
+
   function highlightTtsSegment(segment) {
     clearTtsHighlight();
     segment.classList.add("is-speaking");

package/src/layouts/BaseLayout.astro

@@ -86,6 +86,7 @@ const isChapterPage = Number.isFinite(currentChapterNumber);
         </nav>
         <div class="masthead-actions">
           <a class="chip reader-status" data-continue-link href="./" hidden>Continue reading</a>
+          <button type="button" class="masthead-btn" data-tts-panel-toggle aria-label="Open read aloud controls" aria-pressed="false" hidden>🔊</button>
           <button type="button" class="masthead-btn" data-search-toggle aria-label="Search">🔍</button>
           <button type="button" class="masthead-btn" data-reader-settings-toggle aria-label="Open reading settings">⚙</button>
         </div>

package/src/lib/canon-mentions.ts

@@ -0,0 +1,105 @@
+export type CanonMentionEntry = {
+  id: string;
+  href: string;
+};
+
+export function buildCanonHrefIndex(entries: CanonMentionEntry[]): Map<string, string> {
+  const index = new Map<string, string>();
+
+  for (const entry of entries) {
+    const normalizedHref = normalizeCanonEntityHref(entry.href);
+    if (!normalizedHref) {
+      continue;
+    }
+
+    index.set(normalizedHref, entry.id);
+  }
+
+  return index;
+}
+
+export function resolveCanonEntryIdFromHref(href: string, entries: CanonMentionEntry[]): string | null {
+  const normalizedHref = normalizeCanonEntityHref(href);
+  if (!normalizedHref) {
+    return null;
+  }
+
+  return buildCanonHrefIndex(entries).get(normalizedHref) ?? null;
+}
+
+export function normalizeCanonEntityHref(href: string): string | null {
+  const strippedOrigin = href
+    .trim()
+    .replace(/^[a-z]+:\/\/[^/]+/i, "")
+    .split(/[?#]/, 1)[0]
+    .replace(/\\/g, "/");
+  if (!strippedOrigin) {
+    return null;
+  }
+
+  const segments = strippedOrigin
+    .split("/")
+    .filter(Boolean)
+    .filter((segment) => segment !== "." && segment !== "..");
+
+  for (let index = 0; index < segments.length; index += 1) {
+    const current = segments[index]?.toLowerCase();
+    if (!current) {
+      continue;
+    }
+
+    if (current === "timelines" && segments[index + 1]?.toLowerCase() === "events") {
+      const slug = normalizeSlugSegment(segments[index + 2]);
+      if (slug) {
+        return `timeline/${slug}/`;
+      }
+      continue;
+    }
+
+    const section = normalizeCanonSection(current);
+    if (!section) {
+      continue;
+    }
+
+    const slug = normalizeSlugSegment(segments[index + 1]);
+    if (slug) {
+      return `${section}/${slug}/`;
+    }
+  }
+
+  return null;
+}
+
+function normalizeCanonSection(segment: string): string | null {
+  switch (segment.toLowerCase()) {
+    case "character":
+    case "characters":
+      return "characters";
+    case "location":
+    case "locations":
+      return "locations";
+    case "faction":
+    case "factions":
+      return "factions";
+    case "item":
+    case "items":
+      return "items";
+    case "secret":
+    case "secrets":
+      return "secrets";
+    case "timeline":
+    case "timeline-event":
+      return "timeline";
+    default:
+      return null;
+  }
+}
+
+function normalizeSlugSegment(segment: string | undefined): string | null {
+  if (!segment) {
+    return null;
+  }
+
+  const normalized = segment.replace(/\.md$/i, "").trim().toLowerCase();
+  return /^[a-z0-9-]+$/.test(normalized) ? normalized : null;
+}

package/src/pages/chapters/[chapter].astro

@@ -31,10 +31,10 @@ const currentIndex = allChapters.findIndex((entry) => entry.slug === chapterSlug
 const previousChapter = currentIndex > 0 ? allChapters[currentIndex - 1] : null;
 const nextChapter = currentIndex >= 0 && currentIndex < allChapters.length - 1 ? allChapters[currentIndex + 1] : null;
 const chapterHtml = await marked.parse(chapter.body);
-const chapterMetaEntries = [
-  ["Point of view", chapter.metadata.pov],
-  ["Timeline", chapter.metadata.timeline_ref],
-  ["Tags", chapter.metadata.tags],
+const chapterMetaEntries: Array<[string, unknown]> = [
+  ["Point of view", chapter.metadata.pov] as [string, unknown],
+  ["Timeline", chapter.metadata.timeline_ref] as [string, unknown],
+  ["Tags", chapter.metadata.tags] as [string, unknown],
 ].filter(([, value]) => value !== undefined && value !== null && (!Array.isArray(value) || value.length > 0));
 const chapterId = String(chapter.metadata.id);
 const chapterRelatedLinks = await loadRelatedCanonLinks(chapterId, [chapter.metadata.pov, chapter.metadata.timeline_ref]);
@@ -73,7 +73,7 @@ const renderedParagraphs = await Promise.all(
   </div>
 
   <section class="section chapter-reading-frame">
-    <div class="chapter-focus-banner">
+    <div class="chapter-focus-banner focus-hidden">
       <p class="eyebrow">Full read</p>
       <h2>{chapter.metadata.title}</h2>
       <p class="chapter-meta" data-reader-current-scene>Chapter opening</p>
@@ -195,42 +195,81 @@ const renderedParagraphs = await Promise.all(
         <p class="eyebrow">Full read</p>
         <div class="focus-rail__title">{chapter.metadata.title}</div>
       </div>
-      <div class="focus-rail__status" data-reader-current-scene>Chapter opening</div>
     </div>
     <div class="focus-rail__controls">
       <a class:list={["focus-rail__link", !previousChapter && "is-disabled"]} href={previousChapter ? `chapters/${previousChapter.slug}/` : undefined} aria-disabled={!previousChapter}>Previous</a>
-      <button type="button" class="focus-rail__button is-primary" data-reader-focus-tts="chapter">From start</button>
-      <button type="button" class="focus-rail__button" data-reader-marker-play disabled>From mark</button>
-      <button type="button" class="focus-rail__button" data-reader-focus-stop>Stop voice</button>
+      <label class="focus-rail__jump">
+        <span class="sr-only">Jump to chapter</span>
+        <select data-reader-focus-jump aria-label="Jump to chapter">
+          {allChapters.map((entry) => (
+            <option value={entry.slug} selected={entry.slug === chapterSlug}>
+              {`Chapter ${String(entry.metadata.number).padStart(3, "0")} - ${entry.metadata.title}`}
+            </option>
+          ))}
+        </select>
+      </label>
       <a class:list={["focus-rail__link", !nextChapter && "is-disabled"]} href={nextChapter ? `chapters/${nextChapter.slug}/` : undefined} aria-disabled={!nextChapter}>Next</a>
       <button type="button" class="focus-rail__button" data-reader-focus-toggle>Exit</button>
     </div>
   </aside>
 
+  <div class="focus-hint" data-reader-focus-hint aria-hidden="true">
+    Move the mouse, tap, or press a key to show controls.
+  </div>
+
   <script is:inline>
     (() => {
       const focusModeKey = "narrarium-reader-focus-mode";
       const voiceMarkerKey = "narrarium-reader-voice-marker";
+      const focusRailHideDelayMs = 1800;
+      const focusHintHideDelayMs = 2600;
       const root = document.body;
       const chapterPath = window.location.pathname;
+      const chapterSegments = chapterPath.split("/").filter(Boolean);
+      const currentChapterSlug = chapterSegments[chapterSegments.length - 1] || "";
+      const fullscreenTarget = document.documentElement;
       const toggleButtons = [...document.querySelectorAll("[data-reader-focus-toggle]")];
       const markerButtons = [...document.querySelectorAll("[data-reader-marker-set]")];
-      const markerPlayButton = document.querySelector("[data-reader-marker-play]");
-      const chapterPlayButton = document.querySelector("[data-reader-focus-tts='chapter']");
-      const stopVoiceButton = document.querySelector("[data-reader-focus-stop]");
+      const chapterJumpSelect = document.querySelector("[data-reader-focus-jump]");
+      const focusRail = document.querySelector(".focus-rail");
+      const focusHint = document.querySelector("[data-reader-focus-hint]");
       const currentSceneLabels = [...document.querySelectorAll("[data-reader-current-scene]")];
       const sceneElements = [...document.querySelectorAll("[data-reader-scene]")];
+      let focusRailHideTimer = null;
+      let focusHintHideTimer = null;
+      let railPointerInside = false;
+      let focusHintShownForSession = false;
 
-      applyFocusMode(readStorage(focusModeKey) === "true", false);
+      applyFocusMode(readStorage(focusModeKey) === "true", false, { allowFullscreenRequest: false });
       updateMarkerUi(readMarker());
       updateActiveScene();
 
       window.addEventListener("scroll", scheduleSceneRefresh, { passive: true });
       window.addEventListener("resize", scheduleSceneRefresh);
+      document.addEventListener("pointermove", handleFocusRailWake, { passive: true });
+      document.addEventListener("touchstart", handleFocusRailWake, { passive: true });
+      document.addEventListener("fullscreenchange", handleFullscreenChange);
+
+      focusRail?.addEventListener("pointerenter", () => {
+        railPointerInside = true;
+        showFocusRail();
+      });
+      focusRail?.addEventListener("pointerleave", () => {
+        railPointerInside = false;
+        scheduleFocusRailHide();
+      });
+      focusRail?.addEventListener("focusin", () => {
+        showFocusRail();
+      });
+      focusRail?.addEventListener("focusout", () => {
+        window.requestAnimationFrame(() => {
+          scheduleFocusRailHide();
+        });
+      });
 
       toggleButtons.forEach((button) => {
         button.addEventListener("click", () => {
-          applyFocusMode(!root.classList.contains("is-focus-mode"), true);
+          applyFocusMode(!root.classList.contains("is-focus-mode"), true, { allowFullscreenRequest: true });
         });
       });
 
@@ -246,20 +285,13 @@ const renderedParagraphs = await Promise.all(
         });
       });
 
-      chapterPlayButton?.addEventListener("click", () => {
-        startTtsFromScope("chapter");
-      });
-
-      markerPlayButton?.addEventListener("click", () => {
-        const marker = readMarker();
-        if (!marker || marker.path !== chapterPath || !marker.scopeId) {
+      chapterJumpSelect?.addEventListener("change", () => {
+        const nextSlug = chapterJumpSelect.value;
+        if (!nextSlug || nextSlug === currentChapterSlug) {
           return;
         }
-        startTtsFromScope(marker.scopeId);
-      });
 
-      stopVoiceButton?.addEventListener("click", () => {
-        window.dispatchEvent(new CustomEvent("narrarium:tts-stop", { detail: { keepProgress: true } }));
+        window.location.href = `chapters/${nextSlug}/`;
       });
 
       document.addEventListener("keydown", (event) => {
@@ -268,13 +300,17 @@ const renderedParagraphs = await Promise.all(
         }
 
         if (event.key === "Escape" && root.classList.contains("is-focus-mode")) {
-          applyFocusMode(false, true);
+          applyFocusMode(false, true, { allowFullscreenRequest: true });
+          return;
         }
 
         if (!event.metaKey && !event.ctrlKey && !event.altKey && event.key.toLowerCase() === "f") {
           event.preventDefault();
-          applyFocusMode(!root.classList.contains("is-focus-mode"), true);
+          applyFocusMode(!root.classList.contains("is-focus-mode"), true, { allowFullscreenRequest: true });
+          return;
         }
+
+        handleFocusRailWake();
       });
 
       let refreshScheduled = false;
@@ -291,28 +327,130 @@ const renderedParagraphs = await Promise.all(
         });
       }
 
-      function applyFocusMode(enabled, persist) {
+      function applyFocusMode(enabled, persist, options = { allowFullscreenRequest: false }) {
         root.classList.toggle("is-focus-mode", enabled);
+        window.dispatchEvent(new CustomEvent("narrarium:focus-mode-change", { detail: { enabled } }));
         toggleButtons.forEach((button) => {
           button.textContent = enabled ? "Exit full read" : "Full read";
           button.setAttribute("aria-pressed", enabled ? "true" : "false");
         });
+        if (enabled) {
+          resetFocusHintSession();
+          showFocusRailTemporarily();
+        } else {
+          clearFocusRailHideTimer();
+          clearFocusHintHideTimer();
+          focusRail?.classList.remove("is-hidden");
+          focusHint?.classList.remove("is-visible");
+        }
         scheduleSceneRefresh();
 
         if (persist) {
           writeStorage(focusModeKey, enabled ? "true" : "false");
         }
+
+        if (options.allowFullscreenRequest) {
+          void syncFullscreenForFocusMode(enabled);
+        }
+      }
+
+      function handleFocusRailWake() {
+        if (!root.classList.contains("is-focus-mode")) {
+          return;
+        }
+
+        hideFocusHint();
+        showFocusRailTemporarily();
+      }
+
+      function showFocusRailTemporarily() {
+        showFocusRail();
+        scheduleFocusRailHide();
+      }
+
+      function showFocusRail() {
+        clearFocusRailHideTimer();
+        focusRail?.classList.remove("is-hidden");
+      }
+
+      function scheduleFocusRailHide() {
+        clearFocusRailHideTimer();
+
+        if (!root.classList.contains("is-focus-mode") || railPointerInside || focusRail?.matches(":focus-within")) {
+          return;
+        }
+
+        focusRailHideTimer = window.setTimeout(() => {
+          if (!railPointerInside && !focusRail?.matches(":focus-within") && root.classList.contains("is-focus-mode")) {
+            focusRail?.classList.add("is-hidden");
+            showFocusHintOnce();
+          }
+        }, focusRailHideDelayMs);
+      }
+
+      function clearFocusRailHideTimer() {
+        if (focusRailHideTimer !== null) {
+          window.clearTimeout(focusRailHideTimer);
+          focusRailHideTimer = null;
+        }
+      }
+
+      function showFocusHintOnce() {
+        if (focusHintShownForSession || !root.classList.contains("is-focus-mode")) {
+          return;
+        }
+
+        focusHintShownForSession = true;
+        focusHint?.classList.add("is-visible");
+        clearFocusHintHideTimer();
+        focusHintHideTimer = window.setTimeout(() => {
+          focusHint?.classList.remove("is-visible");
+          focusHintHideTimer = null;
+        }, focusHintHideDelayMs);
+      }
+
+      function hideFocusHint() {
+        clearFocusHintHideTimer();
+        focusHint?.classList.remove("is-visible");
+      }
+
+      function resetFocusHintSession() {
+        focusHintShownForSession = false;
+        hideFocusHint();
       }
 
-      function startTtsFromScope(scopeId) {
-        window.dispatchEvent(
-          new CustomEvent("narrarium:tts-start", {
-            detail: {
-              scopeId,
-              fromStart: true,
-            },
-          }),
-        );
+      function clearFocusHintHideTimer() {
+        if (focusHintHideTimer !== null) {
+          window.clearTimeout(focusHintHideTimer);
+          focusHintHideTimer = null;
+        }
+      }
+
+      async function syncFullscreenForFocusMode(enabled) {
+        if (typeof fullscreenTarget.requestFullscreen !== "function" || typeof document.exitFullscreen !== "function") {
+          return;
+        }
+
+        try {
+          if (enabled) {
+            if (!document.fullscreenElement) {
+              await fullscreenTarget.requestFullscreen();
+            }
+          } else if (document.fullscreenElement) {
+            await document.exitFullscreen();
+          }
+        } catch {
+          // Ignore browsers that block or do not support fullscreen transitions.
+        }
+      }
+
+      function handleFullscreenChange() {
+        root.classList.toggle("is-reader-fullscreen", Boolean(document.fullscreenElement));
+
+        if (root.classList.contains("is-focus-mode")) {
+          hideFocusHint();
+          showFocusRailTemporarily();
+        }
       }
 
       function updateMarkerUi(marker) {
@@ -328,10 +466,6 @@ const renderedParagraphs = await Promise.all(
         document.querySelectorAll("[data-reader-marker-article]").forEach((article) => {
           article.classList.toggle("has-voice-marker", activeScopeId !== null && article.dataset.readerMarkerScope === activeScopeId);
         });
-
-        if (markerPlayButton instanceof HTMLButtonElement) {
-          markerPlayButton.disabled = !activeScopeId;
-        }
       }
 
       function updateActiveScene() {

package/src/styles/global.css

@@ -124,7 +124,6 @@ body.is-focus-mode {
 body.is-focus-mode .masthead,
 body.is-focus-mode .focus-hidden,
 body.is-focus-mode .reader-overlay,
-body.is-focus-mode .canon-overlay,
 body.is-focus-mode .tts-player,
 body.is-focus-mode .scene-tools,
 body.is-focus-mode .scene-media {
@@ -144,6 +143,10 @@ body.is-focus-mode .chapter-reading-frame {
   box-shadow: none;
 }
 
+body.is-focus-mode .chapter-reading-frame > .section {
+  margin-top: 0;
+}
+
 body.is-focus-mode .chapter-focus-banner {
   display: block;
   border: 0;
@@ -159,7 +162,11 @@ body.is-focus-mode .chapter-focus-banner {
 body.is-focus-mode .scene {
   max-width: min(100%, calc(var(--reader-measure) + 8ch));
   margin-inline: auto;
-  padding: 2rem 0;
+  padding: 1.5rem 0;
+}
+
+body.is-focus-mode .scene-header {
+  display: none;
 }
 
 body.is-focus-mode .scene-stack .scene::after {
@@ -174,6 +181,16 @@ body.is-focus-mode .focus-rail {
   display: block;
 }
 
+body.is-focus-mode .focus-rail.is-hidden {
+  opacity: 0;
+  pointer-events: none;
+  transform: translate(-50%, calc(100% + 1.5rem));
+}
+
+body.is-focus-mode .focus-hint {
+  display: inline-flex;
+}
+
 body.tts-enabled .shell {
   padding-bottom: 8rem;
 }
@@ -308,6 +325,12 @@ body.tts-enabled .shell {
   border-color: color-mix(in srgb, var(--accent) 25%, var(--line));
 }
 
+.masthead-btn[aria-pressed="true"] {
+  background: var(--accent-soft);
+  color: var(--text);
+  border-color: color-mix(in srgb, var(--accent) 30%, var(--line));
+}
+
 /* Primary TTS play button */
 .tts-button.is-primary {
   background: var(--accent);
@@ -359,6 +382,18 @@ body.tts-enabled .shell {
   border-color: color-mix(in srgb, var(--accent) 22%, var(--line));
 }
 
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 .chip-row {
   display: flex;
   flex-wrap: wrap;
@@ -1126,6 +1161,12 @@ mark {
   gap: 0.75rem;
 }
 
+.tts-player__top-actions {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
 .tts-player__title {
   margin: 0.15rem 0 0;
   font-weight: 600;
@@ -1139,7 +1180,7 @@ mark {
   position: fixed;
   left: 50%;
   bottom: 1rem;
-  transform: translateX(-50%);
+  transform: translate(-50%, 0);
   z-index: 46;
   width: min(760px, calc(100vw - 1rem));
   padding: 1rem 1.25rem;
@@ -1147,6 +1188,8 @@ mark {
   border: 1px solid var(--line);
   border-radius: 16px;
   box-shadow: var(--shadow);
+  opacity: 1;
+  transition: opacity 180ms ease, transform 180ms ease;
 }
 
 .focus-rail__meta {
@@ -1163,6 +1206,54 @@ mark {
   color: var(--text);
 }
 
+.focus-rail__jump {
+  min-width: min(320px, 100%);
+}
+
+.focus-rail__jump select {
+  min-width: min(320px, 100%);
+}
+
+.focus-hint {
+  display: none;
+  position: fixed;
+  left: 50%;
+  bottom: 6.25rem;
+  transform: translate(-50%, 0.8rem);
+  z-index: 45;
+  max-width: min(520px, calc(100vw - 2rem));
+  padding: 0.7rem 1rem;
+  border: 1px solid color-mix(in srgb, var(--accent) 24%, var(--line));
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--surface) 92%, var(--app-bg));
+  color: var(--text-muted);
+  font-size: 0.82rem;
+  line-height: 1.45;
+  text-align: center;
+  box-shadow: var(--shadow);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 220ms ease, transform 220ms ease;
+}
+
+.focus-hint.is-visible {
+  opacity: 1;
+  transform: translate(-50%, 0);
+  animation: focus-hint-pulse 1.8s ease-in-out 2;
+}
+
+@keyframes focus-hint-pulse {
+  0% {
+    box-shadow: 0 0 0 0 rgba(139, 92, 246, 0.16);
+  }
+  70% {
+    box-shadow: 0 0 0 10px rgba(139, 92, 246, 0);
+  }
+  100% {
+    box-shadow: var(--shadow);
+  }
+}
+
 /* ─── Related links section ──────────────────────────────────── */
 .scene > h2 {
   margin-bottom: 0.9rem;
@@ -1343,6 +1434,22 @@ mark {
     transform: none;
   }
 
+  .focus-hint {
+    left: 0.75rem;
+    right: 0.75rem;
+    bottom: 6.75rem;
+    max-width: none;
+    transform: translateY(0.8rem);
+  }
+
+  .focus-hint.is-visible {
+    transform: translateY(0);
+  }
+
+  body.is-focus-mode .focus-rail.is-hidden {
+    transform: translateY(calc(100% + 1.5rem));
+  }
+
   body.is-focus-mode .shell {
     width: calc(100vw - 1rem);
     padding-bottom: 13rem;