@almadar/std 16.242.0 → 16.244.0

package/behaviors/lolo/agent/atoms/std-agent-tool-loop.lolo

@@ -1,5 +1,5 @@
 app std-agent-tool-loop "2.0.0"
-"std-agent-tool-loop — answers a conversation by operating the running app as the caller, through `call-service llm call-tools`. Its `tools` are `{ scope: declared }` (every declared external input plus a read over every persisted entity), or named declared inputs (addressed like a listens source: `Trait.EVENT`, `Orbital.Trait.EVENT`) and entities to read; each input fires as the signed-in user through the ordinary dispatch (guards and entity policies apply) and each read returns only the rows the caller may read. Headless: the conversation UI (std-agent-session) shows the reply; a failure shows as a toast. CONVERSE carries the conversation (and optionally what std-agent-memory recalled); ASSISTANT_STEP carries each step live while it works (a model call, a tool it used, what the app answered) to the asking tab; ASSISTANT_REPLIED carries the reply, every step and the token usage; ASSISTANT_REPLY_FAILED carries the error. These names are the assistant contract std-agent-session's conversation hears from any orbital. Compose with std-agent-session (the conversation) and std-agent-trace (the step record)."
+"std-agent-tool-loop — answers a conversation by operating the running app as the caller, through `call-service llm call-tools`. Its `tools` are `{ scope: declared }` (every declared external input plus a read over every persisted entity), or named declared inputs (addressed like a listens source: `Trait.EVENT`, `Orbital.Trait.EVENT`) and entities to read; each input fires as the signed-in user through the ordinary dispatch (guards and entity policies apply) and each read returns only the rows the caller may read. Headless: the conversation UI (std-agent-session) shows the reply; a failure shows as a toast, unless `quiet` is on (a background run nobody is watching: no live steps and no toast). CONVERSE carries the conversation (and optionally what std-agent-memory recalled); ASSISTANT_STEP carries each step live while it works (a model call, a tool it used, what the app answered) to the asking tab; ASSISTANT_REPLIED carries the reply, every step and the token usage; ASSISTANT_REPLY_FAILED carries the error. These names are the assistant contract std-agent-session's conversation hears from any orbital. Compose with std-agent-session (the conversation) and std-agent-trace (the step record)."
 
 type AgentTool = {
   event : event
@@ -63,6 +63,7 @@ orbital AgentToolLoopOrbital {
     status : "idle" | "thinking" | "answered" | "failed" @description "Where the current turn is." = idle
     reply : string @description "The last reply." = ""
     error : string @description "Why the last turn failed." = ""
+    ephemeral : boolean @description "The current turn belongs to an ephemeral conversation." = false
   }
 
   trait AgentToolLoop -> AgentTurn [interaction] {
@@ -81,33 +82,73 @@ orbital AgentToolLoopOrbital {
         @label "Model round-trips per request"
         @description "How many model calls one request may take before it fails."
         @tier "policy"
+      quiet : boolean = false
+        @label "Run in the background?"
+        @description "No live ASSISTANT_STEP stream and no failure toast: the request is reported only through ASSISTANT_REPLIED and ASSISTANT_REPLY_FAILED. For a run nobody is watching, such as one the app starts on its own."
+        @synonyms "silent, background, no toast, suppress errors, headless run"
+        @tier "policy"
+      cancelKey : string = "agent-tool-loop"
+        @label "Cancel key"
+        @description "The key this instance's model call runs under, so CANCEL aborts it. Give each instance of the loop in one app its own."
+        @synonyms "call key, abort key"
+        @tier "internal"
     }
     initial: idle
 
     state idle {
       INIT -> idle
         (set @entity.status idle)
-      CONVERSE -> thinking
+      CONVERSE -> thinking when (and (not @config.quiet) (not ?ephemeral))
+        (set @entity.status thinking)
+        (set @entity.ephemeral false)
+        (call-service llm call-tools {
+          messages: ?messages
+          tools: @config.tools
+          instructions: (if ["=", (str/default ?context ""), ""] @config.instructions (str/concat @config.instructions "\n\nWhat you remember that may be relevant:\n" ?context))
+          maxSteps: @config.maxSteps
+        } {
+          key: @config.cancelKey, emit: { failure: ASK_FAILED, success: ANSWERED, onMessage: ASSISTANT_STEP }
+        })
+      CONVERSE -> thinking when (and @config.quiet (not ?ephemeral))
         (set @entity.status thinking)
+        (set @entity.ephemeral false)
         (call-service llm call-tools {
           messages: ?messages
           tools: @config.tools
           instructions: (if ["=", (str/default ?context ""), ""] @config.instructions (str/concat @config.instructions "\n\nWhat you remember that may be relevant:\n" ?context))
           maxSteps: @config.maxSteps
         } {
-          emit: { failure: ASK_FAILED, success: ANSWERED, onMessage: ASSISTANT_STEP }
+          key: @config.cancelKey, emit: { failure: ASK_FAILED, success: ANSWERED }
+        })
+      CONVERSE -> thinking when ?ephemeral
+        (set @entity.status thinking)
+        (set @entity.ephemeral true)
+        (call-service llm call-tools {
+          messages: ?messages
+          tools: (object/get ? tools [])
+          instructions: (if ["=", (str/default ?instructions ""), ""] @config.instructions ?instructions)
+          maxSteps: @config.maxSteps
+        } {
+          key: @config.cancelKey, emit: { failure: ASK_FAILED, success: ANSWERED }
         })
     }
 
     state thinking {
+      CANCEL -> idle
+        (cancel-call @config.cancelKey)
+        (set @entity.status idle)
       ANSWERED -> idle
         (set @entity.status answered)
         (set @entity.reply ?reply)
-        (emit ASSISTANT_REPLIED { reply: ?reply, steps: ?steps, usage: ?usage })
-      ASK_FAILED -> idle
+        (emit ASSISTANT_REPLIED { reply: ?reply, steps: ?steps, usage: ?usage, ephemeral: @entity.ephemeral })
+      ASK_FAILED -> idle when (or @config.quiet @entity.ephemeral)
         (set @entity.status failed)
         (set @entity.error ?error)
-        (emit ASSISTANT_REPLY_FAILED { error: ?error })
+        (emit ASSISTANT_REPLY_FAILED { error: ?error, ephemeral: @entity.ephemeral })
+      ASK_FAILED -> idle when (and (not @config.quiet) (not @entity.ephemeral))
+        (set @entity.status failed)
+        (set @entity.error ?error)
+        (emit ASSISTANT_REPLY_FAILED { error: ?error, ephemeral: @entity.ephemeral })
         (render-ui toast {
           message: ?error
           type: alert
@@ -126,12 +167,14 @@ orbital AgentToolLoopOrbital {
         reply : string!
         steps : [AgentActivity]!
         usage : AgentUsage!
+        ephemeral : boolean
       }
-        @description "The assistant answered; carries every tool step it took and the tokens it used."
+        @description "The assistant answered; carries every tool step it took and the tokens it used. `ephemeral` echoes the conversation's: an ephemeral reply is not stored or remembered, and only an ephemeral conversation shows it."
         @synonyms "answered, responded, done"
         @tier "domain"
       ASSISTANT_REPLY_FAILED -> external {
         error : string!
+        ephemeral : boolean
       }
         @description "The assistant could not answer (model unavailable, or out of steps)."
         @synonyms "failed, error, gave up"
@@ -149,11 +192,18 @@ orbital AgentToolLoopOrbital {
     }
 
     listens {
+      CANCEL {
+      }
+        @description "Abort the request in flight; nothing is replied and no failure is reported."
+        @synonyms "stop, abort, cancel"
       CONVERSE {
         messages : [AgentChatMessage]!
         context : string
+        instructions : string
+        tools : [AgentTool]
+        ephemeral : boolean
       }
-        @description "Answer this conversation; the last turn is the request. `context` is what the assistant remembers that may be relevant."
+        @description "Answer this conversation; the last turn is the request. `context` is what the assistant remembers that may be relevant. An `ephemeral` conversation runs under its own `instructions` (empty: the configured ones) and exactly its own `tools` (absent or `[]`: none, never the configured ones), streams no live steps and shows no failure toast."
         @synonyms "ask, chat, request"
     }
   }

package/behaviors/lolo/agent/organisms/std-agent-assistant.lolo

@@ -110,6 +110,7 @@ orbital AgentAssistantOrbital {
     }
     listens {
       AssistantThread.REQUEST_CONTEXT -> COMPACT
+      *.ASSISTANT_EPHEMERAL_SEND -> COMPACT
     }
   }
 

package/behaviors/lolo/infra/atoms/std-page-search.lolo

@@ -6,6 +6,8 @@ orbital PageSearchOrbital {
     selector : string
     attr : string
     resolve : boolean
+    template : string
+    required : boolean
   }
 
   type PageResult = {
@@ -51,7 +53,7 @@ orbital PageSearchOrbital {
         @tier "domain"
       fields : Map string PageField = {}
         @label "Fields"
-        @description "Field name to how to read it from each result: `selector` (a descendant; absent reads the result itself), `attr` (an attribute; absent reads the text) and `resolve` (the attribute is a URL: return it absolute)"
+        @description "Field name to how to read it from each result: `selector` (a descendant; absent reads the result itself), `attr` (an attribute; absent reads the text) , `resolve` (the value is a URL: return it absolute), `template` (compose the value from other fields, `{name}` per field; empty when any is empty) and `required` (leave the result out until this field reads non-empty)"
         @synonyms "columns, properties, extract"
         @tier "domain"
       maxResults : number = 10

package/behaviors/lolo/infra/atoms/std-page-treat.lolo

@@ -1,7 +1,19 @@
 app std-page-treat "1.0.0"
-"std-page-treat — applies a declared visual treatment to one element of a browser tab (hide, blur, highlight, or label it with text) or restores it, and reports which element it treated. TREAT takes the tab and element id std-page-watch reports. The treatments are a fixed, declared set: no arbitrary styles or scripts. Needs a host with the `page` service (a browser extension)."
+"std-page-treat — applies a declared visual treatment to one element of a browser tab (hide, blur, highlight, or label it with text) or restores it, and reports which element it treated. TREAT takes the tab and element id std-page-watch reports; TREAT_MANY treats a whole list at once and reports which elements were treated and which had already left their page. The treatments are a fixed, declared set: no arbitrary styles or scripts. Needs a host with the `page` service (a browser extension)."
 
 orbital PageTreatOrbital {
+  type PageTreatment = {
+    tab : number!
+    elementId : string!
+    treatment : "hide" | "blur" | "highlight" | "label" | "restore"
+    label : string
+  }
+
+  type PageElementRef = {
+    tab : number!
+    elementId : string!
+  }
+
   entity PageTreatRecord [runtime] {
     treated : number @description "How many treatments were applied" @synonyms "count, applied" = 0
     errorMessage : string @description "Why the last treatment failed; blank = none" @synonyms "error, failure reason" = ""
@@ -27,6 +39,12 @@ orbital PageTreatOrbital {
       APPLIED -> ready
         (set @entity.treated (+ @entity.treated 1))
         (emit TREATED { tab: ?tab, elementId: ?elementId, treatment: ?treatment })
+      TREAT_MANY -> ready
+        (call-service "page" "applyMany" { items: ?items }
+          { emit: { success: APPLIED_MANY, failure: APPLY_FAILED } })
+      APPLIED_MANY -> ready
+        (set @entity.treated (+ @entity.treated (array/len ?applied)))
+        (emit TREATED_MANY { applied: ?applied, missing: ?missing })
       APPLY_FAILED -> ready
         (set @entity.errorMessage ?error)
         (emit TREAT_FAILED { error: ?error })
@@ -37,6 +55,9 @@ orbital PageTreatOrbital {
       APPLIED { applied : boolean!, tab : number!, elementId : string!, treatment : "hide" | "blur" | "highlight" | "label" | "restore" }
         @description "The page service applied the treatment"
         @tier "secondary"
+      APPLIED_MANY { applied : [PageElementRef], missing : [PageElementRef] }
+        @description "The page service applied a list of treatments"
+        @tier "secondary"
       APPLY_FAILED { error : string! }
         @description "The page service could not apply the treatment"
         @tier "secondary"
@@ -44,6 +65,10 @@ orbital PageTreatOrbital {
         @description "The element now shows the treatment (or, for restore, is back as it was)"
         @synonyms "hidden, blurred, highlighted, labelled, restored"
         @tier "primary"
+      TREATED_MANY -> external { applied : [PageElementRef], missing : [PageElementRef] }
+        @description "Each listed element now shows its treatment; `missing` lists those that had left their page (or whose tab closed)"
+        @synonyms "hidden, blurred, restored, treated"
+        @tier "primary"
       TREAT_FAILED -> external { error : string! }
         @description "The treatment could not be applied (the element is gone, or the tab closed)"
         @tier "primary"
@@ -52,6 +77,8 @@ orbital PageTreatOrbital {
     listens {
       TREAT -> external { tab : number!, elementId : string!, treatment : "hide" | "blur" | "highlight" | "label" | "restore", label : string }
         @description "Treat one page element; `label` is the text shown with it (for example why it was hidden)"
+      TREAT_MANY -> external { items : [PageTreatment] }
+        @description "Treat a list of page elements in one call, each with its own treatment and label"
     }
   }
 

package/behaviors/lolo/infra/atoms/std-page-watch.lolo

@@ -6,6 +6,8 @@ orbital PageWatchOrbital {
     selector : string
     attr : string
     resolve : boolean
+    template : string
+    required : boolean
   }
 
   entity PageWatchRecord [runtime] {
@@ -36,7 +38,7 @@ orbital PageWatchOrbital {
         @tier "domain"
       fields : Map string PageField = {}
         @label "Fields"
-        @description "Field name to how to read it from each element: `selector` (a descendant; absent reads the element itself), `attr` (an attribute; absent reads the text) and `resolve` (the attribute is a URL: return it absolute)"
+        @description "Field name to how to read it from each element: `selector` (a descendant; absent reads the element itself), `attr` (an attribute; absent reads the text) , `resolve` (the value is a URL: return it absolute), `template` (compose the value from other fields, `{name}` per field; empty when any is empty) and `required` (leave the element out until this field reads non-empty — a placeholder is reported once it fills in)"
         @synonyms "columns, properties, extract, read"
         @tier "domain"
       itemEvent : event = "PageWatch.ITEM_FOUND"

package/behaviors/lolo/ui/avl/atoms/ui-avl-state-machine.lolo

@@ -27,6 +27,23 @@ orbital AvlStateMachineOrbital {
     type : string!
     args : [SExpr]!
   }
+  type AvlStateMachineAnnotations = {
+    states : Map string AvlStateMachineAnnotationsStatesValue
+    transitions : Map string AvlStateMachineAnnotationsTransitionsValue
+    effects : Map string AvlStateMachineAnnotationsEffectsValue
+  }
+  type AvlStateMachineAnnotationsStatesValue = {
+    title : string
+    body : string!
+  }
+  type AvlStateMachineAnnotationsTransitionsValue = {
+    title : string
+    body : string!
+  }
+  type AvlStateMachineAnnotationsEffectsValue = {
+    title : string
+    body : string!
+  }
   type AvlStateMachineTRANSITIONCLICKTransition = {
     index : number!
     event : string!
@@ -57,6 +74,7 @@ orbital AvlStateMachineOrbital {
           entityFields: @config.entityFields
           direction: @config.direction
           showHeader: @config.showHeader
+          annotations: @config.annotations
           className: @config.className
           enter: @config.enter
           enterDelay: @config.enterDelay
@@ -150,6 +168,10 @@ orbital AvlStateMachineOrbital {
         @label "Show Header"
         @description "Show the trait header (name, entity, listens/emits). @default true"
         @tier "presentation"
+      annotations : AvlStateMachineAnnotations = { 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/avl/atoms/ui-avl-transition-explainer.lolo

@@ -0,0 +1,175 @@
+app ui-avl-transition-explainer "1.0.0"
+"One transition explained step by step: from-state, event and to-state, the guard that must hold, and each effect it runs in order. — UI factory (1:1 with the @almadar/ui avl-transition-explainer pattern)."
+;; @capabilities "transition explainer, event guard effects walkthrough, what happens when an event fires"
+;; @pattern "avl-transition-explainer"
+orbital AvlTransitionExplainerOrbital {
+  type AvlTransitionExplainerTransition = {
+    from : string!
+    to : string!
+    event : string!
+    guard : SExpr
+    effects : [AvlTransitionExplainerTransitionEffectsItem]!
+    index : number!
+  }
+  type AvlTransitionExplainerTransitionEffectsItem = {
+    type : string!
+    args : [SExpr]!
+  }
+  type AvlTransitionExplainerAnnotations = {
+    states : Map string AvlTransitionExplainerAnnotationsStatesValue
+    transitions : Map string AvlTransitionExplainerAnnotationsTransitionsValue
+    effects : Map string AvlTransitionExplainerAnnotationsEffectsValue
+  }
+  type AvlTransitionExplainerAnnotationsStatesValue = {
+    title : string
+    body : string!
+  }
+  type AvlTransitionExplainerAnnotationsTransitionsValue = {
+    title : string
+    body : string!
+  }
+  type AvlTransitionExplainerAnnotationsEffectsValue = {
+    title : string
+    body : string!
+  }
+
+  entity AvlTransitionExplainerItem [runtime] {
+    id : string!
+  }
+
+  trait AvlTransitionExplainerRender -> @rebindable AvlTransitionExplainerItem [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (render-ui main {
+          orbitalName: @config.orbitalName
+          traitName: @config.traitName
+          transition: @config.transition
+          annotations: @config.annotations
+          className: @config.className
+          enter: @config.enter
+          enterDelay: @config.enterDelay
+          skeleton: @config.skeleton
+          aria-label: @config.ariaLabel
+          aria-labelledby: @config.ariaLabelledby
+          aria-describedby: @config.ariaDescribedby
+          aria-live: @config.ariaLive
+          aria-current: @config.ariaCurrent
+          aria-pressed: @config.ariaPressed
+          aria-expanded: @config.ariaExpanded
+          aria-selected: @config.ariaSelected
+          aria-hidden: @config.ariaHidden
+          aria-busy: @config.ariaBusy
+          role: @config.role
+          lang: @config.lang
+          dir: @config.dir
+          tabIndex: @config.tabIndex
+          type: avl-transition-explainer
+        })
+    }
+
+    config {
+      orbitalName : string = ""
+        @label "Orbital Name"
+        @description "Orbital the transition belongs to."
+        @tier "presentation"
+      traitName : string = ""
+        @label "Trait Name"
+        @description "Trait the transition belongs to."
+        @tier "presentation"
+      transition : AvlTransitionExplainerTransition = { from: "pending", to: "paid", event: "PAY", effects: [{ type: "set", args: [] }, { type: "persist", args: [] }], index: 0 }
+        @label "Transition"
+        @description "The transition to explain."
+        @tier "presentation"
+      annotations : AvlTransitionExplainerAnnotations = { transitions: { PAY: { title: "Paying", body: "The customer pays the order total." } }, effects: { persist: { body: "Saves the order." } } }
+        @label "Annotations"
+        @description "Author explanations shown in a popover on hover: the event's note and per-effect-type notes."
+        @tier "presentation"
+      className : string
+        @label "Class Name"
+        @description "className prop"
+        @tier "presentation"
+      enter : "none" | "fade" | "rise" | "scale" | "slide"
+        @label "Enter"
+        @description "How this element animates in when it mounts (theme-styled); overrides the theme's default slot entry. `none` opts out."
+        @tier "presentation"
+      enterDelay : number
+        @label "Enter Delay"
+        @description "Stagger step for the entry: waits this many `--motion-enter-stagger` steps before animating."
+        @tier "presentation"
+      skeleton : "header" | "table" | "list" | "grid" | "detail" | "stats" | "form" | "card" | "text" | "none"
+        @label "Skeleton"
+        @description "Skeleton shown while this element's server render is in flight: a shape (`table`, `list`, …), `{ variant, rows?, columns?, fields? }`, or `none`."
+        @tier "presentation"
+      ariaLabel : string
+        @label "Aria-label"
+        @description "Accessible name read by screen readers when the visible text is missing or not descriptive (e.g. an icon-only control)."
+        @synonyms "aria-label"
+        @tier "presentation"
+      ariaLabelledby : string
+        @label "Aria-labelledby"
+        @description "Id of the element whose text names this one."
+        @synonyms "aria-labelledby"
+        @tier "presentation"
+      ariaDescribedby : string
+        @label "Aria-describedby"
+        @description "Id of the element whose text describes this one (help text, error)."
+        @synonyms "aria-describedby"
+        @tier "presentation"
+      ariaLive : "off" | "polite" | "assertive"
+        @label "Aria-live"
+        @description "Announce changes to this region: polite waits for a pause, assertive interrupts."
+        @synonyms "aria-live"
+        @tier "presentation"
+      ariaCurrent : "page" | "step" | "location" | "date" | "time" | "true" | "false"
+        @label "Aria-current"
+        @description "Marks the current item in a set: the current page, step, location, date or time."
+        @synonyms "aria-current"
+        @tier "presentation"
+      ariaPressed : "true" | "false" | "mixed"
+        @label "Aria-pressed"
+        @description "Toggle-button state."
+        @synonyms "aria-pressed"
+        @tier "presentation"
+      ariaExpanded : boolean
+        @label "Aria-expanded"
+        @description "Whether the element it controls is expanded."
+        @synonyms "aria-expanded"
+        @tier "presentation"
+      ariaSelected : boolean
+        @label "Aria-selected"
+        @description "Whether this item is selected (tabs, options, grid cells)."
+        @synonyms "aria-selected"
+        @tier "presentation"
+      ariaHidden : boolean
+        @label "Aria-hidden"
+        @description "Hide from assistive technology (decorative content only)."
+        @synonyms "aria-hidden"
+        @tier "presentation"
+      ariaBusy : boolean
+        @label "Aria-busy"
+        @description "This region is updating; assistive technology waits before announcing it."
+        @synonyms "aria-busy"
+        @tier "presentation"
+      role : "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "meter" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"
+        @label "Role"
+        @description "WAI-ARIA role when the element's native semantics don't describe it."
+        @tier "presentation"
+      lang : string
+        @label "Lang"
+        @description "Language of this element's content (BCP 47, e.g. ar, sl, en)."
+        @tier "presentation"
+      dir : "ltr" | "rtl" | "auto"
+        @label "Dir"
+        @description "Text direction of this element's content."
+        @tier "presentation"
+      tabIndex : number
+        @label "Tab Index"
+        @description "0 puts the element in the Tab order; -1 makes it focusable only programmatically."
+        @tier "presentation"
+    }
+  }
+
+  page "/avl-transition-explainer" as AvlTransitionExplainerPage -> AvlTransitionExplainerRender
+}

package/behaviors/lolo/ui/avl/atoms/ui-module-card.lolo

@@ -61,6 +61,23 @@ orbital ModuleCardOrbital {
     direction : string!
     traitName : string!
   }
+  type ModuleCardAnnotationsValue = {
+    states : Map string ModuleCardAnnotationsValueStatesValue
+    transitions : Map string ModuleCardAnnotationsValueTransitionsValue
+    effects : Map string ModuleCardAnnotationsValueEffectsValue
+  }
+  type ModuleCardAnnotationsValueStatesValue = {
+    title : string
+    body : string!
+  }
+  type ModuleCardAnnotationsValueTransitionsValue = {
+    title : string
+    body : string!
+  }
+  type ModuleCardAnnotationsValueEffectsValue = {
+    title : string
+    body : string!
+  }
 
   entity ModuleCardItem [runtime] {
     id : string!
@@ -73,6 +90,7 @@ orbital ModuleCardOrbital {
       INIT -> idle
         (render-ui main {
           data: @config.data
+          annotations: @config.annotations
           aria-label: @config.ariaLabel
           aria-labelledby: @config.ariaLabelledby
           aria-describedby: @config.ariaDescribedby
@@ -96,6 +114,10 @@ orbital ModuleCardOrbital {
         @label "Data"
         @description "The orbital to summarize."
         @tier "presentation"
+      annotations : Map string ModuleCardAnnotationsValue = { item: {} }
+        @label "Annotations"
+        @description "Author explanations per trait name (states, transition events, effect types), shown in a popover on hover."
+        @tier "presentation"
       ariaLabel : string
         @label "Aria-label"
         @description "Accessible name read by screen readers when the visible text is missing or not descriptive (e.g. an icon-only control)."

package/behaviors/lolo/ui/core/atoms/std-app-layout.lolo

@@ -28,6 +28,7 @@ orbital AppLayoutOrbital {
           type: box
           children: [{
             appName: @config.appName
+            logo: (if (== @config.logoSrc "") null { type: image, src: @config.logoSrc, alt: "", fit: contain, className: "h-8 w-8" })
             children: [{
               children: [@config.contentTrait]
               className: @config.contentClassName
@@ -40,7 +41,8 @@ orbital AppLayoutOrbital {
             navItems: (array/map (array/filter @config.navItems (fn item (or (= (array/len (object/get @item roles [])) 0) (array/includes (object/get @item roles []) @config.viewerRole)))) (fn item (if (object/has @item children) (object/merge @item { children: (array/filter (object/get @item children []) (fn child (or (= (array/len (object/get @child roles [])) 0) (array/includes (object/get @child roles []) @config.viewerRole)))) }) @item)))
             notificationClickEvent: @config.notificationClickEvent
             notifications: @config.notifications
-            searchEvent: @config.searchEvent
+            searchEvent: (if @config.showSearch @config.searchEvent null)
+            showThemeToggle: @config.showThemeToggle
             sidebarContent: @config.sidebarTrait
             topBarActions: (array/filter @config.topBarActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
             type: @config.layoutPattern
@@ -58,6 +60,7 @@ orbital AppLayoutOrbital {
           type: box
           children: [{
             appName: @config.appName
+            logo: (if (== @config.logoSrc "") null { type: image, src: @config.logoSrc, alt: "", fit: contain, className: "h-8 w-8" })
             children: [{
               children: [{
                 description: @config.accessDeniedDescription
@@ -75,7 +78,8 @@ orbital AppLayoutOrbital {
             navItems: (array/map (array/filter @config.navItems (fn item (or (= (array/len (object/get @item roles [])) 0) (array/includes (object/get @item roles []) @config.viewerRole)))) (fn item (if (object/has @item children) (object/merge @item { children: (array/filter (object/get @item children []) (fn child (or (= (array/len (object/get @child roles [])) 0) (array/includes (object/get @child roles []) @config.viewerRole)))) }) @item)))
             notificationClickEvent: @config.notificationClickEvent
             notifications: @config.notifications
-            searchEvent: @config.searchEvent
+            searchEvent: (if @config.showSearch @config.searchEvent null)
+            showThemeToggle: @config.showThemeToggle
             sidebarContent: @config.sidebarTrait
             topBarActions: (array/filter @config.topBarActions (fn action (or (= (array/len (object/get @action roles [])) 0) (array/includes (object/get @action roles []) @config.viewerRole))))
             type: @config.layoutPattern
@@ -137,6 +141,11 @@ orbital AppLayoutOrbital {
         @description "Name shown in the top-left of the chrome header."
         @synonyms "app title, product name, brand name, application name, site name"
         @tier "presentation"
+      logoSrc : string = ""
+        @label "Logo image"
+        @description "Address of the logo shown beside the app name in the chrome header (an image URL or an inline data: SVG); empty shows the name's first letter."
+        @synonyms "logo, brand mark, app icon, logo url"
+        @tier "presentation"
       viewerName : string = ""
         @label "Who is signed in"
         @description "Display name of the signed-in viewer, shown in the app bar's account menu — typically @user.name. Blank renders no account menu, so people can see which account (and which persona) they are viewing the app as only when it is actually known."
@@ -159,6 +168,16 @@ orbital AppLayoutOrbital {
         @label "Search event"
         @description "Event emitted when the user runs a global search"
         @tier "internal"
+      showSearch : boolean = true
+        @label "Show the search box?"
+        @description "The top-bar search box; turn off for apps whose pages carry their own search."
+        @synonyms "search bar, top search, hide search"
+        @tier "presentation"
+      showThemeToggle : boolean = true
+        @label "Show the light/dark toggle?"
+        @description "The theme toggle in the top bar; turn off when the app offers it elsewhere, such as a settings page."
+        @synonyms "dark mode button, theme switch, hide theme toggle"
+        @tier "presentation"
       topBarActions : [ItemAction] = []
         @label "What shortcuts go in the top bar?"
         @description "Icon buttons shown on the right side of the top bar (e.g. cart, help, profile)."
@@ -177,9 +196,9 @@ orbital AppLayoutOrbital {
         @label "Layout pattern"
         @description "UI pattern used to render the application chrome"
         @tier "internal"
-      layoutMode : "sidebar" | "topnav" | "bottomnav" | "minimal" = sidebar
+      layoutMode : "sidebar" | "topnav" | "bottomnav" | "minimal" | "drawer" = sidebar
         @label "Where should navigation be placed?"
-        @description "sidebar = left rail; topnav = top bar; bottomnav = mobile tab bar; minimal = no nav."
+        @description "sidebar = left rail; topnav = top bar; bottomnav = mobile tab bar; minimal = no nav; drawer = navigation behind a menu button at every width, content full width."
         @synonyms "nav position, navigation style, menu placement, layout style"
         @tier "presentation"
       currentPath : string = ""