@wular/pnext 0.0.1

package/reference/routing.md

@@ -0,0 +1,167 @@
+# Routing
+
+## Files
+
+- `app/**/page` defines a UI route.
+- `app/**/layout` exports metadata and can wrap descendant pages.
+- `app/**/route` defines HTTP handlers.
+- `proxy` or `middleware` runs before route matching.
+- `app/**/loading` defines a Suspense fallback for the segment.
+- `app/**/error` defines fallback UI for server render failures in the segment.
+- `app/**/not-found` defines fallback UI.
+
+Convention files are matched across `.tsx`, `.ts`, `.jsx`, `.js`, and `.mjs`.
+`.tsx`/`.ts` are tried first, so an all-`.tsx` app resolves on the first
+candidate. Route handlers (`route`) match `.ts`, `.tsx`, `.js`, `.mjs`.
+
+## Segments
+
+- `app/about/page.tsx` -> `/about`
+- `app/users/[id]/page.tsx` -> `/users/:id`
+- `app/docs/[...slug]/page.tsx` -> `/docs/*`
+- `app/docs/[[...slug]]/page.tsx` -> matches `/docs` AND `/docs/*` (the base path is included)
+- `app/(marketing)/pricing/page.tsx` -> `/pricing`
+- `app/dashboard/@team/page.tsx` -> a `@slot` directory adds no path segment; it is rendered as a slot of `/dashboard`
+
+### Intercepting markers
+
+A marker prefixes a segment to intercept a route from another level. The marker
+is stripped from the resulting path. See [Intercepting routes](#intercepting-routes).
+
+- `(.)segment` -> same level.
+- `(..)segment` -> one level up.
+- `(..)(..)segment` -> two levels up.
+- `(...)segment` -> from the app root.
+
+## Page Props
+
+Pages receive explicit props:
+
+```ts
+type PageProps<P = Record<string, string | string[]>> = {
+  params: Promise<P>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+  request?: NextRequest;
+};
+```
+
+Request data is read from `props.request`.
+
+## Route Handlers
+
+Route handlers use the Next-compatible `(request, context)` shape:
+
+```ts
+import type { RouteContext } from '#gen/app/api/users/[id]/route';
+import type { NextRequest } from '@wular/pnext/server';
+
+export async function GET(request: NextRequest, { params }: RouteContext) {
+  const { id } = await params;
+  return Response.json({
+    id,
+    q: request.nextUrl.searchParams.get('q'),
+  });
+}
+```
+
+`request` is a `NextRequest` compatible object. It extends the standard `Request` with convenience access for cookies and `nextUrl`.
+
+If `OPTIONS` is not exported, pnext returns an automatic `OPTIONS` response with an `Allow` header. Unsupported methods return `405 Method Not Allowed` with the same `Allow` header.
+
+Static `GET` route handlers are written as files during `pnext build`. Dynamic route handlers can export `params()` to write selected param outputs at build time.
+
+`generateStaticParams()` is supported in Next compat mode.
+
+## Route Rendering
+
+pnext infers route rendering separately from hydration:
+
+- `static`: no dynamic params and no request prop usage.
+- `dynamic`: request prop usage or dynamic route segments.
+
+Route segment config overrides the inference. Hydration is controlled by `"use client"`.
+
+## Route Segment Config
+
+Pages, layouts, and route handlers can export segment config. Values must be literals — they are read from the source, not evaluated.
+
+```ts
+export const dynamic = 'force-dynamic';
+export const maxDuration = 60;
+```
+
+Recognized: `dynamic` (`auto` | `force-dynamic` | `force-static` | `error`), `revalidate` (a non-negative number or `false`), `fetchCache`, `dynamicParams`, `runtime` (`edge` | `nodejs`), `prefetch`, and `maxDuration`.
+
+Config merges across the route's own file and its layout chain, leaf-first: the nearest declaration wins, except `force-dynamic` (any segment forces the whole route) and `revalidate` (the lowest declared number wins).
+
+When building with `pnext build --adapter vercel`, `maxDuration` is copied to the generated Vercel Node function metadata.
+
+## File Conventions
+
+`proxy.ts` and `middleware.ts` run before static files, pages, and route handlers. Use `proxy.ts` for new code. `middleware.ts` is supported for compatibility. If both exist, `proxy.ts` wins.
+
+```ts
+import { NextResponse, type NextRequest } from '@wular/pnext/server';
+
+export const config = {
+  matcher: ['/admin/:path*'],
+};
+
+export function proxy(request: NextRequest) {
+  if (!request.cookies.has('session')) {
+    return NextResponse.redirect(new URL('/login', request.url));
+  }
+  return NextResponse.next();
+}
+```
+
+Supported responses:
+
+- `NextResponse.next()` continues to the matched static file, page, or route handler.
+- `NextResponse.redirect(url)` returns a redirect response.
+- `NextResponse.rewrite(url)` serves another path without changing the browser URL.
+- `new Response(...)` returns a custom response directly.
+
+`config.matcher` takes a string, a string array, or objects with `source` plus `has`/`missing` conditions (`header`, `query`, `cookie`, `host`). Patterns support exact paths, `:param`, `:path*`, and regex. With no `matcher`, every request runs through the proxy.
+
+`loading.tsx` is used as the fallback for automatically wrapped server Suspense boundaries. Static builds wait for final HTML; dev and server responses can stream the fallback first.
+
+`not-found.tsx` is rendered when a route calls `notFound()` or when no route matches. `pnext build` also writes `404.html` when root `app/not-found.tsx` exists.
+
+`global-error.tsx` at the app root replaces the entire document when an unhandled error reaches the root uncaught. It renders its own `<html>` and `<body>`, so pnext skips the normal document shell and serves its markup directly. It only takes over when no nearer `error.tsx` boundary catches first, and a `"use client"` directive opts the file out.
+
+`redirect()` and `permanentRedirect()` stop rendering and return redirect responses. They can be called from pages, server components, route handlers, and server helpers used during rendering.
+Validate redirect targets that come from user input.
+
+`error.tsx` is rendered when server rendering throws. It receives `error`, `reset`, and `unstable_retry`; `reset()`/`unstable_retry()` refresh the current route in `compat.next` apps.
+
+`template.tsx` wraps the segment's children like a layout, but the segment re-renders per request where a layout persists. Nesting order is layout > template > children. A segment without a layout still applies its template.
+
+`default.tsx` is the fallback rendered for a parallel `@slot` that has no page match.
+
+`forbidden.tsx` and `unauthorized.tsx` render at 403/401 when `forbidden()` / `unauthorized()` is thrown. These are COMPAT-only (require `compat.next`) and experimental (`authInterrupts`); without compat they fall through to the normal error page.
+
+### Parallel routes
+
+A `@slot` directory (e.g. `@team`) contributes no path segment. Its content is rendered and passed to the owning segment's layout as a prop keyed by the slot name (without the `@`), alongside `children`. A slot uses its `page` when present, else its `default` fallback, else renders nothing. A slot's `loading` wraps its content in a Suspense boundary.
+
+### Intercepting routes
+
+An interception marker (`(.)`, `(..)`, `(..)(..)`, `(...)`) makes the route respond to soft navigations toward the marked target from the intercepting level, usually rendered into a parallel `@slot`. Hard requests render the non-intercepted target. Intercepting routes are always dynamic and never take static params.
+
+## Static Params
+
+Use `params()` on a dynamic route to choose params that `pnext build` should write as static HTML.
+Requests outside the returned list keep using dynamic rendering.
+
+```tsx
+import type { PageProps, StaticParams } from '#gen/app/users/[id]/page';
+
+export function params(): StaticParams {
+  return [{ id: 'ada' }, { id: 'grace' }];
+}
+
+export default async function Page({ params }: PageProps) {
+  return <p>{(await params).id}</p>;
+}
+```

package/reference/typegen.md

@@ -0,0 +1,64 @@
+# Type Safety
+
+pnext generates route types from the `app/` tree. These types check route params, static params, route handlers, and typed navigation.
+
+## Route Types
+
+Import generated types for the current route. pnext validates those exports against the route inferred from the file path, so a wrong param name, static param shape, or route handler context fails TypeScript.
+
+```tsx
+// app/users/[id]/page.tsx
+import type { PageProps, StaticParams } from '#gen/app/users/[id]/page';
+
+export function params(): StaticParams {
+  return [{ id: 'ada' }];
+}
+
+export default async function Page({ params }: PageProps) {
+  return <p>{(await params).id}</p>;
+}
+```
+
+Route handlers use generated `RouteContext` for the second argument:
+
+```ts
+// app/users/[id]/route.ts
+import type { RouteContext } from '#gen/app/users/[id]/route';
+import type { NextRequest } from '@wular/pnext/server';
+
+export async function GET(request: NextRequest, { params }: RouteContext) {
+  return Response.json({ id: (await params).id });
+}
+```
+
+## Links
+
+Typed links use typed `href` and `params`:
+
+```tsx
+import { Link } from '@wular/pnext/link';
+
+export function Nav() {
+  return <Link href="/users/[id]" params={{ id: 'ada' }}>Ada</Link>;
+}
+```
+
+Use a normal `<a>` for external URLs or intentionally untyped links.
+
+## Generated Types
+
+`pnext dev` and `pnext build` refresh generated types automatically. Use `pnext typegen` to refresh them manually.
+
+Generated files live in `.pnext/types` and should not be edited. Include `.pnext/types/**/*.ts` in the app TypeScript project for editor and `tsc` visibility.
+
+Use a TypeScript path alias for generated imports:
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "#gen/*": ["./.pnext/types/*"]
+    }
+  }
+}
+```

package/src/api/cache.ts

@@ -0,0 +1,80 @@
+import { currentCacheScope, type CacheNode } from '../cache/context';
+
+export function cache<Args extends unknown[], Result>(
+  fn: (...args: Args) => Result,
+): (...args: Args) => Result {
+  return (...args: Args) => {
+    const scope = currentCacheScope();
+    if (!scope) return fn(...args);
+
+    let root = scope.functions.get(fn);
+    if (!root) {
+      root = cacheNode();
+      scope.functions.set(fn, root);
+    }
+
+    const node = cacheNodeForArgs(root, args);
+    const record = node.record;
+    if (record) {
+      if (record.status === 'rejected') {
+        if (record.async) {
+          return Promise.resolve().then(() => {
+            throw record.error;
+          }) as Result;
+        }
+        throw record.error;
+      }
+      if (record.status === 'resolved' && record.async) return Promise.resolve(record.value) as Result;
+      return record.value as Result;
+    }
+
+    try {
+      const value = fn(...args);
+      if (isPromiseLike(value)) {
+        const promise = Promise.resolve(value).then(
+          result => {
+            node.record = { status: 'resolved', value: result, async: true };
+            return result;
+          },
+          error => {
+            node.record = { status: 'rejected', error, async: true };
+            throw error;
+          },
+        );
+        node.record = { status: 'pending', value: promise };
+        return promise as Result;
+      }
+
+      node.record = { status: 'resolved', value, async: false };
+      return value;
+    } catch (error) {
+      node.record = { status: 'rejected', error, async: false };
+      throw error;
+    }
+  };
+}
+
+function cacheNode(): CacheNode {
+  return { children: new Map() };
+}
+
+function cacheNodeForArgs(root: CacheNode, args: unknown[]) {
+  let node = root;
+  for (const arg of args) {
+    let child = node.children.get(arg);
+    if (!child) {
+      child = cacheNode();
+      node.children.set(arg, child);
+    }
+    node = child;
+  }
+  return node;
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === 'object' || typeof value === 'function') &&
+    value !== null &&
+    'then' in value
+  );
+}

package/src/api/client-cache.ts

@@ -0,0 +1,9 @@
+export function cache<Args extends unknown[], Result>(
+  fn: (...args: Args) => Result,
+): (...args: Args) => Result {
+  return (...args: Args) => fn(...args);
+}
+
+export function cacheSignal() {
+  return null;
+}

package/src/api/client-navigation.ts

@@ -0,0 +1,279 @@
+import { useEffect, useState } from 'preact/hooks';
+import { ReadonlyURLSearchParams, type HrefOptions } from './navigation';
+import { blockJavascriptUrl, prefetchRoute, softNavigate } from './router';
+import { seedHistoryEntry } from './router/history';
+import {
+  emitLocationChange,
+  locationListeners,
+  scheduleNavigationScroll,
+} from './router/events';
+import { routeHref } from '../routing/href';
+import type { RouteParams, RouteParamValue, RoutePath } from '../types';
+
+export type NavigateOptions<Route extends RoutePath> = HrefOptions<Route> & {
+  scroll?: boolean;
+};
+
+export type PrefetchOptions<Route extends RoutePath> = HrefOptions<Route> & {
+  kind?: 'auto' | 'full';
+  onInvalidate?: () => void;
+};
+
+export interface PNextRouter {
+  push<Route extends RoutePath>(
+    route: Route,
+    ...options: RouteParams<Route> extends Record<string, never>
+      ? [options?: NavigateOptions<Route>]
+      : [options: NavigateOptions<Route>]
+  ): void;
+  replace<Route extends RoutePath>(
+    route: Route,
+    ...options: RouteParams<Route> extends Record<string, never>
+      ? [options?: NavigateOptions<Route>]
+      : [options: NavigateOptions<Route>]
+  ): void;
+  prefetch<Route extends RoutePath>(
+    route: Route,
+    ...options: RouteParams<Route> extends Record<string, never>
+      ? [options?: PrefetchOptions<Route>]
+      : [options: PrefetchOptions<Route>]
+  ): void;
+  refresh(): void;
+  back(): void;
+  forward(): void;
+  bfcacheId: string;
+}
+
+export { ReadonlyURLSearchParams };
+
+export interface CurrentRoute<Route extends RoutePath = RoutePath> {
+  route: Route | null;
+  pathname: string;
+  params: RouteParams<Route>;
+  searchParams: ReadonlyURLSearchParams;
+}
+
+interface RouteState {
+  route?: string;
+  params?: Record<string, RouteParamValue>;
+  catchAllOptional?: boolean;
+  staticChildren?: string[];
+  bfcacheId?: string;
+  /** `prefetch = 'allow-runtime'`: this route's shell is request-sampled. */
+  runtimePrefetch?: boolean;
+}
+
+/**
+ * `__PNEXT_ROUTE__.route` is stored on the wire in bracket-free colon form
+ * (`/:teamSlug/:slug*`) so no `[x]`/`%5Bx%5D` placeholder ever reaches a
+ * response body. The public `useRoute()` contract exposes the familiar bracket
+ * pattern (`/[teamSlug]/[...slug]`), so convert back at the API boundary.
+ */
+function bracketRoutePattern(state: RouteState): string | null {
+  const route = state.route;
+  if (route == null) return null;
+  return route
+    .replace(/:([\w$]+)\*/g, state.catchAllOptional ? '[[...$1]]' : '[...$1]')
+    .replace(/:([\w$]+)/g, '[$1]');
+}
+
+declare global {
+  interface Window {
+    __PNEXT_ROUTE__?: RouteState;
+    __PNEXT_HISTORY_PATCHED__?: boolean;
+  }
+}
+
+// This module is the reason the hard-loaded entry needs its history ids before first render:
+// `bfcacheId` below reads them, and `patchHistory` carries them onto an app-level pushState. Seeding
+// here rather than in the hub's installRouter keeps a page whose client graph never touches router
+// state from paying for them.
+seedHistoryEntry();
+
+export function useRouter(): PNextRouter {
+  return router;
+}
+
+const router: PNextRouter = {
+  push(route, ...[options]) {
+    navigate(routerHref(route, options), 'push', options?.scroll);
+  },
+  replace(route, ...[options]) {
+    navigate(routerHref(route, options), 'replace', options?.scroll);
+  },
+  prefetch(route, ...[options]) {
+    void prefetchRoute(routerHref(route, options), {
+      strict: true,
+      full: options?.kind === 'full',
+      onInvalidate: options?.onInvalidate,
+    });
+  },
+  refresh() {
+    void softNavigate(window.location.href, { replace: true, scroll: false });
+  },
+  back() {
+    window.history.back();
+  },
+  forward() {
+    window.history.forward();
+  },
+  get bfcacheId() {
+    return routeState().bfcacheId ?? '';
+  },
+};
+
+function routerHref<Route extends RoutePath>(route: Route, options: HrefOptions<Route> | undefined) {
+  return hasHrefParts(options) ? routeHref(route, options) : String(route);
+}
+
+function hasHrefParts<Route extends RoutePath>(
+  options: HrefOptions<Route> | undefined,
+): options is HrefOptions<Route> {
+  return Boolean(options && ('params' in options || 'search' in options || 'hash' in options));
+}
+
+export function usePathname() {
+  return useLocation().pathname;
+}
+
+export function useSearchParams(): ReadonlyURLSearchParams {
+  return new ReadonlyURLSearchParams(useLocation().search);
+}
+
+export function useParams<Route extends RoutePath = RoutePath>() {
+  useLocation();
+  return (routeState().params ?? {}) as RouteParams<Route>;
+}
+
+export function useRoute<Route extends RoutePath = RoutePath>(): CurrentRoute<Route> {
+  const location = useLocation();
+  return {
+    route: bracketRoutePattern(routeState()) as Route | null,
+    pathname: location.pathname,
+    params: (routeState().params ?? {}) as RouteParams<Route>,
+    searchParams: new ReadonlyURLSearchParams(location.search),
+  };
+}
+
+export function useLinkStatus() {
+  return { pending: false };
+}
+
+function useLocation() {
+  const [location, setLocation] = useState(() => currentLocation());
+
+  useEffect(() => {
+    patchHistory();
+    const listener = () =>
+      setLocation(previous => {
+        const next = currentLocation();
+        return previous.pathname === next.pathname &&
+          previous.search === next.search &&
+          previous.hash === next.hash
+          ? previous
+          : next;
+      });
+    locationListeners().add(listener);
+    window.addEventListener('popstate', listener);
+    // Re-read once the listener is attached: the URL can move between the
+    // render that captured it and this effect (a history traversal landing
+    // while a swapped-in tree mounts), and nothing was listening for that one.
+    listener();
+    return () => {
+      locationListeners().delete(listener);
+      window.removeEventListener('popstate', listener);
+    };
+  }, []);
+
+  return location;
+}
+
+function currentLocation() {
+  if (!process.browser && typeof window === 'undefined') {
+    return {
+      pathname: '/',
+      search: '',
+      hash: '',
+    };
+  }
+  return {
+    pathname: window.location.pathname,
+    search: window.location.search,
+    hash: window.location.hash,
+  };
+}
+
+function routeState() {
+  if (!process.browser && typeof window === 'undefined') return {};
+  const state = (history.state as Record<string, unknown> | null) ?? {};
+  const routeState = window.__PNEXT_ROUTE__ ?? {};
+  const bfcacheId = typeof state.__pnextBfcacheId === 'string' ? state.__pnextBfcacheId : undefined;
+  return bfcacheId ? ({ ...routeState, bfcacheId } as RouteState) : routeState;
+}
+
+function navigate(url: string, mode: 'push' | 'replace', scroll = true) {
+  if (blockJavascriptUrl(url)) return;
+  const next = new URL(url, window.location.href);
+  if (next.origin !== window.location.origin) {
+    const holder = globalThis as { __pnextMpaNavigation?: number };
+    holder.__pnextMpaNavigation = (holder.__pnextMpaNavigation ?? 0) + 1;
+    requestAnimationFrame(() =>
+      requestAnimationFrame(() => {
+        if (mode === 'replace') window.location.replace(next.href);
+        else window.location.assign(next.href);
+      }),
+    );
+    return;
+  }
+
+  if (next.pathname !== window.location.pathname || next.search !== window.location.search) {
+    void softNavigate(next.href, { replace: mode === 'replace', scroll });
+    return;
+  }
+
+  if (mode === 'replace') window.history.replaceState(history.state, '', next);
+  else window.history.pushState(history.state, '', next);
+  scheduleNavigationScroll(next, { scroll });
+}
+
+// Exported so compat's link-status can guarantee raw history.pushState /
+// replaceState calls broadcast a location change (ending a link's pending
+// state) even when no useLocation-based hook has mounted yet.
+export function patchHistory() {
+  if ((!process.browser && typeof window === 'undefined') || window.__PNEXT_HISTORY_PATCHED__) return;
+  window.__PNEXT_HISTORY_PATCHED__ = true;
+  const pushState = window.history.pushState.bind(window.history);
+  const replaceState = window.history.replaceState.bind(window.history);
+
+  // Broadcast only when the URL actually changes. The router itself calls replaceState with the
+  // CURRENT href for bookkeeping - including at the start of every soft navigation - and emitting for
+  // those would clear a just-clicked link's pending state.
+  //
+  // An app-level pushState/replaceState creates an entry that still shows THIS document (shallow
+  // routing). Carrying pnext's own entry state over marks the new entry as pointing at the rendered
+  // document, so a later traversal is a location broadcast rather than a fetch-and-swap of a URL that
+  // may not even exist on the server. Router-initiated calls already carry the keys.
+  function copyInternalState(data: unknown): unknown {
+    const current = (window.history.state as Record<string, unknown> | null) ?? {};
+    const carried: Record<string, unknown> = {};
+    for (const key of Object.keys(current)) {
+      if (key.startsWith('__pnext')) carried[key] = current[key];
+    }
+    if (Object.keys(carried).length === 0) return data;
+    const own = (data as Record<string, unknown> | null) ?? {};
+    if (Object.keys(own).some(key => key.startsWith('__pnext'))) return data;
+    return { ...own, ...carried };
+  }
+  window.history.pushState = function patchedPushState(data, unused, url) {
+    const before = window.location.href;
+    const result = pushState(copyInternalState(data), unused, url);
+    if (window.location.href !== before) emitLocationChange();
+    return result;
+  };
+  window.history.replaceState = function patchedReplaceState(data, unused, url) {
+    const before = window.location.href;
+    const result = replaceState(copyInternalState(data), unused, url);
+    if (window.location.href !== before) emitLocationChange();
+    return result;
+  };
+}