@almadar/ui 5.49.1 → 5.51.0

package/dist/avl/index.cjs

@@ -39,7 +39,7 @@ var core = require('@almadar/core');
 var core$1 = require('@dnd-kit/core');
 var sortable = require('@dnd-kit/sortable');
 var utilities = require('@dnd-kit/utilities');
-var THREE = require('three');
+var THREE3 = require('three');
 var GLTFLoader_js = require('three/examples/jsm/loaders/GLTFLoader.js');
 var OBJLoader_js = require('three/examples/jsm/loaders/OBJLoader.js');
 var GLTFLoader = require('three/examples/jsm/loaders/GLTFLoader');
@@ -94,7 +94,7 @@ var ReactMarkdown__default = /*#__PURE__*/_interopDefault(ReactMarkdown);
 var remarkGfm__default = /*#__PURE__*/_interopDefault(remarkGfm);
 var remarkMath__default = /*#__PURE__*/_interopDefault(remarkMath);
 var rehypeKatex__default = /*#__PURE__*/_interopDefault(rehypeKatex);
-var THREE__namespace = /*#__PURE__*/_interopNamespace(THREE);
+var THREE3__namespace = /*#__PURE__*/_interopNamespace(THREE3);
 
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -10839,6 +10839,52 @@ var init_ControlButton = __esm({
     ControlButton.displayName = "ControlButton";
   }
 });
+
+// components/game/organisms/utils/spriteAnimation.ts
+function inferDirection(dx, dy) {
+  if (dx === 0 && dy === 0) return "se";
+  if (dx >= 0 && dy >= 0) return "se";
+  if (dx <= 0 && dy >= 0) return "sw";
+  if (dx >= 0 && dy <= 0) return "ne";
+  return "nw";
+}
+function resolveSheetDirection(facing) {
+  switch (facing) {
+    case "se":
+      return { sheetDir: "se", flipX: false };
+    case "sw":
+      return { sheetDir: "sw", flipX: false };
+    case "ne":
+      return { sheetDir: "sw", flipX: true };
+    case "nw":
+      return { sheetDir: "se", flipX: true };
+  }
+}
+function frameRect(frame, row, columns, frameWidth, frameHeight) {
+  return {
+    sx: frame % columns * frameWidth,
+    sy: row * frameHeight,
+    sw: frameWidth,
+    sh: frameHeight
+  };
+}
+function getCurrentFrameFromDef(def, elapsed) {
+  const frameDuration = 1e3 / def.frameRate;
+  const totalDuration = def.frames * frameDuration;
+  if (def.loop) {
+    const frame2 = Math.floor(elapsed % totalDuration / frameDuration);
+    return { frame: frame2, finished: false };
+  }
+  if (elapsed >= totalDuration) {
+    return { frame: def.frames - 1, finished: true };
+  }
+  const frame = Math.floor(elapsed / frameDuration);
+  return { frame, finished: false };
+}
+var init_spriteAnimation = __esm({
+  "components/game/organisms/utils/spriteAnimation.ts"() {
+  }
+});
 function Sprite({
   spritesheet = "https://almadar-kflow-assets.web.app/shared/isometric-blocks/Spritesheet/allTiles_sheet.png",
   frameWidth = 64,
@@ -10859,12 +10905,8 @@ function Sprite({
 }) {
   const eventBus = useEventBus();
   const sourcePosition = React90.useMemo(() => {
-    const frameX = frame % columns;
-    const frameY = Math.floor(frame / columns);
-    return {
-      x: frameX * frameWidth,
-      y: frameY * frameHeight
-    };
+    const { sx, sy } = frameRect(frame, Math.floor(frame / columns), columns, frameWidth, frameHeight);
+    return { x: sx, y: sy };
   }, [frame, columns, frameWidth, frameHeight]);
   const transform = React90.useMemo(() => {
     const transforms = [
@@ -10912,6 +10954,7 @@ var init_Sprite = __esm({
   "components/game/atoms/Sprite.tsx"() {
     "use client";
     init_useEventBus();
+    init_spriteAnimation();
   }
 });
 function StateIndicator({
@@ -14303,6 +14346,163 @@ var init_useCamera = __esm({
     "use client";
   }
 });
+function unitAtlasUrl(unit) {
+  if (unit.spriteSheet) return unit.spriteSheet;
+  const sprite = unit.sprite;
+  if (!sprite) return null;
+  const match = /^(.*-sprite-sheet)(?:-(?:se|sw))?(?:-v\d+)?\.png$/.exec(sprite);
+  if (!match) return null;
+  return `${match[1]}.json`;
+}
+function resolveSheetUrl(atlasUrl, relativeSheetPath) {
+  try {
+    return new URL(relativeSheetPath, atlasUrl).toString();
+  } catch {
+    const base = atlasUrl.slice(0, atlasUrl.lastIndexOf("/") + 1);
+    return `${base}${relativeSheetPath.replace(/^\.\//, "")}`;
+  }
+}
+function useUnitSpriteAtlas(units) {
+  const atlasCacheRef = React90.useRef(/* @__PURE__ */ new Map());
+  const loadingRef = React90.useRef(/* @__PURE__ */ new Set());
+  const [pendingCount, setPendingCount] = React90.useState(0);
+  const [, forceTick] = React90.useState(0);
+  const animStatesRef = React90.useRef(/* @__PURE__ */ new Map());
+  const lastTickRef = React90.useRef(0);
+  const rafRef = React90.useRef(0);
+  const atlasUrls = React90.useMemo(() => {
+    const set = /* @__PURE__ */ new Set();
+    for (const unit of units) {
+      const url = unitAtlasUrl(unit);
+      if (url) set.add(url);
+    }
+    return [...set];
+  }, [units]);
+  React90.useEffect(() => {
+    const cache = atlasCacheRef.current;
+    const loading = loadingRef.current;
+    const toLoad = atlasUrls.filter((url) => !cache.has(url) && !loading.has(url));
+    if (toLoad.length === 0) return;
+    let cancelled = false;
+    setPendingCount((prev) => prev + toLoad.length);
+    for (const url of toLoad) {
+      loading.add(url);
+      fetch(url).then((res) => res.ok ? res.json() : Promise.reject(new Error(String(res.status)))).then((atlas) => {
+        if (cancelled) return;
+        cache.set(url, atlas);
+      }).catch(() => {
+      }).finally(() => {
+        if (cancelled) return;
+        loading.delete(url);
+        setPendingCount((prev) => Math.max(0, prev - 1));
+        forceTick((n) => n + 1);
+      });
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [atlasUrls]);
+  const sheetUrls = React90.useMemo(() => {
+    const urls = /* @__PURE__ */ new Set();
+    for (const unit of units) {
+      const atlasUrl = unitAtlasUrl(unit);
+      if (!atlasUrl) continue;
+      const atlas = atlasCacheRef.current.get(atlasUrl);
+      if (!atlas) continue;
+      for (const rel of Object.values(atlas.sheets)) {
+        if (rel) urls.add(resolveSheetUrl(atlasUrl, rel));
+      }
+    }
+    return [...urls];
+  }, [units, pendingCount]);
+  React90.useEffect(() => {
+    const hasAtlasUnits = units.some((u) => unitAtlasUrl(u) !== null);
+    if (!hasAtlasUnits) return;
+    let running = true;
+    const tick = (ts) => {
+      if (!running) return;
+      const last = lastTickRef.current || ts;
+      const delta = ts - last;
+      lastTickRef.current = ts;
+      const states = animStatesRef.current;
+      const currentIds = /* @__PURE__ */ new Set();
+      for (const unit of units) {
+        if (unitAtlasUrl(unit) === null) continue;
+        currentIds.add(unit.id);
+        let state = states.get(unit.id);
+        if (!state) {
+          state = { animation: "idle", direction: "se", elapsed: 0, walkHold: 0, prev: null };
+          states.set(unit.id, state);
+        }
+        const posX = unit.position?.x ?? unit.x ?? 0;
+        const posY = unit.position?.y ?? unit.y ?? 0;
+        if (state.prev) {
+          const dx = posX - state.prev.x;
+          const dy = posY - state.prev.y;
+          if (dx !== 0 || dy !== 0) {
+            state.animation = "walk";
+            state.direction = inferDirection(dx, dy);
+            state.walkHold = WALK_HOLD_MS;
+          } else if (state.animation === "walk") {
+            state.walkHold -= delta;
+            if (state.walkHold <= 0) state.animation = "idle";
+          }
+        }
+        state.prev = { x: posX, y: posY };
+        state.elapsed += delta;
+      }
+      for (const id of states.keys()) {
+        if (!currentIds.has(id)) states.delete(id);
+      }
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => {
+      running = false;
+      cancelAnimationFrame(rafRef.current);
+      lastTickRef.current = 0;
+    };
+  }, [units]);
+  const resolveUnitFrame = React90.useCallback((unitId) => {
+    const unit = units.find((u) => u.id === unitId);
+    if (!unit) return null;
+    const atlasUrl = unitAtlasUrl(unit);
+    if (!atlasUrl) return null;
+    const atlas = atlasCacheRef.current.get(atlasUrl);
+    if (!atlas) return null;
+    const state = animStatesRef.current.get(unitId);
+    const animation = state?.animation ?? "idle";
+    const direction = state?.direction ?? "se";
+    const elapsed = state?.elapsed ?? 0;
+    const def = atlas.animations[animation] ?? atlas.animations.idle;
+    if (!def) return null;
+    const { sheetDir, flipX } = resolveSheetDirection(direction);
+    const rel = atlas.sheets[sheetDir] ?? atlas.sheets.se ?? atlas.sheets.sw;
+    if (!rel) return null;
+    const sheetUrl = resolveSheetUrl(atlasUrl, rel);
+    const isIdle = animation === "idle";
+    const frame = isIdle ? 0 : getCurrentFrameFromDef(def, elapsed).frame;
+    const rect = frameRect(frame, def.row, atlas.columns, atlas.frameWidth, atlas.frameHeight);
+    return {
+      sheetUrl,
+      sx: rect.sx,
+      sy: rect.sy,
+      sw: rect.sw,
+      sh: rect.sh,
+      flipX,
+      applyBreathing: isIdle
+    };
+  }, [units]);
+  return { sheetUrls, resolveUnitFrame, pendingCount };
+}
+var WALK_HOLD_MS;
+var init_useUnitSpriteAtlas = __esm({
+  "components/game/molecules/useUnitSpriteAtlas.ts"() {
+    "use client";
+    init_spriteAnimation();
+    WALK_HOLD_MS = 600;
+  }
+});
 
 // components/game/organisms/utils/isometric.ts
 function isoToScreen(tileX, tileY, scale, baseOffsetX) {
@@ -14417,6 +14617,10 @@ function IsometricCanvas({
     () => unitsProp.map((u) => u.position ? u : { ...u, position: { x: u.x ?? 0, y: u.y ?? 0 } }),
     [unitsProp]
   );
+  const { sheetUrls: atlasSheetUrls, resolveUnitFrame: resolveUnitFrameInternal, pendingCount: atlasPending } = useUnitSpriteAtlas(units);
+  const resolveFrameForUnit = React90.useCallback((unitId) => {
+    return resolveUnitFrame?.(unitId) ?? resolveUnitFrameInternal(unitId);
+  }, [resolveUnitFrame, resolveUnitFrameInternal]);
   const features = React90.useMemo(
     () => featuresProp.map((f3) => {
       if (f3.type) return f3;
@@ -14500,9 +14704,10 @@ function IsometricCanvas({
       }
     }
     if (effectSpriteUrls) urls.push(...effectSpriteUrls);
+    if (atlasSheetUrls.length) urls.push(...atlasSheetUrls);
     if (backgroundImage) urls.push(backgroundImage);
     return [...new Set(urls.filter(Boolean))];
-  }, [sortedTiles, features, units, getTerrainSprite, getFeatureSprite, getUnitSprite, effectSpriteUrls, backgroundImage, assetManifest, resolveManifestUrl]);
+  }, [sortedTiles, features, units, getTerrainSprite, getFeatureSprite, getUnitSprite, effectSpriteUrls, atlasSheetUrls, backgroundImage, assetManifest, resolveManifestUrl]);
   const { getImage, pendingCount } = useImageCache(spriteUrls);
   React90.useEffect(() => {
     if (typeof window === "undefined") return;
@@ -14789,7 +14994,7 @@ function IsometricCanvas({
         ctx.lineWidth = 3;
         ctx.stroke();
       }
-      const frame = resolveUnitFrame?.(unit.id) ?? null;
+      const frame = resolveFrameForUnit(unit.id);
       const frameImg = frame ? getImage(frame.sheetUrl) : null;
       if (frame && frameImg) {
         const frameAr = frame.sw / frame.sh;
@@ -14899,7 +15104,7 @@ function IsometricCanvas({
     resolveTerrainSpriteUrl,
     resolveFeatureSpriteUrl,
     resolveUnitSpriteUrl,
-    resolveUnitFrame,
+    resolveFrameForUnit,
     getImage,
     gridWidth,
     gridHeight,
@@ -14931,7 +15136,7 @@ function IsometricCanvas({
     };
   }, [selectedUnitId, units, scale, baseOffsetX, scaledTileWidth, scaledDiamondTopY, scaledFloorHeight, viewportSize, targetCameraRef]);
   React90.useEffect(() => {
-    const hasAnimations = units.length > 0 || validMoves.length > 0 || attackTargets.length > 0 || selectedUnitId != null || targetCameraRef.current != null || hasActiveEffects2 || pendingCount > 0;
+    const hasAnimations = units.length > 0 || validMoves.length > 0 || attackTargets.length > 0 || selectedUnitId != null || targetCameraRef.current != null || hasActiveEffects2 || pendingCount > 0 || atlasPending > 0;
     draw(animTimeRef.current);
     if (!hasAnimations) return;
     let running = true;
@@ -14947,7 +15152,7 @@ function IsometricCanvas({
       running = false;
       cancelAnimationFrame(rafIdRef.current);
     };
-  }, [draw, units.length, validMoves.length, attackTargets.length, selectedUnitId, hasActiveEffects2, pendingCount, lerpToTarget, targetCameraRef]);
+  }, [draw, units.length, validMoves.length, attackTargets.length, selectedUnitId, hasActiveEffects2, pendingCount, atlasPending, lerpToTarget, targetCameraRef]);
   const handleMouseMoveWithCamera = React90.useCallback((e) => {
     if (enableCamera) {
       const wasPanning = handleMouseMove(e, () => draw(animTimeRef.current));
@@ -15092,6 +15297,7 @@ var init_IsometricCanvas = __esm({
     init_ErrorState();
     init_useImageCache();
     init_useCamera();
+    init_useUnitSpriteAtlas();
     init_verificationRegistry();
     init_isometric();
     IsometricCanvas.displayName = "IsometricCanvas";
@@ -31845,13 +32051,13 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect84, useRef: useRef76, useCallback: useCallback124, useState: useState120 } = React90__namespace.default;
+      const { useEffect: useEffect85, useRef: useRef77, useCallback: useCallback125, useState: useState121 } = React90__namespace.default;
       const { Typography: Typography2 } = await Promise.resolve().then(() => (init_Typography(), Typography_exports));
       const { useEventBus: useEventBus4 } = await Promise.resolve().then(() => (init_useEventBus(), useEventBus_exports));
       function MapUpdater({ centerLat, centerLng, zoom }) {
         const map = useMap();
-        const prevRef = useRef76({ centerLat, centerLng, zoom });
-        useEffect84(() => {
+        const prevRef = useRef77({ centerLat, centerLng, zoom });
+        useEffect85(() => {
           const prev = prevRef.current;
           if (prev.centerLat !== centerLat || prev.centerLng !== centerLng || prev.zoom !== zoom) {
             map.setView([centerLat, centerLng], zoom);
@@ -31862,7 +32068,7 @@ var init_MapView = __esm({
       }
       function MapClickHandler({ onMapClick }) {
         const map = useMap();
-        useEffect84(() => {
+        useEffect85(() => {
           if (!onMapClick) return;
           const handler = (e) => {
             onMapClick(e.latlng.lat, e.latlng.lng);
@@ -31890,8 +32096,8 @@ var init_MapView = __esm({
         showAttribution = true
       }) {
         const eventBus = useEventBus4();
-        const [clickedPosition, setClickedPosition] = useState120(null);
-        const handleMapClick = useCallback124((lat, lng) => {
+        const [clickedPosition, setClickedPosition] = useState121(null);
+        const handleMapClick = useCallback125((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -31900,7 +32106,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback124((marker) => {
+        const handleMarkerClick = useCallback125((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -43209,7 +43415,7 @@ var init_AssetLoader = __esm({
         __publicField(this, "textureCache");
         __publicField(this, "loadingPromises");
         this.objLoader = new OBJLoader_js.OBJLoader();
-        this.textureLoader = new THREE__namespace.TextureLoader();
+        this.textureLoader = new THREE3__namespace.TextureLoader();
         this.modelCache = /* @__PURE__ */ new Map();
         this.textureCache = /* @__PURE__ */ new Map();
         this.loadingPromises = /* @__PURE__ */ new Map();
@@ -43283,7 +43489,7 @@ var init_AssetLoader = __esm({
           return this.loadingPromises.get(`texture:${url}`);
         }
         const loadPromise = this.textureLoader.loadAsync(url).then((texture) => {
-          texture.colorSpace = THREE__namespace.SRGBColorSpace;
+          texture.colorSpace = THREE3__namespace.SRGBColorSpace;
           this.textureCache.set(url, texture);
           this.loadingPromises.delete(`texture:${url}`);
           return texture;
@@ -43357,7 +43563,7 @@ var init_AssetLoader = __esm({
         });
         this.modelCache.forEach((model) => {
           model.scene.traverse((child) => {
-            if (child instanceof THREE__namespace.Mesh) {
+            if (child instanceof THREE3__namespace.Mesh) {
               child.geometry.dispose();
               if (Array.isArray(child.material)) {
                 child.material.forEach((m) => m.dispose());
@@ -43913,7 +44119,7 @@ function ModelLoader({
     if (!loadedModel) return null;
     const cloned = loadedModel.clone();
     cloned.traverse((child) => {
-      if (child instanceof THREE__namespace.Mesh) {
+      if (child instanceof THREE3__namespace.Mesh) {
         child.castShadow = castShadow;
         child.receiveShadow = receiveShadow;
       }
@@ -44027,6 +44233,47 @@ function CameraController({
   }, [camera.position, onCameraChange]);
   return null;
 }
+function UnitSpriteBillboard({
+  sheetUrl,
+  resolveFrame,
+  height = 1.2
+}) {
+  const texture = fiber.useLoader(THREE3__namespace.TextureLoader, sheetUrl);
+  const meshRef = React90.useRef(null);
+  const matRef = React90.useRef(null);
+  const [aspect, setAspect] = React90.useState(1);
+  fiber.useFrame(() => {
+    const frame = resolveFrame();
+    if (!frame || !texture.image) return;
+    const imgW = texture.image.width;
+    const imgH = texture.image.height;
+    if (!imgW || !imgH) return;
+    texture.repeat.set((frame.flipX ? -1 : 1) * (frame.sw / imgW), frame.sh / imgH);
+    texture.offset.set(
+      frame.flipX ? (frame.sx + frame.sw) / imgW : frame.sx / imgW,
+      1 - (frame.sy + frame.sh) / imgH
+    );
+    texture.magFilter = THREE3__namespace.NearestFilter;
+    texture.minFilter = THREE3__namespace.NearestFilter;
+    texture.needsUpdate = true;
+    const nextAspect = frame.sw / frame.sh;
+    if (Math.abs(nextAspect - aspect) > 1e-3) setAspect(nextAspect);
+    if (matRef.current) matRef.current.needsUpdate = true;
+  });
+  return /* @__PURE__ */ jsxRuntime.jsxs("mesh", { ref: meshRef, position: [0, height / 2, 0], children: [
+    /* @__PURE__ */ jsxRuntime.jsx("planeGeometry", { args: [height * aspect, height] }),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "meshBasicMaterial",
+      {
+        ref: matRef,
+        map: texture,
+        transparent: true,
+        alphaTest: 0.1,
+        side: THREE3__namespace.DoubleSide
+      }
+    )
+  ] });
+}
 var DEFAULT_GRID_CONFIG, GameCanvas3D;
 var init_GameCanvas3D2 = __esm({
   "components/game/molecules/GameCanvas3D.tsx"() {
@@ -44037,6 +44284,7 @@ var init_GameCanvas3D2 = __esm({
     init_Canvas3DLoadingState2();
     init_Canvas3DErrorBoundary2();
     init_ModelLoader();
+    init_useUnitSpriteAtlas();
     init_cn();
     init_GameCanvas3D();
     DEFAULT_GRID_CONFIG = {
@@ -44093,8 +44341,10 @@ var init_GameCanvas3D2 = __esm({
         const controlsRef = React90.useRef(null);
         const [hoveredTile, setHoveredTile] = React90.useState(null);
         const [internalError, setInternalError] = React90.useState(null);
+        const { sheetUrls: atlasSheetUrls, resolveUnitFrame } = useUnitSpriteAtlas(units);
+        const preloadUrls = React90.useMemo(() => [...preloadAssets, ...atlasSheetUrls], [preloadAssets, atlasSheetUrls]);
         const { isLoading: assetsLoading, progress, loaded, total } = useAssetLoader({
-          preloadUrls: preloadAssets,
+          preloadUrls,
           loader: customAssetLoader
         });
         const eventHandlers = useGameCanvas3DEvents({
@@ -44153,7 +44403,7 @@ var init_GameCanvas3D2 = __esm({
           getCameraPosition: () => {
             if (controlsRef.current) {
               const pos = controlsRef.current.object.position;
-              return new THREE__namespace.Vector3(pos.x, pos.y, pos.z);
+              return new THREE3__namespace.Vector3(pos.x, pos.y, pos.z);
             }
             return null;
           },
@@ -44305,6 +44555,8 @@ var init_GameCanvas3D2 = __esm({
           ({ unit, position }) => {
             const isSelected = selectedUnitId === unit.id;
             const color = unit.faction === "player" ? 4491519 : unit.faction === "enemy" ? 16729156 : 16777028;
+            const hasAtlas = unitAtlasUrl(unit) !== null;
+            const initialFrame = hasAtlas ? resolveUnitFrame(unit.id) : null;
             return /* @__PURE__ */ jsxRuntime.jsxs(
               "group",
               {
@@ -44316,7 +44568,16 @@ var init_GameCanvas3D2 = __esm({
                     /* @__PURE__ */ jsxRuntime.jsx("ringGeometry", { args: [0.4, 0.5, 32] }),
                     /* @__PURE__ */ jsxRuntime.jsx("meshBasicMaterial", { color: "#ffff00", transparent: true, opacity: 0.8 })
                   ] }),
-                  unit.modelUrl ? (
+                  hasAtlas && initialFrame ? (
+                    /* Animated sprite-sheet billboard — single cropped frame, by state */
+                    /* @__PURE__ */ jsxRuntime.jsx(drei.Billboard, { children: /* @__PURE__ */ jsxRuntime.jsx(
+                      UnitSpriteBillboard,
+                      {
+                        sheetUrl: initialFrame.sheetUrl,
+                        resolveFrame: () => resolveUnitFrame(unit.id)
+                      }
+                    ) })
+                  ) : unit.modelUrl ? (
                     /* GLB unit model (box fallback while loading / on error) */
                     /* @__PURE__ */ jsxRuntime.jsx(
                       ModelLoader,
@@ -44370,7 +44631,7 @@ var init_GameCanvas3D2 = __esm({
               }
             );
           },
-          [selectedUnitId, handleUnitClick]
+          [selectedUnitId, handleUnitClick, resolveUnitFrame]
         );
         const DefaultFeatureRenderer = React90.useCallback(
           ({
@@ -57144,6 +57405,28 @@ init_verificationRegistry();
 var crossTraitLog = logger.createLogger("almadar:ui:cross-trait");
 var flushLog = logger.createLogger("almadar:ui:slot-flush");
 var stateLog = logger.createLogger("almadar:ui:state-transitions");
+var tickLog = logger.createLogger("almadar:ui:tick-effects");
+var SYNC_TICK_OPERATORS = /* @__PURE__ */ new Set([
+  "set",
+  "emit",
+  "render-ui",
+  "render",
+  "navigate",
+  "notify",
+  "log",
+  // Synchronous structural forms that wrap sync effects. A tick authored as
+  // a single top-level `(let ((..)) (do (set ..) (render-ui ..)))` or
+  // `(if cond (set ..) ..)` is one of these at its head — the EffectExecutor
+  // resolves the binding values / condition through the canonical evaluator
+  // and runs the wrapped sync effects. Without these in the allow-list the
+  // whole tick is filtered out (its head op isn't `set`/`emit`/...), so the
+  // physics/gameflow/AI tick never runs.
+  "let",
+  "if",
+  "do",
+  "when"
+]);
+var LIFECYCLE_EVENTS = ["INIT", "LOAD", "$MOUNT"];
 function toTraitDefinition(binding) {
   return {
     name: binding.trait.name,
@@ -57176,6 +57459,7 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
   });
   const eventQueueRef = React90.useRef([]);
   const processingRef = React90.useRef(false);
+  const initedTraitsRef = React90.useRef(/* @__PURE__ */ new Set());
   const traitBindingsRef = React90.useRef(traitBindings);
   const managerRef = React90.useRef(manager);
   const uiSlotsRef = React90.useRef(uiSlots);
@@ -57340,50 +57624,196 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
       for (const unreg of snapshotUnregs) unreg();
     };
   }, [traitBindings]);
-  const runTickEffects = React90.useCallback((tick, binding) => {
-    const currentState = traitStatesRef.current.get(binding.trait.name)?.currentState ?? "";
-    if (tick.appliesTo.length > 0 && !tick.appliesTo.includes(currentState)) return;
-    const bindingCtx = { entity: {}, payload: {}, state: currentState };
-    if (binding.config) {
-      bindingCtx.config = binding.config;
-    }
-    const evalCtx = runtime.createContextFromBindings(bindingCtx);
-    if (tick.guard !== void 0) {
-      const passed = runtime.interpolateValue(tick.guard, evalCtx);
-      if (!passed) return;
-    }
+  const executeTransitionEffects = React90.useCallback(async (params) => {
+    const { binding, previousState, newState, payload, flushEvent, syncOnly, log: log15 } = params;
+    const traitName = binding.trait.name;
+    const linkedEntity = binding.linkedEntity || "";
+    const entityId = payload?.entityId;
+    const effects = syncOnly ? params.effects.filter(
+      (e) => Array.isArray(e) && SYNC_TICK_OPERATORS.has(String(e[0]))
+    ) : params.effects;
+    if (effects.length === 0) return [];
     const pendingSlots = /* @__PURE__ */ new Map();
     ({
-      trait: binding.trait.name,
-      transition: `${currentState}->tick:${tick.name}`,
-      effects: tick.effects,
       traitDefinition: binding.trait
     });
-    for (const effect of tick.effects) {
-      if (!Array.isArray(effect)) continue;
-      const op = effect[0];
-      if (op === "render-ui" || op === "render") {
-        const slot = effect[1];
-        const rawPattern = effect[2];
-        if (rawPattern === null || rawPattern === void 0) {
+    const clientHandlers = createClientEffectHandlers({
+      eventBus,
+      slotSetter: {
+        addPattern: (slot, pattern, props) => {
+          const existing = pendingSlots.get(slot) || [];
+          existing.push({ pattern, props: props || {} });
+          pendingSlots.set(slot, existing);
+        },
+        clearSlot: (slot) => {
           pendingSlots.set(slot, []);
-          continue;
         }
-        const updatedCtx = runtime.createContextFromBindings(bindingCtx);
-        const resolved = runtime.interpolateValue(rawPattern, updatedCtx);
-        const existing = pendingSlots.get(slot) ?? [];
-        existing.push({ pattern: resolved, props: {} });
-        pendingSlots.set(slot, existing);
+      },
+      navigate: optionsRef.current?.navigate,
+      notify: optionsRef.current?.notify,
+      callService: optionsRef.current?.callService
+    });
+    const persistence = syncOnly ? void 0 : optionsRef.current?.persistence;
+    let handlers = clientHandlers;
+    if (persistence) {
+      const sharedBindings = {
+        // Seed `@entity` from the trait's scalar field state (a real
+        // EntityRow), the same source the executor's own bindingCtx
+        // uses below. `@payload.*` resolves from `payload` separately,
+        // so dropping the prior `payload as EntityRow` cast loses
+        // nothing — it just stops mislabelling the payload as an entity.
+        entity: traitFieldStatesRef.current.get(traitName) ?? {},
+        payload: payload || {},
+        state: previousState
+      };
+      const sharedDeclared = runtime.collectDeclaredConfigDefaults(binding.trait);
+      const sharedCallSite = binding.config;
+      if (sharedDeclared || sharedCallSite) {
+        sharedBindings.config = {
+          ...sharedDeclared ?? {},
+          ...sharedCallSite ?? {}
+        };
       }
+      const serverHandlers = runtime.createServerEffectHandlers({
+        persistence,
+        eventBus,
+        entityType: linkedEntity,
+        entityId,
+        bindings: sharedBindings,
+        context: {
+          traitName,
+          state: previousState,
+          transition: `${previousState}->${newState}`,
+          linkedEntity,
+          entityId
+        },
+        source: { trait: traitName },
+        callService: optionsRef.current?.callService
+      });
+      handlers = {
+        ...serverHandlers,
+        emit: clientHandlers.emit,
+        renderUI: clientHandlers.renderUI,
+        navigate: clientHandlers.navigate,
+        notify: clientHandlers.notify
+      };
     }
-    for (const [slot, patterns] of pendingSlots) {
-      flushSlot(binding.trait.name, slot, patterns, {
-        event: `tick:${tick.name}`,
-        state: currentState,
-        entity: binding.linkedEntity
+    const baseSet = handlers.set;
+    handlers = {
+      ...handlers,
+      set: async (targetId, field, value) => {
+        let fieldState = traitFieldStatesRef.current.get(traitName);
+        if (!fieldState) {
+          fieldState = {};
+          traitFieldStatesRef.current.set(traitName, fieldState);
+        }
+        fieldState[field] = value;
+        log15.debug("set:write", {
+          traitName,
+          field,
+          value: JSON.stringify(value),
+          transition: `${previousState}->${newState}`
+        });
+        if (baseSet) await baseSet(targetId, field, value);
+      }
+    };
+    const entityForBinding = traitFieldStatesRef.current.get(traitName) ?? {};
+    const bindingCtx = {
+      entity: entityForBinding,
+      payload: payload || {},
+      state: previousState
+    };
+    const declaredDefaults = runtime.collectDeclaredConfigDefaults(binding.trait);
+    const callSiteConfig = binding.config;
+    if (declaredDefaults || callSiteConfig) {
+      bindingCtx.config = {
+        ...declaredDefaults ?? {},
+        ...callSiteConfig ?? {}
+      };
+    }
+    const effectContext = {
+      traitName,
+      state: previousState,
+      transition: `${previousState}->${newState}`,
+      linkedEntity,
+      entityId
+    };
+    const emittedDuringExec = [];
+    const baseEmit = handlers.emit;
+    const trackingHandlers = {
+      ...handlers,
+      emit: (event, eventPayload, source) => {
+        emittedDuringExec.push(event);
+        baseEmit(event, eventPayload, source);
+      }
+    };
+    const executor = new runtime.EffectExecutor({ handlers: trackingHandlers, bindings: bindingCtx, context: effectContext });
+    try {
+      await executor.executeAll(effects);
+      log15.debug("effects:executed", () => ({
+        traitName,
+        transition: `${previousState}->${newState}`,
+        event: flushEvent,
+        effectCount: effects.length,
+        emitted: emittedDuringExec.join(","),
+        entityAfter: JSON.stringify(traitFieldStatesRef.current.get(traitName) ?? {}),
+        slotsTouched: Array.from(pendingSlots.keys()).join(",")
+      }));
+      for (const [slot, patterns] of pendingSlots) {
+        log15.debug("flush:slot", {
+          traitName,
+          slot,
+          patternCount: patterns.length,
+          event: flushEvent,
+          transition: `${previousState}->${newState}`,
+          cleared: patterns.length === 0
+        });
+        flushSlot(traitName, slot, patterns, {
+          event: flushEvent,
+          state: previousState,
+          entity: binding.linkedEntity
+        });
+      }
+    } catch (error) {
+      log15.error("effects:error", {
+        traitName,
+        transition: `${previousState}->${newState}`,
+        event: flushEvent,
+        error: error instanceof Error ? error.message : String(error),
+        effectCount: effects.length
       });
     }
-  }, [flushSlot]);
+    return emittedDuringExec;
+  }, [eventBus, flushSlot]);
+  const runTickEffects = React90.useCallback((tick, binding) => {
+    const traitName = binding.trait.name;
+    const currentState = traitStatesRef.current.get(traitName)?.currentState ?? "";
+    if (tick.appliesTo.length > 0 && !tick.appliesTo.includes(currentState)) return;
+    if (tick.guard !== void 0) {
+      const guardCtx = {
+        entity: traitFieldStatesRef.current.get(traitName) ?? {},
+        payload: {},
+        state: currentState
+      };
+      if (binding.config) {
+        guardCtx.config = binding.config;
+      }
+      const passed = runtime.interpolateValue(tick.guard, runtime.createContextFromBindings(guardCtx));
+      if (!passed) {
+        tickLog.debug("guard-blocked", { traitName, tick: tick.name, state: currentState });
+        return;
+      }
+    }
+    void executeTransitionEffects({
+      binding,
+      effects: tick.effects,
+      previousState: currentState,
+      newState: currentState,
+      flushEvent: `tick:${tick.name}`,
+      syncOnly: true,
+      log: tickLog
+    });
+  }, [executeTransitionEffects]);
   React90.useEffect(() => {
     const hasFrameTicks = traitBindingsRef.current.some(
       (b) => b.trait.ticks?.some((t) => t.interval === "frame")
@@ -57494,161 +57924,17 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
           transition: `${result.previousState} -> ${result.newState}`,
           effects: JSON.stringify(result.effects)
         }));
-        const linkedEntity = binding.linkedEntity || "";
-        const entityId = payload?.entityId;
-        const pendingSlots = /* @__PURE__ */ new Map();
-        const slotSource = {
-          trait: binding.trait.name,
-          state: result.previousState,
-          transition: `${result.previousState}->${result.newState}`,
+        const emittedDuringExec = await executeTransitionEffects({
+          binding,
           effects: result.effects,
-          traitDefinition: binding.trait
-        };
-        const clientHandlers = createClientEffectHandlers({
-          eventBus,
-          slotSetter: {
-            addPattern: (slot, pattern, props) => {
-              const existing = pendingSlots.get(slot) || [];
-              existing.push({ pattern, props: props || {} });
-              pendingSlots.set(slot, existing);
-            },
-            clearSlot: (slot) => {
-              pendingSlots.set(slot, []);
-            }
-          },
-          navigate: optionsRef.current?.navigate,
-          notify: optionsRef.current?.notify,
-          callService: optionsRef.current?.callService
+          previousState: result.previousState,
+          newState: result.newState,
+          payload,
+          flushEvent: eventKey,
+          syncOnly: false,
+          log: stateLog
         });
-        const persistence = optionsRef.current?.persistence;
-        let handlers = clientHandlers;
-        if (persistence) {
-          const sharedBindings = {
-            entity: payload ?? {},
-            payload: payload || {},
-            state: result.previousState
-          };
-          const sharedDeclared = runtime.collectDeclaredConfigDefaults(
-            binding.trait
-          );
-          const sharedCallSite = binding.config;
-          if (sharedDeclared || sharedCallSite) {
-            sharedBindings.config = {
-              ...sharedDeclared ?? {},
-              ...sharedCallSite ?? {}
-            };
-          }
-          const serverHandlers = runtime.createServerEffectHandlers({
-            persistence,
-            eventBus,
-            entityType: linkedEntity,
-            entityId,
-            bindings: sharedBindings,
-            context: {
-              traitName: binding.trait.name,
-              state: result.previousState,
-              transition: `${result.previousState}->${result.newState}`,
-              linkedEntity,
-              entityId
-            },
-            source: { trait: binding.trait.name },
-            callService: optionsRef.current?.callService
-          });
-          handlers = {
-            ...serverHandlers,
-            // Client handlers own UI + emit: keep the slot setter
-            // and pre-prefixed UI:* emit path intact.
-            emit: clientHandlers.emit,
-            renderUI: clientHandlers.renderUI,
-            navigate: clientHandlers.navigate,
-            notify: clientHandlers.notify
-          };
-        }
-        const baseSet = handlers.set;
-        handlers = {
-          ...handlers,
-          set: async (targetId, field, value) => {
-            let fieldState = traitFieldStatesRef.current.get(traitName);
-            if (!fieldState) {
-              fieldState = {};
-              traitFieldStatesRef.current.set(traitName, fieldState);
-            }
-            fieldState[field] = value;
-            if (baseSet) await baseSet(targetId, field, value);
-          }
-        };
-        const entityForBinding = traitFieldStatesRef.current.get(traitName) ?? {};
-        const bindingCtx = {
-          entity: entityForBinding,
-          payload: payload || {},
-          state: result.previousState
-        };
-        const declaredDefaults = runtime.collectDeclaredConfigDefaults(
-          binding.trait
-        );
-        const callSiteConfig = binding.config;
-        if (declaredDefaults || callSiteConfig) {
-          bindingCtx.config = {
-            ...declaredDefaults ?? {},
-            ...callSiteConfig ?? {}
-          };
-        }
-        const effectContext = {
-          traitName: binding.trait.name,
-          state: result.previousState,
-          transition: `${result.previousState}->${result.newState}`,
-          linkedEntity,
-          entityId
-        };
-        const emittedDuringExec = [];
         emittedByTrait.set(traitName, emittedDuringExec);
-        const baseEmit = handlers.emit;
-        const trackingHandlers = {
-          ...handlers,
-          emit: (event, eventPayload, source) => {
-            emittedDuringExec.push(event);
-            baseEmit(event, eventPayload, source);
-          }
-        };
-        const executor = new runtime.EffectExecutor({ handlers: trackingHandlers, bindings: bindingCtx, context: effectContext });
-        try {
-          await executor.executeAll(result.effects);
-          stateLog.debug("transition:render-ui-dispatched", () => ({
-            traitName,
-            fromState: result.previousState,
-            toState: result.newState,
-            event: eventKey,
-            slotsTouched: Array.from(pendingSlots.keys()).join(","),
-            patternTypes: Array.from(pendingSlots.entries()).map(
-              ([slot, patterns]) => `${slot}:[${patterns.map((p2) => p2.pattern?.type ?? "null").join(",")}]`
-            ).join(";")
-          }));
-          void slotSource;
-          for (const [slot, patterns] of pendingSlots) {
-            stateLog.debug("flush:slot", {
-              traitName,
-              slot,
-              patternCount: patterns.length,
-              event: eventKey,
-              transition: `${result.previousState}->${result.newState}`,
-              cleared: patterns.length === 0
-            });
-            flushSlot(traitName, slot, patterns, {
-              event: eventKey,
-              state: result.previousState,
-              entity: binding.linkedEntity
-            });
-          }
-        } catch (error) {
-          stateLog.error("transition:effect-error", {
-            traitName,
-            fromState: result.previousState,
-            toState: result.newState,
-            event: eventKey,
-            error: error instanceof Error ? error.message : String(error),
-            effectCount: result.effects.length
-          });
-        }
       } else if (!result.executed) {
         if (result.guardResult === false) {
           stateLog.debug("guard-blocked-transition", {
@@ -57786,7 +58072,7 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
       if (!orbitalName) continue;
       for (const transition of binding.trait.transitions) {
         const eventKey = transition.event;
-        if (eventKey === "INIT" || eventKey === "LOAD" || eventKey === "$MOUNT") {
+        if (LIFECYCLE_EVENTS.includes(eventKey)) {
           continue;
         }
         const selfBusKey = `UI:${orbitalName}.${traitName}.${eventKey}`;
@@ -57841,6 +58127,24 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
       crossTraitLog.debug("cleanup:done", {});
     };
   }, [traitBindings, eventBus, enqueueAndDrain]);
+  React90.useEffect(() => {
+    const mgr = managerRef.current;
+    const inited = initedTraitsRef.current;
+    for (const binding of traitBindings) {
+      const traitName = binding.trait.name;
+      if (inited.has(traitName)) continue;
+      const lifecycleEvent = LIFECYCLE_EVENTS.find(
+        (evt) => mgr.canHandleEvent(traitName, evt)
+      );
+      if (lifecycleEvent === void 0) continue;
+      inited.add(traitName);
+      stateLog.debug("mount:fire-lifecycle", { traitName, event: lifecycleEvent });
+      enqueueAndDrain(lifecycleEvent, {});
+    }
+    return () => {
+      initedTraitsRef.current = /* @__PURE__ */ new Set();
+    };
+  }, [traitBindings, enqueueAndDrain]);
   return {
     traitStates,
     sendEvent,