@almadar/std 16.183.0 → 16.185.0

package/behaviors/lolo/ui/core/atoms/std-tag-taxonomy.lolo

@@ -1,5 +1,5 @@
 app std-tag-taxonomy "1.1.0"
-"std-tag-taxonomy — hierarchical category tag tree (parent/child). TagBrowse fetches Tag rows on INIT, renders the active level via data-grid, and on SELECT_TAG drills into a tag's children by binding @entity.id to the chosen parent."
+"std-tag-taxonomy — hierarchical category tag tree (parent/child). TagBrowse fetches root-level Tag rows (parentId = \"\") on INIT and renders the active level via data-grid; SELECT_TAG drills into the chosen tag's children by fetching rows whose parentId matches it, binding @entity.id to that parent so the level is remembered; SHOW_ROOT resets back to the root level, surfaced as a back affordance while drilled in. Flat taxonomies (all parentId \"\") render exactly one level, unchanged. TagSelected is emitted on selection for consumers to filter content by tag."
 orbital TagTaxonomyOrbital {
     type TagLoaded = Event { data : [Tag] } "Fired when the tag collection finishes loading"
 
@@ -10,7 +10,7 @@ orbital TagTaxonomyOrbital {
   entity Tag [persistent: tags] {
     id : string!
     name : string! @description "The descriptive label for this item." @synonyms "label, title, description"
-    parentId : string @description "Reference to the parent tag in the hierarchy." @synonyms "parent, superior, ancestor"
+    parentId : Tag @description "Reference to the parent tag in the hierarchy; empty marks a root." @synonyms "parent, superior, ancestor"
     slug : string @description "A unique, URL-friendly identifier." @synonyms "identifier, key, code"
     color : string @description "A visual identifier, often used for categorization." @synonyms "hue, shade, tint, category color"
     count : number @description "The number of items associated with this entry." @synonyms "quantity, total, size, amount" = 0
@@ -22,7 +22,10 @@ orbital TagTaxonomyOrbital {
 
     state loading {
       INIT -> loading
+        (set @entity.id "")
+        (set @entity.parentId "")
         (fetch Tag {
+          filter: ["=", (object/get @entity parentId), ""]
           emit: { failure: TagLoadFailed, success: TagLoaded }
         })
         (render-ui main {
@@ -41,6 +44,14 @@ orbital TagTaxonomyOrbital {
       TagLoaded -> browsing
         (render-ui main {
           children: [{
+            action: SHOW_ROOT
+            disabled: (if (!= @entity.id "") false true)
+            icon: arrow-left
+            label: "All categories"
+            size: sm
+            type: button
+            variant: ghost
+          }, {
             content: @config.title
             type: typography
             variant: h3
@@ -115,7 +126,10 @@ orbital TagTaxonomyOrbital {
 
     state browsing {
       INIT -> loading
+        (set @entity.id "")
+        (set @entity.parentId "")
         (fetch Tag {
+          filter: ["=", (object/get @entity parentId), ""]
           emit: { failure: TagLoadFailed, success: TagLoaded }
         })
         (render-ui main {
@@ -133,8 +147,10 @@ orbital TagTaxonomyOrbital {
         })
       SELECT_TAG -> editing
         (set @entity.id ?tagId)
+        (set @entity.parentId ?tagId)
         (emit TagSelected { tagId: ?tagId })
         (fetch Tag {
+          filter: ["=", (object/get @entity parentId), ?tagId]
           emit: { failure: TagLoadFailed, success: TagLoaded }
         })
         (render-ui main {
@@ -150,9 +166,37 @@ orbital TagTaxonomyOrbital {
           gap: md
           type: stack
         })
+      SHOW_ROOT -> loading
+        (set @entity.id "")
+        (set @entity.parentId "")
+        (fetch Tag {
+          filter: ["=", (object/get @entity parentId), ""]
+          emit: { failure: TagLoadFailed, success: TagLoaded }
+        })
+        (render-ui main {
+          align: center
+          children: [{ type: spinner }, {
+            color: muted
+            content: "Loading categories…"
+            type: typography
+            variant: caption
+          }]
+          className: py-12
+          direction: vertical
+          gap: md
+          type: stack
+        })
       TagLoaded -> browsing
         (render-ui main {
           children: [{
+            action: SHOW_ROOT
+            disabled: (if (!= @entity.id "") false true)
+            icon: arrow-left
+            label: "All categories"
+            size: sm
+            type: button
+            variant: ghost
+          }, {
             content: @config.title
             type: typography
             variant: h3
@@ -227,7 +271,10 @@ orbital TagTaxonomyOrbital {
 
     state editing {
       INIT -> loading
+        (set @entity.id "")
+        (set @entity.parentId "")
         (fetch Tag {
+          filter: ["=", (object/get @entity parentId), ""]
           emit: { failure: TagLoadFailed, success: TagLoaded }
         })
         (render-ui main {
@@ -245,12 +292,22 @@ orbital TagTaxonomyOrbital {
         })
       SELECT_TAG -> editing
         (set @entity.id ?tagId)
+        (set @entity.parentId ?tagId)
         (emit TagSelected { tagId: ?tagId })
       TagSelected -> editing
         (set @entity.id ?tagId)
+        (set @entity.parentId ?tagId)
       TagLoaded -> browsing
         (render-ui main {
           children: [{
+            action: SHOW_ROOT
+            disabled: (if (!= @entity.id "") false true)
+            icon: arrow-left
+            label: "All categories"
+            size: sm
+            type: button
+            variant: ghost
+          }, {
             content: @config.title
             type: typography
             variant: h3
@@ -325,7 +382,10 @@ orbital TagTaxonomyOrbital {
 
     state error {
       INIT -> loading
+        (set @entity.id "")
+        (set @entity.parentId "")
         (fetch Tag {
+          filter: ["=", (object/get @entity parentId), ""]
           emit: { failure: TagLoadFailed, success: TagLoaded }
         })
         (render-ui main {

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

@@ -1,5 +1,5 @@
 app std-thread "1.3.0"
-"std-thread — forum-style nested replies with collapse + flat-mode toggle. Owns ThreadPost (persistent). flat:true covers 1:1 linear inquiry threads; flat:false renders forum-style nested. INIT fetches, scoped by @config.threadRootId when set (blank = every root, the default). REPLY persists a child post under @payload.parentId, stamped with the real @user identity. Layer 3 variants override `bodyContent` to deliver chat-bubble, email-threaded, or linear-comments UX while inheriting the same trait, state machine, emits, and listens."
+"std-thread — forum-style nested replies with collapse + flat-mode toggle. Owns ThreadPost (persistent). flat:true covers 1:1 linear inquiry threads; flat:false renders forum-style nested. INIT fetches, scoped by @config.threadRootId when set (blank = every root, the default). REPLY persists a child post under @payload.parentId, stamped with the real @user identity. A consumer that mounts this as page comments forwards its own document-opened signal to SET_THREAD_ROOT { rootId }, which stamps the frame and refetches filtered by the payload; the after-create and after-select refetch arms keep filtering by @config.threadRootId, so a mutation re-widens the panel until the consumer re-fires SET_THREAD_ROOT. Layer 3 variants override `bodyContent` to deliver chat-bubble, email-threaded, or linear-comments UX while inheriting the same trait, state machine, emits, and listens."
 orbital ThreadPostOrbital {
   ;; Forward relation: array of child ThreadPost IDs whose parentId === this.id.
   ;; Lowers to `type: "relation", cardinality: "many"` (orbital-lolo lower.rs).
@@ -19,6 +19,8 @@ orbital ThreadPostOrbital {
 
     type ThreadPostCreateFailed = Event { error : string, code : string } "Fired when a new thread-post fails to persist"
 
+    type SetThreadRoot = Event { rootId : string! } "Fired to scope every ThreadPost fetch, and new-reply threadRootId stamping, to the descendants of one document root"
+
   entity ThreadPost [persistent: threadposts] {
     id : string!
     parentId : string @description "Identifier of the parent ThreadPost in a nested thread." @synonyms "parent, ancestor, source"
@@ -52,6 +54,14 @@ orbital ThreadPostOrbital {
           type: alert
           variant: error
         })
+      SET_THREAD_ROOT -> loading
+        (set @entity.threadRootId ?rootId)
+        (fetch ThreadPost {
+          emit: { failure: ThreadPostLoadFailed, success: ThreadPostLoaded }
+          filter: (or ["=", ?rootId, ""] ["=", (object/get @entity threadRootId), ?rootId])
+          include: (replies)
+        })
+        (render-ui main { size: sm, type: spinner })
     }
 
     state browsing {
@@ -73,13 +83,14 @@ orbital ThreadPostOrbital {
           authorName: @user.name
           content: ?content
           parentId: (str/default ?parentNodeId ?parentId)
-          threadRootId: (str/default ?parentNodeId (str/default @config.threadRootId root))
+          threadRootId: (str/default ?parentNodeId (str/default @entity.threadRootId (str/default @config.threadRootId root)))
         } {
           emit: { failure: ThreadPostCreateFailed, success: ThreadPostCreated }
         })
       ;; Reply with no text yet (e.g. an email "Reply" button) opens the composer.
       REPLY -> replying when ["=", (str/default ?content ""), ""]
         (set @entity.parentId (str/default ?parentNodeId ?parentId))
+        (set @entity.threadRootId (str/default ?parentNodeId (str/default @entity.threadRootId (str/default @config.threadRootId root))))
         (render-ui main {
           children: [{
             content: "Write a reply"
@@ -139,6 +150,14 @@ orbital ThreadPostOrbital {
           type: alert
           variant: error
         })
+      SET_THREAD_ROOT -> loading
+        (set @entity.threadRootId ?rootId)
+        (fetch ThreadPost {
+          emit: { failure: ThreadPostLoadFailed, success: ThreadPostLoaded }
+          filter: (or ["=", ?rootId, ""] ["=", (object/get @entity threadRootId), ?rootId])
+          include: (replies)
+        })
+        (render-ui main { size: sm, type: spinner })
     }
 
     state replying {
@@ -165,6 +184,14 @@ orbital ThreadPostOrbital {
           type: alert
           variant: error
         })
+      SET_THREAD_ROOT -> loading
+        (set @entity.threadRootId ?rootId)
+        (fetch ThreadPost {
+          emit: { failure: ThreadPostLoadFailed, success: ThreadPostLoaded }
+          filter: (or ["=", ?rootId, ""] ["=", (object/get @entity threadRootId), ?rootId])
+          include: (replies)
+        })
+        (render-ui main { size: sm, type: spinner })
     }
 
     state error {
@@ -175,6 +202,14 @@ orbital ThreadPostOrbital {
           include: (replies)
         })
         (render-ui main { size: sm, type: spinner })
+      SET_THREAD_ROOT -> loading
+        (set @entity.threadRootId ?rootId)
+        (fetch ThreadPost {
+          emit: { failure: ThreadPostLoadFailed, success: ThreadPostLoaded }
+          filter: (or ["=", ?rootId, ""] ["=", (object/get @entity threadRootId), ?rootId])
+          include: (replies)
+        })
+        (render-ui main { size: sm, type: spinner })
     }
 
     emits {
@@ -295,6 +330,12 @@ orbital ThreadPostOrbital {
         @description "Indicates a failure to create a new thread post."
         @synonyms "error, failure, rejected, invalid"
         @tier "internal"
+      SET_THREAD_ROOT {
+        rootId : string!
+      }
+        @description "Scopes every fetch, and new-reply threadRootId stamping, to the descendants of one document root."
+        @synonyms "scope, focus, set root, document scope, thread scope"
+        @tier "domain"
     }
 
     config {

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

@@ -0,0 +1,247 @@
+app std-tree "1.0.0"
+"std-tree — generic hierarchical node browser. Fetches a flat TreeNode collection and renders it through file-tree's flat `items` mode (parentId-nested at render time by the component, not the .lolo); OPEN_NODE is the external handoff for a selected node's id. Rebindable: pass `fields` at the call site to retarget it at any parent-pointer entity (categories, org units, comment threads)."
+orbital TreeNodeOrbital {
+    type TreeNodeLoaded = Event { data : [TreeNode] } "Fired when the tree node collection finishes loading"
+
+    type TreeNodeLoadFailed = Event { error : string, code : string } "Fired when the tree node collection fails to load"
+
+  entity TreeNode [persistent: treenodes] {
+    id : string!
+    name : string! @description "The descriptive label for this node." @synonyms "label, title, text"
+    parentId : string @description "Reference to the parent node in the hierarchy; empty marks a root." @synonyms "parent, superior, ancestor" = ""
+    icon : string @description "Icon name shown beside the node." @synonyms "glyph, symbol, pictogram" = ""
+    createdAt : string
+  }
+
+  trait TreeBrowse -> @rebindable TreeNode [interaction, collection] {
+    initial: loading
+
+    state loading {
+      INIT -> loading
+        (fetch TreeNode {
+          emit: { failure: TreeNodeLoadFailed, success: TreeNodeLoaded }
+        })
+        (render-ui main {
+          align: center
+          children: [{ type: spinner }, {
+            color: muted
+            content: "Loading tree…"
+            type: typography
+            variant: caption
+          }]
+          className: py-12
+          direction: vertical
+          gap: md
+          type: stack
+        })
+      TreeNodeLoaded -> browsing
+        (render-ui main {
+          children: [{
+            align: center
+            children: [{ name: list-tree, type: icon }, {
+              content: @config.title
+              type: typography
+              variant: h3
+            }, {
+              label: (array/len ?data)
+              size: sm
+              type: badge
+              variant: neutral
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          }, { type: divider }, {
+            items: (array/map ?data (fn row {
+              icon: @row.icon
+              id: @row.id
+              label: @row.name
+              parentId: @row.parentId
+            }))
+            onNodeSelect: OPEN_NODE
+            type: file-tree
+          }]
+          direction: vertical
+          gap: md
+          type: stack
+        })
+      TreeNodeLoadFailed -> error
+        (render-ui main {
+          align: center
+          children: [{
+            color: error
+            name: alert-triangle
+            type: icon
+          }, {
+            content: "Failed to load tree"
+            type: typography
+            variant: body
+          }, {
+            color: muted
+            content: ?error
+            type: typography
+            variant: caption
+          }, {
+            action: RETRY
+            icon: rotate-ccw
+            label: Retry
+            type: button
+            variant: ghost
+          }]
+          className: py-8
+          direction: vertical
+          gap: sm
+          type: stack
+        })
+    }
+
+    state browsing {
+      INIT -> loading
+        (fetch TreeNode {
+          emit: { failure: TreeNodeLoadFailed, success: TreeNodeLoaded }
+        })
+        (render-ui main {
+          align: center
+          children: [{ type: spinner }, {
+            color: muted
+            content: "Loading tree…"
+            type: typography
+            variant: caption
+          }]
+          className: py-12
+          direction: vertical
+          gap: md
+          type: stack
+        })
+      OPEN_NODE -> browsing
+        (set @entity.id ?id)
+      TreeNodeLoaded -> browsing
+        (render-ui main {
+          children: [{
+            align: center
+            children: [{ name: list-tree, type: icon }, {
+              content: @config.title
+              type: typography
+              variant: h3
+            }, {
+              label: (array/len ?data)
+              size: sm
+              type: badge
+              variant: neutral
+            }]
+            direction: horizontal
+            gap: sm
+            type: stack
+          }, { type: divider }, {
+            items: (array/map ?data (fn row {
+              icon: @row.icon
+              id: @row.id
+              label: @row.name
+              parentId: @row.parentId
+            }))
+            onNodeSelect: OPEN_NODE
+            type: file-tree
+          }]
+          direction: vertical
+          gap: md
+          type: stack
+        })
+      TreeNodeLoadFailed -> error
+        (render-ui main {
+          align: center
+          children: [{
+            color: error
+            name: alert-triangle
+            type: icon
+          }, {
+            content: "Failed to load tree"
+            type: typography
+            variant: body
+          }, {
+            color: muted
+            content: ?error
+            type: typography
+            variant: caption
+          }, {
+            action: RETRY
+            icon: rotate-ccw
+            label: Retry
+            type: button
+            variant: ghost
+          }]
+          className: py-8
+          direction: vertical
+          gap: sm
+          type: stack
+        })
+    }
+
+    state error {
+      INIT -> loading
+        (fetch TreeNode {
+          emit: { failure: TreeNodeLoadFailed, success: TreeNodeLoaded }
+        })
+        (render-ui main { type: spinner })
+      ;; the error screen's Retry button: INIT is lifecycle-only and the bus never
+      ;; delivers it, so the affordance must target a first-class user event
+      RETRY -> loading
+        (fetch TreeNode {
+          emit: { failure: TreeNodeLoadFailed, success: TreeNodeLoaded }
+        })
+        (render-ui main { type: spinner })
+    }
+
+    emits {
+      OPEN_NODE {
+        id : string!
+      }
+        @description "Signals a tree node has been selected for external handoff."
+        @synonyms "select, choose, open, activate"
+        @tier "domain"
+      TreeNodeLoaded {
+        data : [TreeNode]
+      }
+        @description "Indicates the tree node collection has been successfully retrieved."
+        @synonyms "loaded, fetched, retrieved, ready"
+        @tier "domain"
+      TreeNodeLoadFailed {
+        error : string
+        code : string
+      }
+        @description "Indicates a failure to load the tree node collection."
+        @synonyms "error, failed, problem, unsuccessful"
+        @tier "internal"
+    }
+
+    listens {
+      OPEN_NODE {
+        id : string!
+      }
+        @description "A tree node was selected for external handoff."
+        @synonyms "select, choose, open, activate"
+        @tier "domain"
+      TreeNodeLoaded {
+        data : [TreeNode]
+      }
+        @description "Indicates the tree node collection has been successfully retrieved."
+        @synonyms "loaded, fetched, retrieved, ready"
+        @tier "domain"
+      TreeNodeLoadFailed {
+        error : string
+        code : string
+      }
+        @description "Indicates a failure to load the tree node collection."
+        @synonyms "error, failed, problem, unsuccessful"
+        @tier "internal"
+    }
+
+    config {
+      title : string = Tree
+        @label "Section title"
+        @description "Heading shown above the tree"
+        @tier "presentation"
+    }
+  }
+
+  page "/tree" as TreePage -> TreeBrowse
+}

package/behaviors/lolo/ui/core/atoms/std-version-history.lolo

@@ -1,5 +1,5 @@
 app std-version-history "1.0.0"
-"std-version-history — wiki/CMS revision history with diff + rollback. Browses revisions; opens detail in `viewing_single`; compares two revisions in `comparing` with intrinsic version-diff; persists rollback."
+"std-version-history — wiki/CMS revision history with diff + rollback. Browses revisions; opens detail in `viewing_single`; compares two revisions in `comparing` with intrinsic version-diff; persists rollback. `RevisionManage` is a rebindable single-entity trait: a consumer rebinds it to its own entity via `linkedEntity`. `config.scopeField` names the Revision field holding the parent document id; a page-mounted `{id}` route param scopes INIT's own fetch, and a consumer forwards SHOW_HISTORY { key } (via a `listens` override) to rescope the feed to one document — empty scopeField (default) or no id keeps today's unfiltered global feed. Rollback and retry refetches stay scoped."
 orbital RevisionOrbital {
     type RevisionLoaded = Event { data : [Revision] } "Fired when the revision collection finishes loading"
 
@@ -20,14 +20,17 @@ orbital RevisionOrbital {
     summary : string @description "A brief explanation of the revision's changes." @synonyms "description, note, comment, explanation"
     searchTerm : string @description "The current search query the user submitted." @synonyms "query, term, q" = ""
     createdAt : string
+    scopeKey : string @intrinsic @description "The parent document id the feed is currently scoped to, set by SHOW_HISTORY. Empty when browsing the unfiltered global feed." @synonyms "scope, filter key, document scope" = ""
   }
 
-  trait RevisionManage -> Revision [interaction, collection] {
+  trait RevisionManage -> @rebindable Revision [interaction, collection] {
     initial: loading
 
     state loading {
       INIT -> loading
+        (set @entity.scopeKey (str/default ?id ""))
         (fetch Revision {
+          filter: (or ["=", @config.scopeField, ""] ["=", (str/default ?id ""), ""] ["=", (object/get @entity @config.scopeField), ?id])
           emit: { failure: RevisionLoadFailed, success: RevisionLoaded }
         })
         (render-ui main {
@@ -95,7 +98,9 @@ orbital RevisionOrbital {
           type: stack
         })
       RevisionRolledBack -> loading
+        (set @entity.scopeKey (object/get ?row @config.scopeField ""))
         (fetch Revision {
+          filter: (or ["=", @config.scopeField, ""] ["=", (object/get ?row @config.scopeField ""), ""] ["=", (object/get @entity @config.scopeField), (object/get ?row @config.scopeField "")])
           emit: { failure: RevisionLoadFailed, success: RevisionLoaded }
         })
       RevisionRollbackFailed -> error
@@ -110,11 +115,32 @@ orbital RevisionOrbital {
           type: alert
           variant: error
         })
+      SHOW_HISTORY -> loading
+        (set @entity.scopeKey ?key)
+        (fetch Revision {
+          filter: ["=", (object/get @entity @config.scopeField), ?key]
+          emit: { failure: RevisionLoadFailed, success: RevisionLoaded }
+        })
+        (render-ui main {
+          align: center
+          children: [{ type: spinner }, {
+            color: muted
+            content: "Loading version history…"
+            type: typography
+            variant: caption
+          }]
+          className: py-12
+          direction: vertical
+          gap: md
+          type: stack
+        })
     }
 
     state browsing {
       INIT -> loading
+        (set @entity.scopeKey (str/default ?id ""))
         (fetch Revision {
+          filter: (or ["=", @config.scopeField, ""] ["=", (str/default ?id ""), ""] ["=", (object/get @entity @config.scopeField), ?id])
           emit: { failure: RevisionLoadFailed, success: RevisionLoaded }
         })
         (render-ui main {
@@ -270,6 +296,25 @@ orbital RevisionOrbital {
           gap: md
           type: stack
         })
+      SHOW_HISTORY -> loading
+        (set @entity.scopeKey ?key)
+        (fetch Revision {
+          filter: ["=", (object/get @entity @config.scopeField), ?key]
+          emit: { failure: RevisionLoadFailed, success: RevisionLoaded }
+        })
+        (render-ui main {
+          align: center
+          children: [{ type: spinner }, {
+            color: muted
+            content: "Loading version history…"
+            type: typography
+            variant: caption
+          }]
+          className: py-12
+          direction: vertical
+          gap: md
+          type: stack
+        })
     }
 
     state viewing_single {
@@ -350,6 +395,25 @@ orbital RevisionOrbital {
           gap: md
           type: stack
         })
+      SHOW_HISTORY -> loading
+        (set @entity.scopeKey ?key)
+        (fetch Revision {
+          filter: ["=", (object/get @entity @config.scopeField), ?key]
+          emit: { failure: RevisionLoadFailed, success: RevisionLoaded }
+        })
+        (render-ui main {
+          align: center
+          children: [{ type: spinner }, {
+            color: muted
+            content: "Loading version history…"
+            type: typography
+            variant: caption
+          }]
+          className: py-12
+          direction: vertical
+          gap: md
+          type: stack
+        })
     }
 
     state comparing {
@@ -388,11 +452,39 @@ orbital RevisionOrbital {
           gap: md
           type: stack
         })
+      SHOW_HISTORY -> loading
+        (set @entity.scopeKey ?key)
+        (fetch Revision {
+          filter: ["=", (object/get @entity @config.scopeField), ?key]
+          emit: { failure: RevisionLoadFailed, success: RevisionLoaded }
+        })
+        (render-ui main {
+          align: center
+          children: [{ type: spinner }, {
+            color: muted
+            content: "Loading version history…"
+            type: typography
+            variant: caption
+          }]
+          className: py-12
+          direction: vertical
+          gap: md
+          type: stack
+        })
     }
 
     state error {
       INIT -> loading
+        (set @entity.scopeKey (str/default ?id ""))
         (fetch Revision {
+          filter: (or ["=", @config.scopeField, ""] ["=", (str/default ?id ""), ""] ["=", (object/get @entity @config.scopeField), ?id])
+          emit: { failure: RevisionLoadFailed, success: RevisionLoaded }
+        })
+        (render-ui main { size: sm, type: spinner })
+      SHOW_HISTORY -> loading
+        (set @entity.scopeKey ?key)
+        (fetch Revision {
+          filter: ["=", (object/get @entity @config.scopeField), ?key]
           emit: { failure: RevisionLoadFailed, success: RevisionLoaded }
         })
         (render-ui main { size: sm, type: spinner })
@@ -454,6 +546,12 @@ orbital RevisionOrbital {
     }
 
     listens {
+      INIT {
+        id : string
+      }
+        @description "Optional route param delivered on mount (e.g. an :id page segment); scopes INIT's own fetch to rows whose scopeField equals id. Absent id or empty scopeField config keeps the unfiltered global feed."
+        @synonyms "route id, deep link, initial scope"
+        @tier "domain"
       OPEN_REVISION {
         id : string!
         row : Revision
@@ -506,6 +604,12 @@ orbital RevisionOrbital {
         @description "Indicates that a revision rollback operation has failed."
         @synonyms "rollback error, revert failure, undo failed"
         @tier "internal"
+      SHOW_HISTORY {
+        key : string!
+      }
+        @description "Requests the revision feed scoped to one parent document; stores the key and refetches filtered by config.scopeField."
+        @synonyms "view history, doc history, filter revisions"
+        @tier "domain"
     }
 
     config {
@@ -521,6 +625,10 @@ orbital RevisionOrbital {
         @label "Stat display look"
         @description "Layer 2 visual treatment for stat / KPI cards."
         @tier "presentation"
+      scopeField : string = ""
+        @label "Scope field"
+        @description "Revision entity field holding the parent document's id. When set, a page-mounted {id} route param scopes INIT's fetch, and a SHOW_HISTORY { key } event rescopes the feed, to rows whose scopeField equals the id/key; rollback and retry refetches stay scoped too. Empty (default) or no id = unfiltered global feed, unchanged from prior behavior."
+        @tier "domain"
     }
   }