spice-html5-react 0.1.0

package/dist/protocol/bitmap.d.ts

@@ -0,0 +1,20 @@
+import { SpiceBitmap } from './spicetype.js';
+
+/**
+ * Convert a SPICE protocol bitmap to a web-compatible ImageData.
+ *
+ * SPICE bitmaps use BGRx (32BIT) or BGRA (RGBA) pixel order, while
+ * the HTML Canvas API expects RGBA.  This function swaps the red and
+ * blue channels and handles the top-down vs bottom-up row ordering.
+ *
+ * Only 32-bit (BGRx) and RGBA (BGRA) formats are supported.  Other
+ * formats return `undefined`.
+ *
+ * @param context  A 2D canvas rendering context (used only to call
+ *                 createImageData for the correct backing store).
+ * @param spiceBitmap  The deserialized SpiceBitmap from the protocol.
+ * @returns An ImageData with RGBA pixels, or undefined if the bitmap
+ *          format is not supported.
+ */
+export declare function convertSpiceBitmapToWeb(context: CanvasRenderingContext2D, spiceBitmap: SpiceBitmap): ImageData | undefined;
+//# sourceMappingURL=bitmap.d.ts.map

package/dist/protocol/bitmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bitmap.d.ts","sourceRoot":"","sources":["../../src/protocol/bitmap.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,wBAAwB,EACjC,WAAW,EAAE,WAAW,GACzB,SAAS,GAAG,SAAS,CAuDvB"}

package/dist/protocol/cursor.d.ts

@@ -0,0 +1,16 @@
+import { SpiceConn, SpiceConnOptions } from './spiceconn';
+import { SpiceMiniData } from './spicemsg';
+import { CursorOwner } from './simulatecursor';
+
+export declare class SpiceCursorConn extends SpiceConn implements CursorOwner {
+    /** Simulated cursor <img> element (fallback for unsupported browsers). */
+    simulatedCursor: CursorOwner['simulatedCursor'];
+    /** Event handler stored for cleanup */
+    simulatedCursorHandler: CursorOwner['simulatedCursorHandler'];
+    constructor(options: SpiceConnOptions);
+    protected processChannelMessage(msg: SpiceMiniData): boolean;
+    private setCursor;
+    private getScreen;
+    cleanup(): void;
+}
+//# sourceMappingURL=cursor.d.ts.map

package/dist/protocol/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/protocol/cursor.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAS/D,OAAO,EACH,aAAa,EAGhB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAEH,KAAK,WAAW,EAEnB,MAAM,kBAAkB,CAAC;AAwB1B,qBAAa,eAAgB,SAAQ,SAAU,YAAW,WAAW;IAEjE,0EAA0E;IAC1E,eAAe,EAAE,WAAW,CAAC,iBAAiB,CAAC,CAAa;IAE5D,uCAAuC;IACvC,sBAAsB,EAAE,WAAW,CAAC,wBAAwB,CAAC,CAAa;gBAE9D,OAAO,EAAE,gBAAgB;cASlB,qBAAqB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO;IAyHrE,OAAO,CAAC,SAAS;IAsCjB,OAAO,CAAC,SAAS;IAmBR,OAAO,IAAI,IAAI;CAK3B"}

package/dist/protocol/display.d.ts

@@ -0,0 +1,311 @@
+import { SpiceMiniData, SpiceMsgcDisplayStreamReport } from './spicemsg';
+import { SpiceConn, SpiceConnOptions } from './spiceconn';
+
+/**
+ * Internal canvas wrapper that holds a reference to the 2D context.
+ * The original display.js attached `context` directly to the canvas
+ * element; this interface makes that explicit in TypeScript.
+ */
+interface SpiceCanvas {
+    canvas: HTMLCanvasElement;
+    context: CanvasRenderingContext2D;
+}
+/**
+ * Runtime surface state maintained by the display channel.
+ * One entry exists per active surface (primary or off-screen).
+ */
+export interface SurfaceEntry {
+    /** Surface ID from the SPICE protocol. */
+    surfaceId: number;
+    /** Width in pixels. */
+    width: number;
+    /** Height in pixels. */
+    height: number;
+    /** Pixel format (SpiceSurfaceFmt.*). */
+    format: number;
+    /** Surface flags (e.g. SPICE_SURFACE_FLAGS_PRIMARY). */
+    flags: number;
+    /** Canvas and its 2D context. */
+    canvas: SpiceCanvas;
+    /** Counter of draw operations (for debug canvas naming). */
+    drawCount: number;
+}
+/**
+ * Image cache keyed by the 64-bit image descriptor ID (as bigint).
+ * Values are ImageData objects that can be put directly onto a canvas
+ * context.
+ */
+export type ImageCache = Record<string, ImageData>;
+/**
+ * Stream entry type for video streams (VP8 and MJPEG).
+ * Tracks the video element, MediaSource, SourceBuffer, frame queue,
+ * timing state, and stream report for one active stream.
+ */
+export interface StreamEntry {
+    /** Stream ID from the SPICE protocol. */
+    id: number;
+    /** Surface associated with this stream. */
+    surfaceId: number;
+    /** Video codec type (SpiceVideoCodecType.*). */
+    codecType: number;
+    /** Stream dimensions. */
+    streamWidth: number;
+    streamHeight: number;
+    /** Destination rectangle. */
+    dest: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    /** Clip region. */
+    clip: {
+        type: number;
+    } | undefined;
+    /** MJPEG frames currently loading. */
+    framesLoading: number;
+    /** VP8 video element. */
+    video: HTMLVideoElement | undefined;
+    /** VP8 MediaSource. */
+    media: MediaSource | undefined;
+    /** VP8 SourceBuffer. */
+    sourceBuffer: SourceBuffer | undefined;
+    /** VP8 frame queue. */
+    queue: Array<{
+        msgMmtime: number;
+        mb: ArrayBuffer;
+    }>;
+    /** VP8 start time. */
+    startTime: number;
+    /** VP8 cluster time. */
+    clusterTime: number;
+    /** VP8 append state. */
+    appendOkay: boolean;
+    /** VP8/MJPEG current frame. */
+    currentFrame: {
+        msgMmtime: number;
+        mb?: ArrayBuffer;
+    } | undefined;
+    /** Stream report (if active). */
+    report: SpiceMsgcDisplayStreamReport | undefined;
+    /** Max window size for report. */
+    maxWindowSize: number;
+    /** Timeout in ms for report. */
+    timeoutMs: number;
+}
+/**
+ * Callback fired when the primary surface is created or destroyed.
+ */
+export interface DisplaySurfaceCallback {
+    (surfaceId: number, width: number, height: number, created: boolean): void;
+}
+/**
+ * SPICE display channel.  Manages surface creation/destruction,
+ * image caching, draw operations, and video streaming.
+ *
+ * US-017 scope: surface lifecycle, image cache, event hooking.
+ * US-018 scope: draw COPY/FILL/COPY_BITS, image decompression dispatch.
+ * US-019 scope: VP8 and MJPEG video streaming via MediaSource API.
+ */
+export declare class SpiceDisplayConn extends SpiceConn {
+    surfaces: Record<number, SurfaceEntry>;
+    primarySurface: number | undefined;
+    cache: ImageCache;
+    streams: Record<number, StreamEntry>;
+    private focusListener;
+    onSurface: DisplaySurfaceCallback | undefined;
+    constructor(options: SpiceConnOptions);
+    protected processChannelMessage(msg: SpiceMiniData): boolean;
+    /**
+     * Handle SPICE_MSG_DISPLAY_DRAW_COPY.
+     * Dispatches image decompression based on the source bitmap type:
+     * QUIC, LZ_RGB, BITMAP, JPEG, JPEG_ALPHA, FROM_CACHE, SURFACE.
+     */
+    private handleDrawCopy;
+    /**
+     * Handle SPICE_MSG_DISPLAY_DRAW_FILL.
+     * Currently only handles solid brush fills.
+     */
+    private handleDrawFill;
+    /**
+     * Handle SPICE_MSG_DISPLAY_COPY_BITS.
+     * Copies a region within the same surface.
+     */
+    private handleCopyBits;
+    /**
+     * Common helper for all draw copy operations.
+     * Handles alpha blending, image caching (CACHE_ME flag), and debug dumps.
+     *
+     * @param o - Aggregated draw parameters
+     * @returns true on success
+     */
+    private drawCopyHelper;
+    /**
+     * Handle JPEG and JPEG_ALPHA draw copy operations.
+     * Because JPEG decoding is asynchronous (via Image element onload),
+     * this method creates an Image element, sets up the onload handler,
+     * and returns immediately.
+     *
+     * @param base - The display base (surface, box, clip)
+     * @param descriptor - The image descriptor (for caching)
+     * @param jpegData - The raw JPEG data as ArrayBuffer
+     * @param alphaImg - Optional alpha channel ImageData (for JPEG_ALPHA)
+     * @param surfaceId - The target surface ID
+     */
+    private handleDrawJpeg;
+    /**
+     * Log detailed information about a draw command for debugging.
+     * Faithfully reproduced from the original display.js log_draw method.
+     *
+     * @param prefix - Label prefix (e.g. "DrawCopy", "DrawFill")
+     * @param draw - The draw message (DrawCopy, DrawFill, CopyBits, etc.)
+     */
+    private logDraw;
+    /**
+     * Handle SPICE_MSG_DISPLAY_STREAM_CREATE.
+     * Creates a new stream entry.  For VP8, also creates a <video> element
+     * and a MediaSource with a SourceBuffer for WebM/VP8 frames.  For
+     * MJPEG, just initialises the frame counter.
+     */
+    private handleStreamCreate;
+    /**
+     * Handle SPICE_MSG_DISPLAY_STREAM_DATA and STREAM_DATA_SIZED.
+     * Dispatches to VP8 or MJPEG handler depending on stream codec.
+     */
+    private handleStreamData;
+    /**
+     * Handle SPICE_MSG_DISPLAY_STREAM_ACTIVATE_REPORT.
+     * Sets up a stream report object for quality feedback.
+     */
+    private handleStreamActivateReport;
+    /**
+     * Handle SPICE_MSG_DISPLAY_STREAM_CLIP.
+     * Updates the clip region for a given stream.
+     */
+    private handleStreamClip;
+    /**
+     * Handle SPICE_MSG_DISPLAY_STREAM_DESTROY.
+     * Tears down the video element and MediaSource for VP8 streams,
+     * then removes the stream entry.
+     */
+    private handleStreamDestroy;
+    /**
+     * Called when the MediaSource for a VP8 stream enters 'sourceopen'.
+     * Adds a SourceBuffer for VP8/WebM, sends the WebM header + tracks,
+     * and wires up buffer events.
+     */
+    private handleVideoSourceOpen;
+    /**
+     * Append an ArrayBuffer to the VP8 stream's SourceBuffer.
+     * Sets appendOkay to false until the updateend event fires.
+     */
+    private appendVideoBuffer;
+    /**
+     * Called when the SourceBuffer finishes appending.
+     * Sends stream reports, drains the queue, advances the video
+     * currentTime if it falls behind, and attempts to play if paused.
+     */
+    private handleAppendVideoBufferDone;
+    /**
+     * Either immediately append to SourceBuffer if ready, or queue
+     * the frame for later append when the current operation completes.
+     */
+    private pushOrQueue;
+    /**
+     * Create a WebM SimpleBlock element for a VP8 frame and push/queue it.
+     */
+    private videoSimpleBlock;
+    /**
+     * Start a new WebM Cluster (keyframe), then immediately emit a
+     * SimpleBlock with the same frame data.
+     */
+    private newVideoCluster;
+    /**
+     * Process a VP8 video stream data message.
+     * Starts a new cluster on the first frame or when the cluster
+     * time exceeds MAX_CLUSTER_TIME, otherwise emits a simple block.
+     */
+    private processVideoStreamData;
+    /**
+     * Process an MJPEG stream data frame.
+     * Rate control: if a frame is late and another is currently loading,
+     * the new frame is dropped to help the browser keep up.
+     * Otherwise, the JPEG data is turned into a data URI, a SpiceMsgDisplayBase
+     * is constructed from the stream state, and the existing handleDrawJpeg
+     * path is reused for rendering.
+     */
+    private processMjpegStreamData;
+    /**
+     * Accumulate stream quality data and send a report to the server
+     * when the window is full or the timeout has expired.
+     */
+    private processStreamDataReport;
+    /**
+     * Attach debug event listeners to a VP8 stream's video element.
+     * The level of verbosity is controlled by STREAM_DEBUG.
+     */
+    private listenForVideoEvents;
+    private handleSurfaceCreate;
+    private handleSurfaceDestroy;
+    /**
+     * Remove a surface from the internal registry and the DOM.
+     *
+     * @param surfaceId - The surface ID to remove
+     */
+    deleteSurface(surfaceId: number): void;
+    /**
+     * Destroy all surfaces.  Called during channel teardown.
+     */
+    destroySurfaces(): void;
+    private handleInvalList;
+    /**
+     * Store an image in the cache, keyed by its descriptor ID.
+     *
+     * @param id - The image descriptor ID (bigint)
+     * @param imageData - The ImageData to cache
+     */
+    cacheImage(id: bigint, imageData: ImageData): void;
+    /**
+     * Retrieve a cached image by its descriptor ID.
+     *
+     * @param id - The image descriptor ID (bigint)
+     * @returns The cached ImageData, or undefined if not found
+     */
+    getCachedImage(id: bigint): ImageData | undefined;
+    /**
+     * Check whether an image is in the cache.
+     *
+     * @param id - The image descriptor ID (bigint)
+     * @returns true if the image is cached
+     */
+    hasImageInCache(id: bigint): boolean;
+    /**
+     * Get a surface entry by its ID.
+     *
+     * @param surfaceId - The surface ID
+     * @returns The surface entry, or undefined if not found
+     */
+    getSurface(surfaceId: number): SurfaceEntry | undefined;
+    /**
+     * Get the primary surface entry.
+     *
+     * @returns The primary surface entry, or undefined
+     */
+    getPrimarySurface(): SurfaceEntry | undefined;
+    /**
+     * Hook input and focus events onto the primary surface canvas.
+     * This enables keyboard, mouse, and clipboard interaction.
+     *
+     * Note: Actual input event handler registration will be done by
+     * the inputs channel or component layer.  This method sets up the
+     * canvas for focus/blur and clipboard grab.
+     */
+    hookEvents(): void;
+    /**
+     * Unhook events from the primary surface canvas.
+     */
+    unhookEvents(): void;
+    cleanup(): void;
+}
+export {};
+//# sourceMappingURL=display.d.ts.map

package/dist/protocol/display.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"display.d.ts","sourceRoot":"","sources":["../../src/protocol/display.ts"],"names":[],"mappings":"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"}