@almadar/std 16.183.0 → 16.184.0

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

@@ -1,12 +1,11 @@
 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."
+"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
-    media : string
-    mediaAlt : string
+    demoId : string
   }
 
   entity TutorialState [runtime, shared] {
@@ -15,6 +14,15 @@ orbital TutorialOverlayOrbital {
     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
 
@@ -32,7 +40,7 @@ orbital TutorialOverlayOrbital {
           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" }
+            @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: [
@@ -41,6 +49,8 @@ orbital TutorialOverlayOrbital {
             ] }
           ]
         })
+        (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)
@@ -50,7 +60,7 @@ orbital TutorialOverlayOrbital {
           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" }
+            @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: [
@@ -59,6 +69,8 @@ orbital TutorialOverlayOrbital {
             ] }
           ]
         })
+        (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 {
@@ -70,7 +82,7 @@ orbital TutorialOverlayOrbital {
           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" }
+            @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: [
@@ -80,10 +92,14 @@ orbital TutorialOverlayOrbital {
             ] }
           ]
         })
+        (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)
@@ -94,7 +110,7 @@ orbital TutorialOverlayOrbital {
           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" }
+            @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: [
@@ -104,10 +120,14 @@ orbital TutorialOverlayOrbital {
             ] }
           ]
         })
+        (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" })
     }
 
@@ -142,6 +162,15 @@ orbital TutorialOverlayOrbital {
       }
         @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 {
@@ -151,7 +180,11 @@ orbital TutorialOverlayOrbital {
     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)."
+        @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"

package/behaviors/lolo/ui/learning/atoms/ui-math-canvas.lolo

@@ -307,15 +307,15 @@ orbital MathCanvasOrbital {
         @tier "presentation"
       backgroundColor : string
         @label "Background Color"
-        @description "Canvas fill color; accepts theme-token refs like var(--color-background, transparent) — resolved against the active theme at draw time. Default transparent."
+        @description "Canvas fill color; `var(--token, fallback)` strings resolve against the active theme. Default transparent."
         @tier "presentation"
       gridColor : string = "var(--color-border, #9ca3af)"
         @label "Grid Color"
-        @description "Grid line color; theme-token aware (defaults to the active theme's border color at 35% opacity, falling back to neutral gray)."
+        @description "Grid line color; resolves theme tokens (default `var(--color-border, #9ca3af)`)."
         @tier "presentation"
       axisColor : string = "var(--color-muted-foreground, #374151)"
         @label "Axis Color"
-        @description "Axis line color; theme-token aware (defaults to the active theme's muted-foreground, falling back to slate)."
+        @description "Axis line color; resolves theme tokens (default `var(--color-muted-foreground, #374151)`)."
         @tier "presentation"
       showTickLabels : boolean = false
         @label "Show Tick Labels"

package/behaviors/registry/ui/core/atoms/std-browse.orb

@@ -945,6 +945,17 @@
               "tier": "internal",
               "type": "string"
             },
+            "include": {
+              "default": [],
+              "description": "Entity relation field names to hydrate on fetch (e.g. a `tag : Category` field named `tag`), so grid columns can use dot-paths like tag.name. Empty = no hydration, the default.",
+              "items": {
+                "type": "string"
+              },
+              "label": "Which relation fields to hydrate?",
+              "synonyms": "relation hydration, populate relations, joined fields, hydrate relations",
+              "tier": "internal",
+              "type": "[string]"
+            },
             "initialFilterField": {
               "default": "",
               "description": "Name the field the INITIAL load filters on, paired with initialFilterValue. This is the detail half of a list-detail pair: a thread that must wait for a conversation to be picked sets the field to its parent key and leaves the value blank, so the first load matches nothing and the empty state shows instead of every record in the table. REFETCH_FILTER then supplies the real selection. Left blank the first load is unfiltered, which is the default.",
@@ -1727,6 +1738,7 @@
                           ]
                         ]
                       ],
+                      "include": "@config.include",
                       "limit": "@config.pageSize",
                       "offset": 0.0
                     }
@@ -1888,6 +1900,7 @@
                           ]
                         ]
                       ],
+                      "include": "@config.include",
                       "limit": "@config.pageSize",
                       "offset": 0.0
                     }
@@ -1945,6 +1958,7 @@
                           ]
                         ]
                       ],
+                      "include": "@config.include",
                       "limit": "@config.pageSize",
                       "offset": 0.0
                     }
@@ -2002,6 +2016,7 @@
                           ]
                         ]
                       ],
+                      "include": "@config.include",
                       "limit": "@config.pageSize",
                       "offset": 0.0
                     }
@@ -2039,6 +2054,7 @@
                           "@user.id"
                         ]
                       ],
+                      "include": "@config.include",
                       "limit": "@config.pageSize",
                       "offset": [
                         "*",
@@ -2218,6 +2234,7 @@
                           ]
                         ]
                       ],
+                      "include": "@config.include",
                       "limit": "@config.pageSize",
                       "offset": 0.0
                     }

package/behaviors/registry/ui/core/atoms/std-related.orb

@@ -46,6 +46,24 @@
         "parent": "trt_01KXG04HAWB43BWZ07VSETQEW3",
         "renames": []
       },
+      "evt_01M0RY3YKG5AXYCBSMYMGG5B4E": {
+        "bakedName": "SHOW_RELATED",
+        "curName": "SHOW_RELATED",
+        "id": "evt_01M0RY3YKG5AXYCBSMYMGG5B4E",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KXG04HAWB43BWZ07VSETQEW3",
+        "renames": []
+      },
+      "evt_01M0RY3YKG814RWTP8NGJZCGG7": {
+        "bakedName": "SELECT_RELATED",
+        "curName": "SELECT_RELATED",
+        "id": "evt_01M0RY3YKG814RWTP8NGJZCGG7",
+        "kind": "event",
+        "owner": "workspace",
+        "parent": "trt_01KXG04HAWB43BWZ07VSETQEW3",
+        "renames": []
+      },
       "orb_01KXG04HAW4F728HDBS2FDVGF1": {
         "bakedName": "RelatedItemOrbital",
         "curName": "RelatedItemOrbital",
@@ -114,6 +132,13 @@
         {
           "category": "interaction",
           "config": {
+            "relationField": {
+              "default": "",
+              "description": "RelatedItem field compared against SHOW_RELATED's key to scope the fetch to one parent document; empty renders the full unfiltered collection (default).",
+              "label": "Relation field",
+              "tier": "domain",
+              "type": "string"
+            },
             "tableLook": {
               "default": "dense",
               "description": "Layer 2 visual treatment for the data table rendered by this atom.",
@@ -127,6 +152,13 @@
                 "borderless",
                 "card-rows"
               ]
+            },
+            "title": {
+              "default": "Related",
+              "description": "Heading shown above the related list.",
+              "label": "Section title",
+              "tier": "presentation",
+              "type": "string"
             }
           },
           "emits": [
@@ -161,6 +193,25 @@
               "scope": "internal",
               "synonyms": "error, failure, problem, unsuccessful",
               "tier": "internal"
+            },
+            {
+              "description": "Signals a related item was selected to drive a detail view.",
+              "event": "SELECT_RELATED",
+              "eventId": "evt_01M0RY3YKG814RWTP8NGJZCGG7",
+              "payloadSchema": [
+                {
+                  "name": "id",
+                  "required": true,
+                  "type": "string"
+                },
+                {
+                  "name": "name",
+                  "type": "string"
+                }
+              ],
+              "scope": "external",
+              "synonyms": "select, choose, open, view",
+              "tier": "domain"
             }
           ],
           "entityContract": {
@@ -183,6 +234,21 @@
                 "key": "INIT",
                 "name": "Initialize"
               },
+              {
+                "description": "Scopes the related fetch to rows whose relationField equals key.",
+                "id": "evt_01M0RY3YKG5AXYCBSMYMGG5B4E",
+                "key": "SHOW_RELATED",
+                "name": "Show Related",
+                "payloadSchema": [
+                  {
+                    "name": "key",
+                    "required": true,
+                    "type": "string"
+                  }
+                ],
+                "synonyms": "scope, filter, focus, target",
+                "tier": "domain"
+              },
               {
                 "description": "Signals that related items have been successfully loaded.",
                 "id": "evt_01KXG04HB00F39QDW8TJMSKNJ9",
@@ -215,6 +281,25 @@
                 "synonyms": "error, failure, problem, unsuccessful",
                 "tier": "internal"
               },
+              {
+                "description": "Signals a related item was selected to drive a detail view.",
+                "id": "evt_01M0RY3YKG814RWTP8NGJZCGG7",
+                "key": "SELECT_RELATED",
+                "name": "Select Related",
+                "payloadSchema": [
+                  {
+                    "name": "id",
+                    "required": true,
+                    "type": "string"
+                  },
+                  {
+                    "name": "name",
+                    "type": "string"
+                  }
+                ],
+                "synonyms": "select, choose, open, view",
+                "tier": "domain"
+              },
               {
                 "id": "evt_01KYXKHATCCRC9NH1SPH7KH8BC",
                 "key": "RETRY",
@@ -274,6 +359,63 @@
                 "from": "loading",
                 "to": "loading"
               },
+              {
+                "effects": [
+                  [
+                    "fetch",
+                    "RelatedItem",
+                    {
+                      "emit": {
+                        "failure": "RelatedItemLoadFailed",
+                        "success": "RelatedItemLoaded"
+                      },
+                      "filter": [
+                        "or",
+                        [
+                          "=",
+                          "@config.relationField",
+                          ""
+                        ],
+                        [
+                          "=",
+                          [
+                            "object/get",
+                            "@entity",
+                            "@config.relationField"
+                          ],
+                          "@payload.key"
+                        ]
+                      ]
+                    }
+                  ],
+                  [
+                    "render-ui",
+                    "main",
+                    {
+                      "align": "center",
+                      "children": [
+                        {
+                          "type": "spinner"
+                        },
+                        {
+                          "color": "muted",
+                          "content": "Loading related…",
+                          "type": "typography",
+                          "variant": "caption"
+                        }
+                      ],
+                      "className": "py-8",
+                      "direction": "vertical",
+                      "gap": "sm",
+                      "type": "stack"
+                    }
+                  ]
+                ],
+                "event": "SHOW_RELATED",
+                "eventId": "evt_01M0RY3YKG5AXYCBSMYMGG5B4E",
+                "from": "loading",
+                "to": "loading"
+              },
               {
                 "effects": [
                   [
@@ -289,7 +431,7 @@
                               "type": "icon"
                             },
                             {
-                              "content": "Related",
+                              "content": "@config.title",
                               "type": "typography",
                               "variant": "h3"
                             }
@@ -309,15 +451,29 @@
                             "fn",
                             "item",
                             {
+                              "align": "center",
                               "children": [
                                 {
                                   "content": "@item.name",
                                   "type": "typography",
                                   "variant": "body"
+                                },
+                                {
+                                  "action": "SELECT_RELATED",
+                                  "actionPayload": {
+                                    "id": "@item.id",
+                                    "name": "@item.name"
+                                  },
+                                  "icon": "chevron-right",
+                                  "label": "Open",
+                                  "size": "sm",
+                                  "type": "button",
+                                  "variant": "ghost"
                                 }
                               ],
-                              "direction": "vertical",
+                              "direction": "horizontal",
                               "gap": "xs",
+                              "justify": "between",
                               "type": "stack"
                             }
                           ],
@@ -404,6 +560,61 @@
                 "from": "loaded",
                 "to": "loading"
               },
+              {
+                "effects": [
+                  [
+                    "set",
+                    "@entity.id",
+                    "@payload.id"
+                  ]
+                ],
+                "event": "SELECT_RELATED",
+                "eventId": "evt_01M0RY3YKG814RWTP8NGJZCGG7",
+                "from": "loaded",
+                "to": "loaded"
+              },
+              {
+                "effects": [
+                  [
+                    "fetch",
+                    "RelatedItem",
+                    {
+                      "emit": {
+                        "failure": "RelatedItemLoadFailed",
+                        "success": "RelatedItemLoaded"
+                      },
+                      "filter": [
+                        "or",
+                        [
+                          "=",
+                          "@config.relationField",
+                          ""
+                        ],
+                        [
+                          "=",
+                          [
+                            "object/get",
+                            "@entity",
+                            "@config.relationField"
+                          ],
+                          "@payload.key"
+                        ]
+                      ]
+                    }
+                  ],
+                  [
+                    "render-ui",
+                    "main",
+                    {
+                      "type": "spinner"
+                    }
+                  ]
+                ],
+                "event": "SHOW_RELATED",
+                "eventId": "evt_01M0RY3YKG5AXYCBSMYMGG5B4E",
+                "from": "loaded",
+                "to": "loading"
+              },
               {
                 "effects": [
                   [
@@ -453,6 +664,48 @@
                 "eventId": "evt_01KYXKHATCCRC9NH1SPH7KH8BC",
                 "from": "error",
                 "to": "loading"
+              },
+              {
+                "effects": [
+                  [
+                    "fetch",
+                    "RelatedItem",
+                    {
+                      "emit": {
+                        "failure": "RelatedItemLoadFailed",
+                        "success": "RelatedItemLoaded"
+                      },
+                      "filter": [
+                        "or",
+                        [
+                          "=",
+                          "@config.relationField",
+                          ""
+                        ],
+                        [
+                          "=",
+                          [
+                            "object/get",
+                            "@entity",
+                            "@config.relationField"
+                          ],
+                          "@payload.key"
+                        ]
+                      ]
+                    }
+                  ],
+                  [
+                    "render-ui",
+                    "main",
+                    {
+                      "type": "spinner"
+                    }
+                  ]
+                ],
+                "event": "SHOW_RELATED",
+                "eventId": "evt_01M0RY3YKG5AXYCBSMYMGG5B4E",
+                "from": "error",
+                "to": "loading"
               }
             ]
           }
@@ -461,5 +714,5 @@
     }
   ],
   "schemaVersion": 1,
-  "version": "1.0.0"
+  "version": "1.1.0"
 }