@mdzip/editor 1.4.0 → 1.4.5

package/dist/view.js

@@ -12,9 +12,10 @@ import { MdzipAssetSession, mdzipArchiveSourceId, sniffImageSize } from './asset
 import { MD_MARKDOWN_ICON } from './icons/md-markdown.js';
 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 { buildMdzipNavTree, canEditMdzipPath, escapeHtml, isOrphanedMdzipAsset, mdzipEntryIconKind, isMdzipManifestPath, isMdzipWorkspaceRelativeLink, 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, collectMdzipHeadingIds, MDZIP_HEADING_ID_PREFIX, 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;
@@ -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,56 @@ 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;
+        // A #fragment from a link into another document (`other.md#heading`), held
+        // until that document's preview has mounted so there is a heading to scroll
+        // to. Consumed by firePreviewRendered.
+        this.pendingAnchorFragment = 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 +1017,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 +1052,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 +1469,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 +1627,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 +1662,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 +1685,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 +1743,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 +1827,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 +1847,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 +1876,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 +2061,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, middleEnd);
+            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 +2271,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 +2394,12 @@ 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, 
+    // Exclusive upper bound. Reconciliation mounts just its replacement
+    // "middle"; the records after it are surviving suffix chunks that are
+    // already in the DOM, and running on into them would mount each a second
+    // time (orphaning the first copy's root, which nothing would ever remove).
+    endCursor = records.length) {
         const BATCH_CHAR_BUDGET = 4000;
         const BATCH_TIME_BUDGET_MS = 10;
         const clock = this.elPreviewContent.ownerDocument.defaultView?.performance ?? performance;
@@ -1972,12 +2407,13 @@ export class MdzipWorkspaceView {
         let cursor = startCursor;
         let renderedChars = 0;
         const mountedRoots = [];
-        while (cursor < chunks.length
+        const batchStartCursor = startCursor;
+        while (cursor < Math.min(endCursor, 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 +2447,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 +2473,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 +2508,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 +2638,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 +2659,7 @@ export class MdzipWorkspaceView {
                             }
                             return;
                         }
-                        this.previewHandles.push(handle);
+                        collector.push(handle);
                     }).catch((error) => {
                         if (generation === this.previewGeneration) {
                             this.options.onFailed?.(error);
@@ -2198,7 +2667,7 @@ export class MdzipWorkspaceView {
                     });
                 }
                 else if (mounted) {
-                    this.previewHandles.push(mounted);
+                    collector.push(mounted);
                 }
             }
             catch (error) {
@@ -2337,6 +2806,8 @@ export class MdzipWorkspaceView {
         if (generation !== this.previewGeneration) {
             return;
         }
+        this.restorePendingPreviewScroll(generation);
+        this.flushPendingAnchorSoon();
         try {
             this.options.onPreviewRendered?.(snapshot);
         }
@@ -2344,6 +2815,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 +3133,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) => {
@@ -3331,7 +3829,27 @@ export class MdzipWorkspaceView {
             const clampedTop = Math.max(margin, Math.min(naturalTop, win.innerHeight - margin - submenu.offsetHeight));
             submenu.style.top = `${clampedTop - rect.top}px`;
         });
+        // Chromium treats a Shift+mousedown as "extend the selection", right
+        // button included, so Shift+right-click would first stretch the selection
+        // from the caret to the click — and the native menu reports no misspelled
+        // word (hence no suggestions) unless the selection is collapsed or just
+        // the word. Cancelling that mousedown leaves the selection alone and lets
+        // the browser resolve the word under the pointer itself. Capture phase so
+        // it runs before CodeMirror's own handlers; focus is restored by hand
+        // since the cancelled mousedown no longer moves it.
+        this.elEditorHost.addEventListener('mousedown', (e) => {
+            if (e.button === 2 && e.shiftKey) {
+                e.preventDefault();
+                this.cmEditor?.focus();
+            }
+        }, true);
         this.elEditorHost.addEventListener('contextmenu', (e) => {
+            // Shift+right-click bypasses our own formatting menu so the host's
+            // native context menu (spell-check suggestions, etc.) shows instead —
+            // without this, preventDefault() below suppresses it unconditionally.
+            if (e.shiftKey) {
+                return;
+            }
             if (!this.controlPolicy.contextMenu.editor) {
                 return;
             }
@@ -3421,6 +3939,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
@@ -3434,12 +3957,24 @@ export class MdzipWorkspaceView {
             if (!link || !snapshot) {
                 return;
             }
-            const targetPath = resolveMdzipArchiveLinkTarget(link.getAttribute('href') ?? '', snapshot.currentPath, snapshot.content.paths);
-            if (!targetPath) {
+            const href = link.getAttribute('href') ?? '';
+            if (href.startsWith('#')) {
+                event.preventDefault();
+                void this.scrollPreviewToAnchor(href.slice(1));
                 return;
             }
-            event.preventDefault();
-            void this.openPath(targetPath);
+            const targetPath = resolveMdzipArchiveLinkTarget(href, snapshot.currentPath, snapshot.content.paths);
+            if (targetPath) {
+                event.preventDefault();
+                const hashIndex = href.indexOf('#');
+                const fragment = hashIndex >= 0 ? href.slice(hashIndex + 1) : '';
+                void this.openPathAndScrollToAnchor(targetPath, fragment);
+                return;
+            }
+            if (this.options.onUnresolvedLinkClick && isMdzipWorkspaceRelativeLink(href)) {
+                event.preventDefault();
+                this.options.onUnresolvedLinkClick(href, snapshot);
+            }
         });
         this.elRoot.addEventListener('pointerover', (event) => this.handleTooltipPointer(event));
         this.elRoot.addEventListener('pointerout', (event) => {
@@ -3473,6 +4008,99 @@ export class MdzipWorkspaceView {
             element.removeAttribute('title');
         });
     }
+    async openPathAndScrollToAnchor(path, fragment) {
+        const generationBefore = this.previewGeneration;
+        this.pendingAnchorFragment = fragment || null;
+        await this.openPath(path);
+        // No new render started (already on that document, or the open failed):
+        // nothing will call firePreviewRendered, so apply the anchor now.
+        if (this.pendingAnchorFragment !== null && this.previewGeneration === generationBefore) {
+            const pending = this.pendingAnchorFragment;
+            this.pendingAnchorFragment = null;
+            await this.scrollPreviewToAnchor(pending);
+        }
+    }
+    // Deferred a frame: firePreviewRendered runs inside the first chunk batch's
+    // completion callback, before the lazy-continuation sentinel for the rest is
+    // armed. Scrolling then (which may need to drain those chunks) would race it.
+    flushPendingAnchorSoon() {
+        if (this.pendingAnchorFragment === null) {
+            return;
+        }
+        const generation = this.previewGeneration;
+        requestAnimationFrame(() => {
+            if (generation !== this.previewGeneration || this.pendingAnchorFragment === null) {
+                return;
+            }
+            const pending = this.pendingAnchorFragment;
+            this.pendingAnchorFragment = null;
+            void this.scrollPreviewToAnchor(pending);
+        });
+    }
+    findPreviewAnchor(fragment) {
+        const wanted = new Set([fragment, MDZIP_HEADING_ID_PREFIX + fragment]);
+        const wantedLower = new Set([...wanted].map((value) => value.toLowerCase()));
+        let caseInsensitiveMatch = null;
+        for (const element of Array.from(this.elPreviewContent.querySelectorAll('[id],[name]'))) {
+            for (const value of [element.getAttribute('id'), element.getAttribute('name')]) {
+                if (!value)
+                    continue;
+                if (wanted.has(value))
+                    return element;
+                if (!caseInsensitiveMatch && wantedLower.has(value.toLowerCase()))
+                    caseInsensitiveMatch = element;
+            }
+        }
+        return caseInsensitiveMatch;
+    }
+    recordMayContainAnchor(record, fragment) {
+        const lower = fragment.toLowerCase();
+        if (collectMdzipHeadingIds(record.tokens).some((id) => id.toLowerCase() === lower)) {
+            return true;
+        }
+        // An explicit <a id="x"> / <a name="x"> anchor written in the source.
+        const escaped = fragment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp(`(?:id|name)\\s*=\\s*["']${escaped}["']`, 'i').test(record.key);
+    }
+    /**
+     * Scrolls the preview to the heading (or explicit id/name anchor) a
+     * `#fragment` link names. Under progressive rendering the target may sit in
+     * a chunk that hasn't been mounted yet, so this mounts everything up to and
+     * including that chunk first. Returns whether an anchor was found.
+     */
+    async scrollPreviewToAnchor(rawFragment) {
+        let fragment = rawFragment;
+        try {
+            fragment = decodeURIComponent(rawFragment);
+        }
+        catch {
+            // Malformed escape — use it as written.
+        }
+        let target = fragment ? this.findPreviewAnchor(fragment) : null;
+        const pending = this.chunkedRenderState;
+        if (!target && fragment && pending && pending.cursor < pending.records.length) {
+            const index = pending.records.findIndex((record, i) => i >= pending.cursor && this.recordMayContainAnchor(record, fragment));
+            if (index >= 0) {
+                await this.drainRemainingChunks(pending, () => { }, new AbortController().signal, index);
+                const remaining = this.chunkedRenderState;
+                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);
+                }
+                target = this.findPreviewAnchor(fragment);
+            }
+        }
+        const pane = this.elPreviewPane;
+        if (!target) {
+            // `#` and `#top` mean the top of the document, as in a browser.
+            if (!fragment || fragment.toLowerCase() === 'top') {
+                pane.scrollTop = 0;
+            }
+            return false;
+        }
+        pane.scrollTop += target.getBoundingClientRect().top - pane.getBoundingClientRect().top;
+        return true;
+    }
     async openPath(path) {
         if (!this.workspace) {
             return;
@@ -4240,7 +4868,7 @@ export class MdzipWorkspaceView {
         // spelling suggestions live — there's no API to read the browser's
         // dictionary suggestions into a custom menu. Point at the escape hatch
         // instead of silently dropping the feature.
-        if (editable) {
+        if (editable && this.options.showSpellingSuggestionsHint !== false) {
             groups.push([{
                     action: 'editor-spelling-suggestions-hint',
                     label: 'Spelling Suggestions',
@@ -4460,20 +5088,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 +5133,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 +5177,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;
@@ -4760,33 +5391,42 @@ export class MdzipWorkspaceView {
      * pass over every image at the end avoids the pile-up entirely, without
      * making Copy All wait on it.
      */
-    async drainRemainingChunks(state, onProgress, signal) {
-        const { chunks, context, generation, animateImageHydration } = state;
+    async drainRemainingChunks(state, onProgress, signal, stopAfterRecordIndex) {
+        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
+                && (stopAfterRecordIndex === undefined || this.chunkedRenderState.cursor <= stopAfterRecordIndex)) {
                 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 +6397,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 +6433,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 +6465,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 +6524,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 {