npm - @ilha/router - Versions diffs - 0.9.1 → 0.10.0 - Mend

@ilha/router 0.9.1 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md +70 -33
package/dist/head.d.ts +67 -0
package/dist/http.d.ts +28 -0
package/dist/index.d.ts +64 -69
package/dist/index.js +3 -2247
package/dist/{plugin-DogkskcY.js → plugin-CmI3Brr2.js} +107 -102
package/dist/plugin.d.ts +18 -1
package/dist/route-match.d.ts +22 -0
package/dist/{rspack.d.ts → rsbuild.d.ts} +2 -2
package/dist/rsbuild.js +10 -0
package/dist/server-island.d.ts +17 -2
package/dist/server-island.js +13 -25
package/dist/server-islands.d.ts +16 -2
package/dist/snapshot-CsEaY6h_.js +337 -0
package/dist/snapshot.d.ts +1 -0
package/dist/src-B5dHU24f.js +2161 -0
package/dist/ssr-BxrcUYy5.js +498 -0
package/dist/ssr.d.ts +182 -0
package/dist/ssr.js +2 -159
package/dist/vite.js +1 -1
package/package.json +7 -14
package/dist/request-scope-C4reU4v0.js +0 -34
package/dist/rolldown.d.ts +0 -6
package/dist/rolldown.js +0 -10
package/dist/rspack.js +0 -10
package/dist/server-island-registry.d.ts +0 -77
package/dist/server-island-registry.js +0 -134

package/README.md CHANGED Viewed

@@ -227,7 +227,7 @@ Renders `<div data-router-empty></div>` when no route matches.
 ---
-#### `.renderHydratable(url, registry, options?, request?)` — server / SSR
+#### `.renderHydratable(urlOrRequest, registry, options?, request?)` — server / SSR
 Async variant of `.render()` that outputs HTML with `data-ilha` hydration markers so the client can rehydrate without a full re-render. If a loader is registered for the matched route, it runs first and its return value is serialized into `data-ilha-props`.
@@ -236,19 +236,23 @@ const html = await router().route("/", HomePage).renderHydratable("/", registry)
 // → '<div data-router-view><div data-ilha="Home">…</div></div>'
 ```
+All server render APIs accept a `Request` as the first argument — route, origin, headers, and loader context derive from it, so server handlers can pass the real request directly.
+> **Redirects.** For callers using the string API, a loader redirect is encoded as a `<meta http-equiv="refresh">` tag. This is deprecated: it can't set a real HTTP status. Prefer `.renderResponse()` or `.respond()` to emit a proper 302.
 If the active island is not found in the registry, falls back to plain SSR and emits a `console.warn`.
 **Options** extend `HydratableOptions` from `ilha`:
 | Option     | Type      | Default | Description                                           |
 | ---------- | --------- | ------- | ----------------------------------------------------- |
-| `snapshot` | `boolean` | `true`  | Embed island state as `data-ilha-state` for hydration |
+| `snapshot` | `boolean` | `false` | Embed island state as `data-ilha-state` for hydration |
 ---
-#### `.renderResponse(url, registry, options?, request?)` — server / SSR
+#### `.renderResponse(urlOrRequest, registry, options?, request?)` — server / SSR
-Structured-envelope variant of `.renderHydratable()`. Returns a `RenderResponse` discriminated union instead of a raw HTML string, so the host server can emit proper HTTP status codes for redirects and loader errors.
+Structured-envelope variant of `.renderHydratable()`. Returns a `RenderResponse` discriminated union instead of a raw HTML string, so the host server can emit proper HTTP status codes for redirects and loader errors. Accepts a `Request` as the first argument.
 ```ts
 const res = await router()
@@ -270,11 +274,25 @@ return new Response(res.html, { headers: { "content-type": "text/html" } });
 | `"redirect"` | `to: string`, `status: number`                      | Loader called `redirect()`                 |
 | `"error"`    | `status: number`, `message: string`, `html: string` | Loader called `error()` or threw           |
+#### `.respond(urlOrRequest, registry, options?)` — server / SSR
+Renders a route to a ready-to-send HTTP `Response`, handling redirects, loader errors, and security headers (`Content-Type`, `X-Content-Type-Options: nosniff`, `Referrer-Policy`, `Cache-Control: no-store`, and an optional CSP nonce). Pass a `shell` to inject the serialized `<head>` into a document shell.
+```ts
+const response = await router()
+  .route("/", HomePage)
+  .respond(new Request(request.url), registry, {
+    cspNonce,
+    shell: (head, html) =>
+      `<!doctype html><html lang="en"><head>${head.headTags}</head><body>${html}</body></html>`,
+  });
+```
 ---
-#### `.runLoader(url, request?)` — server / SSR
+#### `.runLoader(urlOrRequest, request?)` — server / SSR
-Runs the loader chain for the matched route without rendering any HTML. Returns a discriminated union result. Used by the `/__ilha/loader` endpoint the Vite plugin exposes for client-side navigation.
+Runs the loader chain for the matched route without rendering any HTML. Returns a discriminated union result. Used by the `/__ilha/loader` endpoint the Vite plugin exposes for client-side navigation — the originating `Request` (cookies, identity, abort signal) is forwarded to the loader through both the endpoint and this method.
 ```ts
 const result = await router().route("/user/:id", userPage, userLoader).runLoader("/user/42");
@@ -378,10 +396,17 @@ router()
 Attaches the route's `+error` boundary so **loader** errors render through it — on the server (`renderResponse` returns the boundary's HTML with the error status) and on client navigations. Render errors are already handled by `wrapError` inside the island; this closes the gap for errors thrown before rendering starts. The FS-routing codegen wires the nearest `+error.ts` automatically; manual routers can call it directly. A throwing boundary falls back to the minimal inline error.
 ```ts
+import { router } from "@ilha/router";
+import { ilha, html } from "ilha";
 router()
   .route("/user/:id", userPage, userLoader)
   .errorBoundary("/user/:id", (err, route) =>
-    ilha.render(() => `<h1>${err.status ?? 500}</h1><p>${err.message}</p>`),
+    ilha(
+      () =>
+        html`<h1>${err.status ?? 500}</h1>
+          <p>${err.message}</p>`,
+    ),
   );
 ```
@@ -425,8 +450,9 @@ Reactive — `true` while a client navigation (loader fetch + view swap) is in f
 ```ts
 import { navigating } from "@ilha/router";
+import { ilha, html } from "ilha";
-const Spinner = ilha.render(() => (navigating() ? `<div class="bar" />` : ""));
+const Spinner = ilha(() => (navigating() ? html`<div class="bar" />` : ""));
 ```
 ---
@@ -556,10 +582,11 @@ Returns reactive signal accessors for the current route state. Safe to call insi
 ```ts
 import { useRoute } from "@ilha/router";
+import { ilha, html } from "ilha";
-const MyPage = ilha.render(() => {
+const MyPage = ilha(() => {
   const { path, params, search, hash } = useRoute();
-  return `<p>user id: ${params().id}</p>`;
+  return html`<p>user id: ${params().id}</p>`;
 });
 ```
@@ -667,10 +694,10 @@ A typed helper that returns the layout function as-is. Use it instead of the `sa
 ```ts
 // src/pages/+layout.ts
 import { defineLayout } from "@ilha/router";
-import ilha, { html } from "ilha";
+import { ilha, html } from "ilha";
 export default defineLayout((children) =>
-  ilha.render(
+  ilha(
     () => html`
       <nav>
         <a href="/">Home</a>
@@ -696,7 +723,7 @@ import { wrapError } from "@ilha/router";
 const safe = wrapError(myErrorHandler, myPage);
 ```
-> **Note:** Error boundaries wrap the _page island's render_, not the loader. Loader errors (thrown via `error()`) are surfaced through `.renderResponse()` — they do not currently route through `+error.ts` boundaries. Use `.renderResponse()` to handle loader errors at the HTTP layer.
+> **Note:** Error boundaries wrap the _page island's render_, not the loader. Loader errors (thrown via `error()`) route through the nearest `+error.ts` / `.errorBoundary()` boundary — on the server `renderResponse` returns the boundary's HTML with the error status, and on client navigations the boundary renders in place. `wrapError` covers render/mount throws inside the island only.
 ---
@@ -725,8 +752,16 @@ interface LoaderContext {
 type Loader<T> = (ctx: LoaderContext) => Promise<T> | T;
-// Extract the return type of a loader
-type InferLoader<L> = L extends Loader<infer T> ? Awaited<T> : never;
+// Infer the complete page props produced by a loader
+type InferLoader<L> = L extends Loader<infer T>
+  ? {
+      load: {
+        loading: boolean;
+        value: Awaited<T>;
+        error: Error | undefined;
+      };
+    }
+  : never;
 // Merge multiple loader return types — later loaders win on key collision
 type MergeLoaders<Ls extends readonly Loader<any>[]> = /* … */;
@@ -882,10 +917,10 @@ A `+layout.ts` wraps every page in its directory and all subdirectories. Layouts
 ```ts
 // src/pages/+layout.ts
 import { defineLayout } from "@ilha/router";
-import ilha, { html } from "ilha";
+import { ilha, html } from "ilha";
 export default defineLayout((children) =>
-  ilha.render(
+  ilha(
     () => html`
       <nav>
         <a href="/">Home</a>
@@ -902,10 +937,10 @@ Alternatively, using the explicit type annotation:
 ```ts
 // src/pages/+layout.ts — using satisfies (equivalent)
 import type { LayoutHandler } from "@ilha/router/vite";
-import ilha, { html } from "ilha";
+import { ilha, html } from "ilha";
 export default ((children) =>
-  ilha.render(
+  ilha(
     () => html`
       <nav>
         <a href="/">Home</a>
@@ -935,14 +970,14 @@ A page file can export a `load` function declared with the `loader()` helper. Th
 ```ts
 // src/pages/user/[id].ts
 import { loader } from "@ilha/router";
-import ilha from "ilha";
+import { ilha, html } from "ilha";
 export const load = loader(async ({ params }) => {
   const user = await fetchUser(params.id);
   return { user };
 });
-export default ilha.input<{ user: User }>().render((input) => `<h1>${input.user.name}</h1>`);
+export default ilha<{ user: User }>(({ user }) => html`<h1>${user.name}</h1>`);
 ```
 The `load` export must be declared with the `loader()` helper so the Vite plugin can identify it via export name.
@@ -971,14 +1006,14 @@ A page or layout can export a `clientLoad` function that runs **in the browser**
 ```ts
 // src/pages/dashboard.ts
 import { loader } from "@ilha/router";
-import ilha from "ilha";
+import { ilha } from "ilha";
 export const clientLoad = loader(async ({ signal }) => {
   const stats = await fetch("/api/stats", { signal }).then((r) => r.json());
   return { stats };
 });
-export default ilha.input<{ stats: Stats }>().render(/* … */);
+export default ilha<{ stats: Stats }>(({ stats }) => html`<pre>${JSON.stringify(stats)}</pre>`);
 ```
 Rules and caveats:
@@ -996,17 +1031,17 @@ A `+error.ts` catches any error thrown during rendering of pages in its director
 ```ts
 // src/pages/+error.ts
 import type { ErrorHandler } from "@ilha/router/vite";
-import ilha from "ilha";
+import { ilha, html } from "ilha";
 export default ((error, route) =>
-  ilha.render(
-    () => `
-    <div class="error">
-      <h1>${error.status ?? 500}</h1>
-      <p>${error.message}</p>
-      <p>Path: ${route.path}</p>
-    </div>
-  `,
+  ilha(
+    () => html`
+      <div class="error">
+        <h1>${error.status ?? 500}</h1>
+        <p>${error.message}</p>
+        <p>Path: ${route.path}</p>
+      </div>
+    `,
   )) satisfies ErrorHandler;
 ```
@@ -1102,7 +1137,9 @@ Or use the one-liner: `pageRouter.hydrate(registry)`.
 On the **server**, loaders run inside `.renderHydratable()` / `.renderResponse()`. Their return value is serialized into `data-ilha-props` on the island element so the client can rehydrate without re-fetching.
-On the **client**, navigations resolve loader data before mounting the next island. Routes with a loader registered in the browser — a manual `.route(path, island, loader)` or an FS-routing `clientLoad` export — run that loader locally, with no network round-trip. Routes with only a server loader (`markLoader()` / a `load` export) fetch from the `/__ilha/loader` endpoint, served automatically by the Vite plugin (dev) and the server adapter (production).
+On the **client**, navigations resolve loader data before mounting the next island. Routes with a loader registered in the browser — a manual `.route(path, island, loader)` or an FS-routing `clientLoad` export — run that loader locally, with no network round-trip. Routes with only a server loader (`markLoader()` / a `load` export) fetch from the `/__ilha/loader` endpoint, served automatically by the Vite plugin (dev) and the server adapter (production). The originating `Request` (cookies, identity, abort signal) is forwarded to the loader and the island-request scope, so `ctx.request` and `useContext().request` behave in client navigations exactly as they do during SSR.
+Like `/__ilha/frame`, the loader endpoint is **denied by default** in production when no guard is registered — gate it with `setLoaderGuard()` (or the shared frame guard / `defaultAction: "open"` policy) or client navigations to server-loader routes return 403.
 ```
 server                         client (navigation)

package/dist/head.d.ts ADDED Viewed

@@ -0,0 +1,67 @@
+/**
+ * Render-scoped head collection and serialization.
+ *
+ * Loaders and render-time `head()` calls push `HeadInput` entries into a
+ * store scoped to the current render (`withHeadStore`); `serializeHead`
+ * turns the collected entries into document-shell fragments.
+ */
+/**
+ * Serializable description of `<head>` (and html/body attributes) contributed
+ * by a loader or a render-time `head()` call. Deliberately a plain POJO — Tier
+ * 1 head management is SSR-only, so there is no reactive wrapper. Dedup keys
+ * mirror unhead so a later move to a runtime head manager stays a drop-in.
+ */
+export interface HeadInput {
+    title?: string;
+    /** Wrap the resolved title. The last template in merge order wins. */
+    titleTemplate?: string | ((title?: string) => string);
+    meta?: Array<Record<string, string>>;
+    link?: Array<Record<string, string>>;
+    /**
+     * Inline script bodies are emitted raw in SSR (`serializeHead`). Must be trusted
+     * app code and must not contain a literal `</script>` sequence.
+     */
+    script?: Array<Record<string, string> & {
+        children?: string;
+    }>;
+    htmlAttrs?: Record<string, string>;
+    bodyAttrs?: Record<string, string>;
+}
+/** Serialized head fragments ready to inject into a document shell. */
+export interface SerializedHead {
+    /** Markup for inside `<head>` (title, meta, link, script). */
+    headTags: string;
+    /** Attribute string for the `<html>` tag (leading space included). */
+    htmlAttrs: string;
+    /** Attribute string for the `<body>` tag (leading space included). */
+    bodyAttrs: string;
+}
+export interface HeadStore {
+    entries: HeadInput[];
+}
+/**
+ * Contribute `<head>` data from inside an island's `.render()` body or a
+ * layout. During SSR this collects into the active render window; on the
+ * client, entries are collected when the router re-renders a route inside
+ * `withHeadStore` and then applied to `document`. Prefer a loader's `ctx.head`
+ * for data that depends on the request.
+ */
+export declare function head(input: HeadInput): void;
+export declare function cssEscapeAttr(value: string): string;
+/**
+ * Apply merged head entries on client navigations. Updates `document.title` and
+ * managed meta/link nodes (`data-ilha-head`). Script tags from HeadInput are
+ * SSR-only and are not re-injected here. Removes managed tags from the previous
+ * route that are not part of this navigation's set.
+ */
+export declare function applyHeadEntriesToDocument(entries: HeadInput[]): void;
+export declare function withHeadStore<T>(store: HeadStore, fn: () => T | Promise<T>): Promise<T>;
+export declare function escapeHeadAttr(value: unknown): string;
+/** Escape text content for inline HTML (loader error messages etc.). */
+export declare function escapeHtml(value: unknown): string;
+/**
+ * Merge head entries in contribution order (loader first as the base, then
+ * render-time outer→inner layouts, then the page) and serialize. Later entries
+ * win on collision; the last `titleTemplate` wraps the resolved title.
+ */
+export declare function serializeHead(entries: HeadInput[]): SerializedHead;

package/dist/http.d.ts ADDED Viewed

@@ -0,0 +1,28 @@
+/**
+ * Standalone HTTP response helper for custom server handlers.
+ */
+import type { SerializedHead } from "./head";
+export interface HttpResponseOptions {
+    status?: number;
+    headers?: HeadersInit;
+    /**
+     * CSP nonce for inline scripts. When set (and `contentSecurityPolicy` is
+     * not), a conservative default CSP is emitted with `'nonce-${nonce}'` for
+     * `script-src` — pass the same nonce to head `<script nonce=…>` tags.
+     */
+    cspNonce?: string;
+    /** Full `Content-Security-Policy` string; overrides the nonce-derived default. */
+    contentSecurityPolicy?: string;
+}
+/**
+ * Build an HTTP `Response` for SSR output with sensible security headers:
+ * `Content-Type: text/html`, `X-Content-Type-Options: nosniff`,
+ * `Referrer-Policy`, `Cache-Control: no-store`, and an optional CSP. This is
+ * a low-level helper — prefer {@link RouterBuilder.respond} for the full
+ * render+head+headers pipeline.
+ */
+export declare function httpResponse(body: string | null, options?: HttpResponseOptions): Response;
+export declare const EMPTY_HEAD: SerializedHead;
+/**
+ * Options for {@link RouterBuilder.respond}.
+ */

package/dist/index.d.ts CHANGED Viewed

@@ -1,9 +1,11 @@
 import type { Island, HydratableOptions } from "ilha";
+import { head, type HeadInput, type SerializedHead } from "./head";
+import { type HttpResponseOptions } from "./http";
 export { setHistoryMode, getHistoryMode } from "./hash";
 export type { HistoryMode } from "./hash";
 export interface RouteRecord {
     pattern: string;
-    island: Island<any, any>;
+    island: Island<any>;
     /** Merged loader chain (layouts outer→inner, then page) — `undefined` if no loaders. */
     loader?: Loader<any>;
     /** True when the route has a server-side loader, even if the client only has a marker. */
@@ -20,39 +22,8 @@ export interface AppError {
     status?: number;
     stack?: string;
 }
-export type LayoutHandler = (children: Island<any, any>) => Island<any, any>;
-export type ErrorHandler = (error: AppError, route: RouteSnapshot) => Island<any, any>;
-/**
- * Serializable description of `<head>` (and html/body attributes) contributed
- * by a loader or a render-time `head()` call. Deliberately a plain POJO — Tier
- * 1 head management is SSR-only, so there is no reactive wrapper. Dedup keys
- * mirror unhead so a later move to a runtime head manager stays a drop-in.
- */
-export interface HeadInput {
-    title?: string;
-    /** Wrap the resolved title. The last template in merge order wins. */
-    titleTemplate?: string | ((title?: string) => string);
-    meta?: Array<Record<string, string>>;
-    link?: Array<Record<string, string>>;
-    /**
-     * Inline script bodies are emitted raw in SSR (`serializeHead`). Must be trusted
-     * app code and must not contain a literal `</script>` sequence.
-     */
-    script?: Array<Record<string, string> & {
-        children?: string;
-    }>;
-    htmlAttrs?: Record<string, string>;
-    bodyAttrs?: Record<string, string>;
-}
-/** Serialized head fragments ready to inject into a document shell. */
-export interface SerializedHead {
-    /** Markup for inside `<head>` (title, meta, link, script). */
-    headTags: string;
-    /** Attribute string for the `<html>` tag (leading space included). */
-    htmlAttrs: string;
-    /** Attribute string for the `<body>` tag (leading space included). */
-    bodyAttrs: string;
-}
+export type LayoutHandler = (children: Island<any>) => Island<any>;
+export type ErrorHandler = (error: AppError, route: RouteSnapshot) => Island<any>;
 export interface LoaderContext {
     params: Record<string, string>;
     request: Request;
@@ -74,8 +45,15 @@ export declare function loader<T>(fn: Loader<T>): Loader<T>;
 export declare namespace loader {
     var client: <T>(fn: Loader<T>) => Loader<T>;
 }
-/** Extract the return type of a loader. */
-export type InferLoader<L> = L extends Loader<infer T> ? Awaited<T> : never;
+/** Infer the page props produced by a loader. */
+export type InferLoader<L> = L extends Loader<infer T> ? {
+    load: {
+        loading: boolean;
+        value: Awaited<T>;
+        error: Error | undefined;
+    };
+} : never;
+type InferLoaderValue<L> = L extends Loader<infer T> ? Awaited<T> : never;
 /**
  * Merge multiple loader return types into a single object type.
  * Later loaders override earlier ones on key collision — matching runtime merge.
@@ -86,7 +64,7 @@ export type InferLoader<L> = L extends Loader<infer T> ? Awaited<T> : never;
 export type MergeLoaders<Ls extends readonly Loader<any>[]> = Ls extends readonly [
     infer First extends Loader<any>,
     ...infer Rest extends readonly Loader<any>[]
-] ? Rest extends readonly [] ? InferLoader<First> : Omit<InferLoader<First>, keyof MergeLoaders<Rest>> & MergeLoaders<Rest> : {};
+] ? Rest extends readonly [] ? InferLoaderValue<First> : Omit<InferLoaderValue<First>, keyof MergeLoaders<Rest>> & MergeLoaders<Rest> : {};
 export declare class Redirect {
     readonly __ilhaRedirect: true;
     readonly to: string;
@@ -111,8 +89,8 @@ export declare function error(status: number, message: string): never;
  * `Redirect` or `LoaderError`, the composed loader re-throws it unchanged.
  */
 export declare function composeLoaders<Ls extends readonly Loader<any>[]>(loaders: Ls): Loader<MergeLoaders<Ls>>;
-export declare function wrapLayout(layout: LayoutHandler, page: Island<any, any>): Island<any, any>;
-export declare function wrapError(handler: ErrorHandler, page: Island<any, any>): Island<any, any>;
+export declare function wrapLayout(layout: LayoutHandler, page: Island<any>): Island<any>;
+export declare function wrapError(handler: ErrorHandler, page: Island<any>): Island<any>;
 export declare function defineLayout(layout: LayoutHandler): LayoutHandler;
 export interface NavigateOptions {
     replace?: boolean;
@@ -144,7 +122,7 @@ export interface RouterOptions {
      * Island rendered when no route matches the current URL — both on the
      * server (with a 404 status) and in the client `RouterView`.
      */
-    notFound?: Island<any, any>;
+    notFound?: Island<any>;
     /**
      * Allow loader `redirect()` targets pointing at other origins. When `false`
      * (default), absolute cross-origin redirect targets are rejected with a 500
@@ -184,7 +162,7 @@ export interface HydrateOptions {
 }
 export interface MountOptions {
     hydrate?: boolean;
-    registry?: Record<string, Island<any, any>>;
+    registry?: Record<string, Island<any>>;
     /**
      * When `true` (default), internal `<a>` clicks are intercepted for
      * client-side navigation. Set to `false` for MPA-style full-page navigations.
@@ -214,7 +192,7 @@ export interface RouterBuilder {
      * (layout loaders outer→inner followed by the page loader) produced by
      * the FS-routing codegen.
      */
-    route(pattern: string, island: Island<any, any>, loader?: Loader<any>): RouterBuilder;
+    route(pattern: string, island: Island<any>, loader?: Loader<any>): RouterBuilder;
     /**
      * Attach (or replace) a loader on an already-registered route pattern.
      * Used by the `ilha:loaders` virtual module to wire server-only loaders
@@ -253,20 +231,20 @@ export interface RouterBuilder {
     prime(): void;
     mount(target: string | Element, options?: MountOptions): () => void;
     render(url: string | URL): string;
-    renderHydratable(url: string | URL, registry: Record<string, Island<any, any>>, options?: HydratableRenderOptions, request?: Request): Promise<string>;
+    renderHydratable(urlOrRequest: string | URL | Request, registry: Record<string, Island<any>>, options?: HydratableRenderOptions, request?: Request): Promise<string>;
     /**
      * Like `renderHydratable` but surfaces loader redirects and errors as
      * structured responses instead of baking them into HTML. Prefer this from
      * host server code so you can emit proper 302 / 4xx responses.
      */
-    renderResponse(url: string | URL, registry: Record<string, Island<any, any>>, options?: HydratableRenderOptions, request?: Request): Promise<RenderResponse>;
+    renderResponse(urlOrRequest: string | URL | Request, registry: Record<string, Island<any>>, options?: HydratableRenderOptions, request?: Request): Promise<RenderResponse>;
     /**
      * Run the loader chain for a given URL without rendering. Backs the
      * `/__ilha/loader` endpoint that the host server handler
      * serves as JSON for client-side navigation. Returns the raw loader result, a
      * redirect sentinel, or an error sentinel.
      */
-    runLoader(url: string | URL, request?: Request): Promise<{
+    runLoader(urlOrRequest: string | URL | Request, request?: Request): Promise<{
         kind: "data";
         data: Record<string, unknown>;
         head?: SerializedHead;
@@ -281,19 +259,25 @@ export interface RouterBuilder {
     } | {
         kind: "not-found";
     }>;
+    /**
+     * Render a route to a ready-to-send HTTP `Response`, handling redirects,
+     * loader errors, and security headers. `request` (or a URL string) selects
+     * the route; the optional `shell` injects `head` tags into a document.
+     */
+    respond(urlOrRequest: string | URL | Request, registry: Record<string, Island<any>>, options?: RespondOptions): Promise<Response>;
     /**
      * Hydrate the application - combines prime(), mount(), and router.mount() into one call.
      * @param registry - The island registry from ilha:registry
      * @param options - Optional root element (defaults to document.body) and router target (defaults to root)
      * @returns Cleanup function
      */
-    hydrate(registry: Record<string, Island<any, any>>, options?: HydrateOptions): () => void;
+    hydrate(registry: Record<string, Island<any>>, options?: HydrateOptions): () => void;
     /**
      * Hydrate islands on the current pre-rendered page without mounting a route
      * view or enabling client navigation. Intended for `static` mode: each page
      * is a self-contained HTML file; only interactive islands need activation.
      */
-    hydrateStatic(registry: Record<string, Island<any, any>>, options?: {
+    hydrateStatic(registry: Record<string, Island<any>>, options?: {
         root?: Element;
     }): () => void;
 }
@@ -305,9 +289,13 @@ export declare const LOADER_ENDPOINT = "/__ilha/loader";
  * navigation) or is superseded by another prefetch.
  */
 export declare function prefetch(pathWithSearch: string): void;
+/** @internal Internal reactive route-state accessor; use the aggregate `useRoute()` for the public surface. */
 export declare function routePath(value?: string): string;
+/** @internal Internal reactive route-state accessor; use the aggregate `useRoute()` for the public surface. */
 export declare function routeParams(value?: Record<string, string>): Record<string, string>;
+/** @internal Internal reactive route-state accessor; use the aggregate `useRoute()` for the public surface. */
 export declare function routeSearch(value?: string): string;
+/** @internal Internal reactive route-state accessor; use the aggregate `useRoute()` for the public surface. */
 export declare function routeHash(value?: string): string;
 /** Reactive: `true` while a client navigation (loader fetch + view swap) is in flight. */
 export declare function navigating(): boolean;
@@ -384,12 +372,11 @@ export interface LinkInterceptionOptions {
     prefetch?: boolean;
 }
 export declare function enableLinkInterception(root?: Element | Document, options?: LinkInterceptionOptions): () => void;
-export declare const RouterView: Island<{
-    [x: string]: unknown;
-}, {}>;
+export declare const RouterView: Island<unknown>;
 export declare const RouterLink: Island<{
-    [x: string]: unknown;
-}, Omit<Omit<{}, K> & Record<"href", string>, "label"> & Record<"label", string>>;
+    href?: string;
+    label?: string;
+}>;
 export interface IsActiveOptions {
     /**
      * When `false`, `isActive("/docs")` also matches nested paths like
@@ -399,20 +386,27 @@ export interface IsActiveOptions {
     exact?: boolean;
 }
 export declare function isActive(pattern: string, options?: IsActiveOptions): boolean;
+export interface RespondOptions extends HydratableRenderOptions, HttpResponseOptions {
+    /**
+     * Wrap the rendered body with a document shell. Receives the serialized
+     * head (title/meta/link/script tags + html/body attributes) and the inner
+     * HTML; return the full document.
+     */
+    shell?: (head: SerializedHead, html: string) => string;
+}
 /**
- * Contribute `<head>` data from inside an island's `.render()` body or a
- * layout. During SSR this collects into the active render window; on the
- * client, entries are collected when the router re-renders a route inside
- * `withHeadStore` and then applied to `document`. Prefer a loader's `ctx.head`
- * for data that depends on the request.
- */
-export declare function head(input: HeadInput): void;
-/**
- * Merge head entries in contribution order (loader first as the base, then
- * render-time outer→inner layouts, then the page) and serialize. Later entries
- * win on collision; the last `titleTemplate` wraps the resolved title.
+ * Validate a loader redirect target. Relative paths always pass; same-origin
+ * absolute URLs collapse to a path; cross-origin targets (including
+ * protocol-relative `//host` URLs) are rejected unless `allowExternal` is set.
+ * Non-http(s) schemes, backslash/control-char smuggling, and unparsable
+ * targets are always rejected.
  */
-export declare function serializeHead(entries: HeadInput[]): SerializedHead;
+export declare function resolveRedirectTarget(to: string, base: URL, allowExternal: boolean): {
+    ok: true;
+    to: string;
+} | {
+    ok: false;
+};
 export declare function router(options?: RouterOptions): RouterBuilder;
 declare const _default: {
     router: typeof router;
@@ -424,12 +418,11 @@ declare const _default: {
     prefetch: typeof prefetch;
     beforeNavigate: typeof beforeNavigate;
     afterNavigate: typeof afterNavigate;
-    RouterView: Island<{
-        [x: string]: unknown;
-    }, {}>;
+    RouterView: Island<unknown>;
     RouterLink: Island<{
-        [x: string]: unknown;
-    }, Omit<Omit<{}, K> & Record<"href", string>, "label"> & Record<"label", string>>;
+        href?: string;
+        label?: string;
+    }>;
     loader: typeof loader;
     redirect: typeof redirect;
     error: typeof error;
@@ -437,3 +430,5 @@ declare const _default: {
     head: typeof head;
 };
 export default _default;
+export { head, serializeHead, type HeadInput, type SerializedHead } from "./head";
+export { httpResponse, type HttpResponseOptions } from "./http";