@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

package/src/shared/slot-params.ts

@@ -0,0 +1,109 @@
+/**
+ * Per-slot segment params — the one definition both halves of the API read.
+ *
+ * A parallel slot matches the URL through its *own* sub-tree, so it can derive
+ * a param the main route never had, or derive the same name with a different
+ * type (`[...year]` → `string[]` where the main route's `[year]` gave
+ * `string`). The server answers `getSegmentParams(slotPath)` from a per-slot
+ * map; the client answers `useSegmentParams(slotPath)` from the same map,
+ * published on the RSC payload (TIM-1285).
+ *
+ * The merge lives here rather than in either half because the two must agree
+ * about what "the slot's params" are — a divergence is invisible until
+ * somebody reads a param of the wrong type, which is exactly the class of bug
+ * this module closes.
+ *
+ * Isomorphic: no server or client imports.
+ *
+ * See design/41-global-params.md §"Params in a parallel slot".
+ */
+
+import type { CoercedParams } from './param-value.ts';
+
+/** Slot tree path → that slot's own coerced params. */
+export type SlotParamsRecord = Record<string, CoercedParams>;
+
+/**
+ * The params a slot sees: the main route's as a base, the slot's own on top.
+ *
+ * Params from segments *above* the slot are not re-derived by the slot's own
+ * chain, so they have to come from the main route; params the slot does
+ * re-derive may have a different type than the main route gave them, so the
+ * slot's win.
+ *
+ * Null-prototype, like every other param record the framework hands out
+ * (`coerceSegmentParams` installs one unconditionally). A spread literal would
+ * inherit `Object.prototype`, so a lookup for a param the route does not
+ * define would resolve to an inherited member — `params.constructor` returning
+ * a function instead of `undefined` — in the one param record that was built
+ * by merging. See design/13-security.md #36c.
+ */
+export function mergeSlotParams(
+  mainParams: CoercedParams,
+  slotParams: CoercedParams
+): CoercedParams {
+  return Object.assign(Object.create(null), mainParams, slotParams);
+}
+
+/**
+ * Resolve the params for a segment path against a published slot map.
+ *
+ * Returns the merge when `segmentPath` names a slot that published params,
+ * and the main route's record otherwise — an ordinary (non-slot) segment
+ * path, an unknown path, or a request with no slots at all. Mirrors the
+ * server's `getSegmentParams(segmentPath)` branch exactly.
+ *
+ * `Object.hasOwn` rather than `in` or a truthiness test: the map arrives from
+ * JSON, so a segment path of `constructor` or `toString` would otherwise
+ * resolve to an inherited member of `Object.prototype`.
+ */
+export function resolveSegmentParams(
+  mainParams: CoercedParams,
+  slotParams: SlotParamsRecord | null | undefined,
+  segmentPath: string | undefined
+): CoercedParams {
+  if (!segmentPath || !slotParams || !Object.hasOwn(slotParams, segmentPath)) return mainParams;
+  return cachedMerge(mainParams, slotParams, segmentPath);
+}
+
+/**
+ * The merged record for one (main record, slot map, path) triple, reused until
+ * one of the three changes.
+ *
+ * `useSegmentParams(slotPath)` calls this on every render. Returning a fresh
+ * object each time makes the hook's result change by reference on renders where
+ * nothing navigated, so a component using it as a `useEffect` dependency
+ * re-runs the effect — and re-renders in a loop if that effect sets state —
+ * while memoized children below it lose their memoization.
+ *
+ * Keyed on the *identities* of the two records, not their contents: both are
+ * replaced rather than mutated on every navigation (`ParamsProvider`'s memoized
+ * value and the server's per-request store), so identity is the correct
+ * equality here and a deep comparison would be slower and no more accurate.
+ *
+ * A `WeakMap` chain rather than a `Map`, so a superseded navigation's records
+ * and their merges become collectable as soon as nothing else holds them.
+ */
+const mergeCache = new WeakMap<object, WeakMap<object, Map<string, CoercedParams>>>();
+
+function cachedMerge(
+  mainParams: CoercedParams,
+  slotParams: SlotParamsRecord,
+  segmentPath: string
+): CoercedParams {
+  let bySlotMap = mergeCache.get(mainParams);
+  if (!bySlotMap) {
+    bySlotMap = new WeakMap();
+    mergeCache.set(mainParams, bySlotMap);
+  }
+  let byPath = bySlotMap.get(slotParams);
+  if (!byPath) {
+    byPath = new Map();
+    bySlotMap.set(slotParams, byPath);
+  }
+  const cached = byPath.get(segmentPath);
+  if (cached) return cached;
+  const merged = mergeSlotParams(mainParams, slotParams[segmentPath]);
+  byPath.set(segmentPath, merged);
+  return merged;
+}

package/src/shared/static-platform-files.ts

@@ -0,0 +1,75 @@
+/**
+ * Platform files the static build is allowed to overwrite in the output.
+ *
+ * The build merges two trees into the deployed directory — the client bundle
+ * (which carries everything the user put in `public/`) and the pre-rendered
+ * site. That merge otherwise refuses overlaps, because a silent overwrite
+ * leaves one of two artifacts deployed with nothing recording which
+ * (TIM-1266).
+ *
+ * These names are the exception, and only because the pre-rendered copy is
+ * *derived from* the one it replaces rather than competing with it:
+ * `plugins/static-build.ts` reads `public/_redirects` and writes the
+ * generated rules plus the user's, so the winner is a superset of the loser.
+ *
+ * That holds only for a file the current pass produced, which is why
+ * `cleanConditionalArtifacts` deletes a previous build's `_redirects` before
+ * generation: written only when a pass finds redirects, it would otherwise
+ * survive into a pass that produced nothing and claim an exemption it no
+ * longer earns.
+ *
+ * `_headers` is NOT here. It is not written into the pre-rendered tree at
+ * all — adapters generate it directly into the output, folding in the
+ * user's copy as they go (TIM-1326).
+ *
+ * Declared once so the code that performs the merge and the code that
+ * produces the merged file cannot disagree about which names are exempt.
+ *
+ * Isomorphic: no server, client, or build-time imports.
+ */
+
+/** Platform redirect rules (Cloudflare Pages, Netlify). See TIM-1245/TIM-1249. */
+export const REDIRECTS_FILE = '_redirects';
+
+/** Platform header rules (Cloudflare Pages, Netlify). See TIM-1241/TIM-1326. */
+export const HEADERS_FILE = '_headers';
+
+/**
+ * Where a user authors platform files. Stated once because two modules read
+ * from here — `plugins/static-build.ts` for `_redirects`, adapters for
+ * `_headers` — and they must look in the same place.
+ *
+ * Both read the **project source**, never the build output. The generated
+ * file lands under the same name in the output directory, so a reader aimed
+ * there would fold the previous build's generated rules back in and compound
+ * them on every rebuild.
+ */
+export const USER_PLATFORM_DIR = 'public';
+
+/** Output-relative paths whose pre-rendered copy subsumes the `public/` one. */
+export const USER_MERGED_PLATFORM_FILES: readonly string[] = [REDIRECTS_FILE];
+
+/**
+ * Output paths the framework writes itself, which no route may claim.
+ *
+ * These are written outside the per-entry writer — `_redirects` after
+ * generation, `_headers` by the adapter after the copy — so the collision
+ * tracker never sees them and a route rendering to one of these paths is
+ * overwritten with nothing recording it.
+ *
+ * Reserved rather than tracked, because there is no version of "serve a route
+ * at `/_headers`" that works: Cloudflare Pages and Netlify read these two
+ * files themselves and never serve them, so the route is unservable however
+ * the conflict is resolved.
+ *
+ * That justification is per-file, not per-mechanism. `.nojekyll` is written
+ * the same way and is deliberately NOT here: only the `github-pages` target
+ * writes it, and everywhere else `/.nojekyll` is an ordinary servable path,
+ * so reserving it globally would refuse a valid Cloudflare site. Its write
+ * site skips the write when a file is already there instead — GitHub Pages
+ * only cares that the file exists.
+ *
+ * Same reasoning as the synthetic 404 entry using an internal urlPath so a
+ * real `/404` route cannot collide with `404.html`.
+ */
+export const RESERVED_OUTPUT_PATHS: readonly string[] = [REDIRECTS_FILE, HEADERS_FILE];

package/src/shared/status-reason-phrase.ts

@@ -0,0 +1,61 @@
+/**
+ * Reason phrases for the framework default status page.
+ *
+ * Shared between the server-rendered default page (`server/default-status-page.ts`,
+ * the HTML terminal of the deny chain) and its client-rendered counterpart
+ * (`client/deny-last-resort.tsx`, the terminal a streamed deny reaches when no
+ * status file sits at or above the component that denied). One table, so the
+ * two surfaces cannot drift — a reader who sees "403 Forbidden" on a document
+ * load must see the same words after a client navigation.
+ *
+ * Nothing here is caller-supplied text: the phrase is looked up from a clamped
+ * integer, never interpolated from a request. See design/13-security.md
+ * principle 4 ("Errors don't leak").
+ */
+
+/**
+ * Canonical reason phrases (RFC 9110 §15) for the statuses an app is likely to
+ * `deny()` with. Anything else falls back to a generic category phrase.
+ */
+const REASON_PHRASES: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  402: 'Payment Required',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  406: 'Not Acceptable',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  410: 'Gone',
+  413: 'Content Too Large',
+  415: 'Unsupported Media Type',
+  418: "I'm a Teapot",
+  422: 'Unprocessable Content',
+  429: 'Too Many Requests',
+  451: 'Unavailable For Legal Reasons',
+  500: 'Internal Server Error',
+  501: 'Not Implemented',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+};
+
+/**
+ * Coerce a status into something safe to put in markup.
+ *
+ * `DenySignal.status` is typed `number` but nothing validates it at
+ * construction, and JS callers can hand us anything. Rather than escaping a
+ * value that should never have been a string, collapse non-integers to 500 —
+ * the page is decoration for a status already on the wire.
+ */
+export function displayStatus(status: number): number {
+  return Number.isInteger(status) && status >= 100 && status <= 599 ? status : 500;
+}
+
+/** Human-readable phrase for a status code. Never caller-supplied text. */
+export function statusReasonPhrase(status: number): string {
+  const code = displayStatus(status);
+  if (REASON_PHRASES[code]) return REASON_PHRASES[code];
+  return code >= 500 ? 'Server Error' : 'Request Error';
+}

package/src/shims/font-google.ts

@@ -17,7 +17,7 @@
  * Design doc: 24-fonts.md, "Next.js Font Compatibility"
  */
 
-import type { GoogleFontConfig, FontResult } from '#/fonts/types.js';
+import type { GoogleFontConfig, FontResult } from '../fonts/types.ts';
 
 export type { GoogleFontConfig, FontResult };
 

package/src/shims/font-local.ts

@@ -0,0 +1,34 @@
+/**
+ * Fallback shim for `next/font/local` → `@timber/fonts/local`.
+ *
+ * At build time, the timber-fonts plugin's transform hook replaces
+ * `localFont()` calls with static FontResult objects containing real
+ * class names and font stacks. This file serves two purposes:
+ *
+ * 1. **TypeScript resolution** — provides types for IDEs and `tsc` outside
+ *    of Vite's module graph (where the virtual module handles it).
+ * 2. **Runtime fallback** — returns empty className/fontFamily values when
+ *    the plugin hasn't processed a call (e.g. in tests or non-Vite environments).
+ *
+ * Design doc: 24-fonts.md, "Next.js Font Compatibility"
+ */
+
+import type { LocalFontConfig, FontResult } from '../fonts/types.ts';
+
+export type { LocalFontConfig, FontResult };
+
+/**
+ * Create a local font.
+ *
+ * The timber-fonts plugin replaces these calls at build time with real
+ * class names and font stacks. This stub ensures code that imports
+ * `localFont` outside of the build pipeline (tests, type-checking)
+ * gets a valid FontResult shape without runtime errors.
+ */
+export default function localFont(config?: LocalFontConfig): FontResult {
+  return {
+    className: '',
+    style: { fontFamily: '' },
+    variable: config?.variable,
+  };
+}

package/src/shims/headers.ts

@@ -4,6 +4,127 @@
  * Imports from @timber-js/app/server which Vite resolves to dist/server/index.js
  * via native package.json exports. This ensures the same ALS singleton as the
  * pipeline (both import from the same shared request-context chunk in dist/).
+ *
+ * `cookies()` is NOT a bare alias of `getCookieJar()`: Next.js's
+ * RequestCookies returns `{ name, value }` RequestCookie objects from
+ * `.get()`/`.getAll()`, while timber's native jar returns bare strings from
+ * `.get()`. Ecosystem libraries written against the real API use
+ * `(await cookies()).get('session')?.value` — with the bare-string shape
+ * that silently reads `undefined` off a string. The adapter below presents
+ * the Next shape while delegating every operation to the timber jar, so the
+ * encoding contract, cookie-octet validation, and mutable-context checks
+ * (design/29-cookies.md, ONGOING_SECURITY.md H-3) apply unchanged.
+ * See TIM-1042 and design/14-ecosystem.md §next/headers.
+ */
+
+import { getCookieJar } from '@timber-js/app/server';
+import type { CookieOptions, SetCookieOptions } from '@timber-js/app/server';
+
+// Re-export timber's primary API
+export { getHeaders, getCookieJar } from '@timber-js/app/server';
+
+// Next.js compat alias — libraries importing from 'next/headers' expect this name.
+export { getHeaders as headers } from '@timber-js/app/server';
+
+/** Next.js's request cookie shape: `cookies().get(name)` → `{ name, value }`. */
+export interface RequestCookie {
+  name: string;
+  value: string;
+}
+
+/** Next.js's `cookies().set()` options — `expires` may be a ms timestamp. */
+export interface NextCookieOptions extends Omit<SetCookieOptions, 'expires'> {
+  expires?: Date | number;
+}
+
+/** Next.js's object overload for `cookies().set({ name, value, ...options })`. */
+export interface NextCookieListItem extends NextCookieOptions {
+  name: string;
+  value: string;
+}
+
+/** Next.js's RequestCookies surface, backed by timber's cookie jar. */
+export interface NextRequestCookies {
+  get(name: string): RequestCookie | undefined;
+  get(cookie: RequestCookie): RequestCookie | undefined;
+  getAll(name?: string): RequestCookie[];
+  getAll(cookie: RequestCookie): RequestCookie[];
+  has(name: string): boolean;
+  readonly size: number;
+  set(name: string, value: string, options?: NextCookieOptions): void;
+  set(cookie: NextCookieListItem): void;
+  delete(name: string): void;
+  delete(cookie: { name: string } & Pick<CookieOptions, 'path' | 'domain'>): void;
+  [Symbol.iterator](): IterableIterator<[string, RequestCookie]>;
+  toString(): string;
+}
+
+/** Normalize Next's `expires?: Date | number` (ms timestamp) to timber's `Date`. */
+function normalizeOptions(options?: NextCookieOptions): SetCookieOptions | undefined {
+  if (!options) return undefined;
+  const { expires, ...rest } = options;
+  if (typeof expires === 'number') return { ...rest, expires: new Date(expires) };
+  return options as SetCookieOptions;
+}
+
+/**
+ * Next.js compat: `cookies()` returning the RequestCookies shape.
+ *
+ * Next.js 15 makes `cookies()` async; awaiting this sync return value works
+ * for both the `(await cookies()).get()` and legacy `cookies().get()` call
+ * styles, so libraries targeting either Next version resolve correctly.
  */
+export function cookies(): NextRequestCookies {
+  const jar = getCookieJar();
+
+  const toCookie = (name: string): RequestCookie | undefined => {
+    const value = jar.get(name);
+    return value === undefined ? undefined : { name, value };
+  };
 
-export { headers, cookies } from '@timber-js/app/server';
+  return {
+    get(nameOrCookie: string | RequestCookie): RequestCookie | undefined {
+      return toCookie(typeof nameOrCookie === 'string' ? nameOrCookie : nameOrCookie.name);
+    },
+    getAll(nameOrCookie?: string | RequestCookie): RequestCookie[] {
+      const all = jar.getAll();
+      if (nameOrCookie === undefined) return all;
+      const name = typeof nameOrCookie === 'string' ? nameOrCookie : nameOrCookie.name;
+      return all.filter((cookie) => cookie.name === name);
+    },
+    has(name: string): boolean {
+      return jar.has(name);
+    },
+    get size(): number {
+      return jar.size;
+    },
+    set(
+      nameOrCookie: string | NextCookieListItem,
+      value?: string,
+      options?: NextCookieOptions
+    ): void {
+      if (typeof nameOrCookie === 'string') {
+        jar.set(nameOrCookie, value as string, normalizeOptions(options));
+      } else {
+        const { name, value: cookieValue, ...objectOptions } = nameOrCookie;
+        jar.set(name, cookieValue, normalizeOptions(objectOptions));
+      }
+    },
+    delete(nameOrCookie: string | ({ name: string } & Pick<CookieOptions, 'path' | 'domain'>)) {
+      if (typeof nameOrCookie === 'string') {
+        jar.delete(nameOrCookie);
+      } else {
+        const { name, ...options } = nameOrCookie;
+        jar.delete(name, options);
+      }
+    },
+    *[Symbol.iterator](): IterableIterator<[string, RequestCookie]> {
+      for (const cookie of jar.getAll()) {
+        yield [cookie.name, cookie];
+      }
+    },
+    toString(): string {
+      return jar.toString();
+    },
+  };
+}

package/src/shims/navigation-client.ts

@@ -1,12 +1,19 @@
 /**
  * Shim: next/navigation (client environment only)
  *
- * Re-exports only the client-side hooks from timber's client API.
- * Server-only functions (redirect, notFound, etc.) are excluded to prevent
- * server/primitives.ts from being pulled into the browser bundle.
+ * Re-exports the client-side hooks from timber's client API, and implements
+ * client-render `redirect()` without pulling server/primitives.ts into the
+ * browser bundle.
+ *
+ * Next.js supports calling redirect() during client component render.
+ * timber matches that by throwing a plain Error carrying the same JSON
+ * digest the server pipeline attaches to RedirectSignal. TimberErrorBoundary
+ * recognizes the digest and converts it to an SPA navigation (replace
+ * semantics), and browser-dev's isFrameworkSignalError() keeps it out of
+ * the dev overlay.
  *
  * The full shim (navigation.ts) is still used in the RSC and SSR environments
- * where both client hooks and server functions are needed.
+ * where the real server primitives produce proper HTTP responses.
  *
  * Imports use @timber-js/app/client (not #/ subpath imports) so they resolve
  * to the same module instances as user code in Vite dev — preventing module
@@ -16,42 +23,39 @@
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
 
-// Hooks — imported from the public barrel for module singleton consistency.
+import { assertRelativeRedirectPath } from '../shared/href-validation.ts';
+import type { RedirectTypeValue } from '../shared/redirect-type.ts';
+
+// Hooks — useSegmentParams and useSearchParams import from direct modules
+// since they're no longer in @timber-js/app/client public exports.
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.ts';
+export { useSearchParams } from '../client/use-search-params.ts';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
 } from '@timber-js/app/client';
 
-// RedirectType enum is safe (no server code dependency) and used by some
-// client-side libraries for type checking.
-export const RedirectType = {
-  push: 'push',
-  replace: 'replace',
-} as const;
-
-// Server-only stubs — throw at runtime if called from the client.
-// These exist for type compatibility with libraries that import the types
-// but should never execute in the browser.
-export function redirect(): never {
-  throw new Error(
-    'redirect() is a server-only function and cannot be called from client components. ' +
-      'Use useRouter().push() or useRouter().replace() for client-side navigation.'
-  );
-}
+// Single source of truth shared with server/primitives.ts.
+export { RedirectType } from '../shared/redirect-type.ts';
 
-export function permanentRedirect(): never {
-  throw new Error(
-    'permanentRedirect() is a server-only function and cannot be called from client components. ' +
-      'Use useRouter().push() or useRouter().replace() for client-side navigation.'
-  );
+/** Throw a plain Error carrying a framework signal digest. */
+function throwSignal(message: string, digest: Record<string, unknown>): never {
+  const err = new Error(message);
+  (err as Error & { digest?: string }).digest = JSON.stringify(digest);
+  throw err;
 }
 
-export function notFound(): never {
-  throw new Error(
-    'notFound() is a server-only function and cannot be called from client components.'
-  );
+/**
+ * Client-render redirect. Throws a redirect-digest error that the nearest
+ * TimberErrorBoundary converts into an SPA navigation (replace semantics).
+ *
+ * The optional RedirectType argument is accepted for Next.js API
+ * compatibility but ignored — timber always uses replace semantics,
+ * matching the server-side redirect().
+ */
+export function redirect(path: string, _type?: RedirectTypeValue): never {
+  assertRelativeRedirectPath(path);
+  throwSignal(`Redirect to ${path}`, { type: 'redirect', location: path, status: 302 });
 }

package/src/shims/navigation-rsc.ts

@@ -0,0 +1,47 @@
+/**
+ * Shim: next/navigation → RSC environment only
+ *
+ * RSC's stripped-down React provides neither `useContext` nor `createContext`,
+ * so the real hook modules cannot be evaluated there. This shim exports
+ * throwing stubs for every client hook, with the same error messages the
+ * guards previously produced inline, and re-exports the server functions
+ * from @timber-js/app/server unchanged.
+ *
+ * The shims plugin resolves `next/navigation` to this file in the RSC
+ * environment, `navigation.ts` in SSR, and `navigation-client.ts` in the
+ * browser. This split eliminates the `typeof React.useContext !== 'function'`
+ * guards that React Compiler flagged as conditional hook calls (TIM-1420).
+ */
+
+function clientOnlyHook(name: string, extra?: string): never {
+  throw new Error(
+    `[timber] ${name}() is only available in Client Components. ` +
+      (extra ?? "Add 'use client' to the module that calls it.")
+  );
+}
+
+export function usePathname(): string {
+  clientOnlyHook('usePathname');
+}
+
+export function useSearchParams(): URLSearchParams {
+  clientOnlyHook('useSearchParams');
+}
+
+export function useSegmentParams(): Record<string, unknown> {
+  clientOnlyHook(
+    'useSegmentParams',
+    "In a Server Component, use getSegmentParams() from '@timber-js/app/server'; " +
+      "otherwise add 'use client' to the module that calls it."
+  );
+}
+
+export { useSegmentParams as useParams };
+
+export {
+  useRouter,
+  useSelectedLayoutSegment,
+  useSelectedLayoutSegments,
+} from '@timber-js/app/client';
+
+export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';

package/src/shims/navigation.ts

@@ -1,20 +1,23 @@
 /**
  * Shim: next/navigation → timber navigation primitives
  *
- * Client hooks import from @timber-js/app/client (the public barrel) so they
- * resolve to the same module instances as user code in Vite dev. Server
- * functions import from @timber-js/app/server for ALS singleton consistency.
+ * Client hooks import from their direct modules since useSegmentParams,
+ * useSearchParams, and useQueryStates are no longer part of
+ * @timber-js/app/client public exports (they live on define* factories).
+ * The shim re-exports them for next/navigation library compat (nuqs etc).
+ *
+ * Server functions import from @timber-js/app/server for ALS singleton consistency.
  */
 
-// Hooks (client-side — imported from public barrel for module singleton)
+// Hooks re-exported for next/navigation compat
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.ts';
+export { useSearchParams } from '../client/use-search-params.ts';
 export {
-  useParams,
   usePathname,
-  useSearchParams,
   useRouter,
   useSelectedLayoutSegment,
   useSelectedLayoutSegments,
 } from '@timber-js/app/client';
 
 // Functions (server-side)
-export { redirect, permanentRedirect, notFound, RedirectType } from '@timber-js/app/server';
+export { redirect, redirectExternal, RedirectType } from '@timber-js/app/server';