gutterpress 0.9.0-alpha.1 → 0.9.0-alpha.2

package/dist/index.js

@@ -142,7 +142,7 @@ import {
   validateProjectPlugins,
   verifyRepoReadable,
   writeAppHeartbeat
-} from "./index-m3pa4wyf.js";
+} from "./index-bynn850m.js";
 import {
   AUTO_SNAPSHOT_MESSAGE,
   HISTORY_PAGE_LIMIT,

package/dist/lib/markdown/assemble.d.ts

@@ -37,12 +37,10 @@ export interface AssembleBookHtmlOptions {
     plugins?: LoadedPlugin[];
     pluginCss?: string;
     /**
-     * Add `data-chapter-src="<file>"` to the same source-mapped block elements
-     * that receive `data-source-line`. The historical option name is retained as
-     * public API, but no wrapper is emitted: even `display: contents` changes CSS
-     * selector relationships such as `body > *`, `:first-child`, and cross-file
-     * siblings, which can change pagination. Off by default; build output is
-     * unaffected.
+     * Wrap each source file in `<div class="gutterpress-chapter"
+     * data-chapter-src="<file>">`. Used only by incremental preview so one
+     * source can be paginated and replaced independently. Off by default; build
+     * output is unaffected.
      */
     wrapChapters?: boolean;
     /**

package/dist/lib/markdown/chapter-id.d.ts

@@ -5,7 +5,7 @@
  * boundary: project-root-relative, forward slashes, no `./` prefix, no
  * duplicate slashes. This single form is used by:
  *
- *   - preview source blocks' `data-chapter-src` tagging
+ *   - preview source wrappers' `data-chapter-src` tagging
  *     (lib/markdown/assemble.ts assembleBookHtml — index.ts's renderChapters
  *     is now just the thin node:fs wrapper around it)
  *   - preview source inspection and chapter-scoped scroll restoration

package/dist/lib/markdown/index.d.ts

@@ -37,7 +37,7 @@ export declare function renderChapters(inputDir: string, opts?: {
     files?: string[] | null;
     plugins?: LoadedPlugin[];
     pluginCss?: string;
-    /** Add chapter identity to source-mapped blocks for preview inspection. */
+    /** Wrap each source file for incremental preview pagination. */
     wrapChapters?: boolean;
     /**
      * ARCH finding #4: per-chapter author-mistake warnings computed by

package/dist/{lint-4sq0dvf6.js → lint-96j9hrj4.js}

@@ -1,16 +1,16 @@
 import {
   MANIFEST_FILENAMES,
   runLint
-} from "./cli-yp0d2hp8.js";
+} from "./cli-k4bd06sd.js";
 import {
   log
-} from "./cli-v2dze8ja.js";
+} from "./cli-najycadg.js";
 import {
   EXIT_CODES,
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-rkqxbnkq.js";
+} from "./cli-e5zhb0xs.js";
 import"./cli-yzrh708h.js";
 import"./cli-wchtvxvw.js";
 import"./cli-yja077f6.js";

package/dist/{new-f2nmyr5b.js → new-8p38wavc.js}

@@ -5,17 +5,17 @@ import {
   TARGETS,
   TARGET_IDS,
   scaffoldProject
-} from "./cli-yp0d2hp8.js";
+} from "./cli-k4bd06sd.js";
 import {
   isToolAvailable,
   resolveGhostscript
-} from "./cli-v2dze8ja.js";
+} from "./cli-najycadg.js";
 import {
   EXIT_CODES,
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-rkqxbnkq.js";
+} from "./cli-e5zhb0xs.js";
 import"./cli-yzrh708h.js";
 import"./cli-wchtvxvw.js";
 import"./cli-yja077f6.js";

package/dist/{pagedjs-interface-80g3xa8p.js → pagedjs-interface-qxvzgwd7.js}

@@ -10,6 +10,8 @@
   var debugMode = false;
   var currentViewMode = 'two-column';
   var ignoreScrollUntil = 0;
+  var lastSourceLine = -1;
+  var lastSourceChapter = null;
 
   function refreshPages() {
     pages = Array.from(document.querySelectorAll('.pagedjs_page'));
@@ -51,6 +53,7 @@
     currentPage = page;
     ignoreScrollUntil = Date.now() + 300;
     pages[page - 1].scrollIntoView({ behavior: 'instant', block: 'start', inline: 'nearest' });
+    recordVisibleSource();
   }
 
   function pageStep(mode) {
@@ -129,11 +132,13 @@
     var top = el.getBoundingClientRect().top;
     if (top < ref) {
       // Find the next annotated sibling-in-flow (document order, higher line —
-      // a higher line also guarantees we haven't crossed into the next chapter,
-      // where data-source-line restarts).
+      // explicitly constrained to this chapter because source lines restart per
+      // file and a following chapter may begin at any line after front matter).
       var blocks = sourcedBlocks();
       var idx = blocks.indexOf(el);
+      var chapter = chapterOf(el);
       for (var i = idx + 1; i < blocks.length; i++) {
+        if (chapterOf(blocks[i]) !== chapter) break;
         var nl = lineOf(blocks[i]);
         if (nl == null) continue;
         if (nl <= line) break;
@@ -148,6 +153,34 @@
     return { el: el, line: line };
   }
 
+  function recordVisibleSource() {
+    var pos = visibleSourcePosition();
+    lastSourceLine = pos && pos.line != null ? pos.line : -1;
+    lastSourceChapter = pos ? chapterOf(pos.el) : null;
+  }
+
+  function preserveViewport(change) {
+    refreshPages();
+    var position = visibleSourcePosition();
+    var anchor = position ? {
+      el: position.el,
+      top: position.el.getBoundingClientRect().top
+    } : null;
+    change();
+    refreshPages();
+    if (!anchor) {
+      scrollToCurrentPage();
+      return;
+    }
+    ignoreScrollUntil = Date.now() + 300;
+    var delta = anchor.el.getBoundingClientRect().top - anchor.top;
+    if (delta) {
+      window.scrollBy({ top: delta, behavior: 'instant' });
+    }
+    currentPage = detectVisiblePage();
+    recordVisibleSource();
+  }
+
   // Resolve a {line, chapter?} target to its enclosing annotated block PLUS the
   // following annotated block, so callers can interpolate within long blocks
   // (markdown-it-source-map only annotates top-level *_open tokens, so a target
@@ -205,16 +238,19 @@
     prevPage: function (mode) { return api.goToPage(currentPage - pageStep(mode)); },
     nextPage: function (mode) { return api.goToPage(currentPage + pageStep(mode)); },
     lastPage: function () { refreshPages(); return api.goToPage(pages.length); },
-    setViewMode: function (mode) {
-      refreshPages();
-      currentViewMode = mode || 'two-column';
-      document.body.classList.remove('view-single', 'view-spread', 'view-two-column');
-      if (mode) document.body.classList.add('view-' + mode);
-      scrollToCurrentPage();
-      return api.notifyPageChange();
+    setViewMode: function (mode, silent) {
+      preserveViewport(function () {
+        currentViewMode = mode || 'two-column';
+        document.body.classList.remove('view-single', 'view-spread', 'view-two-column');
+        if (mode) document.body.classList.add('view-' + mode);
+      });
+      if (!silent) return api.notifyPageChange();
     },
-    setZoom: function (z) {
-      document.documentElement.style.setProperty('--gutterpress-zoom', z);
+    setZoom: function (z, silent) {
+      preserveViewport(function () {
+        document.documentElement.style.setProperty('--gutterpress-zoom', z);
+      });
+      if (!silent) api.notifyPageChange();
     },
     toggleDebugMode: function () {
       debugMode = !debugMode;
@@ -237,13 +273,23 @@
     refresh: function () {
       refreshPages();
       currentPage = detectVisiblePage();
+      recordVisibleSource();
       return api.notifyPageChange();
     },
 
     // ── ADR 0005 generic primitives ─────────────────────────────────────────
     // Bumped whenever a command/event is added so a hot-updated SPA can
     // feature-detect against an older bundled lib.
-    getProtocolVersion: function () { return 2; },
+    getProtocolVersion: function () { return 3; },
+
+    // Publish any debounced reader movement before a host atomically replaces
+    // this frame. `silent` lets the shell relay the returned event itself so a
+    // queued postMessage from the outgoing frame cannot arrive after the swap.
+    flushScroll: function (silent) {
+      if (scrollTimer) clearTimeout(scrollTimer);
+      scrollTimer = null;
+      return publishScrollPosition(true, silent === true);
+    },
 
     // Heading tree with page + source line — powers chapter jump (UX-013), TOC,
     // minimap, scrollspy. Page math needs same-origin paged.js access, so it
@@ -313,6 +359,7 @@
       }
       var page = pageIndexOf(el);
       if (page) currentPage = page;
+      if (!opts.smooth) recordVisibleSource();
       return { page: page || currentPage, sourceLine: lineOf(el) };
     },
 
@@ -369,6 +416,7 @@
       if (spec.scroll && els[0]) {
         ignoreScrollUntil = Date.now() + 350;
         els[0].scrollIntoView({ behavior: 'instant', block: 'center', inline: 'nearest' });
+        recordVisibleSource();
       }
       if (spec.transient && els.length) {
         setTimeout(function () {
@@ -458,28 +506,38 @@
 
   // Scroll tracking
   var scrollTimer = null;
-  var lastSourceLine = -1;
-  window.addEventListener('scroll', function () {
+  function publishScrollPosition(force, silent) {
+    scrollTimer = null;
+    var remainingGuard = ignoreScrollUntil - Date.now();
+    if (!force && remainingGuard > 0) {
+      scrollTimer = setTimeout(publishScrollPosition, remainingGuard);
+      return null;
+    }
     if (pages.length === 0) refreshPages();
-    if (pages.length === 0) return;
-    if (scrollTimer) clearTimeout(scrollTimer);
-    scrollTimer = setTimeout(function () {
-      if (Date.now() < ignoreScrollUntil) return;
-      var page = detectVisiblePage();
-      if (page !== currentPage) {
-        currentPage = page;
-        api.notifyPageChange();
-      }
-      // Emit finer-grained source position for editor sync (ADR 0005).
-      var pos = visibleSourcePosition();
-      var sl = pos ? pos.line : null;
-      if (sl != null && sl !== lastSourceLine) {
-        lastSourceLine = sl;
-        window.dispatchEvent(new CustomEvent('sourceLineChanged', {
-          detail: { sourceLine: sl, chapter: chapterOf(pos.el), page: pageIndexOf(pos.el) }
-        }));
+    if (pages.length === 0) return null;
+    var page = detectVisiblePage();
+    if (page !== currentPage) {
+      currentPage = page;
+      if (!silent) api.notifyPageChange();
+    }
+    // Emit finer-grained source position for editor sync (ADR 0005).
+    var pos = visibleSourcePosition();
+    var sl = pos ? pos.line : null;
+    var chapter = pos ? chapterOf(pos.el) : null;
+    if (sl != null && (sl !== lastSourceLine || chapter !== lastSourceChapter)) {
+      lastSourceLine = sl;
+      lastSourceChapter = chapter;
+      var detail = { sourceLine: sl, chapter: chapter, page: pageIndexOf(pos.el) };
+      if (!silent) {
+        window.dispatchEvent(new CustomEvent('sourceLineChanged', { detail: detail }));
       }
-    }, 150);
+      return detail;
+    }
+    return null;
+  }
+  window.addEventListener('scroll', function () {
+    if (scrollTimer) clearTimeout(scrollTimer);
+    scrollTimer = setTimeout(publishScrollPosition, 150);
   });
 
   // Paged.js calls this when rendering is complete
@@ -490,7 +548,8 @@
     pageObserver.disconnect();
     currentPage = 1;
     ignoreScrollUntil = Date.now() + 300;
-    window.scrollTo(0, 0);
+    window.scrollTo({ top: 0, left: 0, behavior: 'instant' });
+    recordVisibleSource();
     console.log('Paged.js rendered ' + pages.length + ' pages');
     api.notifyRenderingComplete();
     setTimeout(api.notifyPageChange, 0);

package/dist/{plugin-xskq3dtx.js → plugin-ees6nhkc.js}

@@ -1,14 +1,14 @@
 import {
   addNpmPlugin,
   parseNpmPluginSpec
-} from "./cli-yp0d2hp8.js";
-import"./cli-v2dze8ja.js";
+} from "./cli-k4bd06sd.js";
+import"./cli-najycadg.js";
 import {
   EXIT_CODES,
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-rkqxbnkq.js";
+} from "./cli-e5zhb0xs.js";
 import"./cli-yzrh708h.js";
 import"./cli-wchtvxvw.js";
 import"./cli-yja077f6.js";

package/dist/{preflight-epcffags.js → preflight-1q6c2edh.js}

@@ -2,16 +2,16 @@ import {
   executeValidation,
   publishTargetFor,
   reportMissingTools
-} from "./cli-yp0d2hp8.js";
+} from "./cli-k4bd06sd.js";
 import {
   log
-} from "./cli-v2dze8ja.js";
+} from "./cli-najycadg.js";
 import {
   EXIT_CODES,
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-rkqxbnkq.js";
+} from "./cli-e5zhb0xs.js";
 import"./cli-yzrh708h.js";
 import"./cli-wchtvxvw.js";
 import"./cli-yja077f6.js";

package/dist/preview/file-watcher.d.ts

@@ -8,9 +8,9 @@ import { type FSWatcher } from 'chokidar';
 import type { ServerState } from './server-context';
 import type { ResolvedPluginConfig } from '../schema/manifest.types';
 /**
- * Whether the double-buffered preview shell is active. The historical env name
- * is retained because users may already set it; chapter splicing is gone and
- * every source change now performs a full-document pagination.
+ * Whether the incremental preview shell is active. The historical env name is
+ * retained because users may already set it. A single Markdown edit paginates
+ * only that source file; geometry-wide changes still swap a full document.
  */
 export declare function incrementalPreviewEnabled(): boolean;
 /**
@@ -28,21 +28,12 @@ export declare function incrementalPreviewEnabled(): boolean;
  *          serving it from a stable disk path lets the OS file-cache
  *          and Defender hash-cache stay warm across sessions.
  *
- * PAGINATION FIDELITY: this injects NO page-break rule. It used to add
- * `<style>.gutterpress-chapter{break-before:page}</style>` whenever the incremental
- * preview was on (i.e. by default), which started EVERY source file on a new
- * page in the live view. `gutterpress build` emits no such rule — assembleBookHtml
- * in lib/markdown/assemble.ts concatenates source files flat into <body> and
- * breaks only where project CSS or a markdown-it-paged marker says to — so any
- * project that splits one chapter across several source files previewed with
- * different page boundaries than the PDF it built. Preview and build now take
- * their breaks from exactly the same rules.
- *
- * Chapter identity is attached to existing source-mapped blocks. No wrapper or
- * preview-only CSS is emitted, so selectors see exactly the same document tree
- * as the build.
+ * With `pageIsolateChapters`, each source wrapper starts on a fresh page. This
+ * is the v0.8.3 incremental-preview invariant: a standalone source render owns
+ * the same page boundary as that source in the live preview and can be spliced
+ * without paginating the full document.
  */
-export declare function injectPreviewScripts(html: string): string;
+export declare function injectPreviewScripts(html: string, pageIsolateChapters: boolean): string;
 /**
  * Generate HTML from markdown and write book.html to the temp directory.
  * The desktop's iframe loads `book.html` via a relative URL — same name in
@@ -65,6 +56,37 @@ export declare function generateAndWriteHtml(inputPath: string, tempDir: string,
     };
     plugins?: ResolvedPluginConfig[];
 }, cssAssets: Map<string, string>): Promise<void>;
+/**
+ * Render one source file with the same CSS, plugins, source metadata, and
+ * preview scripts as the full book. The shell paginates this small document in
+ * a hidden iframe and replaces only the edited source file's pages.
+ */
+export declare function renderChapterPreviewHtml(inputPath: string, file: string, config: {
+    title?: string;
+    styles?: string[];
+    plugins?: ResolvedPluginConfig[];
+}): Promise<string>;
+/** One changed project file, named for the preview broadcast decision. */
+export interface ChangedFile {
+    relativePath: string;
+    ext: string;
+    event: string;
+}
+/**
+ * Describe in-project changes using the same canonical path form emitted in
+ * `data-chapter-src`. Declared external dependencies intentionally drop out;
+ * their presence in the original change count forces a full reload.
+ */
+export declare function describeChanges(changes: [filePath: string, event: string][], inputResolved: string): ChangedFile[];
+export type BroadcastDecision = {
+    kind: 'chapter-splice';
+    chapterId: string;
+    relativePath: string;
+} | {
+    kind: 'full-reload';
+};
+/** A single surviving Markdown edit can be paginated independently. */
+export declare function decideBroadcast(files: ChangedFile[], changeCount: number, incremental: boolean): BroadcastDecision;
 /**
  * Chokidar 5's `ignored` matcher (regex or function) is tested against the
  * fully-qualified, forward-slash-normalized ABSOLUTE path — never a path

package/dist/preview/http-server.d.ts

@@ -17,10 +17,13 @@ export interface PreviewServer {
     /** Stop the server and close all connections. */
     close(): Promise<void>;
     /**
-     * Broadcast a `{ type: "full-reload" }` message to every connected HMR
-     * client. Safe to call after `close()` (no-op).
+     * Advance the rendered revision and notify every connected HMR client.
+     * Disconnected clients reconcile to the latest revision when they reconnect.
+     * Safe to call after `close()` (no-op).
      */
     broadcastReload(): void;
+    /** Paginate and replace one edited Markdown source in connected shells. */
+    broadcastContentUpdate(file: string): void;
 }
 export declare function isPortAvailable(port: number, host?: string): Promise<boolean>;
 /**

package/dist/preview/server-context.d.ts

@@ -19,6 +19,8 @@ export interface ServerState {
     isRebuilding: boolean;
     /** Active rebuild, awaited before a project restart closes its watcher. */
     rebuildPromise?: Promise<void> | null;
+    /** Bypass watcher settling for a host write that has already completed. */
+    notifySettledWrite?: ((filePath: string, writtenContent: string) => void) | null;
     /** node:http + `ws` preview HTTP/WebSocket server instance */
     previewServer: PreviewServer | null;
     /** Is server shutting down? (prevents multiple shutdown calls) */