@timber-js/app 0.2.0-alpha.52 → 0.2.0-alpha.53

package/src/server/ssr-error-entry.ts

@@ -0,0 +1,237 @@
+/**
+ * SSR Error Entry — Renders error pages directly through Fizz (no RSC).
+ *
+ * Error pages bypass the RSC Flight pipeline because Error objects are not
+ * RSC-serializable (React Flight throws "Only plain objects can be passed
+ * to Client Components"). Instead, this entry receives component module
+ * paths, imports them in the SSR environment, builds the element tree,
+ * and renders through Fizz.
+ *
+ * Layout components may be server components that import 'use client'
+ * children — in the SSR environment, client references resolve to actual
+ * component modules (unlike the RSC environment where they're opaque
+ * reference objects). This is why we import in SSR, not pass from RSC.
+ *
+ * Design docs: 10-error-handling.md §"Three-Tier Error Page Rendering"
+ */
+
+// @ts-expect-error — virtual module provided by timber-entries plugin
+import config from 'virtual:timber-config';
+import { createElement, type ReactNode } from 'react';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import {
+  renderSsrStream,
+  renderSsrNodeStream,
+  nodeReadableToWeb,
+  useNodeStreams,
+  buildSsrResponse,
+} from './ssr-render.js';
+import { logRenderError } from './logger.js';
+import { createBufferedTransformStream, injectHead } from './html-injectors.js';
+import { wrapSsrElement } from './ssr-wrappers.js';
+import { registerSsrDataProvider, type SsrData } from '#/client/ssr-data.js';
+import { setCurrentParams } from '#/client/use-params.js';
+import { withSpan } from './tracing.js';
+
+// ─── SSR Data ALS (shared pattern with ssr-entry.ts) ──────────────────────
+
+const ssrDataAls = new AsyncLocalStorage<SsrData>();
+registerSsrDataProvider(() => ssrDataAls.getStore());
+
+// Pre-import Node.js stream modules at module load time (same as ssr-entry.ts).
+let _nodeStreamImports: {
+  createNodeBufferedTransform: typeof import('./node-stream-transforms.js').createNodeBufferedTransform;
+  createNodeHeadInjector: typeof import('./node-stream-transforms.js').createNodeHeadInjector;
+  createNodeMoveSuffixTransform: typeof import('./node-stream-transforms.js').createNodeMoveSuffixTransform;
+  createNodeErrorHandler: typeof import('./node-stream-transforms.js').createNodeErrorHandler;
+  pipeline: typeof import('node:stream/promises').pipeline;
+  PassThrough: typeof import('node:stream').PassThrough;
+} | null = null;
+
+if (useNodeStreams) {
+  try {
+    const [transforms, streamPromises, stream] = await Promise.all([
+      import('./node-stream-transforms.js'),
+      import('node:stream/promises'),
+      import('node:stream'),
+    ]);
+    _nodeStreamImports = {
+      createNodeBufferedTransform: transforms.createNodeBufferedTransform,
+      createNodeHeadInjector: transforms.createNodeHeadInjector,
+      createNodeMoveSuffixTransform: transforms.createNodeMoveSuffixTransform,
+      createNodeErrorHandler: transforms.createNodeErrorHandler,
+      pipeline: streamPromises.pipeline,
+      PassThrough: stream.PassThrough,
+    };
+  } catch {
+    // Fall back to Web Streams path
+  }
+}
+
+/**
+ * Context for SSR-only error page rendering.
+ * Subset of NavContext — no RSC stream, no Flight injection.
+ */
+export interface ErrorPageContext {
+  /** The requested pathname */
+  pathname: string;
+  /** Extracted route params */
+  params: Record<string, string | string[]>;
+  /** Search params from the URL */
+  searchParams: Record<string, string>;
+  /** The committed HTTP status code */
+  statusCode: number;
+  /** Response headers from middleware/proxy */
+  responseHeaders: Headers;
+  /** Pre-rendered metadata HTML to inject before </head> */
+  headHtml: string;
+  /** Inline JS for React's bootstrapScriptContent */
+  bootstrapScriptContent: string;
+  /** Request abort signal */
+  signal?: AbortSignal;
+  /** Request cookies for useCookie() during SSR */
+  cookies?: Map<string, string>;
+  /** Error component props: { error, digest, reset } */
+  errorProps: {
+    error: Error;
+    digest: { code: string; data: unknown } | null;
+    reset: undefined;
+  };
+  /** File path of the error component module (imported in SSR env) */
+  errorComponentPath: string;
+  /** File paths of layout component modules, ordered root → leaf */
+  layoutPaths: string[];
+}
+
+/**
+ * Render an error page directly through Fizz (no RSC Flight stream).
+ *
+ * Imports the error component and layout components in the SSR environment,
+ * builds the element tree, wraps with SSR-specific components (for useId
+ * matching), and renders to HTML.
+ *
+ * Key difference from handleSsr: NO RSC stream decode, NO Flight injection.
+ */
+export async function handleSsrErrorPage(ctx: ErrorPageContext): Promise<Response> {
+  return withSpan('timber.ssr.error-page', { 'timber.environment': 'ssr' }, async () => {
+    const _runtimeConfig = config;
+
+    const ssrData: SsrData = {
+      pathname: ctx.pathname,
+      searchParams: ctx.searchParams,
+      cookies: ctx.cookies ?? new Map(),
+      params: ctx.params,
+    };
+
+    return ssrDataAls.run(ssrData, async () => {
+      setCurrentParams(ctx.params);
+
+      const h = createElement as (...args: unknown[]) => React.ReactElement;
+
+      // Import error component in SSR environment.
+      // In SSR, 'use client' components resolve to actual module functions
+      // (not opaque client references like in RSC).
+      const errorMod = (await import(/* @vite-ignore */ ctx.errorComponentPath)) as Record<
+        string,
+        unknown
+      >;
+      const ErrorComponent = errorMod.default as (...args: unknown[]) => ReactNode;
+
+      // Build innermost element: error component with props
+      let element: React.ReactElement = h(ErrorComponent, ctx.errorProps);
+
+      // Import and wrap with layouts (root → leaf order, wrap inside-out)
+      for (let i = ctx.layoutPaths.length - 1; i >= 0; i--) {
+        const layoutMod = (await import(/* @vite-ignore */ ctx.layoutPaths[i])) as Record<
+          string,
+          unknown
+        >;
+        const LayoutComponent = layoutMod.default as (...args: unknown[]) => ReactNode;
+        element = h(LayoutComponent, null, element);
+      }
+
+      // Wrap with SSR-specific components for useId matching.
+      const hasTopLoader = _runtimeConfig.topLoader?.enabled !== false;
+      const wrappedElement = wrapSsrElement(element, ctx.searchParams, hasTopLoader);
+
+      // Render to HTML — same dual-path as ssr-entry.ts but NO Flight injection.
+      if (_nodeStreamImports) {
+        return renderViaNodeStreams(wrappedElement, ctx, _runtimeConfig);
+      }
+      return renderViaWebStreams(wrappedElement, ctx, _runtimeConfig);
+    });
+  });
+}
+
+// ─── Render Paths ─────────────────────────────────────────────────────────
+
+async function renderViaNodeStreams(
+  element: ReactNode,
+  ctx: ErrorPageContext,
+  runtimeConfig: Record<string, unknown>
+): Promise<Response> {
+  const {
+    createNodeBufferedTransform,
+    createNodeHeadInjector,
+    createNodeMoveSuffixTransform,
+    createNodeErrorHandler,
+    pipeline,
+    PassThrough,
+  } = _nodeStreamImports!;
+
+  const renderTimeoutMs = (runtimeConfig.renderTimeoutMs as number | undefined) ?? undefined;
+
+  let nodeHtmlStream: import('node:stream').Readable;
+  try {
+    nodeHtmlStream = await renderSsrNodeStream(element, {
+      bootstrapScriptContent: ctx.bootstrapScriptContent || undefined,
+      signal: ctx.signal,
+      renderTimeoutMs,
+    });
+  } catch (renderError) {
+    logRenderError({ method: '', path: '', error: renderError });
+    return new Response(null, { status: ctx.statusCode, headers: ctx.responseHeaders });
+  }
+
+  // Pipeline: buffer → errorHandler → headInjector → moveSuffix → output
+  // NO flightInjector — there's no RSC stream to inline.
+  const bufferedTransform = createNodeBufferedTransform();
+  const errorHandler = createNodeErrorHandler(ctx.signal);
+  const headInjector = createNodeHeadInjector(ctx.headHtml);
+  const moveSuffix = createNodeMoveSuffixTransform();
+
+  const output = new PassThrough();
+  pipeline(nodeHtmlStream, bufferedTransform, errorHandler, headInjector, moveSuffix, output).catch(
+    () => {}
+  );
+
+  const webStream = nodeReadableToWeb(output);
+  return buildSsrResponse(webStream, ctx.statusCode, ctx.responseHeaders);
+}
+
+async function renderViaWebStreams(
+  element: ReactNode,
+  ctx: ErrorPageContext,
+  runtimeConfig: Record<string, unknown>
+): Promise<Response> {
+  const renderTimeoutMs = (runtimeConfig.renderTimeoutMs as number | undefined) ?? undefined;
+
+  let htmlStream: ReadableStream<Uint8Array>;
+  try {
+    htmlStream = await renderSsrStream(element, {
+      bootstrapScriptContent: ctx.bootstrapScriptContent || undefined,
+      signal: ctx.signal,
+      renderTimeoutMs,
+    });
+  } catch (renderError) {
+    logRenderError({ method: '', path: '', error: renderError });
+    return new Response(null, { status: ctx.statusCode, headers: ctx.responseHeaders });
+  }
+
+  let outputStream = htmlStream.pipeThrough(createBufferedTransformStream());
+  outputStream = injectHead(outputStream, ctx.headHtml);
+  return buildSsrResponse(outputStream, ctx.statusCode, ctx.responseHeaders);
+}
+
+export default handleSsrErrorPage;

package/src/shared/merge-search-params.ts

@@ -27,10 +27,16 @@ export function mergePreservedSearchParams(
   const currentParams = new URLSearchParams(currentSearch);
   if (currentParams.size === 0) return targetHref;
 
+  // Split hash fragment from target before processing query params.
+  // Hash must come after query string: /path?query=value#hash
+  const hashIdx = targetHref.indexOf('#');
+  const hrefWithoutHash = hashIdx >= 0 ? targetHref.slice(0, hashIdx) : targetHref;
+  const hash = hashIdx >= 0 ? targetHref.slice(hashIdx) : '';
+
   // Split target into path and existing query
-  const qIdx = targetHref.indexOf('?');
-  const targetPath = qIdx >= 0 ? targetHref.slice(0, qIdx) : targetHref;
-  const targetParams = new URLSearchParams(qIdx >= 0 ? targetHref.slice(qIdx + 1) : '');
+  const qIdx = hrefWithoutHash.indexOf('?');
+  const targetPath = qIdx >= 0 ? hrefWithoutHash.slice(0, qIdx) : hrefWithoutHash;
+  const targetParams = new URLSearchParams(qIdx >= 0 ? hrefWithoutHash.slice(qIdx + 1) : '');
 
   // Collect params to preserve (that aren't already in the target)
   const merged = new URLSearchParams(targetParams);
@@ -44,5 +50,6 @@ export function mergePreservedSearchParams(
   }
 
   const qs = merged.toString();
-  return qs ? `${targetPath}?${qs}` : targetPath;
+  const pathWithQuery = qs ? `${targetPath}?${qs}` : targetPath;
+  return pathWithQuery + hash;
 }

package/src/shims/navigation.ts

@@ -9,6 +9,7 @@
 // Hooks (client-side — imported from public barrel for module singleton)
 export {
   useSegmentParams,
+  useSegmentParams as useParams,
   usePathname,
   useSearchParams,
   useRouter,

package/LICENSE

@@ -1,8 +0,0 @@
-DONTFUCKINGUSE LICENSE
-
-Copyright (c) 2025 Daniel Saewitz
-
-This software may not be used, copied, modified, merged, published,
-distributed, sublicensed, or sold by anyone other than the copyright holder.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/dist/_chunks/segment-context-DBn-nrMN.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"segment-context-DBn-nrMN.js","names":[],"sources":["../../src/shared/merge-search-params.ts","../../src/client/segment-context.ts"],"sourcesContent":["/**\n * Shared utility for merging preserved search params into a target URL.\n *\n * Used by both <Link> (client) and redirect() (server). Extracted to a shared\n * module to avoid importing client code ('use client') from server modules.\n */\n\n/**\n * Merge preserved search params from the current URL into a target href.\n *\n * When `preserve` is `true`, all current search params are merged.\n * When `preserve` is a `string[]`, only the named params are merged.\n *\n * The target href's own search params take precedence — preserved params\n * are only added if the target doesn't already define them.\n *\n * @param targetHref - The resolved target href (may already contain query string)\n * @param currentSearch - The current URL's search string (e.g. \"?private=access&page=2\")\n * @param preserve - `true` to preserve all, or `string[]` to preserve specific params\n * @returns The target href with preserved search params merged in\n */\nexport function mergePreservedSearchParams(\n  targetHref: string,\n  currentSearch: string,\n  preserve: true | string[]\n): string {\n  const currentParams = new URLSearchParams(currentSearch);\n  if (currentParams.size === 0) return targetHref;\n\n  // Split target into path and existing query\n  const qIdx = targetHref.indexOf('?');\n  const targetPath = qIdx >= 0 ? targetHref.slice(0, qIdx) : targetHref;\n  const targetParams = new URLSearchParams(qIdx >= 0 ? targetHref.slice(qIdx + 1) : '');\n\n  // Collect params to preserve (that aren't already in the target)\n  const merged = new URLSearchParams(targetParams);\n  for (const [key, value] of currentParams) {\n    // Only preserve if: (a) not already in target, and (b) included in preserve list\n    if (!targetParams.has(key)) {\n      if (preserve === true || preserve.includes(key)) {\n        merged.append(key, value);\n      }\n    }\n  }\n\n  const qs = merged.toString();\n  return qs ? `${targetPath}?${qs}` : targetPath;\n}\n","/**\n * Segment Context — provides layout segment position for useSelectedLayoutSegment hooks.\n *\n * Each layout in the segment tree is wrapped with a SegmentProvider that stores\n * the URL segments from root to the current layout level. The hooks read this\n * context to determine which child segments are active below the calling layout.\n *\n * The context value is intentionally minimal: just the segment path array and\n * parallel route keys. No internal cache details are exposed.\n *\n * Design docs: design/19-client-navigation.md, design/14-ecosystem.md\n */\n\n'use client';\n\nimport { createContext, useContext, createElement, useMemo } from 'react';\n\n// ─── Types ───────────────────────────────────────────────────────\n\nexport interface SegmentContextValue {\n  /** URL segments from root to this layout (e.g. ['', 'dashboard', 'settings']) */\n  segments: string[];\n  /** Parallel route slot keys available at this layout level (e.g. ['sidebar', 'modal']) */\n  parallelRouteKeys: string[];\n}\n\n// ─── Context ─────────────────────────────────────────────────────\n\nconst SegmentContext = createContext<SegmentContextValue | null>(null);\n\n/** Read the segment context. Returns null if no provider is above this component. */\nexport function useSegmentContext(): SegmentContextValue | null {\n  return useContext(SegmentContext);\n}\n\n// ─── Provider ────────────────────────────────────────────────────\n\ninterface SegmentProviderProps {\n  segments: string[];\n  /**\n   * Unique identifier for this segment, used by the client-side segment\n   * merger for element caching. For route groups this includes the group\n   * name (e.g., \"/(marketing)\") since groups share their parent's urlPath.\n   * Falls back to the reconstructed path from `segments` if not provided.\n   */\n  segmentId?: string;\n  parallelRouteKeys: string[];\n  children: React.ReactNode;\n}\n\n/**\n * Wraps each layout to provide segment position context.\n * Injected by rsc-entry.ts during element tree construction.\n */\nexport function SegmentProvider({\n  segments,\n  segmentId: _segmentId,\n  parallelRouteKeys,\n  children,\n}: SegmentProviderProps) {\n  const value = useMemo(\n    () => ({ segments, parallelRouteKeys }),\n    // segments and parallelRouteKeys are static per layout — they don't change\n    // across navigations. The layout's position in the tree is fixed.\n    // Intentionally using derived keys — segments/parallelRouteKeys are static per layout\n    [segments.join('/'), parallelRouteKeys.join(',')]\n  );\n  return createElement(SegmentContext.Provider, { value }, children);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,2BACd,YACA,eACA,UACQ;CACR,MAAM,gBAAgB,IAAI,gBAAgB,cAAc;AACxD,KAAI,cAAc,SAAS,EAAG,QAAO;CAGrC,MAAM,OAAO,WAAW,QAAQ,IAAI;CACpC,MAAM,aAAa,QAAQ,IAAI,WAAW,MAAM,GAAG,KAAK,GAAG;CAC3D,MAAM,eAAe,IAAI,gBAAgB,QAAQ,IAAI,WAAW,MAAM,OAAO,EAAE,GAAG,GAAG;CAGrF,MAAM,SAAS,IAAI,gBAAgB,aAAa;AAChD,MAAK,MAAM,CAAC,KAAK,UAAU,cAEzB,KAAI,CAAC,aAAa,IAAI,IAAI;MACpB,aAAa,QAAQ,SAAS,SAAS,IAAI,CAC7C,QAAO,OAAO,KAAK,MAAM;;CAK/B,MAAM,KAAK,OAAO,UAAU;AAC5B,QAAO,KAAK,GAAG,WAAW,GAAG,OAAO;;;;;;;;;;;;;;;;AClBtC,IAAM,iBAAiB,cAA0C,KAAK;;AAGtE,SAAgB,oBAAgD;AAC9D,QAAO,WAAW,eAAe;;;;;;AAsBnC,SAAgB,gBAAgB,EAC9B,UACA,WAAW,YACX,mBACA,YACuB;CACvB,MAAM,QAAQ,eACL;EAAE;EAAU;EAAmB,GAItC,CAAC,SAAS,KAAK,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC,CAClD;AACD,QAAO,cAAc,eAAe,UAAU,EAAE,OAAO,EAAE,SAAS"}