@blorkfield/overlay-core 0.5.10 → 0.7.0

package/dist/index.d.cts

@@ -5,7 +5,8 @@ interface OverlaySceneConfig {
     gravity?: number;
     wrapHorizontal?: boolean;
     debug?: boolean;
-    background?: string;
+    /** Background configuration with color, image, and transparency layers */
+    background?: BackgroundConfig;
     /** @deprecated Use floorConfig instead. Pressure threshold for the floor boundary. */
     floorThreshold?: number;
     /** Distance below floor (as fraction of container height) at which objects despawn. Default: 1.0 (100%) */
@@ -69,6 +70,53 @@ interface FloorConfig {
      */
     segmentWidths?: number[];
 }
+/**
+ * Image sizing mode for background images.
+ */
+type BackgroundImageSizing = 'stretch' | 'center' | 'tile' | 'cover' | 'contain';
+/**
+ * Configuration for the background image layer.
+ */
+interface BackgroundImageConfig {
+    /** Image URL or local file path (supports same formats as entity images) */
+    url: string;
+    /** How to size/position the image. Default: 'cover' */
+    sizing?: BackgroundImageSizing;
+}
+/**
+ * Configuration for the transparency/frosted glass overlay layer.
+ * This layer renders on top of everything (including physics objects).
+ */
+interface BackgroundTransparencyConfig {
+    /**
+     * Opacity of the overlay (0-1).
+     * 0 = fully transparent (no overlay)
+     * 0.3 = light frosted glass
+     * 1 = fully opaque overlay
+     */
+    opacity: number;
+    /**
+     * Tint color for the overlay (CSS color string).
+     * If not provided, defaults to white for frosted glass effect.
+     */
+    tintColor?: string;
+}
+/**
+ * Full background configuration with three layers (bottom to top):
+ * 1. Color layer (BOTTOM) - solid background color
+ * 2. Image layer (MIDDLE) - background image
+ * 3. Transparency layer (TOP) - frosted glass effect with optional tint
+ *
+ * Layers render in order: color → image → physics objects → transparency
+ */
+interface BackgroundConfig {
+    /** Base background color (bottom layer). Default: 'transparent' */
+    color?: string;
+    /** Background image configuration (middle layer, behind physics objects) */
+    image?: BackgroundImageConfig;
+    /** Transparency/frosted glass effect (top layer, above physics objects) */
+    transparency?: BackgroundTransparencyConfig;
+}
 interface Bounds {
     top: number;
     bottom: number;
@@ -476,6 +524,7 @@ declare class OverlayScene {
     private floorSegments;
     private floorSegmentPressure;
     private collapsedSegments;
+    private backgroundManager;
     static createContainer(parent: HTMLElement, options?: ContainerOptions): {
         canvas: HTMLCanvasElement;
         bounds: Bounds;
@@ -485,6 +534,16 @@ declare class OverlayScene {
     private handleStartDrag;
     /** Handle canvas clicks for click-to-fall behavior */
     private handleCanvasClick;
+    /**
+     * Handler for Matter.js beforeRender event.
+     * Draws base background layers (color + image) before physics objects.
+     */
+    private handleBeforeRender;
+    /**
+     * Handler for Matter.js afterRender event.
+     * Draws transparency/frosted glass layer after physics objects.
+     */
+    private handleAfterRender;
     /** Get a display name for an obstacle (letter char or short ID) */
     private getObstacleDisplayName;
     /** Update pressure tracking - check which dynamic objects rest on static obstacles */
@@ -519,6 +578,10 @@ declare class OverlayScene {
     stop(): void;
     destroy(): void;
     setDebug(enabled: boolean): void;
+    /**
+     * Update the background configuration at runtime.
+     */
+    setBackground(config: BackgroundConfig | undefined): Promise<void>;
     resize(width: number, height: number): void;
     /**
      * Spawn an object synchronously.
@@ -741,6 +804,7 @@ declare class OverlayScene {
     private fireUpdateCallbacks;
 }
 
+/** Log level for controlling console output verbosity */
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 declare function setLogLevel(level: LogLevel): void;
 declare function getLogLevel(): LogLevel;
@@ -751,6 +815,7 @@ declare const logger: {
     error(prefix: string, message: string, data?: unknown): void;
 };
 
+/** 2D vector representing a point in screen space */
 interface Vector2D {
     x: number;
     y: number;
@@ -793,4 +858,113 @@ declare function measureText(loadedFont: LoadedFont, text: string, fontSize: num
  */
 declare function clearFontCache(): void;
 
-export { type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LoadedFont, type ObjectConfig, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextAlign, type TextBounds, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };
+interface BackgroundManagerConfig {
+    canvas: HTMLCanvasElement;
+    width: number;
+    height: number;
+}
+/**
+ * Manages three-layer background rendering:
+ * 1. Color layer (bottom) - solid background color
+ * 2. Image layer (middle) - background image with sizing options
+ * 3. Transparency layer (top) - frosted glass effect with optional tint
+ *
+ * The color and image layers render BEFORE physics objects (in beforeRender).
+ * The transparency layer renders AFTER physics objects (in afterRender).
+ *
+ * Performance optimization: Base layers (color + image) are pre-rendered to an
+ * offscreen canvas and only re-rendered when the config changes. Each frame
+ * just blits the cached canvas (very fast).
+ */
+declare class BackgroundManager {
+    private canvas;
+    private ctx;
+    private width;
+    private height;
+    private config;
+    private loadedImage;
+    private baseLayerCanvas;
+    private baseLayerCtx;
+    private baseLayerDirty;
+    constructor(managerConfig: BackgroundManagerConfig);
+    /**
+     * Create or recreate the offscreen canvas for base layer caching.
+     */
+    private createOffscreenCanvas;
+    /**
+     * Set the background configuration.
+     */
+    setConfig(config: BackgroundConfig | undefined): Promise<void>;
+    /**
+     * Load and cache a background image.
+     */
+    private loadBackgroundImage;
+    /**
+     * Update the canvas dimensions (call on resize).
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Get the current background config.
+     */
+    getConfig(): BackgroundConfig | null;
+    /**
+     * Check if we have custom layers to render.
+     * Returns true if we need to handle background ourselves.
+     */
+    hasCustomLayers(): boolean;
+    /**
+     * Check if background is fully transparent (no color, no image, opacity = 0 or no transparency config).
+     */
+    isFullyTransparent(): boolean;
+    /**
+     * Pre-render the base layers (color + image) to the offscreen canvas.
+     * Only called when the config changes (baseLayerDirty is true).
+     */
+    private prerenderBaseLayers;
+    /**
+     * Render the base layers (color + image).
+     * Called BEFORE Matter.js renders physics objects.
+     * Uses cached offscreen canvas for performance.
+     */
+    renderBaseLayers(): void;
+    /**
+     * Render the transparency/frosted glass layer.
+     * Called AFTER Matter.js renders physics objects.
+     * This must render every frame since it overlays moving objects.
+     */
+    renderOverlay(): void;
+    /**
+     * Render the background image to a given context with specified sizing.
+     */
+    private renderImageLayerToContext;
+    /**
+     * Draw image centered at original size.
+     */
+    private drawCenter;
+    /**
+     * Draw image tiled (repeating pattern).
+     */
+    private drawTile;
+    /**
+     * Draw image to cover entire area (may crop, maintains aspect ratio).
+     */
+    private drawCover;
+    /**
+     * Draw image to fit within area (may have gaps, maintains aspect ratio).
+     * Gaps are filled by the color layer underneath.
+     */
+    private drawContain;
+    /**
+     * Render the transparency/frosted glass layer.
+     * opacity = 0 means fully transparent (nothing drawn)
+     * opacity = 1 means fully opaque overlay
+     * opacity = 0.3 means light frosted glass
+     */
+    private renderTransparencyLayer;
+    /**
+     * Clear the background image cache.
+     */
+    static clearCache(): void;
+}
+
+export { type BackgroundConfig, type BackgroundImageConfig, type BackgroundImageSizing, BackgroundManager, type BackgroundTransparencyConfig, type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LoadedFont, type LogLevel, type ObjectConfig, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextAlign, type TextBounds, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };

package/dist/index.d.ts

@@ -5,7 +5,8 @@ interface OverlaySceneConfig {
     gravity?: number;
     wrapHorizontal?: boolean;
     debug?: boolean;
-    background?: string;
+    /** Background configuration with color, image, and transparency layers */
+    background?: BackgroundConfig;
     /** @deprecated Use floorConfig instead. Pressure threshold for the floor boundary. */
     floorThreshold?: number;
     /** Distance below floor (as fraction of container height) at which objects despawn. Default: 1.0 (100%) */
@@ -69,6 +70,53 @@ interface FloorConfig {
      */
     segmentWidths?: number[];
 }
+/**
+ * Image sizing mode for background images.
+ */
+type BackgroundImageSizing = 'stretch' | 'center' | 'tile' | 'cover' | 'contain';
+/**
+ * Configuration for the background image layer.
+ */
+interface BackgroundImageConfig {
+    /** Image URL or local file path (supports same formats as entity images) */
+    url: string;
+    /** How to size/position the image. Default: 'cover' */
+    sizing?: BackgroundImageSizing;
+}
+/**
+ * Configuration for the transparency/frosted glass overlay layer.
+ * This layer renders on top of everything (including physics objects).
+ */
+interface BackgroundTransparencyConfig {
+    /**
+     * Opacity of the overlay (0-1).
+     * 0 = fully transparent (no overlay)
+     * 0.3 = light frosted glass
+     * 1 = fully opaque overlay
+     */
+    opacity: number;
+    /**
+     * Tint color for the overlay (CSS color string).
+     * If not provided, defaults to white for frosted glass effect.
+     */
+    tintColor?: string;
+}
+/**
+ * Full background configuration with three layers (bottom to top):
+ * 1. Color layer (BOTTOM) - solid background color
+ * 2. Image layer (MIDDLE) - background image
+ * 3. Transparency layer (TOP) - frosted glass effect with optional tint
+ *
+ * Layers render in order: color → image → physics objects → transparency
+ */
+interface BackgroundConfig {
+    /** Base background color (bottom layer). Default: 'transparent' */
+    color?: string;
+    /** Background image configuration (middle layer, behind physics objects) */
+    image?: BackgroundImageConfig;
+    /** Transparency/frosted glass effect (top layer, above physics objects) */
+    transparency?: BackgroundTransparencyConfig;
+}
 interface Bounds {
     top: number;
     bottom: number;
@@ -476,6 +524,7 @@ declare class OverlayScene {
     private floorSegments;
     private floorSegmentPressure;
     private collapsedSegments;
+    private backgroundManager;
     static createContainer(parent: HTMLElement, options?: ContainerOptions): {
         canvas: HTMLCanvasElement;
         bounds: Bounds;
@@ -485,6 +534,16 @@ declare class OverlayScene {
     private handleStartDrag;
     /** Handle canvas clicks for click-to-fall behavior */
     private handleCanvasClick;
+    /**
+     * Handler for Matter.js beforeRender event.
+     * Draws base background layers (color + image) before physics objects.
+     */
+    private handleBeforeRender;
+    /**
+     * Handler for Matter.js afterRender event.
+     * Draws transparency/frosted glass layer after physics objects.
+     */
+    private handleAfterRender;
     /** Get a display name for an obstacle (letter char or short ID) */
     private getObstacleDisplayName;
     /** Update pressure tracking - check which dynamic objects rest on static obstacles */
@@ -519,6 +578,10 @@ declare class OverlayScene {
     stop(): void;
     destroy(): void;
     setDebug(enabled: boolean): void;
+    /**
+     * Update the background configuration at runtime.
+     */
+    setBackground(config: BackgroundConfig | undefined): Promise<void>;
     resize(width: number, height: number): void;
     /**
      * Spawn an object synchronously.
@@ -741,6 +804,7 @@ declare class OverlayScene {
     private fireUpdateCallbacks;
 }
 
+/** Log level for controlling console output verbosity */
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 declare function setLogLevel(level: LogLevel): void;
 declare function getLogLevel(): LogLevel;
@@ -751,6 +815,7 @@ declare const logger: {
     error(prefix: string, message: string, data?: unknown): void;
 };
 
+/** 2D vector representing a point in screen space */
 interface Vector2D {
     x: number;
     y: number;
@@ -793,4 +858,113 @@ declare function measureText(loadedFont: LoadedFont, text: string, fontSize: num
  */
 declare function clearFontCache(): void;
 
-export { type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LoadedFont, type ObjectConfig, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextAlign, type TextBounds, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };
+interface BackgroundManagerConfig {
+    canvas: HTMLCanvasElement;
+    width: number;
+    height: number;
+}
+/**
+ * Manages three-layer background rendering:
+ * 1. Color layer (bottom) - solid background color
+ * 2. Image layer (middle) - background image with sizing options
+ * 3. Transparency layer (top) - frosted glass effect with optional tint
+ *
+ * The color and image layers render BEFORE physics objects (in beforeRender).
+ * The transparency layer renders AFTER physics objects (in afterRender).
+ *
+ * Performance optimization: Base layers (color + image) are pre-rendered to an
+ * offscreen canvas and only re-rendered when the config changes. Each frame
+ * just blits the cached canvas (very fast).
+ */
+declare class BackgroundManager {
+    private canvas;
+    private ctx;
+    private width;
+    private height;
+    private config;
+    private loadedImage;
+    private baseLayerCanvas;
+    private baseLayerCtx;
+    private baseLayerDirty;
+    constructor(managerConfig: BackgroundManagerConfig);
+    /**
+     * Create or recreate the offscreen canvas for base layer caching.
+     */
+    private createOffscreenCanvas;
+    /**
+     * Set the background configuration.
+     */
+    setConfig(config: BackgroundConfig | undefined): Promise<void>;
+    /**
+     * Load and cache a background image.
+     */
+    private loadBackgroundImage;
+    /**
+     * Update the canvas dimensions (call on resize).
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Get the current background config.
+     */
+    getConfig(): BackgroundConfig | null;
+    /**
+     * Check if we have custom layers to render.
+     * Returns true if we need to handle background ourselves.
+     */
+    hasCustomLayers(): boolean;
+    /**
+     * Check if background is fully transparent (no color, no image, opacity = 0 or no transparency config).
+     */
+    isFullyTransparent(): boolean;
+    /**
+     * Pre-render the base layers (color + image) to the offscreen canvas.
+     * Only called when the config changes (baseLayerDirty is true).
+     */
+    private prerenderBaseLayers;
+    /**
+     * Render the base layers (color + image).
+     * Called BEFORE Matter.js renders physics objects.
+     * Uses cached offscreen canvas for performance.
+     */
+    renderBaseLayers(): void;
+    /**
+     * Render the transparency/frosted glass layer.
+     * Called AFTER Matter.js renders physics objects.
+     * This must render every frame since it overlays moving objects.
+     */
+    renderOverlay(): void;
+    /**
+     * Render the background image to a given context with specified sizing.
+     */
+    private renderImageLayerToContext;
+    /**
+     * Draw image centered at original size.
+     */
+    private drawCenter;
+    /**
+     * Draw image tiled (repeating pattern).
+     */
+    private drawTile;
+    /**
+     * Draw image to cover entire area (may crop, maintains aspect ratio).
+     */
+    private drawCover;
+    /**
+     * Draw image to fit within area (may have gaps, maintains aspect ratio).
+     * Gaps are filled by the color layer underneath.
+     */
+    private drawContain;
+    /**
+     * Render the transparency/frosted glass layer.
+     * opacity = 0 means fully transparent (nothing drawn)
+     * opacity = 1 means fully opaque overlay
+     * opacity = 0.3 means light frosted glass
+     */
+    private renderTransparencyLayer;
+    /**
+     * Clear the background image cache.
+     */
+    static clearCache(): void;
+}
+
+export { type BackgroundConfig, type BackgroundImageConfig, type BackgroundImageSizing, BackgroundManager, type BackgroundTransparencyConfig, type BaseEffectConfig, type Bounds, type BurstEffectConfig, type ClickToFallConfig, type ContainerOptions, type DespawnEffectConfig, type DynamicObject, type EffectConfig, type EffectObjectConfig, type EffectType, type FloorConfig, type FontInfo, type FontManifest, type GlyphData, type LoadedFont, type LogLevel, type ObjectConfig, OverlayScene, type OverlaySceneConfig, type PressureThresholdConfig, type RainEffectConfig, type ShadowConfig, type ShapeConfig, type ShapePreset, type StreamEffectConfig, type TTFTextObstacleConfig, type TextAlign, type TextBounds, type TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };