@utsp/core 0.14.0-nightly.20251219144833.1c27cfe → 0.14.0

package/dist/benchmark.d.ts

@@ -1467,7 +1467,13 @@ declare enum PostProcessOrderType {
      *
      * Parameters: slotId (0-255)
      */
-    SwitchPalette = 6
+    SwitchPalette = 6,
+    /**
+     * 0x07 - SetCellSize: Set cell dimensions in pixels
+     *
+     * Parameters: cellWidth (1-255), cellHeight (1-255)
+     */
+    SetCellSize = 7
 }
 
 /**
@@ -1487,18 +1493,25 @@ declare enum ScanlinesPatternType {
 }
 /**
  * Base interface for all post-process orders
+ *
+ * All post-process orders are scoped to a specific display.
+ * The displayId identifies which display the order applies to.
  */
 interface PostProcessOrderBase {
+    /** Order type identifier */
     type: PostProcessOrderType;
+    /** Display ID this order applies to (0-255) */
+    displayId: number;
 }
 /**
  * SetConfig Order (0x01)
  *
- * Sets the full post-process configuration.
+ * Sets the full post-process configuration for a specific display.
  * Flags indicate which optional sections are present.
  *
  * Binary format:
  * - type: 1 byte (0x01)
+ * - displayId: 1 byte (0-255)
  * - flags: 1 byte (PostProcessConfigFlags)
  * - [if HasScanlines]:
  *   - enabled: 1 byte (0 or 1)
@@ -1536,10 +1549,11 @@ interface SetConfigOrder extends PostProcessOrderBase {
 /**
  * SetScanlines Order (0x02)
  *
- * Sets only the scanlines configuration.
+ * Sets only the scanlines configuration for a specific display.
  *
  * Binary format:
  * - type: 1 byte (0x02)
+ * - displayId: 1 byte (0-255)
  * - enabled: 1 byte (0 or 1)
  * - opacity: 1 byte (0-255, scaled from 0.0-1.0)
  * - pattern: 1 byte (ScanlinesPatternType)
@@ -1559,10 +1573,11 @@ interface SetScanlinesOrder extends PostProcessOrderBase {
 /**
  * SetAmbientEffect Order (0x03)
  *
- * Sets only the ambient effect configuration.
+ * Sets only the ambient effect configuration for a specific display.
  *
  * Binary format:
  * - type: 1 byte (0x03)
+ * - displayId: 1 byte (0-255)
  * - enabled: 1 byte (0 or 1)
  * - blur: 1 byte (0-255 pixels)
  * - scale: 1 byte (100-255, scaled from 1.0-2.55)
@@ -1578,10 +1593,11 @@ interface SetAmbientEffectOrder extends PostProcessOrderBase {
 /**
  * SetScalingMode Order (0x04)
  *
- * Sets the pixel-perfect scaling mode.
+ * Sets the pixel-perfect scaling mode for a specific display.
  *
  * Binary format:
  * - type: 1 byte (0x04)
+ * - displayId: 1 byte (0-255)
  * - mode: 1 byte (ScalingModeValue)
  */
 interface SetScalingModeOrder extends PostProcessOrderBase {
@@ -1591,10 +1607,11 @@ interface SetScalingModeOrder extends PostProcessOrderBase {
 /**
  * SetGrid Order (0x05)
  *
- * Sets the debug grid overlay configuration.
+ * Sets the debug grid overlay configuration for a specific display.
  *
  * Binary format:
  * - type: 1 byte (0x05)
+ * - displayId: 1 byte (0-255)
  * - enabled: 1 byte (0 or 1)
  * - colorR: 1 byte (0-255)
  * - colorG: 1 byte (0-255)
@@ -1614,21 +1631,39 @@ interface SetGridOrder extends PostProcessOrderBase {
 /**
  * SwitchPalette Order (0x06)
  *
- * Switches to a pre-loaded palette slot.
+ * Switches to a pre-loaded palette slot for a specific display.
  * The palette must have been loaded to the Core via loadPaletteToSlot() first.
  *
  * Binary format:
  * - type: 1 byte (0x06)
+ * - displayId: 1 byte (0-255)
  * - slotId: 1 byte (0-255)
  */
 interface SwitchPaletteOrder extends PostProcessOrderBase {
     type: PostProcessOrderType.SwitchPalette;
     slotId: number;
 }
+/**
+ * SetCellSize Order (0x07)
+ *
+ * Sets the cell dimensions in pixels for a specific display.
+ * Used to configure the renderer's native cell size.
+ *
+ * Binary format:
+ * - type: 1 byte (0x07)
+ * - displayId: 1 byte (0-255)
+ * - cellWidth: 1 byte (1-255 pixels)
+ * - cellHeight: 1 byte (1-255 pixels)
+ */
+interface SetCellSizeOrder extends PostProcessOrderBase {
+    type: PostProcessOrderType.SetCellSize;
+    cellWidth: number;
+    cellHeight: number;
+}
 /**
  * Union type for all post-process orders
  */
-type AnyPostProcessOrder = SetConfigOrder | SetScanlinesOrder | SetAmbientEffectOrder | SetScalingModeOrder | SetGridOrder | SwitchPaletteOrder;
+type AnyPostProcessOrder = SetConfigOrder | SetScanlinesOrder | SetAmbientEffectOrder | SetScalingModeOrder | SetGridOrder | SwitchPaletteOrder | SetCellSizeOrder;
 
 /**
  * Update packet according to the new UTSP protocol
@@ -4281,6 +4316,7 @@ declare class User<TData = Record<string, any>> {
     private bytesTickRate;
     private currentTickBytesSent;
     private currentTickBytesReceived;
+    private availableViewports;
     /**
      * Application-specific data storage
      * Use this to store game state, player data, or any custom information
@@ -4310,6 +4346,78 @@ declare class User<TData = Record<string, any>> {
      * Removes all displays from the user
      */
     clearDisplays(): void;
+    /**
+     * Sets the available viewport size (in pixels) for a display
+     *
+     * Called by the server when receiving viewport information from the client.
+     * The application can use this to adapt display resolution.
+     *
+     * @param displayId - Display ID (0-255)
+     * @param pixelWidth - Available width in pixels (0-65535)
+     * @param pixelHeight - Available height in pixels (0-65535)
+     *
+     * @example
+     * ```typescript
+     * // Called automatically by decodeAndApplyCompressedInput()
+     * user.setDisplayViewport(0, 800, 600);
+     * ```
+     */
+    setDisplayViewport(displayId: number, pixelWidth: number, pixelHeight: number): void;
+    /**
+     * Gets the available viewport size (in pixels) for a display
+     *
+     * @param displayId - Display ID (0-255)
+     * @returns Viewport size in pixels, or null if not set
+     *
+     * @example
+     * ```typescript
+     * const viewport = user.getDisplayViewport(0);
+     * if (viewport) {
+     *   console.log(`Available: ${viewport.pixelWidth}x${viewport.pixelHeight}px`);
+     * }
+     * ```
+     */
+    getDisplayViewport(displayId: number): {
+        pixelWidth: number;
+        pixelHeight: number;
+    } | null;
+    /**
+     * Gets all available viewports (in pixels)
+     *
+     * @returns Map of displayId → viewport size
+     */
+    getAllDisplayViewports(): Map<number, {
+        pixelWidth: number;
+        pixelHeight: number;
+    }>;
+    /**
+     * Calculates the maximum number of cells that fit in a display's available viewport
+     *
+     * Helper method that divides pixel dimensions by cell size to get max cells.
+     * The application can use this to decide the optimal display resolution.
+     *
+     * @param displayId - Display ID (0-255)
+     * @param cellWidth - Width of a cell in pixels (e.g., 8 for 8px font)
+     * @param cellHeight - Height of a cell in pixels (e.g., 16 for 16px font)
+     * @returns Max cells { cols, rows }, or null if viewport not set
+     *
+     * @example
+     * ```typescript
+     * // With 8x16 font, calculate how many cells fit in available space
+     * const maxCells = user.calculateMaxCells(0, 8, 16);
+     * if (maxCells) {
+     *   const display = user.getDisplays()[0];
+     *   display.setSize(new Vector2(
+     *     Math.min(maxCells.cols, 120),  // Cap at 120 columns
+     *     Math.min(maxCells.rows, 40)    // Cap at 40 rows
+     *   ));
+     * }
+     * ```
+     */
+    calculateMaxCells(displayId: number, cellWidth: number, cellHeight: number): {
+        cols: number;
+        rows: number;
+    } | null;
     getLayers(): Layer[];
     /**
      * Gets a layer by its ID
@@ -4968,6 +5076,12 @@ declare class User<TData = Record<string, any>> {
      *   // Values are now available
      *   const move = user.getAxis("MoveHorizontal");
      *   if (user.getButton("Jump")) { ... }
+     *
+     *   // Viewport info is available via:
+     *   const viewport = user.getDisplayViewport(0);
+     *   if (viewport) {
+     *     console.log(`Available: ${viewport.pixelWidth}x${viewport.pixelHeight}px`);
+     *   }
      * });
      * ```
      */
@@ -5819,17 +5933,18 @@ declare class User<TData = Record<string, any>> {
      */
     macroActivateFocused(): void;
     /**
-     * Set post-processing configuration
+     * Set post-processing configuration for a specific display
      *
      * The post-process overlay is rendered ONCE when this is called.
      * No per-frame cost - only updates when you call this method.
      *
+     * @param displayId - Display ID (0-255) this setting applies to
      * @param config - Post-processing configuration (or null to disable)
      *
      * @example
      * ```typescript
-     * // Enable scanlines effect
-     * user.setPostProcess({
+     * // Enable scanlines effect on display 0
+     * user.setPostProcess(0, {
      *   scanlines: {
      *     enabled: true,
      *     opacity: 0.15,
@@ -5837,105 +5952,112 @@ declare class User<TData = Record<string, any>> {
      *   }
      * });
      *
-     * // Disable all post-processing
-     * user.setPostProcess(null);
+     * // Disable all post-processing on display 0
+     * user.setPostProcess(0, null);
      * ```
      */
-    setPostProcess(config: PostProcessConfig | null): void;
+    setPostProcess(displayId: number, config: PostProcessConfig | null): void;
     /**
-     * Enable or disable scanlines effect with default/current settings
+     * Enable or disable scanlines effect with default/current settings for a specific display
      *
+     * @param displayId - Display ID (0-255)
      * @param enabled - Whether to enable scanlines
      *
      * @example
      * ```typescript
-     * user.setScanlinesEnabled(true);  // Enable with defaults
-     * user.setScanlinesEnabled(false); // Disable
+     * user.setScanlinesEnabled(0, true);  // Enable with defaults on display 0
+     * user.setScanlinesEnabled(0, false); // Disable on display 0
      * ```
      */
-    setScanlinesEnabled(enabled: boolean): void;
+    setScanlinesEnabled(displayId: number, enabled: boolean): void;
     /**
-     * Set scanlines opacity (0-1)
+     * Set scanlines opacity (0-1) for a specific display
      *
      * Also enables scanlines if not already enabled.
      *
+     * @param displayId - Display ID (0-255)
      * @param opacity - Opacity of dark lines (0 = invisible, 1 = fully opaque)
      *
      * @example
      * ```typescript
-     * user.setScanlinesOpacity(0.2); // Subtle effect
-     * user.setScanlinesOpacity(0.5); // Strong effect
+     * user.setScanlinesOpacity(0, 0.2); // Subtle effect on display 0
+     * user.setScanlinesOpacity(0, 0.5); // Strong effect on display 0
      * ```
      */
-    setScanlinesOpacity(opacity: number): void;
+    setScanlinesOpacity(displayId: number, opacity: number): void;
     /**
-     * Set scanlines pattern
+     * Set scanlines pattern for a specific display
      *
+     * @param displayId - Display ID (0-255)
      * @param pattern - Pattern type: 'horizontal', 'vertical', or 'grid'
      */
-    setScanlinesPattern(pattern: 'horizontal' | 'vertical' | 'grid'): void;
+    setScanlinesPattern(displayId: number, pattern: 'horizontal' | 'vertical' | 'grid'): void;
     /**
-     * Enable or configure ambient effect
+     * Enable or configure ambient effect for a specific display
      *
      * Ambient effect creates a blurred glow around the terminal canvas,
      * filling the unused space with colors from the terminal content.
      * This effect is GPU-accelerated (CSS blur) and has zero CPU cost.
      *
+     * @param displayId - Display ID (0-255)
      * @param config - true to enable with defaults, false to disable,
      *                 or object with blur and scale settings
      *
      * @example
      * ```typescript
-     * // Enable with defaults (blur: 30px, scale: 1.3)
-     * user.setAmbientEffect(true);
+     * // Enable with defaults (blur: 30px, scale: 1.3) on display 0
+     * user.setAmbientEffect(0, true);
      *
-     * // Disable
-     * user.setAmbientEffect(false);
+     * // Disable on display 0
+     * user.setAmbientEffect(0, false);
      *
-     * // Custom settings
-     * user.setAmbientEffect({ blur: 50, scale: 1.5 });
+     * // Custom settings on display 1
+     * user.setAmbientEffect(1, { blur: 50, scale: 1.5 });
      * ```
      */
-    setAmbientEffect(config: boolean | {
+    setAmbientEffect(displayId: number, config: boolean | {
         blur?: number;
         scale?: number;
     }): void;
     /**
-     * Enable or disable ambient effect
+     * Enable or disable ambient effect for a specific display
      *
+     * @param displayId - Display ID (0-255)
      * @param enabled - Whether to enable ambient effect
      *
      * @example
      * ```typescript
-     * user.setAmbientEffectEnabled(true);  // Enable with defaults
-     * user.setAmbientEffectEnabled(false); // Disable
+     * user.setAmbientEffectEnabled(0, true);  // Enable with defaults on display 0
+     * user.setAmbientEffectEnabled(0, false); // Disable on display 0
      * ```
      */
-    setAmbientEffectEnabled(enabled: boolean): void;
+    setAmbientEffectEnabled(displayId: number, enabled: boolean): void;
     /**
-     * Set ambient effect blur intensity
+     * Set ambient effect blur intensity for a specific display
      *
+     * @param displayId - Display ID (0-255)
      * @param blur - Blur intensity in pixels (default: 30)
      *
      * @example
      * ```typescript
-     * user.setAmbientEffectBlur(50); // More blur
-     * user.setAmbientEffectBlur(15); // Less blur
+     * user.setAmbientEffectBlur(0, 50); // More blur on display 0
+     * user.setAmbientEffectBlur(0, 15); // Less blur on display 0
      * ```
      */
-    setAmbientEffectBlur(blur: number): void;
+    setAmbientEffectBlur(displayId: number, blur: number): void;
     /**
-     * Set ambient effect scale factor
+     * Set ambient effect scale factor for a specific display
      *
+     * @param displayId - Display ID (0-255)
      * @param scale - Scale factor for the glow (default: 1.3)
      *
      * @example
      * ```typescript
-     * user.setAmbientEffectScale(1.5); // Larger glow area
-     * user.setAmbientEffectScale(1.1); // Smaller glow area
+     * user.setAmbientEffectScale(0, 1.5); // Larger glow area on display 0
+     * user.setAmbientEffectScale(0, 1.1); // Smaller glow area on display 0
      * ```
      */
-    setAmbientEffectScale(scale: number): void;
+    setAmbientEffectScale(displayId: number, scale: number): void;
     /**
      * Check if ambient effect is currently enabled
      */
@@ -5962,16 +6084,18 @@ declare class User<TData = Record<string, any>> {
      * @internal
      */
     flushPostProcessCommands(): PostProcessCommand[];
-    /** Current scaling mode */
-    private currentScalingMode;
+    /** Current scaling mode per display (Map<displayId, mode>) */
+    private currentScalingModes;
     /**
-     * Set the pixel-perfect scaling mode
+     * Set the pixel-perfect scaling mode for a specific display
      *
      * Controls how the terminal canvas is scaled to fit the available space.
      * Stricter modes produce crisper pixels but may leave empty space.
      *
+     * @param displayId - Display ID (0-255) this setting applies to
      * @param mode - Scaling mode:
      *   - `'none'`: Fill space, may have sub-pixel artifacts (default)
+     *   - `'responsive'`: Fixed cell size, cols/rows adapt to fill space
      *   - `'eighth'`: Snap to 0.125 increments (1.0, 1.125, 1.25...)
      *   - `'quarter'`: Snap to 0.25 increments (1.0, 1.25, 1.5...)
      *   - `'half'`: Snap to 0.5 increments (1.0, 1.5, 2.0...)
@@ -5979,74 +6103,120 @@ declare class User<TData = Record<string, any>> {
      *
      * @example
      * ```typescript
-     * // For crisp retro-style pixels
-     * user.setScalingMode('integer');
+     * // For crisp retro-style pixels on display 0
+     * user.setScalingMode(0, 'integer');
      *
-     * // For balanced quality
-     * user.setScalingMode('quarter');
+     * // For balanced quality on display 1
+     * user.setScalingMode(1, 'quarter');
      *
-     * // Fill all available space
-     * user.setScalingMode('none');
+     * // Fill all available space on display 0
+     * user.setScalingMode(0, 'none');
      * ```
      */
-    setScalingMode(mode: ScalingMode): void;
+    setScalingMode(displayId: number, mode: ScalingMode): void;
     /**
-     * Get current scaling mode
+     * Get current scaling mode for a display
      *
+     * @param displayId - Display ID (0-255)
+     * @param displayId - Display ID (0-255)
      * @returns Current scaling mode or null if not set
      */
-    getScalingMode(): ScalingMode | null;
-    /** Current grid configuration */
-    private currentGridConfig;
+    getScalingMode(displayId: number): ScalingMode | null;
+    /** Current cell size configuration per display (Map<displayId, {width, height}>) */
+    private currentCellSizes;
     /**
-     * Enable or configure the debug grid overlay
+     * Set the cell dimensions in pixels for a specific display (for Responsive mode)
+     *
+     * This is only relevant when using `setScalingMode(displayId, 'responsive')`.
+     * In responsive mode, the cell size is fixed and the number of cols/rows
+     * adapts to fill the available space.
+     *
+     * In other scaling modes (integer, quarter, half, none), the cell size
+     * comes from the font/atlas and CSS scaling is applied to fill space.
+     *
+     * @param displayId - Display ID (0-255) this setting applies to
+     * @param width - Cell width in pixels (1-255, default: 8)
+     * @param height - Cell height in pixels (1-255, default: 8)
+     *
+     * @example
+     * ```typescript
+     * // Responsive mode with 8x8 cells on display 0
+     * user.setScalingMode(0, 'responsive');
+     * user.setCellSize(0, 8, 8);
+     *
+     * // Responsive mode with larger 16x16 tiles on display 1
+     * user.setScalingMode(1, 'responsive');
+     * user.setCellSize(1, 16, 16);
+     * ```
+     */
+    setCellSize(displayId: number, width: number, height: number): void;
+    /**
+     * 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;
+    };
+    /** Current grid configuration per display (Map<displayId, GridConfig>) */
+    private currentGridConfigs;
+    /**
+     * Enable or configure the debug grid overlay for a specific display
      *
      * The grid shows cell boundaries aligned with the terminal grid.
      * Useful for debugging layout and alignment issues.
      *
+     * @param displayId - Display ID (0-255) this setting applies to
      * @param config - true to enable with defaults, false to disable,
      *                 or object with color and lineWidth settings
      *
      * @example
      * ```typescript
-     * // Enable with default red grid
-     * user.setGrid(true);
+     * // Enable with default red grid on display 0
+     * user.setGrid(0, true);
      *
-     * // Disable
-     * user.setGrid(false);
+     * // Disable on display 0
+     * user.setGrid(0, false);
      *
-     * // Custom green grid
-     * user.setGrid({ enabled: true, color: 'rgba(0, 255, 0, 0.5)' });
+     * // Custom green grid on display 1
+     * user.setGrid(1, { enabled: true, color: 'rgba(0, 255, 0, 0.5)' });
      *
-     * // Custom with thicker lines
-     * user.setGrid({ enabled: true, color: '#ff0000', lineWidth: 2 });
+     * // Custom with thicker lines on display 0
+     * user.setGrid(0, { enabled: true, color: '#ff0000', lineWidth: 2 });
      * ```
      */
-    setGrid(config: boolean | GridConfig): void;
+    setGrid(displayId: number, config: boolean | GridConfig): void;
     /**
-     * Enable or disable the grid
+     * Enable or disable the grid for a specific display
      *
+     * @param displayId - Display ID (0-255)
      * @param enabled - Whether to show the grid
      *
      * @example
      * ```typescript
-     * user.setGridEnabled(true);  // Show grid
-     * user.setGridEnabled(false); // Hide grid
+     * user.setGridEnabled(0, true);  // Show grid on display 0
+     * user.setGridEnabled(0, false); // Hide grid on display 0
      * ```
      */
-    setGridEnabled(enabled: boolean): void;
+    setGridEnabled(displayId: number, enabled: boolean): void;
     /**
-     * Check if grid is currently enabled
+     * Check if grid is currently enabled for a display
+     *
+     * @param displayId - Display ID (0-255)
      */
-    isGridEnabled(): boolean;
+    isGridEnabled(displayId: number): boolean;
     /**
-     * Get current grid configuration
+     * Get current grid configuration for a display
+     *
+     * @param displayId - Display ID (0-255)
      */
-    getGridConfig(): GridConfig | null;
-    /** Currently active palette slot ID */
-    private currentPaletteSlotId;
+    getGridConfig(displayId: number): GridConfig | null;
+    /** Currently active palette slot ID per display (Map<displayId, slotId>) */
+    private currentPaletteSlotIds;
     /**
-     * Switch to a pre-loaded palette slot
+     * Switch to a pre-loaded palette slot for a specific display
      *
      * The palette must have been loaded to the Core via `core.loadPaletteToSlot()` first.
      * This allows instant palette switching without re-sending palette data over the network.
@@ -6057,6 +6227,7 @@ declare class User<TData = Record<string, any>> {
      * - Accessibility options (high contrast)
      * - Visual effects (damage flash, power-up)
      *
+     * @param displayId - Display ID (0-255) this setting applies to
      * @param slotId - Palette slot ID (0-255)
      *
      * @example
@@ -6068,24 +6239,24 @@ declare class User<TData = Record<string, any>> {
      *
      * // In IApplication.updateUser() - switch based on game state
      * if (gameState.isNight) {
-     *   user.switchPalette(1);
+     *   user.switchPalette(0, 1); // display 0, night palette
      * } else {
-     *   user.switchPalette(0);
+     *   user.switchPalette(0, 0); // display 0, day palette
      * }
      *
-     * // Zone-based switching
-     * if (player.enteredDungeon) {
-     *   user.switchPalette(2);
-     * }
+     * // Different palettes for different displays (split-screen)
+     * user.switchPalette(0, dayPalette);    // Player 1 display
+     * user.switchPalette(1, nightPalette);  // Player 2 display
      * ```
      */
-    switchPalette(slotId: number): void;
+    switchPalette(displayId: number, slotId: number): void;
     /**
-     * Get the currently active palette slot ID
+     * 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(): number | null;
+    getCurrentPaletteSlotId(displayId: number): number | null;
     /**
      * Send data through the bridge channel to the client application
      *