narrarium-astro-reader 0.1.22 → 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/`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "narrarium-astro-reader",
-  "version": "0.1.22",
+  "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.22",
+    "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">
@@ -156,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 || "[]") : [];
@@ -657,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;
@@ -674,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]");
 
@@ -690,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)
     ) {
@@ -709,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);
@@ -739,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) {
@@ -883,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);
@@ -892,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;
@@ -914,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);
@@ -937,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);
     });
@@ -946,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) {
@@ -1156,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/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;