@timber-js/app 0.1.5 → 0.1.7

package/dist/server/rsc-entry/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA2EA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AA0nBD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;8BAtgBpD,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AAwgBhD,wBAAiE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/server/rsc-entry/index.ts"],"names":[],"mappings":"AA2EA;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAE/F;AAkpBD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;8BA9hBpD,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC;AAgiBhD,wBAAiE"}

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;AA6BH;;;;;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;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAwEnB;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"ssr-entry.d.ts","sourceRoot":"","sources":["../../src/server/ssr-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwCH;;;;;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;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,SAAS,CAC7B,SAAS,EAAE,cAAc,CAAC,UAAU,CAAC,EACrC,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,QAAQ,CAAC,CAwEnB;AAED,eAAe,SAAS,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/src/client/browser-entry.ts

@@ -38,6 +38,16 @@ import { TimberNuqsAdapter } from './nuqs-adapter.js';
 import { isPageUnloading } from './unload-guard.js';
 import { setCurrentParams } from './use-params.js';
 import { ON_NAVIGATE_KEY } from './link-navigate-interceptor.js';
+import { registerUseQueryStatesHook } from '#/search-params/create.js';
+import { useQueryStates as clientUseQueryStates } from './use-query-states.js';
+
+// ─── useQueryStates Registration ─────────────────────────────────
+// Register the client-side useQueryStates implementation so that
+// definition.useQueryStates() works in 'use client' components.
+// See LOCAL-297.
+registerUseQueryStatesHook((codecs, options, urlKeys) => {
+  return clientUseQueryStates(codecs, options, urlKeys);
+});
 
 // ─── Server Action Dispatch ──────────────────────────────────────
 

package/src/search-params/create.ts

@@ -106,6 +106,33 @@ export interface SearchParamsDefinition<T extends Record<string, unknown>> {
   readonly _type?: T;
 }
 
+// ---------------------------------------------------------------------------
+// useQueryStates hook registration
+// ---------------------------------------------------------------------------
+
+/**
+ * The registered useQueryStates implementation.
+ *
+ * null in the RSC environment (hooks can't run during server rendering).
+ * Set by:
+ *   - browser-entry.ts → registers the nuqs-backed client implementation
+ *   - ssr-entry.ts → registers a static SSR adapter
+ *
+ * The registration pattern avoids importing client-only code (nuqs, React hooks)
+ * into the shared search-params module, which is loaded in all three environments.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type UseQueryStatesHook = (codecs: any, options: any, urlKeys: any) => [any, any];
+let _useQueryStatesHook: UseQueryStatesHook | null = null;
+
+/**
+ * Register the runtime useQueryStates implementation.
+ * Called by browser-entry (client) and ssr-entry (SSR).
+ */
+export function registerUseQueryStatesHook(hook: UseQueryStatesHook): void {
+  _useQueryStatesHook = hook;
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -288,14 +315,19 @@ function buildDefinition<T extends Record<string, unknown>>(
   }
 
   // ---- useQueryStates ----
-  // This is a placeholder that will be replaced by the client runtime.
-  // At import time in a server context, calling this throws.
-  // The actual implementation wraps nuqs and lives in @timber-js/app/client.
-  function useQueryStates(_options?: QueryStatesOptions): [T, SetParams<T>] {
-    throw new Error(
-      'useQueryStates() can only be called in a client component. ' +
-        'Import from @timber-js/app/client instead.'
-    );
+  // Delegates to the registered runtime hook (client or SSR).
+  // In the RSC environment, no hook is registered — calling this throws.
+  // On the client, browser-entry.ts registers the nuqs-backed implementation.
+  // In SSR, ssr-entry.ts registers a static adapter.
+  function useQueryStates(options?: QueryStatesOptions): [T, SetParams<T>] {
+    const hook = _useQueryStatesHook;
+    if (!hook) {
+      throw new Error(
+        'useQueryStates() can only be called in a client component. ' +
+          'Import from @timber-js/app/client instead.'
+      );
+    }
+    return hook(codecMap, options, Object.freeze({ ...urlKeys })) as [T, SetParams<T>];
   }
 
   const definition: SearchParamsDefinition<T> = {

package/src/server/error-formatter.ts

@@ -147,6 +147,18 @@ function extractErrorHint(message: string): string | null {
     return 'A component resolved to undefined/null — check default exports and import paths';
   }
 
+  // "Invalid hook call" — hooks called outside React's render context.
+  // In RSC, this typically means a 'use client' component was executed as a
+  // server component instead of being serialized as a client reference.
+  if (message.includes('Invalid hook call')) {
+    return (
+      'A hook was called outside of a React component render. ' +
+      'If this is a \'use client\' component, ensure the directive is at the very top of the file ' +
+      '(before any imports) and that @vitejs/plugin-rsc is loaded correctly. ' +
+      'Barrel re-exports from non-\'use client\' files do not propagate the directive.'
+    );
+  }
+
   return null;
 }
 

package/src/server/rsc-entry/index.ts

@@ -409,6 +409,30 @@ async function renderRoute(
               status: error.status,
             });
           }
+          // Dev diagnostic: detect "Invalid hook call" errors which indicate
+          // a 'use client' component is being executed during RSC rendering
+          // instead of being serialized as a client reference. This happens when
+          // the RSC plugin's transform doesn't detect the directive — e.g., the
+          // directive isn't at the very top of the file, or the component is
+          // re-exported through a barrel file without 'use client'.
+          // See LOCAL-297.
+          if (
+            process.env.NODE_ENV !== 'production' &&
+            error instanceof Error &&
+            error.message.includes('Invalid hook call')
+          ) {
+            console.error(
+              '[timber] A React hook was called during RSC rendering. This usually means a ' +
+                "'use client' component is being executed as a server component instead of " +
+                'being serialized as a client reference.\n\n' +
+                'Common causes:\n' +
+                "  1. The 'use client' directive is not the FIRST statement in the file (before any imports)\n" +
+                "  2. The component is re-exported through a barrel file (index.ts) that lacks 'use client'\n" +
+                '  3. @vitejs/plugin-rsc is not loaded or is misconfigured\n\n' +
+                `Request: ${_req.method} ${new URL(_req.url).pathname}`
+            );
+          }
+
           // Track unhandled errors for pre-flush handling (500 status)
           if (!renderError) {
             renderError = { error, status: 500 };

package/src/server/ssr-entry.ts

@@ -25,6 +25,8 @@ import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
 import { withSpan } from './tracing.js';
 import { setCurrentParams } from '#/client/use-params.js';
 import { registerSsrDataProvider, type SsrData } from '#/client/ssr-data.js';
+import { registerUseQueryStatesHook } from '#/search-params/create.js';
+import { useQueryStates as clientUseQueryStates } from '#/client/use-query-states.js';
 
 // ─── SSR Data ALS ─────────────────────────────────────────────────────────
 //
@@ -39,6 +41,15 @@ const ssrDataAls = new AsyncLocalStorage<SsrData>();
 // Register the ALS-backed provider so getSsrData() reads from ALS.
 registerSsrDataProvider(() => ssrDataAls.getStore());
 
+// Register the useQueryStates hook for SSR.
+// During SSR, 'use client' components that call definition.useQueryStates()
+// need the real nuqs-backed implementation (which uses React hooks that work
+// during SSR). Without this, the placeholder in create.ts throws.
+// See LOCAL-297.
+registerUseQueryStatesHook((codecs, options, urlKeys) => {
+  return clientUseQueryStates(codecs, options, urlKeys);
+});
+
 /**
  * Navigation context passed from the RSC environment to SSR.
  *