@blorkfield/overlay-core 0.3.0

package/dist/index.js

@@ -0,0 +1,2474 @@
+// src/OverlayScene.ts
+import Matter5 from "matter-js";
+
+// src/engine.ts
+import Matter from "matter-js";
+function createEngine(gravity) {
+  const engine = Matter.Engine.create();
+  engine.gravity.y = gravity;
+  return engine;
+}
+function createRender(engine, canvas, config) {
+  const render = Matter.Render.create({
+    canvas,
+    engine,
+    options: {
+      width: config.bounds.right - config.bounds.left,
+      height: config.bounds.bottom - config.bounds.top,
+      wireframes: config.debug ?? false,
+      background: config.background ?? "transparent"
+    }
+  });
+  return render;
+}
+
+// src/bodies.ts
+import Matter2 from "matter-js";
+
+// src/logger.ts
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var currentLevel = "info";
+function setLogLevel(level) {
+  currentLevel = level;
+}
+function getLogLevel() {
+  return currentLevel;
+}
+function shouldLog(level) {
+  return LOG_LEVELS[level] >= LOG_LEVELS[currentLevel];
+}
+function formatMessage(prefix, message, data) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().split("T")[1].slice(0, -1);
+  const base = `[${timestamp}] [${prefix}] ${message}`;
+  return data !== void 0 ? `${base} ${JSON.stringify(data)}` : base;
+}
+var logger = {
+  debug(prefix, message, data) {
+    if (shouldLog("debug")) {
+      console.debug(formatMessage(prefix, message, data));
+    }
+  },
+  info(prefix, message, data) {
+    if (shouldLog("info")) {
+      console.info(formatMessage(prefix, message, data));
+    }
+  },
+  warn(prefix, message, data) {
+    if (shouldLog("warn")) {
+      console.warn(formatMessage(prefix, message, data));
+    }
+  },
+  error(prefix, message, data) {
+    if (shouldLog("error")) {
+      console.error(formatMessage(prefix, message, data));
+    }
+  }
+};
+
+// src/imageClip.ts
+var LOG_PREFIX = "ImageClip";
+var ALPHA_THRESHOLD = 128;
+var contourCache = /* @__PURE__ */ new Map();
+var CACHE_MAX_SIZE = 100;
+var CACHE_TTL_MS = 5 * 60 * 1e3;
+function loadImage(url) {
+  logger.debug(LOG_PREFIX, `Loading image: ${url}`);
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.crossOrigin = "anonymous";
+    img.onload = () => {
+      logger.debug(LOG_PREFIX, `Image loaded successfully`, { width: img.width, height: img.height });
+      resolve(img);
+    };
+    img.onerror = () => {
+      logger.error(LOG_PREFIX, `Failed to load image: ${url}`);
+      reject(new Error(`Failed to load image: ${url}`));
+    };
+    img.src = url;
+  });
+}
+function getImageAlphaData(img) {
+  const canvas = document.createElement("canvas");
+  canvas.width = img.width;
+  canvas.height = img.height;
+  const ctx = canvas.getContext("2d");
+  ctx.drawImage(img, 0, 0);
+  const imageData = ctx.getImageData(0, 0, img.width, img.height);
+  return { data: imageData.data, width: img.width, height: img.height };
+}
+function getAlpha(data, width, x, y) {
+  if (x < 0 || y < 0 || x >= width) return 0;
+  const idx = (y * width + x) * 4 + 3;
+  return data[idx] ?? 0;
+}
+function isSolid(data, width, x, y) {
+  return getAlpha(data, width, x, y) >= ALPHA_THRESHOLD;
+}
+function extractContour(data, width, height) {
+  logger.debug(LOG_PREFIX, `Extracting contour from image`, { width, height });
+  let startX = -1;
+  let startY = -1;
+  outer: for (let y2 = 0; y2 < height; y2++) {
+    for (let x2 = 0; x2 < width; x2++) {
+      if (isSolid(data, width, x2, y2)) {
+        startX = x2;
+        startY = y2;
+        break outer;
+      }
+    }
+  }
+  if (startX === -1) {
+    logger.warn(LOG_PREFIX, `No solid pixels found in image`);
+    return [];
+  }
+  logger.debug(LOG_PREFIX, `Found starting point`, { startX, startY });
+  const contour = [];
+  let x = startX;
+  let y = startY;
+  let dir = 0;
+  const dx = [1, 0, -1, 0];
+  const dy = [0, 1, 0, -1];
+  do {
+    contour.push({ x, y });
+    for (let i = 0; i < 4; i++) {
+      const newDir = (dir + 3 + i) % 4;
+      const nx = x + dx[newDir];
+      const ny = y + dy[newDir];
+      if (nx >= 0 && nx < width && ny >= 0 && ny < height && isSolid(data, width, nx, ny)) {
+        x = nx;
+        y = ny;
+        dir = newDir;
+        break;
+      }
+    }
+    if (contour.length > width * height) {
+      logger.warn(LOG_PREFIX, `Contour extraction hit safety limit, breaking`);
+      break;
+    }
+  } while (x !== startX || y !== startY);
+  logger.debug(LOG_PREFIX, `Contour extracted`, { pointCount: contour.length });
+  return contour;
+}
+function simplifyContour(points, epsilon) {
+  if (points.length < 3) return points;
+  let maxDist = 0;
+  let maxIdx = 0;
+  const first = points[0];
+  const last = points[points.length - 1];
+  for (let i = 1; i < points.length - 1; i++) {
+    const dist = perpendicularDistance(points[i], first, last);
+    if (dist > maxDist) {
+      maxDist = dist;
+      maxIdx = i;
+    }
+  }
+  if (maxDist > epsilon) {
+    const left = simplifyContour(points.slice(0, maxIdx + 1), epsilon);
+    const right = simplifyContour(points.slice(maxIdx), epsilon);
+    return left.slice(0, -1).concat(right);
+  }
+  return [first, last];
+}
+function perpendicularDistance(point, lineStart, lineEnd) {
+  const dx = lineEnd.x - lineStart.x;
+  const dy = lineEnd.y - lineStart.y;
+  const mag = Math.sqrt(dx * dx + dy * dy);
+  if (mag === 0) {
+    return Math.sqrt((point.x - lineStart.x) ** 2 + (point.y - lineStart.y) ** 2);
+  }
+  const u = ((point.x - lineStart.x) * dx + (point.y - lineStart.y) * dy) / (mag * mag);
+  const closestX = lineStart.x + u * dx;
+  const closestY = lineStart.y + u * dy;
+  return Math.sqrt((point.x - closestX) ** 2 + (point.y - closestY) ** 2);
+}
+function getClipBounds(vertices) {
+  if (vertices.length === 0) {
+    return { minX: 0, minY: 0, maxX: 0, maxY: 0 };
+  }
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (const v of vertices) {
+    minX = Math.min(minX, v.x);
+    minY = Math.min(minY, v.y);
+    maxX = Math.max(maxX, v.x);
+    maxY = Math.max(maxY, v.y);
+  }
+  return { minX, minY, maxX, maxY };
+}
+function normalizeVertices(vertices, targetSize, imageWidth, imageHeight) {
+  if (vertices.length === 0) return [];
+  let centerX;
+  let centerY;
+  let refWidth;
+  let refHeight;
+  if (imageWidth !== void 0 && imageHeight !== void 0) {
+    centerX = imageWidth / 2;
+    centerY = imageHeight / 2;
+    refWidth = imageWidth;
+    refHeight = imageHeight;
+  } else {
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const v of vertices) {
+      minX = Math.min(minX, v.x);
+      minY = Math.min(minY, v.y);
+      maxX = Math.max(maxX, v.x);
+      maxY = Math.max(maxY, v.y);
+    }
+    centerX = (minX + maxX) / 2;
+    centerY = (minY + maxY) / 2;
+    refWidth = maxX - minX;
+    refHeight = maxY - minY;
+  }
+  const scale = targetSize / Math.max(refWidth, refHeight);
+  return vertices.map((v) => ({
+    x: (v.x - centerX) * scale,
+    y: (v.y - centerY) * scale
+  }));
+}
+function scaleVertices(vertices, targetSize) {
+  return vertices.map((v) => ({
+    x: v.x * targetSize,
+    y: v.y * targetSize
+  }));
+}
+function cleanupCache() {
+  const now = Date.now();
+  for (const [key, entry] of contourCache) {
+    if (now - entry.timestamp > CACHE_TTL_MS) {
+      contourCache.delete(key);
+    }
+  }
+  if (contourCache.size > CACHE_MAX_SIZE) {
+    const entries = Array.from(contourCache.entries()).sort((a, b) => a[1].timestamp - b[1].timestamp);
+    const toRemove = entries.slice(0, entries.length - CACHE_MAX_SIZE);
+    for (const [key] of toRemove) {
+      contourCache.delete(key);
+    }
+  }
+}
+async function getVerticesAndDimensionsFromImage(imageUrl, targetSize) {
+  const cached = contourCache.get(imageUrl);
+  if (cached) {
+    logger.debug(LOG_PREFIX, `Cache hit for image`, { imageUrl, targetSize, cachedVertices: cached.vertices.length });
+    cached.timestamp = Date.now();
+    const scale = targetSize / Math.max(cached.imageWidth, cached.imageHeight);
+    const imageCenterX = cached.imageWidth / 2;
+    const imageCenterY = cached.imageHeight / 2;
+    const clipCenterX = (cached.clipBounds.minX + cached.clipBounds.maxX) / 2;
+    const clipCenterY = (cached.clipBounds.minY + cached.clipBounds.maxY) / 2;
+    return {
+      vertices: scaleVertices(cached.vertices, targetSize),
+      imageWidth: cached.imageWidth,
+      imageHeight: cached.imageHeight,
+      clipBounds: cached.clipBounds,
+      clipOffset: {
+        x: (clipCenterX - imageCenterX) * scale,
+        y: (clipCenterY - imageCenterY) * scale
+      }
+    };
+  }
+  logger.info(LOG_PREFIX, `Extracting vertices from image (cache miss)`, { imageUrl, targetSize });
+  try {
+    const img = await loadImage(imageUrl);
+    const { data, width, height } = getImageAlphaData(img);
+    const contour = extractContour(data, width, height);
+    if (contour.length < 3) {
+      logger.warn(LOG_PREFIX, `Contour has insufficient points`, { pointCount: contour.length });
+      const emptyClipBounds = { minX: 0, minY: 0, maxX: width, maxY: height };
+      return {
+        vertices: [],
+        imageWidth: width,
+        imageHeight: height,
+        clipBounds: emptyClipBounds,
+        clipOffset: { x: 0, y: 0 }
+      };
+    }
+    const clipBounds = getClipBounds(contour);
+    const epsilon = Math.max(width, height) / 50;
+    const simplified = simplifyContour(contour, epsilon);
+    logger.debug(LOG_PREFIX, `Simplified contour`, { original: contour.length, simplified: simplified.length, epsilon });
+    if (simplified.length < 3) {
+      logger.warn(LOG_PREFIX, `Simplified contour has insufficient points`, { pointCount: simplified.length });
+      return {
+        vertices: [],
+        imageWidth: width,
+        imageHeight: height,
+        clipBounds,
+        clipOffset: { x: 0, y: 0 }
+      };
+    }
+    const unitVertices = normalizeVertices(simplified, 1, width, height);
+    contourCache.set(imageUrl, {
+      vertices: unitVertices,
+      imageWidth: width,
+      imageHeight: height,
+      clipBounds,
+      timestamp: Date.now()
+    });
+    cleanupCache();
+    logger.info(LOG_PREFIX, `Vertices extracted and cached`, {
+      imageUrl,
+      vertexCount: unitVertices.length,
+      width,
+      height,
+      clipBounds
+    });
+    const scale = targetSize / Math.max(width, height);
+    const imageCenterX = width / 2;
+    const imageCenterY = height / 2;
+    const clipCenterX = (clipBounds.minX + clipBounds.maxX) / 2;
+    const clipCenterY = (clipBounds.minY + clipBounds.maxY) / 2;
+    return {
+      vertices: scaleVertices(unitVertices, targetSize),
+      imageWidth: width,
+      imageHeight: height,
+      clipBounds,
+      clipOffset: {
+        x: (clipCenterX - imageCenterX) * scale,
+        y: (clipCenterY - imageCenterY) * scale
+      }
+    };
+  } catch (error) {
+    logger.error(LOG_PREFIX, `Failed to extract vertices from image`, { error: String(error) });
+    return {
+      vertices: [],
+      imageWidth: 0,
+      imageHeight: 0,
+      clipBounds: { minX: 0, minY: 0, maxX: 0, maxY: 0 },
+      clipOffset: { x: 0, y: 0 }
+    };
+  }
+}
+var tintedImageCache = /* @__PURE__ */ new Map();
+var TINTED_CACHE_MAX_SIZE = 200;
+function parseColor(color) {
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const ctx = canvas.getContext("2d");
+  ctx.fillStyle = color;
+  ctx.fillRect(0, 0, 1, 1);
+  const data = ctx.getImageData(0, 0, 1, 1).data;
+  return { r: data[0], g: data[1], b: data[2] };
+}
+async function tintImage(imageUrl, color) {
+  const cacheKey = `${imageUrl}:${color}`;
+  const cached = tintedImageCache.get(cacheKey);
+  if (cached) {
+    logger.debug(LOG_PREFIX, `Tinted image cache hit`, { imageUrl, color });
+    return cached;
+  }
+  logger.debug(LOG_PREFIX, `Tinting image`, { imageUrl, color });
+  try {
+    const img = await loadImage(imageUrl);
+    const canvas = document.createElement("canvas");
+    canvas.width = img.width;
+    canvas.height = img.height;
+    const ctx = canvas.getContext("2d");
+    ctx.drawImage(img, 0, 0);
+    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+    const data = imageData.data;
+    const rgb = parseColor(color);
+    if (!rgb) {
+      logger.warn(LOG_PREFIX, `Failed to parse color, returning original image`, { color });
+      return imageUrl;
+    }
+    for (let i = 0; i < data.length; i += 4) {
+      const alpha = data[i + 3];
+      if (alpha > 0) {
+        data[i] = rgb.r;
+        data[i + 1] = rgb.g;
+        data[i + 2] = rgb.b;
+      }
+    }
+    ctx.putImageData(imageData, 0, 0);
+    const dataUrl = canvas.toDataURL("image/png");
+    tintedImageCache.set(cacheKey, dataUrl);
+    if (tintedImageCache.size > TINTED_CACHE_MAX_SIZE) {
+      const firstKey = tintedImageCache.keys().next().value;
+      if (firstKey) {
+        tintedImageCache.delete(firstKey);
+      }
+    }
+    logger.debug(LOG_PREFIX, `Image tinted successfully`, { imageUrl, color });
+    return dataUrl;
+  } catch (error) {
+    logger.error(LOG_PREFIX, `Failed to tint image`, { error: String(error) });
+    return imageUrl;
+  }
+}
+
+// src/bodies.ts
+var BOUNDARY_THICKNESS = 50;
+var LOG_PREFIX2 = "Bodies";
+var DEFAULT_RADIUS = 20;
+var SHAPE_SIDES = {
+  triangle: 3,
+  rectangle: 4,
+  pentagon: 5,
+  hexagon: 6,
+  octagon: 8
+};
+function generatePolygonVertices(sides, radius, aspectRatio) {
+  if (sides === 4 && aspectRatio !== void 0 && aspectRatio !== 1) {
+    const width = radius * Math.sqrt(2 * aspectRatio / (1 + aspectRatio));
+    const height = width / aspectRatio;
+    return [
+      { x: -width, y: -height },
+      { x: width, y: -height },
+      { x: width, y: height },
+      { x: -width, y: height }
+    ];
+  }
+  const vertices = [];
+  const angleStep = 2 * Math.PI / sides;
+  const startAngle = -Math.PI / 2;
+  for (let i = 0; i < sides; i++) {
+    const angle = startAngle + i * angleStep;
+    vertices.push({
+      x: radius * Math.cos(angle),
+      y: radius * Math.sin(angle)
+    });
+  }
+  return vertices;
+}
+function getShapeVertices(shape, radius) {
+  if (shape.vertices && shape.vertices.length >= 3) {
+    logger.debug(LOG_PREFIX2, `Using custom vertices`, { count: shape.vertices.length });
+    return shape.vertices;
+  }
+  const sides = shape.sides ?? SHAPE_SIDES[shape.type];
+  if (!sides || sides < 3) {
+    logger.warn(LOG_PREFIX2, `Invalid polygon: need sides >= 3`, { type: shape.type, sides });
+    return null;
+  }
+  logger.debug(LOG_PREFIX2, `Generating polygon`, { type: shape.type, sides, aspectRatio: shape.aspectRatio });
+  return generatePolygonVertices(sides, radius, shape.aspectRatio);
+}
+function createBodyFromVertices(id, x, y, vertices, renderOptions) {
+  const matterVertices = vertices.map((v) => ({ x: v.x, y: v.y }));
+  const body = Matter2.Bodies.fromVertices(x, y, [matterVertices], {
+    restitution: 0.3,
+    friction: 0.1,
+    frictionAir: 0.01,
+    label: `entity:${id}`,
+    render: renderOptions
+  });
+  Matter2.Body.setPosition(body, { x, y });
+  return body;
+}
+function createBoundariesWithFloorConfig(bounds, floorConfig) {
+  const width = bounds.right - bounds.left;
+  const height = bounds.bottom - bounds.top;
+  const options = { isStatic: true, render: { visible: false } };
+  const walls = [
+    // Left wall
+    Matter2.Bodies.rectangle(
+      bounds.left - BOUNDARY_THICKNESS / 2,
+      bounds.top + height / 2,
+      BOUNDARY_THICKNESS,
+      height,
+      { ...options, label: "leftWall" }
+    ),
+    // Right wall
+    Matter2.Bodies.rectangle(
+      bounds.right + BOUNDARY_THICKNESS / 2,
+      bounds.top + height / 2,
+      BOUNDARY_THICKNESS,
+      height,
+      { ...options, label: "rightWall" }
+    )
+  ];
+  const segmentCount = floorConfig?.segments ?? 1;
+  const segmentWidth = width / segmentCount;
+  const floorSegments = [];
+  for (let i = 0; i < segmentCount; i++) {
+    const segmentX = bounds.left + (i + 0.5) * segmentWidth;
+    floorSegments.push(
+      Matter2.Bodies.rectangle(
+        segmentX,
+        bounds.bottom + BOUNDARY_THICKNESS / 2,
+        segmentWidth,
+        BOUNDARY_THICKNESS,
+        { ...options, label: `floor-segment-${i}` }
+      )
+    );
+  }
+  return { walls, floorSegments };
+}
+function createFillRenderOptions(config) {
+  return {
+    fillStyle: config.fillStyle ?? "#ff0000"
+  };
+}
+function createSpriteRenderOptions(config, imageWidth, imageHeight) {
+  const radius = config.radius ?? DEFAULT_RADIUS;
+  const targetSize = radius * 2;
+  const maxDim = Math.max(imageWidth, imageHeight);
+  const spriteScale = targetSize / maxDim;
+  return {
+    sprite: {
+      texture: config.imageUrl,
+      xScale: spriteScale,
+      yScale: spriteScale
+    }
+  };
+}
+function createCircleEntity(id, config) {
+  const radius = config.radius ?? DEFAULT_RADIUS;
+  logger.debug(LOG_PREFIX2, `Creating circle entity`, { id, radius });
+  return Matter2.Bodies.circle(config.x, config.y, radius, {
+    restitution: 0.3,
+    friction: 0.1,
+    frictionAir: 0.01,
+    label: `entity:${id}`,
+    render: createFillRenderOptions(config)
+  });
+}
+function createCircleEntityWithSprite(id, config, imageWidth, imageHeight) {
+  const radius = config.radius ?? DEFAULT_RADIUS;
+  logger.debug(LOG_PREFIX2, `Creating circle entity with sprite`, { id, radius, imageWidth, imageHeight });
+  return Matter2.Bodies.circle(config.x, config.y, radius, {
+    restitution: 0.3,
+    friction: 0.1,
+    frictionAir: 0.01,
+    label: `entity:${id}`,
+    render: createSpriteRenderOptions(config, imageWidth, imageHeight)
+  });
+}
+function createEntity(id, config) {
+  const shape = config.shape;
+  if (!shape || shape.type === "circle") {
+    return createCircleEntity(id, config);
+  }
+  if (config.imageUrl) {
+    logger.warn(LOG_PREFIX2, `Image provided but using sync createEntity - shape won't be extracted. Use createEntityAsync for image shape extraction.`);
+  }
+  const radius = config.radius ?? DEFAULT_RADIUS;
+  const vertices = getShapeVertices(shape, radius);
+  if (!vertices) {
+    logger.warn(LOG_PREFIX2, `Failed to get vertices, falling back to circle`, { type: shape.type });
+    return createCircleEntity(id, config);
+  }
+  logger.info(LOG_PREFIX2, `Creating polygon entity`, { id, type: shape.type, vertices: vertices.length });
+  return createBodyFromVertices(id, config.x, config.y, vertices, createFillRenderOptions(config));
+}
+async function createEntityAsync(id, config) {
+  const shape = config.shape;
+  if (shape?.type === "circle") {
+    logger.info(LOG_PREFIX2, `Creating circle entity (explicit)`, { id });
+    return createCircleEntity(id, config);
+  }
+  if (config.imageUrl) {
+    const radius = config.radius ?? DEFAULT_RADIUS;
+    logger.debug(LOG_PREFIX2, `Attempting to extract shape from image`, { id, imageUrl: config.imageUrl });
+    const { vertices, imageWidth, imageHeight } = await getVerticesAndDimensionsFromImage(config.imageUrl, radius * 2);
+    if (vertices.length >= 3) {
+      logger.debug(LOG_PREFIX2, `Image shape extraction succeeded`, { id, vertices: vertices.length, imageWidth, imageHeight });
+      return createBodyFromVertices(id, config.x, config.y, vertices, createSpriteRenderOptions(config, imageWidth, imageHeight));
+    }
+    logger.warn(LOG_PREFIX2, `Image shape extraction failed, falling back to circle`, { id, verticesFound: vertices.length });
+    return createCircleEntityWithSprite(id, config, imageWidth, imageHeight);
+  }
+  if (shape) {
+    const shapeRadius = config.radius ?? DEFAULT_RADIUS;
+    const vertices = getShapeVertices(shape, shapeRadius);
+    if (vertices) {
+      logger.info(LOG_PREFIX2, `Creating polygon entity`, { id, type: shape.type, vertices: vertices.length });
+      return createBodyFromVertices(id, config.x, config.y, vertices, createFillRenderOptions(config));
+    }
+    logger.warn(LOG_PREFIX2, `Failed to get vertices from shape config, falling back to circle`, { type: shape.type });
+  }
+  logger.info(LOG_PREFIX2, `Creating circle entity (default)`, { id });
+  return createCircleEntity(id, config);
+}
+function createObstacle(id, config, isStatic = true) {
+  const width = config.width ?? 100;
+  const height = config.height ?? 20;
+  return Matter2.Bodies.rectangle(config.x, config.y, width, height, {
+    isStatic,
+    label: `obstacle:${id}`,
+    render: {
+      visible: true,
+      fillStyle: config.fillStyle ?? "#4a4a6a"
+    }
+  });
+}
+async function getImageDimensions(imageUrl) {
+  const img = await loadImage(imageUrl);
+  return { width: img.width, height: img.height };
+}
+async function createBoxObstacleWithInfo(id, config, isStatic = true) {
+  const size = config.size ?? 50;
+  const { vertices, imageWidth, imageHeight, clipBounds, clipOffset } = await getVerticesAndDimensionsFromImage(config.imageUrl, size);
+  const maxDim = Math.max(imageWidth, imageHeight);
+  const spriteScale = size / maxDim;
+  const scaledWidth = imageWidth * spriteScale;
+  const scaledHeight = imageHeight * spriteScale;
+  let body;
+  if (vertices.length >= 3) {
+    const worldVertices = vertices.map((v) => ({
+      x: config.x + v.x,
+      y: config.y + v.y
+    }));
+    body = Matter2.Bodies.fromVertices(config.x, config.y, [worldVertices], {
+      isStatic,
+      label: `obstacle:${id}`,
+      render: {
+        sprite: {
+          texture: config.imageUrl,
+          xScale: spriteScale,
+          yScale: spriteScale
+        }
+      }
+    });
+    const spriteOffsetX = (config.x - body.position.x) / scaledWidth;
+    const spriteOffsetY = (config.y - body.position.y) / scaledHeight;
+    if (body.render.sprite) {
+      body.render.sprite.xOffset = 0.5 + spriteOffsetX;
+      body.render.sprite.yOffset = 0.5 + spriteOffsetY;
+    }
+  } else {
+    body = Matter2.Bodies.rectangle(config.x, config.y, scaledWidth, scaledHeight, {
+      isStatic,
+      label: `obstacle:${id}`,
+      render: {
+        sprite: {
+          texture: config.imageUrl,
+          xScale: spriteScale,
+          yScale: spriteScale
+        }
+      }
+    });
+  }
+  return {
+    body,
+    imageWidth,
+    imageHeight,
+    scaledWidth,
+    scaledHeight,
+    clipBounds,
+    clipOffset
+  };
+}
+async function createObstacleAsync(id, config, isStatic = true) {
+  if (!config.imageUrl) {
+    return createObstacle(id, config, isStatic);
+  }
+  const size = config.size ?? 50;
+  logger.info(LOG_PREFIX2, `Creating image-based obstacle`, { id, imageUrl: config.imageUrl, size });
+  const { vertices, imageWidth, imageHeight } = await getVerticesAndDimensionsFromImage(config.imageUrl, size);
+  if (vertices.length >= 3) {
+    logger.info(LOG_PREFIX2, `Image obstacle shape extraction succeeded`, { id, vertices: vertices.length, imageWidth, imageHeight });
+    const matterVertices = vertices.map((v) => ({ x: v.x, y: v.y }));
+    const maxDim = Math.max(imageWidth, imageHeight);
+    const spriteScale = size / maxDim;
+    const body = Matter2.Bodies.fromVertices(config.x, config.y, [matterVertices], {
+      isStatic,
+      label: `obstacle:${id}`,
+      render: {
+        sprite: {
+          texture: config.imageUrl,
+          xScale: spriteScale,
+          yScale: spriteScale
+        }
+      }
+    });
+    Matter2.Body.setPosition(body, { x: config.x, y: config.y });
+    return body;
+  }
+  logger.warn(LOG_PREFIX2, `Image obstacle shape extraction failed, falling back to rectangle`, { id });
+  return createObstacle(id, config, isStatic);
+}
+
+// src/fontLoader.ts
+import opentype from "opentype.js";
+var LOG_PREFIX3 = "FontLoader";
+var fontCache = /* @__PURE__ */ new Map();
+async function loadFont(fontUrl) {
+  const cached = fontCache.get(fontUrl);
+  if (cached) {
+    logger.debug(LOG_PREFIX3, `Font cache hit`, { fontUrl });
+    return cached;
+  }
+  logger.info(LOG_PREFIX3, `Loading font`, { fontUrl });
+  const font = await opentype.load(fontUrl);
+  const loadedFont = {
+    font,
+    unitsPerEm: font.unitsPerEm,
+    ascender: font.ascender,
+    descender: font.descender
+  };
+  fontCache.set(fontUrl, loadedFont);
+  logger.info(LOG_PREFIX3, `Font loaded`, { fontUrl, unitsPerEm: font.unitsPerEm });
+  return loadedFont;
+}
+function glyphToVertices(glyph, fontSize, unitsPerEm) {
+  const path = glyph.getPath(0, 0, fontSize);
+  const commands = path.commands;
+  if (commands.length === 0) {
+    return [];
+  }
+  const vertices = [];
+  let currentX = 0;
+  let currentY = 0;
+  for (const cmd of commands) {
+    switch (cmd.type) {
+      case "M":
+        currentX = cmd.x;
+        currentY = cmd.y;
+        vertices.push({ x: currentX, y: currentY });
+        break;
+      case "L":
+        currentX = cmd.x;
+        currentY = cmd.y;
+        vertices.push({ x: currentX, y: currentY });
+        break;
+      case "Q":
+        {
+          const steps = 4;
+          for (let t = 1; t <= steps; t++) {
+            const tNorm = t / steps;
+            const x = (1 - tNorm) * (1 - tNorm) * currentX + 2 * (1 - tNorm) * tNorm * cmd.x1 + tNorm * tNorm * cmd.x;
+            const y = (1 - tNorm) * (1 - tNorm) * currentY + 2 * (1 - tNorm) * tNorm * cmd.y1 + tNorm * tNorm * cmd.y;
+            vertices.push({ x, y });
+          }
+          currentX = cmd.x;
+          currentY = cmd.y;
+        }
+        break;
+      case "C":
+        {
+          const steps = 6;
+          for (let t = 1; t <= steps; t++) {
+            const tNorm = t / steps;
+            const mt = 1 - tNorm;
+            const x = mt * mt * mt * currentX + 3 * mt * mt * tNorm * cmd.x1 + 3 * mt * tNorm * tNorm * cmd.x2 + tNorm * tNorm * tNorm * cmd.x;
+            const y = mt * mt * mt * currentY + 3 * mt * mt * tNorm * cmd.y1 + 3 * mt * tNorm * tNorm * cmd.y2 + tNorm * tNorm * tNorm * cmd.y;
+            vertices.push({ x, y });
+          }
+          currentX = cmd.x;
+          currentY = cmd.y;
+        }
+        break;
+      case "Z":
+        break;
+    }
+  }
+  return simplifyVertices(vertices, fontSize / 50);
+}
+function simplifyVertices(vertices, minDistance) {
+  if (vertices.length < 3) return vertices;
+  const result = [vertices[0]];
+  for (let i = 1; i < vertices.length; i++) {
+    const last = result[result.length - 1];
+    const curr = vertices[i];
+    const dist = Math.sqrt((curr.x - last.x) ** 2 + (curr.y - last.y) ** 2);
+    if (dist >= minDistance) {
+      result.push(curr);
+    }
+  }
+  return result;
+}
+function getGlyphData(loadedFont, char, fontSize) {
+  const { font, unitsPerEm } = loadedFont;
+  const glyph = font.charToGlyph(char);
+  if (!glyph) {
+    logger.warn(LOG_PREFIX3, `Glyph not found for character`, { char });
+    return {
+      vertices: [],
+      advanceWidth: fontSize / 2,
+      leftSideBearing: 0,
+      boundingBox: null
+    };
+  }
+  const scale = fontSize / unitsPerEm;
+  const advanceWidth = (glyph.advanceWidth ?? 0) * scale;
+  const leftSideBearing = (glyph.leftSideBearing ?? 0) * scale;
+  const bbox = glyph.getBoundingBox();
+  const boundingBox = bbox ? {
+    x1: bbox.x1 * scale,
+    y1: bbox.y1 * scale,
+    x2: bbox.x2 * scale,
+    y2: bbox.y2 * scale
+  } : null;
+  const vertices = glyphToVertices(glyph, fontSize, unitsPerEm);
+  return {
+    vertices,
+    advanceWidth,
+    leftSideBearing,
+    boundingBox
+  };
+}
+function getKerning(loadedFont, char1, char2, fontSize) {
+  const { font, unitsPerEm } = loadedFont;
+  const glyph1 = font.charToGlyph(char1);
+  const glyph2 = font.charToGlyph(char2);
+  if (!glyph1 || !glyph2) return 0;
+  const kerning = font.getKerningValue(glyph1, glyph2);
+  const scale = fontSize / unitsPerEm;
+  return kerning * scale;
+}
+function measureText(loadedFont, text, fontSize) {
+  let width = 0;
+  const chars = text.split("");
+  for (let i = 0; i < chars.length; i++) {
+    const glyphData = getGlyphData(loadedFont, chars[i], fontSize);
+    width += glyphData.advanceWidth;
+    if (i < chars.length - 1) {
+      width += getKerning(loadedFont, chars[i], chars[i + 1], fontSize);
+    }
+  }
+  return width;
+}
+function clearFontCache() {
+  fontCache.clear();
+  logger.debug(LOG_PREFIX3, `Font cache cleared`);
+}
+
+// src/entity.ts
+import Matter3 from "matter-js";
+var MOUSE_FORCE = 1e-3;
+function applyMouseForce(entity, mouseX, grounded) {
+  if (!grounded) return;
+  const direction = Math.sign(mouseX - entity.position.x);
+  Matter3.Body.applyForce(entity, entity.position, { x: MOUSE_FORCE * direction, y: 0 });
+}
+function wrapHorizontal(entity, bounds) {
+  if (entity.position.x < bounds.left) {
+    Matter3.Body.setPosition(entity, { x: bounds.right, y: entity.position.y });
+  } else if (entity.position.x > bounds.right) {
+    Matter3.Body.setPosition(entity, { x: bounds.left, y: entity.position.y });
+  }
+}
+
+// src/EffectManager.ts
+import Matter4 from "matter-js";
+var EffectManager = class {
+  constructor(bounds, spawnObjectAsync, getBody) {
+    this.effects = /* @__PURE__ */ new Map();
+    this.bounds = bounds;
+    this.spawnObjectAsync = spawnObjectAsync;
+    this.getBody = getBody;
+  }
+  /**
+   * Update bounds when scene resizes
+   */
+  setBounds(bounds) {
+    this.bounds = bounds;
+  }
+  /**
+   * Add or update an effect configuration
+   */
+  setEffect(config) {
+    const existing = this.effects.get(config.id);
+    if (existing) {
+      const wasDisabled = !existing.config.enabled;
+      const nowEnabled = config.enabled;
+      if (wasDisabled && nowEnabled) {
+        existing.lastSpawnTime = Date.now();
+        existing.spawnAccumulator = 0;
+      }
+      existing.config = config;
+      logger.debug("EffectManager", `Updated effect: ${config.id}`, { type: config.type, enabled: config.enabled });
+    } else {
+      this.effects.set(config.id, {
+        config,
+        lastSpawnTime: Date.now(),
+        spawnAccumulator: 0
+      });
+      logger.debug("EffectManager", `Added effect: ${config.id}`, { type: config.type, enabled: config.enabled });
+    }
+  }
+  /**
+   * Remove an effect
+   */
+  removeEffect(id) {
+    this.effects.delete(id);
+    logger.debug("EffectManager", `Removed effect: ${id}`);
+  }
+  /**
+   * Enable or disable an effect
+   */
+  setEffectEnabled(id, enabled) {
+    const state = this.effects.get(id);
+    if (state) {
+      state.config.enabled = enabled;
+      if (enabled) {
+        state.lastSpawnTime = Date.now();
+        state.spawnAccumulator = 0;
+      }
+      logger.debug("EffectManager", `Effect ${id} ${enabled ? "enabled" : "disabled"}`);
+    }
+  }
+  /**
+   * Get current effect configuration
+   */
+  getEffect(id) {
+    return this.effects.get(id)?.config;
+  }
+  /**
+   * Get all effect IDs
+   */
+  getEffectIds() {
+    return Array.from(this.effects.keys());
+  }
+  /**
+   * Check if an effect is enabled
+   */
+  isEffectEnabled(id) {
+    return this.effects.get(id)?.config.enabled ?? false;
+  }
+  /**
+   * Called each frame to update effects and spawn objects
+   */
+  update() {
+    const now = Date.now();
+    for (const state of this.effects.values()) {
+      if (!state.config.enabled) continue;
+      switch (state.config.type) {
+        case "burst":
+          this.updateBurstEffect(state, now);
+          break;
+        case "rain":
+          this.updateRainEffect(state, now);
+          break;
+        case "stream":
+          this.updateStreamEffect(state, now);
+          break;
+      }
+    }
+  }
+  updateBurstEffect(state, now) {
+    const config = state.config;
+    const elapsed = now - state.lastSpawnTime;
+    if (elapsed >= config.burstInterval) {
+      state.lastSpawnTime = now;
+      this.spawnBurst(config);
+    }
+  }
+  updateRainEffect(state, now) {
+    const config = state.config;
+    const elapsed = Math.min(now - state.lastSpawnTime, 100);
+    state.lastSpawnTime = now;
+    const deltaSeconds = elapsed / 1e3;
+    state.spawnAccumulator += config.spawnRate * deltaSeconds;
+    while (state.spawnAccumulator >= 1) {
+      state.spawnAccumulator -= 1;
+      this.spawnRainObject(config);
+    }
+  }
+  async spawnBurst(config) {
+    const { bounds } = this;
+    const originX = config.origin?.x ?? this.randomInRange(bounds.left + 50, bounds.right - 50);
+    const originY = config.origin?.y ?? this.randomInRange(bounds.top + 50, bounds.bottom - 100);
+    logger.debug("EffectManager", `Spawning burst at (${originX.toFixed(0)}, ${originY.toFixed(0)})`, { count: config.burstCount });
+    const spawnData = [];
+    for (let i = 0; i < config.burstCount; i++) {
+      const objectConfig = this.selectObjectConfig(config.objectConfigs);
+      if (!objectConfig) continue;
+      const radius = this.calculateRadius(objectConfig);
+      const tags = [...objectConfig.objectConfig.tags ?? []];
+      if (!tags.includes("falling")) tags.push("falling");
+      const fullConfig = {
+        ...objectConfig.objectConfig,
+        x: originX,
+        y: originY,
+        radius,
+        tags
+      };
+      spawnData.push({
+        config: fullConfig,
+        angle: Math.random() * Math.PI * 2
+      });
+    }
+    const ids = await Promise.all(
+      spawnData.map((data) => this.spawnObjectAsync(data.config))
+    );
+    for (let i = 0; i < ids.length; i++) {
+      const body = this.getBody(ids[i]);
+      if (body) {
+        const angle = spawnData[i].angle;
+        const force = config.burstForce;
+        Matter4.Body.setVelocity(body, {
+          x: Math.cos(angle) * force,
+          y: Math.sin(angle) * force
+        });
+      }
+    }
+  }
+  spawnRainObject(config) {
+    const { bounds } = this;
+    const spawnWidth = config.spawnWidth ?? 1;
+    const totalWidth = bounds.right - bounds.left;
+    const spawnAreaWidth = totalWidth * spawnWidth;
+    const spawnAreaStart = bounds.left + (totalWidth - spawnAreaWidth) / 2;
+    const objectConfig = this.selectObjectConfig(config.objectConfigs);
+    if (!objectConfig) return;
+    const radius = this.calculateRadius(objectConfig);
+    const x = this.randomInRange(spawnAreaStart + radius, spawnAreaStart + spawnAreaWidth - radius);
+    const y = bounds.top - radius;
+    const tags = [...objectConfig.objectConfig.tags ?? []];
+    if (!tags.includes("falling")) tags.push("falling");
+    const fullConfig = {
+      ...objectConfig.objectConfig,
+      x,
+      y,
+      radius,
+      tags
+    };
+    this.spawnObjectAsync(fullConfig);
+  }
+  updateStreamEffect(state, now) {
+    const config = state.config;
+    const elapsed = Math.min(now - state.lastSpawnTime, 100);
+    state.lastSpawnTime = now;
+    const deltaSeconds = elapsed / 1e3;
+    state.spawnAccumulator += config.spawnRate * deltaSeconds;
+    while (state.spawnAccumulator >= 1) {
+      state.spawnAccumulator -= 1;
+      this.spawnStreamObject(config);
+    }
+  }
+  async spawnStreamObject(config) {
+    const objectConfig = this.selectObjectConfig(config.objectConfigs);
+    if (!objectConfig) return;
+    const radius = this.calculateRadius(objectConfig);
+    const tags = [...objectConfig.objectConfig.tags ?? []];
+    if (!tags.includes("falling")) tags.push("falling");
+    const fullConfig = {
+      ...objectConfig.objectConfig,
+      x: config.origin.x,
+      y: config.origin.y,
+      radius,
+      tags
+    };
+    const dirLength = Math.sqrt(config.direction.x ** 2 + config.direction.y ** 2);
+    const normalizedDir = dirLength > 0 ? { x: config.direction.x / dirLength, y: config.direction.y / dirLength } : { x: 0, y: 1 };
+    const baseAngle = Math.atan2(normalizedDir.y, normalizedDir.x);
+    const spreadAngle = (Math.random() * 2 - 1) * config.coneAngle;
+    const finalAngle = baseAngle + spreadAngle;
+    const id = await this.spawnObjectAsync(fullConfig);
+    const body = this.getBody(id);
+    if (body) {
+      Matter4.Body.setVelocity(body, {
+        x: Math.cos(finalAngle) * config.force,
+        y: Math.sin(finalAngle) * config.force
+      });
+    }
+  }
+  /**
+   * Select an object config based on probability weights
+   */
+  selectObjectConfig(configs) {
+    if (configs.length === 0) return null;
+    const totalWeight = configs.reduce((sum, c) => sum + c.probability, 0);
+    if (totalWeight === 0) return configs[0];
+    let random = Math.random() * totalWeight;
+    for (const config of configs) {
+      random -= config.probability;
+      if (random <= 0) return config;
+    }
+    return configs[configs.length - 1];
+  }
+  /**
+   * Calculate radius based on scale range
+   */
+  calculateRadius(config) {
+    const baseRadius = config.baseRadius ?? 20;
+    const scale = this.randomInRange(config.minScale, config.maxScale);
+    return baseRadius * scale;
+  }
+  randomInRange(min, max) {
+    return min + Math.random() * (max - min);
+  }
+};
+
+// src/OverlayScene.ts
+var OverlayScene = class {
+  constructor(canvas, config) {
+    /** All scene objects (unified - no more entity/obstacle distinction) */
+    this.objects = /* @__PURE__ */ new Map();
+    this.boundaries = [];
+    this.updateCallbacks = [];
+    this.mouseX = 0;
+    this.animationFrameId = null;
+    this.mouse = null;
+    this.mouseConstraint = null;
+    this.fonts = [];
+    this.fontsInitialized = false;
+    this.letterDebugInfo = /* @__PURE__ */ new Map();
+    // wordTag -> debug info
+    // Pressure tracking: maps obstacle ID -> Set of dynamic object IDs resting on it
+    this.obstaclePressure = /* @__PURE__ */ new Map();
+    this.previousPressure = /* @__PURE__ */ new Map();
+    this.pressureLogTimer = 0;
+    // Floor segment tracking
+    this.floorSegments = [];
+    this.floorSegmentPressure = /* @__PURE__ */ new Map();
+    // segment index -> object IDs
+    this.collapsedSegments = /* @__PURE__ */ new Set();
+    /** Filter drag events - only allow grabbing objects with 'grabable' tag */
+    this.handleStartDrag = (event) => {
+      const body = event.body;
+      if (!body) return;
+      const entry = this.findObjectByBody(body);
+      if (!entry || !entry.tags.includes("grabable")) {
+        if (this.mouseConstraint) {
+          this.mouseConstraint.constraint.bodyB = null;
+        }
+      }
+    };
+    /** Handle canvas clicks for click-to-fall behavior */
+    this.handleCanvasClick = (event) => {
+      const rect = this.canvas.getBoundingClientRect();
+      const x = event.clientX - rect.left;
+      const y = event.clientY - rect.top;
+      const bodies = Matter5.Query.point(
+        Matter5.Composite.allBodies(this.engine.world),
+        { x, y }
+      );
+      for (const body of bodies) {
+        const entry = this.findObjectByBody(body);
+        if (!entry) continue;
+        if (entry.tags.includes("falling")) continue;
+        if (entry.clicksRemaining === void 0) continue;
+        entry.clicksRemaining--;
+        const name = this.getObstacleDisplayName(entry);
+        logger.debug("OverlayScene", `Click on ${name}: ${entry.clicksRemaining} clicks remaining`);
+        if (entry.clicksRemaining <= 0) {
+          this.collapseObstacle(entry);
+        }
+      }
+    };
+    // ==================== PRIVATE ====================
+    this.loop = () => {
+      this.effectManager.update();
+      this.checkTTLExpiration();
+      this.checkDespawnBelowFloor();
+      this.updatePressure();
+      const mouseX = this.mouse?.position.x ?? this.mouseX;
+      for (const entry of this.objects.values()) {
+        const isDragging = this.mouseConstraint?.body === entry.body;
+        if (!isDragging && entry.tags.includes("follow")) {
+          applyMouseForce(entry.body, mouseX, this.isGrounded(entry.body));
+        }
+        if (this.config.wrapHorizontal && entry.tags.includes("falling")) {
+          wrapHorizontal(entry.body, this.config.bounds);
+        }
+      }
+      if (!this.config.debug) {
+        this.drawTTFGlyphs();
+      }
+      if (this.config.debug) {
+        this.drawDebugOverlays();
+      }
+      this.fireUpdateCallbacks();
+      this.animationFrameId = requestAnimationFrame(this.loop);
+    };
+    this.canvas = canvas;
+    this.config = {
+      gravity: 1,
+      wrapHorizontal: true,
+      debug: false,
+      background: "transparent",
+      ...config
+    };
+    this.engine = createEngine(this.config.gravity);
+    this.render = createRender(this.engine, canvas, this.config);
+    this.runner = Matter5.Runner.create();
+    const boundariesResult = createBoundariesWithFloorConfig(this.config.bounds, this.config.floorConfig);
+    this.boundaries = [...boundariesResult.walls, ...boundariesResult.floorSegments];
+    this.floorSegments = boundariesResult.floorSegments;
+    Matter5.Composite.add(this.engine.world, this.boundaries);
+    this.mouse = Matter5.Mouse.create(canvas);
+    this.mouseConstraint = Matter5.MouseConstraint.create(this.engine, {
+      mouse: this.mouse,
+      constraint: {
+        stiffness: 0.2,
+        render: { visible: false }
+      }
+    });
+    Matter5.Composite.add(this.engine.world, this.mouseConstraint);
+    Matter5.Events.on(this.mouseConstraint, "startdrag", this.handleStartDrag);
+    canvas.addEventListener("click", this.handleCanvasClick);
+    this.render.mouse = this.mouse;
+    this.effectManager = new EffectManager(
+      this.config.bounds,
+      (cfg) => this.spawnObjectAsync(cfg),
+      (id) => this.objects.get(id)?.body ?? null
+    );
+  }
+  static createContainer(parent, options = {}) {
+    const canvas = document.createElement("canvas");
+    let width;
+    let height;
+    if (options.fullscreen !== false && !options.width && !options.height) {
+      width = parent.clientWidth;
+      height = parent.clientHeight;
+      canvas.style.width = "100%";
+      canvas.style.height = "100%";
+    } else {
+      width = options.width ?? 800;
+      height = options.height ?? 600;
+    }
+    canvas.width = width;
+    canvas.height = height;
+    parent.appendChild(canvas);
+    return {
+      canvas,
+      bounds: { top: 0, bottom: height, left: 0, right: width }
+    };
+  }
+  /** Get a display name for an obstacle (letter char or short ID) */
+  getObstacleDisplayName(entry) {
+    const letterTag = entry.tags.find((t) => t.startsWith("letter-") && !t.startsWith("letter-index-"));
+    if (letterTag) return letterTag.replace("letter-", "");
+    if (entry.ttfGlyph) return entry.ttfGlyph.char;
+    return entry.id.slice(0, 4);
+  }
+  /** Update pressure tracking - check which dynamic objects rest on static obstacles */
+  updatePressure() {
+    const obstacles = [];
+    const dynamics = [];
+    for (const entry of this.objects.values()) {
+      if (entry.tags.includes("falling")) {
+        if (Math.abs(entry.body.velocity.y) < 2) {
+          dynamics.push(entry);
+        }
+      } else {
+        obstacles.push(entry);
+      }
+    }
+    const newPressure = /* @__PURE__ */ new Map();
+    for (const obstacle of obstacles) {
+      const resting = /* @__PURE__ */ new Set();
+      const obsBounds = obstacle.body.bounds;
+      for (const dyn of dynamics) {
+        const dynBounds = dyn.body.bounds;
+        const tolerance = 10;
+        const dynBottom = dynBounds.max.y;
+        const obsTop = obsBounds.min.y;
+        const obsBottom = obsBounds.max.y;
+        const verticallyOn = dynBottom >= obsTop - tolerance && dynBottom <= obsBottom;
+        const horizontalOverlap = dynBounds.max.x > obsBounds.min.x && dynBounds.min.x < obsBounds.max.x;
+        if (verticallyOn && horizontalOverlap) {
+          resting.add(dyn.id);
+        }
+      }
+      if (resting.size > 0) {
+        newPressure.set(obstacle.id, resting);
+      }
+    }
+    this.checkPressureThresholds(obstacles, newPressure);
+    this.updateFloorSegmentPressure(dynamics);
+    this.checkFloorSegmentThresholds();
+    this.obstaclePressure = newPressure;
+    this.previousPressure.clear();
+    for (const [id, set] of newPressure) {
+      this.previousPressure.set(id, set.size);
+    }
+    this.pressureLogTimer++;
+    if (this.pressureLogTimer >= 120) {
+      this.pressureLogTimer = 0;
+      this.logPressureSummary();
+    }
+  }
+  /** Update pressure tracking for each floor segment */
+  updateFloorSegmentPressure(dynamics) {
+    this.floorSegmentPressure.clear();
+    const onObstacles = /* @__PURE__ */ new Set();
+    for (const objectIds of this.obstaclePressure.values()) {
+      for (const id of objectIds) {
+        onObstacles.add(id);
+      }
+    }
+    for (let i = 0; i < this.floorSegments.length; i++) {
+      if (this.collapsedSegments.has(i)) continue;
+      const segment = this.floorSegments[i];
+      const segmentBounds = segment.bounds;
+      const resting = /* @__PURE__ */ new Set();
+      for (const dyn of dynamics) {
+        if (onObstacles.has(dyn.id)) continue;
+        const dynBounds = dyn.body.bounds;
+        const horizontalOverlap = dynBounds.max.x > segmentBounds.min.x && dynBounds.min.x < segmentBounds.max.x;
+        if (horizontalOverlap) {
+          resting.add(dyn.id);
+        }
+      }
+      if (resting.size > 0) {
+        this.floorSegmentPressure.set(i, resting);
+      }
+    }
+  }
+  /** Check floor segment thresholds and collapse segments that exceed them */
+  checkFloorSegmentThresholds() {
+    const floorConfig = this.config.floorConfig;
+    const legacyThreshold = this.config.floorThreshold;
+    if (!floorConfig?.threshold && legacyThreshold === void 0) return;
+    for (let i = 0; i < this.floorSegments.length; i++) {
+      if (this.collapsedSegments.has(i)) continue;
+      let threshold;
+      if (floorConfig?.threshold !== void 0) {
+        threshold = Array.isArray(floorConfig.threshold) ? floorConfig.threshold[i] : floorConfig.threshold;
+      } else if (legacyThreshold !== void 0) {
+        threshold = legacyThreshold;
+      }
+      if (threshold === void 0) continue;
+      const objectIds = this.floorSegmentPressure.get(i);
+      const pressure = objectIds ? this.calculateWeightedPressure(objectIds) : 0;
+      if (pressure >= threshold) {
+        this.collapseFloorSegment(i, pressure, threshold);
+      }
+    }
+  }
+  /** Collapse a single floor segment */
+  collapseFloorSegment(index, pressure, threshold) {
+    if (this.collapsedSegments.has(index)) return;
+    this.collapsedSegments.add(index);
+    const segment = this.floorSegments[index];
+    Matter5.Composite.remove(this.engine.world, segment);
+    console.log(`[Pressure] Floor segment ${index} collapsed! (pressure: ${pressure} >= ${threshold})`);
+  }
+  /** Log a summary of pressure on all obstacles, grouped by word */
+  logPressureSummary() {
+    if (this.obstaclePressure.size === 0 && this.floorSegmentPressure.size === 0 && this.collapsedSegments.size === 0) return;
+    const wordPressure = /* @__PURE__ */ new Map();
+    for (const [obstacleId, objectIds] of this.obstaclePressure) {
+      const entry = this.objects.get(obstacleId);
+      if (!entry) continue;
+      const wordTag = entry.tags.find((t) => t.includes("-word-"));
+      const groupKey = wordTag ?? "other";
+      const letter = this.getObstacleDisplayName(entry);
+      const pressure = this.calculateWeightedPressure(objectIds);
+      if (!wordPressure.has(groupKey)) {
+        wordPressure.set(groupKey, []);
+      }
+      wordPressure.get(groupKey).push(`${letter}:${pressure}`);
+    }
+    const parts = [];
+    for (const [wordTag, letters] of wordPressure) {
+      const match = wordTag.match(/-word-(\d+)$/);
+      const wordLabel = match ? `w${match[1]}` : wordTag.slice(0, 8);
+      parts.push(`[${wordLabel}: ${letters.join(" ")}]`);
+    }
+    if (this.floorSegmentPressure.size > 0 || this.collapsedSegments.size > 0) {
+      const floorConfig = this.config.floorConfig;
+      const legacyThreshold = this.config.floorThreshold;
+      let thresholdDisplay = "\u221E";
+      if (floorConfig?.threshold !== void 0 && !Array.isArray(floorConfig.threshold)) {
+        thresholdDisplay = floorConfig.threshold;
+      } else if (legacyThreshold !== void 0) {
+        thresholdDisplay = legacyThreshold;
+      }
+      const segmentParts = [];
+      for (let i = 0; i < this.floorSegments.length; i++) {
+        if (this.collapsedSegments.has(i)) {
+          segmentParts.push(`s${i}=X`);
+          continue;
+        }
+        const objectIds = this.floorSegmentPressure.get(i);
+        const pressure = objectIds ? this.calculateWeightedPressure(objectIds) : 0;
+        if (pressure > 0) {
+          segmentParts.push(`s${i}=${pressure}`);
+        }
+      }
+      if (segmentParts.length > 0) {
+        parts.push(`[floor(t=${thresholdDisplay}): ${segmentParts.join(" ")}]`);
+      }
+    }
+    if (parts.length > 0) {
+      console.log("[Pressure]", parts.join(" "));
+    }
+  }
+  /** Calculate weighted pressure from a set of object IDs */
+  calculateWeightedPressure(objectIds) {
+    let total = 0;
+    for (const id of objectIds) {
+      const entry = this.objects.get(id);
+      if (entry) {
+        total += entry.weight;
+      }
+    }
+    return total;
+  }
+  /** Check pressure thresholds and collapse obstacles that exceed them */
+  checkPressureThresholds(obstacles, pressure) {
+    const wordPressure = /* @__PURE__ */ new Map();
+    const wordObstacles = /* @__PURE__ */ new Map();
+    for (const obstacle of obstacles) {
+      if (obstacle.pressureThreshold === void 0) continue;
+      const objectsOnObstacle = pressure.get(obstacle.id);
+      const obstaclePressure = objectsOnObstacle ? this.calculateWeightedPressure(objectsOnObstacle) : 0;
+      if (obstacle.wordCollapseTag) {
+        const currentTotal = wordPressure.get(obstacle.wordCollapseTag) ?? 0;
+        wordPressure.set(obstacle.wordCollapseTag, currentTotal + obstaclePressure);
+        if (!wordObstacles.has(obstacle.wordCollapseTag)) {
+          wordObstacles.set(obstacle.wordCollapseTag, []);
+        }
+        wordObstacles.get(obstacle.wordCollapseTag).push(obstacle);
+      } else {
+        if (obstaclePressure >= obstacle.pressureThreshold) {
+          this.collapseObstacle(obstacle);
+        }
+      }
+    }
+    for (const [wordTag, total] of wordPressure) {
+      const wordObs = wordObstacles.get(wordTag);
+      if (!wordObs || wordObs.length === 0) continue;
+      const threshold = wordObs[0].pressureThreshold;
+      if (threshold !== void 0 && total >= threshold) {
+        for (const obs of wordObs) {
+          this.collapseObstacle(obs);
+        }
+        console.log(`[Pressure] Word collapsed! ${wordTag} (total: ${total} >= ${threshold})`);
+      }
+    }
+  }
+  /** Convert a static obstacle to dynamic (make it fall) */
+  collapseObstacle(entry) {
+    if (entry.tags.includes("falling")) return;
+    const name = this.getObstacleDisplayName(entry);
+    console.log(`[Pressure] Collapsed: ${name}`);
+    if (entry.shadow && entry.originalPosition) {
+      this.createShadow(entry);
+    }
+    entry.tags.push("falling");
+    Matter5.Body.setStatic(entry.body, false);
+    entry.pressureThreshold = void 0;
+    entry.wordCollapseTag = void 0;
+  }
+  /** Create a static shadow copy of an obstacle at its original position */
+  async createShadow(entry) {
+    if (!entry.originalPosition) return;
+    const opacity = entry.shadow?.opacity ?? 0.3;
+    const shadowId = `shadow-${entry.id}`;
+    if (entry.ttfGlyph) {
+      const body = Matter5.Bodies.circle(entry.originalPosition.x, entry.originalPosition.y, 1, {
+        isStatic: true,
+        isSensor: true,
+        // Don't collide
+        label: `shadow:${shadowId}`,
+        render: { visible: false }
+      });
+      const shadowEntry2 = {
+        id: shadowId,
+        body,
+        tags: ["shadow"],
+        spawnTime: performance.now(),
+        weight: 0,
+        ttfGlyph: {
+          ...entry.ttfGlyph,
+          fillColor: this.applyOpacityToColor(entry.ttfGlyph.fillColor, opacity)
+        }
+      };
+      this.objects.set(shadowId, shadowEntry2);
+      Matter5.Composite.add(this.engine.world, body);
+      return;
+    }
+    if (!entry.imageUrl) return;
+    const result = await createBoxObstacleWithInfo(shadowId, {
+      x: entry.originalPosition.x,
+      y: entry.originalPosition.y,
+      imageUrl: entry.imageUrl,
+      size: entry.imageSize ?? 50,
+      tags: ["shadow"]
+    }, true);
+    result.body.isSensor = true;
+    if (result.body.render.sprite) {
+      result.body.render.opacity = opacity;
+    }
+    const shadowEntry = {
+      id: shadowId,
+      body: result.body,
+      tags: ["shadow"],
+      spawnTime: performance.now(),
+      weight: 0
+      // Shadows don't contribute to pressure
+    };
+    this.objects.set(shadowId, shadowEntry);
+    Matter5.Composite.add(this.engine.world, result.body);
+  }
+  /** Apply opacity to a CSS color string */
+  applyOpacityToColor(color, opacity) {
+    if (color.startsWith("#")) {
+      const hex = color.slice(1);
+      let r, g, b;
+      if (hex.length === 3) {
+        r = parseInt(hex[0] + hex[0], 16);
+        g = parseInt(hex[1] + hex[1], 16);
+        b = parseInt(hex[2] + hex[2], 16);
+      } else {
+        r = parseInt(hex.slice(0, 2), 16);
+        g = parseInt(hex.slice(2, 4), 16);
+        b = parseInt(hex.slice(4, 6), 16);
+      }
+      return `rgba(${r}, ${g}, ${b}, ${opacity})`;
+    }
+    if (color.startsWith("rgb")) {
+      const match = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
+      if (match) {
+        return `rgba(${match[1]}, ${match[2]}, ${match[3]}, ${opacity})`;
+      }
+    }
+    return color;
+  }
+  /** Find an object entry by its Matter.js body (handles compound body parts) */
+  findObjectByBody(body) {
+    const rootBody = body.parent ?? body;
+    for (const entry of this.objects.values()) {
+      if (entry.body === body || entry.body === rootBody) {
+        return entry;
+      }
+    }
+    return null;
+  }
+  /** Check if a body is grounded (low vertical velocity indicates resting on something) */
+  isGrounded(body) {
+    return Math.abs(body.velocity.y) < 0.5;
+  }
+  start() {
+    Matter5.Render.run(this.render);
+    Matter5.Runner.run(this.runner, this.engine);
+    this.loop();
+  }
+  stop() {
+    if (this.animationFrameId !== null) {
+      cancelAnimationFrame(this.animationFrameId);
+      this.animationFrameId = null;
+    }
+    Matter5.Render.stop(this.render);
+    Matter5.Runner.stop(this.runner);
+  }
+  destroy() {
+    this.stop();
+    if (this.mouseConstraint) {
+      Matter5.Events.off(this.mouseConstraint, "startdrag", this.handleStartDrag);
+    }
+    this.canvas.removeEventListener("click", this.handleCanvasClick);
+    Matter5.Engine.clear(this.engine);
+    this.objects.clear();
+    this.obstaclePressure.clear();
+    this.previousPressure.clear();
+    this.pressureLogTimer = 0;
+    this.floorSegmentPressure.clear();
+    this.collapsedSegments.clear();
+    this.updateCallbacks = [];
+  }
+  setDebug(enabled) {
+    this.config.debug = enabled;
+    this.render.options.wireframes = enabled;
+    for (const [, entry] of this.objects) {
+      if (entry.ttfGlyph && entry.body.render) {
+        entry.body.render.visible = enabled;
+      }
+    }
+  }
+  resize(width, height) {
+    this.canvas.width = width;
+    this.canvas.height = height;
+    this.config.bounds = { top: 0, bottom: height, left: 0, right: width };
+    Matter5.Composite.remove(this.engine.world, this.boundaries);
+    const boundariesResult = createBoundariesWithFloorConfig(this.config.bounds, this.config.floorConfig);
+    this.boundaries = [...boundariesResult.walls, ...boundariesResult.floorSegments];
+    this.floorSegments = boundariesResult.floorSegments;
+    this.collapsedSegments.clear();
+    this.floorSegmentPressure.clear();
+    Matter5.Composite.add(this.engine.world, this.boundaries);
+    this.render.options.width = width;
+    this.render.options.height = height;
+    this.render.canvas.width = width;
+    this.render.canvas.height = height;
+    this.effectManager.setBounds(this.config.bounds);
+  }
+  // ==================== OBJECT METHODS ====================
+  /**
+   * 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
+   * Without 'falling' tag, object is static.
+   */
+  spawnObject(config) {
+    const id = crypto.randomUUID();
+    const tags = config.tags ?? [];
+    const isStatic = !tags.includes("falling");
+    logger.debug("OverlayScene", `Spawning object`, {
+      id,
+      tags,
+      isStatic,
+      shape: config.shape?.type ?? (config.radius ? "circle" : "rectangle"),
+      ttl: config.ttl
+    });
+    let body;
+    if (config.radius) {
+      body = createEntity(id, config);
+      if (isStatic) {
+        Matter5.Body.setStatic(body, true);
+      }
+    } else {
+      body = createObstacle(id, config, isStatic);
+    }
+    const entry = {
+      id,
+      body,
+      tags,
+      spawnTime: performance.now(),
+      ttl: config.ttl,
+      despawnEffect: config.despawnEffect,
+      weight: config.weight ?? 1
+    };
+    this.objects.set(id, entry);
+    Matter5.Composite.add(this.engine.world, body);
+    return id;
+  }
+  /**
+   * Spawn an object asynchronously. Required for image-based shapes that need
+   * shape extraction from image alpha channel.
+   */
+  async spawnObjectAsync(config) {
+    const id = crypto.randomUUID();
+    const tags = config.tags ?? [];
+    const isStatic = !tags.includes("falling");
+    logger.debug("OverlayScene", `Spawning object async`, {
+      id,
+      tags,
+      isStatic,
+      shape: config.shape?.type ?? (config.radius ? "circle" : "rectangle"),
+      ttl: config.ttl
+    });
+    let body;
+    if (config.radius) {
+      body = await createEntityAsync(id, config);
+      if (isStatic) {
+        Matter5.Body.setStatic(body, true);
+      }
+    } else {
+      body = await createObstacleAsync(id, config, isStatic);
+    }
+    const entry = {
+      id,
+      body,
+      tags,
+      spawnTime: performance.now(),
+      ttl: config.ttl,
+      despawnEffect: config.despawnEffect,
+      weight: config.weight ?? 1
+    };
+    this.objects.set(id, entry);
+    Matter5.Composite.add(this.engine.world, body);
+    return id;
+  }
+  /**
+   * Add 'falling' tag to an object, making it dynamic (affected by gravity).
+   * Also adds 'grabable' tag so released objects can be dragged.
+   * This is the tag-based replacement for releaseObstacle().
+   */
+  addFallingTag(id) {
+    const entry = this.objects.get(id);
+    if (!entry) return;
+    if (!entry.tags.includes("falling")) {
+      entry.tags.push("falling");
+      Matter5.Body.setStatic(entry.body, false);
+    }
+    if (!entry.tags.includes("grabable")) {
+      entry.tags.push("grabable");
+    }
+  }
+  /**
+   * Add a tag to an object.
+   */
+  addTag(id, tag) {
+    const entry = this.objects.get(id);
+    if (!entry) return;
+    if (!entry.tags.includes(tag)) {
+      entry.tags.push(tag);
+      if (tag === "falling") {
+        Matter5.Body.setStatic(entry.body, false);
+      }
+    }
+  }
+  /**
+   * Remove a tag from an object.
+   */
+  removeTag(id, tag) {
+    const entry = this.objects.get(id);
+    if (!entry) return;
+    const index = entry.tags.indexOf(tag);
+    if (index !== -1) {
+      entry.tags.splice(index, 1);
+      if (tag === "falling") {
+        Matter5.Body.setStatic(entry.body, true);
+      }
+    }
+  }
+  /**
+   * Release an object (add 'falling' tag to make it dynamic).
+   * Convenience method - equivalent to addFallingTag().
+   */
+  releaseObject(id) {
+    this.addFallingTag(id);
+  }
+  /**
+   * Release multiple objects by their IDs.
+   */
+  releaseObjects(ids) {
+    for (const id of ids) {
+      this.releaseObject(id);
+    }
+  }
+  /**
+   * Release all static objects (add 'falling' and 'grabable' tags).
+   */
+  releaseAllObjects() {
+    for (const [id] of this.objects) {
+      this.addFallingTag(id);
+    }
+  }
+  /**
+   * Release objects by tag (add 'falling' and 'grabable' tags to matching objects).
+   */
+  releaseObjectsByTag(tag) {
+    for (const [id, entry] of this.objects) {
+      if (entry.tags.includes(tag)) {
+        this.addFallingTag(id);
+      }
+    }
+  }
+  removeObject(id) {
+    const entry = this.objects.get(id);
+    if (!entry) return;
+    Matter5.Composite.remove(this.engine.world, entry.body);
+    this.objects.delete(id);
+  }
+  removeObjects(ids) {
+    for (const id of ids) {
+      this.removeObject(id);
+    }
+  }
+  removeAllObjects() {
+    for (const entry of this.objects.values()) {
+      Matter5.Composite.remove(this.engine.world, entry.body);
+    }
+    this.objects.clear();
+  }
+  removeObjectsByTag(tag) {
+    const toRemove = [];
+    for (const [id, entry] of this.objects) {
+      if (entry.tags.includes(tag)) {
+        Matter5.Composite.remove(this.engine.world, entry.body);
+        toRemove.push(id);
+      }
+    }
+    toRemove.forEach((id) => this.objects.delete(id));
+    this.letterDebugInfo.delete(tag);
+  }
+  getObjectIds() {
+    return Array.from(this.objects.keys());
+  }
+  getObjectIdsByTag(tag) {
+    const ids = [];
+    for (const [id, entry] of this.objects) {
+      if (entry.tags.includes(tag)) {
+        ids.push(id);
+      }
+    }
+    return ids;
+  }
+  /**
+   * Get all unique tags currently in use by objects in the scene.
+   */
+  getAllTags() {
+    const tagsSet = /* @__PURE__ */ new Set();
+    for (const entry of this.objects.values()) {
+      for (const tag of entry.tags) {
+        tagsSet.add(tag);
+      }
+    }
+    return Array.from(tagsSet).sort();
+  }
+  setMousePosition(x, _y) {
+    this.mouseX = x;
+  }
+  // ==================== PRESSURE TRACKING METHODS ====================
+  /**
+   * Get the current pressure (number of objects resting) on an obstacle.
+   * @param obstacleId - The ID of the obstacle
+   * @returns Number of objects currently resting on the obstacle
+   */
+  getPressure(obstacleId) {
+    return this.obstaclePressure.get(obstacleId)?.size ?? 0;
+  }
+  /**
+   * Get the IDs of all objects currently resting on an obstacle.
+   * @param obstacleId - The ID of the obstacle
+   * @returns Array of object IDs resting on the obstacle
+   */
+  getObjectsRestingOn(obstacleId) {
+    const set = this.obstaclePressure.get(obstacleId);
+    return set ? Array.from(set) : [];
+  }
+  /**
+   * Get all obstacles that have pressure (at least one object resting on them).
+   * @returns Map of obstacle ID -> pressure count
+   */
+  getAllPressure() {
+    const result = /* @__PURE__ */ new Map();
+    for (const [id, set] of this.obstaclePressure) {
+      if (set.size > 0) {
+        result.set(id, set.size);
+      }
+    }
+    return result;
+  }
+  /**
+   * Get pressure summary for all obstacles with their display names (letters).
+   * Useful for debugging and visualization.
+   * @returns Array of { id, name, pressure } objects
+   */
+  getPressureSummary() {
+    const summary = [];
+    for (const [id, set] of this.obstaclePressure) {
+      if (set.size > 0) {
+        const entry = this.objects.get(id);
+        summary.push({
+          id,
+          name: entry ? this.getObstacleDisplayName(entry) : id.slice(0, 4),
+          pressure: set.size
+        });
+      }
+    }
+    return summary;
+  }
+  // ==================== FONT MANAGEMENT METHODS ====================
+  /**
+   * Initialize fonts by loading the font manifest.
+   * Should be called before using text obstacles if you want automatic font detection.
+   * @param fontsBasePath Base URL path for fonts directory (default: '/fonts/')
+   */
+  async initializeFonts(fontsBasePath = "/fonts/") {
+    if (this.fontsInitialized) {
+      return;
+    }
+    try {
+      const manifestUrl = `${fontsBasePath}fonts.json`;
+      const response = await fetch(manifestUrl);
+      if (!response.ok) {
+        logger.warn("OverlayScene", `Failed to load fonts manifest from ${manifestUrl}: ${response.status}`);
+        this.fonts = [];
+        this.fontsInitialized = true;
+        return;
+      }
+      const manifest = await response.json();
+      this.fonts = manifest.fonts || [];
+      for (const font of this.fonts) {
+        if (font.type === "ttf" && font.fontUrl) {
+          try {
+            const fontFace = new FontFace(font.name, `url(${font.fontUrl})`);
+            await fontFace.load();
+            document.fonts.add(fontFace);
+            logger.debug("OverlayScene", `Loaded TTF font: ${font.name}`);
+          } catch (err) {
+            logger.warn("OverlayScene", `Failed to load TTF font ${font.name}: ${err}`);
+          }
+        }
+      }
+      this.fontsInitialized = true;
+      logger.info("OverlayScene", `Loaded ${this.fonts.length} fonts`, { fonts: this.fonts.map((f) => f.name) });
+    } catch (error) {
+      logger.warn("OverlayScene", `Error loading fonts manifest: ${error}`);
+      this.fonts = [];
+      this.fontsInitialized = true;
+    }
+  }
+  /**
+   * Get list of available fonts.
+   * Returns empty array if fonts have not been initialized.
+   */
+  getAvailableFonts() {
+    return [...this.fonts];
+  }
+  /**
+   * Get font by index. Returns undefined if index is out of bounds.
+   * @param index Font index (0-based)
+   */
+  getFontByIndex(index) {
+    return this.fonts[index];
+  }
+  /**
+   * Get font by name. Returns undefined if font not found.
+   * @param name Font name to find
+   */
+  getFontByName(name) {
+    return this.fonts.find((f) => f.name === name);
+  }
+  /**
+   * Get the default font (first available font).
+   * Returns undefined if no fonts are available.
+   */
+  getDefaultFont() {
+    return this.fonts[0];
+  }
+  /**
+   * Check if fonts have been initialized.
+   */
+  areFontsInitialized() {
+    return this.fontsInitialized;
+  }
+  // ==================== TEXT OBSTACLE METHODS ====================
+  /**
+   * Create text obstacles from a string. Each character becomes an individual obstacle
+   * with shape extracted from the corresponding letter PNG image.
+   * Supported characters: A-Z, a-z, 0-9 (spaces handled, unsupported chars skipped)
+   * Case is preserved: uses lowercase PNG if available, falls back to uppercase (and vice versa).
+   * Supports multiline text with \n characters.
+   *
+   * Letter positioning is based on original PNG dimensions:
+   * - Each letter's PNG width controls its horizontal spacing
+   * - The clipped shape is positioned correctly within the original bounds
+   * - This allows fine control of letter spacing via PNG canvas size
+   */
+  async addTextObstacles(config) {
+    const text = config.text.replace(/\\n/g, "\n");
+    const letterSize = config.letterSize;
+    const lineHeight = config.lineHeight ?? letterSize * 1.2;
+    const fontsBasePath = config.fontsBasePath ?? "/fonts/";
+    const fontName = config.fontName ?? this.getDefaultFont()?.name ?? "handwritten";
+    const basePath = `${fontsBasePath}${fontName}/`;
+    const stringTag = config.stringTag ?? `str-${crypto.randomUUID().slice(0, 8)}`;
+    const baseTags = config.tags ?? [];
+    const isStatic = !baseTags.includes("falling");
+    const letterColor = config.letterColor;
+    const letterIds = [];
+    const letterMap = /* @__PURE__ */ new Map();
+    const debugInfo = [];
+    const wordTagsSet = /* @__PURE__ */ new Set();
+    let currentWordIndex = 0;
+    let inWord = false;
+    const lines = text.split("\n");
+    const uniqueChars = /* @__PURE__ */ new Set();
+    for (const line of lines) {
+      for (const char of line) {
+        if (/^[A-Za-z0-9]$/.test(char)) {
+          uniqueChars.add(char);
+        }
+      }
+    }
+    const charDimensions = /* @__PURE__ */ new Map();
+    const charFileNames = /* @__PURE__ */ new Map();
+    await Promise.all(
+      Array.from(uniqueChars).map(async (char) => {
+        const imageUrl = `${basePath}${char}.png`;
+        try {
+          const dims = await getImageDimensions(imageUrl);
+          charDimensions.set(char, dims);
+          charFileNames.set(char, char);
+        } catch {
+          if (/^[A-Za-z]$/.test(char)) {
+            const fallbackChar = char === char.toLowerCase() ? char.toUpperCase() : char.toLowerCase();
+            const fallbackUrl = `${basePath}${fallbackChar}.png`;
+            try {
+              const dims = await getImageDimensions(fallbackUrl);
+              charDimensions.set(char, dims);
+              charFileNames.set(char, fallbackChar);
+              logger.debug("OverlayScene", `Using fallback ${fallbackChar} for ${char}`);
+            } catch (fallbackError) {
+              logger.warn("OverlayScene", `Failed to load char ${char} (tried ${fallbackChar} too)`, { error: String(fallbackError) });
+              charDimensions.set(char, { width: 100, height: 100 });
+              charFileNames.set(char, char);
+            }
+          } else {
+            logger.warn("OverlayScene", `Failed to load dimensions for char ${char}`);
+            charDimensions.set(char, { width: 100, height: 100 });
+            charFileNames.set(char, char);
+          }
+        }
+      })
+    );
+    let maxDimension = 0;
+    for (const dims of charDimensions.values()) {
+      maxDimension = Math.max(maxDimension, dims.width, dims.height);
+    }
+    if (maxDimension === 0) maxDimension = 100;
+    let currentY = config.y;
+    let globalCharIndex = 0;
+    for (const line of lines) {
+      const chars = line.split("");
+      let currentX = config.x;
+      if (inWord) {
+        currentWordIndex++;
+        inWord = false;
+      }
+      for (let i = 0; i < chars.length; i++) {
+        const char = chars[i];
+        if (char === " ") {
+          currentX += 20;
+          globalCharIndex++;
+          if (inWord) {
+            currentWordIndex++;
+            inWord = false;
+          }
+          continue;
+        }
+        if (!/^[A-Za-z0-9]$/.test(char)) {
+          globalCharIndex++;
+          continue;
+        }
+        inWord = true;
+        const wordTag = `${stringTag}-word-${currentWordIndex}`;
+        wordTagsSet.add(wordTag);
+        const dims = charDimensions.get(char);
+        const scale = letterSize / Math.max(dims.width, dims.height);
+        const scaledWidth = dims.width * scale;
+        const scaledHeight = dims.height * scale;
+        const boxX = currentX;
+        const boxY = currentY - scaledHeight / 2;
+        const centerX = currentX + scaledWidth / 2;
+        const centerY = currentY;
+        const resolvedChar = charFileNames.get(char) ?? char;
+        const originalImageUrl = `${basePath}${resolvedChar}.png`;
+        const imageUrl = letterColor ? await tintImage(originalImageUrl, letterColor) : originalImageUrl;
+        const tags = [...config.tags ?? [], stringTag, wordTag, `letter-${char}`, `letter-index-${globalCharIndex}`];
+        const id = crypto.randomUUID();
+        const objectConfig = {
+          x: centerX,
+          y: centerY,
+          imageUrl,
+          size: letterSize,
+          tags,
+          ttl: config.ttl
+        };
+        const result = await createBoxObstacleWithInfo(id, objectConfig, isStatic);
+        let pressureThreshold;
+        let wordCollapseTag;
+        if (config.pressureThreshold) {
+          const pt = config.pressureThreshold;
+          if (Array.isArray(pt.value)) {
+            pressureThreshold = pt.value[letterIds.length];
+          } else {
+            pressureThreshold = pt.value;
+            if (pt.wordCollapse) {
+              wordCollapseTag = wordTag;
+            }
+          }
+        }
+        let weight = 1;
+        if (config.weight) {
+          if (Array.isArray(config.weight.value)) {
+            weight = config.weight.value[letterIds.length] ?? 1;
+          } else {
+            weight = config.weight.value;
+          }
+        }
+        const shadow = config.shadow ? { opacity: config.shadow.opacity ?? 0.3 } : void 0;
+        const clicksRemaining = config.clickToFall?.clicks;
+        const entry = {
+          id,
+          body: result.body,
+          tags,
+          spawnTime: performance.now(),
+          ttl: config.ttl,
+          pressureThreshold,
+          wordCollapseTag,
+          weight,
+          shadow,
+          originalPosition: shadow || clicksRemaining !== void 0 ? { x: centerX, y: centerY } : void 0,
+          imageUrl: shadow || clicksRemaining !== void 0 ? imageUrl : void 0,
+          imageSize: shadow || clicksRemaining !== void 0 ? letterSize : void 0,
+          clicksRemaining
+        };
+        this.objects.set(id, entry);
+        Matter5.Composite.add(this.engine.world, result.body);
+        letterIds.push(id);
+        letterMap.set(`${char}-${globalCharIndex}`, id);
+        debugInfo.push({
+          char,
+          id,
+          originalWidth: dims.width,
+          originalHeight: dims.height,
+          scaledWidth,
+          scaledHeight,
+          boxX,
+          boxY,
+          centerX,
+          centerY
+        });
+        const extraSpacing = config.letterSpacing !== void 0 ? config.letterSpacing - scaledWidth : 0;
+        currentX += scaledWidth + Math.max(0, extraSpacing);
+        globalCharIndex++;
+      }
+      currentY += lineHeight;
+    }
+    this.letterDebugInfo.set(stringTag, debugInfo);
+    const wordTags = Array.from(wordTagsSet);
+    logger.info("OverlayScene", `Created text obstacles`, {
+      text: text.replace(/\n/g, "\\n"),
+      fontName,
+      letterCount: letterIds.length,
+      stringTag,
+      wordTags,
+      letterColor,
+      lineCount: lines.length
+    });
+    return {
+      letterIds,
+      stringTag,
+      wordTags,
+      letterMap,
+      letterDebugInfo: debugInfo
+    };
+  }
+  /**
+   * Spawn falling text objects from a string.
+   * Same as addTextObstacles but with 'falling' tag (objects fall with gravity).
+   */
+  async spawnFallingTextObstacles(config) {
+    const tags = [...config.tags ?? []];
+    if (!tags.includes("falling")) tags.push("falling");
+    return this.addTextObstacles({ ...config, tags });
+  }
+  /**
+   * Release all letters in a word (add 'falling' tag so they fall).
+   * @param wordTag - The word tag returned from addTextObstacles
+   */
+  releaseTextObstacles(wordTag) {
+    this.releaseObjectsByTag(wordTag);
+  }
+  /**
+   * Release letters one by one with a delay between each.
+   * @param wordTag - The word tag returned from addTextObstacles
+   * @param delayMs - Delay between releasing each letter (default: 100ms)
+   * @param reverse - If true, release from end to start (default: false)
+   */
+  async releaseTextObstaclesSequentially(wordTag, delayMs = 100, reverse = false) {
+    const ids = this.getObjectIdsByTag(wordTag);
+    if (reverse) ids.reverse();
+    for (const id of ids) {
+      this.releaseObject(id);
+      if (delayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+  }
+  /**
+   * Get letter debug info for a word.
+   * Returns the debug info array for the given word tag, or undefined if not found.
+   * Debug info includes original dimension boxes for each letter.
+   */
+  getLetterDebugInfo(wordTag) {
+    return this.letterDebugInfo.get(wordTag);
+  }
+  /**
+   * Get all stored letter debug info (all words).
+   * Returns a map of wordTag -> debug info array.
+   */
+  getAllLetterDebugInfo() {
+    return new Map(this.letterDebugInfo);
+  }
+  // ==================== TTF FONT TEXT METHODS ====================
+  /**
+   * Create text obstacles from a TTF/OTF font file.
+   * Uses proper font metrics for spacing, kerning, and glyph outlines for collision.
+   * Supports multiline text with \n characters.
+   */
+  async addTTFTextObstacles(config) {
+    const { x, y, fontSize, fontUrl } = config;
+    const text = config.text.replace(/\\n/g, "\n");
+    const stringTag = config.stringTag ?? `str-${crypto.randomUUID().slice(0, 8)}`;
+    const baseTags = config.tags ?? [];
+    const isStatic = !baseTags.includes("falling");
+    const fillColor = config.fillColor ?? "#ffffff";
+    const lineHeight = config.lineHeight ?? fontSize * 1.2;
+    const letterIds = [];
+    const letterMap = /* @__PURE__ */ new Map();
+    const wordTagsSet = /* @__PURE__ */ new Set();
+    let currentWordIndex = 0;
+    let inWord = false;
+    const loadedFont = await loadFont(fontUrl);
+    const fontInfo = this.fonts.find((f) => f.fontUrl === fontUrl);
+    const fontFamily = fontInfo?.name ?? "sans-serif";
+    const lines = text.split("\n");
+    let currentY = y;
+    let globalCharIndex = 0;
+    for (const line of lines) {
+      let currentX = x;
+      if (inWord) {
+        currentWordIndex++;
+        inWord = false;
+      }
+      const chars = line.split("");
+      for (let i = 0; i < chars.length; i++) {
+        const char = chars[i];
+        const glyphData = getGlyphData(loadedFont, char, fontSize);
+        if (glyphData.vertices.length < 3) {
+          currentX += glyphData.advanceWidth;
+          if (i < chars.length - 1) {
+            currentX += getKerning(loadedFont, char, chars[i + 1], fontSize);
+          }
+          globalCharIndex++;
+          if (char === " " && inWord) {
+            currentWordIndex++;
+            inWord = false;
+          }
+          continue;
+        }
+        inWord = true;
+        const wordTag = `${stringTag}-word-${currentWordIndex}`;
+        wordTagsSet.add(wordTag);
+        const id = crypto.randomUUID();
+        const tags = [...config.tags ?? [], stringTag, wordTag, `letter-${char}`, `letter-index-${globalCharIndex}`];
+        const bbox = glyphData.boundingBox;
+        const glyphWidth = bbox ? bbox.x2 - bbox.x1 : glyphData.advanceWidth;
+        const glyphHeight = bbox ? bbox.y2 - bbox.y1 : fontSize;
+        const glyphCenterX = currentX + (bbox ? bbox.x1 + glyphWidth / 2 : glyphData.advanceWidth / 2);
+        const glyphCenterY = currentY - (bbox ? (bbox.y1 + bbox.y2) / 2 : fontSize / 2);
+        const worldVertices = glyphData.vertices.map((v) => ({
+          x: currentX + v.x,
+          y: currentY + v.y
+        }));
+        const body = Matter5.Bodies.fromVertices(glyphCenterX, glyphCenterY, [worldVertices], {
+          isStatic,
+          label: `obstacle:${id}`,
+          render: {
+            visible: false
+          }
+        });
+        const offsetX = currentX - body.position.x;
+        const offsetY = currentY - body.position.y;
+        let pressureThreshold;
+        let wordCollapseTag;
+        if (config.pressureThreshold) {
+          const pt = config.pressureThreshold;
+          if (Array.isArray(pt.value)) {
+            pressureThreshold = pt.value[letterIds.length];
+          } else {
+            pressureThreshold = pt.value;
+            if (pt.wordCollapse) {
+              wordCollapseTag = wordTag;
+            }
+          }
+        }
+        let weight = 1;
+        if (config.weight) {
+          if (Array.isArray(config.weight.value)) {
+            weight = config.weight.value[letterIds.length] ?? 1;
+          } else {
+            weight = config.weight.value;
+          }
+        }
+        const shadow = config.shadow ? { opacity: config.shadow.opacity ?? 0.3 } : void 0;
+        const clicksRemaining = config.clickToFall?.clicks;
+        const entry = {
+          id,
+          body,
+          tags,
+          spawnTime: performance.now(),
+          ttl: config.ttl,
+          ttfGlyph: {
+            char,
+            fontSize,
+            fontFamily,
+            fillColor,
+            offsetX,
+            offsetY
+          },
+          pressureThreshold,
+          wordCollapseTag,
+          weight,
+          shadow,
+          originalPosition: shadow || clicksRemaining !== void 0 ? { x: body.position.x, y: body.position.y } : void 0,
+          clicksRemaining
+        };
+        this.objects.set(id, entry);
+        Matter5.Composite.add(this.engine.world, body);
+        letterIds.push(id);
+        letterMap.set(`${char}-${globalCharIndex}`, id);
+        currentX += glyphData.advanceWidth;
+        if (i < chars.length - 1) {
+          currentX += getKerning(loadedFont, char, chars[i + 1], fontSize);
+        }
+        globalCharIndex++;
+      }
+      currentY += lineHeight;
+    }
+    const wordTags = Array.from(wordTagsSet);
+    logger.info("OverlayScene", `Created TTF text obstacles`, {
+      text: text.replace(/\n/g, "\\n"),
+      fontUrl,
+      fontSize,
+      letterCount: letterIds.length,
+      stringTag,
+      wordTags,
+      lineCount: lines.length
+    });
+    return {
+      letterIds,
+      stringTag,
+      wordTags,
+      letterMap,
+      letterDebugInfo: []
+    };
+  }
+  /**
+   * Spawn falling TTF text objects.
+   * Same as addTTFTextObstacles but with 'falling' tag (objects fall with gravity).
+   */
+  async spawnFallingTTFTextObstacles(config) {
+    const tags = [...config.tags ?? []];
+    if (!tags.includes("falling")) tags.push("falling");
+    return this.addTTFTextObstacles({ ...config, tags });
+  }
+  // ==================== COMBINED TAG METHODS ====================
+  removeAllByTag(tag) {
+    this.removeObjectsByTag(tag);
+  }
+  removeAll() {
+    this.removeAllObjects();
+  }
+  // ==================== CALLBACKS ====================
+  onUpdate(callback) {
+    this.updateCallbacks.push(callback);
+  }
+  // ==================== EFFECT METHODS ====================
+  /**
+   * Add or update an effect configuration.
+   * Effects are persistent spawning mechanisms that run until disabled.
+   */
+  setEffect(config) {
+    this.effectManager.setEffect(config);
+  }
+  /**
+   * Remove an effect by ID
+   */
+  removeEffect(id) {
+    this.effectManager.removeEffect(id);
+  }
+  /**
+   * Enable or disable an effect
+   */
+  setEffectEnabled(id, enabled) {
+    this.effectManager.setEffectEnabled(id, enabled);
+  }
+  /**
+   * Get an effect configuration by ID
+   */
+  getEffect(id) {
+    return this.effectManager.getEffect(id);
+  }
+  /**
+   * Get all effect IDs
+   */
+  getEffectIds() {
+    return this.effectManager.getEffectIds();
+  }
+  /**
+   * Check if an effect is currently enabled
+   */
+  isEffectEnabled(id) {
+    return this.effectManager.isEffectEnabled(id);
+  }
+  /**
+   * Draw debug overlays for letter original dimension boxes
+   */
+  drawDebugOverlays() {
+    const ctx = this.canvas.getContext("2d");
+    if (!ctx) return;
+    for (const [, debugInfos] of this.letterDebugInfo) {
+      for (const info of debugInfos) {
+        const object = this.objects.get(info.id);
+        if (!object) continue;
+        const body = object.body;
+        ctx.save();
+        ctx.strokeStyle = "#00ffff";
+        ctx.lineWidth = 2;
+        ctx.setLineDash([5, 5]);
+        ctx.translate(body.position.x, body.position.y);
+        ctx.rotate(body.angle);
+        const halfWidth = info.scaledWidth / 2;
+        const halfHeight = info.scaledHeight / 2;
+        ctx.strokeRect(-halfWidth, -halfHeight, info.scaledWidth, info.scaledHeight);
+        ctx.restore();
+      }
+    }
+  }
+  /**
+   * Draw TTF glyphs using canvas fillText for clean text rendering
+   */
+  drawTTFGlyphs() {
+    const ctx = this.canvas.getContext("2d");
+    if (!ctx) return;
+    for (const [, entry] of this.objects) {
+      if (!entry.ttfGlyph) continue;
+      const { char, fontSize, fontFamily, fillColor, offsetX, offsetY } = entry.ttfGlyph;
+      const body = entry.body;
+      ctx.save();
+      ctx.translate(body.position.x, body.position.y);
+      ctx.rotate(body.angle);
+      ctx.font = `${fontSize}px "${fontFamily}"`;
+      ctx.fillStyle = fillColor;
+      ctx.textBaseline = "alphabetic";
+      ctx.fillText(char, offsetX, offsetY);
+      ctx.restore();
+    }
+  }
+  checkTTLExpiration() {
+    const now = performance.now();
+    const expiredObjects = [];
+    for (const [id, entry] of this.objects) {
+      if (entry.ttl !== void 0 && now - entry.spawnTime >= entry.ttl) {
+        expiredObjects.push(id);
+      }
+    }
+    for (const id of expiredObjects) {
+      this.removeObject(id);
+    }
+  }
+  /** Despawn objects that have fallen below the floor by the configured distance */
+  checkDespawnBelowFloor() {
+    const despawnDistance = this.config.despawnBelowFloor ?? 1;
+    const containerHeight = this.config.bounds.bottom - this.config.bounds.top;
+    const despawnY = this.config.bounds.bottom + containerHeight * despawnDistance;
+    const toDespawn = [];
+    for (const [id, entry] of this.objects) {
+      if (entry.body.position.y > despawnY) {
+        toDespawn.push(id);
+      }
+    }
+    for (const id of toDespawn) {
+      this.removeObject(id);
+    }
+  }
+  fireUpdateCallbacks() {
+    const objects = [];
+    this.objects.forEach((entry) => {
+      if (entry.tags.includes("falling")) {
+        objects.push({
+          id: entry.id,
+          x: entry.body.position.x,
+          y: entry.body.position.y,
+          angle: entry.body.angle,
+          tags: entry.tags
+        });
+      }
+    });
+    const data = { objects };
+    this.updateCallbacks.forEach((cb) => cb(data));
+  }
+};
+export {
+  OverlayScene,
+  clearFontCache,
+  getGlyphData,
+  getKerning,
+  getLogLevel,
+  loadFont,
+  logger,
+  measureText,
+  setLogLevel
+};
+//# sourceMappingURL=index.js.map