@k67/kaitai-struct-ts 0.8.0 → 0.9.0

package/dist/cli.js

@@ -5,6 +5,73 @@
 var import_fs = require("fs");
 var import_path = require("path");
 var import_util = require("util");
+var import_yaml2 = require("yaml");
+
+// src/parser/schema.ts
+var BUILTIN_TYPES = [
+  // Unsigned integers
+  "u1",
+  "u2",
+  "u2le",
+  "u2be",
+  "u4",
+  "u4le",
+  "u4be",
+  "u8",
+  "u8le",
+  "u8be",
+  // Signed integers
+  "s1",
+  "s2",
+  "s2le",
+  "s2be",
+  "s4",
+  "s4le",
+  "s4be",
+  "s8",
+  "s8le",
+  "s8be",
+  // Floating point
+  "f4",
+  "f4le",
+  "f4be",
+  "f8",
+  "f8le",
+  "f8be",
+  // String
+  "str",
+  "strz"
+];
+function isBuiltinType(type) {
+  if (BUILTIN_TYPES.includes(type)) return true;
+  if (/^b\d+$/.test(type)) return true;
+  return false;
+}
+function getTypeEndianness(type) {
+  if (type.endsWith("le")) return "le";
+  if (type.endsWith("be")) return "be";
+  return void 0;
+}
+function getBaseType(type) {
+  if (type.endsWith("le") || type.endsWith("be")) {
+    return type.slice(0, -2);
+  }
+  return type;
+}
+function isIntegerType(type) {
+  const base = getBaseType(type);
+  return /^[us][1248]$/.test(base);
+}
+function isFloatType(type) {
+  const base = getBaseType(type);
+  return /^f[48]$/.test(base);
+}
+function isStringType(type) {
+  return type === "str" || type === "strz";
+}
+
+// src/parser/KsyParser.ts
+var import_yaml = require("yaml");
 
 // src/utils/errors.ts
 var KaitaiError = class _KaitaiError extends Error {
@@ -44,964 +111,974 @@ var NotImplementedError = class _NotImplementedError extends KaitaiError {
   }
 };
 
-// src/utils/encoding.ts
-function decodeString(bytes, encoding) {
-  const normalizedEncoding = encoding.toLowerCase().replace(/[-_]/g, "");
-  switch (normalizedEncoding) {
-    case "utf8":
-    case "utf-8":
-      return decodeUtf8(bytes);
-    case "ascii":
-    case "usascii":
-      return decodeAscii(bytes);
-    case "utf16":
-    case "utf16le":
-    case "utf-16le":
-      return decodeUtf16Le(bytes);
-    case "utf16be":
-    case "utf-16be":
-      return decodeUtf16Be(bytes);
-    case "latin1":
-    case "iso88591":
-    case "iso-8859-1":
-      return decodeLatin1(bytes);
-    default:
-      if (typeof TextDecoder !== "undefined") {
-        try {
-          return new TextDecoder(encoding).decode(bytes);
-        } catch {
-          throw new Error(`Unsupported encoding: ${encoding}`);
-        }
-      }
-      throw new Error(`Unsupported encoding: ${encoding}`);
-  }
-}
-function decodeUtf8(bytes) {
-  if (typeof TextDecoder !== "undefined") {
-    return new TextDecoder("utf-8").decode(bytes);
-  }
-  let result = "";
-  let i = 0;
-  while (i < bytes.length) {
-    const byte1 = bytes[i++];
-    if (byte1 < 128) {
-      result += String.fromCharCode(byte1);
-    } else if (byte1 < 224) {
-      const byte2 = bytes[i++];
-      result += String.fromCharCode((byte1 & 31) << 6 | byte2 & 63);
-    } else if (byte1 < 240) {
-      const byte2 = bytes[i++];
-      const byte3 = bytes[i++];
-      result += String.fromCharCode(
-        (byte1 & 15) << 12 | (byte2 & 63) << 6 | byte3 & 63
-      );
-    } else {
-      const byte2 = bytes[i++];
-      const byte3 = bytes[i++];
-      const byte4 = bytes[i++];
-      let codePoint = (byte1 & 7) << 18 | (byte2 & 63) << 12 | (byte3 & 63) << 6 | byte4 & 63;
-      codePoint -= 65536;
-      result += String.fromCharCode(
-        55296 + (codePoint >> 10),
-        56320 + (codePoint & 1023)
-      );
-    }
-  }
-  return result;
-}
-function decodeAscii(bytes) {
-  let result = "";
-  for (let i = 0; i < bytes.length; i++) {
-    result += String.fromCharCode(bytes[i] & 127);
-  }
-  return result;
-}
-function decodeLatin1(bytes) {
-  let result = "";
-  for (let i = 0; i < bytes.length; i++) {
-    result += String.fromCharCode(bytes[i]);
-  }
-  return result;
-}
-function decodeUtf16Le(bytes) {
-  if (typeof TextDecoder !== "undefined") {
-    return new TextDecoder("utf-16le").decode(bytes);
-  }
-  let result = "";
-  for (let i = 0; i < bytes.length; i += 2) {
-    const charCode = bytes[i] | bytes[i + 1] << 8;
-    result += String.fromCharCode(charCode);
-  }
-  return result;
-}
-function decodeUtf16Be(bytes) {
-  if (typeof TextDecoder !== "undefined") {
-    return new TextDecoder("utf-16be").decode(bytes);
-  }
-  let result = "";
-  for (let i = 0; i < bytes.length; i += 2) {
-    const charCode = bytes[i] << 8 | bytes[i + 1];
-    result += String.fromCharCode(charCode);
-  }
-  return result;
-}
-
-// src/stream/KaitaiStream.ts
-var KaitaiStream = class _KaitaiStream {
+// src/parser/KsyParser.ts
+var KsyParser = class {
   /**
-   * Create a new KaitaiStream from a buffer
-   * @param buffer - ArrayBuffer or Uint8Array containing the binary data
+   * Parse a .ksy YAML string into a typed schema object.
+   *
+   * @param yaml - YAML string containing the .ksy definition
+   * @param options - Parsing options
+   * @returns Parsed and validated schema
+   * @throws {ParseError} If YAML parsing fails
+   * @throws {ValidationError} If schema validation fails
    */
-  constructor(buffer) {
-    this._pos = 0;
-    this._bits = 0;
-    this._bitsLeft = 0;
-    if (buffer instanceof ArrayBuffer) {
-      this.buffer = new Uint8Array(buffer);
-      this.view = new DataView(buffer);
-    } else {
-      this.buffer = buffer;
-      this.view = new DataView(
-        buffer.buffer,
-        buffer.byteOffset,
-        buffer.byteLength
+  parse(yaml, options = {}) {
+    const { validate = true, strict = false } = options;
+    let parsed;
+    try {
+      parsed = (0, import_yaml.parse)(yaml);
+    } catch (error) {
+      throw new ParseError(
+        `Failed to parse YAML: ${error instanceof Error ? error.message : String(error)}`
       );
     }
-  }
-  /**
-   * Current position in the stream
-   */
-  get pos() {
-    return this._pos;
-  }
-  set pos(value) {
-    this._pos = value;
-    this._bitsLeft = 0;
-  }
-  /**
-   * Total size of the stream in bytes
-   */
-  get size() {
-    return this.buffer.length;
-  }
-  /**
-   * Check if we've reached the end of the stream
-   */
-  isEof() {
-    return this._pos >= this.buffer.length;
-  }
-  /**
-   * Seek to a specific position in the stream
-   * @param pos - Position to seek to
-   */
-  seek(pos) {
-    if (pos < 0 || pos > this.buffer.length) {
-      throw new Error(`Invalid seek position: ${pos}`);
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new ParseError("KSY file must contain an object");
     }
-    this.pos = pos;
+    const schema = parsed;
+    if (validate) {
+      const result = this.validate(schema, { strict });
+      if (!result.valid) {
+        const errorMessages = result.errors.map((e) => e.message).join("; ");
+        throw new ValidationError(
+          `Schema validation failed: ${errorMessages}`
+        );
+      }
+      if (result.warnings.length > 0 && !strict) {
+        console.warn(
+          "Schema validation warnings:",
+          result.warnings.map((w) => w.message)
+        );
+      }
+    }
+    return schema;
   }
   /**
-   * Ensure we have enough bytes available
-   * @param count - Number of bytes needed
+   * Validate a schema object.
+   *
+   * @param schema - Schema to validate
+   * @param options - Validation options
+   * @returns Validation result with errors and warnings
    */
-  ensureBytes(count) {
-    if (this._pos + count > this.buffer.length) {
-      throw new EOFError(
-        `Requested ${count} bytes at position ${this._pos}, but only ${this.buffer.length - this._pos} bytes available`,
-        this._pos
-      );
+  validate(schema, options = {}) {
+    const { strict = false, isNested = false } = options;
+    const errors = [];
+    const warnings = [];
+    if (!schema.meta && !isNested) {
+      errors.push({
+        message: 'Missing required "meta" section',
+        path: [],
+        code: "MISSING_META"
+      });
+    } else if (schema.meta) {
+      if (!schema.meta.id) {
+        errors.push({
+          message: 'Missing required "meta.id" field',
+          path: ["meta"],
+          code: "MISSING_META_ID"
+        });
+      } else if (typeof schema.meta.id !== "string") {
+        errors.push({
+          message: '"meta.id" must be a string',
+          path: ["meta", "id"],
+          code: "INVALID_META_ID_TYPE"
+        });
+      } else if (!/^[a-z][a-z0-9_]*$/.test(schema.meta.id)) {
+        warnings.push({
+          message: '"meta.id" should follow snake_case naming convention',
+          path: ["meta", "id"],
+          code: "META_ID_NAMING"
+        });
+      }
+      if (schema.meta.endian) {
+        if (typeof schema.meta.endian === "string" && schema.meta.endian !== "le" && schema.meta.endian !== "be") {
+          errors.push({
+            message: '"meta.endian" must be "le" or "be"',
+            path: ["meta", "endian"],
+            code: "INVALID_ENDIAN"
+          });
+        }
+      }
+    }
+    if (schema.seq) {
+      if (!Array.isArray(schema.seq)) {
+        errors.push({
+          message: '"seq" must be an array',
+          path: ["seq"],
+          code: "INVALID_SEQ_TYPE"
+        });
+      } else {
+        schema.seq.forEach((attr, index) => {
+          this.validateAttribute(
+            attr,
+            ["seq", String(index)],
+            errors,
+            warnings,
+            strict
+          );
+        });
+      }
     }
+    if (schema.instances) {
+      if (typeof schema.instances !== "object") {
+        errors.push({
+          message: '"instances" must be an object',
+          path: ["instances"],
+          code: "INVALID_INSTANCES_TYPE"
+        });
+      } else {
+        Object.entries(schema.instances).forEach(([key, instance]) => {
+          this.validateAttribute(
+            instance,
+            ["instances", key],
+            errors,
+            warnings,
+            strict
+          );
+        });
+      }
+    }
+    if (schema.types) {
+      if (typeof schema.types !== "object") {
+        errors.push({
+          message: '"types" must be an object',
+          path: ["types"],
+          code: "INVALID_TYPES_TYPE"
+        });
+      } else {
+        Object.entries(schema.types).forEach(([key, type]) => {
+          const typeResult = this.validate(type, { ...options, isNested: true });
+          errors.push(
+            ...typeResult.errors.map((e) => ({
+              ...e,
+              path: ["types", key, ...e.path]
+            }))
+          );
+          warnings.push(
+            ...typeResult.warnings.map((w) => ({
+              ...w,
+              path: ["types", key, ...w.path]
+            }))
+          );
+        });
+      }
+    }
+    if (schema.enums) {
+      if (typeof schema.enums !== "object") {
+        errors.push({
+          message: '"enums" must be an object',
+          path: ["enums"],
+          code: "INVALID_ENUMS_TYPE"
+        });
+      }
+    }
+    return {
+      valid: errors.length === 0 && (strict ? warnings.length === 0 : true),
+      errors,
+      warnings
+    };
   }
-  // ==================== Unsigned Integers ====================
   /**
-   * Read 1-byte unsigned integer (0 to 255)
+   * Validate an attribute specification.
+   *
+   * @param attr - Attribute to validate
+   * @param path - Path to this attribute in the schema
+   * @param errors - Array to collect errors
+   * @param warnings - Array to collect warnings
+   * @param strict - Whether to be strict about warnings
+   * @private
    */
-  readU1() {
-    this.ensureBytes(1);
-    return this.buffer[this._pos++];
+  validateAttribute(attr, path, errors, warnings, _strict) {
+    if (attr.id && typeof attr.id === "string") {
+      if (!/^[a-z][a-z0-9_]*$/.test(attr.id)) {
+        warnings.push({
+          message: `Field "${attr.id}" should follow snake_case naming convention`,
+          path: [...path, "id"],
+          code: "FIELD_ID_NAMING"
+        });
+      }
+    }
+    if (attr.repeat) {
+      if (attr.repeat !== "expr" && attr.repeat !== "eos" && attr.repeat !== "until") {
+        errors.push({
+          message: '"repeat" must be "expr", "eos", or "until"',
+          path: [...path, "repeat"],
+          code: "INVALID_REPEAT"
+        });
+      }
+      if (attr.repeat === "expr" && !attr["repeat-expr"]) {
+        errors.push({
+          message: '"repeat-expr" is required when repeat is "expr"',
+          path: [...path, "repeat-expr"],
+          code: "MISSING_REPEAT_EXPR"
+        });
+      }
+      if (attr.repeat === "until" && !attr["repeat-until"]) {
+        errors.push({
+          message: '"repeat-until" is required when repeat is "until"',
+          path: [...path, "repeat-until"],
+          code: "MISSING_REPEAT_UNTIL"
+        });
+      }
+    }
+    if (attr["size-eos"] && attr.size) {
+      warnings.push({
+        message: '"size-eos" and "size" are mutually exclusive',
+        path: [...path],
+        code: "SIZE_EOS_WITH_SIZE"
+      });
+    }
+    if (attr.contents) {
+      if (!Array.isArray(attr.contents) && typeof attr.contents !== "string") {
+        errors.push({
+          message: '"contents" must be an array or string',
+          path: [...path, "contents"],
+          code: "INVALID_CONTENTS_TYPE"
+        });
+      }
+    }
   }
   /**
-   * Read 2-byte unsigned integer, little-endian
-   */
-  readU2le() {
-    this.ensureBytes(2);
-    const value = this.view.getUint16(this._pos, true);
-    this._pos += 2;
-    return value;
+   * Parse multiple .ksy files and resolve imports.
+   *
+   * @param mainYaml - Main .ksy file content
+   * @param imports - Map of import names to their YAML content
+   * @param options - Parsing options
+   * @returns Parsed schema with resolved imports
+   * @throws {ParseError} If import resolution fails
+   * @example
+   * ```typescript
+   * const parser = new KsyParser()
+   * const imports = new Map([
+   *   ['/common/riff', riffYamlContent]
+   * ])
+   * const schema = parser.parseWithImports(wavYaml, imports)
+   * ```
+   */
+  parseWithImports(mainYaml, imports, options = {}) {
+    const mainSchema = this.parse(mainYaml, options);
+    if (!mainSchema.meta.imports || mainSchema.meta.imports.length === 0) {
+      return mainSchema;
+    }
+    const resolvedTypes = {};
+    for (const importPath of mainSchema.meta.imports) {
+      if (!imports.has(importPath)) {
+        throw new ParseError(
+          `Import not found: ${importPath}. Available imports: ${Array.from(imports.keys()).join(", ")}`
+        );
+      }
+      const importYaml = imports.get(importPath);
+      const importedSchema = this.parse(importYaml, {
+        ...options,
+        validate: false
+        // Skip validation for imported schemas
+      });
+      const namespace = this.extractNamespace(importPath);
+      if (importedSchema.types) {
+        for (const [typeName, typeSchema] of Object.entries(
+          importedSchema.types
+        )) {
+          const qualifiedName = `${namespace}::${typeName}`;
+          resolvedTypes[qualifiedName] = typeSchema;
+        }
+      }
+      resolvedTypes[namespace] = {
+        meta: importedSchema.meta,
+        seq: importedSchema.seq,
+        instances: importedSchema.instances,
+        types: importedSchema.types,
+        enums: importedSchema.enums
+      };
+      if (importedSchema.enums) {
+        if (!mainSchema.enums) {
+          mainSchema.enums = {};
+        }
+        for (const [enumName, enumSpec] of Object.entries(
+          importedSchema.enums
+        )) {
+          const qualifiedEnumName = `${namespace}::${enumName}`;
+          mainSchema.enums[qualifiedEnumName] = enumSpec;
+        }
+      }
+    }
+    if (Object.keys(resolvedTypes).length > 0) {
+      mainSchema.types = {
+        ...resolvedTypes,
+        ...mainSchema.types
+      };
+    }
+    return mainSchema;
   }
   /**
-   * Read 2-byte unsigned integer, big-endian
+   * Extract namespace from import path.
+   * Converts paths like '/common/riff' or 'common/riff' to 'riff'.
+   *
+   * @param importPath - Import path from meta.imports
+   * @returns Namespace identifier
+   * @private
    */
-  readU2be() {
-    this.ensureBytes(2);
-    const value = this.view.getUint16(this._pos, false);
-    this._pos += 2;
-    return value;
+  extractNamespace(importPath) {
+    const normalized = importPath.startsWith("/") ? importPath.slice(1) : importPath;
+    const segments = normalized.split("/");
+    return segments[segments.length - 1];
   }
+};
+
+// src/interpreter/Context.ts
+var Context = class _Context {
   /**
-   * Read 4-byte unsigned integer, little-endian
+   * Create a new execution context.
+   *
+   * @param _io - Binary stream being read
+   * @param _root - Root object of the parse tree
+   * @param _parent - Parent object (optional)
+   * @param enums - Enum definitions from schema (optional)
    */
-  readU4le() {
-    this.ensureBytes(4);
-    const value = this.view.getUint32(this._pos, true);
-    this._pos += 4;
-    return value;
+  constructor(_io, _root = null, _parent = null, enums) {
+    this._io = _io;
+    this._root = _root;
+    /** Stack of parent objects */
+    this.parentStack = [];
+    /** Current object being parsed */
+    this._current = {};
+    /** Enum definitions from schema */
+    this._enums = {};
+    if (_parent !== null) {
+      this.parentStack.push(_parent);
+    }
+    if (enums) {
+      this._enums = enums;
+    }
   }
   /**
-   * Read 4-byte unsigned integer, big-endian
+   * Get the current I/O stream.
+   * Accessible in expressions as `_io`.
+   *
+   * @returns Current stream
    */
-  readU4be() {
-    this.ensureBytes(4);
-    const value = this.view.getUint32(this._pos, false);
-    this._pos += 4;
-    return value;
-  }
-  /**
-   * Read 8-byte unsigned integer, little-endian
-   * Returns BigInt for values > Number.MAX_SAFE_INTEGER
-   */
-  readU8le() {
-    this.ensureBytes(8);
-    const value = this.view.getBigUint64(this._pos, true);
-    this._pos += 8;
-    return value;
+  get io() {
+    return this._io;
   }
   /**
-   * Read 8-byte unsigned integer, big-endian
-   * Returns BigInt for values > Number.MAX_SAFE_INTEGER
+   * Get the root object.
+   * Accessible in expressions as `_root`.
+   *
+   * @returns Root object
    */
-  readU8be() {
-    this.ensureBytes(8);
-    const value = this.view.getBigUint64(this._pos, false);
-    this._pos += 8;
-    return value;
+  get root() {
+    return this._root;
   }
-  // ==================== Signed Integers ====================
   /**
-   * Read 1-byte signed integer (-128 to 127)
+   * Get the parent object.
+   * Accessible in expressions as `_parent`.
+   *
+   * @returns Parent object or null if at root
    */
-  readS1() {
-    this.ensureBytes(1);
-    return this.view.getInt8(this._pos++);
+  get parent() {
+    return this.parentStack.length > 0 ? this.parentStack[this.parentStack.length - 1] : null;
   }
   /**
-   * Read 2-byte signed integer, little-endian
+   * Get the current object being parsed.
+   * Used to access fields defined earlier in the sequence.
+   *
+   * @returns Current object
    */
-  readS2le() {
-    this.ensureBytes(2);
-    const value = this.view.getInt16(this._pos, true);
-    this._pos += 2;
-    return value;
+  get current() {
+    return this._current;
   }
   /**
-   * Read 2-byte signed integer, big-endian
+   * Set the current object.
+   *
+   * @param obj - Object to set as current
    */
-  readS2be() {
-    this.ensureBytes(2);
-    const value = this.view.getInt16(this._pos, false);
-    this._pos += 2;
-    return value;
+  set current(obj) {
+    this._current = obj;
   }
   /**
-   * Read 4-byte signed integer, little-endian
+   * Push a new parent onto the stack.
+   * Used when entering a nested type.
+   *
+   * @param parent - Parent object to push
    */
-  readS4le() {
-    this.ensureBytes(4);
-    const value = this.view.getInt32(this._pos, true);
-    this._pos += 4;
-    return value;
+  pushParent(parent) {
+    this.parentStack.push(parent);
   }
   /**
-   * Read 4-byte signed integer, big-endian
+   * Pop the current parent from the stack.
+   * Used when exiting a nested type.
+   *
+   * @returns The popped parent object
    */
-  readS4be() {
-    this.ensureBytes(4);
-    const value = this.view.getInt32(this._pos, false);
-    this._pos += 4;
-    return value;
+  popParent() {
+    return this.parentStack.pop();
   }
   /**
-   * Read 8-byte signed integer, little-endian
-   * Returns BigInt for values outside Number.MAX_SAFE_INTEGER range
+   * Get a value from the context by path.
+   * Supports special names: _io, _root, _parent, _index.
+   *
+   * @param name - Name or path to resolve
+   * @returns Resolved value
    */
-  readS8le() {
-    this.ensureBytes(8);
-    const value = this.view.getBigInt64(this._pos, true);
-    this._pos += 8;
-    return value;
+  resolve(name) {
+    switch (name) {
+      case "_io":
+        return this._io;
+      case "_root":
+        return this._root;
+      case "_parent":
+        return this.parent;
+      case "_index":
+        return this._current["_index"];
+      default:
+        if (name in this._current) {
+          return this._current[name];
+        }
+        return void 0;
+    }
   }
   /**
-   * Read 8-byte signed integer, big-endian
-   * Returns BigInt for values outside Number.MAX_SAFE_INTEGER range
+   * Set a value in the current object.
+   *
+   * @param name - Field name
+   * @param value - Value to set
    */
-  readS8be() {
-    this.ensureBytes(8);
-    const value = this.view.getBigInt64(this._pos, false);
-    this._pos += 8;
-    return value;
+  set(name, value) {
+    this._current[name] = value;
   }
-  // ==================== Floating Point ====================
   /**
-   * Read 4-byte IEEE 754 single-precision float, little-endian
+   * Get enum value by name.
+   * Used for enum access in expressions (EnumName::value).
+   *
+   * @param enumName - Name of the enum
+   * @param valueName - Name of the enum value
+   * @returns Enum value (number) or undefined
    */
-  readF4le() {
-    this.ensureBytes(4);
-    const value = this.view.getFloat32(this._pos, true);
-    this._pos += 4;
-    return value;
+  getEnumValue(enumName, valueName) {
+    const enumDef = this._enums[enumName];
+    if (!enumDef) {
+      return void 0;
+    }
+    for (const [key, value] of Object.entries(enumDef)) {
+      if (value === valueName) {
+        const numKey = Number(key);
+        return isNaN(numKey) ? key : numKey;
+      }
+    }
+    return void 0;
   }
   /**
-   * Read 4-byte IEEE 754 single-precision float, big-endian
+   * Check if an enum exists.
+   *
+   * @param enumName - Name of the enum
+   * @returns True if enum exists
    */
-  readF4be() {
-    this.ensureBytes(4);
-    const value = this.view.getFloat32(this._pos, false);
-    this._pos += 4;
-    return value;
+  hasEnum(enumName) {
+    return enumName in this._enums;
   }
   /**
-   * Read 8-byte IEEE 754 double-precision float, little-endian
+   * Create a child context for nested parsing.
+   * The current object becomes the parent in the child context.
+   *
+   * @param stream - Stream for the child context (defaults to current stream)
+   * @returns New child context
    */
-  readF8le() {
-    this.ensureBytes(8);
-    const value = this.view.getFloat64(this._pos, true);
-    this._pos += 8;
-    return value;
+  createChild(stream) {
+    const childContext = new _Context(
+      stream || this._io,
+      this._root || this._current,
+      this._current,
+      this._enums
+    );
+    return childContext;
   }
   /**
-   * Read 8-byte IEEE 754 double-precision float, big-endian
+   * Clone this context.
+   * Creates a shallow copy with the same stream, root, and parent.
+   *
+   * @returns Cloned context
    */
-  readF8be() {
-    this.ensureBytes(8);
-    const value = this.view.getFloat64(this._pos, false);
-    this._pos += 8;
-    return value;
+  clone() {
+    const cloned = new _Context(this._io, this._root, this.parent, this._enums);
+    cloned._current = { ...this._current };
+    cloned.parentStack = [...this.parentStack];
+    return cloned;
   }
-  // ==================== Byte Arrays ====================
-  /**
-   * Read a fixed number of bytes
-   * @param length - Number of bytes to read
-   */
-  readBytes(length) {
-    this.ensureBytes(length);
-    const bytes = this.buffer.slice(this._pos, this._pos + length);
-    this._pos += length;
-    return bytes;
+};
+
+// src/utils/encoding.ts
+function decodeString(bytes, encoding) {
+  const normalizedEncoding = encoding.toLowerCase().replace(/[-_]/g, "");
+  switch (normalizedEncoding) {
+    case "utf8":
+    case "utf-8":
+      return decodeUtf8(bytes);
+    case "ascii":
+    case "usascii":
+      return decodeAscii(bytes);
+    case "utf16":
+    case "utf16le":
+    case "utf-16le":
+      return decodeUtf16Le(bytes);
+    case "utf16be":
+    case "utf-16be":
+      return decodeUtf16Be(bytes);
+    case "latin1":
+    case "iso88591":
+    case "iso-8859-1":
+      return decodeLatin1(bytes);
+    default:
+      if (typeof TextDecoder !== "undefined") {
+        try {
+          return new TextDecoder(encoding).decode(bytes);
+        } catch {
+          throw new Error(`Unsupported encoding: ${encoding}`);
+        }
+      }
+      throw new Error(`Unsupported encoding: ${encoding}`);
   }
-  /**
-   * Read all remaining bytes until end of stream
-   */
-  readBytesFull() {
-    const bytes = this.buffer.slice(this._pos);
-    this._pos = this.buffer.length;
-    return bytes;
+}
+function decodeUtf8(bytes) {
+  if (typeof TextDecoder !== "undefined") {
+    return new TextDecoder("utf-8").decode(bytes);
   }
-  /**
-   * Read bytes until a terminator byte is found
-   * @param term - Terminator byte value
-   * @param include - Include terminator in result
-   * @param consume - Consume terminator from stream
-   * @param eosError - Throw error if EOS reached before terminator
-   */
-  readBytesterm(term, include = false, consume = true, eosError = true) {
-    const start = this._pos;
-    let end = start;
-    while (end < this.buffer.length && this.buffer[end] !== term) {
-      end++;
-    }
-    const foundTerm = end < this.buffer.length;
-    if (!foundTerm && eosError) {
-      throw new EOFError(
-        `Terminator byte ${term} not found before end of stream`,
-        this._pos
+  let result = "";
+  let i = 0;
+  while (i < bytes.length) {
+    const byte1 = bytes[i++];
+    if (byte1 < 128) {
+      result += String.fromCharCode(byte1);
+    } else if (byte1 < 224) {
+      const byte2 = bytes[i++];
+      result += String.fromCharCode((byte1 & 31) << 6 | byte2 & 63);
+    } else if (byte1 < 240) {
+      const byte2 = bytes[i++];
+      const byte3 = bytes[i++];
+      result += String.fromCharCode(
+        (byte1 & 15) << 12 | (byte2 & 63) << 6 | byte3 & 63
+      );
+    } else {
+      const byte2 = bytes[i++];
+      const byte3 = bytes[i++];
+      const byte4 = bytes[i++];
+      let codePoint = (byte1 & 7) << 18 | (byte2 & 63) << 12 | (byte3 & 63) << 6 | byte4 & 63;
+      codePoint -= 65536;
+      result += String.fromCharCode(
+        55296 + (codePoint >> 10),
+        56320 + (codePoint & 1023)
       );
     }
-    const includeEnd = include && foundTerm ? end + 1 : end;
-    const bytes = this.buffer.slice(start, includeEnd);
-    if (foundTerm && consume) {
-      this._pos = end + 1;
+  }
+  return result;
+}
+function decodeAscii(bytes) {
+  let result = "";
+  for (let i = 0; i < bytes.length; i++) {
+    result += String.fromCharCode(bytes[i] & 127);
+  }
+  return result;
+}
+function decodeLatin1(bytes) {
+  let result = "";
+  for (let i = 0; i < bytes.length; i++) {
+    result += String.fromCharCode(bytes[i]);
+  }
+  return result;
+}
+function decodeUtf16Le(bytes) {
+  if (typeof TextDecoder !== "undefined") {
+    return new TextDecoder("utf-16le").decode(bytes);
+  }
+  let result = "";
+  for (let i = 0; i < bytes.length; i += 2) {
+    const charCode = bytes[i] | bytes[i + 1] << 8;
+    result += String.fromCharCode(charCode);
+  }
+  return result;
+}
+function decodeUtf16Be(bytes) {
+  if (typeof TextDecoder !== "undefined") {
+    return new TextDecoder("utf-16be").decode(bytes);
+  }
+  let result = "";
+  for (let i = 0; i < bytes.length; i += 2) {
+    const charCode = bytes[i] << 8 | bytes[i + 1];
+    result += String.fromCharCode(charCode);
+  }
+  return result;
+}
+
+// src/stream/KaitaiStream.ts
+var KaitaiStream = class _KaitaiStream {
+  /**
+   * Create a new KaitaiStream from a buffer
+   * @param buffer - ArrayBuffer or Uint8Array containing the binary data
+   */
+  constructor(buffer) {
+    this._pos = 0;
+    this._bits = 0;
+    this._bitsLeft = 0;
+    if (buffer instanceof ArrayBuffer) {
+      this.buffer = new Uint8Array(buffer);
+      this.view = new DataView(buffer);
     } else {
-      this._pos = end;
+      this.buffer = buffer;
+      this.view = new DataView(
+        buffer.buffer,
+        buffer.byteOffset,
+        buffer.byteLength
+      );
     }
-    return bytes;
   }
-  // ==================== Strings ====================
   /**
-   * Read a fixed-length string
-   * @param length - Number of bytes to read
-   * @param encoding - Character encoding (default: UTF-8)
+   * Current position in the stream
    */
-  readStr(length, encoding = "UTF-8") {
-    const bytes = this.readBytes(length);
-    return decodeString(bytes, encoding);
+  get pos() {
+    return this._pos;
+  }
+  set pos(value) {
+    this._pos = value;
+    this._bitsLeft = 0;
   }
   /**
-   * Read a null-terminated string
-   * @param encoding - Character encoding (default: UTF-8)
-   * @param term - Terminator byte (default: 0)
-   * @param include - Include terminator in result
-   * @param consume - Consume terminator from stream
-   * @param eosError - Throw error if EOS reached before terminator
+   * Total size of the stream in bytes
    */
-  readStrz(encoding = "UTF-8", term = 0, include = false, consume = true, eosError = true) {
-    const bytes = this.readBytesterm(term, include, consume, eosError);
-    return decodeString(bytes, encoding);
+  get size() {
+    return this.buffer.length;
   }
-  // ==================== Bit-level Reading ====================
   /**
-   * Align bit reading to byte boundary
+   * Check if we've reached the end of the stream
    */
-  alignToByte() {
-    this._bitsLeft = 0;
+  isEof() {
+    return this._pos >= this.buffer.length;
   }
   /**
-   * Read specified number of bits as unsigned integer (big-endian)
-   * @param n - Number of bits to read (1-64)
+   * Seek to a specific position in the stream
+   * @param pos - Position to seek to
    */
-  readBitsIntBe(n) {
-    if (n < 1 || n > 64) {
-      throw new Error(`Invalid bit count: ${n}. Must be between 1 and 64`);
-    }
-    let result = 0n;
-    for (let bitsNeeded = n; bitsNeeded > 0; ) {
-      if (this._bitsLeft === 0) {
-        this._bits = this.readU1();
-        this._bitsLeft = 8;
-      }
-      const bitsToRead = Math.min(bitsNeeded, this._bitsLeft);
-      const mask = (1 << bitsToRead) - 1;
-      const shift = this._bitsLeft - bitsToRead;
-      result = result << BigInt(bitsToRead) | BigInt(this._bits >> shift & mask);
-      this._bitsLeft -= bitsToRead;
-      bitsNeeded -= bitsToRead;
+  seek(pos) {
+    if (pos < 0 || pos > this.buffer.length) {
+      throw new Error(`Invalid seek position: ${pos}`);
     }
-    return result;
+    this.pos = pos;
   }
   /**
-   * Read specified number of bits as unsigned integer (little-endian)
-   * @param n - Number of bits to read (1-64)
+   * Ensure we have enough bytes available
+   * @param count - Number of bytes needed
    */
-  readBitsIntLe(n) {
-    if (n < 1 || n > 64) {
-      throw new Error(`Invalid bit count: ${n}. Must be between 1 and 64`);
-    }
-    let result = 0n;
-    let bitPos = 0;
-    for (let bitsNeeded = n; bitsNeeded > 0; ) {
-      if (this._bitsLeft === 0) {
-        this._bits = this.readU1();
-        this._bitsLeft = 8;
-      }
-      const bitsToRead = Math.min(bitsNeeded, this._bitsLeft);
-      const mask = (1 << bitsToRead) - 1;
-      result |= BigInt(this._bits & mask) << BigInt(bitPos);
-      this._bits >>= bitsToRead;
-      this._bitsLeft -= bitsToRead;
-      bitsNeeded -= bitsToRead;
-      bitPos += bitsToRead;
+  ensureBytes(count) {
+    if (this._pos + count > this.buffer.length) {
+      throw new EOFError(
+        `Requested ${count} bytes at position ${this._pos}, but only ${this.buffer.length - this._pos} bytes available`,
+        this._pos
+      );
     }
-    return result;
   }
-  // ==================== Utility Methods ====================
+  // ==================== Unsigned Integers ====================
   /**
-   * Get the underlying buffer
+   * Read 1-byte unsigned integer (0 to 255)
    */
-  getBuffer() {
-    return this.buffer;
+  readU1() {
+    this.ensureBytes(1);
+    return this.buffer[this._pos++];
   }
   /**
-   * Create a substream from current position with specified size
-   * @param size - Size of the substream in bytes
+   * Read 2-byte unsigned integer, little-endian
    */
-  substream(size) {
-    this.ensureBytes(size);
-    const subBuffer = this.buffer.slice(this._pos, this._pos + size);
-    this._pos += size;
-    return new _KaitaiStream(subBuffer);
+  readU2le() {
+    this.ensureBytes(2);
+    const value = this.view.getUint16(this._pos, true);
+    this._pos += 2;
+    return value;
   }
-};
-
-// src/parser/schema.ts
-var BUILTIN_TYPES = [
-  // Unsigned integers
-  "u1",
-  "u2",
-  "u2le",
-  "u2be",
-  "u4",
-  "u4le",
-  "u4be",
-  "u8",
-  "u8le",
-  "u8be",
-  // Signed integers
-  "s1",
-  "s2",
-  "s2le",
-  "s2be",
-  "s4",
-  "s4le",
-  "s4be",
-  "s8",
-  "s8le",
-  "s8be",
-  // Floating point
-  "f4",
-  "f4le",
-  "f4be",
-  "f8",
-  "f8le",
-  "f8be",
-  // String
-  "str",
-  "strz"
-];
-function isBuiltinType(type) {
-  return BUILTIN_TYPES.includes(type);
-}
-function getTypeEndianness(type) {
-  if (type.endsWith("le")) return "le";
-  if (type.endsWith("be")) return "be";
-  return void 0;
-}
-function getBaseType(type) {
-  if (type.endsWith("le") || type.endsWith("be")) {
-    return type.slice(0, -2);
+  /**
+   * Read 2-byte unsigned integer, big-endian
+   */
+  readU2be() {
+    this.ensureBytes(2);
+    const value = this.view.getUint16(this._pos, false);
+    this._pos += 2;
+    return value;
   }
-  return type;
-}
-function isIntegerType(type) {
-  const base = getBaseType(type);
-  return /^[us][1248]$/.test(base);
-}
-function isFloatType(type) {
-  const base = getBaseType(type);
-  return /^f[48]$/.test(base);
-}
-function isStringType(type) {
-  return type === "str" || type === "strz";
-}
-
-// src/parser/KsyParser.ts
-var import_yaml = require("yaml");
-var KsyParser = class {
   /**
-   * Parse a .ksy YAML string into a typed schema object.
-   *
-   * @param yaml - YAML string containing the .ksy definition
-   * @param options - Parsing options
-   * @returns Parsed and validated schema
-   * @throws {ParseError} If YAML parsing fails
-   * @throws {ValidationError} If schema validation fails
+   * Read 4-byte unsigned integer, little-endian
    */
-  parse(yaml, options = {}) {
-    const { validate = true, strict = false } = options;
-    let parsed;
-    try {
-      parsed = (0, import_yaml.parse)(yaml);
-    } catch (error) {
-      throw new ParseError(
-        `Failed to parse YAML: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
-    if (typeof parsed !== "object" || parsed === null) {
-      throw new ParseError("KSY file must contain an object");
-    }
-    const schema = parsed;
-    if (validate) {
-      const result = this.validate(schema, { strict });
-      if (!result.valid) {
-        const errorMessages = result.errors.map((e) => e.message).join("; ");
-        throw new ValidationError(
-          `Schema validation failed: ${errorMessages}`
-        );
-      }
-      if (result.warnings.length > 0 && !strict) {
-        console.warn(
-          "Schema validation warnings:",
-          result.warnings.map((w) => w.message)
-        );
-      }
-    }
-    return schema;
+  readU4le() {
+    this.ensureBytes(4);
+    const value = this.view.getUint32(this._pos, true);
+    this._pos += 4;
+    return value;
   }
   /**
-   * Validate a schema object.
-   *
-   * @param schema - Schema to validate
-   * @param options - Validation options
-   * @returns Validation result with errors and warnings
+   * Read 4-byte unsigned integer, big-endian
    */
-  validate(schema, options = {}) {
-    const { strict = false, isNested = false } = options;
-    const errors = [];
-    const warnings = [];
-    if (!schema.meta && !isNested) {
-      errors.push({
-        message: 'Missing required "meta" section',
-        path: [],
-        code: "MISSING_META"
-      });
-    } else if (schema.meta) {
-      if (!schema.meta.id) {
-        errors.push({
-          message: 'Missing required "meta.id" field',
-          path: ["meta"],
-          code: "MISSING_META_ID"
-        });
-      } else if (typeof schema.meta.id !== "string") {
-        errors.push({
-          message: '"meta.id" must be a string',
-          path: ["meta", "id"],
-          code: "INVALID_META_ID_TYPE"
-        });
-      } else if (!/^[a-z][a-z0-9_]*$/.test(schema.meta.id)) {
-        warnings.push({
-          message: '"meta.id" should follow snake_case naming convention',
-          path: ["meta", "id"],
-          code: "META_ID_NAMING"
-        });
-      }
-      if (schema.meta.endian) {
-        if (typeof schema.meta.endian === "string" && schema.meta.endian !== "le" && schema.meta.endian !== "be") {
-          errors.push({
-            message: '"meta.endian" must be "le" or "be"',
-            path: ["meta", "endian"],
-            code: "INVALID_ENDIAN"
-          });
-        }
-      }
-    }
-    if (schema.seq) {
-      if (!Array.isArray(schema.seq)) {
-        errors.push({
-          message: '"seq" must be an array',
-          path: ["seq"],
-          code: "INVALID_SEQ_TYPE"
-        });
-      } else {
-        schema.seq.forEach((attr, index) => {
-          this.validateAttribute(
-            attr,
-            ["seq", String(index)],
-            errors,
-            warnings,
-            strict
-          );
-        });
-      }
-    }
-    if (schema.instances) {
-      if (typeof schema.instances !== "object") {
-        errors.push({
-          message: '"instances" must be an object',
-          path: ["instances"],
-          code: "INVALID_INSTANCES_TYPE"
-        });
-      } else {
-        Object.entries(schema.instances).forEach(([key, instance]) => {
-          this.validateAttribute(
-            instance,
-            ["instances", key],
-            errors,
-            warnings,
-            strict
-          );
-        });
-      }
-    }
-    if (schema.types) {
-      if (typeof schema.types !== "object") {
-        errors.push({
-          message: '"types" must be an object',
-          path: ["types"],
-          code: "INVALID_TYPES_TYPE"
-        });
-      } else {
-        Object.entries(schema.types).forEach(([key, type]) => {
-          const typeResult = this.validate(type, { ...options, isNested: true });
-          errors.push(
-            ...typeResult.errors.map((e) => ({
-              ...e,
-              path: ["types", key, ...e.path]
-            }))
-          );
-          warnings.push(
-            ...typeResult.warnings.map((w) => ({
-              ...w,
-              path: ["types", key, ...w.path]
-            }))
-          );
-        });
-      }
-    }
-    if (schema.enums) {
-      if (typeof schema.enums !== "object") {
-        errors.push({
-          message: '"enums" must be an object',
-          path: ["enums"],
-          code: "INVALID_ENUMS_TYPE"
-        });
-      }
-    }
-    return {
-      valid: errors.length === 0 && (strict ? warnings.length === 0 : true),
-      errors,
-      warnings
-    };
+  readU4be() {
+    this.ensureBytes(4);
+    const value = this.view.getUint32(this._pos, false);
+    this._pos += 4;
+    return value;
+  }
+  /**
+   * Read 8-byte unsigned integer, little-endian
+   * Returns BigInt for values > Number.MAX_SAFE_INTEGER
+   */
+  readU8le() {
+    this.ensureBytes(8);
+    const value = this.view.getBigUint64(this._pos, true);
+    this._pos += 8;
+    return value;
   }
   /**
-   * Validate an attribute specification.
-   *
-   * @param attr - Attribute to validate
-   * @param path - Path to this attribute in the schema
-   * @param errors - Array to collect errors
-   * @param warnings - Array to collect warnings
-   * @param strict - Whether to be strict about warnings
-   * @private
+   * Read 8-byte unsigned integer, big-endian
+   * Returns BigInt for values > Number.MAX_SAFE_INTEGER
    */
-  validateAttribute(attr, path, errors, warnings, _strict) {
-    if (attr.id && typeof attr.id === "string") {
-      if (!/^[a-z][a-z0-9_]*$/.test(attr.id)) {
-        warnings.push({
-          message: `Field "${attr.id}" should follow snake_case naming convention`,
-          path: [...path, "id"],
-          code: "FIELD_ID_NAMING"
-        });
-      }
-    }
-    if (attr.repeat) {
-      if (attr.repeat !== "expr" && attr.repeat !== "eos" && attr.repeat !== "until") {
-        errors.push({
-          message: '"repeat" must be "expr", "eos", or "until"',
-          path: [...path, "repeat"],
-          code: "INVALID_REPEAT"
-        });
-      }
-      if (attr.repeat === "expr" && !attr["repeat-expr"]) {
-        errors.push({
-          message: '"repeat-expr" is required when repeat is "expr"',
-          path: [...path, "repeat-expr"],
-          code: "MISSING_REPEAT_EXPR"
-        });
-      }
-      if (attr.repeat === "until" && !attr["repeat-until"]) {
-        errors.push({
-          message: '"repeat-until" is required when repeat is "until"',
-          path: [...path, "repeat-until"],
-          code: "MISSING_REPEAT_UNTIL"
-        });
-      }
-    }
-    if (attr["size-eos"] && attr.size) {
-      warnings.push({
-        message: '"size-eos" and "size" are mutually exclusive',
-        path: [...path],
-        code: "SIZE_EOS_WITH_SIZE"
-      });
-    }
-    if (attr.contents) {
-      if (!Array.isArray(attr.contents) && typeof attr.contents !== "string") {
-        errors.push({
-          message: '"contents" must be an array or string',
-          path: [...path, "contents"],
-          code: "INVALID_CONTENTS_TYPE"
-        });
-      }
-    }
+  readU8be() {
+    this.ensureBytes(8);
+    const value = this.view.getBigUint64(this._pos, false);
+    this._pos += 8;
+    return value;
   }
+  // ==================== Signed Integers ====================
   /**
-   * Parse multiple .ksy files and resolve imports.
-   *
-   * @param mainYaml - Main .ksy file content
-   * @param imports - Map of import names to their YAML content
-   * @param options - Parsing options
-   * @returns Parsed schema with resolved imports
+   * Read 1-byte signed integer (-128 to 127)
    */
-  parseWithImports(mainYaml, _imports, options = {}) {
-    const mainSchema = this.parse(mainYaml, options);
-    return mainSchema;
+  readS1() {
+    this.ensureBytes(1);
+    return this.view.getInt8(this._pos++);
   }
-};
-
-// src/interpreter/Context.ts
-var Context = class _Context {
   /**
-   * Create a new execution context.
-   *
-   * @param _io - Binary stream being read
-   * @param _root - Root object of the parse tree
-   * @param _parent - Parent object (optional)
-   * @param enums - Enum definitions from schema (optional)
+   * Read 2-byte signed integer, little-endian
    */
-  constructor(_io, _root = null, _parent = null, enums) {
-    this._io = _io;
-    this._root = _root;
-    /** Stack of parent objects */
-    this.parentStack = [];
-    /** Current object being parsed */
-    this._current = {};
-    /** Enum definitions from schema */
-    this._enums = {};
-    if (_parent !== null) {
-      this.parentStack.push(_parent);
-    }
-    if (enums) {
-      this._enums = enums;
-    }
+  readS2le() {
+    this.ensureBytes(2);
+    const value = this.view.getInt16(this._pos, true);
+    this._pos += 2;
+    return value;
   }
   /**
-   * Get the current I/O stream.
-   * Accessible in expressions as `_io`.
-   *
-   * @returns Current stream
+   * Read 2-byte signed integer, big-endian
    */
-  get io() {
-    return this._io;
+  readS2be() {
+    this.ensureBytes(2);
+    const value = this.view.getInt16(this._pos, false);
+    this._pos += 2;
+    return value;
   }
   /**
-   * Get the root object.
-   * Accessible in expressions as `_root`.
-   *
-   * @returns Root object
+   * Read 4-byte signed integer, little-endian
    */
-  get root() {
-    return this._root;
+  readS4le() {
+    this.ensureBytes(4);
+    const value = this.view.getInt32(this._pos, true);
+    this._pos += 4;
+    return value;
   }
   /**
-   * Get the parent object.
-   * Accessible in expressions as `_parent`.
-   *
-   * @returns Parent object or null if at root
+   * Read 4-byte signed integer, big-endian
    */
-  get parent() {
-    return this.parentStack.length > 0 ? this.parentStack[this.parentStack.length - 1] : null;
+  readS4be() {
+    this.ensureBytes(4);
+    const value = this.view.getInt32(this._pos, false);
+    this._pos += 4;
+    return value;
   }
   /**
-   * Get the current object being parsed.
-   * Used to access fields defined earlier in the sequence.
-   *
-   * @returns Current object
+   * Read 8-byte signed integer, little-endian
+   * Returns BigInt for values outside Number.MAX_SAFE_INTEGER range
    */
-  get current() {
-    return this._current;
+  readS8le() {
+    this.ensureBytes(8);
+    const value = this.view.getBigInt64(this._pos, true);
+    this._pos += 8;
+    return value;
+  }
+  /**
+   * Read 8-byte signed integer, big-endian
+   * Returns BigInt for values outside Number.MAX_SAFE_INTEGER range
+   */
+  readS8be() {
+    this.ensureBytes(8);
+    const value = this.view.getBigInt64(this._pos, false);
+    this._pos += 8;
+    return value;
+  }
+  // ==================== Floating Point ====================
+  /**
+   * Read 4-byte IEEE 754 single-precision float, little-endian
+   */
+  readF4le() {
+    this.ensureBytes(4);
+    const value = this.view.getFloat32(this._pos, true);
+    this._pos += 4;
+    return value;
+  }
+  /**
+   * Read 4-byte IEEE 754 single-precision float, big-endian
+   */
+  readF4be() {
+    this.ensureBytes(4);
+    const value = this.view.getFloat32(this._pos, false);
+    this._pos += 4;
+    return value;
+  }
+  /**
+   * Read 8-byte IEEE 754 double-precision float, little-endian
+   */
+  readF8le() {
+    this.ensureBytes(8);
+    const value = this.view.getFloat64(this._pos, true);
+    this._pos += 8;
+    return value;
+  }
+  /**
+   * Read 8-byte IEEE 754 double-precision float, big-endian
+   */
+  readF8be() {
+    this.ensureBytes(8);
+    const value = this.view.getFloat64(this._pos, false);
+    this._pos += 8;
+    return value;
+  }
+  // ==================== Byte Arrays ====================
+  /**
+   * Read a fixed number of bytes
+   * @param length - Number of bytes to read
+   */
+  readBytes(length) {
+    this.ensureBytes(length);
+    const bytes = this.buffer.slice(this._pos, this._pos + length);
+    this._pos += length;
+    return bytes;
+  }
+  /**
+   * Read all remaining bytes until end of stream
+   */
+  readBytesFull() {
+    const bytes = this.buffer.slice(this._pos);
+    this._pos = this.buffer.length;
+    return bytes;
+  }
+  /**
+   * Read bytes until a terminator byte is found
+   * @param term - Terminator byte value
+   * @param include - Include terminator in result
+   * @param consume - Consume terminator from stream
+   * @param eosError - Throw error if EOS reached before terminator
+   */
+  readBytesterm(term, include = false, consume = true, eosError = true) {
+    const start = this._pos;
+    let end = start;
+    while (end < this.buffer.length && this.buffer[end] !== term) {
+      end++;
+    }
+    const foundTerm = end < this.buffer.length;
+    if (!foundTerm && eosError) {
+      throw new EOFError(
+        `Terminator byte ${term} not found before end of stream`,
+        this._pos
+      );
+    }
+    const includeEnd = include && foundTerm ? end + 1 : end;
+    const bytes = this.buffer.slice(start, includeEnd);
+    if (foundTerm && consume) {
+      this._pos = end + 1;
+    } else {
+      this._pos = end;
+    }
+    return bytes;
   }
+  // ==================== Strings ====================
   /**
-   * Set the current object.
-   *
-   * @param obj - Object to set as current
+   * Read a fixed-length string
+   * @param length - Number of bytes to read
+   * @param encoding - Character encoding (default: UTF-8)
    */
-  set current(obj) {
-    this._current = obj;
+  readStr(length, encoding = "UTF-8") {
+    const bytes = this.readBytes(length);
+    return decodeString(bytes, encoding);
   }
   /**
-   * Push a new parent onto the stack.
-   * Used when entering a nested type.
-   *
-   * @param parent - Parent object to push
+   * Read a null-terminated string
+   * @param encoding - Character encoding (default: UTF-8)
+   * @param term - Terminator byte (default: 0)
+   * @param include - Include terminator in result
+   * @param consume - Consume terminator from stream
+   * @param eosError - Throw error if EOS reached before terminator
    */
-  pushParent(parent) {
-    this.parentStack.push(parent);
+  readStrz(encoding = "UTF-8", term = 0, include = false, consume = true, eosError = true) {
+    const bytes = this.readBytesterm(term, include, consume, eosError);
+    return decodeString(bytes, encoding);
   }
+  // ==================== Bit-level Reading ====================
   /**
-   * Pop the current parent from the stack.
-   * Used when exiting a nested type.
-   *
-   * @returns The popped parent object
+   * Align bit reading to byte boundary
    */
-  popParent() {
-    return this.parentStack.pop();
+  alignToByte() {
+    this._bitsLeft = 0;
   }
   /**
-   * Get a value from the context by path.
-   * Supports special names: _io, _root, _parent, _index.
-   *
-   * @param name - Name or path to resolve
-   * @returns Resolved value
+   * Read specified number of bits as unsigned integer (big-endian)
+   * @param n - Number of bits to read (1-64)
    */
-  resolve(name) {
-    switch (name) {
-      case "_io":
-        return this._io;
-      case "_root":
-        return this._root;
-      case "_parent":
-        return this.parent;
-      case "_index":
-        return this._current["_index"];
-      default:
-        if (name in this._current) {
-          return this._current[name];
-        }
-        return void 0;
+  readBitsIntBe(n) {
+    if (n < 1 || n > 64) {
+      throw new Error(`Invalid bit count: ${n}. Must be between 1 and 64`);
     }
+    let result = 0n;
+    for (let bitsNeeded = n; bitsNeeded > 0; ) {
+      if (this._bitsLeft === 0) {
+        this._bits = this.readU1();
+        this._bitsLeft = 8;
+      }
+      const bitsToRead = Math.min(bitsNeeded, this._bitsLeft);
+      const mask = (1 << bitsToRead) - 1;
+      const shift = this._bitsLeft - bitsToRead;
+      result = result << BigInt(bitsToRead) | BigInt(this._bits >> shift & mask);
+      this._bitsLeft -= bitsToRead;
+      bitsNeeded -= bitsToRead;
+    }
+    return result;
   }
   /**
-   * Set a value in the current object.
-   *
-   * @param name - Field name
-   * @param value - Value to set
-   */
-  set(name, value) {
-    this._current[name] = value;
-  }
-  /**
-   * Get enum value by name.
-   * Used for enum access in expressions (EnumName::value).
-   *
-   * @param enumName - Name of the enum
-   * @param valueName - Name of the enum value
-   * @returns Enum value (number) or undefined
+   * Read specified number of bits as unsigned integer (little-endian)
+   * @param n - Number of bits to read (1-64)
    */
-  getEnumValue(enumName, valueName) {
-    const enumDef = this._enums[enumName];
-    if (!enumDef) {
-      return void 0;
+  readBitsIntLe(n) {
+    if (n < 1 || n > 64) {
+      throw new Error(`Invalid bit count: ${n}. Must be between 1 and 64`);
     }
-    for (const [key, value] of Object.entries(enumDef)) {
-      if (value === valueName) {
-        const numKey = Number(key);
-        return isNaN(numKey) ? key : numKey;
+    let result = 0n;
+    let bitPos = 0;
+    for (let bitsNeeded = n; bitsNeeded > 0; ) {
+      if (this._bitsLeft === 0) {
+        this._bits = this.readU1();
+        this._bitsLeft = 8;
       }
+      const bitsToRead = Math.min(bitsNeeded, this._bitsLeft);
+      const mask = (1 << bitsToRead) - 1;
+      result |= BigInt(this._bits & mask) << BigInt(bitPos);
+      this._bits >>= bitsToRead;
+      this._bitsLeft -= bitsToRead;
+      bitsNeeded -= bitsToRead;
+      bitPos += bitsToRead;
     }
-    return void 0;
-  }
-  /**
-   * Check if an enum exists.
-   *
-   * @param enumName - Name of the enum
-   * @returns True if enum exists
-   */
-  hasEnum(enumName) {
-    return enumName in this._enums;
+    return result;
   }
+  // ==================== Utility Methods ====================
   /**
-   * Create a child context for nested parsing.
-   * The current object becomes the parent in the child context.
-   *
-   * @param stream - Stream for the child context (defaults to current stream)
-   * @returns New child context
+   * Get the underlying buffer
    */
-  createChild(stream) {
-    const childContext = new _Context(
-      stream || this._io,
-      this._root || this._current,
-      this._current,
-      this._enums
-    );
-    return childContext;
+  getBuffer() {
+    return this.buffer;
   }
   /**
-   * Clone this context.
-   * Creates a shallow copy with the same stream, root, and parent.
-   *
-   * @returns Cloned context
+   * Create a substream from current position with specified size
+   * @param size - Size of the substream in bytes
    */
-  clone() {
-    const cloned = new _Context(this._io, this._root, this.parent, this._enums);
-    cloned._current = { ...this._current };
-    cloned.parentStack = [...this.parentStack];
-    return cloned;
+  substream(size) {
+    this.ensureBytes(size);
+    const subBuffer = this.buffer.slice(this._pos, this._pos + size);
+    this._pos += size;
+    return new _KaitaiStream(subBuffer);
   }
 };
 
@@ -1132,6 +1209,17 @@ var Lexer = class {
       }
       return createToken("NUMBER" /* NUMBER */, parseInt(value, 16), start);
     }
+    if (this.current === "0" && this.peek() === "b") {
+      value += this.current;
+      this.advance();
+      value += this.current;
+      this.advance();
+      while (this.current !== null && /[01]/.test(this.current)) {
+        value += this.current;
+        this.advance();
+      }
+      return createToken("NUMBER" /* NUMBER */, parseInt(value, 2), start);
+    }
     while (this.current !== null && this.isDigit(this.current)) {
       value += this.current;
       this.advance();
@@ -1343,6 +1431,9 @@ function createMethodCall(object, method, args) {
 function createEnumAccess(enumName, value) {
   return { kind: "EnumAccess", enumName, value };
 }
+function createArrayLiteral(elements) {
+  return { kind: "ArrayLiteral", elements };
+}
 
 // src/expression/Parser.ts
 var ExpressionParser = class {
@@ -1639,6 +1730,17 @@ var ExpressionParser = class {
       this.expect("RPAREN" /* RPAREN */, "Expected ) after expression");
       return expr;
     }
+    if (this.match("LBRACKET" /* LBRACKET */)) {
+      const elements = [];
+      if (this.current().type !== "RBRACKET" /* RBRACKET */) {
+        elements.push(this.parseTernary());
+        while (this.match("COMMA" /* COMMA */)) {
+          elements.push(this.parseTernary());
+        }
+      }
+      this.expect("RBRACKET" /* RBRACKET */, "Expected ] after array literal");
+      return createArrayLiteral(elements);
+    }
     throw new ParseError(
       `Unexpected token: ${this.current().type}`,
       this.current().position
@@ -1677,6 +1779,8 @@ var Evaluator = class {
         return this.evaluateMethodCall(n.object, n.method, n.args, context);
       case "EnumAccess":
         return this.evaluateEnumAccess(n.enumName, n.value, context);
+      case "ArrayLiteral":
+        return this.evaluateArrayLiteral(n.elements, context);
       default:
         throw new ParseError(`Unknown AST node kind: ${node.kind}`);
     }
@@ -1865,8 +1969,30 @@ var Evaluator = class {
     if (typeof left === "bigint" || typeof right === "bigint") {
       return BigInt(left) === BigInt(right);
     }
+    const toArray = (v) => {
+      if (Array.isArray(v))
+        return v.map((x) => typeof x === "bigint" ? Number(x) : x);
+      if (v instanceof Uint8Array) return Array.from(v);
+      return null;
+    };
+    const leftArr = toArray(left);
+    const rightArr = toArray(right);
+    if (leftArr && rightArr) {
+      if (leftArr.length !== rightArr.length) return false;
+      for (let i = 0; i < leftArr.length; i++) {
+        if (leftArr[i] !== rightArr[i]) return false;
+      }
+      return true;
+    }
     return left === right;
   }
+  /**
+   * Evaluate an array literal.
+   * @private
+   */
+  evaluateArrayLiteral(elements, context) {
+    return elements.map((e) => this.evaluate(e, context));
+  }
   /**
    * Helper: Convert to number.
    * @private
@@ -1901,7 +2027,8 @@ var Evaluator = class {
 
 // src/expression/index.ts
 function evaluateExpression(expression, context) {
-  const lexer = new Lexer(expression);
+  const preprocessed = expression.replace(/\.as<[^>]+>/g, "");
+  const lexer = new Lexer(preprocessed);
   const tokens = lexer.tokenize();
   const parser = new ExpressionParser(tokens);
   const ast = parser.parse();
@@ -1927,6 +2054,18 @@ var TypeInterpreter = class _TypeInterpreter {
       throw new ParseError("Root schema must have meta.id");
     }
   }
+  /**
+   * Safely extract a KaitaiStream from an object that may expose `_io`.
+   * Avoids using `any` casts to satisfy linting.
+   */
+  static getKaitaiIO(val) {
+    if (val && typeof val === "object") {
+      const rec = val;
+      const maybe = rec["_io"];
+      if (maybe instanceof KaitaiStream) return maybe;
+    }
+    return null;
+  }
   /**
    * Parse binary data according to the schema.
    *
@@ -1939,6 +2078,7 @@ var TypeInterpreter = class _TypeInterpreter {
     const result = {};
     const context = new Context(stream, result, parent, this.schema.enums);
     context.current = result;
+    result["_io"] = stream;
     if (typeArgs && this.schema.params) {
       for (let i = 0; i < this.schema.params.length && i < typeArgs.length; i++) {
         const param = this.schema.params[i];
@@ -2041,7 +2181,22 @@ var TypeInterpreter = class _TypeInterpreter {
    * @private
    */
   parseAttribute(attr, context) {
-    const stream = context.io;
+    let stream = context.io;
+    if (attr.io !== void 0) {
+      const ioVal = this.evaluateValue(attr.io, context);
+      if (ioVal instanceof KaitaiStream) {
+        stream = ioVal;
+      } else {
+        const kio = _TypeInterpreter.getKaitaiIO(ioVal);
+        if (kio) {
+          stream = kio;
+        } else {
+          throw new ParseError(
+            "io must evaluate to a KaitaiStream or an object with _io"
+          );
+        }
+      }
+    }
     if (attr.if) {
       const condition = this.evaluateValue(attr.if, context);
       if (!condition) {
@@ -2058,9 +2213,6 @@ var TypeInterpreter = class _TypeInterpreter {
         throw new ParseError(`pos must evaluate to a number, got ${typeof pos}`);
       }
     }
-    if (attr.io) {
-      throw new NotImplementedError("Custom I/O streams");
-    }
     if (attr.repeat) {
       return this.parseRepeated(attr, context);
     }
@@ -2157,7 +2309,7 @@ var TypeInterpreter = class _TypeInterpreter {
       }
       return bytes;
     } else {
-      const encoding = attr.encoding || this.schema.meta.encoding || "UTF-8";
+      const encoding = attr.encoding || this.schema.meta?.encoding || this.parentMeta?.encoding || "UTF-8";
       const str = stream.readStr(expected.length, encoding);
       if (str !== expected) {
         throw new ValidationError(
@@ -2186,7 +2338,7 @@ var TypeInterpreter = class _TypeInterpreter {
         throw new ParseError(`size must be non-negative, got ${size}`);
       }
       if (type === "str" || !type) {
-        const encoding = attr.encoding || this.schema.meta.encoding || "UTF-8";
+        const encoding = attr.encoding || this.schema.meta?.encoding || this.parentMeta?.encoding || "UTF-8";
         let data;
         if (type === "str") {
           data = stream.readBytes(size);
@@ -2212,11 +2364,19 @@ var TypeInterpreter = class _TypeInterpreter {
     }
     if (attr["size-eos"]) {
       if (type === "str") {
-        const encoding = attr.encoding || this.schema.meta.encoding || "UTF-8";
+        const encoding = attr.encoding || this.schema.meta?.encoding || this.parentMeta?.encoding || "UTF-8";
         const bytes = stream.readBytesFull();
         return new TextDecoder(encoding).decode(bytes);
       } else {
-        return stream.readBytesFull();
+        let bytes = stream.readBytesFull();
+        if (attr.process) {
+          bytes = this.applyProcessing(bytes, attr.process);
+        }
+        if (type) {
+          const sub = new KaitaiStream(bytes);
+          return this.parseType(type, sub, context, attr["type-args"]);
+        }
+        return bytes;
       }
     }
     if (!type) {
@@ -2312,6 +2472,12 @@ var TypeInterpreter = class _TypeInterpreter {
     if (isFloatType(type)) {
       return this.readFloat(base, endian, stream);
     }
+    if (/^b\d+$/.test(type)) {
+      const n = parseInt(type.slice(1), 10);
+      const val = stream.readBitsIntBe(n);
+      const maxSafe = BigInt(Number.MAX_SAFE_INTEGER);
+      return val <= maxSafe ? Number(val) : val;
+    }
     if (isStringType(type)) {
       const encoding = this.schema.meta?.encoding || "UTF-8";
       if (type === "strz") {
@@ -2420,16 +2586,6 @@ var TypeInterpreter = class _TypeInterpreter {
   }
 };
 
-// src/index.ts
-function parse(ksyYaml, buffer, options = {}) {
-  const { validate = true, strict = false } = options;
-  const parser = new KsyParser();
-  const schema = parser.parse(ksyYaml, { validate, strict });
-  const stream = new KaitaiStream(buffer);
-  const interpreter = new TypeInterpreter(schema);
-  return interpreter.parse(stream);
-}
-
 // src/cli.ts
 function getVersion() {
   try {
@@ -2551,6 +2707,43 @@ function readFile(filePath, description) {
     process.exit(1);
   }
 }
+function loadImports(ksyPath, ksyContent, quiet) {
+  const imports = /* @__PURE__ */ new Map();
+  try {
+    const schema = (0, import_yaml2.parse)(ksyContent);
+    if (!schema.meta?.imports || schema.meta.imports.length === 0) {
+      return imports;
+    }
+    const ksyDir = (0, import_path.dirname)((0, import_path.resolve)(ksyPath));
+    for (const importPath of schema.meta.imports) {
+      const normalizedPath = importPath.startsWith("/") ? importPath.slice(1) : importPath;
+      const importFilePath = (0, import_path.resolve)(ksyDir, "..", normalizedPath + ".ksy");
+      if (!(0, import_fs.existsSync)(importFilePath)) {
+        console.error(
+          `Error: Import file not found: ${importFilePath} (from import: ${importPath})`
+        );
+        process.exit(1);
+      }
+      if (!quiet) {
+        console.error(`  Loading import: ${importPath} -> ${importFilePath}`);
+      }
+      const importContent = (0, import_fs.readFileSync)(importFilePath, "utf-8");
+      imports.set(importPath, importContent);
+      const nestedImports = loadImports(importFilePath, importContent, quiet);
+      for (const [nestedPath, nestedContent] of nestedImports) {
+        if (!imports.has(nestedPath)) {
+          imports.set(nestedPath, nestedContent);
+        }
+      }
+    }
+  } catch (error) {
+    console.error(
+      `Error loading imports: ${error instanceof Error ? error.message : String(error)}`
+    );
+    process.exit(1);
+  }
+  return imports;
+}
 function extractField(obj, path) {
   const parts = path.split(".");
   let current = obj;
@@ -2608,16 +2801,30 @@ function main() {
   }
   const ksyContent = readFile(ksyFile, "KSY definition file").toString("utf-8");
   const binaryData = readFile(binaryFile, "Binary file");
+  if (!options.quiet) {
+    console.error("Detecting imports...");
+  }
+  const imports = loadImports(ksyFile, ksyContent, options.quiet || false);
+  if (!options.quiet && imports.size > 0) {
+    console.error(`Loaded ${imports.size} import(s)`);
+  }
   const parseOptions = {
     validate: options.validate,
     strict: options.strict
   };
   if (!options.quiet) {
-    console.error("Parsing...");
+    console.error("Parsing schema...");
   }
   let result;
   try {
-    result = parse(ksyContent, binaryData, parseOptions);
+    const parser = new KsyParser();
+    const schema = imports.size > 0 ? parser.parseWithImports(ksyContent, imports, parseOptions) : parser.parse(ksyContent, parseOptions);
+    if (!options.quiet) {
+      console.error("Parsing binary data...");
+    }
+    const stream = new KaitaiStream(binaryData);
+    const interpreter = new TypeInterpreter(schema);
+    result = interpreter.parse(stream);
   } catch (error) {
     console.error(
       `Parse error: ${error instanceof Error ? error.message : String(error)}`
@@ -2664,50 +2871,50 @@ function main() {
 }
 main();
 /**
- * @fileoverview Custom error classes for Kaitai Struct parsing and validation
- * @module utils/errors
+ * @fileoverview Type definitions for Kaitai Struct YAML schema (.ksy files)
+ * @module parser/schema
  * @author Fabiano Pinto
  * @license MIT
  */
 /**
- * @fileoverview String encoding and decoding utilities for binary data
- * @module utils/encoding
+ * @fileoverview Custom error classes for Kaitai Struct parsing and validation
+ * @module utils/errors
  * @author Fabiano Pinto
  * @license MIT
  */
 /**
- * @fileoverview Binary stream reader for Kaitai Struct
- * @module stream/KaitaiStream
+ * @fileoverview Parser for Kaitai Struct YAML (.ksy) files
+ * @module parser/KsyParser
  * @author Fabiano Pinto
  * @license MIT
  */
 /**
- * @fileoverview Binary stream reading functionality
- * @module stream
+ * @fileoverview Parser module for Kaitai Struct YAML files
+ * @module parser
  * @author Fabiano Pinto
  * @license MIT
  */
 /**
- * @fileoverview Type definitions for Kaitai Struct YAML schema (.ksy files)
- * @module parser/schema
+ * @fileoverview Execution context for Kaitai Struct parsing
+ * @module interpreter/Context
  * @author Fabiano Pinto
  * @license MIT
  */
 /**
- * @fileoverview Parser for Kaitai Struct YAML (.ksy) files
- * @module parser/KsyParser
+ * @fileoverview String encoding and decoding utilities for binary data
+ * @module utils/encoding
  * @author Fabiano Pinto
  * @license MIT
  */
 /**
- * @fileoverview Parser module for Kaitai Struct YAML files
- * @module parser
+ * @fileoverview Binary stream reader for Kaitai Struct
+ * @module stream/KaitaiStream
  * @author Fabiano Pinto
  * @license MIT
  */
 /**
- * @fileoverview Execution context for Kaitai Struct parsing
- * @module interpreter/Context
+ * @fileoverview Binary stream reading functionality
+ * @module stream
  * @author Fabiano Pinto
  * @license MIT
  */
@@ -2759,37 +2966,6 @@ main();
  * @author Fabiano Pinto
  * @license MIT
  */
-/**
- * @fileoverview Main entry point for kaitai-struct-ts library
- * @module kaitai-struct-ts
- * @author Fabiano Pinto
- * @license MIT
- * @version 0.2.0
- *
- * @description
- * A runtime interpreter for Kaitai Struct binary format definitions in TypeScript.
- * Parse any binary data format by providing a .ksy (Kaitai Struct YAML) definition file.
- *
- * @example
- * ```typescript
- * import { parse } from 'kaitai-struct-ts'
- *
- * const ksyDefinition = `
- * meta:
- *   id: my_format
- *   endian: le
- * seq:
- *   - id: magic
- *     contents: [0x4D, 0x5A]
- *   - id: version
- *     type: u2
- * `
- *
- * const buffer = new Uint8Array([0x4D, 0x5A, 0x01, 0x00])
- * const result = parse(ksyDefinition, buffer)
- * console.log(result.version) // 1
- * ```
- */
 /**
  * @fileoverview CLI utility for parsing binary files with Kaitai Struct definitions
  * @module kaitai-struct-ts/cli