senren-ui 0.1.6 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58a8b09eaa25d57baa0dded24c204b71ba71addac1acf81ae27e08e148d39c06
-  data.tar.gz: 04b5733b08a0dfb54192e35c57bc289800988d9254a7c4ee1fcb6d66520299ee
+  metadata.gz: d99681351df1dad873d945bf82b3070b3f8393c9d14b3ca65917262e6258ef6c
+  data.tar.gz: b487d9ac589b1d9ba2c304a5f53e4d93064b321d76e97a43ccfa1b9909a44b58
 SHA512:
-  metadata.gz: 424219c05372db86c1df17e5274b5432b8fab5fbe82318fc760c7e23e3bd18beec2757e94abe5f2e21e788bd3326b5f2011c7554cb738192c5aca62588d5cf53
-  data.tar.gz: a517a125cb116c79c86094561f59e50b3c54d8ba29f0cdfde8a188b205b504ff1742ac2e14541996fb78fbcfe9a5e74152ba91de47293b3cea45c198373dd803
+  metadata.gz: f383e88dea3c90da1f1f93831bdf26c4bc5e00e1c63ffeb8ae53031d7c7e38c8afbaa30c445839cdbf8ad346acf247dcd04ae597c01b23704837daeb4eb4c2bf
+  data.tar.gz: 54e1f4ad10351c05906cdf1f864160cd3a0555e1698c0fa4944a728752cd97560300a9bae40a337a214a39d19eae87a3620fd4690e412d689b9430d022df0662

data/CHANGELOG.md

@@ -7,6 +7,110 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 v0.x is a pre-stable line: minor bumps may break things; patch bumps are
 bug fixes only.
 
+## [0.2.0] — 2026-08-02
+
+A hardening release. Most of it came out of an adversarial review of the whole
+library; each item below was reproduced by running it before being fixed, and
+pinned by a test that was watched failing first.
+
+### Upgrading
+
+Four changes alter existing behaviour. None requires a code change in your app,
+but read these before upgrading:
+
+- **`class:` now merges instead of replacing.** Previously
+  `ButtonComponent.new(variant: :primary, class: "mt-2")` rendered
+  `class="mt-2"` and dropped the variant and size styling entirely. It now
+  renders both. If you worked around the old behaviour by re-specifying every
+  utility, you can stop.
+- **DOM ids are derived from component arguments, not random.** Ids are now
+  stable across renders, which is what makes Turbo morphing, fragment caching,
+  and ETags work. If you hard-coded a generated id in a test or a stylesheet,
+  it will have changed.
+- **Booting with `app/components` on the asset load path now fails in
+  production.** See *Security* below. If you added that line for sidecar
+  assets, point it at `app/components/assets` instead.
+- **`Senren::Rails::Installer` was removed.** It had no callers, and copying
+  `.tt` templates without rendering them would have written raw ERB into a host
+  app. `senren:install` is the supported path.
+
+### Added
+
+- `CartComponent` and `ProductCardComponent`, plus a `storefront` recipe.
+  The cart keeps a live subtotal and quantity steppers client-side and
+  announces changes with `senren--cart:changed`; the product tile submits a
+  form and ships no JavaScript, so listing pages stay light.
+- `lib/senren-ui.rb`, so `gem "senren-ui"` loads the engine without a
+  `require:` option. Previously that form silently loaded nothing — no engine,
+  no rake tasks, and no asset guard — while the generator kept working.
+- On-demand Stimulus loading, installed rather than documented.
+  `senren:install` switches `controllers/index.js` to `lazyLoadControllersFrom`
+  and adds `preload: false` to the controllers pin. It leaves a customised
+  `index.js` or a non-importmap app alone and reports what it did.
+- `bin/watch`, which syncs template edits into the local preview app and
+  reloads the browser. Development-only; nothing ships to host apps.
+- A Ruby 3.2–3.4 × Rails 7.1–8.1 test matrix, so the versions the gemspec
+  claims are the versions that are proved.
+
+### Changed
+
+- Overlay components (dialog, sheet, popover, dropdown, context menu, alert
+  dialog) drive their state through Stimulus values instead of writing to the
+  DOM directly, so state survives Turbo morphs.
+- `--client` / `--no-client` applies only to the components you name.
+  It used to apply to the whole dependency closure, so
+  `senren:add context_menu --no-client` also stripped `dropdown_menu`'s
+  controller and the installed menu silently never opened.
+- `.senren/skill.md` describes what was actually installed. It previously
+  reported the registry default, naming controller files that were not on disk.
+- `.senren/registry.yml` refreshes on every install instead of drifting from
+  the gem after the first one.
+- Rake helpers live in `SenrenRakeArgs` rather than as top-level methods on
+  `Object`, and argument scanning stops at the next rake task —
+  `rake 'senren:add[button]' db:seed` no longer tries to install `db:seed`.
+- Documentation states the library's scope without characterising other
+  ecosystems.
+
+### Security
+
+- **Component source could be published in production.** With
+  `config.assets.paths << Rails.root.join("app/components")` — a line that
+  circulates as ViewComponent sidecar-asset guidance — Propshaft resolved every
+  component `.rb` and `.html.erb` as an asset, `assets:precompile` copied them
+  into `public/assets`, `.manifest.json` listed each by name, and the digested
+  URL returned Ruby source with `HTTP 200`. A boot check now raises in any
+  deployed environment and warns in development. Sidecar assets in their own
+  directory are unaffected.
+- **The installer could write outside the application root.** A checkout
+  shipping `app/components/senren` as a symlink redirected copied files, and
+  the agent-adapter writers read their destination before rewriting it, so
+  content outside the checkout was modified too. All writes now go through one
+  containment layer that resolves symlinks, covers dangling links, and refuses
+  only paths that leave the root — an in-repo symlink such as
+  `ln -s AGENTS.md CLAUDE.md` keeps working.
+- **`FormComponent#url` and `AvatarComponent#src` were unsanitised.** The first
+  reaches `form_with`'s action, where a protocol-relative URL sends every field
+  and the CSRF token off-origin. Both now use the same URL policy as the rest
+  of the library, and a property test covers every component rather than a list
+  of known ones.
+- Rich-text paste is sanitised, and the two URL policies (markup versus typed
+  input) are separated so neither can promote a relative path to another origin.
+- Five dependency advisories resolved, and `bundler-audit` is now a CI gate.
+
+### Fixed
+
+- `senren:doctor` reported success unconditionally.
+- Marker-managed files could be corrupted by generated content containing
+  regexp backreferences, and could inject their own markers.
+- `TypographyComponent`, `SeparatorComponent`, and `AspectRatioComponent`
+  raised on `.new` without an explicit variant.
+- `data:` passed to any component dropped its `data-senren-component` marker.
+- Eight components produced a new DOM id on every render.
+- `date_picker` lost its height to a fused CSS class.
+- Stimulus controllers no longer leak timers or document-level listeners across
+  Turbo navigations.
+- Checkbox, radio, and switch controls are reachable by their accessible name.
+
 ## [0.1.6] — 2026-06-09
 
 ### Added

data/CONTRIBUTING.md

@@ -20,13 +20,32 @@ git clone <repo>
 cd senren-ui
 bundle install
 bun install
-bundle exec rake test
-bin/system
-bin/performance
+bin/ci             # every gate, reports all failures rather than the first
+bin/ci --matrix    # additionally run the Rails 7.1-8.1 matrix (slow)
+```
+
+Individual gates, if you want to run one in isolation:
+
+```bash
+bin/test                              # unit tests (no Rails app booted)
+bundle exec rake test:integration     # renders all 62 components via test/dummy
+bin/system                            # headless browser tests
+bin/performance                       # payload and runtime budgets
+bin/matrix                            # unit tests on every supported Rails
 bundle exec rubocop
+bundle exec bundle-audit check --update
 bun run controllers:check
 ```
 
+`bin/system` needs no setup: it uses a system Chrome and
+`/usr/bin/chromedriver` when present, and otherwise lets Selenium Manager
+fetch a matching driver.
+
+Supported versions are proved, not asserted. `gemfiles/rails_*.gemfile` drive
+the matrix via `BUNDLE_GEMFILE`, CI runs Ruby 3.2-3.4 × Rails 7.1-8.1 with
+`fail-fast: false`, and `test/gem_packaging_test.rb` fails if the gemspec's
+floors drift out of that matrix.
+
 To exercise the gem against a local host app inside this repo:
 
 ```bash
@@ -38,6 +57,17 @@ bin/rails server
 # SENREN_PREVIEW_ROOT=/abs/path/to/your/preview-app bin/seed_preview
 ```
 
+While the server runs, start the watcher from the gem root in another
+terminal so template edits appear without re-seeding:
+
+```bash
+bin/watch
+```
+
+It copies changed files from `templates/` and `registry/` into the preview
+app and reloads the browser. See `docs/hot_reload.md` for what does and does
+not reload.
+
 The local preview uses Tailwind's browser runtime for convenience. The
 real documentation/reference app is maintained separately in
 `senren-ui-page`.
@@ -61,6 +91,10 @@ real documentation/reference app is maintained separately in
   (`app/javascript/controllers/senren/<name>_controller.js`).
 - Component test in `test/components/`.
 - System test in `test/system/` if interactive.
+- Nothing extra is needed for render coverage: `test/integration/` renders
+  every registered component in every declared variant and size, driven
+  from the registry, so a new component is covered as soon as it has a
+  preview in `ComponentPreviewHelper`.
 - Registry entry in `registry/components.yml` (full schema).
 - Skill block produced by `SkillWriter`.
 - Demo usage in `.local/preview` if relevant to the local preview UI.
@@ -69,6 +103,9 @@ real documentation/reference app is maintained separately in
 
 - One logical change per commit.
 - Mention the affected plan and history files in the commit body.
+- Run `bin/ci` before pushing.
+- Run `bin/ci --matrix` if you touched the gemspec, the Gemfile, or anything
+  version sensitive.
 - Run `bundle exec rake test` before pushing.
 - Run `bin/system` before pushing if you touched component templates,
   Stimulus controllers, or the dummy preview app.

data/README.md

@@ -1,6 +1,6 @@
 # Senren UI (`senren-ui`)
 
-> 洗練 — refined, polished, sophisticated.
+> 洗練 *(senren)* — Japanese for "refinement".
 
 **[Live Docs & Component Reference → senren-ui.dev](https://www.senren-ui.dev)**
 
@@ -16,12 +16,19 @@ skill system and a source-copy install model inspired by shadcn/ui.
   every installed component, its dependencies, and its anti-patterns.
 - A multi-agent instruction sync for Codex, Claude, Copilot, and Cursor.
 
-## What Senren is not
+## Scope
 
-- Not React, Vue, Alpine, or any external state framework.
-- Not a CSS-only kit — components ship Ruby + ERB + (optional) Stimulus.
-- Not an opaque dependency — installed components live in your app
-  under `app/components/senren/` and you own them.
+Senren renders on the server. Components are ViewComponent classes with ERB
+templates, interactivity is Stimulus, and server state is Turbo's job. It is
+not a client-side rendering layer: if your app is built around React, Vue, or
+another client framework, a component library from that ecosystem will fit it
+better than this one.
+
+Two other things worth knowing up front:
+
+- Components ship as Ruby + ERB + optional Stimulus, not as a CSS-only kit.
+- They are copied into your app under `app/components/senren/`, so they are
+  yours to read and edit rather than an opaque dependency.
 
 ## Installation
 
@@ -60,32 +67,87 @@ bin/rails senren:agents:sync                # rebuild .senren/agent-rules + adap
 bin/rails senren:doctor                     # check installation health
 ```
 
+### What reloads while you work
+
+Components copied into your app are ordinary Rails code, so editing a
+`*_component.rb` or `*.html.erb` takes effect on the next request with no
+restart. The exception is Stimulus: a controller under
+`app/javascript/controllers/senren/` is a module the browser has already
+fetched, so editing it needs a page reload — the server does not need
+restarting. `docs/hot_reload.md` has the details, including Turbo morphing.
+
 ## Keeping Stimulus JavaScript small
 
-Senren copies only installed client controllers into your Rails app, but an
-Importmap app can still download every controller on initial page load if it
-keeps the default eager Stimulus loader and preload configuration. Once your
-app has several interactive components, switch Stimulus to lazy loading:
+`bin/rails generate senren:install` wires on-demand controller loading for
+you. It switches `app/javascript/controllers/index.js` from Rails' default
+`eagerLoadControllersFrom` to `lazyLoadControllersFrom`, and adds
+`preload: false` to the controllers pin in `config/importmap.rb`.
+
+Without it, an Importmap app downloads **every** controller on **every** page.
+`pin_all_from "app/javascript/controllers"` is recursive, so it covers
+`app/javascript/controllers/senren` too — a static marketing page paid for the
+rich text editor. With it, a module is fetched the first time its
+`data-controller` identifier appears, including markup Turbo inserts later.
+
+Two things worth knowing:
+
+- It changes loading for **your** controllers as well, because it uses the
+  official `stimulus-loading` helper rather than a Senren-specific loader.
+  Lazy loading is the better default for almost every app, but it is your
+  call — the generator only edits the file while it still carries the
+  untouched Rails default, and reports what it did.
+- If you have already customised `index.js`, or you bundle with esbuild or
+  Vite instead of Importmap, the generator leaves it alone and says so.
+
+This used to be a paragraph asking you to do it by hand, and a CI check that
+passed as long as the paragraph existed. It is now installed and asserted in
+`test/generators/install_generator_test.rb` against the files `rails new`
+actually produces.
+
+## Component source in production
 
-```javascript
-// app/javascript/controllers/index.js
-import { application } from "controllers/application"
-import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
+Senren copies editable ViewComponent, ERB and Stimulus source into your app.
+That is the point of the design, and it means minification and source maps are
+your app's decision, not the gem's — Senren ships readable source and gets out
+of the way.
 
-lazyLoadControllersFrom("controllers", application)
+Readable in your repo is not the same as readable over HTTP, and there is one
+configuration that turns the first into the second:
+
+```ruby
+# config/initializers/assets.rb — do NOT do this
+Rails.application.config.assets.paths << Rails.root.join("app/components")
 ```
 
-Disable import-map preloading for those on-demand controller modules:
+That line appears in guidance about ViewComponent sidecar assets, and under
+Propshaft it publishes the whole directory. Reproduced against Propshaft 1.3.2:
+every `.rb` and `.html.erb` under `app/components` was resolved as an asset,
+`RAILS_ENV=production rails assets:precompile` copied them into `public/assets`,
+`public/assets/.manifest.json` listed each one next to its digested filename —
+so the digest is not a secret — and requesting the digested URL returned the
+Ruby source with `HTTP 200`, served by the web server without Rails involved.
+
+Senren refuses to let this ship. A boot check runs after your initializers:
+
+- **production** — raises, so the app does not boot and `assets:precompile`
+  fails. A failed deploy is recoverable; published source is not.
+- **anywhere else** — prints a warning and carries on, because development is a
+  different risk calculation.
+
+It only objects when component source actually sits under an asset path, so
+sidecar assets remain available — put them in their own directory:
 
 ```ruby
-# config/importmap.rb
-pin_all_from "app/javascript/controllers", under: "controllers", preload: false
+Rails.application.config.assets.paths << Rails.root.join("app/components/assets")
 ```
 
-This keeps controllers mapped and usable while loading each module only when
-its `data-controller` identifier appears in the page. Minification or source
-maps are an application build/deployment decision; Senren deliberately ships
-editable source controllers into the host app.
+The default configuration is unaffected: with no such line, every component
+path returns `404`. The gem itself adds no production request-path code, and
+this check is the sole exception.
+
+See `test/asset_path_guard_test.rb` and
+`test/integration/asset_path_guard_boot_test.rb`, which boot a real Rails app
+with a real Propshaft and assert that precompile cannot publish source.
 
 ## Using a component
 
@@ -150,7 +212,7 @@ generated block and preserves your existing instructions outside that block.
 
 ## Component list
 
-See `registry/components.yml` for the canonical list. v0.1 ships:
+See `registry/components.yml` for the canonical list. Currently shipping:
 
 - **Phase 1 — Foundation** (full): Button, Link, Badge, Typography,
   Separator, Skeleton, Avatar, Alert, Card, AspectRatio.
@@ -183,19 +245,34 @@ See `CONTRIBUTING.md`. Two rules to know up front:
 2. Architectural decisions are captured in `plans/` before code is
    written.
 
-## Open source maintenance baseline
+## Project health
+
+Every push runs the test suite, RuboCop, and the JavaScript checks against
+Ruby 3.2–3.4 × Rails 7.1–8.1. CodeQL scans Ruby and JavaScript, and Dependabot
+tracks Bundler, JS tooling, and Actions.
+
+Security reports go to `SECURITY.md`.
+
+## Acknowledgements
 
-This repo ships with a GitHub baseline for safer public maintenance:
+Senren builds on ideas from prior art. No source code from either project is
+included here — the influence is on architecture and developer experience, and
+both are credited because ideas have authors even when licences do not require
+the notice.
 
-- CI on pull requests and `main` pushes for tests, RuboCop, and JS checks.
-- CodeQL analysis for Ruby and JavaScript.
-- Dependabot updates for Bundler, JS tooling, and GitHub Actions.
-- PR and issue templates, `CODEOWNERS`, `CODE_OF_CONDUCT.md`, and
-  `SECURITY.md`.
+- [shadcn/ui](https://github.com/shadcn-ui/ui) (MIT) — the source-copy install
+  model: components are copied into your app so you own and can edit them,
+  rather than being rendered from inside a dependency.
+- [jetrockets/jet_ui](https://github.com/jetrockets/jet_ui) (MIT, © 2026
+  JetRockets) — a Rails/ViewComponent UI library whose maintainers write openly
+  about the trade-offs they worked through. That writing informed
+  `plans/022_jet_ui_lessons.md`: how Tailwind's content scanning interacts with
+  components shipped from inside a gem, and the case for testing every Ruby and
+  Rails version a gem claims to support. Both points made this library better.
 
-Repository controls such as branch protection, required checks, release
-permissions, and auto-delete branch still need to be enabled in GitHub
-repository settings.
+Both are MIT licensed, which permits use, modification, and study. The MIT
+notice requirement attaches to copies of the software; since Senren copies no
+code from either, this section is attribution rather than a licence obligation.
 
 ## License
 

data/Rakefile

@@ -6,11 +6,24 @@ require 'rake/testtask'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.libs << 'lib'
-  t.test_files = FileList['test/**/*_test.rb'].exclude('test/system/**/*_test.rb')
+  t.test_files = FileList['test/**/*_test.rb']
+                 .exclude('test/system/**/*_test.rb')
+                 .exclude('test/integration/**/*_test.rb')
   t.warning = false
 end
 
 namespace :test do
+  # Separate process, like system tests, and for the same reason: the unit
+  # suite `load`s component classes directly, and booting the dummy app would
+  # load them a second time. ViewComponent 4 raises RedefinedSlotError on the
+  # duplicate declaration.
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << 'test'
+    t.libs << 'lib'
+    t.test_files = FileList['test/integration/**/*_test.rb']
+    t.warning = false
+  end
+
   Rake::TestTask.new(:system) do |t|
     t.libs << 'test'
     t.libs << 'lib'

data/docs/components.md

@@ -51,20 +51,20 @@ Wraps `form_with` with Senren semantic tokens and consistent spacing.
 <% end %>
 ```
 
-> **Warning**: Do NOT pass `method: :post` on edit forms for persisted models.
-> Rails needs `method:` to be nil to infer PATCH, otherwise you'll get
-> `No route matches [POST] "/resource/:id"`.
+Leave `method:` unset on edit forms for persisted models. Rails needs it to be
+`nil` to infer `PATCH`; passing `method: :post` produces
+`No route matches [POST] "/resource/:id"`.
 
 ---
 
 ## InputComponent
 
-### ⚠️ InputComponent vs `form.text_field`
+### InputComponent vs `form.text_field`
 
 **`InputComponent` renders its own `<input>` tag.** It is a **replacement** for
 `form.text_field`, not an add-on. Do not combine them.
 
-#### ✅ Do
+#### Use one or the other
 
 ```erb
 <%# Option A: Use InputComponent standalone %>
@@ -74,10 +74,10 @@ Wraps `form_with` with Senren semantic tokens and consistent spacing.
 <%= f.text_field :email, class: "your-input-classes" %>
 ```
 
-#### ❌ Do NOT
+#### Not both together
 
 ```erb
-<%# WRONG: This renders two inputs %>
+<%# This renders two inputs %>
 <%= render(Senren::InputComponent.new(name: "email")) do %>
   <%= f.text_field :email %>
 <% end %>
@@ -209,14 +209,14 @@ dedicated `FormFieldComponent` ships, use this pattern:
 Always use **parentheses** around `render` when passing an inline content block:
 
 ```erb
-<%# ✅ Correct: parens around render %>
+<%# Correct: parens around render %>
 <%= render(Senren::ButtonComponent.new(variant: :primary)) { "Save" } %>
 
-<%# ✅ Correct: do/end block %>
+<%# Correct: do/end block %>
 <%= render Senren::ButtonComponent.new(variant: :primary) do %>
   Save
 <% end %>
 
-<%# ❌ Wrong: block attaches to .new, not render %>
+<%# Wrong: the block attaches to .new, not to render %>
 <%= render Senren::ButtonComponent.new(variant: :primary) { "Save" } %>
 ```

data/docs/hot_reload.md

@@ -0,0 +1,103 @@
+# Hot reload
+
+What reloads automatically, what does not, and why — for both people working
+on the gem and people using it in an app.
+
+## Working on the gem
+
+`templates/` is the source of truth, and the preview app under `.local/preview`
+holds *copies* made by `bin/seed_preview`. Editing a template therefore has no
+effect on the running preview until the copy is refreshed. `bin/watch` closes
+that gap.
+
+```bash
+bin/seed_preview                       # once
+cd .local/preview && bin/rails server  # terminal 1
+bin/watch                              # terminal 2, from the gem root
+```
+
+With both running, editing `templates/components/button/button_component.html.erb`
+copies that one file into the preview app and the browser reloads within about
+a second.
+
+What each kind of edit does:
+
+| You edit | `bin/watch` does | Result |
+|---|---|---|
+| `templates/components/<name>/*` | copies the one file | page reloads |
+| `templates/controllers/*.js` | copies the one controller | page reloads |
+| `registry/*.yml` | full reinstall of every component | page reloads |
+| `lib/generators/senren/install/templates/*.tt` | copies to its host path | page reloads |
+| `lib/**/*.rb` | nothing | restart `bin/watch` and the server |
+
+`lib/` is deliberately not watched: changing gem internals requires restarting
+the Ruby process, which a file copy cannot do.
+
+`installed_components.yml.tt` is never synced. That file is a *template* for a
+ledger, and the ledger in the preview app is state — copying over it would
+erase the install history.
+
+Options:
+
+- `SENREN_PREVIEW_ROOT` — watch a preview app somewhere else. Matches
+  `bin/seed_preview`.
+- `SENREN_WATCH_INTERVAL` — poll interval in seconds, default `0.5`.
+
+### How the browser reload works
+
+`bin/watch` writes a timestamp to `tmp/senren-reload.txt` after every sync. The
+preview layout polls `/senren/reload_token` twice a second and calls
+`location.reload()` when the value changes.
+
+This exists because Rails only reloads *Ruby and ERB*. A Stimulus controller is
+JavaScript already delivered to the browser: syncing the file changes nothing
+until the page is reloaded and the module is fetched again. The token is what
+makes controller edits feel hot.
+
+There is no websocket, no ActionCable, and no extra gem — deliberately, since
+the whole plumbing exists only in the gitignored `.local/preview` app and must
+never reach a published gem or a host app.
+
+### Manual check
+
+Automated tests cover the path-mapping logic (`test/template_sync_test.rb`).
+The polling loop itself is verified by hand:
+
+1. Start the server and `bin/watch`.
+2. Change a colour class in a component template — the page reloads with the
+   new style.
+3. Add a `console.log` to a controller — the page reloads and the log appears.
+4. Add a component to `registry/components.yml` — the watcher reports a full
+   reinstall and the new component renders.
+
+## Using the gem in your app
+
+After `bin/rails senren:add`, the components are yours. Rails handles most of
+the reloading, so there is little for Senren to add:
+
+| You edit | Reloads? |
+|---|---|
+| `app/components/senren/*.rb` | Yes — Rails reloads on the next request |
+| `app/components/senren/*.html.erb` | Yes — same |
+| `app/assets/stylesheets/senren.css` | Yes, once Tailwind rebuilds |
+| `app/javascript/controllers/senren/*.js` | **No** — needs a page reload |
+
+The Stimulus row is the one to know about. With importmap the controller is a
+module the browser has already fetched, so editing it does nothing until you
+reload the page. In development Propshaft serves the new file immediately, so
+an ordinary refresh is enough — you do not need to restart the server or clear
+a cache.
+
+If you want that refresh automated, the usual choice is the `hotwire-livereload`
+gem in your own `Gemfile`. Senren does not ship one, because doing so would put
+a development dependency and a websocket into every app that installs a
+component library.
+
+### Turbo morphing
+
+If your app uses Turbo 8 page morphing, a morph can move or replace the element
+a controller is attached to, which triggers `disconnect()` and `connect()`.
+Senren controllers clean up their document-level listeners in `disconnect()`,
+so they survive repeated morphs. If you write your own controller, do the same:
+anything you add to `document` or `window` in `connect()` or on open must be
+removed in `disconnect()`, or it will accumulate on every navigation.

data/docs/performance_testing.md

@@ -16,9 +16,13 @@ bin/ci
 `bin/performance` reads `config/performance_budgets.yml`.
 `bin/system` runs headless browser tests against `test/dummy`.
 
-`bin/system` uses Selenium with local Chromium/ChromeDriver by default.
-Override paths with `SENREN_CHROME_BIN` and `SENREN_CHROMEDRIVER` if your
-machine installs them somewhere else.
+`bin/system` runs Selenium against headless Chrome. It uses a system
+Chrome/Chromium and `/usr/bin/chromedriver` when they are present (the Linux CI
+image), and otherwise lets Selenium Manager resolve and download a matching
+driver — so macOS and other local machines need no setup.
+
+Set `SENREN_CHROME_BIN` or `SENREN_CHROMEDRIVER` only to force a specific
+binary; leaving them unset is the supported path.
 
 ## Benchmark Model
 

data/lib/generators/senren/component/templates/controller.js.tt

@@ -3,11 +3,14 @@ import { Controller } from "@hotwired/stimulus"
 // Stimulus controller for Senren <%= class_name %>.
 // Identifier: <%= stimulus_identifier %>
 //
-// Responsibilities (local UI only):
+// Scope — local UI only:
 // - Manage open/close, focus, or keyboard behavior for this component.
-// Forbidden:
-// - fetch / XHR (Turbo handles server state)
-// - importing React, Vue, Alpine, lit, or any other framework
+//
+// Out of scope:
+// - fetch / XHR. Turbo owns server state; a controller that fetches ends up
+//   holding a second copy of it.
+// - Importing a client-side rendering framework. This component's markup comes
+//   from the server, so a second renderer would be fighting it for the DOM.
 export default class extends Controller {
   static targets = []
   static values  = {}