@timber-js/app 0.2.0-alpha.49 → 0.2.0-alpha.50

package/dist/server/ssr-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA8EH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE;QACZ,gFAAgF;QAChF,QAAQ,EAAE,MAAM,CAAC;QACjB,uDAAuD;QACvD,OAAO,EAAE,MAAM,CAAC;QAChB,gEAAgE;QAChE,MAAM,EAAE,MAAM,CAAC;QACf,wEAAwE;QACxE,UAAU,EAAE,MAAM,CAAC;QACnB,+CAA+C;QAC/C,OAAO,EAAE,MAAM,CAAC;QAChB,sDAAsD;QACtD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAmLnB;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA8EH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,iCAAiC;IACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,eAAe,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,sBAAsB,EAAE,MAAM,CAAC;IAC/B,qEAAqE;IACrE,SAAS,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACvC;;;0DAGsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;iFAE6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;4DACwD;IACxD,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE;QACZ,gFAAgF;QAChF,QAAQ,EAAE,MAAM,CAAC;QACjB,uDAAuD;QACvD,OAAO,EAAE,MAAM,CAAC;QAChB,gEAAgE;QAChE,MAAM,EAAE,MAAM,CAAC;QACf,wEAAwE;QACxE,UAAU,EAAE,MAAM,CAAC;QACnB,+CAA+C;QAC/C,OAAO,EAAE,MAAM,CAAC;QAChB,sDAAsD;QACtD,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAuLnB;AAED,eAAe,SAAS,CAAC"}

package/dist/server/ssr-wrappers.d.ts

@@ -0,0 +1,50 @@
+/**
+ * SSR wrapper components that match the client-side component tree depth.
+ *
+ * During hydration, React's useId() generates deterministic IDs based on
+ * the component's position in the fiber tree. If the SSR tree has fewer
+ * wrapper components than the client hydration tree, every useId() call
+ * produces different IDs — causing hydration mismatches in libraries like
+ * Radix UI that rely on useId() internally.
+ *
+ * The client tree (browser-entry.ts) wraps the RSC element with:
+ *   TransitionRoot → PendingNavigationProvider → Fragment(TopLoader, ...) →
+ *     TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider → element
+ *
+ * The SSR tree must produce the same component boundaries. These wrappers
+ * are no-op components that render children directly but exist as fiber
+ * nodes to match the client's tree depth.
+ *
+ * Related issues: facebook/react#24669, radix-ui/primitives#3700
+ * See design/02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
+ */
+import { type ReactNode } from 'react';
+/**
+ * Wrap the SSR element tree with the same component boundaries as the
+ * client hydration tree. This ensures useId() generates matching IDs
+ * on both sides.
+ *
+ * Client tree (browser-entry.ts):
+ *   TransitionRoot
+ *     → PendingNavigationProvider
+ *       → Fragment(TopLoader, element)
+ *         → TimberNuqsAdapter
+ *           → NuqsAdapterProvider (from createAdapterProvider)
+ *             → NavigationProvider
+ *               → [RSC element]
+ *
+ * SSR tree (this function):
+ *   SsrTransitionRoot
+ *     → SsrPendingProvider
+ *       → Fragment(SsrTopLoader, element)
+ *         → SsrNuqsWrapper
+ *           → NuqsAdapterProvider (from withNuqsSsrAdapter → createAdapterProvider)
+ *             → SsrNavigationProvider
+ *               → [RSC element]
+ *
+ * @param element - The decoded RSC element
+ * @param searchParams - Request search params for nuqs SSR adapter
+ * @param hasTopLoader - Whether the top loader is enabled (must match client config)
+ */
+export declare function wrapSsrElement(element: ReactNode, searchParams: Record<string, string>, hasTopLoader: boolean): ReactNode;
+//# sourceMappingURL=ssr-wrappers.d.ts.map

package/dist/server/ssr-wrappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr-wrappers.d.ts","sourceRoot":"","sources":["../../src/server/ssr-wrappers.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAwEhE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,SAAS,EAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,YAAY,EAAE,OAAO,GACpB,SAAS,CAcX"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.49",
+  "version": "0.2.0-alpha.50",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/server/ssr-entry.ts

@@ -31,7 +31,7 @@ import {
 import { logRenderError } from './logger.js';
 import { SsrStreamError } from './primitives.js';
 import { createBufferedTransformStream, injectHead, injectRscPayload } from './html-injectors.js';
-import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
+import { wrapSsrElement } from './ssr-wrappers.js';
 import { withSpan } from './tracing.js';
 import { setCurrentParams } from '#/client/use-params.js';
 import { registerSsrDataProvider, type SsrData } from '#/client/ssr-data.js';
@@ -226,9 +226,13 @@ export async function handleSsr(
       }
       const _decodeEnd = performance.now();
 
-      // Wrap with a server-safe nuqs adapter so that 'use client' components
-      // that call nuqs hooks (useQueryStates, useQueryState) can SSR correctly.
-      const wrappedElement = withNuqsSsrAdapter(navContext.searchParams, element);
+      // Wrap with the same component tree structure as the client hydration
+      // tree (TransitionRoot → PendingNavigationProvider → TopLoader →
+      // TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider).
+      // This ensures useId() produces matching IDs on both sides, preventing
+      // hydration mismatches in libraries like Radix UI. See TIM-532.
+      const hasTopLoader = _runtimeConfig.topLoader?.enabled !== false;
+      const wrappedElement = wrapSsrElement(element, navContext.searchParams, hasTopLoader);
 
       // Render to HTML stream (waits for onShellReady).
       //

package/src/server/ssr-wrappers.tsx

@@ -0,0 +1,139 @@
+/**
+ * SSR wrapper components that match the client-side component tree depth.
+ *
+ * During hydration, React's useId() generates deterministic IDs based on
+ * the component's position in the fiber tree. If the SSR tree has fewer
+ * wrapper components than the client hydration tree, every useId() call
+ * produces different IDs — causing hydration mismatches in libraries like
+ * Radix UI that rely on useId() internally.
+ *
+ * The client tree (browser-entry.ts) wraps the RSC element with:
+ *   TransitionRoot → PendingNavigationProvider → Fragment(TopLoader, ...) →
+ *     TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider → element
+ *
+ * The SSR tree must produce the same component boundaries. These wrappers
+ * are no-op components that render children directly but exist as fiber
+ * nodes to match the client's tree depth.
+ *
+ * Related issues: facebook/react#24669, radix-ui/primitives#3700
+ * See design/02-rendering-pipeline.md §"RSC → SSR → Client Hydration"
+ */
+
+import { createElement, Fragment, type ReactNode } from 'react';
+import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
+
+/**
+ * SSR equivalent of TransitionRoot.
+ *
+ * On the client, TransitionRoot uses useState + useTransition and renders:
+ *   PendingNavigationProvider(Fragment(TopLoader, element))
+ *
+ * This SSR version matches the component boundary depth without client
+ * hooks. It renders SsrPendingProvider → Fragment(SsrTopLoader, children).
+ */
+function SsrTransitionRoot({
+  children,
+  hasTopLoader,
+}: {
+  children: ReactNode;
+  hasTopLoader: boolean;
+}): ReactNode {
+  if (hasTopLoader) {
+    return createElement(
+      SsrPendingProvider,
+      null,
+      createElement(Fragment, null, createElement(SsrTopLoader, null), children)
+    );
+  }
+  return createElement(SsrPendingProvider, null, children);
+}
+
+/**
+ * SSR equivalent of PendingNavigationProvider.
+ * Matches the context.Provider component boundary on the client.
+ */
+function SsrPendingProvider({ children }: { children: ReactNode }): ReactNode {
+  return children as ReactNode;
+}
+
+/**
+ * SSR equivalent of TopLoader.
+ * Exists as a fiber node to match the client tree depth; renders nothing.
+ */
+function SsrTopLoader(): ReactNode {
+  return null;
+}
+
+/**
+ * SSR equivalent of NavigationProvider.
+ * Matches the context.Provider component boundary on the client.
+ */
+function SsrNavigationProvider({ children }: { children: ReactNode }): ReactNode {
+  return children as ReactNode;
+}
+
+/**
+ * SSR equivalent of TimberNuqsAdapter component boundary.
+ * The actual NuqsAdapterProvider (from createAdapterProvider) is added
+ * inside this wrapper via withNuqsSsrAdapter, matching the client's
+ * TimberNuqsAdapter → NuqsAdapterProvider nesting.
+ */
+function SsrNuqsWrapper({
+  searchParams,
+  children,
+}: {
+  searchParams: Record<string, string>;
+  children: ReactNode;
+}): ReactNode {
+  // withNuqsSsrAdapter creates a NuqsAdapterProvider (from createAdapterProvider),
+  // which is the same component factory used by TimberNuqsAdapter on the client.
+  // Both produce the same internal component boundary depth.
+  return withNuqsSsrAdapter(searchParams, children);
+}
+
+/**
+ * Wrap the SSR element tree with the same component boundaries as the
+ * client hydration tree. This ensures useId() generates matching IDs
+ * on both sides.
+ *
+ * Client tree (browser-entry.ts):
+ *   TransitionRoot
+ *     → PendingNavigationProvider
+ *       → Fragment(TopLoader, element)
+ *         → TimberNuqsAdapter
+ *           → NuqsAdapterProvider (from createAdapterProvider)
+ *             → NavigationProvider
+ *               → [RSC element]
+ *
+ * SSR tree (this function):
+ *   SsrTransitionRoot
+ *     → SsrPendingProvider
+ *       → Fragment(SsrTopLoader, element)
+ *         → SsrNuqsWrapper
+ *           → NuqsAdapterProvider (from withNuqsSsrAdapter → createAdapterProvider)
+ *             → SsrNavigationProvider
+ *               → [RSC element]
+ *
+ * @param element - The decoded RSC element
+ * @param searchParams - Request search params for nuqs SSR adapter
+ * @param hasTopLoader - Whether the top loader is enabled (must match client config)
+ */
+export function wrapSsrElement(
+  element: ReactNode,
+  searchParams: Record<string, string>,
+  hasTopLoader: boolean
+): ReactNode {
+  // Build inside-out to match the client's createElement chain:
+  //   NavigationProvider(TimberNuqsAdapter(element))
+  //   → passed as initial to TransitionRoot
+  //   → TransitionRoot renders PendingNavigationProvider(Fragment(TopLoader, initial))
+
+  // 1. Innermost: NavigationProvider equivalent
+  const withNav = createElement(SsrNavigationProvider, null, element);
+
+  // 2. TimberNuqsAdapter equivalent (wraps withNuqsSsrAdapter for the actual nuqs provider)
+  const withNuqs = createElement(SsrNuqsWrapper, { searchParams, children: withNav });
+
+  // 3. Outermost: TransitionRoot equivalent (PendingNavigationProvider + TopLoader)
+  return createElement(SsrTransitionRoot, { hasTopLoader, children: withNuqs });
+}