weft 0.1.0 → 0.2.0

data/docs/error-handling.md

@@ -8,8 +8,9 @@ Two layers cooperate to make this work. On the server, the Router catches errors
 
 - [The error classes](#the-error-classes)
 - [The `recovers` chain](#the-recovers-chain) — matching, targets, blocks, and [the built-in edges](#the-built-in-edges)
-- [What happens when something raises](#what-happens-when-something-raises)
-- [Auto-injected recovery attributes](#auto-injected-recovery-attributes)
+- [What happens when something raises](#what-happens-when-something-raises) — including [where failure-prone work belongs](#where-the-work-that-can-fail-belongs) and [when a companion fails](#when-a-companion-fails)
+- [Error handling on live streams](#error-handling-on-live-streams)
+- [Auto-injected recovery params](#auto-injected-recovery-params)
 - [Presentation settings](#presentation-settings)
 
 ## The error classes
@@ -26,7 +27,7 @@ Weft ships a small semantic hierarchy rooted at `Weft::Error`:
 | `Weft::Unprocessable` | 422 | The request was understood but can't be acted on — validation failures, mostly. |
 | `Weft::InternalError` | 500 | An explicit "we broke" signal. |
 
-Raise these from your `build` methods and action callables to communicate outcomes with the right status semantics: `raise Weft::NotFound` when a record lookup comes up empty, `raise Weft::Unprocessable` when validation fails. Errors that aren't `Weft::HTTPError`s — an unrescued `ActiveRecord::RecordNotFound`, a `NoMethodError` — are treated as status 500.
+Raise these from your `build` methods and action callables to communicate outcomes with the right status semantics: `raise Weft::NotFound` when a record lookup comes up empty, `raise Weft::Unprocessable` when validation fails. They're a convenience, not a requirement — your code can keep raising its own vocabulary (`ActiveRecord::RecordNotFound`, a domain error) and let a `recovers` edge [declare what it means](#the-recovers-chain) with `status:`. An error that's neither a `Weft::HTTPError` nor mapped by such an edge is treated as status 500.
 
 A separate branch of the family reports *your* mistakes to you, raised at definition or configuration time rather than during request handling: `Weft::InvalidConfiguration` (a bad value inside `Weft.configure`), `Weft::InvalidDefinition` (a bad class-body declaration, including route collisions), and `Weft::InvalidUsage` (a bad call at render time). These are meant to fail loudly during development, not to be recovery targets.
 
@@ -36,10 +37,11 @@ Components and pages declare how they handle errors with `recovers`:
 
 ```ruby
 class OrderEditor < Weft::Component
-  recovers from: Weft::Unprocessable do |attrs, error|
+  recovers from: Weft::Unprocessable do |params, error|
     { error_message: error.message }
   end
   recovers from: Weft::Unauthorized, with: LoginPage
+  recovers from: ActiveRecord::RecordNotFound, with: NotFoundCard, status: 404
 end
 ```
 
@@ -53,9 +55,13 @@ Each declaration is an edge: *when this kind of error escapes me, render that in
 - a **Range** — matches statuses in the range (`from: 500..599`);
 - an **Array** of any of the above — matches if any element does.
 
-**`with:`** names the recovery target — what renders in place of the failure. It accepts a component or page class, or a symbol naming a [configuration knob](configuration.md#the-four-fallback-targets) (`with: :error_component`), resolved at error-handling time so reconfiguration propagates. Omitted, it defaults to the declaring class itself — "on this error, re-render me" — which pairs naturally with a block that adjusts attrs.
+**`with:`** names the recovery target — what renders in place of the failure. It accepts a component or page class, or a symbol naming a [configuration knob](configuration.md#the-four-fallback-targets) (`with: :error_component`), resolved at error-handling time so reconfiguration propagates. Omitted, it defaults to the declaring class itself — "on this error, re-render me" — which pairs naturally with a block that adjusts params.
 
-**The block**, if given, receives `(attrs, error)` — the same resolved attrs an action callable sees, plus the exception — and returns a hash merged into the attrs the recovery target renders with (returned keys win). It's for *carrying information onto the error rendering*, like the validation messages above; it never returns HTML.
+**`status:`** declares what a matched error *means* on the wire. Weft's own error classes carry their status with them, but your app's errors don't need translating into Weft's — recover from them directly and let the edge supply the semantics, as the `ActiveRecord::RecordNotFound` edge above does: the response status and the auto-injected `:status_code` param both follow it, so the branded rendering is a genuine 404. Without it, a recovered non-`Weft::HTTPError` reports as 500. Only error statuses (400–599) are assignable; an invalid value raises `Weft::InvalidUsage` at declaration time.
+
+**The block**, if given, receives `(params, error)` — plus the exception — and returns a hash merged into the params the recovery target renders with (returned keys win). It's for *carrying information onto the error rendering*, like the validation messages above; it never returns HTML.
+
+The `params` it gets are **the state the request had reached when it broke**, with every door open: wire values, derivations, defines. If the failure was in an action callable, that's what the callable was reading; if the callable succeeded and the *render* failed, it's that plus whatever the callable returned; and a companion's recovery block sees what its own `build` saw, its inclusion block's delta included. A derivation the failed code had already forced is still forced, so reading it in the recovery block costs nothing — and one it hadn't will run now, which is worth remembering if it's the kind of lookup that can fail twice.
 
 Edges are consulted in a defined order: a class's own declarations first (in declaration order), then its ancestors' — so subclass declarations beat inherited ones, and within a class, first match wins. Put more-specific edges before catch-alls.
 
@@ -77,27 +83,61 @@ The symbols resolve through `Weft.configuration`, so [reassigning those knobs](c
 
 ## What happens when something raises
 
-**In component context** — a fragment render, an action, an SSE frame — the Router walks the failing component's chain and renders the matched target as a fragment, with the response status taken from the exception (`Weft::HTTPError#status`, else 500). On the client, the fragment swaps in where the component's response would have gone, so the error appears exactly where the problem is. If the matched target is a *page* class, the recovery becomes a redirect to that page instead (`HX-Redirect` for htmx requests, 302 otherwise) — the `with: LoginPage` pattern above.
+**In component context** — a fragment render or an action — the Router walks the failing component's chain and renders the matched target as a fragment, with the response status taken from the exception (`Weft::HTTPError#status`, else 500). On the client, the fragment swaps in where the component's response would have gone, so the error appears exactly where the problem is. If the matched target is a *page* class, the recovery becomes a redirect to that page instead (`HX-Redirect` for htmx requests, 302 otherwise) — the `with: LoginPage` pattern above.
 
-One wrinkle worth knowing: for actions with a destructive swap (`dismisses`, or any `performs` with `swap: :delete`), a successful response removes the element — which would make an error invisible. Weft overrides the swap on error responses (via `HX-Reswap`) so the error rendering replaces the component instead of vanishing with it.
+One wrinkle worth knowing: for actions with a destructive swap (`dismisses`, or any `performs` with `swap: :delete`), a successful response removes the element — which would make an error invisible. Weft overrides the swap on error responses (via `HX-Reswap`) so the error rendering replaces the component instead of vanishing with it. The replacement also arrives correctly shaped: recovery fragments adopt the failing component's wrapper tag (via `:component_tag`, below), so a failed delete on a table row produces an error *row* the table can legally contain.
 
 **In page context** — a full-document render, or a request no route matched — the Router walks the page's chain (for routing misses, the base `Weft::Page` chain, which lands on the not-found page). A traditional request gets the recovery page as a complete document; an htmx request gets just the page's body content, since the document shell is already on the client.
 
 **If the recovery itself raises** — a bug in your error component, say — Weft stops walking and emits a minimal hardcoded error rendering, logging the recovery failure and surfacing the *original* error. There is always a floor; error handling never recurses into itself.
 
-Errors during SSE pushes don't kill the stream: the frame is skipped, the error logged, and pushing resumes on the next interval.
+Whatever renders, it wears the **failing component's DOM id**. A recovery fragment stands in the failed component's place, and an out-of-band swap addressed anywhere else would land on the wrong element — or on none. You don't opt into this and can't forget it; Weft stamps the id on every recovery fragment it produces.
+
+### Where the work that can fail belongs
+
+Two Weft surfaces can raise, and they are not equivalent. An action callable — `performs`, `transfers`, `dismisses` — is where your app *does* something: writes, external calls, state changes. A `build` method is where it *describes* something.
+
+**Put the fallible work in the callable and keep `build` free of side effects.** The reason will be familiar from any MVC framework: by the time rendering begins, whatever the action committed is already committed. A failure inside the callable can still be reported as a failure of the whole operation; a failure during rendering can only be reported after the fact — which is why Rails rolls back a controller error but not a view error.
+
+Weft leans into that split rather than papering over it. An action that raises produces an error *response*; a fragment that raises produces an error *fragment*, and everything around it stands. The more your `build` methods are pure descriptions of state, the more that second case is a display problem rather than a correctness one.
+
+### When a companion fails
+
+A component can bring [companions](dsl.md#includes--companions-in-the-same-response) along with a response — other fragments that went stale and ride back on the same request. **A companion is a courtesy, not a contract:** if one raises, the response still belongs to the component the request was about.
+
+So the primary render, the status, and the `HX-*` headers are all untouched. The failing companion walks *its own* `recovers` chain, and the result is delivered as a companion in that companion's own DOM slot — the error appears exactly where that fragment would have been and nowhere else, while the rest of the response arrives as though nothing happened. This is what makes an action with side effects honest: a companion that breaks *after* your callable has written to the database can no longer turn a committed change into a reported failure.
 
-## Auto-injected recovery attributes
+Two wrinkles worth knowing:
 
-A recovery target usually wants context: what failed, where, with what status. The Router offers five values, injected **schema-gated**: each is passed only if the target *declares an attribute of that name*. Declaring the attribute is the opt-in; anything not declared is never injected, so nothing leaks into renders (or URLs) uninvited.
+- **Recovery edges that point at a page class are skipped here**, and the walk continues to the next match. A fragment riding inside a successful response has no business navigating away from it.
+- **If the chain yields nothing, or the recovery render itself raises**, that companion is dropped and the failure is logged with the class and the `includes` declaration site that brought it along. The rest of the response is unaffected either way.
 
-| Attribute | Value |
+Companion failures on a [live stream](#error-handling-on-live-streams) behave the same, with one addition: they don't count against the stream's attempts budget. The budget measures the *stream's* health, and a companion's trouble says nothing about it.
+
+## Error handling on live streams
+
+A failing SSE push walks the same `recovers` chain as any other component-context failure, with three stream-shaped differences:
+
+- **Component targets only.** A stream can't redirect, so an entry whose target is a page class is skipped and the walk continues to the next match. The gem-default `StandardError` edge sits at the bottom of every chain, so a failing push always finds an error component to render (unless you've deliberately reconfigured that default away).
+- **Frames mirror normal pushes.** The recovery component's *content* is pushed under the failing component's event name and swaps into the persistent wrapper's interior, exactly like a healthy frame. The recovery component's own wrapper never ships — so on this path, put the error box and its styling on inner elements (the gem defaults do).
+- **Failure is budgeted.** Consecutive failed pushes count against an attempts budget — the [`push_attempts`](configuration.md#push_attempts) setting (default 3), or per component with `pushes every: ..., attempts: ...`. A successful push resets the count. When the budget runs out, Weft pushes the final recovery frame, then a close event that the wrapper's `sse-close` attribute tells htmx to honor: the browser closes the EventSource and does not reconnect. The stream ends server-side too; the rest of the page is untouched.
+
+The countdown is visible to your error components through the `:attempts_remaining` auto-injected param (below): it reaches 0 on the final frame — the moment to offer a resume affordance. The [`reopen_stream:` preset](dsl.md#presets) makes that a one-liner: `button "Resume live updates", reopen_stream: @params.retry_url` re-fetches the component whole, and the fresh render carries a fresh `sse-connect`, so the stream reopens with a full budget.
+
+If the recovery render itself raises, that frame is skipped (and the failure still counts) — streams share the no-recursion floor with every other error path.
+
+## Auto-injected recovery params
+
+A recovery target usually wants context: what failed, where, with what status. The Router offers six values, delivered as **request overlays**: a component reads each by *declaring a param of that name*. The declaration is the opt-in — anything not declared is never read — and because overlays reach the whole recovery render, a component *nested inside* your branded error page can declare and read them too (a shared error-detail partial reading `:exception` itself, say). Recovery redirect URLs stay schema-gated and carry only the redirect-safe values the destination declares, so nothing rides a URL uninvited.
+
+| Param | Value |
 | --- | --- |
 | `:exception` | The exception object itself. |
 | `:request_path` | The path of the failing request. |
 | `:status_code` | The resolved HTTP status (the exception's, or 500). |
-| `:component_id` | The failing component's DOM id. |
-| `:retry_url` | A GET URL that re-renders the failing component with its current attrs. |
+| `:component_tag` | The failing component's wrapper tag name. |
+| `:retry_url` | A GET URL that re-renders the failing component with its current params. |
+| `:attempts_remaining` | On a live stream: failed pushes left before the stream closes. Absent elsewhere. |
 
 So a custom error component opts in by declaration:
 
@@ -105,26 +145,28 @@ So a custom error component opts in by declaration:
 class MyApp::ErrorComponent < Weft::Component
   abstract!
 
-  attribute :exception
-  attribute :retry_url
+  param :exception
+  param :retry_url
 
   def build(attributes = {})
     super
     add_class "weft-error"
     div { text_node "Something went wrong." }
-    div @attrs.exception.message if Weft.configuration.verbose_error_pages
-    button "Retry", retry: @attrs.retry_url if @attrs.retry_url
+    div @params.exception.message if Weft.configuration.verbose_error_pages
+    button "Retry", retry: @params.retry_url if @params.retry_url
   end
 end
 ```
 
 Notes on the individual values:
 
-- **These five names are reserved** on any class used as a recovery target. Declaring an attribute with one of these names *means* "inject the recovery value here" — so don't reuse them for your own data on error components, or on any component/page reachable through a `recovers` edge.
-- **`:component_id`** preserves DOM identity: render your error wrapper with it as the element id (the gem's defaults do) and the error lands under the failing component's original id — so multiple simultaneous failures each swap into their own slot rather than colliding.
-- **`:retry_url`** feeds the [`retry:` shorthand](dsl.md#shorthands): one button attribute, and the user can re-request the failed component in place. For a failed *action*, the URL renders the underlying component's view — a fresh look, not a replay of the failed action.
+- **These six names are reserved** on any class used as a recovery target. Declaring a param with one of these names *means* "inject the recovery value here" — so don't reuse them for your own data on error components, or on any component/page reachable through a `recovers` edge.
+- **DOM identity is not among them**, because it isn't optional. Weft stamps the failing component's id onto every recovery fragment, so simultaneous failures each swap into their own slot rather than colliding, and a recovery target that has never heard of any of this still lands correctly.
+- **`:component_tag`** keeps swaps *valid*: return it from your error component's `tag_name` (the gem's defaults do) and a failure inside a `<tr>` or `<li>` component produces a fragment its surroundings can legally contain, instead of a `<div>` forced somewhere divs can't go. Weft reads the tag without re-running the failed construction; when a component computes its tag from instance state, the value falls back to absent and the target renders with its own default tag.
+- **`:retry_url`** feeds the [`retry:` preset](dsl.md#presets): one button attribute, and the user can re-request the failed component in place. For a failed *action*, the URL renders the underlying component's view — a fresh look, not a replay of the failed action. On a stream's final frame it feeds [`reopen_stream:`](dsl.md#presets) the same way.
+- **`:attempts_remaining`** is also the push-path context signal: non-nil only when rendering a recovery frame for a live stream. Its presence lets one error component serve both paths — the gem default renders its request shape when it's nil and its stream shape otherwise.
 - When a recovery resolves to a **redirect** (page target from component context), only `:request_path` and `:status_code` travel — the others have no meaning in a URL.
-- Keep the `weft-error` CSS class on custom error components: it's the DOM marker the `retry:` shorthand targets, and a useful styling hook besides.
+- Keep the `weft-error` CSS class on custom error components: it's the DOM marker the `retry:` preset targets, and a useful styling hook besides.
 
 ## Presentation settings
 
@@ -132,5 +174,3 @@ Two configuration settings shape how the built-in fallbacks present; both are co
 
 - [`verbose_error_pages`](configuration.md#verbose_error_pages) — whether the gem defaults show exception class/message and the failing path (turn off in production).
 - [`htmx_errors`](configuration.md#htmx_errors) — whether htmx-request errors falling through to the gem defaults render in place (`:fragment`) or navigate to the error page (`:redirect`). Your own `recovers` edges are never affected, and 404s always render in place.
-
-> **v0.1 limitation:** custom `recovers from: Weft::NotFound` declarations are not yet reliably honored — the gem-default not-found rendering can take over the response. To customize not-found presentation in v0.1, assign the [`not_found_page` / `not_found_component` knobs](configuration.md#the-four-fallback-targets), which are fully supported. First-class custom `NotFound` recoveries land in v0.2.

data/docs/examples/active-search.md

@@ -2,7 +2,7 @@
 
 A search box that filters a result list as the user types. Each (debounced) keystroke asks the server for matches, and the results region is refilled with the answer — search-as-you-type with all the logic living server-side.
 
-This is Weft's take on [htmx's active-search example](https://htmx.org/examples/active-search/), searching the same kind of small contact directory by name or email. One preset detail differs and is worth stating precisely: Weft's `live_search:` shorthand fires on `input changed delay:300ms` — the `input` event, debounced by 300 milliseconds — where htmx's published example uses `keyup changed delay:500ms`. If you want htmx's exact timing (or any other), the `trigger:` kwarg overrides the preset, as shown below.
+This is Weft's take on [htmx's active-search example](https://htmx.org/examples/active-search/), searching the same kind of small contact directory by name or email. One preset detail differs and is worth stating precisely: Weft's `live_search:` preset fires on `input changed delay:300ms` — the `input` event, debounced by 300 milliseconds — where htmx's published example uses `keyup changed delay:500ms`. If you want htmx's exact timing (or any other), the `trigger:` kwarg overrides the preset, as shown below.
 
 ## The components
 
@@ -21,13 +21,13 @@ PEOPLE = [
 class ContactResults < Weft::Component
   builder_method :contact_results
 
-  attribute :q, default: ""
+  param :q, default: ""
 
   def build(attributes = {})
     super
-    matches = search(attrs.q)
+    matches = search(params.q)
     if matches.empty?
-      para "No one matches “#{attrs.q}”."
+      para "No one matches “#{params.q}”."
     else
       table do
         thead { tr { th "Name"; th "Email" } }
@@ -55,7 +55,7 @@ class ContactSearch < Weft::Component
     input type: "search", name: "q", placeholder: "Begin typing to search...",
           live_search: ContactResults, target: "#search-results"
     div id: "search-results" do
-      contact_results(q: "")
+      contact_results
     end
   end
 end
@@ -65,7 +65,7 @@ end
 
 ## How it works
 
-**The input's `name` is the search parameter.** [`live_search:`](../dsl.md#shorthands) presets trigger `:input` and swap `:fill`; the call site supplies the target. Notice that the generated URL below carries no query string — htmx includes the triggering input's own `name`/value with the request, which is how the typed text travels. The two halves must agree: the input says `name: "q"`, and `ContactResults` declares `attribute :q` to receive it. An empty default keeps the blank-box case (matching everyone) working.
+**The input's `name` is the search parameter.** [`live_search:`](../dsl.md#presets) presets trigger `:input` and swap `:fill`; the call site supplies the target. Notice that the generated URL below carries no query string — htmx includes the triggering input's own `name`/value with the request, which is how the typed text travels. The two halves must agree: the input says `name: "q"`, and `ContactResults` declares `param :q` to receive it. An empty default keeps the blank-box case (matching everyone) working.
 
 **Debounced by the preset, adjustable at the call site.** The `:input` semantic trigger expands to `input changed delay:300ms`: fire on input events, only when the value actually changed, at most once per 300ms lull. To reproduce htmx's example exactly, override it in place — the preset's request, swap, and target are all kept:
 
@@ -75,7 +75,7 @@ input type: "search", name: "q",
       trigger: "keyup changed delay:500ms"
 ```
 
-**Results refill a stable container.** The `:fill` swap replaces the *contents* of `#search-results`, so the container div persists across searches while a fresh `ContactResults` lands inside it each time. Pre-rendering `contact_results(q: "")` in the container means the page starts with the full directory rather than an empty pane — the initial state and every subsequent state are the same component.
+**Results refill a stable container.** The `:fill` swap replaces the *contents* of `#search-results`, so the container div persists across searches while a fresh `ContactResults` lands inside it each time. Pre-rendering a bare `contact_results` in the container means the page starts with the full directory rather than an empty pane — its `q` param defaults to the empty string, which matches everyone — and the initial state and every subsequent state are the same component.
 
 **The whole result set re-renders per search.** No row diffing, no client-side state: each request returns the complete table (or the "no matches" paragraph) for that query. At search-box scale this is the simple, correct trade.
 
@@ -94,7 +94,7 @@ The initial render — the wired input, and the container holding the unfiltered
 </div>
 ```
 
-(That `id="contact-results-"` is the component's DOM id — dasherized class name plus first attribute value, which here is the empty string.)
+(That `id="contact-results-"` is the component's DOM id — dasherized class name plus first param value, which here is the empty string.)
 
 Typing "grimes" settles into `GET /_components/contact_results?q=grimes`:
 
@@ -121,5 +121,5 @@ And a query with no matches (`GET /_components/contact_results?q=zz`) returns th
 ## Related
 
 - [Tabs](tabs.md) — the same fill-a-stable-container shape, driven by clicks instead of keystrokes.
-- The [shorthands table](../dsl.md#shorthands) and [trigger values](../dsl.md#trigger-values) in the DSL reference.
-- The [tutorial](../tutorial.md) covers the pairing of form field names with declared attributes in depth.
+- The [presets table](../dsl.md#presets) and [trigger values](../dsl.md#trigger-values) in the DSL reference.
+- The [tutorial](../tutorial.md) covers the pairing of form field names with declared params in depth.

data/docs/examples/browser-dialogs.md

@@ -2,7 +2,7 @@
 
 A destructive button guarded by the browser's native `confirm()` dialog — the user gets a chance to back out before the request is ever made, with no dialog component to build and no CSS to write.
 
-This is Weft's take on [htmx's dialogs example](https://htmx.org/examples/dialogs/). The honest point of this page is that Weft has no kwarg for `hx-confirm` — and doesn't need one: raw htmx attributes pass through to the element untouched, side by side with whatever the Weft kwargs expand to.
+This is Weft's take on [htmx's dialogs example](https://htmx.org/examples/dialogs/). The confirm half is one kwarg — [`confirm:`](../dsl.md#confirm) rides the same button the action already wired. The prompt half is deliberately *not* a kwarg (below), and shows the escape hatch that remains for htmx vocabulary Weft doesn't cover.
 
 ## The components
 
@@ -22,7 +22,7 @@ class AccountPanel < Weft::Component
     para "Your account is #{ACCOUNT[:status]}."
     if ACCOUNT[:status] == "active"
       button "Deactivate my account", action: :deactivate,
-             "hx-confirm" => "Deactivate your account? You can sign back in to reactivate."
+             confirm: "Deactivate your account? You can sign back in to reactivate."
     end
   end
 end
@@ -32,25 +32,25 @@ end
 
 ## How it works
 
-**Raw htmx attributes ride along.** Weft intercepts only its own kwargs — `action:`, `trigger:`, and friends. Everything else on an element, string-keyed htmx attributes included, renders as a plain HTML attribute. So `"hx-confirm" => "..."` lands verbatim next to the wiring that [`action:`](../dsl.md#action) expanded, and htmx picks it up like any hand-written page. This is the general escape hatch: whenever htmx has a feature Weft has no vocabulary for, write the attribute yourself.
+**The guard is one modifier kwarg.** [`confirm:`](../dsl.md#confirm) works alongside any interaction kwarg — this action, a [`navigate:`](../dsl.md#navigate), a preset — or standalone on a container, where htmx inheritance applies it to every request fired from inside. Weft consumes the kwarg and emits `hx-confirm` beside the wiring [`action:`](../dsl.md#action) expanded.
 
-**The guard lives in the browser, not on the server.** `hx-confirm` gates the *request*: htmx shows the native dialog and only issues the POST if the user accepts. The endpoint itself is unchanged — a request made outside htmx skips the question entirely. Treat it as protection against misclicks, never as access control; anything truly destructive still needs authorization server-side.
+**The guard lives in the browser, not on the server.** The confirm gates the *request*: htmx shows the native dialog and only issues the POST if the user accepts. The endpoint itself is unchanged — a request made outside htmx skips the question entirely. Treat it as protection against misclicks, never as access control; anything truly destructive still needs authorization server-side.
 
 **The action is ordinary Weft.** `performs :deactivate` runs the write and re-renders the component, which now shows the deactivated state — the standard action contract, unaware that a dialog ever happened.
 
-**`hx-prompt` doesn't carry over.** htmx's companion attribute asks for a line of text and sends the answer as an `HX-Prompt` *request header* — but a Weft action callable receives only the component's resolved attributes, which come from request parameters, so the prompted value never reaches your code. When an action needs user input, give the component a real input: a form field paired with a declared attribute, as in [Click to Edit](click-to-edit.md).
+**There is no `prompt:` kwarg — on purpose.** htmx's companion attribute asks for a line of text and sends the answer as an `HX-Prompt` *request header* — but a Weft action callable receives only the component's resolved params, which come from request parameters, so the prompted value would never reach your code. When an action needs user input, give the component a real input: a form field paired with a declared param, as in [Click to Edit](click-to-edit.md). And if you want the browser's prompt anyway, the escape hatch is always open: kwargs Weft doesn't recognize pass through untouched, so `"hx-prompt" => "..."` renders verbatim — the general pattern whenever htmx has a feature Weft has no vocabulary for.
 
 ## On the wire
 
-The initial render — the confirm attribute sits verbatim beside the expanded action wiring:
+The initial render — the confirm lands beside the expanded action wiring:
 
 ```html
 <div id="account-panel">
   <p>Your account is active.</p>
-  <button hx-confirm="Deactivate your account? You can sign back in to reactivate."
-          hx-post="/_components/account_panel/deactivate"
+  <button hx-post="/_components/account_panel/deactivate"
           hx-target="#account-panel" hx-swap="outerHTML"
-          hx-vals="{}">Deactivate my account</button>
+          hx-vals="{}"
+          hx-confirm="Deactivate your account? You can sign back in to reactivate.">Deactivate my account</button>
 </div>
 ```
 
@@ -67,5 +67,5 @@ The same POST sent from outside the browser — no htmx, no dialog — is accept
 ## Related
 
 - [Modal Dialog](modal-dialog.md) — when you want a dialog you own instead of the browser's.
-- [Click to Edit](click-to-edit.md) — form fields paired with attributes: the Weft answer to "prompt the user for a value."
+- [Click to Edit](click-to-edit.md) — form fields paired with params: the Weft answer to "prompt the user for a value."
 - [`action:`](../dsl.md#action) and [`performs`](../dsl.md#performs--user-initiated-actions) in the DSL reference.

data/docs/examples/bulk-update.md

@@ -17,11 +17,11 @@ TEAM_MEMBERS = {
 class MemberRoster < Weft::Component
   builder_method :member_roster
 
-  attribute :active_ids, default: []
-  attribute :status
+  param :active_ids, default: []
+  param :status
 
-  performs :update, target: "#member-roster" do |attrs|
-    checked = attrs.active_ids
+  performs :update, target: "#member-roster" do |params|
+    checked = params.active_ids
     activated = deactivated = 0
     TEAM_MEMBERS.each do |id, member|
       active = checked.include?(id)
@@ -56,7 +56,7 @@ class MemberRoster < Weft::Component
       end
       input type: "submit", value: "Bulk Update"
     end
-    para attrs.status if attrs.status
+    para params.status if params.status
   end
 end
 ```
@@ -65,15 +65,15 @@ end
 
 ## How it works
 
-**Bracket naming turns the checkboxes into one array.** Every checkbox shares the name `active_ids[]`, and Rack's parameter parsing folds those into a single array under the bracket-less key — so the component's declared `active_ids` attribute receives `["1", "2", "4"]`, and the callable reads it as `attrs.active_ids`. The values arrive as strings, which is why the data stub's keys are strings too. Checkboxes the user leaves unchecked simply aren't in the submission; that's the whole trick of the pattern.
+**Bracket naming turns the checkboxes into one array.** Every checkbox shares the name `active_ids[]`, and Rack's parameter parsing folds those into a single array under the bracket-less key — so the component's declared `active_ids` param receives `["1", "2", "4"]`, and the callable reads it as `params.active_ids`. The values arrive as strings, which is why the data stub's keys are strings too. Checkboxes the user leaves unchecked simply aren't in the submission; that's the whole trick of the pattern.
 
-**The `default: []` is load-bearing.** When *no* boxes are checked, the browser sends no `active_ids` parameter at all, and the attribute falls back to its default. An empty array makes that case mean "deactivate everyone" — and guarantees the callable always has a real array to call `include?` on, rather than `nil`.
+**The `default: []` is load-bearing.** When *no* boxes are checked, the browser sends no `active_ids` parameter at all, and the param falls back to its default. An empty array makes that case mean "deactivate everyone" — and guarantees the callable always has a real array to call `include?` on, rather than `nil`.
 
-**The callable diffs, then reports through its return value.** It compares each member's stored state against the submitted array, counts the flips, and writes the new state. Returning a hash merges it into the attrs for the re-render (see [the callable contract](../dsl.md#the-callable-contract)), so `{ status: "Activated 1 and deactivated 1 members." }` is how the count reaches the status line — `attrs.status` is `nil` on a fresh render and the paragraph only appears after an update.
+**The callable diffs, then reports through its return value.** It compares each member's stored state against the submitted array, counts the flips, and writes the new state. Returning a hash merges it into the params for the re-render (see [the callable contract](../dsl.md#the-callable-contract)), so `{ status: "Activated 1 and deactivated 1 members." }` is how the count reaches the status line — `params.status` is `nil` on a fresh render and the paragraph only appears after an update.
 
-**An array can't anchor a DOM id.** Weft derives a component's DOM id from its first declared attribute — perfect when that's a record id, unusable when it's an array (`id="member-roster-[]"` is not a selector htmx can target). So this component pins its own identity: `set_attribute :id, "member-roster"` fixes the wrapper's id inside `build`, and `performs :update, target: "#member-roster"` points the action's swap at that same anchor. Both live server-side, so every re-rendered fragment carries the same stable wiring.
+**An array can't anchor a DOM id.** Weft derives a component's DOM id from its first declared param — perfect when that's a record id, unusable when it's an array (`id="member-roster-[]"` is not a selector htmx can target). So this component pins its own identity: `set_attribute :id, "member-roster"` fixes the wrapper's id inside `build`, and `performs :update, target: "#member-roster"` points the action's swap at that same anchor. Both live server-side, so every re-rendered fragment carries the same stable wiring.
 
-**The checkboxes tell the truth after the write.** `build` renders each checkbox from the data store, not from the submitted attrs — the response reflects what was actually saved. And since `form(action: :update)` also emits plain `action`/`method` attributes, the whole thing degrades to a normal POST without JavaScript.
+**The checkboxes tell the truth after the write.** `build` renders each checkbox from the data store, not from the submitted params — the response reflects what was actually saved. And since `form(action: :update)` also emits plain `action`/`method` attributes, the whole thing degrades to a normal POST without JavaScript.
 
 ## On the wire
 
@@ -117,6 +117,6 @@ Submitting with every box unchecked sends an empty body; the default kicks in an
 
 ## Related
 
-- [Click to Edit](click-to-edit.md) — the basics of pairing form fields with declared attributes.
+- [Click to Edit](click-to-edit.md) — the basics of pairing form fields with declared params.
 - [Delete Row](delete-row.md) and [Edit Row](edit-row.md) — acting on table rows one at a time instead of all at once.
 - [`performs`](../dsl.md#performs--user-initiated-actions) and [the callable contract](../dsl.md#the-callable-contract) in the DSL reference.

data/docs/examples/click-to-edit.md

@@ -14,16 +14,16 @@ CONTACTS = {
 class ContactCard < Weft::Component
   builder_method :contact_card
 
-  attribute :contact_id
+  param :contact_id
 
   def build(attributes = {})
     super
-    contact = CONTACTS.fetch(attrs.contact_id)
+    contact = CONTACTS.fetch(params.contact_id)
     div { strong "First Name: "; text_node contact[:first_name] }
     div { strong "Last Name: ";  text_node contact[:last_name] }
     div { strong "Email: ";      text_node contact[:email] }
     button "Click To Edit",
-           loads: ContactEditor, with: { contact_id: attrs.contact_id },
+           loads: ContactEditor, with: { contact_id: params.contact_id },
            swap: :replace, target: self
   end
 end
@@ -31,23 +31,23 @@ end
 class ContactEditor < Weft::Component
   builder_method :contact_editor
 
-  attribute :contact_id
-  attribute :first_name
-  attribute :last_name
-  attribute :email
+  param :contact_id
+  param :first_name
+  param :last_name
+  param :email
 
-  transfers :save, to: ContactCard do |attrs|
-    CONTACTS.fetch(attrs.contact_id).merge!(
-      first_name: attrs.first_name, last_name: attrs.last_name, email: attrs.email
+  transfers :save, to: ContactCard do |params|
+    CONTACTS.fetch(params.contact_id).merge!(
+      first_name: params.first_name, last_name: params.last_name, email: params.email
     )
     nil
   end
 
   def build(attributes = {})
     super
-    contact = CONTACTS.fetch(attrs.contact_id)
+    contact = CONTACTS.fetch(params.contact_id)
     form(action: :save) do
-      input(type: "hidden", name: "contact_id", value: attrs.contact_id)
+      input(type: "hidden", name: "contact_id", value: params.contact_id)
       div do
         label("First Name ", for: "first_name")
         input(type: "text", name: "first_name", id: "first_name", value: contact[:first_name])
@@ -62,7 +62,7 @@ class ContactEditor < Weft::Component
       end
       input(type: "submit", value: "Submit")
       button "Cancel", type: "button",
-             loads: ContactCard, with: { contact_id: attrs.contact_id },
+             loads: ContactCard, with: { contact_id: params.contact_id },
              swap: :replace, target: self
     end
   end
@@ -79,7 +79,7 @@ end
 
 **The two components reference each other — without a cycle.** `transfers :save, to: ContactCard` runs in the class body, so `ContactCard` must already be defined; but `loads: ContactEditor` isn't evaluated until render. Defining the display component first therefore breaks the loop with no forward-declaration tricks. This ordering trick generalizes to any two-state component pair.
 
-**Form fields pair with declared attributes.** The editor declares `first_name`, `last_name`, and `email` so its fields reach the save callable as `attrs.first_name` and friends — and `contact_id` rides along as a hidden input, because it's part of the component's identity rather than something the user edits. (This pairing is covered in depth in [the tutorial](../tutorial.md#7-taking-rsvps).)
+**Form fields pair with declared params.** The editor declares `first_name`, `last_name`, and `email` so its fields reach the save callable as `params.first_name` and friends — and `contact_id` rides along as a hidden input, because it's part of the component's identity rather than something the user edits. (This pairing is covered in depth in [the tutorial](../tutorial.md#7-taking-rsvps).)
 
 **It still works without JavaScript.** `form(action: :save)` emits plain `action`/`method` attributes alongside the htmx wiring, so the save degrades to a normal POST. Note `type: "button"` on Cancel — inside a form, a bare `<button>` is a submit button.
 

data/docs/examples/click-to-load.md

@@ -14,16 +14,16 @@ class AgentRows < Weft::Component
 
   PER_PAGE = 6
 
-  attribute :page, default: 1
+  param :page, default: 1, type: :integer
 
   def build(attributes = {})
     super
-    batch = AGENTS[(attrs.page - 1) * PER_PAGE, PER_PAGE]
+    batch = AGENTS[(params.page - 1) * PER_PAGE, PER_PAGE]
     batch.each do |agent|
       div { strong agent[:name]; text_node " — #{agent[:email]} (##{agent[:number]})" }
     end
-    if attrs.page * PER_PAGE < AGENTS.size
-      button "Load More Agents...", load_more: AgentRows, with: { page: attrs.page + 1 }
+    if params.page * PER_PAGE < AGENTS.size
+      button "Load More Agents...", load_more: AgentRows, with: { page: params.page + 1 }
     end
   end
 end
@@ -31,15 +31,15 @@ end
 
 (The `AGENTS` array stands in for your data layer — swap in ActiveRecord or whatever your app uses.)
 
-Render `agent_rows(page: 1)` wherever the list lives, and the pattern takes care of itself from there.
+Render a bare `agent_rows` wherever the list lives — its `page` param defaults to 1 — and the pattern takes care of itself from there.
 
 ## How it works
 
-**One shorthand, no ceremony.** [`load_more:`](../dsl.md#shorthands) is a preset over the [`loads:`](../dsl.md#loads) machinery: trigger `:click`, swap `:replace`, target `:self`. In plain terms — when this button is clicked, fetch the named component and put it where the button was. The call site supplies only what varies: which component to load (`AgentRows`, the component's own class) and its wire attrs (`with: { page: attrs.page + 1 }`).
+**One preset, no ceremony.** [`load_more:`](../dsl.md#presets) is a preset over the [`loads:`](../dsl.md#loads) machinery: trigger `:click`, swap `:replace`, target `:self`. In plain terms — when this button is clicked, fetch the named component and put it where the button was. The call site supplies only what varies: which component to load (`AgentRows`, the component's own class) and its wire params (`with: { page: params.page + 1 }`).
 
 **The component is a chunk, not the whole list.** Each `AgentRows` instance renders one page of agents and, when more remain, the button that fetches the next chunk *in its own place*. Clicking never touches the agents already on screen; the button alone is replaced, and the new chunk arrives with its own button. The recursion bottoms out naturally — the `if` guard means the final chunk simply renders no button.
 
-**Attributes make the chunk addressable.** Declaring `attribute :page, default: 1` gives the component a route ([Routing](../routing.md)) and coerces the wire value: `page=2` arrives as the string `"2"` and reaches `attrs.page` as the Integer `2`, because the default is an Integer.
+**Params make the chunk addressable.** Declaring `param :page, default: 1, type: :integer` gives the component a route ([Routing](../routing.md)) and coerces the wire value: `page=2` arrives as the string `"2"` and reaches `params.page` as the Integer `2`.
 
 **A component can load itself.** `load_more: AgentRows` inside `AgentRows`'s own `build` is unremarkable — the class reference is evaluated at render time, so self-reference needs no tricks.
 
@@ -73,5 +73,5 @@ The last page (`GET /_components/agent_rows?page=4`) renders its agents and no b
 
 - [Infinite Scroll](infinite-scroll.md) — the same next-page mechanic, triggered by scrolling instead of a click, in a real table.
 - [Lazy Loading](lazy-loading.md) — deferring one expensive section rather than paginating many.
-- The [shorthands table](../dsl.md#shorthands) in the DSL reference, including how to register your own preset.
+- The [presets table](../dsl.md#presets) in the DSL reference, including how to register your own preset.
 - For pagination that *replaces* the current page instead of accumulating, [`navigate:`](../dsl.md#navigate) is the better verb.

data/docs/examples/delete-row.md

@@ -16,10 +16,11 @@ CONTACT_BOOK = {
 class ContactRow < Weft::Component
   builder_method :contact_row
 
-  attribute :contact_id
+  param :contact_id
+  receives :contact_id
 
-  dismisses :destroy do |attrs|
-    CONTACT_BOOK.delete(attrs.contact_id)
+  dismisses :destroy do |params|
+    CONTACT_BOOK.delete(params.contact_id)
     nil
   end
 
@@ -29,14 +30,12 @@ class ContactRow < Weft::Component
 
   def build(attributes = {})
     super
-    contact = CONTACT_BOOK[attrs.contact_id]
-    return unless contact
-
+    contact = CONTACT_BOOK[params.contact_id]
     td contact[:name]
     td contact[:email]
     td contact[:status]
     td do
-      button "Delete", action: :destroy, "hx-confirm" => "Are you sure?"
+      button "Delete", action: :destroy, confirm: "Are you sure?"
     end
   end
 end
@@ -60,13 +59,15 @@ end
 
 ## How it works
 
-**The row is the component.** Overriding `tag_name` makes the wrapper a `<tr>`, so each contact renders as a real table row with its own DOM id. The identifying attribute is declared first because that's where the id comes from — `contact_id` of `"1"` yields `id="contact-row-1"`, which is exactly what the delete needs to target.
+**The row is the component.** Overriding `tag_name` makes the wrapper a `<tr>`, so each contact renders as a real table row with its own DOM id. The identifying param is declared first because that's where the id comes from — `contact_id` of `"1"` yields `id="contact-row-1"`, which is exactly what the delete needs to target.
+
+**Each row is handed its id, and declares it as a param too.** The table gives every row a *different* `contact_id` (`contact_row(contact_id: id)`), which is a [`receives`](../dsl.md#receives--caller-hand-offs) hand-off — sibling rows each need a distinct value, and the shared params bag that flows down the render tree can't supply per-row differences. Declaring [`param :contact_id`](../dsl.md#how-the-doors-combine) alongside it means the same id also serializes into the row's own route and the Delete button's payload, so `GET /_components/contact_row?contact_id=1` reconstructs the row on its own and the delete targets the right record.
 
-**`dismisses` is the delete-shaped verb.** It's sugar for a `performs` with `method: :delete, swap: :delete` (see [`dismisses`](../dsl.md#dismisses--remove-from-the-dom)): the button wired with `action: :destroy` issues a `DELETE` to the action's route, the callable removes the record, and on success htmx deletes the target element — the row — from the DOM. The row's identity travels automatically: an action button carries the component's attrs as `hx-vals`. Note there's no non-JavaScript fallback here — plain HTML has no DELETE — which is the nature of the pattern rather than a Weft limitation.
+**`dismisses` is the delete-shaped verb.** It's sugar for a `performs` with `method: :delete, swap: :delete` (see [`dismisses`](../dsl.md#dismisses--remove-from-the-dom)): the button wired with `action: :destroy` issues a `DELETE` to the action's route, the callable removes the record, and on success htmx deletes the target element — the row — from the DOM. The row's identity travels automatically: an action button carries the component's params as `hx-vals`. Note there's no non-JavaScript fallback here — plain HTML has no DELETE — which is the nature of the pattern rather than a Weft limitation.
 
-**The confirmation is one raw attribute.** Kwargs Weft doesn't recognize pass straight through to the element, so `"hx-confirm" => "Are you sure?"` lands on the button as-is and htmx shows the browser's native confirm dialog before sending anything. No request fires on Cancel. For the fuller confirm-and-prompt story, see [Browser Dialogs](browser-dialogs.md).
+**The confirmation is one kwarg.** [`confirm:`](../dsl.md#confirm) rides along on the wired button: htmx shows the browser's native confirm dialog before sending anything, and no request fires on Cancel. For the fuller confirm-and-prompt story, see [Browser Dialogs](browser-dialogs.md).
 
-**The dismissal response is rendered, then thrown away.** htmx ignores the response body on a delete swap, but Weft still renders the component once after the callable runs — so `build` must survive the record being gone, hence the `return unless contact` guard (an empty `<tr>` nobody will see). The trailing `nil` in the callable matters for the same reason: `Hash#delete` returns the deleted record, and a hash returned from a callable merges into the attrs for that final render. If the callable *raises*, Weft overrides the destructive swap (via `HX-Reswap`) so the error rendering appears where the row was, instead of the row silently vanishing.
+**A successful dismissal responds with nothing.** htmx removes the row on its own, so the response carries no body — Weft doesn't render the component it just helped delete, which is why `build` can assume its record exists without guarding. (Out-of-band [`includes`](../dsl.md#includes--companions-in-the-same-response) companions still ride the response when declared — a delete can update the count beside the table it shrinks.) The trailing `nil` in the callable keeps `Hash#delete`'s return value — the deleted record — from merging into the params those companions read. If the callable *raises*, Weft overrides the destructive swap (via `HX-Reswap`) so the error rendering appears where the row was, instead of the row silently vanishing — and the error fragment arrives as a `<tr>` itself, because recovery fragments [adopt the failing component's tag](../error-handling.md#auto-injected-recovery-params), landing as valid table content.
 
 ## On the wire
 
@@ -78,20 +79,17 @@ Each row arrives fully wired — `GET /_components/contact_row?contact_id=1` ret
   <td>angie@macdowell.org</td>
   <td>Active</td>
   <td>
-    <button hx-confirm="Are you sure?" hx-delete="/_components/contact_row/destroy"
+    <button hx-delete="/_components/contact_row/destroy"
             hx-target="#contact-row-1" hx-swap="delete"
-            hx-vals="{&quot;contact_id&quot;:&quot;1&quot;}">Delete</button>
+            hx-vals="{&quot;contact_id&quot;:&quot;1&quot;}"
+            hx-confirm="Are you sure?">Delete</button>
   </td>
 </tr>
 ```
 
-Confirming the dialog sends `DELETE /_components/contact_row/destroy?contact_id=1` (htmx 2 puts DELETE parameters in the query string). The server deletes the record and responds `200` with the guarded, now-empty render — which htmx discards while removing the row:
-
-```html
-<tr id="contact-row-1"></tr>
-```
+Confirming the dialog sends `DELETE /_components/contact_row/destroy?contact_id=1` (htmx 2 puts DELETE parameters in the query string). The server deletes the record and responds `200` with an empty body — there is nothing left worth rendering — and htmx removes the row.
 
-Fetching the table again shows two rows; fetching the deleted row's own URL returns the same empty `<tr>`, confirming the record is gone.
+Fetching the table again shows two rows. Fetching the deleted row's own URL now fails like any other missing-record lookup and lands in the error chain — if stale fetches are a real path in your app, brand them with [`recovers from:`](../error-handling.md).
 
 ## Related