@utsp/core 0.15.0-nightly.20251227200128.cdc09ed → 0.15.0

package/dist/benchmark.d.ts

@@ -480,6 +480,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)
@@ -1707,6 +1709,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;
+    };
 }
 
 /**
@@ -3721,6 +3735,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;
+        };
+    };
 }
 
 /**
@@ -6441,6 +6469,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[];
+        }>;
+    };
 }
 
 declare class CoreStats {
@@ -6467,6 +6514,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) */
@@ -6507,6 +6559,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
      */
@@ -7763,7 +7819,7 @@ declare class Core {
      * }
      * ```
      */
-    getRenderState(userId: string): UserRenderState | null;
+    getRenderState(userId: string, layerFilter?: (layer: Layer) => boolean): UserRenderState | null;
     /**
      * Generates render state for all users
      *
@@ -8698,6 +8754,8 @@ declare class Core {
  * 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
@@ -8713,6 +8771,7 @@ interface LayerOptions {
 }
 declare class Layer {
     private id;
+    private name?;
     private origin;
     private orders;
     private zOrder;
@@ -8807,6 +8866,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
      *
@@ -8906,6 +8993,7 @@ declare class Layer {
  * DisplayOrigin defines the visible area of a display in world space
  */
 interface DisplayOrigin {
+    id: number;
     x: number;
     y: number;
     width: number;
@@ -8964,6 +9052,12 @@ declare class DisplayRasterizer {
     private cellsBuffer;
     private opacityBuffer;
     private visibleLayersBuffer;
+    private visibleLayerIdsBuffer;
+    /**
+     * Last computed visible layer IDs (sorted in actual composition order).
+     * Updated on every rasterize() call.
+     */
+    getLastVisibleLayerIds(): ReadonlyArray<number>;
     constructor(engine: Core);
     /**
      * Rebuilds the RGB cache from the engine palette