jww-parser 2025.12.3 → 2025.12.4

package/dist/index.js

@@ -1,768 +1,846 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  JwwErrorCode: () => JwwErrorCode,
-  JwwParser: () => JwwParser,
-  JwwParserError: () => JwwParserError,
-  NotInitializedError: () => NotInitializedError,
-  ParseError: () => ParseError,
-  ValidationError: () => ValidationError,
-  WasmLoadError: () => WasmLoadError,
-  createParser: () => createParser,
-  default: () => index_default,
-  isJwwFile: () => isJwwFile,
-  quickValidate: () => quickValidate
-});
-module.exports = __toCommonJS(index_exports);
-var import_meta = {};
-var JwwErrorCode = /* @__PURE__ */ ((JwwErrorCode2) => {
-  JwwErrorCode2["NOT_INITIALIZED"] = "NOT_INITIALIZED";
-  JwwErrorCode2["WASM_LOAD_FAILED"] = "WASM_LOAD_FAILED";
-  JwwErrorCode2["WASM_TIMEOUT"] = "WASM_TIMEOUT";
-  JwwErrorCode2["INVALID_SIGNATURE"] = "INVALID_SIGNATURE";
-  JwwErrorCode2["UNSUPPORTED_VERSION"] = "UNSUPPORTED_VERSION";
-  JwwErrorCode2["PARSE_ERROR"] = "PARSE_ERROR";
-  JwwErrorCode2["CONVERSION_ERROR"] = "CONVERSION_ERROR";
-  JwwErrorCode2["VALIDATION_ERROR"] = "VALIDATION_ERROR";
-  JwwErrorCode2["MEMORY_ERROR"] = "MEMORY_ERROR";
-  JwwErrorCode2["INVALID_ARGUMENT"] = "INVALID_ARGUMENT";
-  return JwwErrorCode2;
-})(JwwErrorCode || {});
-var JwwParserError = class _JwwParserError extends Error {
-  constructor(code, message, options) {
-    super(message);
-    this.name = "JwwParserError";
-    this.code = code;
-    this.cause = options?.cause;
-    this.context = options?.context;
-    this.timestamp = /* @__PURE__ */ new Date();
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(this, _JwwParserError);
-    }
-  }
-  /**
-   * Returns a detailed string representation of the error
-   */
-  toDetailedString() {
-    let details = `[${this.code}] ${this.message}`;
-    if (this.context) {
-      details += `
-Context: ${JSON.stringify(this.context, null, 2)}`;
-    }
-    if (this.cause) {
-      details += `
-Caused by: ${this.cause.message}`;
-    }
-    return details;
-  }
-  /**
-   * Converts the error to a plain object for logging/serialization
-   */
-  toJSON() {
-    return {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      context: this.context,
-      timestamp: this.timestamp.toISOString(),
-      cause: this.cause?.message,
-      stack: this.stack
-    };
-  }
-};
-var NotInitializedError = class extends JwwParserError {
-  constructor() {
-    super(
-      "NOT_INITIALIZED" /* NOT_INITIALIZED */,
-      "Parser not initialized. Call init() first or use createParser() factory function."
-    );
-    this.name = "NotInitializedError";
-  }
-};
-var WasmLoadError = class extends JwwParserError {
-  constructor(message, cause) {
-    super("WASM_LOAD_FAILED" /* WASM_LOAD_FAILED */, message, { cause });
-    this.name = "WasmLoadError";
-  }
-};
-var ValidationError = class extends JwwParserError {
-  constructor(message, issues) {
-    super("VALIDATION_ERROR" /* VALIDATION_ERROR */, message, {
-      context: { issues }
-    });
-    this.name = "ValidationError";
-    this.issues = issues;
-  }
-};
-var ParseError = class extends JwwParserError {
-  constructor(message, options) {
-    super("PARSE_ERROR" /* PARSE_ERROR */, message, {
-      cause: options?.cause,
-      context: {
-        offset: options?.offset,
-        section: options?.section
-      }
-    });
-    this.name = "ParseError";
-    this.offset = options?.offset;
-    this.section = options?.section;
-  }
-};
+/**
+ * JWW (Jw_cad) file parser and DXF converter
+ *
+ * This module provides functionality to parse JWW binary files
+ * and convert them to DXF format using WebAssembly.
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Error Classes
+// =============================================================================
+/**
+ * Error codes for JWW parser operations
+ */
+export var JwwErrorCode;
+(function (JwwErrorCode) {
+    /** Parser has not been initialized */
+    JwwErrorCode["NOT_INITIALIZED"] = "NOT_INITIALIZED";
+    /** WASM module failed to load */
+    JwwErrorCode["WASM_LOAD_FAILED"] = "WASM_LOAD_FAILED";
+    /** WASM functions not available after timeout */
+    JwwErrorCode["WASM_TIMEOUT"] = "WASM_TIMEOUT";
+    /** Invalid JWW file signature */
+    JwwErrorCode["INVALID_SIGNATURE"] = "INVALID_SIGNATURE";
+    /** Unsupported JWW version */
+    JwwErrorCode["UNSUPPORTED_VERSION"] = "UNSUPPORTED_VERSION";
+    /** General parse error */
+    JwwErrorCode["PARSE_ERROR"] = "PARSE_ERROR";
+    /** DXF conversion error */
+    JwwErrorCode["CONVERSION_ERROR"] = "CONVERSION_ERROR";
+    /** Validation error */
+    JwwErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    /** Memory allocation error */
+    JwwErrorCode["MEMORY_ERROR"] = "MEMORY_ERROR";
+    /** Invalid argument provided */
+    JwwErrorCode["INVALID_ARGUMENT"] = "INVALID_ARGUMENT";
+})(JwwErrorCode || (JwwErrorCode = {}));
+/**
+ * Base error class for JWW parser errors
+ */
+export class JwwParserError extends Error {
+    constructor(code, message, options) {
+        super(message);
+        this.name = "JwwParserError";
+        this.code = code;
+        this.cause = options?.cause;
+        this.context = options?.context;
+        this.timestamp = new Date();
+        // Maintain proper stack trace for where our error was thrown
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, JwwParserError);
+        }
+    }
+    /**
+     * Returns a detailed string representation of the error
+     */
+    toDetailedString() {
+        let details = `[${this.code}] ${this.message}`;
+        if (this.context) {
+            details += `\nContext: ${JSON.stringify(this.context, null, 2)}`;
+        }
+        if (this.cause) {
+            details += `\nCaused by: ${this.cause.message}`;
+        }
+        return details;
+    }
+    /**
+     * Converts the error to a plain object for logging/serialization
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            timestamp: this.timestamp.toISOString(),
+            cause: this.cause?.message,
+            stack: this.stack,
+        };
+    }
+}
+/**
+ * Error thrown when the parser is not initialized
+ */
+export class NotInitializedError extends JwwParserError {
+    constructor() {
+        super(JwwErrorCode.NOT_INITIALIZED, "Parser not initialized. Call init() first or use createParser() factory function.");
+        this.name = "NotInitializedError";
+    }
+}
+/**
+ * Error thrown when WASM module fails to load
+ */
+export class WasmLoadError extends JwwParserError {
+    constructor(message, cause) {
+        super(JwwErrorCode.WASM_LOAD_FAILED, message, { cause });
+        this.name = "WasmLoadError";
+    }
+}
+/**
+ * Error thrown when file validation fails
+ */
+export class ValidationError extends JwwParserError {
+    constructor(message, issues) {
+        super(JwwErrorCode.VALIDATION_ERROR, message, {
+            context: { issues },
+        });
+        this.name = "ValidationError";
+        this.issues = issues;
+    }
+}
+/**
+ * Error thrown during parsing
+ */
+export class ParseError extends JwwParserError {
+    constructor(message, options) {
+        super(JwwErrorCode.PARSE_ERROR, message, {
+            cause: options?.cause,
+            context: {
+                offset: options?.offset,
+                section: options?.section,
+            },
+        });
+        this.name = "ParseError";
+        this.offset = options?.offset;
+        this.section = options?.section;
+    }
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Format bytes to human-readable string
+ */
 function formatBytes(bytes) {
-  if (bytes < 1024) return `${bytes} B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
-  if (bytes < 1024 * 1024 * 1024)
-    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
-  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(2)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
 }
+/**
+ * Get file size category based on byte count
+ */
 function getSizeCategory(bytes) {
-  if (bytes < 100 * 1024) return "small";
-  if (bytes < 1024 * 1024) return "medium";
-  if (bytes < 10 * 1024 * 1024) return "large";
-  return "very_large";
+    if (bytes < 100 * 1024)
+        return "small"; // < 100KB
+    if (bytes < 1024 * 1024)
+        return "medium"; // < 1MB
+    if (bytes < 10 * 1024 * 1024)
+        return "large"; // < 10MB
+    return "very_large"; // >= 10MB
 }
+/**
+ * Create a parse error from WASM result
+ */
 function createParseError(result) {
-  const message = result.error || "Parse failed";
-  if (message.includes("invalid JWW signature")) {
-    return new ParseError("Invalid JWW file format: missing or corrupt signature", {
-      section: "header",
-      offset: 0
-    });
-  }
-  if (message.includes("unsupported") && message.includes("version")) {
-    return new ParseError(message, {
-      section: "header"
-    });
-  }
-  return new ParseError(message, {
-    offset: result.offset,
-    section: result.section
-  });
-}
-var JwwParser = class {
-  /**
-   * Create a new JWW parser instance
-   * @param wasmPath - Path to the jww-parser.wasm file
-   */
-  constructor(wasmPath) {
-    this.initialized = false;
-    this.initPromise = null;
-    this.goInstance = null;
-    this.wasmInstance = null;
-    // Debug and logging
-    this.debugOptions = { enabled: false };
-    this.debugLogs = [];
-    // Statistics
-    this.stats = {
-      parseCount: 0,
-      totalBytesProcessed: 0,
-      parseTimes: [],
-      errorCount: 0
-    };
-    this.wasmPath = wasmPath || this.getDefaultWasmPath();
-  }
-  getDefaultWasmPath() {
-    if (typeof process !== "undefined" && process.versions?.node) {
-      return new URL("../wasm/jww-parser.wasm", import_meta.url).pathname;
-    }
-    return "jww-parser.wasm";
-  }
-  // ===========================================================================
-  // Debug Methods
-  // ===========================================================================
-  /**
-   * Enable or configure debug mode
-   * @param options - Debug configuration options
-   */
-  setDebug(options) {
-    if (typeof options === "boolean") {
-      this.debugOptions = { enabled: options };
-    } else {
-      this.debugOptions = { ...this.debugOptions, ...options };
-    }
-    if (this.initialized && typeof globalThis.jwwSetDebug === "function") {
-      globalThis.jwwSetDebug(this.debugOptions.enabled ?? false);
-    }
-    this.log("info", "Debug mode " + (this.debugOptions.enabled ? "enabled" : "disabled"));
-  }
-  /**
-   * Get debug logs
-   * @param level - Optional minimum log level to filter
-   * @returns Array of debug log entries
-   */
-  getDebugLogs(level) {
-    if (!level) return [...this.debugLogs];
-    const levels = ["debug", "info", "warn", "error"];
-    const minIndex = levels.indexOf(level);
-    return this.debugLogs.filter(
-      (entry) => levels.indexOf(entry.level) >= minIndex
-    );
-  }
-  /**
-   * Clear debug logs
-   */
-  clearDebugLogs() {
-    this.debugLogs = [];
-  }
-  log(level, message, data) {
-    if (!this.debugOptions.enabled) return;
-    const levels = ["debug", "info", "warn", "error"];
-    const minLevel = this.debugOptions.logLevel || "info";
-    if (levels.indexOf(level) < levels.indexOf(minLevel)) return;
-    const entry = {
-      timestamp: /* @__PURE__ */ new Date(),
-      level,
-      message,
-      data: this.debugOptions.includeMemoryUsage ? { ...data, memory: this.getMemoryStats() } : data
-    };
-    this.debugLogs.push(entry);
-    if (this.debugLogs.length > (this.debugOptions.maxLogEntries || 1e3)) {
-      this.debugLogs.shift();
-    }
-    if (this.debugOptions.onDebug) {
-      this.debugOptions.onDebug(entry);
-    }
-    if (this.debugOptions.logToConsole) {
-      const consoleFn = level === "error" ? console.error : level === "warn" ? console.warn : level === "debug" ? console.debug : console.log;
-      consoleFn(`[JwwParser:${level}] ${message}`, data || "");
-    }
-  }
-  // ===========================================================================
-  // Initialization Methods
-  // ===========================================================================
-  /**
-   * Check if the parser is initialized
-   */
-  isInitialized() {
-    return this.initialized;
-  }
-  /**
-   * Initialize the WASM module
-   * Must be called before using parse methods
-   */
-  async init() {
-    if (this.initialized) return;
-    if (this.initPromise) return this.initPromise;
-    this.log("info", "Initializing WASM module");
-    const startTime = Date.now();
-    this.initPromise = this.loadWasm();
-    try {
-      await this.initPromise;
-      this.initialized = true;
-      this.log("info", "WASM module initialized", {
-        elapsedMs: Date.now() - startTime
-      });
-    } catch (error) {
-      this.initPromise = null;
-      this.log("error", "WASM initialization failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-      throw error;
-    }
-  }
-  async loadWasm() {
-    if (typeof Go === "undefined") {
-      await this.loadWasmExec();
-    }
-    this.goInstance = new Go();
-    try {
-      if (typeof process !== "undefined" && process.versions?.node) {
-        const fs = await import("fs");
-        const wasmBuffer = fs.readFileSync(this.wasmPath);
-        const wasmModule = await WebAssembly.compile(wasmBuffer);
-        this.wasmInstance = await WebAssembly.instantiate(
-          wasmModule,
-          this.goInstance.importObject
-        );
-      } else {
-        const result = await WebAssembly.instantiateStreaming(
-          fetch(this.wasmPath),
-          this.goInstance.importObject
-        ).catch(async () => {
-          const response = await fetch(this.wasmPath);
-          if (!response.ok) {
-            throw new WasmLoadError(
-              `Failed to fetch WASM file: ${response.status} ${response.statusText}`
-            );
-          }
-          const bytes = await response.arrayBuffer();
-          return WebAssembly.instantiate(bytes, this.goInstance.importObject);
+    const message = result.error || "Parse failed";
+    // Try to extract more specific error type
+    if (message.includes("invalid JWW signature")) {
+        return new ParseError("Invalid JWW file format: missing or corrupt signature", {
+            section: "header",
+            offset: 0,
         });
-        this.wasmInstance = result.instance;
-      }
-    } catch (error) {
-      throw new WasmLoadError(
-        `Failed to load WASM module: ${error instanceof Error ? error.message : String(error)}`,
-        error instanceof Error ? error : void 0
-      );
-    }
-    this.goInstance.run(this.wasmInstance);
-    await this.waitForWasmFunctions();
-    if (this.debugOptions.enabled && typeof globalThis.jwwSetDebug === "function") {
-      globalThis.jwwSetDebug(true);
-    }
-  }
-  async loadWasmExec() {
-    if (typeof process !== "undefined" && process.versions?.node) {
-      const wasmExecPath = new URL("../wasm/wasm_exec.js", import_meta.url).pathname;
-      await import(wasmExecPath);
-    } else {
-      throw new WasmLoadError(
-        "Go runtime not loaded. Please include wasm_exec.js in your HTML before using the parser."
-      );
-    }
-  }
-  async waitForWasmFunctions(timeout = 5e3, interval = 50) {
-    const start = Date.now();
-    while (Date.now() - start < timeout) {
-      if (typeof globalThis.jwwParse === "function" && typeof globalThis.jwwToDxf === "function" && typeof globalThis.jwwToDxfString === "function") {
-        return;
-      }
-      await new Promise((resolve) => setTimeout(resolve, interval));
-    }
-    throw new JwwParserError(
-      "WASM_TIMEOUT" /* WASM_TIMEOUT */,
-      "WASM functions not available after timeout. The WASM module may have failed to initialize."
-    );
-  }
-  ensureInitialized() {
-    if (!this.initialized) {
-      throw new NotInitializedError();
-    }
-  }
-  // ===========================================================================
-  // Validation Methods
-  // ===========================================================================
-  /**
-   * Validate a JWW file without fully parsing it
-   * Useful for checking file validity before processing
-   *
-   * @param data - JWW file content as Uint8Array
-   * @returns Validation result with any issues found
-   */
-  validate(data) {
-    const startTime = Date.now();
-    const issues = [];
-    if (data.length < 16) {
-      issues.push({
-        severity: "error",
-        code: "FILE_TOO_SMALL",
-        message: "File is too small to be a valid JWW file",
-        details: { size: data.length, minimumRequired: 16 }
-      });
     }
-    const signature = new TextDecoder().decode(data.slice(0, 8));
-    if (signature !== "JwwData.") {
-      issues.push({
-        severity: "error",
-        code: "INVALID_SIGNATURE",
-        message: `Invalid file signature: expected "JwwData.", got "${signature.replace(/[^\x20-\x7E]/g, "?")}"`,
-        offset: 0
-      });
-    }
-    let version;
-    if (data.length >= 12) {
-      const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-      version = view.getInt32(8, true);
-      if (version < 200 || version > 1e3) {
-        issues.push({
-          severity: "warning",
-          code: "UNUSUAL_VERSION",
-          message: `Unusual version number: ${version}. Expected between 200-1000.`,
-          details: { version }
+    if (message.includes("unsupported") && message.includes("version")) {
+        return new ParseError(message, {
+            section: "header",
         });
-      }
-    }
-    const estimatedEntityCount = Math.floor(data.length / 75);
-    const sizeCategory = getSizeCategory(data.length);
-    if (sizeCategory === "very_large") {
-      issues.push({
-        severity: "warning",
-        code: "LARGE_FILE",
-        message: `File is very large (${formatBytes(data.length)}). Consider using streaming mode for better performance.`,
-        details: { size: data.length, sizeFormatted: formatBytes(data.length) }
-      });
-    }
-    const hasErrors = issues.some((i) => i.severity === "error");
-    return {
-      valid: !hasErrors,
-      version,
-      sizeCategory,
-      estimatedEntityCount,
-      issues,
-      validationTimeMs: Date.now() - startTime
-    };
-  }
-  /**
-   * Validate and throw if invalid
-   * Convenience method that throws a ValidationError if the file is invalid
-   *
-   * @param data - JWW file content as Uint8Array
-   * @throws {ValidationError} If the file is invalid
-   */
-  validateOrThrow(data) {
-    const result = this.validate(data);
-    if (!result.valid) {
-      throw new ValidationError(
-        "File validation failed: " + result.issues.filter((i) => i.severity === "error").map((i) => i.message).join("; "),
-        result.issues
-      );
-    }
-  }
-  // ===========================================================================
-  // Parsing Methods
-  // ===========================================================================
-  /**
-   * Parse a JWW file and return the document structure
-   *
-   * @param data - JWW file content as Uint8Array
-   * @param options - Optional parsing options
-   * @returns Parsed JWW document
-   * @throws {NotInitializedError} If parser is not initialized
-   * @throws {ParseError} If parsing fails
-   */
-  parse(data, options) {
-    this.ensureInitialized();
-    if (options?.signal?.aborted) {
-      throw new JwwParserError(
-        "PARSE_ERROR" /* PARSE_ERROR */,
-        "Parse operation was aborted"
-      );
-    }
-    const startTime = Date.now();
-    this.log("info", "Starting parse operation", {
-      dataSize: data.length,
-      options: options ? { ...options, onProgress: void 0 } : void 0
+    }
+    return new ParseError(message, {
+        offset: result.offset,
+        section: result.section,
     });
-    if (options?.onProgress) {
-      options.onProgress({
-        stage: "loading",
-        progress: 0,
-        overallProgress: 0,
-        message: "Loading file data",
-        elapsedMs: 0
-      });
-    }
-    try {
-      const result = globalThis.jwwParse(data);
-      if (!result.ok) {
-        this.stats.errorCount++;
-        throw createParseError(result);
-      }
-      if (options?.onProgress) {
-        options.onProgress({
-          stage: "complete",
-          progress: 100,
-          overallProgress: 100,
-          message: "Parsing complete",
-          elapsedMs: Date.now() - startTime
-        });
-      }
-      const doc = JSON.parse(result.data);
-      let filteredDoc = doc;
-      if (options) {
-        filteredDoc = this.applyParseOptions(doc, options);
-      }
-      const parseTime = Date.now() - startTime;
-      this.stats.parseCount++;
-      this.stats.totalBytesProcessed += data.length;
-      this.stats.parseTimes.push(parseTime);
-      if (this.stats.parseTimes.length > 100) {
-        this.stats.parseTimes.shift();
-      }
-      this.log("info", "Parse complete", {
-        parseTimeMs: parseTime,
-        entityCount: filteredDoc.Entities.length,
-        blockCount: filteredDoc.Blocks.length
-      });
-      return filteredDoc;
-    } catch (error) {
-      this.stats.errorCount++;
-      this.log("error", "Parse failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-      if (error instanceof JwwParserError) {
-        throw error;
-      }
-      throw new ParseError(
-        error instanceof Error ? error.message : String(error),
-        { cause: error instanceof Error ? error : void 0 }
-      );
-    }
-  }
-  applyParseOptions(doc, options) {
-    let entities = doc.Entities;
-    let blocks = doc.Blocks;
-    if (options.skipEntityTypes && options.skipEntityTypes.length > 0) {
-      const skipTypes = new Set(options.skipEntityTypes);
-      entities = entities.filter((e) => !skipTypes.has(e.Type));
-    }
-    if (options.layerGroupFilter && options.layerGroupFilter.length > 0) {
-      const groups = new Set(options.layerGroupFilter);
-      entities = entities.filter((e) => groups.has(e.LayerGroup));
-    }
-    if (options.layerFilter) {
-      const filter = options.layerFilter;
-      entities = entities.filter((e) => {
-        const layers = filter[e.LayerGroup];
-        return !layers || layers.includes(e.Layer);
-      });
-    }
-    if (options.maxEntities && entities.length > options.maxEntities) {
-      entities = entities.slice(0, options.maxEntities);
-    }
-    if (options.includeBlocks === false) {
-      blocks = [];
-    }
-    return {
-      ...doc,
-      Entities: entities,
-      Blocks: blocks
-    };
-  }
-  /**
-   * Parse a JWW file and convert to DXF document structure
-   *
-   * @param data - JWW file content as Uint8Array
-   * @param options - Optional conversion options
-   * @returns DXF document object
-   */
-  toDxf(data, options) {
-    this.ensureInitialized();
-    const startTime = Date.now();
-    this.log("info", "Starting DXF conversion", { dataSize: data.length });
-    if (options?.onProgress) {
-      options.onProgress({
-        stage: "converting",
-        progress: 0,
-        overallProgress: 0,
-        message: "Converting to DXF",
-        elapsedMs: 0
-      });
-    }
-    try {
-      const result = globalThis.jwwToDxf(data);
-      if (!result.ok) {
-        this.stats.errorCount++;
-        throw createParseError(result);
-      }
-      if (options?.onProgress) {
-        options.onProgress({
-          stage: "complete",
-          progress: 100,
-          overallProgress: 100,
-          message: "Conversion complete",
-          elapsedMs: Date.now() - startTime
+}
+// =============================================================================
+// JwwParser Class
+// =============================================================================
+/**
+ * JWW file parser with WebAssembly backend
+ *
+ * @example
+ * ```typescript
+ * // Using the factory function (recommended)
+ * const parser = await createParser();
+ * const doc = parser.parse(fileData);
+ *
+ * // Manual initialization
+ * const parser = new JwwParser();
+ * await parser.init();
+ * const doc = parser.parse(fileData);
+ * ```
+ */
+export class JwwParser {
+    /**
+     * Create a new JWW parser instance
+     * @param wasmPath - Path to the jww-parser.wasm file
+     */
+    constructor(wasmPath) {
+        this.initialized = false;
+        this.initPromise = null;
+        this.goInstance = null;
+        this.wasmInstance = null;
+        // Debug and logging
+        this.debugOptions = { enabled: false };
+        this.debugLogs = [];
+        // Statistics
+        this.stats = {
+            parseCount: 0,
+            totalBytesProcessed: 0,
+            parseTimes: [],
+            errorCount: 0,
+        };
+        this.wasmPath = wasmPath || this.getDefaultWasmPath();
+    }
+    getDefaultWasmPath() {
+        if (typeof process !== "undefined" && process.versions?.node) {
+            return new URL("../wasm/jww-parser.wasm", import.meta.url).pathname;
+        }
+        return "jww-parser.wasm";
+    }
+    // ===========================================================================
+    // Debug Methods
+    // ===========================================================================
+    /**
+     * Enable or configure debug mode
+     * @param options - Debug configuration options
+     */
+    setDebug(options) {
+        if (typeof options === "boolean") {
+            this.debugOptions = { enabled: options };
+        }
+        else {
+            this.debugOptions = { ...this.debugOptions, ...options };
+        }
+        // Also set debug mode in WASM if available
+        if (this.initialized && typeof globalThis.jwwSetDebug === "function") {
+            globalThis.jwwSetDebug(this.debugOptions.enabled ?? false);
+        }
+        this.log("info", "Debug mode " + (this.debugOptions.enabled ? "enabled" : "disabled"));
+    }
+    /**
+     * Get debug logs
+     * @param level - Optional minimum log level to filter
+     * @returns Array of debug log entries
+     */
+    getDebugLogs(level) {
+        if (!level)
+            return [...this.debugLogs];
+        const levels = ["debug", "info", "warn", "error"];
+        const minIndex = levels.indexOf(level);
+        return this.debugLogs.filter((entry) => levels.indexOf(entry.level) >= minIndex);
+    }
+    /**
+     * Clear debug logs
+     */
+    clearDebugLogs() {
+        this.debugLogs = [];
+    }
+    log(level, message, data) {
+        if (!this.debugOptions.enabled)
+            return;
+        const levels = ["debug", "info", "warn", "error"];
+        const minLevel = this.debugOptions.logLevel || "info";
+        if (levels.indexOf(level) < levels.indexOf(minLevel))
+            return;
+        const entry = {
+            timestamp: new Date(),
+            level,
+            message,
+            data: this.debugOptions.includeMemoryUsage
+                ? { ...data, memory: this.getMemoryStats() }
+                : data,
+        };
+        // Store log entry
+        this.debugLogs.push(entry);
+        if (this.debugLogs.length > (this.debugOptions.maxLogEntries || 1000)) {
+            this.debugLogs.shift();
+        }
+        // Call debug callback if provided
+        if (this.debugOptions.onDebug) {
+            this.debugOptions.onDebug(entry);
+        }
+        // Log to console if enabled
+        if (this.debugOptions.logToConsole) {
+            const consoleFn = level === "error"
+                ? console.error
+                : level === "warn"
+                    ? console.warn
+                    : level === "debug"
+                        ? console.debug
+                        : console.log;
+            consoleFn(`[JwwParser:${level}] ${message}`, data || "");
+        }
+    }
+    // ===========================================================================
+    // Initialization Methods
+    // ===========================================================================
+    /**
+     * Check if the parser is initialized
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Initialize the WASM module
+     * Must be called before using parse methods
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.log("info", "Initializing WASM module");
+        const startTime = Date.now();
+        this.initPromise = this.loadWasm();
+        try {
+            await this.initPromise;
+            this.initialized = true;
+            this.log("info", "WASM module initialized", {
+                elapsedMs: Date.now() - startTime,
+            });
+        }
+        catch (error) {
+            this.initPromise = null;
+            this.log("error", "WASM initialization failed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    }
+    async loadWasm() {
+        // Load wasm_exec.js if Go is not defined
+        if (typeof Go === "undefined") {
+            await this.loadWasmExec();
+        }
+        this.goInstance = new Go();
+        try {
+            if (typeof process !== "undefined" && process.versions?.node) {
+                // Node.js environment
+                const fs = await import("fs");
+                const wasmBuffer = fs.readFileSync(this.wasmPath);
+                const wasmModule = await WebAssembly.compile(wasmBuffer);
+                this.wasmInstance = await WebAssembly.instantiate(wasmModule, this.goInstance.importObject);
+            }
+            else {
+                // Browser environment
+                const result = await WebAssembly.instantiateStreaming(fetch(this.wasmPath), this.goInstance.importObject).catch(async () => {
+                    const response = await fetch(this.wasmPath);
+                    if (!response.ok) {
+                        throw new WasmLoadError(`Failed to fetch WASM file: ${response.status} ${response.statusText}`);
+                    }
+                    const bytes = await response.arrayBuffer();
+                    return WebAssembly.instantiate(bytes, this.goInstance.importObject);
+                });
+                this.wasmInstance = result.instance;
+            }
+        }
+        catch (error) {
+            throw new WasmLoadError(`Failed to load WASM module: ${error instanceof Error ? error.message : String(error)}`, error instanceof Error ? error : undefined);
+        }
+        // Don't await - Go.run() blocks until the program exits
+        this.goInstance.run(this.wasmInstance);
+        // Wait for functions to be available
+        await this.waitForWasmFunctions();
+        // Set debug mode if already enabled
+        if (this.debugOptions.enabled &&
+            typeof globalThis.jwwSetDebug === "function") {
+            globalThis.jwwSetDebug(true);
+        }
+    }
+    async loadWasmExec() {
+        if (typeof process !== "undefined" && process.versions?.node) {
+            const wasmExecPath = new URL("../wasm/wasm_exec.js", import.meta.url)
+                .pathname;
+            await import(wasmExecPath);
+        }
+        else {
+            throw new WasmLoadError("Go runtime not loaded. Please include wasm_exec.js in your HTML before using the parser.");
+        }
+    }
+    async waitForWasmFunctions(timeout = 5000, interval = 50) {
+        const start = Date.now();
+        while (Date.now() - start < timeout) {
+            if (typeof globalThis.jwwParse === "function" &&
+                typeof globalThis.jwwToDxf === "function" &&
+                typeof globalThis.jwwToDxfString === "function") {
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, interval));
+        }
+        throw new JwwParserError(JwwErrorCode.WASM_TIMEOUT, "WASM functions not available after timeout. The WASM module may have failed to initialize.");
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new NotInitializedError();
+        }
+    }
+    // ===========================================================================
+    // Validation Methods
+    // ===========================================================================
+    /**
+     * Validate a JWW file without fully parsing it
+     * Useful for checking file validity before processing
+     *
+     * @param data - JWW file content as Uint8Array
+     * @returns Validation result with any issues found
+     */
+    validate(data) {
+        const startTime = Date.now();
+        // Basic validation without WASM (always available)
+        const issues = [];
+        // Check minimum size
+        if (data.length < 16) {
+            issues.push({
+                severity: "error",
+                code: "FILE_TOO_SMALL",
+                message: "File is too small to be a valid JWW file",
+                details: { size: data.length, minimumRequired: 16 },
+            });
+        }
+        // Check JWW signature "JwwData."
+        const signature = new TextDecoder().decode(data.slice(0, 8));
+        if (signature !== "JwwData.") {
+            issues.push({
+                severity: "error",
+                code: "INVALID_SIGNATURE",
+                message: `Invalid file signature: expected "JwwData.", got "${signature.replace(/[^\x20-\x7E]/g, "?")}"`,
+                offset: 0,
+            });
+        }
+        // Try to read version (bytes 8-11, little-endian)
+        let version;
+        if (data.length >= 12) {
+            const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+            version = view.getInt32(8, true);
+            if (version < 200 || version > 1000) {
+                issues.push({
+                    severity: "warning",
+                    code: "UNUSUAL_VERSION",
+                    message: `Unusual version number: ${version}. Expected between 200-1000.`,
+                    details: { version },
+                });
+            }
+        }
+        // Estimate entity count based on file size (rough heuristic)
+        // Average entity is approximately 50-100 bytes
+        const estimatedEntityCount = Math.floor(data.length / 75);
+        // Size warnings
+        const sizeCategory = getSizeCategory(data.length);
+        if (sizeCategory === "very_large") {
+            issues.push({
+                severity: "warning",
+                code: "LARGE_FILE",
+                message: `File is very large (${formatBytes(data.length)}). Consider using streaming mode for better performance.`,
+                details: { size: data.length, sizeFormatted: formatBytes(data.length) },
+            });
+        }
+        const hasErrors = issues.some((i) => i.severity === "error");
+        return {
+            valid: !hasErrors,
+            version,
+            sizeCategory,
+            estimatedEntityCount,
+            issues,
+            validationTimeMs: Date.now() - startTime,
+        };
+    }
+    /**
+     * Validate and throw if invalid
+     * Convenience method that throws a ValidationError if the file is invalid
+     *
+     * @param data - JWW file content as Uint8Array
+     * @throws {ValidationError} If the file is invalid
+     */
+    validateOrThrow(data) {
+        const result = this.validate(data);
+        if (!result.valid) {
+            throw new ValidationError("File validation failed: " +
+                result.issues
+                    .filter((i) => i.severity === "error")
+                    .map((i) => i.message)
+                    .join("; "), result.issues);
+        }
+    }
+    // ===========================================================================
+    // Parsing Methods
+    // ===========================================================================
+    /**
+     * Parse a JWW file and return the document structure
+     *
+     * @param data - JWW file content as Uint8Array
+     * @param options - Optional parsing options
+     * @returns Parsed JWW document
+     * @throws {NotInitializedError} If parser is not initialized
+     * @throws {ParseError} If parsing fails
+     */
+    parse(data, options) {
+        this.ensureInitialized();
+        // Check for abort signal
+        if (options?.signal?.aborted) {
+            throw new JwwParserError(JwwErrorCode.PARSE_ERROR, "Parse operation was aborted");
+        }
+        const startTime = Date.now();
+        this.log("info", "Starting parse operation", {
+            dataSize: data.length,
+            options: options ? { ...options, onProgress: undefined } : undefined,
         });
-      }
-      const doc = JSON.parse(result.data);
-      const parseTime = Date.now() - startTime;
-      this.stats.parseCount++;
-      this.stats.totalBytesProcessed += data.length;
-      this.stats.parseTimes.push(parseTime);
-      this.log("info", "DXF conversion complete", {
-        parseTimeMs: parseTime,
-        entityCount: doc.Entities.length
-      });
-      return doc;
-    } catch (error) {
-      this.stats.errorCount++;
-      this.log("error", "DXF conversion failed", {
-        error: error instanceof Error ? error.message : String(error)
-      });
-      if (error instanceof JwwParserError) {
-        throw error;
-      }
-      throw new ParseError(
-        error instanceof Error ? error.message : String(error),
-        { cause: error instanceof Error ? error : void 0 }
-      );
-    }
-  }
-  /**
-   * Parse a JWW file and convert to DXF file content string
-   *
-   * @param data - JWW file content as Uint8Array
-   * @param options - Optional conversion options
-   * @returns DXF file content as string (ready to save as .dxf file)
-   */
-  toDxfString(data, options) {
-    this.ensureInitialized();
-    const startTime = Date.now();
-    this.log("info", "Starting DXF string generation", { dataSize: data.length });
-    try {
-      const result = globalThis.jwwToDxfString(data);
-      if (!result.ok) {
-        this.stats.errorCount++;
-        throw createParseError(result);
-      }
-      const parseTime = Date.now() - startTime;
-      this.stats.parseCount++;
-      this.stats.totalBytesProcessed += data.length;
-      this.stats.parseTimes.push(parseTime);
-      this.log("info", "DXF string generation complete", {
-        parseTimeMs: parseTime,
-        outputLength: result.data.length
-      });
-      return result.data;
-    } catch (error) {
-      this.stats.errorCount++;
-      if (error instanceof JwwParserError) {
-        throw error;
-      }
-      throw new ParseError(
-        error instanceof Error ? error.message : String(error),
-        { cause: error instanceof Error ? error : void 0 }
-      );
-    }
-  }
-  // ===========================================================================
-  // Memory Management
-  // ===========================================================================
-  /**
-   * Get current memory usage statistics
-   */
-  getMemoryStats() {
-    let wasmMemoryBytes = 0;
-    if (this.wasmInstance?.exports.memory) {
-      const memory = this.wasmInstance.exports.memory;
-      wasmMemoryBytes = memory.buffer.byteLength;
-    }
-    let jsHeapBytes;
-    if (typeof process !== "undefined" && typeof process.memoryUsage === "function") {
-      jsHeapBytes = process.memoryUsage().heapUsed;
-    }
-    const totalBytes = wasmMemoryBytes + (jsHeapBytes || 0);
-    return {
-      wasmMemoryBytes,
-      jsHeapBytes,
-      totalBytes,
-      totalFormatted: formatBytes(totalBytes)
-    };
-  }
-  /**
-   * Get parser statistics
-   */
-  getStats() {
-    const parseTimes = this.stats.parseTimes;
-    return {
-      parseCount: this.stats.parseCount,
-      totalBytesProcessed: this.stats.totalBytesProcessed,
-      averageParseTimeMs: parseTimes.length > 0 ? parseTimes.reduce((a, b) => a + b, 0) / parseTimes.length : 0,
-      fastestParseTimeMs: parseTimes.length > 0 ? Math.min(...parseTimes) : 0,
-      slowestParseTimeMs: parseTimes.length > 0 ? Math.max(...parseTimes) : 0,
-      errorCount: this.stats.errorCount,
-      memoryStats: this.getMemoryStats()
-    };
-  }
-  /**
-   * Reset parser statistics
-   */
-  resetStats() {
-    this.stats = {
-      parseCount: 0,
-      totalBytesProcessed: 0,
-      parseTimes: [],
-      errorCount: 0
-    };
-    this.log("debug", "Statistics reset");
-  }
-  /**
-   * Clean up resources and release memory
-   * Call this when you're done using the parser to free WASM memory
-   */
-  dispose() {
-    this.log("info", "Disposing parser resources");
-    this.goInstance = null;
-    this.wasmInstance = null;
-    this.initialized = false;
-    this.initPromise = null;
-    this.stats = {
-      parseCount: 0,
-      totalBytesProcessed: 0,
-      parseTimes: [],
-      errorCount: 0
-    };
-    this.debugLogs = [];
-  }
-  /**
-   * Get the WASM module version
-   */
-  getVersion() {
-    if (typeof globalThis.jwwGetVersion === "function") {
-      return globalThis.jwwGetVersion();
-    }
-    return "1.0.0";
-  }
-};
-async function createParser(wasmPath, options) {
-  const parser = new JwwParser(wasmPath);
-  if (options?.debug) {
-    parser.setDebug(options.debug);
-  }
-  await parser.init();
-  return parser;
+        // Report initial progress
+        if (options?.onProgress) {
+            options.onProgress({
+                stage: "loading",
+                progress: 0,
+                overallProgress: 0,
+                message: "Loading file data",
+                elapsedMs: 0,
+            });
+        }
+        try {
+            const result = globalThis.jwwParse(data);
+            if (!result.ok) {
+                this.stats.errorCount++;
+                throw createParseError(result);
+            }
+            // Report parsing complete
+            if (options?.onProgress) {
+                options.onProgress({
+                    stage: "complete",
+                    progress: 100,
+                    overallProgress: 100,
+                    message: "Parsing complete",
+                    elapsedMs: Date.now() - startTime,
+                });
+            }
+            const doc = JSON.parse(result.data);
+            // Apply filtering options
+            let filteredDoc = doc;
+            if (options) {
+                filteredDoc = this.applyParseOptions(doc, options);
+            }
+            // Update stats
+            const parseTime = Date.now() - startTime;
+            this.stats.parseCount++;
+            this.stats.totalBytesProcessed += data.length;
+            this.stats.parseTimes.push(parseTime);
+            if (this.stats.parseTimes.length > 100) {
+                this.stats.parseTimes.shift();
+            }
+            this.log("info", "Parse complete", {
+                parseTimeMs: parseTime,
+                entityCount: filteredDoc.Entities.length,
+                blockCount: filteredDoc.Blocks.length,
+            });
+            return filteredDoc;
+        }
+        catch (error) {
+            this.stats.errorCount++;
+            this.log("error", "Parse failed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (error instanceof JwwParserError) {
+                throw error;
+            }
+            throw new ParseError(error instanceof Error ? error.message : String(error), { cause: error instanceof Error ? error : undefined });
+        }
+    }
+    applyParseOptions(doc, options) {
+        let entities = doc.Entities;
+        let blocks = doc.Blocks;
+        // Filter by entity type
+        if (options.skipEntityTypes && options.skipEntityTypes.length > 0) {
+            const skipTypes = new Set(options.skipEntityTypes);
+            entities = entities.filter((e) => !skipTypes.has(e.Type));
+        }
+        // Filter by layer group
+        if (options.layerGroupFilter && options.layerGroupFilter.length > 0) {
+            const groups = new Set(options.layerGroupFilter);
+            entities = entities.filter((e) => groups.has(e.LayerGroup));
+        }
+        // Filter by specific layers
+        if (options.layerFilter) {
+            const filter = options.layerFilter;
+            entities = entities.filter((e) => {
+                const layers = filter[e.LayerGroup];
+                return !layers || layers.includes(e.Layer);
+            });
+        }
+        // Limit entity count
+        if (options.maxEntities && entities.length > options.maxEntities) {
+            entities = entities.slice(0, options.maxEntities);
+        }
+        // Handle blocks
+        if (options.includeBlocks === false) {
+            blocks = [];
+        }
+        return {
+            ...doc,
+            Entities: entities,
+            Blocks: blocks,
+        };
+    }
+    /**
+     * Parse a JWW file and convert to DXF document structure
+     *
+     * @param data - JWW file content as Uint8Array
+     * @param options - Optional conversion options
+     * @returns DXF document object
+     */
+    toDxf(data, options) {
+        this.ensureInitialized();
+        const startTime = Date.now();
+        this.log("info", "Starting DXF conversion", { dataSize: data.length });
+        if (options?.onProgress) {
+            options.onProgress({
+                stage: "converting",
+                progress: 0,
+                overallProgress: 0,
+                message: "Converting to DXF",
+                elapsedMs: 0,
+            });
+        }
+        try {
+            const result = globalThis.jwwToDxf(data);
+            if (!result.ok) {
+                this.stats.errorCount++;
+                throw createParseError(result);
+            }
+            if (options?.onProgress) {
+                options.onProgress({
+                    stage: "complete",
+                    progress: 100,
+                    overallProgress: 100,
+                    message: "Conversion complete",
+                    elapsedMs: Date.now() - startTime,
+                });
+            }
+            const doc = JSON.parse(result.data);
+            // Update stats
+            const parseTime = Date.now() - startTime;
+            this.stats.parseCount++;
+            this.stats.totalBytesProcessed += data.length;
+            this.stats.parseTimes.push(parseTime);
+            this.log("info", "DXF conversion complete", {
+                parseTimeMs: parseTime,
+                entityCount: doc.Entities.length,
+            });
+            return doc;
+        }
+        catch (error) {
+            this.stats.errorCount++;
+            this.log("error", "DXF conversion failed", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (error instanceof JwwParserError) {
+                throw error;
+            }
+            throw new ParseError(error instanceof Error ? error.message : String(error), { cause: error instanceof Error ? error : undefined });
+        }
+    }
+    /**
+     * Parse a JWW file and convert to DXF file content string
+     *
+     * @param data - JWW file content as Uint8Array
+     * @param options - Optional conversion options
+     * @returns DXF file content as string (ready to save as .dxf file)
+     */
+    toDxfString(data, options) {
+        this.ensureInitialized();
+        const startTime = Date.now();
+        this.log("info", "Starting DXF string generation", { dataSize: data.length });
+        try {
+            const result = globalThis.jwwToDxfString(data);
+            if (!result.ok) {
+                this.stats.errorCount++;
+                throw createParseError(result);
+            }
+            const parseTime = Date.now() - startTime;
+            this.stats.parseCount++;
+            this.stats.totalBytesProcessed += data.length;
+            this.stats.parseTimes.push(parseTime);
+            this.log("info", "DXF string generation complete", {
+                parseTimeMs: parseTime,
+                outputLength: result.data.length,
+            });
+            return result.data;
+        }
+        catch (error) {
+            this.stats.errorCount++;
+            if (error instanceof JwwParserError) {
+                throw error;
+            }
+            throw new ParseError(error instanceof Error ? error.message : String(error), { cause: error instanceof Error ? error : undefined });
+        }
+    }
+    // ===========================================================================
+    // Memory Management
+    // ===========================================================================
+    /**
+     * Get current memory usage statistics
+     */
+    getMemoryStats() {
+        let wasmMemoryBytes = 0;
+        // Try to get WASM memory size
+        if (this.wasmInstance?.exports.memory) {
+            const memory = this.wasmInstance.exports.memory;
+            wasmMemoryBytes = memory.buffer.byteLength;
+        }
+        // Try to get JS heap size (Node.js only)
+        let jsHeapBytes;
+        if (typeof process !== "undefined" &&
+            typeof process.memoryUsage === "function") {
+            jsHeapBytes = process.memoryUsage().heapUsed;
+        }
+        const totalBytes = wasmMemoryBytes + (jsHeapBytes || 0);
+        return {
+            wasmMemoryBytes,
+            jsHeapBytes,
+            totalBytes,
+            totalFormatted: formatBytes(totalBytes),
+        };
+    }
+    /**
+     * Get parser statistics
+     */
+    getStats() {
+        const parseTimes = this.stats.parseTimes;
+        return {
+            parseCount: this.stats.parseCount,
+            totalBytesProcessed: this.stats.totalBytesProcessed,
+            averageParseTimeMs: parseTimes.length > 0
+                ? parseTimes.reduce((a, b) => a + b, 0) / parseTimes.length
+                : 0,
+            fastestParseTimeMs: parseTimes.length > 0 ? Math.min(...parseTimes) : 0,
+            slowestParseTimeMs: parseTimes.length > 0 ? Math.max(...parseTimes) : 0,
+            errorCount: this.stats.errorCount,
+            memoryStats: this.getMemoryStats(),
+        };
+    }
+    /**
+     * Reset parser statistics
+     */
+    resetStats() {
+        this.stats = {
+            parseCount: 0,
+            totalBytesProcessed: 0,
+            parseTimes: [],
+            errorCount: 0,
+        };
+        this.log("debug", "Statistics reset");
+    }
+    /**
+     * Clean up resources and release memory
+     * Call this when you're done using the parser to free WASM memory
+     */
+    dispose() {
+        this.log("info", "Disposing parser resources");
+        // Clear references
+        this.goInstance = null;
+        this.wasmInstance = null;
+        this.initialized = false;
+        this.initPromise = null;
+        // Clear stats and logs
+        this.stats = {
+            parseCount: 0,
+            totalBytesProcessed: 0,
+            parseTimes: [],
+            errorCount: 0,
+        };
+        this.debugLogs = [];
+        // Note: We cannot truly "free" WASM memory, but clearing references
+        // allows garbage collection to reclaim the memory
+    }
+    /**
+     * Get the WASM module version
+     */
+    getVersion() {
+        if (typeof globalThis.jwwGetVersion === "function") {
+            return globalThis.jwwGetVersion();
+        }
+        return "1.0.0"; // Fallback version
+    }
 }
-function quickValidate(data) {
-  const parser = new JwwParser();
-  return parser.validate(data);
+// =============================================================================
+// Factory Functions
+// =============================================================================
+/**
+ * Create and initialize a JWW parser instance
+ *
+ * @param wasmPath - Optional path to the jww-parser.wasm file
+ * @param options - Optional debug options
+ * @returns Initialized JwwParser instance
+ *
+ * @example
+ * ```typescript
+ * const parser = await createParser();
+ * const doc = parser.parse(fileData);
+ * ```
+ */
+export async function createParser(wasmPath, options) {
+    const parser = new JwwParser(wasmPath);
+    if (options?.debug) {
+        parser.setDebug(options.debug);
+    }
+    await parser.init();
+    return parser;
 }
-function isJwwFile(data) {
-  if (data.length < 8) return false;
-  const signature = new TextDecoder().decode(data.slice(0, 8));
-  return signature === "JwwData.";
+/**
+ * Quick validate a JWW file without initializing a full parser
+ * Performs basic validation only (signature, version check)
+ *
+ * @param data - JWW file content as Uint8Array
+ * @returns Validation result
+ */
+export function quickValidate(data) {
+    const parser = new JwwParser();
+    return parser.validate(data);
+}
+/**
+ * Check if a Uint8Array looks like a JWW file
+ *
+ * @param data - File content as Uint8Array
+ * @returns true if the file appears to be a JWW file
+ */
+export function isJwwFile(data) {
+    if (data.length < 8)
+        return false;
+    const signature = new TextDecoder().decode(data.slice(0, 8));
+    return signature === "JwwData.";
 }
-var index_default = {
-  JwwParser,
-  createParser,
-  quickValidate,
-  isJwwFile,
-  JwwParserError,
-  NotInitializedError,
-  WasmLoadError,
-  ValidationError,
-  ParseError,
-  JwwErrorCode
+// =============================================================================
+// Default Export
+// =============================================================================
+export default {
+    JwwParser,
+    createParser,
+    quickValidate,
+    isJwwFile,
+    JwwParserError,
+    NotInitializedError,
+    WasmLoadError,
+    ValidationError,
+    ParseError,
+    JwwErrorCode,
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  JwwErrorCode,
-  JwwParser,
-  JwwParserError,
-  NotInitializedError,
-  ParseError,
-  ValidationError,
-  WasmLoadError,
-  createParser,
-  isJwwFile,
-  quickValidate
-});