@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.90

package/src/client/link-status-provider.tsx

@@ -1,30 +0,0 @@
-'use client';
-
-// LinkStatusProvider — client component that provides per-link pending status
-// via React context. Used inside <Link> to power useLinkStatus().
-//
-// Reads pendingUrl from PendingNavigationContext (provided by TransitionRoot).
-// The pending URL is set as an URGENT update at navigation start (shows
-// immediately) and cleared inside startTransition when the new tree commits
-// (atomic with params/pathname). This eliminates both:
-// 1. The delay before showing the spinner (urgent update, not deferred)
-// 2. The gap between spinner disappearing and active state updating (same commit)
-
-import type { ReactNode } from 'react';
-import { LinkStatusContext, type LinkStatus } from './use-link-status.js';
-import { usePendingNavigationUrl } from './navigation-context.js';
-
-const NOT_PENDING: LinkStatus = { pending: false };
-const IS_PENDING: LinkStatus = { pending: true };
-
-/**
- * Client component that reads the pending URL from PendingNavigationContext
- * and provides a scoped LinkStatusContext to children. Renders no extra DOM —
- * just a context provider around children.
- */
-export function LinkStatusProvider({ href, children }: { href: string; children?: ReactNode }) {
-  const pendingUrl = usePendingNavigationUrl();
-  const status = pendingUrl === href ? IS_PENDING : NOT_PENDING;
-
-  return <LinkStatusContext.Provider value={status}>{children}</LinkStatusContext.Provider>;
-}

package/src/client/transition-root.tsx

@@ -1,166 +0,0 @@
-/**
- * TransitionRoot — Wrapper component for transition-based rendering.
- *
- * Solves the "new boundary has no old content" problem for client-side
- * navigation. When React renders a completely new Suspense boundary via
- * root.render(), it shows the fallback immediately — root.render() is
- * always an urgent update regardless of startTransition.
- *
- * TransitionRoot holds the current element in React state. Navigation
- * updates call startTransition(() => setState(newElement)), which IS
- * a transition update. React keeps the old committed tree visible while
- * any new Suspense boundaries in the transition resolve.
- *
- * Also manages `pendingUrl` as React state with an urgent/transition split:
- * - Navigation START: `setPendingUrl(url)` is an urgent update — React
- *   commits it before the next paint, showing the spinner immediately.
- * - Navigation END: `setPendingUrl(null)` is inside `startTransition`
- *   alongside `setElement(newTree)` — both commit atomically, so the
- *   spinner disappears in the same frame as the new content appears.
- *
- * See design/05-streaming.md §"deferSuspenseFor"
- * See design/19-client-navigation.md §"NavigationContext"
- */
-
-import { useState, useTransition, createElement, Fragment, type ReactNode } from 'react';
-import { PendingNavigationProvider } from './navigation-context.js';
-import { TopLoader, type TopLoaderConfig } from './top-loader.js';
-
-// ─── Module-level functions ──────────────────────────────────────
-
-/**
- * Module-level reference to the state setter wrapped in startTransition.
- * Used for non-navigation renders (applyRevalidation, popstate replay).
- */
-let _transitionRender: ((element: ReactNode) => void) | null = null;
-
-/**
- * Module-level reference to the navigation transition function.
- * Wraps a full navigation (fetch + render) in a single startTransition
- * with useOptimistic for the pending URL.
- */
-let _navigateTransition:
-  | ((pendingUrl: string, perform: () => Promise<ReactNode>) => Promise<void>)
-  | null = null;
-
-// ─── Component ───────────────────────────────────────────────────
-
-/**
- * Root wrapper component that enables transition-based rendering.
- *
- * Renders PendingNavigationProvider around children for the pending URL
- * context. The DOM tree matches the server-rendered HTML during hydration
- * (the provider renders no extra DOM elements).
- *
- * Usage in browser-entry.ts:
- *   const rootEl = createElement(TransitionRoot, { initial: wrapped });
- *   reactRoot = hydrateRoot(document, rootEl);
- *
- * Subsequent navigations:
- *   navigateTransition(url, async () => { fetch; return wrappedElement; });
- *
- * Non-navigation renders:
- *   transitionRender(newWrappedElement);
- */
-export function TransitionRoot({
-  initial,
-  topLoaderConfig,
-}: {
-  initial: ReactNode;
-  topLoaderConfig?: TopLoaderConfig;
-}): ReactNode {
-  const [element, setElement] = useState<ReactNode>(initial);
-  const [pendingUrl, setPendingUrl] = useState<string | null>(null);
-  const [, startTransition] = useTransition();
-
-  // Non-navigation render (revalidation, popstate cached replay).
-  _transitionRender = (newElement: ReactNode) => {
-    startTransition(() => {
-      setElement(newElement);
-    });
-  };
-
-  // Full navigation transition.
-  // setPendingUrl(url) is an URGENT update — React commits it before the next
-  // paint, so the pending spinner appears immediately when navigation starts.
-  // Inside startTransition: the async fetch + setElement + setPendingUrl(null)
-  // are deferred. When the transition commits, the new tree and pendingUrl=null
-  // 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
-    setPendingUrl(url);
-
-    return new Promise<void>((resolve, reject) => {
-      startTransition(async () => {
-        try {
-          const newElement = await perform();
-          setElement(newElement);
-          // Clear pending inside the transition — commits atomically with new tree
-          setPendingUrl(null);
-          resolve();
-        } catch (err) {
-          // Clear pending on error too
-          setPendingUrl(null);
-          reject(err);
-        }
-      });
-    });
-  };
-
-  // Inject TopLoader alongside the element tree inside PendingNavigationProvider.
-  // The TopLoader reads pendingUrl from context to show/hide the progress bar.
-  // It is rendered only when not explicitly disabled via config.
-  const showTopLoader = topLoaderConfig?.enabled !== false;
-  const children = showTopLoader
-    ? createElement(Fragment, null, createElement(TopLoader, { config: topLoaderConfig }), element)
-    : element;
-  return createElement(PendingNavigationProvider, { value: pendingUrl }, children);
-}
-
-// ─── Public API ──────────────────────────────────────────────────
-
-/**
- * Trigger a transition render for non-navigation updates.
- * React keeps the old committed tree visible while any new Suspense
- * boundaries in the update resolve.
- *
- * Used for: applyRevalidation, popstate replay with cached payload.
- */
-export function transitionRender(element: ReactNode): void {
-  if (_transitionRender) {
-    _transitionRender(element);
-  }
-}
-
-/**
- * Run a full navigation inside a React transition with optimistic pending URL.
- *
- * The `perform` callback runs inside `startTransition` — it should fetch the
- * RSC payload, update router state, and return the wrapped React element.
- * The pending URL shows immediately (useOptimistic urgent update) and reverts
- * to null when the transition commits (atomic with the new tree).
- *
- * Returns a Promise that resolves when the async work completes (note: the
- * React transition may not have committed yet, but all state updates are done).
- *
- * Used for: navigate(), refresh(), popstate with fetch.
- */
-export function navigateTransition(
-  pendingUrl: string,
-  perform: () => Promise<ReactNode>
-): Promise<void> {
-  if (_navigateTransition) {
-    return _navigateTransition(pendingUrl, perform);
-  }
-  // Fallback: no TransitionRoot mounted (shouldn't happen in production)
-  return perform().then(() => {});
-}
-
-/**
- * Check if the TransitionRoot is mounted and ready for renders.
- * Used by browser-entry.ts to guard against renders before hydration.
- */
-export function isTransitionRootReady(): boolean {
-  return _transitionRender !== null;
-}

package/src/plugins/cache-transform.ts

@@ -1,199 +0,0 @@
-import type { Plugin } from 'vite';
-import { findFunctionsWithDirective, containsDirective } from '#/utils/directive-parser.js';
-
-/**
- * Parse a cacheLife duration string to seconds.
- * Supports: '30s', '5m', '1h', '2d', '1w', or a plain number (seconds).
- */
-export function parseCacheLife(value: string | number): number {
-  if (typeof value === 'number') return value;
-
-  const match = value.match(/^(\d+)(s|m|h|d|w)$/);
-  if (!match) {
-    throw new Error(
-      `Invalid cacheLife value: "${value}". Expected format: "30s", "5m", "1h", "2d", "1w", or a number.`
-    );
-  }
-
-  const amount = parseInt(match[1], 10);
-  const unit = match[2];
-  const multipliers: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 };
-  return amount * multipliers[unit];
-}
-
-// Default TTL when no cacheLife() is specified (Infinity means cache until explicit invalidation).
-const DEFAULT_TTL = Infinity;
-
-export interface CacheTransformWarning {
-  message: string;
-  functionName: string;
-}
-
-interface TransformResult {
-  code: string;
-  map?: null;
-  warnings?: CacheTransformWarning[];
-}
-
-/**
- * Match cacheLife() calls: cacheLife('1h'), cacheLife("5m"), cacheLife(300)
- */
-const CACHE_LIFE_PATTERN = /cacheLife\(\s*(?:'([^']+)'|"([^"]+)"|(\d+))\s*\)/;
-
-/**
- * Strip the 'use cache' directive and cacheLife() call from a function body.
- * Returns the cleaned body and the extracted TTL.
- */
-function extractCacheDirectives(body: string): { cleanBody: string; ttl: number } {
-  let ttl = DEFAULT_TTL;
-
-  // Remove 'use cache' / "use cache" directive (including optional semicolon and newline)
-  let cleanBody = body.replace(/\s*['"]use cache['"];?\s*\n?/, '\n');
-
-  // Extract and remove cacheLife() calls
-  const lifeMatch = cleanBody.match(CACHE_LIFE_PATTERN);
-  if (lifeMatch) {
-    const value = lifeMatch[1] || lifeMatch[2] || parseInt(lifeMatch[3], 10);
-    ttl = parseCacheLife(value);
-    cleanBody = cleanBody.replace(/\s*cacheLife\([^)]*\);?\s*\n?/, '\n');
-  }
-
-  return { cleanBody, ttl };
-}
-
-/**
- * Determine if a function name is a React component (PascalCase).
- */
-function isComponentName(name: string): boolean {
-  return /^[A-Z]/.test(name);
-}
-
-/**
- * Pattern matching page/layout file conventions in a dynamic route segment.
- * Matches paths like: app/[slug]/page.tsx, app/[id]/layout.ts, etc.
- */
-const DYNAMIC_ROUTE_PAGE_PATTERN = /\/\[[^\]]+\].*\/(page|layout)\.[jt]sx?$/;
-
-/**
- * Detect if a function declaration has Promise-typed parameters.
- *
- * Checks for common patterns:
- * - `params: Promise<...>`
- * - `{ params }: { params: Promise<...> }`
- * - `props: { params: Promise<...> }`
- */
-const PROMISE_PARAMS_PATTERN = /params\s*(?::|.*?:)\s*Promise\s*</;
-
-/**
- * Check if a 'use cache' function in a dynamic route page/layout receives
- * Promise-typed params, which are not serializable as cache keys.
- */
-export function detectPromiseParamsWarning(
-  declaration: string,
-  functionName: string,
-  fileId: string
-): CacheTransformWarning | null {
-  if (!DYNAMIC_ROUTE_PAGE_PATTERN.test(fileId)) return null;
-  if (!PROMISE_PARAMS_PATTERN.test(declaration)) return null;
-
-  return {
-    message:
-      `'use cache' on "${functionName}" in "${fileId}" receives Promise params. ` +
-      `Promise is not serializable as a cache key and will cause runtime errors. ` +
-      `Either remove 'use cache' or await the params before using them in a separate cached function.`,
-    functionName,
-  };
-}
-
-/**
- * Transform source code containing 'use cache' directives into
- * registerCachedFunction() calls.
- *
- * Returns null if no transformations were made.
- */
-export function transformUseCache(code: string, fileId: string): TransformResult | null {
-  if (!containsDirective(code, 'use cache')) return null;
-
-  const functions = findFunctionsWithDirective(code, 'use cache');
-  if (functions.length === 0) return null;
-
-  let result = code;
-  let needsImport = false;
-  const warnings: CacheTransformWarning[] = [];
-
-  // Process functions from end to start (sorted descending by start position)
-  for (const fn of functions) {
-    // Warn if function receives Promise params in a dynamic route page/layout
-    const promiseWarning = detectPromiseParamsWarning(fn.declaration, fn.name, fileId);
-    if (promiseWarning) warnings.push(promiseWarning);
-    const { cleanBody, ttl } = extractCacheDirectives(fn.bodyContent);
-    const stableId = `${fileId}#${fn.name}`;
-    const isComponent = isComponentName(fn.name);
-
-    // Build the options object
-    const optsParts = [`ttl: ${ttl === Infinity ? 'Infinity' : ttl}`];
-    optsParts.push(`id: '${stableId}'`);
-    if (isComponent) {
-      optsParts.push('isComponent: true');
-    }
-    const optsStr = `{ ${optsParts.join(', ')} }`;
-
-    // Build the replacement
-    let replacement: string;
-    if (fn.isArrow) {
-      // const Name = async (...) => { body } → const Name = registerCachedFunction(async (...) => { body }, opts)
-      const arrowSig = fn.declaration.replace(/^(?:const|let|var)\s+\w+\s*=\s*/, '');
-      replacement = `const ${fn.name} = registerCachedFunction(${arrowSig} {${cleanBody}}, ${optsStr})`;
-    } else {
-      // async function Name(...) { body } → const Name = registerCachedFunction(async function Name(...) { body }, opts)
-      const fnDecl = fn.declaration.replace(/^(?:export\s+default\s+|export\s+)?/, '');
-      const exportPrefix = fn.prefix.includes('default')
-        ? 'export default '
-        : fn.prefix.includes('export')
-          ? 'export '
-          : '';
-
-      replacement = `${exportPrefix}const ${fn.name} = registerCachedFunction(${fnDecl} {${cleanBody}}, ${optsStr})`;
-    }
-
-    result = result.slice(0, fn.start) + replacement + result.slice(fn.end);
-    needsImport = true;
-  }
-
-  if (needsImport) {
-    // Add the import at the top of the file
-    result = `import { registerCachedFunction } from '@timber-js/app/cache';\n` + result;
-  }
-
-  return { code: result, map: null, warnings: warnings.length > 0 ? warnings : undefined };
-}
-
-/**
- * Vite plugin: timber-cache
- *
- * Transforms 'use cache' directives into registerCachedFunction() calls.
- * Only runs in the RSC environment.
- */
-export function cacheTransformPlugin(): Plugin {
-  return {
-    name: 'timber-cache',
-
-    transform(code, id) {
-      // Only transform in RSC environment
-      // Skip node_modules and non-JS/TS files
-      if (id.includes('node_modules')) return null;
-      if (!/\.[jt]sx?$/.test(id)) return null;
-
-      // Quick bail-out: no 'use cache' directive in this file
-      if (!containsDirective(code, 'use cache')) return null;
-
-      const result = transformUseCache(code, id);
-      if (result?.warnings) {
-        for (const w of result.warnings) {
-          this.warn(`[timber] ${w.message}`);
-        }
-      }
-      return result;
-    },
-  };
-}

package/src/plugins/dynamic-transform.ts

@@ -1,161 +0,0 @@
-/**
- * timber-dynamic-transform — Vite sub-plugin for 'use dynamic' directive.
- *
- * Detects `'use dynamic'` directives in server component function bodies
- * and transforms them into `markDynamic()` runtime calls. The directive
- * declares a dynamic boundary — the component and its subtree opt out of
- * the pre-rendered shell and render per-request.
- *
- * - In `output: 'static'` mode, `'use dynamic'` is a build error.
- * - In standard SSR routes (no prerender.ts), the directive is a no-op
- *   (everything is already per-request), but the transform still runs
- *   so the runtime can skip unnecessary work.
- *
- * Design doc: design/15-future-prerendering.md §"'use dynamic'"
- */
-
-import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import { findFunctionsWithDirective, containsDirective } from '#/utils/directive-parser.js';
-
-// ---------------------------------------------------------------------------
-// Detection
-// ---------------------------------------------------------------------------
-
-/**
- * Quick check: does this source file contain 'use dynamic' anywhere?
- * Used as a fast bail-out before doing expensive AST parsing.
- */
-export function containsUseDynamic(code: string): boolean {
-  return containsDirective(code, 'use dynamic');
-}
-
-// ---------------------------------------------------------------------------
-// Transform
-// ---------------------------------------------------------------------------
-
-interface TransformResult {
-  code: string;
-  map?: null;
-}
-
-/**
- * Find function declarations/expressions containing 'use dynamic' and
- * transform them into markDynamic() calls.
- *
- * Input:
- * ```tsx
- * export default async function AddToCartButton({ productId }) {
- *   'use dynamic'
- *   const user = await getUser()
- *   return <button>Add to cart</button>
- * }
- * ```
- *
- * Output:
- * ```tsx
- * import { markDynamic as __markDynamic } from '@timber-js/app/runtime';
- * export default async function AddToCartButton({ productId }) {
- *   __markDynamic();
- *   const user = await getUser()
- *   return <button>Add to cart</button>
- * }
- * ```
- *
- * The markDynamic() call registers the component boundary as dynamic
- * at render time. The pre-render pass uses this to know which subtrees
- * to skip and leave as holes for per-request rendering.
- */
-export function transformUseDynamic(code: string): TransformResult | null {
-  if (!containsUseDynamic(code)) return null;
-
-  const functions = findFunctionsWithDirective(code, 'use dynamic');
-  if (functions.length === 0) return null;
-
-  // Replace directive strings with __markDynamic() calls, processing
-  // from end to start to preserve source offsets
-  let result = code;
-  for (const fn of functions) {
-    // Replace the directive in the body content
-    const cleanBody = fn.bodyContent.replace(/['"]use dynamic['"];?/, '__markDynamic();');
-    // Reconstruct: replace the body content between braces
-    result = result.slice(0, fn.bodyStart) + cleanBody + result.slice(fn.bodyEnd);
-  }
-
-  // Add the import at the top
-  result = `import { markDynamic as __markDynamic } from '@timber-js/app/runtime';\n` + result;
-
-  return { code: result, map: null };
-}
-
-// ---------------------------------------------------------------------------
-// Static mode validation
-// ---------------------------------------------------------------------------
-
-/**
- * In `output: 'static'` mode, `'use dynamic'` is a build error.
- * Static mode renders everything at build time — there is no per-request
- * rendering to opt into.
- */
-export function validateNoDynamicInStaticMode(
-  code: string
-): { message: string; line?: number } | null {
-  if (!containsUseDynamic(code)) return null;
-
-  const functions = findFunctionsWithDirective(code, 'use dynamic');
-  if (functions.length === 0) return null;
-
-  return {
-    message:
-      `'use dynamic' cannot be used in static mode (output: 'static'). ` +
-      `Static mode renders all content at build time — there is no per-request rendering. ` +
-      `Remove the directive or switch to output: 'server'.`,
-    line: functions[functions.length - 1].directiveLine, // First occurrence (sorted descending)
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Vite Plugin
-// ---------------------------------------------------------------------------
-
-/**
- * Create the timber-dynamic-transform Vite plugin.
- *
- * In server mode: transforms 'use dynamic' into markDynamic() calls.
- * In static mode: rejects 'use dynamic' as a build error.
- */
-export function timberDynamicTransform(ctx: PluginContext): Plugin {
-  const isStatic = ctx.config.output === 'static';
-
-  return {
-    name: 'timber-dynamic-transform',
-
-    transform(code: string, id: string) {
-      // Skip node_modules
-      if (id.includes('node_modules')) return null;
-
-      // Only check files in the app directory
-      if (!id.includes('/app/') && !id.startsWith('app/')) return null;
-
-      // Only check JS/TS files
-      if (!/\.[jt]sx?$/.test(id)) return null;
-
-      // Quick bail-out
-      if (!containsUseDynamic(code)) return null;
-
-      // In static mode, 'use dynamic' is a build error
-      if (isStatic) {
-        const error = validateNoDynamicInStaticMode(code);
-        if (error) {
-          this.error(
-            `[timber] Static mode error in ${id}${error.line ? `:${error.line}` : ''}: ${error.message}`
-          );
-        }
-        return null;
-      }
-
-      // In server mode, transform the directive
-      return transformUseDynamic(code);
-    },
-  };
-}