hibiki_rails 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b21e4afc4b4e74e30f3c32286a1a75b30052e55145d25210bb3cecfbb3bc24c
-  data.tar.gz: 5c26612918d2b81c3a6a6a134710331ba656b25e9441856627ddf6b3ee093e71
+  metadata.gz: cd126c85e743e5ec9c89e54a1ffaba4cb04e6b6b0ef89868d60023168a0936a7
+  data.tar.gz: 00b4dfa1606348df1039cf5b69d1129c170fd418966b3db120964b71eba1e1c6
 SHA512:
-  metadata.gz: acf106a0cda97184c5bd9a988bab71efb8be65c76e1f5b08785f96795d7a9dc21f67a5511a9a10ffa7b5fee49d498891ce7516b926eec1868d76820fd7c42c48
-  data.tar.gz: 5e8d7b8aba5eaf643e5c6f82dcde5c824bd8f9eb1594163dd872bc0a304a6b37a796069385ec8fdc78e8bfe48dd7d9345d4f60a20b77fe3f72760d02e9b0157e
+  metadata.gz: 3c1e7d75c946f79cc898c20c2c3a8457ba78c152963f8b8155dd70a26308c138b31acc4b7a732e037d6bc28e933fb542a509d2dabee2e03602727d7e5e81b6d6
+  data.tar.gz: 6edf4361a4edbda81b933167cb6a7e08030cb50aac694c601a22c2210036eab5c56b101a449d3ea174a5485347e7c9c6e1cc86f9da123cbfe02e0e1ed34f41dd

data/CHANGELOG.md

@@ -4,6 +4,132 @@ 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.5.1 — 2026-08-08
+
+### Changed
+
+**Generator output and messages slimmed down.** The scaffold templates used to
+carry long design-rationale comments into every generated file; they are now
+one-to-three-line hints, with the docs holding the prose. The safety notes a
+user editing the file actually needs stayed: public channel methods are
+client-invocable actions, ActionCable's exact-arity rule, the untrusted
+subscribe param, Phlex omitting `false`-valued attributes, and the busy
+stylesheet's do-not-wrap-in-a-layer rule.
+
+The generators' status notices were shortened the same way — they still say
+what to do, just not why at essay length.
+
+No behavior change anywhere: no code inside any template moved, and neither
+the runtime nor the packaged client changed (the npm 0.5.1 exists only to keep
+the lockstep rule). Re-running a scaffold with `--force` rewrites the views
+with the shorter comments; that diff is the whole upgrade.
+
+## 0.5.0 — 2026-08-05
+
+### Added
+
+**`--phlex` on both scaffold generators.** `bin/rails g hibiki:rails:scaffold
+Book title:string --phlex` emits Phlex components under `app/views/books/*.rb`,
+namespaced `Views::`, instead of ERB templates. Purely additive: without the
+flag nothing about the generated output changes, byte for byte.
+
+Only the view layer moves. The channels, the query object, the ReactiveForm,
+the model injections, every action and the whole `data-hibiki-*` protocol are
+the same either way — the controller gains an explicit `render Views::…` at
+each of its six render sites, and the two `broadcast_morph` calls swap
+`partial:`/`locals:` for `renderable:`, and that is the entire difference
+outside the templates.
+
+Needs `phlex-rails` and `bin/rails g phlex:install`. The generator warns when
+either is missing and writes the files anyway, so the scaffold can come first.
+
+Four things worth knowing, because they are not what an ERB reader expects.
+Phlex renders `String`, `Symbol`, `Integer` and `Float` and raises on anything
+else, so date, time and decimal columns are emitted with an explicit `to_s`.
+Phlex omits a `false`-valued attribute entirely, so the page control's
+`data-turbo` is the string `"false"`. Phlex emits no whitespace between
+siblings, so the components space their inline neighbours explicitly. And
+`options_for_select` outputs directly and raises if its return value is passed
+on, so both select sites take their options from a block.
+
+The page control is still the one component with a per-`--css` fork, in both
+trees. Under Phlex the plain-Tailwind fork's *reason* dissolves — a hoisted
+template local becomes an ordinary constant — but it stays forked so the two
+trees match file for file and a future `--css` decision stays a diff rather
+than a judgement call.
+
+### Changed
+
+**The loading and connection recipes are an asset, not a partial.** They were a
+103-line inline `<style>` emitted as `app/views/<resource>/_busy.html.erb` and
+rendered once per page; they are now
+`app/assets/stylesheets/hibiki_busy.css`, written once per app.
+
+Per resource was always wrong: every rule keys on an attribute the client
+stamps and none of them mentions a model, so a two-resource app carried two
+byte-identical copies. It also put CSS somewhere a Content-Security-Policy that
+forbids inline styles would reject.
+
+The generator wires it for you: a cssbundling or tailwindcss-rails entry
+stylesheet gets an `@import`, a layout already using
+`stylesheet_link_tag :app` or `:all` needs nothing, and anything else gets a
+`stylesheet_link_tag` injected into the layout. Only when none of those applies
+does it print the line to add. Every branch is idempotent.
+
+**If you re-run the generator on an app scaffolded before this**, the old
+`_busy.html.erb` stays on disk — a generator never deletes — and nothing
+renders it any more. The post-install output names it; delete it.
+
+The rules are deliberately unlayered, and the file says so: two of them set
+`display` on elements that also carry Tailwind utilities, and unlayered
+declarations beat `@layer utilities` whatever the link order.
+
+### Fixed
+
+**The npm package no longer drags in a second copy of `@rails/actioncable`.**
+It moves from `dependencies` to `peerDependencies` at `>= 7.0`, matching
+turbo-rails' own range.
+
+Why there were two: `@rails/actioncable`'s npm `latest` dist-tag is 7.2.302 even
+though 8.x is published, and resolvers prefer `latest` when it satisfies the
+range. So turbo-rails' `>=7.0` took 7.2.302 while this package's `>= 8.0` was
+forced up to 8.1.301, and both ended up in the bundle — about 16 KB of duplicate
+client, and two separate module instances that could never share a consumer.
+A fresh install happened to hoist a single copy; the duplicate appeared when
+adding hibiki-rails to an app whose lockfile already pinned 7.2.302, which is
+every existing app.
+
+If your bundler warns about an unmet peer, install `@rails/actioncable`
+explicitly — but a stock Rails app already has it via turbo-rails, and both bun
+and npm 7+ auto-install a missing peer. The client uses only `createConsumer`,
+`subscriptions.create` and `subscription.perform`, all stable since Action
+Cable 6, so the lower floor changes nothing at runtime.
+
+### Changed — BREAKING
+
+**The Rails floor is now 8.0.** `actioncable` and `railties` move from
+`>= 7.1` to `>= 8.0`, and the 7.1 / 7.2 CI legs are gone. Ruby stays at `>= 3.4`.
+
+This is a correction as much as a policy change: **generated controllers never
+ran on Rails 7.** `hibiki:rails:scaffold` emits `params.expect` at two sites,
+inherited from Rails 8's own scaffold, and `ActionController::Parameters#expect`
+does not exist before 8.0 — so a generated controller raised `NoMethodError` on
+the first request to `show`, `edit`, `update`, `create` or `destroy` on 7.1 and
+7.2. The generator suite never caught it because those specs assert on emitted
+source text and never boot the result.
+
+The alternative — branching the template on `Rails::VERSION` — was rejected: it
+would also need a way to *execute* generated output on the old legs, which is
+more work than dropping two CI legs for a version combination (Rails 7.x on
+Ruby >= 3.4) that barely exists.
+
+**If you are on Rails 7.1 or 7.2, stay on 0.4.0.** It remains available and is
+unaffected; nothing in 0.5.0 is a security fix for it. Note that the *runtime*
+half of the gem — channels, the graph, the broadcast helpers, the client — has
+no known 8.0-only dependency; it is the generators whose output does. The floor
+applies to the whole gem anyway, because shipping a gem whose headline generator
+cannot run on its own declared floor is what got us here.
+
 ## 0.4.0 — 2026-08-03
 
 ### Added

data/README.md

@@ -10,7 +10,7 @@ Turbo Streams broadcast → Turbo morphs the DOM
 
 A graph lives per cable connection (in practice: per browser tab), built when the channel subscribes and disposed when it unsubscribes. Effects subscribe to whatever signals they read; when an action writes a signal, exactly the affected effects re-render and broadcast.
 
-Supports Rails >= 7.1, Ruby >= 3.4.
+Supports Rails >= 8.0, Ruby >= 3.4.
 
 ## Rails quick start
 
@@ -80,6 +80,13 @@ match your app (DaisyUI, Tailwind, or unstyled — detected automatically, or
 forced with `--css=`). Run `bin/rails g hibiki:rails:scaffold --help` for the
 rest of the options.
 
+Pass `--phlex` for Phlex components under `app/views/books/*.rb` instead of ERB
+templates. It needs `phlex-rails` and `bin/rails g phlex:install`, and it
+changes the view layer only — the channels, the query object, the form and the
+whole client protocol are the same either way. Note this is a different thing
+from the `hibiki_phlex` gem, which makes a component own reactive state; here
+the channel owns the state and the components are ordinary stateless views.
+
 Listing the fields yourself only chooses their order and which ones appear — the
 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.
@@ -90,6 +97,12 @@ each model a `belongs_to` points at gains the `has_many` half plus a ping of its
 own, so renaming a parent repaints the lists that print its name. Both are
 idempotent, announced, and leave anything you already declared alone.
 
+One file lands outside the resource: `app/assets/stylesheets/hibiki_busy.css`,
+which styles the loading and connection state the client stamps. It is written
+once per app, shared by every generated resource, and wired into your stylesheet
+or layout automatically — the post-install output says which, or gives you the
+line to add when it cannot tell.
+
 Restart the server afterwards: `app/forms/` is new, and Rails works out its
 autoload paths at boot.
 
@@ -107,7 +120,7 @@ Congratulations! Now you have your first reactive component!
 
 Documentation site: <https://planetaska.github.io/hibiki/rails-introduction/>
 
-Release notes and upgrade advice: [CHANGELOG.md](CHANGELOG.md). **If you run Rails 7.1 or 7.2, read the 0.3.0 entry** — it fixes channel lifecycle methods that were client-invocable on those versions.
+Release notes and upgrade advice: [CHANGELOG.md](CHANGELOG.md). **Rails 7.1 and 7.2 are supported up to 0.4.0 only** — 0.5.0 raises the floor to 8.0. If you are staying on 0.4.0 with Rails 7.x, read the 0.3.0 entry: it fixes channel lifecycle methods that were client-invocable on those versions.
 
 ## Development
 

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

@@ -121,10 +121,13 @@ module Hibiki
           badge_warning: "inline-flex items-center rounded-full bg-amber-100 px-2 py-1 " \
                          "text-xs font-medium text-amber-800",
           # `inline-block` is load-bearing, not decoration: a bare span is
-          # inline, where h-3/w-3 do nothing. It is safe against the
-          # visibility rules because this stylesheet is linked in <head> and
-          # the transport <style> is in the body, so equal specificity goes
-          # hibiki's way.
+          # inline, where h-3/w-3 do nothing. It also collides with
+          # .hbk-control-busy's `display: none` at equal specificity — the
+          # transport stylesheet wins because it is UNLAYERED and Tailwind's
+          # utilities are in @layer utilities, which beats them whatever the
+          # link order. (Before 0.5.0 the rules were a <style> in the body and
+          # won on document order instead; that is why the stylesheet's header
+          # now says not to wrap it in a layer.)
           spinner: "inline-block h-3 w-3 animate-spin rounded-full border-2 " \
                    "border-current border-r-transparent align-[-0.15em]",
           warning_text: "text-amber-600",

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

@@ -71,8 +71,7 @@ module Hibiki
         def wiring_hint
           return if hibiki_registered? && helpers_included?
 
-          say_status :hint, "the packaged client is not fully wired " \
-                            "(register line and/or Helpers include) — run: " \
+          say_status :hint, "the packaged client is not fully wired. Run: " \
                             "bin/rails g hibiki:rails:install", :yellow
         end
       end

data/lib/generators/hibiki/rails/install/install_generator.rb

@@ -103,8 +103,7 @@ module Hibiki
 
         def bundler_note
           say_status :skip, "#{IMPORTMAP} not found — with a JS bundler, " \
-                            "npm/yarn add hibiki-rails instead (it pulls in " \
-                            "@rails/actioncable)", :yellow
+                            "npm/yarn/bun add hibiki-rails instead", :yellow
         end
       end
     end

data/lib/generators/hibiki/rails/install/templates/hibiki_controller.js.tt

@@ -1,7 +1,4 @@
-// Registers the packaged hibiki client (the "hibiki-rails" module: the
-// engine's importmap pin, or the npm package in bundler apps) as the
-// "hibiki" Stimulus controller — the Ruby helpers hardcode that
-// identifier in data-controller. File-backed on purpose: `bin/rails
-// stimulus:manifest:update` re-derives this exact registration from the
-// filename, so it survives manifest rewrites.
+// Registers the packaged hibiki client as "hibiki" Stimulus controller.
+// `bin/rails stimulus:manifest:update` re-derives this,
+// so it survives manifest rewrites.
 export { default } from "hibiki-rails"

data/lib/generators/hibiki/rails/island/templates/channel.rb.tt

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
 # Generated by hibiki:rails:island — a working mini-example: one state,
-# one derived, one action, one broadcasting effect. The concern owns the
-# actor, the root, the per-action batch, and the [channel_name, cid]
-# stream convention; this class is just the graph and its actions.
+# one derived, one action, one broadcasting effect.
 class <%= class_name %>Channel < ApplicationCable::Channel
   include Hibiki::Rails::Channel
 

data/lib/generators/hibiki/rails/island/templates/display.html.erb.tt

@@ -1,5 +1,4 @@
-<%%# The root id is the broadcast replacement key — keep it in sync with the
-    channel effect's target. %>
+<%%# The root id is the replacement key. Keep in sync with channel effect's target. %>
 <p id="<%= display_dom_id %>">
   count: <strong><%%= count %></strong> &middot; doubled: <strong><%%= doubled %></strong>
 </p>

data/lib/generators/hibiki/rails/island/templates/island.html.erb.tt

@@ -1,13 +1,9 @@
-<%%# Stamped through Hibiki::Rails::Helpers (hibiki_island / on) — never
-    write the underlying data attributes by hand, they are private to the
-    gem and version with its packaged JS. %>
+<%%# Reactive island generated by hibiki_rails %>
 <%% cid = local_assigns.fetch(:cid) { SecureRandom.uuid } %>
 <%%= tag.div(**hibiki_island(<%= class_name %>Channel, cid:)) do %>
   <%%= turbo_stream_from "<%= stream_name %>", cid %>
 
-  <%%# Paint-avoidance placeholder only: the controller subscribes AFTER the
-      Turbo stream above confirms, so the graph's first broadcast replaces
-      this. %>
+  <%%# Placeholder only: the graph's first broadcast replaces this. %>
   <%%= render "<%= view_dir %>/<%= file_name %>_display", count: 0, doubled: 0 %>
 
   <p><%%= tag.button("+1", **on(:increment)) %></p>

data/lib/generators/hibiki/rails/phlex/phlex_generator.rb

@@ -27,9 +27,8 @@ module Hibiki
         def warn_without_hibiki_phlex
           require "hibiki/phlex"
         rescue LoadError
-          say_status :warn, "hibiki_phlex is not in this bundle — the generated channel " \
-                            "calls Hibiki::Phlex.render_effect. Add `gem \"hibiki_phlex\"` " \
-                            "(and `gem \"phlex-rails\"` to render components from views).", :yellow
+          say_status :warn, "hibiki_phlex is not in this bundle. " \
+                            "Add `gem \"hibiki_phlex\"`.", :yellow
         end
 
         def create_channel
@@ -64,7 +63,7 @@ module Hibiki
         def register_hint
           return if hibiki_registered?
 
-          say_status :hint, "the packaged client is not registered — run: " \
+          say_status :hint, "the packaged client is not registered. Run: " \
                             "bin/rails g hibiki:rails:install", :yellow
         end
       end

data/lib/generators/hibiki/rails/phlex/templates/channel.rb.tt

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-# Generated by hibiki:rails:phlex — the component owns the state
-# (Hibiki::Reactive); the channel owns the transport. One render effect,
-# re-rendering THE SAME INSTANCE, its HTML transmitted over the channel's
-# own subscription and swapped in by the fragment's root DOM id.
+# Generated by hibiki:rails:phlex
 class <%= class_name %>Channel < ApplicationCable::Channel
   include Hibiki::Rails::Channel
 

data/lib/generators/hibiki/rails/phlex/templates/component.rb.tt

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-# Generated by hibiki:rails:phlex — a working mini-example. The component
-# is a plain Ruby object: Hibiki::Reactive gives it per-instance signals
-# read as ordinary method calls (no .value anywhere), Rerenderable lets
-# the channel's render effect re-render this same instance, and Helpers
-# stamps the client's wire protocol.
+# Generated by hibiki:rails:phlex
 class Components::<%= class_name %> < Phlex::HTML
   include Hibiki::Reactive
   include Hibiki::Phlex::Rerenderable
@@ -14,11 +10,10 @@ class Components::<%= class_name %> < Phlex::HTML
   derived(:doubled) { count * 2 }
 
   def view_template
-    # The root id is the swap key for transmitted fragments — page-unique.
+    # The root id is the swap key for transmitted fragments; keep page-unique.
     div(id: "<%= component_dom_id %>") do
       p { "count: #{count} · doubled: #{doubled}" }
-      # Inside the swapped fragment on purpose: the island's root-scoped
-      # delegation keeps the button working across replacements.
+      # The island's delegation keeps the button working across replacements.
       button(**on(:increment)) { "+1" }
     end
   end

data/lib/generators/hibiki/rails/phlex/templates/island_component.rb.tt

@@ -1,16 +1,14 @@
 # frozen_string_literal: true
 
-# The island wrapper: one channel subscription per render, identified by
-# a per-page-load cid. Render from any page:
-#
+# Generated by hibiki:rails:phlex
+# Render from any page:
 #   <%%= render Components::<%= class_name %>Island.new %>
 class Components::<%= class_name %>Island < Phlex::HTML
   include Hibiki::Rails::Helpers
 
   def view_template
     div(**hibiki_island(<%= class_name %>Channel, cid: SecureRandom.uuid)) do
-      # A throwaway instance as a paint-avoidance placeholder; the
-      # channel's long-lived instance takes over from its first transmit.
+      # Placeholder; the channel takes over from the first transmit.
       render Components::<%= class_name %>.new
     end
   end

data/lib/generators/hibiki/rails/scaffold/USAGE

@@ -8,9 +8,9 @@ Description:
     Everything is derived from the field list you pass, exactly as Rails'
     scaffold derives its own output. Stock `rails g scaffold` is untouched.
 
-    The generated index is live: search, filter, sort and pagination are signal
-    state, edits happen in place, and a write from anywhere — another tab,
-    another user, the plain controller, a console — repaints every open list.
+    The generated index is live: search, filter, sort, and pagination are all
+    reactive, edits happen in place, and changes from anywhere update every open
+    list.
 
 Example:
     bin/rails generate hibiki:rails:scaffold Book title:string author:references
@@ -25,8 +25,12 @@ Example:
         app/forms/book_form.rb
         app/controllers/books_controller.rb
         app/views/books/*
+        app/assets/stylesheets/hibiki_busy.css
     And add to config/routes.rb:
         resources :books
 
-    Restart the server afterwards: Rails computes autoload paths from the
-    app/* glob at boot, and app/forms is new.
+    Restart the server afterwards if it is running — app/forms is new.
+
+    Pass --phlex to emit Phlex components under app/views/books/*.rb instead of
+    ERB templates. The view layer is the only thing it changes; it needs the
+    phlex-rails gem and `bin/rails g phlex:install`.

data/lib/generators/hibiki/rails/scaffold/scaffold_generator.rb

@@ -45,6 +45,8 @@ module Hibiki
         class_option :skip_search, type: :boolean, default: false,
                                    desc: "Omit the search box and the LIKE terms behind it"
         class_option :page_size, type: :numeric, default: 20, desc: "Rows per page"
+        class_option :phlex, type: :boolean, default: false,
+                             desc: "Emit Phlex components under app/views instead of ERB templates"
 
         def initialize(...)
           super

data/lib/generators/hibiki/rails/scaffold_controller/USAGE

@@ -1,21 +1,18 @@
 Description:
-    Generates a reactive CRUD resource for a model that ALREADY exists — the
-    overlay half of hibiki:rails:scaffold.
+    Generates a reactive CRUD resource for a model that already exists.
 
-    With no field list the model's own schema is read: columns and types,
-    belongs_to reflections, and the validators behind per-field live errors.
-    Pass fields explicitly to override that, or when the table has not been
-    migrated yet.
+    With no field list, the model's schema is used to determine columns, types,
+    associations, and validators. Pass fields explicitly to override this or
+    when the table hasn't been migrated yet.
 
-    The generated index is live: search, filter, sort and pagination are signal
-    state, edits happen in place, and a write from anywhere repaints every open
+    The generated index is live: search, filter, sort, and pagination are all
+    reactive, edits happen in place, and changes from anywhere update every open
     list.
 
-    Two models are MODIFIED. This one gets a delegate per belongs_to plus the
-    after_commit broadcast the whole thing hangs off; each model a belongs_to
-    POINTS AT gets the has_many half Rails' scaffold never writes, and a ping,
-    because a row prints the parent's label rather than its id. Both are
-    idempotent, both are announced, and anything already declared is left alone.
+    Two models are MODIFIED. This one gets a delegate for each belongs_to and
+    an after_commit broadcast. The related models get the missing has_many
+    association and a ping so changes are reflected here. Existing declarations
+    are left alone.
 
 Example:
     bin/rails generate hibiki:rails:scaffold_controller Book
@@ -28,7 +25,12 @@ Example:
         app/forms/book_form.rb
         app/controllers/books_controller.rb
         app/views/books/*
+        app/assets/stylesheets/hibiki_busy.css
     And modify:
         app/models/book.rb
         app/models/author.rb   # each model a belongs_to points at
         config/routes.rb
+
+    Pass --phlex to emit Phlex components under app/views/books/*.rb instead of
+    ERB templates. The view layer is the only thing it changes; it needs the
+    phlex-rails gem and `bin/rails g phlex:install`.

data/lib/generators/hibiki/rails/scaffold_controller/scaffold_controller_generator.rb

@@ -8,7 +8,9 @@ require_relative "../scaffold_view_helpers"
 require_relative "../scaffold_model_injection"
 require_relative "../scaffold_parent_injection"
 require_relative "../scaffold_parent_notices"
+require_relative "../scaffold_phlex_helpers"
 require_relative "../scaffold_post_install"
+require_relative "../scaffold_transport_stylesheet"
 require_relative "../scaffold_schema"
 require_relative "../css_variant"
 
@@ -29,10 +31,12 @@ module Hibiki
         include GeneratorHelpers
         include ScaffoldHelpers
         include ScaffoldViewHelpers
+        include ScaffoldPhlexHelpers
         include ScaffoldModelInjection
         include ScaffoldParentInjection
         include ScaffoldParentNotices
         include ScaffoldPostInstall
+        include ScaffoldTransportStylesheet
 
         TEMPLATE_ROOT = File.expand_path("templates", __dir__)
 
@@ -55,6 +59,8 @@ module Hibiki
                                  desc: "Rows per page"
         class_option :skip_routes, type: :boolean,
                                    desc: "Don't add routes to config/routes.rb"
+        class_option :phlex, type: :boolean, default: false,
+                             desc: "Emit Phlex components under app/views instead of ERB templates"
 
         # Deliberately NO check_class_collision on the controller. Rails' own
         # scaffold_controller assumes a brand-new resource; this one's primary
@@ -62,6 +68,13 @@ module Hibiki
         # controller existing is the normal case rather than an error. Thor's
         # per-file conflict prompt is the right granularity for that.
 
+        # First, so a --phlex app missing its wiring reads that at the TOP of
+        # the output rather than under forty created-file lines. It only warns,
+        # so the files are written either way — see ScaffoldPhlexHelpers.
+        def check_phlex_wiring
+          warn_without_phlex_rails
+        end
+
         # Resolving the schema first means a missing model or an unmigrated
         # table aborts before anything is written, rather than half-way through.
         def resolve_schema
@@ -72,6 +85,14 @@ module Hibiki
           @new_app_dirs = %w[app/forms app/channels app/models app/views].reject { exists?(it) }
         end
 
+        # One file per app, not per resource, and the only thing this generator
+        # writes outside app/{channels,models,forms,views,controllers}. It
+        # carries no model knowledge at all — the rules key on the client's
+        # attributes — so a second resource finds it already there.
+        def create_stylesheet
+          create_transport_stylesheet
+        end
+
         def create_channels
           template "channel.rb.tt", collection_channel_path
           template "member_channel.rb.tt", member_channel_path
@@ -91,7 +112,9 @@ module Hibiki
         end
 
         def create_views
-          %w[index show new edit _form _list _controls _field_error _busy].each do |view|
+          return create_phlex_views if phlex?
+
+          %w[index show new edit _form _list _controls _field_error].each do |view|
             template "views/#{view}.html.erb.tt", view_path("#{view}.html.erb")
           end
 
@@ -149,18 +172,48 @@ module Hibiki
 
         private
 
+        # No underscore, no .html.erb, and no _row/_row_form rename: all three
+        # are Rails PARTIAL conventions, and a Phlex component is reached by
+        # constant. Dropping the rename also drops a step — the file is
+        # row.rb because Zeitwerk wants basename.camelize, and calling it
+        # book.rb would put Views::Books::Book one reformat away from shadowing
+        # the model inside its own namespace.
+        #
+        # Private, because a public method on a Thor generator is a command.
+        def create_phlex_views
+          %w[index show new edit form list row row_form controls field_error].each do |view|
+            template "views/#{view}.rb.tt", view_path("#{view}.rb")
+          end
+
+          template "views/pagination.rb.tt", view_path("pagination.rb") unless infinite?
+        end
+
         # Ordered so an app's own lib/templates/... override wins first, then
-        # the per-variant fork, then the one shared template set. Only
-        # _pagination has a per-variant file — a tag-name change under `none`
-        # and a shared-local extraction under `tailwind`, neither of which a
-        # class-token map can express — so everything else falls through to
-        # shared/ and there is exactly one template set to maintain.
+        # the view layer, then the per-variant fork, then the one shared
+        # template set. Only the page control has a per-variant file — a
+        # tag-name change under `none` and a shared-local extraction under
+        # `tailwind`, neither of which a class-token map can express — so
+        # everything else falls through to shared/.
+        #
+        # The two layers' templates never collide (list.rb.tt vs
+        # _list.html.erb.tt), so the phlex roots could have lived beside the
+        # ERB ones. They are a subtree instead because `ls` is where this
+        # phase's permanent cost should be visible: every view change is now
+        # two templates, forever.
         def source_paths
           @source_paths ||= [*self.class.source_paths_for_search,
+                             *phlex_source_paths,
                              File.join(TEMPLATE_ROOT, css_variant.to_s),
                              File.join(TEMPLATE_ROOT, "shared")]
         end
 
+        def phlex_source_paths
+          return [] unless phlex?
+
+          [File.join(TEMPLATE_ROOT, "phlex", css_variant.to_s),
+           File.join(TEMPLATE_ROOT, "phlex", "shared")]
+        end
+
         # Explicit attributes always win, matching Rails' own precedence; the
         # schema decides the column list only when the argument list is empty.
         # That order also happens to be the only workable one, because
@@ -246,6 +299,11 @@ module Hibiki
 
         def infinite? = options[:infinite_scroll]
         def searchable? = schema.searchable? && !options[:skip_search]
+
+        # The view layer. It reaches the templates and nothing else: the graph,
+        # the query object, the form, the actions and the whole data-hibiki
+        # protocol are the same either way.
+        def phlex? = options[:phlex]
       end
     end
   end