@blorkfield/overlay-core 0.8.7 → 0.8.9

package/README.md

@@ -22,13 +22,24 @@ pnpm add @blorkfield/overlay-core
 
 ### Tag Based Behavior
 
-Objects don't have fixed types. Instead, their behavior is determined by string tags:
+Objects don't have fixed types. Instead, their behavior is determined by string tags. Import the tag constants to avoid magic strings:
 
-| Tag | Behavior |
-|-----|----------|
-| `falling` | Object is dynamic and affected by gravity |
-| `follow` | Object follows mouse position when grounded |
-| `grabable` | Object can be dragged via mouse constraint |
+```typescript
+import { TAGS, TAG_FALLING, TAG_GRABABLE, TAG_FOLLOW_WINDOW } from '@blorkfield/overlay-core';
+
+// Use individual constants
+scene.spawnObject({ tags: [TAG_FALLING, TAG_GRABABLE], ... });
+
+// Or destructure from TAGS object
+const { FALLING, GRABABLE } = TAGS;
+scene.spawnObject({ tags: [FALLING, GRABABLE], ... });
+```
+
+| Constant | Value | Behavior |
+|----------|-------|----------|
+| `TAG_FALLING` / `TAGS.FALLING` | `'falling'` | Object is dynamic and affected by gravity |
+| `TAG_FOLLOW_WINDOW` / `TAGS.FOLLOW_WINDOW` | `'follow_window'` | Object follows mouse position when grounded |
+| `TAG_GRABABLE` / `TAGS.GRABABLE` | `'grabable'` | Object can be grabbed and moved with mouse |
 
 Without the `falling` tag, objects are static and won't move.
 
@@ -153,6 +164,11 @@ When a DOM element collapses:
 - The element's CSS transform is updated each frame to follow physics
 - Shadow creates a cloned DOM element at the original position
 
+```typescript
+// Get the shadow element after collapse (if shadow was configured)
+const shadowEl = scene.getDOMObstacleShadow(id);
+```
+
 ### Pressure, Shadow, and Click Behavior
 
 These options work on any spawned object (shapes, images, or DOM elements):
@@ -225,6 +241,25 @@ const result = await scene.addTTFTextObstacles({
 });
 ```
 
+### Managing Text Obstacles
+
+```typescript
+// Spawn text that immediately falls (already has 'falling' tag)
+const result = await scene.spawnFallingTextObstacles(config);
+const result = await scene.spawnFallingTTFTextObstacles(config);
+
+// Release text obstacles (add 'falling' tag)
+scene.releaseTextObstacles(wordTag);
+
+// Release letters one by one with delay
+await scene.releaseTextObstaclesSequentially(wordTag, 100);        // 100ms delay
+await scene.releaseTextObstaclesSequentially(wordTag, 100, true);  // reverse order
+
+// Get debug info for letter positioning
+const debugInfo = scene.getLetterDebugInfo(wordTag);
+const allDebug = scene.getAllLetterDebugInfo();
+```
+
 ## Effects
 
 Effects are persistent spawning mechanisms that create objects over time.
@@ -294,22 +329,45 @@ scene.setEffect({
 ```typescript
 // Release objects (make them fall)
 scene.releaseObject(id);
+scene.releaseObjects([id1, id2]);
 scene.releaseObjectsByTag('my-text');
 scene.releaseAllObjects();
 
 // Remove objects
 scene.removeObject(id);
+scene.removeObjects([id1, id2]);
 scene.removeObjectsByTag('welcome-text');
 scene.removeAllObjects();
+scene.removeAll();              // Alias for removeAllObjects
+scene.removeAllByTag('tag');    // Alias for removeObjectsByTag
 
 // Add or remove tags
 scene.addTag(id, 'falling');
+scene.addFallingTag(id);        // Convenience for adding 'falling' tag
 scene.removeTag(id, 'grabable');
 
 // Get object info
 const ids = scene.getObjectIds();
 const tagged = scene.getObjectIdsByTag('falling');
 const allTags = scene.getAllTags();
+
+// Get full object state
+const obj = scene.getObject(id);           // Returns ObjectState or null
+const objs = scene.getObjectsByTag('tag'); // Returns ObjectState[]
+```
+
+## Physics Manipulation
+
+```typescript
+// Apply force to objects
+scene.applyForce(id, { x: 0.01, y: -0.02 });
+scene.applyForceToTag('falling', { x: 0.005, y: 0 });
+
+// Set velocity directly
+scene.setVelocity(id, { x: 5, y: -10 });
+
+// Set position directly
+scene.setPosition(id, { x: 100, y: 200 });
 ```
 
 ## Mouse Position and Grab API
@@ -352,9 +410,11 @@ const currentGrab = scene.getGrabbedObject(); // Returns ID or null
 
 | Method | Returns | Description |
 |--------|---------|-------------|
-| `setFollowTarget('mouse', x, y)` | void | Set mouse position for follow behavior and grab detection |
+| `setFollowTarget(key, x, y)` | void | Set a follow target position (e.g., 'mouse' for grab/follow behavior) |
+| `removeFollowTarget(key)` | void | Remove a follow target |
+| `getFollowTargetKeys()` | string[] | Get all active follow target keys |
 | `startGrab()` | string \| null | Link entity at current mouse position to mouse, returns entity ID |
-| `endGrab()` | void | Unlink currently grabbed entity |
+| `endGrab()` | void | Unlink currently grabbed entity (applies release velocity) |
 | `getGrabbedObject()` | string \| null | Get ID of currently grabbed entity |
 
 ## Configuration
@@ -393,6 +453,34 @@ const scene = new OverlayScene(canvas, {
 | `floorConfig.segmentWidths` | none | Proportional widths for each segment (array that sums to 1.0) |
 | `despawnBelowFloor` | 1.0 | Distance below floor to despawn objects (as fraction of height) |
 
+### Background Configuration
+
+The `background` option supports multiple formats:
+
+```typescript
+// Simple color
+background: '#16213e'
+background: 'transparent'
+
+// Full configuration with layers
+background: {
+  color: '#16213e',              // Base color layer
+  image: {
+    url: '/images/bg.png',
+    sizing: 'cover'              // 'stretch' | 'center' | 'tile' | 'cover' | 'contain'
+  },
+  transparency: {
+    mode: 'checkerboard',        // Visual indicator for transparent areas
+    color1: '#ffffff',
+    color2: '#cccccc',
+    size: 10
+  }
+}
+
+// Change background at runtime
+await scene.setBackground({ color: '#000000' });
+```
+
 ## Pressure Tracking
 
 ```typescript
@@ -409,7 +497,11 @@ const allPressure = scene.getAllPressure();
 const summary = scene.getPressureSummary();
 ```
 
-## Update Callbacks
+## Callbacks and Events
+
+### Update Callback
+
+Called every frame with all dynamic object states:
 
 ```typescript
 scene.onUpdate((data) => {
@@ -420,6 +512,30 @@ scene.onUpdate((data) => {
 });
 ```
 
+### Lifecycle Events
+
+Subscribe to object lifecycle events:
+
+```typescript
+// Object spawned
+scene.on('objectSpawned', (obj) => {
+  console.log(`Spawned: ${obj.id}`, obj.x, obj.y);
+});
+
+// Object removed
+scene.on('objectRemoved', (obj) => {
+  console.log(`Removed: ${obj.id}`);
+});
+
+// Objects collided
+scene.on('objectCollision', (a, b) => {
+  console.log(`Collision: ${a.id} hit ${b.id}`);
+});
+
+// Unsubscribe
+scene.off('objectSpawned', myCallback);
+```
+
 ## Font Setup
 
 ### Bundled Fonts
@@ -496,6 +612,22 @@ Add the font file and reference it in the manifest:
 }
 ```
 
+### Font API
+
+```typescript
+// Initialize fonts from a directory
+await scene.initializeFonts('/fonts/');
+
+// Check initialization status
+if (scene.areFontsInitialized()) {
+  // Get available fonts
+  const fonts = scene.getAvailableFonts();      // Returns FontInfo[]
+  const font = scene.getFontByName('Roboto');   // Returns FontInfo | undefined
+  const font = scene.getFontByIndex(0);         // Returns FontInfo | undefined
+  const defaultFont = scene.getDefaultFont();   // Returns first font or undefined
+}
+```
+
 ## Logging
 
 ```typescript
@@ -536,18 +668,67 @@ The package is written in TypeScript and ships with full type definitions. All c
 
 ```typescript
 import type {
+  // Scene configuration
   OverlaySceneConfig,
+  Bounds,
+  ContainerOptions,
+  FloorConfig,
+
+  // Object types
   ObjectConfig,
+  DynamicObject,
+  ObjectState,
+  ShapeConfig,
+  ShapePreset,
+  DespawnEffectConfig,
+
+  // Text obstacle types
   TextObstacleConfig,
+  TextObstacleResult,
   TTFTextObstacleConfig,
+  TextAlign,
+  TextBounds,
+
+  // Effect types
   EffectConfig,
+  EffectType,
+  EffectObjectConfig,
+  BaseEffectConfig,
   BurstEffectConfig,
   RainEffectConfig,
   StreamEffectConfig,
+
+  // Pressure, weight, shadow, click types
   PressureThresholdConfig,
   WeightConfig,
   ShadowConfig,
   ClickToFallConfig,
-  FloorConfig
+
+  // Background types
+  BackgroundConfig,
+  BackgroundImageConfig,
+  BackgroundImageSizing,
+  BackgroundTransparencyConfig,
+
+  // Font types
+  FontInfo,
+  FontManifest,
+  LoadedFont,
+  GlyphData,
+
+  // Lifecycle types
+  LifecycleEvent,
+  LifecycleCallback,
+  UpdateCallback,
+  UpdateCallbackData,
+
+  // Logging
+  LogLevel,
+
+  // Tags
+  Tag
 } from '@blorkfield/overlay-core';
+
+// Tag constants (values, not types)
+import { TAGS, TAG_FALLING, TAG_GRABABLE, TAG_FOLLOW_WINDOW } from '@blorkfield/overlay-core';
 ```

package/dist/index.cjs

@@ -32,6 +32,10 @@ var index_exports = {};
 __export(index_exports, {
   BackgroundManager: () => BackgroundManager,
   OverlayScene: () => OverlayScene,
+  TAGS: () => TAGS,
+  TAG_FALLING: () => TAG_FALLING,
+  TAG_FOLLOW_WINDOW: () => TAG_FOLLOW_WINDOW,
+  TAG_GRABABLE: () => TAG_GRABABLE,
   clearFontCache: () => clearFontCache,
   getGlyphData: () => getGlyphData,
   getKerning: () => getKerning,
@@ -1547,7 +1551,7 @@ var OverlayScene = class {
         const isDragging = this.grabbedObjectId === entry.id;
         if (!isDragging) {
           for (const tag of entry.tags) {
-            const key = tag === "follow" ? "mouse" : tag.startsWith("follow-") ? tag.slice(7) : null;
+            const key = tag === "follow_window" ? "mouse" : tag.startsWith("follow-") ? tag.slice(7) : null;
             if (key) {
               const target = this.followTargets.get(key);
               if (target) {
@@ -2082,8 +2086,8 @@ var OverlayScene = class {
    * Spawn an object synchronously.
    * Object behavior is determined by tags:
    * - 'falling': Object is dynamic (affected by gravity)
-   * - 'follow': Object follows mouse when grounded
-   * - 'grabable': Object can be dragged
+   * - 'follow_window': Object follows mouse when grounded (walks toward mouse)
+   * - 'grabable': Object can be grabbed and moved with mouse
    * Without 'falling' tag, object is static.
    */
   spawnObject(config) {
@@ -3394,10 +3398,24 @@ var OverlayScene = class {
     this.updateCallbacks.forEach((cb) => cb(data));
   }
 };
+
+// src/tags.ts
+var TAG_FALLING = "falling";
+var TAG_FOLLOW_WINDOW = "follow_window";
+var TAG_GRABABLE = "grabable";
+var TAGS = {
+  FALLING: TAG_FALLING,
+  FOLLOW_WINDOW: TAG_FOLLOW_WINDOW,
+  GRABABLE: TAG_GRABABLE
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BackgroundManager,
   OverlayScene,
+  TAGS,
+  TAG_FALLING,
+  TAG_FOLLOW_WINDOW,
+  TAG_GRABABLE,
   clearFontCache,
   getGlyphData,
   getKerning,