plutonium 0.50.0 → 0.51.0

data/docs/reference/ui/components.md

@@ -0,0 +1,165 @@
+# Components
+
+Plutonium ships a Phlex-based component kit. Use the built-in shorthand inside pages/forms/displays, or write your own custom Phlex components by inheriting `Plutonium::UI::Component::Base`.
+
+## Built-in component kit
+
+Inside any `Plutonium::UI::Component::Base` subclass (or any page/form/display class):
+
+```ruby
+PageHeader(title: "Dashboard", description: "...", actions: [...])
+Panel(class: "mt-4") { p { "Content" } }
+Block { TabList(items: tabs) }
+EmptyCard("No items found")
+ActionButton(action, url: "/posts/new")
+DynaFrameHost(src: "/some/path", loading: :lazy)
+DynaFrameContent(content) { |frame| frame.render_content }
+TableSearchBar()
+TableScopesBar()
+TableInfo(pagy)
+TablePagination(pagy)
+Breadcrumbs()
+```
+
+These are shorthand for `render Plutonium::UI::PageHeader.new(...)` etc. — they work because every component class is exposed as a method on `Plutonium::UI::Component::Base`.
+
+## Writing custom Phlex components
+
+```ruby
+# app/components/post_card_component.rb
+class PostCardComponent < Plutonium::UI::Component::Base
+  def initialize(post:)
+    @post = post
+  end
+
+  def view_template
+    div(class: "bg-[var(--pu-card-bg)] border border-[var(--pu-card-border)] rounded-[var(--pu-radius-lg)] p-4") do
+      h3(class: "font-bold text-[var(--pu-text)]") { @post.title }
+      p(class: "text-[var(--pu-text-muted)] mt-2") { @post.excerpt }
+
+      div(class: "mt-4 flex justify-between items-center") do
+        span(class: "text-sm text-[var(--pu-text-subtle)]") {
+          @post.published_at&.strftime("%B %d, %Y")
+        }
+        a(href: resource_url_for(@post), class: "text-primary-600") { "Read more" }
+      end
+    end
+  end
+end
+```
+
+::: tip Always inherit `Plutonium::UI::Component::Base`
+It gives you:
+- The component kit (`PageHeader`, `Panel`, `Block`, …)
+- Resource helpers (`resource_url_for`, `current_user`, `current_record!`, `current_definition`)
+- A `helpers` proxy for Rails helpers (`helpers.link_to`, `helpers.number_to_currency`)
+- Token / class helpers (`tokens`, `classes`)
+:::
+
+### Use in a definition
+
+```ruby
+class PostDefinition < ResourceDefinition
+  display :card, as: PostCardComponent       # custom display component
+  input   :color, as: ColorPickerComponent   # custom input component
+
+  display :metrics do |field|
+    MetricsChartComponent.new(data: field.value)
+  end
+end
+```
+
+### Use in a page / form / display
+
+```ruby
+class ShowPage < ShowPage
+  def render_after_content
+    render RelatedPostsComponent.new(post: object)
+  end
+end
+```
+
+## `DynaFrameContent` pattern
+
+Enables frame-aware rendering — regular requests get the full page (header + content + footer); turbo-frame requests get only the content inside the frame.
+
+```ruby
+def view_template(&block)
+  DynaFrameContent(page_content(block)) do |frame|
+    render_header        # skipped for frame requests
+    frame.render_content # always rendered
+    render_footer        # skipped for frame requests
+  end
+end
+```
+
+All pages inherit this automatically. Modals and frame navigation work without special handling.
+
+### When to call `DynaFrameContent` manually
+
+Rarely. Use it when writing a custom non-resource page that needs the same frame-aware rendering as the built-in pages.
+
+For typical custom pages, just inherit `Plutonium::UI::Page::Base` and override hooks like `render_content` — the DynaFrame wrapping happens in `view_template` automatically.
+
+## Conditional class helpers
+
+For class composition in Phlex components:
+
+```ruby
+class MyComponent < Plutonium::UI::Component::Base
+  def initialize(active:)
+    @active = active
+  end
+
+  def view_template
+    div(class: tokens(
+      "base-class",
+      active?:   "bg-primary-500 text-white",
+      inactive?: "bg-gray-200 text-gray-700"
+    )) { "Content" }
+  end
+
+  private
+
+  def active?   = @active
+  def inactive? = !@active
+end
+```
+
+`classes` returns the class as a kwarg-friendly hash:
+
+```ruby
+div(**classes("p-4 rounded", active?: "ring-2"))
+# => <div class="p-4 rounded ring-2">
+```
+
+`tokens` supports then/else branches:
+
+```ruby
+tokens("base", condition?: {then: "if-true", else: "if-false"})
+```
+
+## Accessing Rails helpers
+
+```ruby
+class MyComponent < Plutonium::UI::Component::Base
+  def view_template
+    helpers.link_to(...)
+    helpers.image_tag(...)
+    helpers.number_to_currency(...)
+  end
+end
+```
+
+The `helpers` proxy gives you everything `ApplicationController#helpers` exposes — including any custom helpers in `app/helpers/`.
+
+## Available context
+
+Inside any custom component, the same set of helpers as pages/forms/displays — see [Pages › Available context](./pages#available-context).
+
+## Related
+
+- [Pages](./pages) — `render_*` hooks call your components
+- [Forms](./forms) — using custom input components via `as: MyComponent`
+- [Displays](./displays) — using custom display components
+- [Assets](./assets) — design tokens (`var(--pu-*)`) and `.pu-*` component classes

data/docs/reference/ui/displays.md

@@ -0,0 +1,104 @@
+# Displays
+
+The show page's record rendering. Override the `Display` nested class in your definition for custom layouts.
+
+## Custom display template
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Display < Display
+    def display_template
+      div(class: "bg-gradient-to-r from-primary-500 to-secondary-600 p-8 rounded-lg text-white mb-6") do
+        h1(class: "text-3xl font-bold") { object.title }
+        p(class: "mt-2 opacity-90") { object.excerpt }
+      end
+
+      Block do
+        fields_wrapper do
+          render_resource_field :author
+          render_resource_field :published_at
+        end
+      end
+
+      Block do
+        div(class: "prose max-w-none") { raw object.content }
+      end
+
+      render_associations if present_associations?
+    end
+  end
+end
+```
+
+## Methods
+
+| Method | Purpose |
+|---|---|
+| `render_fields` | All permitted fields |
+| `render_resource_field(name)` | One field |
+| `render_associations` | Association tabs (driven by `permitted_associations` — see [Behavior › Policy](/reference/behavior/policies#association-permissions)) |
+| `object` | The record |
+| `resource_fields`, `resource_associations` | Permitted lists |
+
+## Custom rendering per field
+
+For per-field custom rendering, prefer declaring it in the **definition** rather than overriding the entire `Display`:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  # Block — returns any Phlex component
+  display :status do |field|
+    StatusBadgeComponent.new(value: field.value, class: field.dom.css_class)
+  end
+
+  # phlexi_tag — proc whose body is rendered inside a Phlex context
+  display :priority, as: :phlexi_tag, with: ->(value, attrs) {
+    case value
+    when 'high'   then span(class: "badge badge-danger")  { "High" }
+    when 'medium' then span(class: "badge badge-warning") { "Medium" }
+    else span(class: "badge badge-info") { "Low" }
+    end
+  }
+
+  # Custom component class
+  display :chart, as: ChartComponent
+end
+```
+
+See [Resource › Definition › Custom rendering](/reference/resource/definition#custom-rendering) for the full per-field rendering surface.
+
+## Theming
+
+Override the theme via a nested `Theme` class:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Display < Display
+    class Theme < Plutonium::UI::Display::Theme
+      def self.theme
+        super.merge(
+          fields_wrapper: "grid grid-cols-3 gap-8",
+          label:          "text-sm font-bold text-[var(--pu-text-muted)] mb-1",
+          string:         "text-lg text-[var(--pu-text)]",
+          markdown:       "prose dark:prose-invert max-w-none"
+        )
+      end
+    end
+  end
+end
+```
+
+### Theme keys
+
+`fields_wrapper`, `label`, `description`, `string`, `text`, `link`, `email`, `phone`, `markdown`, `json`.
+
+## Metadata panel
+
+A right-side aside on the show page. Configured at the definition level, not the Display class — see [Resource › Definition › Metadata panel](/reference/resource/definition#metadata-panel-show-page).
+
+## Related
+
+- [Pages](./pages) — `ShowPage` render hooks (often a lighter alternative to overriding `Display`)
+- [Components](./components) — building reusable Phlex display components
+- [Resource › Definition](/reference/resource/definition) — field-level display configuration (`as:`, `condition:`, blocks)
+- [Behavior › Policy](/reference/behavior/policies) — `permitted_associations` drives the show-page tablist

data/docs/reference/ui/forms.md

@@ -0,0 +1,284 @@
+# Forms
+
+Built on [Phlexi::Form](https://github.com/radioactive-labs/phlexi-form). Override the `Form` nested class in your definition to customize templates, layouts, and field rendering.
+
+## 🚨 Critical
+
+- **`render_actions` is mandatory in custom `form_template`** — without it, the form has no submit button.
+- **Configure inputs in the definition, render them with `render_resource_field`** in the form template. Don't reimplement field widgets from scratch.
+- **Override via nested classes** (`class Form < Form; end`) inside the definition. Don't replace the root `Plutonium::UI::Form::Resource` class.
+
+## Hierarchy
+
+```
+Phlexi::Form::Base
+└── Plutonium::UI::Form::Base
+    ├── Plutonium::UI::Form::Resource          # CRUD
+    │   └── Plutonium::UI::Form::Interaction   # action forms
+    └── Plutonium::UI::Form::Query             # search/filter
+```
+
+## Override the form
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Form < Form
+    def form_template
+      render_fields       # render every permitted field
+      render_actions      # submit buttons — REQUIRED
+    end
+  end
+end
+```
+
+### Form methods
+
+| Method | Purpose |
+|---|---|
+| `form_template` | Main override point |
+| `render_fields` | All permitted fields in default layout |
+| `render_resource_field(name)` | One field, using the definition's `input` config |
+| `render_actions` | Submit + secondary buttons |
+| `fields_wrapper { ... }` | Grid wrapper div (themeable) |
+| `actions_wrapper { ... }` | Button wrapper div (themeable) |
+| `object` / `record` | The form record |
+| `resource_fields` | Array of permitted field names |
+| `resource_definition` | The definition instance |
+
+## Custom layouts
+
+### Sectioned form
+
+```ruby
+class Form < Form
+  def form_template
+    section("Basic Information") do
+      render_resource_field :title
+      render_resource_field :slug
+    end
+
+    section("Content") do
+      render_resource_field :content
+      render_resource_field :excerpt
+    end
+
+    section("Publishing") do
+      render_resource_field :published_at
+      render_resource_field :category
+    end
+
+    render_actions
+  end
+
+  private
+
+  def section(title, &)
+    div(class: "mb-8") do
+      h3(class: "text-lg font-semibold mb-4 text-[var(--pu-text)]") { title }
+      fields_wrapper(&)
+    end
+  end
+end
+```
+
+### Two-column layout
+
+```ruby
+def form_template
+  div(class: "grid grid-cols-1 lg:grid-cols-3 gap-6") do
+    div(class: "lg:col-span-2") do
+      fields_wrapper do
+        render_resource_field :title
+        render_resource_field :content
+      end
+    end
+
+    div(class: "space-y-4") do
+      Panel do
+        h4(class: "font-medium mb-2") { "Settings" }
+        render_resource_field :status
+        render_resource_field :visibility
+      end
+    end
+  end
+  render_actions
+end
+```
+
+## Field builder (`field(:foo).input_tag`)
+
+`render_resource_field` uses the input config from the definition. For ad-hoc rendering — when you want fine-grained control over a specific field — use `field(...)` directly:
+
+```ruby
+render field(:title).wrapped { |f| f.input_tag }                # wrapped: label + hint + errors
+render field(:title).input_tag                                  # bare element only
+render field(:title).wrapped(class: "col-span-full") { |f| f.input_tag }
+```
+
+### Tag methods (standard)
+
+| Tag | Input |
+|---|---|
+| `input_tag` | text (auto-detected type) |
+| `string_tag`, `text_tag`, `number_tag`, `email_tag`, `password_tag`, `url_tag`, `tel_tag`, `hidden_tag` | standard HTML inputs |
+| `checkbox_tag`, `select_tag`, `radio_button_tag` | standard |
+
+### Plutonium-enhanced tags
+
+| Tag | Component |
+|---|---|
+| `easymde_tag` / `markdown_tag` | EasyMDE markdown editor |
+| `slim_select_tag` | Slim Select (enhanced dropdown) |
+| `flatpickr_tag` | Flatpickr date/time picker |
+| `phone_tag` / `int_tel_input_tag` | intl-tel-input phone field |
+| `uppy_tag` / `file_tag` | Uppy file upload |
+| `secure_association_tag` | Association with policy-checked options (inline `+` add, typeahead) |
+| `belongs_to_tag` / `has_many_tag` / `has_one_tag` | Association selects |
+| `key_value_store_tag` | Key/value pairs editor |
+
+```ruby
+render field(:published_at).wrapped { |f| f.flatpickr_tag(min_date: Date.today, enable_time: true) }
+
+render field(:avatar).wrapped do |f|
+  f.uppy_tag(allowed_file_types: %w[.jpg .png], max_file_size: 5.megabytes)
+end
+```
+
+### Wrapped vs unwrapped
+
+- `wrapped` — includes label, hint, and error rendering. Use for normal form fields.
+- Bare tag — just the input element. Use when you're laying out custom wrappers.
+- `wrapped(class: "...")` — pass classes to the wrapper div.
+
+## Association inputs (`secure_association_tag`)
+
+Association inputs render with two affordances out of the box:
+
+- **Inline `+` add** — a button next to the select opens the target resource's `:new` action. Inherits the target's modal mode. If the parent form is already in a modal, the `+` opens a **stacked secondary modal** (see [Pages › Stacked modals](./pages#stacked-modals-secondary-frame)) so the in-progress form isn't lost — on success the secondary closes and the parent reloads.
+- **Typeahead** — server-side autocomplete is on by default. Uses the target's `search` block if defined; otherwise falls back to a `LIKE` on the input's `label_method:` column or the first match from `[name, title, label, slug, display_name, email]`. See [Resource › Query › Search](/reference/resource/query#search) for the typeahead fallback details.
+
+```ruby
+# Opt out of the + button
+input :author, add_action: false
+
+# Custom add URL
+input :author, add_action: "/internal/users/new"
+
+# Opt out of typeahead (use slim-select's client filter only)
+input :author, typeahead: false
+
+# Pick a non-default searchable column
+input :author, label_method: :email
+```
+
+::: tip Large association tables
+For large target tables, write an explicit `search` block on the target resource definition — the fallback's leading-wildcard `LIKE` can't use a b-tree index.
+:::
+
+## Submit buttons
+
+Default `render_actions` produces the primary submit, plus an optional "Save and add another" / "Update and continue editing" secondary button.
+
+Control the secondary button via the definition:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  submit_and_continue false   # nil (default — auto), true (always show), false (always hide)
+end
+```
+
+Singular resources auto-hide it (creating "another" doesn't make sense for `/profile`).
+
+### Custom action strip
+
+```ruby
+def render_actions
+  actions_wrapper do
+    a(href: resource_url_for(resource_class), class: "pu-btn pu-btn-md pu-btn-secondary") { "Cancel" }
+    button(type: :submit, name: "draft", value: "1", class: "pu-btn pu-btn-md") { "Save Draft" }
+    render submit_button
+  end
+end
+```
+
+## Pre-submit, nested inputs, interaction forms
+
+These all live in the definition layer:
+
+- **Pre-submit / dynamic forms** — see [Resource › Definition › Dynamic forms](/reference/resource/definition#dynamic-forms-pre-submit)
+- **Nested inputs** (`nested_input :variants`) — see [Resource › Definition › Nested inputs](/reference/resource/definition#nested-inputs)
+- **Interaction forms** — interactions define their own `attribute` / `input` and inherit `Plutonium::UI::Form::Interaction`; see [Behavior › Interactions](/reference/behavior/interactions)
+
+## Theming
+
+Forms use a theme system for consistent styling. Override per-resource by nesting a `Theme` class inside `Form`:
+
+```ruby
+class PostDefinition < ResourceDefinition
+  class Form < Form
+    class Theme < Plutonium::UI::Form::Theme
+      def self.theme
+        super.merge(
+          base:            "bg-[var(--pu-card-bg)] shadow-md rounded-lg p-6",
+          fields_wrapper:  "grid grid-cols-2 gap-6",
+          actions_wrapper: "flex justify-end mt-6 space-x-2",
+          label:           "block mb-2 text-base font-bold",
+          input:           "pu-input",
+          error:           "pu-error",
+          button:          "pu-btn pu-btn-md pu-btn-primary"
+        )
+      end
+    end
+  end
+end
+```
+
+::: warning Always `super.merge(...)`
+Don't replace the theme wholesale — Plutonium's defaults handle invalid states, focus rings, and dark mode. `super.merge` keeps them.
+:::
+
+### Theme keys
+
+`base`, `fields_wrapper`, `actions_wrapper`, `wrapper`, `inner_wrapper`, `label`, `invalid_label`, `valid_label`, `neutral_label`, `input`, `invalid_input`, `valid_input`, `neutral_input`, `hint`, `error`, `button`, `checkbox`, `select`.
+
+See [Assets › Phlexi component themes](./assets#phlexi-component-themes) for the underlying theme system.
+
+## Context inside form templates
+
+```ruby
+class Form < Form
+  def form_template
+    # Form object
+    object              # the record
+    record              # alias for object
+    object.new_record?  # check if creating
+
+    # Request context
+    current_user
+    current_parent
+    current_scoped_entity
+    request
+    params
+
+    # Definition
+    resource_definition
+    resource_fields     # permitted fields
+
+    # URL helpers
+    resource_url_for(object)
+    resource_url_for(Post, action: :new)
+
+    # Rails helpers
+    helpers.link_to(...)
+  end
+end
+```
+
+## Related
+
+- [Pages](./pages) — `NewPage` / `EditPage` page hooks
+- [Components](./components) — building reusable Phlex components for forms
+- [Assets](./assets) — `.pu-*` classes, design tokens, dark mode
+- [Resource › Definition](/reference/resource/definition) — input configuration (`as:`, `hint:`, `condition:`, blocks)
+- [Behavior › Interactions](/reference/behavior/interactions) — interaction forms (`Plutonium::UI::Form::Interaction`)
+- [Tenancy › Nested resources](/reference/tenancy/nested-resources) — parent fields hidden by URL

data/docs/reference/ui/index.md

@@ -0,0 +1,30 @@
+# UI Reference
+
+Plutonium uses [Phlex](https://www.phlex.fun/) for all view components and TailwindCSS 4 + Stimulus for the frontend.
+
+## Sub-pages
+
+- [Pages](./pages) — `IndexPage`, `ShowPage`, `NewPage`, `EditPage`, render hooks, custom ERB views, context detection
+- [Forms](./forms) — `Form` class, field builder, association inputs (typeahead + inline add), themes
+- [Displays](./displays) — `Display` class, custom rendering, `phlexi_tag`
+- [Tables](./tables) — `Table` class, custom rendering, search/scopes bar
+- [Components](./components) — built-in component kit, custom Phlex components, `DynaFrameContent` pattern, modals & tabs
+- [Layouts](./layouts) — shell config, ejecting chrome, custom `ResourceLayout` class
+- [Assets](./assets) — Tailwind config, Stimulus controllers, design tokens, `.pu-*` component classes, Phlexi themes
+
+## 🚨 Critical (applies across all sub-pages)
+
+- **Override via nested classes in the definition.** `class ShowPage < ShowPage; end`, `class Form < Form; end`. Don't replace the entire view layer.
+- **Use render hooks, not `view_template`.** `render_before_content`, `render_after_content`, `render_before_toolbar`, etc. exist so you don't reimplement the whole page.
+- **All pages inherit `DynaFrameContent`** — turbo-frame requests render only the content. Don't fight it; modals and frame nav "just work".
+- **Custom components inherit `Plutonium::UI::Component::Base`** — gives you the component kit (`PageHeader`, `Panel`, `Block`), resource helpers, and the `helpers` proxy for Rails helpers.
+- **`render_actions` is mandatory in custom `form_template`** — without it, the form has no submit button.
+- **Always `registerControllers(application)`** in `app/javascript/controllers/index.js`. Without it, Plutonium's Stimulus controllers (color-mode, form, slim-select, flatpickr, easymde, etc.) are dead.
+- **Use `plutoniumTailwindConfig.merge`** when extending Tailwind theme — plain object merge drops Plutonium's defaults.
+- **Prefer `.pu-*` classes and `var(--pu-*)` tokens** over hardcoded `gray-X/dark:gray-Y` pairs — they switch with dark mode automatically.
+- **Configure inputs in the definition; render them with `render_resource_field` in the form.** Don't reimplement field widgets from scratch.
+
+## Related
+
+- [Resource › Definition](/reference/resource/definition) — field-level rendering (`field :foo, as: :markdown`, `display :status do |f| … end`)
+- [Behavior › Controllers](/reference/behavior/controllers) — controller render-context hooks (`present_parent?`, `submit_parent?`)

data/docs/reference/ui/layouts.md

@@ -0,0 +1,106 @@
+# Layouts
+
+The overall page chrome — topbar, sidebar, footer, body wrapping. Plutonium ships two shells; you can eject the templates or write a custom `ResourceLayout` for total control.
+
+## Shell
+
+```ruby
+Plutonium.configure do |config|
+  config.shell = :modern     # default — topbar + icon rail
+  # config.shell = :classic  # legacy header + sidebar (only when upgrading)
+end
+```
+
+::: tip `:classic` is only for upgrade paths
+If you're starting fresh, use `:modern`. `:classic` exists so apps upgrading from pre-`:modern` versions can preserve their chrome while migrating.
+:::
+
+## Eject the chrome for per-portal customization
+
+```bash
+rails generate pu:eject:shell --dest=admin_portal
+rails generate pu:eject:layout
+```
+
+`pu:eject:shell` copies `_resource_header.html.erb` and `_resource_sidebar.html.erb` into the portal's `app/views/plutonium/`. The eject is independent of `shell` — you can run it on either.
+
+`pu:eject:layout` copies `layouts/resource.html.erb` for layout-level edits.
+
+## Custom layout class
+
+For full Phlex-level control over the layout:
+
+```ruby
+module AdminPortal
+  class ResourceLayout < Plutonium::UI::Layout::ResourceLayout
+    private
+
+    def body_attributes
+      {class: "antialiased bg-[var(--pu-body)]"}
+    end
+
+    def render_before_main
+      super
+      render AnnouncementBanner.new if Announcement.active.any?
+    end
+
+    def render_body_scripts
+      super
+      script(src: "/custom-analytics.js")
+    end
+  end
+end
+```
+
+### Layout hooks
+
+| Hook | Position |
+|---|---|
+| `render_before_main` / `_after_main` | around the main content area |
+| `render_before_content` / `_after_content` | inside main, around content |
+| `render_flash` | flash messages |
+| `render_head`, `render_title`, `render_metatags`, `render_assets` | head section |
+| `render_body_scripts` | end-of-body scripts |
+| `render_fonts` | font links |
+
+## Typography
+
+Plutonium uses Lato by default. Override via `render_fonts`:
+
+```ruby
+class MyLayout < Plutonium::UI::Layout::ResourceLayout
+  def render_fonts
+    link(rel: "preconnect", href: "https://fonts.googleapis.com")
+    link(href: "https://fonts.googleapis.com/css2?family=Inter&display=swap", rel: "stylesheet")
+  end
+end
+```
+
+Then configure Tailwind to match:
+
+```javascript
+// tailwind.config.js
+theme: plutoniumTailwindConfig.merge(plutoniumTailwindConfig.theme, {
+  fontFamily: {
+    body: ['Inter', 'sans-serif'],
+    sans: ['Inter', 'sans-serif']
+  }
+})
+```
+
+See [Assets › Tailwind config](./assets#tailwind-config) for the full merge story.
+
+## Dark mode
+
+`selector` strategy — toggle by adding/removing `dark` on `<html>`. The bundled `color-mode` Stimulus controller handles toggling; Plutonium ships a switcher.
+
+```javascript
+// Manual toggle if needed
+document.documentElement.classList.toggle('dark')
+```
+
+## Related
+
+- [Assets](./assets) — Tailwind config, design tokens, `.pu-*` classes
+- [Components](./components) — custom components used in layout hooks (`AnnouncementBanner`, etc.)
+- [Pages](./pages) — page-level hooks (a lighter alternative for per-page chrome)