@siglum/engine 0.1.0

package/types/bundles.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Detect the appropriate engine from LaTeX source.
+ * @param {string} source - LaTeX source
+ * @returns {'pdflatex'|'xelatex'} Detected engine
+ */
+export function detectEngine(source: string): "pdflatex" | "xelatex";
+/**
+ * Extract preamble from LaTeX source (everything before \begin{document}).
+ * @param {string} source - LaTeX source
+ * @returns {string} Preamble content
+ */
+export function extractPreamble(source: string): string;
+/**
+ * @typedef {Object} BundleManagerOptions
+ * @property {string} [bundleBase] - Base URL for bundles
+ * @property {(msg: string) => void} [onLog] - Logging callback
+ * @property {(stage: string, detail: string) => void} [onProgress] - Progress callback
+ */
+/**
+ * Manages LaTeX package bundles - loading, caching, and resolution.
+ */
+export class BundleManager {
+    /**
+     * @param {BundleManagerOptions} [options] - Manager options
+     */
+    constructor(options?: BundleManagerOptions);
+    bundleBase: string;
+    bundleCache: Map<any, any>;
+    fileManifest: any;
+    packageMap: any;
+    bundleDeps: {
+        engines: any;
+        bundles: {};
+        deferred: any;
+    };
+    packageDeps: any;
+    bundleRegistry: Set<string>;
+    bytesDownloaded: number;
+    cacheHitCount: number;
+    onLog: (msg: string) => void;
+    onProgress: (stage: string, detail: string) => void;
+    /**
+     * Compute a hash for bundle versioning based on manifest entries
+     * Uses the file paths and sizes to detect changes
+     */
+    getBundleHash(bundleName: any): string;
+    /**
+     * Load bundle manifests from cache or server.
+     * @returns {Promise<Object>} File manifest
+     */
+    loadManifest(): Promise<any>;
+    _initFromBundlesData(bundlesData: any): void;
+    /**
+     * Load bundle dependency information.
+     * @returns {Promise<Object>} Bundle dependencies
+     */
+    loadBundleDeps(): Promise<any>;
+    /**
+     * Check if a bundle exists in the registry.
+     * @param {string} bundleName - Bundle name
+     * @returns {boolean}
+     */
+    bundleExists(bundleName: string): boolean;
+    /**
+     * Resolve packages to their required bundles.
+     * @param {string[]} packages - Package names
+     * @param {string} [engine] - Engine name
+     * @returns {string[]} Bundle names
+     */
+    resolveBundles(packages: string[], engine?: string): string[];
+    /**
+     * Extract packages from LaTeX source and resolve to bundles.
+     * @param {string} source - LaTeX source
+     * @param {string} [engine] - Engine name
+     * @returns {{packages: string[], bundles: string[]}}
+     */
+    checkPackages(source: string, engine?: string): {
+        packages: string[];
+        bundles: string[];
+    };
+    /**
+     * Pre-scan source to identify packages needing CTAN fetch.
+     * Expands detected packages with known dependencies from packageDeps.
+     * Scans additionalFiles for multi-file documents.
+     *
+     * @param {string} source - Main LaTeX source
+     * @param {string} engine - Engine (pdflatex, xelatex, etc.)
+     * @param {Object} additionalFiles - Optional map of filename → content
+     * @returns {{ bundledPackages: string[], ctanPackages: string[] }}
+     */
+    prescanForCtanPackages(source: string, engine?: string, additionalFiles?: any): {
+        bundledPackages: string[];
+        ctanPackages: string[];
+    };
+    /**
+     * Load a bundle by name.
+     * @param {string} bundleName - Bundle name
+     * @returns {Promise<ArrayBuffer|SharedArrayBuffer>} Bundle data
+     */
+    loadBundle(bundleName: string): Promise<ArrayBuffer | SharedArrayBuffer>;
+    /**
+     * Load multiple bundles in parallel.
+     * @param {string[]} bundleNames - Bundle names
+     * @returns {Promise<Object<string, ArrayBuffer|SharedArrayBuffer>>} Map of bundle data
+     */
+    loadBundles(bundleNames: string[]): Promise<{
+        [x: string]: ArrayBuffer | SharedArrayBuffer;
+    }>;
+    /**
+     * Get bundle loading statistics.
+     * @returns {{bytesDownloaded: number, cacheHits: number, bundlesCached: number}}
+     */
+    getStats(): {
+        bytesDownloaded: number;
+        cacheHits: number;
+        bundlesCached: number;
+    };
+    /**
+     * Clear in-memory bundle cache to free RAM. Filesystem cache is preserved.
+     */
+    clearCache(): void;
+    /**
+     * Preload all required bundles for an engine.
+     * @param {string} [engine] - Engine name
+     * @returns {Promise<void>}
+     */
+    preloadEngine(engine?: string): Promise<void>;
+}
+export { hashPreamble } from "./hash.js";
+export type BundleManagerOptions = {
+    /**
+     * - Base URL for bundles
+     */
+    bundleBase?: string;
+    /**
+     * - Logging callback
+     */
+    onLog?: (msg: string) => void;
+    /**
+     * - Progress callback
+     */
+    onProgress?: (stage: string, detail: string) => void;
+};

package/types/compiler.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Browser-based LaTeX compiler using WebAssembly.
+ * Handles bundle loading, CTAN fetching, and compilation orchestration.
+ */
+export class SiglumCompiler {
+    /**
+     * @param {SiglumCompilerOptions} [options] - Compiler options
+     */
+    constructor(options?: SiglumCompilerOptions);
+    bundlesUrl: string;
+    wasmUrl: string;
+    jsUrl: string;
+    workerUrl: string;
+    ctanProxyUrl: string;
+    xzwasmUrl: string;
+    bundleManager: BundleManager;
+    ctanFetcher: CTANFetcher;
+    worker: Worker;
+    workerReady: boolean;
+    wasmModule: WebAssembly.Module;
+    _initWorkerPromise: Promise<any>;
+    pendingCompile: {
+        resolve: (result: any) => Promise<void>;
+        reject: (error: any) => void;
+    };
+    formatGenerationPromise: any;
+    onLog: (msg: string) => void;
+    onProgress: (stage: string, detail: string) => void;
+    enableCtan: boolean;
+    enableLazyFS: boolean;
+    enableDocCache: boolean;
+    maxRetries: number;
+    verbose: boolean;
+    eagerBundles: string[] | {
+        [x: string]: string[];
+    };
+    _pendingRangeRequests: Map<any, any>;
+    _rangeRequestTimer: number;
+    _rangeRequestDebounceMs: number;
+    _rangeCoalesceGapBytes: number;
+    _log(msg: any): void;
+    /**
+     * Get eager bundles for a specific engine.
+     * Eager bundles are loaded immediately instead of being deferred.
+     * @param {string} engine - The engine (pdflatex, xelatex, lualatex)
+     * @returns {string[]} List of bundle names to load eagerly
+     */
+    getEagerBundles(engine: string): string[];
+    /**
+     * Preload bundles into memory cache.
+     * Call this to eagerly load bundles before compilation.
+     * Useful for loading large deferred bundles (like cm-super) in advance.
+     *
+     * @example
+     * // Preload cm-super before first compile
+     * await compiler.preloadBundles(['cm-super']);
+     *
+     * @param {string[]} bundleNames - Bundles to preload
+     * @returns {Promise<{loaded: string[], failed: string[]}>}
+     */
+    preloadBundles(bundleNames: string[]): Promise<{
+        loaded: string[];
+        failed: string[];
+    }>;
+    /**
+     * Pre-warm the compiler in the background.
+     * Call this early (e.g., on page load) to eliminate cold start latency.
+     * The promise resolves when initialization is complete, but you don't need to await it.
+     *
+     * @example
+     * // On app mount, before user starts typing
+     * const compiler = new BusyTeXCompiler(options);
+     * compiler.prewarm(); // Fire and forget - init happens in background
+     *
+     * // Later, when user wants to compile:
+     * await compiler.compile(source); // Already warmed up!
+     *
+     * @returns {Promise<void>} Resolves when initialization is complete
+     */
+    prewarm(): Promise<void>;
+    _prewarmPromise: any;
+    /**
+     * Check if compiler is ready (initialized and warmed up)
+     * @returns {boolean}
+     */
+    isReady(): boolean;
+    /**
+     * Initialize the compiler. Loads WASM, manifests, and prepares the worker.
+     * @returns {Promise<void>}
+     */
+    init(): Promise<void>;
+    _loadManifests(): Promise<void>;
+    _loadWasm(): Promise<void>;
+    _initWorker(): Promise<any>;
+    _doInitWorker(): Promise<any>;
+    _handleWorkerMessage(e: any): void;
+    pendingFormat: {
+        resolve: (result: any) => void;
+        reject: (error: any) => void;
+    };
+    _handleWorkerError(e: any): void;
+    _handleCtanFetchRequest(msg: any): Promise<void>;
+    _handleBundleFetchRequest(msg: any): Promise<void>;
+    /**
+     * Queue a range request for batching. Requests are coalesced and fetched
+     * together to reduce HTTP overhead.
+     */
+    _queueRangeRequest(msg: any): void;
+    /**
+     * Process all pending range requests, coalescing nearby ranges.
+     */
+    _processRangeRequestBatch(): Promise<void>;
+    /**
+     * Coalesce nearby ranges to reduce HTTP requests.
+     * Returns groups of original requests that can be satisfied by a single fetch.
+     */
+    _coalesceRanges(requests: any): any[][];
+    /**
+     * Fetch a coalesced range and distribute data to original requesters.
+     */
+    _fetchCoalescedRange(bundleName: any, group: any): Promise<void>;
+    _handleMemorySnapshot(msg: any): Promise<void>;
+    /**
+     * Compile LaTeX source to PDF.
+     * @param {string} source - LaTeX source code
+     * @param {CompileOptions} [options] - Compilation options
+     * @returns {Promise<CompileResult>} Compilation result with PDF or error
+     */
+    compile(source: string, options?: CompileOptions): Promise<CompileResult>;
+    _fmtMemCache: any;
+    /**
+     * Pre-generate a format file for faster subsequent compilations.
+     * @param {string} source - LaTeX source with preamble to cache
+     * @param {{engine?: string}} [options] - Options
+     * @returns {Promise<Uint8Array|null>} Format data or null if not supported
+     */
+    generateFormat(source: string, options?: {
+        engine?: string;
+    }): Promise<Uint8Array | null>;
+    /**
+     * Clear all caches (CTAN packages, mounted files).
+     * @returns {Promise<void>}
+     */
+    clearCache(): Promise<void>;
+    /**
+     * Get compiler statistics.
+     * @returns {{bundles: Object, ctan: Object}} Statistics from bundle manager and CTAN fetcher
+     */
+    getStats(): {
+        bundles: any;
+        ctan: any;
+    };
+    /**
+     * Terminate the worker. Call unload() for full cleanup.
+     */
+    terminate(): void;
+    /**
+     * Unload compiler to free memory. Clears RAM caches but keeps disk caches.
+     * Call init() again to reinitialize.
+     */
+    unload(): void;
+    /**
+     * Check if compiler is currently loaded.
+     * @returns {boolean}
+     */
+    isLoaded(): boolean;
+}
+/**
+ * Backwards-compatible alias for SiglumCompiler.
+ * @type {typeof SiglumCompiler}
+ */
+export const BusyTeXCompiler: typeof SiglumCompiler;
+export type SiglumCompilerOptions = {
+    /**
+     * - URL to bundles directory
+     */
+    bundlesUrl?: string;
+    /**
+     * - URL to busytex.wasm
+     */
+    wasmUrl?: string;
+    /**
+     * - URL to busytex.js (derived from wasmUrl if not provided)
+     */
+    jsUrl?: string;
+    /**
+     * - URL to worker.js or null for embedded worker
+     */
+    workerUrl?: string | null;
+    /**
+     * - CTAN proxy URL
+     */
+    ctanProxyUrl?: string;
+    /**
+     * - XZ decompression WASM URL
+     */
+    xzwasmUrl?: string;
+    /**
+     * - Logging callback
+     */
+    onLog?: (msg: string) => void;
+    /**
+     * - Progress callback
+     */
+    onProgress?: (stage: string, detail: string) => void;
+    /**
+     * - Enable CTAN fetching (default: true if ctanProxyUrl provided)
+     */
+    enableCtan?: boolean;
+    /**
+     * - Enable lazy filesystem (default: true)
+     */
+    enableLazyFS?: boolean;
+    /**
+     * - Enable document cache (default: true)
+     */
+    enableDocCache?: boolean;
+    /**
+     * - Max fetch retries per compile (default: 15)
+     */
+    maxRetries?: number;
+    /**
+     * - Log TeX stdout (default: false)
+     */
+    verbose?: boolean;
+    /**
+     * - Bundles to load eagerly
+     */
+    eagerBundles?: string[] | {
+        [x: string]: string[];
+    };
+};
+export type CompileOptions = {
+    /**
+     * - 'pdflatex', 'xelatex', or 'lualatex'
+     */
+    engine?: string;
+    /**
+     * - Use document cache
+     */
+    useCache?: boolean;
+    /**
+     * - Additional files for compilation
+     */
+    additionalFiles?: {
+        [x: string]: string | Uint8Array;
+    };
+};
+export type CompileResult = {
+    /**
+     * - Whether compilation succeeded
+     */
+    success: boolean;
+    /**
+     * - Compiled PDF bytes
+     */
+    pdf?: Uint8Array;
+    /**
+     * - True if PDF is in SharedArrayBuffer
+     */
+    pdfIsShared?: boolean;
+    /**
+     * - SyncTeX data for source mapping
+     */
+    syncTexData?: any | null;
+    /**
+     * - Compilation statistics
+     */
+    stats?: any;
+    /**
+     * - TeX compilation log
+     */
+    log?: string;
+    /**
+     * - Error message if failed
+     */
+    error?: string;
+    /**
+     * - TeX exit code if failed
+     */
+    exitCode?: number;
+    /**
+     * - True if result was from cache
+     */
+    cached?: boolean;
+};
+import { BundleManager } from './bundles.js';
+import { CTANFetcher } from './ctan.js';

package/types/ctan.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Extract package name from a missing file path.
+ * Handles special cases like EC/TC fonts (cm-super).
+ * @param {string} filename - File name (e.g., "lingmacros.sty")
+ * @returns {string} Package name
+ */
+export function getPackageFromFile(filename: string): string;
+/**
+ * Check if a string is a valid CTAN package name.
+ * @param {string} name - Package name to validate
+ * @returns {boolean} True if valid
+ */
+export function isValidPackageName(name: string): boolean;
+/**
+ * Force clear a specific package from cache (for version refresh).
+ * @param {string} packageName - Package name to clear
+ * @returns {Promise<boolean>} True if successful
+ */
+export function forceRefreshPackage(packageName: string): Promise<boolean>;
+/**
+ * @typedef {Object} CTANFetcherOptions
+ * @property {string} [proxyUrl] - CTAN proxy URL
+ * @property {string} [bundlesUrl] - Bundles URL
+ * @property {string} [xzwasmUrl] - XZ decompression WASM URL
+ * @property {(msg: string) => void} [onLog] - Logging callback
+ */
+/**
+ * @typedef {Object} PackageResult
+ * @property {Map<string, Uint8Array>} files - Map of file paths to contents
+ * @property {string[]} dependencies - Package dependencies
+ * @property {boolean} [notFound] - True if package was not found
+ */
+/**
+ * Fetches LaTeX packages from CTAN/TexLive archives.
+ */
+export class CTANFetcher {
+    /**
+     * @param {CTANFetcherOptions} [options] - Fetcher options
+     */
+    constructor(options?: CTANFetcherOptions);
+    proxyUrl: string;
+    bundlesUrl: string;
+    mountedFiles: Set<any>;
+    fileCache: Map<any, any>;
+    fetchCount: number;
+    onLog: (msg: string) => void;
+    /**
+     * Load file-to-package index (maps filename.sty → package-name).
+     * @returns {Promise<Object<string, string>>} Index mapping filenames to packages
+     */
+    loadFileToPackageIndex(): Promise<{
+        [x: string]: string;
+    }>;
+    /**
+     * Look up package name for a file.
+     * @param {string} fileName - File name (e.g., "lingmacros.sty")
+     * @returns {Promise<string|null>} Package name or null
+     */
+    lookupPackageForFile(fileName: string): Promise<string | null>;
+    /**
+     * Get all cached file contents.
+     * @returns {Object<string, Uint8Array>} Map of file paths to contents
+     */
+    getCachedFiles(): {
+        [x: string]: Uint8Array;
+    };
+    /**
+     * Load a package from cache.
+     * @param {string} packageName - Package name
+     * @returns {Promise<PackageResult|null>} Package result or null if not cached
+     */
+    loadPackageFromCache(packageName: string): Promise<PackageResult | null>;
+    /**
+     * Fetch a package from CTAN/TexLive.
+     * @param {string} packageName - Package name
+     * @param {{tlYear?: number}} [options] - Options
+     * @returns {Promise<PackageResult|null>} Package result or null if not found
+     */
+    fetchPackage(packageName: string, options?: {
+        tlYear?: number;
+    }): Promise<PackageResult | null>;
+    lookupTexLivePackageName(packageName: any): Promise<any>;
+    fetchTexLivePackage(packageName: any, tlYear?: any): Promise<{
+        files: Map<any, any>;
+        dependencies: any;
+    }>;
+    fetchCtanPackage(packageName: any, tlYear?: any): Promise<{
+        files: Map<any, any>;
+        dependencies: any;
+    }>;
+    fetchWithDependencies(packageName: any, fetched?: Set<any>): Promise<Map<any, any>>;
+    /**
+     * Batch fetch multiple packages in parallel.
+     * Used for pre-fetching detected CTAN packages before compilation.
+     * @param {string[]} packageNames - Package names to fetch
+     * @param {Object} options
+     * @param {number} options.concurrency - Max parallel fetches (default: 1, see note below)
+     * @returns {Promise<{fetched: string[], failed: string[], skipped: string[]}>}
+     */
+    batchFetchPackages(packageNames: string[], options?: {
+        concurrency: number;
+    }): Promise<{
+        fetched: string[];
+        failed: string[];
+        skipped: string[];
+    }>;
+    /**
+     * Get list of all mounted file paths.
+     * @returns {string[]} Array of file paths
+     */
+    getMountedFiles(): string[];
+    /**
+     * Get fetcher statistics.
+     * @returns {{fetchCount: number, mountedFiles: number}} Stats object
+     */
+    getStats(): {
+        fetchCount: number;
+        mountedFiles: number;
+    };
+    /**
+     * Clear the mounted files set.
+     */
+    clearMountedFiles(): void;
+}
+export type CTANFetcherOptions = {
+    /**
+     * - CTAN proxy URL
+     */
+    proxyUrl?: string;
+    /**
+     * - Bundles URL
+     */
+    bundlesUrl?: string;
+    /**
+     * - XZ decompression WASM URL
+     */
+    xzwasmUrl?: string;
+    /**
+     * - Logging callback
+     */
+    onLog?: (msg: string) => void;
+};
+export type PackageResult = {
+    /**
+     * - Map of file paths to contents
+     */
+    files: Map<string, Uint8Array>;
+    /**
+     * - Package dependencies
+     */
+    dependencies: string[];
+    /**
+     * - True if package was not found
+     */
+    notFound?: boolean;
+};

package/types/hash.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Hash content using BLAKE3 (async, preferred for large documents)
+ * @param {string} content
+ * @returns {Promise<string>} hex hash
+ */
+export function hashAsync(content: string): Promise<string>;
+/**
+ * Hash content synchronously - uses BLAKE3 if loaded, else DJB2
+ * Call initHash() early to ensure BLAKE3 is available for sync hashing
+ * @param {string} content
+ * @returns {string} hex hash
+ */
+export function hashSync(content: string): string;
+/**
+ * Initialize BLAKE3 for use with hashSync
+ * Call this early in app startup for best performance
+ * @returns {Promise<boolean>} true if BLAKE3 loaded successfully
+ */
+export function initHash(): Promise<boolean>;
+/**
+ * Check if BLAKE3 is ready for sync hashing
+ * @returns {boolean}
+ */
+export function isBlake3Ready(): boolean;
+export { hashSync as hashContent, hashSync as hashDocument, hashSync as hashPreamble };

package/types/index.d.ts

@@ -0,0 +1,5 @@
+export { createBatchedLogger } from "./utils.js";
+export { SiglumCompiler, BusyTeXCompiler } from "./compiler.js";
+export { BundleManager, detectEngine, extractPreamble, hashPreamble } from "./bundles.js";
+export { CTANFetcher, getPackageFromFile, isValidPackageName, forceRefreshPackage } from "./ctan.js";
+export { clearCTANCache, hashDocument, getCachedPdf, saveCachedPdf, listAllCachedPackages } from "./storage.js";