@almadar/std 16.182.0 → 16.184.0

package/behaviors/lolo/ui/game/atoms/std-gate-lock.lolo

@@ -0,0 +1,96 @@
+app std-gate-lock "1.0.0"
+"Headless collectible-gate mechanic: doors that stay shut until the player's collected total reaches their cost. Listens COLLECT (the board's running total — stars, coins, keys) and flips every door whose cost is met, stamping open on the shared door rows and emitting GATE_OPENED for the first newly opened door (the shared entity is the render authority for the rest). While a closed door's rect contains the player it emits GATE_BLOCKED once per approach — re-arming only after the player steps out — so the board can answer with a PLACE back and a locked fx. RESTART re-locks every door and zeroes the total. Renders nothing; boards draw closed doors as bars/walls and open ones as gaps."
+orbital GateLockOrbital {
+  type Door = {
+    id : string!
+    x : number!
+    y : number!
+    width : number!
+    height : number!
+    cost : number!
+    open : boolean
+    touching : boolean
+    blocked : boolean
+  }
+
+  entity GateLockData [runtime, shared] {
+    id : string!
+    doors : [Door] = []
+    total : number = 0
+  }
+
+  trait GateLock -> @rebindable GateLockData [lifecycle] {
+    initial: active
+
+    state active {
+      INIT -> active
+        (set @entity.doors (array/map @config.doors (fn d (object/merge @d { open: false, touching: false, blocked: false }))))
+        (set @entity.total 0)
+
+      COLLECT -> active when @config.running
+        (set @entity.total @payload.total)
+        (let ((newly (array/filter @entity.doors (fn d (and (== (object/get @d open) false) (<= (object/get @d cost) @payload.total))))))
+        (if (> (array/len @newly) 0)
+          (do
+            (set @entity.doors (array/map @entity.doors (fn d (if (and (== (object/get @d open) false) (<= (object/get @d cost) @payload.total)) (object/merge @d { open: true }) @d))))
+            (emit GATE_OPENED { id: (object/get (array/first @newly) id), cost: (object/get (array/first @newly) cost) }))
+          null))
+
+      BODY_MOVED -> active when @config.running
+        (set @entity.doors (array/map @entity.doors (fn d
+          (let ((inside (and (== (object/get @d open) false)
+                             (and (>= @payload.x (- (object/get @d x) @config.reachMargin))
+                                  (and (<= @payload.x (+ (object/get @d x) (object/get @d width) @config.reachMargin))
+                                       (and (>= @payload.y (- (object/get @d y) @config.reachMargin))
+                                            (<= @payload.y (+ (object/get @d y) (object/get @d height) @config.reachMargin))))))))
+            (object/merge @d { touching: @inside, blocked: (and @inside (== (object/get @d touching) false)) })))))
+        (let ((blocked (array/filter @entity.doors (fn d (== (object/get @d blocked) true)))))
+        (if (> (array/len @blocked) 0)
+          (emit GATE_BLOCKED { id: (object/get (array/first @blocked) id), x: (object/get (array/first @blocked) x), y: (object/get (array/first @blocked) y) })
+          null))
+
+      RESTART -> active
+        (set @entity.doors (array/map @config.doors (fn d (object/merge @d { open: false, touching: false, blocked: false }))))
+        (set @entity.total 0)
+    }
+
+    emits {
+      GATE_OPENED -> external {
+        id : string!
+        cost : number!
+      }
+        @description "A door's cost was reached by the collected total and it flipped open; boards layer unlock fx. When several doors open on one total, the first reports and the shared entity carries the rest."
+        @tier "domain"
+      GATE_BLOCKED -> external {
+        id : string!
+        x : number!
+        y : number!
+      }
+        @description "The player is inside a closed door's rect; fires once per approach and re-arms after they step out. Boards answer with a PLACE back plus a locked fx."
+        @tier "domain"
+    }
+
+    listens {
+      COLLECT { total : number! }
+      BODY_MOVED { x : number!, y : number!, vx : number!, vy : number!, grounded : boolean!, skating : boolean!, speed : number! }
+      RESTART { id : string }
+    }
+
+    config {
+      running : boolean = true
+        @label "Running"
+        @description "When true, COLLECT opens doors and closed doors report contact; toggle to freeze every door as-is."
+        @tier "domain"
+      doors : [Door] = []
+        @label "Doors"
+        @description "One row per gate: id, min-corner rect (x, y, width, height in world units) and the collected total that opens it. open/touching are stamped at runtime."
+        @tier "domain"
+      reachMargin : number = 0.6
+        @label "Reach Margin"
+        @description "Extra world units padded around a closed door's rect when testing player contact (approximates the body's size)."
+        @tier "domain"
+    }
+  }
+
+  page "/gate-lock" as GateLockPage -> GateLock
+}

package/behaviors/lolo/ui/game/atoms/std-lives.lolo

@@ -0,0 +1,121 @@
+app std-lives "1.0.0"
+"Headless lives + checkpoint authority for boards with stakes: owns lives, the current respawn point, and nothing else. DAMAGE (call sites rename their hazard sources — BODY_HAZARD, BODY_FELL, PATROL_HIT — onto it) costs one life, respecting an invulnerability window so overlapping hazards can't chain-drain; losing a life emits LIFE_LOST plus RESPAWN with the current checkpoint (boards route RESPAWN to the body authority's PLACE), and losing the last emits GAME_OVER instead. Checkpoints advance automatically: BODY_MOVED crossing a configured checkpoint's atX moves the respawn point forward and emits CHECKPOINT_REACHED once per checkpoint (tracked by furthest atX reached, so checkpoints are ordered along the run). RESTART reseeds lives and respawn to the spawn. Renders nothing — HUDs read lives off the shared entity."
+orbital LivesOrbital {
+  type Checkpoint = {
+    id : string!
+    atX : number!
+    x : number!
+    y : number!
+  }
+
+  entity LivesData [runtime, shared] {
+    id : string!
+    lives : number = 3
+    respawnX : number = 0
+    respawnY : number = 0
+    cpX : number = -1000000
+    lastHitAt : number = 0
+  }
+
+  trait Lives -> @rebindable LivesData [lifecycle] {
+    initial: active
+
+    state active {
+      INIT -> active
+        (set @entity.lives @config.maxLives)
+        (set @entity.respawnX @config.spawnX)
+        (set @entity.respawnY @config.spawnY)
+        (set @entity.cpX (- 0 1000000))
+        (set @entity.lastHitAt 0)
+
+      DAMAGE -> active when (and @config.running (> @entity.lives 0))
+        (if (>= (- (time/now) @entity.lastHitAt) @config.invulnMs)
+          (do
+            (set @entity.lastHitAt (time/now))
+            (set @entity.lives (- @entity.lives 1))
+            (if (> @entity.lives 0)
+              (do
+                (emit LIFE_LOST { lives: @entity.lives })
+                (emit RESPAWN { x: @entity.respawnX, y: @entity.respawnY }))
+              (emit GAME_OVER { id: "lives" })))
+          null)
+
+      BODY_MOVED -> active when @config.running
+        (let ((reached (array/filter @config.checkpoints (fn c (and (<= (object/get @c atX) @payload.x) (> (object/get @c atX) @entity.cpX))))))
+        (if (> (array/len @reached) 0)
+          (let ((cp (array/last @reached)))
+            (do
+              (set @entity.respawnX (object/get @cp x))
+              (set @entity.respawnY (object/get @cp y))
+              (set @entity.cpX (object/get @cp atX))
+              (emit CHECKPOINT_REACHED { id: (object/get @cp id) })))
+          null))
+
+      RESTART -> active
+        (set @entity.lives @config.maxLives)
+        (set @entity.respawnX @config.spawnX)
+        (set @entity.respawnY @config.spawnY)
+        (set @entity.cpX (- 0 1000000))
+        (set @entity.lastHitAt 0)
+    }
+
+    emits {
+      LIFE_LOST -> external {
+        lives : number!
+      }
+        @description "A life was spent (post-invulnerability check); carries the lives remaining. Boards layer damage fx / HUD heartbeat."
+        @tier "domain"
+      RESPAWN -> external {
+        x : number!
+        y : number!
+      }
+        @description "The checkpoint the body should restart from after this life loss; boards forward it to the body authority's PLACE."
+        @tier "domain"
+      GAME_OVER -> external {
+        id : string!
+      }
+        @description "The last life was spent; boards show the game-over overlay and wait for RESTART."
+        @tier "domain"
+      CHECKPOINT_REACHED -> external {
+        id : string!
+      }
+        @description "The player crossed a checkpoint's atX for the first time this run; the respawn point moved to it. Boards layer flag/save fx."
+        @tier "domain"
+    }
+
+    listens {
+      DAMAGE { source : string }
+      BODY_MOVED { x : number!, y : number!, vx : number!, vy : number!, grounded : boolean!, skating : boolean!, speed : number! }
+      RESTART { id : string }
+    }
+
+    config {
+      running : boolean = true
+        @label "Running"
+        @description "When true, DAMAGE and checkpoint crossings are processed; toggle to make the run harmless (practice mode)."
+        @tier "domain"
+      maxLives : number = 3
+        @label "Max Lives"
+        @description "Lives seeded on INIT/RESTART; reaching zero fires GAME_OVER."
+        @tier "domain"
+      invulnMs : number = 1500
+        @label "Invulnerability Window (ms)"
+        @description "Milliseconds after a accepted hit during which further DAMAGE is ignored, so a hazard overlapping the respawn can't chain-drain."
+        @tier "domain"
+      spawnX : number = 0
+        @label "Spawn X"
+        @description "Respawn x before any checkpoint is reached (match the body authority's spawn)."
+        @tier "domain"
+      spawnY : number = 0
+        @label "Spawn Y"
+        @description "Respawn y before any checkpoint is reached."
+        @tier "domain"
+      checkpoints : [Checkpoint] = []
+        @label "Checkpoints"
+        @description "Ordered along the run: when the player's x crosses atX the respawn point moves to (x, y). Must be sorted by atX ascending."
+        @tier "domain"
+    }
+  }
+
+  page "/lives" as LivesPage -> Lives
+}

package/behaviors/lolo/ui/game/atoms/std-patrol-hazard.lolo

@@ -0,0 +1,96 @@
+app std-patrol-hazard "1.0.0"
+"Headless patrol-hazard mechanic for side-view boards: moves each configured patrol back and forth along its [x0, x1] beat at its own speed (33ms tick, ping-pong with clamped turnarounds), tracks the player position off the body authority's BODY_MOVED, and emits PATROL_HIT once per contact — a per-patrol hit flag re-arms only after the player separates, so damage rules stay sparse (when two patrols connect on the same tick the first reports; the other reports on the next tick). Patrols live on a [runtime, shared] entity for the render layer (boards draw them as markers/sprites); damage, lives, and respawn stay downstream (std-lives) — this atom simulates, it never judges. Renders nothing."
+orbital PatrolHazardOrbital {
+  type Patrol = {
+    id : string!
+    x0 : number!
+    x1 : number!
+    y : number!
+    speed : number!
+    x : number
+    dir : number
+    touching : boolean
+    hit : boolean
+  }
+
+  entity PatrolState [runtime, shared] {
+    id : string!
+    patrols : [Patrol] = []
+    px : number = 0
+    py : number = 0
+  }
+
+  trait PatrolHazard -> @rebindable PatrolState [lifecycle] {
+    initial: active
+
+    state active {
+      INIT -> active
+        (set @entity.patrols (array/map @config.patrols (fn p (object/merge @p { x: (object/get @p x0), dir: 1, touching: false, hit: false }))))
+        (set @entity.px @config.playerSpawnX)
+        (set @entity.py @config.playerSpawnY)
+
+      BODY_MOVED -> active
+        (set @entity.px @payload.x)
+        (set @entity.py @payload.y)
+
+      RESTART -> active
+        (set @entity.patrols (array/map @config.patrols (fn p (object/merge @p { x: (object/get @p x0), dir: 1, touching: false, hit: false }))))
+    }
+
+    ticks {
+      patrolTick every 33ms
+        when (and @config.running (> (array/len @entity.patrols) 0))
+        (set @entity.patrols (array/map @entity.patrols (fn p
+          (let ((nx (+ (object/get @p x) (* (* (object/get @p dir) (object/get @p speed)) 0.033))))
+          (let ((overshoot (> @nx (object/get @p x1))) (undershoot (< @nx (object/get @p x0))))
+          (let ((cx (if @overshoot (object/get @p x1) (if @undershoot (object/get @p x0) @nx)))
+                (cdir (if @overshoot -1 (if @undershoot 1 (object/get @p dir)))))
+          (let ((near (and (<= (math/abs (- @entity.px @cx)) @config.hitRadius) (<= (math/abs (- @entity.py (object/get @p y))) @config.hitRadius))))
+            (object/merge @p { x: @cx, dir: @cdir, hit: (and @near (== (object/get @p touching) false)), touching: @near }))))))))
+        (let ((hits (array/filter @entity.patrols (fn p (== (object/get @p hit) true)))))
+        (if (> (array/len @hits) 0)
+          (emit PATROL_HIT { id: (object/get (array/first @hits) id), x: (object/get (array/first @hits) x), y: (object/get (array/first @hits) y) })
+          null))
+    }
+
+    emits {
+      PATROL_HIT -> external {
+        id : string!
+        x : number!
+        y : number!
+      }
+        @description "A patrol made contact with the player this tick; fires once per contact and re-arms only after separation — boards route it to their damage rule (std-lives DAMAGE)."
+        @tier "domain"
+    }
+
+    listens {
+      BODY_MOVED { x : number!, y : number!, vx : number!, vy : number!, grounded : boolean!, skating : boolean!, speed : number! }
+      RESTART { id : string }
+    }
+
+    config {
+      running : boolean = true
+        @label "Running"
+        @description "When true the 33ms tick moves patrols and tests contact; toggle to freeze every patrol in place."
+        @tier "domain"
+      patrols : [Patrol] = []
+        @label "Patrols"
+        @description "One row per patroller: id, the [x0, x1] beat it walks, its fixed y, and its speed in units/s. Current x/dir/touching/hit are stamped at runtime."
+        @tier "domain"
+      hitRadius : number = 0.7
+        @label "Hit Radius"
+        @description "Per-axis distance (world units) within which a patrol counts as touching the player; smaller values demand precise contact, larger values forgive."
+        @tier "domain"
+      playerSpawnX : number = 0
+        @label "Player Spawn X"
+        @description "Player x assumed before the first BODY_MOVED arrives (match the body authority's spawn)."
+        @tier "domain"
+      playerSpawnY : number = 0
+        @label "Player Spawn Y"
+        @description "Player y assumed before the first BODY_MOVED arrives."
+        @tier "domain"
+    }
+  }
+
+  page "/patrol-hazard" as PatrolHazardPage -> PatrolHazard
+}

package/behaviors/lolo/ui/game/atoms/std-tutorial-autodemo.lolo

@@ -0,0 +1,136 @@
+app std-tutorial-autodemo "1.0.0"
+"Generic scripted input-replay atom: the demo half of a tutorial. Holds one or more named cue scripts (each an ordered list of { at, event, arg } rows where at is a millisecond offset and event is LEFT/RIGHT/JUMP/STOP); listens for TUTORIAL_DEMO_START { demoId } (from std-tutorial-overlay's demoId step) and plays the matching script on a 32ms clock, emitting the semantic DEMO_LEFT / DEMO_RIGHT / DEMO_JUMP / DEMO_STOP events the host board maps onto its own movement. TUTORIAL_DEMO_STOP, DEMO_CANCEL (real user input), or exhausting the cue list end the demo and emit DEMO_STOP so the character stops moving. Renders a small Demo badge while playing. Domain-agnostic: the demo never emits board events (OW_*, etc.) — the organism maps DEMO_* to its own steering, so a demo cannot self-cancel through the board's input path."
+orbital TutorialAutoDemoOrbital {
+  type DemoCue = {
+    at : number!
+    event : string!
+    arg : number
+  }
+  type DemoScript = {
+    id : string!
+    cues : [DemoCue]!
+  }
+
+  entity AutoDemoData [runtime] {
+    id : string!
+    playing : boolean = false
+    scriptId : string = ""
+    elapsed : number = 0
+    cueIndex : number = 0
+  }
+
+  trait AutoDemo -> @rebindable AutoDemoData [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (render-ui hud-top null)
+
+      TUTORIAL_DEMO_START -> playing
+        (set @entity.scriptId @payload.demoId)
+        (set @entity.elapsed 0)
+        (set @entity.cueIndex 0)
+        (set @entity.playing true)
+        (render-ui hud-top {
+          type: badge
+          label: "Demo"
+          variant: "info"
+        })
+
+      TUTORIAL_DEMO_STOP -> idle
+        (render-ui hud-top null)
+
+      DEMO_CANCEL -> idle
+        (render-ui hud-top null)
+    }
+
+    state playing {
+      TUTORIAL_DEMO_START -> playing
+        (set @entity.scriptId @payload.demoId)
+        (set @entity.elapsed 0)
+        (set @entity.cueIndex 0)
+        (render-ui hud-top {
+          type: badge
+          label: "Demo"
+          variant: "info"
+        })
+
+      TUTORIAL_DEMO_STOP -> idle
+        (set @entity.playing false)
+        (render-ui hud-top null)
+        (emit DEMO_STOP {})
+
+      DEMO_CANCEL -> idle
+        (set @entity.playing false)
+        (render-ui hud-top null)
+        (emit DEMO_STOP {})
+    }
+
+    ticks {
+      demoTick every 32ms when (== @entity.playing true)
+        (set @entity.elapsed (+ @entity.elapsed 32))
+        (let ((scriptMatch (array/filter @config.scripts (fn s (== (object/get @s id) @entity.scriptId)))))
+        (let ((cueList (if (> (array/len @scriptMatch) 0) (object/get (array/first @scriptMatch) cues []) [])))
+        (let ((cue (if (< @entity.cueIndex (array/len @cueList)) (array/nth @cueList @entity.cueIndex) { at: 999999, event: "" })))
+        (do
+          (if (<= (object/get @cue at 0) @entity.elapsed)
+            (do
+              (set @entity.cueIndex (+ @entity.cueIndex 1))
+              (if (== (object/get @cue event "") "LEFT") (emit DEMO_LEFT {}) null)
+              (if (== (object/get @cue event "") "RIGHT") (emit DEMO_RIGHT {}) null)
+              (if (== (object/get @cue event "") "JUMP") (emit DEMO_JUMP {}) null)
+              (if (== (object/get @cue event "") "STOP") (emit DEMO_STOP {}) null))
+            null)
+          (if (>= @entity.cueIndex (array/len @cueList))
+            (do
+              (set @entity.playing false)
+              (render-ui hud-top null)
+              (emit DEMO_STOP {}))
+            null)))))
+    }
+
+    listens {
+      TUTORIAL_DEMO_START {
+        demoId : string!
+      }
+        @description "A tutorial step carrying a demoId was shown (std-tutorial-overlay); begin playing the cue script whose id matches demoId."
+        @tier "domain"
+      TUTORIAL_DEMO_STOP {
+      }
+        @description "The tutorial left a demo step or was dismissed; stop the demo and release control."
+        @tier "domain"
+      DEMO_CANCEL {
+      }
+        @description "Real user input was received by the host board; stop the demo immediately and hand control back to the player."
+        @tier "domain"
+    }
+
+    emits {
+      DEMO_LEFT -> external {
+      }
+        @description "Scripted run-left cue; the host board maps this to its own steer-left."
+        @tier "domain"
+      DEMO_RIGHT -> external {
+      }
+        @description "Scripted run-right cue; the host board maps this to its own steer-right."
+        @tier "domain"
+      DEMO_JUMP -> external {
+      }
+        @description "Scripted jump cue; the host board maps this to its own jump."
+        @tier "domain"
+      DEMO_STOP -> external {
+      }
+        @description "Scripted stop cue (or demo end/cancel); the host board maps this to stop movement."
+        @tier "domain"
+    }
+
+    config {
+      scripts : [DemoScript] = []
+        @label "Scripts"
+        @description "Named cue scripts keyed by the tutorial step's demoId; each cue fires its event after `at` milliseconds of the demo clock."
+        @tier "domain"
+    }
+  }
+
+  page "/tutorial-autodemo" as TutorialAutoDemoPage -> AutoDemo
+}

package/behaviors/lolo/ui/game/atoms/std-tutorial-overlay.lolo

@@ -0,0 +1,197 @@
+app std-tutorial-overlay "1.0.0"
+"Tutorial modal with live-demo steps for game boards and learning shells: a paged overlay — title, a live previewTrait frame playing the mechanic via std-tutorial-autodemo (a bare game canvas, no shell chrome), one line of body copy, a step counter, and Back / Next / Skip — composed entirely from registered render types (stack + text + button + trait frame) into the overlay slot, so no new UI component is needed. autoShow opens it on INIT for first-time players; a board's help button re-opens it any time via SHOW (which rewinds to step one). DISMISS (or finishing the last step) marks the run done, clears the overlay, and emits TUTORIAL_DONE so the board can unpause or log. Steps are pure config — a board teaches a new mechanic by adding one { id, title, body, demoId } row plus a previewTrait binding."
+orbital TutorialOverlayOrbital {
+  type TutorialStep = {
+    id : string!
+    title : string!
+    body : string
+    demoId : string
+  }
+
+  entity TutorialState [runtime, shared] {
+    id : string!
+    step : number = 0
+    done : boolean = false
+  }
+
+  trait TutorialEmptyPreview -> TutorialState [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (render-ui overlay null)
+    }
+  }
+
+  trait TutorialOverlay -> @rebindable TutorialState [interaction, instance] {
+    initial: hidden
+
+    state hidden {
+      INIT -> hidden
+        (if @config.autoShow
+          (emit TUT_AUTO { id: "auto" })
+          (render-ui overlay null))
+
+      TUT_AUTO -> showing
+        (set @entity.step 0)
+        (render-ui overlay {
+          type: stack
+          direction: vertical
+          className: "bg-card text-card-foreground border border-border rounded-lg shadow-lg p-6 max-w-md mx-auto mt-16"
+          children: [
+            { type: typography, content: (object/get (array/nth @config.steps 0) title), variant: "h4", weight: "bold" }
+            @config.previewTrait
+            { type: typography, content: (object/get (array/nth @config.steps 0) body), variant: "body" }
+            { type: typography, content: (str/concat "1 / " (array/len @config.steps)), variant: "caption", align: "center" }
+            { type: stack, direction: horizontal, justify: "center", className: "pt-2", children: [
+              { type: button, label: (if (> (array/len @config.steps) 1) "Next ▶" "Got it"), action: "TUT_NEXT", variant: "primary" }
+              { type: button, label: "Skip", action: "TUT_DISMISS", variant: "secondary" }
+            ] }
+          ]
+        })
+        (when (!= (object/get (array/nth @config.steps 0) demoId "") "")
+          (do (emit TUTORIAL_DEMO_START { demoId: (object/get (array/nth @config.steps 0) demoId "") })))
+
+      SHOW -> showing
+        (set @entity.step 0)
+        (render-ui overlay {
+          type: stack
+          direction: vertical
+          className: "bg-card text-card-foreground border border-border rounded-lg shadow-lg p-6 max-w-md mx-auto mt-16"
+          children: [
+            { type: typography, content: (object/get (array/nth @config.steps 0) title), variant: "h4", weight: "bold" }
+            @config.previewTrait
+            { type: typography, content: (object/get (array/nth @config.steps 0) body), variant: "body" }
+            { type: typography, content: (str/concat "1 / " (array/len @config.steps)), variant: "caption", align: "center" }
+            { type: stack, direction: horizontal, justify: "center", className: "pt-2", children: [
+              { type: button, label: (if (> (array/len @config.steps) 1) "Next ▶" "Got it"), action: "TUT_NEXT", variant: "primary" }
+              { type: button, label: "Skip", action: "TUT_DISMISS", variant: "secondary" }
+            ] }
+          ]
+        })
+        (when (!= (object/get (array/nth @config.steps 0) demoId "") "")
+          (do (emit TUTORIAL_DEMO_START { demoId: (object/get (array/nth @config.steps 0) demoId "") })))
+    }
+
+    state showing {
+      TUT_NEXT -> showing when (< (+ @entity.step 1) (array/len @config.steps))
+        (set @entity.step (+ @entity.step 1))
+        (render-ui overlay {
+          type: stack
+          direction: vertical
+          className: "bg-card text-card-foreground border border-border rounded-lg shadow-lg p-6 max-w-md mx-auto mt-16"
+          children: [
+            { type: typography, content: (object/get (array/nth @config.steps @entity.step) title), variant: "h4", weight: "bold" }
+            @config.previewTrait
+            { type: typography, content: (object/get (array/nth @config.steps @entity.step) body), variant: "body" }
+            { type: typography, content: (str/concat (+ @entity.step 1) " / " (array/len @config.steps)), variant: "caption", align: "center" }
+            { type: stack, direction: horizontal, justify: "center", className: "pt-2", children: [
+              { type: button, label: "◀ Back", action: "TUT_BACK", variant: "secondary" }
+              { type: button, label: (if (< (+ @entity.step 1) (array/len @config.steps)) "Next ▶" "Got it"), action: "TUT_NEXT", variant: "primary" }
+              { type: button, label: "Skip", action: "TUT_DISMISS", variant: "secondary" }
+            ] }
+          ]
+        })
+        (emit TUTORIAL_DEMO_STOP {})
+        (when (!= (object/get (array/nth @config.steps @entity.step) demoId "") "")
+          (do (emit TUTORIAL_DEMO_START { demoId: (object/get (array/nth @config.steps @entity.step) demoId "") })))
+
+      TUT_NEXT -> hidden when (>= (+ @entity.step 1) (array/len @config.steps))
+        (set @entity.done true)
+        (render-ui overlay null)
+        (emit TUTORIAL_DEMO_STOP {})
+        (emit TUTORIAL_DONE { id: "tutorial" })
+
+      TUT_BACK -> showing when (> @entity.step 0)
+        (set @entity.step (- @entity.step 1))
+        (render-ui overlay {
+          type: stack
+          direction: vertical
+          className: "bg-card text-card-foreground border border-border rounded-lg shadow-lg p-6 max-w-md mx-auto mt-16"
+          children: [
+            { type: typography, content: (object/get (array/nth @config.steps @entity.step) title), variant: "h4", weight: "bold" }
+            @config.previewTrait
+            { type: typography, content: (object/get (array/nth @config.steps @entity.step) body), variant: "body" }
+            { type: typography, content: (str/concat (+ @entity.step 1) " / " (array/len @config.steps)), variant: "caption", align: "center" }
+            { type: stack, direction: horizontal, justify: "center", className: "pt-2", children: [
+              { type: button, label: "◀ Back", action: "TUT_BACK", variant: "secondary" }
+              { type: button, label: (if (< (+ @entity.step 1) (array/len @config.steps)) "Next ▶" "Got it"), action: "TUT_NEXT", variant: "primary" }
+              { type: button, label: "Skip", action: "TUT_DISMISS", variant: "secondary" }
+            ] }
+          ]
+        })
+        (emit TUTORIAL_DEMO_STOP {})
+        (when (!= (object/get (array/nth @config.steps @entity.step) demoId "") "")
+          (do (emit TUTORIAL_DEMO_START { demoId: (object/get (array/nth @config.steps @entity.step) demoId "") })))
+
+      TUT_DISMISS -> hidden
+        (set @entity.done true)
+        (render-ui overlay null)
+        (emit TUTORIAL_DEMO_STOP {})
+        (emit TUTORIAL_DONE { id: "tutorial" })
+    }
+
+    emits {
+      TUT_AUTO -> external {
+        id : string
+      }
+        @description "Self-emitted on INIT when autoShow is on — opens step one. (A config-valued INIT guard would be constant-folded at compose time and misfire; the self-event keeps the decision in an effect.)"
+        @tier "essential"
+      TUT_NEXT -> external {
+        id : string
+      }
+        @description "Advance one step; on the last step it finishes the tutorial (marks done, clears the overlay, emits TUTORIAL_DONE)."
+        @tier "essential"
+      TUT_BACK -> external {
+        id : string
+      }
+        @description "Return one step (inert on the first)."
+        @tier "essential"
+      TUT_DISMISS -> external {
+        id : string
+      }
+        @description "Skip/close the tutorial; marks done and clears the overlay."
+        @tier "essential"
+      SHOW -> external {
+        id : string
+      }
+        @description "Re-open the tutorial from step one — wire a board's help button here."
+        @tier "essential"
+      TUTORIAL_DONE -> external {
+        id : string!
+      }
+        @description "The tutorial was finished or skipped; boards unpause or log completion."
+        @tier "domain"
+      TUTORIAL_DEMO_START -> external {
+        demoId : string!
+      }
+        @description "Emitted when a tutorial step carrying a demoId is shown; the composed std-tutorial-autodemo atom plays that scripted demo."
+        @tier "domain"
+      TUTORIAL_DEMO_STOP -> external {
+      }
+        @description "Emitted when the tutorial leaves a demo step (next/back) or is dismissed/finished; the autodemo atom stops and releases control."
+        @tier "domain"
+    }
+
+    listens {
+      SHOW { id : string }
+    }
+
+    config {
+      steps : [TutorialStep] = []
+        @label "Steps"
+        @description "One row per tutorial page: title, one line of body copy, and an optional demoId that plays a scripted live demo (std-tutorial-autodemo) for the mechanic being taught."
+        @tier "presentation"
+      previewTrait : trait = @trait.TutorialEmptyPreview
+        @label "Preview trait"
+        @description "Trait rendered in the media position of the modal — the live, demo-driven preview of the mechanic (a bare game canvas, no shell chrome). '@trait.TutorialEmptyPreview' leaves the slot blank. Override with '@trait.<TraitName>' to show a board's live frame."
+        @tier "presentation"
+      autoShow : boolean = true
+        @label "Auto Show"
+        @description "When true the tutorial opens on INIT for this run; when false it stays hidden until SHOW."
+        @tier "domain"
+    }
+  }
+
+  page "/tutorial-overlay" as TutorialOverlayPage -> TutorialOverlay
+}