feat(routing): add routing documentation and route directive reference (#90)

### Why

Routing is a core feature that touches every layer of WebUI — protocol, parser, 
handler, FFI, and a new client-side router package. Before reviewing any code, 
reviewers need to understand what the routing system does, how servers and clients 
interact, and what contract they follow. Shipping docs first gives reviewers 
(and future contributors) the full mental model before the implementation lands.

### What

Two new documentation pages and updates across existing docs:

- **`<route>` directive reference** — documents the HTML syntax developers write: 
  `path`, `name`, `component`, `exact` attributes, parameter segments (`:id`, 
  `:id?`, `*splat`), specificity-based matching, and how the server renders 
  matched vs non-matched routes during SSR.

- **Routing guide** — end-to-end walkthrough of the routing system: installing 
  `@microsoft/webui-router`, starting the `Router` class after hydration, 
  opt-in lazy loading with dynamic imports, the `webui:route:navigated` event, 
  and critically the **server contract for JSON partials** — when the client 
  navigates, it sends `Accept: application/json` with an inventory bitmask, 
  and the server returns `{ state, templates, inventory, path }` instead of 
  full HTML. Includes implementation examples for Node/Express and C#/.NET.

- **Handler docs updated** — all platform handler pages (Rust, Node, FFI) now 
  show the new `RenderOptions` parameter with `entry_id` and `request_path`, 
  so developers aren't surprised by the signature change in later PRs.

- **Installation page** — added `@microsoft/webui-router` as an optional 
  dependency with install commands and a link to the routing guide.

- **Router npm README** — package-level documentation for npmjs.com: quick 
  start, API reference, path syntax table, lazy loading setup, server contract.

### How

Docs-only PR — no Rust or TypeScript logic changes. The handler doc examples 
reference `RenderOptions` which doesn't exist on `main` yet (it lands in PR3). 
This is intentional: the docs describe the target API so reviewers can evaluate 
the design before the implementation.

Author: mohamedmansour

DESIGN.md

@@ -507,7 +507,7 @@ pub trait ParserPlugin {
 - Skips FAST-specific runtime attributes (`@click`, `f-ref`, `f-slotted`, `f-children`)
 - Emits `Plugin` fragments with u32 LE attribute binding counts
 - Tracks components and injects `<f-template>` wrappers at body end
-- Converts BTR syntax to FAST syntax: `<if>`→`<f-when>`, `<for>`→`<f-repeat>`, `{{expr}}`→`{expr}` in `:attr` values
+- Converts syntax to FAST syntax: `<if>`→`<f-when>`, `<for>`→`<f-repeat>`, `{{expr}}`→`{expr}` in `:attr` values
 
 **Usage:**
 ```rust

crates/webui-parser/src/plugin/fast.rs

@@ -1,7 +1,7 @@
 //! FAST parser plugin for the WebUI parser.
 //!
 //! Tracks component definitions during HTML parsing and generates `<f-template>`
-//! wrappers at body end. Converts BTR template syntax (`<if>`, `<for>`, `{{}}`)
+//! wrappers at body end. Converts WebUI Framework template syntax (`<if>`, `<for>`, `{{}}`)
 //! into FAST-compatible syntax (`<f-when>`, `<f-repeat>`, `{}`).
 
 use super::ParserPlugin;
@@ -20,7 +20,7 @@ struct TrackedComponent {
 /// Implements the `ParserPlugin` trait for the FAST framework:
 /// - Filters FAST-specific runtime binding attributes (`@click`, `f-ref`, etc.)
 /// - Tracks components encountered during parsing
-/// - Generates `<f-template>` wrappers with converted BTR→FAST syntax at body end
+/// - Generates `<f-template>` wrappers with converted FAST syntax at body end
 /// - Emits binding attribute counts as `Plugin` protocol fragment data
 pub struct FastParserPlugin {
     /// Components tracked during parsing, in discovery order.
@@ -118,7 +118,7 @@ impl ParserPlugin for FastParserPlugin {
     }
 }
 
-/// Convert BTR template syntax to FAST syntax in HTML content.
+/// Convert WebUI Framework template syntax to FAST syntax in HTML content.
 ///
 /// Performs the following transformations without regex:
 /// - `<if condition="EXPR">` → `<f-when value="{EXPR}">`
@@ -655,7 +655,7 @@ mod tests {
         assert_eq!(output.matches("<f-template name=\"my-card\">").count(), 1);
     }
 
-    // --- BTR→FAST syntax conversion ---
+    // --- FAST syntax conversion ---
 
     #[test]
     fn convert_if_to_f_when() {

docs/.vitepress/config.js

@@ -61,10 +61,12 @@ export default {
                 { text: 'Overview', link: '/guide/concepts/directives/' },
                 { text: '<if> Conditional', link: '/guide/concepts/directives/if' },
                 { text: '<for> Loop', link: '/guide/concepts/directives/for' },
+                { text: '<route> Routing', link: '/guide/concepts/directives/route' },
                 { text: '{{}} Signals', link: '/guide/concepts/directives/signals' },
                 { text: 'Attribute Directives', link: '/guide/concepts/directives/attributes' },
               ]
             },
+            { text: 'Routing', link: '/guide/concepts/routing' },
             { text: 'Hydration & Interactivity', link: '/guide/concepts/hydration', items: [
               { text: 'Class Definition', link: '/guide/concepts/hydration#class-definition' },
               { text: 'Templating', link: '/guide/concepts/hydration#templating' },

docs/guide/concepts/directives/index.md

@@ -8,6 +8,7 @@ WebUI Framework provides the following core directives:
 
 - [**`<if>` Conditional Rendering**](./if) - Conditionally render content based on expressions
 - [**`<for>` Loop Iteration**](./for) - Iterate over collections to generate repeated content
+- [**`<route>` Routing**](./route) - Define client-side routes that map URL paths to components
 - [**<code v-pre>{{}}</code> Signal Binding**](./signals) - Insert dynamic values with automatic HTML escaping
 - [**<code v-pre>{{{}}}</code> Raw Signal Binding**](./signals#raw-signals) - Insert unescaped HTML content
 - [**Attribute Directives**](./attributes) - Bind dynamic data to HTML attributes (`{{}}`, `?`, `:`, and mixed)

docs/guide/concepts/directives/route.md

@@ -0,0 +1,116 @@
+# `<route>` Directive
+
+The `<route>` directive defines a client-side route that maps a URL path to a component. At build time, `<route>` elements are compiled into `<webui-route>` custom elements. At runtime, the server renders the matched route's component and the client router handles subsequent navigations.
+
+## Basic Usage
+
+```html
+<main>
+  <route path="/" name="home" component="home-page" exact />
+  <route path="/users" name="users" component="user-list" exact />
+  <route path="/users/:id" name="user-detail" component="user-detail" exact />
+</main>
+```
+
+The server matches the request path against the defined routes and renders the matching component with its state. Non-matching routes are rendered hidden.
+
+## Attributes
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `path` | Yes | URL path template to match (e.g., `/users/:id`) |
+| `component` | Yes | Tag name of the component to render (e.g., `user-detail`) |
+| `name` | No | Unique name for the route (used in navigation events) |
+| `exact` | No | Only match when the path matches exactly (no prefix matching) |
+
+## Path Parameters
+
+Route paths support dynamic segments that capture values from the URL:
+
+### Required Parameters
+
+Use `:name` to capture a path segment:
+
+```html
+<route path="/users/:id" component="user-detail" exact />
+```
+
+Matches `/users/42` → `{ id: "42" }`
+
+### Optional Parameters
+
+Use `:name?` for optional segments:
+
+```html
+<route path="/search/:query?" component="search-page" exact />
+```
+
+Matches both `/search` and `/search/hello` → `{ query: "hello" }`
+
+### Splat (Catch-all)
+
+Use `*name` to capture the rest of the path:
+
+```html
+<route path="/files/*path" component="file-browser" />
+```
+
+Matches `/files/docs/readme.md` → `{ path: "docs/readme.md" }`
+
+## Route Specificity
+
+When multiple routes can match a path, WebUI picks the most specific one — the route with the most literal (non-parameter) segments wins.
+
+```html
+<route path="/users/add" component="user-form" exact />
+<route path="/users/:id" component="user-detail" exact />
+```
+
+A request to `/users/add` matches the first route (2 literal segments) over the second (1 literal + 1 param).
+
+## Exact vs Prefix Matching
+
+By default, routes use prefix matching — `/users` matches `/users`, `/users/42`, and `/users/42/edit`. Add the `exact` attribute to require a full match:
+
+```html
+<!-- Prefix: matches /app, /app/settings, /app/anything -->
+<route path="/app" component="app-shell" />
+
+<!-- Exact: only matches /app/settings -->
+<route path="/app/settings" component="settings-page" exact />
+```
+
+## Inside Components
+
+Routes are typically placed inside a shell component's template:
+
+```html
+<!-- app-shell.html -->
+<template>
+  <header><nav-bar></nav-bar></header>
+  <main>
+    <route path="/" name="dashboard" component="dashboard-page" exact />
+    <route path="/contacts" name="contacts" component="contacts-page" exact />
+    <route path="/contacts/:id" name="detail" component="contact-detail" exact />
+  </main>
+</template>
+```
+
+The shell component is rendered on every page. Only the matched route's component changes.
+
+## Server-Side Rendering
+
+When the server receives a request, it matches the URL against the route definitions and:
+
+1. **Matched route** — rendered visible with its component's full HTML content (including declarative shadow root)
+2. **Non-matched routes** — rendered hidden (`style="display:none"`) with no content
+
+This means the browser displays the correct page instantly, before any JavaScript loads.
+
+## Notes and Limitations
+
+- Route elements are converted to `<webui-route>` custom elements at build time
+- Routes can be placed in the light DOM or inside a component's shadow DOM
+- The server performs route matching during SSR — no client JavaScript is needed for the initial render
+- For client-side navigation between routes, install the [`@microsoft/webui-router`](/guide/concepts/routing) package
+- Self-closing syntax (`<route ... />`) and open/close syntax (`<route ...>...</route>`) are both supported

docs/guide/concepts/handlers/ffi.md

@@ -51,7 +51,8 @@ void *handler = webui_handler_create();
 uint8_t *data = load_file("dist/protocol.bin", &len);
 
 // Render
-char *html = webui_handler_render(handler, data, len, state_json);
+char *html = webui_handler_render(handler, data, len, state_json,
+                                  "index.html", request_path);
 if (html) {
     // use html...
     webui_free(html);
@@ -68,7 +69,7 @@ webui_handler_destroy(handler);
 | `webui_render` | `char *(const char *html, const char *data_json)` | Parse + render in one call |
 | `webui_handler_create` | `void *()` | Create a reusable handler (no plugin) |
 | `webui_handler_create_with_plugin` | `void *(const char *plugin_id)` | Create a handler with a named plugin (e.g., `"fast"`) |
-| `webui_handler_render` | `char *(void *handler, const uint8_t *data, uintptr_t len, const char *json)` | Render a pre-compiled protocol |
+| `webui_handler_render` | `char *(void *handler, const uint8_t *data, uintptr_t len, const char *json, const char *entry_id, const char *request_path)` | Render a pre-compiled protocol with route matching |
 | `webui_handler_destroy` | `void(void *handler)` | Destroy a handler instance |
 | `webui_free` | `void(char *ptr)` | Free a string returned by any render function |
 | `webui_last_error` | `const char *()` | Get per-thread error message |
@@ -114,7 +115,8 @@ if (handler == NULL) {
 }
 
 // Render — output includes hydration markers
-char *html = webui_handler_render(handler, protocol_data, protocol_len, state_json);
+char *html = webui_handler_render(handler, protocol_data, protocol_len,
+                                  state_json, "index.html", "/");
 
 webui_free(html);
 webui_handler_destroy(handler);

docs/guide/concepts/handlers/index.md

@@ -27,12 +27,13 @@ This consistent approach ensures that the same template produces identical resul
 While the specific implementation details vary between languages, all handlers provide a similar API:
 
 ```
-handle(protocol, state, writer)
+handle(protocol, state, options, writer)
 ```
 
 Where:
 - `protocol` is the WebUI protocol object
 - `state` is the data object with values to be rendered
+- `options` specifies the entry fragment and request path for [route matching](/guide/concepts/routing)
 - `writer` is a callback or interface for writing the rendered output
 
 ## Plugin System
@@ -41,7 +42,7 @@ Handlers support an optional **plugin system** for injecting framework-specific
 
 ```
 handler = Handler::with_plugin(plugin)
-handler.handle(protocol, state, writer)
+handler.handle(protocol, state, options, writer)
 ```
 
 When no plugin is configured, the handler renders plain HTML. When a plugin is loaded (e.g., `FastHydrationPlugin`), it injects markers that enable client-side hydration.

docs/guide/concepts/handlers/node.md

@@ -14,32 +14,33 @@ npm install @microsoft/webui
 ```js [Node.js]
 import { createServer } from 'node:http';
 import { readFileSync } from 'node:fs';
-import { renderStream } from '@microsoft/webui';
+import { render } from '@microsoft/webui';
 
 const protocol = readFileSync('./dist/protocol.bin');
 
 const server = createServer((req, res) => {
-  if (req.url === '/') {
-    res.writeHead(200, { 'Content-Type': 'text/html' });
-    renderStream(protocol, { title: "Home" }, (chunk) => res.write(chunk));
-    res.end();
-  }
+  res.writeHead(200, { 'Content-Type': 'text/html' });
+  render(protocol, JSON.stringify({ title: "Home" }), 'index.html', req.url,
+    (chunk) => res.write(chunk));
+  res.end();
 });
 
 server.listen(3000);
 ```
 
 ```ts [Bun]
-import { renderStream } from '@microsoft/webui';
+import { render } from '@microsoft/webui';
 
 const protocol = Bun.file('./dist/protocol.bin');
 const protocolData = Buffer.from(await protocol.arrayBuffer());
 
 Bun.serve({
   port: 3000,
   fetch(req) {
+    const url = new URL(req.url);
     const chunks: string[] = [];
-    renderStream(protocolData, { title: "Home" }, (chunk) => chunks.push(chunk));
+    render(protocolData, JSON.stringify({ title: "Home" }), 'index.html', url.pathname,
+      (chunk: string) => chunks.push(chunk));
     return new Response(chunks.join(''), {
       headers: { 'Content-Type': 'text/html' },
     });
@@ -48,14 +49,16 @@ Bun.serve({
 ```
 
 ```ts [Deno]
-import { renderStream } from '@microsoft/webui';
+import { render } from '@microsoft/webui';
 
 const protocol = Deno.readFileSync('./dist/protocol.bin');
 const protocolData = Buffer.from(protocol);
 
-Deno.serve({ port: 3000 }, (_req) => {
+Deno.serve({ port: 3000 }, (req) => {
+  const url = new URL(req.url);
   const chunks: string[] = [];
-  renderStream(protocolData, { title: "Home" }, (chunk) => chunks.push(chunk));
+  render(protocolData, JSON.stringify({ title: "Home" }), 'index.html', url.pathname,
+    (chunk: string) => chunks.push(chunk));
   return new Response(chunks.join(''), {
     headers: { 'Content-Type': 'text/html' },
   });
@@ -68,8 +71,7 @@ Deno.serve({ port: 3000 }, (_req) => {
 | Function | Description |
 |----------|-------------|
 | `build(options)` | Build templates into a protocol. Returns `{ protocol, cssFiles, stats }` |
-| `render(protocol, state)` | Render protocol to HTML string |
-| `renderStream(protocol, state, onChunk)` | Stream rendered HTML fragments via callback |
+| `render(protocol, state, entry, requestPath, onChunk, plugin?)` | Render protocol with route matching, streaming HTML fragments via callback |
 | `inspect(protocol)` | Convert protocol to JSON for debugging |
 
 ### BuildOptions

docs/guide/concepts/handlers/rust.md

@@ -14,8 +14,8 @@ serde_json = "1"
 
 ::: code-group
 ```rust [Actix Web]
-use actix_web::{web, App, HttpServer, HttpResponse};
-use webui::{WebUIHandler, ResponseWriter, WebUIProtocol};
+use actix_web::{web, App, HttpServer, HttpRequest, HttpResponse};
+use webui::{WebUIHandler, RenderOptions, ResponseWriter, WebUIProtocol};
 use serde_json::json;
 use std::fs;
 
@@ -38,11 +38,12 @@ async fn main() -> std::io::Result<()> {
     HttpServer::new(move || {
         App::new()
             .app_data(protocol.clone())
-            .route("/", web::get().to(|proto: web::Data<WebUIProtocol>| async move {
+            .route("/{path:.*}", web::get().to(|proto: web::Data<WebUIProtocol>, req: HttpRequest| async move {
                 let state = json!({ "title": "Home" });
                 let mut writer = StringWriter(String::new());
                 let mut handler = WebUIHandler::new();
-                handler.handle(&proto, &state, &mut writer).unwrap();
+                let options = RenderOptions::new("index.html", req.path());
+                handler.handle(&proto, &state, &options, &mut writer).unwrap();
                 HttpResponse::Ok().content_type("text/html").body(writer.0)
             }))
     })
@@ -53,8 +54,8 @@ async fn main() -> std::io::Result<()> {
 ```
 
 ```rust [Axum]
-use axum::{routing::get, Router, extract::State};
-use webui::{WebUIHandler, ResponseWriter, WebUIProtocol};
+use axum::{routing::get, Router, extract::{State, Request}};
+use webui::{WebUIHandler, RenderOptions, ResponseWriter, WebUIProtocol};
 use serde_json::json;
 use std::{fs, sync::Arc};
 
@@ -74,11 +75,12 @@ async fn main() {
     let protocol = Arc::new(WebUIProtocol::from_protobuf(&protocol_bytes).unwrap());
 
     let app = Router::new()
-        .route("/", get(|State(proto): State<Arc<WebUIProtocol>>| async move {
+        .route("/{*path}", get(|State(proto): State<Arc<WebUIProtocol>>, req: Request| async move {
             let state = json!({ "title": "Home" });
             let mut writer = StringWriter(String::new());
             let mut handler = WebUIHandler::new();
-            handler.handle(&proto, &state, &mut writer).unwrap();
+            let options = RenderOptions::new("index.html", req.uri().path());
+            handler.handle(&proto, &state, &options, &mut writer).unwrap();
             axum::response::Html(writer.0)
         }))
         .with_state(protocol);
@@ -92,7 +94,7 @@ async fn main() {
 use hyper::{server::conn::http1, service::service_fn, body::Bytes, Request, Response};
 use hyper_util::rt::TokioIo;
 use http_body_util::Full;
-use webui::{WebUIHandler, ResponseWriter, WebUIProtocol};
+use webui::{WebUIHandler, RenderOptions, ResponseWriter, WebUIProtocol};
 use serde_json::json;
 use std::{fs, sync::Arc};
 
@@ -117,13 +119,14 @@ async fn main() {
         let proto = protocol.clone();
         tokio::spawn(async move {
             http1::Builder::new()
-                .serve_connection(TokioIo::new(stream), service_fn(move |_: Request<_>| {
+                .serve_connection(TokioIo::new(stream), service_fn(move |req: Request<_>| {
                     let proto = proto.clone();
                     async move {
                         let state = json!({ "title": "Home" });
                         let mut writer = StringWriter(String::new());
                         let mut handler = WebUIHandler::new();
-                        handler.handle(&proto, &state, &mut writer).unwrap();
+                        let options = RenderOptions::new("index.html", req.uri().path());
+                        handler.handle(&proto, &state, &options, &mut writer).unwrap();
                         Ok::<_, hyper::Error>(Response::new(Full::new(Bytes::from(writer.0))))
                     }
                 }))

docs/guide/concepts/plugins/index.md

@@ -68,7 +68,7 @@ During `webui build --plugin=fast`, the parser plugin:
 - **Skips framework attributes**: `@click`, `f-ref`, `f-slotted`, `f-children` are removed from the protocol (they're handled client-side)
 - **Counts dynamic bindings**: Emits binding counts per element as `Plugin` fragments for the handler
 - **Tracks components**: Records all custom elements discovered during parsing
-- **Injects `<f-template>` wrappers**: At `</body>`, injects template wrappers for each component with BTR→FAST syntax conversion
+- **Injects `<f-template>` wrappers**: At `</body>`, injects template wrappers for each component with FAST syntax conversion
 
 #### Syntax Conversion