@mdzip/editor 1.3.1 → 1.3.11

package/dist/view.js

@@ -6,13 +6,19 @@ import { EditorView, dropCursor, keymap, lineNumbers } from '@codemirror/view';
 import { tags } from '@lezer/highlight';
 import { Bold, ChevronDown, Code, Columns2, Eye, File, FileBraces, FileImage, Folder, FolderOpen, Hash, Heading1, ImagePlus, Info, Italic, Link2Off, Link, List, ListOrdered, Moon, PanelLeft, Quote, Save, SquarePen, Strikethrough, Sun, ZoomIn } from 'lucide';
 import { browserClipboardHasImage, readBrowserClipboardImage } from './browser.js';
+import { MdzipAssetSession, mdzipArchiveSourceId } from './asset-cache.js';
 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 { MdzipRenderingService, defaultSafeMarkdownRenderer } from './rendering.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;
 const isImageFile = (path) => IMAGE_EXTENSIONS.test(path);
+function isThenable(value) {
+    return typeof value?.then === 'function';
+}
 const NAV_ICON_CLASS = 'nav-lucide-icon';
 const TOOLBAR_ICON_CLASS = 'toggle-icon';
 const MANIFEST_ICON_HTML = lucideIcon(FileBraces, NAV_ICON_CLASS);
@@ -396,6 +402,7 @@ function navNodeOrder(a, b) {
 export class MdzipWorkspaceView {
     constructor(container, options = {}) {
         this.workspace = null;
+        this.assetSession = null;
         this.unsub = null;
         this.layout = 'split';
         this.navVisible = true;
@@ -414,6 +421,12 @@ export class MdzipWorkspaceView {
         this.pendingNewFolders = new Set();
         this.pendingReplacePath = null;
         this.conversionHookPending = false;
+        this.conversionDocumentGeneration = 0;
+        // Monotonic token bumped on every openArchive/openWorkspace call. The async
+        // parse for a superseded call must not win the race and overwrite the latest
+        // input, so each call captures its token and discards its result once a newer
+        // open has started.
+        this.openGeneration = 0;
         this.dragSourcePath = null;
         this.dragOverElement = null;
         this.tooltipState = null;
@@ -423,6 +436,25 @@ export class MdzipWorkspaceView {
         this.readOnlyCompartment = new Compartment();
         this.updatingCm = false;
         this.syncing = false;
+        this.markdownExtensions = [];
+        this.entryRenderers = [];
+        this.renderingService = new MdzipRenderingService();
+        // Preview render memo: the preview pipeline only re-runs when one of these
+        // inputs actually changed, so unrelated snapshot renders (dialogs, nav,
+        // layout toggles) never reset preview DOM or re-run extension mounts.
+        this.previewMemo = null;
+        this.previewGeneration = 0;
+        this.previewAbort = null;
+        this.previewHandles = [];
+        // Whether the latest preview generation has finished mounting and hydrating
+        // its images; drives `whenRendered()` and gates the hydration callback.
+        this.previewHydrated = false;
+        this.renderedWaiters = [];
+        this.entryState = null;
+        // Negative match cache: with only non-matching renderers registered,
+        // matches() does not re-run on every snapshot render of the same entry.
+        this.entryMatchMissKey = null;
+        this.entryGeneration = 0;
         this.options = options;
         this.controlPolicy = resolveMdzipControlPolicy(options.controls);
         this.navigationMode = options.navigationMode ?? 'editor';
@@ -432,6 +464,10 @@ export class MdzipWorkspaceView {
                 ? 'dark'
                 : 'light');
         this.navVisible = options.navigationButtonActive ?? this.navVisible;
+        this.markdownRenderer = options.markdownRenderer;
+        this.markdownExtensions = options.markdownExtensions ?? [];
+        this.entryRenderers = options.entryRenderers ?? [];
+        this.renderingService = new MdzipRenderingService(this.markdownRenderer ?? defaultSafeMarkdownRenderer, this.markdownExtensions);
         injectStyles(container.ownerDocument);
         container.replaceChildren();
         container.innerHTML = SHELL_HTML;
@@ -468,6 +504,7 @@ export class MdzipWorkspaceView {
         this.elSplitResizer = q('[data-ref="split-resizer"]');
         this.elPreviewPane = q('[data-ref="preview-pane"]');
         this.elPreviewContent = q('[data-ref="preview-content"]');
+        this.elEntryPane = q('[data-ref="entry-pane"]');
         this.elTitleDialog = q('[data-ref="title-dialog"]');
         this.elTitleInput = q('[data-ref="title-input"]');
         this.elTitleValidation = q('[data-ref="title-validation"]');
@@ -475,6 +512,7 @@ export class MdzipWorkspaceView {
         this.elTitleResetBtn = q('[data-ref="title-reset-btn"]');
         this.elMetadataDialog = q('[data-ref="metadata-dialog"]');
         this.elMetadataList = q('[data-ref="metadata-list"]');
+        this.elLibraryList = q('[data-ref="library-list"]');
         this.elConversionDialog = q('[data-ref="conversion-dialog"]');
         this.elConversionConfirmBtn = q('[data-ref="conversion-confirm-btn"]');
         this.elNavMenu = q('[data-ref="nav-menu"]');
@@ -504,20 +542,47 @@ export class MdzipWorkspaceView {
         await this.openArchive(bytes, options);
     }
     async openArchive(bytes, options = {}) {
+        const generation = ++this.openGeneration;
         this.unsub?.();
+        this.resetRenderingState();
         this.cmEditor?.destroy();
         this.cmEditor = null;
         this.workspace = null;
+        this.replaceAssetSession(null);
+        this.conversionDocumentGeneration += 1;
         try {
             const ws = await MdzipWorkspaceService.open(bytes, options);
+            if (generation !== this.openGeneration) {
+                // A newer open() started while this parse was in flight; discard this
+                // stale result so the latest input remains authoritative.
+                return;
+            }
             this.workspace = ws;
+            this.replaceAssetSession(new MdzipAssetSession(ws, ws.snapshot().workspace.assets, this.elRoot.ownerDocument, {
+                cache: this.options.assetCache,
+                sourceId: () => mdzipArchiveSourceId(bytes),
+                onFailed: this.options.onFailed
+            }));
             const snap = ws.snapshot();
             if (snap.sourceFormat === 'markdown') {
                 this.navVisible = false;
             }
             this.layout = this.validLayoutForSnapshot(this.options.initialLayout ?? defaultLayoutForPolicy(this.controlPolicy), snap);
-            this.cmEditor = this.createCmEditor(this.elEditorHost, snap.currentText, snap.mode);
+            await this.ensureCmEditor();
+            if (generation !== this.openGeneration) {
+                return;
+            }
             this.unsub = ws.subscribe((event) => {
+                if (event.changes.includes('asset')) {
+                    this.replaceAssetSession(new MdzipAssetSession(ws, event.snapshot.workspace.assets, this.elRoot.ownerDocument, {
+                        cache: this.options.assetCache,
+                        sourceId: () => mdzipArchiveSourceId(event.snapshot.archiveBytes),
+                        onFailed: this.options.onFailed
+                    }));
+                }
+                if (event.changes.includes('workspace') || event.changes.includes('document')) {
+                    this.conversionDocumentGeneration += 1;
+                }
                 this.render();
                 void this.notifyChanged(event);
             });
@@ -525,6 +590,9 @@ export class MdzipWorkspaceView {
             void this.notifyChanged(this.initialWorkspaceEvent(ws.snapshot()));
         }
         catch (error) {
+            if (generation !== this.openGeneration) {
+                return;
+            }
             this.options.onFailed?.(error);
         }
     }
@@ -555,17 +623,46 @@ export class MdzipWorkspaceView {
      * `ERR_LAZY_TEXT_UNAVAILABLE` instead of silently producing an empty file.
      */
     async openWorkspace(workspace, options = {}) {
+        const generation = ++this.openGeneration;
         this.unsub?.();
+        this.resetRenderingState();
         this.cmEditor?.destroy();
         this.cmEditor = null;
         this.workspace = null;
+        this.replaceAssetSession(null);
+        this.conversionDocumentGeneration += 1;
         try {
             const ws = await MdzipWorkspaceService.openWorkspace(workspace, options);
+            if (generation !== this.openGeneration) {
+                // A newer open started while this parse was in flight; discard it.
+                return;
+            }
             this.workspace = ws;
+            this.replaceAssetSession(new MdzipAssetSession(ws, ws.snapshot().workspace.assets, this.elRoot.ownerDocument, {
+                cache: this.options.assetCache,
+                sourceId: options.assetSourceId
+                    ?? (options.archiveBytes ? () => mdzipArchiveSourceId(options.archiveBytes) : undefined),
+                onFailed: this.options.onFailed
+            }));
             const snap = ws.snapshot();
             this.layout = this.validLayoutForSnapshot(this.options.initialLayout ?? defaultLayoutForPolicy(this.controlPolicy), snap);
-            this.cmEditor = this.createCmEditor(this.elEditorHost, snap.currentText, snap.mode);
+            await this.ensureCmEditor();
+            if (generation !== this.openGeneration) {
+                return;
+            }
             this.unsub = ws.subscribe((event) => {
+                if (event.changes.includes('asset')) {
+                    this.replaceAssetSession(new MdzipAssetSession(ws, event.snapshot.workspace.assets, this.elRoot.ownerDocument, {
+                        cache: this.options.assetCache,
+                        sourceId: event.snapshot.archiveBytes.length
+                            ? () => mdzipArchiveSourceId(event.snapshot.archiveBytes)
+                            : undefined,
+                        onFailed: this.options.onFailed
+                    }));
+                }
+                if (event.changes.includes('workspace') || event.changes.includes('document')) {
+                    this.conversionDocumentGeneration += 1;
+                }
                 this.render();
                 void this.notifyChanged(event);
             });
@@ -573,6 +670,9 @@ export class MdzipWorkspaceView {
             void this.notifyChanged(this.initialWorkspaceEvent(ws.snapshot()));
         }
         catch (error) {
+            if (generation !== this.openGeneration) {
+                return;
+            }
             this.options.onFailed?.(error);
         }
     }
@@ -613,14 +713,18 @@ export class MdzipWorkspaceView {
         return this.workspace?.listAssets() ?? [];
     }
     canExecuteCommand(command) {
+        // Availability is currently uniform across commands; the parameter is
+        // kept so per-command policies stay a non-breaking change.
+        void command;
         const snapshot = this.workspace?.snapshot();
-        if (!snapshot || !this.cmEditor || snapshot.mode === 'read-only'
+        if (!snapshot || snapshot.mode === 'read-only'
             || snapshot.currentPathType !== 'markdown') {
             return false;
         }
         return true;
     }
     async executeCommand(command, file) {
+        await this.ensureCmEditor(true);
         if (!this.canExecuteCommand(command)) {
             return false;
         }
@@ -660,12 +764,18 @@ export class MdzipWorkspaceView {
         this.cmEditor?.focus();
     }
     destroy() {
+        this.conversionDocumentGeneration += 1;
         try {
             this.unsub?.();
         }
         catch {
             // Ignore subscription cleanup errors
         }
+        this.resetPreviewState();
+        this.replaceAssetSession(null);
+        this.teardownEntryRenderer();
+        // Release any whenRendered() waiters so their promises do not hang.
+        this.flushRenderedWaiters();
         try {
             this.cmEditor?.destroy();
         }
@@ -679,6 +789,550 @@ export class MdzipWorkspaceView {
             // Ignore DOM cleanup errors
         }
     }
+    /**
+     * Replaces the rendering configuration without recreating the view (and
+     * therefore without re-opening the workspace). Wrappers call this when
+     * renderer props change; the cost is one preview re-render and entry
+     * renderer re-match.
+     */
+    setRenderingOptions(options) {
+        if ('markdownRenderer' in options) {
+            this.markdownRenderer = options.markdownRenderer ?? undefined;
+        }
+        if (options.markdownExtensions) {
+            this.markdownExtensions = options.markdownExtensions;
+        }
+        if (options.entryRenderers) {
+            this.entryRenderers = options.entryRenderers;
+        }
+        this.renderingService = new MdzipRenderingService(this.markdownRenderer ?? defaultSafeMarkdownRenderer, this.markdownExtensions);
+        this.resetPreviewState();
+        this.teardownEntryRenderer();
+        this.entryMatchMissKey = null;
+        this.render();
+    }
+    /**
+     * Tears down all custom rendering state: aborts in-flight renders, destroys
+     * mounted extension and entry renderer handles, and clears memo caches.
+     * Used when the workspace is replaced or the view is destroyed.
+     */
+    resetRenderingState() {
+        this.resetPreviewState();
+        this.teardownEntryRenderer();
+        this.entryMatchMissKey = null;
+    }
+    replaceAssetSession(session) {
+        this.assetSession?.destroy();
+        this.assetSession = session;
+        this.resetPreviewState();
+    }
+    resetPreviewState() {
+        this.previewAbort?.abort();
+        this.previewAbort = null;
+        this.previewGeneration += 1;
+        this.destroyPreviewHandles();
+        this.previewMemo = null;
+    }
+    destroyPreviewHandles() {
+        const handles = this.previewHandles;
+        this.previewHandles = [];
+        for (const handle of handles) {
+            try {
+                handle.destroy();
+            }
+            catch (error) {
+                this.options.onFailed?.(error);
+            }
+        }
+    }
+    updatePreview(snapshot, entryClaimed) {
+        if (entryClaimed) {
+            // The entry renderer owns the pane stack; release preview resources so
+            // a later fallback re-renders from scratch.
+            if (this.previewMemo || this.previewHandles.length > 0 || this.previewAbort) {
+                this.resetPreviewState();
+                this.elPreviewContent.replaceChildren();
+            }
+            // There is no built-in preview to wait for; release any waiters.
+            this.previewHydrated = true;
+            this.flushRenderedWaiters();
+            return;
+        }
+        const memo = this.previewMemo;
+        if (memo
+            && memo.path === snapshot.currentPath
+            && memo.pathType === snapshot.currentPathType
+            && memo.text === snapshot.currentText
+            && memo.colorScheme === this.colorScheme) {
+            // Nothing that feeds the preview changed; keep the existing DOM and any
+            // mounted extension handles.
+            return;
+        }
+        this.previewAbort?.abort();
+        this.previewAbort = null;
+        this.destroyPreviewHandles();
+        const generation = ++this.previewGeneration;
+        this.previewHydrated = false;
+        this.previewMemo = {
+            path: snapshot.currentPath,
+            pathType: snapshot.currentPathType,
+            text: snapshot.currentText,
+            colorScheme: this.colorScheme
+        };
+        if (snapshot.currentPathType !== 'markdown') {
+            if (snapshot.currentPathType === 'image' && this.assetSession) {
+                const abort = new AbortController();
+                this.previewAbort = abort;
+                void this.assetSession.resolve(snapshot.currentPath, snapshot.currentPath).then((src) => {
+                    if (generation !== this.previewGeneration || abort.signal.aborted)
+                        return;
+                    this.elPreviewContent.innerHTML = src
+                        ? `<div class="asset-preview-wrap"><img class="asset-preview-image" src="${escapeHtml(src)}" alt="${escapeHtml(snapshot.currentPath)}"></div>`
+                        : renderMdzipPreviewHtml(snapshot);
+                    this.firePreviewRendered(snapshot, generation);
+                    this.fireAssetsHydrated(snapshot, generation);
+                }).catch((error) => this.options.onFailed?.(error));
+            }
+            else {
+                this.elPreviewContent.innerHTML = renderMdzipPreviewHtml(snapshot);
+                this.firePreviewRendered(snapshot, generation);
+                this.fireAssetsHydrated(snapshot, generation);
+            }
+            return;
+        }
+        const abort = new AbortController();
+        this.previewAbort = abort;
+        const context = this.createMarkdownContext(snapshot, abort.signal);
+        let result;
+        try {
+            result = this.renderingService.renderMarkdown(snapshot.currentText, context);
+        }
+        catch (error) {
+            this.options.onFailed?.(error);
+            this.elPreviewContent.innerHTML = renderMdzipPreviewHtml(snapshot);
+            this.firePreviewRendered(snapshot, generation);
+            this.fireAssetsHydrated(snapshot, generation);
+            return;
+        }
+        if (typeof result === 'string') {
+            // Sync fast path: no microtask hop when every pipeline stage is sync.
+            this.applyPreviewHtml(result, snapshot, context, generation);
+            return;
+        }
+        void result.then((html) => {
+            if (generation !== this.previewGeneration || abort.signal.aborted) {
+                return; // Stale: the selection or content moved on while rendering.
+            }
+            this.applyPreviewHtml(html, snapshot, context, generation);
+        }).catch((error) => {
+            if (generation !== this.previewGeneration || abort.signal.aborted) {
+                return;
+            }
+            if (error?.name !== 'AbortError') {
+                this.options.onFailed?.(error);
+            }
+        });
+    }
+    applyPreviewHtml(html, snapshot, context, generation) {
+        // When the preview references archive images, mount the text immediately
+        // and hydrate each image progressively (reserving layout space from its
+        // sniffed intrinsic size), rather than blocking the whole preview on image
+        // resolution. Other markdown mounts synchronously.
+        if (this.assetSession && /<img\b/i.test(html)) {
+            this.mountProgressivePreview(html, snapshot, context, generation);
+            return;
+        }
+        this.mountPreviewHtml(html, snapshot, context, generation);
+    }
+    mountPreviewHtml(html, snapshot, context, generation) {
+        this.elPreviewContent.innerHTML = html;
+        this.mountPreviewExtensions(context, generation);
+        // No archive images to resolve on this path: the preview is ready now.
+        this.firePreviewRendered(snapshot, generation);
+        this.fireAssetsHydrated(snapshot, generation);
+    }
+    /**
+     * Mounts the rendered text immediately with image placeholders, then swaps
+     * each archive image in as it resolves. `onPreviewRendered` fires once the
+     * text is in the DOM; `onAssetsHydrated` fires once every referenced image
+     * has resolved and had its final `src` assigned (or there are none).
+     */
+    mountProgressivePreview(html, snapshot, context, generation) {
+        this.elPreviewContent.innerHTML = html;
+        const session = this.assetSession;
+        const document = this.elPreviewContent.ownerDocument;
+        const pending = [];
+        for (const image of Array.from(this.elPreviewContent.querySelectorAll('img'))) {
+            const source = image.getAttribute('src');
+            // Leave external, protocol-relative, data, and fragment URLs untouched.
+            if (!source || /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(source)) {
+                continue;
+            }
+            // Drop the archive-relative src so the browser does not fetch the bad
+            // path. Wrap the image in a collapsed slot so the text stays compact and
+            // immediately readable; the slot eases open to the reserved height once
+            // the image resolves.
+            image.removeAttribute('src');
+            image.classList.add('mdzip-image-loading');
+            const slot = document.createElement('span');
+            slot.className = 'mdzip-image-slot';
+            image.parentNode?.insertBefore(slot, image);
+            slot.appendChild(image);
+            pending.push({ image, slot, source });
+        }
+        this.mountPreviewExtensions(context, generation);
+        this.firePreviewRendered(snapshot, generation);
+        if (!session || pending.length === 0) {
+            this.fireAssetsHydrated(snapshot, generation);
+            return;
+        }
+        let remaining = pending.length;
+        const settle = () => {
+            remaining -= 1;
+            if (remaining === 0) {
+                this.fireAssetsHydrated(snapshot, generation);
+            }
+        };
+        for (const { image, slot, source } of pending) {
+            void session.resolveImage(source, context.currentPath).then((resolved) => {
+                if (generation !== this.previewGeneration || context.signal.aborted) {
+                    settle();
+                    return;
+                }
+                if (!resolved) {
+                    image.classList.remove('mdzip-image-loading');
+                    this.openImageSlot(slot);
+                    settle();
+                    return;
+                }
+                // Size the reserved box from the sniffed dimensions so the slot eases
+                // open to the image's exact height in a single slide — and the pixels
+                // drop into an already-correct box with no further reflow.
+                if (resolved.width && resolved.height) {
+                    image.setAttribute('width', String(resolved.width));
+                    image.setAttribute('height', String(resolved.height));
+                }
+                this.attachImageLoadHandlers(image, source, resolved.url, context, generation);
+                image.setAttribute('src', resolved.url);
+                this.openImageSlot(slot);
+                settle();
+            }).catch((error) => {
+                if (error?.name !== 'AbortError') {
+                    this.options.onFailed?.(error);
+                }
+                image.classList.remove('mdzip-image-loading');
+                this.openImageSlot(slot);
+                settle();
+            });
+        }
+    }
+    /**
+     * Reveals a collapsed image slot. Flushing layout before toggling the class
+     * lets the `0fr -> 1fr` grid transition run from the collapsed state instead
+     * of being coalesced into the initial mount; CSS snaps it open instantly
+     * under `prefers-reduced-motion`.
+     */
+    openImageSlot(slot) {
+        void slot.offsetHeight;
+        slot.classList.add('mdzip-image-open');
+    }
+    /**
+     * Wires `<img>` load/error handling for a resolved archive image.
+     *
+     * `resolveImage()` already succeeded, so an `error` here is environmental
+     * rather than a missing asset — most often a host whose CSP `img-src` blocks
+     * the `blob:` object URL. When that happens we retry once with a `data:` URL
+     * (which many such hosts still permit), and only if that also fails do we
+     * surface the failure via `onFailed` instead of leaving a silent blank box.
+     */
+    attachImageLoadHandlers(image, source, resolvedUrl, context, generation) {
+        const clear = () => image.classList.remove('mdzip-image-loading');
+        image.addEventListener('load', clear, { once: true });
+        image.addEventListener('error', () => {
+            const session = this.assetSession;
+            if (resolvedUrl.startsWith('blob:') && session) {
+                void session.resolveDataUrl(source, context.currentPath).then((dataUrl) => {
+                    if (generation !== this.previewGeneration || context.signal.aborted) {
+                        clear();
+                        return;
+                    }
+                    if (dataUrl && dataUrl !== resolvedUrl) {
+                        image.addEventListener('load', clear, { once: true });
+                        image.addEventListener('error', () => {
+                            clear();
+                            this.reportImageLoadFailure(source);
+                        }, { once: true });
+                        image.setAttribute('src', dataUrl);
+                        return;
+                    }
+                    clear();
+                    this.reportImageLoadFailure(source);
+                }).catch((error) => {
+                    clear();
+                    this.options.onFailed?.(error);
+                });
+                return;
+            }
+            clear();
+            this.reportImageLoadFailure(source);
+        }, { once: true });
+    }
+    reportImageLoadFailure(source) {
+        this.options.onFailed?.(new Error(`Failed to load archive image "${source}". When embedding the editor in a `
+            + 'CSP-restricted host (e.g. a VS Code webview), ensure img-src permits '
+            + 'blob: and data:.'));
+    }
+    mountPreviewExtensions(context, generation) {
+        for (const extension of this.markdownExtensions) {
+            if (!extension.mount) {
+                continue;
+            }
+            try {
+                const mounted = extension.mount(this.elPreviewContent, context);
+                if (isThenable(mounted)) {
+                    void Promise.resolve(mounted).then((handle) => {
+                        if (!handle) {
+                            return;
+                        }
+                        if (generation !== this.previewGeneration) {
+                            try {
+                                handle.destroy();
+                            }
+                            catch {
+                                // Stale handle cleanup failure is not actionable.
+                            }
+                            return;
+                        }
+                        this.previewHandles.push(handle);
+                    }).catch((error) => {
+                        if (generation === this.previewGeneration) {
+                            this.options.onFailed?.(error);
+                        }
+                    });
+                }
+                else if (mounted) {
+                    this.previewHandles.push(mounted);
+                }
+            }
+            catch (error) {
+                this.options.onFailed?.(error);
+            }
+        }
+    }
+    firePreviewRendered(snapshot, generation) {
+        if (generation !== this.previewGeneration) {
+            return;
+        }
+        try {
+            this.options.onPreviewRendered?.(snapshot);
+        }
+        catch (error) {
+            this.options.onFailed?.(error);
+        }
+    }
+    fireAssetsHydrated(snapshot, generation) {
+        if (generation !== this.previewGeneration) {
+            return;
+        }
+        this.previewHydrated = true;
+        try {
+            this.options.onAssetsHydrated?.(snapshot);
+        }
+        catch (error) {
+            this.options.onFailed?.(error);
+        }
+        this.flushRenderedWaiters();
+    }
+    flushRenderedWaiters() {
+        const waiters = this.renderedWaiters;
+        this.renderedWaiters = [];
+        for (const resolve of waiters) {
+            resolve();
+        }
+    }
+    /**
+     * Resolves once the current preview (including any images) is mounted and
+     * hydrated. Resolves immediately when the latest preview is already ready.
+     * Useful for revealing or animating content without observing private DOM.
+     */
+    whenRendered() {
+        if (this.previewHydrated) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => this.renderedWaiters.push(resolve));
+    }
+    createMarkdownContext(snapshot, signal) {
+        return {
+            currentPath: snapshot.currentPath,
+            sourceFormat: snapshot.sourceFormat,
+            colorScheme: this.colorScheme,
+            mode: snapshot.mode,
+            manifest: snapshot.content.manifest,
+            assetResolver: {
+                resolveAssetUrl: (path) => this.assetSession?.resolveKnown(path, snapshot.currentPath)
+            },
+            signal
+        };
+    }
+    /**
+     * Entry renderer lifecycle. Renders are keyed by
+     * (path, pathType, mode, sourceFormat): same key keeps the mounted handle
+     * (calling `update()` when colorScheme or manifest changed), a changed key
+     * destroys it and re-runs matching. Rename/move/delete of the backing entry
+     * changes the path and is therefore handled as a selection change.
+     */
+    syncEntryRenderer(snapshot) {
+        if (this.entryRenderers.length === 0) {
+            return false;
+        }
+        const matchKey = [
+            snapshot.currentPath,
+            snapshot.currentPathType,
+            snapshot.mode,
+            snapshot.sourceFormat
+        ].join('\u0000');
+        if (this.entryState?.key === matchKey) {
+            this.maybeUpdateEntryRenderer(snapshot);
+            return true;
+        }
+        if (this.entryState) {
+            this.teardownEntryRenderer();
+        }
+        if (this.entryMatchMissKey === matchKey) {
+            return false;
+        }
+        const abort = new AbortController();
+        const context = this.createEntryContext(snapshot, abort.signal);
+        const renderer = this.matchEntryRenderer(context);
+        if (!renderer) {
+            this.entryMatchMissKey = matchKey;
+            return false;
+        }
+        this.entryMatchMissKey = null;
+        const generation = ++this.entryGeneration;
+        const state = {
+            key: matchKey,
+            renderer,
+            handle: null,
+            abort,
+            lastColorScheme: this.colorScheme,
+            lastManifest: snapshot.content.manifest
+        };
+        this.entryState = state;
+        this.elEntryPane.replaceChildren();
+        try {
+            const mounted = renderer.mount(this.elEntryPane, context);
+            if (isThenable(mounted)) {
+                void Promise.resolve(mounted).then((handle) => {
+                    if (this.entryGeneration !== generation || this.entryState !== state) {
+                        // Stale mount: the selection moved on while mounting.
+                        try {
+                            handle?.destroy();
+                        }
+                        catch {
+                            // Stale handle cleanup failure is not actionable.
+                        }
+                        return;
+                    }
+                    state.handle = handle ?? null;
+                }).catch((error) => {
+                    if (this.entryGeneration === generation) {
+                        this.options.onFailed?.(error);
+                    }
+                });
+            }
+            else {
+                state.handle = mounted ?? null;
+            }
+        }
+        catch (error) {
+            this.options.onFailed?.(error);
+        }
+        return true;
+    }
+    maybeUpdateEntryRenderer(snapshot) {
+        const state = this.entryState;
+        if (!state) {
+            return;
+        }
+        const manifest = snapshot.content.manifest;
+        if (state.lastColorScheme === this.colorScheme && state.lastManifest === manifest) {
+            return;
+        }
+        state.lastColorScheme = this.colorScheme;
+        state.lastManifest = manifest;
+        if (!state.handle?.update) {
+            return;
+        }
+        const context = this.createEntryContext(snapshot, state.abort.signal);
+        try {
+            const result = state.handle.update(context);
+            if (isThenable(result)) {
+                void Promise.resolve(result).catch((error) => this.options.onFailed?.(error));
+            }
+        }
+        catch (error) {
+            this.options.onFailed?.(error);
+        }
+    }
+    matchEntryRenderer(context) {
+        const byPriority = [...this.entryRenderers]
+            .sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+        for (const renderer of byPriority) {
+            try {
+                if (renderer.matches(context)) {
+                    return renderer;
+                }
+            }
+            catch (error) {
+                this.options.onFailed?.(error);
+            }
+        }
+        return null;
+    }
+    teardownEntryRenderer() {
+        const active = this.entryState;
+        if (!active) {
+            return;
+        }
+        this.entryState = null;
+        this.entryGeneration += 1;
+        active.abort.abort();
+        try {
+            active.handle?.destroy();
+        }
+        catch (error) {
+            this.options.onFailed?.(error);
+        }
+        this.elEntryPane.replaceChildren();
+    }
+    createEntryContext(snapshot, signal) {
+        const workspace = this.workspace;
+        const path = snapshot.currentPath;
+        return {
+            path,
+            pathType: snapshot.currentPathType,
+            mode: snapshot.mode,
+            sourceFormat: snapshot.sourceFormat,
+            colorScheme: this.colorScheme,
+            manifest: snapshot.content.manifest,
+            snapshot,
+            signal,
+            readBytes: async () => {
+                const bytes = await workspace?.readPathBytes(path);
+                if (!bytes) {
+                    throw new Error(`Cannot read bytes for "${path}".`);
+                }
+                return bytes;
+            },
+            updateManifest: async (manifest) => {
+                if (!workspace) {
+                    throw new Error('Workspace is not open.');
+                }
+                await workspace.updateManifest(manifest);
+            }
+        };
+    }
     createCmEditor(parent, initialText, mode) {
         // eslint-disable-next-line @typescript-eslint/no-this-alias
         const self = this;
@@ -754,6 +1408,15 @@ export class MdzipWorkspaceView {
         }
         return editor;
     }
+    async ensureCmEditor(force = false) {
+        const snapshot = this.workspace?.snapshot();
+        if (this.cmEditor || !snapshot || (!force && this.layout === 'preview')
+            || !canShowSourceLayout(snapshot)) {
+            return this.cmEditor;
+        }
+        this.cmEditor = this.createCmEditor(this.elEditorHost, snapshot.currentText, snapshot.mode);
+        return this.cmEditor;
+    }
     render() {
         const snapshot = this.workspace?.snapshot() ?? null;
         this.elEmptyState.hidden = snapshot !== null;
@@ -764,7 +1427,9 @@ export class MdzipWorkspaceView {
             return;
         }
         this.layout = this.validLayoutForSnapshot(this.layout, snapshot);
-        const canEdit = canEditMdzipPath(snapshot.currentPathType, snapshot.currentPath, snapshot.mode);
+        const entryClaimed = this.syncEntryRenderer(snapshot);
+        const canEdit = !entryClaimed
+            && canEditMdzipPath(snapshot.currentPathType, snapshot.currentPath, snapshot.mode);
         const canShowSource = canShowSourceLayout(snapshot);
         const showNavigationControl = this.controlPolicy.navigation;
         const showTitleControl = this.controlPolicy.title.visible;
@@ -877,14 +1542,16 @@ export class MdzipWorkspaceView {
                 effects: this.readOnlyCompartment.reconfigure(EditorState.readOnly.of(snapshot.mode === 'read-only'))
             });
         }
-        this.elPreviewContent.innerHTML = renderMdzipPreviewHtml(snapshot);
+        this.updatePreview(snapshot, entryClaimed);
         const pt = snapshot.currentPathType;
-        const showEdit = (pt === 'markdown' || pt === 'text') && this.layout !== 'preview';
-        const showPreview = pt === 'image' || pt === 'binary' || pt === 'text'
-            || (pt === 'markdown' && this.layout !== 'source');
+        const showEdit = !entryClaimed && (pt === 'markdown' || pt === 'text') && this.layout !== 'preview';
+        const showPreview = !entryClaimed && (pt === 'image' || pt === 'binary' || pt === 'text'
+            || (pt === 'markdown' && this.layout !== 'source'));
         this.elEditPane.classList.toggle('active', showEdit);
         this.elPreviewPane.classList.toggle('active', showPreview);
-        this.elPaneStack.classList.toggle('split-mode', this.layout === 'split');
+        this.elEntryPane.classList.toggle('active', entryClaimed);
+        this.elPaneStack.classList.toggle('split-mode', this.layout === 'split' && !entryClaimed);
+        this.elPaneStack.classList.toggle('entry-claimed', entryClaimed);
         if (!showTitleControl) {
             this.titleDialogOpen = false;
             this.metadataDialogOpen = false;
@@ -1026,17 +1693,17 @@ export class MdzipWorkspaceView {
         });
         this.elPreviewBtn.addEventListener('click', () => {
             if (this.controlPolicy.layout.preview) {
-                this.setLayout('preview');
+                void this.setLayout('preview');
             }
         });
         this.elSplitBtn.addEventListener('click', () => {
             if (this.controlPolicy.layout.split) {
-                this.setLayout('split');
+                void this.setLayout('split');
             }
         });
         this.elSourceBtn.addEventListener('click', () => {
             if (this.controlPolicy.layout.source) {
-                this.setLayout('source');
+                void this.setLayout('source');
             }
         });
         this.elSaveBtn.addEventListener('click', () => {
@@ -1477,16 +2144,58 @@ export class MdzipWorkspaceView {
             ['Entry point', snapshot.sourceFormat === 'mdz' ? snapshot.content.entryPoint : 'Not applicable']
         ];
         this.elMetadataList.replaceChildren(...fields.map(([label, value]) => {
-            const row = this.elRoot.ownerDocument.createElement('div');
-            row.className = 'metadata-row';
-            const term = this.elRoot.ownerDocument.createElement('dt');
-            term.textContent = label;
-            const detail = this.elRoot.ownerDocument.createElement('dd');
-            detail.textContent = value;
-            row.append(term, detail);
-            return row;
+            return this.createMetadataRow(label, value);
+        }));
+        const libraries = [
+            ...(this.options.libraries ?? []),
+            ...MDZIP_RUNTIME_LIBRARIES
+        ].filter((library, index, all) => all.findIndex((candidate) => candidate.name === library.name) === index);
+        this.elLibraryList.replaceChildren(...libraries.map((library) => {
+            return this.createLibraryRow(library);
         }));
     }
+    createMetadataRow(label, value) {
+        const row = this.elRoot.ownerDocument.createElement('div');
+        row.className = 'metadata-row';
+        const term = this.elRoot.ownerDocument.createElement('dt');
+        term.textContent = label;
+        const detail = this.elRoot.ownerDocument.createElement('dd');
+        detail.textContent = value;
+        row.append(term, detail);
+        return row;
+    }
+    createLibraryRow(library) {
+        const row = this.elRoot.ownerDocument.createElement('div');
+        row.className = 'metadata-row library-row';
+        const term = this.elRoot.ownerDocument.createElement('dt');
+        const name = this.elRoot.ownerDocument.createElement('span');
+        name.className = 'library-name';
+        if (library.repositoryUrl) {
+            const link = this.elRoot.ownerDocument.createElement('a');
+            link.href = library.repositoryUrl;
+            link.target = '_blank';
+            link.rel = 'noopener noreferrer';
+            link.textContent = library.name;
+            link.setAttribute('aria-label', `${library.name} repository`);
+            name.append(link);
+        }
+        else {
+            name.textContent = library.name;
+        }
+        const version = this.elRoot.ownerDocument.createElement('span');
+        version.className = 'library-version';
+        version.textContent = library.version;
+        term.append(name, version);
+        const detail = this.elRoot.ownerDocument.createElement('dd');
+        if (library.description) {
+            const description = this.elRoot.ownerDocument.createElement('span');
+            description.className = 'library-description';
+            description.textContent = library.description;
+            detail.append(description);
+        }
+        row.append(term, detail);
+        return row;
+    }
     requestMdzConversion(action) {
         const snapshot = this.workspace?.snapshot();
         if (!snapshot || snapshot.mode === 'read-only' || snapshot.sourceFormat !== 'markdown') {
@@ -1501,8 +2210,9 @@ export class MdzipWorkspaceView {
             return;
         }
         this.conversionHookPending = true;
+        const context = this.createConversionContext(action);
         void Promise.resolve()
-            .then(() => hook(action))
+            .then(() => hook(action, context))
             .then((handled) => {
             this.conversionHookPending = false;
             if (!handled) {
@@ -1515,6 +2225,75 @@ export class MdzipWorkspaceView {
             this.openConversionDialog(action);
         });
     }
+    createConversionContext(action) {
+        const workspace = this.workspace;
+        const snapshot = workspace?.snapshot();
+        const selection = this.cmEditor?.state.selection.main;
+        const captured = workspace && snapshot ? {
+            workspace,
+            documentGeneration: this.conversionDocumentGeneration,
+            path: snapshot.currentPath,
+            text: snapshot.currentText,
+            selectionStart: selection?.from,
+            selectionEnd: selection?.to
+        } : null;
+        let consumed = false;
+        const take = () => {
+            if (consumed || !captured || this.workspace !== captured.workspace
+                || this.conversionDocumentGeneration !== captured.documentGeneration) {
+                return null;
+            }
+            const current = captured.workspace.snapshot();
+            if (current.mode === 'read-only'
+                || current.sourceFormat !== 'markdown'
+                || current.currentPath !== captured.path
+                || current.currentText !== captured.text) {
+                return null;
+            }
+            consumed = true;
+            return captured;
+        };
+        return {
+            insertMarkdown: async (text) => {
+                const target = take();
+                if (!target || target.selectionStart === undefined || target.selectionEnd === undefined) {
+                    return false;
+                }
+                const nextText = target.text.slice(0, target.selectionStart)
+                    + text
+                    + target.text.slice(target.selectionEnd);
+                target.workspace.editText(nextText);
+                this.render();
+                const editor = await this.ensureCmEditor();
+                if (editor) {
+                    editor.dispatch({ selection: { anchor: target.selectionStart + text.length } });
+                    editor.focus();
+                }
+                return true;
+            },
+            convertToMdz: async () => {
+                const target = take();
+                if (!target || !await this.convertToMdz()) {
+                    return false;
+                }
+                if (action.kind === 'navigation') {
+                    this.navVisible = true;
+                    this.render();
+                    return true;
+                }
+                const editor = await this.ensureCmEditor();
+                if (editor && target.selectionStart !== undefined) {
+                    editor.dispatch({ selection: { anchor: target.selectionStart } });
+                }
+                if (action.kind === 'image-file') {
+                    await this.insertImageFile(action.file);
+                    return true;
+                }
+                this.elImageInput.click();
+                return true;
+            }
+        };
+    }
     openConversionDialog(action) {
         this.conversionAction = action;
         this.render();
@@ -1857,9 +2636,10 @@ export class MdzipWorkspaceView {
         this.setColorScheme(colorScheme);
         this.options.onColorSchemeChanged?.(colorScheme);
     }
-    setLayout(requested) {
+    async setLayout(requested) {
         const snapshot = this.workspace?.snapshot();
         this.layout = snapshot ? this.validLayoutForSnapshot(requested, snapshot) : requested;
+        await this.ensureCmEditor();
         this.render();
     }
     navMenuTargetFromElement(element) {
@@ -2609,6 +3389,7 @@ const SHELL_HTML = `
       <section class="pane preview-pane" data-ref="preview-pane">
         <article class="preview-content" data-ref="preview-content"></article>
       </section>
+      <section class="pane entry-pane" data-ref="entry-pane"></section>
     </div>
   </div>
 
@@ -2649,6 +3430,8 @@ const SHELL_HTML = `
     <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>