@utsp/core 0.17.0-nightly.20260114213208.c9c64d9 → 0.17.0-nightly.20260120215017.712755a

package/dist/benchmark.d.ts

@@ -1,5 +1,5 @@
 import * as _utsp_types from '@utsp/types';
-import { Vector2, ScalingModeValue, AxisSource, ButtonSource, InputBindingLoadPacket, AxisBinding, ButtonBinding, TouchZoneBinding, SoundInstanceId, AudioConfigCommand, PlaySoundCommand, StopSoundCommand, FadeOutSoundCommand, PauseSoundCommand, ResumeSoundCommand, SetSoundEffectsCommand, IAudioProcessor, VibrationPattern, GamepadVibrationOptions, GamepadVibrationCommand, IGamepadVibrationProcessor, MobileVibrationCommand, IMobileVibrationProcessor, AudioAck, PostProcessConfig, PostProcessCommand, ScalingMode, GridConfig, SoundFormat, SoundLoadType, SoundLoadPacket, SoundExternalLoadPacket, UserRenderState, RenderState } from '@utsp/types';
+import { PostProcessConfig, ScalingMode, GridConfig, Vector2, ScalingModeValue, AxisSource, ButtonSource, InputBindingLoadPacket, AxisBinding, ButtonBinding, TouchZoneBinding, SoundInstanceId, AudioConfigCommand, PlaySoundCommand, StopSoundCommand, FadeOutSoundCommand, PauseSoundCommand, ResumeSoundCommand, SetSoundEffectsCommand, IAudioProcessor, VibrationPattern, GamepadVibrationOptions, GamepadVibrationCommand, IGamepadVibrationProcessor, MobileVibrationCommand, IMobileVibrationProcessor, AudioAck, PostProcessCommand, SoundFormat, SoundLoadType, SoundLoadPacket, SoundExternalLoadPacket, UserRenderState, RenderState } from '@utsp/types';
 export { Vector2 } from '@utsp/types';
 
 /**
@@ -425,6 +425,46 @@ declare class OrderEncoder {
     private encodeFillSpriteMultiColorOrder;
 }
 
+/**
+ * Internal command sink used by `Display` to enqueue network commands via `User`.
+ * @internal
+ */
+interface DisplayCommandSink {
+    setPostProcess(displayId: number, config: PostProcessConfig | null): void;
+    setScanlinesEnabled(displayId: number, enabled: boolean): void;
+    setScanlinesOpacity(displayId: number, opacity: number): void;
+    setScanlinesPattern(displayId: number, pattern: 'horizontal' | 'vertical' | 'grid'): void;
+    setAmbientEffect(displayId: number, config: boolean | {
+        blur?: number;
+        scale?: number;
+    }): void;
+    setAmbientEffectEnabled(displayId: number, enabled: boolean): void;
+    setAmbientEffectBlur(displayId: number, blur: number): void;
+    setAmbientEffectScale(displayId: number, scale: number): void;
+    isAmbientEffectEnabled(displayId: number): boolean;
+    getAmbientEffectConfig(displayId: number): {
+        enabled: boolean;
+        blur: number;
+        scale: number;
+    } | null;
+    getPostProcessConfig(displayId: number): PostProcessConfig | null;
+    setScalingMode(displayId: number, mode: ScalingMode): void;
+    getScalingMode(displayId: number): ScalingMode | null;
+    setCellSize(displayId: number, width: number, height: number): void;
+    getCellSize(displayId: number): {
+        cellWidth: number;
+        cellHeight: number;
+    };
+    setGrid(displayId: number, config: boolean | GridConfig): void;
+    setGridEnabled(displayId: number, enabled: boolean): void;
+    isGridEnabled(displayId: number): boolean;
+    getGridConfig(displayId: number): GridConfig | null;
+    switchPalette(displayId: number, slotId: number): void;
+    getCurrentPaletteSlotId(displayId: number): number | null;
+}
+/**
+ * Render pass definition for multi-pass rendering.
+ */
 interface RenderPassConfig {
     id: number;
     zMin: number;
@@ -432,78 +472,326 @@ interface RenderPassConfig {
     enabled?: boolean;
 }
 /**
- * Represents a display (camera) in the virtual world
+ * Represents a display (camera) in the virtual world.
  *
- * ARCHITECTURE (new protocol):
- * - Display = camera looking into the virtual world
- * - LAYERS are NO LONGER in Display, they are at User level
- * - Display only defines WHICH PART of the world we see (origin)
+ * Architecture:
+ * - `Display` is a camera looking into the world.
+ * - Layers are managed at the `User` level.
+ * - `Display` defines viewport origin/size and display-specific settings.
  */
 declare class Display {
     private id;
     private origin;
     private size;
+    private commandSink?;
     private previousOrigin;
     private previousSize;
-    private toDraw;
     private renderPasses;
+    /**
+     * Creates a new display.
+     *
+     * @param id - Display ID (0-255).
+     * @param sizeX - Width in cells (1-256).
+     * @param sizeY - Height in cells (1-256).
+     *
+     * @example
+     * const display = new Display(0, 80, 45);
+     *
+     * @throws Error if `id`, `sizeX`, or `sizeY` are out of bounds.
+     */
     constructor(id?: number, sizeX?: number, sizeY?: number);
     /**
-     * Gets the display ID (0-255)
+     * Returns the display ID (0-255).
+     *
+     * @returns The display ID.
      */
     getId(): number;
     /**
-     * Gets the origin position in the world
+     * Injects the command sink (set by `User`).
+     * @internal
+     */
+    setCommandSink(sink: DisplayCommandSink): void;
+    /**
+     * Returns the display origin in world space.
+     *
+     * @returns The current origin.
+     *
+     * @example
+     * const origin = display.getOrigin();
      */
     getOrigin(): Vector2;
     /**
-     * Sets the origin position in the world
+     * Sets the display origin in world space.
+     *
+     * @param origin - New world position.
+     *
+     * @example
+     * display.setOrigin(new Vector2(10, 5));
      */
     setOrigin(origin: Vector2): void;
     /**
-     * Moves the origin in the world
+     * Moves the display origin by a delta.
+     *
+     * @param deltaX - Delta X in world cells.
+     * @param deltaY - Delta Y in world cells.
+     *
+     * @example
+     * display.moveOrigin(1, 0);
      */
     moveOrigin(deltaX: number, deltaY: number): void;
     /**
-     * Checks if display origin has changed since last tick
-     * @internal - Used to calculate if update should be sent
+     * Returns `true` if the origin changed since the last tick.
+     *
+     * @returns Whether the origin has changed.
+     * @internal
      */
     hasOriginChanged(): boolean;
     /**
-     * Checks if display size has changed since last tick
-     * @internal - Used to calculate if update should be sent
+     * Returns `true` if the size changed since the last tick.
+     *
+     * @returns Whether the size has changed.
+     * @internal
      */
     hasSizeChanged(): boolean;
     /**
-     * Checks if display has changed (origin OR size)
+     * Returns `true` if origin or size changed since the last tick.
+     *
+     * @returns Whether origin or size has changed.
      * @internal
      */
     hasChanged(): boolean;
     /**
-     * Resets change tracking
-     * @internal - Called by Core.endTick() after sending updates
+     * Resets change tracking to the current state.
+     * @internal
      */
     resetChangeTracking(): void;
     /**
-     * Gets the display size
+     * Returns the display size in cells.
+     *
+     * @returns The current size in cells.
+     *
+     * @example
+     * const size = display.getSize();
      */
     getSize(): Vector2;
     /**
-     * Sets the display size
+     * Sets the display size in cells.
+     *
+     * @param size - New size in cells (1-256).
+     *
+     * @example
+     * display.setSize(new Vector2(80, 45));
+     *
+     * @throws Error if width/height are out of bounds.
      */
     setSize(size: Vector2): void;
     /**
-     * Returns the validated render passes (undefined = single pass [0,255])
+     * Returns the injected command sink.
+     * @throws Error if this display is not attached to a `User`.
+     */
+    private getSink;
+    /**
+     * Sets the post-process configuration for this display.
+     *
+     * @param config - Post-process config or `null` to disable.
+     *
+     * @example
+     * display.setPostProcess({
+     *   scanlines: { enabled: true, opacity: 0.2, pattern: 'horizontal' },
+     * });
+     *
+     * @throws Error if the display is not attached to a `User`.
+     */
+    setPostProcess(config: PostProcessConfig | null): void;
+    /**
+     * Enables or disables scanlines for this display.
+     *
+     * @param enabled - Whether scanlines are enabled.
+     *
+     * @example
+     * display.setScanlinesEnabled(true);
+     */
+    setScanlinesEnabled(enabled: boolean): void;
+    /**
+     * Sets scanlines opacity for this display.
+     *
+     * @param opacity - Opacity in range [0, 1].
+     *
+     * @example
+     * display.setScanlinesOpacity(0.35);
+     */
+    setScanlinesOpacity(opacity: number): void;
+    /**
+     * Sets the scanlines pattern for this display.
+     *
+     * @param pattern - Pattern type.
+     *
+     * @example
+     * display.setScanlinesPattern('grid');
+     */
+    setScanlinesPattern(pattern: 'horizontal' | 'vertical' | 'grid'): void;
+    /**
+     * Enables or configures the ambient effect for this display.
+     *
+     * @param config - `true`/`false` or an object with `blur`/`scale`.
+     *
+     * @example
+     * display.setAmbientEffect({ blur: 40, scale: 1.4 });
+     */
+    setAmbientEffect(config: boolean | {
+        blur?: number;
+        scale?: number;
+    }): void;
+    /**
+     * Enables or disables the ambient effect for this display.
+     *
+     * @param enabled - Whether the effect is enabled.
+     *
+     * @example
+     * display.setAmbientEffectEnabled(false);
+     */
+    setAmbientEffectEnabled(enabled: boolean): void;
+    /**
+     * Sets ambient blur intensity for this display.
+     *
+     * @param blur - Blur amount in pixels.
+     *
+     * @example
+     * display.setAmbientEffectBlur(60);
+     */
+    setAmbientEffectBlur(blur: number): void;
+    /**
+     * Sets ambient effect scale for this display.
+     *
+     * @param scale - Scale factor (>= 1).
+     *
+     * @example
+     * display.setAmbientEffectScale(1.5);
+     */
+    setAmbientEffectScale(scale: number): void;
+    /**
+     * Returns whether the ambient effect is enabled.
+     *
+     * @returns `true` if enabled.
+     */
+    isAmbientEffectEnabled(): boolean;
+    /**
+     * Returns the current ambient effect configuration, or `null` if disabled.
+     *
+     * @returns The ambient effect config or `null`.
+     */
+    getAmbientEffectConfig(): {
+        enabled: boolean;
+        blur: number;
+        scale: number;
+    } | null;
+    /**
+     * Returns the current post-process configuration, or `null` if none.
+     *
+     * @returns The post-process config or `null`.
+     */
+    getPostProcessConfig(): PostProcessConfig | null;
+    /**
+     * Sets the pixel-perfect scaling mode for this display.
+     *
+     * @param mode - Scaling mode.
+     *
+     * @example
+     * display.setScalingMode('integer');
+     */
+    setScalingMode(mode: ScalingMode): void;
+    /**
+     * Returns the current scaling mode for this display, if set.
+     *
+     * @returns The scaling mode or `null`.
+     */
+    getScalingMode(): ScalingMode | null;
+    /**
+     * Sets the cell size (in pixels) for this display.
+     *
+     * @param width - Cell width in pixels.
+     * @param height - Cell height in pixels.
+     *
+     * @example
+     * display.setCellSize(8, 16);
+     */
+    setCellSize(width: number, height: number): void;
+    /**
+     * Returns the current cell size for this display.
+     *
+     * @returns The cell size in pixels.
+     */
+    getCellSize(): {
+        cellWidth: number;
+        cellHeight: number;
+    };
+    /**
+     * Enables or configures the debug grid overlay.
+     *
+     * @param config - `true`/`false` or a `GridConfig` object.
+     *
+     * @example
+     * display.setGrid({ enabled: true, color: '#00ff00', lineWidth: 2 });
+     */
+    setGrid(config: boolean | GridConfig): void;
+    /**
+     * Enables or disables the debug grid overlay.
+     *
+     * @param enabled - Whether the grid is enabled.
+     */
+    setGridEnabled(enabled: boolean): void;
+    /**
+     * Returns whether the debug grid is enabled.
+     *
+     * @returns `true` if enabled.
+     */
+    isGridEnabled(): boolean;
+    /**
+     * Returns the current grid configuration, or `null` if none.
+     *
+     * @returns The grid configuration or `null`.
+     */
+    getGridConfig(): GridConfig | null;
+    /**
+     * Switches to a preloaded palette slot for this display.
+     *
+     * @param slotId - Palette slot ID (0-255).
+     *
+     * @example
+     * display.switchPalette(2);
+     */
+    switchPalette(slotId: number): void;
+    /**
+     * Returns the active palette slot ID for this display, or `null`.
+     *
+     * @returns The current palette slot ID or `null`.
+     */
+    getCurrentPaletteSlotId(): number | null;
+    /**
+     * Returns the render passes configuration.
+     *
+     * @returns Array of passes or `undefined` for single pass.
      */
     getRenderPasses(): RenderPassConfig[] | undefined;
     /**
-     * Sets the render passes configuration (0..4 passes). Applies clamping and swap.
-     * Passing undefined resets to single pass behavior.
+     * Sets render passes configuration (0..4 passes).
+     *
+     * @param passes - Pass definitions or `undefined` to reset.
+     *
+     * @example
+     * display.setRenderPasses([
+     *   { id: 0, zMin: 0, zMax: 127 },
+     *   { id: 1, zMin: 128, zMax: 255 },
+     * ]);
+     *
+     * @throws Error if more than 4 passes are provided.
      */
     setRenderPasses(passes: RenderPassConfig[] | undefined): void;
     private normalizePass;
     /**
-     * Returns a debug-friendly snapshot of this display (metadata only)
+     * Returns a debug-friendly snapshot of this display (metadata only).
+     *
+     * @returns Debug info snapshot.
      */
     getDebugInfo(): {
         id: number;
@@ -580,6 +868,13 @@ interface NetworkLayer {
     orders: AnyNetworkOrder[];
     /** Optional decoded byte size of this layer segment in the update packet */
     byteSize?: number;
+    /**
+     * Macro layer flag
+     * - false: standard layer
+     * - true: macro layer (ephemeral, local effects)
+     * Encoded in updateFlags bit 5
+     */
+    isMacroLayer: boolean;
     /**
      * CharCode mode for this layer
      * - false: 8-bit charCodes (0-255)
@@ -1931,140 +2226,6 @@ declare class MacroOrderEncoder {
  * - 16 blocks = 64×64 grid = 4096 chars (12-bit)
  */
 type AtlasBlocks = 1 | 4 | 16;
-/**
- * WebFont configuration
- * For CSS-based fonts rendered by the browser
- */
-interface WebFontConfig {
-    fontFamily: string;
-    fontSize: number;
-    offsetX?: number;
-    offsetY?: number;
-    charSpacing?: number;
-    lineHeight?: number;
-    fontWeight?: string;
-    fontStyle?: string;
-}
-/**
- * WebFont class
- * Represents a CSS-based font for browser rendering
- */
-declare class WebFont {
-    private fontId;
-    private config;
-    constructor(fontId: number, config: WebFontConfig);
-    /**
-     * Get the unique font ID
-     */
-    getFontId(): number;
-    /**
-     * Get the full configuration (copy)
-     */
-    getConfig(): WebFontConfig;
-    /**
-     * Get the font family
-     */
-    getFontFamily(): string;
-    /**
-     * Get the font size in pixels
-     */
-    getFontSize(): number;
-    /**
-     * Get the horizontal offset
-     */
-    getOffsetX(): number;
-    /**
-     * Get the vertical offset
-     */
-    getOffsetY(): number;
-    /**
-     * Get the character spacing
-     */
-    getCharSpacing(): number;
-    /**
-     * Get the line height multiplier
-     */
-    getLineHeight(): number;
-    /**
-     * Get the font weight
-     */
-    getFontWeight(): string;
-    /**
-     * Get the font style
-     */
-    getFontStyle(): string;
-    /**
-     * Generate CSS declaration for this font
-     * @returns CSS string (e.g., "font-family: Consolas; font-size: 16px;")
-     */
-    toCSS(): string;
-}
-/**
- * BitmapFont configuration
- * For pixel-based fonts with custom glyph data
- */
-interface BitmapFontConfig {
-    charWidth: number;
-    charHeight: number;
-    cellWidth?: number;
-    cellHeight?: number;
-    glyphs: Map<number, Uint8Array>;
-}
-/**
- * BitmapFont class
- * Represents a pixel-based font with custom glyph bitmaps
- * Corresponds to LoadType 0x04 (Charset) in UTSP protocol
- */
-declare class BitmapFont {
-    private fontId;
-    private config;
-    constructor(fontId: number, config: BitmapFontConfig);
-    /**
-     * Get the unique font ID
-     */
-    getFontId(): number;
-    /**
-     * Get the full configuration (deep copy)
-     */
-    getConfig(): BitmapFontConfig;
-    /**
-     * Get the glyph width in pixels (actual bitmap size)
-     */
-    getCharWidth(): number;
-    /**
-     * Get the glyph height in pixels (actual bitmap size)
-     */
-    getCharHeight(): number;
-    /**
-     * Get the target cell width in pixels (rendering size)
-     * Defaults to glyph width if not specified
-     */
-    getCellWidth(): number;
-    /**
-     * Get the target cell height in pixels (rendering size)
-     * Defaults to glyph height if not specified
-     */
-    getCellHeight(): number;
-    /**
-     * Get the bitmap data for a specific character
-     * @param charCode Character code (0-255)
-     * @returns Bitmap data or undefined if not found
-     */
-    getGlyph(charCode: number): Uint8Array | undefined;
-    /**
-     * Check if a glyph exists for a character
-     * @param charCode Character code (0-255)
-     */
-    hasGlyph(charCode: number): boolean;
-    /**
-     * Get the number of glyphs in this font
-     */
-    getGlyphCount(): number;
-    /**
-     * Get all character codes that have glyphs
-     */
-    getCharCodes(): number[];
-}
 /**
  * ImageFont configuration
  * For PNG atlas-based fonts with pre-rendered glyphs
@@ -2075,7 +2236,6 @@ interface ImageFontConfig {
     cellWidth?: number;
     cellHeight?: number;
     atlasBlocks: AtlasBlocks;
-    imageData: Uint8Array;
 }
 /**
  * ImageFont class
@@ -2104,13 +2264,22 @@ declare class ImageFont {
     private config;
     private readonly atlasColumns;
     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 (copy with new imageData reference)
+     * Get the full configuration
      */
     getConfig(): ImageFontConfig;
     /**
@@ -2141,10 +2310,6 @@ declare class ImageFont {
      * Get the maximum supported charCode
      */
     getMaxCharCode(): number;
-    /**
-     * Get the PNG image data
-     */
-    getImageData(): Uint8Array;
     /**
      * Get the atlas dimensions in pixels
      */
@@ -2200,11 +2365,10 @@ declare enum LoadType {
     ColorPalette = 1,
     Sprite = 2,
     MulticolorSprite = 3,
-    BitmapFont = 4,// Formerly "Charset" - pixel-based fonts (bitpacking)
     Sound = 5,
-    WebFont = 6,// CSS-based fonts for browser rendering
     Macro = 7,// Macro template for client-side feedback
-    ImageFont = 8
+    ImageFont = 8,// Header for PNG atlas-based fonts (structure only)
+    ImageFontBlock = 9
 }
 /**
  * Color definition with RGBA+E values
@@ -2222,12 +2386,12 @@ interface Color {
  * Loads a palette of RGBA+E colors
  *
  * When slotId is provided, the palette is loaded into a named slot for later switching.
- * When slotId is undefined/absent, the palette is loaded as the main active palette.
+ * When slotId is undefined/absent, the palette is loaded into the default slot (0).
  *
  * @example
  * ```typescript
- * // Main palette (backward compatible)
- * { loadType: LoadType.ColorPalette, colors: [...] }
+ * // Default slot (backward compatible)
+ * { loadType: LoadType.ColorPalette, colors: [...] } // → treated as slot 0
  *
  * // Palette slot for dynamic switching
  * { loadType: LoadType.ColorPalette, slotId: 1, colors: [...] }
@@ -2272,40 +2436,6 @@ interface MulticolorSpriteLoad {
         data: MulticolorCell[];
     }>;
 }
-/**
- * BitmapFont Load (LoadType 0x04)
- * Custom character definitions (monochrome bitmaps)
- * Formerly known as "Charset" - renamed to BitmapFont for clarity
- */
-interface BitmapFontLoad {
-    loadType: LoadType.BitmapFont;
-    fontId: number;
-    width: number;
-    height: number;
-    cellWidth: number;
-    cellHeight: number;
-    characters: Array<{
-        charCode: number;
-        bitmap: Uint8Array;
-    }>;
-}
-/**
- * WebFont Load (LoadType 0x06)
- * CSS-based font definitions for browser rendering
- * Note: The default font is "Courier New" (monospace), but users can specify non-monospace fonts
- */
-interface WebFontLoad {
-    loadType: LoadType.WebFont;
-    fontId: number;
-    fontFamily: string;
-    fontSize: number;
-    offsetX?: number;
-    offsetY?: number;
-    charSpacing?: number;
-    lineHeight?: number;
-    fontWeight?: string;
-    fontStyle?: string;
-}
 /**
  * Sound Load (LoadType 0x05)
  * MIDI sound data for audio playback
@@ -2320,31 +2450,31 @@ interface SoundLoad {
 /**
  * ImageFont Load (LoadType 0x08)
  * PNG atlas-based fonts for extended character sets (256, 1024, or 4096 chars)
- *
- * Atlas layout (example for 4 blocks = 1024 chars):
- * ```
- * ┌─────────┬─────────┐
- * │ 0-255   │ 256-511 │  32×32 grid
- * ├─────────┼─────────┤  = 1024 chars
- * │ 512-767 │768-1023 │
- * └─────────┴─────────┘
- * ```
+ * Note: Protocol supports only ONE active ImageFont.
  */
 interface ImageFontLoad {
     loadType: LoadType.ImageFont;
-    fontId: number;
     glyphWidth: number;
     glyphHeight: number;
     cellWidth: number;
     cellHeight: number;
     atlasBlocks: AtlasBlocks;
+}
+/**
+ * ImageFont Block Load (LoadType 0x09)
+ * Contains one block of PNG data for the active ImageFont.
+ * One block = 256 characters (16x16 grid).
+ */
+interface ImageFontBlockLoad {
+    loadType: LoadType.ImageFontBlock;
+    blockIndex: number;
     imageData: Uint8Array;
 }
 
 /**
  * Union type for all load types
  */
-type AnyLoad = ColorPaletteLoad | SpriteLoad | MulticolorSpriteLoad | BitmapFontLoad | SoundLoad | WebFontLoad | MacroLoad | ImageFontLoad;
+type AnyLoad = ColorPaletteLoad | SpriteLoad | MulticolorSpriteLoad | SoundLoad | MacroLoad | ImageFontLoad | ImageFontBlockLoad;
 
 /**
  * Encoder for UTSP Load packets
@@ -2357,7 +2487,7 @@ declare class LoadEncoder {
     encode(load: AnyLoad): Uint8Array;
     /**
      * Encode ColorPaletteLoad (0x01)
-     * Structure (main palette): LoadType(1) + HasSlot(1=0x00) + PaletteSize(1) + [ColorId(1) + R(1) + G(1) + B(1) + A(1) + E(1)]*N
+     * Structure (default slot): LoadType(1) + HasSlot(1=0x00) + PaletteSize(1) + [ColorId(1) + R(1) + G(1) + B(1) + A(1) + E(1)]*N
      * Structure (slot palette): LoadType(1) + HasSlot(1=0xFF) + SlotId(1) + PaletteSize(1) + [ColorId(1) + R(1) + G(1) + B(1) + A(1) + E(1)]*N
      */
     private encodeColorPalette;
@@ -2371,29 +2501,23 @@ declare class LoadEncoder {
      * Structure: LoadType(1) + SpriteCount(1) + [SpriteId(1) + SizeX(1) + SizeY(1) + Data(SizeX*SizeY*3)]*N
      */
     private encodeMulticolorSprite;
-    /**
-     * Encode BitmapFontLoad (0x04)
-     * Formerly "CharsetLoad" - renamed to BitmapFont
-     * Structure: LoadType(1) + FontId(1) + Width(1) + Height(1) + CellWidth(1) + CellHeight(1) + CharCount(1) + [CharCode(1) + Bitmap(ceil(W*H/8))]*N
-     */
-    private encodeBitmapFont;
     /**
      * Encode SoundLoad (0x05)
      * Structure: LoadType(1) + SoundCount(1) + [SoundId(1) + DataSize(2) + MidiData(DataSize)]*N
      */
     private encodeSound;
-    /**
-     * Encode WebFontLoad (0x06)
-     * NEW: CSS-based font definitions for browser rendering
-     * Structure: LoadType(1) + FontId(1) + Flags(1) + FontFamily(string) + FontSize(2) + [Optional fields based on flags]
-     */
-    private encodeWebFont;
     /**
      * Encode ImageFontLoad (0x08)
-     * PNG atlas-based font for extended character sets
-     * Structure: LoadType(1) + FontId(1) + GlyphWidth(1) + GlyphHeight(1) + CellWidth(1) + CellHeight(1) + AtlasBlocks(1) + ImageDataSize(4) + ImageData(N)
+     * Header for PNG atlas-based fonts (structure only)
+     * Structure: LoadType(1) + GlyphWidth(1) + GlyphHeight(1) + CellWidth(1) + CellHeight(1) + AtlasBlocks(1)
      */
     private encodeImageFont;
+    /**
+     * Encode ImageFontBlockLoad (0x09)
+     * Data block for PNG atlas-based fonts
+     * Structure: LoadType(1) + BlockIndex(1) + DataLength(4) + Data
+     */
+    private encodeImageFontBlock;
 }
 
 /**
@@ -2795,7 +2919,7 @@ declare class LoadDecoder {
     decode(data: Uint8Array, offset?: number): LoadDecodeResult;
     /**
      * Decode ColorPaletteLoad (0x01)
-     * Structure (main palette): LoadType(1) + HasSlot(1=0x00) + PaletteSize(1) + [ColorId(1) + R(1) + G(1) + B(1) + A(1) + E(1)]*N
+     * Structure (default slot): LoadType(1) + HasSlot(1=0x00) + PaletteSize(1) + [ColorId(1) + R(1) + G(1) + B(1) + A(1) + E(1)]*N
      * Structure (slot palette): LoadType(1) + HasSlot(1=0xFF) + SlotId(1) + PaletteSize(1) + [ColorId(1) + R(1) + G(1) + B(1) + A(1) + E(1)]*N
      */
     private decodeColorPalette;
@@ -2807,11 +2931,6 @@ declare class LoadDecoder {
      * Decode MulticolorSpriteLoad (0x03)
      */
     private decodeMulticolorSprite;
-    /**
-     * Decode BitmapFontLoad (0x04)
-     * Formerly "CharsetLoad" - renamed to BitmapFont
-     */
-    private decodeBitmapFont;
     /**
      * Decode SoundLoad (0x05)
      */
@@ -2820,11 +2939,6 @@ declare class LoadDecoder {
      * Helper to check if buffer has enough bytes remaining
      */
     private checkSize;
-    /**
-     * Decode WebFontLoad (0x06)
-     * NEW: CSS-based font definitions for browser rendering
-     */
-    private decodeWebFont;
     /**
      * Decode MacroLoad (0x07)
      */
@@ -2834,6 +2948,12 @@ declare class LoadDecoder {
      * PNG atlas-based font for extended character sets
      */
     private decodeImageFont;
+    /**
+     * Decode ImageFontBlockLoad (0x09)
+     * Data block for PNG atlas-based fonts
+     * Structure: LoadType(1) + BlockIndex(1) + DataLength(4) + Data
+     */
+    private decodeImageFontBlock;
 }
 
 /**
@@ -2905,8 +3025,8 @@ declare class MacroEventDecoder {
 
 /**
  * CharCode mode for layers
- * - '8bit': Uses Uint8Array, limited to 256 characters (ASCII/CP437), optimized bandwidth
- * - '16bit': Uses Uint16Array, supports 65536 characters (Unicode BMP), universal
+ * - '8bit': 256 char codes (CP437 default)
+ * - '16bit': 65536 char codes (256 atlas blocks × 256 chars)
  */
 type CharCodeMode = '8bit' | '16bit';
 interface Cell {
@@ -2915,19 +3035,16 @@ interface Cell {
     bgColorCode: number;
 }
 /**
- * Optimized buffer for cells with TypedArray
- * Separate arrays for charCodes and colors for optimal memory layout
+ * Optimized buffer for cells
  *
  * CharCode storage depends on mode:
- * - 8-bit mode: Uint8Array (1 byte per charCode) - network optimized
- * - 16-bit mode: Uint16Array (2 bytes per charCode) - full Unicode BMP
+ * - 8-bit mode: 256 char codes
+ * - 16-bit mode: 65536 char codes (atlas indices)
  *
  * Colors are always 8-bit (256 palette colors)
  *
  * Performance:
  * - clear(): ~5-10μs (vs 826μs with object array)
- * - Better cache locality
- * - Less GC pressure
  */
 declare class CellBuffer {
     private charCodes;
@@ -3039,7 +3156,7 @@ declare class CellBuffer {
 /**
  * Optimized buffer to store only charcodes (unicolor sprites)
  * Simple structure: [char0, char1, char2, ...]
- * Always uses 16-bit charCodes to support full Unicode BMP
+ * Always uses 16-bit charCodes to support atlas indices (0-65535)
  *
  * Performance:
  * - Less memory than CellBuffer (2 bytes vs 4 bytes per cell)
@@ -3415,14 +3532,21 @@ declare class ImageFontRegistry {
      */
     private allocateId;
     /**
-     * Register a new ImageFont with auto-assigned ID
+     * Register a new ImageFont structure (no data)
+     * Use addBlock() to add image data
      * @param name Human-readable name for the font
      * @param options Font options (glyph size, atlas blocks)
-     * @param imageData PNG image data
      * @returns The assigned font ID (0-255)
      * @throws Error if name already exists
      */
-    registerFont(name: string, options: ImageFontOptions, imageData: Uint8Array): number;
+    registerFont(name: string, options: ImageFontOptions): number;
+    /**
+     * Add a data block to an existing font
+     * @param fontId The font ID
+     * @param blockIndex Block index (0-15)
+     * @param data PNG image data
+     */
+    addBlock(fontId: number, blockIndex: number, data: Uint8Array): void;
     /**
      * Load a new ImageFont into the registry with specific ID (low-level API)
      * @param fontId Unique font identifier (0-255)
@@ -4317,85 +4441,276 @@ declare class UserStats {
     private _userName;
     constructor(userId: string, userName: string);
     /**
-     * Enables or disables statistics collection
+     * Enables or disables statistics collection.
+     *
+     * @param enabled - Whether to collect stats.
+     *
+     * @example
+     * ```typescript
+     * user.getStats().setEnabled(true);
+     * ```
      */
     setEnabled(enabled: boolean): void;
+    /**
+     * Returns whether statistics collection is enabled.
+     *
+     * @returns true if enabled.
+     */
     isEnabled(): boolean;
-    /** User ID */
+    /**
+     * Returns the user ID.
+     *
+     * @returns User ID.
+     *
+     * @example
+     * ```typescript
+     * const id = user.getStats().userId;
+     * ```
+     */
     get userId(): string;
-    /** User name */
+    /**
+     * Returns the user name.
+     *
+     * @returns User name.
+     *
+     * @example
+     * ```typescript
+     * const name = user.getStats().userName;
+     * ```
+     */
     get userName(): string;
-    /** Current tick number */
+    /**
+     * Returns the current tick number.
+     *
+     * @returns Tick number.
+     *
+     * @example
+     * ```typescript
+     * const tick = user.getStats().tick;
+     * ```
+     */
     get tick(): number;
-    /** Current tick timestamp */
+    /**
+     * Returns the current tick timestamp.
+     *
+     * @returns Timestamp in ms.
+     *
+     * @example
+     * ```typescript
+     * const ts = user.getStats().timestamp;
+     * ```
+     */
     get timestamp(): number;
-    /** Number of displays */
+    /**
+     * Returns the number of displays.
+     *
+     * @returns Display count.
+     *
+     * @example
+     * ```typescript
+     * const count = user.getStats().displayCount;
+     * ```
+     */
     get displayCount(): number;
-    /** Total display surface area (width × height) */
+    /**
+     * Returns the total display surface area (width × height).
+     *
+     * @returns Total display area.
+     *
+     * @example
+     * ```typescript
+     * const area = user.getStats().totalDisplayArea;
+     * ```
+     */
     get totalDisplayArea(): number;
-    /** Total number of layers */
+    /**
+     * Returns the total number of layers.
+     *
+     * @returns Total layer count.
+     *
+     * @example
+     * ```typescript
+     * const total = user.getStats().totalLayers;
+     * ```
+     */
     get totalLayers(): number;
-    /** Visible layers in displays */
+    /**
+     * Returns the number of visible layers in displays.
+     *
+     * @returns Visible layer count.
+     *
+     * @example
+     * ```typescript
+     * const visible = user.getStats().visibleLayers;
+     * ```
+     */
     get visibleLayers(): number;
-    /** Static layers */
+    /**
+     * Returns the number of reliable layers.
+     *
+     * @returns Reliable layer count.
+     *
+     * @example
+     * ```typescript
+     * const reliable = user.getStats().staticLayers;
+     * ```
+     */
     get staticLayers(): number;
-    /** Dynamic layers */
+    /**
+     * Returns the number of volatile layers.
+     *
+     * @returns Volatile layer count.
+     *
+     * @example
+     * ```typescript
+     * const volatile = user.getStats().dynamicLayers;
+     * ```
+     */
     get dynamicLayers(): number;
-    /** Total orders for this user */
+    /**
+     * Returns the total number of orders for this user.
+     *
+     * @returns Total order count.
+     *
+     * @example
+     * ```typescript
+     * const orders = user.getStats().totalOrders;
+     * ```
+     */
     get totalOrders(): number;
-    /** Orders par layer ID */
+    /**
+     * Returns order counts per layer ID.
+     *
+     * @returns Map of layerId → order count.
+     *
+     * @example
+     * ```typescript
+     * const byLayer = user.getStats().ordersByLayer;
+     * const uiOrders = byLayer.get(2) ?? 0;
+     * ```
+     */
     get ordersByLayer(): Map<number, number>;
-    /** Taille du packet statique (octets) */
+    /**
+     * Returns the static packet size in bytes.
+     *
+     * @returns Static packet size.
+     *
+     * @example
+     * ```typescript
+     * const size = user.getStats().staticPacketSize;
+     * ```
+     */
     get staticPacketSize(): number;
-    /** Taille du packet dynamique (octets) */
+    /**
+     * Returns the dynamic packet size in bytes.
+     *
+     * @returns Dynamic packet size.
+     *
+     * @example
+     * ```typescript
+     * const size = user.getStats().dynamicPacketSize;
+     * ```
+     */
     get dynamicPacketSize(): number;
-    /** Taille totale des packets (static + dynamic) */
+    /**
+     * Returns the total packet size (static + dynamic) in bytes.
+     *
+     * @returns Total packet size.
+     *
+     * @example
+     * ```typescript
+     * const total = user.getStats().totalPacketSize;
+     * ```
+     */
     get totalPacketSize(): number;
-    /** Estimated size after gzip compression (25% of original size) */
+    /**
+     * Returns the estimated compressed size (25% of original).
+     *
+     * @returns Estimated compressed size.
+     *
+     * @example
+     * ```typescript
+     * const compressed = user.getStats().compressedPacketSize;
+     * ```
+     */
     get compressedPacketSize(): number;
-    /** If user sent input this tick */
+    /**
+     * Returns whether the user sent input this tick.
+     *
+     * @returns true if input was sent.
+     *
+     * @example
+     * ```typescript
+     * if (user.getStats().hasInput) {
+     *   console.log('Input received this tick');
+     * }
+     * ```
+     */
     get hasInput(): boolean;
-    /** Number of bound axes */
+    /**
+     * Returns the number of bound axes.
+     *
+     * @returns Axis count.
+     *
+     * @example
+     * ```typescript
+     * const axes = user.getStats().axisCount;
+     * ```
+     */
     get axisCount(): number;
-    /** Number of bound buttons */
+    /**
+     * Returns the number of bound buttons.
+     *
+     * @returns Button count.
+     *
+     * @example
+     * ```typescript
+     * const buttons = user.getStats().buttonCount;
+     * ```
+     */
     get buttonCount(): number;
     /**
+     * Starts collection for a new tick.
      * @internal
-     * Starts collection for a new tick
      */
     startTick(tickNumber: number): void;
     /**
+     * Records display information.
      * @internal
-     * Records display information
      */
     recordDisplays(displayCount: number, totalArea: number): void;
     /**
+     * Records layer information.
      * @internal
-     * Enregistre les informations des layers
      */
     recordLayers(total: number, visible: number, staticCount: number, dynamicCount: number): void;
     /**
+     * Records order count for a layer.
      * @internal
-     * Enregistre les orders d'un layer
      */
     recordLayerOrders(layerId: number, orderCount: number): void;
     /**
+     * Records network packet sizes.
      * @internal
-     * Records network packet sizes
      */
     recordPacketSizes(staticSize: number, dynamicSize: number): void;
     /**
+     * Records input information.
      * @internal
-     * Records input information
      */
     recordInput(hasInput: boolean, axisCount: number, buttonCount: number): void;
     /**
+     * Finalizes current tick stats.
      * @internal
-     * Finalizes current tick stats
      */
     endTick(): void;
     /**
-     * Resets statistics
+     * Resets statistics.
+     *
+     * @example
+     * ```typescript
+     * user.getStats().reset();
+     * ```
      */
     reset(): void;
 }
@@ -4457,6 +4772,10 @@ declare class User<TData = Record<string, any>> {
     private currentTickBytesSent;
     private currentTickBytesReceived;
     private availableViewports;
+    /**
+     * Display command sink (used by Display to enqueue network commands)
+     */
+    private readonly displayCommandSink;
     /**
      * Application-specific data storage
      * Use this to store game state, player data, or any custom information
@@ -4468,11 +4787,28 @@ declare class User<TData = Record<string, any>> {
      * @internal
      */
     setSpriteRegistry(registry: SpriteRegistry): void;
+    /**
+     * Returns all displays for this user.
+     *
+     * @returns Array of displays.
+     *
+     * @example
+     * ```typescript
+     * const displays = user.getDisplays();
+     * const mainDisplay = displays[0];
+     * ```
+     */
     getDisplays(): Display[];
     /**
      * Adds a display to the user
      *
      * @param display - The display to add
+     *
+     * @example
+     * ```typescript
+     * const display = new Display(0, 80, 25);
+     * user.addDisplay(display);
+     * ```
      */
     addDisplay(display: Display): void;
     /**
@@ -4480,10 +4816,21 @@ declare class User<TData = Record<string, any>> {
      *
      * @param display - The display to remove
      * @returns true if display was removed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const ok = user.removeDisplay(display);
+     * if (!ok) console.warn('Display not found');
+     * ```
      */
     removeDisplay(display: Display): boolean;
     /**
      * Removes all displays from the user
+     *
+     * @example
+     * ```typescript
+     * user.clearDisplays();
+     * ```
      */
     clearDisplays(): void;
     /**
@@ -4525,6 +4872,12 @@ declare class User<TData = Record<string, any>> {
      * Gets all available viewports (in pixels)
      *
      * @returns Map of displayId → viewport size
+     *
+     * @example
+     * ```typescript
+     * const viewports = user.getAllDisplayViewports();
+     * const display0 = viewports.get(0);
+     * ```
      */
     getAllDisplayViewports(): Map<number, {
         pixelWidth: number;
@@ -4558,12 +4911,29 @@ declare class User<TData = Record<string, any>> {
         cols: number;
         rows: number;
     } | null;
+    /**
+     * Returns all layers for this user.
+     *
+     * @returns Array of layers.
+     *
+     * @example
+     * ```typescript
+     * const layers = user.getLayers();
+     * const uiLayer = layers.find((l) => l.getName() === 'ui');
+     * ```
+     */
     getLayers(): Layer[];
     /**
      * Gets a layer by its ID
      *
      * @param layerId - The layer ID to find
      * @returns The layer, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const layer = user.getLayerById(2);
+     * if (layer) layer.setZOrder(10);
+     * ```
      */
     getLayerById(layerId: number): Layer | undefined;
     /**
@@ -4572,6 +4942,12 @@ declare class User<TData = Record<string, any>> {
      *
      * @param layer - The layer to add
      * @param name - Optional name for macro system (used in createInstance)
+     *
+     * @example
+     * ```typescript
+     * const layer = new Layer(new Vector2(0, 0), 0, 80, 25);
+     * user.addLayer(layer, 'game');
+     * ```
      */
     addLayer(layer: Layer, name?: string): void;
     /**
@@ -4579,10 +4955,20 @@ declare class User<TData = Record<string, any>> {
      *
      * @param layer - The layer to remove
      * @returns true if layer was removed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * user.removeLayer(layer);
+     * ```
      */
     removeLayer(layer: Layer): boolean;
     /**
      * Removes all layers from the user
+     *
+     * @example
+     * ```typescript
+     * user.clearLayers();
+     * ```
      */
     clearLayers(): void;
     /**
@@ -5134,11 +5520,27 @@ declare class User<TData = Record<string, any>> {
     /**
      * Gets total bytes sent to this user (server-side)
      * Excludes bridge messages.
+     *
+     * @returns Total bytes sent.
+     *
+     * @example
+     * ```typescript
+     * const total = user.getTotalBytesSent();
+     * console.log(`Sent: ${total} bytes`);
+     * ```
      */
     getTotalBytesSent(): number;
     /**
      * Gets total bytes received by this user (client-side)
      * Excludes bridge messages.
+     *
+     * @returns Total bytes received.
+     *
+     * @example
+     * ```typescript
+     * const total = user.getTotalBytesReceived();
+     * console.log(`Received: ${total} bytes`);
+     * ```
      */
     getTotalBytesReceived(): number;
     /**
@@ -5153,12 +5555,22 @@ declare class User<TData = Record<string, any>> {
     recordBytesReceived(bytes: number): void;
     /**
      * Resets byte counters (useful for periodic stats)
+     *
+     * @example
+     * ```typescript
+     * user.resetByteCounters();
+     * ```
      */
     resetByteCounters(): void;
     /**
      * Sets the tick rate for bytes-per-second calculation
      * Call this when the runtime tick rate changes
      * @param tickRate - The tick rate in ticks per second
+     *
+     * @example
+     * ```typescript
+     * user.setBytesTickRate(60);
+     * ```
      */
     setBytesTickRate(tickRate: number): void;
     /**
@@ -5170,11 +5582,21 @@ declare class User<TData = Record<string, any>> {
     /**
      * Gets bytes sent per second (sliding window over last second)
      * @returns Bytes sent per second
-     */
-    getBytesSentPerSecond(): number;
-    /**
+     *
+     * @example
+     * ```typescript
+     * const sentPerSec = user.getBytesSentPerSecond();
+     * ```
+     */
+    getBytesSentPerSecond(): number;
+    /**
      * Gets bytes received per second (sliding window over last second)
      * @returns Bytes received per second
+     *
+     * @example
+     * ```typescript
+     * const recvPerSec = user.getBytesReceivedPerSecond();
+     * ```
      */
     getBytesReceivedPerSecond(): number;
     /**
@@ -5182,6 +5604,11 @@ declare class User<TData = Record<string, any>> {
      *
      * @param name - Axis name
      * @returns bindingId or null if not found
+     *
+     * @example
+     * ```typescript
+     * const id = user.getAxisBindingId('MoveHorizontal');
+     * ```
      */
     getAxisBindingId(name: string): number | null;
     /**
@@ -5189,6 +5616,11 @@ declare class User<TData = Record<string, any>> {
      *
      * @param name - Button name
      * @returns bindingId or null if not found
+     *
+     * @example
+     * ```typescript
+     * const id = user.getButtonBindingId('Jump');
+     * ```
      */
     getButtonBindingId(name: string): number | null;
     /**
@@ -5818,6 +6250,13 @@ declare class User<TData = Record<string, any>> {
      *
      * @param soundId - The sound ID to check
      * @returns true if the sound is loaded
+     *
+     * @example
+     * ```typescript
+     * if (user.isSoundLoaded(3)) {
+     *   console.log('Sound 3 is ready');
+     * }
+     * ```
      */
     isSoundLoaded(soundId: number): boolean;
     /**
@@ -5825,12 +6264,24 @@ declare class User<TData = Record<string, any>> {
      *
      * @param soundId - The sound ID to check
      * @returns Error message if failed, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const error = user.getSoundLoadError(3);
+     * if (error) console.warn(error);
+     * ```
      */
     getSoundLoadError(soundId: number): string | undefined;
     /**
      * Get all loaded sounds on the client
      *
      * @returns Map of soundId to load info
+     *
+     * @example
+     * ```typescript
+     * const loaded = user.getLoadedSounds();
+     * console.log(`Loaded: ${loaded.size}`);
+     * ```
      */
     getLoadedSounds(): ReadonlyMap<number, {
         name: string;
@@ -5840,6 +6291,12 @@ declare class User<TData = Record<string, any>> {
      * Get all sound load errors
      *
      * @returns Map of soundId to error info
+     *
+     * @example
+     * ```typescript
+     * const errors = user.getSoundLoadErrors();
+     * errors.forEach((info, id) => console.warn(id, info.error));
+     * ```
      */
     getSoundLoadErrors(): ReadonlyMap<number, {
         name: string;
@@ -5851,12 +6308,25 @@ declare class User<TData = Record<string, any>> {
      *
      * @param instanceId - The instance ID to check
      * @returns true if the instance is playing
+     *
+     * @example
+     * ```typescript
+     * if (user.isSoundPlaying(musicId)) {
+     *   console.log('Music is playing');
+     * }
+     * ```
      */
     isSoundPlaying(instanceId: SoundInstanceId): boolean;
     /**
      * Get all currently playing sounds on the client
      *
      * @returns Map of instanceId to playback info
+     *
+     * @example
+     * ```typescript
+     * const playing = user.getPlayingSounds();
+     * playing.forEach((info, id) => console.log(id, info.soundId));
+     * ```
      */
     getPlayingSounds(): ReadonlyMap<SoundInstanceId, {
         soundId: number;
@@ -5864,6 +6334,13 @@ declare class User<TData = Record<string, any>> {
     }>;
     /**
      * Get the number of sounds currently playing on the client
+     *
+     * @returns Count of active sound instances.
+     *
+     * @example
+     * ```typescript
+     * const count = user.getPlayingSoundCount();
+     * ```
      */
     getPlayingSoundCount(): number;
     /**
@@ -5989,6 +6466,12 @@ declare class User<TData = Record<string, any>> {
      *
      * @param instanceName - Instance name
      * @param eventType - Event type to remove (optional, removes all if not specified)
+     *
+     * @example
+     * ```typescript
+     * user.offMacroEvent('btn-play', 'click');
+     * user.offMacroEvent('btn-play'); // remove all handlers for instance
+     * ```
      */
     offMacroEvent(instanceName: string, eventType?: string): void;
     /**
@@ -6038,6 +6521,11 @@ declare class User<TData = Record<string, any>> {
      *
      * @param name - Layer name (used in createInstance)
      * @param layer - The layer object
+     *
+     * @example
+     * ```typescript
+     * user.registerLayerName('ui', uiLayer);
+     * ```
      */
     registerLayerName(name: string, layer: Layer): void;
     /**
@@ -6054,6 +6542,12 @@ declare class User<TData = Record<string, any>> {
      * Should be called once per tick (tick-based updates)
      *
      * @returns Update result with events and sounds to play
+     *
+     * @example
+     * ```typescript
+     * const result = user.updateMacros();
+     * user.processMacroEvents(result);
+     * ```
      */
     updateMacros(): MacroUpdateResult;
     /**
@@ -6061,6 +6555,12 @@ declare class User<TData = Record<string, any>> {
      * Dispatches events to registered handlers (used in standalone mode)
      *
      * @param result - The result from updateMacros()
+     *
+     * @example
+     * ```typescript
+     * const result = user.updateMacros();
+     * user.processMacroEvents(result);
+     * ```
      */
     processMacroEvents(result: MacroUpdateResult): void;
     /**
@@ -6070,6 +6570,11 @@ declare class User<TData = Record<string, any>> {
      * @param displayX - Mouse X position in display cells (local to display)
      * @param displayY - Mouse Y position in display cells (local to display)
      * @param isDown - Whether the mouse button is pressed
+     *
+     * @example
+     * ```typescript
+     * user.updateMacroMouse(mouseX, mouseY, mouseDown);
+     * ```
      */
     updateMacroMouse(displayX: number, displayY: number, isDown: boolean): void;
     /**
@@ -6078,12 +6583,24 @@ declare class User<TData = Record<string, any>> {
      * by subtracting the display's origin.
      *
      * @returns Map of layerId → render orders (in display coordinates)
+     *
+     * @example
+     * ```typescript
+     * const ordersByLayer = user.getMacroRenderOrders();
+     * const uiOrders = ordersByLayer.get(uiLayerId) ?? [];
+     * ```
      */
     getMacroRenderOrders(): Map<number, AnyNetworkOrder[]>;
     /**
      * Get the effect offset (for screen shake, etc.)
      *
      * @returns Current offset from effect macros
+     *
+     * @example
+     * ```typescript
+     * const offset = user.getMacroEffectOffset();
+     * camera.setShake(offset.x, offset.y);
+     * ```
      */
     getMacroEffectOffset(): {
         x: number;
@@ -6096,14 +6613,29 @@ declare class User<TData = Record<string, any>> {
     getMacroEngine(): MacroEngine;
     /**
      * Move focus to next focusable macro element
+     *
+     * @example
+     * ```typescript
+     * user.macroFocusNext();
+     * ```
      */
     macroFocusNext(): void;
     /**
      * Move focus to previous focusable macro element
+     *
+     * @example
+     * ```typescript
+     * user.macroFocusPrevious();
+     * ```
      */
     macroFocusPrevious(): void;
     /**
      * Activate the currently focused macro element
+     *
+     * @example
+     * ```typescript
+     * user.macroActivateFocused();
+     * ```
      */
     macroActivateFocused(): void;
     /**
@@ -6130,7 +6662,7 @@ declare class User<TData = Record<string, any>> {
      * user.setPostProcess(0, null);
      * ```
      */
-    setPostProcess(displayId: number, config: PostProcessConfig | null): void;
+    private setPostProcess;
     /**
      * Enable or disable scanlines effect with default/current settings for a specific display
      *
@@ -6143,7 +6675,7 @@ declare class User<TData = Record<string, any>> {
      * user.setScanlinesEnabled(0, false); // Disable on display 0
      * ```
      */
-    setScanlinesEnabled(displayId: number, enabled: boolean): void;
+    private setScanlinesEnabled;
     /**
      * Set scanlines opacity (0-1) for a specific display
      *
@@ -6158,14 +6690,14 @@ declare class User<TData = Record<string, any>> {
      * user.setScanlinesOpacity(0, 0.5); // Strong effect on display 0
      * ```
      */
-    setScanlinesOpacity(displayId: number, opacity: number): void;
+    private setScanlinesOpacity;
     /**
      * Set scanlines pattern for a specific display
      *
      * @param displayId - Display ID (0-255)
      * @param pattern - Pattern type: 'horizontal', 'vertical', or 'grid'
      */
-    setScanlinesPattern(displayId: number, pattern: 'horizontal' | 'vertical' | 'grid'): void;
+    private setScanlinesPattern;
     /**
      * Enable or configure ambient effect for a specific display
      *
@@ -6189,10 +6721,7 @@ declare class User<TData = Record<string, any>> {
      * user.setAmbientEffect(1, { blur: 50, scale: 1.5 });
      * ```
      */
-    setAmbientEffect(displayId: number, config: boolean | {
-        blur?: number;
-        scale?: number;
-    }): void;
+    private setAmbientEffect;
     /**
      * Enable or disable ambient effect for a specific display
      *
@@ -6205,7 +6734,7 @@ declare class User<TData = Record<string, any>> {
      * user.setAmbientEffectEnabled(0, false); // Disable on display 0
      * ```
      */
-    setAmbientEffectEnabled(displayId: number, enabled: boolean): void;
+    private setAmbientEffectEnabled;
     /**
      * Set ambient effect blur intensity for a specific display
      *
@@ -6218,7 +6747,7 @@ declare class User<TData = Record<string, any>> {
      * user.setAmbientEffectBlur(0, 15); // Less blur on display 0
      * ```
      */
-    setAmbientEffectBlur(displayId: number, blur: number): void;
+    private setAmbientEffectBlur;
     /**
      * Set ambient effect scale factor for a specific display
      *
@@ -6231,23 +6760,19 @@ declare class User<TData = Record<string, any>> {
      * user.setAmbientEffectScale(0, 1.1); // Smaller glow area on display 0
      * ```
      */
-    setAmbientEffectScale(displayId: number, scale: number): void;
+    private setAmbientEffectScale;
     /**
      * Check if ambient effect is currently enabled
      */
-    isAmbientEffectEnabled(): boolean;
+    private isAmbientEffectEnabled;
     /**
      * Get current ambient effect configuration
      */
-    getAmbientEffectConfig(): {
-        enabled: boolean;
-        blur: number;
-        scale: number;
-    } | null;
+    private getAmbientEffectConfig;
     /**
      * Get current post-process configuration
      */
-    getPostProcessConfig(): PostProcessConfig | null;
+    private getPostProcessConfig;
     /**
      * Check if there are pending post-process commands
      * @internal
@@ -6287,7 +6812,7 @@ declare class User<TData = Record<string, any>> {
      * user.setScalingMode(0, 'none');
      * ```
      */
-    setScalingMode(displayId: number, mode: ScalingMode): void;
+    private setScalingMode;
     /**
      * Get current scaling mode for a display
      *
@@ -6295,7 +6820,7 @@ declare class User<TData = Record<string, any>> {
      * @param displayId - Display ID (0-255)
      * @returns Current scaling mode or null if not set
      */
-    getScalingMode(displayId: number): ScalingMode | null;
+    private getScalingMode;
     /** Current cell size configuration per display (Map<displayId, {width, height}>) */
     private currentCellSizes;
     /**
@@ -6323,17 +6848,14 @@ declare class User<TData = Record<string, any>> {
      * user.setCellSize(1, 16, 16);
      * ```
      */
-    setCellSize(displayId: number, width: number, height: number): void;
+    private setCellSize;
     /**
      * Get current cell size for a display
      *
      * @param displayId - Display ID (0-255)
      * @returns Object with cellWidth and cellHeight in pixels, or default 8x8 if not set
      */
-    getCellSize(displayId: number): {
-        cellWidth: number;
-        cellHeight: number;
-    };
+    private getCellSize;
     /** Current grid configuration per display (Map<displayId, GridConfig>) */
     private currentGridConfigs;
     /**
@@ -6361,7 +6883,7 @@ declare class User<TData = Record<string, any>> {
      * user.setGrid(0, { enabled: true, color: '#ff0000', lineWidth: 2 });
      * ```
      */
-    setGrid(displayId: number, config: boolean | GridConfig): void;
+    private setGrid;
     /**
      * Enable or disable the grid for a specific display
      *
@@ -6374,19 +6896,19 @@ declare class User<TData = Record<string, any>> {
      * user.setGridEnabled(0, false); // Hide grid on display 0
      * ```
      */
-    setGridEnabled(displayId: number, enabled: boolean): void;
+    private setGridEnabled;
     /**
      * Check if grid is currently enabled for a display
      *
      * @param displayId - Display ID (0-255)
      */
-    isGridEnabled(displayId: number): boolean;
+    private isGridEnabled;
     /**
      * Get current grid configuration for a display
      *
      * @param displayId - Display ID (0-255)
      */
-    getGridConfig(displayId: number): GridConfig | null;
+    private getGridConfig;
     /** Currently active palette slot ID per display (Map<displayId, slotId>) */
     private currentPaletteSlotIds;
     /**
@@ -6423,14 +6945,14 @@ declare class User<TData = Record<string, any>> {
      * user.switchPalette(1, nightPalette);  // Player 2 display
      * ```
      */
-    switchPalette(displayId: number, slotId: number): void;
+    private switchPalette;
     /**
      * Get the currently active palette slot ID for a display
      *
      * @param displayId - Display ID (0-255)
      * @returns The active slot ID, or null if no palette has been switched yet
      */
-    getCurrentPaletteSlotId(displayId: number): number | null;
+    private getCurrentPaletteSlotId;
     /**
      * Send data through the bridge channel to the client application
      *
@@ -6578,7 +7100,7 @@ declare class CoreStats {
     /** Details of all layers processed this tick */
     get layerDetails(): Array<{
         layerId: number;
-        isStatic: boolean;
+        mustBeReliable: boolean;
         orderCount: number;
         updateFlags: number;
     }> | undefined;
@@ -6613,7 +7135,7 @@ declare class CoreStats {
     /**
      * Records individual layer information
      */
-    recordLayerInfo(layerId: number, isStatic: boolean, orderCount: number, updateFlags: number): void;
+    recordLayerInfo(layerId: number, mustBeReliable: boolean, orderCount: number, updateFlags: number): void;
     /**
      * Records rendered cell statistics
      */
@@ -6637,119 +7159,6 @@ declare class CoreStats {
     reset(): void;
 }
 
-/**
- * WebFontRegistry - Registry for CSS-based fonts
- */
-
-/**
- * Registry for managing WebFont instances
- * Each font is identified by a unique fontId (0-255)
- */
-declare class WebFontRegistry {
-    private fonts;
-    /**
-     * Load a new WebFont into the registry
-     * @param fontId Unique font identifier (0-255)
-     * @param config WebFont configuration
-     * @throws Error if font ID already exists
-     */
-    loadFont(fontId: number, config: WebFontConfig): void;
-    /**
-     * Get a WebFont by ID
-     * @param fontId Font identifier
-     * @returns WebFont instance or undefined if not found
-     */
-    getFont(fontId: number): WebFont | undefined;
-    /**
-     * Check if a font exists in the registry
-     * @param fontId Font identifier
-     * @returns true if font exists, false otherwise
-     */
-    hasFont(fontId: number): boolean;
-    /**
-     * Remove a WebFont from the registry
-     * @param fontId Font identifier
-     * @returns true if font was removed, false if not found
-     */
-    unloadFont(fontId: number): boolean;
-    /**
-     * Remove all fonts from the registry
-     */
-    clearFonts(): void;
-    /**
-     * Get all font IDs in the registry
-     * @returns Array of font IDs, sorted in ascending order
-     */
-    getFontIds(): number[];
-    /**
-     * Get all WebFont instances in the registry
-     * @returns Array of WebFont instances, sorted by font ID
-     */
-    getAllFonts(): WebFont[];
-    /**
-     * Get the number of fonts in the registry
-     * @returns Number of fonts
-     */
-    getFontCount(): number;
-}
-
-/**
- * BitmapFontRegistry - Registry for pixel-based bitmap fonts
- */
-
-/**
- * Registry for managing BitmapFont instances
- * Each font is identified by a unique fontId (0-255)
- * BitmapFonts correspond to LoadType 0x04 (Charset) in UTSP protocol
- */
-declare class BitmapFontRegistry {
-    private fonts;
-    /**
-     * Load a new BitmapFont into the registry
-     * @param fontId Unique font identifier (0-255)
-     * @param config BitmapFont configuration
-     * @throws Error if font ID already exists
-     */
-    loadFont(fontId: number, config: BitmapFontConfig): void;
-    /**
-     * Get a BitmapFont by ID
-     * @param fontId Font identifier
-     * @returns BitmapFont instance or undefined if not found
-     */
-    getFont(fontId: number): BitmapFont | undefined;
-    /**
-     * Check if a font exists in the registry
-     * @param fontId Font identifier
-     * @returns true if font exists, false otherwise
-     */
-    hasFont(fontId: number): boolean;
-    /**
-     * Remove a BitmapFont from the registry
-     * @param fontId Font identifier
-     * @returns true if font was removed, false if not found
-     */
-    unloadFont(fontId: number): boolean;
-    /**
-     * Remove all fonts from the registry
-     */
-    clearFonts(): void;
-    /**
-     * Get all font IDs in the registry
-     * @returns Array of font IDs, sorted in ascending order
-     */
-    getFontIds(): number[];
-    /**
-     * Get all BitmapFont instances in the registry
-     * @returns Array of BitmapFont instances, sorted by font ID
-     */
-    getAllFonts(): BitmapFont[];
-    /**
-     * Get the number of fonts in the registry
-     * @returns Number of fonts
-     */
-    getFontCount(): number;
-}
-
 /**
  * SoundRegistry - Server-side registry for audio assets
  *
@@ -6901,152 +7310,359 @@ declare class SoundRegistry {
 }
 
 /**
- * Engine execution context type
+ * AudioOrderCollector - Converts high-level audio commands to binary AudioOrders
+ *
+ * This class bridges the gap between the User's high-level audio API
+ * (playSound, stopSound, etc.) and the binary AudioOrder protocol.
+ *
+ * It takes SoundRegistry to resolve sound names to IDs, and produces
+ * AudioOrders ready for binary encoding in UpdatePacket.
+ *
+ * @example
+ * ```typescript
+ * const collector = new AudioOrderCollector(soundRegistry);
+ *
+ * // Convert User's pending commands to orders
+ * const audioOrders = collector.collectFromUser(user);
+ *
+ * // audioOrders can now be added to UpdatePacket
+ * ```
  */
-type CoreMode = 'server' | 'client' | 'standalone';
+
 /**
- * UTSP engine configuration options
+ * Collects and converts audio commands to binary AudioOrders
  */
-interface CoreOptions {
+declare class AudioOrderCollector {
+    private soundRegistry;
+    constructor(soundRegistry: SoundRegistry);
     /**
-     * Execution mode: "server", "client" or "standalone"
-     *
-     * - "server": Server-side engine
-     *   → Marks layers as dirty (change tracking)
-     *   → Does NOT rasterize (CPU savings, client-side rasterization)
-     *   → Manages multiple users (limited by maxUsers)
-     *
-     * - "client": Client-side engine
-     *   → Does NOT mark as dirty (no tracking needed)
-     *   → Rasterizes immediately (local rendering for display)
-     *   → Manages ONE local user only (fixed limit)
+     * Collect all pending audio orders from a user
      *
-     * - "standalone": Standalone engine (preview, tests, debug)
-     *   → Marks as dirty AND rasterizes
-     *   → Manages multiple users
-     *   → Useful for getRenderState(), tests, simulations
+     * This flushes the user's sound and config command queues,
+     * converts them to binary AudioOrders, and returns them.
      *
-     * @default "server"
+     * @param user - The user to collect orders from
+     * @returns Array of AudioOrders ready for encoding
      */
-    mode?: CoreMode;
+    collectFromUser(user: User): AnyAudioOrder[];
     /**
-     * Maximum number of users allowed (server mode only)
-     *
-     * In client mode, this option is ignored (fixed limit of 1 user)
-     *
-     * @default 64
+     * Convert a sound command to an AudioOrder
      */
-    maxUsers?: number;
+    private convertSoundCommand;
     /**
-     * Enable strict validations (useful in development)
-     *
-     * @default false
+     * Convert PlaySoundCommand to PlaySoundOrder or PlayGlobalSoundOrder
      */
-    strictMode?: boolean;
-}
-/**
- * Core - UTSP data management engine
- *
- * Passive API: no loop, no network, no callbacks.
- * Parent package (utsp-server, utsp-client) controls execution flow.
- *
- * Responsibilities:
- * - Store and manage users
- * - Provide data manipulation methods
- * - Pure and predictable API
- *
- * What the core does NOT do:
- * - No tick loop (server/client manages it)
- * - No network (server/client manages it)
- * - No callbacks/events (core is a passive slave)
- */
-declare class Core {
-    private users;
-    private readonly mode;
-    private readonly maxUsers;
-    private readonly strictMode;
-    private currentTick;
-    private encoder;
-    private displayRasterizer;
-    private colorPalette;
-    private static readonly ANSI_VGA_COLORS;
-    private stats;
-    private spriteRegistry;
-    private webFontRegistry;
-    private bitmapFontRegistry;
-    private imageFontRegistry;
-    private soundRegistry;
-    private audioOrderCollector;
-    private vibrationOrderCollector;
-    private postProcessOrderCollector;
-    private activeWebFontId;
-    private _renderCallCount;
-    private paletteSlots;
-    private onPaletteChangedCallback?;
-    private onBitmapFontChangedCallback?;
-    private onImageFontChangedCallback?;
+    private convertPlayCommand;
     /**
-     * Creates a new UTSP engine instance
-     *
-     * @param options - Configuration options
-     *
-     * @example
-     * ```typescript
-     * // Server with 100 max users
-     * const engine = new Core({
-     *   mode: "server",
-     *   maxUsers: 100
-     * });
-     *
-     * // Simple client
-     * const engine = new Core({
-     *   mode: "client"
-     * });
-     *
-     * // Default mode (server)
-     * const engine = new Core();
-     * ```
+     * Convert StopSoundCommand to StopSoundOrder
      */
-    constructor(options?: CoreOptions);
+    private convertStopCommand;
     /**
-     * Initialize default color palette (15 reserved UI colors + free colors)
-     * @private
+     * Convert FadeOutSoundCommand to FadeOutSoundOrder
      */
-    private initializeDefaultPalette;
+    private convertFadeOutCommand;
     /**
-     * Returns current execution mode
-     *
-     * @returns "server", "client" or "standalone"
+     * Convert PauseSoundCommand to PauseSoundOrder
      */
-    getMode(): CoreMode;
+    private convertPauseCommand;
     /**
-     * Returns maximum allowed users
-     *
-     * @returns Max number of users
+     * Convert ResumeSoundCommand to ResumeSoundOrder
      */
-    getMaxUsers(): number;
+    private convertResumeCommand;
     /**
-     * Indicates if strict mode is enabled
+     * Convert SetSoundEffectsCommand to SetSoundEffectsOrder
+     */
+    private convertSetEffectsCommand;
+    /**
+     * Convert AudioConfigCommand to SetListenerPositionOrder or ConfigureSpatialOrder
+     */
+    private convertConfigCommand;
+    /**
+     * Resolve sound name or ID to a numeric soundId
+     */
+    private resolveSoundId;
+    /**
+     * Resolve target (instanceId, soundName, or 'all') to targetType and value
+     */
+    private resolveTarget;
+    /**
+     * Encode volume (0.0-1.0) to byte (0-255)
+     */
+    private encodeVolume;
+    /**
+     * Encode pitch (0.25x-4.0x) to byte (0-255, 128=1.0x)
+     * Formula: pitch = 0.25 * 2^(byte/64)
+     * Inverse: byte = 64 * log2(pitch / 0.25)
+     */
+    private encodePitch;
+    /**
+     * Encode fade time (seconds) to byte (1/10 seconds, 0-25.5s)
+     */
+    private encodeFadeTime;
+    /**
+     * Encode distance for spatial audio (scale: 0-25500 → 0-255)
+     */
+    private encodeDistance;
+    /**
+     * Encode rolloff factor (0.0-2.55 → 0-255)
+     */
+    private encodeRolloff;
+    /**
+     * Encode pan spread (0.0-1.0 → 0-255)
+     */
+    private encodePanSpread;
+    /**
+     * Encode position coordinate for spatial audio (clamp to 0-65535 for Uint16)
+     */
+    private encodePosition;
+    /**
+     * Encode filter frequency (100-25500 Hz) to byte (1-255, * 100 = Hz)
+     * 0 means disabled
+     */
+    private encodeFilterFreq;
+    /**
+     * Encode reverb wet mix (0.0-1.0) to byte (0-255)
+     */
+    private encodeReverb;
+}
+
+/**
+ * VibrationOrderCollector - Converts high-level vibration commands to binary VibrationOrders
+ *
+ * This class bridges the gap between the User's high-level vibration API
+ * (vibrate, vibrateGamepad, etc.) and the binary VibrationOrder protocol.
+ *
+ * It produces VibrationOrders ready for binary encoding in UpdatePacket.
+ * Supports both mobile vibration (pattern-based) and gamepad vibration (dual-motor).
+ *
+ * @example
+ * ```typescript
+ * const collector = new VibrationOrderCollector();
+ *
+ * // Convert User's pending commands to orders
+ * const vibrationOrders = collector.collectFromUser(user);
+ *
+ * // vibrationOrders can now be added to UpdatePacket
+ * ```
+ */
+
+/**
+ * Collects and converts vibration commands to binary VibrationOrders
+ */
+declare class VibrationOrderCollector {
+    /**
+     * Collect all pending vibration orders from a user
+     *
+     * This flushes the user's vibration command queues (mobile + gamepad),
+     * converts them to binary VibrationOrders, and returns them.
+     *
+     * @param user - The user to collect orders from
+     * @returns Array of VibrationOrders ready for encoding
+     */
+    collectFromUser(user: User): AnyVibrationOrder[];
+    /**
+     * Convert a mobile vibration command to a VibrationOrder
+     * Accepts both old format (without target) and new format (with target: 'mobile')
+     */
+    private convertMobileCommand;
+    /**
+     * Convert MobileVibrateCommand to MobileVibrateOrder
+     * Accepts both old format { pattern, intensity? } and new format { target: 'mobile', pattern, intensity? }
+     */
+    private convertMobileVibrateCommand;
+    /**
+     * Convert MobileCancelVibrationCommand to MobileCancelOrder
+     */
+    private convertMobileCancelCommand;
+    /**
+     * Convert a gamepad vibration command to a VibrationOrder
+     * Accepts both old format (without target) and new format (with target: 'gamepad')
+     */
+    private convertGamepadCommand;
+    /**
+     * Convert GamepadVibrateCommand to GamepadVibrateOrder
+     */
+    private convertGamepadVibrateCommand;
+    /**
+     * Convert GamepadCancelVibrationCommand to GamepadCancelOrder
+     */
+    private convertGamepadCancelCommand;
+}
+
+/**
+ * PostProcessOrderCollector - Converts high-level post-process commands to binary PostProcessOrders
+ *
+ * This class bridges the gap between the User's high-level post-process API
+ * (setPostProcess, setAmbientEffect, etc.) and the binary PostProcessOrder protocol.
+ *
+ * It converts PostProcessCommands to PostProcessOrders ready for binary encoding in UpdatePacket.
+ *
+ * @example
+ * ```typescript
+ * const collector = new PostProcessOrderCollector();
+ *
+ * // Convert User's pending commands to orders
+ * const postProcessOrders = collector.collectFromUser(user);
+ *
+ * // postProcessOrders can now be added to UpdatePacket
+ * ```
+ */
+
+/**
+ * Collects and converts post-process commands to binary PostProcessOrders
+ */
+declare class PostProcessOrderCollector {
+    /**
+     * Collect all pending post-process orders from a user
+     *
+     * This flushes the user's post-process command queue,
+     * converts them to binary PostProcessOrders, and returns them.
+     *
+     * @param user - The user to collect orders from
+     * @returns Array of PostProcessOrders ready for encoding
+     */
+    collectFromUser(user: User): AnyPostProcessOrder[];
+    /**
+     * Convert an array of post-process commands to PostProcessOrders
+     *
+     * This is the core conversion logic used by both:
+     * - Server: collectFromUser() → encode → network
+     * - Local: convertCommands() → applyPostProcessOrders() (no encoding)
      *
-     * @returns true if strict mode is enabled
+     * @param commands - Array of PostProcessCommands to convert
+     * @returns Array of PostProcessOrders
+     */
+    convertCommands(commands: PostProcessCommand[]): AnyPostProcessOrder[];
+    /**
+     * Convert a post-process command to a PostProcessOrder
+     */
+    private convertCommand;
+    /**
+     * Convert a full set-config command to a SetConfigOrder
+     */
+    private convertSetConfig;
+    /**
+     * Create a SetScanlinesOrder with given parameters
+     */
+    private createSetScanlinesOrder;
+    /**
+     * Create a SetAmbientEffectOrder with given parameters
+     */
+    private createSetAmbientEffectOrder;
+    /**
+     * Convert pattern string to ScanlinesPatternType
+     */
+    private patternToType;
+    /**
+     * Create a SetScalingModeOrder with given scaling mode
+     */
+    private createSetScalingModeOrder;
+    /**
+     * Create a SetGridOrder with given grid configuration
+     */
+    private createSetGridOrder;
+    /**
+     * Create a SwitchPaletteOrder with given slot ID
+     */
+    private createSwitchPaletteOrder;
+    /**
+     * Create a SetCellSizeOrder with given dimensions
      */
-    isStrictMode(): boolean;
+    private createSetCellSizeOrder;
+    /**
+     * Parse CSS color string to RGBA components
+     */
+    private parseColor;
+}
+
+/**
+ * Engine execution context type
+ */
+type CoreMode = 'server' | 'client' | 'standalone';
+/**
+ * UTSP engine configuration options
+ */
+interface CoreOptions {
+    /**
+     * Execution mode: "server", "client" or "standalone"
+     */
+    mode?: CoreMode;
+    /**
+     * Maximum number of users allowed (server mode only)
+     * Default: 100
+     */
+    maxUsers?: number;
+}
+declare class Core {
+    static readonly ANSI_VGA_COLORS: {
+        colorId: number;
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+        e: number;
+    }[];
+    readonly mode: CoreMode;
+    readonly maxUsers: number;
+    strictMode: boolean;
+    currentTick: number;
+    readonly stats: CoreStats;
+    readonly spriteRegistry: SpriteRegistry;
+    readonly imageFontRegistry: ImageFontRegistry;
+    readonly soundRegistry: SoundRegistry;
+    readonly audioOrderCollector: AudioOrderCollector;
+    readonly vibrationOrderCollector: VibrationOrderCollector;
+    readonly postProcessOrderCollector: PostProcessOrderCollector;
+    readonly encoder: UpdatePacketEncoder;
+    private readonly users;
+    private readonly colorPalette;
+    private readonly paletteSlots;
+    private readonly displayRasterizer;
+    private _renderCallCount;
+    private onPaletteChangedCallback?;
+    private onFontAllocatedCallback?;
+    private onFontBlockAddedCallback?;
+    /** @deprecated Use onFontAllocated/onFontBlockAdded */
+    private onImageFontChangedCallback?;
+    constructor(options?: CoreOptions);
+    private initializeDefaultPalette;
     /**
      * Checks if core is in server mode
      *
      * @returns true if server mode
+     *
+     * @example
+     * ```typescript
+     * if (engine.isServer()) {
+     *   // Server-specific logic
+     * }
+     * ```
      */
     isServer(): boolean;
     /**
      * Checks if core is in client mode
      *
      * @returns true if client mode
+     *
+     * @example
+     * ```typescript
+     * if (engine.isClient()) {
+     *   // Client-specific logic
+     * }
+     * ```
      */
     isClient(): boolean;
     /**
      * Checks if core is in standalone mode
      *
      * @returns true if standalone mode
+     *
+     * @example
+     * ```typescript
+     * if (engine.isStandalone()) {
+     *   // Local preview or tests
+     * }
+     * ```
      */
     isStandalone(): boolean;
     /**
@@ -7182,7 +7798,7 @@ declare class Core {
     /**
      * Register a callback to be notified when palette changes
      *
-     * Use this to update the renderer when palette is modified via loadPalette() or setColor().
+     * Use this to update the renderer when palette is modified via setColor() or resetPalette().
      *
      * @param callback - Function called with the new palette
      *
@@ -7201,22 +7817,6 @@ declare class Core {
         a: number;
         e: number;
     }>) => void): void;
-    /**
-     * Register a callback to be notified when a bitmap font is loaded.
-     *
-     * Use this to update the renderer when a font is loaded via loadBitmapFontById().
-     *
-     * @param callback - Function called with the fontId
-     *
-     * @example
-     * ```typescript
-     * core.onBitmapFontChanged((fontId) => {
-     *   const font = core.getBitmapFont(fontId);
-     *   if (font) renderer.uploadFontToGPU(font);
-     * });
-     * ```
-     */
-    onBitmapFontChanged(callback: (fontId: number) => void): void;
     /**
      * Gets a color from the palette
      *
@@ -7239,38 +7839,6 @@ declare class Core {
         a: number;
         e: number;
     } | null;
-    /**
-     * Loads a complete color palette
-     *
-     * Replaces existing colors for the specified IDs.
-     *
-     * 🎨 RESERVED COLORS (automatically forced):
-     * - ColorIDs 240-254: Standard UI palette (will be overridden even if provided)
-     * - ColorID 255: Skip/transparent color (will be overridden even if provided)
-     * - ColorIDs 0-239: Free for application use
-     *
-     * @param colors - Array of colors to load (any ColorIDs 0-255)
-     *
-     * @example
-     * ```typescript
-     * engine.loadPalette([
-     *   { colorId: 0, r: 255, g: 0, b: 0, a: 255, e: 0 },     // ✅ Custom color (free range)
-     *   { colorId: 1, r: 255, g: 255, b: 255, a: 255, e: 0 }, // ✅ Custom white
-     *   { colorId: 2, r: 255, g: 0, b: 0, a: 255, e: 0 },     // ✅ Custom red
-     *   { colorId: 3, r: 0, g: 255, b: 255, a: 255, e: 255 }, // ✅ Bright cyan
-     *   { colorId: 250, r: 255, g: 0, b: 0, a: 255, e: 0 },   // ⚠️ Will be ignored (reserved)
-     * ]);
-     * // ColorIDs 240-254 and 255 will be forced to standard values
-     * ```
-     */
-    loadPalette(colors: Array<{
-        colorId: number;
-        r: number;
-        g: number;
-        b: number;
-        a: number;
-        e?: number;
-    }>): void;
     /**
      * Gets the entire color palette
      *
@@ -7303,7 +7871,7 @@ declare class Core {
     /**
      * Load a palette into a slot for later switching
      *
-     * Palettes are stored in the Core and can be switched per-user at runtime.
+     * Palettes are stored in the Core and can be switched per-display at runtime.
      * This allows preloading multiple palettes (e.g., day/night themes)
      * and switching between them without re-sending the palette data.
      *
@@ -7316,8 +7884,9 @@ declare class Core {
      * core.loadPaletteToSlot(0, dayColors);
      * core.loadPaletteToSlot(1, nightColors);
      *
-     * // Later, switch user to night palette
-     * user.switchPalette(1);
+     * // Later, switch display to night palette
+     * const display = user.getDisplays()[0];
+     * display.switchPalette(1);
      * ```
      */
     loadPaletteToSlot(slotId: number, colors: Array<{
@@ -7354,16 +7923,33 @@ declare class Core {
      *
      * @param slotId - Slot ID (0-255)
      * @returns true if the slot has a palette loaded
+     *
+     * @example
+     * ```typescript
+     * if (core.hasPaletteSlot(1)) {
+     *   console.log('Slot 1 is ready');
+     * }
+     * ```
      */
     hasPaletteSlot(slotId: number): boolean;
     /**
      * Clear a palette slot
      *
      * @param slotId - Slot ID (0-255)
+     *
+     * @example
+     * ```typescript
+     * core.clearPaletteSlot(1);
+     * ```
      */
     clearPaletteSlot(slotId: number): void;
     /**
      * Clear all palette slots
+     *
+     * @example
+     * ```typescript
+     * core.clearAllPaletteSlots();
+     * ```
      */
     clearAllPaletteSlots(): void;
     /**
@@ -7618,11 +8204,9 @@ declare class Core {
      *
      * This method automatically decodes the binary buffer and applies
      * the asset to the Core according to its LoadType:
-     * - ColorPalette → loadPalette()
+     * - ColorPalette → loadPaletteToSlot()
      * - Sprite → loadUnicolorSprites()
      * - MulticolorSprite → loadMulticolorSprites()
-     * - BitmapFont → loadBitmapFontById()
-     * - WebFont → loadWebFontById()
      * - Sound → (TODO: implement audio system)
      *
      * @param buffer - Encoded binary buffer received via WebSocket
@@ -7637,23 +8221,6 @@ declare class Core {
      * ```
      */
     applyLoadPacket(buffer: Uint8Array): boolean;
-    /**
-     * Generates a LoadPacket for the current color palette (SERVER-SIDE)
-     *
-     * Encodes the complete palette in binary format ready to send to clients.
-     *
-     * @returns Encoded binary buffer (or null if palette empty)
-     *
-     * @example
-     * ```typescript
-     * // Server side
-     * const palettePacket = core.generatePaletteLoadPacket();
-     * if (palettePacket) {
-     *   websocket.emit('load', palettePacket);
-     * }
-     * ```
-     */
-    generatePaletteLoadPacket(): Uint8Array | null;
     /**
      * Generates a LoadPacket for a specific palette slot (SERVER-SIDE)
      *
@@ -7717,39 +8284,7 @@ declare class Core {
      */
     generateMulticolorSpritesLoadPacket(): Uint8Array | null;
     /**
-     * Generates LoadPackets for all web fonts (SERVER-SIDE)
-     *
-     * Returns an array of buffers (one font = one packet)
-     *
-     * @returns Array of encoded buffers (or empty array if no fonts)
-     *
-     * @example
-     * ```typescript
-     * const fontPackets = core.generateWebFontsLoadPackets();
-     * fontPackets.forEach(packet => {
-     *   websocket.emit('load', packet);
-     * });
-     * ```
-     */
-    generateWebFontsLoadPackets(): Uint8Array[];
-    /**
-     * Generates LoadPackets for all bitmap fonts (SERVER-SIDE)
-     *
-     * Returns an array of buffers (one font = one packet)
-     *
-     * @returns Array of encoded buffers (or empty array if no fonts)
-     *
-     * @example
-     * ```typescript
-     * const fontPackets = core.generateBitmapFontsLoadPackets();
-     * fontPackets.forEach(packet => {
-     *   websocket.emit('load', packet);
-     * });
-     * ```
-     */
-    generateBitmapFontsLoadPackets(): Uint8Array[];
-    /**
-     * Generates ALL LoadPackets (palette + sprites + fonts) (SERVER-SIDE)
+     * Generates ALL LoadPackets (palette slots + sprites + fonts) (SERVER-SIDE)
      *
      * Useful when a client initially connects to send them
      * all assets at once.
@@ -7948,6 +8483,26 @@ declare class Core {
      * ```
      */
     loadMulticolorSprites(loadData: MulticolorSpriteLoad): void;
+    /**
+     * Load Font structure (allocate font)
+     * Defines the font dimensions and allocates the atlas in memory (empty)
+     *
+     * @param glyphWidth Width of each glyph source in pixels
+     * @param glyphHeight Height of each glyph source in pixels
+     * @param atlasBlocks Number of 256-char blocks (1, 4, or 16)
+     * @param cellWidth Target rendering width
+     * @param cellHeight Target rendering height
+     */
+    loadFont(glyphWidth: number, glyphHeight: number, atlasBlocks: AtlasBlocks, cellWidth: number, cellHeight: number): void;
+    /**
+     * Load Font data block
+     * Uploads a PNG chunk (256 chars) to the previously allocated font atlas
+     *
+     * @param blockIndex Index of the block (0-15)
+     * @param pathOrData Path to the PNG file (string) or raw data (Uint8Array)
+     */
+    loadFontBlock(blockIndex: number, path: string): Promise<void>;
+    loadFontBlock(blockIndex: number, data: Uint8Array): void;
     /**
      * Unloads a unicolor sprite from memory
      *
@@ -8137,9 +8692,9 @@ declare class Core {
      */
     private detectSoundFormat;
     /**
-     * Loads sound data from path (isomorphic: Node.js or browser)
+     * Loads resource data from path (isomorphic: Node.js or browser)
      */
-    private loadSoundData;
+    private readResource;
     /**
      * Registers a sound with embedded data (File mode) - Low-level API
      *
@@ -8213,345 +8768,37 @@ declare class Core {
      */
     generateSoundLoadPackets(): Array<_utsp_types.SoundLoadPacket | _utsp_types.SoundExternalLoadPacket>;
     /**
-     * Loads the default web font (Courier New, 16px, monospace)
-     *
-     * This font is loaded automatically during engine initialization.
-     * It uses fontId 0 (reserved for the default font).
-     *
-     * @private
-     */
-    private loadDefaultWebFont;
-    /**
-     * Loads a web font into the registry
+     * Loads an image font from a PNG file path
      *
-     * Web fonts use the CSS system for rendering (fontFamily, fontSize, etc.)
-     * FontID 0 is reserved for the default font.
+     * Works identically on server (Node.js) and client (browser).
+     * The PNG is loaded and registered with an auto-assigned ID.
      *
-     * @param font - WebFont instance to load
-     * @throws Error if fontId is already in use
+     * @param name - Human-readable name for the font (e.g., 'tileset', 'icons')
+     * @param path - Path to the PNG atlas file
+     * @param options - Font configuration options
+     * @returns Promise resolving to the assigned font ID (0-255)
      *
      * @example
      * ```typescript
-     * const customFont = new WebFont(1, {
-     *   fontFamily: "Arial",
-     *   fontSize: 20,
-     *   fontWeight: "bold"
-     * });
-     * engine.loadWebFont(customFont);
+     * // In init() - same code works on server and client
+     * async init(core: Core): Promise<void> {
+     *   await core.loadImageFont('tileset', './fonts/tileset.png', {
+     *     glyphWidth: 16,
+     *     glyphHeight: 16,
+     *     atlasBlocks: 4,  // 1024 chars
+     *   });
+     * }
+     *
+     * // Later, use by name or ID
+     * const id = core.getImageFontId('tileset');
      * ```
      */
-    loadWebFont(font: WebFont): void;
+    loadImageFont(name: string, path: string, options: ImageFontOptions): Promise<number>;
     /**
-     * Gets a web font by its ID
+     * Loads multiple image fonts at once
      *
-     * @param fontId - Font ID (0-255)
-     * @returns The WebFont instance or null if not found
-     *
-     * @example
-     * ```typescript
-     * const font = engine.getWebFont(1);
-     * if (font) {
-     *   console.log(font.toCSS());
-     * }
-     * ```
-     */
-    getWebFont(fontId: number): WebFont | null;
-    /**
-     * Checks if a web font exists
-     *
-     * @param fontId - Font ID (0-255)
-     * @returns true if font exists
-     *
-     * @example
-     * ```typescript
-     * if (engine.hasWebFont(1)) {
-     *   console.log("Font 1 is loaded");
-     * }
-     * ```
-     */
-    hasWebFont(fontId: number): boolean;
-    /**
-     * Unloads a web font from the registry
-     *
-     * Note: Cannot unload the default font (fontId 0)
-     *
-     * @param fontId - Font ID to unload (1-255)
-     * @returns true if font was unloaded
-     * @throws Error if attempting to unload default font (fontId 0)
-     *
-     * @example
-     * ```typescript
-     * const removed = engine.unloadWebFont(1);
-     * if (removed) {
-     *   console.log("Font 1 unloaded");
-     * }
-     * ```
-     */
-    unloadWebFont(fontId: number): boolean;
-    /**
-     * Clears all web fonts (except default font)
-     *
-     * @example
-     * ```typescript
-     * engine.clearWebFonts();
-     * console.log("All custom web fonts cleared");
-     * ```
-     */
-    clearWebFonts(): void;
-    /**
-     * Sets the active web font
-     *
-     * The active font is used by default for character rendering.
-     *
-     * @param fontId - Font ID to activate (0-255)
-     * @throws Error if font doesn't exist
-     *
-     * @example
-     * ```typescript
-     * engine.setActiveWebFont(1);
-     * console.log(`Active font: ${engine.getActiveWebFontId()}`);
-     * ```
-     */
-    setActiveWebFont(fontId: number): void;
-    /**
-     * Gets the active web font ID
-     *
-     * @returns Active font ID (0-255)
-     *
-     * @example
-     * ```typescript
-     * const activeFontId = engine.getActiveWebFontId();
-     * console.log(`Current font: ${activeFontId}`);
-     * ```
-     */
-    getActiveWebFontId(): number;
-    /**
-     * Gets the active web font
-     *
-     * @returns The active WebFont instance
-     *
-     * @example
-     * ```typescript
-     * const activeFont = engine.getActiveWebFont();
-     * console.log(activeFont.toCSS());
-     * ```
-     */
-    getActiveWebFont(): WebFont;
-    /**
-     * Counts the number of loaded web fonts
-     *
-     * @returns Number of web fonts in memory
-     *
-     * @example
-     * ```typescript
-     * const count = engine.getWebFontCount();
-     * console.log(`${count} web fonts loaded`);
-     * ```
-     */
-    getWebFontCount(): number;
-    /**
-     * Gets all loaded web font IDs
-     *
-     * @returns Array of fontIds (0-255)
-     *
-     * @example
-     * ```typescript
-     * const fontIds = engine.getWebFontIds();
-     * console.log(`Loaded fonts: ${fontIds.join(", ")}`);
-     * ```
-     */
-    getWebFontIds(): number[];
-    /**
-     * Gets the web font registry
-     *
-     * @returns WebFontRegistry instance
-     *
-     * @example
-     * ```typescript
-     * const registry = engine.getWebFontRegistry();
-     * console.log(`Total fonts: ${registry.getFontCount()}`);
-     * ```
-     */
-    getWebFontRegistry(): WebFontRegistry;
-    /**
-     * Gets the bitmap font registry
-     *
-     * @returns BitmapFontRegistry instance
-     *
-     * @example
-     * ```typescript
-     * const registry = engine.getBitmapFontRegistry();
-     * console.log(`Total fonts: ${registry.getFontCount()}`);
-     * ```
-     */
-    getBitmapFontRegistry(): BitmapFontRegistry;
-    /**
-     * Loads a web font directly with its ID and configuration
-     *
-     * Simplified method that creates and loads the font in one step.
-     *
-     * @param fontId - Unique font ID (0-255, 0 reserved for default font)
-     * @param config - Web font configuration
-     * @throws Error if fontId is already in use
-     *
-     * @example
-     * ```typescript
-     * // Load a custom font
-     * engine.loadWebFontById(1, {
-     *   fontFamily: "Arial",
-     *   fontSize: 20,
-     *   fontWeight: "bold"
-     * });
-     *
-     * // Load a monospace font
-     * engine.loadWebFontById(2, {
-     *   fontFamily: "Consolas",
-     *   fontSize: 16,
-     *   charSpacing: 2
-     * });
-     * ```
-     */
-    loadWebFontById(fontId: number, config: WebFontConfig): void;
-    /**
-     * Loads a bitmap font directly with its ID and configuration
-     *
-     * Simplified method that loads the bitmap font in one step.
-     *
-     * @param fontId - Unique font ID (0-255)
-     * @param config - Bitmap font configuration (dimensions + glyphs)
-     * @throws Error if fontId is already in use
-     *
-     * @example
-     * ```typescript
-     * import { createASCII8x8FontLoad } from "utsp-core";
-     *
-     * // Load the ASCII 8×8 font
-     * const fontLoad = createASCII8x8FontLoad(1);
-     * engine.loadBitmapFontById(1, fontLoad.fontConfig);
-     *
-     * // Load a custom bitmap font
-     * engine.loadBitmapFontById(10, {
-     *   charWidth: 16,
-     *   charHeight: 16,
-     *   glyphs: new Map([
-     *     [65, new Uint8Array([...])], // 'A'
-     *     [66, new Uint8Array([...])], // 'B'
-     *   ])
-     * });
-     * ```
-     */
-    loadBitmapFontById(fontId: number, config: BitmapFontConfig): void;
-    /**
-     * Gets a bitmap font by its ID
-     *
-     * @param fontId - Font ID (0-255)
-     * @returns The BitmapFont instance or null if not found
-     *
-     * @example
-     * ```typescript
-     * const font = engine.getBitmapFont(1);
-     * if (font) {
-     *   console.log(`Font dimensions: ${font.getCharWidth()}×${font.getCharHeight()}`);
-     *   console.log(`Glyphs: ${font.getGlyphCount()}`);
-     * }
-     * ```
-     */
-    getBitmapFont(fontId: number): BitmapFont | null;
-    /**
-     * Checks if a bitmap font exists
-     *
-     * @param fontId - Font ID (0-255)
-     * @returns true if font exists
-     *
-     * @example
-     * ```typescript
-     * if (engine.hasBitmapFont(1)) {
-     *   console.log("Font 1 is loaded");
-     * }
-     * ```
-     */
-    hasBitmapFont(fontId: number): boolean;
-    /**
-     * Unloads a bitmap font from the registry
-     *
-     * @param fontId - Font ID to unload (0-255)
-     * @returns true if font was unloaded
-     *
-     * @example
-     * ```typescript
-     * const removed = engine.unloadBitmapFont(1);
-     * if (removed) {
-     *   console.log("Font 1 unloaded");
-     * }
-     * ```
-     */
-    unloadBitmapFont(fontId: number): boolean;
-    /**
-     * Clears all bitmap fonts
-     *
-     * @example
-     * ```typescript
-     * engine.clearBitmapFonts();
-     * console.log("All bitmap fonts cleared");
-     * ```
-     */
-    clearBitmapFonts(): void;
-    /**
-     * Counts the number of loaded bitmap fonts
-     *
-     * @returns Number of bitmap fonts in memory
-     *
-     * @example
-     * ```typescript
-     * const count = engine.getBitmapFontCount();
-     * console.log(`${count} bitmap fonts loaded`);
-     * ```
-     */
-    getBitmapFontCount(): number;
-    /**
-     * Gets all loaded bitmap font IDs
-     *
-     * @returns Array of fontIds (0-255)
-     *
-     * @example
-     * ```typescript
-     * const fontIds = engine.getBitmapFontIds();
-     * console.log(`Loaded bitmap fonts: ${fontIds.join(", ")}`);
-     * ```
-     */
-    getBitmapFontIds(): number[];
-    /**
-     * Loads an image font from a PNG file path
-     *
-     * Works identically on server (Node.js) and client (browser).
-     * The PNG is loaded and registered with an auto-assigned ID.
-     *
-     * @param name - Human-readable name for the font (e.g., 'tileset', 'icons')
-     * @param path - Path to the PNG atlas file
-     * @param options - Font configuration options
-     * @returns Promise resolving to the assigned font ID (0-255)
-     *
-     * @example
-     * ```typescript
-     * // In init() - same code works on server and client
-     * async init(core: Core): Promise<void> {
-     *   await core.loadImageFont('tileset', './fonts/tileset.png', {
-     *     glyphWidth: 16,
-     *     glyphHeight: 16,
-     *     atlasBlocks: 4,  // 1024 chars
-     *   });
-     * }
-     *
-     * // Later, use by name or ID
-     * const id = core.getImageFontId('tileset');
-     * ```
-     */
-    loadImageFont(name: string, path: string, options: ImageFontOptions): Promise<number>;
-    /**
-     * Loads multiple image fonts at once
-     *
-     * @param fonts - Object mapping font names to { path, options }
-     * @returns Promise resolving to object mapping names to IDs
+     * @param fonts - Object mapping font names to { path, options }
+     * @returns Promise resolving to object mapping names to IDs
      *
      * @example
      * ```typescript
@@ -8613,12 +8860,25 @@ declare class Core {
      * Called when an image font is loaded.
      *
      * @param callback - Function called with the fontId
+    /**
+     * Register a callback for when a font structure is allocated
+     * (Does not imply data is ready, just dimensions)
+     */
+    onFontAllocated(callback: () => void): void;
+    /**
+     * Register a callback for when a font data block is added
+     */
+    onFontBlockAdded(callback: (blockIndex: number) => void): void;
+    /**
+     * Register a callback for when an image font is changed (loaded or updated)
+     * DEPRECATED: Use onFontAllocated/onFontBlockAdded for granular updates
+     *
+     * @param callback Function to call when an image font changes
      *
      * @example
      * ```typescript
      * core.onImageFontChanged((fontId) => {
-     *   const font = core.getImageFont(fontId);
-     *   if (font) renderer.setImageFont(font.getImageData(), ...);
+     *   // Legacy support
      * });
      * ```
      */
@@ -8778,34 +9038,46 @@ declare class Core {
 }
 
 /**
- * Layer configuration options
+ * Layer configuration options.
  */
 interface LayerOptions {
-    /** Optional layer name for tooling/debug */
+    /** Optional layer name for tooling/debug. */
     name?: string;
     /**
      * CharCode mode for this layer (immutable after creation)
-     * - '8bit': Uses Uint8Array, limited to 256 characters (ASCII/CP437), optimized bandwidth
-     * - '16bit': Uses Uint16Array, supports 65536 characters (Unicode BMP), universal
+     * - '8bit': 256 char codes (CP437 default)
+     * - '16bit': 65536 char codes (256 atlas blocks × 256 chars)
      * @default '8bit'
      */
     charCodeMode?: CharCodeMode;
     /**
-     * Static layer (sent only once to client)
+     * 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
      */
-    isStatic?: boolean;
+    isMacroLayer?: boolean;
 }
+/**
+ * Represents a renderable layer in world space.
+ *
+ * Layers store rendering orders and metadata (position, z-order, size)
+ * and can be composed by displays at the `User` level.
+ */
 declare class Layer {
     private id;
     private name?;
+    private isMacroLayer;
     private origin;
     private orders;
     private zOrder;
     private data;
     private width;
     private height;
-    private isStatic;
+    private mustBeReliable;
     private spriteRegistry?;
     private mode;
     private charCodeMode;
@@ -8816,99 +9088,137 @@ declare class Layer {
     private needsCommit;
     private static rasterizer;
     /**
-     * Creates a new Layer
+     * Creates a new layer.
      *
-     * @param origin - Layer origin in world space
-     * @param zOrder - Z-order for layer stacking (higher = on top)
-     * @param width - Layer width in cells (1-256)
-     * @param height - Layer height in cells (1-256)
-     * @param options - Layer options (charCodeMode, isStatic)
+     * @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.
+     *
+     * Options:
+     * - `name`: Optional name for tooling/debug.
+     * - `charCodeMode`: `'8bit'` (default) or `'16bit'`.
+     * - `mustBeReliable`: `true` to use reliable channel, `false` for volatile.
+     * - `isMacroLayer`: `true` for macro effects, `false` for standard layers.
      *
      * @example
-     * // 8-bit layer (default) - optimized for ASCII/CP437 text
+     * // 8-bit layer (default) - CP437 (block 0) only
      * const gameLayer = new Layer(new Vector2(0, 0), 0, 80, 25);
      *
-     * // 16-bit layer - full Unicode support (emoji, CJK, symbols)
-     * const unicodeLayer = new Layer(new Vector2(0, 0), 10, 40, 10, { charCodeMode: '16bit' });
+     * @example
+     * // 16-bit layer - atlas blocks beyond CP437
+     * const atlasLayer = new Layer(new Vector2(0, 0), 10, 40, 10, { charCodeMode: '16bit' });
+     *
+     * @throws Error if width/height are out of bounds.
      */
     constructor(origin: Vector2, zOrder: number, width: number, height: number, options?: LayerOptions | boolean);
     /**
-     * Gets the layer's charCode mode (immutable)
-     * @returns '8bit' or '16bit'
+     * Returns whether the layer is a macro layer.
+     */
+    getIsMacroLayer(): boolean;
+    /**
+     * Returns the layer's charCode mode (immutable).
+     *
+     * @returns `'8bit'` or `'16bit'`.
      */
     getCharCodeMode(): CharCodeMode;
     /**
-     * Configures the layer's execution mode (called by User)
+     * Configures the layer's execution mode.
      * @internal
      */
     setMode(mode: CoreMode): void;
     /**
-     * Injects the SpriteRegistry into the layer (called by Core)
+     * Injects the SpriteRegistry into the layer.
      * @internal
      */
     setSpriteRegistry(registry: SpriteRegistry): void;
+    /**
+     * Returns all orders currently stored in this layer.
+     *
+     * @returns The order list.
+     */
     getOrders(): AnyNetworkOrder[];
     /**
-     * Adds orders to the layer (incremental mode)
-     * Re-rasterizes all orders to ensure consistent state
+     * Adds orders to the layer (incremental mode).
+     * Re-rasterizes all orders to ensure consistent state.
+     *
+     * @param orders - Orders to append.
+     *
+     * @example
+     * layer.addOrders([orderA, orderB]);
      */
     addOrders(orders: AnyNetworkOrder[]): void;
     /**
-     * Adds temporary orders that are rasterized but not stored
-     * Used for macro-generated content (particles, UI) that is regenerated each frame
+     * Adds temporary orders that are rasterized but not stored.
+     * Used for macro-generated content (particles/UI) regenerated each frame.
+     *
+     * @param orders - Orders to rasterize temporarily.
      */
     addTemporaryOrders(orders: AnyNetworkOrder[]): void;
     /**
-     * Replaces all orders in the layer (reset mode)
-     * Automatically rasterizes all orders
+     * Replaces all orders in the layer (reset mode).
+     * Automatically rasterizes all orders.
+     *
+     * @param orders - New orders to set.
      */
     setOrders(orders: AnyNetworkOrder[]): void;
     /**
-     * Clears all orders and cleans the buffer
+     * Clears all orders and resets the buffer.
      */
     clearOrders(): void;
-    getOrigin(): Vector2;
     /**
-     * Updates the layer's origin and rasterizes if necessary
+     * Returns the layer origin in world space.
      *
-     * In client mode, this method automatically rasterizes the layer
-     * to reflect the new position.
+     * @returns The current origin.
+     */
+    getOrigin(): Vector2;
+    /**
+     * Updates the layer's origin.
      *
-     * @param origin - New layer origin
+     * @param origin - New layer origin.
      */
     setOrigin(origin: Vector2): void;
+    /**
+     * Returns the layer's z-order.
+     *
+     * @returns Z-order value.
+     */
     getZOrder(): number;
     /**
-     * Updates the layer's z-order
+     * Updates the layer's z-order.
      *
-     * @param zOrder - New z-order
+     * @param zOrder - New z-order.
      */
     setZOrder(zOrder: number): void;
     /**
-     * Gets the layer's unique ID
-     *
-     * Used for client-side reconstruction when applying UpdatePackets.
-     * The ID allows associating a NetworkLayer with its corresponding Layer.
+     * Returns the layer's unique ID.
      *
-     * @returns Layer ID (0-65535)
+     * @returns Layer ID (0-65535).
      */
     getId(): number;
     /**
-     * Gets the layer's optional name (debug/metadata only)
+     * Returns the layer's optional name (debug/metadata only).
+     *
+     * @returns Name or `undefined`.
      */
     getName(): string | undefined;
     /**
-     * Sets the layer's optional name (debug/metadata only)
+     * Sets the layer's optional name (debug/metadata only).
+     *
+     * @param name - New name or `undefined` to clear.
      */
     setName(name: string | undefined): void;
     /**
-     * Returns a debug-friendly snapshot of this layer (metadata only)
+     * Returns a debug-friendly snapshot of this layer (metadata only).
+     *
+     * @returns Debug info snapshot.
      */
     getDebugInfo(): {
         id: number;
         name?: string;
         z: number;
-        isStatic: boolean;
+        mustBeReliable: boolean;
         charCodeMode: CharCodeMode;
         width: number;
         height: number;
@@ -8922,58 +9232,74 @@ declare class Layer {
         ordersCount: number;
     };
     /**
-     * Sets the layer's unique ID
-     *
-     * @internal - Used by User.applyUpdate() during reconstruction
-     * @param id - Unique layer ID (0-65535)
+     * Sets the layer's unique ID.
+     * @internal
+     * @param id - Unique layer ID (0-65535).
+     */
+    private setIdInternal;
+    /**
+     * Returns the internal cell buffer.
+     * @returns The `CellBuffer` instance.
+     * @internal
      */
-    setId(id: number): void;
     getData(): CellBuffer;
+    /**
+     * Returns the layer width in cells.
+     * @returns Width in cells.
+     */
     getWidth(): number;
+    /**
+     * Returns the layer height in cells.
+     * @returns Height in cells.
+     */
     getHeight(): number;
-    getCellAt(x: number, y: number): Cell | null;
     /**
-     * Marks this layer as static or dynamic
-     *
-     * Static layer: Sent only once to client via reliable channel,
-     * but continues to be rasterized client-side every frame.
-     * Used for UI elements, backgrounds, elements that never change.
+     * Returns the cell at the given coordinates.
      *
-     * Dynamic layer: Sent every tick via volatile channel.
-     * Used for animated elements, players, projectiles, etc.
+     * @param x - X coordinate (0..width-1).
+     * @param y - Y coordinate (0..height-1).
+     * @returns The cell or `null` if out of bounds.
+     */
+    getCellAt(x: number, y: number): Cell | null;
+    /**
+     * Marks this layer as reliable or volatile for network transport.
      *
-     * @param isStatic - true for static, false for dynamic
+     * @param mustBeReliable - `true` for reliable channel, `false` for volatile.
      */
-    setStatic(isStatic: boolean): void;
+    setMustBeReliable(mustBeReliable: boolean): void;
     /**
-     * Checks if this layer is static
+     * Returns whether this layer must be sent reliably.
+     *
+     * @returns `true` if reliable.
      */
-    getStatic(): boolean;
+    getMustBeReliable(): boolean;
     /**
-     * Enables or disables the layer
-     * A disabled layer will not be rendered by DisplayRasterizer
+     * Enables or disables the layer.
+     * A disabled layer will not be rendered by the display rasterizer.
      *
-     * @param enabled - true to enable, false to disable
+     * @param enabled - `true` to enable, `false` to disable.
      */
     setEnabled(enabled: boolean): void;
     /**
-     * Checks if layer is enabled
+     * Returns whether the layer is enabled.
+     *
+     * @returns `true` if enabled.
      */
     isEnabled(): boolean;
     /**
-     * Checks if layer origin changed since last tick
-     * @internal - Used to calculate UpdateFlags
+     * Returns `true` if the origin changed since the last tick.
+     * @internal
      */
     hasOriginChanged(): boolean;
     /**
-     * Checks if layer z-order changed since last tick
-     * @internal - Used to calculate UpdateFlags
+     * Returns `true` if the z-order changed since the last tick.
+     * @internal
      */
     hasZOrderChanged(): boolean;
     /**
-     * Calculates UpdateFlags based on layer state and changes
-     * @internal - Used by Core.endTick()
-     * @returns Bitpacked flags (0x00 to 0x0F)
+     * Calculates UpdateFlags based on layer state and changes.
+     * @internal
+     * @returns Bitpacked flags (0x00 to 0x0F).
      *
      * Flag structure:
      * - Bit 0 (0x01): Layer Enabled (1=active, 0=disabled)
@@ -8983,35 +9309,33 @@ declare class Layer {
      */
     calculateUpdateFlags(): number;
     /**
-     * Resets change tracking after sending a tick
-     * @internal - Used by Core.endTick()
+     * Resets change tracking after sending a tick.
+     * @internal
      */
     resetChangeTracking(): void;
     /**
-     * Marks the layer as needing to be sent on next tick
+     * Marks the layer as needing to be sent on the next tick.
      *
      * Used to optimize bandwidth by sending only modified layers.
      *
      * @example
-     * ```typescript
      * layer.addOrders([...]);
-     * layer.commit(); // Layer will be sent on next tick
-     * ```
+     * layer.commit();
      */
     commit(): void;
     /**
-     * Returns a breakdown of order types for debugging
+     * Returns a breakdown of order types for debugging.
      * @internal
      */
     private getOrdersBreakdown;
     /**
-     * Checks if layer needs to be sent
-     * @internal - Used by Core.endTick()
+     * Returns `true` if the layer needs to be sent.
+     * @internal
      */
     getNeedsCommit(): boolean;
     /**
-     * Resets commit flag after sending
-     * @internal - Used by Core.endTick()
+     * Resets the commit flag after sending.
+     * @internal
      */
     resetCommit(): void;
 }
@@ -9068,7 +9392,7 @@ declare class DisplayRasterizer {
     private static charCache;
     /**
      * Gets the cached character for a charCode, creating it lazily if needed
-     * Supports full 16-bit range (0-65535) for extended Unicode
+     * Supports full 16-bit range (0-65535) for atlas indices
      */
     private static getChar;
     /**
@@ -9090,7 +9414,7 @@ declare class DisplayRasterizer {
     constructor(engine: Core);
     /**
      * Rebuilds the RGB cache from the engine palette
-     * Call after palette modification (loadPalette, setColor)
+     * Call after palette modification (setColor, resetPalette)
      */
     rebuildColorCache(): void;
     /**
@@ -9184,60 +9508,114 @@ interface ColorOptions {
  */
 declare class OrderBuilder {
     /**
-     * Convert string or number to character code
-     * @param char - Either a string (first character used) or a number (0-65535)
-     * @returns Character code (0-65535)
+     * Converts a string or number to a char code.
+     *
+     * @param char - String (first character used) or numeric char code (0-65535).
+     * @returns Char code (0-65535).
+     *
      * @example
-     * toCharCode('#')   // → 0x23 (35)
-     * toCharCode(0x23)  // → 0x23 (35)
-     * toCharCode('ABC') // → 0x41 (65, first char only)
-     * toCharCode(256)   // → 256 (preserved for 16-bit layers)
+     * OrderBuilder.toCharCode('#')   // → 35
+     * OrderBuilder.toCharCode(35)    // → 35
+     * OrderBuilder.toCharCode('ABC') // → 65 (first char only)
+     * OrderBuilder.toCharCode(256)   // → 256 (preserved for 16-bit layers)
      */
     static toCharCode(char: string | number): number;
     /**
-     * Remove common leading whitespace from multiline strings (dedent)
-     * Useful for template literals that are indented in source code
-     * @param text - Multiline text to dedent
-     * @returns Dedented text
+     * Removes common leading whitespace from multiline strings (dedent).
+     * Useful for template literals that are indented in source code.
+     *
+     * @param text - Multiline text to dedent.
+     * @returns Dedented text.
+     *
      * @example
      * const text = `
      *   Hello
      *   World
      * `;
-     * dedent(text) // → "Hello\nWorld"
+     * OrderBuilder.dedent(text); // → "Hello\nWorld"
      */
     static dedent(text: string): string;
     /**
-     * 0x01 - Char: Single character at a position
-     * @param char - Character as string ('#') or charCode (0x23)
+     * Encodes a string into CP437 character codes packed into a string.
+     * This ensures that strings with Unicode characters (e.g. '░', 'é') are
+     * converted to their CP437 byte values (e.g. 176, 130) before being stored.
+     *
+     * @param text - The input string (possibly containing Unicode)
+     * @returns A string where each character is a CP437 byte value (0-255)
+     */
+    static encodeString(text: string): string;
+    /**
+     * Creates a single character order at a position.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param char - Character as string ('#') or numeric code (35).
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Char order.
+     *
+     * @example
+     * OrderBuilder.char(10, 20, '#', 15, 0);
      */
     static char(x: number, y: number, char: string | number, fgColor?: number, bgColor?: number): CharOrder;
     /**
-     * 0x02 - Text: Horizontal character string
+     * Creates a single-line text order.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param text - Text to draw.
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Text order.
+     *
+     * @example
+     * OrderBuilder.text(2, 4, 'Hello', 15, 0);
      */
     static text(x: number, y: number, text: string, fgColor?: number, bgColor?: number): TextOrder;
     /**
-     * 0x17 - TextMultiline: Multiple lines of text (\n for line breaks)
-     * Automatically removes common indentation (dedent) for template literals
+     * Creates a multi-line text order (\n for line breaks).
+     * Automatically dedents template literals.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param text - Text content (can include \n).
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Multiline text order.
+     *
      * @example With explicit \n
-     * OrderBuilder.textMultiline(10, 5, 'Hello\nWorld\n!', 15, 0)
+     * OrderBuilder.textMultiline(10, 5, 'Hello\nWorld\n!', 15, 0);
      *
      * @example With template literal (auto-dedented)
      * OrderBuilder.textMultiline(10, 5, `
      *   Score: ${score}
      *   Lives: ${lives}
      *   Level: ${level}
-     * `, 15, 0)
+     * `, 15, 0);
      */
     static textMultiline(x: number, y: number, text: string, fgColor?: number, bgColor?: number): TextMultilineOrder;
     /**
-     * 0x03 - SubFrame: Rectangular area with uniform colors
-     * @param frame - Array of characters as strings or numbers
+     * Creates a rectangular frame with uniform colors.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param width - Width in cells.
+     * @param height - Height in cells.
+     * @param frame - Array of characters as strings or numbers.
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Sub-frame order.
      */
     static subFrame(x: number, y: number, width: number, height: number, frame: (string | number)[], fgColor?: number, bgColor?: number): SubFrameOrder;
     /**
-     * 0x04 - SubFrameMultiColor: Rectangular area with per-cell colors
-     * @param frame - Array of cells where charCode can be string or number
+     * Creates a rectangular frame with per-cell colors.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param width - Width in cells.
+     * @param height - Height in cells.
+     * @param frame - Array of cells where `charCode` can be string or number.
+     * @returns Sub-frame order (multi-color).
      */
     static subFrameMultiColor(x: number, y: number, width: number, height: number, frame: Array<{
         charCode: string | number;
@@ -9245,13 +9623,19 @@ declare class OrderBuilder {
         fgColorCode: number;
     }>): SubFrameMultiColorOrder;
     /**
-     * 0x05 - FullFrame: Entire layer (256×256) with uniform colors
-     * @param frame - Array of characters as strings or numbers
+     * Creates a full-frame fill for the entire layer (256×256).
+     *
+     * @param frame - Array of characters as strings or numbers.
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Full-frame order.
      */
     static fullFrame(frame: (string | number)[], fgColor?: number, bgColor?: number): FullFrameOrder;
     /**
-     * 0x06 - FullFrameMultiColor: Entire layer (256×256) with per-cell colors
-     * @param frame - Array of cells where charCode can be string or number
+     * Creates a full-frame fill with per-cell colors (256×256).
+     *
+     * @param frame - Array of cells where `charCode` can be string or number.
+     * @returns Full-frame order (multi-color).
      */
     static fullFrameMultiColor(frame: Array<{
         charCode: string | number;
@@ -9259,23 +9643,52 @@ declare class OrderBuilder {
         fgColorCode: number;
     }>): FullFrameMultiColorOrder;
     /**
-     * 0x07 - Sprite: Single-color sprite at a position
+     * Creates a single-color sprite order at a position.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param spriteIndex - Sprite index in the registry.
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Sprite order.
      */
     static sprite(x: number, y: number, spriteIndex: number, fgColor?: number, bgColor?: number): SpriteOrder;
     /**
-     * 0x08 - SpriteMultiColor: Multi-color sprite at a position
+     * Creates a multi-color sprite order at a position.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param spriteIndex - Sprite index in the registry.
+     * @returns Multi-color sprite order.
      */
     static spriteMultiColor(x: number, y: number, spriteIndex: number): SpriteMultiColorOrder;
     /**
-     * 0x09 - ColorMap: Applies colors without changing characters
+     * Applies colors without changing characters.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param width - Width in cells.
+     * @param height - Height in cells.
+     * @param colorData - Array of fg/bg colors per cell.
+     * @returns Color map order.
      */
     static colorMap(x: number, y: number, width: number, height: number, colorData: Array<{
         fgColorCode: number;
         bgColorCode: number;
     }>): ColorMapOrder;
     /**
-     * 0x0A - Rectangle Shape
-     * @param options.charCode - Character as string ('█') or charCode (0x2588)
+     * Creates a rectangle shape order.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param width - Width in cells.
+     * @param height - Height in cells.
+     * @param options - Shape options.
+     * @param options.charCode - Character as string ('█') or numeric code (9608).
+     * @param options.bgColor - Background color (0-255).
+     * @param options.fgColor - Foreground color (0-255).
+     * @param options.filled - Fill shape (default: true).
+     * @returns Shape order.
      */
     static rectangle(x: number, y: number, width: number, height: number, options?: {
         charCode?: string | number;
@@ -9284,8 +9697,17 @@ declare class OrderBuilder {
         filled?: boolean;
     }): ShapeOrder;
     /**
-     * 0x0A - Circle Shape
-     * @param options.charCode - Character as string ('█') or charCode (0x2588)
+     * Creates a circle shape order.
+     *
+     * @param centerX - Center X position (cell).
+     * @param centerY - Center Y position (cell).
+     * @param radius - Radius in cells.
+     * @param options - Shape options.
+     * @param options.charCode - Character as string ('█') or numeric code (9608).
+     * @param options.bgColor - Background color (0-255).
+     * @param options.fgColor - Foreground color (0-255).
+     * @param options.filled - Fill shape (default: true).
+     * @returns Shape order.
      */
     static circle(centerX: number, centerY: number, radius: number, options?: {
         charCode?: string | number;
@@ -9294,8 +9716,17 @@ declare class OrderBuilder {
         filled?: boolean;
     }): ShapeOrder;
     /**
-     * 0x0A - Line Shape
-     * @param options.charCode - Character as string ('█') or charCode (0x2588)
+     * Creates a line shape order.
+     *
+     * @param x1 - Start X position (cell).
+     * @param y1 - Start Y position (cell).
+     * @param x2 - End X position (cell).
+     * @param y2 - End Y position (cell).
+     * @param options - Shape options.
+     * @param options.charCode - Character as string ('█') or numeric code (9608).
+     * @param options.bgColor - Background color (0-255).
+     * @param options.fgColor - Foreground color (0-255).
+     * @returns Shape order.
      */
     static line(x1: number, y1: number, x2: number, y2: number, options?: {
         charCode?: string | number;
@@ -9303,8 +9734,18 @@ declare class OrderBuilder {
         fgColor?: number;
     }): ShapeOrder;
     /**
-     * 0x0A - Ellipse Shape
-     * @param options.charCode - Character as string ('█') or charCode (0x2588)
+     * Creates an ellipse shape order.
+     *
+     * @param centerX - Center X position (cell).
+     * @param centerY - Center Y position (cell).
+     * @param radiusX - Radius on X axis (cells).
+     * @param radiusY - Radius on Y axis (cells).
+     * @param options - Shape options.
+     * @param options.charCode - Character as string ('█') or numeric code (9608).
+     * @param options.bgColor - Background color (0-255).
+     * @param options.fgColor - Foreground color (0-255).
+     * @param options.filled - Fill shape (default: true).
+     * @returns Shape order.
      */
     static ellipse(centerX: number, centerY: number, radiusX: number, radiusY: number, options?: {
         charCode?: string | number;
@@ -9313,8 +9754,20 @@ declare class OrderBuilder {
         filled?: boolean;
     }): ShapeOrder;
     /**
-     * 0x0A - Triangle Shape
-     * @param options.charCode - Character as string ('█') or charCode (0x2588)
+     * Creates a triangle shape order.
+     *
+     * @param x1 - First point X (cell).
+     * @param y1 - First point Y (cell).
+     * @param x2 - Second point X (cell).
+     * @param y2 - Second point Y (cell).
+     * @param x3 - Third point X (cell).
+     * @param y3 - Third point Y (cell).
+     * @param options - Shape options.
+     * @param options.charCode - Character as string ('█') or numeric code (9608).
+     * @param options.bgColor - Background color (0-255).
+     * @param options.fgColor - Foreground color (0-255).
+     * @param options.filled - Fill shape (default: true).
+     * @returns Shape order.
      */
     static triangle(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, options?: {
         charCode?: string | number;
@@ -9323,16 +9776,23 @@ declare class OrderBuilder {
         filled?: boolean;
     }): ShapeOrder;
     /**
-     * 0x0B - DotCloud: Same character at multiple positions
-     * @param char - Character as string ('#') or charCode (0x23)
+     * Creates a dot cloud with the same character at multiple positions.
+     *
+     * @param positions - Array of positions.
+     * @param char - Character as string ('#') or numeric code (35).
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Dot cloud order.
      */
     static dotCloud(positions: Array<{
         posX: number;
         posY: number;
     }>, char: string | number, fgColor?: number, bgColor?: number): DotCloudOrder;
     /**
-     * 0x0C - DotCloudMultiColor: Different characters at multiple positions
-     * @param dots - Array where charCode can be string or number
+     * Creates a multi-color dot cloud (per-dot colors and characters).
+     *
+     * @param dots - Array where `charCode` can be string or number.
+     * @returns Dot cloud order (multi-color).
      */
     static dotCloudMultiColor(dots: Array<{
         posX: number;
@@ -9342,25 +9802,41 @@ declare class OrderBuilder {
         fgColorCode: number;
     }>): DotCloudMultiColorOrder;
     /**
-     * 0x11 - Bitmask: Bitpacked presence/absence mask with uniform character
-     * Perfect for ore veins, destructible terrain, collision maps, fog of war
-     * @param mask - Flat array of booleans (row-major order: sizeX × sizeY)
-     * @param char - Character as string ('#') or charCode (0x23)
-     * @param override - true: clear absences (transparent), false: preserve existing cells
+     * Creates a bitmask order with a uniform character.
+     * Useful for ore veins, destructible terrain, collision maps, or fog of war.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param width - Width in cells.
+     * @param height - Height in cells.
+     * @param mask - Flat array of booleans (row-major order: sizeX × sizeY).
+     * @param char - Character as string ('#') or numeric code (35).
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @param override - true: clear absences (transparent), false: preserve existing cells.
+     * @returns Bitmask order.
+     *
      * @example Create a 3×3 cross pattern
      * OrderBuilder.bitmask(10, 10, 3, 3, [
      *   false, true,  false,
      *   true,  true,  true,
      *   false, true,  false
-     * ], '#', 15, 0, false)
+     * ], '#', 15, 0, false);
      */
     static bitmask(x: number, y: number, width: number, height: number, mask: boolean[], char: string | number, fgColor?: number, bgColor?: number, override?: boolean): BitmaskOrder;
     /**
-     * 0x12 - Bitmask4: 2-bit packed mask with 3 visual variants
-     * @param mask - Flat array of values 0-3 (row-major order: sizeX × sizeY)
-     *               0 = absence, 1-3 = variant index
-     * @param variants - Array of up to 3 variants { char, fgColor, bgColor } for values 1, 2, 3
-     * @param override - true: clear absences (transparent), false: preserve existing cells
+     * Creates a bitmask order with 3 visual variants (values 1..3).
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param width - Width in cells.
+     * @param height - Height in cells.
+     * @param mask - Flat array of values 0-3 (row-major order: sizeX × sizeY).
+     *   0 = absence, 1-3 = variant index.
+     * @param variants - Array of up to 3 variants { char, fgColor, bgColor } for values 1..3.
+     * @param override - true: clear absences (transparent), false: preserve existing cells.
+     * @returns Bitmask4 order.
+     *
      * @example Create a 3×3 pattern with 3 variants
      * OrderBuilder.bitmask4(10, 10, 3, 3, [
      *   0, 1, 0,
@@ -9370,7 +9846,7 @@ declare class OrderBuilder {
      *   { char: 'a', fgColor: 15, bgColor: 0 },
      *   { char: 'b', fgColor: 14, bgColor: 0 },
      *   { char: 'c', fgColor: 13, bgColor: 0 }
-     * ], false)
+     * ], false);
      */
     static bitmask4(x: number, y: number, width: number, height: number, mask: number[], variants: Array<{
         char: string | number;
@@ -9378,11 +9854,18 @@ declare class OrderBuilder {
         bgColor: number;
     }>, override?: boolean): Bitmask4Order;
     /**
-     * 0x18 - Bitmask16: 4-bit packed mask with 15 visual variants
-     * @param mask - Flat array of values 0-15 (row-major order: sizeX × sizeY)
-     *               0 = absence, 1-15 = variant index
-     * @param variants - Array of up to 15 variants { char, fgColor, bgColor } for values 1-15
-     * @param override - true: clear absences (transparent), false: preserve existing cells
+     * Creates a bitmask order with up to 15 visual variants (values 1..15).
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param width - Width in cells.
+     * @param height - Height in cells.
+     * @param mask - Flat array of values 0-15 (row-major order: sizeX × sizeY).
+     *   0 = absence, 1-15 = variant index.
+     * @param variants - Array of up to 15 variants { char, fgColor, bgColor } for values 1..15.
+     * @param override - true: clear absences (transparent), false: preserve existing cells.
+     * @returns Bitmask16 order.
+     *
      * @example Create a 3×3 pattern with multiple variants
      * OrderBuilder.bitmask16(10, 10, 3, 3, [
      *   0,  1,  0,
@@ -9392,7 +9875,7 @@ declare class OrderBuilder {
      *   { char: 'a', fgColor: 15, bgColor: 0 },
      *   { char: 'b', fgColor: 14, bgColor: 0 },
      *   // ... up to 15 variants
-     * ], false)
+     * ], false);
      */
     static bitmask16(x: number, y: number, width: number, height: number, mask: number[], variants: Array<{
         char: string | number;
@@ -9400,21 +9883,34 @@ declare class OrderBuilder {
         bgColor: number;
     }>, override?: boolean): Bitmask16Order;
     /**
-     * 0x0D - SpriteCloud: Same single-color sprite at multiple positions
+     * Creates a sprite cloud with a single-color sprite at multiple positions.
+     *
+     * @param spriteIndex - Sprite index in the registry.
+     * @param positions - Array of positions.
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Sprite cloud order.
      */
     static spriteCloud(spriteIndex: number, positions: Array<{
         posX: number;
         posY: number;
     }>, fgColor?: number, bgColor?: number): SpriteCloudOrder;
     /**
-     * 0x0E - SpriteCloudMultiColor: Same multi-color sprite at multiple positions
+     * Creates a multi-color sprite cloud at multiple positions.
+     *
+     * @param spriteIndex - Sprite index in the registry.
+     * @param positions - Array of positions.
+     * @returns Multi-color sprite cloud order.
      */
     static spriteCloudMultiColor(spriteIndex: number, positions: Array<{
         posX: number;
         posY: number;
     }>): SpriteCloudMultiColorOrder;
     /**
-     * 0x0F - SpriteCloudVaried: Different single-color sprites at multiple positions
+     * Creates a varied sprite cloud (single-color sprites per position).
+     *
+     * @param sprites - Array of sprites with position and colors.
+     * @returns Varied sprite cloud order.
      */
     static spriteCloudVaried(sprites: Array<{
         posX: number;
@@ -9424,7 +9920,10 @@ declare class OrderBuilder {
         fgColorCode: number;
     }>): SpriteCloudVariedOrder;
     /**
-     * 0x10 - SpriteCloudVariedMultiColor: Different multi-color sprites at multiple positions
+     * Creates a varied sprite cloud with multi-color sprites.
+     *
+     * @param sprites - Array of sprites with position.
+     * @returns Varied multi-color sprite cloud order.
      */
     static spriteCloudVariedMultiColor(sprites: Array<{
         posX: number;
@@ -9432,27 +9931,53 @@ declare class OrderBuilder {
         spriteIndex: number;
     }>): SpriteCloudVariedMultiColorOrder;
     /**
-     * 0x13 - Clear: Fills entire layer with a character
-     * @param char - Character as string (' ') or charCode (0x20)
+     * Fills the entire layer with a character.
+     *
+     * @param char - Character as string (' ') or numeric code (32).
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Clear order.
      */
     static clear(char?: string | number, fgColor?: number, bgColor?: number): ClearOrder;
     /**
-     * 0x14 - FillChar: Fills layer with a repeating pattern
-     * @param pattern - Array of characters as strings or numbers
+     * Fills the layer with a repeating character pattern.
+     *
+     * @param patternWidth - Pattern width in cells.
+     * @param patternHeight - Pattern height in cells.
+     * @param pattern - Array of characters as strings or numbers.
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Fill character order.
      */
     static fillChar(patternWidth: number, patternHeight: number, pattern: (string | number)[], fgColor?: number, bgColor?: number): FillCharOrder;
     /**
-     * 0x15 - FillSprite: Fills layer with a repeating single-color sprite
+     * Fills the layer with a repeating single-color sprite.
+     *
+     * @param spriteIndex - Sprite index in the registry.
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Fill sprite order.
      */
     static fillSprite(spriteIndex: number, fgColor?: number, bgColor?: number): FillSpriteOrder;
     /**
-     * 0x16 - FillSpriteMultiColor: Fills layer with a repeating multi-color sprite
+     * Fills the layer with a repeating multi-color sprite.
+     *
+     * @param spriteIndex - Sprite index in the registry.
+     * @returns Fill multi-color sprite order.
      */
     static fillSpriteMultiColor(spriteIndex: number): FillSpriteMultiColorOrder;
     /**
-     * Helper: Create a rectangle with colored border and different interior
-     * @param borderOptions.charCode - Character as string ('█') or charCode (0x2588)
-     * @param fillOptions.charCode - Character as string ('█') or charCode (0x2588)
+     * Creates a rectangle with a colored border and a different interior.
+     *
+     * @param x - X position (cell).
+     * @param y - Y position (cell).
+     * @param width - Width in cells.
+     * @param height - Height in cells.
+     * @param borderOptions - Border colors/char.
+     * @param borderOptions.charCode - Character as string ('█') or numeric code (9608).
+     * @param fillOptions - Fill colors/char.
+     * @param fillOptions.charCode - Character as string ('█') or numeric code (9608).
+     * @returns Array of shape orders (fill + border).
      */
     static boxWithBorder(x: number, y: number, width: number, height: number, borderOptions: ColorOptions & {
         charCode?: string | number;
@@ -9460,25 +9985,35 @@ declare class OrderBuilder {
         charCode?: string | number;
     }): ShapeOrder[];
     /**
-     * Helper: Create a grid of points
-     * @param options.charCode - Character as string ('+') or charCode (0x2b)
+     * Creates a grid of points.
+     *
+     * @param startX - Grid start X (cell).
+     * @param startY - Grid start Y (cell).
+     * @param cellWidth - Cell width in cells.
+     * @param cellHeight - Cell height in cells.
+     * @param rows - Number of rows.
+     * @param cols - Number of columns.
+     * @param options - Color options.
+     * @param options.charCode - Character as string ('+') or numeric code (43).
+     * @returns Dot cloud order.
      */
     static grid(startX: number, startY: number, cellWidth: number, cellHeight: number, rows: number, cols: number, options?: ColorOptions): DotCloudOrder;
     /**
-     * 0x19 - Polyline: Connected line segments through multiple points
-     * Uses Bresenham algorithm to draw lines between consecutive points
+     * Creates a polyline (connected line segments through multiple points).
+     * Uses Bresenham algorithm between consecutive points.
      *
-     * @param points - Array of points to connect (minimum 2 for a line)
-     * @param char - Character as string ('*') or charCode (0x2A)
-     * @param fgColor - Foreground color (default: 15 = white)
-     * @param bgColor - Background color (default: 0 = black)
+     * @param points - Array of points to connect (minimum 2 for a line).
+     * @param char - Character as string ('*') or numeric code (42).
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Polyline order.
      *
      * @example Simple line
      * ```typescript
      * OrderBuilder.polyline(
      *   [{ x: 0, y: 0 }, { x: 10, y: 5 }],
      *   '*', 14, 0
-     * )
+     * );
      * ```
      *
      * @example Path with multiple points
@@ -9491,7 +10026,7 @@ declare class OrderBuilder {
      *     { x: 40, y: 20 }
      *   ],
      *   '#', 11, 0
-     * )
+     * );
      * ```
      */
     static polyline(points: Array<{
@@ -9499,23 +10034,31 @@ declare class OrderBuilder {
         y: number;
     }>, char?: string | number, fgColor?: number, bgColor?: number): PolylineOrder;
     /**
-     * Helper: Create a polyline from flat coordinate array
-     * @param coords - Flat array of coordinates [x1, y1, x2, y2, ...]
-     * @param char - Character as string ('*') or charCode
+     * Creates a polyline from a flat coordinate array.
+     *
+     * @param coords - Flat array of coordinates [x1, y1, x2, y2, ...].
+     * @param char - Character as string ('*') or numeric code.
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Polyline order.
      *
      * @example
      * ```typescript
      * OrderBuilder.polylineFromCoords(
-     *   [0, 0, 10, 5, 20, 0],  // 3 points
+     *   [0, 0, 10, 5, 20, 0], // 3 points
      *   '-', 14
-     * )
+     * );
      * ```
      */
     static polylineFromCoords(coords: number[], char?: string | number, fgColor?: number, bgColor?: number): PolylineOrder;
     /**
-     * Helper: Create a closed polygon (polyline that returns to start)
-     * @param points - Array of points forming the polygon
-     * @param char - Character as string ('*') or charCode
+     * Creates a closed polygon (polyline that returns to start).
+     *
+     * @param points - Array of points forming the polygon.
+     * @param char - Character as string ('*') or numeric code.
+     * @param fgColor - Foreground color (0-255).
+     * @param bgColor - Background color (0-255).
+     * @returns Polyline order.
      *
      * @example Triangle
      * ```typescript
@@ -9526,7 +10069,7 @@ declare class OrderBuilder {
      *     { x: 30, y: 15 }
      *   ],
      *   '#', 12
-     * )
+     * );
      * ```
      */
     static polygon(points: Array<{