@timber-js/app 0.2.0-alpha.166 → 0.2.0-alpha.167

package/src/client/router.ts

@@ -306,6 +306,89 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
+  /**
+   * Atomically update all navigation-owned state for a new page. Every
+   * code path that changes the "current page" must go through this
+   * function — making "forgot a field" impossible by construction.
+   *
+   * The three operations:
+   * 1. Segment cache — update from server-provided segment metadata
+   * 2. Navigation state — params + pathname for useSegmentParams/usePathname
+   * 3. History stack — store the payload for instant back/forward replay
+   */
+  function commitNavigation(
+    url: string,
+    opts: {
+      payload: unknown;
+      params?: Record<string, string | string[]> | null;
+      segmentInfo?: SegmentInfo[] | null;
+      /** When true, clear the segment cache if segmentInfo is empty
+       *  (popstate replay for entries without layout metadata). */
+      clearSegmentCacheOnEmpty?: boolean;
+    }
+  ): NavigationState {
+    if (opts.segmentInfo && opts.segmentInfo.length > 0) {
+      updateSegmentCache(opts.segmentInfo);
+    } else if (opts.clearSegmentCacheOnEmpty) {
+      segmentCache.clear();
+    }
+
+    const navState = updateNavigationState(opts.params, url);
+
+    historyStack.push(url, {
+      payload: opts.payload,
+      params: navState.params,
+      segmentInfo: opts.segmentInfo,
+    });
+
+    return navState;
+  }
+
+  /**
+   * Wrap a navigation in the standard abort/pending/cleanup lifecycle.
+   * Consolidates the createNavAbort + setPending + staleness-guarded
+   * finally that was duplicated across navigate, refresh, and both
+   * handlePopState paths. AbortErrors are swallowed (not application
+   * errors); all other errors propagate to the caller.
+   */
+  async function runNavigation(
+    url: string,
+    fn: (navAbort: AbortController) => Promise<void>,
+    externalSignal?: AbortSignal
+  ): Promise<void> {
+    const navAbort = createNavAbort(externalSignal);
+    setPending(true, url);
+    try {
+      await fn(navAbort);
+    } catch (error) {
+      if (isAbortError(error)) return;
+      throw error;
+    } finally {
+      if (currentNavAbort === navAbort) {
+        currentNavAbort = null;
+        setPending(false);
+        deps.completeRouterNavigation?.();
+      }
+    }
+  }
+
+  /**
+   * Resolve thenable payloads in the test/fallback path (no navigateTransition).
+   * In production, React handles thenables from createFromFetch directly via
+   * Suspense. In tests, renderRoot is a plain mock that expects resolved values.
+   */
+  async function resolveForFallback(payload: unknown): Promise<unknown> {
+    if (
+      !deps.navigateTransition &&
+      payload != null &&
+      typeof payload === 'object' &&
+      'then' in payload
+    ) {
+      return await (payload as PromiseLike<unknown>);
+    }
+    return payload;
+  }
+
   function isPartialNavigation(skippedSegments: string[] | null | undefined): boolean {
     return skippedSegments != null && skippedSegments.length > 0;
   }
@@ -357,9 +440,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
 
   /**
    * Render a payload via navigateTransition (production) or renderRoot (tests).
-   * The perform callback should fetch data, update state, and return the
-   * FetchResult plus the NavigationState (so it can be passed explicitly
-   * to wrapPayload/renderRoot without temporal coupling).
+   * The perform callback should fetch data, call commitNavigation, and return
+   * the FetchResult plus the NavigationState.
+   *
+   * State management (segmentCache, navState, historyStack) is handled by
+   * commitNavigation inside perform — this function only handles rendering.
    */
   async function renderViaTransition(
     url: string,
@@ -372,11 +457,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         if (isPartialNavigation(result.skippedSegments)) {
           const segmentUpdates = buildSegmentUpdates(result);
 
-          historyStack.push(url, {
-            payload: null,
-            params: result.params,
-          });
-
           // Re-wrap the CURRENT element with new context values.
           // SegmentOutlets read updates from SegmentUpdateContext;
           // NavigationProvider gets new params/pathname.
@@ -389,10 +469,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         }
 
         // Full navigation — empty updates, render the new tree.
-        historyStack.push(url, {
-          payload: result.payload,
-          params: result.params,
-        });
         const element = wrapPayload(result.payload, result.navState);
         return { element, decodePromise: result.decodePromise };
       });
@@ -400,24 +476,8 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
     // Fallback: no transition (tests, no React tree)
     const result = await perform();
-    if (isPartialNavigation(result.skippedSegments)) {
-      historyStack.push(url, {
-        payload: null,
-        params: result.params,
-      });
-    } else {
-      // Resolve thenables before storing/rendering in the fallback path
-      // (tests without navigateTransition). In production, React handles
-      // thenables via Suspense; in tests, renderRoot expects resolved values.
-      const payload =
-        result.payload != null && typeof result.payload === 'object' && 'then' in result.payload
-          ? await (result.payload as PromiseLike<unknown>)
-          : result.payload;
-      historyStack.push(url, {
-        payload,
-        params: result.params,
-      });
-      renderPayload(payload, result.navState);
+    if (!isPartialNavigation(result.skippedSegments)) {
+      renderPayload(result.payload, result.navState);
     }
   }
 
@@ -505,18 +565,21 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       deps.setRouterNavigating?.(false);
     }
 
-    // NOTE: History push is deferred — the merged payload (after segment
-    // merging in renderViaTransition) is stored by the caller, not here.
-    // Storing result.payload here would record the partial (pre-merge)
-    // RSC tree, causing handlePopState to replay an incomplete tree.
-
-    // Update the segment cache with the new route's segment tree.
-    updateSegmentCache(result.segmentInfo);
-
-    // Update navigation state and capture it for explicit passing.
-    const navState = updateNavigationState(result.params, url);
+    // Resolve thenable payloads in the test path so popstate replay
+    // and renderPayload receive plain values (see resolveForFallback).
+    const payload = await resolveForFallback(result.payload);
+
+    // Atomically update all navigation state via commitNavigation.
+    // Partial navigations store null payload — the partial RSC tree
+    // can't be replayed standalone; popstate will fetch fresh.
+    const isPartial = isPartialNavigation(result.skippedSegments);
+    const navState = commitNavigation(url, {
+      payload: isPartial ? null : payload,
+      params: result.params,
+      segmentInfo: result.segmentInfo,
+    });
 
-    return { ...result, navState };
+    return { ...result, payload, navState };
   }
 
   async function navigate(url: string, options: NavigationOptions = {}): Promise<void> {
@@ -534,10 +597,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     const hash = hashIndex === -1 ? '' : url.slice(hashIndex);
     const fetchUrl = hashIndex === -1 ? url : url.slice(0, hashIndex);
 
-    // Create an abort controller for this navigation. Links to the external
-    // signal (Navigation API's event.signal) when provided.
-    const navAbort = createNavAbort(externalSignal);
-
     // Capture the departing page's scroll position for scroll={false} preservation.
     const currentScrollY = deps.getScrollY();
 
@@ -549,114 +608,69 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       deps.replaceState({ timber: true, scrollY: currentScrollY }, '', deps.getCurrentUrl());
     }
 
-    // When Navigation API is active, initiate the navigation via
-    // navigation.navigate() BEFORE the fetch. Unlike history.pushState()
-    // which commits the URL synchronously (so Chrome sees it as "done"),
-    // navigation.navigate() fires the navigate event before committing.
-    // Our handler intercepts with a deferred promise, and Chrome shows
-    // its native loading indicator until completeRouterNavigation()
-    // resolves it in the finally block (same time as TopLoader clears).
     let effectiveSkipHistory = skipHistory;
-    if (!skipHistory && deps.navigationNavigate) {
-      deps.setRouterNavigating?.(true);
-      deps.navigationNavigate(url, replace);
-      deps.setRouterNavigating?.(false);
-      effectiveSkipHistory = true;
-    }
 
-    setPending(true, url);
-
-    try {
-      await renderViaTransition(fetchUrl, () =>
-        performNavigationFetch(fetchUrl, {
-          replace,
-          commitUrl: url,
-          signal: navAbort.signal,
-          skipHistory: effectiveSkipHistory,
-        })
-      );
+    await runNavigation(
+      url,
+      async (navAbort) => {
+        // When Navigation API is active, initiate the navigation via
+        // navigation.navigate() BEFORE the fetch. Must happen after
+        // createNavAbort supersedes the previous navigation (done by
+        // runNavigation) so the old deferred is resolved first.
+        if (!effectiveSkipHistory && deps.navigationNavigate) {
+          deps.setRouterNavigating?.(true);
+          deps.navigationNavigate(url, replace);
+          deps.setRouterNavigating?.(false);
+          effectiveSkipHistory = true;
+        }
 
-      // Notify nuqs adapter (and any other listeners) that navigation completed.
-      window.dispatchEvent(new Event('timber:navigation-end'));
+        try {
+          await renderViaTransition(fetchUrl, () =>
+            performNavigationFetch(fetchUrl, {
+              replace,
+              commitUrl: url,
+              signal: navAbort.signal,
+              skipHistory: effectiveSkipHistory,
+            })
+          );
 
-      // Scroll-to-top on forward navigation, scroll to the #fragment target
-      // when the URL has one, or restore captured position for scroll={false}.
-      // React's render() on the document root can reset scroll during DOM
-      // reconciliation, so all scroll must be actively managed.
-      if (scroll && hash) {
-        scrollToHashAfterPaint(hash);
-      } else {
-        restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
-      }
-    } catch (error) {
-      // Version skew — server has been redeployed. Full page reload
-      // so the browser fetches the new bundle. See TIM-446.
-      if (error instanceof VersionSkewError) {
-        setHardNavigating(true);
-        window.location.reload();
-        return new Promise(() => {}) as never;
-      }
-      // Server-side redirect during RSC fetch → soft router navigation.
-      // The redirect navigate will push/replace its own URL.
-      if (error instanceof RedirectError) {
-        // Drop the redirect if a newer navigation superseded this one
-        // while the redirect response was in flight — the newer
-        // navigation wins, same as the stale-transition guard.
-        if (currentNavAbort !== navAbort) return;
-        // The recursive navigate() supersedes this one via createNavAbort,
-        // which also resolves this navigation's Navigation API deferred.
-        await navigate(error.redirectUrl, { replace: true });
-        return;
-      }
-      // Server 5xx error — hard-navigate so the server renders the
-      // error page as HTML. See design/10-error-handling.md
-      // §"Error Page Rendering for Client Navigation".
-      //
-      // Set hard-navigating flag BEFORE setting window.location.href:
-      // 1. Prevents Navigation API from intercepting → infinite loop
-      // 2. Causes NavigationRoot to throw unresolvedThenable → prevents
-      //    React from rendering children during page teardown (avoids
-      //    "Rendered more hooks" crashes). See TIM-626.
-      if (error instanceof ServerErrorResponse) {
-        setHardNavigating(true);
-        window.location.href = error.url;
-        return new Promise(() => {}) as never;
-      }
-      // Abort errors are not application errors — swallow silently.
-      if (isAbortError(error)) return;
-      throw error;
-    } finally {
-      // Staleness guard (TIM-1034): only clean up when this navigation
-      // still owns the abort controller. When a newer navigation
-      // superseded this one, createNavAbort() already replaced
-      // currentNavAbort — running setPending(false) /
-      // completeRouterNavigation() here would clear the NEWER
-      // navigation's pending state and resolve its Navigation API
-      // deferred. The superseding navigation resolved OUR deferred in
-      // createNavAbort().
-      if (currentNavAbort === navAbort) {
-        // Clear the abort controller so we don't abort a completed
-        // navigation when the next one starts. In dev mode, the RSC body
-        // stream stays open after data arrives (React's Flight client
-        // waits for debug rows). Aborting a "completed" navigation kills
-        // the open stream reader → "BodyStreamBuffer was aborted".
-        currentNavAbort = null;
-        setPending(false);
-        // Resolve the Navigation API deferred — clears the browser's
-        // native loading state (tab spinner) at the same time as the
-        // TopLoader.
-        deps.completeRouterNavigation?.();
-      }
-    }
+          // Notify nuqs adapter (and any other listeners) that navigation completed.
+          window.dispatchEvent(new Event('timber:navigation-end'));
+
+          // Scroll-to-top on forward navigation, scroll to the #fragment target
+          // when the URL has one, or restore captured position for scroll={false}.
+          if (scroll && hash) {
+            scrollToHashAfterPaint(hash);
+          } else {
+            restoreScrollAfterPaint(scroll ? 0 : currentScrollY);
+          }
+        } catch (error) {
+          if (error instanceof VersionSkewError) {
+            setHardNavigating(true);
+            window.location.reload();
+            await new Promise(() => {});
+          }
+          if (error instanceof RedirectError) {
+            if (currentNavAbort !== navAbort) return;
+            await navigate(error.redirectUrl, { replace: true });
+            return;
+          }
+          if (error instanceof ServerErrorResponse) {
+            setHardNavigating(true);
+            window.location.href = error.url;
+            await new Promise(() => {});
+          }
+          throw error;
+        }
+      },
+      externalSignal
+    );
   }
 
   async function refresh(): Promise<void> {
     const currentUrl = deps.getCurrentUrl();
-    const navAbort = createNavAbort();
-
-    setPending(true, currentUrl);
 
-    try {
+    await runNavigation(currentUrl, async (navAbort) => {
       await renderViaTransition(currentUrl, async () => {
         // No state tree sent — server renders the complete RSC payload
         const result = await fetchRscPayload(
@@ -666,22 +680,15 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           undefined,
           navAbort.signal
         );
-        // History push handled by renderViaTransition (stores merged payload)
-        updateSegmentCache(result.segmentInfo);
-        const navState = updateNavigationState(result.params, currentUrl);
-        return { ...result, navState };
+        const payload = await resolveForFallback(result.payload);
+        const navState = commitNavigation(currentUrl, {
+          payload,
+          params: result.params,
+          segmentInfo: result.segmentInfo,
+        });
+        return { ...result, payload, navState };
       });
-    } catch (error) {
-      if (isAbortError(error)) return;
-      throw error;
-    } finally {
-      // Staleness guard (TIM-1034) — see navigate()'s finally block.
-      if (currentNavAbort === navAbort) {
-        currentNavAbort = null;
-        setPending(false);
-        deps.completeRouterNavigation?.();
-      }
-    }
+    });
   }
 
   async function handlePopState(
@@ -697,47 +704,51 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (entry && entry.payload !== null) {
       // Replay cached payload — no server roundtrip.
       //
-      // A forward navigation may still be in flight (back pressed while a
-      // slow RSC fetch was pending). createNavAbort() supersedes it: aborts
-      // its fetch and invalidates its render transition so the stale
-      // forward payload can't commit over this replay (TIM-1022). The
-      // replay itself is synchronous — nothing to abort later — so the
-      // controller is cleared immediately, and any pending state left by
-      // the superseded navigation is reset.
-      createNavAbort(externalSignal);
-      currentNavAbort = null;
-      setPending(false);
-      const navState = updateNavigationState(entry.params, url);
-      renderPayload(entry.payload, navState);
-      restoreScrollAfterPaint(scrollY);
+      // runNavigation supersedes any in-flight forward navigation (TIM-1022):
+      // aborts its fetch and invalidates its render transition so the stale
+      // forward payload can't commit over this replay. The replay itself is
+      // synchronous — the fn resolves immediately.
+      await runNavigation(
+        url,
+        async () => {
+          // clearSegmentCacheOnEmpty: popstate to an entry without layout
+          // metadata (e.g., initial SSR page) clears the cache so the next
+          // forward navigation gets a full render.
+          const navState = commitNavigation(url, {
+            payload: entry.payload,
+            params: entry.params,
+            segmentInfo: entry.segmentInfo,
+            clearSegmentCacheOnEmpty: true,
+          });
+          renderPayload(entry.payload, navState);
+          restoreScrollAfterPaint(scrollY);
+        },
+        externalSignal
+      );
     } else {
       // No cached payload — fetch from server.
       // This happens when navigating back to the initial SSR'd page
       // (its payload is null since it was rendered via SSR, not RSC fetch)
       // or when the entry doesn't exist at all.
-      const navAbort = createNavAbort(externalSignal);
-      setPending(true, url);
-      try {
-        await renderViaTransition(url, async () => {
-          const stateTree = segmentCache.serializeStateTree();
-          const result = await fetchRscPayload(url, deps, stateTree, undefined, navAbort.signal);
-          updateSegmentCache(result.segmentInfo);
-          const navState = updateNavigationState(result.params, url);
-          // History push handled by renderViaTransition (stores merged payload)
-          return { ...result, navState };
-        });
+      await runNavigation(
+        url,
+        async (navAbort) => {
+          await renderViaTransition(url, async () => {
+            const stateTree = segmentCache.serializeStateTree();
+            const result = await fetchRscPayload(url, deps, stateTree, undefined, navAbort.signal);
+            const payload = await resolveForFallback(result.payload);
+            const navState = commitNavigation(url, {
+              payload,
+              params: result.params,
+              segmentInfo: result.segmentInfo,
+            });
+            return { ...result, payload, navState };
+          });
 
-        restoreScrollAfterPaint(scrollY);
-      } catch (error) {
-        if (isAbortError(error)) return;
-        throw error;
-      } finally {
-        // Staleness guard (TIM-1034) — see navigate()'s finally block.
-        if (currentNavAbort === navAbort) {
-          currentNavAbort = null;
-          setPending(false);
-        }
-      }
+          restoreScrollAfterPaint(scrollY);
+        },
+        externalSignal
+      );
     }
   }
 
@@ -783,21 +794,16 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // Render the piggybacked element tree from a server action response.
       // Updates the current history entry with the fresh payload —
       // same as refresh() but without a server fetch.
-      // Revalidation payloads are already resolved (no Flight thenable),
-      // so no segment merging is needed — just cache and render.
       const currentUrl = deps.getCurrentUrl();
 
-      // Revalidation doesn't change params/pathname — preserve current state.
-      // DO NOT call updateNavigationState(null, ...) here: that normalizes
-      // params to {}, clearing dynamic route params on every action response.
-      const navState = getNavigationState();
-
-      // Keep params on the overwritten entry — dropping them would make
-      // away-and-back navigation replay this page with params normalized
-      // to {} (TIM-1037).
-      historyStack.push(currentUrl, {
+      // Preserve existing segmentInfo so away-and-back navigation replays
+      // with a correct segment cache (TIM-1037). Preserve current params
+      // so dynamic route params aren't cleared to {}.
+      const existingEntry = historyStack.get(currentUrl);
+      const navState = commitNavigation(currentUrl, {
         payload: element,
-        params: navState.params,
+        params: getNavigationState().params,
+        segmentInfo: existingEntry?.segmentInfo,
       });
       renderPayload(element, navState);
     },

package/src/plugins/adapter-build.ts

@@ -83,6 +83,7 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
         }
 
         const adapterConfig: TimberConfig = {
+          root: ctx.root,
           output: ctx.config.output ?? 'server',
           clientJavascriptDisabled: ctx.clientJavascript.disabled,
           manifestInit,

package/src/plugins/cache.ts

@@ -1,13 +1,13 @@
 /**
  * timber-cache-transform — Vite plugin that injects stable callsite IDs
- * into `cache()` calls imported from `@timber-js/app/cache`.
+ * into `cache.data()` calls imported from `@timber-js/app/cache`.
  *
  * Detected callsite forms (TIM-1054):
- *   - named imports, including aliases: `import { cache as c }` + `c(fn, opts)`
- *   - namespace imports: `import * as ns` + `ns.cache(fn, opts)`
+ *   - named imports, including aliases: `import { cache as c }` + `c.data(fn, opts)`
+ *   - namespace imports: `import * as ns` + `ns.cache.data(fn, opts)`
  * Forms a per-module transform cannot trace — local variable aliases
  * (`const c = cache`), user re-export wrapper modules, computed access
- * (`ns['cache']`) — fall back to the runtime fnId derived from
+ * (`cache['data']`) — fall back to the runtime fnId derived from
  * fnv1a(fn.toString()) (see cache/timber-cache.ts), which is deterministic
  * across instances and cold starts of the same build. Without either
  * mechanism, an ordinal counter would collide across instances with a shared
@@ -15,8 +15,8 @@
  * data to another.
  *
  * The plugin transforms:
- *   cache(fn, opts)      →  cache(fn, opts, "stable-id")
- *   ns.cache(fn, opts)   →  ns.cache(fn, opts, "stable-id")
+ *   cache.data(fn, opts)          →  cache.data(fn, opts, "stable-id")
+ *   ns.cache.data(fn, opts)       →  ns.cache.data(fn, opts, "stable-id")
  *
  * where stable-id =
  *   fnv1a(relPath + ":cache:" + fnv1a(stmtText) + ":" + fnv1a(callSpanText) + ":" + occurrence)
@@ -34,9 +34,9 @@
  * unrelated edits, while a changed call gets a fresh ID — which is exactly
  * when invalidation is wanted.
  *
- * The enclosing-statement text is included so that byte-identical cache()
+ * The enclosing-statement text is included so that byte-identical cache.data()
  * calls in different scopes — e.g. two factory helpers that each `return
- * cache(fn, { ttl: 60 })` — get distinct, insertion-stable IDs: their
+ * cache.data(fn, { ttl: 60 })` — get distinct, insertion-stable IDs: their
  * enclosing declarations differ by name/body even when the call spans are
  * identical. Without it, a source-order occurrence counter alone would shift
  * when an identical span is inserted above, reassigning IDs across deploys.
@@ -75,41 +75,56 @@ import type {
 } from './callsite-ast.js';
 
 /**
- * Is this callee a reference to the imported `cache` function — either a bare
- * identifier bound by a named import, or `ns.cache` on a namespace import?
- * Computed access (`ns['cache']`) is deliberately not matched; it falls back
+ * Is this callee a `cache.data(...)` call? Matches two forms:
+ *   - Named import: `cache.data(fn, opts)` where `cache` is the imported binding
+ *   - Namespace import: `ns.cache.data(fn, opts)` where `ns` is the namespace
+ * Computed access (`cache['data']`) is deliberately not matched; it falls back
  * to the runtime fnId derivation.
  */
-function isCacheCallee(callee: PositionedNode, bindings: ImportBindings): boolean {
-  if (callee.type === 'Identifier') {
-    return bindings.named.has((callee as IdentifierNode).name);
+function isCacheDataCallee(callee: PositionedNode, bindings: ImportBindings): boolean {
+  if (callee.type !== 'MemberExpression') return false;
+  const member = callee as unknown as MemberExpressionNode;
+  if (member.computed) return false;
+  if (member.property.type !== 'Identifier' || (member.property as IdentifierNode).name !== 'data')
+    return false;
+
+  const obj = member.object;
+  // Named import: `cache.data(...)` — obj is the imported `cache` identifier
+  if (obj.type === 'Identifier') {
+    return bindings.named.has((obj as IdentifierNode).name);
   }
-  if (callee.type === 'MemberExpression') {
-    const member = callee as unknown as MemberExpressionNode;
+  // Namespace import: `ns.cache.data(...)` — obj is `ns.cache`
+  if (obj.type === 'MemberExpression') {
+    const outer = obj as unknown as MemberExpressionNode;
     return (
-      !member.computed &&
-      member.object.type === 'Identifier' &&
-      bindings.namespaces.has((member.object as IdentifierNode).name) &&
-      member.property.type === 'Identifier' &&
-      (member.property as IdentifierNode).name === 'cache'
+      !outer.computed &&
+      outer.object.type === 'Identifier' &&
+      bindings.namespaces.has((outer.object as IdentifierNode).name) &&
+      outer.property.type === 'Identifier' &&
+      (outer.property as IdentifierNode).name === 'cache'
     );
   }
   return false;
 }
 
 /**
- * Extract the local binding name that a cache callee resolves to — the
- * identifier for named imports, or the namespace object for `ns.cache()`.
+ * Extract the local binding name that a cache.data callee resolves to — the
+ * `cache` identifier for named imports, or the namespace object for `ns.cache.data()`.
  */
 function calleeBindingName(callee: PositionedNode, bindings: ImportBindings): string | null {
-  if (callee.type === 'Identifier') {
-    const name = (callee as IdentifierNode).name;
+  if (callee.type !== 'MemberExpression') return null;
+  const member = callee as unknown as MemberExpressionNode;
+  const obj = member.object;
+  // Named import: `cache.data(...)` — binding is `cache`
+  if (obj.type === 'Identifier') {
+    const name = (obj as IdentifierNode).name;
     return bindings.named.has(name) ? name : null;
   }
-  if (callee.type === 'MemberExpression') {
-    const member = callee as unknown as MemberExpressionNode;
-    if (member.object.type === 'Identifier') {
-      const name = (member.object as IdentifierNode).name;
+  // Namespace import: `ns.cache.data(...)` — binding is `ns`
+  if (obj.type === 'MemberExpression') {
+    const outer = obj as unknown as MemberExpressionNode;
+    if (outer.object.type === 'Identifier') {
+      const name = (outer.object as IdentifierNode).name;
       return bindings.namespaces.has(name) ? name : null;
     }
   }
@@ -182,7 +197,7 @@ export function timberCacheTransform(ctx: PluginContext): Plugin {
           stmt,
           (call) =>
             call.arguments.length === 2 &&
-            isCacheCallee(call.callee, cacheBindings) &&
+            isCacheDataCallee(call.callee, cacheBindings) &&
             !isCalleeShadowed(call),
           calls
         );