@gaialabs/core 0.1.18 → 0.2.0

package/dist/index.d.mts

@@ -1,72 +1,4 @@
-import { ICompressionProvider, BinType, DbPath, StatusFlags, DbRoot, AddressType, DbStringType, StringWrapper, Op, OpCode, ChunkFile, AsmBlock, Address, CopDef, DbEntryPoint } from '@gaialabs/shared';
-
-/**
- * QuintetLZ compression algorithm implementation
- * Dictionary-based compression used in Quintet games
- */
-declare class QuintetLZ implements ICompressionProvider {
-    static readonly DICTIONARY_SIZE = 256;
-    static readonly DICTIONARY_INIT = 32;
-    static readonly DICTIONARY_OFFSET = 239;
-    private static readonly DEFAULT_PAGE_SIZE;
-    /**
-     * Expand (decompress) data using QuintetLZ algorithm
-     * @param srcData Source data buffer
-     * @param srcPosition Starting position in source data
-     * @param srcLen Length of source data to process
-     * @returns Expanded data
-     */
-    expand(srcData: Uint8Array, srcPosition?: number, srcLen?: number): Uint8Array;
-    /**
-     * Compact (compress) data using QuintetLZ algorithm
-     * @param srcData Source data to compress
-     * @returns Compressed data
-     */
-    compact(srcData: Uint8Array): Uint8Array;
-}
-
-/**
- * Register compression providers with the global registry
- */
-declare function registerCompressionProviders(): void;
-
-/**
- * Main project management class
- * Converted from GaiaLib/ProjectRoot.cs
- */
-interface ProjectConfig {
-    name: string;
-    romPath: string;
-    baseDir: string;
-    system?: string;
-    database: string;
-    flipsPath?: string;
-    resources: Record<BinType, DbPath>;
-    databasePath?: string;
-    systemPath?: string;
-    compression?: string;
-}
-/**
- * Project root management
- */
-declare class ProjectRoot {
-    config: ProjectConfig;
-    name: string;
-    romPath: string;
-    baseDir: string;
-    system?: string;
-    database: string;
-    flipsPath?: string;
-    resources: Record<BinType, DbPath>;
-    databasePath?: string;
-    systemPath?: string;
-    compression?: string;
-    constructor(config: ProjectConfig);
-    /**
-     * Load project from file or directory
-     */
-    static load(path?: string): Promise<ProjectRoot>;
-}
+import { SupabaseClient } from '@supabase/supabase-js';
 
 /**
  * Lightweight ROM state placeholder used during early development.
@@ -124,51 +56,30 @@ declare class Stack {
  * Manages the 65816 processor registers and status flags
  */
 declare class Registers {
-    accumulatorFlag?: boolean;
-    indexFlag?: boolean;
-    direct?: number;
-    dataBank?: number;
-    accumulator?: number;
-    xIndex?: number;
-    yIndex?: number;
+    value: Record<string, number>;
     stack: Stack;
     constructor();
-    /**
-     * Get the current status flags
-     */
-    get statusFlags(): StatusFlags;
-    /**
-     * Set the status flags
-     */
-    set statusFlags(value: StatusFlags);
-    /**
-     * Reset all registers to initial state
-     */
-    reset(): void;
 }
 
+declare class MapExt<K, V> extends Map<K, V> {
+    constructor();
+    tryAdd(key: K, value: V): boolean;
+    setFlag(key: K, flag: number, value?: boolean): void;
+    clearFlag(key: K, flag: number): void;
+}
 /**
  * Manages CPU processor state during ROM analysis
  * Converted from GaiaLib/Rom/Extraction/ProcessorStateManager.cs
  */
 declare class ProcessorStateManager {
-    readonly accumulatorFlags: Map<number, boolean | null>;
-    readonly indexFlags: Map<number, boolean | null>;
-    readonly bankNotes: Map<number, number | null>;
-    readonly stackPositions: Map<number, number>;
+    readonly stackPositions: MapExt<number, number>;
+    private readonly _buckets;
+    get(key: string): MapExt<number, number>;
     /**
      * Hydrate processor registers with stored state
      * Uses Registers from gaia-core/assembly for processor state management
      */
     hydrateRegisters(position: number, reg: Registers): void;
-    getAccumulatorFlag(location: number): boolean | null | undefined;
-    setAccumulatorFlag(location: number, value: boolean | null): void;
-    tryAddAccumulatorFlag(location: number, value: boolean | null): boolean;
-    getIndexFlag(location: number): boolean | null | undefined;
-    setIndexFlag(location: number, value: boolean | null): void;
-    tryAddIndexFlag(location: number, value: boolean | null): boolean;
-    getBankNote(location: number): number | null | undefined;
-    setBankNote(location: number, value: number | null): void;
     getStackPosition(location: number): number | undefined;
     setStackPosition(location: number, value: number): void;
     tryAddStackPosition(location: number, value: number): boolean;
@@ -193,6 +104,854 @@ declare class RomDataReader {
     peekAddress(): number;
 }
 
+/**
+ * Address type classifications
+ * Converted from GaiaLib/Enum/AddressType.cs
+ */
+declare enum AddressType {
+    Unknown = "Unknown",
+    Bank = "Bank",
+    Offset = "Offset",
+    Address = "Address",
+    WBank = "WBank",
+    Relative = "Relative"
+}
+/**
+ * Address space types
+ * Converted from GaiaLib/Types/Address.cs
+ */
+declare enum AddressSpace {
+    None = "None",
+    ROM = "ROM",
+    WRAM = "WRAM",
+    SRAM = "SRAM",
+    System = "System"
+}
+/**
+ * SNES address structure
+ * Converted from GaiaLib/Types/Address.cs
+ */
+declare class Address {
+    offset: number;
+    bank: number;
+    static readonly UPPER_BANK = 32768;
+    static readonly DATA_BANK_FLAG = 64;
+    static readonly FAST_BANK_FLAG = 128;
+    constructor(bank: number, offset: number);
+    get isROM(): boolean;
+    get isCodeBank(): boolean;
+    get space(): AddressSpace;
+    toInt(): number;
+    toString(): string;
+    static fromInt(addr: number): Address;
+    static typeFromCode(code: string): AddressType;
+    static codeFromType(type: AddressType): string | null;
+}
+
+/**
+ * Member type definitions for data structures
+ * Converted from GaiaLib/Enum/MemberType.cs
+ */
+declare enum MemberType {
+    Byte = "Byte",
+    Word = "Word",
+    Offset = "Offset",
+    Address = "Address",
+    Binary = "Binary",
+    Code = "Code"
+}
+
+/**
+ * Processor register type definitions
+ * Converted from GaiaLib/Enum/RegisterType.cs
+ */
+declare enum RegisterType {
+    M = "M",
+    X = "X",
+    B = "B"
+}
+/**
+ * Status flags for 65816 processor
+ * Converted from GaiaLib/Enum/StatusFlags.cs
+ *
+ * Bit pattern: [ n v m x d i z c ]
+ * n = Negative
+ * v = Overflow
+ * m = Accumulator Mode
+ * x = Index Mode
+ * d = Decimal Mode
+ * i = IRQ Disable
+ * z = Zero
+ * c = Carry
+ */
+declare enum StatusFlags {
+    /**
+     * Clear before starting addition or subtraction.
+     * Arithmetic overflow:
+     * [addition - carry out of high bit:]
+     * 0 = no carry
+     * 1 = carry
+     * [subtraction - borrow required to subtract:]
+     * 0 = borrow required
+     * 1 = no borrow required
+     * [Logic:]
+     * receives bit shifted or rotated out;
+     * source of bit rotated in
+     */
+    Carry = 1,
+    /**
+     * Indicates zero or non-zero result:
+     * 0 = non-zero result
+     * 1 = zero result
+     */
+    Zero = 2,
+    /**
+     * Enables or disables processor's IRQ interrupt line:
+     * Set to disable interrupts by masking the IRQ line
+     * Clear to enable IRQ interrupts
+     */
+    IrqDisable = 4,
+    /**
+     * Determines mode for add/subtract (not increment/decrement, though):
+     * Set to force decimal operation (BCD)
+     * Clear to return to binary operation
+     */
+    DecimalMode = 8,
+    IndexMode = 16,
+    AccumulatorMode = 32,
+    /**
+     * Clear to reverse "set-overflow" hardware input.
+     * Indicates invalid carry into high bit of arithmetic
+     * result (two's-complement overflow):
+     * 0 = two's-complement result ok
+     * 1 = error if two's-complement arithmetic
+     */
+    Overflow = 64,
+    /**
+     * Reflects most significant bit of result
+     * (the sign of a two's-complement binary number):
+     * 0 = high bit clear (positive result)
+     * 1 = high bit set (negative result)
+     */
+    Negative = 128
+}
+
+/**
+ * Binary resource type definitions
+ * Converted from GaiaLib/Enum/BinType.cs
+ */
+declare enum BinType {
+    Bitmap = "Bitmap",
+    Tilemap = "Tilemap",
+    Tileset = "Tileset",
+    Palette = "Palette",
+    Sound = "Sound",
+    Music = "Music",
+    Unknown = "Unknown",
+    Meta17 = "Meta17",
+    Spritemap = "Spritemap",
+    Assembly = "Assembly",
+    Patch = "Patch",
+    Transform = "Transform"
+}
+
+/**
+ * Transform type definitions
+ * Converted from GaiaLib/Enum/XformType.cs
+ */
+declare enum XformType {
+    Lookup = "Lookup",
+    Replace = "Replace"
+}
+/**
+ * Transform definition
+ * Converted from GaiaLib/Types/XformDef.cs
+ */
+interface XformDef {
+    type: XformType;
+    key?: string;
+    value?: string;
+    keyIx?: number;
+    valueIx?: number;
+}
+
+declare class DbFile {
+    name: string;
+    type: string;
+    start: number;
+    end: number;
+    compressed?: boolean;
+    upper?: boolean;
+    group?: string;
+    scene?: string;
+    constructor(data: Partial<DbFile>);
+}
+declare class DbFileType {
+    name: string;
+    extension: string;
+    type: string;
+    isPatch: boolean;
+    isBlock: boolean;
+    header: number;
+    constructor(data: Partial<DbFileType>);
+}
+
+/**
+ * Database part definition
+ * Converted from GaiaLib/Database/DbPart.cs
+ */
+declare class DbPart {
+    name: string;
+    start: number;
+    end: number;
+    type: string;
+    bank?: number;
+    order?: number;
+    constructor(data: Partial<DbPart>);
+}
+
+declare class DbTransform {
+    key: string;
+    value: string;
+    constructor(data: Partial<DbTransform>);
+}
+
+/**
+ * Database block definition
+ * Converted from GaiaLib/Database/DbBlock.cs
+ */
+declare class DbBlock {
+    name: string;
+    movable: boolean;
+    group?: string;
+    scene?: string;
+    parts: DbPart[];
+    transforms?: DbTransform[];
+    postProcess?: string;
+    constructor(data: Partial<DbBlock>);
+}
+
+/**
+ * Interface for compression providers
+ */
+interface ICompressionProvider {
+    /**
+     * Expand (decompress) data
+     * @param srcData Source data buffer
+     * @param srcPosition Starting position in source data
+     * @param srcLen Length of source data to process
+     * @returns Expanded data
+     */
+    expand(srcData: Uint8Array, srcPosition?: number, srcLen?: number): Uint8Array;
+    /**
+     * Compact (compress) data
+     * @param srcData Source data to compress
+     * @returns Compressed data
+     */
+    compact(srcData: Uint8Array): Uint8Array;
+}
+
+/**
+ * Chunk file for ROM processing
+ * Converted from GaiaLib/Types/ChunkFile.cs
+ */
+declare class ChunkFile {
+    name: string;
+    size: number;
+    location: number;
+    type: DbFileType;
+    parts?: AsmBlock[];
+    includes?: Set<string>;
+    includeLookup?: Map<string, AsmBlock>;
+    bank?: number;
+    compressed?: boolean;
+    upper?: boolean;
+    rawData?: Uint8Array | null;
+    textData?: string;
+    transforms?: {
+        key: string;
+        value: string;
+    }[];
+    postProcess?: string;
+    mnemonics: Record<number, string>;
+    group?: string;
+    scene?: string;
+    constructor(name: string, size: number, location: number, type: DbFileType);
+}
+declare function createChunkFileFromDbFile(rom: Uint8Array, compression: ICompressionProvider, dbFile: DbFile, fileType: DbFileType): ChunkFile;
+declare function createChunkFileFromDbBlock(block: DbBlock, fileType: DbFileType): ChunkFile;
+/**
+ * Chunk file utilities
+ */
+declare class ChunkFileUtils {
+    /**
+     * Rebase blocks to a new location
+     */
+    static rebase(chunkFile: ChunkFile, newLocation?: number): void;
+    /**
+     * Calculate the total size of all blocks
+     */
+    static calculateSize(chunkFile: ChunkFile): number;
+    /**
+   * Check if a location is outside this block and return the part (matches C# IsOutside)
+   * Returns [isOutside, part] where part is the part containing the location
+   */
+    static isOutsideWithPart(root: ChunkFile[], block: ChunkFile, location: number): [boolean, ChunkFile | null, AsmBlock | null];
+    /**
+     * Check if a location is inside this block and return the part (matches C# IsInside)
+     * Returns [isInside, part] where part is the part containing the location
+     */
+    static isInsideWithPart(block: ChunkFile, location: number): [boolean, AsmBlock | null];
+    /**
+     * Check if a location is outside this block (shorthand version)
+     */
+    static isOutside(block: ChunkFile, location: number): boolean;
+    /**
+     * Check if a location is inside this block (shorthand version)
+     */
+    static isInside(block: ChunkFile, location: number): boolean;
+    /**
+     * Get all included blocks
+     */
+    static getIncludes(chunkFile: ChunkFile): ChunkFile[];
+}
+
+/**
+ * COP instruction definition
+ * Converted from GaiaLib/Database/CopDef.cs
+ */
+declare class CopDef {
+    id: number;
+    name: string;
+    size: number;
+    parts: string[];
+    halt: boolean;
+    constructor(data: Partial<CopDef>);
+}
+
+declare class OpCode {
+    code: number;
+    mnem: string;
+    mode: string;
+    constructor(code: number, mnem: string, mode: string);
+}
+
+/**
+ * Represents a single assembly operation/instruction
+ */
+declare class Op extends OpCode {
+    location: number;
+    operands: unknown[];
+    size: number;
+    copDef?: CopDef;
+    constructor(code: OpCode, location?: number, operands?: unknown[], size?: number);
+}
+/**
+ * Represents a block of assembly code or data
+ */
+declare class AsmBlock {
+    label?: string;
+    location: number;
+    size: number;
+    isString: boolean;
+    objList: any[];
+    structName?: string;
+    bank?: number;
+    includes?: Set<{
+        block: ChunkFile;
+        part: AsmBlock;
+    }>;
+    constructor(location?: number, size?: number, isString?: boolean, label?: string, structName?: string, bank?: number);
+}
+/**
+ * Database part utilities
+ */
+declare class AsmBlockUtils {
+    /**
+     * Check if a location is inside this part
+     */
+    static isInside(part: AsmBlock, location: number): boolean;
+    /**
+     * Check if a location is outside this part
+     */
+    static isOutside(part: AsmBlock, location: number): boolean;
+}
+
+/**
+ * Bit stream for reading/writing binary data at bit level
+ * Converted from GaiaLib/Types/BitStream.cs
+ */
+declare class BitStream {
+    private static readonly NIBBLE_MASK;
+    private static readonly NIBBLE_PERFECT_POSITION;
+    private data;
+    private position;
+    private bitFlag;
+    private writeSample;
+    constructor(data: Uint8Array, position?: number);
+    get dataArray(): Uint8Array;
+    get currentPosition(): number;
+    set currentPosition(value: number);
+    /**
+     * Read a byte from the stream
+     * @returns The byte read, or -1 if the end of the data has been reached
+     */
+    readByte(): number;
+    /**
+     * Read a ushort from the stream (ignores the current bit flag)
+     * @returns The short read, or -1 if the end of the data has been reached
+     */
+    readShort(): number;
+    /**
+     * Read a bit from the stream
+     * @returns True if the current bit at bitFlag is set, false otherwise
+     */
+    readBit(): boolean;
+    /**
+     * Read a nibble from the stream
+     * @returns The nibble read, or -1 if the end of the data has been reached
+     */
+    readNibble(): number;
+    /**
+     * Write a bit to the stream
+     * @param set True if the current bit should be set, false otherwise
+     */
+    writeBit(set: boolean): void;
+    /**
+     * Write a byte to the stream
+     * @param value The byte to write
+     */
+    writeByte(value: number): void;
+    /**
+     * Write a nibble to the stream
+     * @param value The nibble to write
+     */
+    writeNibble(value: number): void;
+    flush(): void;
+}
+
+/**
+ * Registry for compression providers
+ * Allows registration of compression implementations by string ID
+ */
+declare class CompressionRegistry {
+    private static providers;
+    /**
+     * Register a compression provider
+     * @param id String identifier for the compression type
+     * @param factory Factory function that creates the compression provider
+     */
+    static register(id: string, factory: () => ICompressionProvider): void;
+    /**
+     * Get a compression provider by ID
+     * @param id String identifier for the compression type
+     * @returns Compression provider instance
+     */
+    static get(id: string): ICompressionProvider;
+    /**
+     * Check if a compression provider is registered
+     * @param id String identifier for the compression type
+     * @returns True if provider is registered
+     */
+    static has(id: string): boolean;
+    /**
+     * Get list of registered provider IDs
+     * @returns Array of registered provider IDs
+     */
+    static getRegisteredIds(): string[];
+    /**
+     * Clear all registered providers (mainly for testing)
+     */
+    static clear(): void;
+}
+
+/**
+ * ROM processing constants
+ * Converted from GaiaLib/Types/RomProcessingConstants.cs
+ */
+declare class RomProcessingConstants {
+    static readonly PAGE_SIZE = 32768;
+    static readonly SNES_HEADER_SIZE = 80;
+    static readonly DICTIONARIES: string[];
+    static readonly DICT_COMMANDS: number[];
+    static readonly END_CHARS: number[];
+    static readonly WHITESPACE: string[];
+    static readonly OPERATORS: string[];
+    static readonly COMMA_SPACE: string[];
+    static readonly ADDRESS_SPACE: string[];
+    static readonly SYMBOL_SPACE: string[];
+    static readonly LABEL_SPACE: string[];
+    static readonly OBJECT_SPACE: string[];
+    static readonly COP_SPLIT_CHARS: string[];
+    static readonly WHITESPACE_REGEX: RegExp;
+    static readonly COMMA_SPACE_REGEX: RegExp;
+    static readonly SYMBOL_SPACE_REGEX: RegExp;
+    static readonly LABEL_SPACE_REGEX: RegExp;
+    static readonly OBJECT_SPACE_REGEX: RegExp;
+    static readonly ADDRESS_SPACE_REGEX: RegExp;
+    static readonly COP_SPLIT_REGEX: RegExp;
+    static readonly COMMA_SPACE_TRIM_REGEX: RegExp;
+    /**
+     * Gets the size of an object for processing purposes
+     * @param obj The object to get the size for
+     * @returns Size in bytes
+     * @throws Error when unable to determine size
+     */
+    static getSize(obj: unknown): number;
+}
+/**
+ * BlockReader specific constants
+ */
+declare class BlockReaderConstants {
+    static readonly REF_SEARCH_MAX_RANGE = 416;
+    static readonly BANK_MASK_CHECK = 64;
+    static readonly BYTE_DELIMITER_THRESHOLD = 256;
+    static readonly BANK_HIGH_MEMORY_1 = 126;
+    static readonly BANK_HIGH_MEMORY_2 = 127;
+    static readonly POINTER_CHARACTERS: string[];
+    static readonly WIDE_STRING_TYPE = "WideString";
+    static readonly BINARY_TYPE = "Binary";
+    static readonly CODE_TYPE = "Code";
+    static readonly LOCATION_FORMAT = "loc_{0:X6}";
+    static readonly TYPE_NAME_FORMAT = "{0}_{1:X6}";
+    static readonly OFFSET_FORMAT = "+{0:X}";
+    static readonly MARKER_FORMAT = "+M";
+    static readonly NEGATIVE_OFFSET_FORMAT = "-{0:X}";
+    static readonly NEGATIVE_MARKER_FORMAT = "-M";
+}
+
+/**
+ * Location wrapper for additional metadata
+ * Converted from GaiaLib/Types/LocationWrapper.cs
+ */
+declare class LocationWrapper {
+    location: number;
+    type: AddressType;
+    constructor(location: number, type: AddressType);
+}
+
+/**
+ * Database string command definition
+ * Converted from GaiaLib/Database/DbStringCommand.cs
+ */
+declare class DbStringCommand {
+    id: number;
+    name: string;
+    types: MemberType[];
+    delimiter?: number;
+    halt: boolean;
+    constructor(data: Partial<DbStringCommand>);
+}
+/**
+ * Database string layer definition
+ * Converted from GaiaLib/Database/DbStringLayer.cs
+ */
+interface DbStringLayer {
+    base: number;
+    map: string[];
+}
+/**
+ * Database string type definition
+ * Converted from GaiaLib/Database/DbStringType.cs
+ */
+declare class DbStringType {
+    name: string;
+    delimiter: string;
+    terminator: number;
+    shiftType?: string;
+    characterMap: string[];
+    commands: Record<string, DbStringCommand>;
+    commandLookup: Record<number, DbStringCommand>;
+    layers: DbStringLayer[];
+    greedyTerminator: boolean;
+    constructor(data: Partial<DbStringType>);
+}
+/**
+ * String type utilities
+ */
+declare class DbStringTypeUtils {
+    private static readonly shiftDownFunctions;
+    private static readonly shiftUpFunctions;
+    static getShiftDown(shiftType?: string): (x: number) => number;
+    static getShiftUp(shiftType?: string): (x: number) => number;
+}
+
+/**
+ * String marker for positioning
+ * Converted from GaiaLib/Types/StringMarker.cs
+ */
+interface StringMarker {
+    offset: number;
+}
+/**
+ * String wrapper with type and location information
+ * Converted from GaiaLib/Types/StringWrapper.cs
+ */
+interface StringWrapper {
+    string: string;
+    type: DbStringType;
+    marker: number;
+    location: number;
+}
+/**
+ * String entry (commented out in original C# code)
+ * Converted from GaiaLib/Types/StringEntry.cs
+ */
+interface StringEntry {
+    block: AsmBlock;
+    index: number;
+    size: number;
+    data: Uint8Array;
+}
+/**
+ * String size comparer utility
+ * Converted from GaiaLib/Types/StringSizeComparer.cs
+ */
+declare class StringSizeComparer {
+    /**
+     * Compare two strings by length
+     */
+    static compare(a: string, b: string): number;
+    /**
+     * Compare two StringWrapper objects by string length
+     */
+    static compareWrappers(a: StringWrapper, b: StringWrapper): number;
+}
+
+/**
+ * Structure definition
+ * Converted from GaiaLib/Types/StructDef.cs
+ */
+interface StructDef {
+    name: string;
+    parts: unknown[];
+}
+
+/**
+ * Table entry definition
+ * Converted from GaiaLib/Types/TableEntry.cs
+ */
+interface TableEntry {
+    location: number;
+    object: unknown;
+}
+/**
+ * Creates a new TableEntry
+ */
+declare function createTableEntry(location: number, object?: unknown): TableEntry;
+
+declare class TypedNumber {
+    value: number;
+    size: number;
+    constructor(value: number, size: number);
+}
+declare class Byte extends TypedNumber {
+    constructor(value: number);
+}
+declare class Word extends TypedNumber {
+    constructor(value: number);
+}
+declare class Long extends TypedNumber {
+    constructor(value: number);
+}
+
+/**
+ * Database entry point definition
+ * Converted from GaiaLib/Database/DbEntryPoint.cs
+ */
+interface DbEntryPoint {
+    location: number;
+    name: string;
+}
+
+/**
+ * Database path configuration
+ * Converted from GaiaLib/Database/DbPath.cs
+ */
+interface DbPath {
+    folder: string;
+    extension: string;
+}
+/**
+ * Creates a default DbPath
+ */
+declare function createDbPath(folder?: string, extension?: string): DbPath;
+
+/**
+ * Database configuration
+ * Converted from GaiaLib/Database/DbConfig.cs
+ */
+interface DbConfig {
+    sfxLocation: number;
+    sfxCount: number;
+    compression: string;
+    entryPoints: DbEntryPoint[];
+    paths: Record<BinType, DbPath>;
+}
+
+/**
+ * Database structure definition
+ * Converted from GaiaLib/Database/DbStruct.cs
+ */
+declare class DbStruct {
+    name: string;
+    types?: string[];
+    parent?: string;
+    delimiter?: number;
+    discriminator?: number;
+    constructor(data: Partial<DbStruct>);
+}
+
+declare class DbAddressingMode {
+    name: string;
+    shorthand: string;
+    operands: string[];
+    size: number;
+    formatString?: string;
+    parseRegex?: string;
+    instructions: Record<string, number>;
+    constructor(data: Partial<DbAddressingMode>);
+}
+
+interface DbAsset {
+    index: number;
+    type: string;
+    file: string;
+    scene: string;
+    meta: any;
+}
+
+declare class DbScene {
+    name: string;
+    id: number;
+    description?: string;
+    assets: DbAsset[];
+    constructor(data: Partial<DbScene>);
+}
+
+declare class DbGroup {
+    name: string;
+    prefix: string;
+    description?: string;
+    scenes: Record<string, DbScene>;
+    constructor(data: Partial<DbGroup>);
+}
+
+interface DbGameRomModule {
+    mnemonics: Record<number, string>;
+    overrides: Record<number, Record<string, number>>;
+    rewrites: Record<string, number>;
+    blocks: Record<string, Record<string, Partial<DbBlock>>>;
+    files: Record<string, Record<string, Record<string, Partial<DbFile>>>>;
+    config: DbConfig;
+    labels: DbLabel[];
+    structs: Record<string, DbStruct>;
+    copdef: Record<string, Partial<CopDef>>;
+    strings: Record<string, Partial<DbStringType>>;
+    transforms: Record<string, Partial<DbTransform>[]>;
+    addrModes: Record<string, Partial<DbAddressingMode>>;
+    groups: Record<string, Partial<DbGroup>>;
+    fileTypes: Record<string, Partial<DbFileType>>;
+}
+interface DbBaseRomModule extends DbGameRomModule {
+    baseRomFiles: ChunkFile[];
+}
+
+/**
+ * Main database root class
+ * Converted from GaiaLib/Database/DbRoot.cs
+ */
+interface DbRoot {
+    copDef: Record<number, CopDef>;
+    copLookup: Record<string, CopDef>;
+    mnemonics: Record<number, string>;
+    structs: Record<string, DbStruct>;
+    stringTypes: Record<string, DbStringType>;
+    stringDelimiters: string[];
+    files: DbFile[];
+    config: DbConfig;
+    blocks: DbBlock[];
+    overrides: Record<number, Record<string, number>>;
+    labels: Record<number, string>;
+    rewrites: Record<number, number>;
+    entryPoints: DbEntryPoint[];
+    opCodes: Record<number, OpCode>;
+    opLookup: Record<string, OpCode[]>;
+    addrLookup: Record<string, DbAddressingMode>;
+    compression: ICompressionProvider;
+    baseRomFiles?: ChunkFile[];
+    projectFiles?: ChunkFile[];
+    groups: Record<string, DbGroup>;
+    scenes: Record<number, DbScene>;
+    fileTypes: Record<string, DbFileType>;
+    fileExtLookup: Record<string, DbFileType>;
+}
+/**
+ * Database root utilities
+ */
+declare class DbRootUtils {
+    /**
+     * JSON serialization options
+     */
+    /**
+     * Load database from a single file
+     */
+    static fromFolder(folderPath: string, systemPath: string): Promise<DbRoot>;
+    /**
+     * Load database from folder structure
+     */
+    static gameModuleFromFolder(folderPath: string, systemPath: string): Promise<DbGameRomModule>;
+    static fromGameModule(module: DbGameRomModule): DbRoot;
+    static applyFolder(root: DbRoot, folderPath: string, sourceFiles?: ChunkFile[]): Promise<ChunkFile[]>;
+    static extractAllContent(root: DbRoot, romPath: string, outPath: string): Promise<void>;
+    static rebuildAllContent(root: DbRoot, inPath: string[], outPath: string): Promise<void>;
+}
+
+/**
+ * Database label definition
+ * Converted from GaiaLib/Database/DbLabel.cs
+ */
+interface DbLabel {
+    location: number;
+    label: string;
+}
+
+/**
+ * Database mnemonic definition
+ * Converted from GaiaLib/Database/DbMnemonic.cs
+ */
+interface DbMnemonic {
+    key: number;
+    value: string;
+    metadata?: string;
+}
+
+declare class DbOverride {
+    location: number;
+    register: string;
+    value: number;
+    constructor(values: Partial<DbOverride>);
+}
+
+/**
+ * Database rewrite rule definition
+ * Converted from GaiaLib/Database/DbRewrite.cs
+ */
+interface DbRewrite {
+    location: number;
+    value: number;
+}
+
+/**
+ * Database sound effect definition
+ * Converted from GaiaLib/Database/DbSfx.cs
+ */
+interface DbSfx {
+    location: number;
+    size: number;
+    names: string[];
+}
+
 /**
  * Manages references, chunks, and markers during ROM analysis
  * Converted from GaiaLib/Rom/Extraction/ReferenceManager.cs
@@ -257,12 +1016,11 @@ declare class StringReader {
  * Converted from GaiaLib/Rom/Extraction/AsmReader.cs
  */
 declare class AsmReader {
-    private static readonly PROCESSOR_FLAG_MASK;
+    private static readonly STATUS_OP_MASK;
+    private static readonly STATUS_OP_VALUE;
     private static readonly ACCUMULATOR_OP_MASK;
     private static readonly ACCUMULATOR_OP_VALUE;
     static readonly VARIABLE_SIZE_INDICATOR = -2;
-    private static readonly TWO_BYTES_SIZE;
-    private static readonly THREE_BYTES_SIZE;
     private readonly _blockReader;
     private readonly _transformProcessor;
     private readonly _addressingModeHandler;
@@ -312,13 +1070,6 @@ declare class BlockReader {
     readonly _romDataReader: RomDataReader;
     readonly _stateManager: ProcessorStateManager;
     readonly _referenceManager: ReferenceManager;
-    get AccumulatorFlags(): Map<number, boolean | null>;
-    get IndexFlags(): Map<number, boolean | null>;
-    get BankNotes(): Map<number, number | null>;
-    get StackPosition(): Map<number, number>;
-    get _structTable(): Map<number, string>;
-    get _markerTable(): Map<number, number>;
-    get _nameTable(): Map<number, string>;
     _partEnd: number;
     _currentChunk: ChunkFile | null;
     _currentAsmBlock: AsmBlock | null;
@@ -348,7 +1099,7 @@ declare class BlockReader {
      * Notes a type at a location and manages chunk references
      */
     noteType(loc: number, type: string, silent?: boolean, reg?: Registers): string;
-    private updateRegisterState;
+    updateRegisterState(loc: number, reg: Registers): void;
     /**
      * Checks if a delimiter has been reached
      */
@@ -470,7 +1221,6 @@ declare class AddressingModeHandler {
     private readImmediateOperand;
     private updateRegisterForImmediateInstruction;
     private calculateRegisterValue;
-    private updateStatusFlags;
     private handleAbsoluteLongMode;
     private handleBlockMoveMode;
     private handleDirectPageMode;
@@ -604,15 +1354,14 @@ declare class RomLayout {
 declare class RomWriter {
     bpsPath?: string;
     readonly outBuffer: Uint8Array;
-    readonly entryPoints: DbEntryPoint[];
     readonly cartName: string;
     readonly makerCode: string;
-    constructor(entryPoints: DbEntryPoint[], cartName: string, makerCode: string);
+    readonly root: DbRoot;
+    constructor(root: DbRoot, cartName: string, makerCode: string);
     repack(files: ChunkFile[]): Promise<Uint8Array>;
     writeHeader(): void;
     writeChecksum(): void;
     writeEntryPoints(asmFiles: ChunkFile[]): void;
-    writeTransform(location: number, value: number, size?: number): void;
     writeFile(file: ChunkFile, _chunkLookup: Map<string, number>): Promise<number>;
     private writeAscii;
     /**
@@ -669,9 +1418,9 @@ declare class StringProcessor {
     private readonly memBuffer;
     private readonly context;
     private readonly root;
+    private readonly stringCharLookup;
     constructor(context: AssemblerContext);
-    dispose(): void;
-    consumeString(): void;
+    consumeString(typeChar: string): void;
     private flushBuffer;
     private processString;
     private applyLayers;
@@ -713,15 +1462,15 @@ declare class Assembler implements AssemblerContext {
     lineBuffer: string;
     includes: Set<string>;
     blocks: AsmBlock[];
-    tags: SortedMap<string | null>;
+    tags: SortedMap<string>;
     currentBlock: AsmBlock | null;
     lineCount: number;
     blockIndex: number;
     lastDelimiter: number | null;
     reqBank: number | null;
     eof: boolean;
+    strDelimRegex: RegExp;
     constructor(dbRoot: DbRoot, textData: string);
-    dispose(): void;
     parseAssembly(): {
         blocks: AsmBlock[];
         includes: Set<string>;
@@ -770,7 +1519,6 @@ declare class RomGenerator {
     private sourceData;
     constructor(projectName?: string);
     initialize(): Promise<void>;
-    validateAndDownload(sourceData: Uint8Array): Promise<boolean>;
     generateProject(modules: string[], manualFiles?: ChunkFile[], unshiftManualFiles?: boolean): Promise<Uint8Array>;
     private applyProjectInit;
     private assembleCodeFromText;
@@ -779,6 +1527,33 @@ declare class RomGenerator {
     private writeRom;
 }
 
+/**
+ * QuintetLZ compression algorithm implementation
+ * Dictionary-based compression used in Quintet games
+ */
+declare class QuintetLZ implements ICompressionProvider {
+    static readonly DICTIONARY_SIZE = 256;
+    static readonly DICTIONARY_INIT = 32;
+    static readonly DICTIONARY_OFFSET = 239;
+    private static readonly DEFAULT_PAGE_SIZE;
+    /**
+     * Expand (decompress) data using QuintetLZ algorithm
+     * @param srcData Source data buffer
+     * @param srcPosition Starting position in source data
+     * @param srcLen Length of source data to process
+     * @returns Expanded data
+     */
+    expand(srcData: Uint8Array, srcPosition?: number, srcLen?: number): Uint8Array;
+    /**
+     * Compact (compress) data using QuintetLZ algorithm
+     * @param srcData Source data to compress
+     * @returns Compressed data
+     */
+    compact(srcData: Uint8Array): Uint8Array;
+}
+
+declare const CompressionAlgorithms: Record<string, () => ICompressionProvider>;
+
 /**
  * Represents a single frame in a sprite animation sequence
  */
@@ -849,6 +1624,728 @@ declare class SpriteMap {
     toBytes(): Uint8Array;
 }
 
+/**
+ * Project configuration types
+ * TODO: Implement comprehensive project configuration
+ */
+interface ProjectConfig {
+    name: string;
+    version: string;
+    description?: string;
+}
+
+/**
+ * Collaboration types and utilities
+ * TODO: Implement collaboration functionality
+ */
+interface CollaborationConfig {
+    enabled: boolean;
+}
+
+/**
+ * TypeScript interfaces for Supabase API responses
+ * These types represent the structured data returned from ROM database queries
+ */
+interface PlatformData {
+    id: string;
+    name: string;
+    meta: any | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface BranchBaseData {
+    id: string;
+    name: string | null;
+    version: number | null;
+    isActive?: boolean | null;
+    notes?: string[] | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface FileBaseData {
+    id: string;
+    name: string;
+    type: string;
+    version: number | null;
+    crc: number | null;
+    meta: any | null;
+    isText: boolean;
+    text: string | null;
+    data: Uint8Array | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface FileBaseRaw extends Omit<FileBaseData, 'data'> {
+    data: string | null;
+}
+/**
+ * Platform branch information containing instruction set and addressing modes
+ */
+interface PlatformBranchData extends BranchBaseData {
+    platformId: string;
+    addressingModes: any | null;
+    instructionSet: any | null;
+    vectors: any | null;
+    types: any | null;
+    platform: PlatformData;
+}
+/**
+ * Game ROM branch information with platform reference
+ */
+interface GameRomBranchData extends BranchBaseData {
+    gameRomId: string;
+    platformBranchId: string;
+    coplib: any | null;
+    config: any | null;
+    files: any | null;
+    blocks: any | null;
+    fixups: any | null;
+    strings: any | null;
+    structs: any | null;
+    scenes: any | null;
+    gameRom: GameRomData;
+    platformBranch: PlatformBranchData;
+}
+interface GameRomArtifactData extends FileBaseData {
+    gameRomId: string;
+}
+interface GameRomArtifactRaw extends FileBaseRaw {
+    gameRomId: string;
+}
+interface GameRomBranchArtifactRaw {
+    id: string;
+    branchId: string;
+    artifactId: string;
+    artifact: GameRomArtifactRaw;
+}
+/**
+ * Base ROM information
+ */
+interface BaseRomData {
+    id: string;
+    name: string;
+    gameId: string;
+    gameRomId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface GameData {
+    id: string;
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface RegionData {
+    id: string;
+    name: string;
+    meta: any | null;
+    platformId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface GameRomData {
+    id: string;
+    crc: number;
+    meta: any | null;
+    gameId: string;
+    regionId: string;
+    createdAt: string;
+    updatedAt: string;
+    game: GameData;
+    region: RegionData;
+}
+/**
+ * Base ROM branch with complete relationship chain
+ */
+interface BaseRomBranchData extends BranchBaseData {
+    baseRomId: string;
+    gameRomBranchId: string;
+    gameRomBranch: GameRomBranchData;
+    baseRom: BaseRomData;
+}
+/**
+ * Base ROM file containing binary data
+ */
+interface BaseRomFileData extends FileBaseData {
+    baseRomId: string;
+}
+interface BaseRomBranchFileRaw {
+    id: string;
+    branchId: string;
+    fileId: string;
+    file: BaseRomFileRaw;
+}
+/**
+ * Raw BaseRomFile data as returned from Supabase (before conversion)
+ */
+interface BaseRomFileRaw extends FileBaseRaw {
+    baseRomId: string;
+}
+/**
+ * Complete ROM payload containing branch data and files
+ */
+interface BaseRomPayload {
+    baseRomBranch: BaseRomBranchData;
+    files: BaseRomFileData[];
+}
+/**
+ * Options for loading ROM data by name
+ */
+interface FromSupabaseByNameOptions {
+    /**
+     * Name of the game to load
+     * @default 'Illusion of Gaia'
+     */
+    gameName: string;
+    /**
+     * Name of the base ROM to load
+     * @default 'GaiaLabs BaseROM'
+     */
+    baseRomName: string;
+    /**
+     * Name of the branch to load
+     * Set to null to load the main/develop branch
+     * Set to undefined to not filter by branch name
+     */
+    branchName?: string | null;
+    /**
+     * Version of the branch to load
+     * Set to null to load the latest/main version
+     * Set to undefined to not filter by version
+     */
+    branchVersion?: number | null;
+}
+/**
+ * Error codes for Supabase operations
+ */
+declare enum SupabaseErrorCode {
+    BRANCH_NOT_FOUND = "BRANCH_NOT_FOUND",
+    ROM_NOT_FOUND = "ROM_NOT_FOUND",
+    FILES_NOT_FOUND = "FILES_NOT_FOUND",
+    NETWORK_ERROR = "NETWORK_ERROR",
+    INVALID_DATA = "INVALID_DATA",
+    ENVIRONMENT_ERROR = "ENVIRONMENT_ERROR",
+    PERMISSION_ERROR = "PERMISSION_ERROR"
+}
+/**
+ * Custom error class for Supabase operations
+ */
+declare class SupabaseFromError extends Error {
+    readonly code: SupabaseErrorCode;
+    readonly details?: any;
+    constructor(message: string, code: SupabaseErrorCode, details?: any);
+}
+/**
+ * Result type for async operations that may fail
+ */
+type SupabaseResult<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: SupabaseFromError;
+};
+/**
+ * Project information
+ */
+interface ProjectData {
+    id: string;
+    name: string;
+    meta: any | null;
+    gameId: string;
+    baseRomId: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Project branch with complete relationship chain
+ */
+interface ProjectBranchData extends BranchBaseData {
+    projectId: string;
+    baseRomBranchId: string;
+    modules: any[];
+    project: ProjectData;
+    baseRomBranch: BaseRomBranchData;
+}
+/**
+ * Project file containing binary data
+ */
+interface ProjectFileData extends FileBaseData {
+    module: string | null;
+    projectId: string;
+}
+interface ProjectBranchFileRaw {
+    id: string;
+    branchId: string;
+    fileId: string;
+    file: ProjectFileRaw;
+}
+/**
+ * Raw ProjectFile data as returned from Supabase (before conversion)
+ */
+interface ProjectFileRaw extends FileBaseRaw {
+    module: string | null;
+    projectId: string;
+}
+/**
+ * Complete Project payload containing branch data and files
+ */
+interface ProjectPayload {
+    projectBranch: ProjectBranchData;
+    projectFiles: ProjectFileData[];
+    baseRomBranch: BaseRomBranchData;
+    baseRomFiles: BaseRomFileData[];
+}
+/**
+ * Options for loading Project data by name
+ */
+interface FromSupabaseByProjectOptions {
+    projectName: string;
+    /**
+     * Name of the branch to load
+     * Set to null to load the main/develop branch
+     * Set to undefined to not filter by branch name
+     */
+    branchName?: string | null;
+    /**
+     * Version of the branch to load
+     * Set to null to load the latest/main version
+     * Set to undefined to not filter by version
+     */
+    branchVersion?: number | null;
+}
+/**
+ * Query statistics for performance monitoring
+ */
+interface QueryStats {
+    branchQueryTime: number;
+    fileQueryTime: number;
+    totalTime: number;
+    fileCount: number;
+}
+
+/**
+ * Supabase client configuration and initialization
+ */
+
+/**
+ * Database interface definitions based on Prisma schema
+ * These types represent the structure of data returned from Supabase queries
+ */
+interface Database {
+    public: {
+        Tables: {
+            BaseRom: {
+                Row: {
+                    id: string;
+                    name: string;
+                    gameId: string;
+                    gameRomId: string;
+                    createdAt: string;
+                    updatedAt: string;
+                };
+            };
+            BaseRomBranch: {
+                Row: {
+                    id: string;
+                    name: string | null;
+                    version: number | null;
+                    isPublic: boolean;
+                    baseRomId: string;
+                    gameRomBranchId: string;
+                    fileCrcs: number[];
+                    createdAt: string;
+                    updatedAt: string;
+                };
+            };
+            GameRomBranch: {
+                Row: {
+                    id: string;
+                    name: string | null;
+                    version: number | null;
+                    isPublic: boolean;
+                    gameRomId: string;
+                    platformBranchId: string;
+                    coplib: any | null;
+                    config: any | null;
+                    files: any | null;
+                    blocks: any | null;
+                    fixups: any | null;
+                    strings: any | null;
+                    structs: any | null;
+                    scenes: any | null;
+                    createdAt: string;
+                    updatedAt: string;
+                };
+            };
+            GameRomBranchAsset: {
+                Row: {
+                    id: string;
+                    name: string;
+                    type: string;
+                    gameRomBranchId: string;
+                    text: string | null;
+                    data: string | null;
+                    createdAt: string;
+                    updatedAt: string;
+                };
+            };
+            PlatformBranch: {
+                Row: {
+                    id: string;
+                    name: string | null;
+                    version: number | null;
+                    isPublic: boolean;
+                    platformId: string;
+                    addressingModes: any | null;
+                    instructionSet: any | null;
+                    vectors: any | null;
+                    createdAt: string;
+                    updatedAt: string;
+                };
+            };
+            BaseRomFile: {
+                Row: {
+                    id: string;
+                    name: string;
+                    type: string;
+                    version: number | null;
+                    crc: number | null;
+                    meta: any | null;
+                    baseRomId: string;
+                    data: string;
+                    createdAt: string;
+                    updatedAt: string;
+                };
+            };
+        };
+    };
+}
+/**
+ * Create and configure a Supabase client instance
+ * @returns Configured Supabase client
+ */
+declare function createSupabaseClient(): SupabaseClient<Database>;
+/**
+ * Get the singleton Supabase client instance
+ * Creates the instance if it doesn't exist
+ * @returns Supabase client instance
+ */
+declare function getSupabaseClient(): SupabaseClient<Database>;
+/**
+ * Reset the singleton client instance (useful for testing)
+ */
+declare function resetSupabaseClient(): void;
+
+/**
+ * ROM data loading functions for Supabase integration
+ *
+ * This module provides functions to load ROM branch data and files from Supabase,
+ * enabling cloud-based ROM database functionality for the GaiaLabs platform.
+ */
+
+/**
+ * Load ROM data from Supabase using a BaseRomBranch ID
+ *
+ * @param baseRomBranchId - The ID of the BaseRomBranch to load
+ * @returns Promise<BaseRomPayload> containing the branch data and files
+ * @throws {SupabaseFromError} If the branch is not found or other errors occur
+ *
+ * @example
+ * ```typescript
+ * const payload = await fromSupabaseById('clm1234567890');
+ * console.log(payload.baseRomBranch.name);
+ * console.log(`Loaded ${payload.files.length} files`);
+ * ```
+ */
+declare function fromSupabaseById(baseRomBranchId: string): Promise<BaseRomPayload>;
+/**
+ * Load ROM data from Supabase using name-based lookup
+ *
+ * @param options - Options for name-based lookup
+ * @returns Promise<BaseRomPayload> containing the branch data and files
+ * @throws {SupabaseFromError} If the branch is not found or other errors occur
+ *
+ * @example
+ * ```typescript
+ * // Load default ROM (GaiaLabs BaseROM, main branch)
+ * const payload1 = await fromSupabaseByName({});
+ *
+ * // Load specific ROM and branch
+ * const payload2 = await fromSupabaseByName({
+ *   baseRomName: 'My Custom ROM',
+ *   branchName: 'development',
+ *   branchVersion: null // latest version
+ * });
+ *
+ * // Load main branch explicitly
+ * const payload3 = await fromSupabaseByName({
+ *   baseRomName: 'GaiaLabs BaseROM',
+ *   branchName: null, // main branch
+ *   branchVersion: null // latest version
+ * });
+ * ```
+ */
+declare function fromSupabaseByName(options: FromSupabaseByNameOptions): Promise<BaseRomPayload>;
+/**
+ * Load Project data from Supabase using project name-based lookup
+ *
+ * @param projectName - The name of the project to load
+ * @param options - Options for branch filtering
+ * @returns Promise<ProjectPayload> containing the project branch data and files
+ * @throws {SupabaseFromError} If the project branch is not found or other errors occur
+ *
+ * @example
+ * ```typescript
+ * // Load default project branch (main/latest)
+ * const payload1 = await fromSupabaseByProject('My Game Project');
+ *
+ * // Load specific branch
+ * const payload2 = await fromSupabaseByProject('My Game Project', {
+ *   branchName: 'development',
+ *   branchVersion: null // latest version
+ * });
+ *
+ * // Load main branch explicitly
+ * const payload3 = await fromSupabaseByProject('My Game Project', {
+ *   branchName: null, // main branch
+ *   branchVersion: null // latest version
+ * });
+ * ```
+ */
+declare function fromSupabaseByProject(projectName?: string, branchId?: string): Promise<ProjectPayload>;
+declare function fromSupabaseByGameRom(gameName?: string, regionName?: string, platformName?: string, branchId?: string): Promise<ProjectPayload>;
+declare function summaryFromSupabaseByProject(projectName?: string): Promise<ProjectBranchData>;
+
+/**
+ * Utility functions for Supabase integration
+ */
+/**
+ * Get environment variable value that works in both browser and Node.js contexts
+ * @param key - The environment variable key to retrieve
+ * @throws {Error} If the environment variable is not set
+ * @returns The environment variable value
+ */
+declare function getEnvVar(key: string): string;
+/**
+ * Convert base64 string to Uint8Array for binary data processing
+ * @param base64 - Base64 encoded string
+ * @returns Uint8Array containing the binary data
+ */
+declare function base64ToUint8Array(base64: string): Uint8Array;
+/**
+ * Convert hex-encoded string to Uint8Array
+ * @param hexString - Hex encoded string (with or without \x prefix)
+ * @returns Uint8Array containing the binary data
+ */
+declare function hexToUint8Array(hexString: string): Uint8Array;
+/**
+ * Convert binary data to appropriate format based on the input string
+ * Automatically detects if the input is hex-encoded or base64
+ * @param dataString - Either hex-encoded string (starting with \x) or base64 string
+ * @returns Uint8Array containing the binary data
+ */
+declare function decodeDataString(dataString: string): Uint8Array;
+/**
+ * Convert Uint8Array to base64 string
+ * @param uint8Array - Binary data as Uint8Array
+ * @returns Base64 encoded string
+ */
+declare function uint8ArrayToBase64(uint8Array: Uint8Array): string;
+/**
+ * Validate that required environment variables are set
+ * @param requiredVars - Array of environment variable names that must be set
+ * @throws {Error} If any required environment variable is missing
+ */
+declare function validateEnvironmentVariables(requiredVars: string[]): void;
+
+/**
+ * Universal file reading utilities
+ * Works in both Node.js and browser environments
+ */
+interface FileReadOptions {
+    encoding?: 'utf8' | 'binary';
+}
+/**
+ * Read a file as text
+ * @param path File path or URL
+ * @param options Read options
+ * @returns Promise<string>
+ */
+declare function readFileAsText(path: string, options?: FileReadOptions): Promise<string>;
+/**
+ * Read a file as binary data (Uint8Array)
+ * @param path File path or URL
+ * @returns Promise<Uint8Array>
+ */
+declare function readFileAsBinary(path: string): Promise<Uint8Array>;
+/**
+ * Read a JSON file and parse it
+ * @param path File path or URL
+ * @returns Promise<any>
+ */
+declare function readJsonFile<T = any>(path: string): Promise<T>;
+/**
+ * Check if a file exists
+ * @param path File path
+ * @returns Promise<boolean>
+ */
+declare function fileExists(path: string): Promise<boolean>;
+/**
+ * Get the directory path containing a file
+ * @param filePath File path
+ * @returns string
+ */
+declare function getDirectory(filePath: string): Promise<string>;
+/**
+ * Create a temporary directory.
+ * This is a Node.js-specific operation.
+ * @param prefix Prefix for the temporary directory name.
+ * @returns Promise<string> Path to the created temporary directory.
+ */
+declare function createTempDirectory(prefix: string): Promise<string>;
+/**
+ * Remove a directory recursively.
+ * This is a Node.js-specific operation.
+ * @param dirPath Path to the directory to remove.
+ * @returns Promise<void>
+ */
+declare function removeDirectory(dirPath: string): Promise<void>;
+interface DirectoryEntry {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+/**
+ * List directory contents
+ * This is a Node.js-specific operation.
+ * @param dirPath Path to the directory to list
+ * @param options Options for filtering and recursion
+ * @returns Promise<DirectoryEntry[]>
+ */
+declare function listDirectory(dirPath: string, options?: {
+    recursive?: boolean;
+    filter?: (entry: DirectoryEntry) => boolean;
+    extension?: string;
+}): Promise<DirectoryEntry[]>;
+/**
+ * Save text content to a file
+ * This is a Node.js-specific operation.
+ * @param path File path where to save the content
+ * @param text Text content to save
+ * @returns Promise<void>
+ */
+declare function saveFileAsText(path: string, text: string): Promise<void>;
+/**
+ * Save binary data to a file
+ * This is a Node.js-specific operation.
+ * @param path File path where to save the data
+ * @param data Binary data as Uint8Array to save
+ * @returns Promise<void>
+ */
+declare function saveFileAsBinary(path: string, data: Uint8Array): Promise<void>;
+
+declare function crc32_buffer(data: Uint8Array): number;
+declare function crc32_text_utf8(text: string): number;
+declare function crc32_text_utf16(text: string): number;
+
+/**
+ * Base64 encoding and decoding utilities for Uint8Arrays
+ * Works in both Node.js and browser environments
+ */
+/**
+ * Encode a Uint8Array to a base64 string
+ * @param data The binary data to encode
+ * @returns Base64 encoded string
+ */
+declare function encodeBase64(data: Uint8Array): string;
+/**
+ * Decode a base64 string to a Uint8Array
+ * @param base64String The base64 string to decode
+ * @returns Decoded binary data as Uint8Array
+ * @throws {Error} If the input is not a valid base64 string
+ */
+declare function decodeBase64(base64String: string): Uint8Array;
+/**
+ * Check if a string is valid base64
+ * @param str The string to validate
+ * @returns True if the string is valid base64, false otherwise
+ */
+declare function isValidBase64(str: string): boolean;
+/**
+ * Encode a string to base64 (convenience function)
+ * @param text The text string to encode
+ * @returns Base64 encoded string
+ */
+declare function encodeBase64String(text: string): string;
+/**
+ * Decode a base64 string to text (convenience function)
+ * @param base64String The base64 string to decode
+ * @returns Decoded text string
+ * @throws {Error} If the input is not a valid base64 string or doesn't contain valid UTF-8
+ */
+declare function decodeBase64String(base64String: string): string;
+
+/**
+ * Debug utility to export processing results as JSON for comparison
+ */
+declare class DebugExporter {
+    /**
+     * Export chunk files to JSON for comparison with C# output
+     */
+    static exportChunkFiles(files: ChunkFile[], filename: string): void;
+    /**
+     * Export patch application summary
+     */
+    static exportPatchSummary(originalFiles: ChunkFile[], patchedFiles: ChunkFile[], patches: ChunkFile[], filename: string): void;
+    /**
+     * Export layout debugging information
+     */
+    static exportLayoutDebug(files: ChunkFile[], filename: string): void;
+}
+
+/**
+ * Convert bytes to hex string
+ */
+declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * Convert hex string to bytes
+ */
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Clamp a value between min and max
+ */
+declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Convert binary data (Uint8Array) to UTF-8 string representation
+ *
+ * This function properly decodes UTF-8 encoded binary data to avoid corruption
+ * of special characters and multi-byte sequences.
+ *
+ * @param binaryData - The binary data as Uint8Array containing UTF-8 encoded text
+ * @returns The decoded UTF-8 string
+ * @throws {Error} If the binary data contains invalid UTF-8 sequences
+ *
+ * @example
+ * ```typescript
+ * const binaryData = new Uint8Array([72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]);
+ * const text = binaryToUtf8String(binaryData);
+ * console.log(text); // "Hello World"
+ *
+ * // Handle UTF-8 multi-byte characters
+ * const utf8Data = new Uint8Array([240, 159, 152, 128]); // 😀 emoji
+ * const emoji = binaryToUtf8String(utf8Data);
+ * console.log(emoji); // "😀"
+ * ```
+ */
+declare function binaryToUtf8String(binaryData: Uint8Array): string;
+/**
+ * Safely get nested object property
+ */
+declare function getNestedProperty(obj: any, path: string): any;
+declare function indexOfAny(str: string, chars: string[], startIndex?: number): number;
+
 /**
  * GaiaCore - Universal ROM processing engine
  *
@@ -867,7 +2364,7 @@ declare class SpriteMap {
  */
 declare const GAIA_CORE_VERSION = "0.1.6";
 declare const isPlatformBrowser: boolean;
-declare const isPlatformNode: string | false;
+declare const isPlatformNode: string;
 declare const isPlatformWebWorker: boolean;
 
-export { AddressingModeHandler, AsmReader, Assembler, type AssemblerContext, AssemblerState, BlockReader, BlockWriter, CopCommandProcessor, GAIA_CORE_VERSION, ObjectType, OperationContext, PostProcessor, ProcessorStateManager, type ProjectConfig, ProjectRoot, QuintetLZ, ReferenceManager, Registers, RomDataReader, RomGenerator, RomLayout, RomProcessor, RomState, RomStateUtils, RomWriter, SortedMap, SpriteFrame, SpriteGroup, SpriteMap, SpritePart, Stack, StackOperations, StringProcessor, StringReader, TransformProcessor, TypeParser, isPlatformBrowser, isPlatformNode, isPlatformWebWorker, registerCompressionProviders };
+export { Address, AddressSpace, AddressType, AddressingModeHandler, AsmBlock, AsmBlockUtils, AsmReader, Assembler, type AssemblerContext, AssemblerState, type BaseRomBranchData, type BaseRomBranchFileRaw, type BaseRomData, type BaseRomFileData, type BaseRomFileRaw, type BaseRomPayload, BinType, BitStream, BlockReader, BlockReaderConstants, BlockWriter, type BranchBaseData, Byte, ChunkFile, ChunkFileUtils, type CollaborationConfig, CompressionAlgorithms, CompressionRegistry, CopCommandProcessor, CopDef, type Database, DbAddressingMode, type DbAsset, type DbBaseRomModule, DbBlock, type DbConfig, type DbEntryPoint, DbFile, DbFileType, type DbGameRomModule, DbGroup, type DbLabel, type DbMnemonic, DbOverride, DbPart, type DbPath, type DbRewrite, type DbRoot, DbRootUtils, DbScene, type DbSfx, DbStringCommand, type DbStringLayer, DbStringType, DbStringTypeUtils, DbStruct, DbTransform, DebugExporter, type DirectoryEntry, type FileBaseData, type FileBaseRaw, type FileReadOptions, type FromSupabaseByNameOptions, type FromSupabaseByProjectOptions, GAIA_CORE_VERSION, type GameData, type GameRomArtifactData, type GameRomArtifactRaw, type GameRomBranchArtifactRaw, type GameRomBranchData, type GameRomData, type ICompressionProvider, LocationWrapper, Long, MapExt, MemberType, ObjectType, Op, OpCode, OperationContext, type PlatformBranchData, type PlatformData, PostProcessor, ProcessorStateManager, type ProjectBranchData, type ProjectBranchFileRaw, type ProjectConfig, type ProjectData, type ProjectFileData, type ProjectFileRaw, type ProjectPayload, type QueryStats, QuintetLZ, ReferenceManager, type RegionData, RegisterType, Registers, RomDataReader, RomGenerator, RomLayout, RomProcessingConstants, RomProcessor, RomState, RomStateUtils, RomWriter, SortedMap, SpriteFrame, SpriteGroup, SpriteMap, SpritePart, Stack, StackOperations, StatusFlags, type StringEntry, type StringMarker, StringProcessor, StringReader, StringSizeComparer, type StringWrapper, type StructDef, SupabaseErrorCode, SupabaseFromError, type SupabaseResult, type TableEntry, TransformProcessor, TypeParser, TypedNumber, Word, type XformDef, XformType, base64ToUint8Array, binaryToUtf8String, bytesToHex, clamp, crc32_buffer, crc32_text_utf16, crc32_text_utf8, createChunkFileFromDbBlock, createChunkFileFromDbFile, createDbPath, createSupabaseClient, createTableEntry, createTempDirectory, decodeBase64, decodeBase64String, decodeDataString, encodeBase64, encodeBase64String, fileExists, fromSupabaseByGameRom, fromSupabaseById, fromSupabaseByName, fromSupabaseByProject, getDirectory, getEnvVar, getNestedProperty, getSupabaseClient, hexToBytes, hexToUint8Array, indexOfAny, isPlatformBrowser, isPlatformNode, isPlatformWebWorker, isValidBase64, listDirectory, readFileAsBinary, readFileAsText, readJsonFile, removeDirectory, resetSupabaseClient, saveFileAsBinary, saveFileAsText, summaryFromSupabaseByProject, uint8ArrayToBase64, validateEnvironmentVariables };