hibiki_rails 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb224598ce236ad6d2f55b9648fbcb4644a478e1c86db2839dc3648207cd0605
-  data.tar.gz: 2c4c73dbc34338aca84fde08bf520e47dcc5920a7e4a6403ce9b4ee6d7ec62b6
+  metadata.gz: b661448cbe2b84a20e26f5cd0bffaf2cf7be8c755f0f1b9c692f77e9f5798430
+  data.tar.gz: b09c3b35032a6990ab08c17e424a147e9e667905a4f9e9378062d52583e213d6
 SHA512:
-  metadata.gz: 5cace159e074313892f3736f5bed6220e1852fc71d85ee5b063af80c31471662f492d945ad57b5589543b54f43d2f4bac3dce3fdf8718fc0b8b1df18d0f5e756
-  data.tar.gz: 99a518942cc899684e94951d88fea9a08524c83327ae61cc5a924356b16485b33a14cc51fc9fcac3d8dc67d71f96c41ef5f8915d0b97349bc4ed0f74db3de556
+  metadata.gz: dc4013a0867b606341dd9af0135a82ab9e5a8c6b5f5cabd788eea48e0f3b604a708d31aa21c044f8639a5f2951242986b710d893b968246d03703359d562235b
+  data.tar.gz: d407a4c966366e5b11d9db6eaf7e789dcd4e086ca028dad0b2bc9b69bc4ec8f6b110339e338894b51851aa8ace18f08ef2339ce9198cf7a9226dc48d11b8c592

data/CHANGELOG.md

@@ -4,6 +4,144 @@ The gem and the npm package are released in lockstep and share these version
 numbers — `app/assets/javascripts/hibiki.js` is a single copy served both ways,
 so importmap and bundler apps always resolve identical client code.
 
+## 0.9.0 — 2026-08-17
+
+### Added
+
+**`reactive_nested` — nested forms over `accepts_nested_attributes_for`.**
+`reactive_nested :credits, "CreditForm"` on a ReactiveForm declares a signal
+holding an array of child forms; the child class may itself declare
+`reactive_nested`, so depth is composition — nothing counts levels. `#to_h`
+serializes the tree as recursive `*_attributes` (with `id:` and `_destroy:`),
+so `#commit` persists everything in the record's one save; a failed commit
+distributes each child record's errors onto the matching child form, and
+`dirty?` tracks child edits, adds, removes, and destroy-marks for free. New
+instance API: `nested_add` / `nested_remove` (a persisted child is marked
+`_destroy`, a new one leaves the array), `nested_key` (`"c<id>"` / `"n<seq>"`
+— stable DOM identity across repaints), `mark_for_destruction`. The form
+also unloads its nested associations after every commit attempt: a failed
+save leaves AR-built children in the in-memory association, and without the
+unload a later success would insert them twice.
+
+**`Hibiki::Rails::NestedActions` — generic channel actions for nested
+forms.** Opt-in include next to `Hibiki::Rails::Channel`: `nested_add`,
+`nested_remove`, `nested_move` (reorder to an index among visible
+siblings — with position stamped from array order, up/down controls are
+all a reorderable list needs), and `nested_set_field`, addressing any node by a
+`dom` + `path` payload (`"credits/c3/contributions/n1"` — association names
+alternating with child keys, any depth). Every hop is gated against the form
+classes' declarations, keys against live children, fields against
+`hibiki_attributes`. The default form resolver understands the scaffold's
+`@form`/`@editing_id` and `@new_form`/`@creating` ivars; override the private
+`nested_form_for(dom)` for anything else. No client change — nested controls
+name themselves `"#{path}/#{field}"` and ride the existing payload mechanics.
+
+**`hibiki:rails:nested` — generate one parent→child edge of a nested form.**
+`bin/rails g hibiki:rails:nested Song Credit`, then `... Credit Contribution`
+for the next level — depth is composition, each run wires one edge. The child
+model must exist and `belongs_to` the parent; attribute arguments only
+reorder or subset what the schema already knows. Emits the child ReactiveForm
+and a `_<child>_fields` partial (or Phlex component) with path-addressed
+inputs, injects the ordered `has_many` + `accepts_nested_attributes_for`,
+`reactive_nested`, the `NestedActions` include, preloads, and the classic
+`fields_for` + `params.expect` degraded path into the full-page form. A
+`position` column is detected for ordering (`--position=COLUMN` names one,
+adding the migration; `--skip-position` opts out) and ordered edges get
+up/down controls. Works against a scaffolded collection (root mode) or an
+already-nested parent's fields partial (deep mode), on both view layers.
+
+**`perform(action, payload)` is public API — and a `performOn` helper.**
+The blessed seam for app JS (a drag library's drop handler, any third-party
+widget) to fire actions on an island's graph through the island's OWN
+subscription. Reach the controller instance with Stimulus's standard
+`application.getControllerForElementAndIdentifier(islandEl, "hibiki")`, or
+skip the incantation with the new export — `performOn(element, action,
+payload)` finds the island containing `element` and performs through it,
+Stimulus context not required. The return value is the contract: truthy (the
+trip's sequence number) means the action was accepted — sent live, or queued
+during the island's initial connect window — and a repaint is coming, so
+leave the DOM as the user arranged it; `undefined` means it was dropped (the
+island is offline, the socket turned out to be dead, or no island contains
+the element) and the caller owns recovery: revert the gesture, or stand back
+and let the next repaint self-heal. Nothing queues across an offline gap, on
+purpose — a reconnect builds a fresh server-side graph, and replaying intent
+formed against the old one is worse than dropping it. Hand-writing
+`data-hibiki-*` attributes and subclassing `ChannelController` to reach an
+existing island remain unsupported: the attributes are a private contract,
+and a subclass opens a second subscription with a second graph nobody paints
+from.
+
+### Fixed
+
+**`perform` during an offline gap reported success while dropping the
+payload.** Between a socket drop and the reconnect, `perform` returned the
+trip's sequence number as if the action had been accepted, while sending
+nothing and queueing nothing. Declared actions never noticed (the fallback
+machinery gates on island state before performing), but with the return
+value now public API the lie mattered: it returns `undefined` there, the
+same dropped signal as a dead socket caught at send.
+
+## 0.8.0 — 2026-08-15
+
+### Added
+
+**`on(..., fallback: true)` — progressive enhancement over native controls.**
+A control's native behavior — a link's href, a form's `action=` — is its
+degraded path. Only a `ready` island intercepts the gesture and performs the
+channel action; while connecting, offline, or stalled the client stands aside
+entirely and the browser does what the markup says. A dead-but-undetected
+socket is caught too: when the subscription reports the send failed, the
+client settles the trip and runs the native behavior by hand
+(`form.submit()` / `location.assign`) — the gesture never left, so it cannot
+double-fire. Two guarantees ride along: `confirm:` still gates the native
+path while scripts run (a destructive submit must not slip past the dialog
+just because the island is down), and before any native submit the client
+freshens the form's `authenticity_token` from the `csrf-token` meta tag —
+forms repainted by a channel are rendered without a session and carry no
+token, so freshening is load-bearing, not an edge case. A truly script-free
+page still holds its first-paint token and needs no help.
+
+**`transmit_url` — mirror graph state into the address bar.**
+`transmit_value`'s URL sibling: an equality-gated effect transmits `{ url: }`
+and the client `history.replaceState`s the bar to it. Never `pushState` — the
+URL is a mirror of graph state, not a history entry, so there is no popstate
+choreography and Back leaves the page normally. Same-origin only; the client
+resolves the URL against the page's own origin and refuses anything else.
+
+**The scaffold now generates the whole degraded-path pattern.** The query
+object grows a URL half — `from_params` and canonical `url_params` (defaults
+omitted) — shared by the controller's first paint, the island's
+subscribe-params seeding (the graph starts from the URL's state, so its first
+broadcast repaints what the server painted instead of resetting to defaults),
+the pagination hrefs, and the channel's `transmit_url`, which also mirrors an
+open form's URL so a reload mid-edit lands on the standard edit page. The
+controls become one GET form to the index: live, the controls fire channel
+actions; dead, Enter, Apply, and the direction button submit natively and
+`from_params` answers. Edit is a real link to the edit page, Destroy a real
+`button_to` DELETE form, and the page control's links carry real hrefs — all
+with `fallback: true`, in both view layers and every css variant.
+
+**The scaffold's list gains an inline create form, on by default.** The New
+link (now inside the island) opens a channel-owned create form at the top of
+the list — its own `ReactiveForm` instance, so an open row edit and an open
+create never fight over state — and degrades to the standard new page. The
+shared row form is parameterized (`dom:`, `save_action:`, `cancel_action:`,
+`field_action:`, `cancel_with:`) and serves both uses; `--skip-create` omits
+the whole surface. Generated forms also gate live validation on `dirty?`, so
+a freshly opened form paints clean instead of flagging every blank field.
+
+**`hibiki:rails:multiselect` serves the inline create form too.** The
+dropdown appears with the full option list and an empty selection; each
+checkbox's toggle names the form it belongs to, so an open row edit and the
+create form never cross-write, even side by side.
+
+### Changed
+
+**Re-running the scaffold over a pre-0.8.0 app refreshes a same-styled shared
+page control in place** — the regenerated list passes the new `url:` local,
+which the old shared partial does not declare. A page control written under a
+different `--css` style is still kept and noticed, never restyled.
+
 ## 0.7.0 — 2026-08-12
 
 ### Added

data/app/assets/javascripts/hibiki.js

@@ -52,6 +52,11 @@
 //                 data-hibiki-debounce="250"           ms to let the gesture settle
 //                 data-hibiki-confirm="Are you sure?"  window.confirm gate
 //                 data-hibiki-reset="false"            keep a submitted form's inputs
+//                 data-hibiki-fallback="true"          the control's native behavior
+//                 (a link's navigation, a form's action=) is its fallback: while the
+//                 island is `ready` the event is intercepted and only the channel
+//                 action fires; in every other state the client stands aside and the
+//                 browser does what the markup says
 //   value sites   data-hibiki-value="<name>"           reactive-value placeholder;
 //                 the server's transmit_value message updates every match
 //
@@ -75,6 +80,36 @@
 // element entering the viewport). Everything that is not "which event"
 // is a sibling attribute, so the token grammar never has to grow.
 //
+// App JS reaching the graph — the ONE public seam. A gesture that needs
+// script (drag-and-drop, a third-party widget) fires its action through
+// the island's OWN subscription: `perform(action, payload)` on the island
+// controller instance is public API. Reach the instance with Stimulus's
+// standard lookup —
+//
+//   const islandEl = element.closest('[data-controller~="hibiki"]')
+//   const island = application.getControllerForElementAndIdentifier(islandEl, "hibiki")
+//   island?.perform("nested_move", { path, to })
+//
+// — or skip the incantation with the performOn export at the bottom of
+// this file (works outside Stimulus too):
+//
+//   import { performOn } from "hibiki-rails"
+//   performOn(element, "nested_move", { path, to })
+//
+// The return value is the whole contract: truthy (the trip's seq) means
+// the action was ACCEPTED — sent live, or queued during the initial
+// connect window — so a repaint is coming and the caller should leave the
+// DOM as the user arranged it (the morph lands as a visual no-op). Falsy
+// (undefined) means it was DROPPED — the island is offline, or the socket
+// turned out to be dead at send — and the caller owns recovery: revert
+// the gesture, or stand back and let the next repaint self-heal. Nothing
+// queues across an offline gap on purpose (a reconnect builds a fresh
+// server-side graph, so replayed intent would land on state it was not
+// formed against). Everything else is NOT a seam: the data-hibiki-*
+// attributes are private, and subclassing ChannelController to reach an
+// existing island opens a SECOND subscription — a second server-side
+// graph nobody paints from.
+//
 // Register the generic controller under the identifier "hibiki" (the
 // helpers hardcode it):
 //
@@ -88,6 +123,13 @@ import { createConsumer } from "@rails/actioncable"
 // and go with the DOM, the socket stays.
 let consumer
 
+// Live islands by root element, for performOn's ancestor walk — membership
+// here, not an attribute probe, so the helper couples to neither the
+// identifier string nor the wire attributes. Generic islands only:
+// ChannelController subclasses have `this.perform`. WeakMap so a removed
+// island pins nothing even if disconnect never ran.
+const islands = new WeakMap()
+
 // camelCase Stimulus method name → snake_case Ruby channel action.
 const underscore = (name) => name.replace(/([A-Z])/g, "_$1").toLowerCase()
 
@@ -122,6 +164,27 @@ const formPayload = (form) => {
   return payload
 }
 
+// Before a fallback form goes native, re-stamp its CSRF token from the
+// page's csrf-token meta — which is first-paint fresh and session-valid.
+// Server-side repaints render without a session (ApplicationController
+// .render has none), so a repainted form embeds a stale token or none at
+// all; and this only ever runs with scripts alive, which is exactly when
+// the DOM may have been repainted. A truly script-free page still holds
+// its first-paint token and never needed the help.
+const freshenToken = (control) => {
+  if (!(control instanceof HTMLFormElement)) return
+  const meta = document.querySelector('meta[name="csrf-token"]')
+  if (!meta) return
+  let input = control.querySelector('input[name="authenticity_token"]')
+  if (!input) {
+    input = document.createElement("input")
+    input.type = "hidden"
+    input.name = "authenticity_token"
+    control.appendChild(input)
+  }
+  input.value = meta.content
+}
+
 // The subclassable base: one channel subscription per controller element,
 // identified by a per-page-load cid (data-<identifier>-cid-value).
 export class ChannelController extends Controller {
@@ -212,13 +275,28 @@ export class ChannelController extends Controller {
   // ActionCable's own Subscription#perform already writes `action`.)
   //
   // Returns the seq so a caller that knows which control fired can attach
-  // it; nobody has to.
+  // it; nobody has to. Returns undefined instead when the payload went
+  // nowhere: the socket turned out to be closed under a subscription still
+  // believed live, or the island was already offline. Public API on the
+  // island controller (the header's "App JS reaching the graph") — truthy
+  // = accepted, falsy = dropped and the caller owns recovery.
   perform(action, payload = {}) {
     const seq = ++this.seq
     payload.hbk = seq
     if (this.subscribed) {
       this.beginBusy(seq)
-      this.subscription.perform(action, payload)
+      // Action Cable's Subscription#perform returns false when the socket
+      // is not open — the gap between the socket dying and the connection
+      // monitor noticing, during which `subscribed` still says live. The
+      // frame went nowhere: settle rather than letting the trip stall out
+      // at the ceiling, and stamp `offline` now instead of when the
+      // monitor catches up. The monitor still owns reconnecting; its
+      // `connected` callback restores `ready` exactly as after a real gap.
+      if (this.subscription.perform(action, payload) === false) {
+        this.settle(seq)
+        this.linkClosed()
+        return undefined
+      }
       return seq
     }
     // Queue rather than drop while the subscription is still coming up.
@@ -237,8 +315,11 @@ export class ChannelController extends Controller {
     if (!this.connectedOnce) {
       this.beginBusy(seq)
       this.queued.push([action, payload])
+      return seq
     }
-    return seq
+    // The offline gap: dropped, and the return says so — a truthy seq here
+    // would tell a public caller a repaint is coming when none is.
+    return undefined
   }
 
   // ActionCable's `connected`, i.e. the server confirmed the subscription.
@@ -368,7 +449,7 @@ export class ChannelController extends Controller {
     this.received(data)
   }
 
-  // Server → DOM (transmit transport). Two message shapes:
+  // Server → DOM (transmit transport). Three message shapes:
   //
   // { value: { name, text } } — a reactive value (transmit_value): write
   // the text into every [data-hibiki-value=name] placeholder, document-
@@ -376,11 +457,13 @@ export class ChannelController extends Controller {
   // textContent assignment keeps values text-only and preserves each
   // site's own tag/classes, so per-placeholder styling survives updates.
   //
+  // { url } — mirror graph state into the address bar (transmit_url).
+  //
   // { html } — a fragment: swap it in by its root id.
   //
   // Anything else is not ours to interpret. Subclasses may override, but
   // should call super (or handle `value`) to keep reactive values live.
-  received({ html, value }) {
+  received({ html, value, url }) {
     if (value) {
       const selector = `[data-hibiki-value="${CSS.escape(value.name)}"]`
       for (const site of document.querySelectorAll(selector)) {
@@ -388,6 +471,7 @@ export class ChannelController extends Controller {
       }
       return
     }
+    if (url !== undefined) return this.replaceUrl(url)
     if (!html) return
     const template = document.createElement("template")
     template.innerHTML = html
@@ -396,6 +480,17 @@ export class ChannelController extends Controller {
     }
   }
 
+  // replaceState, never pushState: the URL is a mirror of graph state, not
+  // a history entry — Back needs no popstate handling and leaves the page
+  // normally. Same-origin only, so a channel can move the bar solely
+  // within its own app (replaceState would throw on a cross-origin URL;
+  // refusing keeps it silent and intentional).
+  replaceUrl(url) {
+    const resolved = new URL(url, window.location.href)
+    if (resolved.origin !== window.location.origin) return
+    history.replaceState(history.state, "", resolved)
+  }
+
   // `static channel = "..."` wins; otherwise infer Rails-style from the
   // identifier: "counter" → CounterChannel, "my-thing" → MyThingChannel.
   channelName() {
@@ -465,6 +560,7 @@ export default class HibikiController extends ChannelController {
   }
 
   async connect() {
+    islands.set(this.element, this)
     // Before the listeners, not after: a click delegated in the next
     // millisecond reaches perform(), which needs the busy map and the
     // queue to exist. This is also what stamps data-hibiki-state
@@ -528,6 +624,7 @@ export default class HibikiController extends ChannelController {
   }
 
   disconnect() {
+    islands.delete(this.element)
     for (const [type, handler] of this.listeners) {
       this.element.removeEventListener(type, handler)
     }
@@ -574,9 +671,27 @@ export default class HibikiController extends ChannelController {
     if (!token) return
     const action = token.slice(event.type.length + 2)
 
-    // Before the confirm, not after: declining must not let the form
-    // navigate away.
-    if (event.type === "submit") event.preventDefault()
+    // A fallback control's native behavior IS the degraded path: unless
+    // the island is `ready`, stand aside — no perform, no queueing — and
+    // the browser follows the href or submits the form to its own
+    // action=. Deliberately not the connect-window queue: a queued gesture
+    // renders nothing until the link comes up, while the control's
+    // destination answers immediately. Two touches before stepping back:
+    // a confirm: still gates the native behavior (scripts are running, so
+    // a destructive submit must not slip past the dialog), and a form's
+    // authenticity_token is freshened — server-rendered repaints carry no
+    // session, so their forms embed a stale token or none at all.
+    const fallback = "hibikiFallback" in control.dataset
+    if (fallback && this.state !== "ready") {
+      const message = control.dataset.hibikiConfirm
+      if (message && !window.confirm(message)) return event.preventDefault?.()
+      return freshenToken(control)
+    }
+
+    // Before the confirm, not after: declining must not let the form (or
+    // a fallback control's navigation) proceed. Optional call because the
+    // `visible` pseudo-event arrives as a plain object.
+    if (event.type === "submit" || fallback) event.preventDefault?.()
 
     const message = control.dataset.hibikiConfirm
     if (message && !window.confirm(message)) return
@@ -601,7 +716,15 @@ export default class HibikiController extends ChannelController {
     }
     // perform stamps `hbk` after this merge, so a field literally named hbk
     // loses to the seq rather than corrupting it.
-    this.trackControl(this.perform(action, payload), control)
+    const seq = this.perform(action, payload)
+    // The send failed on a socket believed live (perform already marked the
+    // island offline). The gesture's default was prevented in dispatch, so
+    // for a fallback control honor the contract by hand — the action never
+    // left the machine, so the native behavior cannot double-fire.
+    if (seq === undefined && "hibikiFallback" in control.dataset) {
+      return this.fallthrough(control)
+    }
+    this.trackControl(seq, control)
     // Resetting is right for an "add" form and wrong for an edit one: it
     // runs synchronously, before the server has replied, so a failed commit
     // would discard what the user typed.
@@ -610,6 +733,19 @@ export default class HibikiController extends ChannelController {
     }
   }
 
+  // The native behavior the intercepted event would have had. submit(),
+  // not requestSubmit(): the submit event already fired and was prevented,
+  // and re-dispatching it would loop straight back through the delegated
+  // listener.
+  fallthrough(control) {
+    if (control instanceof HTMLFormElement) {
+      freshenToken(control)
+      control.submit()
+    } else if (control.href) {
+      window.location.assign(control.href)
+    }
+  }
+
   // One timer per (control, action): two events on one element debounce
   // independently, and a second control's typing never cancels the first's.
   debounce(control, action, wait, fire) {
@@ -635,6 +771,21 @@ export default class HibikiController extends ChannelController {
 
 export { HibikiController }
 
+// The public seam without the Stimulus lookup (the header's "App JS
+// reaching the graph"): fire an action through the subscription of the
+// island CONTAINING element. Same return contract as perform — the seq
+// when accepted, undefined when dropped or when no island contains the
+// element (a structural mistake, hence the warn; the offline case stays
+// quiet because it is expected weather).
+export function performOn(element, action, payload = {}) {
+  for (let node = element; node; node = node.parentElement) {
+    const island = islands.get(node)
+    if (island) return island.perform(action, payload)
+  }
+  console.warn("hibiki: performOn found no island containing", element)
+  return undefined
+}
+
 // The Turbo-broadcast race helper the base uses internally, still
 // exported for custom (non-Stimulus) clients: resolves once Turbo stamps
 // the `connected` attribute on the given <turbo-cable-stream-source>.

data/lib/generators/hibiki/rails/css_variant.rb

@@ -113,7 +113,15 @@ module Hibiki
           option_label: "label cursor-pointer justify-start gap-2",
           option_note: "p-2 opacity-60 italic",
           checkbox_sm: "checkbox checkbox-sm",
-          filter_input: "input input-sm w-full mb-2"
+          filter_input: "input input-sm w-full mb-2",
+
+          # The nested fieldset (hibiki:rails:nested): one bordered card per
+          # child row, a legend on the fieldset, and the small row controls
+          # (↑/↓/Remove/Add).
+          fieldset_legend: "fieldset-legend px-2",
+          nested_row: "border border-base-300 rounded-box p-3 mb-2 space-y-2",
+          btn_ghost_sm: "btn btn-sm btn-ghost",
+          btn_outline_sm: "btn btn-sm btn-outline"
         }.freeze
 
         # DaisyUI is a plugin over Tailwind, and the merge says so literally:
@@ -167,7 +175,11 @@ module Hibiki
           option_label: "flex cursor-pointer items-center gap-2 py-1 text-sm",
           option_note: "p-2 text-gray-500 italic",
           checkbox_sm: CHECKBOX,
-          filter_input: "#{FIELD_FULL} mb-2 text-sm"
+          filter_input: "#{FIELD_FULL} mb-2 text-sm",
+          fieldset_legend: "px-2 text-sm font-medium text-gray-700",
+          nested_row: "rounded-md border border-gray-200 p-3 mb-2 space-y-2",
+          btn_ghost_sm: SECONDARY_BUTTON.sub("px-3 py-2", "px-2 py-1"),
+          btn_outline_sm: SECONDARY_BUTTON.sub("px-3 py-2", "px-2 py-1")
         ).freeze
 
         # Every lookup misses, so every class argument is omitted entirely.

data/lib/generators/hibiki/rails/multiselect/templates/concern.rb.tt

@@ -26,7 +26,7 @@ module <%= concern_module_name %>
 
 <% if search? -%>
       @<%= target_plural %>_query = Hibiki::State.new("")
-      # Only read while a row is being edited. The filter narrows this list
+      # Only read while a form is open. The filter narrows this list
       # and nothing else — the selection survives it.
       @<%= target_plural %>_options = Hibiki::Derived.new do
         @db_version.value
@@ -40,7 +40,7 @@ module <%= concern_module_name %>
         { options: rows.first(OPTIONS_LIMIT), truncated: rows.size > OPTIONS_LIMIT }
       end
 <% else -%>
-      # Only read while a row is being edited.
+      # Only read while a form is open.
       @<%= target_plural %>_options = Hibiki::Derived.new do
         @db_version.value
         { options: <%= target_class_name %>.order(:<%= label_column %>).pluck(:<%= label_column %>, :id) }
@@ -54,11 +54,19 @@ module <%= concern_module_name %>
       # Each edit starts with an unfiltered dropdown.
       @<%= target_plural %>_query.value = ""
     end
+
+    # The inline create form's dropdown, likewise. `super if defined?` —
+    # on a scaffold without inline create there is nothing to wrap and
+    # this hook is inert.
+    def new_form(data)
+      super if defined?(super)
+      @<%= target_plural %>_query.value = ""
+    end
 <% end -%>
 
     def list_locals
       locals = super
-      return locals unless locals[:editing_id]
+      return locals unless locals[:editing_id] || locals[:creating]
 
       extras = locals.fetch(:extras, {})
       locals.merge(extras: extras.merge(<%= extras_key %>: <%= extras_value_source %>))
@@ -66,16 +74,18 @@ module <%= concern_module_name %>
   end
 
   # One checkbox toggled: a SET, not a toggle — the client sends the box's
-  # checked state, so two tabs converge.
+  # checked state, so two tabs converge. `dom` names the form the box
+  # belongs to — a row edit and the inline create form can be open at once.
   def <%= toggle_action %>(data)
-    return unless @editing_id.peek
+    form = multiselect_form(data["dom"].to_s)
+    return unless form
 
     # Untrusted id — resolve it against the table before it enters the form.
     id = <%= target_class_name %>.where(id: data["id"]).pick(:id)
     return unless id
 
-    ids = @form.<%= ids_attr %>
-    @form.<%= ids_attr %> = data["checked"] ? ids | [id] : ids - [id]
+    ids = form.<%= ids_attr %>
+    form.<%= ids_attr %> = data["checked"] ? ids | [id] : ids - [id]
   end
 <% if search? -%>
 
@@ -84,4 +94,15 @@ module <%= concern_module_name %>
     @<%= target_plural %>_query.value = data["query"].to_s
   end
 <% end -%>
+
+  private
+
+  # Which open form a toggle aims at; nil drops the write.
+  def multiselect_form(dom)
+    if dom.end_with?("_new")
+      @new_form if @creating&.peek
+    else
+      @form if @editing_id.peek
+    end
+  end
 end

data/lib/generators/hibiki/rails/multiselect_helpers.rb

@@ -173,7 +173,7 @@ module Hibiki
           [%("checked"), "id", "#{form_ref}.#{ids_attr}.include?(id)",
            %(id: "\#{#{dom_ref}}_#{target_singular}_\#{id}"),
            *css_args(:checkbox_sm),
-           %(**on(:#{toggle_action}, event: :change, with: { id: id }))]
+           %(**on(:#{toggle_action}, event: :change, with: { id: id, dom: #{dom_ref} }))]
         end
 
         def filter_field_args

data/lib/generators/hibiki/rails/multiselect_injections.rb

@@ -145,7 +145,11 @@ module Hibiki
 
         def inject_component_render
           path = view_path("row_form.rb")
-          line = "        render #{component_class_name}.new(form: @form, dom: dom, extras: @extras)\n"
+          # Two vintages of row_form: dom became a keyword (@dom) when the
+          # form was parameterized for inline create; before that it was a
+          # private method.
+          dom = wired?(path, "@dom = dom") ? "@dom" : "dom"
+          line = "        render #{component_class_name}.new(form: @form, dom: #{dom}, extras: @extras)\n"
           return if wired?(path, "Multiselect.new")
           return manual_wiring(path, line) unless wired?(path, PHLEX_FIELDSET_CLOSE)
 
@@ -218,7 +222,8 @@ module Hibiki
         def thread_extras_erb
           [view_path("_list.html.erb"), view_path("_#{row_partial}.html.erb"),
            view_path("_#{row_form_partial}.html.erb")].each do |path|
-            gsub_file path, /^(<%# locals: \(.*?)\) -%>/, '\1, extras: {}) -%>', verbose: false
+            # /m: the row form's locals header wraps onto a second line.
+            gsub_file path, /^(<%# locals: \(.*?)\) -%>/m, '\1, extras: {}) -%>', verbose: false
           end
           # `form: form` appears exactly once per file, inside the one render
           # call that must pass extras on.

data/lib/generators/hibiki/rails/nested/USAGE

@@ -0,0 +1,30 @@
+Description:
+    Wires one parent→child edge of a nested form onto a resource that
+    hibiki:rails:scaffold_controller already generated: the child's
+    ReactiveForm, a _<child>_fields partial with path-addressed inputs
+    (riding the generic Hibiki::Rails::NestedActions channel actions),
+    reactive_nested on the parent form, model wiring (has_many +
+    accepts_nested_attributes_for allow_destroy), the classic fields_for
+    fallback in the full-page form, and the controller's params.expect
+    double-array group.
+
+    Parent and Child models must exist and be migrated, and Child must
+    declare belongs_to :<parent>. An optional field list narrows or orders
+    the child's form fields; the facts stay the schema's.
+
+    Depth is composition: run once per edge. A run whose Parent is itself a
+    nested child (its _<parent>_fields partial exists) nests into that
+    partial instead of the row form.
+
+    Ordering: a `position` column on the child (or --position=COLUMN) makes
+    the fieldset ordered — the has_many gains an order scope, the parent
+    form stamps positions from array order, and rows get ↑/↓ buttons. The
+    named column is added by migration when missing; --skip-position opts
+    out entirely.
+
+Examples:
+    bin/rails g hibiki:rails:nested Song Credit
+
+    bin/rails g hibiki:rails:nested Credit Contribution
+
+    bin/rails g hibiki:rails:nested Song Credit artist:references role:string --position=rank