phlex-reactive 0.14.3 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4b8ab0285b176f4fab5221687a3d3364e2311eaa4c08c091eef07763cf22a8e
-  data.tar.gz: 9072c2d1b802438c7f39c694753308020d65e9a20e38c1ee4f730351b25de49d
+  metadata.gz: eeebc2783f571e3e3fcc0847318ebef76050954e0e56a99f627e8e5654467133
+  data.tar.gz: 974cc0de7e79babb8834bf41a10001e69a087bda3daf6a87122cae7654e128cb
 SHA512:
-  metadata.gz: fc1c7ffa6b616154f5ce897f256fbd6d8be501948dc63295163b831b0578c55908c9187e4ac461d00dc2dd4d7481090672c654b28d30f9894a1ec65f079579d2
-  data.tar.gz: f889193d4bc9bdb381446d93bfcf5ddf3ac7047b84250787a63f83c61844712ba1c511529792381511570740fff8f37e42c385d14fbecaad9809e52ad3064b35
+  metadata.gz: f95657cd231a4e711d6300fae52cbefacb42f34d5803f98073366710855a7c5906e795844800c55e8a6ee2b089224809bacb739c0c90f1a89c97c23851c2c7e7
+  data.tar.gz: 0b47dacc177e41d086e045ec842879358c68d4ec298615c1fcb6e23fc8cdb8b53ce5db96fa4fe2424b1fdaa381870fd29ce6f50b1ac70b7375790590e1eae793

data/CHANGELOG.md

@@ -8,6 +8,86 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- **Presence — `reactive_presence`, `presence`, `js.presence` (#358).** A
+  roster component declares the presence stream it shows
+  (`reactive_presence :viewers, state: { selected: :integer }, ttl: 45`) and
+  reads it with `presence`: one peer per browser tab (`seat`, `member_id`,
+  `metadata`, `state`), grouped by person with `members`, filtered with
+  `where(selected: id)`. Tabs join on SSE connect, leave on disconnect and
+  expire after `ttl:` seconds of silence; each change re-renders the roster for
+  every viewer (one coalesced morph). Each tab's declared state is set with
+  `js.presence(**state)` (through the generated `presence_set` action, typed,
+  default-deny, and exempt from `verify_authorized` unless the component defines
+  `authorize_presence_state!`) or `presence.set(**state)` from an action. The
+  client marks this tab's element `data-reactive-presence-me` and the same
+  person's other elements `data-reactive-presence-same-member`, and fires
+  `reactive:presence` with the seats that joined and left. A new `presence`
+  feature module (1.3 KB gzipped): the default client bundles it (+992 B), the
+  split client fetches it only for a page with a presence root (+100 B in the
+  core). Needs pgbus 0.18.1 or later; without it a presence root raises
+  `Phlex::Reactive::ConfigurationError` at render. Create the table with
+  `rails g pgbus:add_presence` (or upgrade it with
+  `rails g pgbus:add_presence_seats`), return each viewer's identity from
+  `config.streams_authorize` (with none, pgbus joins the connection to no
+  roster), and run an ActiveJob adapter (joins, leaves and expiries render in
+  `PresenceRenderJob`). A closed tab leaves within about a second.
+  `ttl:` must be above pgbus's `streams_heartbeat_interval` (15 s by default). `js.presence` is refused on a broadcast, like `focus`. `reactive_presence_stream_name_for(record)` on the class gives a record's stream name, for a per-record check in `streams_authorize`. Docs: "Presence".
+
+- **`shortcut:` on `on()` and `on_client(:keydown, …)` — page-level keyboard
+  shortcuts (#357).** `on(:undo, shortcut: "mod+z")` binds a window keydown
+  where `mod` is ⌘ on Apple platforms and Ctrl elsewhere (rendered as a meta
+  twin and a ctrl twin; the client runs its platform's, the other is a no-op).
+  The shortcut does nothing while focus is in an `input`, `textarea`, `select`
+  or anything `contenteditable`, so native text undo keeps working
+  (`shortcut: { keys: "esc", in_editable: true }` opts in), and a matching
+  chord is `preventDefault`-ed before any `confirm:` dialog, also when pressed
+  before the controller connects (`phlex/reactive/early`). `shortcut:` with
+  `event:`, `window:` or `outside:`, a key outside Stimulus's default key map,
+  or an `on_client` event other than `:keydown` raises `ArgumentError` at
+  render. The inspector shows `keydown@window shortcut=mod+z`. `early.min.js`
+  grows 195 B gzipped (1,491 B); the default client 177 B.
+  **Compatibility:** `shortcut` is now a reserved keyword on `on(...)` and no
+  longer passes through as an action param. `event: "keydown.meta+z", window:
+  true` without `shortcut:` behaves exactly as before (never prevented, no
+  editable guard).
+
+- **Sortable lists — `reactive_sortable`, `reactive_sortable_source`,
+  `reactive_sortable_item` (#350).** Rows drag to reorder a list with a mouse,
+  a finger (a 200 ms press) or the keyboard (Space picks up, arrows move,
+  Space drops, Escape cancels, each step announced in the list's own
+  translatable words), and one declared action receives `item`, `position`,
+  `after` and `from` through the normal action pipeline (declare the ones you
+  want in `params:`; undeclared ones are dropped). The row moves at once
+  and goes back when the action fails or its reply does not render the list.
+  Sortables of one `group:` exchange rows (`name:` and static `params:` for a
+  kanban), and a `reactive_sortable_source` list's rows are copied in, routed
+  to their own action with `from:`. `handle:`, `disabled:`, `busy:` and the
+  `data-reactive-sortable-active` / `-dragging` / `-placeholder` styling hooks
+  round it out. The client is a new `sortable` feature module, about 3.1 KB
+  gzipped: the default client bundles it, and the split client fetches it only
+  for a page with a sortable. `core.proceed` now resolves with the reply's
+  HTML on success, so a feature can tell an applied reply from a failure. The
+  Project board demo drags its cards. Docs: "Sortable lists".
+
+- **`reactive_editable(:title)` — a contenteditable element as a first-class,
+  plain-text field (#351).** The helper renders `name` (scope-aware),
+  `contenteditable="plaintext-only"`, `role="textbox"`, `aria-multiline`,
+  `aria-placeholder` and `data-reactive-placeholder` onto your own element. Its
+  value is its text with line breaks as `\n` (folded to spaces when
+  single-line). While it is focused a `reply.morph` or broadcast morph keeps its
+  text and caret and still applies its attributes; unfocused, the server's text
+  wins, and `data-reactive-morph-value` opts out. Paste and drop insert plain
+  text (a handler, and a downgrade to `contenteditable="true"`, where the engine
+  lacks `plaintext-only`); Enter runs `on_enter:` (a `js` chain or `:submit`)
+  and is swallowed in a single-line field; Escape reverts to the last
+  server-rendered text (`on_escape: :revert`). `reactive_dirty` diffs it against
+  that text and `reactive_persist` drafts it with its line breaks. Bare named
+  `[contenteditable]` elements keep the `textContent` reading. An editable that a
+  stream appends into a root already on the page gets its keys and paste from
+  its first focus (the root loads the bindings feature then, and on the split
+  client the stream that brings it starts the import). Bundle: default
+  +977 B gzip, split core +412 B, `features/bindings` +524 B.
+
 - **`on_client(…, detail: { success: true })` — run ops only when the event's
   payload qualifies (#346).** A binding can require top-level `event.detail`
   keys to strictly equal JSON scalars, so `on_client("turbo:submit-end",
@@ -21,6 +101,33 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Fixed
 
+- **A stream that renders into a connected root wires what its content needs
+  (#356).** A root read its feature markers only at connect and after a morph
+  of itself, so a `reactive_show` target, select-all/count group, filter,
+  nested list, dirty field or paste trigger that an `append`, `prepend`,
+  `update`, `before`, `after` or child `replace` brought into it stayed dead
+  until the root reconnected. Now, once such a stream has rendered, the root
+  re-runs the seeds of the features it has (a new show target takes the
+  field's current value) and connects any feature its new content needs, in
+  both clients; bindings and form also wire a binding whose gate reads true
+  only then. As after a morph, this covers a root with an action token or a
+  lazy shell; a tokenless, client-only root does not re-read. On the split
+  client the stream's render waits for the module the content needs, as it
+  already did for an incoming root, so the content lands wired; the wait is
+  capped at 1 s, after which Turbo renders and the root connects the module
+  when it arrives. A draft
+  restore no longer marks fields `data-reactive-dirty` on a root that never
+  opted into dirty tracking (one that only gates a paste trigger).
+- **An editable is editable in an engine without `contenteditable="plaintext-only"`,
+  however it reaches the page (#355).** Such an engine reads the server's
+  `plaintext-only` as invalid, so the element cannot even be focused. The
+  bindings feature switched it to `"true"` only when it connected, or after a
+  morph of the root, which left an editable that a stream appended, a frame
+  loaded or an unfocused morph rewrote uneditable. The runtime now does the
+  switch with one observer, installed only in such an engine (elsewhere the
+  probe is all that runs). Bundle: default +157 B gzip, split core +241 B,
+  `features/bindings` -138 B.
+
 - **A `checked:`-only `reactive_show_targets` entry hides at zero boxes
   (#348).** `"#bulk-bar" => { if: { "ids[]" => { checked: 1.. } } }` was left
   visible once the owning root held no box of the group (the last ticked row

data/README.md

@@ -118,7 +118,7 @@ instead, import `phlex/reactive/early` eagerly (the engine pins it with
 import "phlex/reactive/early"
 ```
 
-It gzips to under 1.3 KB and has no Stimulus import. A trigger (`on(...)` or
+It gzips to under 1.5 KB and has no Stimulus import. A trigger (`on(...)` or
 `on_client(...)`) that fires before the controller connects — a click while a
 lazily loaded controller is still downloading, a custom event dispatched as soon
 as the page is interactive — is queued, its native default is stopped exactly
@@ -162,6 +162,11 @@ Good to know:
   root until it disconnects — keep its trigger element stable across replies
   (a reply that morphs the root but swaps that element leaves the hotkey
   dead until the next disconnect), or bind the hotkey without `once:`.
+- A `shortcut:` (below) is the exception to "never prevented": the chord the
+  page claims is prevented before connect too (so `mod+s` cannot open the
+  browser's save dialog in the first moments), and a chord pressed inside a
+  field the user is typing in, or the other platform's `mod` twin, is neither
+  queued nor prevented.
 - Not captured, so still lost before connect: `outside:` triggers (an outside
   click before connect has nothing to close, and recording it would wake a
   dormant dropdown on every click); key filters beyond Stimulus's default key
@@ -288,14 +293,15 @@ imports one the first time a root on the page needs it:
 
 | Module | Gzipped | Default client | Split client |
 |---|---:|---|---|
-| `phlex/reactive/reactive_controller` | 26.1 KB | loaded with your controllers | not loaded |
-| `phlex/reactive/core` | 12.4 KB | not loaded (it is inside the file above) | loaded with your controllers |
+| `phlex/reactive/reactive_controller` | 28.9 KB | loaded with your controllers | not loaded |
+| `phlex/reactive/core` | 13.5 KB | not loaded (it is inside the file above) | loaded with your controllers |
 | `phlex/reactive/features/persist` (`reactive_persist` drafts) | 3.2 KB | inside the one file | fetched when a root declares `reactive_persist`, or a `persist_state` / `persist_clear` op runs |
 | `phlex/reactive/features/defer` (`reply.defer`, `reactive_lazy`) | 2.8 KB | inside the one file | fetched when a root is a `reactive_lazy` shell, a morph turns one into a shell, or a `reply.defer` arrives |
 | `phlex/reactive/features/form` (dirty tracking, `warn_unsaved`, the paste-trigger gate) | 1.0 KB | inside the one file | fetched when a root tracks dirty fields or holds a `paste_into` trigger |
 | `phlex/reactive/features/effects` (`reactive_effects`, `dismiss_after`) | 1.7 KB | inside the one file | fetched when a root declares an effect, or when the first stream that needs it arrives: one with an effect, or with a dismissing flash |
 | `phlex/reactive/features/bindings` (`reactive_show`, show targets, `reactive_on_complete`, `reactive_filter`, `reactive_tags`, nested rows, the conditional `confirm:`) | 5.4 KB | inside the one file | fetched when a root declares one of them, or holds a trigger with a conditional confirm |
 | `phlex/reactive/features/compute` (`reactive_compute`, `reactive_text`) | 2.1 KB | inside the one file | fetched when a root carries a compute binding |
+| `phlex/reactive/features/sortable` (`reactive_sortable` drag and drop) | 3.1 KB | inside the one file | fetched when a root is or holds a sortable or source list |
 | `phlex/reactive/features/hints` (`optimistic:`, `busy:`) | 1.0 KB | inside the one file | fetched when a root holds a trigger that declares a hint |
 | `phlex/reactive/features/devtools` (the latency simulator, the zero-target warnings, the debug trace) | 1.6 KB | inside the one file | fetched with the core on a page that carries `<meta name="phlex-reactive-env" content="development">` or while a delay is stored for the tab; at connect for a root in debug mode; otherwise the first time a verbose root has something to warn about. In production with none of these, never |
 | `phlex/reactive/early` | 1.2 KB | on every page, if you import it | the same |
@@ -680,6 +686,7 @@ Use in controllers: `render turbo_stream: Counter.replace(counter)`.
 | `on_client(:click, js.toggle("#menu"))` | **Client-only** trigger: applies declared DOM ops with ZERO round trip — no token, no POST, ever. Takes the same `window:`/`once:`/`outside:` modifiers, plus `detail:` (run only when `event.detail` carries the listed values). See [Client-only ops](#client-only-ops-on_client--js--zero-round-trips). |
 | `js` | The immutable op builder behind `on_client`: `show`/`hide`/`toggle` (the `hidden` attribute, with an optional `transition:` and `expanded:`), `add_class`/`remove_class`/`toggle_class`, `set_attr`/`remove_attr`/`toggle_attr` (allowlisted names; `toggle_attr` also flips between two values), `focus`/`focus_first`, `text` (set `textContent` — XSS-safe), `dispatch`, `submit` (requestSubmit the target's own form, optionally through a `submitter:`), `paste_into` (read the clipboard into a field, gesture-gated), `check_group` (tick or untick a checkbox group, then re-sync its bindings), and `persist_state`/`persist_clear` (the `reactive_persist` draft) — chainable. |
 | `reactive_field(:param, **attrs)` | The attribute hash that binds a control to an action param (no magic `name:`) — spread onto any control: `input(**reactive_field(:value, value: @record.name))`, `select(**reactive_field(:status)) { … }`. |
+| `reactive_editable(:name, multiline: false, placeholder: nil, on_enter: nil, on_escape: :revert, spellcheck: true)` | A plain-text **editable element** as a field (issue #351): `h3(**reactive_editable(:title)) { @card.title }`. Its text travels under the scope-aware `name`: with `multiline: true` its line breaks are sent as `\n`; a single-line field (the default) folds them to spaces; a morph keeps the focused element's text and caret (attributes still morph); paste is plain text; Enter runs `on_enter:` (a single-line field swallows it); Escape reverts. `reactive_dirty` and `reactive_persist` treat it like an input. See the [Editable text](https://phlex-reactive.zoolutions.llc/docs/editable-text) page. |
 | `reactive_text(:name, initial)` | Mirror a compute output (or a declared input) into a **text node** — a live preview heading, a character counter, `"Hello, {name}"` — via `textContent` (XSS-safe). The text sibling of `reactive_field`; carries no `name`, so it's never POSTed. See [Client-side computes](#client-side-computes-reactive_compute--reactive_text). |
 | `reactive_show(if:/if_any:/unless:)` | **Value-conditional visibility** (the `x-show`/`data-show` case): spread onto the element to show/hide — it toggles `hidden` from the fields' **current values**, client-only, zero round trip. One conditions language: a **Hash is an AND**, an **Array is membership**, a **Range is a threshold**, `if_any:` is OR-of-AND, `unless:` negates. `reactive_values` computes first paint; `disable:` disables a hidden section's controls. See [Value-conditional visibility](#value-conditional-visibility-reactive_show). |
 | `reactive_enable(if:/if_any:/unless:)` | The sibling of `reactive_show` that flips the element's **own `disabled`** (a button, a fieldset) instead of `hidden` — same conditions, same `reactive_values` first paint. `button(**reactive_enable(if: { "ids[]" => { checked: 1.. } }))`. See [Bulk selection](#bulk-selection-reactive_select_all-reactive_count-reactive_enable). |
@@ -934,6 +941,46 @@ div(**mix(reactive_root, on(:track, event: "scroll", window: true, throttle: 500
 These four (like `debounce:`/`confirm:`/`listnav:`) are **reserved keyword
 names** on `on(...)` — no longer usable as free action params.
 
+**Page-level shortcuts — `shortcut:`.** Undo, redo, save and a command palette
+bind with one keyword on `on(...)` or `on_client(:keydown, …)`:
+
+```ruby
+div(**mix(reactive_root, on_client(:keydown, js.toggle("#palette"), shortcut: "mod+k"))) do
+  span(**on(:undo, shortcut: "mod+z"))         # one reactive action per element
+  span(**on(:redo, shortcut: "mod+shift+z"))
+  textarea(name: "notes")
+end
+```
+
+A shortcut is a window `keydown` binding with three rules a plain
+`event: "keydown.meta+z", window: true` does not have:
+
+- **`mod` is ⌘ on Apple platforms and Ctrl elsewhere.** The helper renders a
+  meta twin and a ctrl twin; the client runs the one for its platform (from
+  `navigator.userAgentData.platform`, else `navigator.platform`), and the other
+  is a complete no-op, so Ctrl+Z on a Mac stays the browser's. A chord without
+  `mod` (`"esc"`, `"alt+n"`) renders one descriptor.
+- **Typing is left alone.** With focus in an `input`, `textarea`, `select` or
+  anything `contenteditable` (including `reactive_editable`), the shortcut does
+  nothing and the browser's own handling (text undo) runs. Opt in with the Hash
+  form: `shortcut: { keys: "esc", in_editable: true }`.
+- **The chord is prevented.** A matching shortcut calls `preventDefault`
+  synchronously, before any `confirm:` dialog, so `mod+s` does not also open
+  the save dialog. (Other window bindings are still never prevented.)
+
+`shortcut:` decides the event and the window binding: passing it with
+`event:`, `window:` or `outside:` raises `ArgumentError`, as does a key outside
+Stimulus's default key map (a letter, a digit, `enter`, `tab`, `esc`, `space`,
+the arrows, `home`, `end`, `page_up`, `page_down`; bind a custom `keyMappings`
+key with `event:` and `window:`). On `on_client` the event must be `:keydown`.
+`shortcut` is now a **reserved keyword** on `on(...)`.
+
+`once: true` on a shortcut unbinds the Stimulus descriptor after its first
+firing, and a press inside a field counts: the guard leaves the chord to the
+browser, but the `:once` listener is already spent. Keep `once:` off a
+shortcut that can be pressed while the user types, or pair it with
+`in_editable: true`.
+
 ### Optimistic visual hints (`optimistic:`)
 
 Every reactive action waits a full round trip for its visual change — and it's
@@ -1139,8 +1186,9 @@ string is legacy and ignored), and `turbo:before-visit` **does not fire on
 restoration visits** (Back/Forward) — a documented Turbo gap, not a
 phlex-reactive one.
 
-**Out of scope (v1):** rich-text / `contenteditable` editors have no `default*`
-baseline and are **not** tracked. Combining `reactive_field` with your own
+**Out of scope (v1):** rich-text editors (Lexxy, Trix) and bare
+`contenteditable` elements have no `default*` baseline and are **not** tracked;
+a `reactive_editable` is (against the text of its last server render, #351). Combining `reactive_field` with your own
 `data:`/`on(...)` still needs `mix(...)` (a bare merge clobbers the `data-action`
 the descriptor rides on — the same rule as everywhere else).
 
@@ -1402,6 +1450,11 @@ free as an ordinary action-param name (`on(:switch, key: "pgbus")` still passes
 > trigger to its own element (the field saves on Enter; a Cancel button — or the
 > field's own blur — handles Escape), as above.
 
+A page-level chord (undo on ⌘Z/Ctrl+Z, save on `mod+s`) is a `shortcut:`
+rather than `event:` with `window: true`: it resolves `mod` per platform,
+leaves fields the user is typing in alone and prevents the chord (see
+*Page-level shortcuts* above).
+
 ### Value-conditional visibility (`reactive_show`)
 
 `on_client` covers the *unconditional* client-only interactions; the last gap
@@ -1635,6 +1688,206 @@ button(id: "bulk-archive", **reactive_group_target_attrs("ids[]", :enable, 1..))
   `(group, :enable, condition)` is `{ disabled: }` (or `{}` when
   `reactive_values` does not cover the group, and the client seeds it).
 
+### Sortable lists (`reactive_sortable`)
+
+Drag rows to reorder a list — with a mouse, a finger or the keyboard — and one
+declared action receives the row and where it landed. No Stimulus controller,
+no endpoint of your own: the drop goes through the action pipeline (signed
+token, request queue, `busy:`, the reply).
+
+```ruby
+class TaskList < Phlex::HTML
+  include Phlex::Reactive::Component
+
+  reactive_record :list
+  action :move, params: { item: :integer, position: :integer }
+
+  def move(item:, position:)
+    authorize! @list, :update?
+    # insert_at is acts_as_list's; any reorder that honours `position` works.
+    @list.tasks.find(item).insert_at(position + 1)
+    reply.morph
+  end
+
+  def view_template
+    ul(**mix(reactive_root, reactive_sortable(:move, handle: "[data-drag-handle]"))) do
+      @list.tasks.each do |task|
+        li(id: dom_id(task), **reactive_sortable_item(task.id)) do
+          span(data: { drag_handle: true }) { "⠿" }
+          plain task.title
+        end
+      end
+    end
+  end
+end
+```
+
+On drop the action gets `item` (the row's key), `position` (its 0-based index
+after the drop), `after` (the key of the row it now follows, `nil` when first)
+and `from` (`"self"` for a reorder) — declare the ones you want. The row moves
+at once and goes back if the action fails or its reply does not render the
+list; a reply that morphs the list puts the rows in the server's order.
+
+- **Drag in from another list**: `reactive_sortable_source(group:, name:)` rows
+  are copied into any sortable of the same group (the source needs no token —
+  it works on a `ClientBindings` root). Route a drag-in to its own action with
+  `from: { templates: :insert }`. Source rows are pointer-only: pass
+  `tabindex: -1` (via `mix`) so they stay out of the tab order.
+- **Between lists** (a kanban): sortables of one `group:` exchange rows; `name:`
+  is what a row dragged out reports as `from`, and static `params:` (e.g.
+  `{ lane: "doing" }`) tell the action which list it landed in.
+- **Keyboard**: a row is focusable; Space/Enter picks it up, the arrows move it
+  (← → into the previous/next list of the group), Space/Enter drops it,
+  Escape puts it back. Each step is announced through a live region; translate
+  the words with `messages:` (`{position}`, `{count}`).
+- **Styling**: `data-reactive-sortable-active` (the list), `-dragging` (the
+  row) and `-placeholder` (the gap) are yours to style.
+- **Guards**: `disabled: true` on the list or a row, and a request in flight on
+  the root, refuse a drag. A drag starts after a 4 px move, or a 200 ms touch
+  press, so clicks, taps and scrolling still work.
+
+Full guide: [Sortable lists](https://phlex-reactive.zoolutions.llc/docs/sortable-lists).
+
+### Presence (`reactive_presence`)
+
+Who is viewing a stream, one entry per browser tab, each tab with a small
+declared state (the item it has selected), on a roster component that
+re-renders itself in every viewer's tab when a tab joins, leaves, goes silent
+or changes its state. No controller code, no Stimulus controller.
+
+```ruby
+class Boards::Viewers < Phlex::HTML
+  include Phlex::Reactive::Component
+
+  reactive_record :board
+  reactive_presence :viewers, state: { selected: :integer }, ttl: 45
+
+  def initialize(board:) = @board = board
+
+  def view_template
+    div(**reactive_root) do
+      presence.members.each do |member|                 # one per person
+        span(**reactive_presence_member(member)) { member.metadata["name"] }
+      end
+      @board.cards.each do |card|
+        li(**on_client(:click, js.presence(selected: card.id))) do
+          plain card.title
+          presence.where(selected: card.id).each do |peer| # who is on this card
+            span(**reactive_presence_peer(peer), class: "dot")
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+- **The stream** is `[record, :presence, name]` (a record-less roster passes
+  `key: ["lobby"]`), named `"<16-char digest of the record (or the key: value)>:presence:<name>"`,
+  so any model name and id fit pgbus's stream-name budget (41 chars with the
+  default queue prefix). That leaves 15 characters for the presence name; a
+  longer one raises `Phlex::Reactive::ConfigurationError` at render. The root
+  subscribes to it by itself: the client mints a
+  `<pgbus-stream-source>` from the root's signed src, so the page must load the
+  pgbus client element (`import "pgbus/stream_source_element"`, which any
+  `pgbus_stream_from` on the page already does).
+- **`presence`** is the roster as this render reads it: `peers` (one per tab:
+  `seat`, `member_id`, `metadata`, `state`, `joined_at`), `members` (grouped by
+  person: `id`, `metadata`, `seats`, `state`), `where(**state)`, `count`,
+  `empty?`, and in an action `me` and `set(**state)`.
+- **State** is declared like action params; undeclared keys are dropped.
+  `js.presence(selected: 7)` sends it from the browser through the generated
+  `presence_set` action; `presence.set(selected: 7)` writes it from an action of
+  your own. Either way only this tab's row changes and the other viewers get a
+  morph. The generated action replies `reply.morph` for the actor; an action of
+  your own must return `reply.morph` itself.
+- **A state-backed roster** (`reactive_state`): its state is stored on each
+  seat row in `pgbus_presence_members` (in the note the re-render reads), and
+  the roster renders as one piece of markup under one id for every viewer. So
+  its `reactive_state` must be the same for every viewer; per-viewer state
+  belongs in presence state (`state:`).
+- **Authorization**: `presence_set` skips `verify_authorized`. The signed token
+  proves the actor rendered this root, and the write is typed, ephemeral, and
+  lands only on the actor's own row, keyed by its SSE connection id, which
+  only that tab knows. To check the value (the card must belong to the board),
+  define `authorize_presence_state!(**state)` and raise; it runs first. That hook
+  guards only the generated `presence_set`: an action of your own that calls
+  `presence.set` authorizes its state itself. The client also sends `presence_set` with no state on every connect (the
+  announce): that writes no value, so the hook is not called for it.
+- **`presence.me`** is the acting tab, and during an action it stays the actor
+  while the roster renders for the other viewers too. Never branch the shared
+  output on it; the client's `-me` marks are per tab. (Likewise
+  `reactive_connection_id` is the first `<pgbus-stream-source>` on the page, so
+  one loaded later, ahead of it in the DOM, can change it; presence writes use
+  their own connection and are unaffected.)
+- **"Me"**: the roster renders once for everyone, so the client marks this
+  tab's element `data-reactive-presence-me` and the same person's other
+  elements `data-reactive-presence-same-member` after every morph. Style them.
+  Both need this tab's `reactive_presence_peer` element on the roster: a roster
+  of members only has none, so nothing is marked.
+- **Events**: `reactive:presence` fires on the root with
+  `{ joined: [seat…], left: [seat…], me: seat }` when a morph changes who is
+  there; a replayed frame that changes nothing fires nothing. The root names
+  the seats its render saw (`data-reactive-presence-roster`), so this works for
+  a roster that renders people, not tabs.
+- **Leaving**: a closed tab leaves within about a second (pgbus watches each
+  SSE socket for the browser closing it). A tab that crashes or loses its
+  network, so nothing closes the socket cleanly, leaves on the next failed
+  heartbeat write (`streams_heartbeat_interval`, 15 s by default) or expires
+  after `ttl:` seconds. A reconnect keeps the tab's seat id and re-sends its
+  state, but pgbus drops the row on the disconnect, so unless the reconnect
+  lands within one coalesce window (150 ms) peers see that seat leave and
+  join again (`reactive:presence` reports both). A row that expires while its
+  socket stays open (the tab missed its beats) is re-joined by the heartbeat
+  without its state, until the tab's next `js.presence`. `ttl:` must be above the
+  transport's heartbeat interval, or a live tab would expire between two
+  beats: `reactive_presence` raises otherwise.
+- **Transport**: needs pgbus 0.18.1 or later (presence keyed by SSE
+  connection, `pgbus:connected` only after the tab's seat joined,
+  `config.streams_authorize`). Create the table with
+  `rails g pgbus:add_presence`, or upgrade an older one with
+  `rails g pgbus:add_presence_seats`. `ttl:` (45 by default) is written into
+  pgbus's `streams_presence_ttl` under the stream's pattern. Action Cable has
+  no connection identity: rendering a presence root without it raises
+  `Phlex::Reactive::ConfigurationError`. Every other component is unaffected.
+- **Identity**: pgbus takes each tab's person from what
+  `config.streams_authorize` returns for the stream. `nil` or `false` answers
+  403; `true` authorizes with no identity, and pgbus joins such a connection
+  to no roster (the tab then warns in the console that it never appeared).
+  Per-record authorization already happens at render: the signed src is
+  minted only into a roster root your app chose to render for this user.
+  `streams_authorize` is the revocation layer (the signed name proves pgbus
+  minted it, not that this viewer may still read it: a removed member keeps a
+  working name until the secret rotates). For a strict per-record check at
+  connect time, compare `stream_name` with the presence key of each record the
+  user may view (or give a record-less roster a `key:` with a prefix you can
+  parse):
+
+  ```ruby
+  # config/initializers/pgbus.rb
+  Pgbus.configure do |config|
+    config.streams_authorize = ->(env, stream_name) {
+      user = env["warden"]&.user
+      next unless user&.active?
+      next unless user.may_stream?(stream_name) # keep your app's own check for every stream
+
+      if stream_name.end_with?(":presence:viewers")
+        next unless user.boards.any? { Boards::Viewers.reactive_presence_stream_name_for(it) == stream_name }
+      end
+      { id: user.id, metadata: { name: user.name } }
+    }
+  end
+  ```
+
+  A presence stream's name is a digest (`"<16 hex>:presence:<name>"`), so the
+  record cannot be read back from it: `reactive_presence_stream_name_for`
+  computes it from the record. A User works too (pgbus reads its `#id`); shape
+  the member from it with
+  `config.streams_presence_member = ->(user) { { id: user.id, metadata: { name: user.name } } }`.
+- **Jobs**: a join, a leave and an expiry re-render the roster in
+  `Phlex::Reactive::PresenceRenderJob` (on `defer_job_queue`), so the app needs
+  an ActiveJob adapter that runs jobs. A state change renders in the action.
+
 ### Client-only drafts (`reactive_persist`)
 
 "Don't make me start over": a public application form, a multi-step wizard,

data/app/controllers/phlex/reactive/actions_controller.rb

@@ -347,24 +347,34 @@ module Phlex
       # Phlex::Reactive::Response survives to response_streams.
       def run_action(component, action_def, coerced)
         Phlex::Reactive.with_connection_id(request.headers["X-Pgbus-Connection"]) do
-          with_around_actions(component, action_def, coerced) do
-            transaction_wrapper do
-              # verify_authorized (issue #168): open the tracking window, run the
-              # action, then verify INSIDE the transaction so an unverified action
-              # rolls its mutation back (fail-closed). with_tracking is a bare
-              # yield's-worth of overhead; verify! is a no-op when the feature is
-              # off / the action is skipped / something marked. The interceptor
-              # (create_action's instrument!) marks the window on a real
-              # authorization call.
-              Phlex::Reactive::Authorization.with_tracking do
-                result = if coerced.any?
-                           component.public_send(action_def.name, **coerced)
-                         else
-                           component.public_send(action_def.name)
-                         end
-                Phlex::Reactive::Authorization.verify!(component.class, action_def)
-                result
-              end
+          # Issue #358: a presence root also sends its presence connection, the
+          # row a presence write lands on.
+          Phlex::Reactive::Presence.with_connection_id(request.headers[Phlex::Reactive::Presence::HEADER]) do
+            run_action_wrapped(component, action_def, coerced)
+          end
+        end
+      end
+
+      # The action inside the around_action stack, the transaction and the
+      # verify_authorized window (see run_action).
+      def run_action_wrapped(component, action_def, coerced)
+        with_around_actions(component, action_def, coerced) do
+          transaction_wrapper do
+            # verify_authorized (issue #168): open the tracking window, run the
+            # action, then verify INSIDE the transaction so an unverified action
+            # rolls its mutation back (fail-closed). with_tracking is a bare
+            # yield's-worth of overhead; verify! is a no-op when the feature is
+            # off / the action is skipped / something marked. The interceptor
+            # (create_action's instrument!) marks the window on a real
+            # authorization call.
+            Phlex::Reactive::Authorization.with_tracking do
+              result = if coerced.any?
+                         component.public_send(action_def.name, **coerced)
+                       else
+                         component.public_send(action_def.name)
+                       end
+              Phlex::Reactive::Authorization.verify!(component.class, action_def)
+              result
             end
           end
         end

data/app/javascript/phlex/reactive/core.js

@@ -26,6 +26,8 @@ registerReactiveFeatureLoader("defer", () => import("phlex/reactive/features/def
 registerReactiveFeatureLoader("form", () => import("phlex/reactive/features/form"))
 registerReactiveFeatureLoader("bindings", () => import("phlex/reactive/features/bindings"))
 registerReactiveFeatureLoader("compute", () => import("phlex/reactive/features/compute"), waitingForEdit)
+registerReactiveFeatureLoader("sortable", () => import("phlex/reactive/features/sortable"))
+registerReactiveFeatureLoader("presence", () => import("phlex/reactive/features/presence"))
 registerReactiveFeatureLoader("effects", () => import("phlex/reactive/features/effects"))
 registerReactiveFeatureLoader("hints", () => import("phlex/reactive/features/hints"))
 registerReactiveFeatureLoader("devtools", () => import("phlex/reactive/features/devtools"))
@@ -144,7 +146,10 @@ onReactiveStreamWithoutEffects((event, loadedEffects) => {
 })
 
 // The reactive roots a stream is about to put on the page: the roots in its
-// template (the template's own root element included).
+// template (the template's own root element included), and the content
+// itself — read as part of the root already on the page it renders into,
+// which re-reads its markers once the render has run (issue #356; an editable
+// it brings, #351). Held for the module, the new content lands wired.
 function incomingRoots(streamEl) {
   const content = streamEl?.querySelector?.("template")?.content
   if (!content) return []
@@ -152,6 +157,7 @@ function incomingRoots(streamEl) {
   for (const child of content.children ?? []) {
     if (child.matches?.('[data-controller~="reactive"]') && !roots.includes(child)) roots.unshift(child)
   }
+  roots.push(content)
   return roots
 }