@almadar/std 16.187.0 → 16.189.0

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

@@ -0,0 +1,731 @@
+app std-record-detail "1.0.0"
+"std-record-detail — single primitive: detail-panel. Owns the fetch-one-record state machine (loading → viewing → error, with RETRY), the record counterpart to std-browse's collection machine. Consumers configure fields/sections/actions and the title/subtitle/status bindings; the atom fetches by the id (or, for slug-routed records, the slug) carried on INIT and renders the panel. `detailLook` (panel default / slide-over / page / document) selects the render body, exactly as std-browse's browseLook selects a collection shape. The `document` look is for records whose shape IS a document (wiki page, note, article): the pure writing surface — a big inline-editable title with the rich-text body DIRECTLY beneath it, Edit/Done and the actions menu tucked into the header corner — where clicking the body drops a cursor in, every typing pause autosaves (CONTENT_SAVED, which the host persists QUIETLY — no refetch, or the editor unmounts mid-keystroke), and Done emits CONTENT_COMMITTED (the host refetches and snapshots version history on this one). Metadata never sits between the title and the words: compose the sibling RecordItemDetails trait beside the doc for a Gutenberg-style settings rail. A row minted blank by a document-first create arrives with draft=1 on INIT and opens straight in the editor. Pair with std-detail-layout for the back + breadcrumb chrome — that atom owns navigation, this one owns the record — exactly as a list page pairs std-browse with std-app-layout."
+;; @capabilities "record detail, single record view, entity detail panel, drill-down record, show one record, record profile, detail page, view details, document editor, wiki page, note taking, article body, rich text editing, write and edit content"
+orbital RecordItemOrbital {
+  type RecordAction = { label : string!, event : string!, icon : string, variant : primary | secondary | ghost | danger }
+  type RecordFieldSpec = { key : string!, header : string, format : date | currency | number | boolean | percent }
+  type MetaFieldSpec = { key : string!, label : string, kind : text | boolean | select | readonly, options : [string], icon : string, format : date | currency | number | boolean | percent }
+  type RecordSection = { title : string!, fields : [string] }
+
+  type RecordItemLoaded = Event { data : RecordItem, totalCount : number } "Fired when the single record finishes loading; payload.data holds the record. totalCount is accepted so a fetch emitter shared with collection atoms still validates."
+
+  type RecordItemSlugLoaded = Event { data : [RecordItem], totalCount : number } "Fired when a slug-routed record finishes loading. The fetch filters on the slug field, so the payload is a collection — (array/first ?data) is the record, and an empty array means no record matches the address."
+
+  type RecordItemLoadFailed = Event { error : string, code : string } "Fired when the record fails to load; drives the error state so a failed load shows an alert with a retry instead of an empty page."
+
+  entity RecordItem [runtime] {
+    id : string!
+    name : string! @description "The record's title or identifier." @synonyms "title, label, heading"
+    description : string @description "A textual explanation or summary of the record." @synonyms "summary, details, notes"
+    status : "active" | "inactive" | "pending" @description "The record's current state." @synonyms "state, condition, stage" = active
+    slug : string @description "URL-friendly identifier, for records opened by address instead of id." @synonyms "permalink, url key, address" = ""
+    content : string @description "The record's rich-text body as HTML, edited in place by the document look." @synonyms "body, text, document, article body" = ""
+    loadedRow : object @intrinsic @description "The full row exactly as last fetched (relations hydrated when config.include asks). The document look binds it as the panel's entity and hands it to header actions as ?row, so a settings modal seeds from the real record instead of the atom's four mapped columns." = {}
+    openDraft : string @intrinsic @description "Set from the navigate payload when the surface was opened on a record that was JUST minted blank; read once the row loads to decide whether the document body opens authoring (draft) or read-only. Absent on a refresh or a normal open, so the draft entry never repeats." @synonyms "new document, just created, draft open" = ""
+    createdAt : string
+  }
+
+  trait RecordItemDetail -> @rebindable RecordItem [interaction, instance] {
+    ;; One machine, two shapes. A page detail (`openOn: init`, the default)
+    ;; falls straight through idle on INIT and behaves exactly as before. An
+    ;; overlay (`openOn: event`) stays blank until a row-click OPEN_VIEW hands
+    ;; it an id, which is the topology 23 hand-authored viewer traits use and
+    ;; the reason they could not compose an `initial: loading` atom: mounting
+    ;; one on a list page would fetch a record it has no id for.
+    initial: idle
+
+    state idle {
+      INIT -> loading when (and ["=", @config.openOn, "init"] ["!=", (str/default ?id ""), ""])
+        (set @entity.id ?id)
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          emit: { failure: RecordItemLoadFailed, success: RecordItemLoaded }
+          id: ?id
+          include: @config.include
+        })
+        (render-ui main { rows: 4, type: skeleton })
+      ;; Slug-routed open (/things/:slug): no id on the payload, so fetch by
+      ;; the slug field instead. Filtered rather than by-id, so the success
+      ;; payload is a collection — its own event keeps the two shapes honest.
+      INIT -> loading when (and ["=", @config.openOn, "init"] ["=", (str/default ?id ""), ""] ["!=", (str/default ?slug ""), ""])
+        (set @entity.slug ?slug)
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          filter: ["=", (object/get @entity slug), ?slug]
+          emit: { failure: RecordItemLoadFailed, success: RecordItemSlugLoaded }
+          include: @config.include
+        })
+        (render-ui main { rows: 4, type: skeleton })
+      ;; Fallback: an init-opened surface whose INIT carried neither key —
+      ;; fetch by the (missing) id so the failure surfaces as the error
+      ;; state's alert + Retry instead of a silent blank page. This is the
+      ;; pre-slug atom's exact behavior, kept as the explicit last arm.
+      INIT -> loading when (and ["=", @config.openOn, "init"] ["=", (str/default ?id ""), ""] ["=", (str/default ?slug ""), ""])
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          emit: { failure: RecordItemLoadFailed, success: RecordItemLoaded }
+          id: ?id
+          include: @config.include
+        })
+        (render-ui main { rows: 4, type: skeleton })
+      ;; 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 /
+      ;; revision path (CONTENT_COMMITTED).
+      CONTENT_SAVED -> idle
+      CONTENT_COMMITTED -> idle
+      TITLE_COMMITTED -> idle
+      ;; ONE unguarded arm on purpose. This briefly carried a second,
+      ;; `when @config.preloaded`-guarded arm that rendered the OPEN_VIEW row
+      ;; directly to skip a round-trip. Both execution paths mishandled it:
+      ;; the live runtime PASSED the guard with `preloaded: false`
+      ;; (StateMachineCore's permissive mode turns an unresolved config guard
+      ;; into true), so overlays rendered from `?row` and never fetched —
+      ;; silently skipping `include` relation hydration; and the canonical
+      ;; evaluator FAILED the guard and then did not fall through to this arm,
+      ;; reporting the event as not firing at all. A guarded arm is not
+      ;; currently a trustworthy correctness boundary, so the atom no longer
+      ;; depends on one. Zero consumers had opted into the skip.
+      OPEN_VIEW -> loading
+        (set @entity.id ?id)
+        (fetch RecordItem {
+          emit: { failure: RecordItemLoadFailed, success: RecordItemLoaded }
+          id: ?id
+          include: @config.include
+        })
+        (render-ui main { rows: 4, type: skeleton })
+    }
+
+    state loading {
+      INIT -> loading when ["!=", (str/default ?id ""), ""]
+        (set @entity.id ?id)
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          emit: { failure: RecordItemLoadFailed, success: RecordItemLoaded }
+          id: ?id
+          include: @config.include
+        })
+        ;; Skeleton, not a blank frame: the hand-authored detail traits this
+        ;; atom replaces rendered nothing until the record arrived.
+        (render-ui main { rows: 4, type: skeleton })
+      INIT -> loading when (and ["=", (str/default ?id ""), ""] ["!=", (str/default ?slug ""), ""])
+        (set @entity.slug ?slug)
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          filter: ["=", (object/get @entity slug), ?slug]
+          emit: { failure: RecordItemLoadFailed, success: RecordItemSlugLoaded }
+          include: @config.include
+        })
+        (render-ui main { rows: 4, type: skeleton })
+      ;; A record minted blank by a document-first create arrives with
+      ;; draft=1 and lands straight in the editor — a distinct target state,
+      ;; not a flag on the render, so the machine stays honest about being
+      ;; in an editing session.
+      RecordItemLoaded -> editing when ["=", (str/default (object/get @entity openDraft) ""), "1"]
+        ;; (object/merge … {}) is a type adapter only: type_compat lacks "declared object accepts a named row type" (ledgered)
+        (set @entity.loadedRow (object/merge ?data {}))
+        (set @entity.id (object/get ?data id))
+        (set @entity.name (object/get ?data @config.titleField))
+        (set @entity.description (str/default (object/get ?data @config.subtitleField) ""))
+        (set @entity.content (object/get ?data @config.contentField))
+        (render-ui main @config.documentEditingContent)
+      RecordItemLoaded -> viewing when ["!=", (str/default (object/get @entity openDraft) ""), "1"]
+        ;; (object/merge … {}) is a type adapter only: type_compat lacks "declared object accepts a named row type" (ledgered)
+        (set @entity.loadedRow (object/merge ?data {}))
+        (set @entity.id (object/get ?data id))
+        (set @entity.name (object/get ?data @config.titleField))
+        (set @entity.description (str/default (object/get ?data @config.subtitleField) ""))
+        (set @entity.content (object/get ?data @config.contentField))
+        (if ["=", @config.detailLook, document]
+          (render-ui main @config.documentBodyContent)
+          (if ["=", @config.detailLook, slide-over]
+            (render-ui main @config.slideOverBodyContent)
+            (if ["=", @config.detailLook, page]
+              (render-ui main @config.pageBodyContent)
+              (render-ui main @config.bodyContent))))
+      RecordItemSlugLoaded -> editing when (and [">", (array/len ?data), 0] ["=", (str/default (object/get @entity openDraft) ""), "1"])
+        (set @entity.loadedRow (array/first ?data))
+        (set @entity.id (object/get (array/first ?data) id))
+        (set @entity.name (object/get (array/first ?data) @config.titleField))
+        (set @entity.description (str/default (object/get (array/first ?data) @config.subtitleField) ""))
+        (set @entity.content (object/get (array/first ?data) @config.contentField))
+        (render-ui main @config.documentEditingContent)
+      RecordItemSlugLoaded -> viewing when (and [">", (array/len ?data), 0] ["!=", (str/default (object/get @entity openDraft) ""), "1"])
+        (set @entity.loadedRow (array/first ?data))
+        (set @entity.id (object/get (array/first ?data) id))
+        (set @entity.name (object/get (array/first ?data) @config.titleField))
+        (set @entity.description (str/default (object/get (array/first ?data) @config.subtitleField) ""))
+        (set @entity.content (object/get (array/first ?data) @config.contentField))
+        (if ["=", @config.detailLook, document]
+          (render-ui main @config.documentBodyContent)
+          (if ["=", @config.detailLook, slide-over]
+            (render-ui main @config.slideOverBodyContent)
+            (if ["=", @config.detailLook, page]
+              (render-ui main @config.pageBodyContent)
+              (render-ui main @config.bodyContent))))
+      RecordItemSlugLoaded -> error when ["=", (array/len ?data), 0]
+        (render-ui main { description: "No record matches this address.", icon: search-x, title: "Not found", type: empty-state })
+      RecordItemLoadFailed -> error
+        (render-ui main { message: ?error, title: "Couldn't load this record", type: alert, variant: error })
+    }
+
+    ;; The document look's editing session. Reached from a draft landing or
+    ;; the read view's EDIT_CONTENT; every typing pause autosaves through
+    ;; CONTENT_SAVED, and Done commits. INIT is handled ONLY for a
+    ;; DIFFERENT record: a page navigation (open another note, open a
+    ;; just-minted subpage) delivers INIT and must not be swallowed — the
+    ;; session's server-side trait state survives navigation, so an
+    ;; INIT-less editing state left every later record page blank. The
+    ;; SAME record's INIT (the refetch echo after an update) stays
+    ;; unhandled on purpose: a repaint would unmount the editor under the
+    ;; author mid-keystroke. Work is already autosaved when we leave.
+    state editing {
+      INIT -> loading when (and ["!=", (str/default ?id ""), ""] ["!=", ?id, @entity.id])
+        (set @entity.id ?id)
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          emit: { failure: RecordItemLoadFailed, success: RecordItemLoaded }
+          id: ?id
+          include: @config.include
+        })
+        (render-ui main { rows: 4, type: skeleton })
+      INIT -> loading when (and ["=", (str/default ?id ""), ""] ["!=", (str/default ?slug ""), ""] ["!=", ?slug, @entity.slug])
+        (set @entity.slug ?slug)
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          filter: ["=", (object/get @entity slug), ?slug]
+          emit: { failure: RecordItemLoadFailed, success: RecordItemSlugLoaded }
+          include: @config.include
+        })
+        (render-ui main { rows: 4, type: skeleton })
+      CONTENT_CHANGE -> editing
+        (set @entity.content ?value)
+        (set @entity.loadedRow (object/set @entity.loadedRow @config.contentField ?value))
+        (emit CONTENT_SAVED { id: @entity.id, content: @entity.content })
+      TITLE_COMMITTED -> editing
+        (set @entity.name ?title)
+        (set @entity.loadedRow (object/set @entity.loadedRow @config.titleField ?title))
+      DONE_EDITING -> viewing
+        (emit CONTENT_SAVED { id: @entity.id, content: @entity.content })
+        (emit CONTENT_COMMITTED { id: @entity.id, content: @entity.content })
+        (render-ui main @config.documentBodyContent)
+      ;; The editing card renders the same header actions as the read view,
+      ;; so a consumer-configured Close must not be a dead button here:
+      ;; flush the autosave stream and close, same contract as Done minus
+      ;; the commit.
+      CLOSE_VIEW -> idle
+        (emit CONTENT_SAVED { id: @entity.id, content: @entity.content })
+        (render-ui main null)
+    }
+
+    state viewing {
+      ;; No skeleton on re-entry: from a populated panel a skeleton unmounts the
+      ;; record and flickers. First mount is unaffected — `initial: loading` and
+      ;; `state loading`'s own INIT still paint it.
+      INIT -> loading when ["!=", (str/default ?id ""), ""]
+        (set @entity.id ?id)
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          emit: { failure: RecordItemLoadFailed, success: RecordItemLoaded }
+          id: ?id
+          include: @config.include
+        })
+      INIT -> loading when (and ["=", (str/default ?id ""), ""] ["!=", (str/default ?slug ""), ""])
+        (set @entity.slug ?slug)
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          filter: ["=", (object/get @entity slug), ?slug]
+          emit: { failure: RecordItemLoadFailed, success: RecordItemSlugLoaded }
+          include: @config.include
+        })
+      RecordItemLoaded -> viewing
+        ;; (object/merge … {}) is a type adapter only: type_compat lacks "declared object accepts a named row type" (ledgered)
+        (set @entity.loadedRow (object/merge ?data {}))
+        (set @entity.id (object/get ?data id))
+        (set @entity.name (object/get ?data @config.titleField))
+        (set @entity.description (str/default (object/get ?data @config.subtitleField) ""))
+        (set @entity.content (object/get ?data @config.contentField))
+        (if ["=", @config.detailLook, document]
+          (render-ui main @config.documentBodyContent)
+          (if ["=", @config.detailLook, slide-over]
+            (render-ui main @config.slideOverBodyContent)
+            (if ["=", @config.detailLook, page]
+              (render-ui main @config.pageBodyContent)
+              (render-ui main @config.bodyContent))))
+      RecordItemSlugLoaded -> viewing when [">", (array/len ?data), 0]
+        (set @entity.loadedRow (array/first ?data))
+        (set @entity.id (object/get (array/first ?data) id))
+        (set @entity.name (object/get (array/first ?data) @config.titleField))
+        (set @entity.description (str/default (object/get (array/first ?data) @config.subtitleField) ""))
+        (set @entity.content (object/get (array/first ?data) @config.contentField))
+        (if ["=", @config.detailLook, document]
+          (render-ui main @config.documentBodyContent)
+          (if ["=", @config.detailLook, slide-over]
+            (render-ui main @config.slideOverBodyContent)
+            (if ["=", @config.detailLook, page]
+              (render-ui main @config.pageBodyContent)
+              (render-ui main @config.bodyContent))))
+      RecordItemSlugLoaded -> error when ["=", (array/len ?data), 0]
+        (render-ui main { description: "No record matches this address.", icon: search-x, title: "Not found", type: empty-state })
+      ;; The document body is its own edit affordance: clicking it (or its
+      ;; Edit button) starts the editing session with a cursor in the text.
+      EDIT_CONTENT -> editing
+        (render-ui main @config.documentEditingContent)
+      ;; The title renames from the read view too, without an editing session.
+      TITLE_COMMITTED -> viewing
+        (set @entity.name ?title)
+        (set @entity.loadedRow (object/set @entity.loadedRow @config.titleField ?title))
+      RecordItemLoadFailed -> error
+        (render-ui main { message: ?error, title: "Couldn't load this record", type: alert, variant: error })
+      CLOSE_VIEW -> idle
+        (render-ui main null)
+    }
+
+    state error {
+      INIT -> loading when ["!=", (str/default ?id ""), ""]
+        (set @entity.id ?id)
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          emit: { failure: RecordItemLoadFailed, success: RecordItemLoaded }
+          id: ?id
+          include: @config.include
+        })
+        (render-ui main { rows: 4, type: skeleton })
+      INIT -> loading when (and ["=", (str/default ?id ""), ""] ["!=", (str/default ?slug ""), ""])
+        (set @entity.slug ?slug)
+        (set @entity.openDraft (str/default ?draft ""))
+        (fetch RecordItem {
+          filter: ["=", (object/get @entity slug), ?slug]
+          emit: { failure: RecordItemLoadFailed, success: RecordItemSlugLoaded }
+          include: @config.include
+        })
+        (render-ui main { rows: 4, type: skeleton })
+      ;; The hand-authored traits sent a failed load back to `loading` with no
+      ;; effect, so the page stayed blank forever with no way out. RETRY is the
+      ;; way out.
+      RETRY -> loading
+        (fetch RecordItem {
+          emit: { failure: RecordItemLoadFailed, success: RecordItemLoaded }
+          id: @entity.id
+          include: @config.include
+        })
+        (render-ui main { rows: 4, type: skeleton })
+    }
+
+    emits {
+      RecordItemLoaded
+        @description "Signals that the record has been successfully loaded."
+        @synonyms "loaded, received, ready, fetched"
+        @tier "domain"
+      RecordItemSlugLoaded
+        @description "A slug-routed record finished loading; the payload is a collection whose first element is the record. Composing traits that need the loaded row (comments scoping, status controls) listen to this."
+        @synonyms "loaded by address, slug resolved, record found"
+        @tier "domain"
+      RecordItemLoadFailed
+        @description "Indicates a failure to load the record."
+        @synonyms "error, failed, problem, unsuccessful"
+        @tier "internal"
+      EDIT -> external {
+        id : string!
+        row : RecordItem
+      }
+        @description "Signals a request to edit the record being viewed."
+        @synonyms "modify, update, change"
+        @tier "domain"
+      DELETE -> external {
+        id : string!
+        row : RecordItem
+      }
+        @description "Signals a request to remove the record being viewed."
+        @synonyms "remove, discard, delete, archive"
+        @tier "domain"
+      CONTENT_SAVED -> external {
+        id : string!
+        content : string
+      }
+        @description "The document look's autosave stream: fired at every typing pause while editing, and once more on Done. This atom never persists — the composing organism routes CONTENT_SAVED into a QUIET persist (one that does not refetch or repaint this surface, or the editor unmounts mid-keystroke)."
+        @synonyms "autosave, saved, persist content, draft saved"
+        @tier "domain"
+      CONTENT_COMMITTED -> external {
+        id : string!
+        content : string
+      }
+        @description "The author finished the document editing session (pressed Done). Hosts refetch the row, repaint, and snapshot version history on THIS event — never on the CONTENT_SAVED autosave stream."
+        @synonyms "done, finished editing, commit, snapshot"
+        @tier "domain"
+      TITLE_COMMITTED -> external {
+        title : string
+        id : string
+      }
+        @description "The viewer renamed the record in place by editing the document title; carries the committed title and the row id for a partial persist."
+        @synonyms "rename, retitle, change title, edit title"
+        @tier "domain"
+      EDIT_CONTENT
+        @description "The viewer clicked the document body (or its Edit button) to start an editing session."
+        @synonyms "edit, start editing, click to edit"
+        @tier "presentation"
+      DONE_EDITING
+        @description "The viewer pressed Done to end the document editing session."
+        @synonyms "done, finish, stop editing"
+        @tier "presentation"
+    }
+
+    listens {
+      INIT {
+        id : string
+        slug : string
+        draft : string
+      }
+        @description "Opens the detail surface for one record: by id, or by slug for address-routed records (the internal re-fetch after an update still carries id). `draft` is set only by a document-first create's navigate, and opens the document look's body straight in the editor."
+        @synonyms "open record, view record, show details, drill in"
+        @tier "domain"
+      CONTENT_CHANGE {
+        value : string
+      }
+        @description "The rich text surface reported an edit (already debounced to typing pauses by the component)."
+        @synonyms "typing, content changed, body edited"
+        @tier "domain"
+      EDIT_CONTENT
+        @description "Start the document editing session."
+        @synonyms "edit, start editing, click to edit"
+        @tier "presentation"
+      DONE_EDITING
+        @description "End the document editing session; work is already autosaved when it fires."
+        @synonyms "done, finish, stop editing"
+        @tier "presentation"
+      TITLE_COMMITTED {
+        title : string
+        id : string
+      }
+        @description "The document title was renamed in place."
+        @synonyms "rename, retitle, change title"
+        @tier "domain"
+      OPEN_VIEW {
+        id : string!
+        row : RecordItem
+      }
+        @description "A row was opened from a list; shows that record in this surface."
+        @synonyms "open record, view row, show details, drill in, expand"
+        @tier "domain"
+      CLOSE_VIEW
+        @description "Closes the record surface and returns it to blank."
+        @synonyms "close, dismiss, back to list"
+        @tier "domain"
+      RETRY
+        @description "Re-runs the fetch after a failed load."
+        @synonyms "try again, reload, refresh"
+        @tier "domain"
+      RecordItemLoadFailed {
+        error : string
+        code : string
+      }
+        @description "Indicates a failure to load the record."
+        @synonyms "error, failure, problem, unsuccessful"
+        @tier "internal"
+    }
+
+    config {
+      fields : [RecordFieldSpec] = [{
+        header: Name
+        key: name
+      }, {
+        header: Description
+        key: description
+      }, {
+        header: Status
+        key: status
+      }, {
+        format: date
+        header: Created
+        key: createdAt
+      }]
+        @label "Which fields appear in the record panel?"
+        @description "Each entry maps one entity field to a labelled row in the panel. Unlike a list row, a detail panel SHOULD label every field — the value stands alone here with no column header or repeated row position to name it."
+        @synonyms "detail fields, record fields, panel fields, shown fields"
+        @tier "presentation"
+      sections : [RecordSection] = []
+        @label "How should the fields be grouped?"
+        @description "Optional titled groups over `fields`, e.g. [{title: Contact, fields: [email, phone]}]. Group into sections of 3-5 once a record carries more than about seven fields — a flat list past that is the cognitive-load problem Almadar_UX.md §1.4 (Miller) describes. Empty = one ungrouped list, the default."
+        @synonyms "field groups, grouped fields, panel sections, fieldsets"
+        @tier "presentation"
+      actions : [RecordAction] = [{
+        event: EDIT
+        label: Edit
+        variant: secondary
+      }, {
+        event: DELETE
+        label: Delete
+        variant: danger
+      }]
+        @label "What actions can users take on this record?"
+        @description "Buttons on the panel header. One primary at most; the rest collapse past maxInlineActions."
+        @synonyms "record actions, detail actions, panel buttons"
+        @tier "presentation"
+      maxInlineActions : number = 3
+        @label "How many actions before collapsing?"
+        @description "Actions beyond this count collapse into a '⋯' overflow menu."
+        @synonyms "inline actions limit, overflow threshold"
+        @tier "presentation"
+      showActions : boolean = true
+        @label "Show the action buttons?"
+        @description "Set false for a read-only record view; a panel with actions nothing listens to is a dead affordance."
+        @synonyms "read only, hide actions, view only"
+        @tier "presentation"
+      ;; Field NAMES, not binding paths. A path knob (`subtitleBinding:
+      ;; @entity.company`) makes the consumer responsible for an @entity field
+      ;; this atom never sets — an ORB_BINDING_ENTITY_FIELD_NEVER_SET and an
+      ;; empty subtitle, which is exactly what the first migration of std-crm
+      ;; ContactDetail hit. Naming the source field instead lets the atom do the
+      ;; (set) itself off the payload, so the trap cannot be reintroduced.
+      titleField : string = name
+        @label "Which field is the record's title?"
+        @description "Name of the field on the loaded record shown as the panel title (e.g. contactName, subject, title)."
+        @synonyms "title field, heading field, name field, label field"
+        @tier "presentation"
+      subtitleField : string = description
+        @label "Which field is the subtitle?"
+        @description "Name of the field shown under the title (e.g. company, category). Set to \"\" for no subtitle at all — the right choice for the document look, whose metadata lives in the properties strip, not a second line."
+        @synonyms "subtitle field, secondary field, subheading, no subtitle"
+        @tier "presentation"
+      include : [string] = []
+        @label "Which relation fields to hydrate?"
+        @description "Entity relation field names to hydrate on fetch, so panel fields can use dot-paths like owner.name. Empty = no hydration, the default."
+        @synonyms "relation hydration, populate relations, joined fields"
+        @tier "internal"
+      openOn : "init" | "event" = init
+        @label "When does this surface load?"
+        @description "init = a routed detail page; the record loads as soon as the page mounts (the default). event = an overlay that stays blank until a row-click OPEN_VIEW hands it an id, which is what a list-embedded slide-over needs — mounting an init-loading surface on a list page would fetch a record it has no id for."
+        @synonyms "open on click, slide over, row click, blank until opened, list embedded"
+        @tier "policy"
+      detailLook : "panel" | "slide-over" | "page" | "document" = panel
+        @label "Detail look"
+        @description "Visual treatment for the record surface. panel = an inline detail-panel in the page flow (bodyContent); slide-over = the same panel as a right-hand drawer over the list behind it (slideOverBodyContent); page = a full-width record page with roomier spacing (pageBodyContent); document = a wiki-page/note/article surface — big editable title over a rich-text body, no labelled field rows, click-to-edit with autosave (documentBodyContent / documentEditingContent). Selecting a look swaps which body tree renders after the record loads; any body may still be overridden directly at the call site."
+        @synonyms "detail style, drawer, slide over, full page, document, wiki page, note, article"
+        @tier "presentation"
+      contentField : string = content
+        @label "Which field holds the document body?"
+        @description "Name of the field on the loaded record that carries the rich-text HTML body the document look renders and edits (e.g. content, body, articleText)."
+        @synonyms "body field, content field, document field"
+        @tier "presentation"
+      editLabel : string = "Edit"
+        @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"
+      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."
+        @tier "presentation"
+      autosaveHint : string = "Saves as you type"
+        @label "Autosave hint"
+        @description "Muted caption next to the Done button telling the author their work persists on its own."
+        @tier "presentation"
+      placeholder : string = "Start writing…"
+        @label "Placeholder text"
+        @description "Placeholder shown in the document body when it is empty."
+        @tier "presentation"
+      bodyContent : render-ui = {
+        children: [{
+          actions: @config.actions
+          entity: ?data
+          fields: @config.fields
+          initialData: ?data
+          maxInlineActions: @config.maxInlineActions
+          sections: @config.sections
+          showActions: @config.showActions
+          subtitle: @entity.description
+          title: @entity.name
+          type: detail-panel
+        }]
+        direction: vertical
+        gap: lg
+        type: stack
+      }
+        @label "Body content tree"
+        @description "Render-ui SExpr rendered after the record loads when detailLook = panel (the default). See slideOverBodyContent/pageBodyContent for the other looks; any may be overridden directly while inheriting the same trait, state machine, emits, and listens."
+        @tier "internal"
+      slideOverBodyContent : render-ui = {
+        children: [{
+          actions: @config.actions
+          entity: ?data
+          fields: @config.fields
+          initialData: ?data
+          maxInlineActions: @config.maxInlineActions
+          sections: @config.sections
+          showActions: @config.showActions
+          slideOver: true
+          subtitle: @entity.description
+          title: @entity.name
+          type: detail-panel
+        }]
+        direction: vertical
+        gap: none
+        type: stack
+      }
+        @label "Slide-over look body"
+        @description "Render-ui SExpr rendered after the record loads when detailLook = slide-over: the same panel as a right-hand drawer, so the list behind stays in place. Use when the record is a glance, not a workspace."
+        @tier "internal"
+      pageBodyContent : render-ui = {
+        children: [{
+          actions: @config.actions
+          entity: ?data
+          fields: @config.fields
+          initialData: ?data
+          maxInlineActions: @config.maxInlineActions
+          sections: @config.sections
+          showActions: @config.showActions
+          subtitle: @entity.description
+          title: @entity.name
+          type: detail-panel
+        }]
+        className: "w-full max-w-4xl"
+        direction: vertical
+        gap: lg
+        type: stack
+      }
+        @label "Page look body"
+        @description "Render-ui SExpr rendered after the record loads when detailLook = page: a full record page, width-capped so field rows do not stretch past a readable measure (Almadar_UI_Beauty.md §3)."
+        @tier "internal"
+      documentBodyContent : render-ui = {
+        actions: @config.actions
+        editEvent: EDIT_CONTENT
+        editLabel: @config.editLabel
+        entity: @entity.loadedRow
+        maxInlineActions: @config.maxInlineActions
+        placeholder: @config.placeholder
+        subtitle: @entity.description
+        title: @entity.name
+        titleCommitEvent: TITLE_COMMITTED
+        type: document-panel
+        value: @entity.content
+        className: "w-full"
+      }
+        @label "Document look body (reading)"
+        @description "Render-ui SExpr for detailLook = document while reading: the pure writing surface — editable title with the rich-text body DIRECTLY beneath it, Edit and the actions menu tucked into the header corner. Metadata never sits between title and content; compose the sibling RecordItemDetails trait beside this one for the settings rail. Binds only @entity fields, never ?data, because it is also painted by arms whose payload is not the record."
+        @tier "internal"
+      documentEditingContent : render-ui = {
+        actions: @config.actions
+        autosaveHint: @config.autosaveHint
+        contentChangeEvent: CONTENT_CHANGE
+        doneEvent: DONE_EDITING
+        doneLabel: @config.doneLabel
+        editing: true
+        entity: @entity.loadedRow
+        maxInlineActions: @config.maxInlineActions
+        placeholder: @config.placeholder
+        subtitle: @entity.description
+        title: @entity.name
+        titleCommitEvent: TITLE_COMMITTED
+        type: document-panel
+        value: @entity.content
+        className: "w-full"
+      }
+        @label "Document look body (editing)"
+        @description "Render-ui SExpr for detailLook = document during an editing session: the same surface with the body live and the header corner showing the autosave hint + Done. Binds only @entity fields, never ?data."
+        @tier "internal"
+    }
+  }
+
+  ;; The document's info panel — an on-demand DRAWER, never page furniture:
+  ;; the composing organism routes the doc's loaded event into SHOW_DETAILS
+  ;; (which only stashes the row) and a "Details" action on the document's
+  ;; menu into OPEN_DETAILS, which slides the panel in from the right over
+  ;; the content. The drawer's X / backdrop dismiss emits CLOSE back to this
+  ;; trait. A sibling of RecordItemDetail: the organism just MOUNTS this
+  ;; trait and wires the two listens — no layout wiring.
+  ;; EDITING metadata is not done here: it rides the document's "⋯" menu as
+  ;; normal actions (the settings modal, favorite/status workflows). The
+  ;; META_CHANGE → META_SAVED commit circuit stays available for a call-site
+  ;; detailsContent override that opts back into in-place editing.
+  trait RecordItemDetails -> @rebindable RecordItem [interaction, instance] {
+    initial: idle
+
+    state idle {
+      INIT -> idle
+      ;; stash only — the drawer opens on demand, never on load
+      SHOW_DETAILS -> idle
+        (set @entity.loadedRow (object/merge ?data {}))
+      OPEN_DETAILS -> showing
+        (render-ui drawer @config.detailsContent)
+      ;; validator self-loop; the real consumer is the host's persistor.
+      META_SAVED -> idle
+    }
+
+    state showing {
+      ;; a refetch echo while the drawer is open repaints it in place
+      SHOW_DETAILS -> showing
+        (set @entity.loadedRow (object/merge ?data {}))
+        (render-ui drawer @config.detailsContent)
+      OPEN_DETAILS -> showing
+        (render-ui drawer @config.detailsContent)
+      ;; the drawer X / backdrop dismiss
+      CLOSE -> idle
+        (render-ui drawer null)
+      ;; navigation must never strand an open drawer over the next page
+      INIT -> idle
+        (render-ui drawer null)
+      META_CHANGE -> showing
+        (emit META_SAVED { id: ?id, patch: ?patch })
+    }
+
+    emits {
+      META_SAVED -> external {
+        id : string!
+        patch : RecordItem
+      }
+        @description "A property in the settings rail committed in place; patch carries the row id plus the one changed field, ready to hand straight to a persist update. Quiet contract: the host persists without refetching or repainting the open document."
+        @synonyms "property saved, metadata changed, field committed, update property"
+        @tier "domain"
+    }
+
+    listens {
+      SHOW_DETAILS {
+        data : RecordItem
+      }
+        @description "The document finished loading; stash the row the details drawer will show. Hosts route the doc trait's RecordItemLoaded (or SlugLoaded first element) here."
+        @synonyms "record loaded, show metadata, populate details"
+        @tier "domain"
+      OPEN_DETAILS {
+        id : string
+      }
+        @description "Open the details drawer. Hosts route the document's Details action (e.g. Doc.VIEW_INFO) here."
+        @synonyms "show info, open details, document info, page info"
+        @tier "presentation"
+      CLOSE {
+        id : string
+      }
+        @description "Close the details drawer; the drawer chrome's X / backdrop dismiss emits this."
+        @synonyms "dismiss, close drawer, hide details"
+        @tier "presentation"
+      META_CHANGE {
+        id : string
+        patch : RecordItem
+      }
+        @description "A property in the rail committed (switch toggled, select changed, text blurred)."
+        @synonyms "property changed, metadata edited, field committed"
+        @tier "domain"
+    }
+
+    config {
+      metaFields : [MetaFieldSpec] = []
+        @label "Which metadata properties appear in the details drawer?"
+        @description "The record's metadata shown as read-only INFO in the details drawer (Updated, address, status, …). Editing metadata is a normal action under the document's menu, not an inline affordance here."
+        @synonyms "properties, metadata fields, document info, page info, front matter"
+        @tier "presentation"
+      detailsTitle : string = Details
+        @label "Details drawer heading"
+        @description "Heading of the settings card (e.g. Details, Page info, Document settings)."
+        @tier "presentation"
+      detailsContent : render-ui = {
+        entity: @entity.loadedRow
+        fields: @config.metaFields
+        title: @config.detailsTitle
+        type: document-details
+      }
+        @label "Details drawer content tree"
+        @description "Render-ui SExpr painted into the drawer slot on OPEN_DETAILS; binds the row stashed by SHOW_DETAILS. Info-only by default — no metaCommitEvent, so every row displays rather than edits (editing rides the document's actions menu). Override at the call site to extend the panel or to opt into in-place commits via metaCommitEvent: META_CHANGE."
+        @tier "internal"
+    }
+  }
+
+  page "/recorditems" as RecordItemDetailPage -> RecordItemDetail, RecordItemDetails
+}