hibiki_rails 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d708875aa67bf5d9b9137ac8d9bb05cf23604db936011706d068ec0b7116429c
-  data.tar.gz: 941b16f996127706d699e8812cf712b755c0f833f7a04c9e71912844421645ba
+  metadata.gz: 2776ffca09f5d60a467d985550fb12c36570a5a22fd5eb7b0a54ee45c30a68e0
+  data.tar.gz: 3a05960da6f7ab9d80a2f6574f6413491610314fd3917a62b48c48127b866830
 SHA512:
-  metadata.gz: 74175d980c70f1b4ea1bb9ba593ef9940326eccfce6c783ceefdebfb2a0659706faa1040393759549366c5880ea23459740e0f3f280e64fb47a4bc32a371f69c
-  data.tar.gz: c88a903f15b13516310beb32a7ed741942c49ae65823a6422fb36823400a9fea420ae08bd2fe047bc1d2e6ff3e38cef8f86c0665eeee6014e0f495c880ad90a4
+  metadata.gz: 29f7fc27b77dbb5e32e94440afc233da170b4095b77bac378426f834a47da38065b5b35881c63dcefe4e3c0053849f0fd2fd23d87d80708aebbec207fe765e93
+  data.tar.gz: 5f85d166f5ff9dec3dc23a4d8e4aae9fbece2f53ee63b10a163622e799c77f6b989743f27a935db3c1915b9bb56c96332462b983ccf3fc0cd7ab9ea8f5477fa4

data/CHANGELOG.md

@@ -4,6 +4,137 @@ 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.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
+
+**`hibiki:rails:multiselect` — a dropdown multi-select over a
+`has_many :through`, layered onto a scaffolded resource.**
+
+```
+bin/rails g hibiki:rails:multiselect Album Song Track
+```
+
+Owner and target must exist and be migrated; the join model is generated when
+missing (a `belongs_to` pair with `touch:` on the owner side — a join write IS
+an owner change — and a unique index over the pair) and named off the owner's
+reflection when the `has_many :through` is already declared, where the third
+argument may be omitted. An existing join gets `touch: true` added to its
+`belongs_to`.
+
+The channel half is a generated concern (`AlbumsChannel::SongsMultiselect`
+under `app/channels/concerns/`) that wraps `build_graph`, `list_locals` and
+`edit` with `super` via a prepended module — one `include` line is the
+channel's only edit, and the concern's public `toggle_song` / `search_songs`
+methods are client-invocable actions like any other. The form object gains
+`reactive_association :songs`.
+
+The selection is owned by the graph, not the form markup: each checkbox sends
+its own toggle carrying its checked state (a set, so two tabs converge), and
+the submit payload never carries the ids. That is what keeps the built-in
+searchable filter honest — narrowing the option list can never drop
+selections it hides. Options are capped (`--limit`, default 50) with a
+LIMIT+1 fetch whose extra row becomes the "type to narrow" hint — no COUNT
+per keystroke. `--skip-search` drops the filter AND the cap, which would
+strand the options it hides. `--label` overrides the inferred display column;
+`--phlex` and `--css` are detected from what the scaffold left behind.
+
+**A multiple `<select>`'s full selection now reaches the channel, and
+`ReactiveForm` can carry a collection's ids.** Two halves shipped together:
+the client collects every FormData entry of a `[]`-suffixed field name as an
+array under the bare key (previously last-wins, so a multi-select submitted
+only one option; non-`[]` duplicate keys stay last-wins on purpose — the
+hidden-field checkbox convention depends on it), and
+`reactive_association :tags` on a `ReactiveForm` defines a `tag_ids` signal
+that hydrates from the record's ids reader and commits through the
+association writer, casting each id via the target model's primary-key type.
+
+**`hibiki:rails:form` — re-derive a resource's form from its validators.**
+`bin/rails g hibiki:rails:form Book` reads the migrated schema and rewrites the
+validator-shaped files only: the `ReactiveForm` (its `live_errors` clauses) and
+the two form views (number-field bounds, requiredness). Everything else the
+scaffold wrote is untouched, and Thor still asks per file before replacing
+edits. `--skip-views` limits it to the form object; the view layer and css
+variant are detected from the files a previous run left, with `--phlex` and
+`--css` as overrides. An optional field list chooses order and subset, never
+facts.
+
+### Changed
+
+**Scaffolded partials pass a generic `extras: {}` hash down the
+list → row → row form chain, in both view layers.** The extension point
+add-on generators ride: merge locals into the broadcast under one key and
+they arrive at the row form with no partial edits. Existing scaffolds keep
+working untouched — a generator that needs the hash on pre-0.7.0 output
+threads it in with a `compat` notice.
+
+**The scaffold's empty-`live_errors` notice now recommends
+`bin/rails g hibiki:rails:form Book`** — on its own line, with no retyped field
+list — instead of re-running `scaffold_controller` with the full arguments. The
+migration the scaffold wrote preserves the argument order, so once it has run
+the schema answers both order and facts.
+
 ## 0.6.0 — 2026-08-10
 
 ### Added

data/README.md

@@ -73,6 +73,9 @@ bin/rails g hibiki:rails:scaffold_controller Book
 
 # Same, but you pick the field order; everything else still comes from the model
 bin/rails g hibiki:rails:scaffold_controller Book title:string author:references
+
+# After adding validators: re-derive the form and its views, touching nothing else
+bin/rails g hibiki:rails:form Book
 ```
 
 Your plain `rails g scaffold` is untouched. The generated markup is styled to
@@ -91,6 +94,12 @@ Listing the fields yourself only chooses their order and which ones appear — t
 model still answers everything else, so the live validation, a number field's
 `min:`/`max:` and a `belongs_to`'s display label all survive the choice.
 
+Because the live validation is derived from the model's validators, a scaffold
+generated before its migration ran starts with none. `hibiki:rails:form` is the
+catch-up: it rewrites only the `ReactiveForm` and the two form views from the
+schema as it stands now, asks before replacing anything you edited, and takes
+`--skip-views` to rewrite the form object alone.
+
 Your models are edited, not just read: the one being scaffolded gains the
 `after_commit` broadcast that makes writes from anywhere reach an open list, and
 each model a `belongs_to` points at gains the `has_many` half plus a ping of its

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
 //
@@ -104,6 +109,45 @@ const controlValue = (control) => {
   return control.value
 }
 
+// A trailing [] is a serialization artifact, not part of the attribute name:
+// the channel payload is JSON, where arrays are native.
+const payloadKey = (name) => (name.endsWith("[]") ? name.slice(0, -2) : name)
+
+// A submitted form's contribution to the payload. A []-named field collects
+// EVERY entry as an array under the bare key; other duplicate keys stay
+// last-wins, which is what lets Rails' hidden-field checkbox convention
+// submit "1" when checked and "0" when not.
+const formPayload = (form) => {
+  const data = new FormData(form)
+  const payload = {}
+  for (const key of new Set(data.keys())) {
+    const all = data.getAll(key)
+    payload[payloadKey(key)] = key.endsWith("[]") ? all : all.at(-1)
+  }
+  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 {
@@ -194,13 +238,25 @@ 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 socket turned
+  // out to be closed under a subscription still believed live.
   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.
@@ -350,7 +406,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-
@@ -358,11 +414,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)) {
@@ -370,6 +428,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
@@ -378,6 +437,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() {
@@ -556,9 +626,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
@@ -577,13 +665,21 @@ export default class HibikiController extends ChannelController {
       ? JSON.parse(control.dataset.hibikiWith)
       : {}
     if (event.type === "submit") {
-      Object.assign(payload, Object.fromEntries(new FormData(control)))
+      Object.assign(payload, formPayload(control))
     } else if (control.name && (event.type === "change" || event.type === "input")) {
-      payload[control.name] = controlValue(control)
+      payload[payloadKey(control.name)] = controlValue(control)
     }
     // 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.
@@ -592,6 +688,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) {

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

@@ -99,7 +99,21 @@ module Hibiki
           counts: "ml-auto text-sm opacity-70",
           # my-, not mt-: the control renders above the list as well as below,
           # and the top copy needs the gap on its other side.
-          pagination_nav: "join my-2 mx-auto flex justify-center w-fit"
+          pagination_nav: "join my-2 mx-auto flex justify-center w-fit",
+
+          # The multiselect dropdown (hibiki:rails:multiselect). One structure
+          # for every variant: DaisyUI's dropdown opens on :focus-within, the
+          # tailwind override hand-rolls the same rule with group-focus-within,
+          # and under --css=none nothing hides the panel so the list renders
+          # inline — unstyled, still functional.
+          dropdown: "dropdown w-full",
+          dropdown_trigger: "select w-full items-center",
+          dropdown_panel: "dropdown-content bg-base-100 rounded-box z-10 mt-1 w-full p-2 shadow-md",
+          option_list: "menu w-full max-h-60 flex-nowrap overflow-y-auto p-0",
+          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"
         }.freeze
 
         # DaisyUI is a plugin over Tailwind, and the merge says so literally:
@@ -144,7 +158,16 @@ module Hibiki
           muted: "text-gray-500 italic",
           muted_inline: "text-gray-400",
           counts: "ml-auto text-sm text-gray-500",
-          pagination_nav: "my-2 mx-auto flex justify-center w-fit -space-x-px rounded-md shadow-sm"
+          pagination_nav: "my-2 mx-auto flex justify-center w-fit -space-x-px rounded-md shadow-sm",
+          dropdown: "group relative w-full",
+          dropdown_trigger: "#{FIELD_FULL} flex cursor-pointer items-center",
+          dropdown_panel: "absolute inset-x-0 z-10 mt-1 hidden rounded-md border border-gray-200 " \
+                          "bg-white p-2 shadow-lg group-focus-within:block",
+          option_list: "max-h-60 space-y-1 overflow-y-auto",
+          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"
         ).freeze
 
         # Every lookup misses, so every class argument is omitted entirely.

data/lib/generators/hibiki/rails/form/USAGE

@@ -0,0 +1,24 @@
+Description:
+    Regenerates a resource's ReactiveForm and its form views from the model's
+    schema and validators. Run it after adding or changing validators so
+    live_errors, number-field bounds and requiredness match the model again.
+
+    The model must exist and its table must be migrated. With no field list,
+    columns and their order come from the schema; pass fields explicitly only
+    to choose a different order or subset — the facts stay the schema's.
+
+    Only the validator-shaped files are rewritten; the rest of the scaffold's
+    output is untouched. Thor asks per file before replacing anything you have
+    edited. The view layer and css variant are detected from the files a
+    previous scaffold left; --phlex and --css override.
+
+Example:
+    bin/rails generate hibiki:rails:form Book
+
+    This will rewrite:
+        app/forms/book_form.rb
+        app/views/books/_form.html.erb
+        app/views/books/_book_form.html.erb
+
+    Under --phlex, the views are app/views/books/{form,row_form}.rb instead.
+    Pass --skip-views to rewrite only app/forms/book_form.rb.

data/lib/generators/hibiki/rails/form/form_generator.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/resource_helpers"
+require_relative "../generator_helpers"
+require_relative "../scaffold_helpers"
+require_relative "../scaffold_view_helpers"
+require_relative "../scaffold_phlex_helpers"
+require_relative "../scaffold_post_install"
+require_relative "../scaffold_shared_views"
+require_relative "../scaffold_schema"
+require_relative "../css_variant"
+
+module Hibiki
+  module Rails
+    module Generators
+      # Re-derives the validator-shaped slice of a scaffolded resource: the
+      # ReactiveForm (live_errors) and the two form views (bounds,
+      # requiredness). Run it after adding or changing validators on the model;
+      # everything else the scaffold wrote is deliberately out of scope, so a
+      # customized index or controller is never put at risk over a validator.
+      #
+      # Always the introspection path: the model and its table must exist,
+      # because validators are the one thing this generator is for and only a
+      # live model can answer them. A field list is optional and chooses order
+      # and subset only — the facts stay the schema's, like the scaffold's own
+      # merge.
+      class FormGenerator < ::Rails::Generators::NamedBase
+        include ::Rails::Generators::ResourceHelpers
+        include GeneratorHelpers
+        include ScaffoldHelpers
+        include ScaffoldViewHelpers
+        include ScaffoldPhlexHelpers
+        include ScaffoldPostInstall
+        include ScaffoldSharedViews
+
+        # The scaffold's templates, reused wholesale — this generator re-emits
+        # a subset of that output and must never drift from it. Its own
+        # source_root stays beside its own USAGE (Base#usage_path resolves
+        # ../USAGE from source_root, and pointing it at the scaffold's tree
+        # would serve the scaffold's help text).
+        SCAFFOLD_TEMPLATES = File.expand_path("../scaffold_controller/templates", __dir__)
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Regenerates a resource's ReactiveForm and form views from the " \
+             "model's schema and validators."
+
+        argument :attributes, type: :array, default: [], banner: "field:type field:type"
+
+        class_option :css, type: :string, enum: CssVariant::NAMES,
+                           desc: "Markup variant for the form views (default: detect)"
+        class_option :skip_views, type: :boolean, default: false,
+                                  desc: "Rewrite only the form object — leave the form views alone"
+        class_option :phlex, type: :boolean,
+                             desc: "Emit Phlex form components (default: detect from existing views)"
+
+        def check_phlex_wiring
+          warn_without_phlex_rails unless skip_views?
+        end
+
+        # Resolving the schema first means a missing model or an unmigrated
+        # table aborts before anything is written.
+        def resolve_schema
+          schema
+          @new_app_dirs = %w[app/forms].reject { exists?(it) }
+        end
+
+        def create_form
+          template "form.rb.tt", form_path
+        end
+
+        def create_views
+          return if skip_views?
+
+          if phlex?
+            template "views/form.rb.tt", view_path("form.rb")
+            template "views/row_form.rb.tt", view_path("row_form.rb")
+          else
+            template "views/_form.html.erb.tt", view_path("_form.html.erb")
+            template "views/_row_form.html.erb.tt", view_path("_#{row_form_partial}.html.erb")
+          end
+
+          create_form_shared_views
+        end
+
+        def post_install
+          restart_notice
+          shared_views_notice
+          skipped_notice
+          live_errors_notice
+          uniqueness_notice
+        end
+
+        private
+
+        # The same layering as the scaffold's, minus nothing: the css-variant
+        # fork holds only the page control today, but an app's own
+        # lib/templates override must keep winning first either way.
+        def source_paths
+          @source_paths ||= [*self.class.source_paths_for_search,
+                             *phlex_source_paths,
+                             File.join(SCAFFOLD_TEMPLATES, css_variant.to_s),
+                             File.join(SCAFFOLD_TEMPLATES, "shared")]
+        end
+
+        def phlex_source_paths
+          return [] unless phlex?
+
+          [File.join(SCAFFOLD_TEMPLATES, "phlex", css_variant.to_s),
+           File.join(SCAFFOLD_TEMPLATES, "phlex", "shared")]
+        end
+
+        # Unlike the scaffold pair, the model is REQUIRED on both branches: an
+        # argument list here chooses order and subset, never facts, because
+        # facts with no validators behind them are exactly the output this
+        # generator exists to replace.
+        def schema
+          @schema ||= if attributes.any?
+                        ScaffoldSchema.from_attributes(attributes, model: model_class)
+                      else
+                        ScaffoldSchema.from_model(model_class)
+                      end
+        end
+
+        # Aborts rather than emitting a form with nothing derived — like the
+        # scaffold's own model_class, but with no field-list escape hatch.
+        def model_class
+          klass = class_name.safe_constantize
+          raise ::Rails::Generators::Error, missing_model_message unless klass
+
+          # Touch the schema here so an unmigrated table fails with our message
+          # rather than somewhere inside a template.
+          klass.tap(&:columns_hash)
+        rescue ::Rails::Generators::Error
+          raise
+        rescue StandardError
+          raise ::Rails::Generators::Error, missing_table_message
+        end
+
+        def missing_model_message
+          "No model #{class_name}. Generate the resource first:\n    " \
+            "bin/rails g hibiki:rails:scaffold #{name} title:string"
+        end
+
+        def missing_table_message
+          "#{class_name} has no table yet. Run bin/rails db:migrate first"
+        end
+
+        def skip_views? = options[:skip_views]
+
+        # Which view layer a previous scaffold left behind. app/views/<res>/
+        # form.rb only ever comes from a --phlex run (the ERB layer's file is
+        # _form.html.erb), so its presence is the layer answer; --phlex and
+        # --no-phlex override for the odd case.
+        def phlex?
+          return @phlex if defined?(@phlex)
+
+          @phlex = options[:phlex].nil? ? exists?(view_path("form.rb")) : options[:phlex]
+        end
+
+        def css_variant
+          @css_variant ||= (options[:css] || CssVariant.detect(destination_root)).to_sym
+        end
+
+        def css(token) = CssVariant.token(css_variant, token)
+        def css? = css_variant != :none
+      end
+    end
+  end
+end

data/lib/generators/hibiki/rails/multiselect/USAGE

@@ -0,0 +1,27 @@
+Description:
+    Adds a dropdown multi-select for a has_many :through association onto a
+    resource that hibiki:rails:scaffold_controller already generated.
+
+    Owner and Target must exist and be migrated. Join is required only when
+    the owner doesn't declare the association yet — the join model and its
+    migration are generated (belongs_to pair, touch: on the owner side, a
+    unique index over the pair), and the has_many :through is injected into
+    the owner.
+
+    The channel gains one `include`; everything else lives in a generated
+    concern under app/channels/concerns that wraps build_graph/list_locals
+    with super. The selection is owned by the graph (the form's <target>_ids
+    signal), so filtering the option list can never drop hidden selections.
+
+    The option list is capped (OPTIONS_LIMIT in the concern, --limit to
+    choose it); the cap is dropped under --skip-search, where it would strand
+    the options it hides. Scaffolds generated before 0.7.0 lack the extras:
+    hash the view rides on — it is threaded through their partials
+    automatically.
+
+Examples:
+    bin/rails g hibiki:rails:multiselect Album Song Track
+
+    bin/rails g hibiki:rails:multiselect Album Song --skip-search
+
+    bin/rails g hibiki:rails:multiselect Album Song Track --label=name --limit=25