@timber-js/app 0.2.0-alpha.145 → 0.2.0-alpha.147

package/src/server/tracing.ts

@@ -94,6 +94,16 @@ export function getTraceStore(): TraceStore | undefined {
 
 // ─── Dev-Mode OTEL Auto-Init ─────────────────────────────────────────────
 
+/**
+ * Well-known key marking dev tracing as initialized.
+ *
+ * The RSC entry module re-evaluates on every HMR invalidation and calls
+ * initDevTracing() again — without this guard, each call would register a
+ * fresh provider/processor and duplicate every span's output. Symbol.for()
+ * survives module re-evaluation. See TIM-1067, B49.
+ */
+const DEV_TRACING_INIT_KEY = Symbol.for('timber.dev.tracing-initialized');
+
 /**
  * Initialize a minimal OTEL SDK in dev mode so spans are recorded and
  * fed to the DevSpanProcessor for dev log output.
@@ -102,11 +112,15 @@ export function getTraceStore(): TraceStore | undefined {
  * our DevSpanProcessor alongside theirs. If no SDK is configured,
  * we create a BasicTracerProvider with our processor.
  *
- * Only called in dev mode — zero overhead in production.
+ * Idempotent across module re-evaluations (HMR) — only the first call
+ * registers. Only called in dev mode — zero overhead in production.
  */
 export async function initDevTracing(
   config: import('../dev-tools/logger.js').DevLoggerConfig
 ): Promise<void> {
+  const globals = globalThis as Record<symbol, unknown>;
+  if (globals[DEV_TRACING_INIT_KEY]) return;
+
   const api = await getOtelApi();
   if (!api) return;
 
@@ -145,6 +159,8 @@ export async function initDevTracing(
 
   // Reset cached tracer so next getTracer() picks up the new provider
   _tracer = undefined;
+
+  globals[DEV_TRACING_INIT_KEY] = true;
 }
 
 // ─── OTEL Span Helpers ───────────────────────────────────────────────────

package/src/server/tree-match.ts

@@ -142,7 +142,7 @@ function matchNode<TFile>(
     // with no path segments.
     const effective = collectEffectiveChildren(node);
     for (const { child, groupChain } of effective) {
-      if (child.segmentType === 'optional-catch-all' && isTerminal(child)) {
+      if (child.segmentType === 'optional-catch-all' && (!requireTerminal || isTerminal(child))) {
         chain.push(...groupChain, child);
         return true;
       }
@@ -187,18 +187,28 @@ function matchNode<TFile>(
     }
   }
 
-  // 3. Catch-all segments ([...param]) — must be terminal
+  // 3. Catch-all segments ([...param]) — must be terminal unless the
+  // caller passed requireTerminal:false (metadata route matching needs to
+  // find the owning segment even when it has no page).
   for (const { child, groupChain } of effective) {
-    if (child.segmentType === 'catch-all' && child.paramName && isTerminal(child)) {
+    if (
+      child.segmentType === 'catch-all' &&
+      child.paramName &&
+      (!requireTerminal || isTerminal(child))
+    ) {
       chain.push(...groupChain, child);
       params[child.paramName] = parts.slice(index);
       return true;
     }
   }
 
-  // 4. Optional catch-all segments ([[...param]]) — must be terminal
+  // 4. Optional catch-all segments ([[...param]]) — same terminal rule
   for (const { child, groupChain } of effective) {
-    if (child.segmentType === 'optional-catch-all' && child.paramName && isTerminal(child)) {
+    if (
+      child.segmentType === 'optional-catch-all' &&
+      child.paramName &&
+      (!requireTerminal || isTerminal(child))
+    ) {
       chain.push(...groupChain, child);
       params[child.paramName] = parts.slice(index);
       return true;

package/src/server/utils/mdx-file.ts

@@ -0,0 +1,22 @@
+/**
+ * MDX file-path detection shared by error/deny rendering paths.
+ *
+ * MDX status and error files are server components — they cannot be passed
+ * as function props across the RSC→client boundary (e.g. to
+ * TimberErrorBoundary or ErrorReconstituter) and must be pre-rendered as
+ * elements with plain props instead.
+ *
+ * See design/10-error-handling.md §"Status-Code File Variants".
+ */
+
+/** MDX/markdown extensions — server components by default. */
+const MDX_EXTENSIONS = new Set(['.mdx', '.md']);
+
+/**
+ * Check if a file path ends with an MDX/markdown extension.
+ */
+export function isMdxFilePath(filePath: string): boolean {
+  const dotIndex = filePath.lastIndexOf('.');
+  if (dotIndex === -1) return false;
+  return MDX_EXTENSIONS.has(filePath.slice(dotIndex));
+}

package/src/shared/head-header.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared encode/decode for the X-Timber-Head response header.
+ *
+ * Head elements (title, meta, link) are forwarded to the client as a JSON
+ * payload in a response header on both the navigation path (RSC payload
+ * responses) and the action-revalidation path. HTTP header values must be
+ * ByteStrings — any character above U+00FF (em dash, curly quotes, emoji,
+ * CJK) makes `new Response(...)` throw. Percent-encoding via
+ * encodeURIComponent keeps the value ASCII-safe.
+ *
+ * This module is the single source of truth for the wire format. Both
+ * server emit sites (rsc-entry/rsc-payload.ts, action-handler.ts) and both
+ * client parse sites (rsc-fetch.ts, browser-entry/action-dispatch.ts) MUST
+ * use it — changing one side alone breaks the other. See TIM-1058.
+ *
+ * Isomorphic: no server or client imports allowed here.
+ *
+ * See design/16-metadata.md and design/08-forms-and-actions.md.
+ */
+
+/** Header name for resolved head elements. */
+export const HEAD_HEADER = 'X-Timber-Head';
+
+/**
+ * Maximum encoded payload size in characters (ASCII after encoding, so
+ * characters === bytes). Headers aren't meant for unbounded payloads;
+ * oversized head metadata is skipped rather than truncated — the client
+ * keeps its current head, which degrades gracefully.
+ */
+export const HEAD_HEADER_MAX_LENGTH = 4096;
+
+/**
+ * A rendered head element descriptor — the structural shape on the wire.
+ * Matches the server's `HeadElement` (route-element-builder.ts); the client
+ * narrows `tag` to 'title' | 'meta' | 'link' when applying to the DOM.
+ */
+export interface HeadElementPayload {
+  tag: string;
+  content?: string;
+  attrs?: Record<string, string | null>;
+}
+
+/**
+ * Encode head elements for the X-Timber-Head header.
+ *
+ * Returns the percent-encoded JSON string, or null when the encoded
+ * payload exceeds HEAD_HEADER_MAX_LENGTH (caller skips the header).
+ */
+export function encodeHeadHeader(headElements: HeadElementPayload[]): string | null {
+  const encoded = encodeURIComponent(JSON.stringify(headElements));
+  return encoded.length <= HEAD_HEADER_MAX_LENGTH ? encoded : null;
+}
+
+/**
+ * Decode an X-Timber-Head header value back into head elements.
+ *
+ * Returns null when the value is missing or malformed (corrupted
+ * percent-encoding or invalid JSON) — callers treat null as "no head
+ * update" rather than failing the navigation or action.
+ */
+export function decodeHeadHeader(header: string | null): HeadElementPayload[] | null {
+  if (!header) return null;
+  try {
+    const parsed = JSON.parse(decodeURIComponent(header));
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}

package/src/shared/href-validation.ts

@@ -80,6 +80,30 @@ export function isInternalHref(href: string): boolean {
   return true;
 }
 
+/** Pattern matching absolute URLs: any scheme (http:, javascript:, …) or protocol-relative // */
+const ABSOLUTE_URL_RE = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
+
+/**
+ * Assert that a redirect target is a relative path — rejects absolute and
+ * protocol-relative URLs. Used by both the server `redirect()` primitive and
+ * the client next/navigation shim so they enforce identical semantics.
+ *
+ * Normalizes for validation only: strips C0 controls, trims, then replaces
+ * backslashes with forward slashes. Browsers normalize \ → / during URL
+ * resolution, so "/\evil.com" becomes "//evil.com" (protocol-relative open
+ * redirect). See design/13-security.md tests #8, #8a–#8c.
+ */
+export function assertRelativeRedirectPath(path: string): void {
+  const cleaned = path.replace(CONTROL_CHARS_RE, '').trimStart().replaceAll('\\', '/');
+
+  if (ABSOLUTE_URL_RE.test(cleaned)) {
+    throw new Error(
+      `redirect() only accepts relative URLs. Got absolute URL: "${path}". ` +
+        'Use redirectExternal(url, allowList) for external redirects.'
+    );
+  }
+}
+
 const SAFE_REDIRECT_SCHEMES = new Set(['http:', 'https:']);
 
 /**

package/src/shared/redirect-type.ts

@@ -0,0 +1,17 @@
+/**
+ * Next.js redirect type discriminator.
+ *
+ * Provided for API compatibility with libraries that import `RedirectType`
+ * from `next/navigation`. In timber, `redirect()` always uses `replace`
+ * semantics (no history entry for the redirect itself).
+ *
+ * Lives in shared/ (isomorphic) so both the server primitives and the
+ * client-only next/navigation shim export the same definition without the
+ * client shim pulling in server code.
+ */
+export const RedirectType = {
+  push: 'push',
+  replace: 'replace',
+} as const;
+
+export type RedirectTypeValue = (typeof RedirectType)[keyof typeof RedirectType];

package/src/shims/headers.ts

@@ -4,10 +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 aliases — libraries importing from 'next/headers' expect these names.
-export { getHeaders as headers, getCookieJar as cookies } 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 };
+  };
+
+  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()` / `permanentRedirect()` / `notFound()` without
+ * pulling server/primitives.ts into the browser bundle.
+ *
+ * Next.js supports calling redirect()/notFound() during client component
+ * render. timber matches that by throwing a plain Error carrying the same
+ * JSON digest the server pipeline attaches to RedirectSignal/DenySignal.
+ * TimberErrorBoundary recognizes the digest and converts it to an SPA
+ * navigation (redirect) or a status-code fallback (notFound), 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,9 +23,12 @@
  * See design/14-ecosystem.md §"next/navigation" for the full shim audit.
  */
 
+import { assertRelativeRedirectPath } from '../shared/href-validation.js';
+import type { RedirectTypeValue } from '../shared/redirect-type.js';
+
 // Hooks — useSegmentParams and useSearchParams import from direct modules
 // since they're no longer in @timber-js/app/client public exports.
-export { useSegmentParams } from '../client/use-segment-params.js';
+export { useSegmentParams, useSegmentParams as useParams } from '../client/use-segment-params.js';
 export { useSearchParams } from '../client/use-search-params.js';
 export {
   usePathname,
@@ -27,32 +37,43 @@ export {
   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;
+// Single source of truth shared with server/primitives.ts.
+export { RedirectType } from '../shared/redirect-type.js';
 
-// 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.'
-  );
+/** 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 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.'
-  );
+/**
+ * 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 });
 }
 
+/**
+ * Client-render permanent redirect. On the client there is no HTTP status —
+ * this behaves identically to redirect() apart from the digest's status.
+ */
+export function permanentRedirect(path: string, _type?: RedirectTypeValue): never {
+  assertRelativeRedirectPath(path);
+  throwSignal(`Redirect to ${path}`, { type: 'redirect', location: path, status: 308 });
+}
+
+/**
+ * Client-render notFound. Throws a deny-digest error (status 404) that the
+ * nearest matching TimberErrorBoundary renders as the 404 fallback. The
+ * message matches DenySignal's so digest-less fallback parsing still works.
+ */
 export function notFound(): never {
-  throw new Error(
-    'notFound() is a server-only function and cannot be called from client components.'
-  );
+  throwSignal('Access denied with status 404', { type: 'deny', status: 404, data: null });
 }

package/LICENSE

@@ -1,8 +0,0 @@
-DONTFUCKINGUSE LICENSE
-
-Copyright (c) 2025 Daniel Saewitz
-
-This software may not be used, copied, modified, merged, published,
-distributed, sublicensed, or sold by anyone other than the copyright holder.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.