senren-ui 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 82671c3e673cf8cf9d922e83685d72bf5448b9acb1073596a9643f3da6fc9c15
-  data.tar.gz: 11691be1d0c35c8137aab34d0cb7ede42dc2b7a9f9d7f4cfa9b7a8b8acb1ba3e
+  metadata.gz: 58a8b09eaa25d57baa0dded24c204b71ba71addac1acf81ae27e08e148d39c06
+  data.tar.gz: 04b5733b08a0dfb54192e35c57bc289800988d9254a7c4ee1fcb6d66520299ee
 SHA512:
-  metadata.gz: 52d5185842e8b35d4d3c6b2b9e3ec0015e1e09e436a830434f32a4f7fe64d846ba301c90d0229243a672cbfcc140e5104de5aef610ee8d33bc666414a08d83ee
-  data.tar.gz: eaf517da0a216f79d74fa6bbd25873f4f510b283a4fcb0b948f60a0dc9a6966c9e09e7cfd4d55987eaefc7d0600fd8bc90170b1b278a9afb8ca71fec875d34bf
+  metadata.gz: 424219c05372db86c1df17e5274b5432b8fab5fbe82318fc760c7e23e3bd18beec2757e94abe5f2e21e788bd3326b5f2011c7554cb738192c5aca62588d5cf53
+  data.tar.gz: a517a125cb116c79c86094561f59e50b3c54d8ba29f0cdfde8a188b205b504ff1742ac2e14541996fb78fbcfe9a5e74152ba91de47293b3cea45c198373dd803

data/CHANGELOG.md

@@ -7,6 +7,53 @@ 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.1.6] — 2026-06-09
+
+### Added
+
+- Local preview app now seeds the full registered Senren component set and renders an exhaustive component kitchen sink.
+
+### Changed
+
+- `bin/seed_preview` is now the canonical local preview seed command and targets `.local/preview`.
+- `bin/seed_preview` writes a local-path gem entry that works for custom preview roots.
+- `.rubocop.yml` target Ruby version now matches the gem runtime floor required by ViewComponent 4.x.
+
+### Fixed
+
+- `safe_url` now accepts same-origin relative URLs such as `?page=:page`, `./settings`, and `settings` while still rejecting unsafe schemes and hosts.
+- `ComponentCopier` applies the same URL rules when patching existing host apps.
+- Local preview layout keeps the Tailwind browser compiler enabled so the preview renders correctly out of the box.
+
+## [0.1.5] — 2026-05-03
+
+### Added
+
+- Multi-agent instruction sync system (`AgentRulesWriter`). A single
+  source-of-truth file (`.senren/agent-rules.md`) plus marker-managed
+  adapter files for Codex (`AGENTS.md`), Claude (`CLAUDE.md`),
+  Copilot (`.github/copilot-instructions.md`), and Cursor
+  (`.cursor/rules/senren.mdc`).
+- New rake task `senren:agents:sync`.
+- Plan 014 and Plan 015 documentation.
+
+### Changed
+
+- `LlmsWriter` is now a thin backward-compatible wrapper that delegates
+  to `AgentRulesWriter`. No more `public/llms*.txt` generation.
+- `senren:llms:generate` kept as deprecated alias.
+- `Doctor` checks now validate agent instruction files instead of
+  `public/llms*.txt`.
+- Doctor `run!` refactored into `runtime_checks` + `installation_checks`.
+- Install generator no longer creates `public/` directory.
+
+### Fixed
+
+- Deprecated `senren:llms:generate` task now passes `registry:` kwarg
+  consistently with all other call sites.
+- Release checklist items updated to reflect agent sync system.
+- Test assertion style standardized on Minitest-native `refute`.
+
 ## [0.1.4] — 2026-05-02
 
 ### Fixed
@@ -50,7 +97,7 @@ bug fixes only.
 - Tailwind design-token stylesheet (`senren.css`) with light/dark.
 - Centralized `.senren/skill.md` system with preserved user-region.
 - `public/llms.txt` and `public/llms-full.txt` generation.
-- `apps/todolist` Rails app dogfooding the gem via local path.
+- A Rails dogfooding app for local-path gem integration.
 - Bun-based JS tooling for Stimulus templates:
   - `bun run controllers:syntax`
   - `bun run controllers:lint`
@@ -79,4 +126,4 @@ bug fixes only.
 ## [0.1.0] — 2026-04-27
 
 First tagged release once the Unreleased entries are validated end-to-end
-in `apps/todolist` per `plans/011_release_checklist.md`.
+against the project dogfooding app per `plans/011_release_checklist.md`.

data/CONTRIBUTING.md

@@ -17,24 +17,31 @@ this file before opening a PR.
 
 ```bash
 git clone <repo>
-cd senren-rails
+cd senren-ui
 bundle install
 bun install
 bundle exec rake test
+bin/system
+bin/performance
+bundle exec rubocop
 bun run controllers:check
 ```
 
-To exercise the gem against a real Rails app, use the bundled workspace:
+To exercise the gem against a local host app inside this repo:
 
 ```bash
-cd ../apps/todolist
-bundle install
-bin/rails db:setup
-bin/rails generate senren:install
-bin/rails senren:add button card badge alert
+cd /path/to/senren-ui
+bin/seed_preview
+cd .local/preview
 bin/rails server
+# optional custom path:
+# SENREN_PREVIEW_ROOT=/abs/path/to/your/preview-app bin/seed_preview
 ```
 
+The local preview uses Tailwind's browser runtime for convenience. The
+real documentation/reference app is maintained separately in
+`senren-ui-page`.
+
 ## What to forbid in PRs
 
 - React, Vue, Alpine, lit, or any other JS framework dependency.
@@ -56,12 +63,38 @@ bin/rails server
 - System test in `test/system/` if interactive.
 - Registry entry in `registry/components.yml` (full schema).
 - Skill block produced by `SkillWriter`.
-- Demo usage in `apps/todolist` if relevant to the Todo UI.
+- Demo usage in `.local/preview` if relevant to the local preview UI.
 
 ## Commit hygiene
 
 - One logical change per commit.
 - Mention the affected plan and history files in the commit body.
 - Run `bundle exec rake test` before pushing.
+- Run `bin/system` before pushing if you touched component templates,
+  Stimulus controllers, or the dummy preview app.
+- Run `bundle exec rubocop` before pushing.
+- Run `bin/performance` before pushing if you touched component
+  templates, Stimulus controllers, or Importmap loading guidance.
 - Run `bun run controllers:check` before pushing if you touched
   `templates/controllers/*.js`.
+
+## Pull request workflow
+
+1. Fork the repo and branch from `main`.
+2. Keep each PR scoped to one logical change.
+3. If the change is architectural, add or update a matching `plans/`
+   entry first.
+4. Before opening the PR, add or update the matching `history/` file.
+5. Fill in the PR template with exact validation commands and results.
+
+## Security workflow
+
+- Do not report vulnerabilities in public issues.
+- Use GitHub Security Advisories or the contact in `SECURITY.md`.
+- Do not commit API keys, credentials, or private tokens, even in tests
+  or screenshots.
+- Do not pass untrusted URLs directly to component `href`/`src`
+  attributes. Use the shared `safe_url` / `safe_media_url` helpers.
+- Do not use `raw`, `html_safe`, `innerHTML =`,
+  `insertAdjacentHTML`, `eval`, direct SQL APIs, or string-built SQL.
+  The security tests intentionally fail on these escape hatches.

data/README.md

@@ -14,8 +14,7 @@ skill system and a source-copy install model inspired by shadcn/ui.
 - A registry of well-tested ViewComponents and Stimulus controllers.
 - A centralized `.senren/skill.md` file so AI coding agents understand
   every installed component, its dependencies, and its anti-patterns.
-- An `llms.txt` / `llms-full.txt` generator so AI agents can discover
-  Senren without scraping your codebase.
+- A multi-agent instruction sync for Codex, Claude, Copilot, and Cursor.
 
 ## What Senren is not
 
@@ -43,6 +42,10 @@ bin/rails senren:add button card badge alert form input \
   textarea native_select table dropdown_menu dialog alert_dialog
 ```
 
+`senren:add` also works via `bundle exec rails senren:add ...`. The older
+bracketed Rake task form, `bin/rails 'senren:add[button,card]'`, remains
+supported for backward compatibility.
+
 ## Daily commands
 
 ```bash
@@ -51,11 +54,39 @@ bin/rails generate senren:component picker --client  # custom component with Sti
 bin/rails generate senren:component picker --no-client  # without Stimulus
 bin/rails senren:add dialog --client        # install interactive official component
 bin/rails senren:add button                 # install static official component
+bundle exec rails senren:add form input     # equivalent alternate entry point
 bin/rails senren:skill:sync                 # rebuild .senren/skill.md
-bin/rails senren:llms:generate              # rebuild public/llms*.txt
+bin/rails senren:agents:sync                # rebuild .senren/agent-rules + adapters
 bin/rails senren:doctor                     # check installation health
 ```
 
+## 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:
+
+```javascript
+// app/javascript/controllers/index.js
+import { application } from "controllers/application"
+import { lazyLoadControllersFrom } from "@hotwired/stimulus-loading"
+
+lazyLoadControllersFrom("controllers", application)
+```
+
+Disable import-map preloading for those on-demand controller modules:
+
+```ruby
+# config/importmap.rb
+pin_all_from "app/javascript/controllers", under: "controllers", preload: false
+```
+
+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.
+
 ## Using a component
 
 ```erb
@@ -74,17 +105,27 @@ bin/rails senren:doctor                     # check installation health
 
 ## Workspace layout
 
-This repository ships as a workspace with a real Rails dogfooding app:
+This repository ships as a gem source checkout with a git-ignored local
+preview host:
 
 ```text
-senren-workspace/
-  senren-rails/        # the local gem source directory
-  apps/
-    todolist/          # real Rails app that uses senren-ui via local path
+senren-ui/
+  .local/
+    preview/           # local Rails preview host, ignored by git
+```
+
+Use `bin/seed_preview` to create or refresh `.local/preview`. It
+installs a small Senren component preview route, imports `senren.css`,
+and loads Tailwind's browser runtime for local visual checks.
+
+```bash
+bin/seed_preview
+cd .local/preview
+bin/rails server
 ```
 
-`apps/todolist` is the production-like acceptance test for Senren — a
-small SaaS-style Todo manager built entirely from Senren components.
+The full documentation/reference site lives outside this gem checkout in
+`senren-ui-page`.
 
 ## AI Agent skill system
 
@@ -96,12 +137,17 @@ After install, your app contains:
 - `.senren/registry.yml` — mirror of the gem-side registry.
 - `.senren/installed_components.yml` — ledger of installed components.
 - `.senren/conventions.md` — Senren conventions for humans and agents.
-- `public/llms.txt`, `public/llms-full.txt` — discoverable AI summary.
+- `.senren/agent-rules.md` — source of truth for generated agent rules.
+- `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`,
+  `.cursor/rules/senren.mdc` — marker-managed adapter files for each agent.
 
 The skill file uses `<!-- senren:skill:start -->` / `:end` markers; only
 the region between them is rewritten by the generator, so any notes you
 add outside the markers are preserved.
 
+Agent adapter files are also marker-managed, so Senren updates only its own
+generated block and preserves your existing instructions outside that block.
+
 ## Component list
 
 See `registry/components.yml` for the canonical list. v0.1 ships:
@@ -122,6 +168,8 @@ See `registry/components.yml` for the canonical list. v0.1 ships:
 bundle install
 bun install
 bundle exec rake test            # gem tests
+bin/system                       # headless browser system tests
+bin/performance                  # local payload/performance budgets
 bun run controllers:check        # lint + syntax check for templates/controllers/*.js
 bun run controllers:lint:fix     # auto-fix lint issues for controllers
 bundle exec rake test:system     # Stimulus/system tests
@@ -135,6 +183,20 @@ See `CONTRIBUTING.md`. Two rules to know up front:
 2. Architectural decisions are captured in `plans/` before code is
    written.
 
+## Open source maintenance baseline
+
+This repo ships with a GitHub baseline for safer public maintenance:
+
+- 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`.
+
+Repository controls such as branch protection, required checks, release
+permissions, and auto-delete branch still need to be enabled in GitHub
+repository settings.
+
 ## License
 
 MIT — see `LICENSE`.

data/docs/components.md

@@ -0,0 +1,222 @@
+# Senren Components Guide
+
+This guide covers the form-related components in detail, with runnable examples
+and explicit guidance on common pitfalls.
+
+---
+
+## FormComponent
+
+Wraps `form_with` with Senren semantic tokens and consistent spacing.
+
+### Key behavior
+
+- **Yields a Rails form builder** (`|f|`) — use `f.text_field`, `f.select`, etc.
+  inside the block just like a normal Rails form.
+- **`method:` defaults to `nil`** — Rails will infer `:post` for new records and
+  `:patch` for persisted records. Only pass `method:` explicitly when you need to
+  override this (e.g., `method: :delete`).
+- **`model: nil` is safe** — model-less forms (login, search, password reset)
+  work without passing a model.
+
+### Examples
+
+#### Basic model form (create)
+
+```erb
+<%= render(Senren::FormComponent.new(model: @post, url: posts_path)) do |f| %>
+  <%= render(Senren::LabelComponent.new(for_field: "title", variant: :required)) { "Title" } %>
+  <%= f.text_field :title, class: "senren-input" %>
+  <%= render(Senren::ButtonComponent.new(variant: :primary, type: :submit)) { "Create" } %>
+<% end %>
+```
+
+#### Edit form (Rails infers PATCH automatically)
+
+```erb
+<%= render(Senren::FormComponent.new(model: @post, url: post_path(@post))) do |f| %>
+  <%= render(Senren::LabelComponent.new(for_field: "title")) { "Title" } %>
+  <%= f.text_field :title, class: "senren-input" %>
+  <%= render(Senren::ButtonComponent.new(variant: :primary, type: :submit)) { "Update" } %>
+<% end %>
+```
+
+#### Model-less form (login)
+
+```erb
+<%= render(Senren::FormComponent.new(url: session_path)) do |f| %>
+  <%= render(Senren::InputComponent.new(name: "email", type: "email", placeholder: "you@example.com")) %>
+  <%= render(Senren::InputComponent.new(name: "password", type: "password")) %>
+  <%= render(Senren::ButtonComponent.new(variant: :primary, type: :submit)) { "Sign in" } %>
+<% 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"`.
+
+---
+
+## InputComponent
+
+### ⚠️ 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
+
+```erb
+<%# Option A: Use InputComponent standalone %>
+<%= render(Senren::InputComponent.new(name: "email", type: "email")) %>
+
+<%# Option B: Use Rails form builder with plain classes %>
+<%= f.text_field :email, class: "your-input-classes" %>
+```
+
+#### ❌ Do NOT
+
+```erb
+<%# WRONG: This renders two inputs %>
+<%= render(Senren::InputComponent.new(name: "email")) do %>
+  <%= f.text_field :email %>
+<% end %>
+```
+
+### Required params
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | String/Symbol | **Yes** | — | Input `name` attribute |
+| `type` | String | No | `"text"` | HTML input type |
+| `value` | String | No | `nil` | Pre-filled value |
+| `placeholder` | String | No | `nil` | Placeholder text |
+| `id` | String | No | auto | Defaults to parameterized `name` |
+| `variant` | Symbol | No | `:default` | `:default` or `:error` |
+| `size` | Symbol | No | `:md` | `:sm`, `:md`, or `:lg` |
+
+### File inputs
+
+File inputs automatically get styled button treatment:
+
+```erb
+<%= render(Senren::InputComponent.new(name: "avatar", type: "file")) %>
+```
+
+The file selector button uses a segmented style with a divider, semantic surface
+color, and pointer cursor — no additional classes needed.
+
+### Date/time inputs
+
+Native date and datetime-local inputs work correctly. The component intentionally
+omits `display: flex` from base styles because it breaks browser-native
+date/time picker UI on some engines.
+
+```erb
+<%= render(Senren::InputComponent.new(name: "starts_at", type: "datetime-local")) %>
+<%= render(Senren::InputComponent.new(name: "due_date", type: "date")) %>
+```
+
+---
+
+## LabelComponent
+
+### Required params
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `for_field` | String | **Yes** | — | ID of the associated form control |
+| `text` | String | No | `nil` | Fallback label text (if block is empty) |
+| `variant` | Symbol | No | `:default` | `:default` or `:required` (adds `*`) |
+
+### Examples
+
+Both patterns below are fully supported and produce identical output:
+
+```erb
+<%# Block syntax %>
+<%= render(Senren::LabelComponent.new(for_field: "name", variant: :required)) { "Student name" } %>
+
+<%# Text param syntax (useful when block content might be empty) %>
+<%= render(Senren::LabelComponent.new(for_field: "name", text: "Student name", variant: :required)) %>
+```
+
+> **Note**: The `text:` param acts as a fallback. If both a block and `text:` are
+> provided, the block content wins.
+
+---
+
+## NativeSelectComponent
+
+Renders a native `<select>` element with Senren styling.
+
+### Key behavior
+
+- **Defaults to native browser arrow** (`native_arrow: true`). This preserves
+  the platform's familiar select appearance (iOS wheel, Android dropdown, etc.).
+- Pass `native_arrow: false` to use a custom SVG chevron overlay instead.
+
+### Required params
+
+| Param | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `name` | String/Symbol | **Yes** | — | Select `name` attribute |
+| `options` | Array | **Yes** | — | `["a","b"]` or `[["val","Label"],...]` |
+| `selected` | String | No | `nil` | Pre-selected value |
+| `prompt` | String | No | `nil` | Blank option text (e.g., "Choose…") |
+| `native_arrow` | Boolean | No | `true` | Use native browser arrow |
+| `variant` | Symbol | No | `:default` | `:default` or `:error` |
+
+### Examples
+
+```erb
+<%# Native arrow (default — recommended) %>
+<%= render(Senren::NativeSelectComponent.new(
+  name: "role",
+  options: [["admin", "Admin"], ["member", "Member"]],
+  prompt: "Choose role…"
+)) %>
+
+<%# Custom SVG arrow %>
+<%= render(Senren::NativeSelectComponent.new(
+  name: "role",
+  options: [["admin", "Admin"], ["member", "Member"]],
+  native_arrow: false
+)) %>
+```
+
+---
+
+## FormFieldComponent (pattern — not yet a shipped component)
+
+A common pattern when building forms is wrapping label + control + error. Until a
+dedicated `FormFieldComponent` ships, use this pattern:
+
+```erb
+<div class="space-y-1.5">
+  <%= render(Senren::LabelComponent.new(for_field: "email", variant: :required)) { "Email" } %>
+  <%= render(Senren::InputComponent.new(name: "email", type: "email", variant: @errors[:email] ? :error : :default)) %>
+  <% if @errors[:email] %>
+    <p class="text-sm text-[hsl(var(--senren-destructive))]"><%= @errors[:email] %></p>
+  <% end %>
+</div>
+```
+
+---
+
+## Render syntax reminder
+
+Always use **parentheses** around `render` when passing an inline content block:
+
+```erb
+<%# ✅ Correct: parens around render %>
+<%= render(Senren::ButtonComponent.new(variant: :primary)) { "Save" } %>
+
+<%# ✅ Correct: do/end block %>
+<%= render Senren::ButtonComponent.new(variant: :primary) do %>
+  Save
+<% end %>
+
+<%# ❌ Wrong: block attaches to .new, not render %>
+<%= render Senren::ButtonComponent.new(variant: :primary) { "Save" } %>
+```

data/docs/performance_testing.md

@@ -0,0 +1,34 @@
+# Performance Testing
+
+Senren uses CI-safe performance gates by default. The goal is to catch
+regressions that this source-copy UI gem can control: template payload
+growth, Stimulus controller payload growth, eager controller loading, and
+runtime-heavy client behavior.
+
+## Commands
+
+```bash
+bin/performance
+bin/system
+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.
+
+## Benchmark Model
+
+- Static budgets are deterministic and run on every PR.
+- System tests verify browser behavior and coarse budgets.
+- Lighthouse CI is deferred until a stable preview/docs URL exists.
+- Competitive framework benchmarking is out of scope for normal CI.
+
+## Browser Budgets
+
+System tests assert gross DOM size, controller loading, external resource,
+and interaction-duration budgets. They intentionally avoid tight timing
+thresholds because shared CI hardware is noisy.

data/lib/commands/senren/add/add_command.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'rails/command'
+require 'senren/rails'
+
+module Senren
+  module Command
+    class AddCommand < ::Rails::Command::Base
+      class_option :client, type: :boolean, default: nil,
+                            desc: 'Override registry client behavior for installed components.'
+      class_option :force, type: :boolean, default: false,
+                           desc: 'Overwrite existing component files.'
+
+      desc 'add COMPONENT [COMPONENT...]',
+           'Install one or more Senren components into the current Rails app.'
+      def perform(*names)
+        require_application!
+
+        component_installer.install(
+          names: names,
+          client_override: options[:client],
+          force: options[:force]
+        )
+      rescue ArgumentError => e
+        raise ::Rails::Command::Base::Error, e.message
+      end
+
+      private
+
+      def component_installer
+        Senren::Rails::ComponentInstaller.new
+      end
+    end
+  end
+end

data/lib/generators/senren/install/install_generator.rb

@@ -27,10 +27,6 @@ module Senren
         empty_directory 'app/assets/stylesheets'
       end
 
-      def create_public_dir
-        empty_directory 'public'
-      end
-
       def copy_base_files
         template 'base_component.rb.tt', 'app/components/senren/base_component.rb'
         template 'senren.css.tt',                'app/assets/stylesheets/senren.css'
@@ -47,14 +43,15 @@ module Senren
         Senren::Rails::SkillWriter.new(paths: host_paths).sync!
       end
 
-      def write_llms_files
-        say_status :senren, 'writing public/llms.txt and public/llms-full.txt'
-        Senren::Rails::LlmsWriter.new(paths: host_paths).generate!
+      def write_agent_files
+        say_status :senren, 'syncing Codex/Cursor/Claude/Copilot instruction files'
+        Senren::Rails::AgentRulesWriter.new(paths: host_paths).sync!
       end
 
       def print_next_steps
         say "\nSenren installed."
         say 'Next: bin/rails senren:add button card badge alert dialog'
+        say 'Then: bin/rails senren:agents:sync'
       end
 
       private