@almadar/ui 5.151.0 → 5.153.0

package/dist/context/index.d.cts

@@ -1,8 +1,8 @@
-export { U as UISlotContext, a as UISlotProvider, u as useSlotContent, b as useSlotHasContent, c as useUISlots } from '../UISlotContext-D8_SoDsD.cjs';
+export { U as UISlotContext, a as UISlotProvider, u as useSlotContent, b as useSlotHasContent, c as useUISlots } from '../UISlotContext-BlRDbHDy.cjs';
 export { B as BUILT_IN_THEMES, C as ColorMode, a as CurrentPagePathContext, b as CurrentPagePathProvider, c as CurrentPagePathProviderProps, D as DesignTheme, d as DesignThemeProvider, O as OrbitalThemeProvider, e as OrbitalThemeProviderProps, R as ResolvedMode, T as ThemeContext, f as ThemeProvider, g as ThemeProviderProps, U as UIThemeDefinition, h as UserContext, i as UserContextValue, j as UserData, k as UserProvider, l as UserProviderProps, u as useCurrentPagePath, m as useDesignTheme, n as useHasPermission, o as useHasRole, p as useTheme, q as useUser, r as useUserForEvaluation } from '../UserContext-g_LcDiGN.cjs';
 import { ThemeRef, ThemeDefinition, ThemeTokens, ThemeVariant } from '@almadar/core';
 export { ANONYMOUS_USER, UISlot } from '@almadar/core';
-export { S as SlotAnimation, a as SlotChangeCallback, b as SlotContent, c as SlotRenderConfig, U as UISlotManager } from '../useUISlots-BesZYMks.cjs';
+export { S as SlotAnimation, a as SlotChangeCallback, b as SlotContent, c as SlotRenderConfig, U as UISlotManager } from '../useUISlots-GNwGLlW2.cjs';
 import 'react';
 
 /**

package/dist/context/index.d.ts

@@ -1,8 +1,8 @@
-export { U as UISlotContext, a as UISlotProvider, u as useSlotContent, b as useSlotHasContent, c as useUISlots } from '../UISlotContext-C1FsU9GB.js';
+export { U as UISlotContext, a as UISlotProvider, u as useSlotContent, b as useSlotHasContent, c as useUISlots } from '../UISlotContext-CB89mv7N.js';
 export { B as BUILT_IN_THEMES, C as ColorMode, a as CurrentPagePathContext, b as CurrentPagePathProvider, c as CurrentPagePathProviderProps, D as DesignTheme, d as DesignThemeProvider, O as OrbitalThemeProvider, e as OrbitalThemeProviderProps, R as ResolvedMode, T as ThemeContext, f as ThemeProvider, g as ThemeProviderProps, U as UIThemeDefinition, h as UserContext, i as UserContextValue, j as UserData, k as UserProvider, l as UserProviderProps, u as useCurrentPagePath, m as useDesignTheme, n as useHasPermission, o as useHasRole, p as useTheme, q as useUser, r as useUserForEvaluation } from '../UserContext-g_LcDiGN.js';
 import { ThemeRef, ThemeDefinition, ThemeTokens, ThemeVariant } from '@almadar/core';
 export { ANONYMOUS_USER, UISlot } from '@almadar/core';
-export { S as SlotAnimation, a as SlotChangeCallback, b as SlotContent, c as SlotRenderConfig, U as UISlotManager } from '../useUISlots-BesZYMks.js';
+export { S as SlotAnimation, a as SlotChangeCallback, b as SlotContent, c as SlotRenderConfig, U as UISlotManager } from '../useUISlots-GNwGLlW2.js';
 import 'react';
 
 /**

package/dist/hooks/index.d.cts

@@ -3,7 +3,7 @@ export { BusEvent, BusEventListener, BusEventSource, BusEventListener as EventLi
 import { a as useEventBus } from '../useEventBus-Ckr4wqW3.cjs';
 export { u as useEmitEvent, b as useEventListener } from '../useEventBus-Ckr4wqW3.cjs';
 export { E as EventBusContextType } from '../event-bus-types-Bl78kokd.cjs';
-export { D as DEFAULT_SLOTS, S as SlotAnimation, a as SlotChangeCallback, b as SlotContent, c as SlotRenderConfig, U as UISlotManager, u as useUISlotManager } from '../useUISlots-BesZYMks.cjs';
+export { D as DEFAULT_SLOTS, S as SlotAnimation, a as SlotChangeCallback, b as SlotContent, c as SlotRenderConfig, U as UISlotManager, u as useUISlotManager } from '../useUISlots-GNwGLlW2.cjs';
 import * as React$1 from 'react';
 import React__default from 'react';
 import * as _tanstack_react_query from '@tanstack/react-query';

package/dist/hooks/index.d.ts

@@ -3,7 +3,7 @@ export { BusEvent, BusEventListener, BusEventSource, BusEventListener as EventLi
 import { a as useEventBus } from '../useEventBus-CQWyAWpK.js';
 export { u as useEmitEvent, b as useEventListener } from '../useEventBus-CQWyAWpK.js';
 export { E as EventBusContextType } from '../event-bus-types-Bl78kokd.js';
-export { D as DEFAULT_SLOTS, S as SlotAnimation, a as SlotChangeCallback, b as SlotContent, c as SlotRenderConfig, U as UISlotManager, u as useUISlotManager } from '../useUISlots-BesZYMks.js';
+export { D as DEFAULT_SLOTS, S as SlotAnimation, a as SlotChangeCallback, b as SlotContent, c as SlotRenderConfig, U as UISlotManager, u as useUISlotManager } from '../useUISlots-GNwGLlW2.js';
 import * as React$1 from 'react';
 import React__default from 'react';
 import * as _tanstack_react_query from '@tanstack/react-query';

package/dist/lib/drawable/three/index.cjs

@@ -712,6 +712,201 @@ function applyMeshAnimation(node, timeMs) {
     emissive: trackValue("emissive")
   };
 }
+
+// components/core/atoms/fx.ts
+function resolveFxView(item, presets) {
+  const row = presets?.find((p) => p.type === item.type);
+  if (!row) return item;
+  return {
+    ...item,
+    space: item.space ?? row.space,
+    effect: item.effect ?? row.effect,
+    color: item.color ?? row.color,
+    size: item.size ?? row.size,
+    vx: item.vx ?? row.vx,
+    vy: item.vy ?? row.vy,
+    vz: item.vz ?? row.vz,
+    particleCount: item.particleCount ?? row.particleCount,
+    shape: row.shape,
+    count: row.count,
+    glow: row.glow,
+    gravity: row.gravity,
+    color2: row.color2
+  };
+}
+function fxLifecycle(item, epochNowMs, tickMs) {
+  const maxTtl = Math.max(item.maxTtl ?? item.ttl, item.ttl, 1);
+  const lifeMs = maxTtl * tickMs;
+  const ageMs = item.bornAt !== void 0 && epochNowMs > 0 ? Math.max(0, epochNowMs - item.bornAt) : (1 - item.ttl / maxTtl) * lifeMs;
+  const progress = Math.min(1, Math.max(0, ageMs / lifeMs));
+  return { lifeMs, ageMs, progress, fade: 1 - progress };
+}
+function fxHash01(seed, salt) {
+  let h = 2166136261 ^ salt;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  h ^= h >>> 13;
+  h = Math.imul(h, 1274126177);
+  h ^= h >>> 16;
+  return (h >>> 0) / 4294967296;
+}
+
+// components/game/molecules/DrawFxLayer.tsx
+var DEFAULT_TICK_MS = 500;
+var DEFAULT_TEXT_COLOR = "#ffe066";
+var DEFAULT_SPARK_COLOR = "#ffffff";
+var easeOut = (t) => 1 - (1 - t) * (1 - t);
+function fxPosition(view, dim, ageSec) {
+  const g = view.gravity ?? 0;
+  const fall = 0.5 * g * ageSec * ageSec;
+  const base = view.position ?? { x: view.x, y: view.z ?? 0, z: view.y };
+  if (!Number.isFinite(base.x) || !Number.isFinite(base.y)) return void 0;
+  return {
+    x: base.x + (view.vx ?? 0) * ageSec,
+    y: base.y + (view.vz ?? 0) * ageSec,
+    ...base.z !== void 0 || view.vy !== void 0 || g !== 0 ? { z: (base.z ?? 0) + (view.vy ?? 0) * ageSec - fall } : {}
+  };
+}
+function sparkShape(view, pos, i, fade, progress) {
+  const size = view.size ?? 0.5;
+  const angle = fxHash01(view.id, i * 3) * Math.PI * 2;
+  const dist = size * (0.4 + 0.6 * fxHash01(view.id, i * 3 + 1)) * easeOut(progress);
+  const r = size * (0.06 + 0.06 * fxHash01(view.id, i * 3 + 2));
+  const color = view.color ?? DEFAULT_SPARK_COLOR;
+  return {
+    type: "draw-shape",
+    shape: "ellipse",
+    position: { ...pos, x: pos.x + Math.cos(angle) * dist, y: pos.y + Math.sin(angle) * dist },
+    anchor: "center",
+    radiusX: r,
+    fill: color,
+    blendMode: "lighter",
+    opacity: fade,
+    ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+  };
+}
+function proceduralShapes(view, pos, fade, progress) {
+  const size = view.size ?? 0.5;
+  const color = view.color ?? DEFAULT_SPARK_COLOR;
+  switch (view.shape ?? "spark") {
+    case "ring": {
+      return [
+        {
+          type: "draw-shape",
+          shape: "ellipse",
+          position: pos,
+          anchor: "center",
+          radiusX: size * easeOut(progress),
+          stroke: view.color2 ?? color,
+          strokeWidth: 2,
+          blendMode: "lighter",
+          opacity: fade,
+          ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+        }
+      ];
+    }
+    case "puff": {
+      const count = view.count ?? 3;
+      return Array.from({ length: count }, (_, i) => {
+        const angle = fxHash01(view.id, i * 5) * Math.PI * 2;
+        const drift = size * 0.3 * fxHash01(view.id, i * 5 + 1) * easeOut(progress);
+        return {
+          type: "draw-shape",
+          shape: "ellipse",
+          position: { ...pos, x: pos.x + Math.cos(angle) * drift, y: pos.y + Math.sin(angle) * drift },
+          anchor: "center",
+          radiusX: size * (0.15 + 0.35 * progress) * (0.7 + 0.6 * fxHash01(view.id, i * 5 + 2)),
+          fill: i === 0 && view.color2 ? view.color2 : color,
+          opacity: fade * 0.6,
+          ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+        };
+      });
+    }
+    case "streak": {
+      const count = view.count ?? 5;
+      return Array.from({ length: count }, (_, i) => {
+        const angle = fxHash01(view.id, i * 3) * Math.PI * 2;
+        const inner = size * (0.2 + 0.8 * easeOut(progress)) * (0.6 + 0.4 * fxHash01(view.id, i * 3 + 1));
+        const len = size * 0.35;
+        return {
+          type: "draw-shape",
+          shape: "ellipse",
+          position: pos,
+          anchor: "center",
+          offsetX: inner + len / 2,
+          offsetY: 0,
+          radiusX: len / 2,
+          radiusY: size * 0.04,
+          rotate: angle,
+          fill: color,
+          blendMode: "lighter",
+          opacity: fade,
+          ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+        };
+      });
+    }
+    default: {
+      const count = view.count ?? 6;
+      return Array.from({ length: count }, (_, i) => sparkShape(view, pos, i, fade, progress));
+    }
+  }
+}
+function expandFxItem(view, node, epochNowMs, dim) {
+  if (view.space === "screen") return [];
+  const tickMs = node.tickMs ?? DEFAULT_TICK_MS;
+  const { ageMs, progress, fade } = fxLifecycle(view, epochNowMs, tickMs);
+  if (progress >= 1) return [];
+  const pos = fxPosition(view, dim, ageMs / 1e3);
+  if (!pos) return [];
+  const out = [];
+  const artItems = node.art?.[view.type]?.["idle"];
+  const sprite = node.sprites?.[view.type];
+  if (Array.isArray(artItems)) {
+    out.push({
+      type: "draw-group",
+      position: pos,
+      opacity: fade,
+      ...view.size !== void 0 ? { scale: view.size } : {},
+      items: artItems
+    });
+  } else if (sprite?.url) {
+    const spriteSize = view.size ?? 0.6;
+    out.push({
+      type: "draw-sprite",
+      position: pos,
+      asset: sprite,
+      anchor: "center",
+      width: spriteSize,
+      height: spriteSize,
+      opacity: fade
+    });
+  } else {
+    out.push(...proceduralShapes(view, pos, fade, progress));
+  }
+  if (view.message) {
+    const text = {
+      type: "draw-text",
+      text: view.message,
+      position: pos,
+      offsetY: -(0.15 + 0.55 * progress),
+      color: view.color ?? node.textColor ?? DEFAULT_TEXT_COLOR,
+      opacity: fade
+    };
+    out.push(text);
+  }
+  return out;
+}
+function expandFxLayer(node, epochNowMs, dim) {
+  if (!Array.isArray(node.items)) return [];
+  const out = [];
+  for (const item of node.items) {
+    if (!item || typeof item.id !== "string") continue;
+    out.push(...expandFxItem(resolveFxView(item, node.presets), node, epochNowMs, dim));
+  }
+  return out;
+}
 var NUMERIC_TRACKS2 = [
   "offsetX",
   "offsetY",
@@ -1577,6 +1772,8 @@ function Drawable3D({ node, projector, groupOpacity = 1 }) {
         if (node.clip) warnUnsupported3d("draw-group:clip");
         return /* @__PURE__ */ jsxRuntime.jsx(Group3D, { node, projector, groupOpacity });
       }
+      case "draw-fx-layer":
+        return /* @__PURE__ */ jsxRuntime.jsx(FxLayer3D, { node, projector, groupOpacity });
     }
   })();
   return node.id ? /* @__PURE__ */ jsxRuntime.jsx("group", { userData: { drawableId: node.id }, children: rendered }) : rendered;
@@ -1624,6 +1821,21 @@ function Group3D({
   ] });
   return scopedStore ? /* @__PURE__ */ jsxRuntime.jsx(BoneRegistryContext.Provider, { value: scopedStore, children }) : children;
 }
+function FxLayer3D({
+  node,
+  projector,
+  groupOpacity
+}) {
+  const [, setFrame] = React3.useState(0);
+  const live = Array.isArray(node.items) && node.items.length > 0;
+  fiber.useFrame(() => {
+    if (live) setFrame((f) => (f + 1) % 1e6);
+  });
+  if (!live) return null;
+  const epochNow = typeof performance !== "undefined" ? performance.timeOrigin + performance.now() : 0;
+  const children = expandFxLayer(node, epochNow, "3d");
+  return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: children.map((c, i) => /* @__PURE__ */ jsxRuntime.jsx(Drawable3D, { node: c, projector, groupOpacity }, i)) });
+}
 
 // lib/drawable/three/game3dTheme.ts
 var GRID_COLORS_3D = {

package/dist/lib/drawable/three/index.d.cts

@@ -1,12 +1,12 @@
-import { C as CanvasPointLightConfig, I as IsometricTile, a as IsometricUnit, b as IsometricFeature, A as ApplicationLevelData, O as OrbitalLevelData, T as TraitLevelData, c as TransitionLevelData } from '../../../avl-schema-parser-CVzkNzg7.cjs';
-export { d as Canvas3DHost, e as Canvas3DHostHandle, f as Canvas3DHostProps, d as GameCanvas3D, U as UnitAnimationState } from '../../../avl-schema-parser-CVzkNzg7.cjs';
+import { C as CanvasPointLightConfig, I as IsometricTile, a as IsometricUnit, b as IsometricFeature, A as ApplicationLevelData, O as OrbitalLevelData, T as TraitLevelData, c as TransitionLevelData } from '../../../avl-schema-parser-Do_LPV1o.cjs';
+export { d as Canvas3DHost, e as Canvas3DHostHandle, f as Canvas3DHostProps, d as GameCanvas3D, U as UnitAnimationState } from '../../../avl-schema-parser-Do_LPV1o.cjs';
 import * as React$1 from 'react';
 import React__default, { Component, ReactNode, ErrorInfo } from 'react';
 import * as THREE from 'three';
 import { QuadraticBezierCurve3 } from 'three';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { JsonObject, EventEmit, OrbitalSchema } from '@almadar/core';
-import '../../../paintDispatch-BjZjUbcb.cjs';
+import '../../../paintDispatch-DgBctxIq.cjs';
 import '../../../types-B3nHgnMG.cjs';
 
 /**

package/dist/lib/drawable/three/index.d.ts

@@ -1,12 +1,12 @@
-import { C as CanvasPointLightConfig, I as IsometricTile, a as IsometricUnit, b as IsometricFeature, A as ApplicationLevelData, O as OrbitalLevelData, T as TraitLevelData, c as TransitionLevelData } from '../../../avl-schema-parser-Cx_4SVg9.js';
-export { d as Canvas3DHost, e as Canvas3DHostHandle, f as Canvas3DHostProps, d as GameCanvas3D, U as UnitAnimationState } from '../../../avl-schema-parser-Cx_4SVg9.js';
+import { C as CanvasPointLightConfig, I as IsometricTile, a as IsometricUnit, b as IsometricFeature, A as ApplicationLevelData, O as OrbitalLevelData, T as TraitLevelData, c as TransitionLevelData } from '../../../avl-schema-parser-CLIm28Wa.js';
+export { d as Canvas3DHost, e as Canvas3DHostHandle, f as Canvas3DHostProps, d as GameCanvas3D, U as UnitAnimationState } from '../../../avl-schema-parser-CLIm28Wa.js';
 import * as React$1 from 'react';
 import React__default, { Component, ReactNode, ErrorInfo } from 'react';
 import * as THREE from 'three';
 import { QuadraticBezierCurve3 } from 'three';
 import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
 import { JsonObject, EventEmit, OrbitalSchema } from '@almadar/core';
-import '../../../paintDispatch-CxdLjHQq.js';
+import '../../../paintDispatch-B5n2DTB-.js';
 import '../../../types-B3nHgnMG.js';
 
 /**

package/dist/lib/drawable/three/index.js

@@ -688,6 +688,201 @@ function applyMeshAnimation(node, timeMs) {
     emissive: trackValue("emissive")
   };
 }
+
+// components/core/atoms/fx.ts
+function resolveFxView(item, presets) {
+  const row = presets?.find((p) => p.type === item.type);
+  if (!row) return item;
+  return {
+    ...item,
+    space: item.space ?? row.space,
+    effect: item.effect ?? row.effect,
+    color: item.color ?? row.color,
+    size: item.size ?? row.size,
+    vx: item.vx ?? row.vx,
+    vy: item.vy ?? row.vy,
+    vz: item.vz ?? row.vz,
+    particleCount: item.particleCount ?? row.particleCount,
+    shape: row.shape,
+    count: row.count,
+    glow: row.glow,
+    gravity: row.gravity,
+    color2: row.color2
+  };
+}
+function fxLifecycle(item, epochNowMs, tickMs) {
+  const maxTtl = Math.max(item.maxTtl ?? item.ttl, item.ttl, 1);
+  const lifeMs = maxTtl * tickMs;
+  const ageMs = item.bornAt !== void 0 && epochNowMs > 0 ? Math.max(0, epochNowMs - item.bornAt) : (1 - item.ttl / maxTtl) * lifeMs;
+  const progress = Math.min(1, Math.max(0, ageMs / lifeMs));
+  return { lifeMs, ageMs, progress, fade: 1 - progress };
+}
+function fxHash01(seed, salt) {
+  let h = 2166136261 ^ salt;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  h ^= h >>> 13;
+  h = Math.imul(h, 1274126177);
+  h ^= h >>> 16;
+  return (h >>> 0) / 4294967296;
+}
+
+// components/game/molecules/DrawFxLayer.tsx
+var DEFAULT_TICK_MS = 500;
+var DEFAULT_TEXT_COLOR = "#ffe066";
+var DEFAULT_SPARK_COLOR = "#ffffff";
+var easeOut = (t) => 1 - (1 - t) * (1 - t);
+function fxPosition(view, dim, ageSec) {
+  const g = view.gravity ?? 0;
+  const fall = 0.5 * g * ageSec * ageSec;
+  const base = view.position ?? { x: view.x, y: view.z ?? 0, z: view.y };
+  if (!Number.isFinite(base.x) || !Number.isFinite(base.y)) return void 0;
+  return {
+    x: base.x + (view.vx ?? 0) * ageSec,
+    y: base.y + (view.vz ?? 0) * ageSec,
+    ...base.z !== void 0 || view.vy !== void 0 || g !== 0 ? { z: (base.z ?? 0) + (view.vy ?? 0) * ageSec - fall } : {}
+  };
+}
+function sparkShape(view, pos, i, fade, progress) {
+  const size = view.size ?? 0.5;
+  const angle = fxHash01(view.id, i * 3) * Math.PI * 2;
+  const dist = size * (0.4 + 0.6 * fxHash01(view.id, i * 3 + 1)) * easeOut(progress);
+  const r = size * (0.06 + 0.06 * fxHash01(view.id, i * 3 + 2));
+  const color = view.color ?? DEFAULT_SPARK_COLOR;
+  return {
+    type: "draw-shape",
+    shape: "ellipse",
+    position: { ...pos, x: pos.x + Math.cos(angle) * dist, y: pos.y + Math.sin(angle) * dist },
+    anchor: "center",
+    radiusX: r,
+    fill: color,
+    blendMode: "lighter",
+    opacity: fade,
+    ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+  };
+}
+function proceduralShapes(view, pos, fade, progress) {
+  const size = view.size ?? 0.5;
+  const color = view.color ?? DEFAULT_SPARK_COLOR;
+  switch (view.shape ?? "spark") {
+    case "ring": {
+      return [
+        {
+          type: "draw-shape",
+          shape: "ellipse",
+          position: pos,
+          anchor: "center",
+          radiusX: size * easeOut(progress),
+          stroke: view.color2 ?? color,
+          strokeWidth: 2,
+          blendMode: "lighter",
+          opacity: fade,
+          ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+        }
+      ];
+    }
+    case "puff": {
+      const count = view.count ?? 3;
+      return Array.from({ length: count }, (_, i) => {
+        const angle = fxHash01(view.id, i * 5) * Math.PI * 2;
+        const drift = size * 0.3 * fxHash01(view.id, i * 5 + 1) * easeOut(progress);
+        return {
+          type: "draw-shape",
+          shape: "ellipse",
+          position: { ...pos, x: pos.x + Math.cos(angle) * drift, y: pos.y + Math.sin(angle) * drift },
+          anchor: "center",
+          radiusX: size * (0.15 + 0.35 * progress) * (0.7 + 0.6 * fxHash01(view.id, i * 5 + 2)),
+          fill: i === 0 && view.color2 ? view.color2 : color,
+          opacity: fade * 0.6,
+          ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+        };
+      });
+    }
+    case "streak": {
+      const count = view.count ?? 5;
+      return Array.from({ length: count }, (_, i) => {
+        const angle = fxHash01(view.id, i * 3) * Math.PI * 2;
+        const inner = size * (0.2 + 0.8 * easeOut(progress)) * (0.6 + 0.4 * fxHash01(view.id, i * 3 + 1));
+        const len = size * 0.35;
+        return {
+          type: "draw-shape",
+          shape: "ellipse",
+          position: pos,
+          anchor: "center",
+          offsetX: inner + len / 2,
+          offsetY: 0,
+          radiusX: len / 2,
+          radiusY: size * 0.04,
+          rotate: angle,
+          fill: color,
+          blendMode: "lighter",
+          opacity: fade,
+          ...view.glow ? { shadow: { color, blur: view.glow } } : {}
+        };
+      });
+    }
+    default: {
+      const count = view.count ?? 6;
+      return Array.from({ length: count }, (_, i) => sparkShape(view, pos, i, fade, progress));
+    }
+  }
+}
+function expandFxItem(view, node, epochNowMs, dim) {
+  if (view.space === "screen") return [];
+  const tickMs = node.tickMs ?? DEFAULT_TICK_MS;
+  const { ageMs, progress, fade } = fxLifecycle(view, epochNowMs, tickMs);
+  if (progress >= 1) return [];
+  const pos = fxPosition(view, dim, ageMs / 1e3);
+  if (!pos) return [];
+  const out = [];
+  const artItems = node.art?.[view.type]?.["idle"];
+  const sprite = node.sprites?.[view.type];
+  if (Array.isArray(artItems)) {
+    out.push({
+      type: "draw-group",
+      position: pos,
+      opacity: fade,
+      ...view.size !== void 0 ? { scale: view.size } : {},
+      items: artItems
+    });
+  } else if (sprite?.url) {
+    const spriteSize = view.size ?? 0.6;
+    out.push({
+      type: "draw-sprite",
+      position: pos,
+      asset: sprite,
+      anchor: "center",
+      width: spriteSize,
+      height: spriteSize,
+      opacity: fade
+    });
+  } else {
+    out.push(...proceduralShapes(view, pos, fade, progress));
+  }
+  if (view.message) {
+    const text = {
+      type: "draw-text",
+      text: view.message,
+      position: pos,
+      offsetY: -(0.15 + 0.55 * progress),
+      color: view.color ?? node.textColor ?? DEFAULT_TEXT_COLOR,
+      opacity: fade
+    };
+    out.push(text);
+  }
+  return out;
+}
+function expandFxLayer(node, epochNowMs, dim) {
+  if (!Array.isArray(node.items)) return [];
+  const out = [];
+  for (const item of node.items) {
+    if (!item || typeof item.id !== "string") continue;
+    out.push(...expandFxItem(resolveFxView(item, node.presets), node, epochNowMs, dim));
+  }
+  return out;
+}
 var NUMERIC_TRACKS2 = [
   "offsetX",
   "offsetY",
@@ -1553,6 +1748,8 @@ function Drawable3D({ node, projector, groupOpacity = 1 }) {
         if (node.clip) warnUnsupported3d("draw-group:clip");
         return /* @__PURE__ */ jsx(Group3D, { node, projector, groupOpacity });
       }
+      case "draw-fx-layer":
+        return /* @__PURE__ */ jsx(FxLayer3D, { node, projector, groupOpacity });
     }
   })();
   return node.id ? /* @__PURE__ */ jsx("group", { userData: { drawableId: node.id }, children: rendered }) : rendered;
@@ -1600,6 +1797,21 @@ function Group3D({
   ] });
   return scopedStore ? /* @__PURE__ */ jsx(BoneRegistryContext.Provider, { value: scopedStore, children }) : children;
 }
+function FxLayer3D({
+  node,
+  projector,
+  groupOpacity
+}) {
+  const [, setFrame] = useState(0);
+  const live = Array.isArray(node.items) && node.items.length > 0;
+  useFrame(() => {
+    if (live) setFrame((f) => (f + 1) % 1e6);
+  });
+  if (!live) return null;
+  const epochNow = typeof performance !== "undefined" ? performance.timeOrigin + performance.now() : 0;
+  const children = expandFxLayer(node, epochNow, "3d");
+  return /* @__PURE__ */ jsx(Fragment, { children: children.map((c, i) => /* @__PURE__ */ jsx(Drawable3D, { node: c, projector, groupOpacity }, i)) });
+}
 
 // lib/drawable/three/game3dTheme.ts
 var GRID_COLORS_3D = {

package/dist/lib/index.cjs

@@ -3,6 +3,7 @@
 var clsx = require('clsx');
 var tailwindMerge = require('tailwind-merge');
 var logger = require('@almadar/logger');
+var core = require('@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;
@@ -866,8 +867,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;
@@ -888,6 +887,15 @@ function getNestedValue(obj, path) {
   }
   return value;
 }
+function resolveImageUrl(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (core.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();
@@ -2116,6 +2124,7 @@ exports.registerTrait = registerTrait;
 exports.registerTraitSnapshot = registerTraitSnapshot;
 exports.renderStateMachineToDomData = renderStateMachineToDomData;
 exports.renderStateMachineToSvg = renderStateMachineToSvg;
+exports.resolveImageUrl = resolveImageUrl;
 exports.setDebugEnabled = setDebugEnabled;
 exports.setEntityProvider = setEntityProvider;
 exports.setTickActive = setTickActive;

package/dist/lib/index.d.cts

@@ -1,8 +1,8 @@
-export { C as ContentSegment, D as DEFAULT_CONFIG, a as DomEntityBox, b as DomLayoutData, c as DomOutputsBox, d as DomStateNode, e as DomTransitionLabel, f as DomTransitionPath, E as EntityDefinition, L as LessonSegment, R as RenderOptions, S as StateDefinition, g as StateMachineDefinition, T as TraitSnapshotGetter, h as TransitionDefinition, V as VisualizerConfig, i as bindCanvasCapture, j as bindEventBus, k as bindLastDrawables, l as bindTraitStateGetter, m as clearVerification, n as cn, o as extractOutputsFromTransitions, p as extractStateMachine, q as formatGuard, r as getAllChecks, s as getBridgeHealth, t as getEffectSummary, u as getSnapshot, v as getSummary, w as getTraitSnapshots, x as getTransitions, y as getTransitionsForTrait, z as parseContentSegments, A as parseLessonSegments, B as parseMarkdownWithCodeBlocks, F as recordServerResponse, G as recordTransition, H as registerCheck, I as registerTraitSnapshot, J as renderStateMachineToDomData, K as renderStateMachineToSvg, M as subscribeToVerification, N as updateAssetStatus, O as updateBridgeHealth, P as updateCheck, Q as waitForTransition } from '../cn-BnAJZcNb.cjs';
+export { C as ContentSegment, D as DEFAULT_CONFIG, a as DomEntityBox, b as DomLayoutData, c as DomOutputsBox, d as DomStateNode, e as DomTransitionLabel, f as DomTransitionPath, E as EntityDefinition, L as LessonSegment, R as RenderOptions, S as StateDefinition, g as StateMachineDefinition, T as TraitSnapshotGetter, h as TransitionDefinition, V as VisualizerConfig, i as bindCanvasCapture, j as bindEventBus, k as bindLastDrawables, l as bindTraitStateGetter, m as clearVerification, n as cn, o as extractOutputsFromTransitions, p as extractStateMachine, q as formatGuard, r as getAllChecks, s as getBridgeHealth, t as getEffectSummary, u as getSnapshot, v as getSummary, w as getTraitSnapshots, x as getTransitions, y as getTransitionsForTrait, z as parseContentSegments, A as parseLessonSegments, B as parseMarkdownWithCodeBlocks, F as recordServerResponse, G as recordTransition, H as registerCheck, I as registerTraitSnapshot, J as renderStateMachineToDomData, K as renderStateMachineToSvg, M as subscribeToVerification, N as updateAssetStatus, O as updateBridgeHealth, P as updateCheck, Q as waitForTransition } from '../cn-TH-RHihd.cjs';
 import { FieldValue, EntityRow, EventPayload } from '@almadar/core';
 export { AssetLoadStatus, BridgeHealth, CheckStatus, EffectTrace, EventLogEntry, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary } from '@almadar/core';
 import 'react';
-import '../paintDispatch-BjZjUbcb.cjs';
+import '../paintDispatch-DgBctxIq.cjs';
 import '../types-B3nHgnMG.cjs';
 import 'clsx';
 
@@ -354,6 +354,13 @@ declare function sortRows<T extends Record<string, FieldValue | undefined>>(rows
  * getNestedValue(data, "company.missing");      // => undefined
  */
 declare function getNestedValue(obj: EventPayload | Record<string, FieldValue | undefined> | null | undefined, path: string): FieldValue | undefined;
+/**
+ * Resolve a field value that may be a raw URL string (legacy `image`/`url` fields) or a
+ * structured `file`-typed {@link FileValue} into the URL an `<img src>` can use. Gallery/card
+ * grid image tiles only ever rendered the raw-string case before the file-type promotion —
+ * this keeps them working once a field is retyped to `file`.
+ */
+declare function resolveImageUrl(value: FieldValue | undefined): string | undefined;
 /**
  * Format a nested field path as a human-readable label.
  *
@@ -551,4 +558,4 @@ declare function eightPointedStarPath(cx: number, cy: number, outerR: number, in
  */
 declare function arrowheadPath(size: number): string;
 
-export { ApiError, type DebugEvent, type DebugEventType, type EntitySnapshot, type EntityState, type GuardContext, type GuardEvaluation, JAZARI_COLORS, type JazariArmLayout, type JazariEffectInfo, type JazariGearLayout, type JazariGuardInfo, type JazariLayout, type LayoutInput, type LayoutState, type LayoutTransition, type PersistentEntityInfo, type RuntimeEntity, type SortDirection, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, type ValueFormat, apiClient, arrowheadPath, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, compareCellValues, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, formatDate, formatDateTime, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getTick, getTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, pipeIconPath, recordGuardEvaluation, registerTick, registerTrait, setDebugEnabled, setEntityProvider, setTickActive, sortRows, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, toggleDebug, unregisterTick, unregisterTrait, updateGuardResult, updateTickExecution, updateTraitState };
+export { ApiError, type DebugEvent, type DebugEventType, type EntitySnapshot, type EntityState, type GuardContext, type GuardEvaluation, JAZARI_COLORS, type JazariArmLayout, type JazariEffectInfo, type JazariGearLayout, type JazariGuardInfo, type JazariLayout, type LayoutInput, type LayoutState, type LayoutTransition, type PersistentEntityInfo, type RuntimeEntity, type SortDirection, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, type ValueFormat, apiClient, arrowheadPath, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, compareCellValues, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, formatDate, formatDateTime, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getTick, getTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, pipeIconPath, recordGuardEvaluation, registerTick, registerTrait, resolveImageUrl, setDebugEnabled, setEntityProvider, setTickActive, sortRows, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, toggleDebug, unregisterTick, unregisterTrait, updateGuardResult, updateTickExecution, updateTraitState };

package/dist/lib/index.d.ts

@@ -1,8 +1,8 @@
-export { C as ContentSegment, D as DEFAULT_CONFIG, a as DomEntityBox, b as DomLayoutData, c as DomOutputsBox, d as DomStateNode, e as DomTransitionLabel, f as DomTransitionPath, E as EntityDefinition, L as LessonSegment, R as RenderOptions, S as StateDefinition, g as StateMachineDefinition, T as TraitSnapshotGetter, h as TransitionDefinition, V as VisualizerConfig, i as bindCanvasCapture, j as bindEventBus, k as bindLastDrawables, l as bindTraitStateGetter, m as clearVerification, n as cn, o as extractOutputsFromTransitions, p as extractStateMachine, q as formatGuard, r as getAllChecks, s as getBridgeHealth, t as getEffectSummary, u as getSnapshot, v as getSummary, w as getTraitSnapshots, x as getTransitions, y as getTransitionsForTrait, z as parseContentSegments, A as parseLessonSegments, B as parseMarkdownWithCodeBlocks, F as recordServerResponse, G as recordTransition, H as registerCheck, I as registerTraitSnapshot, J as renderStateMachineToDomData, K as renderStateMachineToSvg, M as subscribeToVerification, N as updateAssetStatus, O as updateBridgeHealth, P as updateCheck, Q as waitForTransition } from '../cn-DJTUjk1M.js';
+export { C as ContentSegment, D as DEFAULT_CONFIG, a as DomEntityBox, b as DomLayoutData, c as DomOutputsBox, d as DomStateNode, e as DomTransitionLabel, f as DomTransitionPath, E as EntityDefinition, L as LessonSegment, R as RenderOptions, S as StateDefinition, g as StateMachineDefinition, T as TraitSnapshotGetter, h as TransitionDefinition, V as VisualizerConfig, i as bindCanvasCapture, j as bindEventBus, k as bindLastDrawables, l as bindTraitStateGetter, m as clearVerification, n as cn, o as extractOutputsFromTransitions, p as extractStateMachine, q as formatGuard, r as getAllChecks, s as getBridgeHealth, t as getEffectSummary, u as getSnapshot, v as getSummary, w as getTraitSnapshots, x as getTransitions, y as getTransitionsForTrait, z as parseContentSegments, A as parseLessonSegments, B as parseMarkdownWithCodeBlocks, F as recordServerResponse, G as recordTransition, H as registerCheck, I as registerTraitSnapshot, J as renderStateMachineToDomData, K as renderStateMachineToSvg, M as subscribeToVerification, N as updateAssetStatus, O as updateBridgeHealth, P as updateCheck, Q as waitForTransition } from '../cn-CFurBb2q.js';
 import { FieldValue, EntityRow, EventPayload } from '@almadar/core';
 export { AssetLoadStatus, BridgeHealth, CheckStatus, EffectTrace, EventLogEntry, OrbitalVerificationAPI, ServerResponseTrace, TraitStateSnapshot, TransitionTrace, VerificationCheck, VerificationSnapshot, VerificationSummary } from '@almadar/core';
 import 'react';
-import '../paintDispatch-CxdLjHQq.js';
+import '../paintDispatch-B5n2DTB-.js';
 import '../types-B3nHgnMG.js';
 import 'clsx';
 
@@ -354,6 +354,13 @@ declare function sortRows<T extends Record<string, FieldValue | undefined>>(rows
  * getNestedValue(data, "company.missing");      // => undefined
  */
 declare function getNestedValue(obj: EventPayload | Record<string, FieldValue | undefined> | null | undefined, path: string): FieldValue | undefined;
+/**
+ * Resolve a field value that may be a raw URL string (legacy `image`/`url` fields) or a
+ * structured `file`-typed {@link FileValue} into the URL an `<img src>` can use. Gallery/card
+ * grid image tiles only ever rendered the raw-string case before the file-type promotion —
+ * this keeps them working once a field is retyped to `file`.
+ */
+declare function resolveImageUrl(value: FieldValue | undefined): string | undefined;
 /**
  * Format a nested field path as a human-readable label.
  *
@@ -551,4 +558,4 @@ declare function eightPointedStarPath(cx: number, cy: number, outerR: number, in
  */
 declare function arrowheadPath(size: number): string;
 
-export { ApiError, type DebugEvent, type DebugEventType, type EntitySnapshot, type EntityState, type GuardContext, type GuardEvaluation, JAZARI_COLORS, type JazariArmLayout, type JazariEffectInfo, type JazariGearLayout, type JazariGuardInfo, type JazariLayout, type LayoutInput, type LayoutState, type LayoutTransition, type PersistentEntityInfo, type RuntimeEntity, type SortDirection, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, type ValueFormat, apiClient, arrowheadPath, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, compareCellValues, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, formatDate, formatDateTime, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getTick, getTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, pipeIconPath, recordGuardEvaluation, registerTick, registerTrait, setDebugEnabled, setEntityProvider, setTickActive, sortRows, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, toggleDebug, unregisterTick, unregisterTrait, updateGuardResult, updateTickExecution, updateTraitState };
+export { ApiError, type DebugEvent, type DebugEventType, type EntitySnapshot, type EntityState, type GuardContext, type GuardEvaluation, JAZARI_COLORS, type JazariArmLayout, type JazariEffectInfo, type JazariGearLayout, type JazariGuardInfo, type JazariLayout, type LayoutInput, type LayoutState, type LayoutTransition, type PersistentEntityInfo, type RuntimeEntity, type SortDirection, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, type ValueFormat, apiClient, arrowheadPath, brainIconPath, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, compareCellValues, computeJazariLayout, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, eightPointedStarPath, formatDate, formatDateTime, formatNestedFieldLabel, formatTime, formatValue, gearTeethPath, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getTick, getTrait, humanizeEnumValue, humanizeFieldName, initDebugShortcut, isDebugEnabled, lockIconPath, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, pipeIconPath, recordGuardEvaluation, registerTick, registerTrait, resolveImageUrl, setDebugEnabled, setEntityProvider, setTickActive, sortRows, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, toggleDebug, unregisterTick, unregisterTrait, updateGuardResult, updateTickExecution, updateTraitState };