@almadar/std 16.192.0 → 16.194.0

package/behaviors/lolo/infra/atoms/std-approval-gate.lolo

@@ -1,5 +1,5 @@
 app std-approval-gate "1.1.0"
-"std-approval-gate — generic approval gate / approver workflow. Use when a user voices that an action must be reviewed, approved, signed off, or authorized by a privileged role before it proceeds (admin approval, supervisor sign-off, manager approval, gatekeeper review, editor approval, senior editor approval, reviewer approval, publishing approval, draft approval, content review, submit drafts then editors review and approve or reject, needs approval before going live, requires sign-off before publish). Persists ApprovalRequest rows + surfaces the PENDING ones in a review queue showing what is being approved and who asked, with Approve / Deny actions — Deny captures a written reason. approverRoles is ENFORCED by the review transitions themselves: an APPROVE/DENY from a viewer whose role is not listed does not fire. On approval emits ApprovalGranted; on denial emits ApprovalDenied (with the reason). Hosts that replay the gated action MUST route a failed replay back via APPROVAL_REPLAY_FAILED so the request reopens instead of being silently consumed. Compose onto any orbital whose action you want to gate: the target orbital emits an external event, an ApprovalRequest row is created (stamp subjectLabel/subjectId/requestedBy so reviewers see what they are judging), and downstream effects wait on ApprovalGranted. Differs from std-mod-queue, which is content-moderation-specific."
+"std-approval-gate — generic approval gate / approver workflow. Use when a user voices that an action must be reviewed, approved, signed off, or authorized by a privileged role before it proceeds (admin approval, supervisor sign-off, manager approval, gatekeeper review, editor approval, senior editor approval, reviewer approval, publishing approval, draft approval, content review, submit drafts then editors review and approve or reject, needs approval before going live, requires sign-off before publish). Persists ApprovalRequest rows + surfaces the PENDING ones in a review queue showing what is being approved and who asked, with Approve / Deny actions — Deny captures a written reason. approverRoles is ENFORCED by the review transitions themselves: an APPROVE/DENY from a viewer whose role is not listed does not fire. blockSelfApproval additionally stops a reviewer approving their own request (four-eyes) — DENY stays allowed as self-withdrawal. On approval emits ApprovalGranted; on denial emits ApprovalDenied (with the reason). Hosts that replay the gated action MUST route a failed replay back via APPROVAL_REPLAY_FAILED so the request reopens instead of being silently consumed. Compose onto any orbital whose action you want to gate: the target orbital emits an external event, an ApprovalRequest row is created (stamp subjectLabel/subjectId/requestedBy so reviewers see what they are judging), and downstream effects wait on ApprovalGranted. Differs from std-mod-queue, which is content-moderation-specific."
 orbital ApprovalGateOrbital {
     uses Spinner from "std/behaviors/ui-spinner"
     uses Typography from "std/behaviors/ui-typography"
@@ -227,8 +227,9 @@ orbital ApprovalGateOrbital {
       ;; The role guard IS the enforcement (both execution paths honor
       ;; transition guards, for the button and for a bus-delivered event
       ;; alike): empty approverRoles = ungated, otherwise the viewer's role
-      ;; must be listed or the decision does not fire.
-      APPROVE -> reviewing when (or ["=", (array/len @config.approverRoles), 0] (array/includes @config.approverRoles @user.role))
+      ;; must be listed or the decision does not fire. blockSelfApproval
+      ;; additionally blocks APPROVE when ?row.requestedBy is the viewer.
+      APPROVE -> reviewing when (and (or ["=", (array/len @config.approverRoles), 0] (array/includes @config.approverRoles @user.role)) (or ["=", @config.blockSelfApproval, false] ["!=", (object/get ?row requestedBy), @user.id]))
         (set @entity.id ?id)
         (set @entity.status approved)
         (set @entity.reviewer @user.id)
@@ -499,6 +500,11 @@ orbital ApprovalGateOrbital {
         @description "Roles eligible to decide. ENFORCED by the APPROVE/DENY transition guards: a viewer whose @user.role is not listed cannot fire a decision, from the button or from the bus. Empty = every signed-in viewer may decide (ungated)."
         @synonyms "approver, reviewer, authorized roles, sign-off roles, who approves"
         @tier "policy"
+      blockSelfApproval : boolean = false
+        @label "Block approving your own requests?"
+        @description "When on, a reviewer cannot APPROVE a request they submitted themselves (requestedBy = the viewer's id) — enforced by the APPROVE transition guard, from the button or from the bus. Requires hosts to stamp requestedBy at request creation. DENY stays allowed on your own request (denying your own request withdraws it). Off by default."
+        @synonyms "self approval, self-approval, four eyes, four-eyes, separation of duties, cannot approve own, no self sign-off, dual control"
+        @tier "policy"
       threshold : number = 0
         @label "Auto-approve below this value"
         @description "Requests whose gated value is below this threshold are auto-approved. v1.0 declarative only."

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

@@ -41,6 +41,7 @@ orbital AppLayoutOrbital {
             notificationClickEvent: @config.notificationClickEvent
             notifications: @config.notifications
             searchEvent: @config.searchEvent
+            sidebarContent: @config.sidebarTrait
             topBarActions: @config.topBarActions
             type: @config.layoutPattern
             user: (if @config.viewerName { avatar: @config.viewerAvatar, email: @config.viewerEmail, name: @config.viewerName } null)
@@ -90,6 +91,11 @@ orbital AppLayoutOrbital {
         @label "Content trait"
         @description "Trait rendered inside the app layout content area"
         @tier "presentation"
+      sidebarTrait : trait
+        @label "Sidebar trait"
+        @description "Optional trait rendered in the sidebar between the nav links and the footer — the Notion/Confluence-style always-visible page tree; scrolls independently. Unset renders plain nav only."
+        @synonyms "sidebar tree, nav tree, page tree in sidebar, hierarchy rail"
+        @tier "presentation"
       appName : string = App
         @label "What should this app be called?"
         @description "Name shown in the top-left of the chrome header."
@@ -113,7 +119,7 @@ orbital AppLayoutOrbital {
         @description "Top-level navigation links shown on the left rail."
         @synonyms "nav links, menu items, sidebar sections, navigation entries, pages"
         @tier "presentation"
-      searchEvent : string = SEARCH
+      searchEvent : event = SEARCH
         @label "Search event"
         @description "Event emitted when the user runs a global search"
         @tier "internal"
@@ -127,7 +133,7 @@ orbital AppLayoutOrbital {
         @description "Items shown in the notifications dropdown."
         @synonyms "alerts, messages, notices, notification items, bell items"
         @tier "presentation"
-      notificationClickEvent : string = NOTIFY_CLICK
+      notificationClickEvent : event = NOTIFY_CLICK
         @label "Notification click event"
         @description "Event emitted when the user picks a notification"
         @tier "internal"

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

@@ -370,7 +370,7 @@ orbital BrowseItemOrbital {
         @description "Actions beyond this count collapse into a '⋯' overflow menu. Set 2–3 for dense tables."
         @synonyms "inline actions limit, overflow threshold, max buttons per row"
         @tier "presentation"
-      itemClickEvent : string = VIEW
+      itemClickEvent : event = VIEW
         @label "Which event does clicking a row fire?"
         @description "Row-click channel. Retarget when two browse lists coexist in one orbital and their VIEW payloads differ, so each gets its own typed channel."
         @synonyms "row click event, item click, open event, select event"

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

@@ -234,7 +234,7 @@ orbital CalendarEventOrbital {
         @description "Row column holding the timestamp the calendar grid places each chip by. Rebound hosts point this at their own column (e.g. startTime, startsAt, dueAt); the chip's LABEL comes from titleBinding, not from here."
         @synonyms "start column, date column, when field, timestamp field"
         @tier "presentation"
-      onEventClick : string = ""
+      onEventClick : event = ""
         @label "On Event Click"
         @description "Event emitted when a calendar chip is clicked: UI:{onEventClick} with { event } carrying the clicked row. Empty means chips are not clickable."
         @synonyms "open event, event click, select event, chip click"

package/behaviors/lolo/ui/core/atoms/std-date-range.lolo

@@ -78,7 +78,7 @@ orbital DateRangeOrbital {
     }
 
     config {
-      event : string = DATE_RANGE_CHANGED
+      event : event = DATE_RANGE_CHANGED
         @label "Change event"
         @description "Event name emitted when the user picks a new range"
         @tier "internal"

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

@@ -18,9 +18,9 @@ orbital DetailLayoutOrbital {
           className: "w-full"
           children: [{
             type: stack
-            direction: horizontal
-            align: center
-            gap: sm
+            direction: vertical
+            align: start
+            gap: xs
             className: "w-full border-b border-border pb-3"
             children: [{
               type: button

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

@@ -82,7 +82,7 @@ orbital FilterTargetOrbital {
         @description "Field, label, control type, and options for each filter input. numberrange renders a min/max slider pair (bounded by min/max/step) and emits one FILTER per side as `<field>_min` / `<field>_max`, mirroring daterange's `<field>_from` / `<field>_to` convention."
         @synonyms "numeric range, price range, min max, slider filter, range filter, threshold filter"
         @tier "presentation"
-      event : string = FILTER
+      event : event = FILTER
         @label "Filter event"
         @description "Event emitted when the user changes a filter selection"
         @tier "internal"

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

@@ -112,7 +112,7 @@ orbital GeoSearchResultOrbital {
         @label "Default radius (km)"
         @description "Initial search radius around the chosen center"
         @tier "presentation"
-      event : string = GEO_SEARCH
+      event : event = GEO_SEARCH
         @label "Search event"
         @description "Event emitted when the user runs a geo search"
         @tier "internal"

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

@@ -128,7 +128,7 @@ orbital GraphItemOrbital {
         @description "Keep only the first N points after sorting (0 = all)"
         @synonyms "user phrases: 'top 5' -> 5; 'top 10' -> 10; 'first 3' -> 3; 'all' / 'no limit' -> 0; 'show all' -> 0"
         @tier "presentation"
-      drillEvent : string = ""
+      drillEvent : event = ""
         @label "Drill event"
         @description "Event emitted when a user clicks a chart point"
         @synonyms "click-through navigation event. user phrases: 'on click navigate to X' / 'drill into X' / 'when clicked open X' -> X event name"

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

@@ -154,7 +154,7 @@ orbital ModalRecordOrbital {
         @description "Per-field label/placeholder/hint overrides, keyed by field name. Types, options and required-ness stay entity-schema-driven (declare once on the entity); override only display copy the entity's @description doesn't fit."
         @synonyms "field labels, custom labels, help text overrides, placeholder text"
         @tier "presentation"
-      mode : string = create
+      mode : "create" | "edit" = create
         @label "Is this for creating or editing?"
         @description "create = blank form; edit = pre-filled from the selected row."
         @synonyms "form mode, create or edit, new or update, add or modify"

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

@@ -97,7 +97,7 @@ orbital PagedItemOrbital {
         @label "Page size"
         @description "Rows per page used to derive total page count"
         @tier "presentation"
-      event : string = PAGE
+      event : event = PAGE
         @label "Page-change event"
         @description "Event emitted when the user picks a new page"
         @tier "internal"

package/behaviors/lolo/ui/core/atoms/std-record-detail.lolo

@@ -70,6 +70,12 @@ orbital RecordItemOrbital {
           include: @config.include
         })
         (render-ui main { rows: 4, type: skeleton })
+      ;; Event-opened overlay (openOn: event): stays blank until OPEN_VIEW,
+      ;; but renders the blank EXPLICITLY — an embedded @trait.X reference to
+      ;; a trait with no indexed content is flagged by the compiled client's
+      ;; render probe (trait_bindings_resolved).
+      INIT -> idle when ["=", @config.openOn, "event"]
+        (render-ui main null)
       ;; self-loops on the external emits so the validator sees in-atom
       ;; listeners — the real consumers are the composing organism's
       ;; persistor (CONTENT_SAVED, TITLE_COMMITTED) and its refetch /
@@ -535,6 +541,11 @@ orbital RecordItemOrbital {
         @label "Edit button label"
         @description "Label of the quiet button above the document body that starts an editing session (the body itself is also clickable)."
         @tier "presentation"
+      allowEdit : boolean = true
+        @label "Allow editing the document?"
+        @description "When false the document look is a pure read surface: no header Edit button, no click-to-edit body, no click-to-rename title. Hosts pass a role condition here so read-only viewers get the page without its authoring affordances; the entity's own access predicates stay the enforcement floor."
+        @synonyms "read only document, viewer mode, can edit, editing allowed"
+        @tier "policy"
       doneLabel : string = "Done"
         @label "Done button label"
         @description "Label of the button that ends the document editing session; work is already autosaved when it is pressed."
@@ -613,14 +624,14 @@ orbital RecordItemOrbital {
         actions: @config.actions
         coverImage: @entity.coverUrl
         icon: @entity.iconName
-        editEvent: EDIT_CONTENT
+        editEvent: (if @config.allowEdit EDIT_CONTENT null)
         editLabel: @config.editLabel
         id: @entity.id
         maxInlineActions: @config.maxInlineActions
         placeholder: @config.placeholder
         subtitle: @entity.description
         title: @entity.name
-        titleCommitEvent: TITLE_COMMITTED
+        titleCommitEvent: (if @config.allowEdit TITLE_COMMITTED null)
         type: document-panel
         value: @entity.content
         className: "w-full"

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

@@ -118,7 +118,7 @@ orbital ScatterItemOrbital {
         @label "Chart height"
         @description "Pixel height of the rendered scatter plot"
         @tier "presentation"
-      drillEvent : string = ""
+      drillEvent : event = ""
         @label "Drill event"
         @description "Event emitted when the user clicks a data point"
         @tier "internal"

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

@@ -48,7 +48,7 @@ orbital SearchResultOrbital {
         @label "Placeholder text"
         @description "Hint text shown inside the empty search input"
         @tier "presentation"
-      event : string = SEARCH
+      event : event = SEARCH
         @label "Search event"
         @description "Event emitted when the user submits a query"
         @tier "internal"

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

@@ -0,0 +1,319 @@
+app std-tag-strip "1.0.0"
+"std-tag-strip — inline tag editing ON the document surface: the record's tags render as removable chips with a type-to-add input (a typed name that matches an existing tag attaches it; an unknown name is created in the shared taxonomy first), plus one-click chips for every existing tag not yet attached. Emits TAGS_CHANGED { id, tagIds } — the host organism routes it into its persistor's update; the document's refetch re-scopes the strip. Binds any record carrying a tagIds relation array; the tag store is the shared `tags` collection (std-tag-taxonomy's)."
+;; @capabilities "inline tags, tag chips on a document, add tag from taxonomy, create tag by typing, remove tag chip, tag editing in place"
+orbital TagStripOrbital {
+    type TagStripOptions = Event { data : [StripTag] } "The shared tag store loaded for the strip's display pass"
+
+    type TagStripAddOptions = Event { data : [StripTag] } "The shared tag store loaded to resolve a typed tag name on add"
+
+    type TagStripRemoveOptions = Event { data : [StripTag] } "The shared tag store loaded to resolve the remaining names on remove"
+
+    type TagStripTagCreated = Event { id : string, row : StripTag } "A typed tag name had no existing row; one was created in the shared taxonomy"
+
+    type TagStripLoadFailed = Event { error : string, code : string } "The tag store fetch or create failed"
+
+  entity StripTag [persistent: tags] {
+    id : string!
+    name : string! @description "The descriptive label for this tag." @synonyms "label, title"
+    parentId : StripTag @description "Reference to the parent tag in the hierarchy; empty marks a root." @synonyms "parent, ancestor"
+    createdAt : string = ""
+    pendingId : string = ""
+    docId : string @intrinsic @description "The open record's id, stashed at SHOW_TAG_STRIP so commits know which row to update." @synonyms "record id, scope id" = ""
+    docTagIds : [string] @intrinsic @description "The open record's current tag ids, stashed at SHOW_TAG_STRIP for membership tests." @synonyms "attached tags, current tags"
+    pendingTagName : string @intrinsic @description "The tag name typed or clicked on add, held across the resolve fetch." @synonyms "typed tag, adding tag" = ""
+    pendingNames : [string] @intrinsic @description "The chip names remaining after a remove, held across the resolve fetch." @synonyms "remaining tags, kept names"
+  }
+
+  trait TagStrip -> @rebindable StripTag [interaction, collection] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+        (fetch StripTag {
+          emit: { failure: TagStripLoadFailed, success: TagStripOptions }
+        })
+      ;; Pre-scope paint: the store is warm but no record is open yet.
+      TagStripOptions -> idle
+      TagStripLoadFailed -> idle
+      SHOW_TAG_STRIP -> loading
+        (set @entity.docId ?id)
+        (set @entity.docTagIds (array/map ?tagIds (fn t (str/default (object/get @t id) @t))))
+        (fetch StripTag {
+          emit: { failure: TagStripLoadFailed, success: TagStripOptions }
+        })
+    }
+
+    state loading {
+      SHOW_TAG_STRIP -> loading
+        (set @entity.docId ?id)
+        (set @entity.docTagIds (array/map ?tagIds (fn t (str/default (object/get @t id) @t))))
+        (fetch StripTag {
+          emit: { failure: TagStripLoadFailed, success: TagStripOptions }
+        })
+      TagStripOptions -> ready
+        (render-ui main {
+          children: [(if (or @config.readOnly ["=", @config.title, ""]) null {
+            color: muted
+            content: @config.title
+            type: typography
+            variant: caption
+          }), (if @config.readOnly null {
+            addEvent: ADD_TAG
+            helperText: @config.helperText
+            placeholder: @config.placeholder
+            removeEvent: REMOVE_TAG
+            type: tag-input
+            value: (array/map (array/filter ?data (fn t (array/includes @entity.docTagIds (object/get @t id)))) (fn t (object/get @t name)))
+            variant: secondary
+          }), (if (or @config.readOnly ["=", (array/len (array/filter ?data (fn t (if (array/includes @entity.docTagIds (object/get @t id)) false true)))), 0]) null {
+            children: (array/map (array/filter ?data (fn t (if (array/includes @entity.docTagIds (object/get @t id)) false true))) (fn t {
+              action: ADD_TAG
+              actionPayload: { tag: @t.name }
+              icon: tag
+              label: @t.name
+              size: sm
+              type: button
+              variant: ghost
+            }))
+            className: flex-wrap
+            direction: horizontal
+            gap: xs
+            type: stack
+          })]
+          direction: vertical
+          gap: xs
+          type: stack
+        })
+      TagStripLoadFailed -> idle
+        (render-ui main {
+          message: ?error
+          type: alert
+          variant: error
+        })
+    }
+
+    state ready {
+      SHOW_TAG_STRIP -> loading
+        (set @entity.docId ?id)
+        (set @entity.docTagIds (array/map ?tagIds (fn t (str/default (object/get @t id) @t))))
+        (fetch StripTag {
+          emit: { failure: TagStripLoadFailed, success: TagStripOptions }
+        })
+      ADD_TAG -> adding
+        (set @entity.pendingTagName ?tag)
+        (fetch StripTag {
+          emit: { failure: TagStripLoadFailed, success: TagStripAddOptions }
+        })
+        (render-ui main {
+          align: center
+          children: [{ size: sm, type: spinner }]
+          direction: horizontal
+          gap: xs
+          type: stack
+        })
+      REMOVE_TAG -> removing
+        (set @entity.pendingNames ?value)
+        (fetch StripTag {
+          emit: { failure: TagStripLoadFailed, success: TagStripRemoveOptions }
+        })
+        (render-ui main {
+          align: center
+          children: [{ size: sm, type: spinner }]
+          direction: horizontal
+          gap: xs
+          type: stack
+        })
+      TagStripTagCreated -> ready
+    }
+
+    state adding {
+      SHOW_TAG_STRIP -> loading
+        (set @entity.docId ?id)
+        (set @entity.docTagIds (array/map ?tagIds (fn t (str/default (object/get @t id) @t))))
+        (fetch StripTag {
+          emit: { failure: TagStripLoadFailed, success: TagStripOptions }
+        })
+      ;; The typed name matches an existing tag — attach its id.
+      TagStripAddOptions -> ready when (array/includes (array/map ?data (fn t (object/get @t name))) @entity.pendingTagName)
+        (emit TAGS_CHANGED {
+          id: @entity.docId
+          tagIds: (array/append @entity.docTagIds (object/get (array/first (array/filter ?data (fn t ["=", (object/get @t name), @entity.pendingTagName]))) id))
+        })
+      ;; Unknown name — create it in the shared taxonomy, then attach.
+      TagStripAddOptions -> creating
+        (persist create StripTag { name: @entity.pendingTagName } {
+          emit: { failure: TagStripLoadFailed, success: TagStripTagCreated }
+        })
+      TagStripLoadFailed -> idle
+        (render-ui main {
+          message: ?error
+          type: alert
+          variant: error
+        })
+    }
+
+    state creating {
+      SHOW_TAG_STRIP -> loading
+        (set @entity.docId ?id)
+        (set @entity.docTagIds (array/map ?tagIds (fn t (str/default (object/get @t id) @t))))
+        (fetch StripTag {
+          emit: { failure: TagStripLoadFailed, success: TagStripOptions }
+        })
+      TagStripTagCreated -> ready when ["!=", (str/default ?id ""), ""]
+        (emit TAGS_CHANGED {
+          id: @entity.docId
+          tagIds: (array/append @entity.docTagIds ?id)
+        })
+      TagStripLoadFailed -> idle
+        (render-ui main {
+          message: ?error
+          type: alert
+          variant: error
+        })
+    }
+
+    state removing {
+      SHOW_TAG_STRIP -> loading
+        (set @entity.docId ?id)
+        (set @entity.docTagIds (array/map ?tagIds (fn t (str/default (object/get @t id) @t))))
+        (fetch StripTag {
+          emit: { failure: TagStripLoadFailed, success: TagStripOptions }
+        })
+      ;; The remaining chip names map back to ids — every kept name exists
+      ;; by construction (chips only render attached, existing tags).
+      TagStripRemoveOptions -> ready
+        (emit TAGS_CHANGED {
+          id: @entity.docId
+          tagIds: (array/map (array/filter ?data (fn t (array/includes @entity.pendingNames (object/get @t name)))) (fn t (object/get @t id)))
+        })
+      TagStripLoadFailed -> idle
+        (render-ui main {
+          message: ?error
+          type: alert
+          variant: error
+        })
+    }
+
+    emits {
+      TAGS_CHANGED -> external {
+        id : string
+        tagIds : [string]
+      }
+        @description "The record's tag set changed (chip added or removed); the host routes this into its persistor's update so the write and the refetch stay the organism's."
+        @synonyms "tags updated, tag set changed, retagged"
+        @tier "domain"
+      ADD_TAG {
+        tag : string!
+      }
+        @description "A tag name was typed into the strip or an existing tag's suggestion chip was clicked."
+        @synonyms "attach tag, add label"
+        @tier "presentation"
+      REMOVE_TAG {
+        tag : string
+        value : [string]
+      }
+        @description "A chip's remove affordance was clicked; value carries the names that remain."
+        @synonyms "detach tag, remove label"
+        @tier "presentation"
+      TagStripOptions {
+        data : [StripTag]
+      }
+        @description "The shared tag store loaded for the display pass."
+        @tier "internal"
+      TagStripAddOptions {
+        data : [StripTag]
+      }
+        @description "The shared tag store loaded to resolve a typed name on add."
+        @tier "internal"
+      TagStripRemoveOptions {
+        data : [StripTag]
+      }
+        @description "The shared tag store loaded to resolve the remaining names on remove."
+        @tier "internal"
+      TagStripTagCreated {
+        id : string
+        row : StripTag
+      }
+        @description "A typed name had no existing tag; a fresh row was created in the shared taxonomy."
+        @tier "internal"
+      TagStripLoadFailed {
+        error : string
+        code : string
+      }
+        @description "The tag store fetch or create failed."
+        @tier "internal"
+    }
+
+    listens {
+      SHOW_TAG_STRIP {
+        id : string!
+        tagIds : [string]
+      }
+        @description "Scope the strip to the open record — routed from the document's load events; carries the record's id and current tag ids (hydrated tag rows are normalized to their ids at stash time, so include-hydrated fetches route straight through)."
+        @synonyms "load tags, scope tag strip, show tags"
+        @tier "domain"
+      ADD_TAG {
+        tag : string!
+      }
+        @description "Attach a tag by name — typed into the input or clicked from the existing-tag chips."
+        @synonyms "attach tag, add label"
+        @tier "presentation"
+      REMOVE_TAG {
+        tag : string
+        value : [string]
+      }
+        @description "Detach a chip; value carries the names that remain."
+        @synonyms "detach tag, remove label"
+        @tier "presentation"
+      TagStripOptions {
+        data : [StripTag]
+      }
+        @description "Display-pass fetch resolved."
+        @tier "internal"
+      TagStripAddOptions {
+        data : [StripTag]
+      }
+        @description "Add-resolve fetch resolved."
+        @tier "internal"
+      TagStripRemoveOptions {
+        data : [StripTag]
+      }
+        @description "Remove-resolve fetch resolved."
+        @tier "internal"
+      TagStripTagCreated {
+        id : string
+        row : StripTag
+      }
+        @description "The taxonomy row for a typed name persisted; attach its id."
+        @tier "internal"
+      TagStripLoadFailed {
+        error : string
+        code : string
+      }
+        @description "The tag store fetch or create failed."
+        @tier "internal"
+    }
+
+    config {
+      title : string = Tags
+        @label "Strip caption"
+        @description "Small caption above the chips; empty hides it"
+        @tier "presentation"
+      readOnly : boolean = false
+        @label "Read-only?"
+        @description "When true the strip renders nothing — no add input, no remove, no suggestion chips. Hosts pass a role condition here so read-only viewers rely on the record's read-only rails (which keep showing the tags) instead of an editing surface."
+        @synonyms "read only tags, viewer mode, no tag editing, hide tag input"
+        @tier "policy"
+      placeholder : string = "Add a tag…"
+        @label "Input placeholder"
+        @description "Placeholder in the type-to-add input"
+        @tier "presentation"
+      helperText : string = ""
+        @label "Helper text"
+        @description "Optional helper line under the input"
+        @tier "presentation"
+    }
+  }
+
+  page "/tagstrip/demo" as TagStripDemoPage -> TagStrip
+}