@timber-js/app 0.1.52 → 0.1.54

package/src/client/router.ts

@@ -7,6 +7,13 @@ import { HistoryStack } from './history';
 import type { HeadElement } from './head';
 import { setCurrentParams } from './use-params.js';
 import { setNavigationState } from './navigation-context.js';
+import {
+  SegmentElementCache,
+  cacheSegmentElements,
+  mergeSegmentTree,
+} from './segment-merger.js';
+import { fetchRscPayload, RedirectError } from './rsc-fetch.js';
+import type { FetchResult } from './rsc-fetch.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
@@ -71,16 +78,6 @@ export interface RouterDeps {
   ) => Promise<void>;
 }
 
-/** Result of fetching an RSC payload — includes head elements and segment metadata. */
-interface FetchResult {
-  payload: unknown;
-  headElements: HeadElement[] | null;
-  /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
-  segmentInfo: SegmentInfo[] | null;
-  /** Route params from X-Timber-Params header for populating useParams(). */
-  params: Record<string, string | string[]> | null;
-}
-
 export interface RouterInstance {
   /** Navigate to a new URL (forward navigation) */
   navigate(url: string, options?: NavigationOptions): Promise<void>;
@@ -107,6 +104,12 @@ export interface RouterInstance {
    * Called on initial hydration with segment info embedded in the HTML.
    */
   initSegmentCache(segments: SegmentInfo[]): void;
+  /**
+   * Cache segment elements from a decoded RSC element tree.
+   * Called on initial hydration to populate the element cache so the
+   * first client navigation can use partial payloads.
+   */
+  cacheElementTree(element: unknown): void;
   /** The segment cache (exposed for tests and <Link> prefetch) */
   segmentCache: SegmentCache;
   /** The prefetch cache (exposed for tests and <Link> prefetch) */
@@ -115,18 +118,6 @@ export interface RouterInstance {
   historyStack: HistoryStack;
 }
 
-/**
- * Thrown when an RSC payload response contains X-Timber-Redirect header.
- * Caught in navigate() to trigger a soft router navigation to the redirect target.
- */
-class RedirectError extends Error {
-  readonly redirectUrl: string;
-  constructor(url: string) {
-    super(`Server redirect to ${url}`);
-    this.redirectUrl = url;
-  }
-}
-
 /**
  * Check if an error is an abort error (connection closed / fetch aborted).
  * Browsers throw DOMException with name 'AbortError' when a fetch is aborted.
@@ -137,168 +128,6 @@ function isAbortError(error: unknown): boolean {
   return false;
 }
 
-// ─── RSC Fetch ───────────────────────────────────────────────────
-
-const RSC_CONTENT_TYPE = 'text/x-component';
-
-/**
- * Generate a short random cache-busting ID (5 chars, a-z0-9).
- * Matches the format Next.js uses for _rsc params.
- */
-function generateCacheBustId(): string {
-  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
-  let id = '';
-  for (let i = 0; i < 5; i++) {
-    id += chars[(Math.random() * 36) | 0];
-  }
-  return id;
-}
-
-/**
- * Append a `_rsc=<id>` query parameter to the URL.
- * Follows Next.js's pattern — prevents CDN/browser from serving cached HTML
- * for RSC navigation requests and signals that this is an RSC fetch.
- */
-function appendRscParam(url: string): string {
-  const separator = url.includes('?') ? '&' : '?';
-  return `${url}${separator}_rsc=${generateCacheBustId()}`;
-}
-
-function buildRscHeaders(
-  stateTree: { segments: string[] } | undefined,
-  currentUrl?: string
-): Record<string, string> {
-  const headers: Record<string, string> = {
-    Accept: RSC_CONTENT_TYPE,
-  };
-  if (stateTree) {
-    headers['X-Timber-State-Tree'] = JSON.stringify(stateTree);
-  }
-  // Send current URL for intercepting route resolution.
-  // The server uses this to determine if an intercepting route should
-  // render instead of the actual target route (modal pattern).
-  // See design/07-routing.md §"Intercepting Routes"
-  if (currentUrl) {
-    headers['X-Timber-URL'] = currentUrl;
-  }
-  return headers;
-}
-
-/**
- * Extract head elements from the X-Timber-Head response header.
- * Returns null if the header is missing or malformed.
- */
-function extractHeadElements(response: Response): HeadElement[] | null {
-  const header = response.headers.get('X-Timber-Head');
-  if (!header) return null;
-  try {
-    return JSON.parse(decodeURIComponent(header));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Extract segment metadata from the X-Timber-Segments response header.
- * Returns null if the header is missing or malformed.
- *
- * Format: JSON array of {path, isAsync} objects describing the rendered
- * segment chain from root to leaf. Used to populate the client-side
- * segment cache for state tree diffing on subsequent navigations.
- */
-function extractSegmentInfo(response: Response): SegmentInfo[] | null {
-  const header = response.headers.get('X-Timber-Segments');
-  if (!header) return null;
-  try {
-    return JSON.parse(header);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Extract route params from the X-Timber-Params response header.
- * Returns null if the header is missing or malformed.
- *
- * Used to populate useParams() after client-side navigation.
- */
-function extractParams(response: Response): Record<string, string | string[]> | null {
-  const header = response.headers.get('X-Timber-Params');
-  if (!header) return null;
-  try {
-    return JSON.parse(header);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Fetch an RSC payload from the server. If a decodeRsc function is provided,
- * the response is decoded into a React element tree via createFromFetch.
- * Otherwise, the raw response text is returned (test mode).
- *
- * Also extracts head elements from the X-Timber-Head response header
- * so the client can update document.title and <meta> tags after navigation.
- */
-async function fetchRscPayload(
-  url: string,
-  deps: RouterDeps,
-  stateTree?: { segments: string[] },
-  currentUrl?: string
-): Promise<FetchResult> {
-  const rscUrl = appendRscParam(url);
-  const headers = buildRscHeaders(stateTree, currentUrl);
-  if (deps.decodeRsc) {
-    // Production path: use createFromFetch for streaming RSC decoding.
-    // createFromFetch takes a Promise<Response> and progressively parses
-    // the RSC Flight stream as chunks arrive.
-    //
-    // Intercept the response to read X-Timber-Head before createFromFetch
-    // consumes the body. Reading headers does NOT consume the body stream.
-    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual' });
-    let headElements: HeadElement[] | null = null;
-    let segmentInfo: SegmentInfo[] | null = null;
-    let params: Record<string, string | string[]> | null = null;
-    const wrappedPromise = fetchPromise.then((response) => {
-      // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
-      // for RSC payload requests instead of a raw 302, because fetch with
-      // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
-      // which crashes createFromFetch when it tries to read the body stream.
-      const redirectLocation =
-        response.headers.get('X-Timber-Redirect') ||
-        (response.status >= 300 && response.status < 400 ? response.headers.get('Location') : null);
-      if (redirectLocation) {
-        throw new RedirectError(redirectLocation);
-      }
-      headElements = extractHeadElements(response);
-      segmentInfo = extractSegmentInfo(response);
-      params = extractParams(response);
-      return response;
-    });
-    // Await so headElements/segmentInfo/params are populated before we return.
-    // Also await the decoded payload — createFromFetch returns a thenable
-    // that resolves to the React element tree.
-    await wrappedPromise;
-    const payload = await deps.decodeRsc(wrappedPromise);
-    return { payload, headElements, segmentInfo, params };
-  }
-  // Test/fallback path: return raw text
-  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual' });
-  // Check for redirect in test path too
-  if (response.status >= 300 && response.status < 400) {
-    const location = response.headers.get('Location');
-    if (location) {
-      throw new RedirectError(location);
-    }
-  }
-  return {
-    payload: await response.text(),
-    headElements: extractHeadElements(response),
-    segmentInfo: extractSegmentInfo(response),
-    params: extractParams(response),
-  };
-}
-
 // ─── Router Factory ──────────────────────────────────────────────
 
 /**
@@ -309,6 +138,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
   const segmentCache = new SegmentCache();
   const prefetchCache = new PrefetchCache();
   const historyStack = new HistoryStack();
+  const segmentElementCache = new SegmentElementCache();
 
   let pending = false;
   let pendingUrl: string | null = null;
@@ -343,6 +173,28 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     }
   }
 
+  /**
+   * Merge a partial RSC payload with cached segment elements if segments
+   * were skipped, then cache segments from the (merged) payload.
+   * Returns the merged payload ready for rendering.
+   */
+  function mergeAndCachePayload(
+    payload: unknown,
+    skippedSegments: string[] | null | undefined
+  ): unknown {
+    let merged = payload;
+
+    // If segments were skipped, merge the partial payload with cached segments
+    if (skippedSegments && skippedSegments.length > 0) {
+      merged = mergeSegmentTree(payload, skippedSegments, segmentElementCache);
+    }
+
+    // Cache segment elements from the (merged) payload for future merges
+    cacheSegmentElements(merged, segmentElementCache);
+
+    return merged;
+  }
+
   /**
    * Update navigation state (params + pathname) for the next render.
    *
@@ -370,21 +222,38 @@ export function createRouter(deps: RouterDeps): RouterInstance {
    * useOptimistic for the pending URL. In tests, the payload is rendered directly.
    */
   async function renderViaTransition(
-    pendingUrl: string,
+    url: string,
     perform: () => Promise<FetchResult>
   ): Promise<HeadElement[] | null> {
     if (deps.navigateTransition) {
       let headElements: HeadElement[] | null = null;
-      await deps.navigateTransition(pendingUrl, async (wrapPayload) => {
+      await deps.navigateTransition(url, async (wrapPayload) => {
         const result = await perform();
         headElements = result.headElements;
-        return wrapPayload(result.payload);
+        // Merge partial payload with cached segments before wrapping
+        const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+        // Store the MERGED payload in history — not the partial pre-merge tree.
+        // This ensures handlePopState replays the complete tree on back/forward.
+        historyStack.push(url, {
+          payload: merged,
+          headElements: result.headElements,
+          params: result.params,
+        });
+        return wrapPayload(merged);
       });
       return headElements;
     }
     // Fallback: no transition (tests, no React tree)
     const result = await perform();
-    renderPayload(result.payload);
+    // Merge partial payload with cached segments before rendering
+    const merged = mergeAndCachePayload(result.payload, result.skippedSegments);
+    // Store merged payload in history
+    historyStack.push(url, {
+      payload: merged,
+      headElements: result.headElements,
+      params: result.params,
+    });
+    renderPayload(merged);
     return result.headElements;
   }
 
@@ -421,13 +290,14 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           headElements: prefetched.headElements,
           segmentInfo: prefetched.segmentInfo ?? null,
           params: prefetched.params ?? null,
+          skippedSegments: prefetched.skippedSegments ?? null,
         }
       : undefined;
 
     if (result === undefined) {
       // Fetch RSC payload with state tree for partial rendering.
       // Send current URL for intercepting route resolution (modal pattern).
-      const stateTree = segmentCache.serializeStateTree();
+      const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
       const rawCurrentUrl = deps.getCurrentUrl();
       const currentUrl = rawCurrentUrl.startsWith('http')
         ? new URL(rawCurrentUrl).pathname
@@ -442,12 +312,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       deps.pushState({ timber: true, scrollY: 0 }, '', url);
     }
 
-    // Store the payload in the history stack
-    historyStack.push(url, {
-      payload: result.payload,
-      headElements: result.headElements,
-      params: result.params,
-    });
+    // 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);
@@ -518,11 +386,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       const headElements = await renderViaTransition(currentUrl, async () => {
         // No state tree sent — server renders the complete RSC payload
         const result = await fetchRscPayload(currentUrl, deps);
-        historyStack.push(currentUrl, {
-          payload: result.payload,
-          headElements: result.headElements,
-          params: result.params,
-        });
+        // History push handled by renderViaTransition (stores merged payload)
         updateSegmentCache(result.segmentInfo);
         updateNavigationState(result.params, currentUrl);
         return result;
@@ -557,15 +421,11 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       setPending(true, url);
       try {
         const headElements = await renderViaTransition(url, async () => {
-          const stateTree = segmentCache.serializeStateTree();
+          const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
           const result = await fetchRscPayload(url, deps, stateTree);
           updateSegmentCache(result.segmentInfo);
           updateNavigationState(result.params, url);
-          historyStack.push(url, {
-            payload: result.payload,
-            headElements: result.headElements,
-            params: result.params,
-          });
+          // History push handled by renderViaTransition (stores merged payload)
           return result;
         });
 
@@ -590,7 +450,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     if (historyStack.has(url)) return;
 
     // Fire-and-forget fetch
-    const stateTree = segmentCache.serializeStateTree();
+    const stateTree = segmentCache.serializeStateTree(segmentElementCache.getMergeablePaths());
     void fetchRscPayload(url, deps, stateTree).then(
       (result) => {
         prefetchCache.set(url, result);
@@ -616,15 +476,18 @@ 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 and applies
       // head elements — same as refresh() but without a server fetch.
+      // Cache segment elements for future partial merges.
       const currentUrl = deps.getCurrentUrl();
+      const merged = mergeAndCachePayload(element, null);
       historyStack.push(currentUrl, {
-        payload: element,
+        payload: merged,
         headElements,
       });
-      renderPayload(element);
+      renderPayload(merged);
       applyHead(headElements);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),
+    cacheElementTree: (element: unknown) => cacheSegmentElements(element, segmentElementCache),
     segmentCache,
     prefetchCache,
     historyStack,

package/src/client/rsc-fetch.ts

@@ -0,0 +1,234 @@
+/**
+ * RSC Fetch — handles fetching and parsing RSC Flight payloads.
+ *
+ * Extracted from router.ts to keep both files under the 500-line limit.
+ * This module handles:
+ * - Cache-busting URL generation for RSC requests
+ * - Building RSC request headers (Accept, X-Timber-State-Tree)
+ * - Extracting metadata from RSC response headers
+ * - Fetching and decoding RSC payloads
+ *
+ * See design/19-client-navigation.md §"RSC Payload Handling"
+ */
+
+import type { SegmentInfo } from './segment-cache';
+import type { HeadElement } from './head';
+import type { RouterDeps } from './router';
+
+// ─── Types ───────────────────────────────────────────────────────
+
+/** Result of fetching an RSC payload — includes head elements and segment metadata. */
+export interface FetchResult {
+  payload: unknown;
+  headElements: HeadElement[] | null;
+  /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
+  segmentInfo: SegmentInfo[] | null;
+  /** Route params from X-Timber-Params header for populating useParams(). */
+  params: Record<string, string | string[]> | null;
+  /** Segment paths that were skipped by the server (for client-side merging). */
+  skippedSegments: string[] | null;
+}
+
+// ─── Constants ───────────────────────────────────────────────────
+
+export const RSC_CONTENT_TYPE = 'text/x-component';
+
+// ─── URL Helpers ─────────────────────────────────────────────────
+
+/**
+ * Generate a short random cache-busting ID (5 chars, a-z0-9).
+ * Matches the format Next.js uses for _rsc params.
+ */
+function generateCacheBustId(): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+  let id = '';
+  for (let i = 0; i < 5; i++) {
+    id += chars[(Math.random() * 36) | 0];
+  }
+  return id;
+}
+
+/**
+ * Append a `_rsc=<id>` query parameter to the URL.
+ * Follows Next.js's pattern — prevents CDN/browser from serving cached HTML
+ * for RSC navigation requests and signals that this is an RSC fetch.
+ */
+function appendRscParam(url: string): string {
+  const separator = url.includes('?') ? '&' : '?';
+  return `${url}${separator}_rsc=${generateCacheBustId()}`;
+}
+
+export function buildRscHeaders(
+  stateTree: { segments: string[] } | undefined,
+  currentUrl?: string
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: RSC_CONTENT_TYPE,
+  };
+  if (stateTree) {
+    headers['X-Timber-State-Tree'] = JSON.stringify(stateTree);
+  }
+  // Send current URL for intercepting route resolution.
+  // The server uses this to determine if an intercepting route should
+  // render instead of the actual target route (modal pattern).
+  // See design/07-routing.md §"Intercepting Routes"
+  if (currentUrl) {
+    headers['X-Timber-URL'] = currentUrl;
+  }
+  return headers;
+}
+
+// ─── Response Header Extraction ──────────────────────────────────
+
+/**
+ * Extract head elements from the X-Timber-Head response header.
+ * Returns null if the header is missing or malformed.
+ */
+export function extractHeadElements(response: Response): HeadElement[] | null {
+  const header = response.headers.get('X-Timber-Head');
+  if (!header) return null;
+  try {
+    return JSON.parse(decodeURIComponent(header));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract segment metadata from the X-Timber-Segments response header.
+ * Returns null if the header is missing or malformed.
+ *
+ * Format: JSON array of {path, isAsync} objects describing the rendered
+ * segment chain from root to leaf. Used to populate the client-side
+ * segment cache for state tree diffing on subsequent navigations.
+ */
+export function extractSegmentInfo(response: Response): SegmentInfo[] | null {
+  const header = response.headers.get('X-Timber-Segments');
+  if (!header) return null;
+  try {
+    return JSON.parse(header);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract skipped segment paths from the X-Timber-Skipped-Segments header.
+ * Returns null if the header is missing or malformed.
+ *
+ * When the server skips sync layouts the client already has cached,
+ * it sends this header listing the skipped segment paths (outermost first).
+ * The client uses this to merge the partial payload with cached segments.
+ */
+export function extractSkippedSegments(response: Response): string[] | null {
+  const header = response.headers.get('X-Timber-Skipped-Segments');
+  if (!header) return null;
+  try {
+    const parsed = JSON.parse(header);
+    return Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract route params from the X-Timber-Params response header.
+ * Returns null if the header is missing or malformed.
+ *
+ * Used to populate useParams() after client-side navigation.
+ */
+export function extractParams(response: Response): Record<string, string | string[]> | null {
+  const header = response.headers.get('X-Timber-Params');
+  if (!header) return null;
+  try {
+    return JSON.parse(header);
+  } catch {
+    return null;
+  }
+}
+
+// ─── Redirect Error ──────────────────────────────────────────────
+
+/**
+ * Thrown when an RSC payload response contains X-Timber-Redirect header.
+ * Caught in navigate() to trigger a soft router navigation to the redirect target.
+ */
+export class RedirectError extends Error {
+  readonly redirectUrl: string;
+  constructor(url: string) {
+    super(`Server redirect to ${url}`);
+    this.redirectUrl = url;
+  }
+}
+
+// ─── Fetch ───────────────────────────────────────────────────────
+
+/**
+ * Fetch an RSC payload from the server. If a decodeRsc function is provided,
+ * the response is decoded into a React element tree via createFromFetch.
+ * Otherwise, the raw response text is returned (test mode).
+ *
+ * Also extracts head elements from the X-Timber-Head response header
+ * so the client can update document.title and <meta> tags after navigation.
+ */
+export async function fetchRscPayload(
+  url: string,
+  deps: RouterDeps,
+  stateTree?: { segments: string[] },
+  currentUrl?: string
+): Promise<FetchResult> {
+  const rscUrl = appendRscParam(url);
+  const headers = buildRscHeaders(stateTree, currentUrl);
+  if (deps.decodeRsc) {
+    // Production path: use createFromFetch for streaming RSC decoding.
+    // createFromFetch takes a Promise<Response> and progressively parses
+    // the RSC Flight stream as chunks arrive.
+    //
+    // Intercept the response to read X-Timber-Head before createFromFetch
+    // consumes the body. Reading headers does NOT consume the body stream.
+    const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual' });
+    let headElements: HeadElement[] | null = null;
+    let segmentInfo: SegmentInfo[] | null = null;
+    let params: Record<string, string | string[]> | null = null;
+    let skippedSegments: string[] | null = null;
+    const wrappedPromise = fetchPromise.then((response) => {
+      // Detect server-side redirects. The server returns 204 + X-Timber-Redirect
+      // for RSC payload requests instead of a raw 302, because fetch with
+      // redirect: "manual" turns 302s into opaque redirects (status 0, null body)
+      // which crashes createFromFetch when it tries to read the body stream.
+      const redirectLocation =
+        response.headers.get('X-Timber-Redirect') ||
+        (response.status >= 300 && response.status < 400 ? response.headers.get('Location') : null);
+      if (redirectLocation) {
+        throw new RedirectError(redirectLocation);
+      }
+      headElements = extractHeadElements(response);
+      segmentInfo = extractSegmentInfo(response);
+      params = extractParams(response);
+      skippedSegments = extractSkippedSegments(response);
+      return response;
+    });
+    // Await so headElements/segmentInfo/params are populated before we return.
+    // Also await the decoded payload — createFromFetch returns a thenable
+    // that resolves to the React element tree.
+    await wrappedPromise;
+    const payload = await deps.decodeRsc(wrappedPromise);
+    return { payload, headElements, segmentInfo, params, skippedSegments };
+  }
+  // Test/fallback path: return raw text
+  const response = await deps.fetch(rscUrl, { headers, redirect: 'manual' });
+  // Check for redirect in test path too
+  if (response.status >= 300 && response.status < 400) {
+    const location = response.headers.get('Location');
+    if (location) {
+      throw new RedirectError(location);
+    }
+  }
+  return {
+    payload: await response.text(),
+    headElements: extractHeadElements(response),
+    segmentInfo: extractSegmentInfo(response),
+    params: extractParams(response),
+    skippedSegments: extractSkippedSegments(response),
+  };
+}

package/src/client/segment-cache.ts

@@ -13,6 +13,8 @@ export interface PrefetchResult {
   segmentInfo?: SegmentInfo[] | null;
   /** Route params from X-Timber-Params header for populating useParams(). */
   params?: Record<string, string | string[]> | null;
+  /** Segment paths skipped by the server (for client-side merging). */
+  skippedSegments?: string[] | null;
 }
 
 /**
@@ -70,25 +72,34 @@ export class SegmentCache {
    * Only includes sync segments — async segments are excluded because the
    * server must always re-render them (they may depend on request context).
    *
+   * When mergeableFilter is provided, only segments whose paths are in the
+   * set are included. This ensures the server only skips segments that the
+   * client can actually merge (i.e., segments whose cached element tree
+   * contains an inner SegmentProvider the merger can splice into).
+   *
    * This is a performance optimization only, NOT a security boundary.
    * The server always runs all access.ts files regardless of the state tree.
    */
-  serializeStateTree(): StateTree {
+  serializeStateTree(mergeableFilter?: Set<string>): StateTree {
     const segments: string[] = [];
     if (this.root) {
-      collectSyncSegments(this.root, segments);
+      collectSyncSegments(this.root, segments, mergeableFilter);
     }
     return { segments };
   }
 }
 
 /** Recursively collect sync segment paths from the tree */
-function collectSyncSegments(node: SegmentNode, out: string[]): void {
-  if (!node.isAsync) {
+function collectSyncSegments(
+  node: SegmentNode,
+  out: string[],
+  mergeableFilter?: Set<string>
+): void {
+  if (!node.isAsync && (!mergeableFilter || mergeableFilter.has(node.segment))) {
     out.push(node.segment);
   }
   for (const child of node.children.values()) {
-    collectSyncSegments(child, out);
+    collectSyncSegments(child, out, mergeableFilter);
   }
 }