@mdzip/editor 1.4.8 → 1.5.0

package/dist/view.js

@@ -12,7 +12,7 @@ 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, isMdzipWorkspaceRelativeLink, resolveMdzipArchiveLinkTarget, renderMdzipPreviewHtml } from './workspace-view.js';
+import { buildMdzipNavTree, canEditMdzipPath, escapeHtml, isOrphanedMdzipAsset, mdzipEntryIconKind, isMdzipManifestPath, isMdzipDefaultPolicyExternalLink, isMdzipExternalLink, isMdzipWorkspaceRelativeLink, parseMdzipLink, renderMdzipPreviewHtml } from './workspace-view.js';
 import { escapeMarkdownImageAlt, findImageReferenceAtOffset, formatImageEditMarkdown } from './image-edit.js';
 import { MdzipRenderingService, defaultSafeMarkdownRenderer, groupTokensIntoChunks, chunkSourceKey, collectMdzipHeadingIds, MDZIP_HEADING_ID_PREFIX, tokenEmbedsImage, tokenIsHeading } from './rendering.js';
 import { mdzipFrontMatterExtension } from './front-matter-extension.js';
@@ -23,6 +23,14 @@ const isImageFile = (path) => IMAGE_EXTENSIONS.test(path);
 function isThenable(value) {
     return typeof value?.then === 'function';
 }
+function restoreAttribute(element, name, value) {
+    if (value === null) {
+        element.removeAttribute(name);
+    }
+    else {
+        element.setAttribute(name, value);
+    }
+}
 const NAV_ICON_CLASS = 'nav-lucide-icon';
 const TOOLBAR_ICON_CLASS = 'toggle-icon';
 const MANIFEST_ICON_HTML = lucideIcon(FileBraces, NAV_ICON_CLASS);
@@ -1006,6 +1014,21 @@ export class MdzipWorkspaceView {
         // until that document's preview has mounted so there is a heading to scroll
         // to. Consumed by firePreviewRendered.
         this.pendingAnchorFragment = null;
+        // The previewGeneration whose preview last mounted (or was claimed by an
+        // entry renderer); scrollToAnchor() waits until it catches up.
+        this.previewMountedGeneration = -1;
+        this.previewMountWaiters = [];
+        // True while onPreviewRendered runs — see scrollToAnchor().
+        this.firingPreviewRendered = false;
+        this.destroyed = false;
+        // After an anchor scroll, content above the target can still change height
+        // (images loading or easing open, a diagram rendering) and push it out of
+        // view. This holds the target at the pane's top edge until the user
+        // scrolls either pane or the preview re-renders.
+        this.anchorPin = null;
+        // Each link's own target/rel from before the external-link policy touched
+        // it, so a policy change can restore them before re-applying.
+        this.externalLinkOriginals = new WeakMap();
         // 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
@@ -1442,6 +1465,9 @@ export class MdzipWorkspaceView {
         this.teardownEntryRenderer();
         // Release any whenRendered() waiters so their promises do not hang.
         this.flushRenderedWaiters();
+        this.destroyed = true;
+        this.markPreviewMounted();
+        this.releaseAnchorPin();
         try {
             this.workspace?.dispose();
         }
@@ -1594,6 +1620,54 @@ export class MdzipWorkspaceView {
     setImageEditOptions(options) {
         this.options.imageEditHandler = options.imageEditHandler;
     }
+    /**
+     * Replaces the external-link rendering policy and re-applies it to the
+     * links already in the preview, without re-rendering. `undefined` restores
+     * every link's own `target`/`rel`.
+     */
+    setExternalLinks(policy) {
+        this.options.externalLinks = policy;
+        this.applyExternalLinkPolicy(this.elPreviewContent);
+    }
+    applyExternalLinkPolicy(root) {
+        const policy = this.options.externalLinks;
+        for (const link of Array.from(root.querySelectorAll('a[href]'))) {
+            const original = this.externalLinkOriginals.get(link);
+            if (original) {
+                this.externalLinkOriginals.delete(link);
+                restoreAttribute(link, 'target', original.target);
+                restoreAttribute(link, 'rel', original.rel);
+            }
+            if (!policy) {
+                continue;
+            }
+            const rel = policy.rel ?? (policy.target === '_blank' ? 'noopener noreferrer' : undefined);
+            if (policy.target === undefined && rel === undefined) {
+                continue;
+            }
+            const href = link.getAttribute('href') ?? '';
+            if (!isMdzipExternalLink(href)) {
+                continue;
+            }
+            let external = false;
+            try {
+                external = policy.predicate ? policy.predicate(href) : isMdzipDefaultPolicyExternalLink(href);
+            }
+            catch (error) {
+                this.options.onFailed?.(error);
+            }
+            if (!external) {
+                continue;
+            }
+            this.externalLinkOriginals.set(link, { target: link.getAttribute('target'), rel: link.getAttribute('rel') });
+            if (policy.target !== undefined) {
+                link.setAttribute('target', policy.target);
+            }
+            if (rel !== undefined) {
+                link.setAttribute('rel', rel);
+            }
+        }
+    }
     applyDensityClasses() {
         this.elRoot.classList.remove('toolbar-density-comfortable', 'toolbar-density-compact', 'toolbar-density-dense', 'content-density-comfortable', 'content-density-compact');
         this.elRoot.classList.add(`toolbar-density-${this.toolbarDensity}`);
@@ -1681,6 +1755,7 @@ export class MdzipWorkspaceView {
             // There is no built-in preview to wait for; release any waiters.
             this.previewHydrated = true;
             this.flushRenderedWaiters();
+            this.markPreviewMounted();
             return;
         }
         const memo = this.previewMemo;
@@ -1816,6 +1891,7 @@ export class MdzipWorkspaceView {
         if (codeBlockHandle) {
             this.previewHandles.push(codeBlockHandle);
         }
+        this.applyExternalLinkPolicy(this.elPreviewContent);
         // No archive images to resolve on this path: the preview is ready now.
         this.firePreviewRendered(snapshot, generation);
         this.fireAssetsHydrated(snapshot, generation);
@@ -1838,6 +1914,7 @@ export class MdzipWorkspaceView {
         if (codeBlockHandle) {
             this.previewHandles.push(codeBlockHandle);
         }
+        this.applyExternalLinkPolicy(this.elPreviewContent);
         this.firePreviewRendered(snapshot, generation);
         this.hydrateImages(pending, context, generation, animateImageHydration, () => {
             this.fireAssetsHydrated(snapshot, generation);
@@ -2466,6 +2543,7 @@ export class MdzipWorkspaceView {
             if (codeBlockHandle) {
                 record.handles.push(codeBlockHandle);
             }
+            this.applyExternalLinkPolicy(record.root);
         }
         return { cursor, mountedRoots };
     }
@@ -2813,12 +2891,26 @@ export class MdzipWorkspaceView {
         }
         this.restorePendingPreviewScroll(generation);
         this.flushPendingAnchorSoon();
+        this.markPreviewMounted();
+        this.firingPreviewRendered = true;
         try {
             this.options.onPreviewRendered?.(snapshot);
         }
         catch (error) {
             this.options.onFailed?.(error);
         }
+        finally {
+            this.firingPreviewRendered = false;
+        }
+    }
+    /** Releases {@link scrollToAnchor} calls waiting for the current preview to mount. */
+    markPreviewMounted() {
+        this.previewMountedGeneration = this.previewGeneration;
+        const waiters = this.previewMountWaiters;
+        this.previewMountWaiters = [];
+        for (const resolve of waiters) {
+            resolve();
+        }
     }
     /** See `pendingPreviewScrollRestore`'s doc comment. */
     restorePendingPreviewScroll(generation) {
@@ -3147,7 +3239,10 @@ export class MdzipWorkspaceView {
             // 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(); };
+            const markEditorGesture = () => {
+                self.lastEditorGestureTime = performance.now();
+                self.releaseAnchorPin();
+            };
             scroller.addEventListener('wheel', markEditorGesture, { passive: true });
             scroller.addEventListener('touchstart', markEditorGesture, { passive: true });
             scroller.addEventListener('mousedown', markEditorGesture);
@@ -3944,7 +4039,10 @@ export class MdzipWorkspaceView {
                 void this.replaceFileFromPicker(path, file);
             }
         });
-        const markPreviewGesture = () => { this.lastPreviewGestureTime = performance.now(); };
+        const markPreviewGesture = () => {
+            this.lastPreviewGestureTime = performance.now();
+            this.releaseAnchorPin();
+        };
         this.elPreviewPane.addEventListener('wheel', markPreviewGesture, { passive: true });
         this.elPreviewPane.addEventListener('touchstart', markPreviewGesture, { passive: true });
         this.elPreviewPane.addEventListener('mousedown', markPreviewGesture);
@@ -3963,17 +4061,20 @@ export class MdzipWorkspaceView {
                 return;
             }
             const href = link.getAttribute('href') ?? '';
+            const parsed = parseMdzipLink(href, snapshot.currentPath, snapshot.content.paths);
+            if (this.options.onLinkActivated && this.dispatchLinkActivated(event, link, href, parsed, snapshot)) {
+                return;
+            }
             if (href.startsWith('#')) {
                 event.preventDefault();
                 void this.scrollPreviewToAnchor(href.slice(1));
                 return;
             }
-            const targetPath = resolveMdzipArchiveLinkTarget(href, snapshot.currentPath, snapshot.content.paths);
-            if (targetPath) {
+            if (parsed.targetPath) {
                 event.preventDefault();
                 const hashIndex = href.indexOf('#');
                 const fragment = hashIndex >= 0 ? href.slice(hashIndex + 1) : '';
-                void this.openPathAndScrollToAnchor(targetPath, fragment);
+                void this.openPathAndScrollToAnchor(parsed.targetPath, fragment);
                 return;
             }
             if (this.options.onUnresolvedLinkClick && isMdzipWorkspaceRelativeLink(href)) {
@@ -4025,6 +4126,132 @@ export class MdzipWorkspaceView {
             await this.scrollPreviewToAnchor(pending);
         }
     }
+    /** Returns true when the host prevented the click, ending all further handling. */
+    dispatchLinkActivated(domEvent, link, href, parsed, snapshot) {
+        let prevented = false;
+        const event = {
+            href,
+            text: (link.textContent ?? '').trim(),
+            kind: parsed.kind,
+            isExternal: parsed.kind === 'external',
+            isAnchor: parsed.kind === 'anchor',
+            path: parsed.path,
+            anchor: parsed.anchor,
+            sourcePath: snapshot.currentPath,
+            targetPath: parsed.targetPath,
+            ctrlKey: domEvent.ctrlKey,
+            metaKey: domEvent.metaKey,
+            shiftKey: domEvent.shiftKey,
+            altKey: domEvent.altKey,
+            domEvent,
+            snapshot,
+            preventDefault: () => {
+                prevented = true;
+            },
+            get defaultPrevented() {
+                return prevented;
+            }
+        };
+        try {
+            this.options.onLinkActivated?.(event);
+        }
+        catch (error) {
+            this.options.onFailed?.(error);
+        }
+        if (prevented) {
+            domEvent.preventDefault();
+        }
+        return prevented;
+    }
+    /**
+     * Scrolls the preview to a heading or an explicit `id`/`name` anchor.
+     * Accepts the fragment with or without its leading `#` and matches it the
+     * way a clicked `#fragment` link does: case-insensitive, percent-decoded,
+     * against both bare and `user-content-`-prefixed heading ids.
+     *
+     * Safe to call at any point — straight after `open()`/`openWorkspace()`,
+     * or from `onPreviewRendered`: it waits for the current document's
+     * preview to mount, and under progressive rendering mounts the chunks up
+     * to the target first. Resolves `true` when it scrolled to a matching
+     * anchor (`''` and `'top'` scroll to the top and resolve `true`), and
+     * `false` when nothing matches, an entry renderer owns the pane, or the
+     * view is destroyed first.
+     */
+    async scrollToAnchor(anchor) {
+        const fragment = anchor.startsWith('#') ? anchor.slice(1) : anchor;
+        // onPreviewRendered runs inside the first chunk batch's completion,
+        // before the lazy-continuation sentinel is armed — same race as
+        // flushPendingAnchorSoon, so a call from it (or one that had to wait for
+        // the mount) is deferred a frame.
+        let deferFrame = this.firingPreviewRendered;
+        while (!this.destroyed && this.previewMountedGeneration !== this.previewGeneration) {
+            deferFrame = true;
+            await new Promise((resolve) => this.previewMountWaiters.push(resolve));
+        }
+        if (this.destroyed) {
+            return false;
+        }
+        if (deferFrame) {
+            const generation = this.previewGeneration;
+            await new Promise((resolve) => requestAnimationFrame(() => resolve()));
+            if (this.destroyed) {
+                return false;
+            }
+            if (generation !== this.previewGeneration) {
+                return this.scrollToAnchor(anchor);
+            }
+        }
+        if (this.entryState) {
+            return false;
+        }
+        const found = await this.scrollPreviewToAnchor(fragment);
+        return found || !fragment || fragment.toLowerCase() === 'top';
+    }
+    /**
+     * The anchors {@link scrollToAnchor} can reach in the current preview, in
+     * document order: every heading id (without the `user-content-` prefix),
+     * including headings in chunks progressive rendering hasn't mounted yet,
+     * plus explicit `id`/`name` anchors on links in the mounted preview.
+     * Empty before the preview first mounts.
+     */
+    getAvailableAnchors() {
+        if (this.entryState) {
+            return [];
+        }
+        const anchors = [];
+        const seen = new Set();
+        const add = (value) => {
+            if (!value)
+                return;
+            const bare = value.startsWith(MDZIP_HEADING_ID_PREFIX) ? value.slice(MDZIP_HEADING_ID_PREFIX.length) : value;
+            if (bare && !seen.has(bare)) {
+                seen.add(bare);
+                anchors.push(bare);
+            }
+        };
+        const fromDom = (root) => {
+            for (const element of Array.from(root.querySelectorAll('h1[id],h2[id],h3[id],h4[id],h5[id],h6[id],a[id],a[name]'))) {
+                add(element.getAttribute('id'));
+                add(element.getAttribute('name'));
+            }
+        };
+        const state = this.chunkedRenderState;
+        if (state && state.generation === this.previewGeneration) {
+            // Walk records in order so unmounted chunks' headings land in place.
+            state.records.forEach((record) => {
+                if (record.root) {
+                    fromDom(record.root);
+                }
+                else {
+                    collectMdzipHeadingIds(record.tokens).forEach(add);
+                }
+            });
+        }
+        else {
+            fromDom(this.elPreviewContent);
+        }
+        return anchors;
+    }
     // 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.
@@ -4103,9 +4330,35 @@ export class MdzipWorkspaceView {
             }
             return false;
         }
-        pane.scrollTop += target.getBoundingClientRect().top - pane.getBoundingClientRect().top;
+        this.scrollPaneToElement(target);
+        this.pinPreviewAnchor(target);
         return true;
     }
+    scrollPaneToElement(target) {
+        const pane = this.elPreviewPane;
+        pane.scrollTop += target.getBoundingClientRect().top - pane.getBoundingClientRect().top;
+    }
+    /** See `anchorPin`. */
+    pinPreviewAnchor(target) {
+        this.releaseAnchorPin();
+        if (typeof ResizeObserver === 'undefined') {
+            return;
+        }
+        const generation = this.previewGeneration;
+        const observer = new ResizeObserver(() => {
+            if (generation !== this.previewGeneration || !target.isConnected) {
+                this.releaseAnchorPin();
+                return;
+            }
+            this.scrollPaneToElement(target);
+        });
+        observer.observe(this.elPreviewContent);
+        this.anchorPin = observer;
+    }
+    releaseAnchorPin() {
+        this.anchorPin?.disconnect();
+        this.anchorPin = null;
+    }
     async openPath(path) {
         if (!this.workspace) {
             return;