@siglum/engine 0.1.1 → 0.1.4

package/README.md

@@ -15,7 +15,8 @@ The full bundle is ~195MB to deploy, but clients only download what their docume
 
 **Guides:**
 - [Examples & Playground Tutorial](examples/README.md) — Build a LaTeX editor UI
-- [CTAN Proxy Guide](docs/CTAN_PROXY.md) — Self-host the package proxy for production
+- [CTAN Proxy Guide](docs/ctan-proxy.md) — Self-host the package proxy for production
+- [Building from Source](docs/building.md) — Build WASM engine and bundles
 
 ## Quick Start (Local Demo)
 
@@ -95,6 +96,8 @@ const compiler = new SiglumCompiler({
 
 ## Usage
 
+> **Note:** If using a bundler (Vite, Webpack, etc.), see [Usage with Bundlers](#usage-with-bundlers-vite-webpack-etc) for required setup.
+
 ```javascript
 import { SiglumCompiler } from '@siglum/engine';
 
@@ -129,7 +132,7 @@ const compiler = new SiglumCompiler({
     wasmUrl: '/wasm/busytex.wasm',    // URL to WASM binary
     jsUrl: null,                      // URL to busytex.js (derived from wasmUrl if null)
     ctanProxyUrl: null,               // CTAN proxy URL (enables CTAN fetching when set)
-    workerUrl: null,                  // Custom worker URL (uses embedded worker if null)
+    workerUrl: null,                  // Custom worker URL (required for bundlers)
 
     // Feature flags
     enableCtan: false,                // Auto-enabled when ctanProxyUrl is set
@@ -260,6 +263,29 @@ compiler.init(); // Fire and forget — bundles download in background
 await compiler.compile(source); // Already warmed up
 ```
 
+## Usage with Bundlers (Vite, Webpack, etc.)
+
+Bundlers pre-bundle dependencies, which breaks the automatic worker loading. You need to copy the worker file and pass an explicit URL:
+
+```json
+// package.json
+{
+  "scripts": {
+    "postinstall": "cp node_modules/@siglum/engine/src/worker.js public/worker.js"
+  }
+}
+```
+
+```javascript
+const compiler = new SiglumCompiler({
+    bundlesUrl: '/bundles',
+    wasmUrl: '/busytex.wasm',
+    workerUrl: '/worker.js',  // Explicit path to copied worker
+});
+```
+
+The `postinstall` script runs automatically on `npm install`, keeping the worker in sync with the package version.
+
 ## Engines
 
 | Engine | Status |
@@ -312,7 +338,7 @@ bun packages/ctan-proxy.ts
 
 Packages are cached permanently. The proxy tries TexLive 2025 archives first, then falls back to CTAN mirrors.
 
-For configuration and deployment options, see **[docs/CTAN_PROXY.md](docs/CTAN_PROXY.md)**.
+For configuration and deployment options, see **[docs/ctan-proxy.md](docs/ctan-proxy.md)**.
 
 ## Browser Requirements
 

package/package.json

@@ -1,16 +1,31 @@
 {
   "name": "@siglum/engine",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "A browser-based LaTeX compiler. TeX Live 2025 running in WebAssembly, with lazy bundle loading and on-demand package fetching.",
   "type": "module",
   "main": "src/index.js",
   "types": "types/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./compiler": "./src/compiler.js",
-    "./bundles": "./src/bundles.js",
-    "./ctan": "./src/ctan.js",
-    "./storage": "./src/storage.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./compiler": {
+      "types": "./types/compiler.d.ts",
+      "default": "./src/compiler.js"
+    },
+    "./bundles": {
+      "types": "./types/bundles.d.ts",
+      "default": "./src/bundles.js"
+    },
+    "./ctan": {
+      "types": "./types/ctan.d.ts",
+      "default": "./src/ctan.js"
+    },
+    "./storage": {
+      "types": "./types/storage.d.ts",
+      "default": "./src/storage.js"
+    }
   },
   "files": [
     "src/",
@@ -18,7 +33,6 @@
   ],
   "scripts": {
     "dev": "bun serve-local.ts",
-    "build:worker": "cp src/worker.js ../webtex/siglum-ui/app/public/worker.js && echo 'Copied worker.js to siglum-ui'",
     "proxy": "cd packages && bun run ctan-proxy.ts",
     "build:types": "tsc",
     "prepublishOnly": "tsc"

package/src/compiler.js

@@ -10,7 +10,7 @@ import { BundleManager, detectEngine, extractPreamble, hashPreamble } from './bu
  * @property {string} [bundlesUrl] - URL to bundles directory
  * @property {string} [wasmUrl] - URL to busytex.wasm
  * @property {string} [jsUrl] - URL to busytex.js (derived from wasmUrl if not provided)
- * @property {string|null} [workerUrl] - URL to worker.js or null for embedded worker
+ * @property {string|null} [workerUrl] - URL to worker.js (required for bundlers like Vite/Webpack)
  * @property {string} [ctanProxyUrl] - CTAN proxy URL
  * @property {string} [xzwasmUrl] - XZ decompression WASM URL
  * @property {(msg: string) => void} [onLog] - Logging callback
@@ -320,7 +320,7 @@ export class SiglumCompiler {
             _globalActiveWorker = null;
         }
 
-        // Get worker code - use external URL or read from src/worker.js
+        // Get worker code - use external URL or fetch from package
         let workerUrl = this.workerUrl;
         if (!workerUrl) {
             // Fetch worker.js and create blob URL

package/src/ctan.js

@@ -135,6 +135,7 @@ export class CTANFetcher {
         this.bundlesUrl = options.bundlesUrl || this.proxyUrl + '/bundles';
         this.mountedFiles = new Set();
         this.fileCache = new Map(); // Memory cache for file contents
+        this.loadedPackages = new Set(); // Track packages already loaded into memory
         this.fetchCount = 0;
         this.onLog = options.onLog || (() => {});
 
@@ -268,7 +269,7 @@ export class CTANFetcher {
 
         // Skip cache for version-specific requests - we want a different version
         if (!tlYear) {
-            // Check cache first
+            // Check persistent cache
             const cached = await this.loadPackageFromCache(packageName);
             if (cached) {
                 if (cached.notFound) {
@@ -288,6 +289,7 @@ export class CTANFetcher {
                     return null;
                 }
                 this.onLog(`[FETCH] ${packageName}: loaded from cache`);
+                this.loadedPackages.add(packageName);
                 return cached;
             }
         } else {
@@ -334,7 +336,7 @@ export class CTANFetcher {
             return this.fetchCtanPackage(packageName, tlYear);
         }
 
-        // Check cache first (same cache as CTAN)
+        // Check persistent cache (same cache as CTAN)
         const cached = await this.loadPackageFromCache(packageName);
         if (cached) {
             if (cached.notFound) {
@@ -342,6 +344,7 @@ export class CTANFetcher {
                 return null;
             }
             this.onLog(`Package ${packageName} loaded from cache (TexLive)`);
+            this.loadedPackages.add(packageName);
             return cached;
         }
 
@@ -526,6 +529,10 @@ export class CTANFetcher {
             }
 
             this.fetchCount++;
+            this.loadedPackages.add(packageName);
+            if (texlivePkg !== packageName) {
+                this.loadedPackages.add(texlivePkg);
+            }
             return { files, dependencies: [] };
         } catch (e) {
             this.onLog(`[TEXLIVE] EXTRACTION ERROR for ${packageName}: ${e.message}`);
@@ -638,6 +645,10 @@ export class CTANFetcher {
             }
 
             this.fetchCount++;
+            this.loadedPackages.add(packageName);
+            if (ctanPkg !== packageName) {
+                this.loadedPackages.add(ctanPkg);
+            }
             return {
                 files,
                 dependencies: data.dependencies || [],
@@ -695,14 +706,21 @@ export class CTANFetcher {
         const uniquePackages = [...new Set(packageNames)];
         const toFetch = [];
 
-        // Check cache first
+        // Check cache first - use memory cache to avoid filesystem reads on every recompile
         for (const pkgName of uniquePackages) {
+            // Skip filesystem check if package already loaded into memory this session
+            if (this.loadedPackages.has(pkgName)) {
+                skipped.push(pkgName);
+                continue;
+            }
+
             const cached = await this.loadPackageFromCache(pkgName);
             if (cached && cached.files && !cached.notFound) {
                 // Already cached and has files - populate memory cache
                 for (const [path, content] of cached.files) {
                     this.fileCache.set(path, content);
                 }
+                this.loadedPackages.add(pkgName);
                 skipped.push(pkgName);
             } else {
                 toFetch.push(pkgName);
@@ -728,6 +746,7 @@ export class CTANFetcher {
             for (const res of results) {
                 if (res.status === 'fulfilled' && res.value.result) {
                     fetched.push(res.value.pkgName);
+                    this.loadedPackages.add(res.value.pkgName);
                 } else {
                     const pkgName = res.status === 'fulfilled'
                         ? res.value.pkgName
@@ -761,10 +780,12 @@ export class CTANFetcher {
     }
 
     /**
-     * Clear the mounted files set.
+     * Clear the mounted files set and memory caches.
      */
     clearMountedFiles() {
         this.mountedFiles.clear();
+        this.fileCache.clear();
+        this.loadedPackages.clear();
     }
 }
 

package/types/compiler.d.ts

@@ -184,7 +184,7 @@ export type SiglumCompilerOptions = {
      */
     jsUrl?: string;
     /**
-     * - URL to worker.js or null for embedded worker
+     * - URL to worker.js (required for bundlers like Vite/Webpack)
      */
     workerUrl?: string | null;
     /**

package/types/ctan.d.ts

@@ -42,6 +42,7 @@ export class CTANFetcher {
     bundlesUrl: string;
     mountedFiles: Set<any>;
     fileCache: Map<any, any>;
+    loadedPackages: Set<any>;
     fetchCount: number;
     onLog: (msg: string) => void;
     /**
@@ -118,7 +119,7 @@ export class CTANFetcher {
         mountedFiles: number;
     };
     /**
-     * Clear the mounted files set.
+     * Clear the mounted files set and memory caches.
      */
     clearMountedFiles(): void;
 }