@almadar/ui 5.49.1 → 5.50.0

package/dist/runtime/index.js

@@ -41,14 +41,14 @@ import { DndContext, pointerWithin, rectIntersection, closestCorners, useSensors
 import { useSortable, arrayMove, sortableKeyboardCoordinates, SortableContext, rectSortingStrategy, verticalListSortingStrategy } from '@dnd-kit/sortable';
 import { CSS } from '@dnd-kit/utilities';
 import { useNodeId, ReactFlowProvider, Handle, Position } from '@xyflow/react';
-import * as THREE from 'three';
+import * as THREE3 from 'three';
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
 import { OBJLoader } from 'three/examples/jsm/loaders/OBJLoader.js';
 import { GLTFLoader as GLTFLoader$1 } from 'three/examples/jsm/loaders/GLTFLoader';
-import { Canvas, useThree } from '@react-three/fiber';
-import { Grid as Grid$1, OrbitControls } from '@react-three/drei';
+import { Canvas, useLoader, useFrame, useThree } from '@react-three/fiber';
+import { Billboard, Grid as Grid$1, OrbitControls } from '@react-three/drei';
 import { getPatternDefinition, getComponentForPattern as getComponentForPattern$1 } from '@almadar/patterns';
-import { StateMachineManager, createContextFromBindings, interpolateValue, collectDeclaredConfigDefaults, createServerEffectHandlers, EffectExecutor, InMemoryPersistence } from '@almadar/runtime';
+import { StateMachineManager, collectDeclaredConfigDefaults, createServerEffectHandlers, EffectExecutor, interpolateValue, createContextFromBindings, InMemoryPersistence } from '@almadar/runtime';
 import { OrbitalServerRuntime } from '@almadar/runtime/OrbitalServerRuntime';
 
 var __defProp = Object.defineProperty;
@@ -7053,6 +7053,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,
@@ -7073,12 +7119,8 @@ function Sprite({
 }) {
   const eventBus = useEventBus();
   const sourcePosition = 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 = useMemo(() => {
     const transforms = [
@@ -7126,6 +7168,7 @@ var init_Sprite = __esm({
   "components/game/atoms/Sprite.tsx"() {
     "use client";
     init_useEventBus();
+    init_spriteAnimation();
   }
 });
 function StateIndicator({
@@ -10517,6 +10560,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 = useRef(/* @__PURE__ */ new Map());
+  const loadingRef = useRef(/* @__PURE__ */ new Set());
+  const [pendingCount, setPendingCount] = useState(0);
+  const [, forceTick] = useState(0);
+  const animStatesRef = useRef(/* @__PURE__ */ new Map());
+  const lastTickRef = useRef(0);
+  const rafRef = useRef(0);
+  const atlasUrls = useMemo(() => {
+    const set = /* @__PURE__ */ new Set();
+    for (const unit of units) {
+      const url = unitAtlasUrl(unit);
+      if (url) set.add(url);
+    }
+    return [...set];
+  }, [units]);
+  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 = 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]);
+  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 = 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) {
@@ -10631,6 +10831,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 = useCallback((unitId) => {
+    return resolveUnitFrame?.(unitId) ?? resolveUnitFrameInternal(unitId);
+  }, [resolveUnitFrame, resolveUnitFrameInternal]);
   const features = useMemo(
     () => featuresProp.map((f3) => {
       if (f3.type) return f3;
@@ -10714,9 +10918,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);
   useEffect(() => {
     if (typeof window === "undefined") return;
@@ -11003,7 +11208,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;
@@ -11113,7 +11318,7 @@ function IsometricCanvas({
     resolveTerrainSpriteUrl,
     resolveFeatureSpriteUrl,
     resolveUnitSpriteUrl,
-    resolveUnitFrame,
+    resolveFrameForUnit,
     getImage,
     gridWidth,
     gridHeight,
@@ -11145,7 +11350,7 @@ function IsometricCanvas({
     };
   }, [selectedUnitId, units, scale, baseOffsetX, scaledTileWidth, scaledDiamondTopY, scaledFloorHeight, viewportSize, targetCameraRef]);
   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;
@@ -11161,7 +11366,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 = useCallback((e) => {
     if (enableCamera) {
       const wasPanning = handleMouseMove(e, () => draw(animTimeRef.current));
@@ -11306,6 +11511,7 @@ var init_IsometricCanvas = __esm({
     init_ErrorState();
     init_useImageCache();
     init_useCamera();
+    init_useUnitSpriteAtlas();
     init_verificationRegistry();
     init_isometric();
     IsometricCanvas.displayName = "IsometricCanvas";
@@ -28888,13 +29094,13 @@ var init_MapView = __esm({
         shadowSize: [41, 41]
       });
       L.Marker.prototype.options.icon = defaultIcon;
-      const { useEffect: useEffect80, useRef: useRef74, useCallback: useCallback118, useState: useState112 } = React81__default;
+      const { useEffect: useEffect81, useRef: useRef75, useCallback: useCallback119, useState: useState113 } = React81__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 = useRef74({ centerLat, centerLng, zoom });
-        useEffect80(() => {
+        const prevRef = useRef75({ centerLat, centerLng, zoom });
+        useEffect81(() => {
           const prev = prevRef.current;
           if (prev.centerLat !== centerLat || prev.centerLng !== centerLng || prev.zoom !== zoom) {
             map.setView([centerLat, centerLng], zoom);
@@ -28905,7 +29111,7 @@ var init_MapView = __esm({
       }
       function MapClickHandler({ onMapClick }) {
         const map = useMap();
-        useEffect80(() => {
+        useEffect81(() => {
           if (!onMapClick) return;
           const handler = (e) => {
             onMapClick(e.latlng.lat, e.latlng.lng);
@@ -28933,8 +29139,8 @@ var init_MapView = __esm({
         showAttribution = true
       }) {
         const eventBus = useEventBus4();
-        const [clickedPosition, setClickedPosition] = useState112(null);
-        const handleMapClick = useCallback118((lat, lng) => {
+        const [clickedPosition, setClickedPosition] = useState113(null);
+        const handleMapClick = useCallback119((lat, lng) => {
           if (showClickedPin) {
             setClickedPosition({ lat, lng });
           }
@@ -28943,7 +29149,7 @@ var init_MapView = __esm({
             eventBus.emit(`UI:${mapClickEvent}`, { latitude: lat, longitude: lng });
           }
         }, [onMapClick, mapClickEvent, eventBus, showClickedPin]);
-        const handleMarkerClick = useCallback118((marker) => {
+        const handleMarkerClick = useCallback119((marker) => {
           onMarkerClick?.(marker);
           if (markerClickEvent) {
             eventBus.emit(`UI:${markerClickEvent}`, { ...marker });
@@ -40661,7 +40867,7 @@ var init_AssetLoader = __esm({
         __publicField(this, "textureCache");
         __publicField(this, "loadingPromises");
         this.objLoader = new OBJLoader();
-        this.textureLoader = new THREE.TextureLoader();
+        this.textureLoader = new THREE3.TextureLoader();
         this.modelCache = /* @__PURE__ */ new Map();
         this.textureCache = /* @__PURE__ */ new Map();
         this.loadingPromises = /* @__PURE__ */ new Map();
@@ -40735,7 +40941,7 @@ var init_AssetLoader = __esm({
           return this.loadingPromises.get(`texture:${url}`);
         }
         const loadPromise = this.textureLoader.loadAsync(url).then((texture) => {
-          texture.colorSpace = THREE.SRGBColorSpace;
+          texture.colorSpace = THREE3.SRGBColorSpace;
           this.textureCache.set(url, texture);
           this.loadingPromises.delete(`texture:${url}`);
           return texture;
@@ -40809,7 +41015,7 @@ var init_AssetLoader = __esm({
         });
         this.modelCache.forEach((model) => {
           model.scene.traverse((child) => {
-            if (child instanceof THREE.Mesh) {
+            if (child instanceof THREE3.Mesh) {
               child.geometry.dispose();
               if (Array.isArray(child.material)) {
                 child.material.forEach((m) => m.dispose());
@@ -41365,7 +41571,7 @@ function ModelLoader({
     if (!loadedModel) return null;
     const cloned = loadedModel.clone();
     cloned.traverse((child) => {
-      if (child instanceof THREE.Mesh) {
+      if (child instanceof THREE3.Mesh) {
         child.castShadow = castShadow;
         child.receiveShadow = receiveShadow;
       }
@@ -41479,6 +41685,47 @@ function CameraController({
   }, [camera.position, onCameraChange]);
   return null;
 }
+function UnitSpriteBillboard({
+  sheetUrl,
+  resolveFrame,
+  height = 1.2
+}) {
+  const texture = useLoader(THREE3.TextureLoader, sheetUrl);
+  const meshRef = useRef(null);
+  const matRef = useRef(null);
+  const [aspect, setAspect] = useState(1);
+  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.NearestFilter;
+    texture.minFilter = THREE3.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__ */ jsxs("mesh", { ref: meshRef, position: [0, height / 2, 0], children: [
+    /* @__PURE__ */ jsx("planeGeometry", { args: [height * aspect, height] }),
+    /* @__PURE__ */ jsx(
+      "meshBasicMaterial",
+      {
+        ref: matRef,
+        map: texture,
+        transparent: true,
+        alphaTest: 0.1,
+        side: THREE3.DoubleSide
+      }
+    )
+  ] });
+}
 var DEFAULT_GRID_CONFIG, GameCanvas3D;
 var init_GameCanvas3D2 = __esm({
   "components/game/molecules/GameCanvas3D.tsx"() {
@@ -41489,6 +41736,7 @@ var init_GameCanvas3D2 = __esm({
     init_Canvas3DLoadingState2();
     init_Canvas3DErrorBoundary2();
     init_ModelLoader();
+    init_useUnitSpriteAtlas();
     init_cn();
     init_GameCanvas3D();
     DEFAULT_GRID_CONFIG = {
@@ -41545,8 +41793,10 @@ var init_GameCanvas3D2 = __esm({
         const controlsRef = useRef(null);
         const [hoveredTile, setHoveredTile] = useState(null);
         const [internalError, setInternalError] = useState(null);
+        const { sheetUrls: atlasSheetUrls, resolveUnitFrame } = useUnitSpriteAtlas(units);
+        const preloadUrls = useMemo(() => [...preloadAssets, ...atlasSheetUrls], [preloadAssets, atlasSheetUrls]);
         const { isLoading: assetsLoading, progress, loaded, total } = useAssetLoader({
-          preloadUrls: preloadAssets,
+          preloadUrls,
           loader: customAssetLoader
         });
         const eventHandlers = useGameCanvas3DEvents({
@@ -41605,7 +41855,7 @@ var init_GameCanvas3D2 = __esm({
           getCameraPosition: () => {
             if (controlsRef.current) {
               const pos = controlsRef.current.object.position;
-              return new THREE.Vector3(pos.x, pos.y, pos.z);
+              return new THREE3.Vector3(pos.x, pos.y, pos.z);
             }
             return null;
           },
@@ -41757,6 +42007,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__ */ jsxs(
               "group",
               {
@@ -41768,7 +42020,16 @@ var init_GameCanvas3D2 = __esm({
                     /* @__PURE__ */ jsx("ringGeometry", { args: [0.4, 0.5, 32] }),
                     /* @__PURE__ */ jsx("meshBasicMaterial", { color: "#ffff00", transparent: true, opacity: 0.8 })
                   ] }),
-                  unit.modelUrl ? (
+                  hasAtlas && initialFrame ? (
+                    /* Animated sprite-sheet billboard — single cropped frame, by state */
+                    /* @__PURE__ */ jsx(Billboard, { children: /* @__PURE__ */ jsx(
+                      UnitSpriteBillboard,
+                      {
+                        sheetUrl: initialFrame.sheetUrl,
+                        resolveFrame: () => resolveUnitFrame(unit.id)
+                      }
+                    ) })
+                  ) : unit.modelUrl ? (
                     /* GLB unit model (box fallback while loading / on error) */
                     /* @__PURE__ */ jsx(
                       ModelLoader,
@@ -41822,7 +42083,7 @@ var init_GameCanvas3D2 = __esm({
               }
             );
           },
-          [selectedUnitId, handleUnitClick]
+          [selectedUnitId, handleUnitClick, resolveUnitFrame]
         );
         const DefaultFeatureRenderer = useCallback(
           ({
@@ -51151,6 +51412,27 @@ init_verificationRegistry();
 var crossTraitLog = createLogger("almadar:ui:cross-trait");
 var flushLog = createLogger("almadar:ui:slot-flush");
 var stateLog = createLogger("almadar:ui:state-transitions");
+var tickLog = 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"
+]);
 function toTraitDefinition(binding) {
   return {
     name: binding.trait.name,
@@ -51347,50 +51629,196 @@ function useTraitStateMachine(traitBindings, uiSlots, options) {
       for (const unreg of snapshotUnregs) unreg();
     };
   }, [traitBindings]);
-  const runTickEffects = 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 = createContextFromBindings(bindingCtx);
-    if (tick.guard !== void 0) {
-      const passed = interpolateValue(tick.guard, evalCtx);
-      if (!passed) return;
-    }
+  const executeTransitionEffects = useCallback(async (params) => {
+    const { binding, previousState, newState, payload, flushEvent, syncOnly, log: log14 } = 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 = createContextFromBindings(bindingCtx);
-        const resolved = 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 = collectDeclaredConfigDefaults(binding.trait);
+      const sharedCallSite = binding.config;
+      if (sharedDeclared || sharedCallSite) {
+        sharedBindings.config = {
+          ...sharedDeclared ?? {},
+          ...sharedCallSite ?? {}
+        };
       }
+      const serverHandlers = 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;
+        log14.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 = 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 EffectExecutor({ handlers: trackingHandlers, bindings: bindingCtx, context: effectContext });
+    try {
+      await executor.executeAll(effects);
+      log14.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) {
+        log14.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) {
+      log14.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 = 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 = interpolateValue(tick.guard, 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]);
   useEffect(() => {
     const hasFrameTicks = traitBindingsRef.current.some(
       (b) => b.trait.ticks?.some((t) => t.interval === "frame")
@@ -51501,161 +51929,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 = collectDeclaredConfigDefaults(
-            binding.trait
-          );
-          const sharedCallSite = binding.config;
-          if (sharedDeclared || sharedCallSite) {
-            sharedBindings.config = {
-              ...sharedDeclared ?? {},
-              ...sharedCallSite ?? {}
-            };
-          }
-          const serverHandlers = 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 = 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 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", {