@almadar/ui 5.151.0 → 5.153.0

package/dist/lib/index.js

@@ -1,6 +1,7 @@
 import { clsx } from 'clsx';
 import { twMerge } from 'tailwind-merge';
 import { createLogger, isLogLevelEnabled } from '@almadar/logger';
+import { isFileValue } from '@almadar/core';
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -864,8 +865,6 @@ function sortRows(rows, field, direction = "asc") {
   const dir = direction === "desc" ? -1 : 1;
   return [...rows].sort((a, b) => dir * compareCellValues(a?.[field], b?.[field]));
 }
-
-// lib/getNestedValue.ts
 function getNestedValue(obj, path) {
   if (obj === null || obj === void 0 || !path) {
     return void 0;
@@ -886,6 +885,15 @@ function getNestedValue(obj, path) {
   }
   return value;
 }
+function resolveImageUrl(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (isFileValue(value)) {
+    return value.url;
+  }
+  return void 0;
+}
 function formatNestedFieldLabel(path) {
   const lastPart = path.includes(".") ? path.split(".").pop() : path;
   return lastPart.replace(/([A-Z])/g, " $1").replace(/^./, (str) => str.toUpperCase()).replace(/Id$/, "").trim();
@@ -2024,4 +2032,4 @@ var JAZARI_COLORS = {
   darkBg: "#1a1a2e"
 };
 
-export { ApiError, DEFAULT_CONFIG, JAZARI_COLORS, apiClient, arrowheadPath, bindCanvasCapture, bindEventBus, bindLastDrawables, bindTraitStateGetter, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, clearVerification, cn, compareCellValues, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, extractOutputsFromTransitions, extractStateMachine, formatDate, formatDateTime, formatGuard, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllChecks, getAllTicks, getAllTraits, getBridgeHealth, getDebugEvents, getEffectSummary, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getSnapshot, getSummary, getTick, getTrait, getTraitSnapshots, getTransitions, getTransitionsForTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, parseContentSegments, parseLessonSegments, parseMarkdownWithCodeBlocks, pipeIconPath, recordGuardEvaluation, recordServerResponse, recordTransition, registerCheck, registerTick, registerTrait, registerTraitSnapshot, renderStateMachineToDomData, renderStateMachineToSvg, setDebugEnabled, setEntityProvider, setTickActive, sortRows, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, subscribeToVerification, toggleDebug, unregisterTick, unregisterTrait, updateAssetStatus, updateBridgeHealth, updateCheck, updateGuardResult, updateTickExecution, updateTraitState, waitForTransition };
+export { ApiError, DEFAULT_CONFIG, JAZARI_COLORS, apiClient, arrowheadPath, bindCanvasCapture, bindEventBus, bindLastDrawables, bindTraitStateGetter, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, clearVerification, cn, compareCellValues, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, extractOutputsFromTransitions, extractStateMachine, formatDate, formatDateTime, formatGuard, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllChecks, getAllTicks, getAllTraits, getBridgeHealth, getDebugEvents, getEffectSummary, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getSnapshot, getSummary, getTick, getTrait, getTraitSnapshots, getTransitions, getTransitionsForTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, parseContentSegments, parseLessonSegments, parseMarkdownWithCodeBlocks, pipeIconPath, recordGuardEvaluation, recordServerResponse, recordTransition, registerCheck, registerTick, registerTrait, registerTraitSnapshot, renderStateMachineToDomData, renderStateMachineToSvg, resolveImageUrl, setDebugEnabled, setEntityProvider, setTickActive, sortRows, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, subscribeToVerification, toggleDebug, unregisterTick, unregisterTrait, updateAssetStatus, updateBridgeHealth, updateCheck, updateGuardResult, updateTickExecution, updateTraitState, waitForTransition };

package/dist/{paintDispatch-CxdLjHQq.d.ts → paintDispatch-B5n2DTB-.d.ts}

@@ -505,6 +505,182 @@ interface DrawTextLayerProps extends DrawableBase {
     items: DrawTextProps[];
 }
 
+/**
+ * fx — the shared transient-effect contract (type-only module + pure helpers).
+ *
+ * One `FxItem` descriptor feeds BOTH render substrates: `draw-fx-layer` (game
+ * molecules — world-space, painted on the canvas) and `fx-overlay` (core
+ * molecules — screen-space, DOM/CSS). The substrate is NAME-BLIND: an item's
+ * look comes entirely from its resolved typed fields (color/size/shape/…),
+ * never from a kind→look table inside a component. The effect-kind vocabulary
+ * (`hit`, `explosion`, `correct-burst`, …) is declared by the CONSUMER — a
+ * board, lab, or themed organism — as an `FxPreset[]` table in its own `.lolo`
+ * config; `resolveFxView` merges the matching row under the item's own fields.
+ *
+ * Lifetime is owned by the fx mechanic (`std-fx-particles`): `ttl` decays every
+ * `tickMs` and removal is authoritative. Renderers derive smooth per-frame
+ * progress from `bornAt` (epoch ms, stamped at spawn) against the paint clock,
+ * falling back to the stepped `1 − ttl/maxTtl` fraction when `bornAt` is absent
+ * or no clock is running. Sub-particle scatter is seeded from the item `id` —
+ * deterministic, no `Math.random` at paint time.
+ */
+
+/** Which render substrate an fx entry belongs to. */
+type FxSpace = 'world' | 'screen';
+/** The screen-space render kinds `fx-overlay` can play — component capability, not domain vocabulary. */
+type FxOverlayKind = 'confetti' | 'flash' | 'shake' | 'sparkle' | 'float-text' | 'streak-glow';
+/** The procedural world-space recipes `draw-fx-layer` can paint — component capability, not domain vocabulary. */
+type FxProceduralShape = 'spark' | 'ring' | 'puff' | 'streak';
+/**
+ * One live transient effect — a row of the fx mechanic's `fx` entity list.
+ * Only `id`/`type`/`x`/`ttl` are guaranteed; everything else is optional so the
+ * 13 pre-existing producer emit sites keep compiling unchanged.
+ */
+interface FxItem {
+    /** Stable identity — the render key and the deterministic scatter seed. */
+    id: string;
+    /** Effect-kind key into the consumer-declared `FxPreset[]` table. */
+    type: string;
+    /** Canonical scene position; when absent the renderer derives it from `x`/`z`/`y`. */
+    position?: ScenePos;
+    /** Scene x in world units. */
+    x: number;
+    /** Ground-plane row in world units (2D boards paint it as screen y). */
+    z?: number;
+    /** Vertical axis in world units (3D height; 2D fallback row). */
+    y?: number;
+    /** Floating text painted with the effect (damage numbers, "+1", …). */
+    message?: string;
+    /** Remaining lifetime in mechanic ticks — the authoritative removal clock. */
+    ttl: number;
+    /** Spawn-time ttl (stamped by the mechanic when absent); grounds the fade fraction. */
+    maxTtl?: number;
+    /** Spawn timestamp in epoch ms (stamped by the mechanic) — enables smooth paint-clock progress. */
+    bornAt?: number;
+    /** Render substrate routing; default `world`. */
+    space?: FxSpace;
+    /** Screen-space render kind (`fx-overlay` vocabulary); ignored by the world layer. */
+    effect?: FxOverlayKind;
+    /** Primary color; renderer defaults apply when absent. */
+    color?: string;
+    /** Size in world units (canvas) / relative scale (overlay). */
+    size?: number;
+    /** Drift velocity along scene x, world-units/sec (render hint — the mechanic never integrates). */
+    vx?: number;
+    /** Drift velocity along the vertical axis, world-units/sec. */
+    vy?: number;
+    /** Drift velocity along the ground-plane row, world-units/sec. */
+    vz?: number;
+    /** Sub-particle count override (procedural burst / confetti). */
+    particleCount?: number;
+}
+/**
+ * One row of a consumer-declared effect vocabulary: the look + recipe for one
+ * fx `type`. Item fields always win over the preset row (`resolveFxView`).
+ */
+interface FxPreset {
+    /** The effect-kind key this row styles. */
+    type: string;
+    /** Primary color. */
+    color?: string;
+    /** Secondary color (ring stroke / puff core accents). */
+    color2?: string;
+    /** Size in world units (canvas) / relative scale (overlay). */
+    size?: number;
+    /** Procedural recipe when no vector art or sprite matches. Default `spark`. */
+    shape?: FxProceduralShape;
+    /** Sub-particle count for the procedural recipe. */
+    count?: number;
+    /** Glow strength — soft shadow blur in world units around procedural particles. */
+    glow?: number;
+    /** Downward acceleration in world-units/sec² applied to the drift. */
+    gravity?: number;
+    /** Default drift velocities, world-units/sec. */
+    vx?: number;
+    vy?: number;
+    vz?: number;
+    /** Render substrate routing for this kind. */
+    space?: FxSpace;
+    /** Screen-space render kind for this kind. */
+    effect?: FxOverlayKind;
+    /** Sub-particle count for screen-space kinds (confetti/sparkle). */
+    particleCount?: number;
+}
+/**
+ * A screen-space fx entry as `fx-overlay` consumes it — the same mechanic rows,
+ * filtered to `space == "screen"`. Deliberately carries NO `ScenePos`: overlay
+ * coordinates are viewport fractions, and the absence of a core `ScenePos` is
+ * what keeps `fx-overlay` out of the canvas-drawable capability.
+ */
+interface FxOverlayItem {
+    /** Stable identity — the mount key that starts the CSS animation, and the scatter seed. */
+    id: string;
+    /** Effect-kind key (consumer vocabulary); display comes from `effect` + style fields. */
+    type: string;
+    /** Overlay render kind; default `sparkle`. */
+    effect?: FxOverlayKind;
+    /** Floating text (`float-text`). */
+    message?: string;
+    /** Primary color. */
+    color?: string;
+    /** Relative scale multiplier. */
+    size?: number;
+    /** Horizontal viewport fraction 0..1; default 0.5. */
+    x?: number;
+    /** Vertical viewport fraction 0..1 (`z` wins, then `y`); default 0.4. */
+    z?: number;
+    y?: number;
+    /** Remaining lifetime in mechanic ticks — removal unmounts the node. */
+    ttl: number;
+    /** Spawn-time ttl; animation duration = maxTtl × tickMs. */
+    maxTtl?: number;
+    /** Spawn timestamp in epoch ms. */
+    bornAt?: number;
+    /** Render substrate routing; `world` entries are skipped defensively. */
+    space?: FxSpace;
+    /** Particle count for confetti/sparkle. */
+    particleCount?: number;
+    /** Drift velocities (unused by the DOM overlay; present so mechanic rows pass through untouched). */
+    vx?: number;
+    vy?: number;
+    vz?: number;
+}
+
+/**
+ * `draw-fx-layer` — the batched transient-effects pass in one descriptor.
+ *
+ * Collapses the fx triple every board used to hand-roll (message text layer +
+ * sprite fallback layer + vector-art group per fx entry) into ONE node:
+ * `{ type: draw-fx-layer, items: @entity.fx, presets: @config.fxPresets, … }`.
+ * NAME-BLIND: each item's look comes from its resolved typed fields via the
+ * consumer-declared `FxPreset[]` table — never a kind→look table in here.
+ * Render priority per item: vector `art[type].idle` (draw-group) → sprite
+ * `sprites[type]` (draw-sprite) → a procedural seeded recipe
+ * (spark/ring/puff/streak draw-shapes); a `message` always adds a rising,
+ * fading draw-text. Expansion is PURE (descriptors → descriptors, routed
+ * through the normal paint dispatch); per-frame smoothness comes from the host
+ * paint clock against each item's `bornAt`, while the fx mechanic's ttl decay
+ * stays the authoritative removal clock. `space: "screen"` entries are skipped
+ * — the `fx-overlay` core molecule owns those. The React component renders
+ * `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawFxLayerProps extends DrawableBase {
+    type: 'draw-fx-layer';
+    /** The live fx entries — the mechanic's `@entity.fx` list passed whole; `space: "screen"` entries are skipped (the overlay owns those). */
+    items: FxItem[];
+    /** Consumer-declared effect vocabulary — one row per fx `type` (look + recipe). Unknown types fall back to a neutral spark burst. */
+    presets?: FxPreset[];
+    /** Vector art per fx type (an asset-art map: type → anim-state → drawables); a type's `idle` state wins over sprites/procedural. */
+    art?: Record<string, Record<string, DrawableNode[]>>;
+    /** Sprite asset per fx type (an asset-manifest effects map) — used when no vector art matches. */
+    sprites?: Record<string, Asset>;
+    /** The fx mechanic's decay tick period in ms; lifetime = maxTtl × tickMs. Default 500. */
+    tickMs?: number;
+    /** Floating-message text color when an item declares none. Default `#ffe066`. */
+    textColor?: string;
+}
+
 /**
  * Drawable paint dispatch (2D) + the `DrawableNode` union.
  *
@@ -517,6 +693,6 @@ interface DrawTextLayerProps extends DrawableBase {
  */
 
 /** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
-type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawMeshProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawMeshProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps | DrawFxLayerProps;
 
-export type { DrawableNode as D, MeshShapeKind as M, MeshMaterial as a, DrawGroupProps as b, DrawTextProps as c, DrawMeshProps as d };
+export type { DrawableNode as D, FxOverlayItem as F, MeshShapeKind as M, MeshMaterial as a, DrawGroupProps as b, DrawTextProps as c, DrawMeshProps as d, FxOverlayKind as e };

package/dist/{paintDispatch-BjZjUbcb.d.cts → paintDispatch-DgBctxIq.d.cts}

@@ -505,6 +505,182 @@ interface DrawTextLayerProps extends DrawableBase {
     items: DrawTextProps[];
 }
 
+/**
+ * fx — the shared transient-effect contract (type-only module + pure helpers).
+ *
+ * One `FxItem` descriptor feeds BOTH render substrates: `draw-fx-layer` (game
+ * molecules — world-space, painted on the canvas) and `fx-overlay` (core
+ * molecules — screen-space, DOM/CSS). The substrate is NAME-BLIND: an item's
+ * look comes entirely from its resolved typed fields (color/size/shape/…),
+ * never from a kind→look table inside a component. The effect-kind vocabulary
+ * (`hit`, `explosion`, `correct-burst`, …) is declared by the CONSUMER — a
+ * board, lab, or themed organism — as an `FxPreset[]` table in its own `.lolo`
+ * config; `resolveFxView` merges the matching row under the item's own fields.
+ *
+ * Lifetime is owned by the fx mechanic (`std-fx-particles`): `ttl` decays every
+ * `tickMs` and removal is authoritative. Renderers derive smooth per-frame
+ * progress from `bornAt` (epoch ms, stamped at spawn) against the paint clock,
+ * falling back to the stepped `1 − ttl/maxTtl` fraction when `bornAt` is absent
+ * or no clock is running. Sub-particle scatter is seeded from the item `id` —
+ * deterministic, no `Math.random` at paint time.
+ */
+
+/** Which render substrate an fx entry belongs to. */
+type FxSpace = 'world' | 'screen';
+/** The screen-space render kinds `fx-overlay` can play — component capability, not domain vocabulary. */
+type FxOverlayKind = 'confetti' | 'flash' | 'shake' | 'sparkle' | 'float-text' | 'streak-glow';
+/** The procedural world-space recipes `draw-fx-layer` can paint — component capability, not domain vocabulary. */
+type FxProceduralShape = 'spark' | 'ring' | 'puff' | 'streak';
+/**
+ * One live transient effect — a row of the fx mechanic's `fx` entity list.
+ * Only `id`/`type`/`x`/`ttl` are guaranteed; everything else is optional so the
+ * 13 pre-existing producer emit sites keep compiling unchanged.
+ */
+interface FxItem {
+    /** Stable identity — the render key and the deterministic scatter seed. */
+    id: string;
+    /** Effect-kind key into the consumer-declared `FxPreset[]` table. */
+    type: string;
+    /** Canonical scene position; when absent the renderer derives it from `x`/`z`/`y`. */
+    position?: ScenePos;
+    /** Scene x in world units. */
+    x: number;
+    /** Ground-plane row in world units (2D boards paint it as screen y). */
+    z?: number;
+    /** Vertical axis in world units (3D height; 2D fallback row). */
+    y?: number;
+    /** Floating text painted with the effect (damage numbers, "+1", …). */
+    message?: string;
+    /** Remaining lifetime in mechanic ticks — the authoritative removal clock. */
+    ttl: number;
+    /** Spawn-time ttl (stamped by the mechanic when absent); grounds the fade fraction. */
+    maxTtl?: number;
+    /** Spawn timestamp in epoch ms (stamped by the mechanic) — enables smooth paint-clock progress. */
+    bornAt?: number;
+    /** Render substrate routing; default `world`. */
+    space?: FxSpace;
+    /** Screen-space render kind (`fx-overlay` vocabulary); ignored by the world layer. */
+    effect?: FxOverlayKind;
+    /** Primary color; renderer defaults apply when absent. */
+    color?: string;
+    /** Size in world units (canvas) / relative scale (overlay). */
+    size?: number;
+    /** Drift velocity along scene x, world-units/sec (render hint — the mechanic never integrates). */
+    vx?: number;
+    /** Drift velocity along the vertical axis, world-units/sec. */
+    vy?: number;
+    /** Drift velocity along the ground-plane row, world-units/sec. */
+    vz?: number;
+    /** Sub-particle count override (procedural burst / confetti). */
+    particleCount?: number;
+}
+/**
+ * One row of a consumer-declared effect vocabulary: the look + recipe for one
+ * fx `type`. Item fields always win over the preset row (`resolveFxView`).
+ */
+interface FxPreset {
+    /** The effect-kind key this row styles. */
+    type: string;
+    /** Primary color. */
+    color?: string;
+    /** Secondary color (ring stroke / puff core accents). */
+    color2?: string;
+    /** Size in world units (canvas) / relative scale (overlay). */
+    size?: number;
+    /** Procedural recipe when no vector art or sprite matches. Default `spark`. */
+    shape?: FxProceduralShape;
+    /** Sub-particle count for the procedural recipe. */
+    count?: number;
+    /** Glow strength — soft shadow blur in world units around procedural particles. */
+    glow?: number;
+    /** Downward acceleration in world-units/sec² applied to the drift. */
+    gravity?: number;
+    /** Default drift velocities, world-units/sec. */
+    vx?: number;
+    vy?: number;
+    vz?: number;
+    /** Render substrate routing for this kind. */
+    space?: FxSpace;
+    /** Screen-space render kind for this kind. */
+    effect?: FxOverlayKind;
+    /** Sub-particle count for screen-space kinds (confetti/sparkle). */
+    particleCount?: number;
+}
+/**
+ * A screen-space fx entry as `fx-overlay` consumes it — the same mechanic rows,
+ * filtered to `space == "screen"`. Deliberately carries NO `ScenePos`: overlay
+ * coordinates are viewport fractions, and the absence of a core `ScenePos` is
+ * what keeps `fx-overlay` out of the canvas-drawable capability.
+ */
+interface FxOverlayItem {
+    /** Stable identity — the mount key that starts the CSS animation, and the scatter seed. */
+    id: string;
+    /** Effect-kind key (consumer vocabulary); display comes from `effect` + style fields. */
+    type: string;
+    /** Overlay render kind; default `sparkle`. */
+    effect?: FxOverlayKind;
+    /** Floating text (`float-text`). */
+    message?: string;
+    /** Primary color. */
+    color?: string;
+    /** Relative scale multiplier. */
+    size?: number;
+    /** Horizontal viewport fraction 0..1; default 0.5. */
+    x?: number;
+    /** Vertical viewport fraction 0..1 (`z` wins, then `y`); default 0.4. */
+    z?: number;
+    y?: number;
+    /** Remaining lifetime in mechanic ticks — removal unmounts the node. */
+    ttl: number;
+    /** Spawn-time ttl; animation duration = maxTtl × tickMs. */
+    maxTtl?: number;
+    /** Spawn timestamp in epoch ms. */
+    bornAt?: number;
+    /** Render substrate routing; `world` entries are skipped defensively. */
+    space?: FxSpace;
+    /** Particle count for confetti/sparkle. */
+    particleCount?: number;
+    /** Drift velocities (unused by the DOM overlay; present so mechanic rows pass through untouched). */
+    vx?: number;
+    vy?: number;
+    vz?: number;
+}
+
+/**
+ * `draw-fx-layer` — the batched transient-effects pass in one descriptor.
+ *
+ * Collapses the fx triple every board used to hand-roll (message text layer +
+ * sprite fallback layer + vector-art group per fx entry) into ONE node:
+ * `{ type: draw-fx-layer, items: @entity.fx, presets: @config.fxPresets, … }`.
+ * NAME-BLIND: each item's look comes from its resolved typed fields via the
+ * consumer-declared `FxPreset[]` table — never a kind→look table in here.
+ * Render priority per item: vector `art[type].idle` (draw-group) → sprite
+ * `sprites[type]` (draw-sprite) → a procedural seeded recipe
+ * (spark/ring/puff/streak draw-shapes); a `message` always adds a rising,
+ * fading draw-text. Expansion is PURE (descriptors → descriptors, routed
+ * through the normal paint dispatch); per-frame smoothness comes from the host
+ * paint clock against each item's `bornAt`, while the fx mechanic's ttl decay
+ * stays the authoritative removal clock. `space: "screen"` entries are skipped
+ * — the `fx-overlay` core molecule owns those. The React component renders
+ * `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawFxLayerProps extends DrawableBase {
+    type: 'draw-fx-layer';
+    /** The live fx entries — the mechanic's `@entity.fx` list passed whole; `space: "screen"` entries are skipped (the overlay owns those). */
+    items: FxItem[];
+    /** Consumer-declared effect vocabulary — one row per fx `type` (look + recipe). Unknown types fall back to a neutral spark burst. */
+    presets?: FxPreset[];
+    /** Vector art per fx type (an asset-art map: type → anim-state → drawables); a type's `idle` state wins over sprites/procedural. */
+    art?: Record<string, Record<string, DrawableNode[]>>;
+    /** Sprite asset per fx type (an asset-manifest effects map) — used when no vector art matches. */
+    sprites?: Record<string, Asset>;
+    /** The fx mechanic's decay tick period in ms; lifetime = maxTtl × tickMs. Default 500. */
+    tickMs?: number;
+    /** Floating-message text color when an item declares none. Default `#ffe066`. */
+    textColor?: string;
+}
+
 /**
  * Drawable paint dispatch (2D) + the `DrawableNode` union.
  *
@@ -517,6 +693,6 @@ interface DrawTextLayerProps extends DrawableBase {
  */
 
 /** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
-type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawMeshProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawGroupProps | DrawMeshProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps | DrawFxLayerProps;
 
-export type { DrawableNode as D, MeshShapeKind as M, MeshMaterial as a, DrawGroupProps as b, DrawTextProps as c, DrawMeshProps as d };
+export type { DrawableNode as D, FxOverlayItem as F, MeshShapeKind as M, MeshMaterial as a, DrawGroupProps as b, DrawTextProps as c, DrawMeshProps as d, FxOverlayKind as e };