@reckona/mreact-router 0.0.160 → 0.0.162

package/src/adapters/edge.ts

@@ -8,8 +8,14 @@ import {
   type AppRouterLogger,
 } from "../logger.js";
 
+/**
+ * Handles one standard Web `Request` in an edge runtime.
+ */
 export type EdgeRequestHandler = (request: Request) => Response | Promise<Response>;
 
+/**
+ * Configures edge-runtime logging, rendering, and error handling.
+ */
 export interface EdgeRequestHandlerOptions {
   logger?: AppRouterLogger | undefined;
   onError?: ((error: unknown, request: Request) => Response | Promise<Response>) | undefined;

package/src/adapters/node.ts

@@ -15,6 +15,7 @@ import {
 import type { AppRouterResponseHook } from "../render.js";
 import type { RouterInstrumentation } from "../trace.js";
 
+/** Re-exports router instrumentation hooks for Node handlers. */
 export type { RouterInstrumentation } from "../trace.js";
 import {
   renderBuiltAppRequest,
@@ -25,6 +26,9 @@ import {
   type ResponseSinkStrategy,
 } from "../serve.js";
 
+/**
+ * Configures a Node request handler for built app-router output.
+ */
 export interface NodeRequestHandlerOptions {
   allowedHosts?: readonly string[] | undefined;
   errorHandler?:
@@ -48,6 +52,9 @@ export interface NodeRequestHandlerOptions {
   sinkStrategy?: ResponseSinkStrategy | undefined;
 }
 
+/**
+ * Handles one Node HTTP request/response pair for built app-router output.
+ */
 export type NodeRequestHandler = (
   incoming: IncomingMessage,
   outgoing: ServerResponse,

package/src/adapters/static.ts

@@ -2,12 +2,18 @@ import { cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
 import type { BuiltPrerenderedRoute, BuiltServerManifest } from "../build.js";
 
+/**
+ * Configures static export from a built app-router output directory.
+ */
 export interface StaticExportOptions {
   exportDir: string;
   outDir: string;
   paths?: readonly string[] | undefined;
 }
 
+/**
+ * Lists the routes written by a static app-router export.
+ */
 export interface StaticExportResult {
   routes: string[];
 }

package/src/app-router-globals.ts

@@ -1,6 +1,9 @@
 import type { ReactCompatElement, ReactCompatNode } from "@reckona/mreact-compat";
 
 declare global {
+  /**
+   * Renders the fulfilled, rejected, or placeholder state of a deferred value.
+   */
   function Await<T>(props: {
     children?: (value: Awaited<T>) => ReactCompatNode;
     catch?: (error: Error) => ReactCompatNode;
@@ -9,6 +12,9 @@ declare global {
     value: T | PromiseLike<T>;
   }): ReactCompatElement;
 
+  /**
+   * Renders a named layout slot with optional fallback children.
+   */
   function Slot(props?: {
     children?: ReactCompatNode;
     name?: string;

package/src/assets.ts

@@ -1,3 +1,6 @@
+/**
+ * Describes the generated files associated with a client bundle manifest entry.
+ */
 export interface AssetManifestEntry {
   assets?: readonly string[];
   css?: readonly string[];
@@ -5,17 +8,29 @@ export interface AssetManifestEntry {
   imports?: readonly string[];
 }
 
+/**
+ * Maps app-router entry keys to generated client asset metadata.
+ */
 export type AssetManifest = Readonly<Record<string, AssetManifestEntry>>;
 
+/**
+ * Configures URL generation for asset helper functions.
+ */
 export interface AssetHelperOptions {
   base?: string;
 }
 
+/**
+ * Represents a preload or stylesheet link descriptor derived from an asset manifest.
+ */
 export interface AssetLinkDescriptor {
   attrs: Record<string, string>;
   tag: "link";
 }
 
+/**
+ * Resolves a manifest entry key to its public asset URL.
+ */
 export function assetHref(
   manifest: AssetManifest,
   key: string,
@@ -24,6 +39,9 @@ export function assetHref(
   return assetPath(manifestEntry(manifest, key).file, options.base);
 }
 
+/**
+ * Builds unique preload and stylesheet link descriptors for one or more manifest entries.
+ */
 export function assetPreloadLinks(
   manifest: AssetManifest,
   keys: readonly string[] | string,

package/src/build.ts

@@ -113,6 +113,9 @@ const serverArtifactFilesystemConcurrency = 2;
 type ServerTransformOutput = ReturnType<typeof transform>;
 type ServerTransformCache = Map<string, Promise<ServerTransformOutput>>;
 
+/**
+ * Configures an app-router production build and its deployment targets.
+ */
 export interface BuildAppOptions extends AppRouterProjectOptions {
   onBuildProgress?: ((event: BuildAppProgressEvent) => void) | undefined;
   onBuildPhaseTiming?: ((timing: BuildAppPhaseTiming) => void) | undefined;
@@ -161,6 +164,9 @@ async function collectBuildMiddlewareIds(appDir: string): Promise<ReadonlySet<st
   return ids;
 }
 
+/**
+ * Names a high-level phase reported while building an app-router application.
+ */
 export type BuildAppPhase =
   | "scan"
   | "collectFiles"
@@ -179,11 +185,17 @@ export type BuildAppPhase =
   | "writeManifests"
   | "adapterArtifacts";
 
+/**
+ * Captures the elapsed time for a completed app-router build phase.
+ */
 export interface BuildAppPhaseTiming {
   ms: number;
   phase: BuildAppPhase;
 }
 
+/**
+ * Reports build progress events emitted during app-router compilation and packaging.
+ */
 export type BuildAppProgressEvent =
   | {
       kind: "phase-start";
@@ -199,16 +211,25 @@ export type BuildAppProgressEvent =
       kind: "routes-discovered";
     };
 
+/**
+ * Contains the route graph produced by an app-router build.
+ */
 export interface BuildAppResult {
   routes: AppRoute[];
 }
 
+/**
+ * Describes the generated import policy artifact consumed by built request handlers.
+ */
 export interface BuiltImportPolicyArtifact {
   byRoute: Record<string, string[]>;
   runtimePackages: string[];
   version: 1;
 }
 
+/**
+ * Summarizes the files and entry point produced for an AWS Lambda artifact.
+ */
 export interface AwsLambdaArtifactManifest {
   files: Array<{ bytes: number; path: string }>;
   handler: string;
@@ -217,6 +238,9 @@ export interface AwsLambdaArtifactManifest {
   version: 1;
 }
 
+/**
+ * Summarizes the files and worker entry produced for a Cloudflare Pages artifact.
+ */
 export interface CloudflarePagesArtifactManifest {
   files: Array<{ bytes: number; path: string }>;
   runtime: "cloudflare-pages";
@@ -225,6 +249,9 @@ export interface CloudflarePagesArtifactManifest {
   worker: "_worker.js";
 }
 
+/**
+ * Configures packaging of a built app-router output directory for AWS Lambda.
+ */
 export interface PackageAwsLambdaArtifactOptions {
   fromDir: string;
   handlerEntry?: string | undefined;
@@ -232,6 +259,9 @@ export interface PackageAwsLambdaArtifactOptions {
   skipRuntimeDependencyCheck?: boolean | undefined;
 }
 
+/**
+ * Configures packaging of a built app-router output directory for Cloudflare Pages.
+ */
 export interface PackageCloudflarePagesArtifactOptions {
   fromDir: string;
   outDir: string;
@@ -1876,6 +1906,13 @@ async function prerenderStaticRoutes(options: {
       route.css !== undefined && route.css.length > 0 ? [[route.path, route.css]] : [],
     ),
   );
+  const navigationScripts = new Map(
+    options.clientRoutes.flatMap((route) =>
+      route.navigation === true && route.navigationScript !== undefined
+        ? [[route.path, route.navigationScript]]
+        : [],
+    ),
+  );
   const prerendered: Record<string, BuiltPrerenderedRoute> = {};
   const importPolicy = {
     allowedPackages: await readDeclaredProjectPackages(options.project.projectRoot),
@@ -1914,6 +1951,7 @@ async function prerenderStaticRoutes(options: {
           clientStyles,
           define: options.define,
           importPolicy,
+          navigationScripts,
           request: new Request(`http://mreact.local${pathname}`),
           serverModuleCacheVersion,
           serverModules: serverModuleMap,

package/src/cache-stats.ts

@@ -1,3 +1,6 @@
+/**
+ * Reports runtime cache counters for a named router cache.
+ */
 export interface RouterRuntimeCacheStat {
   evictions: number;
   hits: number;

package/src/cache.ts

@@ -1,16 +1,25 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 
+/**
+ * Describes the cache lifetime assigned to a rendered route response.
+ */
 export interface RouteCachePolicy {
   cacheControl: string;
   revalidateSeconds: number;
 }
 
+/**
+ * Configures cache-control directives for route response caching.
+ */
 export interface CacheControlOptions {
   maxAge?: number | undefined;
   sMaxAge?: number | undefined;
   staleWhileRevalidate?: boolean | number | undefined;
 }
 
+/**
+ * Stores a cached route response body and its expiration metadata.
+ */
 export interface AppRouterCacheEntry {
   body: string;
   cacheControl: string;
@@ -19,6 +28,9 @@ export interface AppRouterCacheEntry {
   status: number;
 }
 
+/**
+ * Defines the storage interface used by app-router route response caching.
+ */
 export interface AppRouterCache {
   deleteByPath(path: string): void | Promise<void>;
   get(
@@ -28,6 +40,9 @@ export interface AppRouterCache {
   set(key: string, entry: AppRouterCacheEntry): void | Promise<void>;
 }
 
+/**
+ * Configures the process-local in-memory route cache implementation.
+ */
 export interface MemoryRouteCacheOptions {
   maxEntries?: number;
   sweepIntervalMs?: number;

package/src/cli-options.ts

@@ -256,11 +256,13 @@ export function formatCliHelp(command?: string | undefined): string {
       "Start the mreact app router development server.",
       "",
       "Options:",
+      "  --host <host>  Bind address. Default: 127.0.0.1. Use 0.0.0.0 for LAN or device testing.",
       "  --port <port>  TCP port. Overrides PORT and vite.config.ts server.port.",
       "  --log=requests  Print request summaries.",
       "  -h, --help      Show this help message.",
       "",
       "Environment:",
+      "  HOST            Bind address when --host is not set.",
       "  PORT            TCP port when --port is not set.",
     ].join("\n");
   }

package/src/cli.ts

@@ -119,6 +119,7 @@ if (parsed !== undefined) {
               };
         const server = await startDevServer({
           ...loaded.project,
+          hostname: resolveCliHost(parsed.host, process.env),
           logger,
           port: resolveCliDevPort(parsed.port, process.env, loaded.serverPort),
           viteConfig: loaded.viteConfig,

package/src/config.ts

@@ -1,10 +1,25 @@
 import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
 
+/**
+ * Selects the deployment runtime artifacts emitted by an app-router build.
+ */
 export type AppRouterBuildTarget = "node" | "cloudflare" | "aws-lambda";
+/**
+ * Names a browser console method that can be stripped from client bundles.
+ */
 export type AppRouterClientConsoleMethod = "debug" | "error" | "info" | "log" | "trace" | "warn";
+/**
+ * Controls how client bundle source maps are generated.
+ */
 export type AppRouterClientSourceMapMode = "none" | "hidden" | "linked";
+/**
+ * Configures client source map output with a boolean shortcut or explicit mode.
+ */
 export type AppRouterClientSourceMapOption = boolean | AppRouterClientSourceMapMode;
 
+/**
+ * Configures production-only app-router build behavior.
+ */
 export interface AppRouterProductionOptions {
   dropClientConsole?: boolean | readonly AppRouterClientConsoleMethod[] | undefined;
 }

package/src/cookies.ts

@@ -1,3 +1,6 @@
+/**
+ * Configures attributes used when serializing a Set-Cookie header.
+ */
 export interface CookieOptions {
   domain?: string;
   expires?: Date;

package/src/csrf.ts

@@ -2,6 +2,9 @@ const csrfCookieNameProduction = "__Host-mreact.csrf";
 const csrfCookieNameDevelopment = "mreact.csrf";
 const formFieldCsrf = "__mreact_csrf";
 
+/**
+ * Names the hidden form field used for app-router CSRF validation.
+ */
 export const formCsrfFieldName = formFieldCsrf;
 
 export function serverActionCookie(csrfToken: string): string {
@@ -20,14 +23,23 @@ export function serverActionCookie(csrfToken: string): string {
   return parts.join("; ");
 }
 
+/**
+ * Creates or reuses the CSRF token embedded into server-rendered forms.
+ */
 export function createFormCsrfToken(request?: Request | undefined): string {
   return readExistingFormCsrfToken(request) ?? randomToken();
 }
 
+/**
+ * Serializes the CSRF cookie used to validate app-router form submissions.
+ */
 export function formCsrfCookie(csrfToken: string): string {
   return serverActionCookie(csrfToken);
 }
 
+/**
+ * Validates the CSRF cookie and hidden form field for a form submission.
+ */
 export function validateFormCsrf(request: Request, formData: FormData): Response | undefined {
   const formToken = stringFormValue(formData.get(formFieldCsrf));
   const cookieHeader = request.headers.get("cookie");

package/src/deferred.ts

@@ -1,9 +1,15 @@
 const deferredLoaderDataSymbol = Symbol.for("mreact.router.deferred-loader-data");
 
+/**
+ * Marks loader data that contains streamed deferred values.
+ */
 export type DeferredLoaderData<TData extends Record<string, unknown>> = TData & {
   readonly [deferredLoaderDataSymbol]: true;
 };
 
+/**
+ * Marks loader data for deferred streaming without changing its data shape.
+ */
 export function defer<TData extends Record<string, unknown>>(
   data: TData,
 ): DeferredLoaderData<TData> {
@@ -15,6 +21,9 @@ export function defer<TData extends Record<string, unknown>>(
   }) as DeferredLoaderData<TData>;
 }
 
+/**
+ * Checks whether loader data was marked with `defer()`.
+ */
 export function isDeferredLoaderData(
   value: unknown,
 ): value is DeferredLoaderData<Record<string, unknown>> {

package/src/dev-server.ts

@@ -21,6 +21,9 @@ import {
 } from "./logger.js";
 import type { HttpUpgradeHandler } from "./upgrade.js";
 
+/**
+ * Configures the Vite-powered app-router development server.
+ */
 export interface StartDevServerOptions extends AppRouterProjectOptions {
   port?: number | undefined;
   hostname?: string;

package/src/file-conventions.ts

@@ -1,3 +1,6 @@
+/**
+ * Names file conventions that app-router treats as metadata or static asset routes.
+ */
 export type AppFileConvention =
   | "apple-icon"
   | "icon"

package/src/i18n.ts

@@ -1,18 +1,30 @@
+/**
+ * Configures locale detection for app-router requests.
+ */
 export interface LocaleRoutingOptions<Locale extends string = string> {
   defaultLocale: Locale;
   locales: readonly Locale[];
 }
 
+/**
+ * Reports the locale selected for an incoming request.
+ */
 export interface DetectedLocale<Locale extends string = string> {
   locale: Locale;
   pathname: string;
   source: "accept-language" | "default" | "path";
 }
 
+/**
+ * Describes a nested tree of localized message strings.
+ */
 export type MessageTree = {
   readonly [key: string]: MessageTree | string;
 };
 
+/**
+ * Detects the request locale from the URL path or Accept-Language header.
+ */
 export function detectLocale<Locale extends string>(
   request: Request,
   options: LocaleRoutingOptions<Locale>,
@@ -48,6 +60,9 @@ export function detectLocale<Locale extends string>(
   };
 }
 
+/**
+ * Preserves literal types for a localized message tree.
+ */
 export function defineMessages<const Messages extends MessageTree>(messages: Messages): Messages {
   return messages;
 }

package/src/import-policy.ts

@@ -12,6 +12,9 @@ const alwaysAllowedPackages = new Set([
   "@reckona/mreact-router",
 ]);
 
+/**
+ * Controls which source roots and runtime packages built app-router handlers may import.
+ */
 export interface AppRouterImportPolicy {
   allowedPackages?: readonly string[] | undefined;
   allowedSourceDirs?: readonly string[] | undefined;

package/src/index.ts

@@ -53,22 +53,32 @@ import type {
 } from "./session.js";
 
 /**
+ * Creates a deprecated process-local session store alias.
+ *
  * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
  */
 export const createMemorySessionStore = createMemorySessionStoreInternal;
 /**
+ * Creates a deprecated session record and cookie alias.
+ *
  * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
  */
 export const createSession = createSessionInternal;
 /**
+ * Destroys a session through a deprecated router session alias.
+ *
  * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
  */
 export const destroySession = destroySessionInternal;
 /**
+ * Reads a session through a deprecated router session alias.
+ *
  * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
  */
 export const getSession = getSessionInternal;
 /**
+ * Rotates a session through a deprecated router session alias.
+ *
  * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
  */
 export const rotateSession = rotateSessionInternal;
@@ -148,6 +158,7 @@ export type {
 } from "./cache.js";
 export type { CookieOptions } from "./cookies.js";
 export type { AppRouterImportPolicy } from "./import-policy.js";
+/** Re-exports link types used by the router root entrypoint. */
 export type {
   AppRouteDeclarations,
   ConcreteLinkHrefGuard,
@@ -161,12 +172,14 @@ export type {
   LinkTransition,
   TrustedLinkHtml,
 } from "./link.js";
+/** Re-exports client navigation state types used by the router root entrypoint. */
 export type {
   AppRouterNavigationState,
   AppRouterNavigationStateListener,
   AppRouterNavigationType,
 } from "./navigation-state.js";
 export type { RouterRuntimeCacheStat } from "./runtime-cache.js";
+/** Configures the deprecated router memory session store alias. */
 export type { MemorySessionStoreOptionsInternal as MemorySessionStoreOptions };
 export type {
   AppRouterCspInlineNonceWarningLogEvent,
@@ -194,14 +207,20 @@ export type {
   PreparedFormActionReference,
 } from "./actions.js";
 /**
+ * Configures the deprecated router session cookie alias.
+ *
  * @deprecated Import session helpers and types from `@reckona/mreact-auth` instead.
  */
 export type SessionCookieOptions = SessionCookieOptionsInternal;
 /**
+ * Stores session data through the deprecated router session record alias.
+ *
  * @deprecated Import session helpers and types from `@reckona/mreact-auth` instead.
  */
 export type SessionRecord<TData = unknown> = SessionRecordInternal<TData>;
 /**
+ * Defines session persistence through the deprecated router session store alias.
+ *
  * @deprecated Import session helpers and types from `@reckona/mreact-auth` instead.
  */
 export type SessionStore<TData = unknown> = SessionStoreInternal<TData>;

package/src/link.ts

@@ -3,6 +3,7 @@ import type { HtmlSink } from "@reckona/mreact-shared/compiler-contract";
 import type { ReactCompatElement, ReactCompatNode } from "@reckona/mreact-compat";
 import { safeUrlAttributeValue } from "@reckona/mreact-shared/url-safety";
 import type { AppRouteLinkHref } from "./typed-routes.js";
+/** Re-exports typed route href helper types used by Link. */
 export type {
   AppRouteLinkHref,
   AppRouteLinkHrefSuffix,
@@ -13,19 +14,46 @@ export type {
 
 const TRUSTED_LINK_HTML = Symbol.for("modular.react.router.trusted_link_html");
 
+/**
+ * Selects when the app router should prefetch a linked route.
+ */
 export type LinkPrefetch = "intent" | "viewport" | "none" | false;
+/**
+ * Controls scroll restoration behavior after client navigation.
+ */
 export type LinkScroll = "top" | "preserve";
+/**
+ * Controls whether client navigation participates in view transitions.
+ */
 export type LinkTransition = "auto" | "none" | false;
+/**
+ * Wraps pre-escaped HTML that can be used as trusted link children.
+ */
 export type TrustedLinkHtml = { readonly [TRUSTED_LINK_HTML]: string };
+/**
+ * Represents children accepted by the app-router Link renderer.
+ */
 export type LinkChild = ReactCompatNode | Node | TrustedLinkHtml | readonly LinkChild[];
+/**
+ * Allows applications to augment statically registered app route paths through `@reckona/mreact-router/link`.
+ */
 export interface AppRouteDeclarations {}
+/**
+ * Extracts registered route paths from `AppRouteDeclarations`.
+ */
 export type RegisteredAppRoutePath = AppRouteDeclarations extends { readonly path: infer Path }
   ? Extract<Path, `/${string}`>
   : never;
+/**
+ * Resolves the accepted `href` type for app-router links.
+ */
 export type LinkHref = [RegisteredAppRoutePath] extends [never]
   ? string
   : AppRouteLinkHref<RegisteredAppRoutePath>;
 
+/**
+ * Configures client navigation behavior for a router link.
+ */
 export interface LinkOptions<Href extends string = LinkHref> {
   href: Href;
   prefetch?: LinkPrefetch | undefined;
@@ -34,6 +62,9 @@ export interface LinkOptions<Href extends string = LinkHref> {
   transition?: LinkTransition | undefined;
 }
 
+/**
+ * Combines router link options with anchor attributes and children.
+ */
 export interface LinkProps<Href extends string = LinkHref> extends LinkOptions<Href> {
   children?: LinkChild;
   [attribute: string]: unknown;
@@ -60,6 +91,9 @@ export function linkProps(options: LinkOptions<string>): Record<string, string>
   };
 }
 
+/**
+ * Produces a compile-time error shape when a typed Link receives an unresolved route pattern.
+ */
 export type ConcreteLinkHrefGuard<Href extends string> = [RegisteredAppRoutePath] extends [never]
   ? unknown
   : Href extends Extract<RegisteredAppRoutePath, `${string}:${string}`>