@almadar/std 16.173.0 → 16.175.0

package/behaviors/lolo/ui/learning/atoms/std-learn-scenario.lolo

@@ -0,0 +1,307 @@
+app std-learn-scenario "1.0.0"
+"Generic branching decision scenario — a config-declared node graph of situations and choices plays out as a choose-your-path story with modeled consequences: every choice shifts two config-named metrics, appends to a visible decision log, and moves to its declared next node, until a node with no choices ends the run with the final metrics and the full path. This simulates decisions rather than browsing records: the learner feels trade-offs compound. All vocabulary is config-declared, so the same mechanism serves any consequence-chain lesson: fiscal policy choices, ecosystem interventions, historical what-ifs, medical triage, engineering trade-offs. Standalone by default; behind a lab router set matchMode and it renders only when MODE_SELECTED matches."
+orbital ScenarioOrbital {
+  type ScenarioChoice = {
+    label : string!
+    next : string!
+    deltaA : number
+    deltaB : number
+    note : string
+  }
+  type ScenarioNode = {
+    id : string!
+    situation : string!
+    choices : [ScenarioChoice]
+  }
+
+  entity ScenarioScene [runtime] {
+    id : string!
+    active : boolean = false
+    title : string
+    currentId : string
+    situation : string
+    choices : [ScenarioChoice]
+    metricA : number = 0
+    metricB : number = 0
+    stepCount : number = 0
+    path : [string]
+    done : boolean = false
+    feedback : string
+    view : [node]
+  }
+
+  trait ScenarioSim -> @rebindable ScenarioScene [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle when (== @config.matchMode "")
+        (let (
+            (start (array/find @config.nodes (fn n (== (object/get @n id) @config.startId))))
+          )
+          (do
+            (set @entity.active true)
+            (set @entity.title @config.title)
+            (set @entity.currentId @config.startId)
+            (set @entity.situation (object/get @start situation))
+            (set @entity.choices (object/get @start choices []))
+            (set @entity.metricA @config.metricAStart)
+            (set @entity.metricB @config.metricBStart)
+            (set @entity.stepCount 0)
+            (set @entity.path [])
+            (set @entity.done false)
+            (set @entity.feedback "")
+            (set @entity.view [
+              { type: card, variant: bordered, padding: md, children: [
+                  { type: typography, variant: body, content: @entity.situation }
+                ] }
+            ])))
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: typography, variant: body, content: (str/concat @config.metricALabel ": " (math/round @entity.metricA 0) " · " @config.metricBLabel ": " (math/round @entity.metricB 0) " · decisions: " (str/concat "" @entity.stepCount)) },
+                { type: stack, direction: vertical, gap: md, children: @entity.view },
+                { type: stack, direction: vertical, gap: xs, children: (array/map (array/range 0 (array/len @entity.choices)) (fn (i)
+                    { type: button, action: CHOOSE, actionPayload: { index: @i }, label: (object/get (array/nth @entity.choices @i) label), variant: secondary, size: sm, disabled: (if @entity.done true false) })) },
+                { type: typography, variant: caption, content: @entity.feedback },
+                { type: stack, direction: vertical, gap: xs, children: (array/map @entity.path (fn (line)
+                    { type: typography, variant: caption, color: muted, content: @line })) },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RESTART, label: @config.restartLabel, variant: primary, disabled: (if @entity.done false true) }
+                  ] }
+              ] }
+          ]
+        })
+
+      MODE_SELECTED -> idle when (== ?mode @config.matchMode)
+        (let (
+            (start (array/find @config.nodes (fn n (== (object/get @n id) @config.startId))))
+          )
+          (do
+            (set @entity.active true)
+            (set @entity.title @config.title)
+            (set @entity.currentId @config.startId)
+            (set @entity.situation (object/get @start situation))
+            (set @entity.choices (object/get @start choices []))
+            (set @entity.metricA @config.metricAStart)
+            (set @entity.metricB @config.metricBStart)
+            (set @entity.stepCount 0)
+            (set @entity.path [])
+            (set @entity.done false)
+            (set @entity.feedback "")
+            (set @entity.view [
+              { type: card, variant: bordered, padding: md, children: [
+                  { type: typography, variant: body, content: @entity.situation }
+                ] }
+            ])))
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: typography, variant: body, content: (str/concat @config.metricALabel ": " (math/round @entity.metricA 0) " · " @config.metricBLabel ": " (math/round @entity.metricB 0) " · decisions: " (str/concat "" @entity.stepCount)) },
+                { type: stack, direction: vertical, gap: md, children: @entity.view },
+                { type: stack, direction: vertical, gap: xs, children: (array/map (array/range 0 (array/len @entity.choices)) (fn (i)
+                    { type: button, action: CHOOSE, actionPayload: { index: @i }, label: (object/get (array/nth @entity.choices @i) label), variant: secondary, size: sm, disabled: (if @entity.done true false) })) },
+                { type: typography, variant: caption, content: @entity.feedback },
+                { type: stack, direction: vertical, gap: xs, children: (array/map @entity.path (fn (line)
+                    { type: typography, variant: caption, color: muted, content: @line })) },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RESTART, label: @config.restartLabel, variant: primary, disabled: (if @entity.done false true) }
+                  ] }
+              ] }
+          ]
+        })
+
+      CHOOSE -> idle when (and (== @entity.active true) (== @entity.done false))
+        (let (
+            (choice (array/nth @entity.choices ?index))
+            (nextId (object/get @choice next))
+            (nextNode (array/find @config.nodes (fn n (== (object/get @n id) @nextId))))
+            (nextChoices (object/get @nextNode choices []))
+            (ended (== (array/len @nextChoices) 0))
+            (note (object/get @choice note ""))
+            (newA (+ @entity.metricA (object/get @choice deltaA 0)))
+            (newB (+ @entity.metricB (object/get @choice deltaB 0)))
+          )
+          (do
+            (set @entity.currentId @nextId)
+            (set @entity.situation (object/get @nextNode situation))
+            (set @entity.choices @nextChoices)
+            (set @entity.metricA @newA)
+            (set @entity.metricB @newB)
+            (set @entity.stepCount (+ @entity.stepCount 1))
+            (set @entity.path (array/append @entity.path (str/concat (str/concat "" @entity.stepCount) ". " (object/get @choice label) (if (!= @note "") (str/concat " — " @note) ""))))
+            (set @entity.done (if @ended true false))
+            (set @entity.feedback (if (!= @note "") @note ""))
+            (set @entity.view (if @ended
+              [
+                { type: card, variant: bordered, padding: md, children: [
+                    { type: typography, variant: h4, content: "Outcome" },
+                    { type: typography, variant: body, content: @entity.situation },
+                    { type: typography, variant: body, content: (str/concat "Final " @config.metricALabel ": " (math/round @entity.metricA 0) " · final " @config.metricBLabel ": " (math/round @entity.metricB 0) " after " (str/concat "" @entity.stepCount) " decisions.") }
+                  ] }
+              ]
+              [
+                { type: card, variant: bordered, padding: md, children: [
+                    { type: typography, variant: body, content: @entity.situation }
+                  ] }
+              ])))
+          )
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: typography, variant: body, content: (str/concat @config.metricALabel ": " (math/round @entity.metricA 0) " · " @config.metricBLabel ": " (math/round @entity.metricB 0) " · decisions: " (str/concat "" @entity.stepCount)) },
+                { type: stack, direction: vertical, gap: md, children: @entity.view },
+                { type: stack, direction: vertical, gap: xs, children: (array/map (array/range 0 (array/len @entity.choices)) (fn (i)
+                    { type: button, action: CHOOSE, actionPayload: { index: @i }, label: (object/get (array/nth @entity.choices @i) label), variant: secondary, size: sm, disabled: (if @entity.done true false) })) },
+                { type: typography, variant: caption, content: @entity.feedback },
+                { type: stack, direction: vertical, gap: xs, children: (array/map @entity.path (fn (line)
+                    { type: typography, variant: caption, color: muted, content: @line })) },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RESTART, label: @config.restartLabel, variant: primary, disabled: (if @entity.done false true) }
+                  ] }
+              ] }
+          ]
+        })
+        (emit CHOICE_MADE { nodeId: @entity.currentId, metricA: @entity.metricA, metricB: @entity.metricB, ended: @entity.done })
+
+      RESTART -> idle when (and (== @entity.active true) (== @entity.done true))
+        (let (
+            (start (array/find @config.nodes (fn n (== (object/get @n id) @config.startId))))
+          )
+          (do
+            (set @entity.active true)
+            (set @entity.title @config.title)
+            (set @entity.currentId @config.startId)
+            (set @entity.situation (object/get @start situation))
+            (set @entity.choices (object/get @start choices []))
+            (set @entity.metricA @config.metricAStart)
+            (set @entity.metricB @config.metricBStart)
+            (set @entity.stepCount 0)
+            (set @entity.path [])
+            (set @entity.done false)
+            (set @entity.feedback "")
+            (set @entity.view [
+              { type: card, variant: bordered, padding: md, children: [
+                  { type: typography, variant: body, content: @entity.situation }
+                ] }
+            ])))
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: typography, variant: body, content: (str/concat @config.metricALabel ": " (math/round @entity.metricA 0) " · " @config.metricBLabel ": " (math/round @entity.metricB 0) " · decisions: " (str/concat "" @entity.stepCount)) },
+                { type: stack, direction: vertical, gap: md, children: @entity.view },
+                { type: stack, direction: vertical, gap: xs, children: (array/map (array/range 0 (array/len @entity.choices)) (fn (i)
+                    { type: button, action: CHOOSE, actionPayload: { index: @i }, label: (object/get (array/nth @entity.choices @i) label), variant: secondary, size: sm, disabled: (if @entity.done true false) })) },
+                { type: typography, variant: caption, content: @entity.feedback },
+                { type: stack, direction: vertical, gap: xs, children: (array/map @entity.path (fn (line)
+                    { type: typography, variant: caption, color: muted, content: @line })) },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RESTART, label: @config.restartLabel, variant: primary, disabled: (if @entity.done false true) }
+                  ] }
+              ] }
+          ]
+        })
+        (emit SCENARIO_RESTARTED { startId: @config.startId })
+    }
+
+    listens {
+      MODE_SELECTED {
+        mode : string
+      }
+        @description "Lab router broadcast naming the active mode; this instrument renders when the mode equals matchMode, otherwise renders null."
+        @tier "domain"
+      CHOOSE {
+        index : number
+      }
+        @description "Learner picked one of the current node's choices — index selects it; its metric deltas apply, the decision log grows, and the story moves to the declared next node."
+        @tier "domain"
+      RESTART {
+      }
+        @description "Learner restarted the scenario from the start node with fresh metrics and an empty decision log."
+        @tier "domain"
+    }
+
+    emits {
+      CHOICE_MADE -> external {
+        nodeId : string
+        metricA : number
+        metricB : number
+        ended : boolean
+      }
+        @description "A decision was taken: the node reached, both metric values after the deltas, and whether the run just ended — a composed listener (coach, grader) can subscribe; a harmless no-op when the atom runs standalone."
+        @synonyms "branching scenario, choose your path, decision tree, consequences, trade-offs, what-if"
+        @tier "domain"
+      SCENARIO_RESTARTED -> external {
+        startId : string
+      }
+        @description "The learner restarted the scenario from scratch."
+        @tier "domain"
+    }
+
+    config {
+      matchMode : string = ""
+        @label "Match Mode"
+        @description "When composed behind a lab router, the MODE_SELECTED mode value this instrument responds to. Empty string means standalone — render immediately on INIT."
+        @tier "presentation"
+      title : string = "Decision Scenario"
+        @label "Title"
+        @description "Title shown above the scenario."
+        @tier "presentation"
+      metricALabel : string = "Budget"
+        @label "Metric A Label"
+        @description "Display name of the first tracked consequence metric."
+        @tier "domain"
+      metricBLabel : string = "Support"
+        @label "Metric B Label"
+        @description "Display name of the second tracked consequence metric."
+        @tier "domain"
+      metricAStart : number = 100
+        @label "Metric A Start"
+        @tier "domain"
+      metricBStart : number = 50
+        @label "Metric B Start"
+        @tier "domain"
+      startId : string = "start"
+        @label "Start Node"
+        @description "Id of the node the scenario opens on."
+        @tier "domain"
+      nodes : [ScenarioNode] = [
+        { id: "start", situation: "Your town's river floods every spring. The council asks you to lead the response.", choices: [
+            { label: "Build a levee now", next: "levee", deltaA: -60, deltaB: 10, note: "Fast protection, most of the budget gone." },
+            { label: "Restore the upstream wetlands", next: "wetlands", deltaA: -25, deltaB: -5, note: "Cheaper and greener, but slower to work." }
+          ] },
+        { id: "levee", situation: "The levee holds the first spring, but silt builds up and the river rises higher each year.", choices: [
+            { label: "Raise the levee again", next: "end-lock-in", deltaA: -30, deltaB: -10, note: "Costs keep compounding." },
+            { label: "Add wetlands as a second line", next: "end-hybrid", deltaA: -20, deltaB: 15, note: "Late, but it eases the pressure." }
+          ] },
+        { id: "wetlands", situation: "Two springs pass; the wetlands now absorb most floods, and wildlife is returning.", choices: [
+            { label: "Expand the wetland corridor", next: "end-green", deltaA: -15, deltaB: 25, note: "The town rallies behind the project." },
+            { label: "Bank the savings", next: "end-thrifty", deltaA: 10, deltaB: 5, note: "Prudent, though the corridor stays small." }
+          ] },
+        { id: "end-lock-in", situation: "You are locked into an arms race with the river: protected, but at ever-growing cost.", choices: [] },
+        { id: "end-hybrid", situation: "The hybrid defense works: the levee buys time and the wetlands cut the peak floods.", choices: [] },
+        { id: "end-green", situation: "The restored river corridor protects the town and becomes its most loved public space.", choices: [] },
+        { id: "end-thrifty", situation: "The town stays safe in normal years, with savings in reserve for a bigger flood.", choices: [] }
+      ]
+        @label "Nodes"
+        @description "The decision graph; each node carries a situation and its choices, each choice naming the next node, metric deltas, and a consequence note. A node with no choices ends the run. Realizations declare their own subject's decision tree here."
+        @tier "domain"
+      restartLabel : string = "Play Again"
+        @label "Restart Label"
+        @tier "presentation"
+    }
+  }
+
+  page "/learn-scenario" as ScenarioPage -> ScenarioSim
+}

package/behaviors/lolo/ui/learning/atoms/std-learn-sim-3d.lolo

@@ -0,0 +1,318 @@
+app std-learn-sim-3d "1.0.0"
+"Generic 3D simulation-transport (clock) instrument. Contract: the atom owns the transport and the clock but NOT the physics — Run/Pause/Reset plus a 0.5x/1x/2x/4x speed row drive a running flag and speed multiplier, and a 32ms tick advances steps and simTime by dt x speedMultiplier, emitting SIM_3D_TICK { dt, simTime } each step WITHOUT rendering; a composed sibling trait transitions directly on the SIM_3D_TICK / SIM_3D_UPDATED broadcasts (the same bare-event cascade the lab routers use), applies the domain physics, and owns the scene render — this atom renders no canvas. A caption readout shows steps, sim time, and current speed. Standalone by default; behind a lab router set matchMode and it renders only when MODE_SELECTED matches."
+orbital LearnSim3DOrbital {
+  entity Learn3DSimScene [runtime] {
+    id : string!
+    active : boolean = false
+    title : string
+    running : boolean = false
+    speedMultiplier : number = 1
+    steps : int = 0
+    simTime : number = 0
+  }
+
+  trait Learn3DSimTransport -> @rebindable Learn3DSimScene [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle when (== @config.matchMode "")
+        (set @entity.active true)
+        (set @entity.title @config.title)
+        (set @entity.running @config.running)
+        (set @entity.speedMultiplier 1)
+        (set @entity.steps 0)
+        (set @entity.simTime 0)
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RUN, label: "Run", variant: primary },
+                    { type: button, action: PAUSE, label: "Pause", variant: secondary },
+                    { type: button, action: RESET, label: "Reset", variant: ghost }
+                  ] },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: SPEED_HALF, label: "0.5x", variant: ghost },
+                    { type: button, action: SPEED_NORMAL, label: "1x", variant: ghost },
+                    { type: button, action: SPEED_DOUBLE, label: "2x", variant: ghost },
+                    { type: button, action: SPEED_QUAD, label: "4x", variant: ghost }
+                  ] },
+                { type: typography, variant: caption, content: (str/concat "Steps: " @entity.steps " — sim time: " (math/round @entity.simTime 1) " s — speed: " @entity.speedMultiplier "x") }
+              ] }
+          ]
+        })
+        (emit SIM_3D_UPDATED { running: @entity.running, speedMultiplier: @entity.speedMultiplier, steps: @entity.steps, simTime: @entity.simTime })
+
+      MODE_SELECTED -> idle when (== ?mode @config.matchMode)
+        (set @entity.active true)
+        (set @entity.title @config.title)
+        (set @entity.running @config.running)
+        (set @entity.speedMultiplier 1)
+        (set @entity.steps 0)
+        (set @entity.simTime 0)
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RUN, label: "Run", variant: primary },
+                    { type: button, action: PAUSE, label: "Pause", variant: secondary },
+                    { type: button, action: RESET, label: "Reset", variant: ghost }
+                  ] },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: SPEED_HALF, label: "0.5x", variant: ghost },
+                    { type: button, action: SPEED_NORMAL, label: "1x", variant: ghost },
+                    { type: button, action: SPEED_DOUBLE, label: "2x", variant: ghost },
+                    { type: button, action: SPEED_QUAD, label: "4x", variant: ghost }
+                  ] },
+                { type: typography, variant: caption, content: (str/concat "Steps: " @entity.steps " — sim time: " (math/round @entity.simTime 1) " s — speed: " @entity.speedMultiplier "x") }
+              ] }
+          ]
+        })
+        (emit SIM_3D_UPDATED { running: @entity.running, speedMultiplier: @entity.speedMultiplier, steps: @entity.steps, simTime: @entity.simTime })
+
+      RUN -> idle when (== @entity.active true)
+        (set @entity.running true)
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RUN, label: "Run", variant: primary },
+                    { type: button, action: PAUSE, label: "Pause", variant: secondary },
+                    { type: button, action: RESET, label: "Reset", variant: ghost }
+                  ] },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: SPEED_HALF, label: "0.5x", variant: ghost },
+                    { type: button, action: SPEED_NORMAL, label: "1x", variant: ghost },
+                    { type: button, action: SPEED_DOUBLE, label: "2x", variant: ghost },
+                    { type: button, action: SPEED_QUAD, label: "4x", variant: ghost }
+                  ] },
+                { type: typography, variant: caption, content: (str/concat "Steps: " @entity.steps " — sim time: " (math/round @entity.simTime 1) " s — speed: " @entity.speedMultiplier "x") }
+              ] }
+          ]
+        })
+        (emit SIM_3D_UPDATED { running: @entity.running, speedMultiplier: @entity.speedMultiplier, steps: @entity.steps, simTime: @entity.simTime })
+
+      PAUSE -> idle when (== @entity.active true)
+        (set @entity.running false)
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RUN, label: "Run", variant: primary },
+                    { type: button, action: PAUSE, label: "Pause", variant: secondary },
+                    { type: button, action: RESET, label: "Reset", variant: ghost }
+                  ] },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: SPEED_HALF, label: "0.5x", variant: ghost },
+                    { type: button, action: SPEED_NORMAL, label: "1x", variant: ghost },
+                    { type: button, action: SPEED_DOUBLE, label: "2x", variant: ghost },
+                    { type: button, action: SPEED_QUAD, label: "4x", variant: ghost }
+                  ] },
+                { type: typography, variant: caption, content: (str/concat "Steps: " @entity.steps " — sim time: " (math/round @entity.simTime 1) " s — speed: " @entity.speedMultiplier "x") }
+              ] }
+          ]
+        })
+        (emit SIM_3D_UPDATED { running: @entity.running, speedMultiplier: @entity.speedMultiplier, steps: @entity.steps, simTime: @entity.simTime })
+
+      RESET -> idle when (== @entity.active true)
+        (set @entity.running @config.running)
+        (set @entity.speedMultiplier 1)
+        (set @entity.steps 0)
+        (set @entity.simTime 0)
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RUN, label: "Run", variant: primary },
+                    { type: button, action: PAUSE, label: "Pause", variant: secondary },
+                    { type: button, action: RESET, label: "Reset", variant: ghost }
+                  ] },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: SPEED_HALF, label: "0.5x", variant: ghost },
+                    { type: button, action: SPEED_NORMAL, label: "1x", variant: ghost },
+                    { type: button, action: SPEED_DOUBLE, label: "2x", variant: ghost },
+                    { type: button, action: SPEED_QUAD, label: "4x", variant: ghost }
+                  ] },
+                { type: typography, variant: caption, content: (str/concat "Steps: " @entity.steps " — sim time: " (math/round @entity.simTime 1) " s — speed: " @entity.speedMultiplier "x") }
+              ] }
+          ]
+        })
+        (emit SIM_3D_UPDATED { running: @entity.running, speedMultiplier: @entity.speedMultiplier, steps: @entity.steps, simTime: @entity.simTime })
+
+      SPEED_HALF -> idle when (== @entity.active true)
+        (set @entity.speedMultiplier 0.5)
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RUN, label: "Run", variant: primary },
+                    { type: button, action: PAUSE, label: "Pause", variant: secondary },
+                    { type: button, action: RESET, label: "Reset", variant: ghost }
+                  ] },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: SPEED_HALF, label: "0.5x", variant: ghost },
+                    { type: button, action: SPEED_NORMAL, label: "1x", variant: ghost },
+                    { type: button, action: SPEED_DOUBLE, label: "2x", variant: ghost },
+                    { type: button, action: SPEED_QUAD, label: "4x", variant: ghost }
+                  ] },
+                { type: typography, variant: caption, content: (str/concat "Steps: " @entity.steps " — sim time: " (math/round @entity.simTime 1) " s — speed: " @entity.speedMultiplier "x") }
+              ] }
+          ]
+        })
+        (emit SIM_3D_UPDATED { running: @entity.running, speedMultiplier: @entity.speedMultiplier, steps: @entity.steps, simTime: @entity.simTime })
+
+      SPEED_NORMAL -> idle when (== @entity.active true)
+        (set @entity.speedMultiplier 1)
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RUN, label: "Run", variant: primary },
+                    { type: button, action: PAUSE, label: "Pause", variant: secondary },
+                    { type: button, action: RESET, label: "Reset", variant: ghost }
+                  ] },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: SPEED_HALF, label: "0.5x", variant: ghost },
+                    { type: button, action: SPEED_NORMAL, label: "1x", variant: ghost },
+                    { type: button, action: SPEED_DOUBLE, label: "2x", variant: ghost },
+                    { type: button, action: SPEED_QUAD, label: "4x", variant: ghost }
+                  ] },
+                { type: typography, variant: caption, content: (str/concat "Steps: " @entity.steps " — sim time: " (math/round @entity.simTime 1) " s — speed: " @entity.speedMultiplier "x") }
+              ] }
+          ]
+        })
+        (emit SIM_3D_UPDATED { running: @entity.running, speedMultiplier: @entity.speedMultiplier, steps: @entity.steps, simTime: @entity.simTime })
+
+      SPEED_DOUBLE -> idle when (== @entity.active true)
+        (set @entity.speedMultiplier 2)
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RUN, label: "Run", variant: primary },
+                    { type: button, action: PAUSE, label: "Pause", variant: secondary },
+                    { type: button, action: RESET, label: "Reset", variant: ghost }
+                  ] },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: SPEED_HALF, label: "0.5x", variant: ghost },
+                    { type: button, action: SPEED_NORMAL, label: "1x", variant: ghost },
+                    { type: button, action: SPEED_DOUBLE, label: "2x", variant: ghost },
+                    { type: button, action: SPEED_QUAD, label: "4x", variant: ghost }
+                  ] },
+                { type: typography, variant: caption, content: (str/concat "Steps: " @entity.steps " — sim time: " (math/round @entity.simTime 1) " s — speed: " @entity.speedMultiplier "x") }
+              ] }
+          ]
+        })
+        (emit SIM_3D_UPDATED { running: @entity.running, speedMultiplier: @entity.speedMultiplier, steps: @entity.steps, simTime: @entity.simTime })
+
+      SPEED_QUAD -> idle when (== @entity.active true)
+        (set @entity.speedMultiplier 4)
+        (render-ui main {
+          type: box
+          padding: md
+          children: [
+            { type: stack, direction: vertical, gap: md, children: [
+                { type: typography, variant: h4, content: @entity.title },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: RUN, label: "Run", variant: primary },
+                    { type: button, action: PAUSE, label: "Pause", variant: secondary },
+                    { type: button, action: RESET, label: "Reset", variant: ghost }
+                  ] },
+                { type: stack, direction: horizontal, gap: sm, children: [
+                    { type: button, action: SPEED_HALF, label: "0.5x", variant: ghost },
+                    { type: button, action: SPEED_NORMAL, label: "1x", variant: ghost },
+                    { type: button, action: SPEED_DOUBLE, label: "2x", variant: ghost },
+                    { type: button, action: SPEED_QUAD, label: "4x", variant: ghost }
+                  ] },
+                { type: typography, variant: caption, content: (str/concat "Steps: " @entity.steps " — sim time: " (math/round @entity.simTime 1) " s — speed: " @entity.speedMultiplier "x") }
+              ] }
+          ]
+        })
+        (emit SIM_3D_UPDATED { running: @entity.running, speedMultiplier: @entity.speedMultiplier, steps: @entity.steps, simTime: @entity.simTime })
+    }
+
+    ticks {
+      simTick every 32ms
+        when (== @entity.running true)
+        (let (
+          (dtEff (* @config.dt @entity.speedMultiplier))
+        )
+        (do
+          (set @entity.steps (+ @entity.steps 1))
+          (set @entity.simTime (+ @entity.simTime @dtEff))
+          (emit SIM_3D_TICK { dt: @dtEff, simTime: @entity.simTime })
+        ))
+    }
+
+    listens {
+      MODE_SELECTED {
+        mode : string
+      }
+        @description "Lab router broadcast naming the active mode; this instrument renders when the mode equals matchMode, otherwise renders null."
+        @tier "domain"
+    }
+
+    emits {
+      SIM_3D_TICK -> external {
+        dt : number
+        simTime : number
+      }
+        @description "Fires every 32ms tick while running with the effective timestep (config dt x speed multiplier) and accumulated sim time — the clock a composed physics trait subscribes to; a harmless no-op when the atom runs standalone."
+        @synonyms "tick, frame, step, clock, sim update, telemetry"
+        @tier "domain"
+      SIM_3D_UPDATED -> external {
+        running : boolean
+        speedMultiplier : number
+        steps : int
+        simTime : number
+      }
+        @description "Fires on INIT/MODE_SELECTED/Run/Pause/Reset/speed change with the transport state — running flag, speed multiplier, step counter, and sim time — a composed listener (readout, graph) can subscribe; a harmless no-op when the atom runs standalone."
+        @synonyms "run, pause, reset, speed, transport, sim state"
+        @tier "domain"
+    }
+
+    config {
+      matchMode : string = ""
+        @label "Match Mode"
+        @description "When composed behind a lab router, the MODE_SELECTED mode value this instrument responds to. Empty string means standalone — render immediately on INIT."
+        @tier "presentation"
+      title : string = "3D Simulation"
+        @label "Title"
+        @description "Title shown above the transport controls."
+        @tier "presentation"
+      dt : number = 0.02
+        @label "Timestep"
+        @description "Simulated seconds per tick before the speed multiplier; the effective step emitted on SIM_3D_TICK is dt x speedMultiplier."
+        @tier "domain"
+      running : boolean = true
+        @label "Running"
+        @description "When true the clock starts ticking on INIT; the Reset arm restores this value."
+        @tier "domain"
+    }
+  }
+
+  page "/learn-sim-3d" as Learn3DSimPage -> Learn3DSimTransport
+}