@primitiv/core 0.19.0

package/dist/index.d.ts

@@ -0,0 +1,2421 @@
+import { Vector2, Order, PostProcessConfig, ScalingMode, RenderPassConfig, AmbientEffectConfig, GridConfig, ScanlinesConfig, AxisSource, ButtonSource, InputBindingLoadPacket, AxisBinding, ButtonBinding, TouchZoneBinding, MacroTemplate, MacroDefine, MacroOrder, MacroCreateOrder, MacroFeedback, BridgeMessage, CompressedInputPacket, AudioAck, SoundInstanceId, SoundFormat, SoundLoadType, SoundLoadPacket, SoundExternalLoadPacket, IResourceLoader, RenderPassState, CharOrder, TextOrder, TextMultilineOrder, SubFrameOrder, SubFrameMultiOrder, FullFrameOrder, FullFrameMultiOrder, SpriteOrder, SpriteMultiOrder, ColorMapCell, ShapeOrder, PolylineOrder, DotCloudOrder, DotCloudMultiOrder, SpriteCloudOrder, SpriteCloudMultiOrder, SpriteCloudVariedOrder, SpriteCloudVariedMultiOrder, BitmaskOrder, Bitmask4Order, Bitmask16Order, FillOrder, FillCharOrder, FillSpriteOrder, FillSpriteMultiOrder, AudioOrder, VibrationOrder } from '@primitiv/types';
+
+/**
+ * Primitiv Core - Grid Primitive
+ */
+/**
+ * Optimized 2D buffer using a single Uint32Array for performance.
+ *
+ * Storage Format (32-bit Packed Integer):
+ * - Bits 0-15  (16 bits): CharCode (0-65535)
+ * - Bits 16-23 (8 bits):  Foreground Color (0-255)
+ * - Bits 24-31 (8 bits):  Background Color (0-255)
+ *
+ * Example:
+ * [ BG (8) | FG (8) | CHAR (16) ]
+ *
+ * This allows:
+ * - Atomic reads/writes (1 ops vs 3)
+ * - Fast comparison (dirty checks)
+ * - Zero-allocation updates
+ */
+declare class Grid {
+    readonly width: number;
+    readonly height: number;
+    readonly size: number;
+    readonly data: Uint32Array;
+    constructor(width: number, height: number);
+    /**
+     * Clear the grid with empty cells (BG: COLOR_SKIP, FG: COLOR_SKIP, Char: 0)
+     */
+    clear(): void;
+    /**
+     * Fill the entire grid with a specific char/color
+     */
+    fill(charCode: number, fg: number, bg: number): void;
+    /**
+     * Set a cell with bounds checking (Safe version for rasterization)
+     */
+    setSafe(x: number, y: number, charCode: number, fg: number, bg: number): void;
+    /**
+     * Set a single cell (Atomic)
+     * @param index Array index (y * width + x)
+     * @param charCode 16-bit char code
+     * @param fg 8-bit foreground color
+     * @param bg 8-bit background color
+     */
+    set(index: number, charCode: number, fg: number, bg: number): void;
+    /**
+     * Set a single cell using packed value
+     */
+    setPacked(index: number, value: number): void;
+    /**
+     * Get packed cell value
+     */
+    get(index: number): number;
+    /**
+     * Unpack a cell at index into components
+     * Useful for rendering or debugging
+     */
+    unpack(index: number): {
+        char: number;
+        fg: number;
+        bg: number;
+    };
+    /**
+     * Create a clone of this grid
+     */
+    clone(): Grid;
+}
+
+/**
+ * Static helpers for cell bitwise operations without object overhead.
+ */
+declare class CellStruct {
+    /**
+     * Pack components into a 32-bit integer
+     */
+    static pack(char: number, fg: number, bg: number): number;
+    /**
+     * Extract CharCode (Bits 0-15)
+     */
+    static getChar(cell: number): number;
+    /**
+     * Extract Foreground Color (Bits 16-23)
+     */
+    static getFg(cell: number): number;
+    /**
+     * Extract Background Color (Bits 24-31)
+     */
+    static getBg(cell: number): number;
+}
+
+/**
+ * Structure of Sprite objects in Primitives
+ */
+/**
+ * Unicolor sprite - Stores only charcodes.
+ * Colors (fg/bg) are defined at render time via SpriteOrder.
+ */
+interface UnicolorSprite {
+    id: number;
+    width: number;
+    height: number;
+    data: Uint16Array;
+}
+/**
+ * Multicolor sprite - Stores charcodes + fg/bg colors.
+ * Each cell contains its own complete set of attributes.
+ * The data buffer format must match the Grid (packed 32-bit: BG|FG|Char).
+ */
+interface MulticolorSprite {
+    id: number;
+    width: number;
+    height: number;
+    data: Uint32Array;
+}
+/**
+ * Definition for creating a Unicolor Sprite (friendly format)
+ */
+interface UnicolorSpriteDefinition {
+    spriteId: number;
+    width: number;
+    height: number;
+    data: string | string[] | number[];
+}
+/**
+ * Definition for creating a Multicolor Sprite (friendly format)
+ * Not implementing fully yet as we need to define the Cell input format
+ */
+interface MulticolorSpriteDefinition {
+    spriteId: number;
+    width: number;
+    height: number;
+    data: any[];
+}
+
+/**
+ * SpriteRegistry
+ * Central registry to manage unicolor and multicolor sprites.
+ * Adapted for Primitiv Core V6 (Uint32Array / Uint16Array based).
+ */
+declare class SpriteRegistry {
+    private unicolorSprites;
+    private multicolorSprites;
+    /**
+     * Loads unicolor sprites from public definitions
+     * Supports strings, string arrays, and numbers
+     */
+    loadUnicolorSprites(definitions: UnicolorSpriteDefinition[]): void;
+    /**
+     * Loads multicolor sprites from public definitions
+     */
+    loadMulticolorSprites(definitions: MulticolorSpriteDefinition[]): void;
+    getUnicolorSprite(id: number): UnicolorSprite | undefined;
+    getMulticolorSprite(id: number): MulticolorSprite | undefined;
+    hasUnicolorSprite(id: number): boolean;
+    hasMulticolorSprite(id: number): boolean;
+    clearAll(): void;
+}
+
+type CharCodeMode = '8bit' | '16bit';
+/**
+ * Layer configuration options.
+ */
+interface LayerOptions {
+    /** Optional layer name for tooling/debug. */
+    name?: string;
+    /**
+     * CharCode mode for this layer (immutable after creation)
+     * - '8bit': 256 char codes (CP437 default)
+     * - '16bit': 65536 char codes (256 atlas blocks × 256 chars)
+     * @default '8bit'
+     */
+    charCodeMode?: CharCodeMode;
+    /**
+     * If true, the layer is sent on the reliable channel.
+     * @default false
+     */
+    mustBeReliable?: boolean;
+    /**
+     * If true, the layer is considered a macro layer (ephemeral, local effects).
+     * @default false
+     */
+    isMacroLayer?: boolean;
+}
+/**
+ * Layer State
+ * Represents a renderable surface in the world.
+ * Wraps a Grid with positioning and composition properties.
+ */
+declare class Layer {
+    id: number;
+    grid: Grid;
+    x: number;
+    y: number;
+    private origin;
+    zIndex: number;
+    visible: boolean;
+    private name?;
+    private isMacroLayer;
+    private width;
+    private height;
+    private mustBeReliable;
+    private spriteRegistry?;
+    readonly charCodeMode: CharCodeMode;
+    /** Pre-computed flag: true when charCodeMode is '16bit' (avoids string comparison per tick) */
+    readonly is16bit: boolean;
+    private pendingOrders;
+    private ordersUpdatedThisTick;
+    private enabled;
+    private needsCommit;
+    private static rasterizer;
+    /**
+     * Creates a new layer.
+     *
+     * @param origin - Layer origin in world space.
+     * @param zOrder - Z-order for stacking (higher = on top).
+     * @param width - Layer width in cells (1-256).
+     * @param height - Layer height in cells (1-256).
+     * @param options - Layer options.
+     */
+    constructor(origin: Vector2, zOrder: number, width: number, height: number, options?: LayerOptions | boolean);
+    /**
+     * Explicitly set the layer ID.
+     * Needed because the constructor no longer takes an ID.
+     */
+    setId(id: number): void;
+    /**
+     * Injects the SpriteRegistry into the layer.
+     * Required for sprite-dependent orders (Sprite, SpriteCloud, FillSprite, etc.)
+     * @internal
+     */
+    setSpriteRegistry(registry: SpriteRegistry): void;
+    /**
+     * Resize the layer (clears content)
+     */
+    resize(width: number, height: number): void;
+    getMustBeReliable(): boolean;
+    getName(): string | undefined;
+    getIsMacroLayer(): boolean;
+    getWidth(): number;
+    getHeight(): number;
+    getOrigin(): Vector2;
+    /**
+     * Sets the layer origin in world space.
+     * Marks the layer as needing commit so the new position is transmitted.
+     */
+    setOrigin(origin: Vector2): void;
+    /**
+     * Sets the layer name (debug/metadata).
+     * Trims whitespace; empty string clears the name.
+     */
+    setName(name: string | undefined): void;
+    /**
+     * Enables or disables the layer.
+     * The enabled state is transmitted over the network so the client
+     * hides/shows the layer accordingly.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Sets the z-index (stacking order).
+     * Marks the layer as needing commit so the new z-index is transmitted.
+     */
+    setZIndex(zIndex: number): void;
+    /**
+     * Marks this layer as reliable or volatile for network transport.
+     */
+    setMustBeReliable(reliable: boolean): void;
+    /**
+     * Returns the cell at the given coordinates (unpacked).
+     *
+     * @param x - X coordinate (0..width-1).
+     * @param y - Y coordinate (0..height-1).
+     * @returns The unpacked cell `{ char, fg, bg }` or `null` if out of bounds.
+     */
+    getCellAt(x: number, y: number): {
+        char: number;
+        fg: number;
+        bg: number;
+    } | null;
+    /**
+     * UTSP Parity: Set orders for this layer.
+     * Stores orders for serialization AND rasterizes into the grid.
+     */
+    setOrders(orders: Order[]): void;
+    /**
+     * Get pending orders (for serialization by TickPacketEncoder).
+     */
+    getPendingOrders(): Order[];
+    /**
+     * Clear pending orders after serialization.
+     * Called by Engine.endTick() after encoding.
+     */
+    clearPendingOrders(): void;
+    /**
+     * Returns true if setOrders() was called this tick (even with empty array).
+     * Used by TickPacketEncoder to determine FLAG_HAS_ORDERS.
+     */
+    getOrdersUpdatedThisTick(): boolean;
+    /**
+     * Marks the layer as needing to be sent to clients.
+     *
+     * **Note:** You typically do NOT need to call this method.
+     * All setters (`setOrders()`, `setOrigin()`, `setEnabled()`, `setZIndex()`)
+     * already mark the layer for commit automatically.
+     *
+     * This method is only useful for:
+     * - Force resync: sending a layer's current state even if unchanged this tick
+     * - Internal use after direct grid manipulation (not recommended)
+     */
+    commit(): void;
+    getNeedsCommit(): boolean;
+    /**
+     * Clear the commit flag after endTick processing.
+     */
+    clearCommit(): void;
+    isEnabled(): boolean;
+    /**
+     * Returns a debug-friendly snapshot of this layer (metadata only).
+     */
+    getDebugInfo(): {
+        id: number;
+        name?: string;
+        zIndex: number;
+        origin: {
+            x: number;
+            y: number;
+        };
+        width: number;
+        height: number;
+        visible: boolean;
+        enabled: boolean;
+        mustBeReliable: boolean;
+        isMacroLayer: boolean;
+        charCodeMode: CharCodeMode;
+        needsCommit: boolean;
+        ordersCount: number;
+    };
+}
+
+/**
+ * Display State
+ * Represents a Viewport (Camera) into the world.
+ * Does NOT contain logic, only state.
+ */
+declare class Display {
+    readonly id: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    cellWidth: number;
+    cellHeight: number;
+    pixelWidth: number;
+    pixelHeight: number;
+    postProcess: PostProcessConfig;
+    scalingMode: ScalingMode;
+    activePaletteSlot: number;
+    renderPasses: RenderPassConfig[] | undefined;
+    constructor(id: number, width: number, height: number);
+    /**
+     * Move the camera to a specific position
+     */
+    teleport(x: number, y: number): void;
+    /**
+     * Resize the viewport (cell dimensions).
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Resize the viewport using a Vector2 (cell dimensions).
+     * Alias for `resize(size.x, size.y)`.
+     */
+    setSize(size: Vector2): void;
+    /**
+     * Store the client's pixel viewport dimensions.
+     * Called by the runtime when the client reports its screen size.
+     * @internal
+     */
+    setPixelViewport(pixelWidth: number, pixelHeight: number): void;
+    /**
+     * Calculate the maximum number of cells that fit in the client's pixel viewport
+     * for the given cell size. Uses the stored pixelWidth/pixelHeight.
+     *
+     * @param cellW - Cell width in pixels (defaults to this.cellWidth).
+     * @param cellH - Cell height in pixels (defaults to this.cellHeight).
+     * @returns `{ cols, rows }` clamped to [1, 256], or `null` if no pixel viewport is known.
+     */
+    calculateMaxCells(cellW?: number, cellH?: number): {
+        cols: number;
+        rows: number;
+    } | null;
+    /**
+     * Set cell pixel dimensions.
+     * Clamped to [1, 255]. Affects canvas resolution and Responsive grid calculation.
+     */
+    setCellSize(width: number, height: number): void;
+    /**
+     * Get cell pixel dimensions.
+     */
+    getCellSize(): {
+        cellWidth: number;
+        cellHeight: number;
+    };
+    /**
+     * Set scaling mode.
+     */
+    setScalingMode(mode: ScalingMode): void;
+    /**
+     * Set ambient (CRT/Blur) effects.
+     */
+    setAmbientEffect(config: boolean | Partial<AmbientEffectConfig>): void;
+    /**
+     * Set grid overlay (debug cell delimitation).
+     */
+    setGrid(config: boolean | Partial<GridConfig>): void;
+    /**
+     * Move the camera by a delta (relative movement).
+     *
+     * @param deltaX - Delta X in world cells.
+     * @param deltaY - Delta Y in world cells.
+     */
+    moveOrigin(deltaX: number, deltaY: number): void;
+    /**
+     * Set scanlines configuration.
+     * Pass `true` to enable with defaults, `false` to disable,
+     * or a partial config to merge.
+     */
+    setScanlines(config: boolean | Partial<ScanlinesConfig>): void;
+    /**
+     * Enable or disable scanlines.
+     */
+    setScanlinesEnabled(enabled: boolean): void;
+    /**
+     * Set scanlines opacity (0..1).
+     */
+    setScanlinesOpacity(opacity: number): void;
+    /**
+     * Enable or disable the grid overlay.
+     */
+    setGridEnabled(enabled: boolean): void;
+    /**
+     * Enable or disable the ambient effect.
+     */
+    setAmbientEffectEnabled(enabled: boolean): void;
+    /**
+     * Set post-processing effects.
+     */
+    setPostProcess(config: PostProcessConfig | null): void;
+    /**
+     * Set origin (top-left of viewport).
+     */
+    setOrigin(origin: Vector2): void;
+    /**
+     * Get origin (top-left of viewport).
+     * Backward-compatible helper.
+     */
+    getOrigin(): Vector2;
+    /**
+     * Get viewport size.
+     * Backward-compatible helper.
+     */
+    getSize(): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Switch palette slot.
+     */
+    switchPalette(slotId: number): void;
+    /**
+     * Set render passes for multi-pass compositing (max 4).
+     * Each pass filters layers by Z-range.
+     * Pass `undefined` or empty array to reset to the default single pass.
+     */
+    setRenderPasses(passes: RenderPassConfig[] | undefined): void;
+    /**
+     * Get the current render pass configuration.
+     */
+    getRenderPasses(): RenderPassConfig[] | undefined;
+    private normalizePass;
+    /**
+     * Returns a debug-friendly snapshot of this display (metadata only).
+     */
+    getDebugInfo(): {
+        id: number;
+        origin: {
+            x: number;
+            y: number;
+        };
+        size: {
+            width: number;
+            height: number;
+        };
+        pixelViewport: {
+            pixelWidth: number;
+            pixelHeight: number;
+        };
+        cellSize: {
+            cellWidth: number;
+            cellHeight: number;
+        };
+        scalingMode: ScalingMode;
+        activePaletteSlot: number;
+        postProcess: PostProcessConfig;
+        renderPasses?: RenderPassConfig[];
+    };
+}
+
+/**
+ * InputBindingRegistry - Registry for logical axes and buttons.
+ *
+ * This registry is shared between client and server to ensure consistent input decoding.
+ * The server defines the bindings and sends them to the client via a JSON LoadPacket.
+ * Both sides use this registry to evaluate raw source values into logical actions.
+ */
+declare class InputBindingRegistry {
+    private axes;
+    private buttons;
+    private touchZones;
+    private axisNameToId;
+    private buttonNameToId;
+    private touchZoneNameToId;
+    private version;
+    private _axesSortedCache;
+    private _buttonsSortedCache;
+    private _touchZonesSortedCache;
+    defineAxis(bindingId: number, name: string, sources?: AxisSource[], min?: number, max?: number, defaultValue?: number): void;
+    defineButton(bindingId: number, name: string, sources?: ButtonSource[], defaultValue?: boolean): void;
+    defineTouchZone(zoneId: number, name: string, x: number, y: number, width: number, height: number): void;
+    /**
+     * Evaluates an axis by summing all its sources.
+     *
+     * @param bindingId - Axis binding ID
+     * @param sourceValues - Map of raw source values (sourceId -> value)
+     * @returns Final axis value (clamped)
+     */
+    evaluateAxis(bindingId: number, sourceValues: Map<number, number>): number;
+    /**
+     * Evaluates a button with OR logic (pressed if any source is pressed).
+     */
+    evaluateButton(bindingId: number, sourceValues: Map<number, boolean>): boolean;
+    toLoadPacket(): InputBindingLoadPacket;
+    /**
+     * Rebuild this registry from a previously serialised `InputBindingLoadPacket`.
+     *
+     * Clears any existing bindings first, then re-registers every axis,
+     * button, and touch zone contained in the packet.
+     */
+    loadFromPacket(packet: InputBindingLoadPacket): void;
+    getAllAxes(): AxisBinding[];
+    getAllButtons(): ButtonBinding[];
+    getAllTouchZones(): TouchZoneBinding[];
+    getAxisCount(): number;
+    getButtonCount(): number;
+    getAxisId(name: string): number | null;
+    getButtonId(name: string): number | null;
+    clear(): void;
+}
+
+interface MacroInstanceState {
+    instanceId: number;
+    templateId: number;
+    layerId: number;
+    x: number;
+    y: number;
+    zIndex: number;
+    params: Record<string, unknown>;
+    state: 'running' | 'paused';
+}
+interface CreateInstanceConfig {
+    /** Template name (resolved to templateId internally) */
+    macro: string;
+    /** Target layer ID */
+    layer: number;
+    /** Position in cell coordinates on the layer */
+    x: number;
+    y: number;
+    /** Z-index within the macro layer (for multi-instance ordering) */
+    zIndex?: number;
+    /** Instance name (for later reference by name) */
+    name?: string;
+    /** Runtime parameters (merged with template defaults) */
+    params?: Record<string, unknown>;
+}
+declare class MacroRegistry {
+    private templates;
+    private templateNameToId;
+    private nextTemplateId;
+    private instances;
+    private instanceNameToId;
+    private nextInstanceId;
+    private pendingDefines;
+    private pendingOrders;
+    private feedbackHandlers;
+    registerTemplate(name: string, template: MacroTemplate): number;
+    getTemplate(idOrName: number | string): MacroTemplate | undefined;
+    getTemplateId(name: string): number | undefined;
+    createInstance(config: CreateInstanceConfig): number;
+    updateInstance(nameOrId: number | string, params: Record<string, unknown>): void;
+    removeInstance(nameOrId: number | string): void;
+    pauseInstance(nameOrId: number | string): void;
+    resumeInstance(nameOrId: number | string): void;
+    getPendingDefines(): MacroDefine[];
+    getPendingOrders(): MacroOrder[];
+    clearPendingDefines(): void;
+    clearPendingOrders(): void;
+    getAllDefines(): MacroDefine[];
+    getActiveInstanceOrders(): MacroCreateOrder[];
+    onEvent(nameOrId: number | string, event: string, handler: (data?: unknown) => void): void;
+    handleFeedback(feedback: MacroFeedback): void;
+    private resolveInstanceId;
+}
+
+/**
+ * User
+ * Represents a user connected to the Primitiv Engine.
+ * Owns a set of Layers and Displays (Viewports).
+ * Holds the current input state (axes, buttons, mouse).
+ * Collects imperative commands (Audio, Vibration) for the current tick.
+ *
+ * @typeParam TData - Custom per-user data state.
+ */
+declare class User<TData = any> {
+    readonly id: string;
+    readonly name: string;
+    /** Custom persistent state for this user */
+    data: TData;
+    /**
+     * Incoming bridge messages from the remote peer (client or server).
+     *
+     * Populated between ticks by the runtime. Read during `updateUser()` to
+     * process messages synchronised with the game tick. The runtime clears the
+     * inbox automatically after `updateUser()` completes.
+     */
+    bridgeInbox: BridgeMessage[];
+    private _loadedSounds;
+    private _soundLoadErrors;
+    private _playingSounds;
+    /**
+     * Whether this user's browser tab is hidden.
+     * Set by the runtime when a visibility-change message is received.
+     * Used by RuntimeServer to skip sending updates to inactive clients.
+     */
+    isTabHidden: boolean;
+    private layers;
+    private displays;
+    private nextLayerId;
+    private _layersCache;
+    private _displaysCache;
+    private spriteRegistry?;
+    private macroRegistry;
+    private commandQueue;
+    private _commandQueueSwap;
+    private nextSoundInstanceId;
+    private axes;
+    private buttons;
+    private justPressed;
+    private justReleased;
+    mouseX: number;
+    mouseY: number;
+    activeDisplay: number;
+    mouseOver: boolean;
+    constructor(id: string, name: string);
+    /**
+     * Inject the sprite registry into this user.
+     * Called by the runtime after creation so layers can rasterize sprites.
+     * @internal
+     */
+    setSpriteRegistry(registry: SpriteRegistry): void;
+    /**
+     * Alias for createLayer for better readability in application code.
+     * Auto-assigns a unique numeric ID to the layer (like UTSP).
+     */
+    addLayer(layer: Layer, _id?: string): void;
+    /**
+     * Alias for createDisplay for better readability.
+     */
+    addDisplay(display: Display): void;
+    /**
+     * Returns a summary of mouse position info relative to the local display.
+     */
+    getMouseDisplayInfo(): {
+        localX: number;
+        localY: number;
+        displayId: number;
+    } | null;
+    /**
+     * Backward-compatible alias for touch display info.
+     * Uses unified pointer state (mouse/touch) tracked on the active display.
+     */
+    getTouchDisplayInfo(displayId?: number): {
+        localX: number;
+        localY: number;
+        displayId: number;
+    } | null;
+    /**
+     * Get viewport info for a display, including pixel dimensions
+     * reported by the client.
+     */
+    getDisplayViewport(displayId: number): {
+        id: number;
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        pixelWidth: number;
+        pixelHeight: number;
+        origin: {
+            x: number;
+            y: number;
+        };
+        size: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    } | null;
+    /**
+     * Calculate the maximum number of cells that fit in the client's pixel viewport
+     * for the given cell size. Delegates to Display.calculateMaxCells().
+     *
+     * @param displayId - Display ID.
+     * @param cellW - Cell width in pixels.
+     * @param cellH - Cell height in pixels.
+     */
+    calculateMaxCells(displayId: number, cellW: number, cellH: number): {
+        cols: number;
+        rows: number;
+    } | null;
+    private inputRegistry;
+    /**
+     * Get binding registry for application specific input definitions.
+     */
+    getInputBindingRegistry(): InputBindingRegistry;
+    /**
+     * Updates the user state from a binary input packet.
+     * This is called on the server when receiving a packet,
+     * or on the client after hardware sampling.
+     */
+    applyInput(packet: CompressedInputPacket, registry: InputBindingRegistry): void;
+    /**
+     * Clears one-frame transitions and command queues.
+     * Should be called at the end of the engine update.
+     */
+    poll(): void;
+    /**
+     * Play a sound for this user.
+     * Queues an AudioOrder for the next network update.
+     */
+    playSound(sound: string | number, options?: {
+        volume?: number;
+        pitch?: number;
+        loop?: boolean;
+        fadeIn?: number;
+        x?: number;
+        y?: number;
+        lowpass?: number;
+        highpass?: number;
+        reverb?: number;
+    }): number;
+    /**
+     * Stop a sound immediately by instance ID or name.
+     */
+    stopSound(target: number | string): void;
+    /**
+     * Stop all sounds immediately.
+     */
+    stopAllSounds(): void;
+    /**
+     * Fade out a sound over a duration (seconds).
+     */
+    fadeOutSound(target: number | string, duration: number): void;
+    /**
+     * Fade out all sounds over a duration (seconds).
+     */
+    fadeOutAllSounds(duration: number): void;
+    /**
+     * Pause a specific sound instance.
+     */
+    pauseSound(target: number | string): void;
+    /**
+     * Pause all sounds.
+     */
+    pauseAllSounds(): void;
+    /**
+     * Resume a specific sound instance.
+     */
+    resumeSound(target: number | string): void;
+    /**
+     * Resume all sounds.
+     */
+    resumeAllSounds(): void;
+    /**
+     * Set audio effects (lowpass, highpass, reverb) on a playing sound instance.
+     */
+    setSoundEffects(instanceId: number, options: {
+        lowpass?: number;
+        highpass?: number;
+        reverb?: number;
+        pitch?: number;
+        volume?: number;
+    }): void;
+    /**
+     * Set the listener position for 2D spatial audio.
+     */
+    setListenerPosition(x: number, y: number): void;
+    /**
+     * Configure spatial audio parameters.
+     */
+    configureSpatialAudio(config: {
+        maxDistance?: number;
+        referenceDistance?: number;
+        rolloffFactor?: number;
+        panSpread?: number;
+    }): void;
+    /**
+     * Signal that all registered sounds should be sent to this user's client.
+     * In standalone mode, this triggers loading sounds into the AudioEngine's SoundBank.
+     */
+    sendSounds(): void;
+    /** @internal */
+    _pendingSendSounds: boolean;
+    /**
+     * Trigger a vibration on the user's device (mobile).
+     */
+    vibrate(pattern: number | number[]): void;
+    /**
+     * Trigger a dual-rumble vibration on the user's gamepad.
+     *
+     * @param options Vibration parameters (duration, motors, gamepad index).
+     *
+     * @example
+     * ```ts
+     * // Heavy hit on first gamepad
+     * user.vibrateGamepad({ duration: 200, strongMagnitude: 1.0, weakMagnitude: 0.3 });
+     *
+     * // Light buzz on second gamepad
+     * user.vibrateGamepad({ duration: 100, strongMagnitude: 0, weakMagnitude: 0.8, gamepadIndex: 1 });
+     * ```
+     */
+    vibrateGamepad(options: {
+        duration: number;
+        strongMagnitude?: number;
+        weakMagnitude?: number;
+        startDelay?: number;
+        gamepadIndex?: number;
+    }): void;
+    /**
+     * Update post-processing effects for a specific display.
+     */
+    setPostProcess(displayId: number, config: PostProcessConfig | null): void;
+    setAmbientEffect(displayId: number, config: boolean | Partial<AmbientEffectConfig>): void;
+    setGrid(displayId: number, config: boolean | Partial<GridConfig>): void;
+    setScalingMode(displayId: number, mode: ScalingMode): void;
+    switchPalette(displayId: number, slotId: number): void;
+    setOrigin(displayId: number, origin: Vector2): void;
+    /**
+     * Returns and clears the current command queue.
+     * Internal use for synchronization.
+     */
+    flushCommands(): Order[];
+    getAxis(name: string): number;
+    getButton(name: string): boolean;
+    isJustPressed(name: string): boolean;
+    isJustReleased(name: string): boolean;
+    createLayer(id: number, width: number, height: number): Layer;
+    getLayer(id: number): Layer | undefined;
+    removeLayer(id: number): boolean;
+    getLayers(): Layer[];
+    createDisplay(id: number, width: number, height: number): Display;
+    getDisplay(id: number): Display | undefined;
+    removeDisplay(id: number): boolean;
+    getDisplays(): Display[];
+    defineButton(bindingId: number, name: string, sources: ButtonSource[], defaultValue?: boolean): void;
+    defineAxis(bindingId: number, name: string, sources: AxisSource[], min?: number, max?: number, defaultValue?: number): void;
+    /**
+     * Process an audio acknowledgment from this user's client.
+     *
+     * Called automatically by the runtime when the client reports audio events.
+     * Updates internal tracking maps so the application can query state at any
+     * time via `isSoundLoaded()`, `isSoundPlaying()`, etc.
+     *
+     * @internal
+     */
+    handleAudioAck(ack: AudioAck): void;
+    /** Check whether a sound (by soundId) is loaded on this user's client. */
+    isSoundLoaded(soundId: number): boolean;
+    /** Get all loaded sounds for this user. */
+    getLoadedSounds(): ReadonlyMap<number, {
+        name: string;
+        loadedAt: number;
+    }>;
+    /** Get the load error for a specific sound, if any. */
+    getSoundLoadError(soundId: number): string | undefined;
+    /** Get all sound load errors for this user. */
+    getSoundLoadErrors(): ReadonlyMap<number, {
+        name: string;
+        error: string;
+        at: number;
+    }>;
+    /** Check whether a sound instance is currently playing on this user's client. */
+    isSoundPlaying(instanceId: SoundInstanceId): boolean;
+    /** Get all currently playing sound instances for this user. */
+    getPlayingSounds(): ReadonlyMap<SoundInstanceId, {
+        soundId: number;
+        startedAt: number;
+    }>;
+    /** Get the number of sound instances currently playing on this user's client. */
+    getPlayingSoundCount(): number;
+    /** Injected by Engine.createUser() */
+    setMacroRegistry(registry: MacroRegistry): void;
+    /** Get the macro registry (used by encoder to gather pending orders/defines). */
+    getMacroRegistry(): MacroRegistry | null;
+    /**
+     * Load a macro template. Call during initUser().
+     * Returns the templateId for reference.
+     */
+    loadMacro(name: string, template: MacroTemplate): number;
+    /** Create a macro instance on a macro layer. */
+    createMacroInstance(config: {
+        macro: string;
+        layer: number;
+        x: number;
+        y: number;
+        zIndex?: number;
+        name?: string;
+        params?: Record<string, unknown>;
+    }): number;
+    updateMacroInstance(nameOrId: number | string, params: Record<string, unknown>): void;
+    removeMacroInstance(nameOrId: number | string): void;
+    pauseMacroInstance(nameOrId: number | string): void;
+    resumeMacroInstance(nameOrId: number | string): void;
+    /** Register a handler for macro feedback from the client. */
+    onMacroEvent(nameOrId: number | string, event: string, handler: (data?: unknown) => void): void;
+    /** Handle macro feedback received from ClientCallback. */
+    handleMacroFeedback(feedback: MacroFeedback): void;
+}
+
+/**
+ * UserUpdateBuilder
+ *
+ * Serializes UserSession state and commands into a binary update packet.
+ * Currently focuses on imperative commands (Audio, Vibration).
+ */
+declare class UserUpdateBuilder {
+    private buffer;
+    private view;
+    private offset;
+    private textEncoder;
+    constructor(initialSize?: number);
+    /**
+     * Serializes the session's pending commands into a binary payload.
+     * Note: This does not yet serialize the Grid/Layer state, only the command queue.
+     */
+    serialize(session: User): Uint8Array;
+    private writeOrder;
+    private writeAudioOrder;
+    private writeVibrationOrder;
+    private writePostProcessOrder;
+    private ensureCapacity;
+    private writeUint8;
+    private writeUint16;
+    private writeInt16;
+    private writeString;
+}
+
+/**
+ * UserUpdateParser
+ *
+ * Deserializes binary update packets into User state and commands.
+ * Currently focuses on imperative commands (Audio, Vibration).
+ */
+declare class UserUpdateParser {
+    private textDecoder;
+    /**
+     * Parses a binary update payload into a list of Orders.
+     */
+    parse(payload: Uint8Array): Order[];
+    private parseOrder;
+    private parseAudioOrder;
+    private parseVibrationOrder;
+    private parsePostProcessOrder;
+}
+
+/**
+ * Encodes a CompressedInputPacket into a self-describing binary buffer.
+ *
+ * Binary layout:
+ *   [axisCount(1), buttonCount(1),
+ *    axes(N × (bindingId:uint16 + value:int8) = 3 bytes each),
+ *    buttonBindingIds(M × uint16), buttonValues(ceil(M/8) bytes bitpacked),
+ *    displayId(1), mouseX(1), mouseY(1), flags(1),
+ *    textInputs(variable), viewports(variable), touches(variable)]
+ *
+ * The 2-byte header (axisCount, buttonCount) makes the format self-describing
+ * so the decoder does not need an external registry to know the field counts.
+ * BindingIds are preserved to ensure correct input mapping after decode.
+ */
+declare function encodeCompressedInput(packet: CompressedInputPacket): Uint8Array;
+/**
+ * Decodes a self-describing binary buffer into a CompressedInputPacket.
+ *
+ * Axis and button counts are read from the 2-byte header, so no external
+ * registry is needed to parse the packet. BindingIds are preserved from
+ * the encoded data to ensure correct input mapping.
+ */
+declare function decodeCompressedInput(buffer: Uint8Array, _registry?: InputBindingRegistry): CompressedInputPacket;
+
+/**
+ * Font system for Primitiv Core
+ * Supports BitmapFont (pixel-based) and ImageFont (PNG atlas-based)
+ */
+/**
+ * Font type enumeration
+ */
+declare enum FontType {
+    Bitmap = "bitmap",
+    Image = "image"
+}
+/**
+ * Number of 256-char blocks in an atlas
+ * Must be a power of two from 1 to 256.
+ * - 1 block  = 256 chars   (128×128 @ 8px)
+ * - 2 blocks = 512 chars   (256×128 @ 8px)
+ * - 4 blocks = 1024 chars  (256×256 @ 8px)
+ * - 256 blocks = 65536 chars (2048×2048 @ 8px)
+ */
+type AtlasBlocks = 1 | 2 | 4 | 8 | 16 | 32 | 64 | 128 | 256;
+/**
+ * Glyph size in pixels (uniform within an atlas)
+ */
+type GlyphSize = 8 | 16 | 32;
+/**
+ * Atlas grid layout computed from block count.
+ * The atlas may be rectangular (cols ≠ rows).
+ */
+interface AtlasLayout {
+    /** Number of character columns (blocksPerRow × 16) */
+    cols: number;
+    /** Number of character rows (blocksPerCol × 16) */
+    rows: number;
+    /** Number of blocks per row */
+    blocksPerRow: number;
+    /** Number of block rows */
+    blocksPerCol: number;
+}
+/**
+ * Return the smallest power of two ≥ n (n must be > 0).
+ */
+declare function nextPow2(n: number): number;
+/**
+ * Compute the atlas grid layout for a given block count.
+ * Both blocksPerRow and blocksPerCol are powers of two.
+ */
+declare function getAtlasLayout(blocks: number): AtlasLayout;
+/**
+ * Get the number of columns in an atlas grid
+ * @param blocks Number of atlas blocks (1, 4, or 16)
+ * @returns Number of columns (16, 32, or 64)
+ */
+declare function getAtlasColumns(blocks: AtlasBlocks): number;
+/**
+ * Get the number of rows in an atlas grid
+ * @param blocks Number of atlas blocks
+ * @returns Number of rows
+ */
+declare function getAtlasRows(blocks: AtlasBlocks): number;
+/**
+ * Get the maximum character code for an atlas configuration
+ * @param blocks Number of atlas blocks
+ * @returns Maximum charCode (blocks * 256 - 1)
+ */
+declare function getMaxCharCode(blocks: AtlasBlocks): number;
+/**
+ * Get atlas texture dimensions in pixels.
+ * Each block occupies 16 × nextPow2(glyphWidth) by 16 × nextPow2(glyphHeight),
+ * so the overall atlas is always PoT.
+ *
+ * @param blocks Number of atlas blocks
+ * @param glyphWidth Width of each glyph in pixels
+ * @param glyphHeight Height of each glyph in pixels (defaults to glyphWidth)
+ * @returns Atlas dimensions { width, height }
+ */
+declare function getAtlasDimensions(blocks: AtlasBlocks, glyphWidth: number, glyphHeight?: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Options for loading an ImageFont
+ */
+interface ImageFontOptions {
+    /** Width of each glyph in pixels (8, 16, or 32) */
+    glyphWidth: number;
+    /** Height of each glyph in pixels (8, 16, or 32) */
+    glyphHeight: number;
+    /** Target cell width for rendering (default: glyphWidth) */
+    cellWidth?: number;
+    /** Target cell height for rendering (default: glyphHeight) */
+    cellHeight?: number;
+    /** Number of 256-char blocks (power of two, 1-256) */
+    atlasBlocks?: AtlasBlocks;
+}
+/**
+ * ImageFont configuration
+ * For PNG atlas-based fonts with pre-rendered glyphs
+ */
+interface ImageFontConfig {
+    glyphWidth: number;
+    glyphHeight: number;
+    cellWidth?: number;
+    cellHeight?: number;
+    atlasBlocks: AtlasBlocks;
+}
+/**
+ * ImageFont class
+ * Represents a PNG atlas-based font for extended character sets
+ */
+declare class ImageFont {
+    private fontId;
+    private config;
+    private readonly atlasColumns;
+    private readonly atlasRows;
+    private readonly maxCharCode;
+    private blocks;
+    constructor(fontId: number, config: ImageFontConfig);
+    /**
+     * Add image data for a specific block
+     */
+    addBlock(blockIndex: number, data: Uint8Array): void;
+    /**
+     * Get image data for a specific block
+     */
+    getBlock(blockIndex: number): Uint8Array | undefined;
+    /**
+     * Get the unique font ID
+     */
+    getFontId(): number;
+    /**
+     * Get the full configuration
+     */
+    getConfig(): ImageFontConfig;
+    /**
+     * Get the glyph width in pixels
+     */
+    getGlyphWidth(): number;
+    /**
+     * Get the glyph height in pixels
+     */
+    getGlyphHeight(): number;
+    /**
+     * Get the target cell width in pixels (rendering size)
+     */
+    getCellWidth(): number;
+    /**
+     * Get the target cell height in pixels (rendering size)
+     */
+    getCellHeight(): number;
+    /**
+     * Get the number of atlas blocks
+     */
+    getAtlasBlocks(): AtlasBlocks;
+    /**
+     * Get the number of columns in the atlas grid
+     */
+    getAtlasColumns(): number;
+    /**
+     * Get the maximum supported charCode
+     */
+    getMaxCharCode(): number;
+    /**
+     * Get the number of rows in the atlas grid
+     */
+    getAtlasRows(): number;
+    /**
+     * Get the atlas dimensions in pixels.
+     * Uses effective (next-PoT) glyph size for PoT texture dimensions.
+     */
+    getAtlasDimensions(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Get UV coordinates for a character code.
+     *
+     * Glyphs are tightly packed within each block (no per-glyph padding).
+     * Blocks are positioned at PoT boundaries in the atlas.
+     * UV coordinates sample only the real glyph area.
+     *
+     * @param charCode Character code (0 to maxCharCode)
+     * @returns UV coordinates { u1, v1, u2, v2 } or null if out of range
+     */
+    getCharUV(charCode: number): {
+        u1: number;
+        v1: number;
+        u2: number;
+        v2: number;
+    } | null;
+    /**
+     * Check if a charCode is valid for this atlas
+     */
+    isValidCharCode(charCode: number): boolean;
+}
+
+/**
+ * Registry for managing ImageFont instances
+ * Each font is identified by a unique fontId (0-255) and a human-readable name
+ */
+declare class ImageFontRegistry {
+    private fonts;
+    private nameToId;
+    private nextId;
+    private allocateId;
+    /**
+     * Register a new ImageFont structure (no data)
+     */
+    registerFont(name: string, options: ImageFontOptions): number;
+    /**
+     * Unregister a font by name
+     */
+    unregisterFont(name: string): void;
+    /**
+     * Check if a font exists by name
+     */
+    hasFont(name: string): boolean;
+    /**
+     * Add a data block to an existing font
+     */
+    addBlock(fontId: number, blockIndex: number, data: Uint8Array): void;
+    getFont(fontId: number): ImageFont | undefined;
+    getFontByName(name: string): ImageFont | undefined;
+    getFontId(name: string): number | undefined;
+    /**
+     * Get all registered fonts
+     */
+    getAllFonts(): ImageFont[];
+    /**
+     * Get the human-readable name of a font by its ID
+     */
+    getFontName(fontId: number): string | undefined;
+}
+
+/**
+ * Internal representation of a registered sound
+ */
+interface SoundEntry {
+    soundId: number;
+    name: string;
+    loadType: SoundLoadType;
+    format: SoundFormat;
+    data?: Uint8Array;
+    url?: string;
+    size?: number;
+    checksum?: string;
+}
+/**
+ * SoundRegistry - Manages sound definitions on the server
+ */
+declare class SoundRegistry {
+    private sounds;
+    private nameToId;
+    private nextId;
+    /**
+     * Register a sound with embedded data (File mode)
+     */
+    registerFile(name: string, format: SoundFormat, data: Uint8Array): number;
+    /**
+     * Register an external sound (FileExternal mode)
+     */
+    registerExternal(name: string, format: SoundFormat, url: string, size?: number, checksum?: string): number;
+    get(idOrName: number | string): SoundEntry | undefined;
+    has(idOrName: number | string): boolean;
+    /**
+     * Generate load packets for all registered sounds
+     */
+    toLoadPackets(): Array<SoundLoadPacket | SoundExternalLoadPacket>;
+    private allocateId;
+    private addEntry;
+}
+
+interface TickPackets {
+    reliable: Uint8Array;
+    volatile: Uint8Array;
+}
+declare class TickPacketEncoder {
+    /**
+     * Encode a user's tick state into reliable + volatile packets.
+     */
+    static encode(user: User): TickPackets;
+    /**
+     * Encode the complete user state into a single packet (for LoadBundle).
+     *
+     * Unlike encode(), this includes ALL layers regardless of mustBeReliable
+     * and ignores the needsCommit flag - every layer is encoded.
+     * This is used to send the full initial state during the handshake.
+     */
+    static encodeFull(user: User, palettes?: Map<number, any[]>): Uint8Array;
+    private static encodePacket;
+    private static encodeAudioOrder;
+    private static encodeSoundTarget;
+    private static encodeVibrationOrder;
+    private static encodeMacroDefine;
+    private static encodeMacroOrder;
+    /**
+     * Encode PostProcessConfig into the binary stream.
+     *
+     * Format:
+     *   flags: u8  (bit0=ambientEffect, bit1=scanlines, bit2=grid)
+     *   If bit0: enabled(1) blur(1) scale×10(1) opacity×100(1)
+     *   If bit1: enabled(1) opacity×100(1) pattern(1) spacing(1) thickness(1) colorR(1) colorG(1) colorB(1)
+     *   If bit2: enabled(1) lineWidth×10(1) colorLen(1) color(utf8)
+     */
+    private static encodePostProcess;
+}
+
+/**
+ * EngineStats - Lightweight tick-level metrics for the Primitiv Engine.
+ *
+ * Tracks per-tick encoding cost (time, bytes, layer/cell/order counts)
+ * using a fixed-size ring buffer. Provides rolling averages and
+ * instantaneous snapshots with zero allocation in the hot path.
+ */
+/** Snapshot of engine metrics at query time. */
+interface EngineStatsSnapshot {
+    /** Total ticks encoded since engine start. */
+    totalTicks: number;
+    /** Duration of the last endTick() call (ms). */
+    lastTickDurationMs: number;
+    /** Rolling average of endTick() duration over the window (ms). */
+    avgTickDurationMs: number;
+    /** Peak endTick() duration within the window (ms). */
+    peakTickDurationMs: number;
+    /** Bytes produced by the last endTick() (reliable + volatile). */
+    lastTickBytes: number;
+    /** Rolling average bytes per tick. */
+    avgTickBytes: number;
+    /** Number of layers encoded in the last tick. */
+    lastLayerCount: number;
+    /** Number of draw orders encoded in the last tick. */
+    lastOrderCount: number;
+    /** Number of display cells composited in the last tick. */
+    lastCellCount: number;
+    /** Number of displays encoded in the last tick. */
+    lastDisplayCount: number;
+}
+/**
+ * Collects per-tick metrics in a fixed-size ring buffer.
+ *
+ * Usage (called by Engine.endTick internals):
+ *   stats.beginTick();
+ *   // … encode …
+ *   stats.endTick({ bytes, layers, orders, cells, displays });
+ */
+declare class EngineStats {
+    private readonly samples;
+    private head;
+    private count;
+    private readonly windowSize;
+    /** Monotonically increasing tick counter. */
+    totalTicks: number;
+    private _t0;
+    constructor(windowSize?: number);
+    /** Call immediately before encoding begins. */
+    beginTick(): void;
+    /** Call immediately after encoding finishes with the tick's counters. */
+    endTick(counters: {
+        bytes: number;
+        layers: number;
+        orders: number;
+        cells: number;
+        displays: number;
+    }): void;
+    /** Return a snapshot of current metrics. Zero-alloc for the ring scan. */
+    getSnapshot(): EngineStatsSnapshot;
+    /** Reset all samples and counters. */
+    reset(): void;
+}
+
+type EngineMode = 'server' | 'client' | 'standalone';
+interface EngineOptions {
+    mode: EngineMode;
+}
+/**
+ * Engine
+ * The central game engine that orchestrates the world.
+ * Unified Architecture: Operates as Server or Client based on mode.
+ */
+declare class Engine {
+    static readonly VGA_COLORS: {
+        colorId: number;
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    }[];
+    static readonly SYSTEM_COLORS: {
+        colorId: number;
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    }[];
+    readonly mode: EngineMode;
+    readonly sessions: Map<string, User>;
+    readonly spriteRegistry: SpriteRegistry;
+    readonly fontRegistry: ImageFontRegistry;
+    readonly soundRegistry: SoundRegistry;
+    readonly inputBindings: InputBindingRegistry;
+    readonly macroRegistry: MacroRegistry;
+    /** Per-tick performance metrics. */
+    readonly stats: EngineStats;
+    /**
+     * Get the sprite registry instance.
+     */
+    getSpriteRegistry(): SpriteRegistry;
+    private resourceLoader;
+    private onFontAllocatedCallback;
+    private onFontBlockAddedCallback;
+    constructor(options: EngineOptions);
+    /**
+     * Set the resource loader implementation.
+     * Must be called by the runtime before any loadSound() / loadSounds() call.
+     *
+     * - ClientRuntime injects FetchResourceLoader (browser)
+     * - RuntimeServer injects NodeResourceLoader  (Node.js)
+     */
+    setResourceLoader(loader: IResourceLoader): void;
+    /**
+     * Create and register a new User session.
+     *
+     * @param clientId - Numeric client ID (will be converted to string internally)
+     * @param name - Optional display name (defaults to "Player {clientId}")
+     * @returns The newly created User
+     */
+    createUser(clientId: number, name?: string): User;
+    /**
+     * Remove a User session by numeric client ID.
+     *
+     * @param clientId - Numeric client ID
+     * @returns true if the user was found and removed
+     */
+    removeUser(clientId: number): boolean;
+    /**
+     * Get a User session by numeric client ID.
+     *
+     * @param clientId - Numeric client ID
+     * @returns The User if found, undefined otherwise
+     */
+    getUser(clientId: number): User | undefined;
+    /**
+     * Encode a user's current tick state into binary packets.
+     *
+     * Produces two packets:
+     * - `reliable`: layers with mustBeReliable=true + audio/vibration commands
+     * - `volatile`: layers with mustBeReliable=false (no commands)
+     *
+     * After encoding, clears pending orders and commit flags on dirty layers.
+     * The caller is responsible for transporting these packets (loopback or network).
+     */
+    endTick(user: User): TickPackets;
+    /**
+     * Get a snapshot of engine performance metrics.
+     *
+     * Returns rolling averages over the last ~120 ticks:
+     * tick duration, bytes produced, layer/order/cell counts.
+     */
+    getEngineStats(): EngineStatsSnapshot;
+    /**
+     * Encode the complete initial state of a user into a single packet (for LoadBundle).
+     *
+     * Unlike endTick(), this includes ALL layers regardless of mustBeReliable flag
+     * and does NOT require layers to be committed. Used during the handshake to send
+     * the full initial state (displays, layers, commands) to the client before simulation.
+     *
+     * Does NOT clear pending orders or commit flags - the caller (RuntimeServer)
+     * manages post-encoding cleanup separately.
+     */
+    encodeInitialState(user: User): Uint8Array;
+    /**
+     * Register a callback fired when font structure is (re)allocated.
+     * The runtime uses this to call renderer.setImageFontStructure().
+     */
+    onFontAllocated(cb: () => void): void;
+    /**
+     * Register a callback fired when a font block is added.
+     * The runtime uses this to call renderer.setImageFontBlock().
+     */
+    onFontBlockAdded(cb: (blockIndex: number) => void): void;
+    /**
+     * Configure the font / atlas structure.
+     *
+     * @param glyphWidth   Width of each glyph in the atlas PNG (px)
+     * @param glyphHeight  Height of each glyph in the atlas PNG (px)
+     * @param atlasBlocks  Number of 256-char blocks (power of two, 1-256)
+     * @param cellWidth    Rendering cell width (px) - may be larger than glyph for padding
+     * @param cellHeight   Rendering cell height (px)
+     */
+    loadFont(glyphWidth: number, glyphHeight: number, atlasBlocks: AtlasBlocks, cellWidth: number, cellHeight: number): void;
+    /**
+     * Load a font block from a resource path (PNG image).
+     * Can also accept raw Uint8Array data directly.
+     *
+     * @param blockIndex  Block index (0-based). Block 0 is the base ASCII set.
+     * @param pathOrData  Path to a PNG file, or raw PNG bytes
+     */
+    loadFontBlock(blockIndex: number, pathOrData: string | Uint8Array): Promise<void>;
+    /**
+     * Load multiple font blocks in parallel.
+     * @param blocks Record of blockIndex -> path/URL
+     */
+    loadFontBlocks(blocks: Record<number, string>): Promise<void>;
+    /**
+     * Get the current font configuration (fontId 0).
+     * Returns undefined if no font is allocated.
+     */
+    getFontConfig(): ImageFontConfig | undefined;
+    /**
+     * Get block data for a specific block index.
+     */
+    getFontBlock(blockIndex: number): Uint8Array | undefined;
+    private palettes;
+    /**
+     * Detect sound format from file path extension.
+     */
+    private detectSoundFormat;
+    /**
+     * Load a sound from a file path and register it.
+     * Returns the assigned sound ID (0-255).
+     *
+     * Works isomorphically:
+     * - Browser: fetches via HTTP
+     * - Node.js: reads from filesystem
+     */
+    loadSound(name: string, path: string): Promise<number>;
+    /**
+     * Load multiple sounds in parallel.
+     * @param sounds Record of name -> path pairs
+     * @returns Record of name -> soundId
+     */
+    loadSounds(sounds: Record<string, string>): Promise<Record<string, number>>;
+    /**
+     * Initialize the default palette (slot 0).
+     *
+     * Matches UTSP Core.initializeDefaultPalette():
+     * - 0-15: VGA base colors
+     * - 16-239: Undefined -> transparent (r:0, g:0, b:0, a:0)
+     * - 240-254: System reserved colors (cannot be overridden)
+     * - 255: COLOR_SKIP -> transparent (r:0, g:0, b:0, a:0)
+     */
+    private initializeDefaultPalette;
+    /**
+     * Load a palette into a specific slot.
+     *
+     * Matches UTSP Core.loadPaletteToSlot():
+     * - Accepts user-defined colors for indices 0-239
+     * - Forces system reserved colors 240-254 (cannot be overridden)
+     * - Forces color 255 as transparent (COLOR_SKIP)
+     * - Undefined slots default to transparent (r:0, g:0, b:0, a:0)
+     */
+    loadPaletteToSlot(slot: number, palette: any[]): void;
+    /**
+     * Get a palette from a specific slot.
+     */
+    getPalette(slot: number): any[] | undefined;
+}
+
+/**
+ * DisplayCompositor
+ *
+ * Merges multiple Layers into a single Display buffer.
+ * Optimized for Primitiv V6 (Uint32Array).
+ *
+ * Supports multi-pass rendering: each pass filters layers by Z-range,
+ * then passes are composited bottom-up (lowest pass first).
+ *
+ * Cached scratch buffers (opaqueMask, passGrids, sortScratch) are reused
+ * across frames to avoid per-frame heap allocations.
+ */
+declare class DisplayCompositor {
+    /** Reusable opaque-mask buffer (resized as needed). */
+    private _opaqueMask;
+    /** Per-pass cached grids for multi-pass compositing. */
+    private _passGrids;
+    /** Per-pass opaque-mask buffers. */
+    private _passOpaqueMasks;
+    /** Scratch array for sorting layers without allocating. */
+    private _sortScratch;
+    /** Last composite pass output (cached for retrieval). */
+    private _lastPasses;
+    /** Ensure the opaque mask is large enough, then zero it. */
+    private ensureMask;
+    /** Ensure per-pass grid buffers are allocated and correctly sized. */
+    private ensurePassGrids;
+    /**
+     * Composites layers onto a target Display grid.
+     *
+     * When the display has no render passes defined, uses a single default
+     * pass that accepts Z 0-255.
+     *
+     * With render passes:
+     * 1. Each pass composites only the layers whose zIndex falls in [zMin, zMax].
+     * 2. Passes are composited bottom-up (pass 0 first), each pass's opaque pixels
+     *    overwrite the previous ones.
+     * 3. Per-pass grid data is preserved for renderers that support multi-pass.
+     *
+     * @returns Per-pass render states when multi-pass is active, undefined otherwise.
+     */
+    composite(display: Display, layers: Layer[], target: Grid): RenderPassState[] | undefined;
+    /** Retrieve the last composite passes result (for callers who can't use the return value). */
+    getLastPasses(): RenderPassState[] | undefined;
+    private compositeSinglePass;
+    private compositeMultiPass;
+    /**
+     * Overlay pass data onto target.
+     * Foreground passes overwrite background passes:
+     * - Opaque BG: fully replaces target cell
+     * - Transparent BG with char/fg: char and fg overwrite target (foreground wins)
+     */
+    private overlayPass;
+    private compositeLayer;
+}
+
+/**
+ * LayerRasterizer
+ *
+ * Responsible for translating drawing orders into a Grid's packed data.
+ * Optimized for Primitiv V6 (Uint32Array).
+ */
+declare class LayerRasterizer {
+    /**
+     * Rasterize a set of orders onto a target grid.
+     * Note: Does NOT clear the grid; assume it's pre-cleared if needed.
+     */
+    rasterize(grid: Grid, orders: Order[], spriteRegistry?: SpriteRegistry): void;
+    private executeOrder;
+    private drawChar;
+    private drawText;
+    private drawTextMultiline;
+    private drawSubFrame;
+    private drawSubFrameMulti;
+    private drawFullFrame;
+    private drawFullFrameMulti;
+    private drawColorMap;
+    private drawFill;
+    private drawFillChar;
+    private drawFillSprite;
+    private drawFillSpriteMulti;
+    private drawSprite;
+    private drawSpriteMulti;
+    private drawDotCloud;
+    private drawDotCloudMulti;
+    private drawSpriteCloud;
+    private drawSpriteCloudMulti;
+    private drawSpriteCloudVaried;
+    private drawSpriteCloudVariedMulti;
+    private drawBitmask;
+    private drawBitmask4;
+    private drawBitmask16;
+    private drawPolyline;
+    private drawLineBresenham;
+    private drawShape;
+    private drawRectangle;
+    private drawCircle;
+    private drawEllipse;
+    private drawTriangle;
+}
+
+/**
+ * OrderBuilder - Fluent API for generating draw orders
+ */
+declare class OrderBuilder {
+    private orders;
+    /**
+     * Convert string or number to char code
+     */
+    static toCharCode(char: string | number): number;
+    /**
+     * Dedent template literals
+     */
+    static dedent(text: string): string;
+    /**
+     * Encodes a string into CP437 character codes packed into a string.
+     */
+    static encodeString(text: string): string;
+    /**
+     * Get the accumulated orders
+     */
+    getOrders(): Order[];
+    /**
+     * Clear orders
+     */
+    clear(): this;
+    /**
+     * Draw a single character
+     */
+    char(x: number, y: number, char: string | number, fg?: number, bg?: number): this;
+    static char(x: number, y: number, char: string | number, fg?: number, bg?: number): CharOrder;
+    /**
+     * Draw a single line of text
+     */
+    text(x: number, y: number, text: string, fg?: number, bg?: number): this;
+    static text(x: number, y: number, text: string, fg?: number, bg?: number): TextOrder;
+    /**
+     * Draw multiple lines of text
+     */
+    textMultiline(x: number, y: number, text: string, fg?: number, bg?: number): this;
+    static textMultiline(x: number, y: number, text: string, fg?: number, bg?: number): TextMultilineOrder;
+    /**
+     * Draw a sub-frame (region of characters)
+     */
+    subFrame(x: number, y: number, width: number, height: number, frame: (string | number)[], fg?: number, bg?: number): this;
+    static subFrame(x: number, y: number, width: number, height: number, frame: (string | number)[], fg?: number, bg?: number): SubFrameOrder;
+    /**
+     * Draw a sub-frame with individual cell colors
+     */
+    subFrameMulti(x: number, y: number, width: number, height: number, frame: {
+        char: string | number;
+        fg: number;
+        bg: number;
+    }[]): this;
+    static subFrameMulti(x: number, y: number, width: number, height: number, frame: {
+        char?: string | number;
+        charCode?: string | number;
+        fg?: number;
+        fgColor?: number;
+        fgColorCode?: number;
+        bg?: number;
+        bgColor?: number;
+        bgColorCode?: number;
+    }[]): SubFrameMultiOrder;
+    /**
+     * Draw a full frame (entire grid of characters)
+     */
+    fullFrame(frame: (string | number)[], fg?: number, bg?: number): this;
+    static fullFrame(frame: (string | number)[], fg?: number, bg?: number): FullFrameOrder;
+    /**
+     * Draw a full frame with individual cell colors
+     */
+    fullFrameMulti(frame: {
+        char?: string | number;
+        charCode?: string | number;
+        fg?: number;
+        fgColor?: number;
+        fgColorCode?: number;
+        bg?: number;
+        bgColor?: number;
+        bgColorCode?: number;
+    }[]): this;
+    static fullFrameMulti(frame: {
+        char?: string | number;
+        charCode?: string | number;
+        fg?: number;
+        fgColor?: number;
+        fgColorCode?: number;
+        bg?: number;
+        bgColor?: number;
+        bgColorCode?: number;
+    }[]): FullFrameMultiOrder;
+    /**
+     * Draw a unicolor sprite
+     */
+    sprite(x: number, y: number, spriteId: number, fg?: number, bg?: number): this;
+    static sprite(x: number, y: number, spriteId: number, fg?: number, bg?: number): SpriteOrder;
+    /**
+     * Draw a multicolor sprite
+     */
+    spriteMulti(x: number, y: number, spriteId: number): this;
+    static spriteMulti(x: number, y: number, spriteId: number): SpriteMultiOrder;
+    /**
+     * Draw a color map (region of colors)
+     */
+    colorMap(x: number, y: number, width: number, height: number, data: ColorMapCell[]): this;
+    /**
+     * Draw a rectangle
+     */
+    rect(x: number, y: number, width: number, height: number, char?: string | number, fg?: number, bg?: number, filled?: boolean): this;
+    static rect(x: number, y: number, width: number, height: number, char?: string | number, fg?: number, bg?: number, filled?: boolean): ShapeOrder;
+    /**
+     * Draw a circle
+     */
+    circle(x: number, y: number, radius: number, char: string | number, fg?: number, bg?: number, filled?: boolean): this;
+    static circle(x: number, y: number, radius: number, charOrOptions?: string | number | {
+        charCode?: string | number;
+        fgColor?: number;
+        bgColor?: number;
+        filled?: boolean;
+    }, fg?: number, bg?: number, filled?: boolean): ShapeOrder;
+    /**
+     * Draw a line
+     */
+    line(x1: number, y1: number, x2: number, y2: number, charOrOptions: string | number | {
+        charCode?: string | number;
+        fgColor?: number;
+        bgColor?: number;
+    }, fg?: number, bg?: number): this;
+    static line(x1: number, y1: number, x2: number, y2: number, charOrOptions: string | number | {
+        charCode?: string | number;
+        fgColor?: number;
+        bgColor?: number;
+    }, fg?: number, bg?: number): ShapeOrder;
+    /**
+     * Draw a triangle
+     */
+    triangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, char: string | number, fg?: number, bg?: number, filled?: boolean): this;
+    static triangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, charOrOptions?: string | number | {
+        charCode?: string | number;
+        fgColor?: number;
+        bgColor?: number;
+        filled?: boolean;
+    }, fg?: number, bg?: number, filled?: boolean): ShapeOrder;
+    /**
+     * Draw an ellipse
+     */
+    ellipse(x: number, y: number, radiusX: number, radiusY: number, char: string | number, fg?: number, bg?: number, filled?: boolean): this;
+    static ellipse(x: number, y: number, radiusX: number, radiusY: number, charOrOptions?: string | number | {
+        charCode?: string | number;
+        fgColor?: number;
+        bgColor?: number;
+        filled?: boolean;
+    }, fg?: number, bg?: number, filled?: boolean): ShapeOrder;
+    /**
+     * Draw a polyline
+     */
+    polyline(points: {
+        x: number;
+        y: number;
+    }[], char: string | number, fg?: number, bg?: number): this;
+    static polyline(points: {
+        x: number;
+        y: number;
+    }[], char: string | number, fg?: number, bg?: number): PolylineOrder;
+    /**
+     * Draw a closed polygon (polyline that connects back to start)
+     */
+    polygon(points: {
+        x: number;
+        y: number;
+    }[], char: string | number, fg?: number, bg?: number): this;
+    static polygon(points: {
+        x: number;
+        y: number;
+    }[], char: string | number, fg?: number, bg?: number): PolylineOrder;
+    /**
+     * Draw a cloud of dots with a single character and color
+     */
+    dotCloud(positions: {
+        x: number;
+        y: number;
+    }[], char: string | number, fg?: number, bg?: number): this;
+    static dotCloud(positions: {
+        x?: number;
+        y?: number;
+        posX?: number;
+        posY?: number;
+    }[], char: string | number, fg?: number, bg?: number): DotCloudOrder;
+    /**
+     * Draw a cloud of dots with individual characters and colors
+     */
+    dotCloudMulti(dots: {
+        x: number;
+        y: number;
+        char: string | number;
+        fg: number;
+        bg: number;
+    }[]): this;
+    static dotCloudMulti(dots: {
+        x?: number;
+        y?: number;
+        posX?: number;
+        posY?: number;
+        char?: string | number;
+        charCode?: string | number;
+        fg?: number;
+        fgColor?: number;
+        fgColorCode?: number;
+        bg?: number;
+        bgColor?: number;
+        bgColorCode?: number;
+    }[]): DotCloudMultiOrder;
+    /**
+     * Draw a cloud of sprites with a single sprite ID and color
+     */
+    spriteCloud(positions: {
+        x: number;
+        y: number;
+    }[], spriteId: number, fg?: number, bg?: number): this;
+    static spriteCloud(spriteId: number, positions: {
+        x?: number;
+        y?: number;
+        posX?: number;
+        posY?: number;
+    }[], fg?: number, bg?: number): SpriteCloudOrder;
+    /**
+     * Draw a cloud of sprites with a single sprite ID (multicolor)
+     */
+    spriteCloudMulti(positions: {
+        x: number;
+        y: number;
+    }[], spriteId: number): this;
+    static spriteCloudMulti(spriteId: number, positions: {
+        x?: number;
+        y?: number;
+        posX?: number;
+        posY?: number;
+    }[]): SpriteCloudMultiOrder;
+    /**
+     * Draw a cloud of sprites where each position has a specific sprite ID (varied)
+     */
+    spriteCloudVaried(sprites: {
+        x: number;
+        y: number;
+        spriteId: number;
+        fg: number;
+        bg: number;
+    }[]): this;
+    static spriteCloudVaried(sprites: {
+        x?: number;
+        y?: number;
+        posX?: number;
+        posY?: number;
+        spriteId?: number;
+        spriteIndex?: number;
+        fg?: number;
+        fgColor?: number;
+        fgColorCode?: number;
+        bg?: number;
+        bgColor?: number;
+        bgColorCode?: number;
+    }[]): SpriteCloudVariedOrder;
+    /**
+     * Draw a cloud of sprites where each position has a specific sprite ID (varied multicolor)
+     */
+    spriteCloudVariedMulti(sprites: {
+        x: number;
+        y: number;
+        spriteId: number;
+    }[]): this;
+    static spriteCloudVariedMulti(sprites: {
+        x?: number;
+        y?: number;
+        posX?: number;
+        posY?: number;
+        spriteId?: number;
+        spriteIndex?: number;
+    }[]): SpriteCloudVariedMultiOrder;
+    /**
+     * Draw a 1-bit bitmask (char vs empty)
+     */
+    bitmask(x: number, y: number, width: number, height: number, mask: ArrayLike<number>, char: string | number, fg?: number, bg?: number, override?: boolean): this;
+    static bitmask(x: number, y: number, width: number, height: number, mask: ArrayLike<number | boolean>, char: string | number, fg?: number, bg?: number, override?: boolean): BitmaskOrder;
+    /**
+     * Draw a 2-bit bitmask (up to 3 variants + empty)
+     */
+    bitmask4(x: number, y: number, width: number, height: number, mask: ArrayLike<number>, variants: {
+        char: string | number;
+        charCode?: string | number;
+        fg?: number;
+        fgColor?: number;
+        bg?: number;
+        bgColor?: number;
+    }[], override?: boolean): this;
+    static bitmask4(x: number, y: number, width: number, height: number, mask: ArrayLike<number>, variants: {
+        char: string | number;
+        charCode?: string | number;
+        fg?: number;
+        fgColor?: number;
+        bg?: number;
+        bgColor?: number;
+    }[], override?: boolean): Bitmask4Order;
+    /**
+     * Draw a 4-bit bitmask (up to 15 variants + empty)
+     */
+    bitmask16(x: number, y: number, width: number, height: number, mask: ArrayLike<number>, variants: {
+        char: string | number;
+        charCode?: string | number;
+        fg?: number;
+        fgColor?: number;
+        bg?: number;
+        bgColor?: number;
+    }[], override?: boolean): this;
+    static bitmask16(x: number, y: number, width: number, height: number, mask: ArrayLike<number>, variants: {
+        char: string | number;
+        charCode?: string | number;
+        fg?: number;
+        fgColor?: number;
+        bg?: number;
+        bgColor?: number;
+    }[], override?: boolean): Bitmask16Order;
+    /**
+     * Fill a region or the whole grid
+     */
+    fill(char: string | number, fg?: number, bg?: number): this;
+    static fill(char: string | number, fg?: number, bg?: number): FillOrder;
+    /**
+     * Fill the grid with a character pattern
+     */
+    fillChar(patternWidth: number, patternHeight: number, pattern: (string | number)[], fg?: number, bg?: number): this;
+    static fillChar(patternWidth: number, patternHeight: number, pattern: (string | number)[], fg?: number, bg?: number): FillCharOrder;
+    /**
+     * Fill the grid with a unicolor sprite pattern
+     */
+    fillSprite(spriteId: number, fg?: number, bg?: number): this;
+    static fillSprite(spriteId: number, fg?: number, bg?: number): FillSpriteOrder;
+    /**
+     * Fill the grid with a multicolor sprite pattern
+     */
+    fillSpriteMulti(spriteId: number): this;
+    static fillSpriteMulti(spriteId: number): FillSpriteMultiOrder;
+    /**
+     * Draw a box with a border (returns two ShapeOrders: filled interior + unfilled border).
+     *
+     * @param x       - Left edge
+     * @param y       - Top edge
+     * @param width   - Total width including border
+     * @param height  - Total height including border
+     * @param border  - Border appearance { charCode?, fgColor?, bgColor? }
+     * @param fill    - Interior fill { charCode?, fgColor?, bgColor? }
+     */
+    boxWithBorder(x: number, y: number, width: number, height: number, border?: {
+        charCode?: string | number;
+        fgColor?: number;
+        bgColor?: number;
+    }, fill?: {
+        charCode?: string | number;
+        fgColor?: number;
+        bgColor?: number;
+    }): this;
+    static boxWithBorder(x: number, y: number, width: number, height: number, border?: {
+        charCode?: string | number;
+        fgColor?: number;
+        bgColor?: number;
+    }, fill?: {
+        charCode?: string | number;
+        fgColor?: number;
+        bgColor?: number;
+    }): ShapeOrder[];
+    /**
+     * Draw a grid of dots at regular intervals.
+     *
+     * Places a character at every intersection of a grid with the given
+     * cell dimensions and row/col count.
+     *
+     * @param startX     - Left origin
+     * @param startY     - Top origin
+     * @param cellWidth  - Horizontal distance between grid points
+     * @param cellHeight - Vertical distance between grid points
+     * @param rows       - Number of rows (grid lines = rows + 1)
+     * @param cols       - Number of columns (grid lines = cols + 1)
+     * @param char       - Character to place at each intersection
+     * @param fg         - Foreground color
+     * @param bg         - Background color
+     */
+    grid(startX: number, startY: number, cellWidth: number, cellHeight: number, rows: number, cols: number, char?: string | number, fg?: number, bg?: number): this;
+    static grid(startX: number, startY: number, cellWidth: number, cellHeight: number, rows: number, cols: number, char?: string | number, fg?: number, bg?: number): DotCloudOrder;
+}
+
+/**
+ * BinaryReader - Position-tracked binary buffer reader.
+ *
+ * Shared implementation used by TickPacketDecoder and OrderDecoder.
+ * Supports all primitive read operations needed by the Primitiv V6 protocol.
+ */
+declare class BinaryReader {
+    private _buf;
+    private _view;
+    offset: number;
+    constructor(buffer: Uint8Array, offset?: number);
+    get remaining(): number;
+    /** Access the underlying buffer (for sub-slicing). */
+    get rawBuffer(): Uint8Array;
+    readU8(): number;
+    readI8(): number;
+    readU16BE(): number;
+    readI16BE(): number;
+    readU16LE(): number;
+    readBytes(count: number): Uint8Array;
+}
+
+/**
+ * BinaryWriter - Growable binary buffer for encoding.
+ *
+ * Shared implementation used by TickPacketEncoder and OrderEncoder.
+ * Supports pooling via reset() to avoid per-tick heap allocations.
+ */
+declare class BinaryWriter {
+    private buffer;
+    private view;
+    offset: number;
+    constructor(initialSize?: number);
+    /**
+     * Reset the writer for reuse (zero-alloc).
+     * Keeps the existing buffer - only resets the write cursor.
+     */
+    reset(): void;
+    private ensure;
+    /**
+     * Ensure capacity and return the underlying buffer for direct writes
+     * (e.g. TextEncoder.encodeInto). Caller must advance offset manually.
+     */
+    ensureAndGetBuffer(bytes: number): Uint8Array;
+    writeU8(v: number): void;
+    writeI8(v: number): void;
+    writeU16BE(v: number): void;
+    writeI16BE(v: number): void;
+    writeU16LE(v: number): void;
+    writeBytes(data: Uint8Array): void;
+    /**
+     * Return a trimmed copy of the written data.
+     * Safe to use when the writer will be reused/reset afterwards.
+     */
+    toUint8Array(): Uint8Array;
+    /**
+     * Return a view (subarray) of the written data - zero-copy.
+     * WARNING: The view shares the underlying buffer. Only valid until the next
+     * write or reset. Use when a short-lived read is sufficient (e.g. immediate
+     * copy into a packet).
+     */
+    getView(): Uint8Array;
+}
+
+/**
+ * OrderEncoder - Encodes render orders to compact binary format.
+ *
+ * Each order starts with a 1-byte type tag followed by type-specific payload.
+ * Convention: Big-endian for sizes/positions, charCodes as-is (1 byte 8bit, 2 bytes LE 16bit).
+ */
+
+declare class OrderEncoder {
+    private static readonly _sharedWriter;
+    /**
+     * Encode a list of render orders into binary.
+     * @param orders The orders to encode.
+     * @param is16bit Whether charCodes are 16-bit (true) or 8-bit (false).
+     * @returns Encoded binary data.
+     */
+    static encode(orders: Order[], is16bit?: boolean): Uint8Array;
+    /**
+     * Encode a list of render orders directly into a provided BinaryWriter.
+     * Zero-alloc variant - avoids creating an intermediate Uint8Array.
+     * Used by TickPacketEncoder to write orders inline.
+     */
+    static encodeInto(w: BinaryWriter, orders: Order[], is16bit?: boolean): void;
+    /**
+     * Encode a single order into the writer.
+     */
+    private static encodeOne;
+    private static encodeChar;
+    private static encodeText;
+    private static encodeTextMultiline;
+    private static encodeSubFrame;
+    private static encodeSubFrameMulti;
+    private static encodeFullFrame;
+    private static encodeFullFrameMulti;
+    private static encodeSprite;
+    private static encodeSpriteMulti;
+    private static encodeColorMap;
+    private static encodeShape;
+    private static encodePolyline;
+    private static encodeDotCloud;
+    private static encodeDotCloudMulti;
+    private static encodeSpriteCloud;
+    private static encodeSpriteCloudMulti;
+    private static encodeSpriteCloudVaried;
+    private static encodeSpriteCloudVariedMulti;
+    private static encodeBitmask;
+    private static encodeBitmask4;
+    private static encodeBitmask16;
+    private static encodeFill;
+    private static encodeFillChar;
+    private static encodeFillSprite;
+    private static encodeFillSpriteMulti;
+}
+
+/**
+ * OrderDecoder - Decodes render orders from compact binary format.
+ *
+ * Mirrors OrderEncoder: Big-endian for sizes/positions, charCodes 1 byte (8bit) or 2 bytes LE (16bit).
+ */
+
+declare class OrderDecoder {
+    /**
+     * Decode a binary buffer into a list of render orders.
+     * @param buffer The binary data (may contain 0..N orders concatenated).
+     * @param is16bit Whether charCodes are 16-bit.
+     * @param layerWidth Width of the target layer (needed for FullFrame).
+     * @param layerHeight Height of the target layer (needed for FullFrame).
+     * @returns Decoded orders array.
+     */
+    static decode(buffer: Uint8Array, is16bit?: boolean, layerWidth?: number, layerHeight?: number): Order[];
+    /**
+     * Decode exactly `count` orders from an existing BinaryReader.
+     *
+     * Unlike decode(), this does not create its own reader and does not
+     * read until end-of-buffer. It advances the shared reader by exactly
+     * the bytes consumed by `count` orders, allowing the caller to
+     * continue reading subsequent sections from the same buffer.
+     */
+    static decodeN(r: BinaryReader, count: number, is16bit: boolean, layerWidth: number, layerHeight: number): Order[];
+    private static decodeOne;
+    private static decodeChar;
+    private static decodeText;
+    private static decodeTextMultiline;
+    private static decodeSubFrame;
+    private static decodeSubFrameMulti;
+    private static decodeFullFrame;
+    private static decodeFullFrameMulti;
+    private static decodeSprite;
+    private static decodeSpriteMulti;
+    private static decodeColorMap;
+    private static decodeShape;
+    private static decodePolyline;
+    private static decodeDotCloud;
+    private static decodeDotCloudMulti;
+    private static decodeSpriteCloud;
+    private static decodeSpriteCloudMulti;
+    private static decodeSpriteCloudVaried;
+    private static decodeSpriteCloudVariedMulti;
+    private static decodeBitmask;
+    private static decodeBitmask4;
+    private static decodeBitmask16;
+    private static decodeFill;
+    private static decodeFillChar;
+    private static decodeFillSprite;
+    private static decodeFillSpriteMulti;
+}
+
+/**
+ * TickPacketDecoder - Decodes a full tick update packet from binary.
+ *
+ * Mirrors TickPacketEncoder. Produces a structured object suitable for
+ * ClientRuntime.applyUpdate().
+ */
+
+interface DecodedDisplay {
+    id: number;
+    originX: number;
+    originY: number;
+    width: number;
+    height: number;
+    paletteSlot: number;
+    scalingMode: ScalingMode;
+    cellWidth: number;
+    cellHeight: number;
+    renderPasses?: {
+        id: number;
+        zMin: number;
+        zMax: number;
+        enabled: boolean;
+    }[];
+    postProcess: PostProcessConfig;
+}
+interface DecodedLayer {
+    id: number;
+    enabled: boolean;
+    isMacro: boolean;
+    is16bit: boolean;
+    /** True when the server sent new orders this tick. When false, the client should preserve its existing orders. */
+    hasOrders: boolean;
+    zIndex: number;
+    originX: number;
+    originY: number;
+    width: number;
+    height: number;
+    orders: Order[];
+    /** Wire size in bytes consumed by this layer (header + orders). */
+    byteSize: number;
+}
+interface DecodedPalette {
+    slot: number;
+    colors: {
+        colorId: number;
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    }[];
+}
+interface DecodedTickPacket {
+    displays: DecodedDisplay[];
+    palettes: DecodedPalette[];
+    layers: DecodedLayer[];
+    audioOrders: AudioOrder[];
+    vibrationOrders: VibrationOrder[];
+    macroDefines: MacroDefine[];
+    macroOrders: MacroOrder[];
+    /** Input binding definitions (only present in LoadBundle / full snapshot). */
+    inputBindings?: InputBindingLoadPacket;
+    /** Wire byte sizes of each packet section (for traffic tracking). */
+    sectionSizes: {
+        displays: number;
+        palettes: number;
+        layers: number;
+        audio: number;
+        vibration: number;
+        macroDefines: number;
+        macroOrders: number;
+        total: number;
+    };
+}
+declare class TickPacketDecoder {
+    /**
+     * Decode a binary tick packet into a structured object.
+     */
+    static decode(buffer: Uint8Array): DecodedTickPacket;
+    /**
+     * Decode N orders from the reader.
+     *
+     * Delegates directly to OrderDecoder.decodeN() which reads exactly
+     * `count` orders from the shared BinaryReader, advancing its offset.
+     * No skip pass needed - single-pass decoding.
+     */
+    private static decodeOrders;
+    private static decodeAudioOrder;
+    private static decodeSoundTarget;
+    private static decodeVibrationOrder;
+    private static decodeMacroDefine;
+    private static decodeMacroOrder;
+    /**
+     * Decode PostProcessConfig from the binary stream.
+     * Mirrors TickPacketEncoder.encodePostProcess().
+     */
+    private static decodePostProcess;
+}
+
+/**
+ * Unicode to IBM CP437 Conversion Table
+ *
+ * ROBUST VERSION: Uses only numeric codepoints, no literal characters.
+ * This prevents any encoding issues (UTF-8, Latin-1, Windows-1252, etc.)
+ *
+ * Maps Unicode codepoints to CP437 byte values (0-255).
+ */
+/**
+ * Unicode -> CP437 Map (built from the numeric table above)
+ */
+declare const UNICODE_TO_CP437: Map<number, number>;
+/**
+ * Convert Unicode codepoint to CP437 byte value.
+ *
+ * @param unicodeChar - Unicode codepoint (from string.charCodeAt())
+ * @returns CP437 byte value (0-255)
+ *
+ * @example
+ * unicodeToCp437(0x2591) // -> 176 (░ Light Shade)
+ * unicodeToCp437(0x0041) // -> 65 (A)
+ * unicodeToCp437('░'.charCodeAt(0)) // -> 176
+ */
+declare function unicodeToCp437(unicodeChar: number): number;
+/**
+ * Convert a JavaScript string to CP437 byte array.
+ *
+ * @param text - Unicode string
+ * @returns Uint8Array of CP437 byte values
+ *
+ * @example
+ * stringToCp437('░▒▓') // -> Uint8Array [176, 177, 178]
+ */
+declare function stringToCp437(text: string): Uint8Array;
+/**
+ * Convert CP437 byte value to Unicode codepoint.
+ *
+ * @param cp437Byte - CP437 byte value (0-255)
+ * @returns Unicode codepoint
+ *
+ * @example
+ * cp437ToUnicode(176) // -> 0x2591 (░)
+ */
+declare function cp437ToUnicodeCodepoint(cp437Byte: number): number;
+/**
+ * Convert CP437 byte value to Unicode character string.
+ *
+ * @param cp437Byte - CP437 byte value (0-255)
+ * @returns Unicode character
+ *
+ * @example
+ * cp437ToUnicode(176) // -> '░'
+ */
+declare function cp437ToUnicode(cp437Byte: number): string;
+/**
+ * Check if a Unicode codepoint has a CP437 mapping.
+ *
+ * @param unicodeChar - Unicode codepoint
+ * @returns true if character can be mapped to CP437
+ */
+declare function hasCP437Mapping(unicodeChar: number): boolean;
+/**
+ * Encodes a string into CP437 character codes packed into a string.
+ */
+declare function encodeCp437String(text: string): string;
+
+/**
+ * Lightweight Event Emitter
+ * Browser/Node compatible implementation to avoid 'events' dependency.
+ */
+declare class EventEmitter<T = any> {
+    private listeners;
+    on(event: string, callback: (data: T) => void): void;
+    off(event: string, callback: (data: T) => void): void;
+    emit(event: string, data?: T): void;
+    removeAllListeners(): void;
+}
+
+/**
+ * Primitiv Core Constants
+ */
+/**
+ * COLOR_SKIP (255)
+ * Used as a special color index to signify transparency/skipping in the rendering pipeline.
+ * Matches UTSP parity.
+ */
+declare const COLOR_SKIP = 255;
+/**
+ * LAYER_SIZE
+ * Maximum width/height for a single layer grid.
+ */
+declare const LAYER_SIZE = 256;
+
+export { BinaryReader, COLOR_SKIP, CellStruct, Display, DisplayCompositor, Engine, EngineStats, EventEmitter, FontType, Grid, ImageFont, ImageFontRegistry, InputBindingRegistry, LAYER_SIZE, Layer, LayerRasterizer, MacroRegistry, OrderBuilder, OrderDecoder, OrderEncoder, SoundRegistry, SpriteRegistry, TickPacketDecoder, TickPacketEncoder, UNICODE_TO_CP437, User, UserUpdateBuilder, UserUpdateParser, cp437ToUnicode, cp437ToUnicodeCodepoint, decodeCompressedInput, encodeCompressedInput, encodeCp437String, getAtlasColumns, getAtlasDimensions, getAtlasLayout, getAtlasRows, getMaxCharCode, hasCP437Mapping, nextPow2, stringToCp437, unicodeToCp437 };
+export type { AtlasBlocks, AtlasLayout, CharCodeMode, CreateInstanceConfig, DecodedDisplay, DecodedLayer, DecodedPalette, DecodedTickPacket, EngineMode, EngineOptions, EngineStatsSnapshot, GlyphSize, ImageFontConfig, ImageFontOptions, LayerOptions, MacroInstanceState, SoundEntry, TickPackets };