@timber-js/app 0.2.0-alpha.71 → 0.2.0-alpha.72

package/src/client/index.ts

@@ -1,57 +1,37 @@
 // @timber-js/app/client — Client-side primitives
 // These are the primary imports for client components.
+//
+// Framework-internal bootstrap, SSR bridge, and segment plumbing is in
+// #client-internal (Node package import).
+// Design doc: design/triage/api-naming-spike.md §8.5
 
-export type { JsonSerializable, RenderErrorDigest } from './types';
+// JsonSerializable moved to @timber-js/app/codec as the single canonical path.
+// Re-export removed per TIM-721.
+export type { RenderErrorDigest } from './types';
 
 // Navigation
 export { Link, interpolateParams, resolveHref, validateLinkHref, buildLinkProps } from './link';
 export { mergePreservedSearchParams } from '../shared/merge-search-params.js';
 export type { LinkFunction, LinkProps, LinkPropsWithHref, LinkPropsWithParams } from './link';
 export type { LinkSegmentParams, OnNavigateHandler, OnNavigateEvent } from './link';
-export { createRouter } from './router';
-export type {
-  RouterInstance,
-  NavigationOptions,
-  RouterDeps,
-  RouterPhase,
-  RscDecoder,
-  RootRenderer,
-} from './router';
-export { useNavigationPending } from './use-navigation-pending';
+export { usePendingNavigation } from './use-pending-navigation';
 export { useLinkStatus, LinkStatusContext } from './use-link-status';
 export type { LinkStatus } from './use-link-status';
-export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref';
 export { useRouter } from './use-router';
 export type { AppRouterInstance } from './use-router';
 export { usePathname } from './use-pathname';
 export { useSearchParams } from './use-search-params';
 export { useSelectedLayoutSegment, useSelectedLayoutSegments } from './use-selected-layout-segment';
 
-// Segment context (internal, used by rsc-entry to inject layout position)
-export { SegmentProvider, useSegmentContext } from './segment-context';
-export type { SegmentContextValue } from './segment-context';
-
-// Segment cache (internal, but exported for advanced use)
-export { SegmentCache, PrefetchCache } from './segment-cache';
-export type { SegmentNode, StateTree } from './segment-cache';
-
-// History (internal, but exported for advanced use)
-export { HistoryStack } from './history';
-export type { HistoryEntry } from './history';
-
 // Forms
 export { useActionState, useFormAction, useFormErrors } from './form';
 export type { UseActionStateFn, UseActionStateReturn, FormErrorsResult } from './form';
 
 // Params
-export { useSegmentParams, setCurrentParams } from './use-params';
-
-// Navigation context (framework-internal, used by browser-entry for atomic updates)
-export { NavigationProvider, getNavigationState, setNavigationState } from './navigation-context';
-export type { NavigationState } from './navigation-context';
+export { useSegmentParams } from './use-params';
 
 // Query states (URL-synced search params)
-export { useQueryStates, bindUseQueryStates } from './use-query-states';
+export { useQueryStates } from './use-query-states';
 
 // Cookies
 export { useCookie } from './use-cookie';
@@ -63,11 +43,3 @@ export type { ClientCookieOptions, CookieSetter } from './use-cookie';
 import * as _useCookieMod from './use-cookie.js';
 import { _registerUseCookieModule } from '../cookies/define-cookie.js';
 _registerUseCookieModule(_useCookieMod);
-
-// SSR data (framework-internal, used by ssr-entry to provide request data to hooks)
-export { setSsrData, clearSsrData, getSsrData } from './ssr-data';
-export type { SsrData } from './ssr-data';
-
-// Error boundary (framework-internal, used by tree-builder and rsc-entry)
-export { TimberErrorBoundary } from './error-boundary';
-export type { TimberErrorBoundaryProps } from './error-boundary';

package/src/client/internal.ts

@@ -0,0 +1,57 @@
+// #client-internal — Framework-internal client exports
+//
+// This module is a Node package import (#client-internal in package.json
+// "imports" field). It is only resolvable from within @timber-js/app —
+// external consumers cannot import it.
+//
+// These exports are consumed by browser-entry, ssr-entry, and build plugins.
+// They are NOT part of the user-facing API and should not appear in
+// documentation or autocomplete for application developers.
+//
+// Design doc: design/triage/api-naming-spike.md §8.5
+
+// ── Bootstrap ────────────────────────────────────────────────────────────
+export { createRouter } from './router.js';
+export type {
+  RouterInstance,
+  NavigationOptions,
+  RouterDeps,
+  RouterPhase,
+  RscDecoder,
+  RootRenderer,
+} from './router.js';
+export { getRouter, getRouterOrNull, setGlobalRouter } from './router-ref.js';
+
+// ── SSR bridge ───────────────────────────────────────────────────────────
+export { setSsrData, clearSsrData, getSsrData } from './ssr-data.js';
+export type { SsrData } from './ssr-data.js';
+
+// ── Segment context ──────────────────────────────────────────────────────
+export { SegmentProvider, useSegmentContext } from './segment-context.js';
+export type { SegmentContextValue } from './segment-context.js';
+
+// ── Segment cache ────────────────────────────────────────────────────────
+export { SegmentCache, PrefetchCache } from './segment-cache.js';
+export type { SegmentNode, StateTree } from './segment-cache.js';
+
+// ── History ──────────────────────────────────────────────────────────────
+export { HistoryStack } from './history.js';
+export type { HistoryEntry } from './history.js';
+
+// ── Params (internal setter) ─────────────────────────────────────────────
+export { setCurrentParams } from './use-params.js';
+
+// ── Navigation context ───────────────────────────────────────────────────
+export {
+  NavigationProvider,
+  getNavigationState,
+  setNavigationState,
+} from './navigation-context.js';
+export type { NavigationState } from './navigation-context.js';
+
+// ── Query states (internal binder) ───────────────────────────────────────
+export { bindUseQueryStates } from './use-query-states.js';
+
+// ── Error boundary ───────────────────────────────────────────────────────
+export { TimberErrorBoundary } from './error-boundary.js';
+export type { TimberErrorBoundaryProps } from './error-boundary.js';

package/src/client/navigation-context.ts

@@ -63,10 +63,14 @@ export interface NavigationState {
  * variables) because the ESM bundler can duplicate this module across
  * chunks. Module-level variables would create separate instances per
  * chunk — the provider in NavigationRoot (index chunk) would use
- * context A while the consumer in useNavigationPending (shared chunk)
+ * context A while the consumer in usePendingNavigation (shared chunk)
  * reads from context B. globalThis guarantees a single instance.
  *
  * See design/27-chunking-strategy.md §"Singleton Safety"
+ *
+ * NOTE: Despite similar naming, `usePendingNavigationUrl()` here is an
+ * internal helper — the public hook is `usePendingNavigation()` in
+ * use-pending-navigation.ts.
  */
 
 // Symbol keys for globalThis storage — prevents collisions with user code
@@ -168,7 +172,7 @@ export function getNavigationState(): NavigationState {
 
 /**
  * Separate context for the in-flight navigation URL. Provided by
- * NavigationRoot (urgent useState), consumed by useNavigationPending
+ * NavigationRoot (urgent useState), consumed by usePendingNavigation
  * and TopLoader. Per-link pending state uses useOptimistic instead
  * (see link-pending-store.ts).
  *

package/src/client/navigation-root.tsx

@@ -195,7 +195,7 @@ export function NavigationRoot({
   // both apply in the same React commit — making the pending→active transition
   // atomic (no frame where pending is false but the old tree is still visible).
   _navigateTransition = (url: string, perform: () => Promise<ReactNode>) => {
-    // Urgent: show pending state immediately (for TopLoader / useNavigationPending)
+    // Urgent: show pending state immediately (for TopLoader / usePendingNavigation)
     setPendingUrl(url);
 
     // Increment the transition counter SYNCHRONOUSLY (before startTransition

package/src/client/router-ref.ts

@@ -18,7 +18,7 @@ export function setGlobalRouter(router: RouterInstance): void {
 
 /**
  * Get the global router instance. Throws if called before bootstrap.
- * Used by client-side hooks (useNavigationPending, etc.)
+ * Used by client-side hooks (usePendingNavigation, etc.)
  */
 export function getRouter(): RouterInstance {
   if (!globalRouter) {

package/src/client/top-loader.tsx

@@ -7,7 +7,7 @@
  *
  * Configuration is via timber.config.ts `topLoader` key. Enabled by default.
  * Users who want a fully custom progress indicator disable the built-in one
- * (`topLoader: { enabled: false }`) and use `useNavigationPending()` directly.
+ * (`topLoader: { enabled: false }`) and use `usePendingNavigation()` directly.
  *
  * Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
  * width over ~30s using ease-out timing. When navigation completes, the bar
@@ -21,7 +21,7 @@
  * stays invisible during the delay period. If navigation finishes before the
  * delay, the bar was never visible so the finish transition is also invisible.
  *
- * See design/19-client-navigation.md §"useNavigationPending()"
+ * See design/19-client-navigation.md §"usePendingNavigation()"
  * See LOCAL-336 for design decisions.
  */
 

package/src/client/use-link-status.ts

@@ -20,7 +20,7 @@ export const LinkStatusContext = createContext<LinkStatus>({ pending: false });
  * Returns `{ pending: true }` while the nearest parent `<Link>` component's
  * navigation is in flight. Must be used inside a `<Link>` component's children.
  *
- * Unlike `useNavigationPending()` which is global, this hook is scoped to
+ * Unlike `usePendingNavigation()` which is global, this hook is scoped to
  * the nearest parent `<Link>` — only the link the user clicked shows pending.
  *
  * ```tsx

package/src/client/{use-navigation-pending.ts → use-pending-navigation.ts}

@@ -1,5 +1,5 @@
-// useNavigationPending — returns true while an RSC navigation is in flight.
-// See design/19-client-navigation.md §"useNavigationPending()"
+// usePendingNavigation — returns true while an RSC navigation is in flight.
+// See design/19-client-navigation.md §"usePendingNavigation()"
 //
 // Reads from PendingNavigationContext (provided by NavigationRoot) so the
 // pending state shows immediately (urgent update) and clears atomically
@@ -19,10 +19,10 @@ import { usePendingNavigationUrl } from './navigation-context.js';
  *
  * ```tsx
  * 'use client'
- * import { useNavigationPending } from '@timber-js/app/client'
+ * import { usePendingNavigation } from '@timber-js/app/client'
  *
  * export function NavBar() {
- *   const isPending = useNavigationPending()
+ *   const isPending = usePendingNavigation()
  *   return (
  *     <nav className={isPending ? 'opacity-50' : ''}>
  *       <Link href="/dashboard">Dashboard</Link>
@@ -31,7 +31,7 @@ import { usePendingNavigationUrl } from './navigation-context.js';
  * }
  * ```
  */
-export function useNavigationPending(): boolean {
+export function usePendingNavigation(): boolean {
   const pendingUrl = usePendingNavigationUrl();
   // During SSR or outside PendingNavigationProvider, no navigation is pending
   return pendingUrl !== null;

package/src/client/use-query-states.ts

@@ -18,7 +18,7 @@ import type {
   SetParams,
   QueryStatesOptions,
 } from '../search-params/define.js';
-import { getSearchParams } from '../search-params/registry.js';
+import { getSearchParamsDefinition } from '../search-params/registry.js';
 
 // ─── Codec Bridge ─────────────────────────────────────────────────
 
@@ -79,7 +79,7 @@ export function useQueryStates<T extends Record<string, unknown>>(
   let codecs: { [K in keyof T]: SearchParamCodec<T[K]> };
   let resolvedUrlKeys = urlKeys;
   if (typeof codecsOrRoute === 'string') {
-    const definition = getSearchParams(codecsOrRoute);
+    const definition = getSearchParamsDefinition(codecsOrRoute);
     if (!definition) {
       throw new Error(
         `useQueryStates('${codecsOrRoute}'): no search params registered for this route. ` +

package/src/client/use-router.ts

@@ -20,7 +20,7 @@
  *
  * For loading UI during navigation, use:
  * - useLinkStatus()          — per-link pending indicator (inside <Link>)
- * - useNavigationPending()   — global navigation pending state
+ * - usePendingNavigation()   — global navigation pending state
  */
 
 import { getRouterOrNull } from './router-ref.js';

package/src/codec.ts

@@ -22,6 +22,21 @@ export interface Codec<T> {
   serialize(value: T): string | null;
 }
 
+/**
+ * Recursive JSON-serializable type. The canonical definition for data that
+ * can safely cross the RSC → client boundary.
+ *
+ * Previously exported from both @timber-js/app/server and @timber-js/app/client.
+ * Moved here so there is exactly one canonical import path.
+ */
+export type JsonSerializable =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonSerializable[]
+  | { [key: string]: JsonSerializable };
+
 // ─── Standard Schema bridge ──────────────────────────────────────────────
 
 export {

package/src/config-types.ts

@@ -0,0 +1,208 @@
+/**
+ * Timber configuration types.
+ *
+ * Extracted to a shared file so both the public entry point (index.ts)
+ * and internal plugin-context.ts can import them without circular deps.
+ */
+
+/** Configuration for client-side JavaScript output. */
+export interface ClientJavascriptConfig {
+  /** When true, no client JS bundles are emitted or referenced in HTML. */
+  disabled: boolean;
+  /**
+   * When `disabled` is true, still inject the Vite HMR client in dev mode
+   * so hot reloading works during development. Default: true.
+   */
+  enableHMRInDev?: boolean;
+}
+
+export interface TimberUserConfig {
+  output?: 'server' | 'static';
+  /**
+   * Enable timber debug logging in production builds.
+   *
+   * When `true`, timber's own diagnostics (dev warnings, verbose logging)
+   * are active even in production mode. React stays in production mode —
+   * only timber's logs are affected.
+   *
+   * Can also be enabled at runtime via the `TIMBER_DEBUG` environment variable.
+   *
+   * Default: `false`.
+   */
+  debug?: boolean;
+  /**
+   * Control client-side JavaScript output.
+   *
+   * Boolean shorthand:
+   *   `clientJavascript: false` disables all client JS (equivalent to `{ disabled: true }`).
+   *   `clientJavascript: true` enables client JS (the default).
+   *
+   * Object form:
+   *   `clientJavascript: { disabled: true, enableHMRInDev: true }` disables client JS
+   *   in production but preserves Vite HMR in dev mode.
+   *
+   * When `disabled` is true, `enableHMRInDev` defaults to `true`.
+   * Server-side JS still runs — this only affects what is sent to the browser.
+   */
+  clientJavascript?: boolean | ClientJavascriptConfig;
+  adapter?: unknown;
+  cacheHandler?: unknown;
+  allowedOrigins?: string[];
+  csrf?: boolean;
+  limits?: {
+    actionBodySize?: string;
+    uploadBodySize?: string;
+    maxFields?: number;
+  };
+  pageExtensions?: string[];
+  /**
+   * Slow request threshold in milliseconds. Requests exceeding this emit
+   * a warning via the logger. Set to 0 to disable. Default: 3000.
+   *
+   * See design/17-logging.md §"slowRequestMs".
+   */
+  slowRequestMs?: number;
+  /**
+   * Render timeout in milliseconds. If an SSR render or RSC stream read
+   * does not complete within this duration, the render is aborted and
+   * the connection is closed. Protects against hung fetches and Suspense
+   * components that never resolve.
+   *
+   * Set to 0 to disable (not recommended in production).
+   * Default: 30000 (30 seconds).
+   *
+   * See design/02-rendering-pipeline.md §"Streaming Constraints".
+   */
+  renderTimeoutMs?: number;
+  /**
+   * Forward browser console output to the server terminal in dev mode.
+   *
+   * Sets the minimum log level to forward:
+   * - `'error'` — only `console.error`
+   * - `'warn'` — `console.error` + `console.warn` (default)
+   * - `'info'` — `console.error` + `console.warn` + `console.info`
+   * - `'none'` — disabled
+   *
+   * Does not intercept `console.log` or `console.debug` (too noisy).
+   * No effect in production builds.
+   *
+   * See TIM-513.
+   */
+  devBrowserLogs?: 'error' | 'warn' | 'info' | 'none';
+  /** Dev-mode options. These have no effect in production builds. */
+  dev?: {
+    /** Threshold in ms to highlight slow phases in dev logging output. Default: 200. */
+    slowPhaseMs?: number;
+  };
+  /**
+   * Control Server-Timing header output.
+   *
+   * - `'detailed'` — per-phase breakdown (proxy, middleware, render). Useful
+   *   for APM / network monitoring. Exposes phase names to clients.
+   * - `'total'` — single `total;dur=N` entry. Safe to expose, gives
+   *   browser DevTools useful timing without internal details.
+   * - `false` — no Server-Timing header at all.
+   *
+   * Default: `'detailed'` in dev, `'total'` in production.
+   *
+   * This is separate from `debug` / `TIMBER_DEBUG` — it's an intentional
+   * decision to expose timing data to clients, not a side effect of debug
+   * logging.
+   */
+  serverTiming?: 'detailed' | 'total' | false;
+  /**
+   * Override the app directory location. By default, timber auto-detects
+   * `app/` at the project root, falling back to `src/app/`.
+   *
+   * Set this to a relative path from the project root (e.g. `'src/app'`)
+   * to use a custom location.
+   */
+  appDir?: string;
+  /** MDX compilation options passed to @mdx-js/rollup. See design/20-content-collections.md. */
+  mdx?: {
+    remarkPlugins?: unknown[];
+    rehypePlugins?: unknown[];
+    recmaPlugins?: unknown[];
+    remarkRehypeOptions?: Record<string, unknown>;
+  };
+  /**
+   * Server action bound args encryption configuration.
+   *
+   * The RSC plugin encrypts closure variables captured by 'use server' functions
+   * using AES-256-GCM so they are opaque and tamper-proof in the Flight payload.
+   * Encryption is always enabled in production.
+   *
+   * The encryption key is auto-generated at build time and embedded in the server bundle,
+   * so all instances running the same build share the same key automatically.
+   * For rolling/blue-green deployments where multiple builds coexist, set
+   * `TIMBER_ACTIONS_ENCRYPTION_KEY` env var to share a key across builds.
+   *
+   * See design/08-forms-and-actions.md §"Security"
+   */
+  actionEncryption?: {
+    /**
+     * Disable encryption in dev mode for easier debugging of bound args.
+     * Has no effect in production — encryption is always enabled.
+     * Default: false (encryption is on in dev too).
+     */
+    disableInDev?: boolean;
+  };
+  /**
+   * Enable the React Compiler (babel-plugin-react-compiler) for automatic
+   * memoization of components and hooks at build time.
+   *
+   * - `true` — enable with default options
+   * - `{ compilationMode, target }` — enable with custom options
+   *   - `compilationMode: 'annotation'` — only compile files with `'use memo'`
+   *   - `target: '18'` — target React 18 (uses react-compiler-runtime package)
+   * - `false` or omitted — disabled (default)
+   *
+   * Uses `@vitejs/plugin-react`'s built-in `reactCompilerPreset`, which:
+   * - Applies Babel only for the compiler pass (OXC handles JSX)
+   * - Automatically scopes to client environment only
+   * - Uses `react/compiler-runtime` built into React 19
+   *
+   * Requires `babel-plugin-react-compiler` as a peer dependency.
+   */
+  reactCompiler?: boolean | { compilationMode?: string; target?: string };
+  /**
+   * Auto-generate sitemap.xml from the route tree.
+   *
+   * When enabled, timber walks the file-system route tree and produces a sitemap
+   * for all discoverable pages. Dynamic routes with `generateStaticParams()` are
+   * enumerated. Routes protected by `access.ts` are excluded by default.
+   *
+   * If a user-authored `sitemap.ts` or `sitemap.xml` exists at the app root,
+   * auto-generation is disabled — the user takes full control.
+   *
+   * Supports automatic pagination (sitemap index) for sites with > 50,000 URLs.
+   *
+   * See design/16-metadata.md §"Auto-generated Sitemap"
+   */
+  sitemap?: {
+    /** Must be explicitly `true` to enable auto-generation. Default: false. */
+    enabled?: boolean;
+    /** Base URL for absolute URLs in the sitemap. Required when enabled. e.g., 'https://example.com' */
+    baseUrl?: string;
+    /** Default `<changefreq>` for all entries. Optional. */
+    defaultChangeFrequency?: string;
+    /** Default `<priority>` for all entries (0.0–1.0). Optional. */
+    defaultPriority?: number;
+    /** Include routes protected by `access.ts`. Default: false. */
+    includeProtected?: boolean;
+  };
+  topLoader?: {
+    /** Whether the top-loader is enabled. Default: true. */
+    enabled?: boolean;
+    /** Bar color. Default: '#2299DD'. */
+    color?: string;
+    /** Bar height in pixels. Default: 3. */
+    height?: number;
+    /** Show subtle glow/shadow effect. Default: true. */
+    shadow?: boolean;
+    /** Delay in ms before showing the bar (avoids flash on fast navs). Default: 0. */
+    delay?: number;
+    /** CSS z-index. Default: 1600. */
+    zIndex?: number;
+  };
+}

package/src/content/index.ts

@@ -1,13 +1,5 @@
-/**
- * @timber-js/app/content — Public API for content collections.
- *
- * Re-exports from content-collections and provides timber-specific utilities.
- * Users can import directly from 'content-collections' for generated types,
- * or use this module for the re-exports.
- *
- * Design doc: 20-content-collections.md §"Querying Collections"
- */
-
-// Re-export defineCollection and defineConfig for convenience.
-// Users can also import these directly from @content-collections/core.
-export { defineCollection, defineConfig } from '@content-collections/core';
+// @timber-js/app/content entry point removed per TIM-722.
+//
+// Import defineCollection and defineConfig directly from @content-collections/core.
+// This file is kept for the content plugin which uses other files in this directory.
+export {};

package/src/cookies/define-cookie.ts

@@ -130,28 +130,30 @@ export function defineCookie<T>(
     codec,
 
     async getCookie(): Promise<T> {
-      const { cookies } = await import('../server/request-context.js');
-      const jar = cookies();
+      const { getCookies } = await import('../server/request-context.js');
+      const jar = await getCookies();
       const raw = jar.get(name);
       return codec.parse(raw);
     },
 
     async setCookie(value: T): Promise<void> {
-      const { cookies } = await import('../server/request-context.js');
+      const { getCookies } = await import('../server/request-context.js');
+      const jar = await getCookies();
       const serialized = codec.serialize(value);
       if (serialized === null) {
-        cookies().delete(name, {
+        jar.delete(name, {
           path: resolvedOptions.path,
           domain: resolvedOptions.domain,
         });
       } else {
-        cookies().set(name, serialized, resolvedOptions);
+        jar.set(name, serialized, resolvedOptions);
       }
     },
 
     async deleteCookie(): Promise<void> {
-      const { cookies } = await import('../server/request-context.js');
-      cookies().delete(name, {
+      const { getCookies } = await import('../server/request-context.js');
+      const jar = await getCookies();
+      jar.delete(name, {
         path: resolvedOptions.path,
         domain: resolvedOptions.domain,
       });

package/src/cookies/index.ts

@@ -4,9 +4,10 @@
 export { defineCookie } from './define-cookie.js';
 export type { CookieDefinition, CookieCodec, DefineCookieOptions } from './define-cookie.js';
 
-// Codec protocol
-export type { Codec } from '../codec.js';
+// Codec is the canonical home for the Codec type — import from
+// @timber-js/app/codec. Re-export removed per TIM-721.
 
-// Re-export cookies() so there's one import path for all cookie concerns.
-// cookies() is also available from @timber-js/app/server.
-export { cookies } from '../server/request-context.js';
+// cookies() is a server-only function (requires AsyncLocalStorage) and is
+// exported from @timber-js/app/server. It is intentionally NOT re-exported
+// here so that client-side code importing defineCookie doesn't pull in
+// server ALS code. See TIM-704.