@mdzip/core-js 1.2.1

package/dist/mdz-core.d.ts

@@ -0,0 +1,866 @@
+type MdzCoreZipAsyncKind = 'text' | 'base64' | 'arraybuffer';
+/**
+ * Binary input accepted for opening an existing `.mdz` archive.
+ */
+export type MdzCoreArchiveBinary = Blob | ArrayBuffer | Uint8Array;
+/**
+ * Content input accepted when mutating archive entries.
+ *
+ * String values are written as UTF-8 text; binary values are written as raw bytes.
+ */
+export type MdzArchiveMutationInput = File | Blob | ArrayBuffer | Uint8Array | string;
+interface ZipEntry {
+    name: string;
+    dir: boolean;
+    async(kind: MdzCoreZipAsyncKind): Promise<string | ArrayBuffer>;
+}
+interface ZipLike {
+    files: Record<string, ZipEntry>;
+}
+interface ZipFactoryLike {
+    loadAsync(data: MdzCoreArchiveBinary): Promise<ZipLike>;
+}
+interface ZipWriterLike {
+    file(path: string, data: string | ArrayBuffer | Uint8Array): void;
+    generateAsync(options: {
+        type: 'blob';
+        compression: 'DEFLATE';
+        compressionOptions: {
+            level: number;
+        };
+    }): Promise<Blob>;
+}
+interface ZipWriterFactoryLike {
+    create(): ZipWriterLike;
+}
+/**
+ * Author/contact metadata used by manifest fields.
+ */
+export interface MdzManifestAuthor {
+    /** Human-readable display name. */
+    name?: string;
+    /** Optional contact email address. */
+    email?: string;
+    /** Optional author profile/home URL. */
+    url?: string;
+}
+/**
+ * Identity metadata used by timestamp `by` blocks.
+ */
+export interface MdzManifestBy {
+    /** Display name for creator/modifier attribution. */
+    name?: string;
+    /** Optional contact email address. */
+    email?: string;
+    /** Optional profile/home URL. */
+    url?: string;
+}
+/**
+ * Object-form timestamp metadata used by draft 1.0.x manifests.
+ */
+export interface MdzManifestTimestampObject {
+    /** ISO-8601 timestamp value. */
+    when: string;
+    /** Optional identity metadata for who performed the action. */
+    by?: MdzManifestBy;
+}
+/**
+ * Specification compatibility metadata for the archive manifest.
+ */
+export interface MdzManifestSpec {
+    /** Spec identifier (for example `mdzip-spec`). */
+    name?: string;
+    /** Target spec version string (semver). */
+    version?: string;
+}
+/**
+ * Producer metadata node describing an app/core identity.
+ */
+export interface MdzManifestProducerNode {
+    /** Producer display name. */
+    name?: string;
+    /** Producer version string. */
+    version?: string;
+    /** Producer homepage/repository URL. */
+    url?: string;
+}
+/**
+ * Producer metadata grouping for application and reusable core.
+ */
+export interface MdzManifestProducer {
+    /** Top-level application/tool metadata. */
+    application?: MdzManifestProducerNode;
+    /** Reusable core/runtime metadata used by the producer app. */
+    core?: MdzManifestProducerNode;
+}
+/**
+ * Optional file-map entry used when source files are remapped during packaging.
+ */
+export interface MdzManifestFileMapEntry {
+    /** Final archive-relative path after normalization/sanitization. */
+    path: string;
+    /** Original source-relative path before remapping. */
+    originalPath: string;
+    /** Human-friendly title derived from file name/source. */
+    title: string;
+}
+/**
+ * Supported archive interpretation modes defined by the spec.
+ */
+export type MdzManifestMode = 'document' | 'project';
+/**
+ * Parsed shape of `manifest.json` as supported by this library.
+ *
+ * Includes current fields plus legacy draft compatibility fields.
+ */
+export interface MdzManifest {
+    /** Legacy pre-`spec.version` manifest version field. */
+    mdz?: string;
+    /** Specification compatibility metadata. */
+    spec?: MdzManifestSpec;
+    /** Producer provenance metadata. */
+    producer?: MdzManifestProducer;
+    /** Primary author attribution metadata. */
+    author?: MdzManifestAuthor;
+    /** Human-readable document title. */
+    title?: string;
+    /** Archive interpretation mode. */
+    mode?: MdzManifestMode;
+    /** Primary Markdown entry path, archive-relative. */
+    entryPoint?: string | null;
+    /** Natural language tag (for example `en`, `fr-CA`). */
+    language?: string | null;
+    /** Legacy plural author field retained for compatibility. */
+    authors?: MdzManifestAuthor[] | null;
+    /** Short document summary/description. */
+    description?: string | null;
+    /** Document version (not spec version). */
+    version?: string | null;
+    /** Creation timestamp (string or draft object form). */
+    created?: string | MdzManifestTimestampObject;
+    /** Last-modified timestamp (string or draft object form). */
+    modified?: string | MdzManifestTimestampObject;
+    /** SPDX ID or license URL. */
+    license?: string;
+    /** Keyword list used for cataloging/search. */
+    keywords?: string[];
+    /** Archive-relative cover asset path. */
+    cover?: string;
+    /** Optional file-map metadata generated during packing. */
+    files?: MdzManifestFileMapEntry[];
+}
+/**
+ * Packaging options used by {@link MdzPackagerCore.buildArchive}.
+ */
+export interface MdzPackOptions {
+    /** Generate `index.md` when no unambiguous entry point exists. */
+    createIndex: boolean;
+    /** Enable path sanitization and include manifest file-map metadata. */
+    mapFiles: boolean;
+    /** Glob filters that determine which input files are included. */
+    filters: string[];
+    /** Optional manifest title override. */
+    title?: string | null;
+    /** Optional archive interpretation mode. */
+    mode?: MdzManifestMode | null;
+    /** Optional manifest entry point override. */
+    entryPoint?: string | null;
+    /** Optional language tag override. */
+    language?: string | null;
+    /** Optional single-author display name. */
+    author?: string | null;
+    /** Optional manifest description override. */
+    description?: string | null;
+    /** Optional document version field value. */
+    docVersion?: string | null;
+}
+/**
+ * Single source file candidate for packaging.
+ */
+export interface MdzPackInputFile {
+    /** Source-relative path used as the archive path candidate. */
+    path: string;
+    /** Browser `File` source for binary/text loading. */
+    file?: File;
+    /** Direct binary source when not providing `file`. */
+    data?: ArrayBuffer | Uint8Array | Blob;
+    /** Direct text source when not providing `file`. */
+    text?: string;
+}
+/**
+ * Internal/returned representation of a file selected for archive output.
+ */
+export interface MdzSelectedFile {
+    /** Final archive-relative output path. */
+    archivePath: string;
+    /** Original source path before remapping/sanitization. */
+    originalPath: string;
+    /** Original `File` input when provided. */
+    file?: File;
+    /** In-memory binary content when provided/generated. */
+    data?: ArrayBuffer | Uint8Array | Blob;
+    /** In-memory text content when provided/generated. */
+    text?: string;
+}
+/**
+ * Non-fatal packaging warnings and counters produced during archive build.
+ */
+export interface MdzPackWarnings {
+    /** Count of source paths that failed strict archive path validation. */
+    invalidPathCount: number;
+    /** Count of paths that were sanitized and remapped. */
+    sanitizedPathCount: number;
+    /** Breakdown of skipped files by reason key. */
+    skippedByReason: Record<string, number>;
+    /** Advisory packaging warnings for callers to surface to users. */
+    messages?: string[];
+    /** True when no entry point could be resolved at build completion. */
+    unresolvedEntry: boolean;
+}
+/**
+ * Result object returned by archive build operations.
+ */
+export interface MdzPackBuildResult {
+    /** Final archive blob payload. */
+    blob: Blob;
+    /** Manifest written to archive, when present. */
+    manifest: MdzManifest | null;
+    /** Resolved primary entry path (or `null`). */
+    resolvedEntryPoint: string | null;
+    /** All file paths written into the archive. */
+    archivePaths: string[];
+    /** Detailed selection list for included/generated files. */
+    selected: MdzSelectedFile[];
+    /** Packaging warnings/counters. */
+    warnings: MdzPackWarnings;
+}
+/**
+ * Conformance validation summary for an archive.
+ */
+export interface MdzValidationResult {
+    /** True when no validation errors were found. */
+    isValid: boolean;
+    /** Fatal/non-conformant issues discovered during validation. */
+    errors: string[];
+    /** Non-fatal advisory findings discovered during validation. */
+    warnings: string[];
+}
+/**
+ * Compact validation state for UI save/status indicators.
+ */
+export type MdzValidationStatus = 'valid' | 'warning' | 'error';
+/**
+ * Result object returned by archive mutation operations.
+ */
+export interface MdzArchiveMutationResult {
+    /** New archive blob generated after mutation. */
+    blob: Blob;
+    /** Parsed manifest after mutation, when present. */
+    manifest: MdzManifest | null;
+    /** Resolved primary entry path after mutation, if any. */
+    resolvedEntryPoint: string | null;
+    /** Archive file paths present after mutation. */
+    archivePaths: string[];
+}
+/**
+ * Controls archive path/entry listing output.
+ */
+export interface MdzArchiveListOptions {
+    /** Include directory entries. Defaults to `false`. */
+    includeDirectories?: boolean;
+    /** Normalize paths via `normalizePath`. Defaults to `true`. */
+    normalize?: boolean;
+    /** Sort output paths case-insensitively. Defaults to `true`. */
+    sort?: boolean;
+}
+/**
+ * Metadata for one archive entry returned by `listEntries`.
+ */
+export interface MdzArchiveEntryInfo {
+    /** Archive-relative path. */
+    path: string;
+    /** True when entry extension is Markdown. */
+    isMarkdown: boolean;
+    /** True when entry extension is known image type. */
+    isImage: boolean;
+    /** True when entry is a directory. */
+    isDirectory: boolean;
+}
+/**
+ * Optional controls for orphaned-asset analysis.
+ */
+export interface MdzOrphanedAssetsOptions {
+    /**
+     * Markdown scan mode.
+     * - `entrypoint`: scan only the resolved/selected entry point (default)
+     * - `all-markdown`: scan all Markdown files in archive
+     */
+    scanMode?: 'entrypoint' | 'all-markdown';
+    /** Optional explicit markdown entry path to scan for `entrypoint` mode. */
+    entryPoint?: string;
+}
+/**
+ * One unresolved or ignored image reference observed during scan.
+ */
+export interface MdzOrphanedAssetReferenceIssue {
+    /** Markdown file where the reference was found. */
+    sourcePath: string;
+    /** Raw reference value from Markdown. */
+    reference: string;
+    /** Normalized reason for why the reference was not counted. */
+    reason: 'unsupported-scheme' | 'invalid-path' | 'not-found' | 'not-asset';
+}
+/**
+ * Result for orphaned image analysis.
+ */
+export interface MdzOrphanedAssetsResult {
+    /** Markdown files scanned for references. */
+    scannedMarkdownPaths: string[];
+    /** All image-asset paths in archive considered by v1 analysis. */
+    assetPaths: string[];
+    /** Asset paths referenced by scanned markdown and/or manifest cover. */
+    referencedAssetPaths: string[];
+    /** Asset paths not referenced by scanned markdown/cover. */
+    orphanedAssetPaths: string[];
+    /** References that could not be counted as valid image asset references. */
+    unresolvedReferences: MdzOrphanedAssetReferenceIssue[];
+}
+/**
+ * Asset classification used by normalized workspace models.
+ */
+export type MdzWorkspaceAssetKind = 'image' | 'audio' | 'video' | 'font' | 'data' | 'other';
+/**
+ * Options for opening an archive as an app-friendly workspace.
+ */
+export interface MdzOpenWorkspaceOptions {
+    /** Include orphaned image analysis in the returned workspace. Defaults to `false`. */
+    includeOrphanedAssetAnalysis?: boolean;
+    /** Scan mode used when orphaned analysis is enabled. Defaults to `entrypoint`. */
+    orphanedAssetScanMode?: 'entrypoint' | 'all-markdown';
+    /** Include lazy `readBytes` and `readDataUri` functions on assets. Defaults to `true`. */
+    includeLazyAssetReaders?: boolean;
+}
+/**
+ * One Markdown document in an opened workspace.
+ */
+export interface MdzWorkspaceDocument {
+    /** Archive-relative document path. */
+    path: string;
+    /** Human-readable title for app navigation. */
+    title: string;
+    /** UTF-8 Markdown source text. */
+    text: string;
+    /** True when this document is the resolved archive entry point. */
+    isEntryPoint: boolean;
+}
+/**
+ * One non-Markdown, non-manifest asset in an opened workspace.
+ */
+export interface MdzWorkspaceAsset {
+    /** Archive-relative asset path. */
+    path: string;
+    /** Base file name. */
+    fileName: string;
+    /** Asset byte length. */
+    byteSize: number;
+    /** Inferred MIME type. */
+    mimeType: string;
+    /** Broad asset kind inferred from MIME type/extension. */
+    kind: MdzWorkspaceAssetKind;
+    /** True when common browser preview surfaces can display the asset. */
+    isPreviewable: boolean;
+    /** Optional in-memory bytes used by buildWorkspace/import flows. */
+    bytes?: ArrayBuffer | Uint8Array | Blob;
+    /** Lazy byte reader for archives opened through `openWorkspace`. */
+    readBytes?: () => Promise<Uint8Array>;
+    /** Lazy data-URI reader for previewable assets. */
+    readDataUri?: () => Promise<string>;
+}
+/**
+ * Normalized archive workspace for app shells and editor hosts.
+ */
+export interface MdzWorkspace {
+    /** Manifest title, or `null` when unavailable. */
+    title: string | null;
+    /** Resolved archive interpretation mode. */
+    mode: MdzManifestMode;
+    /** Parsed manifest when present and valid. */
+    manifest: MdzManifest | null;
+    /** Resolved primary Markdown entry path, or `null` when unresolved. */
+    entryPoint: string | null;
+    /** All Markdown documents in archive path order. */
+    documents: MdzWorkspaceDocument[];
+    /** All non-Markdown, non-manifest assets in archive path order. */
+    assets: MdzWorkspaceAsset[];
+    /** Archive validation summary. */
+    validation: MdzValidationResult;
+    /** Optional orphaned image analysis. */
+    orphanedAssets?: MdzOrphanedAssetsResult;
+}
+/**
+ * App-safe manifest metadata fields.
+ */
+export interface MdzManifestEditableMetadata {
+    title?: string | null;
+    author?: MdzManifestAuthor | string | null;
+    description?: string | null;
+    keywords?: string[] | null;
+    language?: string | null;
+    license?: string | null;
+    version?: string | null;
+    cover?: string | null;
+}
+/**
+ * Spec-managed manifest fields apps should normally avoid free-form editing.
+ */
+export interface MdzManifestReservedFields {
+    spec?: MdzManifestSpec;
+    producer?: MdzManifestProducer;
+    created?: string | MdzManifestTimestampObject;
+    modified?: string | MdzManifestTimestampObject;
+    entryPoint?: string | null;
+    mode?: MdzManifestMode;
+    files?: MdzManifestFileMapEntry[];
+}
+/**
+ * Options for canonical manifest creation and updates.
+ */
+export interface MdzManifestUpdateOptions {
+    /** Set `created` when creating a new manifest. Defaults to `true`. */
+    setCreatedIfMissing?: boolean;
+    /** Refresh `modified`. Defaults to `true`. */
+    refreshModified?: boolean;
+}
+/**
+ * Options for building an archive from a normalized workspace.
+ */
+export interface MdzBuildWorkspaceOptions {
+    /** Fallback root/source label. Defaults to workspace title or `MDZip Workspace`. */
+    rootName?: string;
+    /** Optional manifest metadata updates applied before packaging. */
+    metadata?: MdzManifestEditableMetadata;
+    /** Optional title override. */
+    title?: string | null;
+    /** Optional mode override. */
+    mode?: MdzManifestMode | null;
+    /** Optional entry point override. */
+    entryPoint?: string | null;
+}
+/**
+ * Generic archive path tree node for navigation UIs.
+ */
+export interface MdzPathTreeNode {
+    /** Node display name. */
+    name: string;
+    /** Archive-relative path. */
+    path: string;
+    /** True for inferred folder nodes. */
+    isDirectory: boolean;
+    /** Child nodes for directory entries. */
+    children: MdzPathTreeNode[];
+}
+/**
+ * Extension-to-MIME map for common image assets in MDZip archives.
+ */
+export declare const MDZ_IMAGE_MIME_TYPES: Record<string, string>;
+/**
+ * Core archive reader/validator/mutator for `.mdz` files.
+ */
+export declare class MdzArchiveCore {
+    private readonly zip;
+    /**
+     * Public image MIME map for consumers.
+     */
+    static readonly IMAGE_MIME_TYPES: Record<string, string>;
+    private static readonly SUPPORTED_MDZ_MAJOR;
+    private static readonly SUPPORTED_MODES;
+    private static readonly SEMVER_RE;
+    private static readonly MARKDOWN_IMAGE_REF_RE;
+    private static readonly entriesCache;
+    private static readonly manifestCache;
+    /**
+     * Creates an archive wrapper around a previously loaded ZIP object.
+     *
+     * @param zip - Loaded zip-like structure containing archive entries.
+     */
+    constructor(zip: ZipLike);
+    /**
+     * Opens archive binary data and returns a core archive instance.
+     *
+     * @param input - Raw archive bytes.
+     * @param zipFactory - Optional custom zip loader.
+     */
+    static open(input: MdzCoreArchiveBinary, zipFactory?: ZipFactoryLike): Promise<MdzArchiveCore>;
+    /**
+     * Convenience helper to open and validate an archive in one call.
+     *
+     * @param input - Raw archive bytes.
+     * @param zipFactory - Optional custom zip loader.
+     */
+    static validate(input: MdzCoreArchiveBinary, zipFactory?: ZipFactoryLike): Promise<MdzValidationResult>;
+    /**
+     * 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 addFile(input: MdzCoreArchiveBinary, archiveEntryPath: string, content: MdzArchiveMutationInput): Promise<MdzArchiveMutationResult>;
+    /**
+     * 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 removeFile(input: MdzCoreArchiveBinary, archiveEntryPath: string): Promise<MdzArchiveMutationResult>;
+    /**
+     * Removes multiple archive entries in one mutation operation.
+     *
+     * @param input - Existing archive bytes.
+     * @param archiveEntryPaths - Archive-relative paths to remove.
+     */
+    static removeFiles(input: MdzCoreArchiveBinary, archiveEntryPaths: string[]): Promise<MdzArchiveMutationResult>;
+    /**
+     * Finds orphaned image assets in an archive.
+     *
+     * @param input - Existing archive bytes.
+     * @param options - Scan options.
+     */
+    static findOrphanedAssets(input: MdzCoreArchiveBinary, options?: MdzOrphanedAssetsOptions): Promise<MdzOrphanedAssetsResult>;
+    /**
+     * 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 openWorkspace(input: MdzCoreArchiveBinary, options?: MdzOpenWorkspaceOptions, zipFactory?: ZipFactoryLike): Promise<MdzWorkspace>;
+    private static getDefaultZipFactory;
+    private static loadZip;
+    /**
+     * Normalizes path separators and strips leading slashes.
+     *
+     * @param path - Any input path.
+     */
+    static normalizePath(path: string): string;
+    /**
+     * Returns true if the provided path looks like a Markdown document path.
+     *
+     * @param path - Archive-relative path.
+     */
+    static isMarkdownFile(path: string): boolean;
+    /**
+     * 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: string, fallbackMime?: string): string;
+    /**
+     * Classifies an asset using path extension and MIME type.
+     *
+     * @param path - Archive-relative path.
+     * @param mimeType - Optional known MIME type.
+     */
+    static classifyAssetKind(path: string, mimeType?: string): MdzWorkspaceAssetKind;
+    /**
+     * Returns true when common browser surfaces can preview this asset.
+     *
+     * @param path - Archive-relative path.
+     * @param mimeType - Optional known MIME type.
+     */
+    static isPreviewableAsset(path: string, mimeType?: string): boolean;
+    /**
+     * Converts validation details into a compact status.
+     *
+     * @param result - Validation result.
+     */
+    static getValidationStatus(result: MdzValidationResult): MdzValidationStatus;
+    /**
+     * Returns a case-insensitive, normalized archive path sort.
+     *
+     * @param paths - Archive-relative paths.
+     */
+    static sortArchivePaths(paths: string[]): string[];
+    /**
+     * Returns the archive-relative directory name for a path.
+     *
+     * @param path - Archive-relative path.
+     */
+    static dirname(path: string): string;
+    /**
+     * Returns the final path segment for an archive-relative path.
+     *
+     * @param path - Archive-relative path.
+     */
+    static basename(path: string): string;
+    /**
+     * Builds a generic inferred folder tree from archive-relative paths.
+     *
+     * @param paths - Archive-relative paths.
+     */
+    static buildPathTree(paths: string[]): MdzPathTreeNode[];
+    /**
+     * Validates archive path constraints.
+     *
+     * @param path - Archive-relative path.
+     * @returns `null` when valid, otherwise a short reason string.
+     */
+    static validateArchivePath(path: string): string | null;
+    private static dirOf;
+    /**
+     * 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: string, relative: string): string;
+    /**
+     * Finds an archive entry by path (case-insensitive fallback).
+     *
+     * @param path - Archive-relative path.
+     */
+    findEntry(path: string): ZipEntry | null;
+    /**
+     * Lists archive paths.
+     *
+     * @param options - Listing controls.
+     */
+    listPaths(options?: MdzArchiveListOptions): string[];
+    /**
+     * Lists archive entries with basic type metadata.
+     *
+     * @param options - Listing controls.
+     */
+    listEntries(options?: MdzArchiveListOptions): MdzArchiveEntryInfo[];
+    /**
+     * Returns true if an entry path exists (file or directory).
+     *
+     * @param path - Archive-relative path.
+     */
+    hasEntry(path: string): boolean;
+    /**
+     * Reads UTF-8 text content from an entry.
+     *
+     * @param path - Archive-relative file path.
+     */
+    readText(path: string): Promise<string>;
+    /**
+     * Reads raw bytes from an entry.
+     *
+     * @param path - Archive-relative file path.
+     */
+    readBytes(path: string): Promise<Uint8Array>;
+    /**
+     * Reads entry content as raw base64 (no data URI prefix).
+     *
+     * @param path - Archive-relative file path.
+     */
+    readBase64(path: string): Promise<string>;
+    /**
+     * Reads entry content and returns a data URI string.
+     *
+     * @param path - Archive-relative file path.
+     * @param fallbackMime - Optional fallback MIME when extension is unknown.
+     */
+    readDataUri(path: string, fallbackMime?: string): Promise<string>;
+    /**
+     * Finds orphaned image assets from markdown references.
+     *
+     * @param options - Scan options.
+     */
+    findOrphanedAssets(options?: MdzOrphanedAssetsOptions): Promise<MdzOrphanedAssetsResult>;
+    /**
+     * Returns a normalized app/editor workspace model for this archive.
+     *
+     * @param options - Workspace open controls.
+     */
+    openWorkspace(options?: MdzOpenWorkspaceOptions): Promise<MdzWorkspace>;
+    static validateManifest(manifest: unknown): asserts manifest is MdzManifest;
+    /**
+     * Parses and validates `manifest.json` if present.
+     *
+     * Missing or invalid cover references are normalized away in returned data.
+     */
+    readManifest(): Promise<MdzManifest | null>;
+    /**
+     * Resolves archive interpretation mode using manifest data or the spec default.
+     */
+    resolveMode(): Promise<MdzManifestMode>;
+    /**
+     * Validates archive conformance and returns errors/warnings.
+     */
+    validate(): Promise<MdzValidationResult>;
+    /**
+     * Resolves the primary markdown entry point for rendering.
+     *
+     * @throws When no unambiguous entry point can be determined.
+     */
+    resolveEntryPoint(): Promise<string>;
+    private static getArchivePaths;
+    private static getArchiveEntries;
+    private findEntryWithDirectoryFallback;
+    private getFileEntryOrThrow;
+    private static getPathExtension;
+    private static isImagePath;
+    private static getDocumentTitle;
+    private static extractMarkdownImageReferences;
+    private static cleanMarkdownLinkTarget;
+    private static hasUriScheme;
+    private static resolveAssetPathCase;
+    private static removeEntryIgnoreCase;
+    private static isTextFile;
+    private static normaliseLf;
+    private static readExistingManifestObject;
+    private static parseManifestObjectContent;
+    private static ensureManifestSpecObject;
+    private static stampManifestObject;
+    private static ensureCreatableEntryPoint;
+    private static readMutationInputAsText;
+    private static readMutationInputAsBinary;
+    private static writeZipEntry;
+    private static finalizeMutation;
+}
+/**
+ * Packaging helpers for creating `.mdz` archives from source files.
+ */
+export declare class MdzPackagerCore {
+    /**
+     * Default include globs for markdown and common image assets.
+     */
+    static readonly DEFAULT_FILTERS: string[];
+    /**
+     * Normalizes input file paths for archive packaging.
+     *
+     * @param path - Source file path.
+     */
+    static normalizePath(path: string): string;
+    /**
+     * Validates archive path constraints.
+     *
+     * @param path - Archive-relative path.
+     */
+    static validateArchivePath(path: string): string | null;
+    /**
+     * Sanitizes one archive path segment by replacing forbidden characters.
+     *
+     * @param segment - Single path segment.
+     */
+    static sanitisePathSegment(segment: string): string;
+    /**
+     * Sanitizes a full archive path by normalizing each path segment.
+     *
+     * @param path - Candidate archive path.
+     */
+    static sanitiseArchivePath(path: string): string;
+    /**
+     * 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: string, usedPaths: Set<string>): string;
+    /**
+     * Tests whether a path matches a glob pattern supporting `*`, `?`, and `**`.
+     *
+     * @param path - Archive-relative path.
+     * @param pattern - Glob pattern.
+     */
+    static globMatch(path: string, pattern: string): boolean;
+    /**
+     * Returns true if a path matches at least one filter pattern.
+     *
+     * @param path - Archive-relative path.
+     * @param filters - Glob filter list.
+     */
+    static matchesAnyFilter(path: string, filters: string[]): boolean;
+    /**
+     * 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: string, options: MdzPackOptions): MdzManifest | null;
+    /**
+     * 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: string[], manifest?: Pick<MdzManifest, 'entryPoint'> | null): string | 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: string[], title?: string | null): string;
+    /**
+     * Creates a canonical MDZip manifest from app-safe metadata.
+     *
+     * @param metadata - Editable manifest fields.
+     */
+    static createManifest(metadata?: MdzManifestEditableMetadata & Pick<MdzManifest, 'mode' | 'entryPoint'>): MdzManifest;
+    /**
+     * 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: MdzManifest | null, updates?: MdzManifestEditableMetadata & Partial<Pick<MdzManifest, 'mode' | 'entryPoint'>>, options?: MdzManifestUpdateOptions): MdzManifest;
+    /**
+     * Splits a manifest into spec-managed fields and ordinary editable metadata.
+     *
+     * @param manifest - Manifest to split.
+     */
+    static splitManifestMetadata(manifest: MdzManifest): {
+        reserved: MdzManifestReservedFields;
+        editable: MdzManifestEditableMetadata;
+    };
+    /**
+     * Creates a workspace asset from a browser `File`/`Blob` or raw bytes.
+     *
+     * @param source - Asset source.
+     * @param targetPath - Optional archive path override.
+     */
+    static createWorkspaceAssetFromFile(source: File | Blob | ArrayBuffer | Uint8Array, targetPath?: string): Promise<MdzWorkspaceAsset>;
+    /**
+     * Exports a workspace asset as a browser-safe `Blob`.
+     *
+     * @param asset - Workspace asset.
+     */
+    static exportWorkspaceAsset(asset: MdzWorkspaceAsset): Promise<Blob>;
+    /**
+     * 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 buildWorkspace(workspace: MdzWorkspace, options?: MdzBuildWorkspaceOptions, zipWriterFactory?: ZipWriterFactoryLike): Promise<MdzPackBuildResult>;
+    private static normalizeLf;
+    private static isTextFile;
+    private static readProvidedManifest;
+    private static ensureCanonicalManifest;
+    private static readBinarySource;
+    private static readWorkspaceAssetBytes;
+    /**
+     * 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 buildArchive(files: MdzPackInputFile[], rootName: string, options: MdzPackOptions, zipWriterFactory?: ZipWriterFactoryLike): Promise<MdzPackBuildResult>;
+    private static getDefaultZipWriterFactory;
+}
+export {};
+//# sourceMappingURL=mdz-core.d.ts.map