@almadar/std 16.178.0 → 16.179.0

package/behaviors/lolo/ui/core/molecules/ui-fx-overlay.lolo

@@ -0,0 +1,63 @@
+app ui-fx-overlay "1.0.0"
+"FxOverlay — UI factory (1:1 with the @almadar/ui fx-overlay pattern)."
+orbital FxOverlayOrbital {
+  type FxOverlayItemsItem = {
+    id : string!
+    type : string!
+    effect : "confetti" | "flash" | "shake" | "sparkle" | "float-text" | "streak-glow"
+    message : string
+    color : string
+    size : number
+    x : number
+    z : number
+    y : number
+    ttl : number!
+    maxTtl : number
+    bornAt : number
+    space : "world" | "screen"
+    particleCount : number
+    vx : number
+    vy : number
+    vz : number
+  }
+
+  entity FxOverlayItem [runtime] {
+    id : string!
+  }
+
+  trait FxOverlayRender -> @rebindable FxOverlayItem [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (render-ui main {
+          items: @config.items
+          tickMs: @config.tickMs
+          children: @config.children
+          className: @config.className
+          type: fx-overlay
+        })
+    }
+
+    config {
+      items : [FxOverlayItemsItem] = [{ id: "e1", x: 2, y: 2, type: "spawn", message: "Unit spawned" }, { id: "e2", x: 3, y: 1, type: "effect", message: "Attack landed" }]
+        @label "Items"
+        @description "Live screen-space fx entries (the mechanic's fx list filtered to `space == 'screen'`); mount starts each item's animation, ttl decay unmounts it."
+        @tier "presentation"
+      tickMs : number
+        @label "Tick Ms"
+        @description "The fx mechanic's decay tick period in ms; per-item animation duration = maxTtl × tickMs. Default 500."
+        @tier "presentation"
+      children : node
+        @label "Children"
+        @description "Wrapped content — the `shake` target and the overlay's bounds."
+        @tier "presentation"
+      className : string
+        @label "Class Name"
+        @description "Additional class names on the outermost element."
+        @tier "presentation"
+    }
+  }
+
+  page "/fx-overlay" as FxOverlayPage -> FxOverlayRender
+}

package/behaviors/lolo/ui/core/molecules/ui-page-header.lolo

@@ -94,7 +94,7 @@ orbital PageHeaderOrbital {
         @tier "presentation"
       status : PageHeaderStatus
         @label "Status"
-        @description "Status badge"
+        @description "Status badge — a bare string (an entity's status field bound directly, e.g. `status: @entity.status`) renders as a default-variant badge"
         @tier "presentation"
       actions : [PageHeaderActionsItem] = []
         @label "Actions"

package/behaviors/lolo/ui/core/organisms/ui-form-section.lolo

@@ -69,10 +69,10 @@ orbital FormSectionOrbital {
     message : string!
   }
   type FormSectionEvaluationContext = {
-    formValues : object!
+    formValues : Map string object!
     globalVariables : Map string json!
     localVariables : Map string json
-    entity : object
+    entity : Map string object
   }
   type FormSectionSectionsItem = {
     id : string!

package/behaviors/lolo/ui/core/organisms/ui-form.lolo

@@ -69,10 +69,10 @@ orbital FormOrbital {
     message : string!
   }
   type FormEvaluationContext = {
-    formValues : object!
+    formValues : Map string object!
     globalVariables : Map string json!
     localVariables : Map string json
-    entity : object
+    entity : Map string object
   }
   type FormSectionsItem = {
     id : string!

package/behaviors/lolo/ui/core/templates/ui-dashboard-layout.lolo

@@ -10,7 +10,7 @@ orbital DashboardLayoutOrbital {
   }
   type DashboardLayoutUser = {
     name : string!
-    email : string!
+    email : string
     avatar : asset
   }
   type DashboardLayoutTopBarActionsItem = {
@@ -98,7 +98,7 @@ orbital DashboardLayoutOrbital {
         @tier "presentation"
       user : DashboardLayoutUser
         @label "User"
-        @description "Current user info (optional - auto-populated from auth context if not provided)"
+        @description "Current user info (optional - auto-populated from auth context if not provided). Accepts `null` as well as `undefined`: the `.lolo` substrate's signed-out spelling is `(if @config.viewerName {…} null)`, and the compiled path passes that `null` through verbatim."
         @tier "presentation"
       headerActions : node
         @label "Header Actions"

package/behaviors/lolo/ui/game/atoms/std-fx-particles.lolo

@@ -1,5 +1,5 @@
-app std-fx-particles "1.0.0"
-"Headless floating-text/particle mechanic: decays each fx entry's ttl every tick and drops the dead ones, and appends spawned particles on BURST. Composed onto a [runtime, shared] game entity; renders nothing (the board owns the single render authority)."
+app std-fx-particles "1.1.0"
+"Headless transient-fx mechanic serving BOTH game boards and learning shells: appends spawned particles on BURST — stamping maxTtl (fade envelope) and bornAt (epoch ms, smooth render interpolation) when absent — decays each entry's ttl every tick, drops the dead ones, and clears on RESTART. Name-blind mechanism: the effect-kind vocabulary is consumer-declared (FxPreset tables at the render call sites). Composed onto a [runtime, shared] entity; renders nothing — the board/shell owns the single render authority (draw-fx-layer for space \"world\", fx-overlay for space \"screen\")."
 orbital FxParticlesOrbital {
   type Fx = {
     id : string!
@@ -9,6 +9,16 @@ orbital FxParticlesOrbital {
     y : number
     message : string
     ttl : number!
+    maxTtl : number
+    bornAt : number
+    space : string
+    effect : string
+    color : string
+    size : number
+    vx : number
+    vy : number
+    vz : number
+    particleCount : number
   }
 
   entity FxState [runtime, shared] {
@@ -21,9 +31,17 @@ orbital FxParticlesOrbital {
 
     state active {
       INIT -> active
-        (set @entity.fx @config.fx)
+        (set @entity.fx (array/map @config.fx (fn p (object/merge @p {
+          maxTtl: (if (object/get @p maxTtl) (object/get @p maxTtl) (object/get @p ttl))
+          bornAt: (if (object/get @p bornAt) (object/get @p bornAt) (time/now))
+        }))))
       BURST -> active
-        (set @entity.fx (array/concat @entity.fx @payload.particles))
+        (set @entity.fx (array/concat @entity.fx (array/map @payload.particles (fn p (object/merge @p {
+          maxTtl: (if (object/get @p maxTtl) (object/get @p maxTtl) (object/get @p ttl))
+          bornAt: (if (object/get @p bornAt) (object/get @p bornAt) (time/now))
+        })))))
+      RESTART -> active
+        (set @entity.fx [])
     }
 
     ticks {
@@ -36,6 +54,7 @@ orbital FxParticlesOrbital {
 
     listens {
       BURST { particles : [Fx] }
+      RESTART { }
     }
 
     config {

package/behaviors/lolo/ui/game/atoms/std-platformer-body.lolo

@@ -0,0 +1,251 @@
+app std-platformer-body "1.0.0"
+"Headless run/jump platformer-physics authority: the SOLE writer of body + fell + hazardId + goalId on side-view boards. Where std-motion-body owns free 2D drift (no collision), this atom owns the platformer contract: every 33ms physics tick it integrates gravity into the body's vertical velocity, steps position in per-second units, and collides the body rect against the config platforms with one-way semantics — a body moving in the gravity direction that overlaps a ground/platform tile lands on its anti-gravity face (vy zeroed, grounded set), while a body moving against gravity passes through, so jumping up through a platform and walking up a staircase both just work. The sign of gravity IS the vertical convention: positive pulls toward +y (screen boards, y down — sprite canvases), negative toward −y (math canvases, y up); jumps always fire against it. Intents: STEER sets horizontal velocity (dir −1/0/1 × moveSpeed, hold-to-run: keydown steers, keyup steers 0), JUMP kicks vertical velocity when grounded, PLACE teleports (spawns, hazard respawns), RESTART reseeds. Emits BODY_MOVED every tick for the render layer (boards that don't subscribe pay nothing), plus the sparse rule signals a board needs to score: BODY_JUMPED, BODY_LANDED (with impact speed), BODY_HAZARD (once per hazard entry, re-arms on exit), BODY_GOAL (same arming), BODY_FELL (once per fall past killY, re-armed by PLACE/RESTART). Curve skating: when config.skate is on and the grounded body comes within skateSnap of the config.skateCurve surface, the body rides the curve — y snaps to the interpolated surface and tangential gravity (g·slope/(1+slope²)) accelerates vx, so the body slides downhill along the graph itself and launches ballistically off its ends; jumping kicks free. Sparse BODY_SKATE_START/BODY_SKATE_END signals fire on engage/disengage so boards can layer fx. Lives, score, and win/lose stay downstream — this atom simulates, it never judges. Renders nothing."
+orbital PlatformerBodyOrbital {
+  type PlatformerBody = {
+    x : number!
+    y : number!
+    width : number!
+    height : number!
+    vx : number
+    vy : number
+    grounded : boolean
+    facingRight : boolean
+  }
+  type PlatformerPlatform = {
+    id : string
+    x : number!
+    y : number!
+    width : number!
+    height : number!
+    type : "ground" | "platform" | "hazard" | "goal"
+  }
+  type PlatformerCurveSample = {
+    x : number!
+    y : number!
+  }
+
+  entity PlatformerBodyData [runtime, shared] {
+    id : string!
+    body : PlatformerBody = { x: 0, y: 0, width: 1, height: 1, vx: 0, vy: 0, grounded: false, facingRight: true }
+    fell : boolean = false
+    hazardId : string = ""
+    goalId : string = ""
+    skating : boolean = false
+  }
+
+  trait PlatformerBody -> @rebindable PlatformerBodyData [lifecycle] {
+    initial: active
+
+    state active {
+      INIT -> active
+        (set @entity.body @config.spawn)
+        (set @entity.fell false)
+        (set @entity.hazardId "")
+        (set @entity.goalId "")
+        (set @entity.skating false)
+
+      STEER -> active when @config.running
+        (set @entity.body (object/merge @entity.body { vx: (* @payload.dir @config.moveSpeed), facingRight: (if (!= @payload.dir 0) (> @payload.dir 0) @entity.body.facingRight) }))
+
+      JUMP -> active when (and @config.running (== @entity.body.grounded true))
+        (set @entity.body (object/merge @entity.body { vy: (if (> @config.gravity 0) (- 0 @config.jumpStrength) @config.jumpStrength), grounded: false }))
+        (emit BODY_JUMPED { x: @entity.body.x, y: @entity.body.y })
+
+      PLACE -> active
+        (set @entity.body (object/merge @entity.body { x: @payload.x, y: @payload.y, vx: 0, vy: 0, grounded: false }))
+        (set @entity.fell false)
+        (set @entity.hazardId "")
+        (set @entity.skating false)
+
+      RESTART -> active
+        (set @entity.body @config.spawn)
+        (set @entity.fell false)
+        (set @entity.hazardId "")
+        (set @entity.goalId "")
+        (set @entity.skating false)
+    }
+
+    ticks {
+      physicsTick every 33ms
+        when (and @config.running (> @entity.body.width 0))
+        (let ((gdir (if (> @config.gravity 0) 1 -1)))
+        (let ((vy1 (math/clamp (+ @entity.body.vy (* @config.gravity 0.033)) (- 0 @config.maxFallSpeed) @config.maxFallSpeed)))
+        (let ((bw (object/get @entity.body width)) (bh (object/get @entity.body height)))
+        (let ((nx (math/clamp (+ @entity.body.x (* @entity.body.vx 0.033)) @config.xMin @config.xMax)))
+        (let ((ny (+ @entity.body.y (* @vy1 0.033))))
+        (let ((rect { x: @nx, y: @ny, w: @bw, h: @bh }))
+        (let ((hit (array/find @config.platforms (fn p (and (or (== (object/get @p type) "ground") (== (object/get @p type) "platform")) (geo/aabb-overlap @rect { x: @p.x, y: @p.y, w: @p.width, h: @p.height }))))))
+        (let ((landed (and (!= @hit null) (> (* @vy1 @gdir) 0))))
+        (let ((ny2 (if @landed (if (> @gdir 0) (- (object/get @hit y) @bh) (+ (object/get @hit y) (object/get @hit height))) @ny)) (vy2 (if @landed 0 @vy1)))
+        (let ((cx (+ @nx (/ @bw 2))))
+        (let ((inRange (and @config.skate (and (> (array/len @config.skateCurve) 1) (and (>= @cx (object/get (array/first @config.skateCurve) x)) (< @cx (object/get (array/last @config.skateCurve) x)))))))
+        (let ((leftSamp (if @inRange (array/last (array/filter @config.skateCurve (fn s (<= (object/get @s x) @cx)))) { x: 0, y: 0 })))
+        (let ((rightSamp (if @inRange (array/first (array/filter @config.skateCurve (fn s (> (object/get @s x) @cx)))) { x: 1, y: 0 })))
+        (let ((slope (if @inRange (/ (- (object/get @rightSamp y) (object/get @leftSamp y)) (- (object/get @rightSamp x) (object/get @leftSamp x))) 0)))
+        (let ((curveY (if @inRange (+ (object/get @leftSamp y) (* @slope (- @cx (object/get @leftSamp x)))) 0)))
+        (let ((movingUp (< (* @vy1 @gdir) -0.01)))
+        (let ((skateNow (and @inRange (and (<= (math/abs (- @ny2 @curveY)) @config.skateSnap) (and (or @landed @entity.skating) (or @entity.body.grounded (not @movingUp)))))))
+        (let ((vx2 (if @skateNow (math/clamp (+ @entity.body.vx (* (/ (* @config.gravity @slope) (+ 1 (* @slope @slope))) 0.033)) (- 0 @config.maxFallSpeed) @config.maxFallSpeed) @entity.body.vx)))
+        (let ((fy (if @skateNow @curveY @ny2)) (fvy (if @skateNow (* @slope @vx2) @vy2)) (fgrounded (or @landed @skateNow)))
+        (let ((hazardHit (array/find @config.platforms (fn p (and (== (object/get @p type) "hazard") (geo/aabb-overlap @rect { x: @p.x, y: @p.y, w: @p.width, h: @p.height }))))))
+        (let ((goalHit (array/find @config.platforms (fn p (and (== (object/get @p type) "goal") (geo/aabb-overlap @rect { x: @p.x, y: @p.y, w: @p.width, h: @p.height }))))))
+        (let ((fellNow (if (> @gdir 0) (> @fy @config.killY) (< @fy @config.killY))))
+          (do
+            (set @entity.body (object/merge @entity.body { x: @nx, y: @fy, vx: (if (or (== @nx @config.xMin) (== @nx @config.xMax)) 0 @vx2), vy: @fvy, grounded: @fgrounded }))
+            (set @entity.skating @skateNow)
+            (if (and @skateNow (== @entity.skating false))
+              (emit BODY_SKATE_START { x: @nx, y: @fy, slope: @slope })
+              null)
+            (if (and (== @skateNow false) (== @entity.skating true))
+              (emit BODY_SKATE_END { x: @nx, y: @fy })
+              null)
+            (if (and @landed (== @entity.body.grounded false))
+              (emit BODY_LANDED { x: @nx, y: @fy, impact: (* @vy1 @gdir) })
+              null)
+            (if (!= @hazardHit null)
+              (if (!= @entity.hazardId (object/get @hazardHit "id" ""))
+                (do
+                  (set @entity.hazardId (object/get @hazardHit "id" ""))
+                  (emit BODY_HAZARD { id: (object/get @hazardHit "id" ""), x: @nx, y: @fy }))
+                null)
+              (set @entity.hazardId ""))
+            (if (!= @goalHit null)
+              (if (!= @entity.goalId (object/get @goalHit "id" ""))
+                (do
+                  (set @entity.goalId (object/get @goalHit "id" ""))
+                  (emit BODY_GOAL { id: (object/get @goalHit "id" ""), x: @nx, y: @fy }))
+                null)
+              (set @entity.goalId ""))
+            (if (and @fellNow (== @entity.fell false))
+              (do
+                (set @entity.fell true)
+                (emit BODY_FELL { x: @nx, y: @fy }))
+              null)
+            (emit BODY_MOVED { x: @nx, y: @fy, vx: @entity.body.vx, vy: @fvy, grounded: @fgrounded, skating: @skateNow, speed: (math/hypot @entity.body.vx @fvy) }))))))))))))))))))))))))
+    }
+
+    emits {
+      BODY_MOVED -> external {
+        x : number!
+        y : number!
+        vx : number!
+        vy : number!
+        grounded : boolean!
+        skating : boolean!
+        speed : number!
+      }
+        @description "The body after this physics tick: position, velocity, grounded and skating flags, and scalar speed; render layers subscribe (or read the shared entity), rule layers stay on the sparse signals"
+        @tier "domain"
+      BODY_SKATE_START -> external {
+        x : number!
+        y : number!
+        slope : number!
+      }
+        @description "Body engaged curve skating this tick (grounded within skateSnap of the skateCurve surface); slope is the local dy/dx — boards layer fx and equation readouts"
+        @tier "domain"
+      BODY_SKATE_END -> external {
+        x : number!
+        y : number!
+      }
+        @description "Body left the curve surface (jumped, walked past an end, or drifted beyond skateSnap); boards tear down skate fx"
+        @tier "domain"
+      BODY_JUMPED -> external {
+        x : number!
+        y : number!
+      }
+        @description "Jump accepted (grounded at intent time) and vertical velocity kicked against gravity; boards layer squash/sound fx"
+        @tier "domain"
+      BODY_LANDED -> external {
+        x : number!
+        y : number!
+        impact : number!
+      }
+        @description "Body transitioned airborne → standing on a ground/platform tile this tick; impact is the pre-landing fall speed in units/s so boards can scale dust or damage"
+        @tier "domain"
+      BODY_HAZARD -> external {
+        id : string!
+        x : number!
+        y : number!
+      }
+        @description "Body entered overlap with a hazard tile; fires once per entry and re-arms only after the body leaves, so damage rules stay sparse"
+        @tier "domain"
+      BODY_GOAL -> external {
+        id : string!
+        x : number!
+        y : number!
+      }
+        @description "Body entered overlap with a goal tile; fires once per entry and re-arms only after the body leaves — the board's win-rule trigger"
+        @tier "domain"
+      BODY_FELL -> external {
+        x : number!
+        y : number!
+      }
+        @description "Body crossed killY in the gravity direction (pit fall); fires once per fall and re-arms on PLACE/RESTART, leaving the respawn rule to the board"
+        @tier "domain"
+    }
+
+    listens {
+      STEER { dir : number! }
+      JUMP { id : string }
+      PLACE { x : number!, y : number! }
+      RESTART { id : string }
+    }
+
+    config {
+      running : boolean = true
+        @label "Running"
+        @description "When true the 33ms physics tick integrates and collides; toggle to freeze the body"
+        @tier "domain"
+      spawn : PlatformerBody = { x: 2, y: 8, width: 0.6, height: 0.6, vx: 0, vy: 0, grounded: false, facingRight: true }
+        @label "Spawn Body"
+        @description "Initial body rect (min-corner x/y plus width/height) seeded on INIT/RESTART; width/height also define the collision box"
+        @tier "domain"
+      platforms : [PlatformerPlatform] = []
+        @label "Platforms"
+        @description "Level geometry as min-corner rects: ground/platform tiles are solid one-way landing surfaces, hazard tiles emit BODY_HAZARD on touch, goal tiles emit BODY_GOAL"
+        @tier "domain"
+      gravity : number = 24
+        @label "Gravity"
+        @description "Units/s² added to vertical velocity; the SIGN is the vertical convention — positive pulls toward +y (screen boards, y down), negative toward −y (math canvases, y up) — and jumps always fire against it"
+        @tier "domain"
+      jumpStrength : number = 11
+        @label "Jump Strength"
+        @description "Vertical speed in units/s imparted by JUMP, directed against gravity; apex height ≈ jumpStrength² / (2·|gravity|)"
+        @tier "domain"
+      moveSpeed : number = 5
+        @label "Move Speed"
+        @description "Horizontal run speed in units/s applied by STEER dir ±1"
+        @tier "domain"
+      maxFallSpeed : number = 14
+        @label "Max Fall Speed"
+        @description "Terminal velocity cap in units/s applied to vertical speed each tick"
+        @tier "presentation"
+      xMin : number = -1000000
+        @label "Left Wall"
+        @description "Smallest x the body's min corner may hold (world bounds, not level geometry)"
+        @tier "presentation"
+      xMax : number = 1000000
+        @label "Right Wall"
+        @description "Largest x the body's min corner may hold (world bounds, not level geometry)"
+        @tier "presentation"
+      killY : number = 1000000
+        @description "Fall line: crossing it in the gravity direction fires BODY_FELL once (past it downward on y-down boards, below it on y-up canvases); y-up consumers must set a value below their world floor"
+        @label "Kill Y"
+        @tier "domain"
+      skate : boolean = false
+        @label "Curve Skating"
+        @description "When true, a grounded body within skateSnap of the skateCurve surface rides the curve: y snaps to the interpolated surface and tangential gravity (g·slope/(1+slope²)) accelerates vx, so the body slides downhill along the graph and launches off its ends; JUMP kicks free"
+        @tier "domain"
+      skateCurve : [PlatformerCurveSample] = []
+        @label "Skate Curve"
+        @description "Surface samples (x strictly increasing) the body skates when skate is on; y is the surface height for the body's MIN corner, linearly interpolated between bracketing samples — mirror the render-side curve so what you see is what you ride"
+        @tier "domain"
+      skateSnap : number = 0.75
+        @label "Skate Snap"
+        @description "Max vertical gap (world units) between the body's min corner and the curve surface for skating to engage or stay engaged; larger values grab earlier on landing, smaller values release sooner on bumps"
+        @tier "domain"
+    }
+  }
+
+  page "/platformer-body" as PlatformerBodyPage -> PlatformerBody
+}

package/behaviors/lolo/ui/game/atoms/ui-draw-fx-layer.lolo

@@ -0,0 +1,109 @@
+app ui-draw-fx-layer "1.0.0"
+"DrawFxLayer — UI factory (1:1 with the @almadar/ui draw-fx-layer pattern)."
+orbital DrawFxLayerOrbital {
+  type DrawFxLayerItemsItem = {
+    id : string!
+    type : string!
+    position : DrawFxLayerItemsItemPosition
+    x : number!
+    z : number
+    y : number
+    message : string
+    ttl : number!
+    maxTtl : number
+    bornAt : number
+    space : "world" | "screen"
+    effect : "confetti" | "flash" | "shake" | "sparkle" | "float-text" | "streak-glow"
+    color : string
+    size : number
+    vx : number
+    vy : number
+    vz : number
+    particleCount : number
+  }
+  type DrawFxLayerItemsItemPosition = {
+    x : number!
+    y : number!
+    z : number
+  }
+  type DrawFxLayerPresetsItem = {
+    type : string!
+    color : string
+    color2 : string
+    size : number
+    shape : "spark" | "ring" | "puff" | "streak"
+    count : number
+    glow : number
+    gravity : number
+    vx : number
+    vy : number
+    vz : number
+    space : "world" | "screen"
+    effect : "confetti" | "flash" | "shake" | "sparkle" | "float-text" | "streak-glow"
+    particleCount : number
+  }
+  type DrawFxLayerSpritesValue = {
+    url : asset!
+    role : string!
+    category : string!
+    animations : [string]
+    style : "pixel" | "vector" | "hd" | "1-bit" | "isometric"
+    variant : string
+    dimension : "2d" | "3d"
+    aspect : "1:1" | "16:9" | "5:7" | "8:1"
+    atlas : asset
+    sprite : string
+    name : string
+    thumbnailUrl : string
+  }
+
+  entity DrawFxLayerItem [runtime] {
+    id : string!
+  }
+
+  trait DrawFxLayerRender -> @rebindable DrawFxLayerItem [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (render-ui main {
+          items: @config.items
+          presets: @config.presets
+          art: @config.art
+          sprites: @config.sprites
+          tickMs: @config.tickMs
+          textColor: @config.textColor
+          type: draw-fx-layer
+        })
+    }
+
+    config {
+      items : [DrawFxLayerItemsItem] = [{ id: "e1", x: 2, y: 2, type: "spawn", message: "Unit spawned" }, { id: "e2", x: 3, y: 1, type: "effect", message: "Attack landed" }]
+        @label "Items"
+        @description "The live fx entries — the mechanic's `@entity.fx` list passed whole; `space: 'screen'` entries are skipped (the overlay owns those)."
+        @tier "presentation"
+      presets : [DrawFxLayerPresetsItem] = []
+        @label "Presets"
+        @description "Consumer-declared effect vocabulary — one row per fx `type` (look + recipe). Unknown types fall back to a neutral spark burst."
+        @tier "presentation"
+      art : Map string Map string [object] = { item: {} }
+        @label "Art"
+        @description "Vector art per fx type (an asset-art map: type → anim-state → drawables); a type's `idle` state wins over sprites/procedural."
+        @tier "presentation"
+      sprites : Map string DrawFxLayerSpritesValue = { item: { url: "https://almadar-kflow-assets.web.app/shared/ui-roguelike-board/default/features/sword.png", role: "item", category: "item", animations: ["static"], style: "pixel", dimension: "2d", aspect: "1:1", name: "item", thumbnailUrl: "" } }
+        @label "Sprites"
+        @description "Sprite asset per fx type (an asset-manifest effects map) — used when no vector art matches."
+        @tier "presentation"
+      tickMs : number
+        @label "Tick Ms"
+        @description "The fx mechanic's decay tick period in ms; lifetime = maxTtl × tickMs. Default 500."
+        @tier "presentation"
+      textColor : string
+        @label "Text Color"
+        @description "Floating-message text color when an item declares none. Default `#ffe066`."
+        @tier "presentation"
+    }
+  }
+
+  page "/draw-fx-layer" as DrawFxLayerPage -> DrawFxLayerRender
+}

package/behaviors/lolo/ui/game/organisms/std-arcade-board-3d.lolo

@@ -50,6 +50,32 @@ orbital ArcadeBoard3DFrameOrbital {
     y : number
     message : string
     ttl : number!
+    maxTtl : number
+    bornAt : number
+    space : string
+    effect : string
+    color : string
+    size : number
+    vx : number
+    vy : number
+    vz : number
+    particleCount : number
+  }
+  type FxPreset = {
+    type : string!
+    color : string
+    color2 : string
+    size : number
+    shape : string
+    count : number
+    glow : number
+    gravity : number
+    vx : number
+    vy : number
+    vz : number
+    space : string
+    effect : string
+    particleCount : number
   }
   type ValidMove = { x : number!  z : number! }
   type Machine = {
@@ -159,7 +185,7 @@ orbital ArcadeBoard3DFrameOrbital {
             { type: draw-shape-layer, items: (array/map @entity.units (fn u { type: draw-shape, shape: "rect", position: { x: (object/get (object/get @u position) x), y: (object/get (object/get @u position) y), z: (object/get @u z) }, offsetY: -0.6, width: 0.8, height: 0.12, fill: "rgba(0,0,0,0.6)" })) }
             { type: draw-shape-layer, items: (array/map @entity.units (fn u { type: draw-shape, shape: "rect", position: { x: (object/get (object/get @u position) x), y: (object/get (object/get @u position) y), z: (object/get @u z) }, offsetY: -0.6, width: (* 0.8 (/ (object/get @u health) (object/get @u maxHealth))), height: 0.12, fill: "#22c55e" })) }
             { type: draw-text-layer, items: (array/map @entity.units (fn u { type: draw-text, text: (object/get @u name), position: { x: (object/get (object/get @u position) x), y: (object/get (object/get @u position) y), z: (object/get @u z) }, offsetY: -0.85, color: "#ffffff" })) }
-            { type: draw-text-layer, items: (array/map @entity.fx (fn f { type: draw-text, text: (object/get @f message), position: { x: (object/get @f x), y: (object/get @f y), z: (object/get @f z) }, color: "#ffe066" })) }
+            { type: draw-fx-layer, items: @entity.fx, tickMs: 500, presets: @config.fxPresets }
           ] } ]
         })
 
@@ -205,7 +231,7 @@ orbital ArcadeBoard3DFrameOrbital {
             { type: draw-shape-layer, items: (array/map @entity.units (fn u { type: draw-shape, shape: "rect", position: { x: (object/get (object/get @u position) x), y: (object/get (object/get @u position) y), z: (object/get @u z) }, offsetY: -0.6, width: 0.8, height: 0.12, fill: "rgba(0,0,0,0.6)" })) }
             { type: draw-shape-layer, items: (array/map @entity.units (fn u { type: draw-shape, shape: "rect", position: { x: (object/get (object/get @u position) x), y: (object/get (object/get @u position) y), z: (object/get @u z) }, offsetY: -0.6, width: (* 0.8 (/ (object/get @u health) (object/get @u maxHealth))), height: 0.12, fill: "#22c55e" })) }
             { type: draw-text-layer, items: (array/map @entity.units (fn u { type: draw-text, text: (object/get @u name), position: { x: (object/get (object/get @u position) x), y: (object/get (object/get @u position) y), z: (object/get @u z) }, offsetY: -0.85, color: "#ffffff" })) }
-            { type: draw-text-layer, items: (array/map @entity.fx (fn f { type: draw-text, text: (object/get @f message), position: { x: (object/get @f x), y: (object/get @f y), z: (object/get @f z) }, color: "#ffe066" })) }
+            { type: draw-fx-layer, items: @entity.fx, tickMs: 500, presets: @config.fxPresets }
           ] } ]
         })
 
@@ -315,6 +341,10 @@ orbital ArcadeBoard3DFrameOrbital {
         @label "Features"
         @description "Arcade machines + decorations rendered on the board (static; matched against machines for playability)."
         @tier "presentation"
+      fxPresets : [FxPreset] = [ { type: "score", color: "#ffd23f", color2: "#ff6b35", size: 0.55, shape: "spark", count: 7, glow: 0.16, vy: -0.3 }, { type: "info", color: "#38bdf8", color2: "#0c4a6e", size: 0.4, shape: "puff", count: 4 } ]
+        @label "Fx Presets"
+        @description "This board's effect vocabulary — one look/recipe row per fx type its mechanics emit; unknown types fall back to a neutral spark."
+        @tier "presentation"
       assetManifest : AssetManifest = { terrains: {}, units: {}, features: {}, effects: {} }
         @label "Asset Manifest"
         @description "Per-role model manifest resolving tile/unit/feature models by terrain/category key."

package/behaviors/lolo/ui/game/organisms/std-crew-board-2d.lolo

@@ -48,6 +48,32 @@ orbital CrewBoard2DOrbital {
     y : number
     message : string
     ttl : number!
+    maxTtl : number
+    bornAt : number
+    space : string
+    effect : string
+    color : string
+    size : number
+    vx : number
+    vy : number
+    vz : number
+    particleCount : number
+  }
+  type FxPreset = {
+    type : string!
+    color : string
+    color2 : string
+    size : number
+    shape : string
+    count : number
+    glow : number
+    gravity : number
+    vx : number
+    vy : number
+    vz : number
+    space : string
+    effect : string
+    particleCount : number
   }
   type ValidMove = { x : number!  z : number! }
   type Feature = {
@@ -141,7 +167,7 @@ orbital CrewBoard2DOrbital {
             { type: draw-shape-layer, items: (array/map @entity.units (fn u { type: draw-shape, shape: "rect", position: (object/get @u position), anchor: "ground", offsetX: -0.25, offsetY: -0.6, width: 0.5, height: 0.12, fill: "rgba(0,0,0,0.6)" })) }
             { type: draw-shape-layer, items: (array/map @entity.units (fn u { type: draw-shape, shape: "rect", position: (object/get @u position), anchor: "ground", offsetX: -0.25, offsetY: -0.6, width: (* 0.5 (/ (object/get @u health) (object/get @u maxHealth))), height: 0.12, fill: "#22c55e" })) }
             { type: draw-text-layer, items: (array/map @entity.units (fn u { type: draw-text, text: (object/get @u name), position: (object/get @u position), offsetY: -0.85, color: "#ffffff" })) }
-            { type: draw-text-layer, items: (array/map @entity.fx (fn f { type: draw-text, text: (object/get @f message), position: { x: (object/get @f x), y: (object/get @f y) }, color: "#ffe066" })) }
+            { type: draw-fx-layer, items: @entity.fx, tickMs: 500, presets: @config.fxPresets, sprites: (object/get @config.assetManifest effects) }
             { type: draw-sprite-layer, items: (array/map (array/filter (array/flatten (array/map @entity.units (fn u (array/flatten (array/map [ ["idle", 4], ["walk", 2], ["attack", 1], ["hit", 1], ["death", 1] ] (fn st (array/map (array/range 0 (array/nth @st 1)) (fn i (if (and (object/get (object/get @u modelUrl) url) (str/includes (object/get (object/get @u modelUrl) url) ".svg")) (str/concat (array/nth (str/split (object/get (object/get @u modelUrl) url) ".svg") 0) (str/concat "." (str/concat (array/nth @st 0) (str/concat "-" (str/concat @i ".svg"))))) ""))))))))) (fn w (!= @w ""))) (fn warmUrl { type: draw-sprite, position: { x: 0, y: 0 }, asset: { url: @warmUrl }, opacity: 0, width: 0.5, height: 0.5 })) }
           ] } ]
         })
@@ -193,7 +219,7 @@ orbital CrewBoard2DOrbital {
             { type: draw-shape-layer, items: (array/map @entity.units (fn u { type: draw-shape, shape: "rect", position: (object/get @u position), anchor: "ground", offsetX: -0.25, offsetY: -0.6, width: 0.5, height: 0.12, fill: "rgba(0,0,0,0.6)" })) }
             { type: draw-shape-layer, items: (array/map @entity.units (fn u { type: draw-shape, shape: "rect", position: (object/get @u position), anchor: "ground", offsetX: -0.25, offsetY: -0.6, width: (* 0.5 (/ (object/get @u health) (object/get @u maxHealth))), height: 0.12, fill: "#22c55e" })) }
             { type: draw-text-layer, items: (array/map @entity.units (fn u { type: draw-text, text: (object/get @u name), position: (object/get @u position), offsetY: -0.85, color: "#ffffff" })) }
-            { type: draw-text-layer, items: (array/map @entity.fx (fn f { type: draw-text, text: (object/get @f message), position: { x: (object/get @f x), y: (object/get @f y) }, color: "#ffe066" })) }
+            { type: draw-fx-layer, items: @entity.fx, tickMs: 500, presets: @config.fxPresets, sprites: (object/get @config.assetManifest effects) }
             { type: draw-sprite-layer, items: (array/map (array/filter (array/flatten (array/map @entity.units (fn u (array/flatten (array/map [ ["idle", 4], ["walk", 2], ["attack", 1], ["hit", 1], ["death", 1] ] (fn st (array/map (array/range 0 (array/nth @st 1)) (fn i (if (and (object/get (object/get @u modelUrl) url) (str/includes (object/get (object/get @u modelUrl) url) ".svg")) (str/concat (array/nth (str/split (object/get (object/get @u modelUrl) url) ".svg") 0) (str/concat "." (str/concat (array/nth @st 0) (str/concat "-" (str/concat @i ".svg"))))) ""))))))))) (fn w (!= @w ""))) (fn warmUrl { type: draw-sprite, position: { x: 0, y: 0 }, asset: { url: @warmUrl }, opacity: 0, width: 0.5, height: 0.5 })) }
           ] } ]
         })
@@ -250,6 +276,10 @@ orbital CrewBoard2DOrbital {
         @label "Features"
         @description "Decorative environment features (e.g. consoles) drawn on the board."
         @tier "presentation"
+      fxPresets : [FxPreset] = []
+        @label "Fx Presets"
+        @description "This board's effect vocabulary — one look/recipe row per fx type; its composed mechanics currently emit none, so the channel is forward-compat only."
+        @tier "presentation"
       assetManifest : AssetManifest = { terrains: {}, units: {}, features: {}, effects: {} }
         @label "Asset Manifest"
         @description "Terrain/unit/feature/effect sprite manifest."