@blorkfield/overlay-core 0.5.0 → 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 */
@@ -353,41 +419,6 @@ interface TTFTextObstacleConfig {
     /** Click to fall config - when set, letters collapse after being clicked N times */
     clickToFall?: ClickToFallConfig;
 }
-/**
- * Configuration for attaching a DOM element to physics.
- * The element will follow the physics body and can have pressure/shadow/click behavior.
- */
-interface DOMObstacleConfig {
-    /** The DOM element to attach to physics */
-    element: HTMLElement;
-    /** X position of the element center */
-    x: number;
-    /** Y position of the element center */
-    y: number;
-    /** Width of the collision body (defaults to element.offsetWidth) */
-    width?: number;
-    /** Height of the collision body (defaults to element.offsetHeight) */
-    height?: number;
-    /** Tags that define object behavior */
-    tags?: string[];
-    /** Pressure threshold config - when reached, element collapses */
-    pressureThreshold?: PressureThresholdConfig;
-    /** Weight for pressure calculation (default: 1) */
-    weight?: number;
-    /** Shadow config - when enabled, a cloned element remains after collapse */
-    shadow?: ShadowConfig;
-    /** Click to fall config - when set, element collapses after being clicked N times */
-    clickToFall?: ClickToFallConfig;
-}
-/**
- * Result of attaching a DOM element to physics
- */
-interface DOMObstacleResult {
-    /** ID of the created physics object */
-    id: string;
-    /** The shadow element if shadow was configured (null until collapse) */
-    shadowElement: HTMLElement | null;
-}
 /**
  * Information about an available font
  */
@@ -451,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 */
@@ -586,15 +621,10 @@ declare class OverlayScene {
      */
     areFontsInitialized(): boolean;
     /**
-     * Attach a DOM element to physics. The element will follow the physics body
-     * and can have pressure threshold, shadow, and click-to-fall behavior.
-     *
-     * When the element collapses (becomes dynamic), its CSS transform will be
-     * updated each frame to match the physics body position and rotation.
-     *
-     * Shadow creates a cloned DOM element that stays at the original position.
+     * Internal: Attach a DOM element to physics.
+     * Called by spawnObject when element is provided.
      */
-    addDOMObstacle(config: DOMObstacleConfig): DOMObstacleResult;
+    private addDOMObstacleInternal;
     /**
      * Get the shadow element for a DOM obstacle (available after collapse).
      */
@@ -750,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 DOMObstacleConfig, type DOMObstacleResult, 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 */
@@ -353,41 +419,6 @@ interface TTFTextObstacleConfig {
     /** Click to fall config - when set, letters collapse after being clicked N times */
     clickToFall?: ClickToFallConfig;
 }
-/**
- * Configuration for attaching a DOM element to physics.
- * The element will follow the physics body and can have pressure/shadow/click behavior.
- */
-interface DOMObstacleConfig {
-    /** The DOM element to attach to physics */
-    element: HTMLElement;
-    /** X position of the element center */
-    x: number;
-    /** Y position of the element center */
-    y: number;
-    /** Width of the collision body (defaults to element.offsetWidth) */
-    width?: number;
-    /** Height of the collision body (defaults to element.offsetHeight) */
-    height?: number;
-    /** Tags that define object behavior */
-    tags?: string[];
-    /** Pressure threshold config - when reached, element collapses */
-    pressureThreshold?: PressureThresholdConfig;
-    /** Weight for pressure calculation (default: 1) */
-    weight?: number;
-    /** Shadow config - when enabled, a cloned element remains after collapse */
-    shadow?: ShadowConfig;
-    /** Click to fall config - when set, element collapses after being clicked N times */
-    clickToFall?: ClickToFallConfig;
-}
-/**
- * Result of attaching a DOM element to physics
- */
-interface DOMObstacleResult {
-    /** ID of the created physics object */
-    id: string;
-    /** The shadow element if shadow was configured (null until collapse) */
-    shadowElement: HTMLElement | null;
-}
 /**
  * Information about an available font
  */
@@ -451,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 */
@@ -586,15 +621,10 @@ declare class OverlayScene {
      */
     areFontsInitialized(): boolean;
     /**
-     * Attach a DOM element to physics. The element will follow the physics body
-     * and can have pressure threshold, shadow, and click-to-fall behavior.
-     *
-     * When the element collapses (becomes dynamic), its CSS transform will be
-     * updated each frame to match the physics body position and rotation.
-     *
-     * Shadow creates a cloned DOM element that stays at the original position.
+     * Internal: Attach a DOM element to physics.
+     * Called by spawnObject when element is provided.
      */
-    addDOMObstacle(config: DOMObstacleConfig): DOMObstacleResult;
+    private addDOMObstacleInternal;
     /**
      * Get the shadow element for a DOM obstacle (available after collapse).
      */
@@ -750,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 DOMObstacleConfig, type DOMObstacleResult, 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 };