@almadar/std 16.243.0 → 16.244.1

package/behaviors/lolo/ui/core/atoms/std-hero.lolo

@@ -1,5 +1,5 @@
 app std-hero "1.0.0"
-"std-hero — the headline block at the top of a page, or a call-to-action banner further down. Optional eyebrow badge, headline, supporting text, up to two link actions, an optional copyable command, and optional media below or beside the copy. `look: banner` turns it into a contained call-to-action card. Links follow `href` (in-app path, #anchor, or absolute URL); each click also emits CTA_PRIMARY / CTA_SECONDARY with the href. Pick for landing, product, pricing and campaign pages."
+"std-hero — the headline block at the top of a page, or a call-to-action banner further down. Optional eyebrow badge, headline, supporting text, up to two link actions, an optional copyable command, optional media below or beside the copy, and an optional backdrop scene behind it all. `look: banner` turns it into a contained call-to-action card. Links follow `href` (in-app path, #anchor, or absolute URL); each click also emits CTA_PRIMARY / CTA_SECONDARY with the href. Pick for landing, product, pricing and campaign pages."
 orbital HeroOrbital {
   entity HeroView [runtime] {
     id : string!
@@ -109,6 +109,17 @@ orbital HeroOrbital {
         @label "Surface"
         @description "Background behind the block"
         @tier "presentation"
+      height : "auto" | "tall" = auto
+        @label "Height"
+        @description "auto fits the copy; tall fills most of the screen with the copy centred, for a hero over a backdrop scene"
+        @tier "presentation"
+      backdropContent : render-ui = {
+        type: box
+        className: "hidden"
+      }
+        @label "Backdrop"
+        @description "A scene behind the whole block, such as an animated canvas; it fills the block, never takes clicks, and the copy stays on top. Empty by default."
+        @tier "presentation"
       copyContent : render-ui = {
         type: stack
         direction: vertical
@@ -189,24 +200,38 @@ orbital HeroOrbital {
         paddingY: (if (== @config.look banner) xl "2xl")
         bg: (if (== @config.surface muted) muted transparent)
         fullWidth: true
+        position: relative
+        overflow: hidden
+        className: (if (== @config.height tall) "flex min-h-[80vh] items-center" "")
         children: [{
-          type: container
-          size: xl
-          maxWidth: xl
-          padding: lg
+          type: box
+          position: absolute
+          className: "inset-0 pointer-events-none"
+          aria-hidden: true
+          children: [@config.backdropContent]
+        }, {
+          type: box
+          position: relative
+          fullWidth: true
           children: [{
-            type: box
-            padding: (if (== @config.look banner) xl none)
-            rounded: (if (== @config.look banner) "2xl" none)
-            border: (== @config.look banner)
-            bg: (if (== @config.look banner) muted transparent)
-            children: [{
-              type: stack
-              direction: vertical
-              gap: "2xl"
-              align: (if (== @config.alignment center) center stretch)
-              children: [@config.copyContent, @config.mediaContent]
-            }]
+              type: container
+              size: xl
+              maxWidth: xl
+              padding: lg
+              children: [{
+                type: box
+                padding: (if (== @config.look banner) xl none)
+                rounded: (if (== @config.look banner) "2xl" none)
+                border: (== @config.look banner)
+                bg: (if (== @config.look banner) muted transparent)
+                children: [{
+                  type: stack
+                  direction: vertical
+                  gap: "2xl"
+                  align: (if (== @config.alignment center) center stretch)
+                  children: [@config.copyContent, @config.mediaContent]
+                }]
+              }]
           }]
         }]
       }
@@ -217,24 +242,38 @@ orbital HeroOrbital {
         paddingY: (if (== @config.look banner) xl "2xl")
         bg: (if (== @config.surface muted) muted transparent)
         fullWidth: true
+        position: relative
+        overflow: hidden
+        className: (if (== @config.height tall) "flex min-h-[80vh] items-center" "")
         children: [{
-          type: container
-          size: xl
-          maxWidth: xl
-          padding: lg
+          type: box
+          position: absolute
+          className: "inset-0 pointer-events-none"
+          aria-hidden: true
+          children: [@config.backdropContent]
+        }, {
+          type: box
+          position: relative
+          fullWidth: true
           children: [{
-            type: box
-            padding: (if (== @config.look banner) xl none)
-            rounded: (if (== @config.look banner) "2xl" none)
-            border: (== @config.look banner)
-            bg: (if (== @config.look banner) muted transparent)
-            children: [{
-              type: split
-              ratio: "1:1"
-              gap: xl
-              align: center
-              children: [@config.copyContent, @config.mediaContent]
-            }]
+              type: container
+              size: xl
+              maxWidth: xl
+              padding: lg
+              children: [{
+                type: box
+                padding: (if (== @config.look banner) xl none)
+                rounded: (if (== @config.look banner) "2xl" none)
+                border: (== @config.look banner)
+                bg: (if (== @config.look banner) muted transparent)
+                children: [{
+                  type: split
+                  ratio: "1:1"
+                  gap: xl
+                  align: center
+                  children: [@config.copyContent, @config.mediaContent]
+                }]
+              }]
           }]
         }]
       }

package/behaviors/lolo/ui/core/molecules/ui-agent-chat-feed.lolo

@@ -202,7 +202,7 @@ orbital AgentChatFeedOrbital {
         @tier "presentation"
       idPrefix : string = ""
         @label "Id Prefix"
-        @description "Prefix for the toolbar test id and the switch's element id."
+        @description "Prefix for the scroller test id and the switch's element id."
         @tier "presentation"
       working : boolean = false
         @label "Working"

package/behaviors/lolo/ui/core/molecules/ui-markdown-content.lolo

@@ -2,6 +2,12 @@ app ui-markdown-content "1.0.0"
 "MarkdownContent — UI factory (1:1 with the @almadar/ui markdown-content pattern)."
 ;; @pattern "markdown-content"
 orbital MarkdownContentOrbital {
+  type MarkdownContentAnnotationsItem = {
+    id : string!
+    text : string!
+    kind : "question" | "note"!
+  }
+
   entity MarkdownContentItem [runtime] {
     id : string!
   }
@@ -14,6 +20,12 @@ orbital MarkdownContentOrbital {
         (render-ui main {
           content: @config.content
           direction: @config.direction
+          askEvent: @config.askEvent
+          noteEvent: @config.noteEvent
+          askLabel: @config.askLabel
+          noteLabel: @config.noteLabel
+          annotations: @config.annotations
+          annotationEvent: @config.annotationEvent
           className: @config.className
           enter: @config.enter
           enterDelay: @config.enterDelay
@@ -36,6 +48,24 @@ orbital MarkdownContentOrbital {
         })
     }
 
+    emits {
+      @config.askEvent -> external {
+        selectedText : string!
+      }
+        @description "Event emitted when the reader picks Ask on selected text (as `UI:<askEvent>`)"
+        @tier "essential"
+      @config.noteEvent -> external {
+        selectedText : string!
+      }
+        @description "Event emitted when the reader picks Note on selected text (as `UI:<noteEvent>`)"
+        @tier "essential"
+      @config.annotationEvent -> external {
+        annotationId : string
+      }
+        @description "Event emitted when a highlighted passage is clicked (as `UI:<annotationEvent>`)"
+        @tier "essential"
+    }
+
     config {
       content : string = ""
         @label "Content"
@@ -45,6 +75,30 @@ orbital MarkdownContentOrbital {
         @label "Direction"
         @description "Text direction (defaults to ltr; `ltr` is first so the generated config seeds it)"
         @tier "presentation"
+      askEvent : event = "ASK"
+        @label "Ask Event"
+        @description "Event emitted when the reader picks Ask on selected text (as `UI:<askEvent>`)"
+        @tier "presentation"
+      noteEvent : event = "NOTE"
+        @label "Note Event"
+        @description "Event emitted when the reader picks Note on selected text (as `UI:<noteEvent>`)"
+        @tier "presentation"
+      askLabel : string
+        @label "Ask Label"
+        @description "Ask action label (default: translated)"
+        @tier "presentation"
+      noteLabel : string
+        @label "Note Label"
+        @description "Note action label (default: translated)"
+        @tier "presentation"
+      annotations : [MarkdownContentAnnotationsItem] = []
+        @label "Annotations"
+        @description "Passages to highlight. Each `text` is matched exactly, first occurrence in document order inside a single rendered text node (outside code); a passage that spans formatting boundaries is not highlighted."
+        @tier "presentation"
+      annotationEvent : event = "ANNOTATION"
+        @label "Annotation Event"
+        @description "Event emitted when a highlighted passage is clicked (as `UI:<annotationEvent>`)"
+        @tier "presentation"
       className : string
         @label "Class Name"
         @description "Additional CSS classes"

package/behaviors/lolo/ui/core/molecules/ui-upload-drop-zone.lolo

@@ -26,6 +26,7 @@ orbital UploadDropZoneOrbital {
           description: @config.description
           icon: @config.icon
           disabled: @config.disabled
+          readAs: @config.readAs
           action: @config.action
           actionPayload: @config.actionPayload
           className: @config.className
@@ -87,6 +88,10 @@ orbital UploadDropZoneOrbital {
         @label "Disabled"
         @description "Disabled state"
         @tier "presentation"
+      readAs : "dataUrl" | "text" = dataUrl
+        @label "Read As"
+        @description "How the file is read into `content`: a base64 data URL (default) or its UTF-8 text"
+        @tier "presentation"
       action : event = "ACTION"
         @label "Action"
         @description "Declarative event name for file selection"

package/behaviors/lolo/ui/core/organisms/ui-segment-renderer.lolo

@@ -2,11 +2,50 @@ app ui-segment-renderer "1.0.0"
 "SegmentRenderer — UI factory (1:1 with the @almadar/ui segment-renderer pattern)."
 ;; @pattern "segment-renderer"
 orbital SegmentRendererOrbital {
-  type SegmentRendererSegmentsItem = {
+  type SegmentRendererSegmentsItem = SegmentRendererSegmentsItemMarkdown | SegmentRendererSegmentsItemCode | SegmentRendererSegmentsItemQuiz | SegmentRendererSegmentsItemActivate | SegmentRendererSegmentsItemConnect | SegmentRendererSegmentsItemReflect | SegmentRendererSegmentsItemBloom | SegmentRendererSegmentsItemVisualization
+  type SegmentRendererSegmentsItemMarkdown = {
+    type : "markdown"!
+    content : string!
+  }
+  type SegmentRendererSegmentsItemCode = {
+    type : "code"!
+    language : string!
+    content : string!
+    runnable : boolean
+  }
+  type SegmentRendererSegmentsItemQuiz = {
     type : "quiz"!
     question : string!
     answer : string!
   }
+  type SegmentRendererSegmentsItemActivate = {
+    type : "activate"!
+    question : string!
+  }
+  type SegmentRendererSegmentsItemConnect = {
+    type : "connect"!
+    content : string!
+  }
+  type SegmentRendererSegmentsItemReflect = {
+    type : "reflect"!
+    prompt : string!
+  }
+  type SegmentRendererSegmentsItemBloom = {
+    type : "bloom"!
+    level : "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create"!
+    question : string!
+    answer : string!
+  }
+  type SegmentRendererSegmentsItemVisualization = {
+    type : "visualization"!
+    visualizationType : "algorithms" | "math" | "physics" | "biology" | "chemistry" | "probability"!
+    description : string!
+  }
+  type SegmentRendererAnnotationsItem = {
+    id : string!
+    text : string!
+    kind : "question" | "note"!
+  }
   type SegmentRendererUserProgress = {
     activationResponse : string
     reflectionNotes : [string]
@@ -24,6 +63,16 @@ orbital SegmentRendererOrbital {
       INIT -> idle
         (render-ui main {
           segments: @config.segments
+          lesson: @config.lesson
+          activationSaveEvent: @config.activationSaveEvent
+          reflectionSaveEvent: @config.reflectionSaveEvent
+          bloomAnswerEvent: @config.bloomAnswerEvent
+          askEvent: @config.askEvent
+          noteEvent: @config.noteEvent
+          askLabel: @config.askLabel
+          noteLabel: @config.noteLabel
+          annotations: @config.annotations
+          annotationEvent: @config.annotationEvent
           className: @config.className
           containerClassName: @config.containerClassName
           userProgress: @config.userProgress
@@ -48,10 +97,85 @@ orbital SegmentRendererOrbital {
         })
     }
 
+    emits {
+      @config.activationSaveEvent -> external {
+        response : string!
+      }
+        @description "Event emitted when the activation prompt is saved or skipped (as `UI:<activationSaveEvent>`)"
+        @tier "essential"
+      @config.reflectionSaveEvent -> external {
+        index : number!
+        note : string!
+      }
+        @description "Event emitted when a reflection note is saved (as `UI:<reflectionSaveEvent>`)"
+        @tier "essential"
+      @config.bloomAnswerEvent -> external {
+        index : number!
+        level : "remember" | "understand" | "apply" | "analyze" | "evaluate" | "create"!
+      }
+        @description "Event emitted on the first reveal of a Bloom question (as `UI:<bloomAnswerEvent>`)"
+        @tier "essential"
+      @config.askEvent -> external {
+        selectedText : string!
+      }
+        @description "Event emitted when the reader picks Ask on selected text (as `UI:<askEvent>`)"
+        @tier "essential"
+      @config.noteEvent -> external {
+        selectedText : string!
+      }
+        @description "Event emitted when the reader picks Note on selected text (as `UI:<noteEvent>`)"
+        @tier "essential"
+      @config.annotationEvent -> external {
+        annotationId : string
+      }
+        @description "Event emitted when a highlighted passage is clicked (as `UI:<annotationEvent>`)"
+        @tier "essential"
+    }
+
     config {
-      segments : [SegmentRendererSegmentsItem] = [{ type: quiz, question: "Question", answer: "Answer" }, { type: quiz, question: "Question 2", answer: "Answer 2" }]
+      segments : [SegmentRendererSegmentsItem] = []
         @label "Segments"
-        @description "Parsed lesson segments (see `parseLessonSegments`)"
+        @description "Parsed lesson segments (see `parseLessonSegments`). Ignored when `lesson` is given."
+        @tier "presentation"
+      lesson : string
+        @label "Lesson"
+        @description "Raw lesson markdown with learning tags; parsed with `parseLessonSegments` and rendered"
+        @tier "presentation"
+      activationSaveEvent : event = "ACTIVATION_SAVE"
+        @label "Activation Save Event"
+        @description "Event emitted when the activation prompt is saved or skipped (as `UI:<activationSaveEvent>`)"
+        @tier "presentation"
+      reflectionSaveEvent : event = "REFLECTION_SAVE"
+        @label "Reflection Save Event"
+        @description "Event emitted when a reflection note is saved (as `UI:<reflectionSaveEvent>`)"
+        @tier "presentation"
+      bloomAnswerEvent : event = "BLOOM_ANSWER"
+        @label "Bloom Answer Event"
+        @description "Event emitted on the first reveal of a Bloom question (as `UI:<bloomAnswerEvent>`)"
+        @tier "presentation"
+      askEvent : event = "ASK"
+        @label "Ask Event"
+        @description "Event emitted when the reader picks Ask on selected text (as `UI:<askEvent>`)"
+        @tier "presentation"
+      noteEvent : event = "NOTE"
+        @label "Note Event"
+        @description "Event emitted when the reader picks Note on selected text (as `UI:<noteEvent>`)"
+        @tier "presentation"
+      askLabel : string
+        @label "Ask Label"
+        @description "Ask action label (default: translated)"
+        @tier "presentation"
+      noteLabel : string
+        @label "Note Label"
+        @description "Note action label (default: translated)"
+        @tier "presentation"
+      annotations : [SegmentRendererAnnotationsItem] = []
+        @label "Annotations"
+        @description "Passages to highlight. Each `text` is matched exactly against the markdown segments, first segment whose source contains it, first occurrence inside one rendered text node (outside code); one that spans formatting is not highlighted."
+        @tier "presentation"
+      annotationEvent : event = "ANNOTATION"
+        @label "Annotation Event"
+        @description "Event emitted when a highlighted passage is clicked (as `UI:<annotationEvent>`)"
         @tier "presentation"
       className : string
         @label "Class Name"

package/behaviors/lolo/ui/core/organisms/ui-state-machine-view.lolo

@@ -2,6 +2,23 @@ app ui-state-machine-view "1.0.0"
 "StateMachineView — UI factory (1:1 with the @almadar/ui state-machine-view pattern)."
 ;; @pattern "state-machine-view"
 orbital StateMachineViewOrbital {
+  type StateMachineViewAnnotations = {
+    states : Map string StateMachineViewAnnotationsStatesValue
+    transitions : Map string StateMachineViewAnnotationsTransitionsValue
+    effects : Map string StateMachineViewAnnotationsEffectsValue
+  }
+  type StateMachineViewAnnotationsStatesValue = {
+    title : string
+    body : string!
+  }
+  type StateMachineViewAnnotationsTransitionsValue = {
+    title : string
+    body : string!
+  }
+  type StateMachineViewAnnotationsEffectsValue = {
+    title : string
+    body : string!
+  }
   type StateMachineViewTrait = {
     name : string!
     linkedEntity : string!
@@ -62,6 +79,7 @@ orbital StateMachineViewOrbital {
           entityFields: @config.entityFields
           direction: @config.direction
           showHeader: @config.showHeader
+          annotations: @config.annotations
           className: @config.className
           trait: @config.traitProp
           isLoading: @config.isLoading
@@ -153,6 +171,10 @@ orbital StateMachineViewOrbital {
         @label "Show Header"
         @description "Show the trait header (name, entity, listens/emits). @default true"
         @tier "presentation"
+      annotations : StateMachineViewAnnotations = { states: { pending: { title: "Unpaid", body: "Every order starts here." } }, transitions: { PAY: { body: "Only fires when the amount is positive." } }, effects: { persist: { body: "Saves the order." } } }
+        @label "Annotations"
+        @description "Author explanations shown in a popover on hover: a note per state name, per transition event and per effect type."
+        @tier "presentation"
       className : string
         @label "Class Name"
         @description "className prop"

package/behaviors/lolo/ui/core/templates/ui-dashboard-layout.lolo

@@ -152,9 +152,9 @@ orbital DashboardLayoutOrbital {
         @label "On Sign Out"
         @description "Callback when user clicks sign out (optional - uses auth context signOut if not provided)"
         @tier "presentation"
-      layoutMode : "sidebar" | "topnav" | "bottomnav" | "minimal" = sidebar
+      layoutMode : "sidebar" | "topnav" | "bottomnav" | "minimal" | "drawer" = sidebar
         @label "Layout Mode"
-        @description "Layout mode. Default `'sidebar'`. - `sidebar`: Left sidebar nav + top header (classic dashboard) - `topnav`: Horizontal nav in header, no sidebar - `bottomnav`: Bottom tab bar, no sidebar - `minimal`: No nav chrome, content only"
+        @description "Layout mode. Default `'sidebar'`. - `sidebar`: Left sidebar nav + top header (classic dashboard) - `topnav`: Horizontal nav in header, no sidebar - `bottomnav`: Bottom tab bar, no sidebar - `minimal`: No nav chrome, content only - `drawer`: Sidebar nav behind a menu button at every width; content gets the full width"
         @tier "presentation"
       children : node
         @label "Children"