@reckona/mreact-router 0.0.189 → 0.0.191

package/src/index.ts

@@ -7,6 +7,7 @@ export { defer, isDeferredLoaderData } from "./deferred.js";
 export type { DeferredLoaderData } from "./deferred.js";
 export { definePage } from "./types.js";
 export { Link, linkProps } from "./link.js";
+export type { LinkSerializableAttribute, LinkSinkChild, LinkSinkProps } from "./link.js";
 export { href } from "./typed-routes.js";
 export { parseMultipartStream } from "./multipart.js";
 export type {
@@ -35,7 +36,7 @@ export {
   textError,
   throwNotFound,
 } from "./navigation.js";
-export type { ParseSchema } from "./navigation.js";
+export type { MiddlewareNext, ParseSchema, RedirectOptions, RequestCookies } from "./navigation.js";
 export { createMemoryPrerenderStore } from "./prerender-store.js";
 export { getServerRuntimeState } from "./runtime-state.js";
 import {
@@ -57,43 +58,80 @@ import type {
  *
  * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
  */
-export const createMemorySessionStore = createMemorySessionStoreInternal;
+export function createMemorySessionStore<TData = unknown>(
+  options: MemorySessionStoreOptionsInternal = {},
+): SessionStoreInternal<TData> {
+  return createMemorySessionStoreInternal<TData>(options);
+}
 /**
  * Creates a deprecated session record and cookie alias.
  *
  * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
  */
-export const createSession = createSessionInternal;
+export async function createSession<TData>(
+  response: Response,
+  store: SessionStoreInternal<TData>,
+  data: TData,
+  options: SessionCookieOptionsInternal = {},
+): Promise<SessionRecordInternal<TData>> {
+  return createSessionInternal(response, store, data, options);
+}
 /**
  * Destroys a session through a deprecated router session alias.
  *
  * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
  */
-export const destroySession = destroySessionInternal;
+export async function destroySession<TData>(
+  request: Request,
+  response: Response,
+  store: SessionStoreInternal<TData>,
+  options: SessionCookieOptionsInternal = {},
+): Promise<void> {
+  return destroySessionInternal(request, response, store, options);
+}
 /**
  * Reads a session through a deprecated router session alias.
  *
  * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
  */
-export const getSession = getSessionInternal;
+export async function getSession<TData>(
+  request: Request,
+  store: SessionStoreInternal<TData>,
+  options: SessionCookieOptionsInternal = {},
+): Promise<SessionRecordInternal<TData> | undefined> {
+  return getSessionInternal(request, store, options);
+}
 /**
  * Rotates a session through a deprecated router session alias.
  *
  * @deprecated Import session helpers from `@reckona/mreact-auth` instead.
  */
-export const rotateSession = rotateSessionInternal;
+export async function rotateSession<TData>(
+  request: Request,
+  response: Response,
+  store: SessionStoreInternal<TData>,
+  options: SessionCookieOptionsInternal = {},
+): Promise<SessionRecordInternal<TData> | undefined> {
+  return rotateSessionInternal(request, response, store, options);
+}
 export type {
   AwsLambdaArtifactManifest,
+  AwsLambdaGeneratedHandlerPreloadMode,
   BuildAppPhase,
   BuildAppPhaseTiming,
   BuildAppOptions,
   BuildAppProgressEvent,
   BuildAppResult,
   BuiltImportPolicyArtifact,
+  BuiltPrerenderedRoute,
+  BuiltRouteSourceAnalysisSummary,
+  BuiltServerModuleArtifact,
+  BuiltServerModuleOutput,
   CloudflarePagesArtifactManifest,
   PackageAwsLambdaArtifactOptions,
   PackageCloudflarePagesArtifactOptions,
 } from "./build.js";
+export type { AppRouterProjectOptions } from "./config.js";
 export type { ServerActionContext } from "./actions.js";
 export type {
   AppRouteHref,
@@ -106,7 +144,11 @@ export type {
   RouteParamsFor,
   RouteSearchParams,
   RouteSearchValue,
+  SegmentRouteParam,
   StaticHrefOptions,
+  ExtractRouteParams,
+  HasRouteParams,
+  Simplify,
 } from "./typed-routes.js";
 export type {
   InferLoaderData,
@@ -180,7 +222,7 @@ export type {
 } 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 { MemorySessionStoreOptions } from "./session.js";
 export type {
   AppRouterCspInlineNonceWarningLogEvent,
   AppRouterLogError,
@@ -211,23 +253,24 @@ export type {
  *
  * @deprecated Import session helpers and types from `@reckona/mreact-auth` instead.
  */
-export type SessionCookieOptions = SessionCookieOptionsInternal;
+export type { SessionCookieOptions } from "./session.js";
 /**
  * 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>;
+export type { SessionRecord } from "./session.js";
 /**
  * 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>;
+export type { SessionStore } from "./session.js";
 export { startDevServer } from "./dev-server.js";
 export type { StartDevServerOptions } from "./dev-server.js";
 export { renderAppRequest } from "./render.js";
 export type {
+  AppRouterRenderPreload,
   AppRouterResponseHook,
   AppRouterResponseHookContext,
   RenderAppRequestOptions,
@@ -250,6 +293,7 @@ export type {
   FileSystemPrerenderStoreOptions,
   KeyValuePrerenderStoreAdapter,
   KeyValuePrerenderStoreOptions,
+  MemoryPrerenderStoreEntry,
   MemoryPrerenderStoreOptions,
 } from "./prerender-store.js";
 export { createFileSystemPrerenderStore, createKeyValuePrerenderStore } from "./prerender-store.js";
@@ -260,9 +304,12 @@ export type {
   BuiltAppRuntimePreloadStrategy,
   RenderBuiltAppRequestOptions,
   RequestHostPolicy,
+  ResponseSinkStrategy,
   StartServerOptions,
 } from "./serve.js";
 export { matchRoute, scanAppRoutes } from "./routes.js";
+export type { CachedClientRouteSource, ClientRouteInferenceCache } from "./client.js";
+export type { RouteMatcher, ScanAppRoutesOptions } from "./routes.js";
 export type { AppFileConvention } from "./file-conventions.js";
 export type {
   AppAssetRoute,

package/src/link.ts

@@ -13,6 +13,7 @@ export type {
 } from "./typed-routes.js";
 
 const TRUSTED_LINK_HTML = Symbol.for("modular.react.router.trusted_link_html");
+const VALID_LINK_ATTRIBUTE_NAME = /^[A-Za-z_][\w.\-:]*$/;
 
 /**
  * Selects when the app router should prefetch a linked route.
@@ -70,6 +71,37 @@ export interface LinkProps<Href extends string = LinkHref> extends LinkOptions<H
   [attribute: string]: unknown;
 }
 
+/** Represents attributes that can be serialized when Link writes to an HtmlSink. */
+export type LinkSerializableAttribute = boolean | number | string | null | undefined;
+
+/** Represents child values that an HtmlSink Link can serialize without a browser DOM. */
+export type LinkSinkChild =
+  | boolean
+  | number
+  | string
+  | null
+  | undefined
+  | TrustedLinkHtml
+  | readonly LinkSinkChild[];
+
+/** Configures an HtmlSink Link without browser-only event handlers or refs. */
+export interface LinkSinkProps extends LinkOptions<string> {
+  children?: LinkSinkChild;
+  class?: string | undefined;
+  className?: string | undefined;
+  download?: string | boolean | undefined;
+  id?: string | undefined;
+  name?: string | undefined;
+  rel?: string | undefined;
+  role?: string | undefined;
+  style?: Readonly<Record<string, boolean | number | string | null | undefined>> | undefined;
+  tabIndex?: number | undefined;
+  target?: string | undefined;
+  title?: string | undefined;
+  [ariaAttribute: `aria-${string}`]: LinkSerializableAttribute;
+  [dataAttribute: `data-${string}`]: LinkSerializableAttribute;
+}
+
 /**
  * Converts router link options into anchor attributes consumed by the client navigation runtime.
  *
@@ -85,7 +117,9 @@ export function linkProps(options: LinkOptions<string>): Record<string, string>
     ...(options.scroll === undefined || options.scroll === "top"
       ? {}
       : { "data-mreact-scroll": options.scroll }),
-    ...(options.transition === undefined || options.transition === false || options.transition === "none"
+    ...(options.transition === undefined ||
+    options.transition === false ||
+    options.transition === "none"
       ? {}
       : { "data-mreact-transition": options.transition }),
   };
@@ -108,19 +142,51 @@ export type ConcreteLinkHrefGuard<Href extends string> = [RegisteredAppRoutePath
 export function Link<const Href extends LinkHref>(
   props: LinkProps<Href> & ConcreteLinkHrefGuard<Href>,
 ): ReactCompatElement;
-export function Link(sink: HtmlSink, props: LinkProps<string>): void;
+export function Link(sink: HtmlSink, props: LinkSinkProps): void;
 export function Link(
   sinkOrProps: HtmlSink | LinkProps<string>,
-  maybeProps?: LinkProps<string>,
+  maybeProps?: LinkProps<string> | LinkSinkProps,
 ): ReactCompatElement | string | HTMLAnchorElement | void {
   if (maybeProps !== undefined) {
-    (sinkOrProps as HtmlSink).append(renderLinkString(maybeProps));
+    reportUnsupportedSinkProps(maybeProps);
+    (sinkOrProps as HtmlSink).append(renderLinkString(maybeProps as LinkSinkProps));
     return;
   }
 
   return renderLink(sinkOrProps as LinkProps);
 }
 
+function reportUnsupportedSinkProps(props: LinkProps<string> | LinkSinkProps): void {
+  const nodeEnv = (
+    globalThis as typeof globalThis & {
+      process?: { env?: { NODE_ENV?: string | undefined } | undefined } | undefined;
+    }
+  ).process?.env?.NODE_ENV;
+
+  if (nodeEnv === "production") {
+    return;
+  }
+
+  const unsupported = Object.entries(props)
+    .filter(
+      ([name, value]) =>
+        name === "ref" ||
+        typeof value === "function" ||
+        typeof value === "symbol" ||
+        isLinkEventAttributeName(name) ||
+        (name === "children" && !isSerializableSinkChild(value)) ||
+        (name !== "children" && name !== "style" && typeof value === "object" && value !== null) ||
+        (name !== "children" && !isSafeLinkAttributeName(attributeName(name))),
+    )
+    .map(([name]) => name);
+
+  if (unsupported.length > 0) {
+    console.warn(
+      `[MR_LINK_SINK_UNSUPPORTED_PROP] HtmlSink Link cannot serialize browser-only props: ${unsupported.join(", ")}. Render Link through JSX for event handlers and refs.`,
+    );
+  }
+}
+
 (Link as typeof Link & { trustedHtml(html: string): TrustedLinkHtml }).trustedHtml = (
   html: string,
 ): TrustedLinkHtml => ({
@@ -141,13 +207,14 @@ function renderLink(props: LinkProps<string>): string | HTMLAnchorElement {
   return renderAnchorString(propsWithLinkAttrs);
 }
 
-function renderLinkString(props: LinkProps<string>): string {
+function renderLinkString(props: LinkSinkProps): string {
   const { href, prefetch, reload, scroll, transition, ...rest } = props;
-
-  return renderAnchorString({
+  const propsWithLinkAttrs = {
     ...rest,
     ...linkProps({ href, prefetch, reload, scroll, transition }),
-  });
+  };
+
+  return `<a${renderAnchorAttributes(propsWithLinkAttrs)}>${renderSinkChildren(props.children)}</a>`;
 }
 
 function createAnchorElement(props: Record<string, unknown>): HTMLAnchorElement {
@@ -159,18 +226,53 @@ function createAnchorElement(props: Record<string, unknown>): HTMLAnchorElement
       continue;
     }
 
+    if (name === "ref") {
+      if (typeof value === "function") {
+        (value as (element: HTMLAnchorElement) => void)(anchor);
+      } else if (typeof value === "object" && value !== null && "current" in value) {
+        (value as { current: HTMLAnchorElement | null }).current = anchor;
+      }
+      continue;
+    }
+
+    if (/^on[A-Z]/.test(name) && typeof value === "function") {
+      const capture = name.endsWith("Capture");
+      const eventName = name.slice(2, capture ? -"Capture".length : undefined).toLowerCase();
+      anchor.addEventListener(eventName, value as EventListener, capture);
+      continue;
+    }
+
+    if (isLinkEventAttributeName(name)) {
+      reportRejectedBrowserEventProp(name);
+      continue;
+    }
+
+    if (name === "style" && typeof value === "object" && value !== null) {
+      for (const [property, styleValue] of Object.entries(value as Record<string, unknown>)) {
+        const cssProperty = linkStylePropertyName(property);
+        const cssValue = linkStyleValue(styleValue);
+        if (cssProperty !== undefined && cssValue !== undefined) {
+          anchor.style.setProperty(cssProperty, cssValue);
+        }
+      }
+      continue;
+    }
+
     if (!shouldSetAttribute(name, value)) {
       continue;
     }
 
     const attrName = attributeName(name);
+    if (!isSafeLinkAttributeName(attrName)) {
+      continue;
+    }
     const safeValue = safeUrlAttributeValue(attrName, String(value));
 
     if (safeValue === undefined) {
       continue;
     }
 
-    anchor.setAttribute(attrName, safeValue);
+    anchor.setAttribute(attrName, value === true ? "" : safeValue);
   }
 
   return anchor;
@@ -204,11 +306,33 @@ function renderAnchorAttributes(props: Record<string, unknown>): string {
   const attrs: string[] = [];
 
   for (const [name, value] of Object.entries(props)) {
-    if (name === "children" || !shouldSetAttribute(name, value)) {
+    if (name === "children" || isLinkEventAttributeName(name) || !shouldSetAttribute(name, value)) {
+      continue;
+    }
+
+    if (name !== "style" && typeof value === "object" && value !== null) {
       continue;
     }
 
     const attrName = attributeName(name);
+    if (!isSafeLinkAttributeName(attrName)) {
+      continue;
+    }
+    if (name === "style" && typeof value === "object" && value !== null) {
+      const style = Object.entries(value as Record<string, unknown>)
+        .flatMap(([property, styleValue]) => {
+          const cssProperty = linkStylePropertyName(property);
+          const cssValue = linkStyleValue(styleValue);
+          return cssProperty === undefined || cssValue === undefined
+            ? []
+            : [`${cssProperty}:${cssValue}`];
+        })
+        .join(";");
+      if (style !== "") {
+        attrs.push(`${escapeHtmlAttribute(attrName)}="${escapeHtmlAttribute(style)}"`);
+      }
+      continue;
+    }
     const attrValue = String(value);
     const safeValue = safeUrlAttributeValue(attrName, attrValue);
 
@@ -238,6 +362,42 @@ function attributeName(name: string): string {
   return name === "className" ? "class" : name;
 }
 
+function isSafeLinkAttributeName(name: string): boolean {
+  return VALID_LINK_ATTRIBUTE_NAME.test(name);
+}
+
+function isLinkEventAttributeName(name: string): boolean {
+  return /^on/i.test(name);
+}
+
+function reportRejectedBrowserEventProp(name: string): void {
+  const nodeEnv = (
+    globalThis as typeof globalThis & {
+      process?: { env?: { NODE_ENV?: string | undefined } | undefined } | undefined;
+    }
+  ).process?.env?.NODE_ENV;
+
+  if (nodeEnv !== "production") {
+    console.warn(
+      `[MR_LINK_UNSAFE_EVENT_PROP] Link rejected event-like prop ${JSON.stringify(name)}. Pass a supported camel-cased function handler such as onClick instead.`,
+    );
+  }
+}
+
+function linkStylePropertyName(property: string): string | undefined {
+  const cssProperty = property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+  return /^(?:--[a-zA-Z0-9_-]+|[a-zA-Z][a-zA-Z0-9-]*)$/.test(cssProperty) ? cssProperty : undefined;
+}
+
+function linkStyleValue(value: unknown): string | undefined {
+  if (value === null || value === undefined || value === false) {
+    return undefined;
+  }
+
+  const cssValue = String(value);
+  return /[;{}]/.test(cssValue) ? undefined : cssValue;
+}
+
 function renderChildren(child: LinkChild): string {
   if (child === null || child === undefined || typeof child === "boolean") {
     return "";
@@ -254,6 +414,41 @@ function renderChildren(child: LinkChild): string {
   return escapeHtmlText(child);
 }
 
+function renderSinkChildren(child: LinkSinkChild): string {
+  if (child === null || child === undefined || typeof child === "boolean") {
+    return "";
+  }
+
+  if (Array.isArray(child)) {
+    return child.map(renderSinkChildren).join("");
+  }
+
+  if (isTrustedLinkHtml(child)) {
+    return child[TRUSTED_LINK_HTML];
+  }
+
+  if (typeof child === "object") {
+    return "";
+  }
+
+  return escapeHtmlText(String(child));
+}
+
+function isSerializableSinkChild(value: unknown): value is LinkSinkChild {
+  if (
+    value === null ||
+    value === undefined ||
+    typeof value === "boolean" ||
+    typeof value === "number" ||
+    typeof value === "string" ||
+    isTrustedLinkHtml(value)
+  ) {
+    return true;
+  }
+
+  return Array.isArray(value) && value.every(isSerializableSinkChild);
+}
+
 function isTrustedLinkHtml(value: unknown): value is TrustedLinkHtml {
   return (
     typeof value === "object" &&

package/src/render.ts

@@ -53,7 +53,8 @@ import {
 import { serverActionCookie } from "./csrf.js";
 import {
   type AppRouterCache,
-  beginRouteCacheContext,
+  activeRouteCacheContext,
+  withRouteCacheContext,
   cachedRouteResponse,
   cacheRouteResponse,
   routeCacheKey,
@@ -981,8 +982,7 @@ async function renderAppRequestInternal(
         script: string | undefined;
       }
     | undefined;
-  let routeCacheContext: ReturnType<typeof beginRouteCacheContext> | undefined;
-
+  return (await withRouteCacheContext(options.routeCache, async () => {
   try {
     if (matched.route.kind === "asset") {
       return await dispatchConventionAssetRoute({
@@ -1031,7 +1031,6 @@ async function renderAppRequestInternal(
       return methodResponse;
     }
 
-    routeCacheContext = beginRouteCacheContext(options.routeCache);
     const clientScript = options.clientScripts?.get(matched.route.path);
     const clientStyleSheets = options.clientStyles?.get(matched.route.path);
     phaseStartedAt = renderTimingPhaseStartedAt(timing);
@@ -1607,7 +1606,7 @@ async function renderAppRequestInternal(
       preparedActions.csrfTokenIsNew === true,
     );
 
-    const effectiveCachePolicy = cachePolicy ?? routeCacheContext.cachePolicy;
+    const effectiveCachePolicy = cachePolicy ?? activeRouteCacheContext()?.cachePolicy;
 
     const finalResponse = preparedActions.hasFormActions
       ? withRouteCacheHeader(response, effectiveCachePolicy)
@@ -1686,9 +1685,8 @@ async function renderAppRequestInternal(
     });
     emitRenderTiming(options, timing, response.status);
     return response;
-  } finally {
-    await routeCacheContext?.dispose();
   }
+  })).value;
 }
 
 async function applyAppRouterResponseHook(

package/src/request.ts

@@ -0,0 +1,35 @@
+/** Lightweight request/control-plane helpers that do not import router build or Vite modules. */
+export { cacheControl, createMemoryRouteCache, revalidatePath } from "./cache.js";
+export type {
+  AppRouterCache,
+  AppRouterCacheEntry,
+  CacheControlOptions,
+  MemoryRouteCacheOptions,
+} from "./cache.js";
+export { deleteCookie, parseCookieHeader, serializeCookie, setCookie } from "./cookies.js";
+export type { CookieOptions } from "./cookies.js";
+export { defer, isDeferredLoaderData } from "./deferred.js";
+export type { DeferredLoaderData } from "./deferred.js";
+export {
+  cookies,
+  headers,
+  html,
+  isNotFoundError,
+  isRedirectError,
+  json,
+  next,
+  notFound,
+  parseForm,
+  redirect,
+  redirect303,
+  redirectExternal,
+  rewrite,
+  textError,
+  throwNotFound,
+} from "./navigation.js";
+export type {
+  MiddlewareNext,
+  ParseSchema,
+  RedirectOptions,
+  RequestCookies,
+} from "./navigation.js";

package/src/typed-routes.ts

@@ -43,21 +43,21 @@ export interface DynamicHrefOptions<Path extends `/${string}`> extends StaticHre
   params: RouteParamsFor<Path>;
 }
 
-type HasRouteParams<Path extends `/${string}`> = keyof RouteParamsFor<Path> extends never
+export type HasRouteParams<Path extends `/${string}`> = keyof RouteParamsFor<Path> extends never
   ? false
   : true;
 
-type ExtractRouteParams<Path extends string> = Path extends `${infer Segment}/${infer Rest}`
+export type ExtractRouteParams<Path extends string> = Path extends `${infer Segment}/${infer Rest}`
   ? SegmentRouteParam<Segment> & ExtractRouteParams<Rest>
   : SegmentRouteParam<Path>;
 
-type SegmentRouteParam<Segment extends string> = Segment extends `:...${infer Name}`
+export type SegmentRouteParam<Segment extends string> = Segment extends `:...${infer Name}`
   ? { [Key in Name]: readonly string[] }
   : Segment extends `:${infer Name}`
     ? { [Key in Name]: string }
     : Record<never, never>;
 
-type Simplify<T> = { [Key in keyof T]: T[Key] } & {};
+export type Simplify<T> = { [Key in keyof T]: T[Key] } & {};
 
 /**
  * Represents the search and hash suffix portion of a typed route href.

package/src/vite.ts

@@ -54,6 +54,32 @@ import { hasJsxSyntax } from "./source-jsx.js";
 import { prependTailwindSourceDirectives } from "./tailwind-source.js";
 import { workspacePackageFile } from "./workspace-packages.js";
 
+export type { AppRouterAllowedServerAction, AppRouterServerActionOptions } from "./actions.js";
+export type { AppRouterCache, AppRouterCacheEntry } from "./cache.js";
+export type {
+  AppRouterBuildTarget,
+  AppRouterClientConsoleMethod,
+  AppRouterClientSourceMapMode,
+  AppRouterClientSourceMapOption,
+  AppRouterProductionOptions,
+  AppRouterProjectOptions,
+  ResolvedAppRouterProject,
+} from "./config.js";
+export type { AppRouterImportPolicy } from "./import-policy.js";
+export type {
+  AppRouterCspInlineNonceWarningLogEvent,
+  AppRouterLogError,
+  AppRouterLogEvent,
+  AppRouterLogger,
+  AppRouterRuntime,
+  AppRouterRenderTimingLogEvent,
+  AppRouterRequestEndLogEvent,
+  AppRouterRequestErrorLogEvent,
+  AppRouterRequestStartLogEvent,
+  AppRouterRequestTimingLogEvent,
+} from "./logger.js";
+export type { RequestHostPolicy } from "./serve.js";
+
 /**
  * Configures the app-router Vite middleware used by development servers.
  */
@@ -316,9 +342,12 @@ export function cell(initial) {
 
       if (id === virtualReactiveDevtoolsId) {
         return `export function emitReactiveDevtoolsEvent() {}
+export function emitReactiveEffectRunDevtoolsEvent() {}
 export function hasReactiveDevtoolsEmitter() { return false; }
 export function currentDevtoolsEmitter() { return undefined; }
-export function currentReactiveDevtools() { return undefined; }`;
+export function currentReactiveDevtools() { return undefined; }
+export function invalidateReactiveDevtoolsCache() {}
+export function prepareReactiveEffectRunDevtoolsEvent() { return undefined; }`;
       }
 
       if (id.startsWith(virtualClientPrefix)) {