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

@ilha/router 0.9.1 → 0.9.2

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 (16) hide show

package/README.md +26 -6
package/dist/index.d.ts +52 -3
package/dist/index.js +2 -2247
package/dist/{plugin-DogkskcY.js → plugin-BHuojFhQ.js} +36 -18
package/dist/plugin.d.ts +17 -0
package/dist/public-types.d.ts +7 -0
package/dist/rolldown.js +1 -1
package/dist/route-match.d.ts +22 -0
package/dist/rspack.js +1 -1
package/dist/server-island-registry.d.ts +46 -1
package/dist/server-island-registry.js +76 -21
package/dist/src-BBsbD5vU.js +2365 -0
package/dist/ssr.d.ts +9 -0
package/dist/ssr.js +57 -16
package/dist/vite.js +1 -1
package/package.json +3 -3

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,6 +236,10 @@ 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`:
@@ -246,9 +250,9 @@ If the active island is not found in the registry, falls back to plain SSR and e
 ---
-#### `.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");
@@ -1102,7 +1120,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/index.d.ts CHANGED Viewed

@@ -253,20 +253,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, 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, 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,6 +281,12 @@ 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, 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
@@ -413,6 +419,49 @@ export declare function head(input: HeadInput): void;
  * win on collision; the last `titleTemplate` wraps the resolved title.
  */
 export declare function serializeHead(entries: HeadInput[]): SerializedHead;
+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;
+/**
+ * Options for {@link RouterBuilder.respond}.
+ */
+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;
+}
+/**
+ * Validate a loader redirect target. Relative paths always pass; same-origin
+ * absolute URLs collapse to a path; cross-origin targets are rejected unless
+ * `allowExternal`. Protocol-relative (`//host`) and unparsable targets are
+ * always rejected.
+ */
+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;