@almadar/std 16.183.0 → 16.185.0

package/behaviors/lolo/ui/core/molecules/ui-file-tree.lolo

@@ -9,6 +9,12 @@ orbital FileTreeOrbital {
     size : number
     language : string
   }
+  type FileTreeItemsItem = {
+    id : string!
+    label : string!
+    parentId : string
+    icon : string
+  }
 
   entity FileTreeItem [runtime] {
     id : string!
@@ -21,8 +27,10 @@ orbital FileTreeOrbital {
       INIT -> idle
         (render-ui main {
           tree: @config.tree
+          items: @config.items
           selectedPath: @config.selectedPath
           onFileSelect: @config.onFileSelect
+          onNodeSelect: @config.onNodeSelect
           className: @config.className
           indent: @config.indent
           type: file-tree
@@ -38,9 +46,13 @@ orbital FileTreeOrbital {
     }
 
     config {
-      tree : [FileTreeTreeItem] = [{ name: "Name", path: "Path", type: file, children: [], size: 1, language: "Language" }, { name: "Name 2", path: "Path 2", type: dir, children: [], size: 2, language: "Language 2" }]
+      tree : [FileTreeTreeItem] = []
         @label "Tree"
-        @description "The tree data"
+        @description "The tree data (pre-nested). Ignored when `items` is provided."
+        @tier "presentation"
+      items : [FileTreeItemsItem] = []
+        @label "Items"
+        @description "Flat node list, nested by `parentId` at render time — takes precedence over `tree` when provided. A `parentId` with no matching row renders that node as a root rather than dropping it."
         @tier "presentation"
       selectedPath : string
         @label "Selected Path"
@@ -50,6 +62,10 @@ orbital FileTreeOrbital {
         @label "On File Select"
         @description "Called when a file is clicked"
         @tier "presentation"
+      onNodeSelect : string = ""
+        @label "On Node Select"
+        @description "Called when a node is clicked, in flat `items` mode; carries the selected node's id. Presence-gated: binding this prop is what turns on the click-to-select affordance, mirroring Badge's `onRemove`."
+        @tier "presentation"
       className : string
         @label "Class Name"
         @description "CSS class"

package/behaviors/lolo/ui/core/organisms/ui-detail-panel.lolo

@@ -41,7 +41,11 @@ orbital DetailPanelOrbital {
     header : string
     type : string
     values : [string]
-    relation : string
+    relation : DetailPanelFieldsItemRelation
+  }
+  type DetailPanelFieldsItemRelation = {
+    entity : string!
+    cardinality : "one" | "many" | "one-to-many" | "many-to-one" | "many-to-many"
   }
   type DetailPanelRelationsDataValueItem = {
     value : string!
@@ -74,6 +78,7 @@ orbital DetailPanelOrbital {
           selectedIds: @config.selectedIds
           entity: @entity
           title: @config.title
+          onTitleCommit: @config.onTitleCommit
           subtitle: @config.subtitle
           status: @config.status
           avatar: @config.avatar
@@ -109,6 +114,7 @@ orbital DetailPanelOrbital {
           selectedIds: @config.selectedIds
           entity: @payload.data
           title: @config.title
+          onTitleCommit: @config.onTitleCommit
           subtitle: @config.subtitle
           status: @config.status
           avatar: @config.avatar
@@ -188,6 +194,10 @@ orbital DetailPanelOrbital {
         @label "Title"
         @description "title prop"
         @tier "presentation"
+      onTitleCommit : string = ""
+        @label "On Title Commit"
+        @description "When bound, the title becomes editable in place: clicking it swaps the heading for an input, Enter or blur commits, Escape reverts. Receives the committed title and the record's id so the host can persist a partial update. Unbound, the title stays a plain heading."
+        @tier "presentation"
       subtitle : string
         @label "Subtitle"
         @description "subtitle prop"
@@ -224,7 +234,7 @@ orbital DetailPanelOrbital {
         @label "Slide Over"
         @description "slideOver prop"
         @tier "presentation"
-      fields : [DetailPanelFieldsItem] = [{ key: "Key", header: "Header", type: "Type", values: ["Item", "Item 2"], relation: "Relation" }, { key: "Key 2", header: "Header 2", type: "Type 2", values: ["Item", "Item 2"], relation: "Relation 2" }]
+      fields : [DetailPanelFieldsItem] = [{ key: "Key", header: "Header", type: "Type", values: ["Item", "Item 2"], relation: { entity: "Entity", cardinality: one } }, { key: "Key 2", header: "Header 2", type: "Type 2", values: ["Item", "Item 2"], relation: { entity: "Entity 2", cardinality: many } }]
         @label "Fields"
         @description "Fields to display - accepts string[], {key, header}[], or DetailField[]"
         @tier "presentation"

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

@@ -29,7 +29,7 @@ orbital FormSectionOrbital {
   type FormSectionFieldsItemRelation = {
     entity : string!
     displayField : string
-    cardinality : "one" | "many"
+    cardinality : "one" | "many" | "one-to-many" | "many-to-one" | "many-to-many"
   }
   type FormSectionFieldsItemValidation = {
     enum : [string]
@@ -108,7 +108,7 @@ orbital FormSectionOrbital {
   type FormSectionSectionsItemFieldsItemRelation = {
     entity : string!
     displayField : string
-    cardinality : "one" | "many"
+    cardinality : "one" | "many" | "one-to-many" | "many-to-one" | "many-to-many"
   }
   type FormSectionSectionsItemFieldsItemValidation = {
     enum : [string]

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

@@ -29,7 +29,7 @@ orbital FormOrbital {
   type FormFieldsItemRelation = {
     entity : string!
     displayField : string
-    cardinality : "one" | "many"
+    cardinality : "one" | "many" | "one-to-many" | "many-to-one" | "many-to-many"
   }
   type FormFieldsItemValidation = {
     enum : [string]
@@ -108,7 +108,7 @@ orbital FormOrbital {
   type FormSectionsItemFieldsItemRelation = {
     entity : string!
     displayField : string
-    cardinality : "one" | "many"
+    cardinality : "one" | "many" | "one-to-many" | "many-to-one" | "many-to-many"
   }
   type FormSectionsItemFieldsItemValidation = {
     enum : [string]

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

@@ -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
                     }