rapid-render 0.1.21 → 1.0.0

package/dist/render.d.ts

@@ -1,255 +1,392 @@
-import { ICircleRenderOptions, IGraphicRenderOptions, ILayerRenderOptions, IRapidOptions, IRectRenderOptions, IRenderLineOptions, ISpriteRenderOptions, ShaderType as ShaderType, MaskType, WebGLContext, BlendMode, ILightRenderOptions, IParticleOptions, ICameraOptions, IPolygonGraphicRenderOptions } from "./interface";
-import { LightManager } from "./light";
-import { Color, MatrixStack, Vec2 } from "./math";
-import RenderRegion from "./regions/region";
-import { FrameBufferObject, Texture, TextureCache } from "./texture";
-import { TileMapRender, TileSet } from "./tilemap";
-import GLShader from "./webgl/glshader";
-import { ParticleEmitter } from "./particle";
+import { WebGLContext } from './webgl/utils';
+import { default as GLShader, CustomGlShader } from './webgl/glshader';
+import { Region } from './region/region';
+import { SpriteRegion } from './region/spriteRegion';
+import { MatrixStack, MatrixStore, ITransformOptions } from './matrix-engine';
+import { GraphicRegion } from './region/graphicRegion';
+import { RenderTexture, Texture, TextureManager } from './texture';
+import { Color } from './color';
+import { ICircleOptions, IGraphicOptions, ILineOptions, IMaskImageOptions, IRectOptions, ISpriteOptions } from './draw';
+import { Vec2 } from './math';
+import { AtlasSprtieRegion } from './region/atlasSpriteRegion';
 /**
- * The `Rapid` class provides a WebGL-based rendering engine.
+ * Options for initializing the Rapid application.
  */
-declare class Rapid {
-    gl: WebGLContext;
+export interface IAppOptions {
+    /** The HTML canvas element to render onto. */
     canvas: HTMLCanvasElement;
-    projection: Float32Array;
-    projectionDirty: boolean;
-    matrixStack: MatrixStack;
-    textures: TextureCache;
-    tileMap: TileMapRender;
-    light: LightManager;
-    width: number;
-    height: number;
-    backgroundColor: Color;
-    devicePixelRatio: number;
-    private physicsWidth;
-    private physicsHeight;
-    private logicWidth;
-    private logicHeight;
-    private scaleEnable;
-    private scaleRadio;
-    readonly maxTextureUnits: number;
-    private readonly defaultColor;
-    private currentRegion?;
-    private currentRegionName?;
-    private regions;
-    private currentMaskType;
-    private currentTransform;
-    private currentFBO;
-    private lastTime;
-    /**
-     * Constructs a new `Rapid` instance with the given options.
-     * @param options - Options for initializing the `Rapid` instance.
-     */
-    constructor(options: IRapidOptions);
-    /**
-     * @param displayWdith css px size
-     * @param displayHeight css px size
-     */
-    updateDisplaySize(displayWdith: number, displayHeight: number): void;
-    private resizeSize;
-    private updateProjection;
-    /**
-     * Initializes WebGL context settings.
-     * @param gl - The WebGL context.
-     */
-    private initWebgl;
-    /**
-     * @ignore
-     */
-    clearTextureUnit(): void;
-    /**
-     * Registers built-in regions such as sprite and graphic regions.
-     */
-    private registerBuildInRegion;
-    /**
-     * Registers a custom render region with a specified name.
-     * @param name - The name of the region.
-     * @param regionClass - The class of the region to register.
-     */
-    registerRegion(name: string, regionClass: typeof RenderRegion): void;
-    private quitCurrentRegion;
+    /** The logical width of the application (CSS pixels). */
+    logicWidth?: number;
+    /** The logical height of the application (CSS pixels). */
+    logicHeight?: number;
+    /** The physical width of the application (actual pixels). */
+    physicsWidth?: number;
+    /** The physical height of the application (actual pixels). */
+    physicsHeight?: number;
+    /** The default clear color for the application background. */
+    backgroundColor?: Color;
+    /** Whether to enable MSAA antialiasing on the WebGL canvas. Default: false. */
+    antialias?: boolean;
+    textureFilter?: TextureFilterMode;
+    /** Whether textures are uploaded with premultiplied alpha. Default: true. */
+    premultipliedAlpha?: boolean;
+    roundPixels?: boolean;
+    scaleMode?: CanvasScaleMode;
+}
+/**
+ * The type of mask to apply.
+ */
+export declare enum MaskType {
     /**
-     * Sets the current render region by name and optionally a custom shader.
-     * @param regionName - The name of the region to set as current.
-     * @param customShader - An optional custom shader to use with the region.
-     * @param hasUnifrom - have costum unifrom
+     * Draw inside the mask.
      */
-    setRegion(regionName: string, customShader?: GLShader): void;
+    EQUAL = 0,
     /**
-     * Saves the current matrix state to the stack.
+     * Draw outside the mask.
      */
-    save(): void;
+    NOT_EQUAL = 1
+}
+/**
+ * Supported blend modes for rendering.
+ */
+export declare enum BlendMode {
+    /** Normal alpha blending. */
+    NORMAL = 0,
+    /** Additive blending (useful for glow effects). */
+    ADD = 1,
+    /** Multiply blending (useful for shadows and darkening). */
+    MULTIPLY = 2,
+    /** Screen blending (produces a softer additive effect). */
+    SCREEN = 3,
+    /** Erase blending (removes alpha based on source). */
+    ERASE = 4
+}
+export declare enum TextureFilterMode {
+    LINEAR = 0,
+    NEAREST = 1
+}
+export declare enum CanvasScaleMode {
     /**
-     * Restores the matrix state from the stack.
+     * Scales the canvas by increasing the WebGL backbuffer size.
+     * The logical game size stays the same, but rendering happens at the final display resolution,
+     * so rotated sprites, lines, and geometry get more rasterized pixels and look smoother.
      */
-    restore(): void;
+    CanvasItem = 0,
     /**
-     * Executes a callback function within a saved and restored matrix state scope.
-     * @param cb - The callback function to execute within the saved and restored matrix state scope.
+     * Scales only the final canvas element on the page.
+     * The WebGL backbuffer stays at the logical game size, then the browser stretches that bitmap
+     * to the CSS display size. This preserves low-resolution/pixel-art rendering and does not add
+     * more fragments while scaling up.
      */
-    withTransform(cb: () => void): void;
-    /**
-     * Starts the rendering process, resetting the matrix stack and clearing the current region.
-     * @param clear - Whether to clear the matrix stack. Defaults to true.
+    Viewport = 1
+}
+/**
+ * The main application class for the Rapid rendering engine.
+ * Manages the WebGL context, rendering regions, state, and matrices.
+ */
+export declare class Rapid {
+    /** The active WebGL context. */
+    gl: WebGLContext;
+    /** The target HTMLCanvasElement. */
+    canvas: HTMLCanvasElement;
+    /** The current orthographic projection matrix (16 elements). */
+    projection: Float32Array;
+    /** Indicates if the projection matrix has changed and needs to be uploaded to shaders. */
+    projectionDirty: boolean;
+    /** The current device pixel ratio. */
+    dpr: number;
+    /** Background clear color [r, g, b, a], values range from 0 to 255. */
+    backgroundColor: Color;
+    /** Logical width in CSS pixels, used for coordinate system and projection matrix. */
+    logicWidth: number;
+    /** Logical height in CSS pixels, used for coordinate system and projection matrix. */
+    logicHeight: number;
+    /** Physical width (canvas actual pixels = logical width * dpr). */
+    physicsWidth: number;
+    /** Physical height (canvas actual pixels = logical height * dpr). */
+    physicsHeight: number;
+    /** The currently active rendering region. */
+    currentRegion: Region | null;
+    /** Maximum number of texture units supported by the device. */
+    maxTextureUnits: number;
+    /** Matrix stack for hierarchical transformations. */
+    matrixStack: MatrixStack;
+    /** Direct access to the underlying matrix store. */
+    matrix: MatrixStore;
+    /** Region dedicated to fast sprite rendering. */
+    spriteRegion: SpriteRegion;
+    /** Region dedicated to arbitrary geometry and shapes rendering. */
+    graphicRegion: GraphicRegion;
+    atlasSpriteRegion: AtlasSprtieRegion;
+    /** Counts the number of WebGL draw calls made in the current frame. */
+    drawcallCount: number;
+    /** Indicates whether we are currently writing to the stencil buffer to create a mask. */
+    inCreateMask: boolean;
+    /** Manager for creating and organizing textures. */
+    texture: TextureManager;
+    /** Whether textures use premultiplied alpha. Set once at construction. */
+    premultipliedAlpha: boolean;
+    /** Default texture filtering preference and requested canvas MSAA setting. */
+    antialias: boolean;
+    roundPixels: boolean;
+    /** Default filtering mode used when sampling textures. */
+    textureFilter: TextureFilterMode;
+    scaleMode?: CanvasScaleMode;
+    /** Internal ping-pong RenderTextures for multi-filter chains. */
+    private _filterRT;
+    private _filterInput;
+    get height(): number;
+    get width(): number;
+    /**
+     * Creates a new Rapid application instance.
+     * @param options Initialization options including the target canvas.
+     */
+    constructor(options: IAppOptions);
+    setTextureFilter(filter: TextureFilterMode): void;
+    setAntialias(antialias: boolean): void;
+    private getColorUint32;
+    /**
+     * Enters a specific rendering region, flushing the previous one if necessary.
+     * @param region The rendering region to enter.
+     * @param customShader An optional custom shader to use for this region.
+     */
+    enterRegion(region: Region, customShader?: GLShader | CustomGlShader): void;
+    drawSprite(options: ISpriteOptions): void;
+    drawLine(options: ILineOptions): void;
+    drawGraphic(options: IGraphicOptions): void;
+    drawRect(options: IRectOptions): void;
+    drawCircle(options: ICircleOptions): void;
+    /**
+     * Starts rendering arbitrary graphics geometries.
+     * @param drawMode The WebGL drawing mode (e.g., gl.TRIANGLES, gl.TRIANGLE_FAN).
+     * @param texture  An optional texture applied to the graphic vertices.
+     * @param customShader An optional custom shader overriding the region's default shader.
+     */
+    startGraphic(drawMode?: number, texture?: Texture, customShader?: GLShader | CustomGlShader, customMatrix?: number): void;
+    /**
+     * Starts rendering graphics explicitly for use as a mask, overriding the shader.
+     * @param drawMode The WebGL drawing mode (e.g., gl.TRIANGLES).
+     * @param texture  An optional texture whose alpha channel may dictate masking rules.
+     */
+    startMaskGraphic(drawMode?: number, texture?: Texture, customMatrix?: number): void;
+    /**
+     * Utility method: Draws an image directly as a mask using a generic rectangle geometry.
+     * @param texture The texture to be used as a mask.
+     */
+    drawMaskImage(options: IMaskImageOptions): void;
+    /**
+     * Pushes vertices for a rectangle geometry. Should be enclosed by startGraphic and endGraphic.
+     * @param w The width of the rectangle.
+     * @param h The height of the rectangle.
+     * @param color An optional tint color.
+     */
+    addRectVertex(w: number, h: number, color?: Color): void;
+    /**
+     * Pushes vertices for a circle geometry using TRIANGLES or similar primitives.
+     * @param r The radius of the circle.
+     * @param color An optional tint color.
+     * @param segments The number of segments (polygons) used to approximate the circle.
+     */
+    addCircleVertex(r: number, color?: Color, segments?: number): void;
+    /**
+     * Adds an individual vertex to the current graphics batch.
+     * @param x The relative X coordinate of the vertex.
+     * @param y The relative Y coordinate of the vertex.
+     * @param u The U texture coordinate (0 to 1).
+     * @param v The V texture coordinate (0 to 1).
+     * @param color The vertex color as a 32-bit unsigned integer.
+     */
+    addGraphicVertex(x: number, y: number, u?: number, v?: number, color?: number): void;
+    /**
+     * Ends the current graphics geometry definition, readying it for rendering.
+     */
+    endGraphic(): void;
+    /**
+     * Resizes the canvas, updates internal viewport values, and recreates projection boundaries.
+     * @param logicWidth The new logical display width.
+     * @param logicHeight The new logical display height.
+     * @param cssWidth Optional CSS display width.
+     * @param cssHeight Optional CSS display height.
+     */
+    resize(logicWidth: number, logicHeight: number, cssWidth?: number, cssHeight?: number): void;
+    /**
+     * Updates the projection matrix using an orthographic mapping.
+     * Automatically sets local flag projectionDirty.
      */
-    startRender(clear?: boolean): number;
+    private updateProjection;
     /**
-     * Ends the rendering process by rendering the current region.
+     * Clears the active framebuffer applying the default background color.
      */
-    endRender(): void;
+    clear(): void;
     /**
-     * Render
-     * @param cb - The function to render.
+     * Populates an orthographic projection matrix in place.
+     * Avoids continuous Float32Array allocations for performance reasons.
      */
-    render(cb: (dt: number) => void): void;
+    private updateOrthMatrix;
     /**
-     * Render a tile map layer.
-     * @param data - The map data to render.
-     * @param options - The options for rendering the tile map layer.
+     * Flushes currently buffered rendering operations across all active regions.
      */
-    renderTileMapLayer(data: (number | string)[][], options: ILayerRenderOptions | TileSet): void;
-    applyCameraTransform(options: ICameraOptions): void;
+    flush(): void;
     /**
-     * Renders a sprite with the specified options.
+     * Applies a chain of shaders to a texture sequentially using ping-pong RenderTextures.
+     * Each shader receives the output of the previous one as its input.
+     * Two internal RenderTextures are reused across calls (resized as needed).
      *
-     * @param options - The rendering options for the sprite, including texture, position, color, and shader.
-     */
-    renderSprite(options: ISpriteRenderOptions): void;
-    renderParticles(particleEmitter: ParticleEmitter): void;
-    /**
-     * Renders a texture directly without additional options.
-     * This is a convenience method that calls renderSprite with just the texture.
+     * @param source   The input texture to start the filter chain from.
+     * @param shaders  An ordered array of CustomGlShader to apply in sequence.
+     * @returns The RenderTexture containing the final filtered result.
+     *          Draw it with `rapid.drawSprite({ texture: result })` to display it on screen.
      *
-     * @param texture - The texture to render at the current transformation position.
+     * @example
+     * const result = rapid.applyFilters(tex, [blurShader, outlineShader]);
+     * rapid.drawSprite({ texture: result });
      */
-    renderTexture(texture: Texture): void;
+    applyFilters(source: Texture, shaders: CustomGlShader[]): RenderTexture;
+    enterRenderTexture(rt: RenderTexture): void;
     /**
-     * Renders a line with the specified options.
-     *
-     * @param options - The options for rendering the line, including points, color, width, and join/cap types.
+     * Clears a RenderTexture to a solid color.
+     * Must be called while the RT is the active render target (i.e. inside enterRenderTexture/leaveRenderTexture).
+     * Can also be called standalone — it will bind the RT, clear it, but NOT restore the main framebuffer.
+     * @param rt    The render texture to clear.
+     * @param color Clear color. Defaults to transparent black (0, 0, 0, 0).
      */
-    renderLine(options: IRenderLineOptions): void;
+    clearRenderTexture(color?: Color): void;
     /**
-     * Renders graphics based on the provided options.
-     *
-     * @param options - The options for rendering the graphic, including points, color, texture, and draw type.
+     * Completes rendering to an offscreen render texture and reverts rendering back to the main canvas.
      */
-    renderGraphic(options: IPolygonGraphicRenderOptions): void;
+    leaveRenderTexture(): void;
     /**
-     * Starts the graphic drawing process.
+     * Convenience wrapper: enters a RenderTexture, optionally clears it, runs a callback, then leaves.
+     * @param rt    The RenderTexture to render into.
+     * @param cb    The callback containing draw calls to execute inside the RT.
+     * @param color Clear color before rendering. Pass `null` to skip clearing. Defaults to transparent black.
      *
-     * @param options - The options for the graphic drawing, including shader, texture, and draw type.
-     */
-    startGraphicDraw(options: IGraphicRenderOptions): void;
-    /**
-     * Adds a vertex to the current graphic being drawn.
+     * @example
+     * rapid.drawToRenderTexture(myRT, () => {
+     *     rapid.drawSprite({ texture: mySprite });
+     * });
+     */
+    drawToRenderTexture(rt: RenderTexture, cb: () => void, color?: Color | null): void;
+    /**
+     * Convenience wrapper: writes a mask using the stencil buffer, then renders within it, then exits the mask.
+     * @param maskCb   Callback that defines the mask geometry (drawn to stencil, not visible).
+     * @param drawCb   Callback containing the actual draw calls masked by the stencil.
+     * @param type     Mask type: EQUAL (draw inside) or NOT_EQUAL (draw outside). Defaults to EQUAL.
+     * @param ref      Stencil reference value. Defaults to 1.
      *
-     * @param offsetX - The X coordinate of the vertex.
-     * @param offsetY - The Y coordinate of the vertex.
-     * @param uv - The texture UV coordinates for the vertex.
-     * @param color - The color of the vertex. Defaults to the renderer's default color.
-     */
-    addGraphicVertex(offsetX: number, offsetY: number, uv: Vec2, color?: Color): void;
-    /**
-     * Completes the graphic drawing process and renders the result.
-     */
-    endGraphicDraw(): void;
-    private startDraw;
-    private afterDraw;
-    /**
-     * Renders a rectangle with the specified options.
+     * @example
+     * rapid.withMask(
+     *     () => rapid.drawRect({ width: 200, height: 200 }),
+     *     () => rapid.drawSprite({ texture: myTexture }),
+     * );
+     */
+    withMask(maskCb: () => void, drawCb: () => void, type?: MaskType, ref?: number): void;
+    /**
+     * Convenience wrapper: saves the matrix stack, applies an optional transform, runs a callback, then restores.
+     * When `transform` is provided, delegates to `matrixStack.applyTransform()` which handles
+     * position, rotation, scale, offset, and origin automatically.
+     * @param cb        The callback to execute within the saved transform context.
+     * @param transform Optional transform options to apply before running the callback.
+     * @param width     The logical width used to resolve `origin` anchoring. Defaults to 0.
+     * @param height    The logical height used to resolve `origin` anchoring. Defaults to 0.
      *
-     * @param options - The options for rendering the rectangle, including width, height, position, and color.
-     */
-    renderRect(options: IRectRenderOptions): void;
-    /**
-     * Renders a circle with the specified options.
+     * @example
+     * // Simple save/restore
+     * rapid.withTransform(() => {
+     *     rapid.matrixStack.translate(100, 100);
+     *     rapid.drawSprite({ texture: myTexture });
+     * });
      *
-     * @param options - The options for rendering the circle, including radius, position, color, and segment count.
-     */
-    renderCircle(options: ICircleRenderOptions): void;
-    /**
-     * Clears the canvas with the background color.
-     * @param bgColor - The background color to clear the canvas with.
-     */
-    clear(bgColor?: Color): void;
-    /**
-     * Creates an orthogonal projection matrix.
-     * @param left - The left bound of the projection.
-     * @param right - The right bound of the projection.
-     * @param bottom - The bottom bound of the projection.
-     * @param top - The top bound of the projection.
-     * @returns The orthogonal projection matrix as a `Float32Array`.
+     * @example
+     * // With a transform applied
+     * rapid.withTransform(() => {
+     *     rapid.drawSprite({ texture: myTexture });
+     * }, { x: 100, y: 50, rotation: Math.PI / 4, origin: 0.5 }, myTexture.width, myTexture.height);
+     */
+    withTransform(cb: () => void, transform?: ITransformOptions, width?: number, height?: number): void;
+    /**
+     * Convenience wrapper: enables scissor clipping for a region, runs a callback, then disables it.
+     * @param x      Left edge in logical pixels.
+     * @param y      Top edge in logical pixels.
+     * @param width  Width in logical pixels.
+     * @param height Height in logical pixels.
+     * @param cb     The callback to execute within the scissor region.
+     *
+     * @example
+     * rapid.withScissor(50, 50, 300, 200, () => {
+     *     rapid.drawSprite({ texture: myTexture });
+     * });
      */
-    private createOrthMatrix;
+    withScissor(x: number, y: number, width: number, height: number, cb: () => void): void;
     /**
-     * Draw a mask. Automatically calls startDrawMask.
-     * @param type - The type of mask to draw.
-     * @param cb - The callback function to execute.
+     * Convenience wrapper: sets a blend mode, runs a callback, then restores NORMAL blend mode.
+     * @param mode The BlendMode to apply for the duration of the callback.
+     * @param cb   The callback to execute under the given blend mode.
+     *
+     * @example
+     * rapid.withBlendMode(BlendMode.ADD, () => {
+     *     rapid.drawSprite({ texture: glowTexture });
+     * });
      */
-    drawMask(type: MaskType | undefined, cb: () => void): void;
+    withBlendMode(mode: BlendMode, cb: () => void): void;
     /**
-     * Start drawing a mask using the stencil buffer.
-     * This method configures the WebGL context to begin defining a mask area.
+     * Starts drawing into the stencil buffer to construct a rendering mask.
+     * @param ref The stencil reference value.
+     * @param mask The stencil bitmask.
      */
-    startDrawMask(type?: MaskType): void;
+    startDrawMask(ref?: number, mask?: number): void;
     /**
-     * End the mask drawing process.
-     * This method configures the WebGL context to use the defined mask for subsequent rendering.
+     * Finishes the mask drawing phase and restores color buffer writing.
      */
     endDrawMask(): void;
     /**
-     * Set the mask type for rendering
-     * @param type - The mask type to apply
-     * @param start - Whether this is the start of mask drawing
+     * Clears bounds created into the stencil mask.
+     * @param mask The bitmask specifying which stencil layer to clear.
      */
-    private setMaskType;
+    clearMask(mask?: number): void;
     /**
-     * Clear the current mask by clearing the stencil buffer.
-     * This effectively removes any previously defined mask.
+     * Enters a constrained rendering phase masked by the existing stencil buffer values.
+     * @param type Equality check type. Use "equal" to draw inside the mask, or "notEqual" to draw outside.
+     * @param ref The reference value to test against.
+     * @param mask The bitmask specifying which stencil bits to consider.
      */
-    clearMask(): void;
+    enterMask(type: MaskType, ref?: number, mask?: number): void;
     /**
-     * Creates a custom shader.
-     * @param vs - Vertex shader code.
-     * @param fs - Fragment shader code.
-     * @param type - Shader type.
-     * @returns The created shader object.
+     * Exits the masked rendering phase, restoring default full-screen stencil values tests.
      */
-    createCostumShader(vs: string, fs: string, type: ShaderType, textureUnitNum?: number): GLShader;
+    exitMask(): void;
     /**
-     * Starts rendering to a Frame Buffer Object (FBO)
-     * Sets up the FBO for rendering by binding it, adjusting viewport size and projection
-     * @param fbo - The Frame Buffer Object to render to
-     */
-    startFBO(fbo: FrameBufferObject): void;
-    /**
-     * Ends rendering to a Frame Buffer Object
-     * Restores the default framebuffer and original viewport settings
-     * @param fbo - The Frame Buffer Object to unbind
-     */
-    endFBO(): void;
-    /**
-     * Convenience method to render to a Frame Buffer Object
-     * Handles starting and ending the FBO rendering automatically
-     * @param fbo - The Frame Buffer Object to render to
-     * @param cb - Callback function containing render commands to execute on the FBO
-     */
-    drawToFBO(fbo: FrameBufferObject, cb: () => void): void;
-    /**
-     * Set the blend mode for rendering
-     * @param mode - The blend mode to apply
+     * Configures the global WebGL blending behavior.
+     * @param mode The targeted BlendMode to switch onto.
      */
     setBlendMode(mode: BlendMode): void;
     /**
-     * Render light shadow
-     * @param occlusion - The occlusion polygon
-     * @param lightSource - The light source position
-     */
-    drawLightShadowMask(options: ILightRenderOptions): void;
-    createParticleEmitter(options: IParticleOptions): ParticleEmitter;
-    cssToGameCoords(x: number | Vec2, y?: number): Vec2;
-    gameToCssCoords(x: number | Vec2, y?: number): Vec2;
+     * Enables rectangular scissor clipping. Only pixels within the specified
+     * rectangle (in logical coordinates) will be rendered.
+     * Coordinates use the same system as your drawing calls (top-left origin).
+     * @param x Left edge in logical pixels.
+     * @param y Top edge in logical pixels.
+     * @param width Width in logical pixels.
+     * @param height Height in logical pixels.
+     */
+    startScissor(x: number, y: number, width: number, height: number): void;
+    /**
+     * Disables scissor clipping, restoring full-canvas rendering.
+     */
+    endScissor(): void;
+    renderCamera(transform: ITransformOptions): void;
+    logicToPhysics(p: Vec2): Vec2;
+    physicsToLogic(p: Vec2): Vec2;
+    cssToDevicePixel(p: Vec2): Vec2;
+    cssToLogic(p: Vec2): Vec2;
+    devicePixelToCss(p: Vec2): Vec2;
+    /**
+     * Exports a world matrix as a CSS `matrix(...)` string, ready to assign
+     * directly to a DOM element's `style.transform`.
+     * Unlike `matrixStack.toCSSMatrix()`, this bakes in the logic-pixel → CSS-pixel
+     * scale (accounting for dpr and a custom `logicWidth`/`logicHeight`), so the
+     * result lines up with the canvas without any extra `scale(...)` on your end.
+     * @param index - Matrix index to export. Defaults to the current world matrix.
+     */
+    toCSSMatrix(index?: number): string;
 }
-export default Rapid;