@mdzip/editor 1.4.0 → 1.4.4

package/dist/view.js

@@ -14,7 +14,8 @@ import { MDZIP_RUNTIME_LIBRARIES } from './library-info.js';
 import { MdzipWorkspaceService, extensionForMime, normalizeArchivePath, relativeArchivePath } from './workspace.js';
 import { buildMdzipNavTree, canEditMdzipPath, escapeHtml, isOrphanedMdzipAsset, mdzipEntryIconKind, isMdzipManifestPath, resolveMdzipArchiveLinkTarget, renderMdzipPreviewHtml } from './workspace-view.js';
 import { escapeMarkdownImageAlt, findImageReferenceAtOffset, formatImageEditMarkdown } from './image-edit.js';
-import { MdzipRenderingService, defaultSafeMarkdownRenderer, groupTokensIntoChunks } from './rendering.js';
+import { MdzipRenderingService, defaultSafeMarkdownRenderer, groupTokensIntoChunks, chunkSourceKey, tokenEmbedsImage, tokenIsHeading } from './rendering.js';
+import { mdzipFrontMatterExtension } from './front-matter-extension.js';
 import { WORKSPACE_CSS } from './view-css.js';
 const STYLE_ATTR = 'data-mdzip-ws-styles';
 const IMAGE_EXTENSIONS = /\.(jpg|jpeg|png|gif|webp|svg|bmp|ico|tiff?)$/i;
@@ -745,19 +746,19 @@ depth = 0) {
                 : isImageFile(node.entry.path)
                     ? IMAGE_ICON_HTML
                     : FILE_ICON_HTML;
-        const orphanBtnHtml = isOrphaned && options.allowOrphanActions ? `
-      <span class="nav-orphan-button" role="button" tabindex="0"
-        title="Orphaned asset" aria-label="Orphaned asset actions"
-        data-orphan-path="${safePath}">
-        ${ORPHAN_ICON_HTML}
+        const orphanBtnHtml = isOrphaned && options.allowOrphanActions ? `
+      <span class="nav-orphan-button" role="button" tabindex="0"
+        title="Orphaned asset" aria-label="Orphaned asset actions"
+        data-orphan-path="${safePath}">
+        ${ORPHAN_ICON_HTML}
       </span>` : '';
         const draggable = options.allowDrag && !isManifest;
-        return `<button type="button" class="${classes}" title="${title}"
-      data-nav-path="${safePath}" data-orphan="${isOrphaned ? 'true' : ''}"${draggable ? ' draggable="true"' : ''}>
-      ${guides}<span class="nav-caret"></span>
-      <span class="nav-file-icon ${iconKind}">${iconHtml}</span>
-      ${orphanBtnHtml}
-      <span class="nav-label">${safeName}</span>
+        return `<button type="button" class="${classes}" title="${title}"
+      data-nav-path="${safePath}" data-orphan="${isOrphaned ? 'true' : ''}"${draggable ? ' draggable="true"' : ''}>
+      ${guides}<span class="nav-caret"></span>
+      <span class="nav-file-icon ${iconKind}">${iconHtml}</span>
+      ${orphanBtnHtml}
+      <span class="nav-label">${safeName}</span>
     </button>`;
     }
     const childTrail = depth === 0 ? [] : [...trail, !isLast];
@@ -765,14 +766,14 @@ depth = 0) {
         .map((child, index) => renderNavNode(child, state, options, childTrail, index === node.children.length - 1, depth + 1))
         .join('');
     const pending = options.pendingFolders.has(node.path.toLowerCase());
-    return `<details class="nav-directory${pending ? ' pending-folder' : ''}" open data-nav-dir="${escapeHtml(node.path)}">
-    <summary${pending ? ` title="${escapeHtml(node.path)} — not saved until it contains a file"` : ''}>
-      ${guides}<span class="nav-caret" aria-hidden="true"></span>
-      <span class="nav-folder-icon closed">${FOLDER_CLOSED_ICON_HTML}</span>
-      <span class="nav-folder-icon open">${FOLDER_OPEN_ICON_HTML}</span>
-      <span class="nav-label">${escapeHtml(node.name)}</span>
-    </summary>
-    <div class="nav-directory-children">${children}</div>
+    return `<details class="nav-directory${pending ? ' pending-folder' : ''}" open data-nav-dir="${escapeHtml(node.path)}">
+    <summary${pending ? ` title="${escapeHtml(node.path)} — not saved until it contains a file"` : ''}>
+      ${guides}<span class="nav-caret" aria-hidden="true"></span>
+      <span class="nav-folder-icon closed">${FOLDER_CLOSED_ICON_HTML}</span>
+      <span class="nav-folder-icon open">${FOLDER_OPEN_ICON_HTML}</span>
+      <span class="nav-label">${escapeHtml(node.name)}</span>
+    </summary>
+    <div class="nav-directory-children">${children}</div>
   </details>`;
 }
 // Inserts view-local pending (not yet saved) folders into the nav tree so they
@@ -838,6 +839,8 @@ function rawHtmlImageAlignClass(image) {
     return null;
 }
 export class MdzipWorkspaceView {
+    static { this.SCROLL_SYNC_SETTLE_MS = 250; }
+    static { this.SCROLL_SYNC_GESTURE_WINDOW_MS = 500; }
     constructor(container, options = {}) {
         this.workspace = null;
         this.assetSession = null;
@@ -859,12 +862,19 @@ export class MdzipWorkspaceView {
         this.packFilesDialogState = null;
         // Tracks an in-progress progressive (chunked) preview render so Copy All
         // can force-drain whatever's left unmounted. `cursor` is how many of
-        // `chunks` are mounted so far; null once everything's mounted (or when
+        // `records` are mounted so far; null once everything's mounted (or when
         // progressive rendering isn't active at all) — that's Copy All's signal
         // to skip the dialog and copy instantly. `sentinelHandle` is the
         // scroll-driven continuation's IntersectionObserver, if one is currently
         // armed; Copy All tears it down before manually draining so the two don't
         // race and double-mount the same chunk.
+        //
+        // Each record carries its own mounted DOM root and extension/code-block
+        // handles (rather than those living only in the flat `previewHandles`
+        // array below) so that a same-document text edit can reconcile against the
+        // *previous* render's records: chunks whose `chunkSourceKey` didn't change
+        // keep their existing `root`/`handles` untouched — see
+        // `applyChunkReconciliation`.
         this.chunkedRenderState = null;
         // Per-generation memo of renderChunk's raw HTML output, keyed by chunk
         // index, shared between the DOM-mount path (renderAndMountChunkBatch) and
@@ -946,6 +956,52 @@ export class MdzipWorkspaceView {
         // syncScrollFromPreview/syncScrollToPreview).
         this.lastSyncedEditorScrollTop = null;
         this.lastSyncedPreviewScrollTop = null;
+        // Timestamp of the most recent updatePreview() call (edit-driven or
+        // otherwise). A content change that alters a mounted element's rendered
+        // height (a chunk reconcile re-rendering a mermaid diagram, an image
+        // finishing decode, CodeMirror re-measuring line heights after the edit
+        // that triggered it) can cause a 'scroll' event with no explicit write
+        // behind it — the browser's own scroll anchoring, or CodeMirror's internal
+        // viewport/anchor recalculation, adjusting scrollTop on its own to keep
+        // content visually pinned. That's indistinguishable from a real user
+        // scroll to the listeners below, so within a brief window after a content
+        // change we treat scroll events as noise from settling layout rather than
+        // sync-worthy user intent — otherwise this class's own ratio-based writes
+        // (raw pixel values that don't correspond to any document position
+        // CodeMirror has actually measured) can themselves destabilize
+        // CodeMirror's virtualized viewport measurement mid-settle.
+        this.lastContentChangeTime = 0;
+        // Timestamp of the most recent genuine user-input gesture (wheel, touch,
+        // mousedown — including a scrollbar-thumb drag, which lands on the same
+        // element — or a key press) on each pane. Content-change-adjacent 'scroll'
+        // events (see lastContentChangeTime above) turned out to be one of several
+        // distinct ways a non-user-driven scroll can fire: native CSS scroll
+        // anchoring reacting to an unrelated element's height changing — a chunk
+        // reconcile, an image decode, or (confirmed live) an image/mermaid reveal
+        // transition finishing several seconds after the edit that triggered it —
+        // can smoothly drive scrollTop, frame by frame, all the way to a pane's
+        // absolute end, entirely decoupled from any edit and well outside any
+        // settle window. Rather than continuing to special-case each newly
+        // discovered non-user cause after the fact, sync is now gated on positive
+        // evidence of real user intent: a 'scroll' event is only treated as
+        // sync-worthy if a genuine input gesture on that same pane happened very
+        // recently. Everything else — anchoring, our own reconcile restores,
+        // CodeMirror's internal viewport correction — is left alone by definition.
+        this.lastEditorGestureTime = 0;
+        this.lastPreviewGestureTime = 0;
+        // Every preview re-render — whether reconciled or a full cold-start reset
+        // (mountChunkedPreview unconditionally does `elPreviewContent.
+        // replaceChildren()`) — has a real window where the preview is shorter
+        // than before (old DOM torn down, replacement mounted asynchronously: a
+        // chunk reconcile, a full reset, mermaid's async completion). If the
+        // current scroll position no longer fits that transient shrink, the
+        // browser clamps scrollTop to what does fit and never un-clamps once the
+        // replacement's DOM restores the true height. Captured once per
+        // updatePreview() call (before anything moves), restored in
+        // firePreviewRendered — the one point every rendering path (reconcile,
+        // cold-start, progressive, eager, mermaid-triggered or not) already calls
+        // once its content is back in the DOM.
+        this.pendingPreviewScrollRestore = null;
         // Guards syncScrollToPreviewBottom against overlapping drains: set to the
         // chunkedRenderState generation currently being force-drained, null when
         // none is in flight. A second bottom-edge sync that arrives mid-drain
@@ -957,6 +1013,7 @@ export class MdzipWorkspaceView {
         // debounce) — see syncScrollToPreviewBottom.
         this.scrollCatchUpState = null;
         this.markdownExtensions = [];
+        this.frontMatterOptions = {};
         this.entryRenderers = [];
         this.renderingService = new MdzipRenderingService();
         // Preview render memo: the preview pipeline only re-runs when one of these
@@ -991,8 +1048,9 @@ export class MdzipWorkspaceView {
         this.navVisible = options.navigationButtonActive ?? this.navVisible;
         this.markdownRenderer = options.markdownRenderer;
         this.markdownExtensions = options.markdownExtensions ?? [];
+        this.frontMatterOptions = options.frontMatter ?? {};
         this.entryRenderers = options.entryRenderers ?? [];
-        this.renderingService = new MdzipRenderingService(this.markdownRenderer ?? defaultSafeMarkdownRenderer, this.markdownExtensions);
+        this.renderingService = new MdzipRenderingService(this.markdownRenderer ?? defaultSafeMarkdownRenderer, this.pipelineMarkdownExtensions());
         injectStyles(container.ownerDocument);
         container.replaceChildren();
         container.innerHTML = SHELL_HTML;
@@ -1407,15 +1465,46 @@ export class MdzipWorkspaceView {
         if (options.markdownExtensions) {
             this.markdownExtensions = options.markdownExtensions;
         }
+        if (options.frontMatter) {
+            this.frontMatterOptions = options.frontMatter;
+        }
         if (options.entryRenderers) {
             this.entryRenderers = options.entryRenderers;
         }
-        this.renderingService = new MdzipRenderingService(this.markdownRenderer ?? defaultSafeMarkdownRenderer, this.markdownExtensions);
+        this.renderingService = new MdzipRenderingService(this.markdownRenderer ?? defaultSafeMarkdownRenderer, this.pipelineMarkdownExtensions());
         this.resetPreviewState();
         this.teardownEntryRenderer();
         this.entryMatchMissKey = null;
         this.render();
     }
+    /**
+     * The extensions actually handed to `MdzipRenderingService`: the front
+     * matter extension first (always on — see `frontMatterOptions`), then
+     * whatever extensions the host passed via `markdownExtensions`. A fresh
+     * front matter extension instance is created each time this runs (view
+     * construction, `setRenderingOptions`), which is fine — its per-render
+     * state lives in a `WeakMap` keyed by the render context, not on the
+     * extension instance across renders.
+     */
+    pipelineMarkdownExtensions() {
+        return [mdzipFrontMatterExtension(this.frontMatterOptions), ...this.markdownExtensions];
+    }
+    /**
+     * Chunking options combining every registered extension's
+     * {@link MdzipMarkdownRenderExtension.shouldIsolateChunk} — see that doc
+     * comment for why a token an extension owns needs its own chunk regardless
+     * of the size budget — with the same treatment built in for any token that
+     * embeds an image ({@link tokenEmbedsImage}'s doc comment), plus a forced
+     * chunk boundary at every heading ({@link tokenIsHeading}'s doc comment)
+     * so unrelated sections never share a chunk.
+     */
+    chunkOptions() {
+        const extensions = this.pipelineMarkdownExtensions();
+        return {
+            shouldIsolate: (token) => tokenEmbedsImage(token) || extensions.some((ext) => ext.shouldIsolateChunk?.(token)),
+            shouldStartChunk: tokenIsHeading
+        };
+    }
     /**
      * Replaces the view control policy without recreating the workspace or
      * CodeMirror editor. In particular, `lineNumbers` is reconfigured through a
@@ -1534,6 +1623,19 @@ export class MdzipWorkspaceView {
                 this.options.onFailed?.(error);
             }
         }
+        // Per-chunk handles live on their own records (see MdzipChunkRecord), not
+        // in the flat array above — a full reset must still destroy every one of
+        // them, the same as it always destroyed everything in previewHandles.
+        for (const record of this.chunkedRenderState?.records ?? []) {
+            for (const handle of record.handles) {
+                try {
+                    handle.destroy();
+                }
+                catch (error) {
+                    this.options.onFailed?.(error);
+                }
+            }
+        }
         // A new render generation invalidates any in-progress chunk draining —
         // Copy All's own abort check unwinds it and hides the dialog. It also
         // invalidates a "ready to copy" or "done" dialog left over from a
@@ -1556,6 +1658,10 @@ export class MdzipWorkspaceView {
             && memo.colorScheme === this.colorScheme;
     }
     updatePreview(snapshot, entryClaimed) {
+        this.lastContentChangeTime = performance.now();
+        // Captured before anything below can move it — see
+        // `pendingPreviewScrollRestore`'s doc comment.
+        const previewScrollTopBeforeUpdate = this.elPreviewPane.scrollTop;
         if (entryClaimed) {
             // The entry renderer owns the pane stack; release preview resources so
             // a later fallback re-renders from scratch.
@@ -1575,10 +1681,33 @@ export class MdzipWorkspaceView {
             return;
         }
         const animateImageHydration = this.shouldAnimateImageHydration(memo, snapshot);
+        // A same-document, text-only edit with an existing chunked structure can
+        // be reconciled against (only the chunks whose source actually changed
+        // get touched) instead of torn down and rebuilt from scratch. Every
+        // other case — first render, a path/pathType/colorScheme change, a
+        // non-default renderer, a prior explicit reset that already cleared
+        // chunkedRenderState, or an edit-triggered batch mount still in flight
+        // for the current generation (`mounting` — see its doc comment: its
+        // `cursor` doesn't yet reflect where that mount actually is, so
+        // reconciling against it risks orphaned duplicate DOM) — falls through
+        // to today's full reset + cold start, unchanged.
+        const reconcileEligible = !!memo
+            && memo.path === snapshot.currentPath
+            && memo.pathType === snapshot.currentPathType
+            && memo.colorScheme === this.colorScheme
+            && snapshot.currentPathType === 'markdown'
+            && this.renderingService.supportsChunking
+            && !!this.chunkedRenderState
+            && this.chunkedRenderState.generation === this.previewGeneration
+            && !this.chunkedRenderState.mounting;
+        const priorChunkedState = reconcileEligible ? this.chunkedRenderState : null;
         this.previewAbort?.abort();
         this.previewAbort = null;
-        this.destroyPreviewHandles();
+        if (!priorChunkedState) {
+            this.destroyPreviewHandles();
+        }
         const generation = ++this.previewGeneration;
+        this.pendingPreviewScrollRestore = { scrollTop: previewScrollTopBeforeUpdate, generation };
         this.previewHydrated = false;
         this.previewMemo = {
             path: snapshot.currentPath,
@@ -1610,8 +1739,13 @@ export class MdzipWorkspaceView {
         const abort = new AbortController();
         this.previewAbort = abort;
         const context = this.createMarkdownContext(snapshot, abort.signal);
-        if (this.progressiveTextRendering && this.renderingService.supportsChunking) {
-            this.renderChunkedPreview(snapshot, context, generation, animateImageHydration);
+        if (this.renderingService.supportsChunking) {
+            if (priorChunkedState) {
+                this.reconcileChunkedPreview(snapshot, context, generation, animateImageHydration, priorChunkedState);
+            }
+            else {
+                this.renderChunkedPreview(snapshot, context, generation, animateImageHydration);
+            }
             return;
         }
         let result;
@@ -1689,7 +1823,7 @@ export class MdzipWorkspaceView {
         // controls mount, same relative order as always — see
         // collectPendingImages for why it's split from the (expensive) slot
         // creation that follows.
-        const pending = this.collectPendingImages([this.elPreviewContent], animateImageHydration);
+        const pending = this.collectPendingImages([this.elPreviewContent], context, generation, animateImageHydration);
         this.mountPreviewExtensions(context, generation);
         const codeBlockHandle = this.mountCodeBlockControls();
         if (codeBlockHandle) {
@@ -1709,8 +1843,19 @@ export class MdzipWorkspaceView {
      * class, if any — they never get a slot). Returns `[]` without touching
      * anything when there's no asset session to resolve archive images
      * against, matching `mountPreviewHtml`'s no-op image handling.
+     *
+     * An image this session has *already* resolved once (e.g. it was already
+     * on screen before an edit elsewhere caused its chunk to remount) is
+     * applied immediately here via `resolveKnownImage` — no slot, no loading
+     * class, no `hydrateImages`/`IntersectionObserver` round trip — instead of
+     * being handed to the async placeholder-then-swap path meant for an image
+     * that's genuinely being resolved for the first time. Skipping that path
+     * for a re-mount of an already-known image is what actually avoids the
+     * visible flash; still going through it (even instantly) briefly blanks
+     * the image, since a fresh `<img>` element never carries over its
+     * predecessor's already-resolved `src`.
      */
-    collectPendingImages(roots, animateImageHydration) {
+    collectPendingImages(roots, context, generation, animateImageHydration) {
         if (!this.assetSession) {
             return [];
         }
@@ -1727,6 +1872,22 @@ export class MdzipWorkspaceView {
                     }
                     continue;
                 }
+                const known = this.assetSession.resolveKnownImage(source, context.currentPath);
+                if (known) {
+                    if (known.width && known.height && !image.hasAttribute('width') && !image.hasAttribute('height')) {
+                        image.setAttribute('width', String(known.width));
+                        image.setAttribute('height', String(known.height));
+                    }
+                    // No slot wrapper on this path — same direct-on-image alignment as
+                    // the external-URL branch above, not the slot's own align classes.
+                    const alignClass = rawHtmlImageAlignClass(image);
+                    if (alignClass) {
+                        image.classList.add(alignClass);
+                    }
+                    this.attachImageLoadHandlers(image, source, known.url, context, generation);
+                    image.setAttribute('src', known.url);
+                    continue;
+                }
                 image.removeAttribute('src');
                 if (animateImageHydration) {
                     image.classList.add('mdzip-image-loading');
@@ -1896,6 +2057,201 @@ export class MdzipWorkspaceView {
             }
         });
     }
+    /**
+     * Same-document, text-only-edit counterpart to {@link renderChunkedPreview}:
+     * tokenizes the new text, then reconciles against the *previous* render's
+     * records (`priorState`) instead of tearing everything down. Only reachable
+     * when `updatePreview` determined the prior chunked structure is still
+     * reuse-eligible (same path/pathType/colorScheme); the caller already
+     * checked that.
+     */
+    reconcileChunkedPreview(snapshot, context, generation, animateImageHydration, priorState) {
+        let tokens;
+        try {
+            tokens = this.renderingService.tokenizeMarkdown(snapshot.currentText, context);
+        }
+        catch (error) {
+            this.options.onFailed?.(error);
+            // Can't reconcile without tokens — fall back to a hard reset.
+            this.destroyPreviewHandles();
+            this.elPreviewContent.innerHTML = renderMdzipPreviewHtml(snapshot);
+            this.firePreviewRendered(snapshot, generation);
+            this.fireAssetsHydrated(snapshot, generation);
+            return;
+        }
+        const proceed = (resolvedTokens) => {
+            if (generation !== this.previewGeneration || context.signal.aborted)
+                return;
+            this.applyChunkReconciliation(resolvedTokens, snapshot, context, generation, animateImageHydration, priorState);
+        };
+        if (Array.isArray(tokens)) {
+            proceed(tokens);
+            return;
+        }
+        void tokens.then(proceed).catch((error) => {
+            if (generation !== this.previewGeneration || context.signal.aborted)
+                return;
+            if (error?.name !== 'AbortError') {
+                this.options.onFailed?.(error);
+            }
+        });
+    }
+    /** Destroys one chunk record's mounted DOM and handles (but not the record object itself). */
+    teardownChunkRecord(record) {
+        for (const handle of record.handles) {
+            try {
+                handle.destroy();
+            }
+            catch (error) {
+                this.options.onFailed?.(error);
+            }
+        }
+        record.root?.remove();
+    }
+    /**
+     * Diffs the new tokenize pass's chunks against `priorState.records` by
+     * source-text identity (`chunkSourceKey`) and reconciles: chunks in the
+     * matched leading/trailing run keep their existing DOM and handles
+     * untouched (never re-rendered, never re-mounted — see
+     * `chunkSourceKey`'s doc comment for why that matters for extensions like
+     * mermaid); only the "middle" range that actually changed is torn down and
+     * remounted. Uses prefix/suffix matching rather than a general LCS — a
+     * text editor's edits are localized, so this is both simpler and correct
+     * for the real-world case.
+     */
+    applyChunkReconciliation(tokens, snapshot, context, generation, animateImageHydration, priorState) {
+        // Tear down any live sentinel from the prior state before touching DOM —
+        // same reasoning as drainRemainingChunks: stops it from racing this
+        // reconciliation and double-mounting a chunk.
+        priorState.sentinelHandle?.destroy();
+        this.previewHandles = this.previewHandles.filter((h) => h !== priorState.sentinelHandle);
+        const newChunks = groupTokensIntoChunks(tokens, this.chunkOptions());
+        const oldRecords = priorState.records;
+        const oldCursor = priorState.cursor;
+        if (newChunks.length === 0) {
+            // Whole document collapsed to nothing renderable — nothing to reuse.
+            for (const record of oldRecords) {
+                this.teardownChunkRecord(record);
+            }
+            this.elPreviewContent.replaceChildren();
+            this.chunkedRenderState = null;
+            this.firePreviewRendered(snapshot, generation);
+            this.fireAssetsHydrated(snapshot, generation);
+            return;
+        }
+        const oldKeys = oldRecords.map((r) => r.key);
+        const newKeys = newChunks.map((c) => chunkSourceKey(c));
+        const maxMatch = Math.min(oldKeys.length, newKeys.length);
+        let prefixLen = 0;
+        while (prefixLen < maxMatch && oldKeys[prefixLen] === newKeys[prefixLen])
+            prefixLen += 1;
+        const maxSuffix = maxMatch - prefixLen;
+        let suffixLen = 0;
+        while (suffixLen < maxSuffix
+            && oldKeys[oldKeys.length - 1 - suffixLen] === newKeys[newKeys.length - 1 - suffixLen])
+            suffixLen += 1;
+        const oldMiddleStart = prefixLen;
+        const oldMiddleEnd = oldRecords.length - suffixLen;
+        const newMiddleStart = prefixLen;
+        const newMiddleEnd = newChunks.length - suffixLen;
+        const newRecords = [];
+        for (let i = 0; i < prefixLen; i += 1) {
+            newRecords.push({ ...oldRecords[i], key: newKeys[i], tokens: newChunks[i] });
+        }
+        for (let i = newMiddleStart; i < newMiddleEnd; i += 1) {
+            newRecords.push({ key: newKeys[i], tokens: newChunks[i], root: null, html: null, handles: [] });
+        }
+        for (let i = 0; i < suffixLen; i += 1) {
+            const oi = oldRecords.length - suffixLen + i;
+            const ni = newChunks.length - suffixLen + i;
+            newRecords.push({ ...oldRecords[oi], key: newKeys[ni], tokens: newChunks[ni] });
+        }
+        // Destroy DOM+handles for old-middle records that were actually mounted
+        // (bounded by the old cursor — everything from there on was still
+        // waiting in the lazy-load tail, never mounted, nothing to destroy).
+        const oldMountedMiddleEnd = Math.min(oldCursor, oldMiddleEnd);
+        for (let i = oldMiddleStart; i < oldMountedMiddleEnd; i += 1) {
+            this.teardownChunkRecord(oldRecords[i]);
+        }
+        const oldMountedMiddleCount = Math.max(0, oldMountedMiddleEnd - oldMiddleStart);
+        // Reference node for splicing in the new middle's DOM: the first
+        // surviving *mounted* suffix record (mounted suffix records are
+        // contiguous from newMiddleEnd by construction), else null (append).
+        let insertBeforeNode = null;
+        for (let i = newMiddleEnd; i < newRecords.length; i += 1) {
+            if (newRecords[i].root) {
+                insertBeforeNode = newRecords[i].root;
+                break;
+            }
+        }
+        this.chunkedRenderState = {
+            records: newRecords,
+            cursor: oldCursor,
+            context,
+            generation,
+            animateImageHydration,
+            sentinelHandle: null,
+            mounting: oldMountedMiddleCount > 0
+        };
+        if (oldMountedMiddleCount === 0) {
+            // The edit is entirely beyond what was mounted (progressive mode,
+            // still in the lazy-load tail) — nothing was destroyed, nothing needs
+            // mounting now. Cursor is unaffected: every index below it is an
+            // untouched prefix survivor, valid at the same index in newRecords. The
+            // old sentinel was already torn down above, so a fresh one has to be
+            // armed to keep the lazy-load tail continuing.
+            if (oldCursor < newRecords.length) {
+                this.armChunkSentinel(newRecords, oldCursor, context, generation, animateImageHydration);
+            }
+            this.firePreviewRendered(snapshot, generation);
+            this.fireAssetsHydrated(snapshot, generation);
+            return;
+        }
+        void this.mountReconciledMiddle(newRecords, newMiddleStart, newMiddleEnd, insertBeforeNode, context, generation, animateImageHydration, snapshot, oldCursor, oldMiddleEnd);
+    }
+    /**
+     * Mounts a reconciliation's replacement "middle" range in full (uncapped —
+     * a single edit only ever touches 1-2 chunks in practice; see the plan's
+     * disclosed v1 risk for the pathological large-paste case), then carries
+     * forward however much of the surviving suffix was already mounted before
+     * reconciling, and re-arms the sentinel for whatever's still left.
+     */
+    async mountReconciledMiddle(records, middleStart, middleEnd, insertBeforeNode, context, generation, animateImageHydration, snapshot, oldCursor, oldMiddleEnd) {
+        let cursor = middleStart;
+        let mountedRoots = [];
+        while (cursor < middleEnd) {
+            const batch = await this.renderAndMountChunkBatch(records, cursor, context, generation, insertBeforeNode);
+            if (generation !== this.previewGeneration || context.signal.aborted)
+                return;
+            if (batch.cursor === cursor)
+                break; // Aborted/superseded mid-loop with no progress.
+            cursor = batch.cursor;
+            mountedRoots = mountedRoots.concat(batch.mountedRoots);
+        }
+        const carriedSuffixMounted = Math.max(0, oldCursor - oldMiddleEnd);
+        const finalCursor = Math.min(records.length, Math.max(cursor, middleEnd) + carriedSuffixMounted);
+        // See armChunkSentinel's mountNext for why this is recorded before the
+        // staleness check: finalCursor already correctly folds in the carried-
+        // forward suffix (chunks beyond the reconciled middle that were already
+        // mounted), so discarding it here just because a newer edit has since
+        // landed would regress chunkedRenderState.cursor back down — causing the
+        // next reconcile to re-arm a sentinel from that stale, lower cursor and
+        // re-mount (duplicate) chunks that are already correctly in the DOM.
+        this.recordChunkProgress(generation, records, finalCursor);
+        if (generation !== this.previewGeneration || context.signal.aborted)
+            return;
+        if (this.chunkedRenderState?.generation === generation) {
+            this.chunkedRenderState.mounting = false;
+        }
+        const pending = this.collectPendingImages(mountedRoots, context, generation, animateImageHydration);
+        this.hydrateImages(pending, context, generation, animateImageHydration, () => {
+            this.fireAssetsHydrated(snapshot, generation);
+        });
+        this.firePreviewRendered(snapshot, generation);
+        if (this.chunkedRenderState?.generation === generation && finalCursor < records.length) {
+            this.armChunkSentinel(records, finalCursor, context, generation, animateImageHydration);
+        }
+    }
     /**
      * Groups tokens into chunks and mounts them: an initial batch synchronously
      * (enough for a small document to behave exactly like the non-chunked
@@ -1911,41 +2267,111 @@ export class MdzipWorkspaceView {
         this.elPreviewContent.replaceChildren();
         // Also called with no options in renderFullDocumentHtml — see the
         // comment there; keep both call sites' chunking in sync.
-        const chunks = groupTokensIntoChunks(tokens);
+        const chunks = groupTokensIntoChunks(tokens, this.chunkOptions());
         if (chunks.length === 0) {
             this.chunkedRenderState = null;
             this.firePreviewRendered(snapshot, generation);
             this.fireAssetsHydrated(snapshot, generation);
             return;
         }
-        this.chunkedRenderState = { chunks, cursor: 0, context, generation, animateImageHydration, sentinelHandle: null };
-        void this.mountChunkBatch(chunks, 0, context, generation, animateImageHydration, () => {
-            this.fireAssetsHydrated(snapshot, generation);
-        }).then((cursor) => {
+        const records = chunks.map((chunkTokens) => ({
+            key: chunkSourceKey(chunkTokens),
+            tokens: chunkTokens,
+            root: null,
+            html: null,
+            handles: []
+        }));
+        this.chunkedRenderState = {
+            records, cursor: 0, context, generation, animateImageHydration, sentinelHandle: null,
+            // Set for the whole initial batch/eager mount below — see the field's
+            // doc comment: an edit landing before this settles must not reconcile
+            // against a `cursor` that doesn't yet reflect this in-flight mount.
+            mounting: true
+        };
+        if (this.progressiveTextRendering) {
+            // Mount an initial batch synchronously (enough for a small document to
+            // behave exactly like a non-progressive mount), then lazily continue
+            // the rest as the user scrolls near a trailing sentinel.
+            void this.mountChunkBatch(records, 0, context, generation, animateImageHydration, () => {
+                this.fireAssetsHydrated(snapshot, generation);
+            }).then((cursor) => {
+                // See armChunkSentinel's mountNext for why this is recorded before
+                // the staleness check below.
+                this.recordChunkProgress(generation, records, cursor);
+                if (generation !== this.previewGeneration || context.signal.aborted)
+                    return;
+                if (this.chunkedRenderState?.generation === generation) {
+                    this.chunkedRenderState.mounting = false;
+                }
+                this.firePreviewRendered(snapshot, generation);
+                if (cursor < records.length) {
+                    this.armChunkSentinel(records, cursor, context, generation, animateImageHydration);
+                }
+            });
+            return;
+        }
+        // Not opted into lazy-load-on-scroll: mount every chunk up front, same
+        // visible end state as the old monolithic non-chunked path, but yielding
+        // a frame between batches (mirroring drainRemainingChunks) instead of
+        // blocking the main thread for one giant synchronous render — see the
+        // plan's disclosed cold-start tradeoff.
+        void this.mountAllChunksEagerly(records, context, generation, animateImageHydration, snapshot);
+    }
+    /**
+     * Mounts every chunk of a non-progressive (`progressiveTextRendering:
+     * false`) document up front — same end state as the old monolithic
+     * non-chunked path (the whole document mounted before `onPreviewRendered`
+     * fires), but yielding a frame between batches (mirroring
+     * `drainRemainingChunks`) instead of blocking the main thread for one
+     * giant synchronous render.
+     */
+    async mountAllChunksEagerly(records, context, generation, animateImageHydration, snapshot) {
+        const allPending = [];
+        while (generation === this.previewGeneration && !context.signal.aborted) {
+            const cursorBefore = this.chunkedRenderState?.generation === generation
+                ? this.chunkedRenderState.cursor
+                : records.length;
+            if (cursorBefore >= records.length)
+                break;
+            const { cursor, mountedRoots } = await this.renderAndMountChunkBatch(records, cursorBefore, context, generation);
+            // See armChunkSentinel's mountNext for why this is recorded before the
+            // staleness check: the chunks this batch appended are physically in
+            // the DOM regardless of whether a newer edit has since landed, and
+            // recordChunkProgress's own generation check keeps this a safe no-op
+            // once chunkedRenderState has moved on.
+            this.recordChunkProgress(generation, records, cursor);
             if (generation !== this.previewGeneration || context.signal.aborted)
                 return;
-            this.recordChunkProgress(generation, chunks, cursor);
-            this.firePreviewRendered(snapshot, generation);
-            if (cursor < chunks.length) {
-                this.armChunkSentinel(chunks, cursor, context, generation, animateImageHydration);
+            allPending.push(...this.collectPendingImages(mountedRoots, context, generation, animateImageHydration));
+            if (cursor >= records.length)
+                break;
+            await new Promise((resolve) => requestAnimationFrame(() => resolve()));
+        }
+        if (generation === this.previewGeneration && !context.signal.aborted) {
+            if (this.chunkedRenderState?.generation === generation) {
+                this.chunkedRenderState.mounting = false;
             }
-        });
+            this.firePreviewRendered(snapshot, generation);
+            this.hydrateImages(allPending, context, generation, animateImageHydration, () => {
+                this.fireAssetsHydrated(snapshot, generation);
+            });
+        }
     }
     /**
-     * Updates `chunkedRenderState.cursor` after a batch mounts, or clears the
-     * whole state once every chunk is in the DOM — that `null` is Copy All's
-     * signal that there's nothing left to force-render. A no-op if a newer
-     * render generation has already superseded this one.
+     * Updates `chunkedRenderState.cursor` after a batch mounts. A no-op if a
+     * newer render generation has already superseded this one. Deliberately
+     * never nulls `chunkedRenderState` out just because `cursor` reached
+     * `records.length` — the records stay alive for the whole generation so a
+     * later same-document edit can reconcile against them (see
+     * `applyChunkReconciliation`). Callers that need "is there still an
+     * unmounted lazy tail" (Copy All's instant path, the scroll-to-bottom fast
+     * path) check `cursor < records.length` directly instead of this field's
+     * truthiness.
      */
-    recordChunkProgress(generation, chunks, cursor) {
+    recordChunkProgress(generation, records, cursor) {
         if (this.chunkedRenderState?.generation !== generation)
             return;
-        if (cursor >= chunks.length) {
-            this.chunkedRenderState = null;
-        }
-        else {
-            this.chunkedRenderState.cursor = cursor;
-        }
+        this.chunkedRenderState.cursor = cursor;
     }
     /**
      * Renders+appends chunks starting at `startCursor` up to a char budget
@@ -1964,7 +2390,7 @@ export class MdzipWorkspaceView {
      * included here; see {@link mountChunkBatch} and
      * {@link drainRemainingChunks} for the two different ways callers pace it.
      */
-    async renderAndMountChunkBatch(chunks, startCursor, context, generation) {
+    async renderAndMountChunkBatch(records, startCursor, context, generation, insertBeforeNode = null) {
         const BATCH_CHAR_BUDGET = 4000;
         const BATCH_TIME_BUDGET_MS = 10;
         const clock = this.elPreviewContent.ownerDocument.defaultView?.performance ?? performance;
@@ -1972,12 +2398,13 @@ export class MdzipWorkspaceView {
         let cursor = startCursor;
         let renderedChars = 0;
         const mountedRoots = [];
-        while (cursor < chunks.length
+        const batchStartCursor = startCursor;
+        while (cursor < records.length
             && renderedChars < BATCH_CHAR_BUDGET
             && (mountedRoots.length === 0 || clock.now() - batchStart < BATCH_TIME_BUDGET_MS)) {
             if (generation !== this.previewGeneration || context.signal.aborted)
                 return { cursor, mountedRoots };
-            const chunkTokens = chunks[cursor];
+            const chunkTokens = records[cursor].tokens;
             const chunkIndex = cursor;
             cursor += 1;
             let html;
@@ -2011,15 +2438,19 @@ export class MdzipWorkspaceView {
                 }
                 this.chunkHtmlCache.html.set(chunkIndex, html);
             }
-            const root = this.appendChunkHtml(html);
+            const root = this.appendChunkHtml(html, insertBeforeNode);
+            records[chunkIndex].root = root;
+            records[chunkIndex].html = html;
             mountedRoots.push(root);
             renderedChars += html.length;
         }
-        for (const root of mountedRoots) {
-            this.mountPreviewExtensions(context, generation, root);
-            const codeBlockHandle = this.mountCodeBlockControls(root);
+        for (const record of records.slice(batchStartCursor, cursor)) {
+            if (!record.root)
+                continue;
+            this.mountPreviewExtensions(context, generation, record.root, record.handles);
+            const codeBlockHandle = this.mountCodeBlockControls(record.root);
             if (codeBlockHandle) {
-                this.previewHandles.push(codeBlockHandle);
+                record.handles.push(codeBlockHandle);
             }
         }
         return { cursor, mountedRoots };
@@ -2033,21 +2464,31 @@ export class MdzipWorkspaceView {
      * by how fast the user scrolls, so one independent hydration loop per
      * batch never has a chance to pile up against another.
      */
-    async mountChunkBatch(chunks, startCursor, context, generation, animateImageHydration, onImagesSettled) {
-        const { cursor, mountedRoots } = await this.renderAndMountChunkBatch(chunks, startCursor, context, generation);
+    async mountChunkBatch(records, startCursor, context, generation, animateImageHydration, onImagesSettled) {
+        const { cursor, mountedRoots } = await this.renderAndMountChunkBatch(records, startCursor, context, generation);
         // Same relative order as the non-chunked path: cheap image pass, then
         // the (expensive) slot/observe pass.
-        const pending = this.collectPendingImages(mountedRoots, animateImageHydration);
+        const pending = this.collectPendingImages(mountedRoots, context, generation, animateImageHydration);
         this.hydrateImages(pending, context, generation, animateImageHydration, onImagesSettled);
         return cursor;
     }
-    /** Wraps one chunk's rendered HTML in a mount boundary and appends it. See the `.mdzip-chunk` CSS rules for why. */
-    appendChunkHtml(html) {
+    /**
+     * Wraps one chunk's rendered HTML in a mount boundary and appends it (or,
+     * given `beforeNode`, splices it in ahead of that still-attached node —
+     * used by reconciliation to insert a replacement chunk ahead of a
+     * surviving mounted suffix). See the `.mdzip-chunk` CSS rules for why.
+     */
+    appendChunkHtml(html, beforeNode = null) {
         const doc = this.elPreviewContent.ownerDocument;
         const wrapper = doc.createElement('div');
         wrapper.className = 'mdzip-chunk';
         wrapper.innerHTML = html;
-        this.elPreviewContent.appendChild(wrapper);
+        if (beforeNode && beforeNode.parentNode === this.elPreviewContent) {
+            this.elPreviewContent.insertBefore(wrapper, beforeNode);
+        }
+        else {
+            this.elPreviewContent.appendChild(wrapper);
+        }
         return wrapper;
     }
     /**
@@ -2058,17 +2499,36 @@ export class MdzipWorkspaceView {
      * every chunk is mounted. Falls back to mounting everything immediately
      * when IntersectionObserver isn't available, matching `hydrateImages`.
      */
-    armChunkSentinel(chunks, cursor, context, generation, animateImageHydration) {
+    armChunkSentinel(records, cursor, context, generation, animateImageHydration) {
         const doc = this.elPreviewContent.ownerDocument;
         const observerWindow = doc.defaultView;
         const mountNext = (nextCursor) => {
-            void this.mountChunkBatch(chunks, nextCursor, context, generation, animateImageHydration, () => { })
+            // Same race this field guards against everywhere else: an edit landing
+            // while this scroll-triggered continuation is mid-flight must not
+            // reconcile against a cursor that doesn't yet reflect it.
+            if (this.chunkedRenderState?.generation === generation) {
+                this.chunkedRenderState.mounting = true;
+            }
+            void this.mountChunkBatch(records, nextCursor, context, generation, animateImageHydration, () => { })
                 .then((newCursor) => {
+                // Record whatever this batch actually mounted regardless of
+                // whether a newer edit has since landed — recordChunkProgress's
+                // own generation check already makes this a safe no-op once
+                // chunkedRenderState has moved on. Skipping this call when stale
+                // was a real bug: the chunks this batch appended are physically in
+                // the DOM either way, but a newer edit's reconcile still saw the
+                // *old*, un-advanced cursor and re-armed a sentinel from the same
+                // starting point — re-rendering and re-appending (duplicating)
+                // chunks that were already mounted, visible as an already-settled
+                // image flashing back to broken as a fresh duplicate replaced it.
+                this.recordChunkProgress(generation, records, newCursor);
                 if (generation !== this.previewGeneration || context.signal.aborted)
                     return;
-                this.recordChunkProgress(generation, chunks, newCursor);
-                if (newCursor < chunks.length) {
-                    this.armChunkSentinel(chunks, newCursor, context, generation, animateImageHydration);
+                if (this.chunkedRenderState?.generation === generation) {
+                    this.chunkedRenderState.mounting = false;
+                }
+                if (newCursor < records.length) {
+                    this.armChunkSentinel(records, newCursor, context, generation, animateImageHydration);
                 }
             });
         };
@@ -2169,7 +2629,7 @@ export class MdzipWorkspaceView {
      * appended chunk rather than once over the whole document. Defaults to
      * the whole preview content, matching the non-chunked path exactly.
      */
-    mountPreviewExtensions(context, generation, root = this.elPreviewContent) {
+    mountPreviewExtensions(context, generation, root = this.elPreviewContent, collector = this.previewHandles) {
         for (const extension of this.markdownExtensions) {
             if (!extension.mount) {
                 continue;
@@ -2190,7 +2650,7 @@ export class MdzipWorkspaceView {
                             }
                             return;
                         }
-                        this.previewHandles.push(handle);
+                        collector.push(handle);
                     }).catch((error) => {
                         if (generation === this.previewGeneration) {
                             this.options.onFailed?.(error);
@@ -2198,7 +2658,7 @@ export class MdzipWorkspaceView {
                     });
                 }
                 else if (mounted) {
-                    this.previewHandles.push(mounted);
+                    collector.push(mounted);
                 }
             }
             catch (error) {
@@ -2337,6 +2797,7 @@ export class MdzipWorkspaceView {
         if (generation !== this.previewGeneration) {
             return;
         }
+        this.restorePendingPreviewScroll(generation);
         try {
             this.options.onPreviewRendered?.(snapshot);
         }
@@ -2344,6 +2805,20 @@ export class MdzipWorkspaceView {
             this.options.onFailed?.(error);
         }
     }
+    /** See `pendingPreviewScrollRestore`'s doc comment. */
+    restorePendingPreviewScroll(generation) {
+        const pending = this.pendingPreviewScrollRestore;
+        if (!pending || pending.generation !== generation) {
+            return;
+        }
+        this.pendingPreviewScrollRestore = null;
+        if (this.elPreviewPane.scrollTop !== pending.scrollTop) {
+            this.syncing = true;
+            this.lastSyncedPreviewScrollTop = pending.scrollTop;
+            this.elPreviewPane.scrollTop = pending.scrollTop;
+            this.syncing = false;
+        }
+    }
     fireAssetsHydrated(snapshot, generation) {
         if (generation !== this.previewGeneration) {
             return;
@@ -2648,6 +3123,19 @@ export class MdzipWorkspaceView {
         // Attach scroll listener to sync with preview
         const scroller = editor.dom.querySelector('.cm-scroller');
         if (scroller) {
+            // No 'keydown' here, deliberately: .cm-scroller receives every keystroke
+            // typed into the editor, not just navigation keys, so it can't tell
+            // "user pressed PageDown to scroll" apart from "user typed a letter" —
+            // confirmed live, where ordinary typing was arming this gesture window
+            // and letting CodeMirror's own small post-edit viewport-correction
+            // scroll (a real native behavior) through as if it were a deliberate
+            // scroll, on every keystroke. Wheel/touch/mousedown (which also covers
+            // a scrollbar-thumb drag, since that lands on this same element) are
+            // unambiguous and cover the vast majority of real scrolling.
+            const markEditorGesture = () => { self.lastEditorGestureTime = performance.now(); };
+            scroller.addEventListener('wheel', markEditorGesture, { passive: true });
+            scroller.addEventListener('touchstart', markEditorGesture, { passive: true });
+            scroller.addEventListener('mousedown', markEditorGesture);
             scroller.addEventListener('scroll', () => self.syncScrollToPreview());
         }
         editor.dom.addEventListener(IMAGE_EDIT_AFFORDANCE_CLICK_EVENT, (event) => {
@@ -3421,6 +3909,11 @@ export class MdzipWorkspaceView {
                 void this.replaceFileFromPicker(path, file);
             }
         });
+        const markPreviewGesture = () => { this.lastPreviewGestureTime = performance.now(); };
+        this.elPreviewPane.addEventListener('wheel', markPreviewGesture, { passive: true });
+        this.elPreviewPane.addEventListener('touchstart', markPreviewGesture, { passive: true });
+        this.elPreviewPane.addEventListener('mousedown', markPreviewGesture);
+        this.elPreviewPane.addEventListener('keydown', markPreviewGesture);
         this.elPreviewPane.addEventListener('scroll', () => this.syncScrollFromPreview());
         // Gives the pane logical focus on click so a subsequent Ctrl/Cmd+A (below)
         // can be scoped to it. tabindex="-1" keeps it out of Tab order; this is
@@ -4460,20 +4953,22 @@ export class MdzipWorkspaceView {
      * Copies the entire rendered document as plain text (same fidelity as
      * `copyPreviewSelection` — no HTML, no `ClipboardItem`), regardless of how
      * much of it is currently mounted under progressive rendering. If
-     * everything's already mounted (small doc, non-chunked render, or the user
-     * already scrolled through it) this is instant — `chunkedRenderState` is
-     * null in exactly that case. Otherwise it force-drains the rest first,
-     * showing a cancelable progress dialog once the wait clears a short
-     * debounce so fast documents never flicker it into view.
+     * everything's already mounted (small doc, eager/non-progressive mount, or
+     * the user already scrolled through it) this is instant —
+     * `chunkedRenderState` is either null (no markdown open, or a non-default
+     * renderer) or has nothing left to mount (`cursor >= records.length`) in
+     * exactly that case. Otherwise it force-drains the rest first, showing a
+     * cancelable progress dialog once the wait clears a short debounce so fast
+     * documents never flicker it into view.
      */
     async copyAllPreviewContent() {
         const pending = this.chunkedRenderState;
-        if (!pending) {
+        if (!pending || pending.cursor >= pending.records.length) {
             const outcome = await this.copyPreviewSelection(this.elPreviewContent.textContent ?? '');
             this.finishCopyNotification(false, outcome);
             return;
         }
-        const total = pending.chunks.length;
+        const total = pending.records.length;
         const abort = new AbortController();
         let dialogShown = false;
         const label = 'Rendering the full document';
@@ -4503,8 +4998,9 @@ export class MdzipWorkspaceView {
             // Cancelled partway through — whatever's left stays unmounted, so
             // re-arm the usual scroll-driven continuation for it.
             const remaining = this.chunkedRenderState;
-            if (remaining && remaining.generation === pending.generation && !remaining.sentinelHandle) {
-                this.armChunkSentinel(remaining.chunks, remaining.cursor, remaining.context, remaining.generation, remaining.animateImageHydration);
+            if (remaining && remaining.generation === pending.generation && !remaining.sentinelHandle
+                && remaining.cursor < remaining.records.length) {
+                this.armChunkSentinel(remaining.records, remaining.cursor, remaining.context, remaining.generation, remaining.animateImageHydration);
             }
             return;
         }
@@ -4546,7 +5042,7 @@ export class MdzipWorkspaceView {
         // renderAndMountChunkBatch's caller (mountChunkedPreview) — keep both
         // call sites' chunking in sync, since chunk index is chunkHtmlCache's
         // only key.
-        const chunks = groupTokensIntoChunks(tokens);
+        const chunks = groupTokensIntoChunks(tokens, this.chunkOptions());
         const view = this.elPreviewContent.ownerDocument.defaultView;
         const clock = view?.performance ?? performance;
         const BATCH_TIME_BUDGET_MS = 10;
@@ -4761,32 +5257,39 @@ export class MdzipWorkspaceView {
      * making Copy All wait on it.
      */
     async drainRemainingChunks(state, onProgress, signal) {
-        const { chunks, context, generation, animateImageHydration } = state;
+        const { records, context, generation, animateImageHydration } = state;
         // Draining is instead of the scroll-driven continuation, not alongside
         // it — tearing down any armed sentinel first stops the two from racing
         // and double-mounting the same chunk.
         state.sentinelHandle?.destroy();
         if (this.chunkedRenderState?.generation === generation) {
             this.chunkedRenderState.sentinelHandle = null;
+            // Same race the `mounting` field guards against elsewhere: an edit
+            // landing mid-drain must not reconcile against a cursor this loop is
+            // actively advancing out from under it.
+            this.chunkedRenderState.mounting = true;
         }
         const allPending = [];
         try {
-            while (this.chunkedRenderState?.generation === generation && this.chunkedRenderState.cursor < chunks.length) {
+            while (this.chunkedRenderState?.generation === generation && this.chunkedRenderState.cursor < records.length) {
                 if (signal.aborted || generation !== this.previewGeneration || context.signal.aborted)
                     return;
                 const cursor = this.chunkedRenderState.cursor;
-                const { cursor: newCursor, mountedRoots } = await this.renderAndMountChunkBatch(chunks, cursor, context, generation);
+                const { cursor: newCursor, mountedRoots } = await this.renderAndMountChunkBatch(records, cursor, context, generation);
                 if (generation !== this.previewGeneration || context.signal.aborted)
                     return;
-                allPending.push(...this.collectPendingImages(mountedRoots, animateImageHydration));
-                this.recordChunkProgress(generation, chunks, newCursor);
-                onProgress(newCursor, chunks.length);
+                allPending.push(...this.collectPendingImages(mountedRoots, context, generation, animateImageHydration));
+                this.recordChunkProgress(generation, records, newCursor);
+                onProgress(newCursor, records.length);
                 if (signal.aborted)
                     return;
                 await new Promise((resolve) => requestAnimationFrame(() => resolve()));
             }
         }
         finally {
+            if (this.chunkedRenderState?.generation === generation) {
+                this.chunkedRenderState.mounting = false;
+            }
             if (generation === this.previewGeneration && !context.signal.aborted) {
                 this.hydrateImages(allPending, context, generation, animateImageHydration, () => { });
             }
@@ -5757,6 +6260,12 @@ export class MdzipWorkspaceView {
         if (this.syncing || !this.cmEditor || this.layout !== 'split') {
             return;
         }
+        if (performance.now() - this.lastPreviewGestureTime > MdzipWorkspaceView.SCROLL_SYNC_GESTURE_WINDOW_MS) {
+            return;
+        }
+        if (performance.now() - this.lastContentChangeTime < MdzipWorkspaceView.SCROLL_SYNC_SETTLE_MS) {
+            return;
+        }
         const currentTop = this.elPreviewPane.scrollTop;
         // Recognize this event as the echo of our own prior write (from
         // syncScrollToPreview) by comparing values instead of racing timing.
@@ -5787,6 +6296,12 @@ export class MdzipWorkspaceView {
         if (this.syncing || !this.cmEditor || this.layout !== 'split') {
             return;
         }
+        if (performance.now() - this.lastEditorGestureTime > MdzipWorkspaceView.SCROLL_SYNC_GESTURE_WINDOW_MS) {
+            return;
+        }
+        if (performance.now() - this.lastContentChangeTime < MdzipWorkspaceView.SCROLL_SYNC_SETTLE_MS) {
+            return;
+        }
         const cmScroller = this.cmEditor.dom.querySelector('.cm-scroller');
         if (!cmScroller) {
             return;
@@ -5813,8 +6328,23 @@ export class MdzipWorkspaceView {
         // CodeMirror has actually decided to draw for the current scroll
         // position, so comparing it to the document length is exact regardless
         // of any height estimation drift.
-        const atDocEnd = this.cmEditor.viewport.to >= this.cmEditor.state.doc.length;
-        if (atDocEnd && this.chunkedRenderState) {
+        //
+        // `viewport.to >= doc.length` alone is a false positive whenever the
+        // whole document already fits within the editor's visible area — there
+        // is no scrolling at all in that case, so `viewport.to` trivially covers
+        // the full document from position 0 regardless of scroll intent. Without
+        // the overflow check below, a short-to-medium document (especially one
+        // with images, which slow down per-chunk mounting enough to leave a real
+        // window where `cursor < records.length`) could hit this branch off of
+        // an incidental scroll event fired mid-edit — e.g. focus or cursor
+        // movement nudging `scrollTop` by a sub-pixel amount — and force-drain
+        // plus jump the preview to its bottom for no reason the user asked for,
+        // which (via the echo-breaking reflow that follows, since late-arriving
+        // image layout shifts the "bottom" after the jump) can drag the editor's
+        // own scroll down to match through `syncScrollFromPreview`'s echo path.
+        const hasScrollableOverflow = editorHeight > 0;
+        const atDocEnd = hasScrollableOverflow && this.cmEditor.viewport.to >= this.cmEditor.state.doc.length;
+        if (atDocEnd && this.chunkedRenderState && this.chunkedRenderState.cursor < this.chunkedRenderState.records.length) {
             void this.syncScrollToPreviewBottom();
             return;
         }
@@ -5857,7 +6387,7 @@ export class MdzipWorkspaceView {
         }
         let showToastTimer = setTimeout(() => {
             showToastTimer = null;
-            this.scrollCatchUpState = { done: state.cursor, total: state.chunks.length };
+            this.scrollCatchUpState = { done: state.cursor, total: state.records.length };
             this.updateScrollCatchUpToast();
         }, 200);
         try {
@@ -6057,325 +6587,325 @@ function formatMetadataValue(value) {
     }
     return 'Not available';
 }
-const SHELL_HTML = `
-<section class="mdzip-root">
-  <div class="document-strip" data-ref="document-strip" hidden>
-    <button type="button" class="title-button" data-ref="title-btn"></button>
-    <button type="button" class="document-info-button" data-ref="document-info-btn"
-      title="Document information" aria-label="Document information">
-      ${INFO_ICON_HTML}
-    </button>
-  </div>
-
-  <header class="toolbar" data-ref="toolbar" hidden>
-    <div class="toolbar-start">
-      <div class="toolbar-left">
-        <button type="button" class="icon-toggle nav-toggle" data-ref="nav-btn" title="Toggle contents" aria-label="Toggle contents">
-          ${NAV_TOGGLE_ICON_HTML}
-        </button>
-      </div>
-
-      <div class="edit-toolbar" data-ref="edit-toolbar" role="toolbar" aria-label="Markdown formatting">
-        <div class="edit-toolbar-group">
-          <button type="button" data-format="bold" data-format-control="bold" title="Bold" aria-label="Bold">${BOLD_ICON_HTML}</button>
-          <button type="button" data-format="italic" data-format-control="italic" title="Italic" aria-label="Italic">${ITALIC_ICON_HTML}</button>
-          <button type="button" data-format="strike" data-format-control="strikethrough" title="Strikethrough" aria-label="Strikethrough">${STRIKE_ICON_HTML}</button>
-          <div class="format-menu" data-format-control="headings">
-            <button type="button" class="format-menu-toggle" data-format-menu-toggle
-              aria-label="Heading" aria-haspopup="menu" aria-expanded="false">
-              ${HEADING_ICON_HTML}${CHEVRON_ICON_HTML}
-            </button>
-            <div class="format-menu-popover" data-format-menu role="menu" aria-label="Heading level" hidden>
-              <button type="button" role="menuitem" data-format="paragraph">Paragraph</button>
-              <button type="button" role="menuitem" data-format="heading-1" data-heading-level="1"><strong>H1</strong> Heading 1</button>
-              <button type="button" role="menuitem" data-format="heading-2" data-heading-level="2"><strong>H2</strong> Heading 2</button>
-              <button type="button" role="menuitem" data-format="heading-3" data-heading-level="3"><strong>H3</strong> Heading 3</button>
-              <button type="button" role="menuitem" data-format="heading-4" data-heading-level="4"><strong>H4</strong> Heading 4</button>
-              <button type="button" role="menuitem" data-format="heading-5" data-heading-level="5"><strong>H5</strong> Heading 5</button>
-              <button type="button" role="menuitem" data-format="heading-6" data-heading-level="6"><strong>H6</strong> Heading 6</button>
-            </div>
-          </div>
-        </div>
-        <span class="edit-toolbar-divider" aria-hidden="true"></span>
-        <div class="edit-toolbar-group">
-          <button type="button" data-format="bullet-list" data-format-control="bulletList" title="Bulleted list" aria-label="Bulleted list">${BULLET_LIST_ICON_HTML}</button>
-          <button type="button" data-format="ordered-list" data-format-control="orderedList" title="Numbered list" aria-label="Numbered list">${ORDERED_LIST_ICON_HTML}</button>
-          <div class="format-menu" data-format-control="code">
-            <button type="button" class="format-menu-toggle" data-format-menu-toggle
-              aria-label="Code" aria-haspopup="menu" aria-expanded="false">
-              ${CODE_ICON_HTML}${CHEVRON_ICON_HTML}
-            </button>
-            <div class="format-menu-popover" data-format-menu role="menu" aria-label="Code format" hidden>
-              <button type="button" role="menuitem" data-format="code" data-code-kind="inline">Inline code</button>
-              <button type="button" role="menuitem" data-format="code-block" data-code-kind="block">Code block</button>
-            </div>
-          </div>
-          <button type="button" data-format="quote" data-format-control="blockquote" title="Blockquote" aria-label="Blockquote">${QUOTE_ICON_HTML}</button>
-          <button type="button" data-format="line-break" data-format-control="lineBreak" title="Line break" aria-label="Line break">${LINE_BREAK_ICON_HTML}</button>
-        </div>
-        <span class="edit-toolbar-divider" aria-hidden="true"></span>
-        <div class="edit-toolbar-group">
-          <button type="button" data-format="link" data-format-control="link" title="Link" aria-label="Link">${LINK_ICON_HTML}</button>
-          <button type="button" data-format="image" data-format-control="image" title="Image" aria-label="Image">${IMAGE_FORMAT_ICON_HTML}</button>
-          <input type="file" data-ref="image-input" accept="image/*" hidden />
-        </div>
-      </div>
-    </div>
-
-    <div class="toolbar-buttons view-mode-toggle-group" data-ref="layout-controls" role="group" aria-label="Editor layout">
-      <button type="button" class="icon-toggle view-mode-toggle" data-ref="source-btn" title="Edit" aria-label="Edit" aria-pressed="false">
-        <span class="commandbar-flex-container" data-ref="source-icon">${SOURCE_EDIT_ICON_HTML}</span>
-      </button>
-      <button type="button" class="icon-toggle view-mode-toggle" data-ref="split-btn" title="Split" aria-label="Split" aria-pressed="false">
-        <span class="commandbar-flex-container">
-          ${SPLIT_ICON_HTML}
-        </span>
-      </button>
-      <button type="button" class="icon-toggle view-mode-toggle" data-ref="preview-btn" title="View" aria-label="View" aria-pressed="false">
-        <span class="commandbar-flex-container">
-          ${PREVIEW_ICON_HTML}
-        </span>
-      </button>
-    </div>
-
-    <div class="toolbar-controls" data-ref="toolbar-controls">
-      <button type="button" class="icon-toggle" data-ref="search-btn" title="Find/replace (Mod-F)" aria-label="Find/replace">
-        ${SEARCH_ICON_HTML}
-      </button>
-      <button type="button" class="icon-toggle" data-ref="save-btn" title="Save" aria-label="Save">
-        ${SAVE_ICON_HTML}
-      </button>
-      <button type="button" class="icon-toggle zoom-toggle" data-ref="zoom-btn" title="Zoom controls" aria-label="Zoom controls">
-        ${ZOOM_ICON_HTML}
-      </button>
-      <div class="theme-toggle-group" data-ref="theme-controls" role="group" aria-label="Color scheme">
-        <button type="button" class="icon-toggle theme-toggle" data-ref="dark-theme-btn"
-          title="Dark mode" aria-label="Dark mode" aria-pressed="false">
-          ${DARK_THEME_ICON_HTML}
-        </button>
-        <button type="button" class="icon-toggle theme-toggle" data-ref="light-theme-btn"
-          title="Light mode" aria-label="Light mode" aria-pressed="false">
-          ${LIGHT_THEME_ICON_HTML}
-        </button>
-      </div>
-      <div class="zoom-popover" data-ref="zoom-popover" hidden role="group" aria-label="Zoom">
-        <span class="zoom-level" data-ref="zoom-level">100%</span>
-        <span class="zoom-stepper">
-          <button type="button" data-action="zoom-out" title="Zoom out" aria-label="Zoom out">-</button>
-          <button type="button" data-action="zoom-in" title="Zoom in" aria-label="Zoom in">+</button>
-        </span>
-        <button type="button" class="zoom-reset" data-action="zoom-reset" title="Reset zoom">Reset</button>
-      </div>
-    </div>
-  </header>
-
-  <div class="workspace-shell" data-ref="workspace-shell" hidden>
-    <aside class="nav-pane" data-ref="nav-pane" aria-label="Package contents">
-      <div class="nav-tree" data-ref="nav-tree"></div>
-    </aside>
-    <div class="nav-resizer" data-ref="nav-resizer"
-      role="separator" aria-orientation="vertical" aria-label="Resize contents pane"></div>
-
-    <div class="pane-stack" data-ref="pane-stack">
-      <section class="pane edit-pane" data-ref="edit-pane">
-        <div class="editor-host" data-ref="editor-host"></div>
-      </section>
-      <div class="split-resizer" data-ref="split-resizer"
-        role="separator" aria-orientation="vertical" aria-label="Resize split panes"></div>
-      <section class="pane preview-pane" data-ref="preview-pane" tabindex="-1">
-        <article class="preview-content" data-ref="preview-content"></article>
-      </section>
-      <section class="pane entry-pane" data-ref="entry-pane"></section>
-    </div>
-  </div>
-
-  <div class="title-dialog-backdrop" data-ref="title-dialog" hidden
-    role="dialog" aria-modal="true" aria-labelledby="mdzip-title-dialog-heading">
-    <div class="title-dialog">
-      <h3 id="mdzip-title-dialog-heading">Set Document Title</h3>
-      <p>This is the package-level title stored in manifest.json.</p>
-      <input type="text" maxlength="120" data-ref="title-input" aria-label="Document title" />
-      <p class="title-dialog-validation" data-ref="title-validation" hidden>Title cannot be empty.</p>
-      <p>If unset, consumers may fall back to entry point, filename, or first heading.</p>
-      <div class="title-dialog-actions">
-        <button type="button" class="reset-title" data-ref="title-reset-btn">Reset</button>
-        <button type="button" data-action="cancel-title">Cancel</button>
-        <button type="button" class="save-title" data-ref="title-save-btn">Save</button>
-      </div>
-    </div>
-  </div>
-
-  <div class="title-dialog-backdrop" data-ref="conversion-dialog" hidden
-    role="dialog" aria-modal="true" aria-labelledby="mdzip-conversion-dialog-heading">
-    <div class="title-dialog">
-      <h3 id="mdzip-conversion-dialog-heading">Convert to MDZ?</h3>
-      <p>
-        Regular Markdown files contain only text. Convert this document to an
-        MDZ package to add images, package navigation, and document metadata.
-      </p>
-      <p>The next save will produce an .mdz file.</p>
-      <div class="title-dialog-actions">
-        <button type="button" data-action="cancel-conversion">Cancel</button>
-        <button type="button" class="save-title" data-ref="conversion-confirm-btn">Convert</button>
-      </div>
-    </div>
-  </div>
-
-  <div class="title-dialog-backdrop" data-ref="image-insert-dialog" hidden
-    role="dialog" aria-modal="true" aria-labelledby="mdzip-image-insert-dialog-heading">
-    <div class="title-dialog image-insert-dialog">
-      <h3 id="mdzip-image-insert-dialog-heading">Insert Image</h3>
-      <p>Choose the Markdown inserted for this image.</p>
-      <fieldset class="image-insert-options">
-        <legend>Output</legend>
-        <label>
-          <input type="radio" name="mdzip-image-insert-mode" value="markdown"
-            data-ref="image-insert-mode-markdown" checked />
-          Markdown image
-        </label>
-        <label>
-          <input type="radio" name="mdzip-image-insert-mode" value="html"
-            data-ref="image-insert-mode-html" />
-          HTML &lt;img&gt; with sizing
-        </label>
-      </fieldset>
-      <label class="image-insert-field">
-        <span>Alt text</span>
-        <input type="text" data-ref="image-insert-alt" />
-      </label>
-      <div class="image-insert-grid">
-        <label class="image-insert-field">
-          <span>Size by</span>
-          <select data-ref="image-insert-size-mode">
-            <option value="original">Original size</option>
-            <option value="width" selected>Width</option>
-            <option value="height">Height</option>
-            <option value="percent">Percent</option>
-          </select>
-        </label>
-        <label class="image-insert-field">
-          <span>Value</span>
-          <input type="number" min="1" step="1" data-ref="image-insert-size-value" />
-        </label>
-      </div>
-      <label class="image-insert-field">
-        <span>Position</span>
-        <select data-ref="image-insert-position">
-          <option value="inline">Inline/default</option>
-          <option value="left">Left</option>
-          <option value="center">Center</option>
-          <option value="right">Right</option>
-          <option value="wrap-left">Wrap left</option>
-          <option value="wrap-right">Wrap right</option>
-        </select>
-      </label>
-      <div class="title-dialog-actions">
-        <button type="button" data-action="cancel-image-insert">Cancel</button>
-        <button type="button" class="save-title" data-ref="image-insert-confirm-btn">Insert</button>
-      </div>
-    </div>
-  </div>
-
-  <div class="title-dialog-backdrop" data-ref="pack-files-dialog" hidden
-    role="dialog" aria-modal="true" aria-labelledby="mdzip-pack-files-dialog-heading">
-    <div class="title-dialog pack-files-dialog">
-      <h3 id="mdzip-pack-files-dialog-heading">Package Markdown Files</h3>
-      <p>These files contain more than one Markdown document. Choose how to package them.</p>
-      <fieldset class="pack-files-options">
-        <legend>Mode</legend>
-        <label>
-          <input type="radio" name="mdzip-pack-files-mode" value="document"
-            data-ref="pack-files-mode-document" checked />
-          Document — one primary page; the rest are attached
-        </label>
-        <label>
-          <input type="radio" name="mdzip-pack-files-mode" value="project"
-            data-ref="pack-files-mode-project" />
-          Project — a set of related documents
-        </label>
-      </fieldset>
-      <label class="pack-files-field">
-        <span>Entry point</span>
-        <select data-ref="pack-files-entry"></select>
-      </label>
-      <div class="title-dialog-actions">
-        <button type="button" data-action="cancel-pack-files">Cancel</button>
-        <button type="button" class="save-title" data-ref="pack-files-confirm-btn">Package</button>
-      </div>
-    </div>
-  </div>
-
-  <div class="title-dialog-backdrop" data-ref="copy-render-dialog" hidden
-    role="dialog" aria-modal="true" aria-labelledby="mdzip-copy-render-dialog-heading">
-    <div class="title-dialog copy-render-dialog">
-      <h3 id="mdzip-copy-render-dialog-heading" data-ref="copy-render-heading">Copying document...</h3>
-      <div data-ref="copy-render-progress-section">
-        <p data-ref="copy-render-progress-text">Rendering the full document...</p>
-        <div class="copy-render-progress-track">
-          <div class="copy-render-progress-bar" data-ref="copy-render-progress-bar"></div>
-        </div>
-      </div>
-      <p data-ref="copy-render-ready-text" hidden>
-        The document is ready. Browsers only allow a clipboard write right after a click, so this needs one more —
-        click Copy to finish.
-      </p>
-      <p data-ref="copy-render-done-text" hidden></p>
-      <div class="title-dialog-actions">
-        <button type="button" data-action="cancel-copy-render" data-ref="copy-render-cancel-btn">Cancel</button>
-        <button type="button" data-action="cancel-copy-ready" data-ref="copy-render-ready-cancel-btn" hidden>Cancel</button>
-        <button type="button" class="save-title" data-action="confirm-copy-ready" data-ref="copy-render-confirm-btn" hidden>Copy</button>
-        <button type="button" class="save-title" data-action="dismiss-copy-render" data-ref="copy-render-dismiss-btn" hidden>Dismiss</button>
-      </div>
-    </div>
-  </div>
-
-  <div class="title-dialog-backdrop" data-ref="metadata-dialog" hidden
-    role="dialog" aria-modal="true" aria-labelledby="mdzip-metadata-dialog-heading">
-    <div class="title-dialog metadata-dialog">
-      <h3 id="mdzip-metadata-dialog-heading">Document Information</h3>
-      <dl data-ref="metadata-list"></dl>
-      <h4>Libraries</h4>
-      <dl data-ref="library-list"></dl>
-      <div class="title-dialog-actions">
-        <button type="button" class="save-title" data-action="close-metadata">Close</button>
-      </div>
-    </div>
-  </div>
-
-  <div class="title-dialog-backdrop" data-ref="name-dialog" hidden
-    role="dialog" aria-modal="true" aria-labelledby="mdzip-name-dialog-heading">
-    <div class="title-dialog">
-      <h3 id="mdzip-name-dialog-heading" data-ref="name-dialog-heading">New Markdown File</h3>
-      <input type="text" maxlength="260" data-ref="name-input" aria-label="File name" />
-      <p class="title-dialog-validation" data-ref="name-validation" hidden></p>
-      <div class="title-dialog-actions">
-        <button type="button" data-action="cancel-name">Cancel</button>
-        <button type="button" class="save-title" data-ref="name-confirm-btn">Create</button>
-      </div>
-    </div>
-  </div>
-
-  <div class="title-dialog-backdrop" data-ref="delete-dialog" hidden
-    role="dialog" aria-modal="true" aria-labelledby="mdzip-delete-dialog-heading">
-    <div class="title-dialog">
-      <h3 id="mdzip-delete-dialog-heading">Delete File?</h3>
-      <p data-ref="delete-dialog-text"></p>
-      <div class="title-dialog-actions">
-        <button type="button" data-action="cancel-delete">Cancel</button>
-        <button type="button" class="danger-action" data-ref="delete-confirm-btn">Delete</button>
-      </div>
-    </div>
-  </div>
-
-  <input type="file" data-ref="replace-input" hidden />
-
-  <div class="nav-context-menu" data-ref="nav-menu" hidden role="menu"></div>
-
-  <div class="mdzip-tooltip" data-ref="tooltip" role="tooltip" hidden></div>
-
-  <div class="mdzip-copy-toast" data-ref="copy-toast" role="status" aria-live="polite" hidden></div>
-
-  <p class="mdzip-empty" data-ref="empty-state">No MDZip workspace loaded.</p>
-</section>
+const SHELL_HTML = `
+<section class="mdzip-root">
+  <div class="document-strip" data-ref="document-strip" hidden>
+    <button type="button" class="title-button" data-ref="title-btn"></button>
+    <button type="button" class="document-info-button" data-ref="document-info-btn"
+      title="Document information" aria-label="Document information">
+      ${INFO_ICON_HTML}
+    </button>
+  </div>
+
+  <header class="toolbar" data-ref="toolbar" hidden>
+    <div class="toolbar-start">
+      <div class="toolbar-left">
+        <button type="button" class="icon-toggle nav-toggle" data-ref="nav-btn" title="Toggle contents" aria-label="Toggle contents">
+          ${NAV_TOGGLE_ICON_HTML}
+        </button>
+      </div>
+
+      <div class="edit-toolbar" data-ref="edit-toolbar" role="toolbar" aria-label="Markdown formatting">
+        <div class="edit-toolbar-group">
+          <button type="button" data-format="bold" data-format-control="bold" title="Bold" aria-label="Bold">${BOLD_ICON_HTML}</button>
+          <button type="button" data-format="italic" data-format-control="italic" title="Italic" aria-label="Italic">${ITALIC_ICON_HTML}</button>
+          <button type="button" data-format="strike" data-format-control="strikethrough" title="Strikethrough" aria-label="Strikethrough">${STRIKE_ICON_HTML}</button>
+          <div class="format-menu" data-format-control="headings">
+            <button type="button" class="format-menu-toggle" data-format-menu-toggle
+              aria-label="Heading" aria-haspopup="menu" aria-expanded="false">
+              ${HEADING_ICON_HTML}${CHEVRON_ICON_HTML}
+            </button>
+            <div class="format-menu-popover" data-format-menu role="menu" aria-label="Heading level" hidden>
+              <button type="button" role="menuitem" data-format="paragraph">Paragraph</button>
+              <button type="button" role="menuitem" data-format="heading-1" data-heading-level="1"><strong>H1</strong> Heading 1</button>
+              <button type="button" role="menuitem" data-format="heading-2" data-heading-level="2"><strong>H2</strong> Heading 2</button>
+              <button type="button" role="menuitem" data-format="heading-3" data-heading-level="3"><strong>H3</strong> Heading 3</button>
+              <button type="button" role="menuitem" data-format="heading-4" data-heading-level="4"><strong>H4</strong> Heading 4</button>
+              <button type="button" role="menuitem" data-format="heading-5" data-heading-level="5"><strong>H5</strong> Heading 5</button>
+              <button type="button" role="menuitem" data-format="heading-6" data-heading-level="6"><strong>H6</strong> Heading 6</button>
+            </div>
+          </div>
+        </div>
+        <span class="edit-toolbar-divider" aria-hidden="true"></span>
+        <div class="edit-toolbar-group">
+          <button type="button" data-format="bullet-list" data-format-control="bulletList" title="Bulleted list" aria-label="Bulleted list">${BULLET_LIST_ICON_HTML}</button>
+          <button type="button" data-format="ordered-list" data-format-control="orderedList" title="Numbered list" aria-label="Numbered list">${ORDERED_LIST_ICON_HTML}</button>
+          <div class="format-menu" data-format-control="code">
+            <button type="button" class="format-menu-toggle" data-format-menu-toggle
+              aria-label="Code" aria-haspopup="menu" aria-expanded="false">
+              ${CODE_ICON_HTML}${CHEVRON_ICON_HTML}
+            </button>
+            <div class="format-menu-popover" data-format-menu role="menu" aria-label="Code format" hidden>
+              <button type="button" role="menuitem" data-format="code" data-code-kind="inline">Inline code</button>
+              <button type="button" role="menuitem" data-format="code-block" data-code-kind="block">Code block</button>
+            </div>
+          </div>
+          <button type="button" data-format="quote" data-format-control="blockquote" title="Blockquote" aria-label="Blockquote">${QUOTE_ICON_HTML}</button>
+          <button type="button" data-format="line-break" data-format-control="lineBreak" title="Line break" aria-label="Line break">${LINE_BREAK_ICON_HTML}</button>
+        </div>
+        <span class="edit-toolbar-divider" aria-hidden="true"></span>
+        <div class="edit-toolbar-group">
+          <button type="button" data-format="link" data-format-control="link" title="Link" aria-label="Link">${LINK_ICON_HTML}</button>
+          <button type="button" data-format="image" data-format-control="image" title="Image" aria-label="Image">${IMAGE_FORMAT_ICON_HTML}</button>
+          <input type="file" data-ref="image-input" accept="image/*" hidden />
+        </div>
+      </div>
+    </div>
+
+    <div class="toolbar-buttons view-mode-toggle-group" data-ref="layout-controls" role="group" aria-label="Editor layout">
+      <button type="button" class="icon-toggle view-mode-toggle" data-ref="source-btn" title="Edit" aria-label="Edit" aria-pressed="false">
+        <span class="commandbar-flex-container" data-ref="source-icon">${SOURCE_EDIT_ICON_HTML}</span>
+      </button>
+      <button type="button" class="icon-toggle view-mode-toggle" data-ref="split-btn" title="Split" aria-label="Split" aria-pressed="false">
+        <span class="commandbar-flex-container">
+          ${SPLIT_ICON_HTML}
+        </span>
+      </button>
+      <button type="button" class="icon-toggle view-mode-toggle" data-ref="preview-btn" title="View" aria-label="View" aria-pressed="false">
+        <span class="commandbar-flex-container">
+          ${PREVIEW_ICON_HTML}
+        </span>
+      </button>
+    </div>
+
+    <div class="toolbar-controls" data-ref="toolbar-controls">
+      <button type="button" class="icon-toggle" data-ref="search-btn" title="Find/replace (Mod-F)" aria-label="Find/replace">
+        ${SEARCH_ICON_HTML}
+      </button>
+      <button type="button" class="icon-toggle" data-ref="save-btn" title="Save" aria-label="Save">
+        ${SAVE_ICON_HTML}
+      </button>
+      <button type="button" class="icon-toggle zoom-toggle" data-ref="zoom-btn" title="Zoom controls" aria-label="Zoom controls">
+        ${ZOOM_ICON_HTML}
+      </button>
+      <div class="theme-toggle-group" data-ref="theme-controls" role="group" aria-label="Color scheme">
+        <button type="button" class="icon-toggle theme-toggle" data-ref="dark-theme-btn"
+          title="Dark mode" aria-label="Dark mode" aria-pressed="false">
+          ${DARK_THEME_ICON_HTML}
+        </button>
+        <button type="button" class="icon-toggle theme-toggle" data-ref="light-theme-btn"
+          title="Light mode" aria-label="Light mode" aria-pressed="false">
+          ${LIGHT_THEME_ICON_HTML}
+        </button>
+      </div>
+      <div class="zoom-popover" data-ref="zoom-popover" hidden role="group" aria-label="Zoom">
+        <span class="zoom-level" data-ref="zoom-level">100%</span>
+        <span class="zoom-stepper">
+          <button type="button" data-action="zoom-out" title="Zoom out" aria-label="Zoom out">-</button>
+          <button type="button" data-action="zoom-in" title="Zoom in" aria-label="Zoom in">+</button>
+        </span>
+        <button type="button" class="zoom-reset" data-action="zoom-reset" title="Reset zoom">Reset</button>
+      </div>
+    </div>
+  </header>
+
+  <div class="workspace-shell" data-ref="workspace-shell" hidden>
+    <aside class="nav-pane" data-ref="nav-pane" aria-label="Package contents">
+      <div class="nav-tree" data-ref="nav-tree"></div>
+    </aside>
+    <div class="nav-resizer" data-ref="nav-resizer"
+      role="separator" aria-orientation="vertical" aria-label="Resize contents pane"></div>
+
+    <div class="pane-stack" data-ref="pane-stack">
+      <section class="pane edit-pane" data-ref="edit-pane">
+        <div class="editor-host" data-ref="editor-host"></div>
+      </section>
+      <div class="split-resizer" data-ref="split-resizer"
+        role="separator" aria-orientation="vertical" aria-label="Resize split panes"></div>
+      <section class="pane preview-pane" data-ref="preview-pane" tabindex="-1">
+        <article class="preview-content" data-ref="preview-content"></article>
+      </section>
+      <section class="pane entry-pane" data-ref="entry-pane"></section>
+    </div>
+  </div>
+
+  <div class="title-dialog-backdrop" data-ref="title-dialog" hidden
+    role="dialog" aria-modal="true" aria-labelledby="mdzip-title-dialog-heading">
+    <div class="title-dialog">
+      <h3 id="mdzip-title-dialog-heading">Set Document Title</h3>
+      <p>This is the package-level title stored in manifest.json.</p>
+      <input type="text" maxlength="120" data-ref="title-input" aria-label="Document title" />
+      <p class="title-dialog-validation" data-ref="title-validation" hidden>Title cannot be empty.</p>
+      <p>If unset, consumers may fall back to entry point, filename, or first heading.</p>
+      <div class="title-dialog-actions">
+        <button type="button" class="reset-title" data-ref="title-reset-btn">Reset</button>
+        <button type="button" data-action="cancel-title">Cancel</button>
+        <button type="button" class="save-title" data-ref="title-save-btn">Save</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="title-dialog-backdrop" data-ref="conversion-dialog" hidden
+    role="dialog" aria-modal="true" aria-labelledby="mdzip-conversion-dialog-heading">
+    <div class="title-dialog">
+      <h3 id="mdzip-conversion-dialog-heading">Convert to MDZ?</h3>
+      <p>
+        Regular Markdown files contain only text. Convert this document to an
+        MDZ package to add images, package navigation, and document metadata.
+      </p>
+      <p>The next save will produce an .mdz file.</p>
+      <div class="title-dialog-actions">
+        <button type="button" data-action="cancel-conversion">Cancel</button>
+        <button type="button" class="save-title" data-ref="conversion-confirm-btn">Convert</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="title-dialog-backdrop" data-ref="image-insert-dialog" hidden
+    role="dialog" aria-modal="true" aria-labelledby="mdzip-image-insert-dialog-heading">
+    <div class="title-dialog image-insert-dialog">
+      <h3 id="mdzip-image-insert-dialog-heading">Insert Image</h3>
+      <p>Choose the Markdown inserted for this image.</p>
+      <fieldset class="image-insert-options">
+        <legend>Output</legend>
+        <label>
+          <input type="radio" name="mdzip-image-insert-mode" value="markdown"
+            data-ref="image-insert-mode-markdown" checked />
+          Markdown image
+        </label>
+        <label>
+          <input type="radio" name="mdzip-image-insert-mode" value="html"
+            data-ref="image-insert-mode-html" />
+          HTML &lt;img&gt; with sizing
+        </label>
+      </fieldset>
+      <label class="image-insert-field">
+        <span>Alt text</span>
+        <input type="text" data-ref="image-insert-alt" />
+      </label>
+      <div class="image-insert-grid">
+        <label class="image-insert-field">
+          <span>Size by</span>
+          <select data-ref="image-insert-size-mode">
+            <option value="original">Original size</option>
+            <option value="width" selected>Width</option>
+            <option value="height">Height</option>
+            <option value="percent">Percent</option>
+          </select>
+        </label>
+        <label class="image-insert-field">
+          <span>Value</span>
+          <input type="number" min="1" step="1" data-ref="image-insert-size-value" />
+        </label>
+      </div>
+      <label class="image-insert-field">
+        <span>Position</span>
+        <select data-ref="image-insert-position">
+          <option value="inline">Inline/default</option>
+          <option value="left">Left</option>
+          <option value="center">Center</option>
+          <option value="right">Right</option>
+          <option value="wrap-left">Wrap left</option>
+          <option value="wrap-right">Wrap right</option>
+        </select>
+      </label>
+      <div class="title-dialog-actions">
+        <button type="button" data-action="cancel-image-insert">Cancel</button>
+        <button type="button" class="save-title" data-ref="image-insert-confirm-btn">Insert</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="title-dialog-backdrop" data-ref="pack-files-dialog" hidden
+    role="dialog" aria-modal="true" aria-labelledby="mdzip-pack-files-dialog-heading">
+    <div class="title-dialog pack-files-dialog">
+      <h3 id="mdzip-pack-files-dialog-heading">Package Markdown Files</h3>
+      <p>These files contain more than one Markdown document. Choose how to package them.</p>
+      <fieldset class="pack-files-options">
+        <legend>Mode</legend>
+        <label>
+          <input type="radio" name="mdzip-pack-files-mode" value="document"
+            data-ref="pack-files-mode-document" checked />
+          Document — one primary page; the rest are attached
+        </label>
+        <label>
+          <input type="radio" name="mdzip-pack-files-mode" value="project"
+            data-ref="pack-files-mode-project" />
+          Project — a set of related documents
+        </label>
+      </fieldset>
+      <label class="pack-files-field">
+        <span>Entry point</span>
+        <select data-ref="pack-files-entry"></select>
+      </label>
+      <div class="title-dialog-actions">
+        <button type="button" data-action="cancel-pack-files">Cancel</button>
+        <button type="button" class="save-title" data-ref="pack-files-confirm-btn">Package</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="title-dialog-backdrop" data-ref="copy-render-dialog" hidden
+    role="dialog" aria-modal="true" aria-labelledby="mdzip-copy-render-dialog-heading">
+    <div class="title-dialog copy-render-dialog">
+      <h3 id="mdzip-copy-render-dialog-heading" data-ref="copy-render-heading">Copying document...</h3>
+      <div data-ref="copy-render-progress-section">
+        <p data-ref="copy-render-progress-text">Rendering the full document...</p>
+        <div class="copy-render-progress-track">
+          <div class="copy-render-progress-bar" data-ref="copy-render-progress-bar"></div>
+        </div>
+      </div>
+      <p data-ref="copy-render-ready-text" hidden>
+        The document is ready. Browsers only allow a clipboard write right after a click, so this needs one more —
+        click Copy to finish.
+      </p>
+      <p data-ref="copy-render-done-text" hidden></p>
+      <div class="title-dialog-actions">
+        <button type="button" data-action="cancel-copy-render" data-ref="copy-render-cancel-btn">Cancel</button>
+        <button type="button" data-action="cancel-copy-ready" data-ref="copy-render-ready-cancel-btn" hidden>Cancel</button>
+        <button type="button" class="save-title" data-action="confirm-copy-ready" data-ref="copy-render-confirm-btn" hidden>Copy</button>
+        <button type="button" class="save-title" data-action="dismiss-copy-render" data-ref="copy-render-dismiss-btn" hidden>Dismiss</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="title-dialog-backdrop" data-ref="metadata-dialog" hidden
+    role="dialog" aria-modal="true" aria-labelledby="mdzip-metadata-dialog-heading">
+    <div class="title-dialog metadata-dialog">
+      <h3 id="mdzip-metadata-dialog-heading">Document Information</h3>
+      <dl data-ref="metadata-list"></dl>
+      <h4>Libraries</h4>
+      <dl data-ref="library-list"></dl>
+      <div class="title-dialog-actions">
+        <button type="button" class="save-title" data-action="close-metadata">Close</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="title-dialog-backdrop" data-ref="name-dialog" hidden
+    role="dialog" aria-modal="true" aria-labelledby="mdzip-name-dialog-heading">
+    <div class="title-dialog">
+      <h3 id="mdzip-name-dialog-heading" data-ref="name-dialog-heading">New Markdown File</h3>
+      <input type="text" maxlength="260" data-ref="name-input" aria-label="File name" />
+      <p class="title-dialog-validation" data-ref="name-validation" hidden></p>
+      <div class="title-dialog-actions">
+        <button type="button" data-action="cancel-name">Cancel</button>
+        <button type="button" class="save-title" data-ref="name-confirm-btn">Create</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="title-dialog-backdrop" data-ref="delete-dialog" hidden
+    role="dialog" aria-modal="true" aria-labelledby="mdzip-delete-dialog-heading">
+    <div class="title-dialog">
+      <h3 id="mdzip-delete-dialog-heading">Delete File?</h3>
+      <p data-ref="delete-dialog-text"></p>
+      <div class="title-dialog-actions">
+        <button type="button" data-action="cancel-delete">Cancel</button>
+        <button type="button" class="danger-action" data-ref="delete-confirm-btn">Delete</button>
+      </div>
+    </div>
+  </div>
+
+  <input type="file" data-ref="replace-input" hidden />
+
+  <div class="nav-context-menu" data-ref="nav-menu" hidden role="menu"></div>
+
+  <div class="mdzip-tooltip" data-ref="tooltip" role="tooltip" hidden></div>
+
+  <div class="mdzip-copy-toast" data-ref="copy-toast" role="status" aria-live="polite" hidden></div>
+
+  <p class="mdzip-empty" data-ref="empty-state">No MDZip workspace loaded.</p>
+</section>
 `;
 //# sourceMappingURL=view.js.map