@timber-js/app 0.1.55 → 0.1.57

package/dist/plugins/chunks.d.ts

@@ -1,56 +1,37 @@
 /**
- * timber-chunks — Vite sub-plugin for intelligent client chunk splitting.
+ * timber-chunks — Vite sub-plugin for client chunk configuration.
  *
- * Splits client bundles into cache tiers based on update frequency:
+ * Previously implemented a 5-tier cache strategy (vendor-react, vendor-timber,
+ * vendor-app, shared-app, shared-client) via manualChunks. This was removed
+ * in LOCAL-337 because the cache-tier separation added HTTP requests,
+ * complicated the architecture, and caused module duplication across chunks
+ * that required globalThis + Symbol.for workarounds.
  *
- * Tier 1: vendor-react    — react, react-dom, scheduler (changes rarely)
- * Tier 2: vendor-timber   — timber runtime, RSC runtime (changes per framework update)
- * Tier 3: vendor-app      — user node_modules (changes on dependency updates)
- * Tier 4: shared-app      — small shared app utilities/components (< 5KB source)
- * Tier 5: [route]-*       — per-route page/layout chunks (default Rollup splitting)
- *
- * The shared-app tier prevents tiny utility modules (constants, helpers,
- * small UI components) from becoming individual chunks when shared across
- * routes. Without this, Rolldown creates per-module chunks for any code
- * shared between two or more entry points, producing many sub-1KB chunks.
- *
- * Server environments (RSC, SSR) are left to Vite's default chunking since
- * Cloudflare Workers load all code from a single deployment bundle with no
- * benefit from cache-tier separation.
+ * Current strategy: let Rolldown handle natural code splitting.
+ * Output is typically:
+ *   - 1 main bundle (React + timber runtime + shared app code + user vendors)
+ *   - Per-route chunks (page/layout components, only when route-specific)
+ *   - rolldown-runtime (Rolldown's own output, unavoidable)
  *
  * Design docs: 27-chunking-strategy.md
  */
 import type { Plugin } from 'vite';
 /**
- * Categorize a module ID into a cache tier chunk name.
- *
- * Returns a chunk name for vendor modules and small shared app code,
- * or undefined to let Rollup's default splitting handle route code.
- */
-export declare function assignChunk(id: string): string | undefined;
-/**
- * Group timber's internal 'use client' modules into the vendor-timber chunk.
+ * Check if a module is part of the timber framework runtime.
  *
- * The RSC plugin creates separate entry points for each 'use client' module,
- * which manualChunks can't merge. This function is passed as the RSC plugin's
- * `clientChunks` callback to group timber internals into a single chunk.
+ * Matches both monorepo paths (packages/timber-app/...) and consumer
+ * project paths (node_modules/@timber-js/app/...) so identification
+ * is consistent regardless of how timber is installed.
  *
- * User client components that are small (< 5KB) are grouped into shared-client
- * to prevent thin facade wrappers from becoming individual chunks. This handles
- * the RSC client reference facade problem where each 'use client' module gets
- * a ~100-300 byte re-export wrapper chunk.
+ * Exported for use in tests (singleton-audit, etc.).
  */
-export declare function assignClientChunk(meta: {
-    id: string;
-    normalizedId: string;
-    serverChunk: string;
-}): string | undefined;
+export declare function isTimberRuntime(id: string): boolean;
 /**
  * Create the timber-chunks Vite plugin.
  *
- * Uses Vite's per-environment config to apply manualChunks only to
- * the client build. The config hook runs before environments are
- * created, so we use `environments.client` to target the client.
+ * Currently a no-op — Rolldown's default splitting produces the desired
+ * output (one main bundle + per-route chunks). The plugin is retained as
+ * a hook point for future chunking adjustments if needed.
  */
 export declare function timberChunks(): Plugin;
 //# sourceMappingURL=chunks.d.ts.map

package/dist/plugins/chunks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/plugins/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAwGnC;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA4B1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,GAAG,SAAS,CAerB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAoBrC"}
+{"version":3,"file":"chunks.d.ts","sourceRoot":"","sources":["../../src/plugins/chunks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAEnC;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAIrC"}

package/dist/plugins/entries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../src/plugins/entries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAInC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAyHhD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAwBxF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwExD"}
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../src/plugins/entries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAInC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA0HhD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAwBxF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAwExD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.55",
+  "version": "0.1.57",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/client/browser-entry.ts

@@ -381,7 +381,7 @@ function bootstrap(runtimeConfig: typeof config): void {
       element as React.ReactNode
     );
     const wrapped = createElement(TimberNuqsAdapter, null, withNav);
-    const rootElement = createElement(TransitionRoot, { initial: wrapped });
+    const rootElement = createElement(TransitionRoot, { initial: wrapped, topLoaderConfig: _config.topLoader });
     _reactRoot = hydrateRoot(document, rootElement, {
       // Suppress recoverable hydration errors from deny/error signals
       // inside Suspense boundaries. The server already handled these

package/src/client/navigation-context.ts

@@ -25,6 +25,11 @@
  * that depend on these APIs are safe to call from any environment —
  * they return null or no-op when the APIs aren't available.
  *
+ * Singleton guarantee: With the simplified chunking strategy (LOCAL-337),
+ * this module lives in exactly one client chunk. The previous globalThis +
+ * Symbol.for workaround for cross-chunk duplication is no longer needed.
+ * See design/27-chunking-strategy.md.
+ *
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
@@ -47,33 +52,17 @@ export interface NavigationState {
  * The context is created lazily to avoid calling createContext at module
  * level. In the RSC environment, React.createContext doesn't exist —
  * calling it at import time would crash the server.
- *
- * IMPORTANT: Context instances are stored on globalThis, NOT in module-
- * level variables. The RSC client bundler duplicates this module across
- * the browser-entry chunk (index) and client-reference chunk (shared-app)
- * because both entry graphs import it. Module-level variables would create
- * separate singleton instances per chunk — the provider in TransitionRoot
- * (index chunk) would use context A while the consumer in LinkStatusProvider
- * (shared-app chunk) reads from context B. globalThis guarantees a single
- * instance regardless of how many times the module is duplicated.
- *
- * See design/19-client-navigation.md §"Singleton Context Guarantee"
  */
 
-// Symbol keys for globalThis storage — prevents collisions with user code
-const NAV_CTX_KEY = Symbol.for('__timber_nav_ctx');
-const PENDING_CTX_KEY = Symbol.for('__timber_pending_nav_ctx');
+let _navCtx: React.Context<NavigationState | null> | undefined;
+let _pendingNavCtx: React.Context<string | null> | undefined;
 
 function getOrCreateContext(): React.Context<NavigationState | null> | undefined {
-  const existing = (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] as
-    | React.Context<NavigationState | null>
-    | undefined;
-  if (existing !== undefined) return existing;
+  if (_navCtx !== undefined) return _navCtx;
   // createContext may not exist in the RSC environment
   if (typeof React.createContext === 'function') {
-    const ctx = React.createContext<NavigationState | null>(null);
-    (globalThis as Record<symbol, unknown>)[NAV_CTX_KEY] = ctx;
-    return ctx;
+    _navCtx = React.createContext<NavigationState | null>(null);
+    return _navCtx;
   }
   return undefined;
 }
@@ -130,27 +119,15 @@ export function NavigationProvider({
  * NavigationProvider with the correct params/pathname.
  *
  * This is NOT used by hooks directly — hooks read from React context.
- *
- * Stored on globalThis (like the context instances above) because the
- * router lives in the shared-app chunk while renderRoot lives in the
- * index chunk. Module-level variables would be separate per chunk.
  */
-const NAV_STATE_KEY = Symbol.for('__timber_nav_state');
-
-function _getNavStateStore(): { current: NavigationState } {
-  const g = globalThis as Record<symbol, unknown>;
-  if (!g[NAV_STATE_KEY]) {
-    g[NAV_STATE_KEY] = { current: { params: {}, pathname: '/' } };
-  }
-  return g[NAV_STATE_KEY] as { current: NavigationState };
-}
+let _navState: NavigationState = { params: {}, pathname: '/' };
 
 export function setNavigationState(state: NavigationState): void {
-  _getNavStateStore().current = state;
+  _navState = state;
 }
 
 export function getNavigationState(): NavigationState {
-  return _getNavStateStore().current;
+  return _navState;
 }
 
 // ---------------------------------------------------------------------------
@@ -161,21 +138,13 @@ export function getNavigationState(): NavigationState {
  * Separate context for the in-flight navigation URL. Provided by
  * TransitionRoot (urgent useState), consumed by LinkStatusProvider
  * and useNavigationPending.
- *
- * Uses globalThis via Symbol.for for the same reason as NavigationContext
- * above — the bundler duplicates this module across chunks, and module-
- * level variables would create separate context instances.
  */
 
 function getOrCreatePendingContext(): React.Context<string | null> | undefined {
-  const existing = (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] as
-    | React.Context<string | null>
-    | undefined;
-  if (existing !== undefined) return existing;
+  if (_pendingNavCtx !== undefined) return _pendingNavCtx;
   if (typeof React.createContext === 'function') {
-    const ctx = React.createContext<string | null>(null);
-    (globalThis as Record<symbol, unknown>)[PENDING_CTX_KEY] = ctx;
-    return ctx;
+    _pendingNavCtx = React.createContext<string | null>(null);
+    return _pendingNavCtx;
   }
   return undefined;
 }

package/src/client/top-loader.tsx

@@ -0,0 +1,196 @@
+/**
+ * TopLoader — Built-in progress bar for client navigations.
+ *
+ * Shows an animated progress bar at the top of the viewport while an RSC
+ * navigation is in flight. Injected automatically by the framework into
+ * TransitionRoot — users never render this component directly.
+ *
+ * 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.
+ *
+ * Animation approach: pure CSS @keyframes. The bar crawls from 0% to ~90%
+ * width over ~30s using ease-out timing. When navigation completes, the bar
+ * snaps to 100% and fades out over 200ms. No JS animation loops (RAF, setInterval).
+ *
+ * Phase transitions are derived synchronously during render (React's
+ * getDerivedStateFromProps pattern) — no useEffect needed for state tracking.
+ * The finishing → hidden cleanup uses onTransitionEnd from the CSS transition.
+ *
+ * When delay > 0, CSS animation-delay + a visibility keyframe ensure the bar
+ * 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 LOCAL-336 for design decisions.
+ */
+
+'use client';
+
+import { useState, createElement } from 'react';
+import { usePendingNavigationUrl } from './navigation-context.js';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+export interface TopLoaderConfig {
+  /** 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. Default: 0. */
+  delay?: number;
+  /** CSS z-index. Default: 1600. */
+  zIndex?: number;
+}
+
+// ─── Defaults ────────────────────────────────────────────────────
+
+const DEFAULT_COLOR = '#2299DD';
+const DEFAULT_HEIGHT = 3;
+const DEFAULT_SHADOW = true;
+const DEFAULT_DELAY = 0;
+const DEFAULT_Z_INDEX = 1600;
+
+// ─── Keyframes ───────────────────────────────────────────────────
+
+// Unique keyframes name to avoid collisions with user styles.
+const CRAWL_KEYFRAMES = '__timber_top_loader_crawl';
+const APPEAR_KEYFRAMES = '__timber_top_loader_appear';
+
+// Track whether the @keyframes rules have been injected into the document.
+let keyframesInjected = false;
+
+/**
+ * Inject the @keyframes rules into the document head once.
+ * Called during render (idempotent). Uses a <style> tag so the
+ * animations are available for inline-styled elements.
+ */
+function ensureKeyframes(): void {
+  if (keyframesInjected) return;
+  if (typeof document === 'undefined') return;
+
+  const style = document.createElement('style');
+  style.textContent = `
+@keyframes ${CRAWL_KEYFRAMES} {
+  0% { width: 0%; }
+  100% { width: 90%; }
+}
+@keyframes ${APPEAR_KEYFRAMES} {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+`;
+  document.head.appendChild(style);
+  keyframesInjected = true;
+}
+
+// ─── Component ───────────────────────────────────────────────────
+
+/**
+ * Internal top-loader component. Injected by TransitionRoot.
+ *
+ * Reads pending navigation state from PendingNavigationContext.
+ * Phase transitions are derived synchronously during render:
+ *
+ *   hidden → crawling:   when isPending becomes true
+ *   crawling → finishing: when isPending becomes false
+ *   finishing → hidden:   when CSS transition ends (onTransitionEnd)
+ *   finishing → crawling: when isPending becomes true again
+ *
+ * No useEffect — all state changes are either derived during render
+ * (getDerivedStateFromProps pattern) or triggered by DOM events.
+ */
+export function TopLoader({ config }: { config?: TopLoaderConfig }): React.ReactElement | null {
+  const pendingUrl = usePendingNavigationUrl();
+  const isPending = pendingUrl !== null;
+
+  const color = config?.color ?? DEFAULT_COLOR;
+  const height = config?.height ?? DEFAULT_HEIGHT;
+  const shadow = config?.shadow ?? DEFAULT_SHADOW;
+  const delay = config?.delay ?? DEFAULT_DELAY;
+  const zIndex = config?.zIndex ?? DEFAULT_Z_INDEX;
+
+  const [phase, setPhase] = useState<'hidden' | 'crawling' | 'finishing'>('hidden');
+
+  // ─── Synchronous phase derivation (getDerivedStateFromProps) ──
+  // React allows setState during render if the value changes — it
+  // immediately re-renders with the updated state before committing.
+
+  if (isPending && (phase === 'hidden' || phase === 'finishing')) {
+    setPhase('crawling');
+  }
+  if (!isPending && phase === 'crawling') {
+    setPhase('finishing');
+  }
+
+  // Inject keyframes on first visible render (idempotent)
+  if (phase !== 'hidden') {
+    ensureKeyframes();
+  }
+
+  if (phase === 'hidden') return null;
+
+  // ─── Styles ──────────────────────────────────────────────────
+
+  const containerStyle: React.CSSProperties = {
+    position: 'fixed',
+    top: 0,
+    left: 0,
+    width: '100%',
+    height: `${height}px`,
+    zIndex,
+    pointerEvents: 'none',
+  };
+
+  const barStyle: React.CSSProperties = {
+    height: '100%',
+    backgroundColor: color,
+    ...(phase === 'crawling'
+      ? {
+          // Crawl from 0% to 90% over 30s. When delay > 0, both the crawl
+          // and a visibility animation are delayed — the bar stays at width 0%
+          // and opacity 0 during the delay, then appears and starts crawling.
+          // With delay 0, the appear animation is instant (0s duration, no delay).
+          animation: [
+            `${CRAWL_KEYFRAMES} 30s ease-out ${delay}ms forwards`,
+            `${APPEAR_KEYFRAMES} 0s ${delay}ms both`,
+          ].join(', '),
+        }
+      : {
+          // Finishing: snap to 100% and fade out over 200ms.
+          width: '100%',
+          opacity: 0,
+          transition: 'width 200ms ease, opacity 200ms ease',
+        }),
+    ...(shadow
+      ? {
+          boxShadow: `0 0 10px ${color}, 0 0 5px ${color}`,
+        }
+      : {}),
+  };
+
+  // Clean up the finishing phase when the CSS transition completes.
+  // onTransitionEnd fires once per transitioned property — we act on
+  // the first one (opacity) and ignore subsequent (width).
+  const handleTransitionEnd = phase === 'finishing'
+    ? (e: React.TransitionEvent) => {
+        if (e.propertyName === 'opacity') {
+          setPhase('hidden');
+        }
+      }
+    : undefined;
+
+  return createElement(
+    'div',
+    {
+      style: containerStyle,
+      'aria-hidden': 'true',
+      'data-timber-top-loader': '',
+    },
+    createElement('div', { style: barStyle, onTransitionEnd: handleTransitionEnd })
+  );
+}

package/src/client/transition-root.tsx

@@ -22,8 +22,9 @@
  * See design/19-client-navigation.md §"NavigationContext"
  */
 
-import { useState, useTransition, createElement, type ReactNode } from 'react';
+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 ──────────────────────────────────────
 
@@ -61,7 +62,7 @@ let _navigateTransition:
  * Non-navigation renders:
  *   transitionRender(newWrappedElement);
  */
-export function TransitionRoot({ initial }: { initial: ReactNode }): ReactNode {
+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();
@@ -101,7 +102,14 @@ export function TransitionRoot({ initial }: { initial: ReactNode }): ReactNode {
     });
   };
 
-  return createElement(PendingNavigationProvider, { value: pendingUrl }, element);
+  // 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 ──────────────────────────────────────────────────

package/src/index.ts

@@ -18,7 +18,7 @@ import { timberServerActionExports } from './plugins/server-action-exports';
 import { timberBuildManifest } from './plugins/build-manifest';
 import { timberDevLogs } from './plugins/dev-logs';
 import { timberReactProd } from './plugins/react-prod';
-import { timberChunks, assignClientChunk } from './plugins/chunks';
+import { timberChunks } from './plugins/chunks';
 import { timberServerBundle } from './plugins/server-bundle';
 import { timberAdapterBuild } from './plugins/adapter-build';
 import { timberBuildReport } from './plugins/build-report';
@@ -110,6 +110,30 @@ export interface TimberUserConfig {
     recmaPlugins?: unknown[];
     remarkRehypeOptions?: Record<string, unknown>;
   };
+  /**
+   * Built-in top-loader progress bar for client navigations.
+   * Shows an animated bar at the top of the viewport during RSC navigations.
+   * Enabled by default — set `enabled: false` to opt out.
+   *
+   * Users who want a fully custom progress indicator should disable this
+   * and use `useNavigationPending()` directly.
+   *
+   * See LOCAL-336 for design decisions.
+   */
+  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;
+  };
 }
 
 /**
@@ -376,7 +400,8 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
           ssr: 'virtual:timber-ssr-entry',
           client: 'virtual:timber-browser-entry',
         },
-        clientChunks: assignClientChunk,
+        // No custom clientChunks — Rolldown handles natural code splitting.
+        // See design/27-chunking-strategy.md and LOCAL-337.
       });
     }
   );