gutterpress 0.0.0 → 0.9.0-alpha.2

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-wf2cbmwc.js → plugin-ees6nhkc.js}

@@ -1,16 +1,16 @@
 import {
   addNpmPlugin,
   parseNpmPluginSpec
-} from "./cli-7ykx7pp0.js";
-import"./cli-h7phg3ka.js";
+} from "./cli-k4bd06sd.js";
+import"./cli-najycadg.js";
 import {
   EXIT_CODES,
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-hvqjs342.js";
-import"./cli-5bxx0c4y.js";
-import"./cli-1tyj4bk3.js";
+} from "./cli-e5zhb0xs.js";
+import"./cli-yzrh708h.js";
+import"./cli-wchtvxvw.js";
 import"./cli-yja077f6.js";
 import"./cli-37x76zdn.js";
 

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

@@ -1,18 +1,19 @@
 import {
   executeValidation,
+  publishTargetFor,
   reportMissingTools
-} from "./cli-7ykx7pp0.js";
+} from "./cli-k4bd06sd.js";
 import {
   log
-} from "./cli-h7phg3ka.js";
+} from "./cli-najycadg.js";
 import {
   EXIT_CODES,
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-hvqjs342.js";
-import"./cli-5bxx0c4y.js";
-import"./cli-1tyj4bk3.js";
+} from "./cli-e5zhb0xs.js";
+import"./cli-yzrh708h.js";
+import"./cli-wchtvxvw.js";
 import"./cli-yja077f6.js";
 import"./cli-37x76zdn.js";
 
@@ -35,25 +36,19 @@ function severityRank(severity) {
   return 2;
 }
 function buildRequiredChecks(execution) {
-  if (execution.profile !== "dtrpg")
-    return [];
-  const requiredIds = [
-    "pdf.structure.qpdf",
-    "pdf.print.pdfx-markers",
-    "pdf.print.pdfx-metadata",
-    "pdf.print.embedded-fonts"
-  ];
   const skipped = new Set(execution.tools.skippedChecks);
-  const failed = new Set(execution.report.errors.map((item) => item.checkId));
   const passed = new Set(execution.report.passed);
-  return requiredIds.map((id) => {
-    if (skipped.has(id))
-      return { id, status: "skipped" };
-    if (failed.has(id))
-      return { id, status: "fail" };
-    if (passed.has(id))
-      return { id, status: "pass" };
-    return { id, status: "fail" };
+  return execution.targets.flatMap((targetId) => {
+    const failed = new Set(execution.report.errors.filter((item) => item.target === undefined || item.target === targetId).map((item) => item.checkId));
+    return publishTargetFor(targetId).requiredChecks.map((id) => {
+      if (skipped.has(id))
+        return { target: targetId, id, status: "skipped" };
+      if (failed.has(id))
+        return { target: targetId, id, status: "fail" };
+      if (passed.has(id))
+        return { target: targetId, id, status: "pass" };
+      return { target: targetId, id, status: "fail" };
+    });
   });
 }
 function buildPreflightPayload(execution) {
@@ -85,8 +80,8 @@ function buildPreflightPayload(execution) {
   const requiredChecks = buildRequiredChecks(execution);
   const skippedRequired = requiredChecks.some((check) => check.status === "skipped");
   return {
-    schemaVersion: 1,
-    profile: execution.profile ?? null,
+    schemaVersion: 2,
+    targets: [...execution.targets],
     status: computeStatus(execution.report.summary.errors, execution.report.summary.warnings, execution.tools.missing.length, skippedRequired),
     pdf: execution.context.pdfPath ?? "",
     summary: { ...execution.report.summary },
@@ -103,7 +98,7 @@ function toPreflightMarkdown(payload) {
   lines.push("# gutterpress preflight");
   lines.push("");
   lines.push(`- Status: **${payload.status}**`);
-  lines.push(`- Profile: ${payload.profile ?? "none"}`);
+  lines.push(`- Targets: ${payload.targets.length > 0 ? payload.targets.join(", ") : "none"}`);
   lines.push(`- PDF: ${payload.pdf}`);
   lines.push(`- Summary: ${payload.summary.errors} error(s), ${payload.summary.warnings} warning(s), ${payload.summary.passed}/${payload.summary.total} checks passed`);
   if (payload.tools.missing.length > 0) {
@@ -117,7 +112,7 @@ function toPreflightMarkdown(payload) {
     lines.push("");
     lines.push("## Required Checks");
     for (const check of payload.requiredChecks) {
-      lines.push(`- ${check.id}: ${check.status}`);
+      lines.push(`- [${check.target}] ${check.id}: ${check.status}`);
     }
   }
   if (payload.issues.length > 0) {
@@ -155,9 +150,9 @@ var preflightArgs = {
     type: "string",
     description: "Path to manifest.yaml"
   },
-  profile: {
+  target: {
     type: "string",
-    description: "Validation profile lock (currently: dtrpg)"
+    description: "Publish targets to preflight against (comma-separated, e.g. dtrpg,itch), overriding the manifest's `targets:`"
   },
   "report-dir": {
     type: "string",
@@ -187,7 +182,7 @@ var preflight_default = defineCommand({
         pdf: typeof args.pdf === "string" ? args.pdf : undefined,
         input,
         phase: "post-build",
-        profile: typeof args.profile === "string" ? args.profile : undefined
+        target: typeof args.target === "string" ? args.target : undefined
       });
     } catch (error) {
       log.error(error instanceof Error ? error.message : String(error));

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

@@ -8,31 +8,11 @@ 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;
-/**
- * Shared preview render path. renderChapters() does all Markdown, CSS, and
- * Paged.js-slot work.
- *
- * Named `renderPreviewBook` (ARCH finding #53) to distinguish it from
- * build-runner.ts's `renderBook` — same name, different module, and a
- * genuinely different contract: this one is degrade-and-report (a plugin the
- * author enabled but hasn't installed yet is skipped with a loud warning so
- * the rest of the live preview still renders); build-runner.ts's is
- * fail-fast, because a final artifact must never silently drop a plugin.
- * Both preambles now share {@link loadPluginsWithCss}.
- */
-export declare function renderPreviewBook(inputPath: string, config: {
-    title?: string;
-    styles?: string[];
-    plugins?: ResolvedPluginConfig[];
-}, opts: {
-    files: string[] | null;
-    wrapChapters: boolean;
-}): Promise<string>;
 /**
  * Rewrite rendered book HTML for the live preview. Injects, in order:
  *   1. pagedjs-interface.js — defines window.previewAPI for in-iframe controls
@@ -48,21 +28,12 @@ export declare function renderPreviewBook(inputPath: string, config: {
  *          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
@@ -70,6 +41,12 @@ export declare function injectPreviewScripts(html: string): string;
  *
  * Empty `inputPath` writes a static placeholder — the desktop app (packages/desktop)
  * supplies a real path via its own folder picker.
+ *
+ * `cssAssets` is REQUIRED, not optional: it is the map the HTTP server resolves
+ * the inliner's rewritten asset URLs against (see {@link ServerState.cssAssets}),
+ * so a caller that skipped it would render a book.html whose shared-art URLs
+ * 404 — the exact bug this parameter exists to fix, reintroduced silently.
+ * Every render replaces its contents.
  */
 export declare function generateAndWriteHtml(inputPath: string, tempDir: string, config: {
     title?: string;
@@ -78,7 +55,38 @@ export declare function generateAndWriteHtml(inputPath: string, tempDir: string,
         files?: string[] | null;
     };
     plugins?: ResolvedPluginConfig[];
-}): Promise<void>;
+}, 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
@@ -102,7 +110,8 @@ export declare function isDotPathUnderRoot(candidatePath: string, root: string):
  * Whether the watcher should ignore a path.
  *
  * IN-PROJECT paths get the dotfile rule ({@link isDotPathUnderRoot}) — a
- * project's own `.git/`, `.DS_Store`, editor swap files, and so on are noise.
+ * project's own `.git/`, `.DS_Store`, editor swap files, and so on are noise —
+ * plus the generated/vendored-subtree rule ({@link isGeneratedProjectPath}).
  *
  * A path OUTSIDE the project is only ever seen because it is a DECLARED
  * external dependency the manifest named explicitly (see

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) */
@@ -29,6 +31,28 @@ export interface ServerState {
     config: ResolvedConfig;
     /** Server options */
     options: PreviewServerOptions;
+    /**
+     * Files the inlined CSS references but could not embed, as
+     * `book.html`-relative URL path → absolute source path.
+     *
+     * `asset-inline.ts` embeds fonts and images up to
+     * `IMAGE_INLINE_MAX_BYTES`; anything larger keeps its project-relative path
+     * (if it lives in the book) or becomes `assets/<contentHash><ext>` (if it
+     * does not — e.g. art referenced from a repo-root shared stylesheet, the
+     * normative multi-book layout). Either way the inliner returns a COPY PLAN,
+     * which the build executes into its output dir.
+     *
+     * The preview serves the project in place and has no output dir, so a
+     * rewritten `assets/<hash>` URL had nothing behind it and shared art
+     * rendered broken in the live preview while building correctly. Keeping the
+     * plan here lets the server resolve those URLs straight from their real
+     * location — same URL as the build, still nothing copied.
+     *
+     * Rebuilt from scratch on every render, so a stylesheet edit that drops an
+     * image drops its URL too. Exact-match lookups only: never a path-traversal
+     * surface.
+     */
+    cssAssets: Map<string, string>;
 }
 /**
  * Create initial server state