@utsp/core 0.14.2 → 0.15.0-nightly.20251230160137.3077b87

package/dist/index.d.ts

@@ -2524,6 +2524,8 @@ interface NetworkLayer {
     height: number;
     orderCount: number;
     orders: AnyNetworkOrder[];
+    /** Optional decoded byte size of this layer segment in the update packet */
+    byteSize?: number;
     /**
      * CharCode mode for this layer
      * - false: 8-bit charCodes (0-255)
@@ -2820,6 +2822,18 @@ interface UpdatePacket {
     postProcessOrderCount: number;
     /** List of post-process orders (scanlines, ambient effect) */
     postProcessOrders: AnyPostProcessOrder[];
+    /**
+     * Optional: precise byte sizes (on-wire) for each section in this decoded packet.
+     * Intended for debugging/telemetry (client-side). Not required for protocol correctness.
+     */
+    __byteSizes?: {
+        displays: number;
+        layers: number;
+        audioOrders: number;
+        vibrationOrders: number;
+        macroOrders: number;
+        postProcessOrders: number;
+    };
 }
 
 /**
@@ -2882,6 +2896,20 @@ declare class Display {
      * Sets the display size
      */
     setSize(size: Vector2): void;
+    /**
+     * Returns a debug-friendly snapshot of this display (metadata only)
+     */
+    getDebugInfo(): {
+        id: number;
+        origin: {
+            x: number;
+            y: number;
+        };
+        size: {
+            x: number;
+            y: number;
+        };
+    };
 }
 
 /**
@@ -2893,6 +2921,8 @@ declare const MAX_ORDERS_PER_LAYER = 255;
  * Layer configuration options
  */
 interface LayerOptions {
+    /** 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
@@ -2908,6 +2938,7 @@ interface LayerOptions {
 }
 declare class Layer {
     private id;
+    private name?;
     private origin;
     private orders;
     private zOrder;
@@ -3002,6 +3033,34 @@ declare class Layer {
      * @returns Layer ID (0-65535)
      */
     getId(): number;
+    /**
+     * Gets the layer's optional name (debug/metadata only)
+     */
+    getName(): string | undefined;
+    /**
+     * Sets the layer's optional name (debug/metadata only)
+     */
+    setName(name: string | undefined): void;
+    /**
+     * Returns a debug-friendly snapshot of this layer (metadata only)
+     */
+    getDebugInfo(): {
+        id: number;
+        name?: string;
+        z: number;
+        isStatic: boolean;
+        charCodeMode: CharCodeMode;
+        width: number;
+        height: number;
+        origin: {
+            x: number;
+            y: number;
+        };
+        enabled: boolean;
+        useSetMode: boolean;
+        needsCommit: boolean;
+        ordersCount: number;
+    };
     /**
      * Sets the layer's unique ID
      *
@@ -5839,6 +5898,25 @@ declare class User<TData = Record<string, any>> {
      * @internal
      */
     hasBridgeMessages(): boolean;
+    /**
+     * Returns a debug-friendly snapshot of this user (metadata only)
+     */
+    getDebugInfo(): {
+        id: string;
+        name: string;
+        bytesSentTotal: number;
+        bytesSentTick: number;
+        availableViewports: Array<{
+            displayId: number;
+            pixelWidth: number;
+            pixelHeight: number;
+        }>;
+        layers: ReturnType<Layer['getDebugInfo']>[];
+        displays: ReturnType<Display['getDebugInfo']>[];
+        displayComposite?: Record<number, {
+            layerIdsTopToBottom: number[];
+        }>;
+    };
 }
 
 /**
@@ -5862,6 +5940,7 @@ interface TickStats {
     totalCells: number;
     nonEmptyCells: number;
     cellsWithBackground: number;
+    displayCompositeLayerIds?: Map<number, number[]>;
     rasterizationTimeMs: number;
     encodingTimeMs: number;
 }
@@ -5889,6 +5968,11 @@ declare class CoreStats {
     get visibleLayers(): number;
     /** Layers visibles par display ID */
     get layersPerDisplay(): Map<number, number>;
+    /**
+     * Last known composition layer IDs per display (top-to-bottom).
+     * Available only for the latest tick when stats are enabled.
+     */
+    get displayCompositeLayerIds(): Map<number, number[]>;
     /** Total encoded UpdatePacket size (bytes) */
     get updatePacketSize(): number;
     /** Display header size (bytes) */
@@ -5929,6 +6013,10 @@ declare class CoreStats {
      * Starts collecting statistics for a new tick
      */
     startTick(tickNumber: number): void;
+    /**
+     * Records the exact layer IDs used for composition, in order.
+     */
+    recordDisplayComposite(displayId: number, layerIdsTopToBottom: number[]): void;
     /**
      * Records orders for a layer
      */
@@ -7185,7 +7273,7 @@ declare class Core {
      * }
      * ```
      */
-    getRenderState(userId: string): UserRenderState | null;
+    getRenderState(userId: string, layerFilter?: (layer: Layer) => boolean): UserRenderState | null;
     /**
      * Generates render state for all users
      *