weft 0.1.0 → 0.2.0

data/docs/examples/value-select.md

@@ -16,12 +16,12 @@ CAR_MODELS = {
 class ModelSelect < Weft::Component
   builder_method :model_select
 
-  attribute :make, default: "audi"
+  param :make, default: "audi"
 
   def build(attributes = {})
     super
     set_attribute :name, "model"
-    CAR_MODELS.fetch(attrs.make).each do |model|
+    CAR_MODELS.fetch(params.make).each do |model|
       option model, value: model.downcase
     end
   end
@@ -41,7 +41,7 @@ class CarsPage < Weft::Page
     div do
       label "Make ", for: "make"
       select name: "make", id: "make",
-             loads: ModelSelect, trigger: "change", swap: :fill, target: "#models" do
+             loads: ModelSelect, trigger: :change, swap: :fill, target: "#models" do
         option "Audi",   value: "audi"
         option "Toyota", value: "toyota"
         option "BMW",    value: "bmw"
@@ -50,7 +50,7 @@ class CarsPage < Weft::Page
     div do
       label "Model "
       span id: "models" do
-        model_select(make: "audi")
+        model_select
       end
     end
   end
@@ -61,13 +61,13 @@ end
 
 ## How it works
 
-**The select's own value is the parameter.** The [`loads:`](../dsl.md#loads) kwarg generates a GET to `ModelSelect`'s route with *no* query string — and htmx completes it at request time: per [its parameter rules](https://htmx.org/docs/#parameters), the element that causes a request includes its own `name=value`. Changing the select to Toyota therefore sends `GET /_components/model_select?make=toyota`, and the component's declared `make` attribute picks the parameter up on the server (see [Attributes](../dsl.md#attributes)). That inclusion is htmx client-side behavior — you won't see it in any rendered attribute — so if the models ever fail to repopulate, the first thing to check is that the triggering select still has its `name`.
+**The select's own value is the parameter.** The [`loads:`](../dsl.md#loads) kwarg generates a GET to `ModelSelect`'s route with *no* query string — and htmx completes it at request time: per [its parameter rules](https://htmx.org/docs/#parameters), the element that causes a request includes its own `name=value`. Changing the select to Toyota therefore sends `GET /_components/model_select?make=toyota`, and the component's declared `make` param picks the parameter up on the server (see [Params](../dsl.md#params)). That inclusion is htmx client-side behavior — you won't see it in any rendered attribute — so if the models ever fail to repopulate, the first thing to check is that the triggering select still has its `name`.
 
-**Keep the URL clean of `with:`.** Baking `with: { make: ... }` into the URL would freeze the value at render time, fighting the live selection htmx appends. In page markup, simply omitting `with:` does the right thing. Inside a *component's* `build`, though, an omitted `with:` defaults to that component's current attrs — pass an explicit `with: {}` there to keep the live value as the only parameter.
+**Keep the URL clean of `with:`.** Baking `with: { make: ... }` into the URL would freeze the value at render time, fighting the live selection htmx appends. In page markup, simply omitting `with:` does the right thing. Inside a *component's* `build`, though, an omitted `with:` defaults to that component's current params — pass an explicit `with: {}` there to keep the live value as the only parameter.
 
-**The component is the `<select>` itself.** Overriding `tag_name` (an [Arbre-layer move](../arbre.md#inside-build-the-component-contract)) makes the wrapper element a `<select>` rather than the default `<div>`, so the fetched fragment drops into the form as a real form control. Note that its `name` attribute is set inside `build` rather than at the call site: a fragment fetched over the wire is rebuilt from its declared attributes alone, so any wrapper attribute the pattern depends on belongs in `build`. And its DOM id derives from the `make` value, changing with every swap — which is why the make select targets the stable `#models` slot with `swap: :fill` instead of chasing the select by id.
+**The component is the `<select>` itself.** Overriding `tag_name` (an [Arbre-layer move](../arbre.md#inside-build-the-component-contract)) makes the wrapper element a `<select>` rather than the default `<div>`, so the fetched fragment drops into the form as a real form control. Note that its `name` attribute is set inside `build` rather than at the call site: a fragment fetched over the wire is rebuilt from its declared params alone, so any wrapper attribute the pattern depends on belongs in `build`. And its DOM id derives from the `make` value, changing with every swap — which is why the make select targets the stable `#models` slot with `swap: :fill` instead of chasing the select by id.
 
-**`trigger: "change"` is spelled out for clarity.** It's also htmx's default trigger for a `<select>`, which is why the original htmx example omits it; keeping it explicit costs one kwarg and makes the interaction readable at the call site.
+**`trigger: :change` is spelled out for clarity.** It's also htmx's default trigger for a `<select>`, which is why the original htmx example omits it; keeping it explicit costs one kwarg and makes the interaction readable at the call site.
 
 ## On the wire
 
@@ -100,10 +100,10 @@ Choosing Toyota sends `GET /_components/model_select?make=toyota`, which returns
 </select>
 ```
 
-— and htmx fills `#models` with it. With no `make` parameter at all, the attribute's default renders the Audi list; parameters the component doesn't declare are simply ignored.
+— and htmx fills `#models` with it. With no `make` parameter at all, the param's default renders the Audi list; parameters the component doesn't declare are simply ignored.
 
 ## Related
 
 - [Click to Edit](click-to-edit.md) — the same `loads:` machinery swapping whole UI states instead of one control.
-- [`loads:`](../dsl.md#loads) and [`trigger:`](../dsl.md#trigger) in the DSL reference; [Attributes](../dsl.md#attributes) for how parameters become `attrs`.
-- The [`live_search:` shorthand](../dsl.md#shorthands) is this same fetch-into-a-slot pattern, triggered by typing instead of selecting.
+- [`loads:`](../dsl.md#loads) and [`trigger:`](../dsl.md#trigger) in the DSL reference; [Params](../dsl.md#params) for how parameters become `params`.
+- The [`live_search:` preset](../dsl.md#presets) is this same fetch-into-a-slot pattern, triggered by typing instead of selecting.

data/docs/params.md

@@ -0,0 +1,112 @@
+# How params flow
+
+A Weft component's data — the values it renders from, the record it looks up, the id it needs to refresh itself — all arrive through one object: `params`. This page follows that data from the moment a request lands to the moment a component re-renders itself, and shows where each of the four declarations (`param`, `receives`, `derives`, `defines`) fits. For the precise behavior of each, see [the DSL reference](dsl.md#params); this page is the map, not the legend.
+
+The whole model in one breath: **a request's params flow in and down the render tree; each component pulls out the ones it declares; and each component renders carrying enough of its own wire state that a later request — a refresh, an action — can reconstruct it from scratch.**
+
+## A request comes in
+
+Every render starts with a request, and a request carries **wire params**: the query string, the path segments, and any form body, all as strings. Weft routes the request to a page (or a standalone component), which resolves its declared `param`s from those wire values — coercing each into its declared `type:`, and filling in defaults where the request said nothing.
+
+```ruby
+class OrderPage < Weft::Page
+  self.page_path = "/orders/:order_id"
+  param :order_id
+end
+```
+
+A GET to `/orders/42` gives this page `params.order_id == "42"`. Nothing else about the request — session, headers, cookies — is part of `params`; that channel is deliberately just the request's own parameters. (For per-request identity like the current user, see [Application patterns](app-patterns.md#authentication-and-sessions).)
+
+## Params flow down the render tree
+
+A page is rarely one component. It embeds others, which embed others. Within a single render, **each component starts from a copy of its nearest ancestor's resolved params** — it sees everything above it in the tree, nothing beside it.
+
+```ruby
+class OrderPage < Weft::Page
+  param :order_id
+
+  def build(attributes = {})
+    super
+    order_summary            # embedded — no arguments
+  end
+end
+
+class OrderSummary < Weft::Component
+  builder_method :order_summary
+  # declares no order_id of its own …
+
+  def build(attributes = {})
+    super
+    h2 "Order #{params.order_id}"   # … yet reads it, inherited from the page
+  end
+end
+```
+
+`OrderSummary` never declares `order_id`, but because it renders inside a page that has it, it reads `params.order_id` for free. This is why embedding is so quiet in Weft: a child that needs what its parent already holds just reads it. Declaring the key anyway (`param :order_id`) is often worth it — it documents the dependency and, as the next sections show, lets the child stand on its own — but it isn't required merely to *read* an inherited value.
+
+## Four doors: how a component gets what it needs
+
+When a component wants to control a value rather than inherit it, it declares that value — through whichever of the four doors suits the value's nature:
+
+- **`param`** — wire state, small enough to travel in a URL: an id, a page number, a filter. Comes from the request, or is inherited from above.
+- **`derives`** — a value the component computes for itself, lazily, the first time it's read.
+- **`defines`** — a static value a subclass pins; sugar over `derives`.
+- **`receives`** — a rich object a caller hands over directly: a record, a built collection, anything that can't ride a query string.
+
+A single key can have more than one door, and they resolve in a fixed order — a handed value beats a request overlay (a hash a verb block returned earlier in the request) beats a wire value beats an inherited value beats a derivation beats a default. The [DSL reference](dsl.md#how-the-doors-combine) lays out that precedence and the useful *dual* combinations; the shape to carry away here is that all four doors land in the same `params`, read the same way (`params.name`).
+
+Three of the four are open to every verb block too — an action callable, a `transfers`, `includes` or `recovers` block all read the same `param`, `derives` and `defines` a `build` would. Only `receives` is missing there, and it has to be: a hand-off comes from a call site, and a request arriving over the wire has none. When a block needs such a key, give it a second door.
+
+## What a component keeps for itself
+
+Here is the pivot that makes the whole system hold together: **only a component's own declared `param`s are serialized.** When Weft renders a component, it bakes that component's wire params into the things that will make the *next* request on its behalf —
+
+- its **refresh URL** (`refreshes`) and **stream URL** (`pushes`),
+- the **payload of every action** it declares (`performs`, `transfers`, `dismisses`).
+
+The other three doors never serialize: you can't put an `Order` object in a query string, and a derived value can always be re-derived. So what travels forward is exactly the URL-safe wire state the component declared with `param`, and nothing else. Inherited values don't travel either — a child that merely *read* its parent's `order_id` doesn't carry it. A child that needs `order_id` on the next request must declare it.
+
+The same discipline applies to a component's HTML attributes. Chrome passed at the call site (`status_card(class: "wide", name: "picker")`) exists only in that in-page render — a wire re-render rebuilds the component from its params alone, and the call-site attributes are gone. An attribute the component *depends on* (a `name` the pattern reads, an ARIA role) belongs inside `build` via `set_attribute`, where every render path reproduces it.
+
+## The round trip: refresh and actions
+
+This is the payoff. Because a rendered component carries its own wire params, it can regenerate itself without its parent in the picture:
+
+- A **refresh** is a GET to the component's own route, its own params in the query string. Weft routes straight to that component, resolves those params from the wire — the first step again — and re-renders.
+- An **action** is a POST (or DELETE) to the component's route, its params in the payload. The callable runs, then the component re-renders — and the re-render, nested components and OOB companions included, resolves against the *same request wire*, with the callable's returned hash overlaid on top. One universe per request, amended by the verbs that run in it: no matter how rendering flows inside a request (an action re-render, a `transfers` hand-off, an error recovery), a component that reads a wire param keeps reading it, without any outer component relaying it.
+
+The callable and the render that follows it are two points on **one chain**, not two independent resolutions. Weft composes the component's params from the wire, hands that to the callable, layers whatever the callable returned on top, and passes the result on to the render — which branches it the same way a child branches its parent's. So a callable reads the same `derives` its `build` does, and a derivation it forces is already a value by the time the render, and the companions riding alongside, read the same key. One lookup, one response.
+
+So "render with enough to get where it needs" is literal: whatever a component will need to reconstruct itself on the next request, it must hold as its own `param`s at render time, because that is what gets serialized into the refresh URL and the action payload. A self-refreshing card embedded as `status_card(status: "hot")` keeps refreshing correctly *only* if it declares `param :status` — otherwise the refresh request carries no status and the standalone re-render has nothing to go on.
+
+## Lists, and why `receives` exists
+
+Inheritance flows one value down to every descendant — which is exactly wrong for a list, where each row needs a *different* value. Siblings share their parent's bag; they can't each inherit a distinct id. So the parent must **hand** each row its own value, and that is what `receives` is for:
+
+```ruby
+class ContactRow < Weft::Component
+  builder_method :contact_row
+
+  param :contact_id       # serialized — lets the row refresh and act on its own
+  receives :contact_id    # handed — the table gives each row its distinct id
+end
+
+class ContactsTable < Weft::Component
+  builder_method :contacts_table
+
+  def build(attributes = {})
+    super
+    tbody do
+      CONTACT_BOOK.each_key { |id| contact_row(contact_id: id) }
+    end
+  end
+end
+```
+
+The `receives :contact_id` is what consumes the `contact_row(contact_id: id)` hand-off — without it, that kwarg would fall through and render as a stray HTML attribute. The `param :contact_id` alongside it is what lets each row stand on its own: when a row fires its delete action, its id is already serialized into the payload, so the server knows which contact to remove. Handed when embedded, wire-borne when acting — two doors, one key. This *dual* is the backbone of every interactive list; you'll see it in [Delete Row](examples/delete-row.md) and [Edit Row](examples/edit-row.md).
+
+## The shape of it
+
+End to end: a request's wire params resolve into the top component and flow down the tree; each component reads what it inherits and declares what it wants to own; at render time each bakes its own wire params into its refresh URL and action payloads; and the next request — refresh or action — arrives carrying exactly what that component needs to do it all again. Data in from the wire, data down the tree, data forward into the next request. That loop is the whole of it.
+
+That loop moves *data* down the tree. Once in a while a component needs to reach the other way — *up* the tree, for an ancestor's **identity** rather than its data: a nested pager needs its enclosing panel's route and DOM id to aim a swap at it. That's a separate affordance, [`closest` / `enclosing`](arbre.md#reaching-enclosing-components) — not part of the params flow, but its natural complement. Params come *to* you; identity you reach *for*.

data/docs/routing.md

@@ -30,7 +30,7 @@ One prerequisite worth knowing: registration happens when a class is *defined* (
 
 ## Component routes
 
-Every routable component is addressable at a GET route that renders it as an HTML fragment — the mechanism behind `refreshes`, `navigate:`, `loads:`, and the shorthands, and equally usable directly (`curl` it; you'll get the component's HTML).
+Every routable component is addressable at a GET route that renders it as an HTML fragment — the mechanism behind `refreshes`, `navigate:`, `loads:`, and the presets, and equally usable directly (`curl` it; you'll get the component's HTML).
 
 The path derives from the class name: strip a trailing `Component` if present, snake-case what's left, prefix `/_components/`. Namespaces become path segments.
 
@@ -42,7 +42,7 @@ The path derives from the class name: strip a trailing `Component` if present, s
 
 The suffix-stripping means `OrdersPanel` and `OrdersPanelComponent` are the same route — pick whichever naming style your app prefers, consistently. The `/_components/` prefix keeps the fragment namespace visibly separate from your page URLs; the leading underscore marks it as infrastructure.
 
-Attributes arrive as query parameters (`/_components/orders_panel?status=shipped&page=2`) and resolve through the component's declared schema — undeclared parameters are ignored, and declared ones are type-coerced from their defaults (see [Attributes](dsl.md#attributes)).
+Params arrive as query parameters (`/_components/orders_panel?status=shipped&page=2`) and resolve through the component's declared schema — undeclared parameters are ignored, and declared ones are coerced per their declared `type:` (see [Params](dsl.md#params)).
 
 To change the path for one class, set `component_path` on it — a string, or a proc receiving the class:
 
@@ -69,30 +69,30 @@ A component declaring `pushes` also gets an SSE endpoint at its path plus the st
 
 ## Page routes
 
-Pages route as full HTML documents at people-facing URLs — no prefix, no derivation from fragments. A page declares its pattern with `page_path`, Sinatra-style, with `:param` segments mapping to attributes:
+Pages route as full HTML documents at people-facing URLs — no prefix, no derivation from fragments. A page declares its pattern with `page_path`, Sinatra-style, with `:param` segments mapping to params:
 
 ```ruby
 class OrderDetailPage < Weft::Page
   self.page_path = "/orders/:order_id"
-  attribute :order_id
+  param :order_id
 end
 ```
 
-A request for `/orders/42` renders the page with `attrs.order_id == "42"`. Path parameters merge with query and body parameters (path wins on conflicts), and the combined set resolves through the page's attribute schema like any other wire state.
+A request for `/orders/42` renders the page with `params.order_id == "42"`. Path parameters merge with query and body parameters (path wins on conflicts), and the combined set resolves through the page's param schema like any other wire state.
 
-The pattern is bidirectional — it also builds URLs. `Weft.redirect(OrderDetailPage, order_id: 42)` interpolates the attrs into the pattern, and `OrderDetailPage.redirect_url(order_id: 42, highlight: "items")` additionally turns declared-but-not-in-path attrs into a query string (undeclared keys are discarded, never leaked into URLs).
+The pattern is bidirectional — it also builds URLs. `Weft.redirect(OrderDetailPage, order_id: 42)` interpolates the params into the pattern, and `OrderDetailPage.redirect_url(order_id: 42, highlight: "items")` additionally turns declared-but-not-in-path params into a query string (undeclared keys are discarded, never leaked into URLs).
 
 Pages without an explicit `page_path` infer one from the class name: demodulized, snake-cased, with a trailing `Page` stripped if present — `DashboardPage` and `Dashboard` both route at `/dashboard`. Two edges of the inference to know:
 
-- A page with **attributes** must declare `page_path` explicitly — a parameterized pattern can't be guessed from a name, so Weft raises with the pattern it suggests rather than inventing one.
+- A page with **params** must declare `page_path` explicitly — a parameterized pattern can't be guessed from a name, so Weft raises with the pattern it suggests rather than inventing one.
 - A page named such that nothing usable remains after stripping (`Admin::Page`) also raises, with the remediation options spelled out.
 
 ## What routes — and what doesn't
 
 Registration and routability are separate ideas. *Every* `Weft::Component` and `Weft::Page` subclass registers; whether it gets a route is inferred from what it declares:
 
-- A **component** is routable when it declares interactive behavior: any attribute, action, `refreshes`, or `pushes`. A purely presentational component — just a `build` method — registers but is never served; there's nothing to address it *for*.
-- A **page** is routable when it has a usable path: an explicit `page_path`, or a name the default can be derived from (and no attributes, per the edge above).
+- A **component** is routable when it declares interactive behavior: any param, action, `refreshes`, or `pushes`. A purely presentational component — just a `build` method — registers but is never served; there's nothing to address it *for*.
+- A **page** is routable when it has a usable path: an explicit `page_path`, or a name the default can be derived from (and no params, per the edge above).
 
 ### `abstract!` and `routable!`
 
@@ -108,9 +108,9 @@ end
 
 ### Routable vs. render target
 
-"Routable" means *addressable at its own GET URL* — and that is orthogonal to being a **render target**. Verbs with transfer semantics (`transfers to:`, `recovers with:`) render their target on the server, inside an in-flight response; the target class needs attributes to render with, but no route of its own. Weft's own default error components work exactly this way: they're `abstract!`, unreachable by URL, and rendered constantly.
+"Routable" means *addressable at its own GET URL* — and that is orthogonal to being a **render target**. Verbs with transfer semantics (`transfers to:`, `recovers with:`) render their target on the server, inside an in-flight response; the target class needs params to render with, but no route of its own. Weft's own default error components work exactly this way: they're `abstract!`, unreachable by URL, and rendered constantly.
 
-Navigation-semantic wiring (`refreshes`, `navigate:`, `loads:`, shorthands) *does* need its target addressable — and here the inference has a gap to watch. Declaring `refreshes` makes a component routable, but being the *target* of another component's `loads:` or shorthand kwarg confers nothing: a target with no attributes and no verbs of its own quietly stays off the route table, and the element wired to load it gets a not-found response at interaction time. Most real targets declare attributes and route on their own; for a purely presentational one, declare `routable!` explicitly. Where you'll reach for `abstract!` is the opposite case: a transfer target that declares attributes (so it can render) but should never be an endpoint — declare it abstract and it carries attributes for rendering while staying off the route table.
+Navigation-semantic wiring (`refreshes`, `navigate:`, `loads:`, presets) *does* need its target addressable — and being the *target* of another component's `loads:` or preset kwarg confers nothing by itself: a target with no params and no verbs of its own stays off the route table. Weft refuses to wire a click that could only 404: a `loads:` or preset kwarg naming a non-routable class raises `Weft::InvalidUsage` at render time, as does a `navigate:` inside a component marked `abstract!`/`dependent!`. Most real targets declare params and route on their own; for a purely presentational one, declare `routable!` explicitly — the error says so. Where you'll reach for `abstract!` is the opposite case: a transfer target that declares params (so it can render) but should never be an endpoint — declare it abstract and it carries params for rendering while staying off the route table, because transfer rendering happens server-side and never fetches.
 
 ## Collision detection
 
@@ -126,6 +126,6 @@ The same validation rejects malformed paths (anything that isn't a string beginn
 
 ## Code reloading
 
-Development-mode reloaders redefine constants, which would strand the *old* class object in Weft's registry — and a stale twin at the same path would read as a route collision. Weft prunes superseded registrations automatically: at route-resolution time it drops any registered class whose name no longer resolves to that same class object. The sweep is memoized per registry generation, so production pays it once, ever.
+Development-mode reloaders redefine constants, which would strand the *old* class object in Weft's registry — a stale twin at the same path that reads as a route collision, or worse, a deleted class whose route keeps serving. The registry's answer is eviction: `Weft.registry.evict(klass)` removes a class and re-arms route validation, so the fresh definition (or nothing, if the file is gone) takes over cleanly.
 
-This works with any reloading setup — [`auto_reload`](configuration.md#auto_reload), or your own Zeitwerk `reload` hook. `Weft.registry.clear` is the explicit full-reset primitive if your integration wants to rebuild registration from scratch.
+With [`Weft.configure_autoloading`](configuration.md#autoloading-weftconfigure_autoloading) and `reload: true`, this is wired for you — Zeitwerk announces each constant it unloads and Weft evicts it on the spot. If you drive your own reloader, call `evict` from its unload hook, or use `Weft.registry.clear` to rebuild registration from scratch on each reload. A collision error naming two classes with the same name is the tell that a reload happened without eviction.

data/docs/tutorial.md

@@ -68,23 +68,16 @@ require "weft"
 
 APP_ROOT = File.expand_path("..", __dir__)
 
-# Load the application: data first, then components, then pages
-# (pages compose components). Within each directory, files load
-# alphabetically.
-%w[data components pages].each do |dir|
-  Dir[File.join(APP_ROOT, "app", dir, "*.rb")].sort.each { |file| require file }
-end
-
-Weft.configure do |c|
-  c.auto_reload = true
-  c.reload_paths = [File.join(APP_ROOT, "app", "**", "*.rb")]
-end
+Weft.configure_autoloading(
+  paths: %w[data components pages].map { |dir| File.join(APP_ROOT, "app", dir) },
+  reload: true
+)
 ```
 
 Two things to notice:
 
-- **Loading is just `require`.** Weft discovers your pages and components the moment their classes are defined — there's nothing to register. The directory ordering matters a little: if a component references another class *in its class body* (you'll see `includes AttendeeList` later), the referenced file has to load first. Our data → components → pages ordering plus alphabetical luck covers this tutorial; a growing app eventually wants a real autoloader like Zeitwerk.
-- **Turn on `auto_reload` before your first run.** In a moment you'll be editing files and refreshing the browser; with these two settings, your edits apply without restarting the server. (In a real app you'd gate this on an environment check — see [Configuration](configuration.md#auto_reload).)
+- **Loading is managed for you.** `configure_autoloading` puts [Zeitwerk](https://github.com/fxn/zeitwerk) in charge of the `app` directories: each file defines the constant its name implies (`event_store.rb` ↔ `EventStore`), references between files resolve on demand, and load order is never your problem. Weft discovers your pages and components the moment their classes load — there's nothing to register.
+- **`reload: true` is the development loop.** In a moment you'll be editing files and refreshing the browser; with it, your edits apply without restarting the server. (In a real app you'd gate it on an environment check — see [Configuration](configuration.md#autoloading-weftconfigure_autoloading).)
 
 ## 3. Your first page
 
@@ -92,8 +85,9 @@ Create `app/pages/events_page.rb`:
 
 ```ruby
 class EventsPage < Weft::Page
+  title "Upcoming Events"
+
   def build(attributes = {})
-    attributes[:title] = "Upcoming Events"
     super
     h1 "Upcoming Events"
     para "If you can read this in the browser, the app is wired up."
@@ -101,7 +95,7 @@ class EventsPage < Weft::Page
 end
 ```
 
-A page is a class. `build` describes its content using [Arbre](arbre.md)'s HTML builder methods — `h1`, `ul`, `div`, and friends — as plain Ruby. The `super` call renders the document shell around you: doctype, `<head>` with the htmx script, `<body>`. Setting `attributes[:title]` before `super` puts your title in the `<head>`.
+A page is a class. The `title` declaration names the browser tab; `build` describes the content using [Arbre](arbre.md)'s HTML builder methods — `h1`, `ul`, `div`, and friends — as plain Ruby. The `super` call renders the document shell around you: doctype, `<head>` with your title and the htmx script, `<body>`.
 
 Start the server and have a look:
 
@@ -124,7 +118,7 @@ Nobody told Weft about that URL. The route came from the class name: `EventsPage
 Two more things worth ten seconds each while the server is up:
 
 - Visit [http://localhost:9292/](http://localhost:9292/) — a styled "Not found" page, for free. Weft ships default error and not-found handling out of the box ([Error handling](error-handling.md)).
-- Edit the `para` text and refresh — the change appears without a restart. That's `auto_reload` earning its keep.
+- Edit the `para` text and refresh — the change appears without a restart. That's `reload: true` earning its keep.
 
 ## 4. Some data
 
@@ -157,8 +151,9 @@ And make `EventsPage` list the real events:
 
 ```ruby
 class EventsPage < Weft::Page
+  title "Upcoming Events"
+
   def build(attributes = {})
-    attributes[:title] = "Upcoming Events"
     super
     h1 "Upcoming Events"
     ul do
@@ -175,9 +170,9 @@ end
 
 (`text_node` inserts plain text next to other elements — handy when a line mixes a link and loose text.)
 
-**Restart the server for this one.** `auto_reload` re-runs files it already knows about, but `event_store.rb` is a *new* file — the loader glob ran at boot, before it existed. If you refresh without restarting, you'll get Weft's error page with `uninitialized constant EventsPage::EventStore`, which is your cue. New file → restart; edits to existing files → just refresh.
+**No restart needed — not even for a new file.** `event_store.rb` didn't exist when the server booted, but the loader discovers it on your next refresh, and `EventsPage`'s `EventStore` reference resolves on demand.
 
-After the restart, `/events` lists both events as links. They 404 — let's fix that.
+Refresh `/events`: both events appear as links. They 404 — let's fix that.
 
 ## 5. The event page
 
@@ -187,13 +182,14 @@ Create `app/pages/event_page.rb`:
 class EventPage < Weft::Page
   self.page_path = "/events/:event_id"
 
-  attribute :event_id
+  param :event_id
+
+  title { |params| EventStore.find(params.event_id).name }
 
   def build(attributes = {})
-    event = EventStore.find(attributes[:event_id])
-    raise Weft::NotFound, "no event called #{attributes[:event_id]}" unless event
+    event = EventStore.find(params.event_id)
+    raise Weft::NotFound, "no event called #{params.event_id}" unless event
 
-    attributes[:title] = event.name
     super
     h1 event.name
     para "#{event.date} — #{event.location}"
@@ -204,9 +200,9 @@ end
 
 Restart (new file), then click through to an event. Two new ideas here:
 
-**Attributes are a page's wire state.** `attribute :event_id` declares that this page is parameterized, and the `page_path` pattern says where the value comes from: `/events/summer-bbq` gives the page `event_id = "summer-bbq"`. A page with attributes needs an explicit `page_path` — there's no way to derive a parameterized pattern from a class name, and Weft will tell you exactly that if you forget.
+**Params are a page's wire state.** `param :event_id` declares that this page is parameterized, and the `page_path` pattern says where the value comes from: `/events/summer-bbq` gives the page `event_id = "summer-bbq"`. A page with params needs an explicit `page_path` — there's no way to derive a parameterized pattern from a class name, and Weft will tell you exactly that if you forget.
 
-One timing wrinkle: before the `super` call, read incoming values from the raw `attributes` hash (as above). After `super`, the resolved values are available the nicer way — `attrs.event_id`. You'll see `attrs` used in the components below, where `super` comes first.
+**The title can be dynamic.** The block form of `title` receives the page's resolved params, so each event names its own browser tab. The block runs while `super` renders the `<head>` — after the guard at the top of `build` has already raised for a bogus id, so it can assume the event exists. (And looking the event up twice is fine against a hash; when lookups get real, [`derives`](params.md#four-doors-how-a-component-gets-what-it-needs) declares the record once and every reader — the title block included — shares it.)
 
 **Raising is error handling.** For an unknown event, we `raise Weft::NotFound` and we're done — Weft turns it into a proper 404 response with its default not-found page. Try [http://localhost:9292/events/nope](http://localhost:9292/events/nope). There's a whole family of semantic errors (`Weft::Unprocessable` will appear shortly), and everything about the resulting rendering is customizable — see [Error handling](error-handling.md).
 
@@ -218,11 +214,11 @@ Pages are destinations; **components** are the composable, interactive pieces in
 class AttendeeList < Weft::Component
   builder_method :attendee_list
 
-  attribute :event_id
+  param :event_id
 
   def build(attributes = {})
     super
-    event = EventStore.find(attrs.event_id)
+    event = EventStore.find(params.event_id)
     h2 "Who's coming"
     if event.rsvps.empty?
       para "No RSVPs yet. Be the first!"
@@ -242,9 +238,11 @@ end
 Add it to `EventPage`, before the back-link:
 
 ```ruby
-    attendee_list(event_id: event.id)
+    attendee_list
 ```
 
+Notice there's no `event_id:` here. The component is nested inside a page that already carries `event_id`, and params flow down the render tree — so `attendee_list` inherits it automatically. That inheritance is central to how Weft composes; the [DSL reference](dsl.md#inheritance-and-the-render-tree) has the full picture.
+
 Restart, and the Summer BBQ page shows Priya under "Who's coming".
 
 View the page source and look at the wrapper Weft rendered:
@@ -253,7 +251,7 @@ View the page source and look at the wrapper Weft rendered:
 <div id="attendee-list-summer-bbq">
 ```
 
-That DOM id was derived, not written: the class name, plus the value of the component's **first declared attribute**. The convention matters — it's how updates land on the right element when several instances share a page — so declare the identifying attribute first. (A list of attendee *rows*, say, would want `attribute :name` first, or every row would collide on the same event-derived id.)
+That DOM id was derived, not written: the class name, plus the value of the component's **first declared param**. The convention matters — it's how updates land on the right element when several instances share a page — so declare the identifying param first. (A list of attendee *rows*, say, would want `param :name` first, or every row would collide on the same event-derived id.)
 
 One more thing, and it's the heart of Weft. Your component isn't just markup inside the page — it's independently addressable:
 
@@ -271,32 +269,32 @@ Now the interactive part. Create `app/components/rsvp_form.rb`:
 class RSVPForm < Weft::Component
   builder_method :rsvp_form
 
-  attribute :event_id
-  attribute :name
-  attribute :answer
-  attribute :error_message
+  param :event_id
+  param :name
+  param :answer
+  param :error_message
 
   includes AttendeeList
 
-  performs :submit do |attrs|
-    event = EventStore.find(attrs.event_id)
-    name = attrs.name.to_s.strip
+  performs :submit do |params|
+    event = EventStore.find(params.event_id)
+    name = params.name.to_s.strip
     raise Weft::Unprocessable, "Please tell us your name." if name.empty?
 
-    event.rsvps[name] = attrs.answer
+    event.rsvps[name] = params.answer
     nil
   end
 
-  recovers from: Weft::Unprocessable do |_attrs, error|
+  recovers from: Weft::Unprocessable do |_params, error|
     { error_message: error.message }
   end
 
   def build(attributes = {})
     super
     h2 "RSVP"
-    para(attrs.error_message, style: "color:#b91c1c") if attrs.error_message
+    para(params.error_message, style: "color:#b91c1c") if params.error_message
     form(action: :submit) do
-      input(type: "hidden", name: "event_id", value: attrs.event_id)
+      input(type: "hidden", name: "event_id", value: params.event_id)
       label("Your name: ", for: "name")
       input(type: "text", name: "name", id: "name")
       label(" Coming? ", for: "answer")
@@ -312,15 +310,15 @@ end
 Add it to `EventPage` above the attendee list:
 
 ```ruby
-    rsvp_form(event_id: event.id)
-    attendee_list(event_id: event.id)
+    rsvp_form
+    attendee_list
 ```
 
 Restart, open Trivia Night, RSVP as yourself — **the attendee list updates without a page reload**, and the form clears. Then try submitting with a blank name: a red message appears in the form, and the list is untouched.
 
 That's a lot from one class. Unpacking it:
 
-**`performs :submit` declares a user action.** The block is the behavior: it receives the component's resolved attributes, does its work, and whatever it returns directs what renders next — `nil` means "re-render me fresh" (our success path). Weft generates the route for the action; you never wrote one.
+**`performs :submit` declares a user action.** The block is the behavior: it receives the component's resolved params, does its work, and whatever it returns directs what renders next — `nil` means "re-render me fresh" (our success path). Weft generates the route for the action; you never wrote one.
 
 **`form(action: :submit)` wires the form to the action.** Look at the rendered HTML:
 
@@ -331,15 +329,15 @@ That's a lot from one class. Unpacking it:
 
 The `hx-*` attributes make the form submit in place. The plain `action` and `method` attributes are there too, so the form still works with JavaScript disabled — it degrades to a normal POST.
 
-**Form fields map to declared attributes, one to one.** The action block reads `attrs.name` and `attrs.answer` because the form has fields named `name` and `answer` *and* the component declares attributes of the same names. Both halves are needed: declared-but-not-a-field values don't travel (that's why `event_id` rides along as a hidden input — it's part of the component's identity, not something the user types), and field-but-not-declared values are ignored.
+**Form fields map to declared params, one to one.** The action block reads `params.name` and `params.answer` because the form has fields named `name` and `answer` *and* the component declares params of the same names. Both halves are needed: declared-but-not-a-field values don't travel (that's why `event_id` rides along as a hidden input — it's part of the component's identity, not something the user types), and field-but-not-declared values are ignored.
 
-**Validation is a raise plus a recovery.** The action raises `Weft::Unprocessable`; the `recovers` declaration catches it, and its block returns extra attributes to merge into the re-render — here, `error_message`, which `build` displays when present. Note that `error_message` is itself a declared attribute: recovery data flows through the same schema as everything else. The response even carries a semantically-correct 422 status. See [Error handling](error-handling.md) for how far this system goes.
+**Validation is a raise plus a recovery.** The action raises `Weft::Unprocessable`; the `recovers` declaration catches it, and its block returns extra params to merge into the re-render — here, `error_message`, which `build` displays when present. Note that `error_message` is itself a declared param: recovery data flows through the same schema as everything else. The response even carries a semantically-correct 422 status. See [Error handling](error-handling.md) for how far this system goes.
 
 **`includes AttendeeList` updates the list in the same response.** Submitting the form changes data that *another* component displays. This declaration says: whenever RSVPForm responds to an action, render AttendeeList too, marked so it swaps into its own place in the page (by that derived DOM id — this is why the convention exists). One interaction, two regions updated, zero JavaScript.
 
 ## 8. Going live
 
-The attendee list updates when *you* RSVP — but not when someone else does. One line fixes that. In `AttendeeList`, under the attribute:
+The attendee list updates when *you* RSVP — but not when someone else does. One line fixes that. In `AttendeeList`, under the param:
 
 ```ruby
   refreshes every: 10
@@ -359,13 +357,13 @@ Declared once on the class, the behavior is present in the initial page render *
 
 You've built pages that route themselves, components that compose and self-address, a validated user action with out-of-band updates, and a live-polling list — the core of how Weft apps are put together.
 
-**An exercise, if you're enjoying yourself:** add a "withdraw" button next to each attendee. You'll want a per-attendee component (careful which attribute you declare first — each row needs its own DOM id), and the `dismisses` verb, which removes a component from the page when its action succeeds. The [DSL reference](dsl.md#dismisses--remove-from-the-dom) has what you need.
+**An exercise, if you're enjoying yourself:** add a "withdraw" button next to each attendee. You'll want a per-attendee component (careful which param you declare first — each row needs its own DOM id), and the `dismisses` verb, which removes a component from the page when its action succeeds. The [DSL reference](dsl.md#dismisses--remove-from-the-dom) has what you need.
 
 **A finishing touch:** the events list living at `/events` leaves `/` as a 404. Give `EventsPage` an explicit home: `self.page_path = "/"`.
 
 **The reference docs**, when you want the full picture:
 
-- [The Weft DSL](dsl.md) — every verb (`transfers`, `pushes`, `dismisses`, `triggers`…), the element kwargs, and the interaction shorthands (tooltips, modals, lazy loading) this tutorial didn't touch.
+- [The Weft DSL](dsl.md) — every verb (`transfers`, `pushes`, `dismisses`, `triggers`…), the element kwargs, and the interaction presets (tooltips, modals, lazy loading) this tutorial didn't touch.
 - [Arbre: the HTML layer](arbre.md) — the HTML builder underneath every `build` method: its argument conventions, text handling, container patterns, and gotchas beyond `para`.
 - [Routing](routing.md) — how paths derive, what's routable, collision detection.
 - [Error handling](error-handling.md) — the error family, recovery chains, branding your error pages.

data/lib/weft/action.rb

@@ -47,6 +47,8 @@ module Weft
 
     TRIGGER_VALUES = {
       click: "click",
+      click_once: "click once",
+      change: "change",
       hover: "mouseenter once",
       visible: "revealed",
       input: "input changed delay:300ms"
@@ -64,9 +66,9 @@ module Weft
       path = route_path(component.class.resolved_component_path)
       {
         "hx-#{method}" => path,
-        "hx-target" => target || "##{component.weft_id}",
+        "hx-target" => target || "##{component.weft_dom_id}",
         "hx-swap" => self.class.resolve_swap(swap),
-        "hx-vals" => component.attrs.to_h.to_json
+        "hx-vals" => component.serializable_params.to_json
       }
     end
 

data/lib/weft/autoloading.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "weft/error"
+require "weft/router"
+
+module Weft
+  # Zeitwerk-backed autoloading for application code, behind
+  # {Weft.configure_autoloading}. Each call builds one Zeitwerk loader over the
+  # given paths and eager-loads it immediately — Weft routes from the Registry,
+  # which populates via the `inherited` hook, so the classes must exist before
+  # the first request (lazy autoload alone would serve an empty route table).
+  #
+  # With reload: true, a per-request Router hook reloads constants, and
+  # Zeitwerk's on_unload callback evicts each outgoing class from the registry
+  # as it unloads — the push-model complement to {Registry#evict}, which
+  # hand-rolled reloaders call directly.
+  module Autoloading
+    class << self
+      # Loaders created so far, in creation order. @api private
+      def loaders
+        @loaders ||= []
+      end
+
+      def setup(paths:, inflections: {}, reload: false)
+        paths = Array(paths)
+        validate!(paths, inflections)
+        require "zeitwerk"
+
+        loader = build_loader(paths, inflections, reload)
+        loader.setup
+        loader.eager_load
+        install_reload_hook(loader) if reload
+        loaders << loader
+        loader
+      end
+
+      private
+
+      def build_loader(paths, inflections, reload)
+        loader = Zeitwerk::Loader.new
+        paths.each { |dir| loader.push_dir(dir) }
+        loader.inflector.inflect(inflections) unless inflections.empty?
+        loader.enable_reloading if reload # must precede setup — Zeitwerk's contract
+        loader.on_unload { |_cpath, value, _abspath| Weft.registry.evict(value) }
+        loader
+      end
+
+      def validate!(paths, inflections)
+        raise Weft::InvalidConfiguration, "configure_autoloading requires at least one path" if paths.empty?
+        return if inflections.all? { |k, v| k.is_a?(String) && v.is_a?(String) }
+
+        raise Weft::InvalidConfiguration,
+              "configure_autoloading inflections must map file basenames to constant names " \
+              "(String => String), got #{inflections.inspect}"
+      end
+
+      # The dev-mode request hook: reload constants (evicting via on_unload as
+      # they unload), eager-load so everything re-registers, then rebind any
+      # configuration knob left holding a superseded class.
+      def install_reload_hook(loader)
+        Router.before do
+          loader.reload
+          loader.eager_load
+          Weft.configuration.refresh_stale_classes!
+        end
+      end
+    end
+  end
+end