@almadar/std 16.182.0 → 16.183.0

package/behaviors/lolo/infra/atoms/std-migration-job.lolo

@@ -297,9 +297,9 @@ orbital MigrationJobOrbital {
         @description "Name of the host entity this import writes into (e.g. the organism's own entity). The migration service derives the full target descriptor from the running app's schema."
         @synonyms "destination, import into, target type"
         @tier "domain"
-      connectionRef : string = ""
+      connectionRef : secret = ""
         @label "Connection reference"
-        @description "Secret-store / environment KEY holding the source credentials. The reference is stored; the secret itself never enters config, traces, or snapshots — the migration service resolves it at run time. (Typed `string` until the `secret` config-field type lands in the lolo language — tracked gap.)"
+        @description "Secret-store / environment KEY holding the source credentials. The reference is stored; the secret itself never enters config, traces, or snapshots — the migration service resolves it at run time. (Typed `secret` — the config-field type that marks a credential reference; UI password-renders it and traces mask it.)"
         @synonyms "credential key, connection string reference, secret name"
         @tier "internal"
       reviewSlot : slot = modal

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

@@ -0,0 +1,63 @@
+app std-fx-trail "1.0.0"
+"Headless motion-trail mechanic: records the moving body's recent positions as timestamped dots on a [runtime, shared] entity so the render layer can draw a fading comet trail. Rides the body authority's BODY_MOVED — appends a dot only when the body's speed exceeds minSpeed (standing still leaves no trail) and prunes dots older than ttl on the same pass, so no decay tick is needed and a stopped body's trail simply stops growing (the render side fades each dot by bornAt/ttl). RESTART clears. Renders nothing."
+orbital FxTrailOrbital {
+  type TrailDot = {
+    id : string!
+    x : number!
+    y : number!
+    bornAt : number!
+    ttl : number!
+  }
+
+  entity FxTrailData [runtime, shared] {
+    id : string!
+    trail : [TrailDot] = []
+    seq : number = 0
+  }
+
+  trait FxTrail -> @rebindable FxTrailData [lifecycle] {
+    initial: active
+
+    state active {
+      INIT -> active
+        (set @entity.trail [])
+        (set @entity.seq 0)
+
+      BODY_MOVED -> active when @config.running
+        (set @entity.trail
+          (array/filter
+            (if (> @payload.speed @config.minSpeed)
+              (array/concat @entity.trail [ { id: (str/concat "trail-" (+ @entity.seq 1)), x: @payload.x, y: @payload.y, bornAt: (time/now), ttl: @config.ttl } ])
+              @entity.trail)
+            (fn d (< (- (time/now) (object/get @d bornAt)) (object/get @d ttl)))))
+        (if (> @payload.speed @config.minSpeed)
+          (set @entity.seq (+ @entity.seq 1))
+          null)
+
+      RESTART -> active
+        (set @entity.trail [])
+    }
+
+    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, BODY_MOVED appends trail dots; toggle to freeze the trail (existing dots still age out)."
+        @tier "domain"
+      ttl : number = 600
+        @label "Trail Ttl (ms)"
+        @description "Milliseconds a trail dot lives; at a 33ms move cadence ~600ms keeps the last eighteen positions. The ttl is also the natural length cap — no separate limit needed."
+        @tier "presentation"
+      minSpeed : number = 0.5
+        @label "Min Speed"
+        @description "Body speed (units/s, from BODY_MOVED) below which no dot is appended, so a resting body doesn't pile dots on one spot."
+        @tier "domain"
+    }
+  }
+
+  page "/fx-trail" as FxTrailPage -> FxTrail
+}

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-overlay.lolo

@@ -0,0 +1,164 @@
+app std-tutorial-overlay "1.0.0"
+"Tutorial modal with media steps for game boards and learning shells: a paged overlay — title, an animated GIF/clip showing exactly how the mechanic is done, one line of body copy, a step counter, and Back / Next / Skip — composed entirely from registered render types (stack + text + image + button) 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, media } row."
+orbital TutorialOverlayOrbital {
+  type TutorialStep = {
+    id : string!
+    title : string!
+    body : string
+    media : string
+    mediaAlt : string
+  }
+
+  entity TutorialState [runtime, shared] {
+    id : string!
+    step : number = 0
+    done : boolean = false
+  }
+
+  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" }
+            { type: atlas-image, asset: { url: (object/get (array/nth @config.steps 0) media), name: (object/get (array/nth @config.steps 0) id), category: "tutorial" }, fit: "contain", alt: (object/get (array/nth @config.steps 0) mediaAlt), className: "rounded-md" }
+            { 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" }
+            ] }
+          ]
+        })
+
+      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" }
+            { type: atlas-image, asset: { url: (object/get (array/nth @config.steps 0) media), name: (object/get (array/nth @config.steps 0) id), category: "tutorial" }, fit: "contain", alt: (object/get (array/nth @config.steps 0) mediaAlt), className: "rounded-md" }
+            { 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" }
+            ] }
+          ]
+        })
+    }
+
+    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" }
+            { type: atlas-image, asset: { url: (object/get (array/nth @config.steps @entity.step) media), name: (object/get (array/nth @config.steps @entity.step) id), category: "tutorial" }, fit: "contain", alt: (object/get (array/nth @config.steps @entity.step) mediaAlt), className: "rounded-md" }
+            { 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" }
+            ] }
+          ]
+        })
+
+      TUT_NEXT -> hidden when (>= (+ @entity.step 1) (array/len @config.steps))
+        (set @entity.done true)
+        (render-ui overlay null)
+        (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" }
+            { type: atlas-image, asset: { url: (object/get (array/nth @config.steps @entity.step) media), name: (object/get (array/nth @config.steps @entity.step) id), category: "tutorial" }, fit: "contain", alt: (object/get (array/nth @config.steps @entity.step) mediaAlt), className: "rounded-md" }
+            { 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" }
+            ] }
+          ]
+        })
+
+      TUT_DISMISS -> hidden
+        (set @entity.done true)
+        (render-ui overlay null)
+        (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"
+    }
+
+    listens {
+      SHOW { id : string }
+    }
+
+    config {
+      steps : [TutorialStep] = []
+        @label "Steps"
+        @description "One row per tutorial page: title, one line of body copy, and media — the URL of an animated GIF/clip showing exactly how the mechanic is performed (recorded from real gameplay)."
+        @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
+}