gutterpress 0.9.0-alpha.2 → 0.10.0-alpha.3

package/dist/lib/remote-auth/sync-types.d.ts

@@ -15,25 +15,28 @@ import type { HostCredential, TokenStore } from "./token-store.ts";
  * the root cause of the 0.5.0 "sync uses 2 GB" report.
  */
 export type GitCache = Record<string, unknown>;
-/** How one conflicted file differs between the two copies. */
-export type ConflictKind = 
-/** Edited in both copies. */
-"both-edited"
-/** The author deleted it; the online copy edited it. */
- | "you-deleted"
-/** The online copy deleted it; the author edited it. */
- | "online-deleted";
-/** One file that changed in both the local and the online copy. */
-export interface ConflictFile {
-    path: string;
-    kind: ConflictKind;
-}
-/** Author's per-file decision for a conflicted file (ADR 0006 D5). */
-export interface ConflictResolution {
+/**
+ * One image file that changed on both sides. Sync already converged (the
+ * NEWER side's bytes are on disk and committed — the safe default); this
+ * record lets a host offer a non-blocking side-by-side picker afterwards.
+ * Both blob oids are pinned by the merge commit's two parents, so the picker
+ * can never go stale.
+ */
+export interface ImageClash {
+    /** Repo-relative path of the image. */
     path: string;
-    choice: "mine" | "theirs" | "both";
+    /** Blob oid of the local version. */
+    localOid: string;
+    /** Blob oid of the online version. */
+    remoteOid: string;
+    /** Which side the automatic newer-wins policy kept on disk. */
+    kept: "local" | "online";
 }
-/** Outcome of a sync (or conflict-resolution) attempt. */
+/** Outcome of a sync attempt. Sync always converges — there is no "conflict"
+ *  arm: overlapping text edits land in the file inside standard git conflict
+ *  markers (`combinedFiles`), clashing binaries keep the newer side
+ *  (`imageClashes` for images), and the other version is always reachable in
+ *  history. Owner ruling 2026-08-14. */
 export type SyncOutcome = {
     status: "synced";
     message: string;
@@ -43,20 +46,15 @@ export type SyncOutcome = {
     mergedRemoteChanges: boolean;
     /** True when pulling online changes changed the local working tree. */
     filesChanged?: boolean;
+    /** Files whose text now holds BOTH versions inside git conflict markers. */
+    combinedFiles?: string[];
+    /** Clashing images (newer kept) for the host's non-blocking picker. */
+    imageClashes?: ImageClash[];
 } | {
     status: "up-to-date";
     message: string;
     snapshotId?: string;
     filesChanged?: boolean;
-} | {
-    status: "conflict";
-    message: string;
-    files: ConflictFile[];
-    /** Local branch tip the conflict was computed against. */
-    localId: string;
-    /** Online tip the conflict was computed against. */
-    remoteId: string;
-    snapshotId?: string;
 } | {
     status: "auth";
     message: string;
@@ -71,11 +69,11 @@ export type SyncOutcome = {
     status: "error";
     message: string;
     /**
-     * Stable machine-readable signal for the small set of known "the project
-     * isn't set up right" failures (no remote / SSH remote / no named
-     * branch) — set by conflict-resolution.ts's setupErrorMessage() check.
-     * Lets a host UI route to its connect/setup surface without
-     * string-matching `message` (which stays free to reword).
+     * Stable machine-readable signal so a host UI can route without
+     * string-matching `message` (which stays free to reword):
+     * "needs-connection-setup" — the project isn't set up right (no
+     * remote / SSH remote / no named branch); route to the connect/setup
+     * surface.
      */
     code?: "needs-connection-setup";
     snapshotId?: string;
@@ -83,9 +81,8 @@ export type SyncOutcome = {
 };
 /**
  * Outcome of a pull-only attempt ({@link pullChanges}): fetch + fast-forward/
- * merge of the online changes, NEVER a push. Conflict semantics are identical
- * to {@link syncProject} (abortOnConflict — the working tree is never left
- * with conflict markers).
+ * converge-merge of the online changes, NEVER a push. The merge always lands
+ * (see converge-merge.ts) — there is no "conflict" arm.
  */
 export type PullOutcome = {
     status: "pulled";
@@ -102,17 +99,14 @@ export type PullOutcome = {
      * from before) — the host should refresh its preview.
      */
     filesChanged: boolean;
+    /** Files whose text now holds BOTH versions inside git conflict markers. */
+    combinedFiles?: string[];
+    /** Clashing images (newer kept) for the host's non-blocking picker. */
+    imageClashes?: ImageClash[];
 } | {
     status: "up-to-date";
     message: string;
     snapshotId?: string;
-} | {
-    status: "conflict";
-    message: string;
-    files: ConflictFile[];
-    localId: string;
-    remoteId: string;
-    snapshotId?: string;
 } | {
     status: "auth";
     message: string;
@@ -193,28 +187,6 @@ export interface SyncRetryOptions {
     /** Injectable delay (tests only); defaults to a real timer. */
     sleep?: (ms: number) => Promise<void>;
 }
-export interface ResolveConflictsOptions {
-    projectDir: string;
-    resolutions: ConflictResolution[];
-    /** The `localId` from the conflict outcome. */
-    localId: string;
-    /** The `remoteId` from the conflict outcome. */
-    remoteId: string;
-    credential?: HostCredential;
-    tokenStore?: TokenStore;
-    authorName?: string;
-    authorEmail?: string;
-    httpClient?: typeof httpNode;
-    /**
-     * When true, the merge is allowed to combine two commits that share no
-     * common ancestor (unrelated histories). Set by the unrelated-histories
-     * recovery path; regular merge conflicts leave this false (the local and
-     * remote share a common base, so `allowUnrelatedHistories` is unnecessary).
-     */
-    allowUnrelatedHistories?: boolean;
-    /** Optional log file for debugging conflict resolution steps. */
-    logFile?: string;
-}
 /** Resolved project remote + credential used by every transport call. */
 export interface RemoteTransport {
     remote: string;

package/dist/lib/remote-auth/sync.d.ts

@@ -1,30 +1,23 @@
-import { conflictFilesFrom, onAuthFor } from "./transport.ts";
+import { onAuthFor } from "./transport.ts";
 import type { PullOutcome, PushOutcome, SyncOutcome, SyncProjectOptions } from "./sync-types.ts";
-export { onAuthFor, conflictFilesFrom };
-export { onlineCopyPath, resolveConflicts } from "./conflict-resolution.ts";
+export { onAuthFor };
 export { SYNC_SNAPSHOT_MESSAGE } from "./sync-messages.ts";
-export type { ConflictFile, ConflictKind, ConflictResolution, PullOutcome, PushOutcome, ResolveConflictsOptions, SyncOutcome, SyncProjectOptions, } from "./sync-types.ts";
+export type { ImageClash, PullOutcome, PushOutcome, SyncOutcome, SyncProjectOptions, } from "./sync-types.ts";
 /**
  * Snapshot-first sync (ADR 0006 D5) — the composition of {@link pullChanges}
  * then {@link pushChanges}. If someone pushes between our pull and our push,
- * the push reports pull-first and the pair re-runs (their commits merge in on
- * the next pass), with a short backoff between passes. The loop is ALWAYS
- * bounded by `retry.attempts` (BUG 6 — a fast-moving remote no longer triggers
- * a FALSE race message after only two attempts); a remote that genuinely races
- * every pass surfaces a friendly "try again" rather than looping forever. The
- * snapshot-first guarantee holds on every path (the work is saved locally
- * before any network step). Never throws for expected outcomes — everything is
- * reported through the {@link SyncOutcome} union.
+ * the push reports pull-first and the pair re-runs (their commits converge in
+ * on the next pass), with a short backoff between passes. The loop is ALWAYS
+ * bounded by `retry.attempts`; a remote that races every pass surfaces a
+ * friendly "try again in a moment" rather than looping forever. Never throws
+ * for expected outcomes — everything is reported through {@link SyncOutcome}.
  */
 export declare function syncProject(options: SyncProjectOptions): Promise<SyncOutcome>;
 /**
  * Pull-only operation (the History tab's "Pull"): snapshot-if-needed →
- * fetch → fast-forward or clean merge of the online changes — NEVER a push.
- *
- * Same conflict semantics as {@link syncProject}: `abortOnConflict` keeps the
- * working tree completely untouched and the conflict comes back as
- * `{ status: "conflict", files }` for the per-file choices dialog. Serialized
- * on the per-repo lock; one function-scoped object cache, released on return.
+ * fetch → fast-forward or CONVERGE-merge of the online changes — NEVER a
+ * push, never a question. Serialized on the per-repo lock; one
+ * function-scoped object cache, released on return.
  */
 export declare function pullChanges(options: SyncProjectOptions): Promise<PullOutcome>;
 /**

package/dist/lib/remote-auth/transport.d.ts

@@ -1,6 +1,7 @@
 import httpNode from "isomorphic-git/http/node";
 import { type HostCredential, type TokenStore } from "./token-store.ts";
-import type { ConflictFile, GitCache, RemoteTransport } from "./sync-types.ts";
+import type { OperationLogger } from "./operation-log.ts";
+import type { GitCache, RemoteTransport } from "./sync-types.ts";
 /**
  * The git repo directory for a project dir. A project IS its git repo, so this
  * walks up to the enclosing repo root (opening a subfolder syncs the whole
@@ -47,12 +48,6 @@ export declare function failureOutcome(e: unknown, snapshotId?: string): {
     message: string;
     snapshotId?: string;
 };
-export declare function conflictFilesFrom(data: {
-    filepaths: string[];
-    bothModified: string[];
-    deleteByUs: string[];
-    deleteByTheirs: string[];
-}): ConflictFile[];
 /** Friendly setup-problem message for the expected gate errors, else null. */
 export declare function setupErrorMessage(e: unknown): string | null;
 /**
@@ -70,6 +65,18 @@ export declare function snapshotBeforeAction(args: {
     authorEmail?: string;
     cache: GitCache;
 }): Promise<string | undefined>;
+/**
+ * Structural preflight — never touch the tree of a damaged repo. An interrupted
+ * merge/rebase/cherry-pick, detached HEAD, stale lock, or missing `.git` must be
+ * REPAIRED before any sync work: snapshot-first would otherwise commit whatever
+ * is on disk (e.g. the literal conflict markers a half-done native-git merge
+ * leaves in tracked files) and push it to every collaborator. Throwing the
+ * typed error routes the caller through the recover() path.
+ * `checkLocalChanges: false` — only the structural flags matter here.
+ *
+ * Runs INSIDE the caller's repo lock. Shared by pullChanges and pushChanges.
+ */
+export declare function assertNoStructuralDamage(projectDir: string, logger: OperationLogger): Promise<void>;
 export declare function currentBranchOrThrow(dir: string): Promise<string>;
 /**
  * Run `fn` (a fetch that moves remote-tracking refs) with a rollback guard

package/dist/lib/theme-import.d.ts

@@ -29,11 +29,10 @@ export declare function locateThemeRoot(names: string[]): string | null;
 /**
  * Split print-safety findings into the one that REJECTS the import (a CSS
  * syntax/parse failure — the stylesheet is unusable) vs. WARN findings the
- * author should still see (remote URLs, risky print effects, paged.js crash
- * selectors) that import anyway. The discriminator is the rule id, not
- * severity: `no-remote-urls`/`no-pagedjs-crash-selectors` are `error`-severity
- * but the #106 spec still imports them with a warning; only `syntax-error`
- * refuses.
+ * author should still see (remote URLs, risky print effects) that import
+ * anyway. The discriminator is the rule id, not severity: `no-remote-urls` is
+ * `error`-severity but the #106 spec still imports it with a warning; only
+ * `syntax-error` refuses.
  */
 export declare function classifyThemeCssFindings(findings: PrintSafeWarning[]): {
     reject: PrintSafeWarning | null;

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

@@ -1,19 +1,22 @@
 import {
   MANIFEST_FILENAMES,
   runLint
-} from "./cli-k4bd06sd.js";
+} from "./cli-5czby0dd.js";
 import {
   log
-} from "./cli-najycadg.js";
+} from "./cli-gk3wsdpb.js";
 import {
-  EXIT_CODES,
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-e5zhb0xs.js";
-import"./cli-yzrh708h.js";
-import"./cli-wchtvxvw.js";
-import"./cli-yja077f6.js";
+} from "./cli-f4rcbt2t.js";
+import"./cli-yp3p0sf2.js";
+import"./cli-c41yr7he.js";
+import {
+  EXIT_CODES
+} from "./cli-46ycxe6r.js";
+import"./cli-k1065rkg.js";
+import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 
 // src/commands/lint.ts

package/dist/{manifest.schema-z61rzw44.json → manifest.schema-zxgxnbg7.json}

@@ -29,6 +29,27 @@
       "enum": ["dtrpg", "book", "custom"],
       "examples": ["dtrpg", "book", "custom"]
     },
+    "engine": {
+      "type": "string",
+      "description": "Pagination engine. Paged.js has been removed — the Gutterpress engine (native Chromium pagination) is the only engine, and \"native\" is the only meaningful value. \"paged\" is accepted for backward-compatible manifest parsing only: it produces a one-line warning and the build proceeds natively regardless. `--engine` on the CLI is likewise an accepted-but-ignored no-op.",
+      "enum": ["paged", "native"],
+      "default": "native",
+      "examples": ["native"]
+    },
+    "engineStyles": {
+      "type": "object",
+      "description": "Engine-conditional stylesheets, appended AFTER `styles`. `.native` is the only list that still applies; `.paged` is accepted-but-ignored (a warning fires if it has entries) now that Paged.js has been removed.",
+      "properties": {
+        "paged": {
+          "type": "array",
+          "description": "REMOVED — Paged.js has been deleted. Accepted for backward-compatible manifest parsing only; entries here are ignored with a warning.",
+          "items": { "type": "string" }
+        },
+        "native": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false,
+      "examples": [{ "native": ["css/native-furniture.css"] }]
+    },
     "targets": {
       "type": "array",
       "description": "Where the book is published (ADR 0008): publish targets whose requirements `gutterpress validate` checks the built PDF against — each target is validated separately, so one book can target several destinations. Omitting it uses the preset's default (dtrpg -> [\"dtrpg\"]; book/custom -> []).",

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

@@ -5,20 +5,24 @@ import {
   TARGETS,
   TARGET_IDS,
   scaffoldProject
-} from "./cli-k4bd06sd.js";
+} from "./cli-5czby0dd.js";
 import {
-  isToolAvailable,
   resolveGhostscript
-} from "./cli-najycadg.js";
+} from "./cli-gk3wsdpb.js";
 import {
-  EXIT_CODES,
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-e5zhb0xs.js";
-import"./cli-yzrh708h.js";
-import"./cli-wchtvxvw.js";
-import"./cli-yja077f6.js";
+} from "./cli-f4rcbt2t.js";
+import"./cli-yp3p0sf2.js";
+import {
+  isToolAvailable
+} from "./cli-c41yr7he.js";
+import {
+  EXIT_CODES
+} from "./cli-46ycxe6r.js";
+import"./cli-k1065rkg.js";
+import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 
 // src/commands/new.ts

package/dist/{plugin-ees6nhkc.js → plugin-129wcs93.js}

@@ -1,17 +1,20 @@
 import {
   addNpmPlugin,
   parseNpmPluginSpec
-} from "./cli-k4bd06sd.js";
-import"./cli-najycadg.js";
+} from "./cli-5czby0dd.js";
+import"./cli-gk3wsdpb.js";
 import {
-  EXIT_CODES,
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-e5zhb0xs.js";
-import"./cli-yzrh708h.js";
-import"./cli-wchtvxvw.js";
-import"./cli-yja077f6.js";
+} from "./cli-f4rcbt2t.js";
+import"./cli-yp3p0sf2.js";
+import"./cli-c41yr7he.js";
+import {
+  EXIT_CODES
+} from "./cli-46ycxe6r.js";
+import"./cli-k1065rkg.js";
+import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 
 // src/commands/plugin.ts

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

@@ -2,19 +2,22 @@ import {
   executeValidation,
   publishTargetFor,
   reportMissingTools
-} from "./cli-k4bd06sd.js";
+} from "./cli-5czby0dd.js";
 import {
   log
-} from "./cli-najycadg.js";
+} from "./cli-gk3wsdpb.js";
 import {
-  EXIT_CODES,
   UsageError,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-e5zhb0xs.js";
-import"./cli-yzrh708h.js";
-import"./cli-wchtvxvw.js";
-import"./cli-yja077f6.js";
+} from "./cli-f4rcbt2t.js";
+import"./cli-yp3p0sf2.js";
+import"./cli-c41yr7he.js";
+import {
+  EXIT_CODES
+} from "./cli-46ycxe6r.js";
+import"./cli-k1065rkg.js";
+import"./cli-v5mp7a6q.js";
 import"./cli-37x76zdn.js";
 
 // src/commands/preflight.ts

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

@@ -14,24 +14,20 @@ import type { ResolvedPluginConfig } from '../schema/manifest.types';
  */
 export declare function incrementalPreviewEnabled(): boolean;
 /**
- * Rewrite rendered book HTML for the live preview. Injects, in order:
- *   1. pagedjs-interface.js — defines window.previewAPI for in-iframe controls
- *   2. pagedjs-bridge.js    — postMessage bridge for cross-origin toolbar (desktop)
- *   3. BREAK_INSIDE_HANDLER — polyfill for break-inside: avoid
- *   4. Paged.js polyfill itself, served directly from the process-wide
- *      embedded-assets dir by the HTTP server (see http-server.ts route
- *      for /vendor/*). We no longer copy it into the per-project tempDir
- *      because:
- *        - The polyfill is 904 KB and copying it per open is wasted IO
- *          (one of the worst-case Defender scan targets on Windows).
- *        - The per-process extracted copy is identical across opens so
- *          serving it from a stable disk path lets the OS file-cache
- *          and Defender hash-cache stay warm across sessions.
+ * Rewrite rendered book HTML for the live preview: inject the Gutterpress
+ * engine's viewer bundle (`/engine/gutterpress-viewer.js`, embedded the same
+ * way as every other preview asset — see lib/embedded-assets.ts) PLUS the
+ * preview-interface.js/preview-bridge.js pair, before `</head>`.
+ * preview-interface.js defines `window.previewAPI` for in-iframe controls;
+ * preview-bridge.js is the postMessage bridge for the cross-origin desktop
+ * toolbar — together they make the desktop's whole
+ * `gutterpress:cmd/reply/event` command protocol work.
  *
- * 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.
+ * `pageIsolateChapters` is reserved for the one-source render. The full book
+ * always paginates as one document: native preview updates use a full iframe
+ * swap, so forcing every source wrapper to a new page buys no incremental
+ * splice boundary and diverges from the PDF whenever a source file begins in
+ * the middle of a printed page.
  */
 export declare function injectPreviewScripts(html: string, pageIsolateChapters: boolean): string;
 /**

package/dist/preview/lifecycle.d.ts

@@ -42,7 +42,7 @@ export declare function validateInputPath(inputPath: string): Promise<void>;
  * For empty input (no-input mode), skip manifest loading entirely and
  * return a default resolved config.
  */
-export declare function initializeConfiguration(inputPath: string): Promise<ResolvedConfig>;
+export declare function initializeConfiguration(inputPath: string, engine?: "paged" | "native"): Promise<ResolvedConfig>;
 /**
  * Restart the preview server with a new input directory.
  *

package/dist/{pagedjs-bridge-vn4hk9fx.js → preview-bridge-fz7vpk8m.js}

@@ -71,9 +71,17 @@
   window.addEventListener('sourceLineChanged', function (e) {
     post({ type: 'gutterpress:event', name: 'sourceLineChanged', detail: e.detail });
   });
+  window.addEventListener('viewportChanged', function (e) {
+    post({ type: 'gutterpress:event', name: 'viewportChanged', detail: e.detail });
+  });
   window.addEventListener('elementActivated', function (e) {
     post({ type: 'gutterpress:event', name: 'elementActivated', detail: e.detail });
   });
+  // docs/inline-editing-plan.md §3.1/§3.2 (protocol v4): right-click / keyboard
+  // context-menu target request.
+  window.addEventListener('contextMenuRequested', function (e) {
+    post({ type: 'gutterpress:event', name: 'contextMenuRequested', detail: e.detail });
+  });
 
   // Announce readiness as soon as previewAPI is defined.
   function announceReady() {