@blorkfield/overlay-core 0.4.3 → 0.5.1

package/dist/index.d.cts

@@ -30,6 +30,33 @@ interface FloorConfig {
      * If not provided, segments have infinite capacity.
      */
     threshold?: number | number[];
+    /**
+     * Thickness of floor segments in pixels:
+     * - number: Same thickness for all segments (default: 50)
+     * - number[]: Per-segment thickness (segment 0 uses value[0], etc.)
+     */
+    thickness?: number | number[];
+    /**
+     * Color of floor segments (visible when set):
+     * - string: Same color for all segments
+     * - string[]: Per-segment colors (segment 0 uses value[0], etc.)
+     * If not provided, floor segments are invisible.
+     */
+    color?: string | string[];
+    /**
+     * Minimum number of segments that must remain for floor integrity.
+     * When remaining segments drops below this value, ALL remaining segments collapse.
+     * Example: segments=10, minIntegrity=7 means once 4+ segments collapse, the rest follow.
+     * If set higher than segments count, floor collapses immediately.
+     */
+    minIntegrity?: number;
+    /**
+     * Proportional widths for each segment (must sum to 1.0):
+     * - number[]: Per-segment width proportions (e.g., [0.2, 0.3, 0.5] for 3 segments)
+     * If not provided, segments have equal widths.
+     * Array length should match segments count.
+     */
+    segmentWidths?: number[];
 }
 interface Bounds {
     top: number;
@@ -68,6 +95,8 @@ interface DespawnEffectConfig {
 interface ObjectConfig {
     x: number;
     y: number;
+    /** DOM element to link to physics. When provided, element moves with physics body and shadow clones the element */
+    element?: HTMLElement;
     /** Radius for circle/polygon shapes */
     radius?: number;
     /** Width for rectangle objects (ignored if imageUrl is provided) */
@@ -90,6 +119,12 @@ interface ObjectConfig {
     despawnEffect?: DespawnEffectConfig;
     /** Weight for pressure calculation (default: 1). Higher weight = more pressure contribution */
     weight?: number;
+    /** Pressure threshold config - when reached, object collapses */
+    pressureThreshold?: PressureThresholdConfig;
+    /** Shadow config - when enabled, a visual copy remains after collapse (true for default opacity) */
+    shadow?: ShadowConfig | boolean;
+    /** Click to fall config - when set, object collapses after being clicked N times */
+    clickToFall?: ClickToFallConfig;
 }
 /**
  * Dynamic object data passed to update callbacks.
@@ -247,16 +282,25 @@ interface ClickToFallConfig {
      */
     clicks: number;
 }
+/**
+ * Text alignment option for positioning text obstacles.
+ * - 'left': x coordinate is the left edge of the text (default)
+ * - 'center': x coordinate is the center of the text
+ * - 'right': x coordinate is the right edge of the text
+ */
+type TextAlign = 'left' | 'center' | 'right';
 /**
  * Configuration for creating text objects from strings
  */
 interface TextObstacleConfig {
     /** The text to create objects from (A-Z, 0-9 supported, supports \n for multiline) */
     text: string;
-    /** X position of the first letter's center */
+    /** X position (interpretation depends on align setting) */
     x: number;
     /** Y position of the letter centers */
     y: number;
+    /** Text alignment - 'left' (default), 'center', or 'right' */
+    align?: TextAlign;
     /** Size of each letter (width/height) */
     letterSize: number;
     /** Spacing between letter centers (default: letterSize) */
@@ -305,6 +349,24 @@ interface LetterDebugInfo {
     centerX: number;
     centerY: number;
 }
+/**
+ * Bounding box for text obstacles.
+ * Useful for positioning subsequent elements relative to the text.
+ */
+interface TextBounds {
+    /** X position of the left edge of the text */
+    left: number;
+    /** X position of the right edge of the text */
+    right: number;
+    /** Y position of the top edge of the text */
+    top: number;
+    /** Y position of the bottom edge of the text */
+    bottom: number;
+    /** Total width of the text */
+    width: number;
+    /** Total height of the text (including all lines) */
+    height: number;
+}
 /**
  * Result of creating text obstacles
  */
@@ -319,6 +381,8 @@ interface TextObstacleResult {
     letterMap: Map<string, string>;
     /** Debug info for each letter (for drawing original dimension boxes) */
     letterDebugInfo: LetterDebugInfo[];
+    /** Bounding box of the entire text block */
+    bounds: TextBounds;
 }
 /**
  * Configuration for creating text objects from a TTF font
@@ -326,10 +390,12 @@ interface TextObstacleResult {
 interface TTFTextObstacleConfig {
     /** Text to display (supports \n for multiline) */
     text: string;
-    /** X position of the start of text */
+    /** X position (interpretation depends on align setting) */
     x: number;
     /** Y position of the text baseline */
     y: number;
+    /** Text alignment - 'left' (default), 'center', or 'right' */
+    align?: TextAlign;
     /** Font size in pixels */
     fontSize: number;
     /** URL path to the TTF/OTF font file */
@@ -416,6 +482,10 @@ declare class OverlayScene {
     private checkFloorSegmentThresholds;
     /** Collapse a single floor segment */
     private collapseFloorSegment;
+    /** Check if floor integrity requirement is violated and collapse all remaining if so */
+    private checkFloorIntegrity;
+    /** Check floor integrity on initialization (handles minIntegrity > segments) */
+    private checkInitialFloorIntegrity;
     /** Log a summary of pressure on all obstacles, grouped by word */
     private logPressureSummary;
     /** Calculate weighted pressure from a set of object IDs */
@@ -550,6 +620,15 @@ declare class OverlayScene {
      * Check if fonts have been initialized.
      */
     areFontsInitialized(): boolean;
+    /**
+     * Internal: Attach a DOM element to physics.
+     * Called by spawnObject when element is provided.
+     */
+    private addDOMObstacleInternal;
+    /**
+     * Get the shadow element for a DOM obstacle (available after collapse).
+     */
+    getDOMObstacleShadow(id: string): HTMLElement | null;
     /**
      * Create text obstacles from a string. Each character becomes an individual obstacle
      * with shape extracted from the corresponding letter PNG image.
@@ -639,6 +718,10 @@ declare class OverlayScene {
      * Draw TTF glyphs using canvas fillText for clean text rendering
      */
     private drawTTFGlyphs;
+    /**
+     * Update a DOM element's CSS transform to match its physics body position and rotation.
+     */
+    private updateDOMElementTransform;
     private checkTTLExpiration;
     /** Despawn objects that have fallen below the floor by the configured distance */
     private checkDespawnBelowFloor;
@@ -697,4 +780,4 @@ 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 TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };
+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 };

package/dist/index.d.ts

@@ -30,6 +30,33 @@ interface FloorConfig {
      * If not provided, segments have infinite capacity.
      */
     threshold?: number | number[];
+    /**
+     * Thickness of floor segments in pixels:
+     * - number: Same thickness for all segments (default: 50)
+     * - number[]: Per-segment thickness (segment 0 uses value[0], etc.)
+     */
+    thickness?: number | number[];
+    /**
+     * Color of floor segments (visible when set):
+     * - string: Same color for all segments
+     * - string[]: Per-segment colors (segment 0 uses value[0], etc.)
+     * If not provided, floor segments are invisible.
+     */
+    color?: string | string[];
+    /**
+     * Minimum number of segments that must remain for floor integrity.
+     * When remaining segments drops below this value, ALL remaining segments collapse.
+     * Example: segments=10, minIntegrity=7 means once 4+ segments collapse, the rest follow.
+     * If set higher than segments count, floor collapses immediately.
+     */
+    minIntegrity?: number;
+    /**
+     * Proportional widths for each segment (must sum to 1.0):
+     * - number[]: Per-segment width proportions (e.g., [0.2, 0.3, 0.5] for 3 segments)
+     * If not provided, segments have equal widths.
+     * Array length should match segments count.
+     */
+    segmentWidths?: number[];
 }
 interface Bounds {
     top: number;
@@ -68,6 +95,8 @@ interface DespawnEffectConfig {
 interface ObjectConfig {
     x: number;
     y: number;
+    /** DOM element to link to physics. When provided, element moves with physics body and shadow clones the element */
+    element?: HTMLElement;
     /** Radius for circle/polygon shapes */
     radius?: number;
     /** Width for rectangle objects (ignored if imageUrl is provided) */
@@ -90,6 +119,12 @@ interface ObjectConfig {
     despawnEffect?: DespawnEffectConfig;
     /** Weight for pressure calculation (default: 1). Higher weight = more pressure contribution */
     weight?: number;
+    /** Pressure threshold config - when reached, object collapses */
+    pressureThreshold?: PressureThresholdConfig;
+    /** Shadow config - when enabled, a visual copy remains after collapse (true for default opacity) */
+    shadow?: ShadowConfig | boolean;
+    /** Click to fall config - when set, object collapses after being clicked N times */
+    clickToFall?: ClickToFallConfig;
 }
 /**
  * Dynamic object data passed to update callbacks.
@@ -247,16 +282,25 @@ interface ClickToFallConfig {
      */
     clicks: number;
 }
+/**
+ * Text alignment option for positioning text obstacles.
+ * - 'left': x coordinate is the left edge of the text (default)
+ * - 'center': x coordinate is the center of the text
+ * - 'right': x coordinate is the right edge of the text
+ */
+type TextAlign = 'left' | 'center' | 'right';
 /**
  * Configuration for creating text objects from strings
  */
 interface TextObstacleConfig {
     /** The text to create objects from (A-Z, 0-9 supported, supports \n for multiline) */
     text: string;
-    /** X position of the first letter's center */
+    /** X position (interpretation depends on align setting) */
     x: number;
     /** Y position of the letter centers */
     y: number;
+    /** Text alignment - 'left' (default), 'center', or 'right' */
+    align?: TextAlign;
     /** Size of each letter (width/height) */
     letterSize: number;
     /** Spacing between letter centers (default: letterSize) */
@@ -305,6 +349,24 @@ interface LetterDebugInfo {
     centerX: number;
     centerY: number;
 }
+/**
+ * Bounding box for text obstacles.
+ * Useful for positioning subsequent elements relative to the text.
+ */
+interface TextBounds {
+    /** X position of the left edge of the text */
+    left: number;
+    /** X position of the right edge of the text */
+    right: number;
+    /** Y position of the top edge of the text */
+    top: number;
+    /** Y position of the bottom edge of the text */
+    bottom: number;
+    /** Total width of the text */
+    width: number;
+    /** Total height of the text (including all lines) */
+    height: number;
+}
 /**
  * Result of creating text obstacles
  */
@@ -319,6 +381,8 @@ interface TextObstacleResult {
     letterMap: Map<string, string>;
     /** Debug info for each letter (for drawing original dimension boxes) */
     letterDebugInfo: LetterDebugInfo[];
+    /** Bounding box of the entire text block */
+    bounds: TextBounds;
 }
 /**
  * Configuration for creating text objects from a TTF font
@@ -326,10 +390,12 @@ interface TextObstacleResult {
 interface TTFTextObstacleConfig {
     /** Text to display (supports \n for multiline) */
     text: string;
-    /** X position of the start of text */
+    /** X position (interpretation depends on align setting) */
     x: number;
     /** Y position of the text baseline */
     y: number;
+    /** Text alignment - 'left' (default), 'center', or 'right' */
+    align?: TextAlign;
     /** Font size in pixels */
     fontSize: number;
     /** URL path to the TTF/OTF font file */
@@ -416,6 +482,10 @@ declare class OverlayScene {
     private checkFloorSegmentThresholds;
     /** Collapse a single floor segment */
     private collapseFloorSegment;
+    /** Check if floor integrity requirement is violated and collapse all remaining if so */
+    private checkFloorIntegrity;
+    /** Check floor integrity on initialization (handles minIntegrity > segments) */
+    private checkInitialFloorIntegrity;
     /** Log a summary of pressure on all obstacles, grouped by word */
     private logPressureSummary;
     /** Calculate weighted pressure from a set of object IDs */
@@ -550,6 +620,15 @@ declare class OverlayScene {
      * Check if fonts have been initialized.
      */
     areFontsInitialized(): boolean;
+    /**
+     * Internal: Attach a DOM element to physics.
+     * Called by spawnObject when element is provided.
+     */
+    private addDOMObstacleInternal;
+    /**
+     * Get the shadow element for a DOM obstacle (available after collapse).
+     */
+    getDOMObstacleShadow(id: string): HTMLElement | null;
     /**
      * Create text obstacles from a string. Each character becomes an individual obstacle
      * with shape extracted from the corresponding letter PNG image.
@@ -639,6 +718,10 @@ declare class OverlayScene {
      * Draw TTF glyphs using canvas fillText for clean text rendering
      */
     private drawTTFGlyphs;
+    /**
+     * Update a DOM element's CSS transform to match its physics body position and rotation.
+     */
+    private updateDOMElementTransform;
     private checkTTLExpiration;
     /** Despawn objects that have fallen below the floor by the configured distance */
     private checkDespawnBelowFloor;
@@ -697,4 +780,4 @@ 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 TextObstacleConfig, type TextObstacleResult, type UpdateCallback, type UpdateCallbackData, type WeightConfig, clearFontCache, getGlyphData, getKerning, getLogLevel, loadFont, logger, measureText, setLogLevel };
+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 };