@davmash/bygone 0.8.5 → 0.8.7

package/CHANGELOG.md

@@ -2,11 +2,24 @@
 
 ## Unreleased
 
+## 0.8.7
+
+- Refined tour narration controls with clearer playback state, sentence-level skipping, and consolidated play/pause behavior
+- Allowed narration skips to continue across adjacent tour steps and slides while preserving paused playback
+- Improved tour and comparison toolbar controls, including clearer disabled word-wrap feedback
+
+## 0.8.6
+
+- Added optional authored-tour `windowTitle` labels and context-aware desktop and VS Code window titles
+- Fixed tour presenter windows so authored `windowTitle` values appear in the native title instead of staying on the default `Bygone Tour` label
+
 ## 0.8.5
 
 - Fixed Homebrew cask `bygone` CLI launch on Apple Silicon by routing through a bundle-aware launcher script inside the app
 - Documented the macOS **“app is damaged”** workaround for unsigned desktop downloads (README, releasing docs, PR Tour Guide skill)
 
+**macOS install:** Desktop builds are unsigned. If Gatekeeper reports the app is damaged, run `xattr -cr /Applications/Bygone.app` then open the app.
+
 ## 0.8.4
 
 - Clarified PR Tour Guide skill install commands for project scope and agent-specific global installs

package/README.md

@@ -98,6 +98,12 @@ new comparison brings the central app window forward and replaces its current
 session after any unsaved-change confirmation. Tours reuse a dedicated window
 owned by that same app process.
 
+When Bygone is quit or restarted for an upgrade, the desktop app remembers the
+open Explore session and tour windows. A normal no-argument launch restores
+them; an explicit file, directory, review, or presentation launch takes
+precedence. Windows whose source files or Git targets no longer exist are
+skipped or replaced with a blank Explore window.
+
 Shell completion is generated from the same command specification as `bygone --help`, including contextual file arguments and local Git refs for branch review. `npm run dev:sync`, the desktop app's command-line installer, and the Homebrew packages install completions automatically. To install one manually, choose the command for your shell:
 
 ```bash

package/cli/present.js

@@ -3,6 +3,7 @@ const { createServer } = require('http');
 const path = require('path');
 const { spawn } = require('child_process');
 const { buildChangeTourManifest, parseChangeTourStory } = require('../out/changeTour.js');
+const { buildTourWindowTitle } = require('../out/windowTitle.js');
 const { tokenMatches } = require('./commandSpec.js');
 const { loadTourSource } = require('./tourFile.js');
 
@@ -39,8 +40,26 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
         process.stdout.write(`Wrote change-tour manifest to ${resolvedOutput}\n`);
     }
 
+    const tourWindowTitle = buildTourWindowTitle(manifest, 'Bygone');
+    const presenterIndexPath = path.join(packageRoot, 'web', 'index.html');
+    let presenterIndexTemplate;
+
     const server = createServer((request, response) => {
         const requestUrl = new URL(request.url || '/', 'http://127.0.0.1');
+        if (requestUrl.pathname === '/narration/claim') {
+            if (request.method !== 'POST') {
+                respond(response, 405, 'Method not allowed');
+                return;
+            }
+            if (!isSameOriginLoopbackRequest(request)) {
+                respond(response, 403, 'Forbidden');
+                return;
+            }
+            options.onNarrationClaim?.();
+            response.writeHead(204, { 'Cache-Control': 'no-store' });
+            response.end();
+            return;
+        }
         if (requestUrl.pathname === '/tour.json') {
             response.writeHead(200, {
                 'Content-Type': 'application/json; charset=utf-8',
@@ -49,6 +68,21 @@ async function startPresentation(args, cwd, packageRoot, options = {}) {
             response.end(serializedManifest);
             return;
         }
+        if (requestUrl.pathname === '/' || requestUrl.pathname === '/index.html') {
+            if (!presenterIndexTemplate) {
+                presenterIndexTemplate = readFileSync(presenterIndexPath, 'utf8');
+            }
+            const html = presenterIndexTemplate.replace(
+                /<title>Bygone Tour<\/title>/,
+                `<title>${escapeHtml(tourWindowTitle)}</title>`
+            );
+            response.writeHead(200, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Cache-Control': 'no-store'
+            });
+            response.end(html);
+            return;
+        }
         const targetPath = resolveAssetPath(packageRoot, requestUrl.pathname);
         if (!targetPath) {
             respond(response, 404, 'Not found');
@@ -120,7 +154,7 @@ function parsePresentArgs(args) {
 
 function resolveAssetPath(packageRoot, requestPath) {
     if (requestPath === '/' || requestPath === '/index.html') {
-        return path.join(packageRoot, 'web', 'index.html');
+        return null;
     }
     if (!requestPath.startsWith('/web/') && !requestPath.startsWith('/media/')) {
         return null;
@@ -160,7 +194,28 @@ function respond(response, statusCode, message) {
     response.end(message);
 }
 
+function isSameOriginLoopbackRequest(request) {
+    const origin = request.headers.origin;
+    const host = request.headers.host;
+    if (typeof origin !== 'string' || typeof host !== 'string') return false;
+    try {
+        const parsed = new URL(origin);
+        return parsed.protocol === 'http:' && parsed.hostname === '127.0.0.1' && parsed.host === host;
+    } catch {
+        return false;
+    }
+}
+
+function escapeHtml(text) {
+    return text
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;');
+}
+
 module.exports = {
     parsePresentArgs,
-    startPresentation
+    startPresentation,
+    escapeHtml
 };

package/docs/change-tour-format.md

@@ -35,11 +35,16 @@ contents, and diffs into the portable JSON manifest served by the presenter.
 Compilation fails if an anchor has no match or has multiple matches without an
 explicit `occurrence`.
 
+The optional `windowTitle` sets the native window title for the tour presenter.
+Use a short label such as a pull request number when several tours may be open at
+once. When omitted, the presenter falls back to `title`, then a generic tour label.
+
 ## Structure
 
 ```yaml
 version: 1
 title: A reviewer-facing title
+windowTitle: PR-1234
 sourceUrl: https://example.test/pull/123
 range:
   base: 0123456789abcdef

package/docs/present.md

@@ -14,6 +14,38 @@ The Files rail is independent of the narrative. Browsing another file keeps
 the active tour anchor visible and offers **Return to Tour** to restore the
 scene's intended focus.
 
+## Listen to a tour
+
+Use **Listen** in the narrative header or **Present → Listen to Tour** in the
+desktop app to read the tour aloud with a device voice. Narration works
+offline and does not send tour text to a hosted speech service.
+
+- **Pause/Resume** retains the current sentence; **Stop** clears playback. The
+  outer jump controls move one sentence backward or forward within the current
+  narration item.
+- Existing Previous and Next controls move through the same scene/step order
+  used by continuous narration.
+- Choose any device voice exposed by the browser and a speed from 0.75× to
+  1.5×. Bygone stores those preferences locally and returns to the system
+  default if a selected voice disappears.
+- The visible sentence is highlighted while it is spoken. Pausing retains a
+  distinct paused highlight without moving keyboard focus.
+- Direct scene, file, or search navigation interrupts speech and leaves it
+  paused at the selected tour position. Resume continues from there.
+
+Automatic narration reads chapter and scene framing, summaries, bullets,
+step titles and bodies, connection labels, and takeaways. It does not
+automatically read diff contents, code blocks, hashes, line numbers, or raw
+URLs. Those remain visible and available to assistive technology normally.
+
+Device voice names and quality depend on the operating system and browser.
+If no device speech engine is exposed, Bygone disables Listen with a specific
+unsupported-device message; lack of network access alone never disables it.
+
+Future narration work may add opt-in treatment for code and raw URLs, plus
+higher-quality hosted voices or routing through the agent that originated the
+conversation. Those remain separate from the offline, device-first baseline.
+
 ## Read provenance correctly
 
 - Normal walkthrough scenes point to exact committed source evidence.

package/docs/product-surface.md

@@ -48,6 +48,7 @@ not packaged.
 | --- | --- | --- | --- | --- | --- |
 | Explain the current branch automatically | Present → Present Current Branch; `bygone present` | Committed merge-base-to-tip range | Read-only | Core | presentation launch and generated-tour tests |
 | Open an authored walkthrough | Present → Open Authored Tour; `bygone present --tour`; VS Code hand-off | Manifest range, scene, step, exact source anchor | Read-only | Core | reproducible example and tour validation tests |
+| Listen to a generated or authored tour | Narrative Listen controls; Present → Listen to Tour | Existing manifest narrative segmented locally by scene/step and visible sentence | Read-only device TTS; voice/rate preferences remain local; continuous playback follows tour navigation and direct exploration pauses it | Core | narration model/controller and presenter-host tests |
 | Explain a real stack | `stacked-diff` scene | Exact real Git revisions per panel | Read-only | Advanced | `examples/stacked-diff.bygone` |
 | Explain a change in conceptual stages | `deconstructed-diff` scene | Explicitly labeled synthetic explanation stages backed by exact hunk IDs | Read-only | Advanced/experimental authoring | `examples/deconstructed-diff.bygone` |
 | Browse away from the narration | Files rail, change navigation | Browsed file versus active tour focus remain distinct | Read-only; Return to Tour restores narrative focus | Core | tour focus and persistent-anchor tests |