@mdzip/core-js 1.2.1

package/dist/mdz-core.js

@@ -0,0 +1,1781 @@
+import JSZip from '@progress/jszip-esm';
+const PRODUCER_SPEC_VERSION = '1.1.0';
+const CORE_LIBRARY_VERSION = '1.2.0';
+const CORE_LIBRARY_URL = 'https://github.com/mdzip-project/mdzip-core-js';
+/**
+ * Extension-to-MIME map for common image assets in MDZip archives.
+ */
+export const MDZ_IMAGE_MIME_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    avif: 'image/avif',
+    ico: 'image/x-icon'
+};
+/**
+ * Core archive reader/validator/mutator for `.mdz` files.
+ */
+export class MdzArchiveCore {
+    zip;
+    /**
+     * Public image MIME map for consumers.
+     */
+    static IMAGE_MIME_TYPES = MDZ_IMAGE_MIME_TYPES;
+    static SUPPORTED_MDZ_MAJOR = 1;
+    static SUPPORTED_MODES = ['document', 'project'];
+    static SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+    static MARKDOWN_IMAGE_REF_RE = /!\[[^\]]*\]\(([^)\n]+)\)/g;
+    static entriesCache = new WeakMap();
+    static manifestCache = new WeakMap();
+    /**
+     * Creates an archive wrapper around a previously loaded ZIP object.
+     *
+     * @param zip - Loaded zip-like structure containing archive entries.
+     */
+    constructor(zip) {
+        this.zip = zip;
+    }
+    /**
+     * Opens archive binary data and returns a core archive instance.
+     *
+     * @param input - Raw archive bytes.
+     * @param zipFactory - Optional custom zip loader.
+     */
+    static async open(input, zipFactory) {
+        const factory = zipFactory ?? MdzArchiveCore.getDefaultZipFactory();
+        const zip = await factory.loadAsync(input);
+        return new MdzArchiveCore(zip);
+    }
+    /**
+     * Convenience helper to open and validate an archive in one call.
+     *
+     * @param input - Raw archive bytes.
+     * @param zipFactory - Optional custom zip loader.
+     */
+    static async validate(input, zipFactory) {
+        const archive = await MdzArchiveCore.open(input, zipFactory);
+        return archive.validate();
+    }
+    /**
+     * Adds or replaces an archive entry and returns a newly generated archive blob.
+     *
+     * Also validates entry-point integrity and refreshes manifest metadata when present.
+     *
+     * @param input - Existing archive bytes.
+     * @param archiveEntryPath - Archive-relative destination path.
+     * @param content - New entry content.
+     */
+    static async addFile(input, archiveEntryPath, content) {
+        const targetPath = MdzPackagerCore.normalizePath(archiveEntryPath);
+        const pathError = MdzArchiveCore.validateArchivePath(targetPath);
+        if (pathError) {
+            throw new Error(`ERR_PATH_INVALID: ${pathError}`);
+        }
+        const zip = await MdzArchiveCore.loadZip(input);
+        const targetLower = targetPath.toLowerCase();
+        const archivePaths = MdzArchiveCore.getArchivePaths(zip);
+        const nextArchivePaths = archivePaths.filter((p) => p.toLowerCase() !== targetLower);
+        nextArchivePaths.push(targetPath);
+        if (targetLower === 'manifest.json') {
+            const replacement = await MdzArchiveCore.parseManifestObjectContent(content, true);
+            const preparedManifest = MdzArchiveCore.stampManifestObject(replacement, true);
+            MdzArchiveCore.validateManifest(preparedManifest);
+            MdzArchiveCore.ensureCreatableEntryPoint(nextArchivePaths, preparedManifest);
+            MdzArchiveCore.removeEntryIgnoreCase(zip, targetPath);
+            zip.file('manifest.json', MdzArchiveCore.normaliseLf(JSON.stringify(preparedManifest, null, 2)));
+            return MdzArchiveCore.finalizeMutation(zip);
+        }
+        const existingManifestObject = await MdzArchiveCore.readExistingManifestObject(zip, true);
+        if (existingManifestObject) {
+            MdzArchiveCore.validateManifest(existingManifestObject);
+        }
+        MdzArchiveCore.ensureCreatableEntryPoint(nextArchivePaths, existingManifestObject);
+        MdzArchiveCore.removeEntryIgnoreCase(zip, targetPath);
+        await MdzArchiveCore.writeZipEntry(zip, targetPath, content);
+        if (existingManifestObject) {
+            const refreshed = MdzArchiveCore.stampManifestObject(existingManifestObject, false);
+            MdzArchiveCore.removeEntryIgnoreCase(zip, 'manifest.json');
+            zip.file('manifest.json', MdzArchiveCore.normaliseLf(JSON.stringify(refreshed, null, 2)));
+        }
+        return MdzArchiveCore.finalizeMutation(zip);
+    }
+    /**
+     * Removes an archive entry and returns a newly generated archive blob.
+     *
+     * Also validates entry-point integrity and refreshes manifest metadata when present.
+     *
+     * @param input - Existing archive bytes.
+     * @param archiveEntryPath - Archive-relative path to remove.
+     */
+    static async removeFile(input, archiveEntryPath) {
+        const targetPath = MdzPackagerCore.normalizePath(archiveEntryPath);
+        const pathError = MdzArchiveCore.validateArchivePath(targetPath);
+        if (pathError) {
+            throw new Error(`ERR_PATH_INVALID: ${pathError}`);
+        }
+        const zip = await MdzArchiveCore.loadZip(input);
+        const targetLower = targetPath.toLowerCase();
+        const archivePaths = MdzArchiveCore.getArchivePaths(zip);
+        const exists = archivePaths.some((p) => p.toLowerCase() === targetLower);
+        if (!exists) {
+            throw new Error(`ERR_NOT_FOUND: Entry "${targetPath}" was not found in archive.`);
+        }
+        const nextArchivePaths = archivePaths.filter((p) => p.toLowerCase() !== targetLower);
+        const existingManifestObject = targetLower === 'manifest.json' ? null : await MdzArchiveCore.readExistingManifestObject(zip, true);
+        if (existingManifestObject) {
+            MdzArchiveCore.validateManifest(existingManifestObject);
+        }
+        MdzArchiveCore.ensureCreatableEntryPoint(nextArchivePaths, existingManifestObject);
+        MdzArchiveCore.removeEntryIgnoreCase(zip, targetPath);
+        if (existingManifestObject) {
+            const refreshed = MdzArchiveCore.stampManifestObject(existingManifestObject, false);
+            MdzArchiveCore.removeEntryIgnoreCase(zip, 'manifest.json');
+            zip.file('manifest.json', MdzArchiveCore.normaliseLf(JSON.stringify(refreshed, null, 2)));
+        }
+        return MdzArchiveCore.finalizeMutation(zip);
+    }
+    /**
+     * Removes multiple archive entries in one mutation operation.
+     *
+     * @param input - Existing archive bytes.
+     * @param archiveEntryPaths - Archive-relative paths to remove.
+     */
+    static async removeFiles(input, archiveEntryPaths) {
+        const targets = archiveEntryPaths.map((p) => {
+            const normalized = MdzPackagerCore.normalizePath(p);
+            const pathError = MdzArchiveCore.validateArchivePath(normalized);
+            if (pathError) {
+                throw new Error(`ERR_PATH_INVALID: ${pathError}`);
+            }
+            return normalized;
+        });
+        if (targets.length === 0) {
+            const zip = await MdzArchiveCore.loadZip(input);
+            return MdzArchiveCore.finalizeMutation(zip);
+        }
+        const zip = await MdzArchiveCore.loadZip(input);
+        const targetSet = new Set(targets.map((p) => p.toLowerCase()));
+        const archivePaths = MdzArchiveCore.getArchivePaths(zip);
+        for (const target of targetSet) {
+            if (!archivePaths.some((p) => p.toLowerCase() === target)) {
+                throw new Error(`ERR_NOT_FOUND: Entry "${target}" was not found in archive.`);
+            }
+        }
+        const nextArchivePaths = archivePaths.filter((p) => !targetSet.has(p.toLowerCase()));
+        const removesManifest = targetSet.has('manifest.json');
+        const existingManifestObject = removesManifest ? null : await MdzArchiveCore.readExistingManifestObject(zip, true);
+        if (existingManifestObject) {
+            MdzArchiveCore.validateManifest(existingManifestObject);
+        }
+        MdzArchiveCore.ensureCreatableEntryPoint(nextArchivePaths, existingManifestObject);
+        for (const target of targetSet) {
+            MdzArchiveCore.removeEntryIgnoreCase(zip, target);
+        }
+        if (existingManifestObject) {
+            const refreshed = MdzArchiveCore.stampManifestObject(existingManifestObject, false);
+            MdzArchiveCore.removeEntryIgnoreCase(zip, 'manifest.json');
+            zip.file('manifest.json', MdzArchiveCore.normaliseLf(JSON.stringify(refreshed, null, 2)));
+        }
+        return MdzArchiveCore.finalizeMutation(zip);
+    }
+    /**
+     * Finds orphaned image assets in an archive.
+     *
+     * @param input - Existing archive bytes.
+     * @param options - Scan options.
+     */
+    static async findOrphanedAssets(input, options) {
+        const archive = await MdzArchiveCore.open(input);
+        return archive.findOrphanedAssets(options);
+    }
+    /**
+     * Opens archive binary data and returns an app-friendly normalized workspace model.
+     *
+     * @param input - Raw archive bytes.
+     * @param options - Workspace open controls.
+     * @param zipFactory - Optional custom zip loader.
+     */
+    static async openWorkspace(input, options, zipFactory) {
+        const archive = await MdzArchiveCore.open(input, zipFactory);
+        return archive.openWorkspace(options);
+    }
+    static getDefaultZipFactory() {
+        return {
+            async loadAsync(data) {
+                const zip = await new JSZip().loadAsync(data);
+                return zip;
+            }
+        };
+    }
+    static async loadZip(input) {
+        const zip = await new JSZip().loadAsync(input);
+        return zip;
+    }
+    /**
+     * Normalizes path separators and strips leading slashes.
+     *
+     * @param path - Any input path.
+     */
+    static normalizePath(path) {
+        return String(path || '').replace(/\\/g, '/').replace(/^\/+/, '');
+    }
+    /**
+     * Returns true if the provided path looks like a Markdown document path.
+     *
+     * @param path - Archive-relative path.
+     */
+    static isMarkdownFile(path) {
+        return /\.(md|markdown)$/i.test(path);
+    }
+    /**
+     * Infers a MIME type from an archive path.
+     *
+     * @param path - Archive-relative path.
+     * @param fallbackMime - MIME type used when extension is unknown.
+     */
+    static inferMimeType(path, fallbackMime = 'application/octet-stream') {
+        const ext = MdzArchiveCore.getPathExtension(path);
+        const known = {
+            ...MDZ_IMAGE_MIME_TYPES,
+            mp3: 'audio/mpeg',
+            wav: 'audio/wav',
+            ogg: 'audio/ogg',
+            m4a: 'audio/mp4',
+            mp4: 'video/mp4',
+            webm: 'video/webm',
+            mov: 'video/quicktime',
+            woff: 'font/woff',
+            woff2: 'font/woff2',
+            ttf: 'font/ttf',
+            otf: 'font/otf',
+            json: 'application/json',
+            csv: 'text/csv',
+            txt: 'text/plain',
+            css: 'text/css',
+            html: 'text/html',
+            htm: 'text/html',
+            xml: 'application/xml',
+            pdf: 'application/pdf'
+        };
+        return known[ext] ?? fallbackMime;
+    }
+    /**
+     * Classifies an asset using path extension and MIME type.
+     *
+     * @param path - Archive-relative path.
+     * @param mimeType - Optional known MIME type.
+     */
+    static classifyAssetKind(path, mimeType = MdzArchiveCore.inferMimeType(path)) {
+        if (mimeType.startsWith('image/'))
+            return 'image';
+        if (mimeType.startsWith('audio/'))
+            return 'audio';
+        if (mimeType.startsWith('video/'))
+            return 'video';
+        if (mimeType.startsWith('font/'))
+            return 'font';
+        if (/^(application\/json|text\/csv|text\/plain|text\/css|text\/html|application\/xml|text\/xml)$/.test(mimeType))
+            return 'data';
+        return 'other';
+    }
+    /**
+     * Returns true when common browser surfaces can preview this asset.
+     *
+     * @param path - Archive-relative path.
+     * @param mimeType - Optional known MIME type.
+     */
+    static isPreviewableAsset(path, mimeType = MdzArchiveCore.inferMimeType(path)) {
+        return mimeType.startsWith('image/') || /^(application\/json|text\/csv|text\/plain|text\/css|text\/html|application\/xml|text\/xml)$/.test(mimeType);
+    }
+    /**
+     * Converts validation details into a compact status.
+     *
+     * @param result - Validation result.
+     */
+    static getValidationStatus(result) {
+        if (result.errors.length > 0 || !result.isValid)
+            return 'error';
+        if (result.warnings.length > 0)
+            return 'warning';
+        return 'valid';
+    }
+    /**
+     * Returns a case-insensitive, normalized archive path sort.
+     *
+     * @param paths - Archive-relative paths.
+     */
+    static sortArchivePaths(paths) {
+        return paths
+            .map(MdzArchiveCore.normalizePath)
+            .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }));
+    }
+    /**
+     * Returns the archive-relative directory name for a path.
+     *
+     * @param path - Archive-relative path.
+     */
+    static dirname(path) {
+        const normalized = MdzArchiveCore.normalizePath(path).replace(/\/+$/, '');
+        const slash = normalized.lastIndexOf('/');
+        return slash >= 0 ? normalized.slice(0, slash) : '';
+    }
+    /**
+     * Returns the final path segment for an archive-relative path.
+     *
+     * @param path - Archive-relative path.
+     */
+    static basename(path) {
+        const normalized = MdzArchiveCore.normalizePath(path).replace(/\/+$/, '');
+        const slash = normalized.lastIndexOf('/');
+        return slash >= 0 ? normalized.slice(slash + 1) : normalized;
+    }
+    /**
+     * Builds a generic inferred folder tree from archive-relative paths.
+     *
+     * @param paths - Archive-relative paths.
+     */
+    static buildPathTree(paths) {
+        const roots = [];
+        const ensureNode = (siblings, name, path, isDirectory) => {
+            let node = siblings.find((item) => item.name.toLowerCase() === name.toLowerCase() && item.isDirectory === isDirectory);
+            if (!node) {
+                node = { name, path, isDirectory, children: [] };
+                siblings.push(node);
+            }
+            return node;
+        };
+        for (const archivePath of MdzArchiveCore.sortArchivePaths(paths)) {
+            const parts = archivePath.split('/').filter(Boolean);
+            let siblings = roots;
+            let currentPath = '';
+            for (let i = 0; i < parts.length; i += 1) {
+                const part = parts[i] ?? '';
+                currentPath = currentPath ? `${currentPath}/${part}` : part;
+                const isDirectory = i < parts.length - 1;
+                const node = ensureNode(siblings, part, currentPath, isDirectory);
+                siblings = node.children;
+            }
+        }
+        const sortNodes = (nodes) => {
+            nodes.sort((a, b) => {
+                if (a.isDirectory !== b.isDirectory)
+                    return a.isDirectory ? -1 : 1;
+                return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' });
+            });
+            for (const node of nodes)
+                sortNodes(node.children);
+        };
+        sortNodes(roots);
+        return roots;
+    }
+    /**
+     * Validates archive path constraints.
+     *
+     * @param path - Archive-relative path.
+     * @returns `null` when valid, otherwise a short reason string.
+     */
+    static validateArchivePath(path) {
+        const raw = String(path || '');
+        if (!raw)
+            return 'empty path';
+        if (raw.startsWith('/'))
+            return 'leading slash';
+        if (raw.includes('\\'))
+            return 'reserved character';
+        const normalized = raw;
+        if (normalized.split('/').includes('..'))
+            return 'path traversal';
+        for (const c of normalized) {
+            const code = c.charCodeAt(0);
+            if (c === '\0' || (code >= 1 && code <= 31) || code === 127)
+                return 'control char';
+        }
+        if (/[\\:*?"<>|]/.test(normalized))
+            return 'reserved character';
+        return null;
+    }
+    static dirOf(filePath) {
+        const i = filePath.lastIndexOf('/');
+        return i >= 0 ? filePath.slice(0, i + 1) : '';
+    }
+    /**
+     * Resolves a relative Markdown link target against an archive base path.
+     *
+     * Query/hash fragments are stripped and traversal beyond archive root is rejected.
+     *
+     * @param base - Referencing file path.
+     * @param relative - Relative target path from markdown/link source.
+     */
+    static resolvePath(base, relative) {
+        let target = String(relative || '').trim();
+        if (target.startsWith('<') && target.endsWith('>')) {
+            target = target.slice(1, -1).trim();
+        }
+        const q = target.indexOf('?');
+        if (q >= 0)
+            target = target.slice(0, q);
+        const h = target.indexOf('#');
+        if (h >= 0)
+            target = target.slice(0, h);
+        try {
+            target = decodeURI(target);
+        }
+        catch {
+            // keep original
+        }
+        target = target.replace(/\\/g, '/');
+        if (target.startsWith('/'))
+            throw new Error('Path must be relative');
+        const parts = (MdzArchiveCore.dirOf(base) + target).split('/');
+        const out = [];
+        for (const part of parts) {
+            if (part === '..') {
+                if (out.length === 0)
+                    throw new Error('Path escapes archive root');
+                out.pop();
+                continue;
+            }
+            if (part === '.')
+                continue;
+            out.push(part);
+        }
+        return out.join('/');
+    }
+    /**
+     * Finds an archive entry by path (case-insensitive fallback).
+     *
+     * @param path - Archive-relative path.
+     */
+    findEntry(path) {
+        const normalized = MdzArchiveCore.normalizePath(path);
+        if (this.zip.files[normalized])
+            return this.zip.files[normalized];
+        if (!MdzArchiveCore.entriesCache.has(this.zip)) {
+            MdzArchiveCore.entriesCache.set(this.zip, Object.fromEntries(Object.entries(this.zip.files).map(([k, v]) => [MdzArchiveCore.normalizePath(k).toLowerCase(), v])));
+        }
+        return MdzArchiveCore.entriesCache.get(this.zip)?.[normalized.toLowerCase()] ?? null;
+    }
+    /**
+     * Lists archive paths.
+     *
+     * @param options - Listing controls.
+     */
+    listPaths(options) {
+        return MdzArchiveCore.getArchivePaths(this.zip, options);
+    }
+    /**
+     * Lists archive entries with basic type metadata.
+     *
+     * @param options - Listing controls.
+     */
+    listEntries(options) {
+        const entries = MdzArchiveCore.getArchiveEntries(this.zip, options);
+        return entries.map((entry) => ({
+            path: entry.path,
+            isMarkdown: !entry.isDirectory && MdzArchiveCore.isMarkdownFile(entry.path),
+            isImage: !entry.isDirectory && MdzArchiveCore.isImagePath(entry.path),
+            isDirectory: entry.isDirectory
+        }));
+    }
+    /**
+     * Returns true if an entry path exists (file or directory).
+     *
+     * @param path - Archive-relative path.
+     */
+    hasEntry(path) {
+        return this.findEntryWithDirectoryFallback(path) != null;
+    }
+    /**
+     * Reads UTF-8 text content from an entry.
+     *
+     * @param path - Archive-relative file path.
+     */
+    async readText(path) {
+        const entry = this.getFileEntryOrThrow(path);
+        return String(await entry.async('text'));
+    }
+    /**
+     * Reads raw bytes from an entry.
+     *
+     * @param path - Archive-relative file path.
+     */
+    async readBytes(path) {
+        const entry = this.getFileEntryOrThrow(path);
+        const out = await entry.async('arraybuffer');
+        return new Uint8Array(out);
+    }
+    /**
+     * Reads entry content as raw base64 (no data URI prefix).
+     *
+     * @param path - Archive-relative file path.
+     */
+    async readBase64(path) {
+        const entry = this.getFileEntryOrThrow(path);
+        return String(await entry.async('base64'));
+    }
+    /**
+     * Reads entry content and returns a data URI string.
+     *
+     * @param path - Archive-relative file path.
+     * @param fallbackMime - Optional fallback MIME when extension is unknown.
+     */
+    async readDataUri(path, fallbackMime) {
+        const normalizedPath = MdzArchiveCore.normalizePath(path);
+        const base64 = await this.readBase64(normalizedPath);
+        const ext = MdzArchiveCore.getPathExtension(normalizedPath);
+        const mime = MDZ_IMAGE_MIME_TYPES[ext] ?? (fallbackMime?.trim() || 'application/octet-stream');
+        return `data:${mime};base64,${base64}`;
+    }
+    /**
+     * Finds orphaned image assets from markdown references.
+     *
+     * @param options - Scan options.
+     */
+    async findOrphanedAssets(options) {
+        const allEntries = this.listEntries();
+        const assetPaths = allEntries
+            .filter((entry) => entry.isImage)
+            .map((entry) => entry.path)
+            .sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }));
+        const assetPathSet = new Set(assetPaths.map((p) => p.toLowerCase()));
+        const scanMode = options?.scanMode ?? 'entrypoint';
+        const scannedMarkdownPaths = scanMode === 'all-markdown'
+            ? allEntries.filter((entry) => entry.isMarkdown).map((entry) => entry.path)
+            : [options?.entryPoint ? MdzArchiveCore.normalizePath(options.entryPoint) : await this.resolveEntryPoint()];
+        const referencedAssets = new Set();
+        const unresolvedReferences = [];
+        for (const markdownPath of scannedMarkdownPaths) {
+            const markdown = await this.readText(markdownPath);
+            const refs = MdzArchiveCore.extractMarkdownImageReferences(markdown);
+            for (const ref of refs) {
+                if (MdzArchiveCore.hasUriScheme(ref)) {
+                    unresolvedReferences.push({ sourcePath: markdownPath, reference: ref, reason: 'unsupported-scheme' });
+                    continue;
+                }
+                let resolved;
+                try {
+                    resolved = MdzArchiveCore.normalizePath(MdzArchiveCore.resolvePath(markdownPath, ref));
+                }
+                catch {
+                    unresolvedReferences.push({ sourcePath: markdownPath, reference: ref, reason: 'invalid-path' });
+                    continue;
+                }
+                const entry = this.findEntryWithDirectoryFallback(resolved);
+                if (!entry || entry.dir) {
+                    unresolvedReferences.push({ sourcePath: markdownPath, reference: ref, reason: 'not-found' });
+                    continue;
+                }
+                if (!MdzArchiveCore.isImagePath(resolved) || !assetPathSet.has(resolved.toLowerCase())) {
+                    unresolvedReferences.push({ sourcePath: markdownPath, reference: ref, reason: 'not-asset' });
+                    continue;
+                }
+                referencedAssets.add(MdzArchiveCore.resolveAssetPathCase(assetPaths, resolved));
+            }
+        }
+        const manifest = await this.readManifest();
+        if (manifest?.cover) {
+            const cover = MdzArchiveCore.normalizePath(manifest.cover);
+            if (assetPathSet.has(cover.toLowerCase())) {
+                referencedAssets.add(MdzArchiveCore.resolveAssetPathCase(assetPaths, cover));
+            }
+        }
+        const referencedAssetPaths = Array.from(referencedAssets).sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }));
+        const referencedSet = new Set(referencedAssetPaths.map((p) => p.toLowerCase()));
+        const orphanedAssetPaths = assetPaths.filter((p) => !referencedSet.has(p.toLowerCase()));
+        return {
+            scannedMarkdownPaths,
+            assetPaths,
+            referencedAssetPaths,
+            orphanedAssetPaths,
+            unresolvedReferences
+        };
+    }
+    /**
+     * Returns a normalized app/editor workspace model for this archive.
+     *
+     * @param options - Workspace open controls.
+     */
+    async openWorkspace(options) {
+        const validation = await this.validate();
+        const manifest = await this.readManifest().catch(() => null);
+        const mode = await this.resolveMode().catch(() => 'document');
+        const entryPoint = await this.resolveEntryPoint().catch(() => null);
+        const entries = this.listEntries();
+        const includeLazyReaders = options?.includeLazyAssetReaders !== false;
+        const documents = [];
+        for (const entry of entries.filter((item) => item.isMarkdown)) {
+            documents.push({
+                path: entry.path,
+                title: MdzArchiveCore.getDocumentTitle(entry.path, manifest),
+                text: await this.readText(entry.path),
+                isEntryPoint: !!entryPoint && entry.path.toLowerCase() === entryPoint.toLowerCase()
+            });
+        }
+        const assets = [];
+        for (const entry of entries.filter((item) => !item.isMarkdown && !item.isDirectory && item.path.toLowerCase() !== 'manifest.json')) {
+            const bytes = await this.readBytes(entry.path);
+            const mimeType = MdzArchiveCore.inferMimeType(entry.path);
+            const asset = {
+                path: entry.path,
+                fileName: MdzArchiveCore.basename(entry.path),
+                byteSize: bytes.byteLength,
+                mimeType,
+                kind: MdzArchiveCore.classifyAssetKind(entry.path, mimeType),
+                isPreviewable: MdzArchiveCore.isPreviewableAsset(entry.path, mimeType)
+            };
+            if (includeLazyReaders) {
+                asset.readBytes = () => this.readBytes(entry.path);
+                asset.readDataUri = () => this.readDataUri(entry.path, mimeType);
+            }
+            assets.push(asset);
+        }
+        const workspace = {
+            title: manifest?.title ?? null,
+            mode,
+            manifest,
+            entryPoint,
+            documents,
+            assets,
+            validation
+        };
+        if (options?.includeOrphanedAssetAnalysis) {
+            workspace.orphanedAssets = await this.findOrphanedAssets({ scanMode: options.orphanedAssetScanMode });
+        }
+        return workspace;
+    }
+    static validateManifest(manifest) {
+        if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json must be a JSON object.');
+        }
+        const candidate = manifest;
+        const validateMetadataNode = (value, path) => {
+            if (value == null)
+                return;
+            if (typeof value !== 'object' || Array.isArray(value)) {
+                throw new Error(`ERR_MANIFEST_INVALID: manifest.json "${path}" must be an object when provided.`);
+            }
+            const node = value;
+            for (const key of ['name', 'version', 'url']) {
+                const v = node[key];
+                if (v != null && typeof v !== 'string') {
+                    throw new Error(`ERR_MANIFEST_INVALID: manifest.json "${path}.${key}" must be a string when provided.`);
+                }
+            }
+        };
+        const validateByNode = (value, path) => {
+            if (value == null)
+                return;
+            if (typeof value !== 'object' || Array.isArray(value)) {
+                throw new Error(`ERR_MANIFEST_INVALID: manifest.json "${path}" must be an object when provided.`);
+            }
+            const node = value;
+            for (const key of ['name', 'email', 'url']) {
+                const v = node[key];
+                if (v != null && typeof v !== 'string') {
+                    throw new Error(`ERR_MANIFEST_INVALID: manifest.json "${path}.${key}" must be a string when provided.`);
+                }
+            }
+        };
+        const validateTimestamp = (value, path) => {
+            if (value == null)
+                return;
+            if (typeof value === 'string')
+                return;
+            if (typeof value !== 'object' || Array.isArray(value)) {
+                throw new Error(`ERR_MANIFEST_INVALID: manifest.json "${path}" must be a string or object when provided.`);
+            }
+            const node = value;
+            if (typeof node.when !== 'string' || node.when.trim() === '') {
+                throw new Error(`ERR_MANIFEST_INVALID: manifest.json "${path}.when" must be a non-empty string when "${path}" is an object.`);
+            }
+            validateByNode(node.by, `${path}.by`);
+        };
+        if (candidate.title != null && (typeof candidate.title !== 'string' || candidate.title.trim() === '')) {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json "title" must be a non-empty string when provided.');
+        }
+        if (candidate.mode != null) {
+            if (typeof candidate.mode !== 'string') {
+                throw new Error('ERR_MANIFEST_INVALID: manifest.json "mode" must be a string when provided.');
+            }
+            if (!MdzArchiveCore.SUPPORTED_MODES.includes(candidate.mode)) {
+                throw new Error(`ERR_MODE_UNSUPPORTED: manifest.json mode "${candidate.mode}" is not supported.`);
+            }
+        }
+        if (candidate.description != null && typeof candidate.description !== 'string') {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json "description" must be a string when provided.');
+        }
+        if (candidate.version != null && typeof candidate.version !== 'string') {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json "version" must be a string when provided.');
+        }
+        if (candidate.language != null && typeof candidate.language !== 'string') {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json "language" must be a string when provided.');
+        }
+        if (candidate.license != null && typeof candidate.license !== 'string') {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json "license" must be a string when provided.');
+        }
+        if (candidate.keywords != null) {
+            if (!Array.isArray(candidate.keywords) || candidate.keywords.some((k) => typeof k !== 'string')) {
+                throw new Error('ERR_MANIFEST_INVALID: manifest.json "keywords" must be an array of strings when provided.');
+            }
+        }
+        if (candidate.cover != null && typeof candidate.cover !== 'string') {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json "cover" must be a string when provided.');
+        }
+        if (candidate.entryPoint != null && typeof candidate.entryPoint !== 'string') {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json "entryPoint" must be a string when provided.');
+        }
+        if (candidate.entryPoint != null && MdzArchiveCore.validateArchivePath(candidate.entryPoint) != null) {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json "entryPoint" must be a valid archive-relative path.');
+        }
+        if (candidate.spec != null) {
+            if (typeof candidate.spec !== 'object' || Array.isArray(candidate.spec)) {
+                throw new Error('ERR_MANIFEST_INVALID: manifest.json "spec" must be an object when provided.');
+            }
+            const spec = candidate.spec;
+            if (spec.name != null && typeof spec.name !== 'string') {
+                throw new Error('ERR_MANIFEST_INVALID: manifest.json "spec.name" must be a string when provided.');
+            }
+            if (spec.version != null) {
+                if (typeof spec.version !== 'string' || !MdzArchiveCore.SEMVER_RE.test(spec.version)) {
+                    throw new Error('ERR_MANIFEST_INVALID: manifest.json "spec.version" must be a valid semver string when provided.');
+                }
+                const specMajor = Number.parseInt(spec.version.split('.')[0] ?? '0', 10);
+                if (specMajor > MdzArchiveCore.SUPPORTED_MDZ_MAJOR) {
+                    throw new Error(`ERR_VERSION_UNSUPPORTED: manifest.json spec.version ${spec.version} is not supported; this viewer supports major ${MdzArchiveCore.SUPPORTED_MDZ_MAJOR}.x only.`);
+                }
+            }
+        }
+        if (candidate.mdz != null) {
+            if (typeof candidate.mdz !== 'string' || !MdzArchiveCore.SEMVER_RE.test(candidate.mdz)) {
+                throw new Error('ERR_MANIFEST_INVALID: manifest.json "mdz" must be a valid semver string when provided.');
+            }
+            const major = Number.parseInt(candidate.mdz.split('.')[0] ?? '0', 10);
+            if (major > MdzArchiveCore.SUPPORTED_MDZ_MAJOR) {
+                throw new Error(`ERR_VERSION_UNSUPPORTED: manifest.json targets mdz ${candidate.mdz}, but this viewer supports major ${MdzArchiveCore.SUPPORTED_MDZ_MAJOR}.x only.`);
+            }
+        }
+        if (candidate.producer != null) {
+            if (typeof candidate.producer !== 'object' || Array.isArray(candidate.producer)) {
+                throw new Error('ERR_MANIFEST_INVALID: manifest.json "producer" must be an object when provided.');
+            }
+            const producer = candidate.producer;
+            validateMetadataNode(producer.application, 'producer.application');
+            validateMetadataNode(producer.core, 'producer.core');
+        }
+        if (candidate.author != null) {
+            validateByNode(candidate.author, 'author');
+        }
+        validateTimestamp(candidate.created, 'created');
+        validateTimestamp(candidate.modified, 'modified');
+    }
+    /**
+     * Parses and validates `manifest.json` if present.
+     *
+     * Missing or invalid cover references are normalized away in returned data.
+     */
+    async readManifest() {
+        if (MdzArchiveCore.manifestCache.has(this.zip)) {
+            return MdzArchiveCore.manifestCache.get(this.zip) ?? null;
+        }
+        const entry = this.zip.files['manifest.json'];
+        if (!entry) {
+            MdzArchiveCore.manifestCache.set(this.zip, null);
+            return null;
+        }
+        const raw = await entry.async('text');
+        let manifest;
+        try {
+            manifest = JSON.parse(String(raw));
+        }
+        catch {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json is not valid JSON');
+        }
+        MdzArchiveCore.validateManifest(manifest);
+        const normalized = { ...manifest };
+        if (normalized.cover) {
+            const coverPath = MdzArchiveCore.normalizePath(normalized.cover);
+            const coverPathError = MdzArchiveCore.validateArchivePath(coverPath);
+            const coverEntry = Object.entries(this.zip.files).find(([p]) => MdzArchiveCore.normalizePath(p).toLowerCase() === coverPath.toLowerCase())?.[1];
+            const coverExistsAsFile = !!coverEntry && !coverEntry.dir;
+            if (coverPathError || !coverExistsAsFile) {
+                delete normalized.cover;
+            }
+        }
+        MdzArchiveCore.manifestCache.set(this.zip, normalized);
+        return normalized;
+    }
+    /**
+     * Resolves archive interpretation mode using manifest data or the spec default.
+     */
+    async resolveMode() {
+        const manifest = await this.readManifest();
+        return manifest?.mode ?? 'document';
+    }
+    /**
+     * Validates archive conformance and returns errors/warnings.
+     */
+    async validate() {
+        const errors = [];
+        const warnings = [];
+        const archivePaths = MdzArchiveCore.getArchivePaths(this.zip);
+        for (const path of archivePaths) {
+            const pathError = MdzArchiveCore.validateArchivePath(path);
+            if (pathError)
+                errors.push(`ERR_PATH_INVALID: ${pathError}`);
+        }
+        let manifest = null;
+        let manifestReadFailed = false;
+        const manifestEntry = this.findEntry('manifest.json');
+        if (manifestEntry) {
+            let rawManifest = null;
+            try {
+                const rawText = await manifestEntry.async('text');
+                const parsed = JSON.parse(String(rawText));
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    rawManifest = parsed;
+                }
+            }
+            catch {
+                // readManifest() will report JSON parse errors as ERR_MANIFEST_INVALID
+            }
+            try {
+                manifest = await this.readManifest();
+            }
+            catch (error) {
+                manifestReadFailed = true;
+                errors.push(error instanceof Error ? error.message : String(error));
+            }
+            if (manifest) {
+                const specVersion = manifest.spec?.version;
+                if (!specVersion || specVersion.trim() === '') {
+                    warnings.push("manifest 'spec.version' is missing; version metadata is unavailable.");
+                }
+                else if (MdzArchiveCore.SEMVER_RE.test(specVersion)) {
+                    const major = Number.parseInt(specVersion.split('.')[0] ?? '0', 10);
+                    if (major < MdzArchiveCore.SUPPORTED_MDZ_MAJOR) {
+                        warnings.push(`manifest 'spec.version' major version ${major} is older than supported major ${MdzArchiveCore.SUPPORTED_MDZ_MAJOR}.`);
+                    }
+                }
+                if (manifest.entryPoint && !archivePaths.some((p) => p.toLowerCase() === manifest.entryPoint.toLowerCase())) {
+                    errors.push(`ERR_ENTRYPOINT_MISSING: manifest 'entryPoint' references '${manifest.entryPoint}' which does not exist in the archive.`);
+                }
+                const coverCandidate = typeof rawManifest?.cover === 'string' ? rawManifest.cover : manifest.cover;
+                if (coverCandidate) {
+                    const cover = MdzArchiveCore.normalizePath(coverCandidate);
+                    const coverEntry = this.findEntry(cover);
+                    if (!coverEntry || coverEntry.dir) {
+                        warnings.push(`manifest 'cover' references '${coverCandidate}' which does not exist in the archive.`);
+                    }
+                }
+            }
+        }
+        else {
+            warnings.push('No manifest.json present. Version metadata is unavailable.');
+        }
+        if (!manifestReadFailed) {
+            try {
+                await this.resolveEntryPoint();
+            }
+            catch (error) {
+                errors.push(error instanceof Error ? error.message : String(error));
+            }
+        }
+        return {
+            isValid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    /**
+     * Resolves the primary markdown entry point for rendering.
+     *
+     * @throws When no unambiguous entry point can be determined.
+     */
+    async resolveEntryPoint() {
+        const manifest = await this.readManifest();
+        const archivePaths = MdzArchiveCore.getArchivePaths(this.zip);
+        if (manifest?.entryPoint && !archivePaths.some((p) => p.toLowerCase() === manifest.entryPoint.toLowerCase())) {
+            throw new Error(`ERR_ENTRYPOINT_MISSING: manifest.json references "${manifest.entryPoint}" which is not in the archive`);
+        }
+        const resolved = MdzPackagerCore.resolveEntryPoint(archivePaths, manifest);
+        if (resolved)
+            return resolved;
+        const rootMd = archivePaths.filter((p) => !p.includes('/') && MdzArchiveCore.isMarkdownFile(p));
+        if (rootMd.length > 1) {
+            throw new Error('ERR_ENTRYPOINT_UNRESOLVED: Multiple Markdown files at the archive root and no manifest.json entryPoint. Add an index.md or manifest.json entryPoint.');
+        }
+        throw new Error('ERR_ENTRYPOINT_UNRESOLVED: No Markdown file found at the archive root.');
+    }
+    static getArchivePaths(zip, options) {
+        return MdzArchiveCore.getArchiveEntries(zip, options).map((entry) => entry.path);
+    }
+    static getArchiveEntries(zip, options) {
+        const includeDirectories = options?.includeDirectories === true;
+        const normalize = options?.normalize !== false;
+        const sort = options?.sort !== false;
+        const entries = Object.entries(zip.files)
+            .filter(([, entry]) => includeDirectories || !entry?.dir)
+            .map(([path, entry]) => ({
+            path: normalize ? MdzArchiveCore.normalizePath(path) : path,
+            isDirectory: !!entry?.dir
+        }));
+        if (sort) {
+            entries.sort((a, b) => a.path.localeCompare(b.path, undefined, { sensitivity: 'base' }));
+        }
+        return entries;
+    }
+    findEntryWithDirectoryFallback(path) {
+        const normalized = MdzArchiveCore.normalizePath(path);
+        const direct = this.findEntry(normalized);
+        if (direct)
+            return direct;
+        if (normalized.endsWith('/')) {
+            return this.findEntry(normalized.slice(0, -1));
+        }
+        return this.findEntry(`${normalized}/`);
+    }
+    getFileEntryOrThrow(path) {
+        const normalized = MdzArchiveCore.normalizePath(path);
+        const entry = this.findEntryWithDirectoryFallback(normalized);
+        if (!entry) {
+            throw new Error(`ERR_NOT_FOUND: Entry "${normalized}" was not found in archive.`);
+        }
+        if (entry.dir) {
+            throw new Error(`ERR_IS_DIRECTORY: Entry "${normalized}" is a directory.`);
+        }
+        return entry;
+    }
+    static getPathExtension(path) {
+        const slash = path.lastIndexOf('/');
+        const dot = path.lastIndexOf('.');
+        if (dot <= slash)
+            return '';
+        return path.slice(dot + 1).toLowerCase();
+    }
+    static isImagePath(path) {
+        return MdzArchiveCore.getPathExtension(path) in MDZ_IMAGE_MIME_TYPES;
+    }
+    static getDocumentTitle(path, manifest) {
+        const mapped = manifest?.files?.find((file) => file.path.toLowerCase() === path.toLowerCase());
+        if (mapped?.title?.trim())
+            return mapped.title.trim();
+        const fileName = MdzArchiveCore.basename(path).replace(/\.[^/.]+$/, '');
+        const title = fileName.replace(/[_-]+/g, ' ').trim();
+        return title || path;
+    }
+    static extractMarkdownImageReferences(markdown) {
+        const refs = [];
+        const re = new RegExp(MdzArchiveCore.MARKDOWN_IMAGE_REF_RE.source, 'g');
+        let match;
+        while ((match = re.exec(markdown)) != null) {
+            const raw = match[1]?.trim();
+            if (!raw)
+                continue;
+            refs.push(MdzArchiveCore.cleanMarkdownLinkTarget(raw));
+        }
+        return refs;
+    }
+    static cleanMarkdownLinkTarget(raw) {
+        let target = raw.trim();
+        if (target.startsWith('<') && target.endsWith('>')) {
+            target = target.slice(1, -1).trim();
+        }
+        const quotedTitleIndex = target.search(/\s+"/);
+        if (quotedTitleIndex > 0) {
+            target = target.slice(0, quotedTitleIndex).trim();
+        }
+        else {
+            const singleQuotedTitleIndex = target.search(/\s+'/);
+            if (singleQuotedTitleIndex > 0) {
+                target = target.slice(0, singleQuotedTitleIndex).trim();
+            }
+        }
+        return target;
+    }
+    static hasUriScheme(value) {
+        return /^[A-Za-z][A-Za-z\d+\-.]*:/.test(value);
+    }
+    static resolveAssetPathCase(assetPaths, resolvedPath) {
+        const lower = resolvedPath.toLowerCase();
+        const exact = assetPaths.find((p) => p.toLowerCase() === lower);
+        return exact ?? resolvedPath;
+    }
+    static removeEntryIgnoreCase(zip, targetPath) {
+        const targetLower = targetPath.toLowerCase();
+        for (const path of Object.keys(zip.files)) {
+            if (MdzArchiveCore.normalizePath(path).toLowerCase() === targetLower) {
+                zip.remove(path);
+            }
+        }
+    }
+    static isTextFile(path) {
+        return /\.(md|markdown|json|txt|css|html|htm|xml|svg|yaml|yml|toml)$/i.test(path);
+    }
+    static normaliseLf(content) {
+        return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    }
+    static async readExistingManifestObject(zip, requireValid) {
+        const manifestEntry = Object.entries(zip.files).find(([p, entry]) => MdzArchiveCore.normalizePath(p).toLowerCase() === 'manifest.json' && !entry.dir)?.[1];
+        if (!manifestEntry)
+            return null;
+        const raw = await manifestEntry.async('text');
+        try {
+            const parsed = JSON.parse(String(raw));
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                if (requireValid)
+                    throw new Error('ERR_MANIFEST_INVALID: Existing manifest.json is invalid: expected a JSON object.');
+                return null;
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (requireValid) {
+                if (error instanceof Error && /expected a JSON object/.test(error.message))
+                    throw error;
+                throw new Error('ERR_MANIFEST_INVALID: Existing manifest.json is invalid JSON.');
+            }
+            return null;
+        }
+    }
+    static async parseManifestObjectContent(content, requireValid) {
+        const raw = await MdzArchiveCore.readMutationInputAsText(content);
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                if (requireValid)
+                    throw new Error('ERR_MANIFEST_INVALID: Replacement manifest.json is invalid: expected a JSON object.');
+                return {};
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (requireValid) {
+                if (error instanceof Error && /expected a JSON object/.test(error.message))
+                    throw error;
+                throw new Error('ERR_MANIFEST_INVALID: Replacement manifest.json is invalid JSON.');
+            }
+            return {};
+        }
+    }
+    static ensureManifestSpecObject(manifest) {
+        let spec = manifest.spec;
+        if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+            spec = {};
+            manifest.spec = spec;
+        }
+        const specObj = spec;
+        if (typeof specObj.name !== 'string' || !specObj.name.trim()) {
+            specObj.name = 'mdzip-spec';
+        }
+        if (typeof specObj.version !== 'string' || !specObj.version.trim()) {
+            specObj.version = PRODUCER_SPEC_VERSION;
+        }
+    }
+    static stampManifestObject(manifest, setCreatedIfMissing) {
+        const now = new Date().toISOString();
+        const next = { ...manifest };
+        MdzArchiveCore.ensureManifestSpecObject(next);
+        if (setCreatedIfMissing && next.created == null) {
+            next.created = now;
+        }
+        const modified = next.modified;
+        if (modified && typeof modified === 'object' && !Array.isArray(modified)) {
+            next.modified = { ...modified, when: now };
+        }
+        else {
+            next.modified = now;
+        }
+        return next;
+    }
+    static ensureCreatableEntryPoint(archivePaths, manifest) {
+        if (manifest?.entryPoint && !archivePaths.some((p) => p.toLowerCase() === manifest.entryPoint.toLowerCase())) {
+            throw new Error(`ERR_ENTRYPOINT_MISSING: manifest 'entryPoint' references '${manifest.entryPoint}' which does not exist in the archive.`);
+        }
+        const resolved = MdzPackagerCore.resolveEntryPoint(archivePaths, manifest);
+        if (!resolved) {
+            throw new Error('ERR_ENTRYPOINT_UNRESOLVED: No unambiguous entry point could be determined. Add index.md at the archive root, keep exactly one root Markdown file, or set manifest.entryPoint.');
+        }
+    }
+    static async readMutationInputAsText(content) {
+        if (typeof content === 'string')
+            return content;
+        if (content instanceof Blob)
+            return content.text();
+        return new TextDecoder().decode(content);
+    }
+    static async readMutationInputAsBinary(content) {
+        if (typeof content === 'string')
+            return new TextEncoder().encode(content);
+        if (content instanceof Blob)
+            return content.arrayBuffer();
+        if (content instanceof Uint8Array)
+            return content;
+        return content;
+    }
+    static async writeZipEntry(zip, path, content) {
+        if (MdzArchiveCore.isTextFile(path)) {
+            const text = await MdzArchiveCore.readMutationInputAsText(content);
+            zip.file(path, MdzArchiveCore.normaliseLf(text));
+            return;
+        }
+        const binary = await MdzArchiveCore.readMutationInputAsBinary(content);
+        zip.file(path, binary);
+    }
+    static async finalizeMutation(zip) {
+        const bytes = await zip.generateAsync({
+            type: 'uint8array',
+            compression: 'DEFLATE',
+            compressionOptions: { level: 6 }
+        });
+        const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        const blob = new Blob([buffer], { type: 'application/zip' });
+        const archive = await MdzArchiveCore.open(buffer);
+        const manifest = await archive.readManifest();
+        const resolvedEntryPoint = await archive.resolveEntryPoint().catch(() => null);
+        return {
+            blob,
+            manifest,
+            resolvedEntryPoint,
+            archivePaths: MdzArchiveCore.getArchivePaths(zip)
+        };
+    }
+}
+/**
+ * Packaging helpers for creating `.mdz` archives from source files.
+ */
+export class MdzPackagerCore {
+    /**
+     * Default include globs for markdown and common image assets.
+     */
+    static DEFAULT_FILTERS = [
+        '**/*.md',
+        '**/*.markdown',
+        '**/*.png',
+        '**/*.jpg',
+        '**/*.jpeg',
+        '**/*.gif',
+        '**/*.webp',
+        '**/*.svg',
+        '**/*.avif'
+    ];
+    /**
+     * Normalizes input file paths for archive packaging.
+     *
+     * @param path - Source file path.
+     */
+    static normalizePath(path) {
+        return MdzArchiveCore.normalizePath(path).replace(/^\.\//, '');
+    }
+    /**
+     * Validates archive path constraints.
+     *
+     * @param path - Archive-relative path.
+     */
+    static validateArchivePath(path) {
+        return MdzArchiveCore.validateArchivePath(path);
+    }
+    /**
+     * Sanitizes one archive path segment by replacing forbidden characters.
+     *
+     * @param segment - Single path segment.
+     */
+    static sanitisePathSegment(segment) {
+        let out = '';
+        for (const c of segment) {
+            const code = c.charCodeAt(0);
+            if (/[\\:*?"<>|]/.test(c) || c === '\0' || (code >= 1 && code <= 31) || code === 127)
+                out += '_';
+            else
+                out += c;
+        }
+        out = out.trim();
+        if (!out)
+            return '_';
+        if (out === '.' || out === '..')
+            return out.replace(/\./g, '_');
+        return out;
+    }
+    /**
+     * Sanitizes a full archive path by normalizing each path segment.
+     *
+     * @param path - Candidate archive path.
+     */
+    static sanitiseArchivePath(path) {
+        return MdzPackagerCore.normalizePath(path)
+            .split('/')
+            .filter(Boolean)
+            .map(MdzPackagerCore.sanitisePathSegment)
+            .join('/');
+    }
+    /**
+     * Ensures archive path uniqueness by appending `-2`, `-3`, etc when needed.
+     *
+     * @param candidate - Desired archive path.
+     * @param usedPaths - Case-insensitive set of already-used paths.
+     */
+    static makeUniqueArchivePath(candidate, usedPaths) {
+        if (!usedPaths.has(candidate.toLowerCase())) {
+            usedPaths.add(candidate.toLowerCase());
+            return candidate;
+        }
+        const slash = candidate.lastIndexOf('/');
+        const dir = slash >= 0 ? candidate.slice(0, slash + 1) : '';
+        const name = slash >= 0 ? candidate.slice(slash + 1) : candidate;
+        const dot = name.lastIndexOf('.');
+        const base = dot >= 0 ? name.slice(0, dot) : name;
+        const ext = dot >= 0 ? name.slice(dot) : '';
+        let n = 2;
+        while (true) {
+            const next = `${dir}${base}-${n}${ext}`;
+            if (!usedPaths.has(next.toLowerCase())) {
+                usedPaths.add(next.toLowerCase());
+                return next;
+            }
+            n += 1;
+        }
+    }
+    /**
+     * Tests whether a path matches a glob pattern supporting `*`, `?`, and `**`.
+     *
+     * @param path - Archive-relative path.
+     * @param pattern - Glob pattern.
+     */
+    static globMatch(path, pattern) {
+        const pathParts = path.split('/').filter(Boolean);
+        const patternParts = pattern.replace(/\\/g, '/').split('/').filter(Boolean);
+        const segmentMatch = (segment, pat) => {
+            let si = 0;
+            let pi = 0;
+            let star = -1;
+            let match = 0;
+            while (si < segment.length) {
+                const patChar = pat.charAt(pi);
+                const segChar = segment.charAt(si);
+                if (pi < pat.length && (patChar === '?' || patChar.toLowerCase() === segChar.toLowerCase())) {
+                    si += 1;
+                    pi += 1;
+                }
+                else if (pi < pat.length && patChar === '*') {
+                    star = pi;
+                    pi += 1;
+                    match = si;
+                }
+                else if (star !== -1) {
+                    pi = star + 1;
+                    match += 1;
+                    si = match;
+                }
+                else {
+                    return false;
+                }
+            }
+            while (pi < pat.length && pat[pi] === '*')
+                pi += 1;
+            return pi === pat.length;
+        };
+        const matchParts = (pi, gi) => {
+            if (gi === patternParts.length)
+                return pi === pathParts.length;
+            const part = patternParts[gi];
+            if (part == null)
+                return false;
+            if (part === '**') {
+                if (gi === patternParts.length - 1)
+                    return true;
+                for (let skip = pi; skip <= pathParts.length; skip += 1) {
+                    if (matchParts(skip, gi + 1))
+                        return true;
+                }
+                return false;
+            }
+            if (pi >= pathParts.length)
+                return false;
+            const pathPart = pathParts[pi];
+            if (pathPart == null)
+                return false;
+            return segmentMatch(pathPart, part) && matchParts(pi + 1, gi + 1);
+        };
+        return matchParts(0, 0);
+    }
+    /**
+     * Returns true if a path matches at least one filter pattern.
+     *
+     * @param path - Archive-relative path.
+     * @param filters - Glob filter list.
+     */
+    static matchesAnyFilter(path, filters) {
+        return filters.some((pattern) => MdzPackagerCore.globMatch(path, pattern));
+    }
+    /**
+     * Builds a generated manifest from packaging options, or `null` when none is needed.
+     *
+     * @param rootName - Root/source label for fallback title.
+     * @param options - Packaging options.
+     */
+    static buildManifestFromOptions(rootName, options) {
+        const hasManifestOption = options.mapFiles
+            || !!options.title
+            || !!options.mode
+            || !!options.entryPoint
+            || !!options.language
+            || !!options.author
+            || !!options.description
+            || !!options.docVersion;
+        if (!hasManifestOption)
+            return null;
+        const now = new Date().toISOString();
+        return {
+            spec: {
+                name: 'mdzip-spec',
+                version: PRODUCER_SPEC_VERSION
+            },
+            producer: {
+                core: {
+                    name: 'mdzip-core-js',
+                    version: CORE_LIBRARY_VERSION,
+                    url: CORE_LIBRARY_URL
+                }
+            },
+            title: options.title || rootName,
+            mode: options.mode || undefined,
+            entryPoint: options.entryPoint || null,
+            language: options.language || 'en',
+            author: options.author ? { name: options.author } : undefined,
+            authors: options.author ? [{ name: options.author }] : null,
+            description: options.description || null,
+            version: options.docVersion || null,
+            created: now,
+            modified: now
+        };
+    }
+    /**
+     * Resolves entry point using manifest override, `index.md`, or single-root-markdown fallback.
+     *
+     * @param archivePaths - Archive file paths.
+     * @param manifest - Optional manifest with `entryPoint`.
+     */
+    static resolveEntryPoint(archivePaths, manifest) {
+        if (manifest?.entryPoint && archivePaths.some((p) => p.toLowerCase() === manifest.entryPoint.toLowerCase())) {
+            return manifest.entryPoint;
+        }
+        if (archivePaths.some((p) => p.toLowerCase() === 'index.md'))
+            return 'index.md';
+        const rootMarkdown = archivePaths.filter((p) => !p.includes('/') && MdzArchiveCore.isMarkdownFile(p));
+        return rootMarkdown.length === 1 ? (rootMarkdown[0] ?? null) : null;
+    }
+    /**
+     * Generates a simple index markdown page for archives without a clear entry point.
+     *
+     * @param markdownPaths - Markdown files to list.
+     * @param title - Optional heading title.
+     */
+    static buildGeneratedIndex(markdownPaths, title) {
+        const pageTitle = title && title.trim() ? title.trim() : 'Index';
+        const lines = [`# ${pageTitle}`, ''];
+        if (!markdownPaths.length) {
+            lines.push('No Markdown files were found.');
+            return lines.join('\n');
+        }
+        const sorted = markdownPaths.slice().sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }));
+        for (const p of sorted) {
+            const fileName = p.split('/').pop() || p;
+            const encoded = p.split('/').map(encodeURIComponent).join('/');
+            lines.push(`- [${fileName}](<${encoded}>)`);
+        }
+        lines.push('', '---', '', 'Generated by `mdz-core`', '', 'More info: [markdownzip.org](https://markdownzip.org)');
+        return lines.join('\n');
+    }
+    /**
+     * Creates a canonical MDZip manifest from app-safe metadata.
+     *
+     * @param metadata - Editable manifest fields.
+     */
+    static createManifest(metadata) {
+        const now = new Date().toISOString();
+        const author = typeof metadata?.author === 'string' ? { name: metadata.author } : (metadata?.author ?? undefined);
+        return {
+            spec: {
+                name: 'mdzip-spec',
+                version: PRODUCER_SPEC_VERSION
+            },
+            producer: {
+                core: {
+                    name: 'mdzip-core-js',
+                    version: CORE_LIBRARY_VERSION,
+                    url: CORE_LIBRARY_URL
+                }
+            },
+            title: metadata?.title ?? undefined,
+            mode: metadata?.mode ?? undefined,
+            entryPoint: metadata?.entryPoint ?? null,
+            language: metadata?.language ?? 'en',
+            author,
+            authors: author ? [author] : null,
+            description: metadata?.description ?? null,
+            version: metadata?.version ?? null,
+            license: metadata?.license ?? undefined,
+            keywords: metadata?.keywords ?? undefined,
+            cover: metadata?.cover ?? undefined,
+            created: now,
+            modified: now
+        };
+    }
+    /**
+     * Updates a manifest while preserving spec-managed fields unless explicitly changed elsewhere.
+     *
+     * @param manifest - Existing manifest, or `null` to create one.
+     * @param updates - Editable metadata updates.
+     * @param options - Timestamp controls.
+     */
+    static updateManifest(manifest, updates, options) {
+        const next = manifest ? { ...manifest } : MdzPackagerCore.createManifest(updates);
+        MdzPackagerCore.ensureCanonicalManifest(next, options);
+        if (updates) {
+            if ('title' in updates)
+                next.title = updates.title ?? undefined;
+            if ('author' in updates) {
+                const author = typeof updates.author === 'string' ? { name: updates.author } : (updates.author ?? undefined);
+                next.author = author;
+                next.authors = author ? [author] : null;
+            }
+            if ('description' in updates)
+                next.description = updates.description ?? null;
+            if ('keywords' in updates)
+                next.keywords = updates.keywords ?? undefined;
+            if ('language' in updates)
+                next.language = updates.language ?? null;
+            if ('license' in updates)
+                next.license = updates.license ?? undefined;
+            if ('version' in updates)
+                next.version = updates.version ?? null;
+            if ('cover' in updates)
+                next.cover = updates.cover ?? undefined;
+            if ('mode' in updates)
+                next.mode = updates.mode ?? undefined;
+            if ('entryPoint' in updates)
+                next.entryPoint = updates.entryPoint ?? null;
+        }
+        MdzPackagerCore.ensureCanonicalManifest(next, options);
+        return next;
+    }
+    /**
+     * Splits a manifest into spec-managed fields and ordinary editable metadata.
+     *
+     * @param manifest - Manifest to split.
+     */
+    static splitManifestMetadata(manifest) {
+        return {
+            reserved: {
+                spec: manifest.spec,
+                producer: manifest.producer,
+                created: manifest.created,
+                modified: manifest.modified,
+                entryPoint: manifest.entryPoint,
+                mode: manifest.mode,
+                files: manifest.files
+            },
+            editable: {
+                title: manifest.title ?? null,
+                author: manifest.author ?? null,
+                description: manifest.description ?? null,
+                keywords: manifest.keywords ?? null,
+                language: manifest.language ?? null,
+                license: manifest.license ?? null,
+                version: manifest.version ?? null,
+                cover: manifest.cover ?? null
+            }
+        };
+    }
+    /**
+     * Creates a workspace asset from a browser `File`/`Blob` or raw bytes.
+     *
+     * @param source - Asset source.
+     * @param targetPath - Optional archive path override.
+     */
+    static async createWorkspaceAssetFromFile(source, targetPath) {
+        const isFile = typeof File !== 'undefined' && source instanceof File;
+        const isBlob = typeof Blob !== 'undefined' && source instanceof Blob;
+        const path = MdzPackagerCore.normalizePath(targetPath || (isFile ? source.name : 'asset.bin'));
+        const pathError = MdzPackagerCore.validateArchivePath(path);
+        if (pathError)
+            throw new Error(`ERR_PATH_INVALID: ${pathError}`);
+        const bytes = await MdzPackagerCore.readBinarySource(source);
+        const mimeType = isBlob && source.type ? source.type : MdzArchiveCore.inferMimeType(path);
+        return {
+            path,
+            fileName: MdzArchiveCore.basename(path),
+            byteSize: bytes.byteLength,
+            mimeType,
+            kind: MdzArchiveCore.classifyAssetKind(path, mimeType),
+            isPreviewable: MdzArchiveCore.isPreviewableAsset(path, mimeType),
+            bytes
+        };
+    }
+    /**
+     * Exports a workspace asset as a browser-safe `Blob`.
+     *
+     * @param asset - Workspace asset.
+     */
+    static async exportWorkspaceAsset(asset) {
+        const bytes = await MdzPackagerCore.readWorkspaceAssetBytes(asset);
+        const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        return new Blob([buffer], { type: asset.mimeType || MdzArchiveCore.inferMimeType(asset.path) });
+    }
+    /**
+     * Builds an `.mdz` archive from a normalized workspace.
+     *
+     * @param workspace - Workspace model.
+     * @param options - Build controls and metadata overrides.
+     * @param zipWriterFactory - Optional custom zip writer.
+     */
+    static async buildWorkspace(workspace, options, zipWriterFactory) {
+        const entryPoint = options?.entryPoint ?? workspace.entryPoint ?? workspace.documents.find((doc) => doc.isEntryPoint)?.path ?? workspace.documents[0]?.path ?? null;
+        const mode = options?.mode ?? workspace.mode;
+        const title = options?.title ?? workspace.title ?? workspace.manifest?.title ?? null;
+        const manifest = MdzPackagerCore.updateManifest(workspace.manifest, {
+            ...(options?.metadata ?? {}),
+            title,
+            mode,
+            entryPoint
+        });
+        const files = [
+            ...workspace.documents.map((document) => ({
+                path: document.path,
+                text: document.text
+            })),
+            ...(await Promise.all(workspace.assets.map(async (asset) => ({
+                path: asset.path,
+                data: await MdzPackagerCore.readWorkspaceAssetBytes(asset)
+            })))),
+            {
+                path: 'manifest.json',
+                text: JSON.stringify(manifest, null, 2)
+            }
+        ];
+        return MdzPackagerCore.buildArchive(files, options?.rootName || title || 'MDZip Workspace', {
+            createIndex: false,
+            mapFiles: false,
+            filters: ['**/*', '*']
+        }, zipWriterFactory);
+    }
+    static normalizeLf(content) {
+        return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+    }
+    static isTextFile(path) {
+        return /\.(md|markdown|json|txt|css|html|htm|xml|svg|yaml|yml|toml)$/i.test(path);
+    }
+    static async readProvidedManifest(selected) {
+        const manifestItem = selected.find((item) => item.archivePath.toLowerCase() === 'manifest.json');
+        if (!manifestItem)
+            return null;
+        const raw = manifestItem.file ? await manifestItem.file.text() : (manifestItem.text ?? '');
+        let manifest;
+        try {
+            manifest = JSON.parse(raw);
+        }
+        catch {
+            throw new Error('ERR_MANIFEST_INVALID: manifest.json is not valid JSON');
+        }
+        MdzArchiveCore.validateManifest(manifest);
+        return manifest;
+    }
+    static ensureCanonicalManifest(manifest, options) {
+        const now = new Date().toISOString();
+        manifest.spec = {
+            ...(manifest.spec ?? {}),
+            name: manifest.spec?.name || 'mdzip-spec',
+            version: manifest.spec?.version || PRODUCER_SPEC_VERSION
+        };
+        manifest.producer = {
+            ...(manifest.producer ?? {}),
+            core: {
+                ...(manifest.producer?.core ?? {}),
+                name: manifest.producer?.core?.name || 'mdzip-core-js',
+                version: manifest.producer?.core?.version || CORE_LIBRARY_VERSION,
+                url: manifest.producer?.core?.url || CORE_LIBRARY_URL
+            }
+        };
+        if (options?.setCreatedIfMissing !== false && manifest.created == null) {
+            manifest.created = now;
+        }
+        if (options?.refreshModified !== false) {
+            const modified = manifest.modified;
+            if (modified && typeof modified === 'object' && !Array.isArray(modified)) {
+                manifest.modified = { ...modified, when: now };
+            }
+            else {
+                manifest.modified = now;
+            }
+        }
+    }
+    static async readBinarySource(source) {
+        if (source instanceof Uint8Array)
+            return source;
+        if (source instanceof ArrayBuffer)
+            return new Uint8Array(source);
+        if (typeof source.arrayBuffer === 'function')
+            return new Uint8Array(await source.arrayBuffer());
+        throw new Error('ERR_ASSET_BYTES_INVALID: Asset source is not readable as bytes.');
+    }
+    static async readWorkspaceAssetBytes(asset) {
+        if (asset.bytes)
+            return MdzPackagerCore.readBinarySource(asset.bytes);
+        if (asset.readBytes)
+            return asset.readBytes();
+        throw new Error(`ERR_ASSET_BYTES_MISSING: Asset "${asset.path}" has no bytes or readBytes() source.`);
+    }
+    /**
+     * Builds an `.mdz` archive from input files and packaging options.
+     *
+     * @param files - Source file candidates.
+     * @param rootName - Root/source label for generated metadata.
+     * @param options - Packaging options.
+     * @param zipWriterFactory - Optional custom zip writer.
+     */
+    static async buildArchive(files, rootName, options, zipWriterFactory) {
+        const cleanInput = files
+            .map((f) => ({ path: MdzPackagerCore.normalizePath(f.path), file: f.file, data: f.data, text: f.text }))
+            .filter((f) => f.path && !f.path.endsWith('/'));
+        if (!cleanInput.length) {
+            throw new Error('ERR_PACK_NO_INPUT: No files found to package.');
+        }
+        let manifest = MdzPackagerCore.buildManifestFromOptions(rootName, options);
+        const skipMap = new Map();
+        const usedPaths = new Set();
+        const selected = [];
+        const manifestFiles = [];
+        let invalidPathCount = 0;
+        let sanitizedPathCount = 0;
+        const addSkip = (reason) => {
+            skipMap.set(reason, (skipMap.get(reason) || 0) + 1);
+        };
+        for (const item of cleanInput) {
+            const originalPath = item.path;
+            let archivePath = originalPath;
+            if (!MdzPackagerCore.matchesAnyFilter(originalPath, options.filters)) {
+                addSkip('excluded by filter');
+                continue;
+            }
+            if (manifest && archivePath.toLowerCase() === 'manifest.json') {
+                addSkip('manifest.json replaced by generated manifest');
+                continue;
+            }
+            const pathError = MdzPackagerCore.validateArchivePath(archivePath);
+            if (pathError) {
+                invalidPathCount += 1;
+                if (!options.mapFiles) {
+                    addSkip('invalid path for MDZ rules');
+                    continue;
+                }
+                archivePath = MdzPackagerCore.makeUniqueArchivePath(MdzPackagerCore.sanitiseArchivePath(archivePath), usedPaths);
+                sanitizedPathCount += 1;
+            }
+            else {
+                archivePath = MdzPackagerCore.makeUniqueArchivePath(archivePath, usedPaths);
+            }
+            const selectedItem = { archivePath, originalPath };
+            if (item.file)
+                selectedItem.file = item.file;
+            if (item.data)
+                selectedItem.data = item.data;
+            if (item.text != null)
+                selectedItem.text = item.text;
+            selected.push(selectedItem);
+            if (options.mapFiles && manifest && MdzArchiveCore.isMarkdownFile(archivePath)) {
+                const base = originalPath.split('/').pop()?.replace(/\.[^/.]+$/, '') || originalPath;
+                manifestFiles.push({ path: archivePath, originalPath, title: base.replace(/[_-]+/g, ' ').trim() || originalPath });
+            }
+        }
+        if (!manifest) {
+            manifest = await MdzPackagerCore.readProvidedManifest(selected);
+        }
+        let archivePaths = selected.map((f) => f.archivePath);
+        let resolvedEntryPoint = MdzPackagerCore.resolveEntryPoint(archivePaths, manifest);
+        const warningMessages = [];
+        const markdownPaths = archivePaths.filter(MdzArchiveCore.isMarkdownFile);
+        if (!manifest?.mode && markdownPaths.length > 1) {
+            warningMessages.push('Archive contains multiple Markdown files and no explicit manifest.mode; consumers will default to document mode. If these files are intended as separate documents, set mode: "project".');
+        }
+        if (options.createIndex && !resolvedEntryPoint) {
+            if (manifest?.entryPoint) {
+                throw new Error(`ERR_PACK_ENTRYPOINT_MISSING: Manifest entry-point "${manifest.entryPoint}" does not exist.`);
+            }
+            const sortedMarkdownPaths = markdownPaths.slice().sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }));
+            const generated = MdzPackagerCore.buildGeneratedIndex(sortedMarkdownPaths, options.title || rootName);
+            selected.push({ archivePath: 'index.md', originalPath: '[generated]', text: generated });
+            archivePaths = selected.map((f) => f.archivePath);
+            resolvedEntryPoint = 'index.md';
+            if (manifest)
+                manifest.entryPoint = 'index.md';
+        }
+        if (manifest?.entryPoint && !archivePaths.some((p) => p.toLowerCase() === manifest.entryPoint.toLowerCase())) {
+            throw new Error(`ERR_PACK_ENTRYPOINT_MISSING: Manifest entry-point "${manifest.entryPoint}" does not exist in archive.`);
+        }
+        if (options.mapFiles && manifest) {
+            manifest.files = manifestFiles;
+        }
+        const factory = zipWriterFactory ?? MdzPackagerCore.getDefaultZipWriterFactory();
+        const zip = factory.create();
+        for (const item of selected) {
+            if (item.file) {
+                if (MdzPackagerCore.isTextFile(item.archivePath)) {
+                    const text = await item.file.text();
+                    zip.file(item.archivePath, MdzPackagerCore.normalizeLf(text));
+                }
+                else {
+                    const buffer = await item.file.arrayBuffer();
+                    zip.file(item.archivePath, buffer);
+                }
+            }
+            else if (item.data) {
+                if (MdzPackagerCore.isTextFile(item.archivePath)) {
+                    const bytes = await MdzPackagerCore.readBinarySource(item.data);
+                    const text = new TextDecoder().decode(bytes);
+                    zip.file(item.archivePath, MdzPackagerCore.normalizeLf(text));
+                }
+                else {
+                    const bytes = await MdzPackagerCore.readBinarySource(item.data);
+                    zip.file(item.archivePath, bytes);
+                }
+            }
+            else {
+                const content = item.text || '';
+                if (MdzPackagerCore.isTextFile(item.archivePath)) {
+                    zip.file(item.archivePath, MdzPackagerCore.normalizeLf(content));
+                }
+                else {
+                    zip.file(item.archivePath, content);
+                }
+            }
+        }
+        if (manifest) {
+            zip.file('manifest.json', JSON.stringify(manifest, null, 2));
+        }
+        const blob = await zip.generateAsync({ type: 'blob', compression: 'DEFLATE', compressionOptions: { level: 6 } });
+        return {
+            blob,
+            manifest,
+            resolvedEntryPoint,
+            archivePaths,
+            selected,
+            warnings: {
+                invalidPathCount,
+                sanitizedPathCount,
+                skippedByReason: Object.fromEntries(skipMap.entries()),
+                messages: warningMessages,
+                unresolvedEntry: !resolvedEntryPoint
+            }
+        };
+    }
+    static getDefaultZipWriterFactory() {
+        return {
+            create() {
+                return new JSZip();
+            }
+        };
+    }
+}
+//# sourceMappingURL=mdz-core.js.map