@almadar/std 16.233.0 → 16.235.0

package/behaviors/lolo/ui/avl/atoms/ui-avl-glyph.lolo

@@ -0,0 +1,54 @@
+app ui-avl-glyph "1.0.0"
+"AvlGlyph — UI factory (1:1 with the @almadar/ui avl-glyph pattern)."
+;; @pattern "avl-glyph"
+orbital AvlGlyphOrbital {
+  entity AvlGlyphItem [runtime] {
+    id : string!
+  }
+
+  trait AvlGlyphRender -> @rebindable AvlGlyphItem [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (render-ui main {
+          kind: @config.kind
+          label: @config.label
+          effectType: @config.effectType
+          size: @config.size
+          showCaption: @config.showCaption
+          className: @config.className
+          type: avl-glyph
+        })
+    }
+
+    config {
+      kind : "application" | "orbital" | "entity" | "trait" | "page" | "state" | "transition" | "event" | "guard" | "effect" | "field" | "fieldType" | "binding" | "bindingRef" | "persistence" | "operator" | "sexpr" | "literal" = state
+        @label "Kind"
+        @description "Which notation symbol to draw."
+        @tier "presentation"
+      label : string
+        @label "Label"
+        @description "Caption, and the drawn text for operator / literal / bindingRef symbols."
+        @tier "presentation"
+      effectType : string
+        @label "Effect Type"
+        @description "Effect symbol variant. @default 'set'"
+        @tier "presentation"
+      size : "sm" | "md" | "lg" = md
+        @label "Size"
+        @description "Symbol height. @default 'md'"
+        @tier "presentation"
+      showCaption : boolean = true
+        @label "Show Caption"
+        @description "Show the caption under the symbol. @default true"
+        @tier "presentation"
+      className : string
+        @label "Class Name"
+        @description "className prop"
+        @tier "presentation"
+    }
+  }
+
+  page "/avl-glyph" as AvlGlyphPage -> AvlGlyphRender
+}

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

@@ -0,0 +1,132 @@
+app ui-avl-state-machine "1.0.0"
+"AvlStateMachine — UI factory (1:1 with the @almadar/ui avl-state-machine pattern)."
+;; @pattern "avl-state-machine"
+orbital AvlStateMachineOrbital {
+  type AvlStateMachineTrait = {
+    name : string!
+    linkedEntity : string!
+    states : [AvlStateMachineTraitStatesItem]!
+    transitions : [AvlStateMachineTraitTransitionsItem]!
+    emittedEvents : [string]!
+    listenedEvents : [string]!
+  }
+  type AvlStateMachineTraitStatesItem = {
+    name : string!
+    isInitial : boolean
+    isTerminal : boolean
+  }
+  type AvlStateMachineTraitTransitionsItem = {
+    from : string!
+    to : string!
+    event : string!
+    guard : SExpr
+    effects : [AvlStateMachineTraitTransitionsItemEffectsItem]!
+    index : number!
+  }
+  type AvlStateMachineTraitTransitionsItemEffectsItem = {
+    type : string!
+    args : [SExpr]!
+  }
+
+  entity AvlStateMachineItem [runtime] {
+    id : string!
+  }
+
+  trait AvlStateMachineRender -> @rebindable AvlStateMachineItem [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (render-ui main {
+          trait: @config.traitProp
+          activeState: @config.activeState
+          activeTransition: @config.activeTransition
+          visitedStates: @config.visitedStates
+          stateClickEvent: @config.stateClickEvent
+          transitionClickEvent: @config.transitionClickEvent
+          selectedState: @config.selectedState
+          pendingSourceState: @config.pendingSourceState
+          nodeShape: @config.nodeShape
+          entityFields: @config.entityFields
+          direction: @config.direction
+          showHeader: @config.showHeader
+          className: @config.className
+          type: avl-state-machine
+        })
+    }
+
+    emits {
+      @config.stateClickEvent -> external {
+        stateId : string!
+      }
+        @description "Emits UI:{stateClickEvent} with { stateId } when a state is clicked."
+        @tier "essential"
+      @config.transitionClickEvent -> external {
+        index : number!
+        event : string!
+        from : string!
+        to : string!
+      }
+        @description "Emits UI:{transitionClickEvent} with { index, event, from, to } when a transition label is clicked."
+        @tier "essential"
+    }
+
+    config {
+      traitProp : AvlStateMachineTrait = { name: "OrderFlow", linkedEntity: "Order", states: [{ name: "browsing", isInitial: true, isTerminal: false }, { name: "editing", isInitial: false, isTerminal: false }, { name: "saving", isInitial: false, isTerminal: false }, { name: "confirmed", isInitial: false, isTerminal: true }, { name: "failed", isInitial: false, isTerminal: false }], transitions: [{ from: "browsing", to: "editing", event: "EDIT", effects: [{ type: "render-ui", args: [] }], index: 0 }, { from: "editing", to: "saving", event: "SAVE", effects: [{ type: "persist", args: [] }, { type: "notify", args: [] }], index: 1 }, { from: "saving", to: "confirmed", event: "SAVED", effects: [{ type: "emit", args: [] }, { type: "render-ui", args: [] }], index: 2 }, { from: "saving", to: "failed", event: "SAVE_FAILED", effects: [{ type: "notify", args: [] }], index: 3 }, { from: "failed", to: "editing", event: "RETRY", effects: [], index: 4 }, { from: "editing", to: "browsing", event: "CANCEL", effects: [{ type: "render-ui", args: [] }], index: 5 }, { from: "confirmed", to: "browsing", event: "DONE", effects: [{ type: "navigate", args: [] }], index: 6 }], emittedEvents: ["ORDER_SAVED"], listenedEvents: ["PAYMENT_OK"] }
+        @label "Trait"
+        @description "The trait to draw (see `parseTraitLevel`)."
+        @synonyms "trait"
+        @tier "presentation"
+      activeState : string
+        @label "Active State"
+        @description "State execution is currently in."
+        @tier "presentation"
+      activeTransition : number
+        @label "Active Transition"
+        @description "`index` of the transition that just fired."
+        @tier "presentation"
+      visitedStates : [string] = []
+        @label "Visited States"
+        @description "States already passed through, in order."
+        @tier "presentation"
+      stateClickEvent : event = "STATE_CLICK"
+        @label "State Click Event"
+        @description "Emits UI:{stateClickEvent} with { stateId } when a state is clicked."
+        @tier "presentation"
+      transitionClickEvent : event = "TRANSITION_CLICK"
+        @label "Transition Click Event"
+        @description "Emits UI:{transitionClickEvent} with { index, event, from, to } when a transition label is clicked."
+        @tier "presentation"
+      selectedState : string
+        @label "Selected State"
+        @description "State picked in an editor (first click)."
+        @tier "presentation"
+      pendingSourceState : string
+        @label "Pending Source State"
+        @description "Source of a transition being drawn — the next state click picks its target."
+        @tier "presentation"
+      nodeShape : "pill" | "gear" = pill
+        @label "Node Shape"
+        @description "Node silhouette. @default 'pill'"
+        @tier "presentation"
+      entityFields : [string] = []
+        @label "Entity Fields"
+        @description "Entity field names listed in the header."
+        @tier "presentation"
+      direction : "ltr" | "rtl" = ltr
+        @label "Direction"
+        @description "Flow direction. @default 'ltr'"
+        @tier "presentation"
+      showHeader : boolean = true
+        @label "Show Header"
+        @description "Show the trait header (name, entity, listens/emits). @default true"
+        @tier "presentation"
+      className : string
+        @label "Class Name"
+        @description "className prop"
+        @tier "presentation"
+    }
+  }
+
+  page "/avl-state-machine" as AvlStateMachinePage -> AvlStateMachineRender
+}

package/behaviors/lolo/ui/avl/atoms/ui-behavior-view.lolo

@@ -5,7 +5,6 @@ orbital BehaviorViewOrbital {
   type BehaviorViewData = {
     orbitalName : string!
     entityName : string!
-    persistence : string!
     fields : [BehaviorViewDataFieldsItem]!
     traits : [BehaviorViewDataTraitsItem]!
     pages : [BehaviorViewDataPagesItem]!
@@ -40,14 +39,14 @@ orbital BehaviorViewOrbital {
   }
   type BehaviorViewDataTraitDetailsValueStatesItem = {
     name : string!
-    isInitial : boolean!
-    isTerminal : boolean!
+    isInitial : boolean
+    isTerminal : boolean
   }
   type BehaviorViewDataTraitDetailsValueTransitionsItem = {
     from : string!
     to : string!
     event : string!
-    guard : SExpr!
+    guard : SExpr
     effects : [BehaviorViewDataTraitDetailsValueTransitionsItemEffectsItem]!
     index : number!
   }
@@ -78,9 +77,9 @@ orbital BehaviorViewOrbital {
     }
 
     config {
-      data : BehaviorViewData = { orbitalName: "Orbital Name", entityName: "Entity Name", persistence: "Persistence", fields: [{ name: "Name", type: "Type", required: false, hasDefault: false }, { name: "Name 2", type: "Type 2", required: true, hasDefault: true }], traits: [{ name: "Name", stateCount: 1, eventCount: 1, transitionCount: 1, emits: ["Item", "Item 2"], listens: ["Item", "Item 2"] }, { name: "Name 2", stateCount: 2, eventCount: 2, transitionCount: 2, emits: ["Item", "Item 2"], listens: ["Item", "Item 2"] }], pages: [{ name: "Name", route: "Route" }, { name: "Name 2", route: "Route 2" }], traitDetails: {}, externalLinks: [{ targetOrbital: "Target Orbital", eventName: "Event Name", direction: "Direction", traitName: "Trait Name" }, { targetOrbital: "Target Orbital 2", eventName: "Event Name 2", direction: "Direction 2", traitName: "Trait Name 2" }] }
+      data : BehaviorViewData = { orbitalName: "OrderOrbital", entityName: "Order", persistence: "persistent", fields: [{ name: "customer", type: "string", required: true, hasDefault: false }, { name: "qty", type: "number", required: true, hasDefault: true }, { name: "status", type: "string", required: false, hasDefault: true }], traits: [{ name: "OrderFlow", stateCount: 5, eventCount: 7, transitionCount: 7, emits: ["ORDER_SAVED"], listens: ["PAYMENT_OK"] }], pages: [{ name: "Orders", route: "/orders" }], traitDetails: { OrderFlow: { name: "OrderFlow", linkedEntity: "Order", states: [{ name: "browsing", isInitial: true, isTerminal: false }, { name: "editing", isInitial: false, isTerminal: false }, { name: "saving", isInitial: false, isTerminal: false }, { name: "confirmed", isInitial: false, isTerminal: true }, { name: "failed", isInitial: false, isTerminal: false }], transitions: [{ from: "browsing", to: "editing", event: "EDIT", effects: [{ type: "render-ui", args: [] }], index: 0 }, { from: "editing", to: "saving", event: "SAVE", effects: [{ type: "persist", args: [] }, { type: "notify", args: [] }], index: 1 }, { from: "saving", to: "confirmed", event: "SAVED", effects: [{ type: "emit", args: [] }, { type: "render-ui", args: [] }], index: 2 }, { from: "saving", to: "failed", event: "SAVE_FAILED", effects: [{ type: "notify", args: [] }], index: 3 }, { from: "failed", to: "editing", event: "RETRY", effects: [], index: 4 }, { from: "editing", to: "browsing", event: "CANCEL", effects: [{ type: "render-ui", args: [] }], index: 5 }, { from: "confirmed", to: "browsing", event: "DONE", effects: [{ type: "navigate", args: [] }], index: 6 }], emittedEvents: ["ORDER_SAVED"], listenedEvents: ["PAYMENT_OK"] } }, externalLinks: [{ targetOrbital: "PaymentOrbital", eventName: "PAYMENT_OK", direction: "in", traitName: "OrderFlow" }] }
         @label "Data"
-        @description "data prop"
+        @description "The orbital to summarize."
         @tier "presentation"
     }
   }

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

@@ -1,12 +1,11 @@
 app ui-module-card "1.0.0"
-"ModuleCard — a card summarizing one course module or lesson with progress and entry point. — UI factory (1:1 with the @almadar/ui module-card pattern)."
-;; @capabilities "course module card, lesson card, curriculum unit card, learning-path step card"
+"ModuleCard — a compact summary card for one orbital module: its entity and fields, a mini state machine per trait, and its pages. — UI factory (1:1 with the @almadar/ui module-card pattern)."
+;; @capabilities "orbital module summary card, entity and trait overview card, app architecture node card"
 ;; @pattern "module-card"
 orbital ModuleCardOrbital {
   type ModuleCardData = {
     orbitalName : string!
     entityName : string!
-    persistence : string!
     fields : [ModuleCardDataFieldsItem]!
     traits : [ModuleCardDataTraitsItem]!
     pages : [ModuleCardDataPagesItem]!
@@ -41,14 +40,14 @@ orbital ModuleCardOrbital {
   }
   type ModuleCardDataTraitDetailsValueStatesItem = {
     name : string!
-    isInitial : boolean!
-    isTerminal : boolean!
+    isInitial : boolean
+    isTerminal : boolean
   }
   type ModuleCardDataTraitDetailsValueTransitionsItem = {
     from : string!
     to : string!
     event : string!
-    guard : SExpr!
+    guard : SExpr
     effects : [ModuleCardDataTraitDetailsValueTransitionsItemEffectsItem]!
     index : number!
   }
@@ -79,9 +78,9 @@ orbital ModuleCardOrbital {
     }
 
     config {
-      data : ModuleCardData = { orbitalName: "Orbital Name", entityName: "Entity Name", persistence: "Persistence", fields: [{ name: "Name", type: "Type", required: false, hasDefault: false }, { name: "Name 2", type: "Type 2", required: true, hasDefault: true }], traits: [{ name: "Name", stateCount: 1, eventCount: 1, transitionCount: 1, emits: ["Item", "Item 2"], listens: ["Item", "Item 2"] }, { name: "Name 2", stateCount: 2, eventCount: 2, transitionCount: 2, emits: ["Item", "Item 2"], listens: ["Item", "Item 2"] }], pages: [{ name: "Name", route: "Route" }, { name: "Name 2", route: "Route 2" }], traitDetails: {}, externalLinks: [{ targetOrbital: "Target Orbital", eventName: "Event Name", direction: "Direction", traitName: "Trait Name" }, { targetOrbital: "Target Orbital 2", eventName: "Event Name 2", direction: "Direction 2", traitName: "Trait Name 2" }] }
+      data : ModuleCardData = { orbitalName: "OrderOrbital", entityName: "Order", persistence: "persistent", fields: [{ name: "customer", type: "string", required: true, hasDefault: false }, { name: "qty", type: "number", required: true, hasDefault: true }, { name: "status", type: "string", required: false, hasDefault: true }], traits: [{ name: "OrderFlow", stateCount: 5, eventCount: 7, transitionCount: 7, emits: ["ORDER_SAVED"], listens: ["PAYMENT_OK"] }], pages: [{ name: "Orders", route: "/orders" }], traitDetails: { OrderFlow: { name: "OrderFlow", linkedEntity: "Order", states: [{ name: "browsing", isInitial: true, isTerminal: false }, { name: "editing", isInitial: false, isTerminal: false }, { name: "saving", isInitial: false, isTerminal: false }, { name: "confirmed", isInitial: false, isTerminal: true }, { name: "failed", isInitial: false, isTerminal: false }], transitions: [{ from: "browsing", to: "editing", event: "EDIT", effects: [{ type: "render-ui", args: [] }], index: 0 }, { from: "editing", to: "saving", event: "SAVE", effects: [{ type: "persist", args: [] }, { type: "notify", args: [] }], index: 1 }, { from: "saving", to: "confirmed", event: "SAVED", effects: [{ type: "emit", args: [] }, { type: "render-ui", args: [] }], index: 2 }, { from: "saving", to: "failed", event: "SAVE_FAILED", effects: [{ type: "notify", args: [] }], index: 3 }, { from: "failed", to: "editing", event: "RETRY", effects: [], index: 4 }, { from: "editing", to: "browsing", event: "CANCEL", effects: [{ type: "render-ui", args: [] }], index: 5 }, { from: "confirmed", to: "browsing", event: "DONE", effects: [{ type: "navigate", args: [] }], index: 6 }], emittedEvents: ["ORDER_SAVED"], listenedEvents: ["PAYMENT_OK"] } }, externalLinks: [{ targetOrbital: "PaymentOrbital", eventName: "PAYMENT_OK", direction: "in", traitName: "OrderFlow" }] }
         @label "Data"
-        @description "data prop"
+        @description "The orbital to summarize."
         @tier "presentation"
     }
   }

package/behaviors/lolo/ui/core/molecules/ui-code-block.lolo

@@ -25,6 +25,15 @@ orbital CodeBlockOrbital {
     code : string
     stack : string
   }
+  type CodeBlockDiagnosticsItem = {
+    line : number!
+    column : number
+    endLine : number
+    endColumn : number
+    severity : "error" | "warning"!
+    message : string!
+    approximate : boolean
+  }
 
   entity CodeBlockItem [runtime] {
     id : string!
@@ -70,6 +79,11 @@ orbital CodeBlockOrbital {
           onSetMode: @config.onSetMode
           motions: @config.motions
           operators: @config.operators
+          problems: @config.problems
+          diagnostics: @config.diagnostics
+          onGoToDefinition: @config.onGoToDefinition
+          diagnosticsCode: @config.diagnosticsCode
+          lineNumbers: @config.lineNumbers
           type: code-block
         })
       CHANGE -> idle
@@ -105,6 +119,11 @@ orbital CodeBlockOrbital {
           onSetMode: @config.onSetMode
           motions: @config.motions
           operators: @config.operators
+          problems: @config.problems
+          diagnostics: @config.diagnostics
+          onGoToDefinition: @config.onGoToDefinition
+          diagnosticsCode: @config.diagnosticsCode
+          lineNumbers: @config.lineNumbers
           type: code-block
         })
       EDITOR_FOCUS -> idle
@@ -140,6 +159,11 @@ orbital CodeBlockOrbital {
           onSetMode: @config.onSetMode
           motions: @config.motions
           operators: @config.operators
+          problems: @config.problems
+          diagnostics: @config.diagnostics
+          onGoToDefinition: @config.onGoToDefinition
+          diagnosticsCode: @config.diagnosticsCode
+          lineNumbers: @config.lineNumbers
           type: code-block
         })
       EDITOR_BLUR -> idle
@@ -175,6 +199,11 @@ orbital CodeBlockOrbital {
           onSetMode: @config.onSetMode
           motions: @config.motions
           operators: @config.operators
+          problems: @config.problems
+          diagnostics: @config.diagnostics
+          onGoToDefinition: @config.onGoToDefinition
+          diagnosticsCode: @config.diagnosticsCode
+          lineNumbers: @config.lineNumbers
           type: code-block
         })
       MOTION -> idle
@@ -210,6 +239,11 @@ orbital CodeBlockOrbital {
           onSetMode: @config.onSetMode
           motions: @config.motions
           operators: @config.operators
+          problems: @config.problems
+          diagnostics: @config.diagnostics
+          onGoToDefinition: @config.onGoToDefinition
+          diagnosticsCode: @config.diagnosticsCode
+          lineNumbers: @config.lineNumbers
           type: code-block
         })
       OPERATE -> idle
@@ -245,6 +279,11 @@ orbital CodeBlockOrbital {
           onSetMode: @config.onSetMode
           motions: @config.motions
           operators: @config.operators
+          problems: @config.problems
+          diagnostics: @config.diagnostics
+          onGoToDefinition: @config.onGoToDefinition
+          diagnosticsCode: @config.diagnosticsCode
+          lineNumbers: @config.lineNumbers
           type: code-block
         })
       INSERT_TEXT -> idle
@@ -280,6 +319,11 @@ orbital CodeBlockOrbital {
           onSetMode: @config.onSetMode
           motions: @config.motions
           operators: @config.operators
+          problems: @config.problems
+          diagnostics: @config.diagnostics
+          onGoToDefinition: @config.onGoToDefinition
+          diagnosticsCode: @config.diagnosticsCode
+          lineNumbers: @config.lineNumbers
           type: code-block
         })
       SET_MODE -> idle
@@ -315,6 +359,11 @@ orbital CodeBlockOrbital {
           onSetMode: @config.onSetMode
           motions: @config.motions
           operators: @config.operators
+          problems: @config.problems
+          diagnostics: @config.diagnostics
+          onGoToDefinition: @config.onGoToDefinition
+          diagnosticsCode: @config.diagnosticsCode
+          lineNumbers: @config.lineNumbers
           type: code-block
         })
     }
@@ -335,6 +384,11 @@ orbital CodeBlockOrbital {
       }
         @description "Declarative bus emit fired when this editor loses focus."
         @tier "essential"
+      @config.onGoToDefinition -> external {
+        identifier : string
+      }
+        @description "Editable only: Cmd/Ctrl+click, or Cmd/Ctrl+Enter at the caret, on an identifier `definitionAt` accepts."
+        @tier "essential"
     }
 
     listens {
@@ -490,6 +544,26 @@ orbital CodeBlockOrbital {
         @label "Operators"
         @description "Operator vocabulary this editor accepts. Default: the full `EditorOperator` set."
         @tier "presentation"
+      problems : number
+        @label "Problems"
+        @description "Editable only: how many problems the host knows the code has (some, like a parse error, have no line to mark). With `assist`, the editor offers to fix them."
+        @tier "presentation"
+      diagnostics : [CodeBlockDiagnosticsItem] = []
+        @label "Diagnostics"
+        @description "Editable only: problems located in the code (1-based line/column in characters, `endColumn` just past the last one), each underlined exactly — red wavy for an error, amber for a warning, dotted where the position is approximate. The message of the one under the caret shows below the editor."
+        @tier "presentation"
+      onGoToDefinition : event = "GO_TO_DEFINITION"
+        @label "On Go To Definition"
+        @description "Editable only: Cmd/Ctrl+click, or Cmd/Ctrl+Enter at the caret, on an identifier `definitionAt` accepts."
+        @tier "presentation"
+      diagnosticsCode : string
+        @label "Diagnostics Code"
+        @description "The code `diagnostics` were computed on. When the editor's text has moved on, each range is carried over the edit; a range the edit touches is dropped until the code is checked again. Absent: they describe the current text."
+        @tier "presentation"
+      lineNumbers : boolean
+        @label "Line Numbers"
+        @description "Editable only: number the lines in a gutter (lines with errors in red). Default on."
+        @tier "presentation"
     }
   }
 

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

@@ -8,6 +8,7 @@ orbital FileTreeOrbital {
     type : "file" | "dir"!
     children : [FileTreeTreeItem]
     note : string
+    expandable : boolean
     size : number
     language : string
   }
@@ -34,6 +35,8 @@ orbital FileTreeOrbital {
           selectedId: @config.selectedId
           look: @config.look
           onFileSelect: @config.onFileSelect
+          onNodeExpand: @config.onNodeExpand
+          expandedPaths: @config.expandedPaths
           onNodeSelect: @config.onNodeSelect
           onNodeAction: @config.onNodeAction
           nodeActionIcon: @config.nodeActionIcon
@@ -51,6 +54,11 @@ orbital FileTreeOrbital {
       }
         @description "Called when a file is clicked"
         @tier "essential"
+      @config.onNodeExpand -> external {
+        path : string
+      }
+        @description "Called the first time a node marked `expandable` is expanded, with its path, so its children can be loaded."
+        @tier "essential"
     }
 
     config {
@@ -78,6 +86,14 @@ orbital FileTreeOrbital {
         @label "On File Select"
         @description "Called when a file is clicked"
         @tier "presentation"
+      onNodeExpand : event = "NODE_EXPAND"
+        @label "On Node Expand"
+        @description "Called the first time a node marked `expandable` is expanded, with its path, so its children can be loaded."
+        @tier "presentation"
+      expandedPaths : [string] = []
+        @label "Expanded Paths"
+        @description "Paths to show expanded (e.g. to reveal a node): each is expanded when it appears here, loading its children if needed."
+        @tier "presentation"
       onNodeSelect : event = ""
         @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`."

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

@@ -2,6 +2,31 @@ 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 StateMachineViewTrait = {
+    name : string!
+    linkedEntity : string!
+    states : [StateMachineViewTraitStatesItem]!
+    transitions : [StateMachineViewTraitTransitionsItem]!
+    emittedEvents : [string]!
+    listenedEvents : [string]!
+  }
+  type StateMachineViewTraitStatesItem = {
+    name : string!
+    isInitial : boolean
+    isTerminal : boolean
+  }
+  type StateMachineViewTraitTransitionsItem = {
+    from : string!
+    to : string!
+    event : string!
+    guard : SExpr
+    effects : [StateMachineViewTraitTransitionsItemEffectsItem]!
+    index : number!
+  }
+  type StateMachineViewTraitTransitionsItemEffectsItem = {
+    type : string!
+    args : [SExpr]!
+  }
   type StateMachineViewError = {
     message : string!
     name : string
@@ -19,19 +44,96 @@ orbital StateMachineViewOrbital {
     state idle {
       INIT -> idle
         (render-ui main {
+          activeState: @config.activeState
+          activeTransition: @config.activeTransition
+          visitedStates: @config.visitedStates
+          stateClickEvent: @config.stateClickEvent
+          transitionClickEvent: @config.transitionClickEvent
+          selectedState: @config.selectedState
+          pendingSourceState: @config.pendingSourceState
+          nodeShape: @config.nodeShape
+          entityFields: @config.entityFields
+          direction: @config.direction
+          showHeader: @config.showHeader
           className: @config.className
+          trait: @config.traitProp
           isLoading: @config.isLoading
           error: @config.error
           type: state-machine-view
         })
     }
 
+    emits {
+      @config.stateClickEvent -> external {
+        stateId : string!
+      }
+        @description "Emits UI:{stateClickEvent} with { stateId } when a state is clicked."
+        @tier "essential"
+      @config.transitionClickEvent -> external {
+        index : number!
+        event : string!
+        from : string!
+        to : string!
+      }
+        @description "Emits UI:{transitionClickEvent} with { index, event, from, to } when a transition label is clicked."
+        @tier "essential"
+    }
+
     config {
+      activeState : string
+        @label "Active State"
+        @description "State execution is currently in."
+        @tier "presentation"
+      activeTransition : number
+        @label "Active Transition"
+        @description "`index` of the transition that just fired."
+        @tier "presentation"
+      visitedStates : [string] = []
+        @label "Visited States"
+        @description "States already passed through, in order."
+        @tier "presentation"
+      stateClickEvent : event = "STATE_CLICK"
+        @label "State Click Event"
+        @description "Emits UI:{stateClickEvent} with { stateId } when a state is clicked."
+        @tier "presentation"
+      transitionClickEvent : event = "TRANSITION_CLICK"
+        @label "Transition Click Event"
+        @description "Emits UI:{transitionClickEvent} with { index, event, from, to } when a transition label is clicked."
+        @tier "presentation"
+      selectedState : string
+        @label "Selected State"
+        @description "State picked in an editor (first click)."
+        @tier "presentation"
+      pendingSourceState : string
+        @label "Pending Source State"
+        @description "Source of a transition being drawn — the next state click picks its target."
+        @tier "presentation"
+      nodeShape : "pill" | "gear" = pill
+        @label "Node Shape"
+        @description "Node silhouette. @default 'pill'"
+        @tier "presentation"
+      entityFields : [string] = []
+        @label "Entity Fields"
+        @description "Entity field names listed in the header."
+        @tier "presentation"
+      direction : "ltr" | "rtl" = ltr
+        @label "Direction"
+        @description "Flow direction. @default 'ltr'"
+        @tier "presentation"
+      showHeader : boolean
+        @label "Show Header"
+        @description "Show the trait header (name, entity, listens/emits). @default true"
+        @tier "presentation"
       className : string
         @label "Class Name"
-        @description "Additional CSS classes"
+        @description "className prop"
+        @tier "presentation"
+      traitProp : StateMachineViewTrait
+        @label "Trait"
+        @description "The trait to draw (see `parseTraitLevel` / `traitLevelFromTrait`)."
+        @synonyms "trait"
         @tier "presentation"
-      isLoading : boolean
+      isLoading : boolean = false
         @label "Is Loading"
         @description "Loading state indicator"
         @tier "presentation"

package/behaviors/lolo/ui/game/atoms/ui-draw-skinned-mesh.lolo

@@ -38,7 +38,7 @@ orbital DrawSkinnedMeshOrbital {
   }
   type DrawSkinnedMeshBonesItem = {
     name : string!
-    parent : string!
+    parent : string
     pivot : [number]!
     tip : [number]!
   }