@timber-js/app 0.1.56 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.56",
+  "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/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

@@ -13,8 +13,13 @@
  * 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).
  *
- * The bar respects a configurable delay (default 150ms) — if navigation
- * resolves faster than the delay, the bar never appears.
+ * 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.
@@ -22,7 +27,7 @@
 
 'use client';
 
-import { useState, useEffect, useRef, createElement } from 'react';
+import { useState, createElement } from 'react';
 import { usePendingNavigationUrl } from './navigation-context.js';
 
 // ─── Types ───────────────────────────────────────────────────────
@@ -36,7 +41,7 @@ export interface TopLoaderConfig {
   height?: number;
   /** Show subtle glow/shadow effect. Default: true. */
   shadow?: boolean;
-  /** Delay in ms before showing the bar. Default: 150. */
+  /** Delay in ms before showing the bar. Default: 0. */
   delay?: number;
   /** CSS z-index. Default: 1600. */
   zIndex?: number;
@@ -47,20 +52,22 @@ export interface TopLoaderConfig {
 const DEFAULT_COLOR = '#2299DD';
 const DEFAULT_HEIGHT = 3;
 const DEFAULT_SHADOW = true;
-const DEFAULT_DELAY = 150;
+const DEFAULT_DELAY = 0;
 const DEFAULT_Z_INDEX = 1600;
 
-// ─── Keyframes ID ────────────────────────────────────────────────
+// ─── Keyframes ───────────────────────────────────────────────────
 
 // Unique keyframes name to avoid collisions with user styles.
-const KEYFRAMES_NAME = '__timber_top_loader_crawl';
+const CRAWL_KEYFRAMES = '__timber_top_loader_crawl';
+const APPEAR_KEYFRAMES = '__timber_top_loader_appear';
 
-// Track whether the @keyframes rule has been injected into the document.
+// Track whether the @keyframes rules have been injected into the document.
 let keyframesInjected = false;
 
 /**
- * Inject the @keyframes rule into the document head once.
- * Uses a <style> tag so the animation is available for inline-styled elements.
+ * 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;
@@ -68,10 +75,14 @@ function ensureKeyframes(): void {
 
   const style = document.createElement('style');
   style.textContent = `
-@keyframes ${KEYFRAMES_NAME} {
+@keyframes ${CRAWL_KEYFRAMES} {
   0% { width: 0%; }
   100% { width: 90%; }
 }
+@keyframes ${APPEAR_KEYFRAMES} {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
 `;
   document.head.appendChild(style);
   keyframesInjected = true;
@@ -83,8 +94,15 @@ function ensureKeyframes(): void {
  * Internal top-loader component. Injected by TransitionRoot.
  *
  * Reads pending navigation state from PendingNavigationContext.
- * Shows nothing when no navigation is pending or when the navigation
- * resolves before the delay threshold.
+ * 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();
@@ -96,75 +114,23 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
   const delay = config?.delay ?? DEFAULT_DELAY;
   const zIndex = config?.zIndex ?? DEFAULT_Z_INDEX;
 
-  // Track visibility states:
-  // - 'hidden': no bar shown
-  // - 'crawling': bar is animating from 0% to 90%
-  // - 'finishing': bar is snapping to 100% and fading out
   const [phase, setPhase] = useState<'hidden' | 'crawling' | 'finishing'>('hidden');
-  const delayTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const finishTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  // Inject keyframes on mount
-  useEffect(() => {
-    ensureKeyframes();
-  }, []);
-
-  // Handle pending state changes
-  useEffect(() => {
-    if (isPending) {
-      // Navigation started — wait for delay before showing the bar
-      // Clear any finish timer from a previous navigation
-      if (finishTimerRef.current !== null) {
-        clearTimeout(finishTimerRef.current);
-        finishTimerRef.current = null;
-      }
-
-      if (delay > 0) {
-        delayTimerRef.current = setTimeout(() => {
-          delayTimerRef.current = null;
-          setPhase('crawling');
-        }, delay);
-      } else {
-        setPhase('crawling');
-      }
-    } else {
-      // Navigation ended (or was never pending)
-      // Clear the delay timer — if it hasn't fired, the bar never shows
-      if (delayTimerRef.current !== null) {
-        clearTimeout(delayTimerRef.current);
-        delayTimerRef.current = null;
-        // Bar was never shown — stay hidden
-        if (phase === 'hidden') return;
-      }
+  // ─── Synchronous phase derivation (getDerivedStateFromProps) ──
+  // React allows setState during render if the value changes — it
+  // immediately re-renders with the updated state before committing.
 
-      if (phase === 'crawling') {
-        // Bar was visible — snap to 100% and fade out
-        setPhase('finishing');
-        finishTimerRef.current = setTimeout(() => {
-          finishTimerRef.current = null;
-          setPhase('hidden');
-        }, 200);
-      }
-      // If already 'finishing' or 'hidden', do nothing
-    }
+  if (isPending && (phase === 'hidden' || phase === 'finishing')) {
+    setPhase('crawling');
+  }
+  if (!isPending && phase === 'crawling') {
+    setPhase('finishing');
+  }
 
-    return () => {
-      if (delayTimerRef.current !== null) {
-        clearTimeout(delayTimerRef.current);
-        delayTimerRef.current = null;
-      }
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- phase is read but intentionally not a dependency
-  }, [isPending, delay]);
-
-  // Cleanup finish timer on unmount
-  useEffect(() => {
-    return () => {
-      if (finishTimerRef.current !== null) {
-        clearTimeout(finishTimerRef.current);
-      }
-    };
-  }, []);
+  // Inject keyframes on first visible render (idempotent)
+  if (phase !== 'hidden') {
+    ensureKeyframes();
+  }
 
   if (phase === 'hidden') return null;
 
@@ -185,11 +151,17 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
     backgroundColor: color,
     ...(phase === 'crawling'
       ? {
-          // Crawling: animate from 0% to 90% over 30s
-          animation: `${KEYFRAMES_NAME} 30s ease-out forwards`,
+          // 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
+          // Finishing: snap to 100% and fade out over 200ms.
           width: '100%',
           opacity: 0,
           transition: 'width 200ms ease, opacity 200ms ease',
@@ -201,6 +173,17 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
       : {}),
   };
 
+  // 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',
     {
@@ -208,6 +191,6 @@ export function TopLoader({ config }: { config?: TopLoaderConfig }): React.React
       'aria-hidden': 'true',
       'data-timber-top-loader': '',
     },
-    createElement('div', { style: barStyle })
+    createElement('div', { style: barStyle, onTransitionEnd: handleTransitionEnd })
   );
 }

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';
@@ -129,7 +129,7 @@ export interface TimberUserConfig {
     height?: number;
     /** Show subtle glow/shadow effect. Default: true. */
     shadow?: boolean;
-    /** Delay in ms before showing the bar (avoids flash on fast navs). Default: 150. */
+    /** Delay in ms before showing the bar (avoids flash on fast navs). Default: 0. */
     delay?: number;
     /** CSS z-index. Default: 1600. */
     zIndex?: number;
@@ -400,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.
       });
     }
   );