weft 0.1.0

data/docs/examples/tooltip.md

@@ -0,0 +1,88 @@
+# Tooltip
+
+Hovering over an element fetches a small piece of server-rendered detail — a profile card, a definition, a status readout — and places it in a bubble beside the trigger. The detail is rendered fresh from the server on first hover, then stays put.
+
+There's no counterpart for this in the htmx examples catalog; `tooltip:` is Weft-native sugar over the same [`loads:`](../dsl.md#loads) machinery as the other shorthands. It earns its keep when the tooltip content is worth a server round-trip — live data, per-record queries — rather than static text a `title=` attribute could carry.
+
+## The components
+
+```ruby
+TEAM = {
+  "priya" => { role: "Backend",  timezone: "UTC+5:30", focus: "payments migration" },
+  "marco" => { role: "Design",   timezone: "UTC+1",    focus: "checkout redesign" },
+  "june"  => { role: "Support",  timezone: "UTC−8",    focus: "triage rotation" }
+}.freeze
+
+class MemberPeek < Weft::Component
+  builder_method :member_peek
+
+  attribute :handle
+
+  def build(attributes = {})
+    super
+    member = TEAM.fetch(attrs.handle)
+    strong attrs.handle.capitalize
+    para "#{member[:role]} — #{member[:timezone]}"
+    para "Focus: #{member[:focus]}"
+  end
+end
+
+class TeamRoster < Weft::Component
+  builder_method :team_roster
+
+  def build(attributes = {})
+    super
+    h3 "On the project"
+    ul do
+      TEAM.each_key do |handle|
+        li style: "position: relative" do
+          span handle.capitalize, class: "peek-trigger",
+               tooltip: MemberPeek, with: { handle: handle }, target: "#peek-#{handle}"
+          div id: "peek-#{handle}", class: "peek-bubble",
+              style: "position: absolute; left: 8rem; top: 0;"
+        end
+      end
+    end
+  end
+end
+```
+
+(The `TEAM` hash stands in for your data layer; the inline styles are the minimum to float each bubble beside its row — real styling belongs in your stylesheet.)
+
+## How it works
+
+**Hover fetches; the bubble receives.** [`tooltip:`](../dsl.md#shorthands) presets trigger `:hover` and swap `:fill`; the call site says where the content lands. Each name targets its own empty bubble div (`target: "#peek-#{handle}"`), so every row has an independent tooltip slot. The bubbles start empty and cost nothing until hovered.
+
+**`:hover` means *first* hover.** The semantic trigger expands to htmx's `mouseenter once` — the fetch happens the first time the pointer enters, and never again. Be clear about what that buys and what it doesn't: Weft delivers the *content*, once, lazily. It does not show and hide the bubble as the pointer comes and goes — that's presentation, and it belongs to CSS (a `.peek-bubble` hidden until `li:hover`, for instance). After the first hover, showing the tooltip again is free, because the content is already in the page.
+
+**Per-row wire attrs, one component.** Every trigger loads the same `MemberPeek` class with a different `with: { handle: ... }` — the component is written once and addressed per record, which is the same shape as every list-plus-detail pattern in this catalog.
+
+## On the wire
+
+The initial render — each name wired, each bubble empty:
+
+```html
+<li style="position: relative">
+  <span class="peek-trigger" hx-get="/_components/member_peek?handle=priya"
+        hx-swap="innerHTML" hx-target="#peek-priya"
+        hx-trigger="mouseenter once">Priya</span>
+  <div id="peek-priya" class="peek-bubble"
+       style="position: absolute; left: 8rem; top: 0;"></div>
+</li>
+```
+
+The first hover over Priya issues `GET /_components/member_peek?handle=priya`, and the bubble fills:
+
+```html
+<div id="member-peek-priya">
+  <strong>Priya</strong>
+  <p>Backend — UTC+5:30</p>
+  <p>Focus: payments migration</p>
+</div>
+```
+
+## Related
+
+- [Inline Expansion](inline-expansion.md) — the other Weft-native shorthand: click-driven detail that lands *after* its trigger instead of in a bubble.
+- [Lazy Loading](lazy-loading.md) — the same load-once deferral, triggered by visibility instead of the pointer.
+- The [shorthands table](../dsl.md#shorthands) in the DSL reference.

data/docs/examples/updating-other-content.md

@@ -0,0 +1,169 @@
+# Updating Other Content
+
+A form adds a contact, and a contacts table elsewhere on the page — outside the form, not enclosing it, not enclosed by it — updates in the same interaction. One submit, two regions refreshed.
+
+This is Weft's take on [htmx's update-other-content example](https://htmx.org/examples/update-other-content/), which uses the same scenario: a table of contacts with an add-contact form below it. htmx's page is really an essay weighing four manual solutions — expanding the target, out-of-band swaps, event triggers, and a path-dependencies extension — each with its own wiring to write and trade-offs to hold in your head. Weft collapses the choice to declarations: `includes ContactsTable` on the form covers the common case in one line, and a `triggers`/`refreshes on:` pair covers the decoupled case in two. [The full four-way mapping is below.](#htmxs-four-solutions-mapped)
+
+## The components
+
+```ruby
+ADDRESS_BOOK = [
+  { name: "Joe Smith", email: "joe@smith.org" }
+]
+
+class ContactsTable < Weft::Component
+  builder_method :contacts_table
+
+  def build(attributes = {})
+    super
+    table do
+      thead { tr { th "Name"; th "Email" } }
+      tbody do
+        ADDRESS_BOOK.each { |contact| tr { td contact[:name]; td contact[:email] } }
+      end
+    end
+  end
+end
+
+class NewContactForm < Weft::Component
+  builder_method :new_contact_form
+
+  attribute :name
+  attribute :email
+
+  includes ContactsTable
+
+  performs :add do |attrs|
+    ADDRESS_BOOK << { name: attrs.name, email: attrs.email }
+    { name: nil, email: nil }
+  end
+
+  def build(attributes = {})
+    super
+    h3 "Add a contact"
+    form(action: :add) do
+      label("Name ", for: "name")
+      input(type: "text", name: "name", id: "name")
+      label(" Email ", for: "email")
+      input(type: "email", name: "email", id: "email")
+      input(type: "submit", value: "Add Contact")
+    end
+  end
+end
+```
+
+And the page that places them side by side:
+
+```ruby
+class ContactsPage < Weft::Page
+  def build(attributes = {})
+    attributes[:title] = "Contacts"
+    super
+    h1 "Contacts"
+    contacts_table
+    new_contact_form
+  end
+end
+```
+
+(`ADDRESS_BOOK` stands in for your data layer, as usual.)
+
+## How it works
+
+**`includes` declares the relationship once, in the class body.** [`includes ContactsTable`](../dsl.md#includes--companions-in-the-same-response) means: whenever this form responds to an action, render the table too, marked out-of-band. htmx receives one response containing two fragments — the re-rendered form swaps into the form's place as usual, and the table fragment, carrying `hx-swap-oob="true"`, is routed to its own DOM slot by id (`#contacts-table`). One request, one response, two regions updated. This is htmx's out-of-band solution with the response construction, the OOB attribute, and the id bookkeeping all handled for you.
+
+**The included component needs no route.** In this variant `ContactsTable` declares no attributes and no verbs, so it isn't independently addressable — `GET /_components/contacts_table` answers 404 — and that's fine: it renders inside the page and travels inside the form's responses. Companions only need to *render* (see [routing](../routing.md#routable-vs-render-target)).
+
+**The callable resets the form.** An action callable's return value directs the re-render ([the callable contract](../dsl.md#the-callable-contract)): returning a hash merges it into the attrs. Returning `{ name: nil, email: nil }` clears the just-submitted values, so the form comes back empty after each add — htmx's reset-the-form problem solved server-side, with no `hx-on` handler. (It also keeps the component's derived DOM id, which is built from the first attribute's value, stable across renders.)
+
+**Form fields pair with declared attributes.** The form declares `name` and `email` so the submitted fields reach the callable as `attrs.name` and `attrs.email` — the same pairing as every Weft form (covered in depth in [the tutorial](../tutorial.md#7-taking-rsvps)). And since `form(action: :add)` also emits plain `action`/`method` attributes, the add still works without JavaScript; only the tableside update needs htmx.
+
+## The decoupled variant
+
+`includes` is directional: the form knows the table exists. Sometimes it shouldn't — the reacting components may be many, elsewhere, or someone else's. Then the form *announces* and interested components *listen*:
+
+```ruby
+class ContactsTable < Weft::Component
+  # …exactly as before, plus one declaration:
+  refreshes on: "contact-added"
+end
+
+class NewContactForm < Weft::Component
+  # …exactly as before, but in place of `includes ContactsTable`:
+  triggers "contact-added"
+end
+```
+
+[`triggers`](../dsl.md#triggers--announce-to-the-rest-of-the-page) stamps every action response from the form with an `HX-Trigger: contact-added` header; htmx fires that as an event on the page body. [`refreshes on:`](../dsl.md#refreshes--the-client-re-fetches) wires the table's wrapper to listen for it (`from:body`) and re-fetch its own route. The two components never mention each other — any number of components can subscribe to `"contact-added"` without the form changing at all. The trade: each listener re-fetches itself, so a submit costs one extra GET per listener (and the table must now be routable, which its `refreshes` declaration itself ensures).
+
+**Choosing between them:** reach for `includes` when the form naturally knows what it changes — everything arrives in the same response, zero extra requests. Reach for `triggers` when the reactions should be open-ended or the components shouldn't know about each other.
+
+## htmx's four solutions, mapped
+
+| htmx's solution | In Weft |
+| --- | --- |
+| 1. Expand the target | Still available — wrap both regions in one component and re-render it whole — but rarely needed once the next two are declarations. |
+| 2. Out-of-band responses | `includes ContactsTable` on the form. |
+| 3. Triggering events | `triggers "contact-added"` on the form, `refreshes on: "contact-added"` on the table. |
+| 4. Path dependencies (extension) | Not needed — solutions 2 and 3 as declarations cover both coupling directions without an extension. |
+
+## On the wire
+
+The initial page render — two independent regions, and in this variant the table wrapper carries no wiring at all:
+
+```html
+<div id="contacts-table">
+  <table>…Joe Smith…</table>
+</div>
+<div id="new-contact-form">
+  <h3>Add a contact</h3>
+  <form hx-post="/_components/new_contact_form/add" hx-target="#new-contact-form"
+        hx-swap="outerHTML" action="/_components/new_contact_form/add" method="post">
+    …
+  </form>
+</div>
+```
+
+Submitting `POST /_components/new_contact_form/add` with `name=Angie MacDowell&email=angie@macdowell.org` returns one response holding both fragments — the emptied form, then the table marked out-of-band, new row included:
+
+```html
+<div id="new-contact-form">
+  <h3>Add a contact</h3>
+  <form hx-post="/_components/new_contact_form/add" hx-target="#new-contact-form"
+        hx-swap="outerHTML" action="/_components/new_contact_form/add" method="post">
+    …fresh, empty fields…
+  </form>
+</div>
+<div id="contacts-table" hx-swap-oob="true">
+  <table>
+    <thead><tr><th>Name</th><th>Email</th></tr></thead>
+    <tbody>
+      <tr><td>Joe Smith</td><td>joe@smith.org</td></tr>
+      <tr><td>Angie MacDowell</td><td>angie@macdowell.org</td></tr>
+    </tbody>
+  </table>
+</div>
+```
+
+In the decoupled variant, the same submit instead answers with the form alone plus the event header:
+
+```
+HTTP/1.1 200 OK
+content-type: text/html;charset=utf-8
+hx-trigger: contact-added
+```
+
+…and the table, whose wrapper rendered as
+
+```html
+<div id="contacts-table" hx-get="/_components/contacts_table"
+     hx-trigger="contact-added from:body" hx-swap="outerHTML">
+```
+
+hears the event and issues `GET /_components/contacts_table`, which returns the fresh table with both rows.
+
+## Related
+
+- [Click to Edit](click-to-edit.md) — the form-fields-pair-with-attributes pattern this example builds on.
+- [`includes`](../dsl.md#includes--companions-in-the-same-response), [`triggers`](../dsl.md#triggers--announce-to-the-rest-of-the-page), and [`refreshes`](../dsl.md#refreshes--the-client-re-fetches) in the DSL reference.
+- `includes` accepts `on: :action_name` to scope a companion to one action, and a block to map the primary component's attrs onto the companion's — see [the DSL reference](../dsl.md#includes--companions-in-the-same-response).

data/docs/examples/value-select.md

@@ -0,0 +1,109 @@
+# Value Select
+
+Two selects, where the first drives the second: pick a car make, and the model select repopulates with that make's models — no page reload, no hand-written JavaScript.
+
+This is Weft's take on [htmx's cascading-selects example](https://htmx.org/examples/value-select/), with one structural difference. Their server returns bare `<option>` tags that swap into the model select's interior; a Weft component brings its own wrapper element, so here the model select *is* the component — changing the make fetches a fresh `<select>` and swaps it into a stable slot.
+
+## The components
+
+```ruby
+CAR_MODELS = {
+  "audi"   => %w[A1 A4 A6],
+  "toyota" => %w[Landcruiser Tacoma Yaris],
+  "bmw"    => %w[325i 325ix X5]
+}.freeze
+
+class ModelSelect < Weft::Component
+  builder_method :model_select
+
+  attribute :make, default: "audi"
+
+  def build(attributes = {})
+    super
+    set_attribute :name, "model"
+    CAR_MODELS.fetch(attrs.make).each do |model|
+      option model, value: model.downcase
+    end
+  end
+
+  def tag_name
+    "select"
+  end
+end
+```
+
+The make select needs no component of its own — it's plain markup in the page, with the Weft wiring as kwargs:
+
+```ruby
+class CarsPage < Weft::Page
+  def build(attributes = {})
+    super
+    div do
+      label "Make ", for: "make"
+      select name: "make", id: "make",
+             loads: ModelSelect, trigger: "change", swap: :fill, target: "#models" do
+        option "Audi",   value: "audi"
+        option "Toyota", value: "toyota"
+        option "BMW",    value: "bmw"
+      end
+    end
+    div do
+      label "Model "
+      span id: "models" do
+        model_select(make: "audi")
+      end
+    end
+  end
+end
+```
+
+(The `CAR_MODELS` hash stands in for your data layer, as usual.)
+
+## 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`.
+
+**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.
+
+**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.
+
+**`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
+
+The initial render of the two selects:
+
+```html
+<select name="make" id="make" hx-get="/_components/model_select"
+        hx-swap="innerHTML" hx-target="#models" hx-trigger="change">
+  <option value="audi">Audi</option>
+  <option value="toyota">Toyota</option>
+  <option value="bmw">BMW</option>
+</select>
+...
+<span id="models">
+  <select id="model-select-audi" name="model">
+    <option value="a1">A1</option>
+    <option value="a4">A4</option>
+    <option value="a6">A6</option>
+  </select>
+</span>
+```
+
+Choosing Toyota sends `GET /_components/model_select?make=toyota`, which returns the fresh select:
+
+```html
+<select id="model-select-toyota" name="model">
+  <option value="landcruiser">Landcruiser</option>
+  <option value="tacoma">Tacoma</option>
+  <option value="yaris">Yaris</option>
+</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.
+
+## 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.

data/docs/routing.md

@@ -0,0 +1,131 @@
+# Routing
+
+Weft has no routes file. Defining a `Weft::Component` or `Weft::Page` subclass registers it, and `Weft::Router` serves it: components as HTML fragments at derived paths, pages as full documents at their declared patterns, actions and SSE streams at paths derived from their components. This document is the reference for how those routes come to be — and how to control the parts you sometimes need to.
+
+**In this document:**
+
+- [Mounting the Router](#mounting-the-router)
+- [Component routes](#component-routes), including [action routes](#action-routes) and [stream endpoints](#stream-endpoints)
+- [Page routes](#page-routes)
+- [What routes — and what doesn't](#what-routes--and-what-doesnt), including [`abstract!` and `routable!`](#abstract-and-routable) and [routable vs. render target](#routable-vs-render-target)
+- [Collision detection](#collision-detection)
+- [Code reloading](#code-reloading)
+
+## Mounting the Router
+
+`Weft::Router` is Rack middleware. It serves the requests it recognizes and passes the rest through:
+
+```ruby
+# config.ru — alongside an existing app
+use Weft::Router
+run MyApp
+
+# config.ru — standalone, Weft is the whole app
+run Weft::Router
+```
+
+In standalone mode there is no downstream app, so unmatched requests render the configured not-found page instead (see [Error handling](error-handling.md)).
+
+One prerequisite worth knowing: registration happens when a class is *defined* (via Ruby's `inherited` hook), so your component and page files must be loaded before the first request. If you use an autoloader, eager-load these directories at boot.
+
+## 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).
+
+The path derives from the class name: strip a trailing `Component` if present, snake-case what's left, prefix `/_components/`. Namespaces become path segments.
+
+| Class | Route |
+| --- | --- |
+| `OrdersPanel` | `/_components/orders_panel` |
+| `OrdersPanelComponent` | `/_components/orders_panel` |
+| `Oms::OrderHeader` | `/_components/oms/order_header` |
+
+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)).
+
+To change the path for one class, set `component_path` on it — a string, or a proc receiving the class:
+
+```ruby
+class OrdersPanel < Weft::Component
+  self.component_path = "/api/panels/orders"
+end
+```
+
+The setting is inherited by subclasses (handy on an abstract base for a whole family). To change the convention app-wide instead, replace the [`component_path` configuration proc](configuration.md#component_path).
+
+### Action routes
+
+Actions declared with `performs`/`transfers`/`dismisses` route under their component's path:
+
+- **Named actions** get a subpath: `performs :advance` on `Oms::OrderHeader` routes at `POST /_components/oms/order_header/advance`.
+- **Nameless actions** route at the component's own path, distinguished by HTTP method: `performs(method: :delete)` answers `DELETE /_components/oms/order_header`. A nameless GET action intercepts the component's render route itself.
+
+The HTTP method comes from the declaration's `method:` kwarg (default `:post`); the Router answers GET, POST, PUT, DELETE, and PATCH.
+
+### Stream endpoints
+
+A component declaring `pushes` also gets an SSE endpoint at its path plus the stream suffix — by default, `/_components/order_feed/_stream`. The component's rendered `sse-connect` URL and the Router's stream handling both derive from the same [`stream_suffix` setting](configuration.md#stream_suffix), so they can't drift apart. The suffix's leading underscore keeps stream endpoints from ever colliding with a nested component path, since path segments derived from Ruby class names can't begin with an underscore.
+
+## 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:
+
+```ruby
+class OrderDetailPage < Weft::Page
+  self.page_path = "/orders/:order_id"
+  attribute :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.
+
+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).
+
+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 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).
+
+### `abstract!` and `routable!`
+
+When the inference gets it wrong, override it — per class, in either direction:
+
+```ruby
+class ApplicationPage < Weft::Page
+  abstract!            # shared assets and recoveries; not itself a destination
+end
+```
+
+`abstract!` marks a class non-routable no matter what it declares; `routable!` forces the opposite. The override applies only to the class that declares it — subclasses of an abstract base infer (or declare) their own routability, so the common pattern of an abstract `ApplicationPage`/`ApplicationComponent` with concrete routable children just works.
+
+### 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.
+
+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.
+
+## Collision detection
+
+Distinct classes can resolve to the same route — two same-named classes in different namespaces under a custom `component_path` proc, a page pattern matching a component path, a class named such that suffix-stripping collides with a sibling. Rather than letting one silently shadow the other, Weft validates the whole route table on the first request: every routable component's path, each component's reserved stream endpoint, and every routable page pattern. Any duplicate raises `Weft::InvalidDefinition` naming both parties:
+
+```
+Route collision on "/_components/orders_panel": component Oms::OrdersPanel and
+component Admin::OrdersPanel resolve to the same route. Rename one class, set an
+explicit component_path/page_path, or mark one abstract! if it should not route.
+```
+
+The same validation rejects malformed paths (anything that isn't a string beginning with `/`) from a misbehaving custom proc. Validation runs once and is memoized; registering a new class re-arms it. Non-routable classes occupy no route and can never collide.
+
+## 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.
+
+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.