@gaialabs/core 0.1.0 → 0.1.2

package/dist/index.d.mts

@@ -1,145 +1,4 @@
-import { DbRoot, BinType, DbPath, AddressingMode, AddressType, StatusFlags, CopDef, DbStringType, StringWrapper, DbBlock, DbPart, Address } from 'gaia-shared';
-export { DbRoot } from 'gaia-shared';
-
-/**
- * Represents a single frame in a sprite animation sequence
- */
-declare class SpriteFrame {
-    duration: number;
-    groupIndex: number;
-    /**
-     * Internal offset to the group data (not serialized)
-     */
-    groupOffset: number;
-    constructor(duration?: number, groupIndex?: number, groupOffset?: number);
-}
-
-/**
- * Represents a single part/piece of a sprite
- */
-declare class SpritePart {
-    isLarge: boolean;
-    xOffset: number;
-    xOffsetMirror: number;
-    yOffset: number;
-    yOffsetMirror: number;
-    vMirror: boolean;
-    hMirror: boolean;
-    someOffset: number;
-    paletteIndex: number;
-    tileIndex: number;
-    constructor();
-}
-
-/**
- * Represents a group of sprite parts that form a complete sprite frame
- */
-declare class SpriteGroup {
-    xOffset: number;
-    xOffsetMirror: number;
-    yOffset: number;
-    yOffsetMirror: number;
-    xRecoilHitboxOffset: number;
-    yRecoilHitboxOffset: number;
-    xRecoilHitboxTilesize: number;
-    yRecoilHitboxTilesize: number;
-    xHostileHitboxOffset: number;
-    xHostileHitboxSize: number;
-    yHostileHitboxOffset: number;
-    yHostileHitboxSize: number;
-    parts: SpritePart[];
-    constructor();
-}
-
-/**
- * Represents a complete sprite map with frame sets and groups
- */
-declare class SpriteMap {
-    frameSets: SpriteFrame[][];
-    groups: SpriteGroup[];
-    constructor();
-    /**
-     * Create a SpriteMap from binary data
-     * @param data Binary data buffer
-     * @returns SpriteMap instance
-     */
-    static fromBytes(data: Uint8Array): SpriteMap;
-    /**
-     * Convert this SpriteMap to binary data
-     * @returns Binary data buffer
-     */
-    toBytes(): Uint8Array;
-}
-
-/**
- * ROM state management for SNES hardware emulation
- * Converted from GaiaLib/Rom/RomState.cs
- */
-declare class RomState {
-    readonly cgram: Uint8Array<ArrayBuffer>;
-    readonly vram: Uint8Array<ArrayBuffer>;
-    readonly mainTileset: Uint8Array<ArrayBuffer>;
-    readonly effectTileset: Uint8Array<ArrayBuffer>;
-    mainTilesetPath?: string;
-    effectTilesetPath?: string;
-    mainTilemap: Uint8Array<ArrayBuffer>;
-    mainTilemapW: number;
-    mainTilemapH: number;
-    mainTilemapPath?: string;
-    effectTilemap: Uint8Array<ArrayBuffer>;
-    effectTilemapW: number;
-    effectTilemapH: number;
-    effectTilemapPath?: string;
-    static spriteMap: SpriteMap | null;
-    static spriteMapPath: string | null;
-    /**
-     * Strip address space prefixes from names
-     */
-    static stripName(name: string): string;
-    /**
-     * Create ROM state from scene metadata
-     * Simplified version of the C# implementation
-     */
-    static fromScene(baseDir: string, root: DbRoot, metaFile: string, id: number): Promise<RomState>;
-    /**
-     * Process scene command (simplified version)
-     * TODO: Implement full command processing
-     */
-    private static processCommand;
-}
-/**
- * ROM state utilities
- */
-declare class RomStateUtils {
-    /**
-     * Create empty ROM state
-     */
-    static createEmpty(): RomState;
-    /**
-     * Clear all data in ROM state
-     */
-    static clear(state: RomState): void;
-}
-
-/**
- * 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;
-}
+import { ICompressionProvider, BinType, DbPath, StatusFlags, DbRoot, AddressType, DbStringType, StringWrapper, Op, OpCode, ChunkFile, AsmBlock, Address, CopDef, DbEntryPoint } from '@gaialabs/shared';
 
 /**
  * QuintetLZ compression algorithm implementation
@@ -166,6 +25,11 @@ declare class QuintetLZ implements ICompressionProvider {
     compact(srcData: Uint8Array): Uint8Array;
 }
 
+/**
+ * Register compression providers with the global registry
+ */
+declare function registerCompressionProviders(): void;
+
 /**
  * Main project management class
  * Converted from GaiaLib/ProjectRoot.cs
@@ -198,257 +62,89 @@ declare class ProjectRoot {
     systemPath?: string;
     compression?: string;
     constructor(config: ProjectConfig);
-    /**
-     * Get compression provider
-     */
-    getCompression(): ICompressionProvider;
     /**
      * Load project from file or directory
      */
     static load(path?: string): Promise<ProjectRoot>;
-    /**
-     * Build the ROM (simplified)
-     */
-    build(): Promise<void>;
-    /**
-     * Dump database and extract ROM data
-     */
-    dumpDatabase(): Promise<DbRoot>;
 }
 
 /**
- * Unified ROM processor providing high-level APIs for common ROM processing workflows
- * This is the main entry point for ROM processing operations
+ * Lightweight ROM state placeholder used during early development.
+ * This stub will be expanded as the ROM extraction pipeline matures.
  */
-declare class RomProcessor {
-    private projectRoot;
-    private dbRoot;
-    private romData;
-    private romState;
-    constructor(projectConfig: ProjectConfig);
-    /**
-     * Create ROM processor from project file or directory
-     */
-    static fromProject(path?: string): Promise<RomProcessor>;
-    /**
-     * Load ROM data from file or URL
-     */
-    loadRom(romPath?: string): Promise<void>;
-    /**
-     * Initialize database and load ROM metadata
-     */
-    initialize(): Promise<void>;
-    /**
-     * Analyze ROM structure and extract metadata
-     */
-    analyze(): Promise<RomAnalysisResult>;
-    /**
-     * Extract files from ROM data
-     */
-    extract(outputDir: string): Promise<ExtractionResult>;
-    /**
-     * Process scene data for a specific scene ID
-     */
-    processScene(sceneId: number, metaFile: string): Promise<RomState>;
-    /**
-     * Build ROM from extracted files
-     */
-    build(outputPath: string): Promise<BuildResult>;
-    /**
-     * Get compression provider for the project
-     */
-    getCompression(): QuintetLZ;
-    /**
-     * Get current ROM state
-     */
-    getRomState(): RomState | null;
-    /**
-     * Get database root
-     */
-    getDatabase(): DbRoot | null;
+declare class RomState {
+    readonly cgram: Uint8Array<ArrayBuffer>;
+    readonly vram: Uint8Array<ArrayBuffer>;
     /**
-     * Get project configuration
+     * Create ROM state from scene metadata.
+     * Parameters are currently unused but kept for future implementation.
      */
-    getProject(): ProjectRoot;
-    private analyzeHeader;
-    private detectCompression;
-    private analyzeOpcodes;
-}
-interface RomAnalysisResult {
-    romSize: number;
-    headerInfo: RomHeaderInfo;
-    entryPoints: any[];
-    fileCount: number;
-    blockCount: number;
-    compressionUsed: boolean;
-    spriteMapFound: boolean;
-    opcodeStats: OpcodeStats;
-}
-interface RomHeaderInfo {
-    title: string;
-    mapMode: number;
-    cartridgeType: number;
-    romSize: number;
-    ramSize: number;
-    isValid: boolean;
-}
-interface ExtractionResult {
-    extractedFiles: string[];
-    errors: string[];
-    totalSize: number;
+    static fromScene(_baseDir: string, _root: unknown, _metaFile: string, _id: number): Promise<RomState>;
 }
-interface BuildResult {
-    success: boolean;
-    outputPath: string;
-    romSize: number;
-    errors: string[];
-}
-interface OpcodeStats {
-    totalOpcodes: number;
-    uniqueOpcodes: number;
-    coverage: number;
-}
-
 /**
- * Project lifecycle management events
+ * Utility helpers for working with RomState.
  */
-interface ProjectEvents {
-    onLoadStart?: () => void;
-    onLoadComplete?: (processor: RomProcessor) => void;
-    onLoadError?: (error: Error) => void;
-    onAnalysisStart?: () => void;
-    onAnalysisComplete?: (results: any) => void;
-    onExtractionStart?: () => void;
-    onExtractionComplete?: (results: any) => void;
-    onBuildStart?: () => void;
-    onBuildComplete?: (results: any) => void;
-}
-/**
- * Project status tracking
- */
-interface ProjectStatus {
-    isLoaded: boolean;
-    isAnalyzed: boolean;
-    isExtracted: boolean;
-    canBuild: boolean;
-    lastError?: Error;
-    progress: number;
-    currentTask?: string;
+declare class RomStateUtils {
+    /** Create an empty ROM state */
+    static createEmpty(): RomState;
+    /** Clear all data in the given ROM state */
+    static clear(state: RomState): void;
 }
+
 /**
- * Unified project manager for complete project lifecycle management
- * This is the highest-level API for managing ROM hacking projects
+ * Represents the stack for the 65816 processor
  */
-declare class ProjectManager {
-    private processor;
-    private status;
-    private events;
-    constructor(events?: ProjectEvents);
-    /**
-     * Create project manager from existing project configuration
-     */
-    static fromConfig(config: ProjectConfig, events?: ProjectEvents): Promise<ProjectManager>;
-    /**
-     * Create project manager from project file or directory
-     */
-    static fromPath(path: string, events?: ProjectEvents): Promise<ProjectManager>;
-    /**
-     * Load project from configuration
-     */
-    loadProject(config: ProjectConfig): Promise<void>;
-    /**
-     * Load project from file or directory path
-     */
-    loadProjectFromPath(path: string): Promise<void>;
-    /**
-     * Analyze ROM structure and extract metadata
-     */
-    analyzeRom(): Promise<any>;
-    /**
-     * Extract files from ROM
-     */
-    extractFiles(outputDir: string): Promise<any>;
-    /**
-     * Build ROM from extracted files
-     */
-    buildRom(outputPath: string): Promise<any>;
-    /**
-     * Process specific scene
-     */
-    processScene(sceneId: number, metaFile: string): Promise<RomState>;
-    /**
-     * Get current project status
-     */
-    getStatus(): ProjectStatus;
+declare class Stack {
+    bytes: Uint8Array;
+    location: number;
+    constructor();
     /**
-     * Get the ROM processor instance
+     * Push a byte onto the stack
      */
-    getProcessor(): RomProcessor | null;
+    push(value: number): void;
     /**
-     * Get project configuration
+     * Push a 16-bit value onto the stack (little-endian)
      */
-    getProjectConfig(): ProjectConfig | null;
+    pushUInt16(value: number): void;
     /**
-     * Get database root
+     * Pop a byte from the stack
      */
-    getDatabase(): DbRoot | null;
+    popByte(): number;
     /**
-     * Get ROM state
+     * Pop a 16-bit value from the stack (little-endian)
      */
-    getRomState(): RomState | null;
+    popUInt16(): number;
     /**
-     * Reset project to initial state
+     * Reset the stack to initial state
      */
     reset(): void;
-    /**
-     * Complete workflow: load, analyze, extract, and build
-     */
-    completeWorkflow(projectPath: string, outputDir: string, outputRomPath: string): Promise<any>;
-    private updateStatus;
 }
 
 /**
- * Represents a 65816 processor opcode
- */
-declare class OpCode {
-    code: number;
-    mnem: string;
-    mode: AddressingMode;
-    size: number;
-    constructor(code: number, mnem: string, mode: AddressingMode, size: number);
-}
-/**
- * Complete 65816 instruction set lookup table
- */
-declare const ALL_OPCODES: Record<number, OpCode>;
-/**
- * Grouped opcodes by mnemonic
- */
-declare const GROUPED_OPCODES: Record<string, OpCode[]>;
-/**
- * Regular expressions for parsing addressing modes
- */
-declare const ADDRESSING_REGEX: Record<AddressingMode, RegExp>;
-/**
- * Hex character validation regex
- */
-declare const HEX_REGEX: RegExp;
-/**
- * Utility methods for OpCode class
+ * Manages the 65816 processor registers and status flags
  */
-declare class OpCodeUtils {
+declare class Registers {
+    accumulatorFlag?: boolean;
+    indexFlag?: boolean;
+    direct?: number;
+    dataBank?: number;
+    accumulator?: number;
+    xIndex?: number;
+    yIndex?: number;
+    stack: Stack;
+    constructor();
     /**
-     * Get all available opcodes
+     * Get the current status flags
      */
-    static getAllOpcodes(): OpCode[];
+    get statusFlags(): StatusFlags;
     /**
-     * Get opcodes by mnemonic
+     * Set the status flags
      */
-    static getByMnemonic(mnemonic: string): OpCode[];
+    set statusFlags(value: StatusFlags);
     /**
-     * Find opcode by hex value
+     * Reset all registers to initial state
      */
-    static findByCode(code: number): OpCode | undefined;
+    reset(): void;
 }
 
 /**
@@ -464,7 +160,7 @@ declare class ProcessorStateManager {
      * Hydrate processor registers with stored state
      * Uses Registers from gaia-core/assembly for processor state management
      */
-    hydrateRegisters(position: number, reg: any): void;
+    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;
@@ -536,78 +232,6 @@ declare class ReferenceManager {
     private processClosestMatch;
 }
 
-/**
- * Represents the stack for the 65816 processor
- */
-declare class Stack {
-    bytes: Uint8Array;
-    location: number;
-    constructor();
-    /**
-     * Push a byte onto the stack
-     */
-    push(value: number): void;
-    /**
-     * Push a 16-bit value onto the stack (little-endian)
-     */
-    pushUInt16(value: number): void;
-    /**
-     * Pop a byte from the stack
-     */
-    popByte(): number;
-    /**
-     * Pop a 16-bit value from the stack (little-endian)
-     */
-    popUInt16(): number;
-    /**
-     * Reset the stack to initial state
-     */
-    reset(): void;
-}
-
-/**
- * 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;
-    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;
-}
-
-/**
- * Represents a single assembly operation/instruction
- */
-declare class Op {
-    code: OpCode;
-    location: number;
-    operands: unknown[];
-    size: number;
-    copDef?: CopDef;
-    constructor(code: OpCode, location?: number, operands?: unknown[], size?: number);
-    /**
-     * Get the formatted string representation of this operation
-     */
-    toString(): string;
-}
-
 /**
  * Reads and processes strings from ROM data
  * Converted from GaiaLib/Rom/Extraction/StringReader.cs
@@ -633,9 +257,10 @@ declare class StringReader {
  * Converted from GaiaLib/Rom/Extraction/AsmReader.cs
  */
 declare class AsmReader {
+    private static readonly PROCESSOR_FLAG_MASK;
     private static readonly ACCUMULATOR_OP_MASK;
     private static readonly ACCUMULATOR_OP_VALUE;
-    private static readonly VARIABLE_SIZE_INDICATOR;
+    static readonly VARIABLE_SIZE_INDICATOR = -2;
     private static readonly TWO_BYTES_SIZE;
     private static readonly THREE_BYTES_SIZE;
     private readonly _blockReader;
@@ -694,9 +319,10 @@ declare class BlockReader {
     get _structTable(): Map<number, string>;
     get _markerTable(): Map<number, number>;
     get _nameTable(): Map<number, string>;
-    _currentBlock: DbBlock;
-    _currentPart: DbPart | null;
     _partEnd: number;
+    _currentChunk: ChunkFile | null;
+    _currentAsmBlock: AsmBlock | null;
+    _enrichedChunks: ChunkFile[];
     constructor(romData: Uint8Array, root: DbRoot);
     /**
      * Processes predefined overrides for registers and bank notes
@@ -731,14 +357,10 @@ declare class BlockReader {
      * Checks if processing of the current part can continue
      */
     partCanContinue(): boolean;
-    /**
-     * Main analysis entry point
-     */
-    analyzeAndResolve(): void;
+    analyzeAndResolve(): ChunkFile[];
     /**
      * Analyzes all blocks in the ROM
      */
-    private analyzeBlocks;
     /**
      * Initializes blocks and parts with base references
      */
@@ -756,7 +378,27 @@ declare class BlockReader {
      */
     private processNewEntry;
     /**
-     * Resolves all references after analysis
+     * Creates ChunkFile objects from database structure
+     */
+    private createChunkFilesFromDatabase;
+    /**
+     * Creates binary ChunkFiles from DbFiles (enriched with rawData)
+     */
+    private createChunkFilesFromSfx;
+    /**
+     * Creates binary ChunkFiles from DbFiles (enriched with rawData)
+     */
+    private createChunkFilesFromDbFiles;
+    /**
+     * Creates assembly ChunkFiles from DbBlocks (enriched with parts)
+     */
+    private createChunkFilesFromDbBlocks;
+    /**
+     * Analyzes only assembly ChunkFiles (those with parts from DbBlocks)
+     */
+    private analyzeChunkFiles;
+    /**
+     * Resolves references in assembly ChunkFiles only
      */
     private resolveReferences;
     /**
@@ -775,10 +417,6 @@ declare class BlockReader {
      * Hydrates registers with stored state
      */
     hydrateRegisters(reg: Registers): void;
-    /**
-     * PascalCase wrapper for hydrateRegisters (for C# compatibility)
-     */
-    HydrateRegisters(reg: Registers): void;
 }
 
 /**
@@ -815,7 +453,7 @@ declare class OperationContext {
     nextAddress: number;
     xForm1: string | null;
     xForm2: string | null;
-    copDef: any;
+    copDef: CopDef | null;
 }
 /**
  * Handles different addressing modes for assembly instructions
@@ -863,56 +501,6 @@ declare class StackOperations {
     private handleExchangeBytes;
 }
 
-/**
- * Reads and extracts SFX data from ROM
- * Converted from GaiaLib/Rom/Extraction/SfxReader.cs
- */
-declare class SfxReader {
-    private readonly _romData;
-    private readonly _dbRoot;
-    private _location;
-    private _count;
-    constructor(romData: Uint8Array, dbRoot: DbRoot);
-    /**
-     * Reads a byte from the rom data
-     */
-    private readByte;
-    /**
-     * Reads a short from the rom data
-     */
-    private readShort;
-    /**
-     * Extracts the sfx from the rom data to the given output path
-     */
-    extract(outPath: string): Promise<void>;
-    /**
-     * Gets the path information for a binary type
-     * TODO: This should be implemented in DbRoot
-     */
-    private getPath;
-}
-
-/**
- * Reads and extracts files from ROM
- * Converted from GaiaLib/Rom/Extraction/FileReader.cs
- */
-declare class FileReader {
-    static readonly PALETTE_MIN_SIZE = 512;
-    private readonly _romData;
-    private readonly _dbRoot;
-    private readonly _compression;
-    constructor(romData: Uint8Array, dbRoot: DbRoot, provider: ICompressionProvider);
-    /**
-     * Extracts all files from the ROM to the given output path
-     */
-    extract(outPath: string): Promise<void>;
-    private processFileData;
-    /**
-     * Gets the path information for a binary type from DbRoot configuration
-     */
-    private getPath;
-}
-
 /**
  * Handles COP (Coprocessor) command processing
  * Converted from GaiaLib/Rom/Extraction/CopCommandProcessor.cs
@@ -953,8 +541,8 @@ declare class BlockWriter {
     private _isInline;
     private _currentPart;
     constructor(reader: BlockReader);
-    writeBlocks(outPath: string): Promise<void>;
-    generateAsm(block: DbBlock): string;
+    generateAllAsm(chunkFiles: ChunkFile[]): any[];
+    generateAsm(block: ChunkFile): string;
     private getMnemonicsForBlock;
     private resolveOperand;
     private getObjectType;
@@ -981,15 +569,295 @@ declare class PostProcessor {
     /**
      * Execute post process directive on a block if present.
      */
-    process(block: DbBlock): void;
+    process(block: ChunkFile): void;
     /**
      * Builds a lookup table from struct entries.
      * Equivalent to PostProcessor.Lookup in C# implementation.
      */
-    Lookup(block: DbBlock, keyIx: string, valueIx: string): void;
+    Lookup(block: ChunkFile, keyIx: string, valueIx: string): void;
 }
 
-declare const ROM_REBUILD_MODULE = "gaia-core/rom/rebuild";
+/**
+ * ROM layout planner
+ * Converted from ext/GaiaLib/Rom/Rebuild/RomLayout.cs
+ */
+declare class RomLayout {
+    private static readonly MIN_ACCEPTED_REMAINING;
+    readonly unmatchedFiles: ChunkFile[];
+    private readonly bestResult;
+    private readonly bestSample;
+    private currentBank;
+    private currentUpper;
+    private bestDepth;
+    private bestOffset;
+    private bestRemain;
+    constructor(files: Iterable<ChunkFile>);
+    organize(): void;
+    private testDepth;
+    private commitPage;
+}
+
+/**
+ * ROM writer (binary)
+ * Converted from ext/GaiaLib/Rom/Rebuild/RomWriter.cs (subset: binary write only)
+ */
+declare class RomWriter {
+    bpsPath?: string;
+    readonly outBuffer: Uint8Array;
+    readonly entryPoints: DbEntryPoint[];
+    readonly cartName: string;
+    readonly makerCode: string;
+    constructor(entryPoints: DbEntryPoint[], 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;
+    /**
+     * Parse assembly blocks and write binary data to output buffer
+     * Converted from ext/GaiaLib/Rom/Rebuild/RomWriter.cs ParseAssembly method
+     */
+    private parseAssembly;
+    /**
+     * Helper method to find index of any character from an array in a string
+     */
+    private indexOfAny;
+    /**
+     * Helper method to check if an object is a StringMarker
+     */
+    private isStringMarker;
+    private isTableEntry;
+}
+
+/**
+ * ROM rebuild processor
+ * Converted from ext/GaiaLib/Rom/Rebuild/RomProcessor.cs
+ */
+declare class RomProcessor {
+    private readonly writer;
+    constructor(writer: RomWriter);
+    repack(allFiles: ChunkFile[]): Promise<void>;
+    static applyPatches(asmFiles: ChunkFile[], patches: ChunkFile[]): void;
+}
+
+/**
+ * Shared context interface for assembler components
+ * This eliminates circular dependencies between Assembler, AssemblerState, and StringProcessor
+ */
+interface AssemblerContext {
+    readonly root: DbRoot;
+    readonly stringProcessor: StringProcessor;
+    currentBlock: AsmBlock | null;
+    lineBuffer: string;
+    blockIndex: number;
+    lastDelimiter: number | null;
+    blocks: AsmBlock[];
+    eof: boolean;
+    lineCount: number;
+    getLine(): boolean;
+    processRawData(): void;
+    parseOperand(operand: string): unknown;
+}
+
+/**
+ * String processor for assembly parsing
+ * Converted from GaiaLib/Rom/Rebuild/StringProcessor.cs
+ */
+declare class StringProcessor {
+    private readonly memBuffer;
+    private readonly context;
+    private readonly root;
+    constructor(context: AssemblerContext);
+    dispose(): void;
+    consumeString(): void;
+    private flushBuffer;
+    private processString;
+    private applyLayers;
+    private applyMap;
+    private processStringCommand;
+    private getShiftUp;
+}
+
+/**
+ * A map that sorts keys by length in descending order, then alphabetically
+ * This is used for tag replacement where longer tags should be replaced first
+ * to avoid conflicts (e.g., "ABCD" should be replaced before "ABC")
+ */
+declare class SortedMap<V> {
+    private map;
+    private _keys;
+    get size(): number;
+    set(key: string, value: V): this;
+    get(key: string): V | undefined;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    keys(): string[];
+    values(): V[];
+    entries(): [string, V][];
+    [Symbol.iterator](): Generator<[string, V], void, unknown>;
+    private sortKeys;
+}
+
+/**
+ * Main assembler class for parsing assembly files
+ * Converted from GaiaLib/Rom/Rebuild/Assembler.cs
+ */
+declare class Assembler implements AssemblerContext {
+    readonly root: DbRoot;
+    private readonly lines;
+    private currentLineIndex;
+    readonly stringProcessor: StringProcessor;
+    lineBuffer: string;
+    includes: Set<string>;
+    blocks: AsmBlock[];
+    tags: SortedMap<string | null>;
+    currentBlock: AsmBlock | null;
+    lineCount: number;
+    blockIndex: number;
+    lastDelimiter: number | null;
+    reqBank: number | null;
+    eof: boolean;
+    constructor(dbRoot: DbRoot, textData: string);
+    dispose(): void;
+    parseAssembly(): {
+        blocks: AsmBlock[];
+        includes: Set<string>;
+        reqBank: number | null;
+    };
+    getLine(): boolean;
+    private trimComments;
+    private processDirectives;
+    private processTags;
+    private resolveTags;
+    parseOperand(opnd: string): unknown;
+    processRawData(): void;
+    private hexStringToBytes;
+}
+
+/**
+ * Assembler state machine for processing assembly text
+ * Converted from GaiaLib/Rom/Rebuild/AssemblerState.cs
+ */
+declare class AssemblerState {
+    private readonly dbStruct;
+    private readonly parentStruct;
+    private readonly root;
+    private readonly discriminator;
+    private delimiter;
+    private memberOffset;
+    private dataOffset;
+    private readonly memberTypes;
+    private currentType;
+    private readonly context;
+    constructor(context: AssemblerContext, structType?: string | null, saveDelimiter?: boolean);
+    private checkDisc;
+    private advancePart;
+    private processOrigin;
+    private static doMath;
+    private tryCreateLabel;
+    processText(openTag?: string): void;
+    private hexStringToBytes;
+}
+
+declare class RomGenerator {
+    private readonly moduleLookup;
+    private readonly moduleList;
+    private readonly sourceData;
+    private readonly patchFiles;
+    private chunkFiles;
+    private asmFiles;
+    private dbRoot;
+    constructor(modules: string[], sourceData: Uint8Array);
+    generateProject(projectName: string): Promise<Uint8Array>;
+    private initializeDatabase;
+    private initializeChunks;
+    private writeScriptTexts;
+    private applyBaseRom;
+    private applyProjectInit;
+    private applySelectedModules;
+    private assembleCodeFromText;
+    private applyCodePatches;
+    private calculateSizes;
+    private performLayout;
+    private rebaseAssemblies;
+    private generateAsmIncludeLookups;
+    applyPatchFile(chunkFile: ChunkFile): void;
+    private generateBlockLookup;
+    private writeRom;
+}
+
+/**
+ * Represents a single frame in a sprite animation sequence
+ */
+declare class SpriteFrame {
+    duration: number;
+    groupIndex: number;
+    /**
+     * Internal offset to the group data (not serialized)
+     */
+    groupOffset: number;
+    constructor(duration?: number, groupIndex?: number, groupOffset?: number);
+}
+
+/**
+ * Represents a single part/piece of a sprite
+ */
+declare class SpritePart {
+    isLarge: boolean;
+    xOffset: number;
+    xOffsetMirror: number;
+    yOffset: number;
+    yOffsetMirror: number;
+    vMirror: boolean;
+    hMirror: boolean;
+    someOffset: number;
+    paletteIndex: number;
+    tileIndex: number;
+    constructor();
+}
+
+/**
+ * Represents a group of sprite parts that form a complete sprite frame
+ */
+declare class SpriteGroup {
+    xOffset: number;
+    xOffsetMirror: number;
+    yOffset: number;
+    yOffsetMirror: number;
+    xRecoilHitboxOffset: number;
+    yRecoilHitboxOffset: number;
+    xRecoilHitboxTilesize: number;
+    yRecoilHitboxTilesize: number;
+    xHostileHitboxOffset: number;
+    xHostileHitboxSize: number;
+    yHostileHitboxOffset: number;
+    yHostileHitboxSize: number;
+    parts: SpritePart[];
+    constructor();
+}
+
+/**
+ * Represents a complete sprite map with frame sets and groups
+ */
+declare class SpriteMap {
+    frameSets: SpriteFrame[][];
+    groups: SpriteGroup[];
+    constructor();
+    /**
+     * Create a SpriteMap from binary data
+     * @param data Binary data buffer
+     * @returns SpriteMap instance
+     */
+    static fromBytes(data: Uint8Array): SpriteMap;
+    /**
+     * Convert this SpriteMap to binary data
+     * @returns Binary data buffer
+     */
+    toBytes(): Uint8Array;
+}
 
 /**
  * GaiaCore - Universal ROM processing engine
@@ -1007,9 +875,9 @@ declare const ROM_REBUILD_MODULE = "gaia-core/rom/rebuild";
  * - Compression: QuintetLZ compression algorithm
  * - Sprites: Sprite animation system
  */
-declare const GAIA_CORE_VERSION = "0.1.0";
+declare const GAIA_CORE_VERSION = "0.1.2";
 declare const isPlatformBrowser: boolean;
 declare const isPlatformNode: string | false;
 declare const isPlatformWebWorker: boolean;
 
-export { ADDRESSING_REGEX, ALL_OPCODES, AddressingModeHandler, AsmReader, BlockReader, BlockWriter, type BuildResult, CopCommandProcessor, type ExtractionResult, FileReader, GAIA_CORE_VERSION, GROUPED_OPCODES, HEX_REGEX, type ICompressionProvider, ObjectType, Op, OpCode, OpCodeUtils, type OpcodeStats, OperationContext, PostProcessor, ProcessorStateManager, type ProjectConfig, type ProjectEvents, ProjectManager, ProjectRoot, type ProjectStatus, QuintetLZ, ROM_REBUILD_MODULE, ReferenceManager, Registers, type RomAnalysisResult, RomDataReader, type RomHeaderInfo, RomProcessor, RomState, RomStateUtils, SfxReader, SpriteFrame, SpriteGroup, SpriteMap, SpritePart, Stack, StackOperations, StringReader, TransformProcessor, TypeParser, isPlatformBrowser, isPlatformNode, isPlatformWebWorker };
+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 };