@ilha/router 0.10.3 → 0.11.0

package/dist/als-key-CVxbuM3z.js

@@ -0,0 +1,5 @@
+//#region src/als-key.ts
+const REQUEST_ALS_KEY = Symbol.for("ilha.requestAls");
+
+//#endregion
+export { REQUEST_ALS_KEY as t };

package/dist/als-key.d.ts

@@ -0,0 +1 @@
+export declare const REQUEST_ALS_KEY: unique symbol;

package/dist/codegen.d.ts

@@ -22,8 +22,6 @@ export interface GeneratedPaths {
     serverFile: string;
     /** Client module: ?client imports, browser-optimised. `ilha:pages/client` */
     clientFile: string;
-    /** Server-only loaders side-effect module. `ilha:loaders` */
-    loadersFile: string;
 }
 export declare function resolveGeneratedPaths(outDir: string): GeneratedPaths;
 export declare function generate(pagesDir: string, outDir: string, options?: GenerateOptions): Promise<void>;

package/dist/{snapshot-CsEaY6h_.js → head-DpYV3bHH.js}

@@ -27,7 +27,10 @@ let _headAlsInit = null;
 /** ESM dynamic import — Nitro/Vite SSR workers have no `require`. */
 async function getHeadAlsAsync() {
 	if (_headAls) return _headAls;
-	if (!_headAlsInit) _headAlsInit = import("node:async_hooks").then(({ AsyncLocalStorage }) => {
+	if (!_headAlsInit) _headAlsInit = import(
+		/* @vite-ignore */
+		"node:async_hooks"
+).then(({ AsyncLocalStorage }) => {
 		_headAls = new AsyncLocalStorage();
 		return _headAls;
 	});
@@ -161,10 +164,6 @@ const HEAD_ESC = {
 function escapeHeadAttr(value) {
 	return String(value).replace(/[&<>"']/g, (c) => HEAD_ESC[c]);
 }
-/** Escape text content for inline HTML (loader error messages etc.). */
-function escapeHtml(value) {
-	return String(value).replace(/[&<>]/g, (c) => HEAD_ESC[c]);
-}
 function serializeAttrs(attrs) {
 	const parts = [];
 	for (const [k, v] of Object.entries(attrs)) {
@@ -283,55 +282,4 @@ function isSafeRefreshTarget(content) {
 }
 
 //#endregion
-//#region src/snapshot.ts
-/**
-* Defensive parser for `data-ilha-state` / `data-ilha-props` snapshot
-* attributes on the router side. Mirrors the core ilha guards: size cap,
-* plain-object check, depth cap, and prototype-key stripping. Returns
-* undefined (degrade gracefully) on any failure.
-*/
-const MAX_SNAPSHOT_CHARS = 262144;
-const MAX_SNAPSHOT_DEPTH = 32;
-const UNSAFE_SNAPSHOT_KEYS = /* @__PURE__ */ new Set([
-	"__proto__",
-	"constructor",
-	"prototype"
-]);
-function stripUnsafeKeys(value) {
-	if (value === null || typeof value !== "object") return;
-	if (Array.isArray(value)) {
-		for (const item of value) stripUnsafeKeys(item);
-		return;
-	}
-	for (const key of Object.getOwnPropertyNames(value)) if (UNSAFE_SNAPSHOT_KEYS.has(key)) delete value[key];
-	else stripUnsafeKeys(value[key]);
-}
-function exceedsDepth(value, depth) {
-	if (depth > MAX_SNAPSHOT_DEPTH) return true;
-	if (value === null || typeof value !== "object") return false;
-	if (Array.isArray(value)) {
-		for (const item of value) if (exceedsDepth(item, depth + 1)) return true;
-		return false;
-	}
-	for (const key in value) {
-		if (!Object.hasOwn(value, key)) continue;
-		if (exceedsDepth(value[key], depth + 1)) return true;
-	}
-	return false;
-}
-function parseSnapshotAttr(raw) {
-	if (raw.length > MAX_SNAPSHOT_CHARS) return void 0;
-	let parsed;
-	try {
-		parsed = JSON.parse(raw);
-	} catch {
-		return;
-	}
-	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
-	if (exceedsDepth(parsed, 1)) return void 0;
-	stripUnsafeKeys(parsed);
-	return parsed;
-}
-
-//#endregion
-export { escapeHtml as a, withHeadStore as c, escapeHeadAttr as i, applyHeadEntriesToDocument as n, head as o, cssEscapeAttr as r, serializeHead as s, parseSnapshotAttr as t };
+export { withHeadStore as i, head as n, serializeHead as r, applyHeadEntriesToDocument as t };

package/dist/index.d.ts

@@ -1,15 +1,16 @@
-import type { Island, HydratableOptions } from "ilha";
-import { head, type HeadInput, type SerializedHead } from "./head";
+import type { Component, View } from "ilha";
+import { type SerializedHead } from "./head";
 import { type HttpResponseOptions } from "./http";
 export { setHistoryMode, getHistoryMode } from "./hash";
 export type { HistoryMode } from "./hash";
+export { head, serializeHead } from "./head";
+export type { HeadInput, SerializedHead } from "./head";
+export { httpResponse, EMPTY_HEAD } from "./http";
+export type { HttpResponseOptions } from "./http";
+export type Page = Component;
 export interface RouteRecord {
     pattern: string;
-    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. */
-    hasLoader?: boolean;
+    page: Page;
 }
 export interface RouteSnapshot {
     path: string;
@@ -22,154 +23,46 @@ export interface AppError {
     status?: number;
     stack?: 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;
-    url: URL;
-    signal: AbortSignal;
-    /** Contribute `<head>` data for this route. Safe to call multiple times. */
-    head: (input: HeadInput) => void;
-}
-export type Loader<T> = (ctx: LoaderContext) => Promise<T> | T;
-/**
- * Identity function for declaring a loader. Exists purely as a type anchor and
- * a marker for the Vite plugin to detect by export name.
- *
- * Loaders must read `ctx.params`/`ctx.url` rather than `useRoute()` — the
- * route store still holds the previous route while a navigation's loader is
- * in flight, so `useRoute().params()` inside a loader reads stale params.
- */
-export declare function loader<T>(fn: Loader<T>): Loader<T>;
-export declare namespace loader {
-    var client: <T>(fn: Loader<T>) => Loader<T>;
+export interface IslandContext {
+    request?: Request;
 }
-/** 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.
- *
- * @example
- * type PageInput = MergeLoaders<[typeof rootLayoutLoad, typeof sectionLayoutLoad, typeof pageLoad]>;
- */
-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 [] ? InferLoaderValue<First> : Omit<InferLoaderValue<First>, keyof MergeLoaders<Rest>> & MergeLoaders<Rest> : {};
+export type LayoutHandler = (props: {
+    children?: View;
+} & Record<string, unknown>) => unknown;
+export type ErrorHandler = (error: AppError, route: RouteSnapshot) => Page | View;
 export declare class Redirect {
     readonly __ilhaRedirect: true;
     readonly to: string;
     readonly status: number;
     constructor(to: string, status?: number);
 }
-export declare class LoaderError {
-    readonly __ilhaLoaderError: true;
+export declare class RouteError {
+    readonly __ilhaRouteError: true;
     readonly status: number;
     readonly message: string;
     constructor(status: number, message: string);
 }
 export declare function redirect(to: string, status?: number): never;
 export declare function error(status: number, message: string): never;
-/**
- * Compose a list of loaders into a single loader. Later loaders win on key
- * collision (page loader overrides layout loader for the same key). All loaders
- * run concurrently within a chain since they share the same abort signal and
- * request — re-fetching is cheap with a request-scoped cache (future work).
- *
- * For v1 we run them in parallel via `Promise.all`. If a loader throws a
- * `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>): Island<any>;
-export declare function wrapError(handler: ErrorHandler, page: Island<any>): Island<any>;
+export declare function wrapLayout(layout: LayoutHandler, page: Page): Page;
+export declare function wrapError(handler: ErrorHandler, page: Page): Page;
 export declare function defineLayout(layout: LayoutHandler): LayoutHandler;
 export interface NavigateOptions {
     replace?: boolean;
-    /**
-     * When `false`, keep the current scroll position instead of scrolling to the
-     * top (or to the URL hash target) after navigation. Default: `true`.
-     */
     scroll?: boolean;
 }
 export type RouterMode = "spa" | "static";
 export interface RouterOptions {
-    /**
-     * Client navigation mode.
-     * - `spa` — full route graph, SSR/hydration, client-side navigation.
-     * - `static` — no route graph bundled; hydrate islands on the current
-     *   pre-rendered page only.
-     * Default: `spa`.
-     */
     mode?: RouterMode;
-    /**
-     * When `true` (default), internal `<a>` clicks are intercepted and handled
-     * by the client router. Set to `false` for MPA-style behavior where links
-     * perform full document navigations.
-     * Only meaningful in `spa` mode; ignored in `static` mode.
-     * Default: `true`.
-     */
     interceptLinks?: boolean;
-    /**
-     * 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>;
-    /**
-     * Allow loader `redirect()` targets pointing at other origins. When `false`
-     * (default), absolute cross-origin redirect targets are rejected with a 500
-     * — redirect targets frequently carry user input (`?next=` params), and
-     * rejecting external targets by default prevents open redirects.
-     */
     allowExternalRedirects?: boolean;
-    /**
-     * Abort a route loader after this many milliseconds during SSR / loader
-     * endpoint execution. `0`/`undefined` disables the timeout. The loader's
-     * `ctx.signal` also aborts when the incoming `Request`'s signal aborts.
-     */
-    loaderTimeout?: number;
-    /**
-     * Wrap client-side view swaps in `document.startViewTransition()` when the
-     * browser supports it (falls back to an instant swap otherwise).
-     * Default: `false`.
-     */
     viewTransitions?: boolean;
-}
-export interface HydratableRenderOptions extends Partial<Omit<HydratableOptions, "name">> {
-    /**
-     * Base `<head>` data merged before loader and render-time contributions, so
-     * route-level head overrides it. Used by host entries rendering routes server-side
-     * to supply app-wide title/meta/scripts.
-     */
-    baseHead?: HeadInput;
-}
-export interface HydrateOptions {
-    root?: Element;
-    target?: string | Element;
-    /**
-     * When `true` (default), internal `<a>` clicks are intercepted for
-     * client-side navigation. Set to `false` for MPA-style full-page navigations.
-     */
-    interceptLinks?: boolean;
+    notFound?: Page;
 }
 export interface MountOptions {
     hydrate?: boolean;
-    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.
-     */
     interceptLinks?: boolean;
 }
-/** Response envelope returned by `renderResponse` — lets the host app handle redirects. */
 export type RenderResponse = {
     kind: "html";
     html: string;
@@ -186,147 +79,49 @@ export type RenderResponse = {
     html: string;
     head?: SerializedHead;
 };
+export interface RespondOptions extends HttpResponseOptions {
+    timeout?: number;
+    snapshot?: boolean;
+    markers?: boolean;
+    shell?: (head: SerializedHead, html: string) => string;
+}
 export interface RouterBuilder {
-    /**
-     * Register a route. The optional `loader` is the merged loader chain
-     * (layout loaders outer→inner followed by the page loader) produced by
-     * the FS-routing codegen.
-     */
-    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
-     * onto the client-safe `pageRouter` at SSR time. No-op if the pattern
-     * was never registered via `.route()`.
-     */
-    attachLoader(pattern: string, loader: Loader<any>): RouterBuilder;
-    /**
-     * Attach a loader that runs **in the browser** on client navigations,
-     * instead of fetching from the loader endpoint. Used by the FS-routing
-     * codegen for `loader.client` exports; also available for manual routers.
-     * When a route has both, the client loader wins on client navigations and
-     * the server loader runs during SSR. No-op if the pattern was never
-     * registered via `.route()`.
-     */
-    clientLoader(pattern: string, loader: Loader<any>): RouterBuilder;
-    /**
-     * Attach the route's nearest `+error` boundary so **loader** errors render
-     * through it (render errors are already handled by `wrapError` inside the
-     * island). Used by the FS-routing codegen; also available for manual
-     * routers. No-op if the pattern was never registered via `.route()`.
-     */
+    route(pattern: string, page: Page): RouterBuilder;
     errorBoundary(pattern: string, handler: ErrorHandler): RouterBuilder;
-    /**
-     * Mark an already-registered route as having a server-side loader without
-     * importing that loader into the client bundle. Used by FS-routing codegen
-     * so SPA navigation knows to call the loader endpoint.
-     */
-    markLoader(pattern: string): RouterBuilder;
-    /**
-     * Return a snapshot of every registered route in match order. Useful for
-     * prerenderers that need to discover the filesystem routes exposed by
-     * `pageRouter` without reaching into router internals.
-     */
     routes(): RouteRecord[];
     prime(): void;
     mount(target: string | Element, options?: MountOptions): () => void;
-    render(url: string | URL): 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(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(urlOrRequest: string | URL | Request, request?: Request): Promise<{
-        kind: "data";
-        data: Record<string, unknown>;
-        head?: SerializedHead;
-    } | {
-        kind: "redirect";
-        to: string;
-        status: number;
-    } | {
-        kind: "error";
-        status: number;
-        message: string;
-    } | {
-        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>>, 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>>, options?: {
+    render(url: string | URL | Request, options?: {
+        timeout?: number;
+        snapshot?: boolean;
+        markers?: boolean;
+    }): Promise<string>;
+    renderResponse(url: string | URL | Request, options?: {
+        timeout?: number;
+        snapshot?: boolean;
+        markers?: boolean;
+    }): Promise<RenderResponse>;
+    respond(url: string | URL | Request, options?: RespondOptions): Promise<Response>;
+    hydrate(options?: {
         root?: Element;
+        interceptLinks?: boolean;
     }): () => void;
 }
-/** Path of the loader endpoint served by the Vite plugin / production adapter. */
-export declare const LOADER_ENDPOINT = "/__ilha/loader";
-/**
- * Prefetch loader data for a given path. Safe to call repeatedly — a single
- * inflight request is reused until it either resolves (and is consumed by
- * 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;
-/**
- * Re-run the current route's loader and re-render the view with fresh data —
- * e.g. after a mutation. Resolves when the view has updated. No-op on the
- * server or when no router is mounted.
- */
-export declare function invalidate(): Promise<void>;
-/**
- * Context seeded for server-owned island renders. Extensible: future entries
- * (route params, app middleware values) land here without moving call sites.
- */
-export interface IslandContext {
-    /**
-     * The `Request` seeding this render, when one exists — page SSR passes the
-     * incoming request; frame renders pass a synthesized POST with forwarded
-     * identity headers (`cookie`, `authorization`, …). Absent in unscoped
-     * renders (plain `toString()` in tests).
-     */
-    request?: Request;
+export interface Navigation {
+    from: string;
+    to: string;
+    type: "push" | "replace" | "pop";
+    cancel?: () => void;
 }
-/**
- * The context seeding the current server-island render. Always returns an
- * object — check `.request` rather than the context itself. Never throws, so
- * render functions stay safe under plain `toString()` calls and in tests.
- *
- * Only meaningful inside `.server.tsx` render functions (page SSR or frame
- * rendering); client code never has a reason to call it.
- */
-export declare function useContext(): IslandContext;
+type BeforeNavigateHook = (nav: Navigation & {
+    cancel: () => void;
+}) => void;
+type AfterNavigateHook = (nav: Navigation) => void;
+export declare function routePath(): string;
+export declare function routeParams(): Record<string, string>;
+export declare function routeSearch(): string;
+export declare function routeHash(): string;
+export declare function navigating(): boolean;
 export declare function useRoute(): {
     path: typeof routePath;
     params: typeof routeParams;
@@ -334,73 +129,20 @@ export declare function useRoute(): {
     hash: typeof routeHash;
     navigating: typeof navigating;
 };
-/**
- * Prime route context signals from the current `location` so that islands
- * hydrated by `ilha.mount()` see the correct route values on their first
- * render — preventing a mismatch morph that would destroy hydrated bindings.
- */
+export declare function useContext(): {
+    request: Request | undefined;
+};
 export declare function prime(): void;
-export interface Navigation {
-    /** Logical URL (path + search + hash) being navigated away from. */
-    from: string;
-    /** Logical URL being navigated to. */
-    to: string;
-    /** `"push"`/`"replace"` for programmatic navigations, `"pop"` for history traversal. */
-    type: "push" | "replace" | "pop";
-}
-export type BeforeNavigateHook = (nav: Navigation & {
-    cancel(): void;
-}) => void;
-export type AfterNavigateHook = (nav: Navigation) => void;
-/**
- * Run before a programmatic navigation commits. Call `nav.cancel()` to keep
- * the current URL (e.g. unsaved-changes guards). Not invoked for browser
- * back/forward — the URL has already changed by the time `popstate` fires.
- * Returns an unsubscribe function.
- */
 export declare function beforeNavigate(fn: BeforeNavigateHook): () => void;
-/** Run after a navigation (push, replace, or pop) has committed. Returns an unsubscribe function. */
 export declare function afterNavigate(fn: AfterNavigateHook): () => void;
 export declare function navigate(to: string, opts?: NavigateOptions): void;
 export interface LinkInterceptionOptions {
-    /**
-     * Prefetch loader data on `mouseenter` for eligible links. Links opt in via
-     * the `data-prefetch` attribute (set `data-prefetch="false"` to opt out a
-     * specific link even when the framework is configured to prefetch by default).
-     * Default: `true` — prefetches on hover for any link with `data-prefetch`.
-     */
-    prefetch?: boolean;
 }
-export declare function enableLinkInterception(root?: Element | Document, options?: LinkInterceptionOptions): () => void;
-export declare const RouterView: Island<unknown>;
-export declare const RouterLink: Island<{
-    href?: string;
-    label?: string;
-}>;
+export declare function enableLinkInterception(root?: Element | Document, _options?: LinkInterceptionOptions): () => void;
 export interface IsActiveOptions {
-    /**
-     * When `false`, `isActive("/docs")` also matches nested paths like
-     * `/docs/getting-started` (prefix match on the current path).
-     * Default: `true` (the matched route's pattern must equal `pattern`).
-     */
-    exact?: boolean;
+    end?: 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;
-}
-/**
- * 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 resolveRedirectTarget(to: string, base: URL, allowExternal: boolean): {
     ok: true;
     to: string;
@@ -408,27 +150,3 @@ export declare function resolveRedirectTarget(to: string, base: URL, allowExtern
     ok: false;
 };
 export declare function router(options?: RouterOptions): RouterBuilder;
-declare const _default: {
-    router: typeof router;
-    navigate: typeof navigate;
-    useRoute: typeof useRoute;
-    isActive: typeof isActive;
-    enableLinkInterception: typeof enableLinkInterception;
-    prime: typeof prime;
-    prefetch: typeof prefetch;
-    beforeNavigate: typeof beforeNavigate;
-    afterNavigate: typeof afterNavigate;
-    RouterView: Island<unknown>;
-    RouterLink: Island<{
-        href?: string;
-        label?: string;
-    }>;
-    loader: typeof loader;
-    redirect: typeof redirect;
-    error: typeof error;
-    composeLoaders: typeof composeLoaders;
-    head: typeof head;
-};
-export default _default;
-export { head, serializeHead, type HeadInput, type SerializedHead } from "./head";
-export { httpResponse, type HttpResponseOptions } from "./http";