@real-router/preact 0.11.1 → 0.12.0

package/dist/esm/ssr.d.mts

@@ -0,0 +1,169 @@
+import { ComponentChildren } from "preact";
+
+//#region src/components/ClientOnly.d.ts
+interface ClientOnlyProps {
+  readonly children: ComponentChildren;
+  readonly fallback?: ComponentChildren;
+}
+declare function ClientOnly({
+  children,
+  fallback
+}: ClientOnlyProps): ComponentChildren;
+//#endregion
+//#region src/components/ServerOnly.d.ts
+interface ServerOnlyProps {
+  readonly children: ComponentChildren;
+  readonly fallback?: ComponentChildren;
+}
+declare function ServerOnly({
+  children,
+  fallback
+}: ServerOnlyProps): ComponentChildren;
+//#endregion
+//#region src/components/Await.d.ts
+interface AwaitProps<T> {
+  /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
+  readonly name: string;
+  /** Render the resolved value. Suspends while pending; throws inside the
+   * nearest Error Boundary on rejection. */
+  readonly children: (value: T) => ComponentChildren;
+}
+/**
+ * Reads `useDeferred(name)` and hands the resolved value to the render-prop
+ * via Preact's `<Suspense>`-throwing convention. Wrap in `<Streamed>` (or
+ * `<Suspense>` from `preact/compat`).
+ *
+ * ```tsx
+ * <Streamed fallback={<Spinner />}>
+ *   <Await<Review[]> name="reviews">
+ *     {(reviews) => <ReviewList items={reviews} />}
+ *   </Await>
+ * </Streamed>
+ * ```
+ */
+declare function Await<T = unknown>({
+  name,
+  children
+}: AwaitProps<T>): ComponentChildren;
+//#endregion
+//#region src/components/Streamed.d.ts
+interface StreamedProps {
+  /** Shown while any descendant `<Await>` / `use(promise)`-equivalent suspends. */
+  readonly fallback: ComponentChildren;
+  readonly children: ComponentChildren;
+}
+/**
+ * Cross-adapter alias for `<Suspense fallback={…}>` from `preact/compat`.
+ * Pairs with `<Await>` for symmetry with the React/Solid/Svelte/Vue/Angular
+ * SSR streaming naming.
+ *
+ * Preact's `Suspense` is part of `preact/compat` (experimental). For
+ * production streaming the preact-render-to-string toolchain is required.
+ */
+declare function Streamed({
+  fallback,
+  children
+}: StreamedProps): ComponentChildren;
+//#endregion
+//#region src/components/HttpStatusCode.d.ts
+interface HttpStatusCodeProps {
+  /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */
+  readonly code: number;
+}
+/**
+ * Render-time HTTP status declaration. Mount inside a route component (typical
+ * use case: a glob `*` route's NotFound page) when the status is decided by
+ * the rendered tree rather than a loader.
+ *
+ * Writes `code` to the nearest `<HttpStatusProvider>`'s sink during render and
+ * returns `null`. With no provider mounted (the standard client-side case)
+ * the component is a silent no-op — same component tree hydrates without
+ * touching the DOM or warning about mismatches.
+ *
+ * Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
+ * working as before; this component covers render-time decisions only.
+ *
+ * Last write wins when several `<HttpStatusCode />` instances mount in the
+ * same render pass — sink reflects the last component that ran.
+ *
+ * ```tsx
+ * // entry-server.tsx
+ * import { renderToString } from "preact-render-to-string";
+ * import { createHttpStatusSink, HttpStatusProvider } from "@real-router/preact/ssr";
+ *
+ * const sink = createHttpStatusSink();
+ * const html = renderToString(
+ *   <HttpStatusProvider sink={sink}>
+ *     <RouterProvider router={router}>
+ *       <App />
+ *     </RouterProvider>
+ *   </HttpStatusProvider>,
+ * );
+ * response.status(sink.code ?? 200).send(html);
+ * ```
+ *
+ * **Streaming SSR (`renderToReadableStream`):** the response status MUST be
+ * sent before the first body byte flushes. If `<HttpStatusCode />` is mounted
+ * inside a late-resolving `<Suspense>` boundary, the sink write may happen
+ * AFTER the headers are already on the wire — the override is then lost.
+ * Mount the component in the shell (above every `<Suspense>` that could
+ * delay it). For non-streaming SSR (`renderToString` / `renderToStringAsync`)
+ * there is no such ordering concern.
+ *
+ * **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on
+ * `NaN`, `0`, negative values, or values `> 999` — this surfaces as a 5xx /
+ * dropped connection, not silent corruption. Pass a real HTTP status integer
+ * (commonly 4xx/5xx; 100-999 is what Node accepts).
+ */
+declare function HttpStatusCode({
+  code
+}: HttpStatusCodeProps): ComponentChildren;
+//#endregion
+//#region src/utils/createHttpStatusSink.d.ts
+/**
+ * Render-scoped HTTP status sink. Created per request on the server, passed to
+ * `<HttpStatusProvider sink={...}>`, and read after `renderToString` (or the
+ * Preact streaming helper) to apply the value to the HTTP response.
+ *
+ * Last write wins: if the rendered tree mounts more than one
+ * `<HttpStatusCode />`, the value reflects the last component that ran during
+ * the render pass.
+ *
+ * No-op on the client — `<HttpStatusCode />` reads the optional context and
+ * skips the write when no provider is mounted, so the same component tree can
+ * be hydrated without changing behaviour.
+ *
+ * Constraints:
+ * - **Per-request only.** Don't share a sink across requests; the rendered
+ *   tree mutates `code` in place. Module-level singletons leak status
+ *   between concurrent requests.
+ * - **Don't `Object.freeze` the sink.** The component writes to `.code`;
+ *   freezing makes the assignment throw under ESM strict mode.
+ */
+interface HttpStatusSink {
+  code: number | undefined;
+}
+declare function createHttpStatusSink(): HttpStatusSink;
+//#endregion
+//#region src/components/HttpStatusProvider.d.ts
+interface HttpStatusProviderProps {
+  readonly sink: HttpStatusSink;
+  readonly children: ComponentChildren;
+}
+declare function HttpStatusProvider({
+  sink,
+  children
+}: HttpStatusProviderProps): ComponentChildren;
+//#endregion
+//#region src/hooks/useDeferred.d.ts
+/**
+ * Read a deferred promise published by `defer({ deferred: { <key>: Promise } })`
+ * inside an SSR data loader. Mirror of `@real-router/react/ssr` `useDeferred`
+ * — same `state.context.ssrDataDeferred` contract, same NEVER-on-missing
+ * fallback. Pair with `<Await>` (this package) which adds Preact-side
+ * promise-status tracking since Preact 10 has no `use(promise)` analogue.
+ */
+declare function useDeferred<T = unknown>(key: string): Promise<T>;
+//#endregion
+export { Await, type AwaitProps, ClientOnly, type ClientOnlyProps, HttpStatusCode, type HttpStatusCodeProps, HttpStatusProvider, type HttpStatusProviderProps, type HttpStatusSink, ServerOnly, type ServerOnlyProps, Streamed, type StreamedProps, createHttpStatusSink, useDeferred };
+//# sourceMappingURL=ssr.d.mts.map

package/dist/esm/ssr.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr.d.mts","names":[],"sources":["../../src/components/ClientOnly.tsx","../../src/components/ServerOnly.tsx","../../src/components/Await.tsx","../../src/components/Streamed.tsx","../../src/components/HttpStatusCode.tsx","../../src/utils/createHttpStatusSink.ts","../../src/components/HttpStatusProvider.tsx","../../src/hooks/useDeferred.tsx"],"mappings":";;;UAIiB,eAAA;EAAA,SACN,QAAA,EAAU,iBAAA;EAAA,SACV,QAAA,GAAW,iBAAA;AAAA;AAAA,iBAGN,UAAA,CAAA;EACd,QAAA;EACA;AAAA,GACC,eAAA,GAAkB,iBAAA;;;UCRJ,eAAA;EAAA,SACN,QAAA,EAAU,iBAAA;EAAA,SACV,QAAA,GAAW,iBAAA;AAAA;AAAA,iBAGN,UAAA,CAAA;EACd,QAAA;EACA;AAAA,GACC,eAAA,GAAkB,iBAAA;;;UC6CJ,UAAA;;WAEN,IAAA;EFvDqB;;EAAA,SE0DrB,QAAA,GAAW,KAAA,EAAO,CAAA,KAAM,iBAAA;AAAA;;;;;;AFrDnC;;;;;;;;iBEqEgB,KAAA,aAAA,CAAA;EACd,IAAA;EACA;AAAA,GACC,UAAA,CAAW,CAAA,IAAK,iBAAA;;;UC7EF,aAAA;;WAEN,QAAA,EAAU,iBAAA;EAAA,SACV,QAAA,EAAU,iBAAA;AAAA;;;;;;;;AHErB;iBGSgB,QAAA,CAAA;EACd,QAAA;EACA;AAAA,GACC,aAAA,GAAgB,iBAAA;;;UCfF,mBAAA;;WAEN,IAAA;AAAA;;;;;;;;;AJCX;;;;;;;;;;;;;;;;;;;;ACLA;;;;;;;;;;AAKA;;;;;;;iBG+CgB,cAAA,CAAA;EACd;AAAA,GACC,mBAAA,GAAsB,iBAAA;;;;;;AJtDzB;;;;;;;;;;AAKA;;;;;;;UKWiB,cAAA;EACf,IAAA;AAAA;AAAA,iBAGc,oBAAA,CAAA,GAAwB,cAAA;;;UCjBvB,uBAAA;EAAA,SACN,IAAA,EAAM,cAAA;EAAA,SACN,QAAA,EAAU,iBAAA;AAAA;AAAA,iBAGL,kBAAA,CAAA;EACd,IAAA;EACA;AAAA,GACC,uBAAA,GAA0B,iBAAA;;;;;;ANX7B;;;;iBOcgB,WAAA,aAAA,CAAyB,GAAA,WAAc,OAAA,CAAQ,CAAA"}

package/dist/esm/ssr.mjs

@@ -0,0 +1,2 @@
+import{t as e}from"./useRoute-BSPVVbLz.mjs";import{useContext as t,useEffect as n,useState as r}from"preact/hooks";import{createContext as i}from"preact";import{Suspense as a}from"preact/compat";import{jsx as o}from"preact/jsx-runtime";function s({children:e,fallback:t=null}){let[i,a]=r(!1);return n(()=>{a(!0)},[]),i?e:t}function c({children:e,fallback:t=null}){let[i,a]=r(!1);return n(()=>{a(!0)},[]),i?t:e}const l=new Promise(()=>{});function u(t){let{route:n}=e();return n.context.ssrDataDeferred?.[t]??l}function d(e){let t=e;return t.status===void 0?(t.status=`pending`,e.then(e=>{t.status===`pending`&&(t.status=`fulfilled`,t.value=e)},e=>{t.status===`pending`&&(t.status=`rejected`,t.reason=e)}),t):t}function f({name:e,children:t}){let n=u(e),r=d(n);if(r.status===`fulfilled`)return t(r.value);throw r.status===`rejected`?r.reason:n}function p({fallback:e,children:t}){return o(a,{fallback:e,children:t})}const m=i(null);function h({sink:e,children:t}){return o(m.Provider,{value:e,children:t})}function g({code:e}){let n=t(m);return n&&(process.env.NODE_ENV!==`production`&&(!Number.isInteger(e)||e<100||e>999)&&console.error(`[real-router] <HttpStatusCode code={${String(e)}} /> received an invalid HTTP status code. Node's res.end() rejects values that are not an integer in [100, 999] — pass a real HTTP status (commonly 4xx/5xx).`),n.code=e),null}function _(){return{code:void 0}}export{f as Await,s as ClientOnly,g as HttpStatusCode,h as HttpStatusProvider,c as ServerOnly,p as Streamed,_ as createHttpStatusSink,u as useDeferred};
+//# sourceMappingURL=ssr.mjs.map

package/dist/esm/ssr.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ssr.mjs","names":[],"sources":["../../src/components/ClientOnly.tsx","../../src/components/ServerOnly.tsx","../../src/hooks/useDeferred.tsx","../../src/components/Await.tsx","../../src/components/Streamed.tsx","../../src/components/HttpStatusProvider.tsx","../../src/components/HttpStatusCode.tsx","../../src/utils/createHttpStatusSink.ts"],"sourcesContent":["import { useEffect, useState } from \"preact/hooks\";\n\nimport type { ComponentChildren } from \"preact\";\n\nexport interface ClientOnlyProps {\n  readonly children: ComponentChildren;\n  readonly fallback?: ComponentChildren;\n}\n\nexport function ClientOnly({\n  children,\n  fallback = null,\n}: ClientOnlyProps): ComponentChildren {\n  const [mounted, setMounted] = useState(false);\n\n  useEffect(() => {\n    // SSR/hydration boundary: server emits the fallback branch, client matches\n    // it on first paint, then this effect flips state to swap in the children.\n    // The intentional re-render is what makes the markup match across renders.\n    // eslint-disable-next-line @eslint-react/set-state-in-effect -- intentional post-hydration swap\n    setMounted(true);\n  }, []);\n\n  return mounted ? children : fallback;\n}\n","import { useEffect, useState } from \"preact/hooks\";\n\nimport type { ComponentChildren } from \"preact\";\n\nexport interface ServerOnlyProps {\n  readonly children: ComponentChildren;\n  readonly fallback?: ComponentChildren;\n}\n\nexport function ServerOnly({\n  children,\n  fallback = null,\n}: ServerOnlyProps): ComponentChildren {\n  const [mounted, setMounted] = useState(false);\n\n  useEffect(() => {\n    // SSR/hydration boundary: server emits the children branch, client matches\n    // it on first paint, then this effect flips state to swap in the fallback\n    // (or hide entirely). The intentional re-render keeps markup consistent\n    // across renders.\n    // eslint-disable-next-line @eslint-react/set-state-in-effect -- intentional post-hydration swap\n    setMounted(true);\n  }, []);\n\n  return mounted ? fallback : children;\n}\n","import { useRoute } from \"./useRoute\";\n\ninterface DeferredContext {\n  ssrDataDeferred?: Record<string, Promise<unknown>>;\n}\n\nconst NEVER_PROMISE = new Promise<never>(() => {\n  // Intentionally never resolves — surfaces a forever-pending Suspense boundary\n  // when a key is requested that the loader never declared.\n});\n\n/**\n * Read a deferred promise published by `defer({ deferred: { <key>: Promise } })`\n * inside an SSR data loader. Mirror of `@real-router/react/ssr` `useDeferred`\n * — same `state.context.ssrDataDeferred` contract, same NEVER-on-missing\n * fallback. Pair with `<Await>` (this package) which adds Preact-side\n * promise-status tracking since Preact 10 has no `use(promise)` analogue.\n */\nexport function useDeferred<T = unknown>(key: string): Promise<T> {\n  const { route } = useRoute();\n  const context = route.context as DeferredContext;\n  const deferred = context.ssrDataDeferred;\n  const promise = deferred?.[key];\n\n  return (promise ?? NEVER_PROMISE) as Promise<T>;\n}\n","import { useDeferred } from \"../hooks/useDeferred\";\n\nimport type { ComponentChildren } from \"preact\";\n\ninterface TrackedPromise<T> extends Promise<T> {\n  status?: \"pending\" | \"fulfilled\" | \"rejected\";\n  value?: T;\n  reason?: unknown;\n}\n\n/**\n * Preact's `Suspense` (from `preact/compat`) catches a thrown thenable and\n * re-runs the boundary's render once it settles. For deterministic re-renders\n * we tag the promise with `.status` / `.value` / `.reason` on first access so\n * the second render-pass can return the value synchronously instead of\n * throwing again.\n *\n * The same tag layout is used by React 19's internal `use(promise)` cache,\n * so promises that already carry the tag (e.g. emitted by a Suspense-aware\n * data lib) are reused as-is.\n */\nfunction track<T>(promise: Promise<T>): TrackedPromise<T> {\n  const tracked = promise as TrackedPromise<T>;\n\n  if (tracked.status !== undefined) {\n    return tracked;\n  }\n\n  tracked.status = \"pending\";\n  promise.then(\n    (value) => {\n      /* v8 ignore next 4 -- @preserve: the `.status === \"pending\"` guard\n         protects against external mutation between `track()` and the .then\n         microtask; covered branch is the always-true case in our control. */\n      if (tracked.status === \"pending\") {\n        tracked.status = \"fulfilled\";\n        tracked.value = value;\n      }\n    },\n    /* v8 ignore start -- @preserve: rejection .then handler — tested\n       end-to-end via the React adapter's e2e ssr-streaming Scenario 10\n       (id=4 reviews promise rejects on the wire); covering it in unit tests\n       requires Preact's Suspense to surface the rejection through render,\n       which doesn't compose cleanly with vitest's unhandled-rejection\n       detector. Behaviour is symmetric to the success handler above. */\n    (error: unknown) => {\n      if (tracked.status === \"pending\") {\n        tracked.status = \"rejected\";\n        tracked.reason = error;\n      }\n    },\n    /* v8 ignore stop */\n  );\n\n  return tracked;\n}\n\nexport interface AwaitProps<T> {\n  /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */\n  readonly name: string;\n  /** Render the resolved value. Suspends while pending; throws inside the\n   * nearest Error Boundary on rejection. */\n  readonly children: (value: T) => ComponentChildren;\n}\n\n/**\n * Reads `useDeferred(name)` and hands the resolved value to the render-prop\n * via Preact's `<Suspense>`-throwing convention. Wrap in `<Streamed>` (or\n * `<Suspense>` from `preact/compat`).\n *\n * ```tsx\n * <Streamed fallback={<Spinner />}>\n *   <Await<Review[]> name=\"reviews\">\n *     {(reviews) => <ReviewList items={reviews} />}\n *   </Await>\n * </Streamed>\n * ```\n */\nexport function Await<T = unknown>({\n  name,\n  children,\n}: AwaitProps<T>): ComponentChildren {\n  const promise = useDeferred<T>(name);\n  const tracked = track(promise);\n\n  if (tracked.status === \"fulfilled\") {\n    return children(tracked.value as T);\n  }\n\n  if (tracked.status === \"rejected\") {\n    throw tracked.reason;\n  }\n\n  // Suspense catches the thrown thenable and waits for resolution. ESLint\n  // complains because Promises aren't Errors, but Preact's Suspense (like\n  // React's pre-`use()` Suspense convention) explicitly expects a thenable.\n  // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspense thenable convention\n  throw promise;\n}\n","import { Suspense } from \"preact/compat\";\n\nimport type { ComponentChildren } from \"preact\";\n\nexport interface StreamedProps {\n  /** Shown while any descendant `<Await>` / `use(promise)`-equivalent suspends. */\n  readonly fallback: ComponentChildren;\n  readonly children: ComponentChildren;\n}\n\n/**\n * Cross-adapter alias for `<Suspense fallback={…}>` from `preact/compat`.\n * Pairs with `<Await>` for symmetry with the React/Solid/Svelte/Vue/Angular\n * SSR streaming naming.\n *\n * Preact's `Suspense` is part of `preact/compat` (experimental). For\n * production streaming the preact-render-to-string toolchain is required.\n */\nexport function Streamed({\n  fallback,\n  children,\n}: StreamedProps): ComponentChildren {\n  return <Suspense fallback={fallback}>{children}</Suspense>;\n}\n","import { createContext } from \"preact\";\n\nimport type { HttpStatusSink } from \"../utils/createHttpStatusSink\";\nimport type { ComponentChildren } from \"preact\";\n\nexport const HttpStatusContext = createContext<HttpStatusSink | null>(null);\n\nexport interface HttpStatusProviderProps {\n  readonly sink: HttpStatusSink;\n  readonly children: ComponentChildren;\n}\n\nexport function HttpStatusProvider({\n  sink,\n  children,\n}: HttpStatusProviderProps): ComponentChildren {\n  return (\n    <HttpStatusContext.Provider value={sink}>\n      {children}\n    </HttpStatusContext.Provider>\n  );\n}\n","import { useContext } from \"preact/hooks\";\n\nimport { HttpStatusContext } from \"./HttpStatusProvider\";\n\nimport type { ComponentChildren } from \"preact\";\n\nexport interface HttpStatusCodeProps {\n  /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */\n  readonly code: number;\n}\n\n/**\n * Render-time HTTP status declaration. Mount inside a route component (typical\n * use case: a glob `*` route's NotFound page) when the status is decided by\n * the rendered tree rather than a loader.\n *\n * Writes `code` to the nearest `<HttpStatusProvider>`'s sink during render and\n * returns `null`. With no provider mounted (the standard client-side case)\n * the component is a silent no-op — same component tree hydrates without\n * touching the DOM or warning about mismatches.\n *\n * Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep\n * working as before; this component covers render-time decisions only.\n *\n * Last write wins when several `<HttpStatusCode />` instances mount in the\n * same render pass — sink reflects the last component that ran.\n *\n * ```tsx\n * // entry-server.tsx\n * import { renderToString } from \"preact-render-to-string\";\n * import { createHttpStatusSink, HttpStatusProvider } from \"@real-router/preact/ssr\";\n *\n * const sink = createHttpStatusSink();\n * const html = renderToString(\n *   <HttpStatusProvider sink={sink}>\n *     <RouterProvider router={router}>\n *       <App />\n *     </RouterProvider>\n *   </HttpStatusProvider>,\n * );\n * response.status(sink.code ?? 200).send(html);\n * ```\n *\n * **Streaming SSR (`renderToReadableStream`):** the response status MUST be\n * sent before the first body byte flushes. If `<HttpStatusCode />` is mounted\n * inside a late-resolving `<Suspense>` boundary, the sink write may happen\n * AFTER the headers are already on the wire — the override is then lost.\n * Mount the component in the shell (above every `<Suspense>` that could\n * delay it). For non-streaming SSR (`renderToString` / `renderToStringAsync`)\n * there is no such ordering concern.\n *\n * **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on\n * `NaN`, `0`, negative values, or values `> 999` — this surfaces as a 5xx /\n * dropped connection, not silent corruption. Pass a real HTTP status integer\n * (commonly 4xx/5xx; 100-999 is what Node accepts).\n */\nexport function HttpStatusCode({\n  code,\n}: HttpStatusCodeProps): ComponentChildren {\n  const sink = useContext(HttpStatusContext);\n\n  if (sink) {\n    // Dev-only validation: Node's `res.end()` throws `Invalid status code` on\n    // NaN / 0 / negative / non-integer / >999. Surface the bad value at the\n    // source so the consumer can fix the routing logic, instead of waiting\n    // for the server to crash mid-response. Production builds (Vite, esbuild,\n    // tsdown all replace `process.env.NODE_ENV !== \"production\"` with `false`)\n    // strip the check.\n    if (\n      process.env.NODE_ENV !== \"production\" &&\n      (!Number.isInteger(code) || code < 100 || code > 999)\n    ) {\n      console.error(\n        `[real-router] <HttpStatusCode code={${String(code)}} /> received an invalid HTTP status code. Node's res.end() rejects values that are not an integer in [100, 999] — pass a real HTTP status (commonly 4xx/5xx).`,\n      );\n    }\n\n    sink.code = code;\n  }\n\n  return null;\n}\n","/**\n * Render-scoped HTTP status sink. Created per request on the server, passed to\n * `<HttpStatusProvider sink={...}>`, and read after `renderToString` (or the\n * Preact streaming helper) to apply the value to the HTTP response.\n *\n * Last write wins: if the rendered tree mounts more than one\n * `<HttpStatusCode />`, the value reflects the last component that ran during\n * the render pass.\n *\n * No-op on the client — `<HttpStatusCode />` reads the optional context and\n * skips the write when no provider is mounted, so the same component tree can\n * be hydrated without changing behaviour.\n *\n * Constraints:\n * - **Per-request only.** Don't share a sink across requests; the rendered\n *   tree mutates `code` in place. Module-level singletons leak status\n *   between concurrent requests.\n * - **Don't `Object.freeze` the sink.** The component writes to `.code`;\n *   freezing makes the assignment throw under ESM strict mode.\n */\nexport interface HttpStatusSink {\n  code: number | undefined;\n}\n\nexport function createHttpStatusSink(): HttpStatusSink {\n  return { code: undefined };\n}\n"],"mappings":"4OASA,SAAgB,EAAW,CACzB,WACA,WAAW,MAC0B,CACrC,GAAM,CAAC,EAAS,GAAc,EAAS,GAAM,CAU7C,OARA,MAAgB,CAKd,EAAW,GAAK,EACf,EAAE,CAAC,CAEC,EAAU,EAAW,ECd9B,SAAgB,EAAW,CACzB,WACA,WAAW,MAC0B,CACrC,GAAM,CAAC,EAAS,GAAc,EAAS,GAAM,CAW7C,OATA,MAAgB,CAMd,EAAW,GAAK,EACf,EAAE,CAAC,CAEC,EAAU,EAAW,EClB9B,MAAM,EAAgB,IAAI,YAAqB,GAG7C,CASF,SAAgB,EAAyB,EAAyB,CAChE,GAAM,CAAE,SAAU,GAAU,CAK5B,OAJgB,EAAM,QACG,kBACE,IAER,ECHrB,SAAS,EAAS,EAAwC,CACxD,IAAM,EAAU,EAgChB,OA9BI,EAAQ,SAAW,IAAA,IAIvB,EAAQ,OAAS,UACjB,EAAQ,KACL,GAAU,CAIL,EAAQ,SAAW,YACrB,EAAQ,OAAS,YACjB,EAAQ,MAAQ,IASnB,GAAmB,CACd,EAAQ,SAAW,YACrB,EAAQ,OAAS,WACjB,EAAQ,OAAS,IAItB,CAEM,GA7BE,EAqDX,SAAgB,EAAmB,CACjC,OACA,YACmC,CACnC,IAAM,EAAU,EAAe,EAAK,CAC9B,EAAU,EAAM,EAAQ,CAE9B,GAAI,EAAQ,SAAW,YACrB,OAAO,EAAS,EAAQ,MAAW,CAWrC,MARI,EAAQ,SAAW,WACf,EAAQ,OAOV,EC/ER,SAAgB,EAAS,CACvB,WACA,YACmC,CACnC,OAAO,EAAC,EAAD,CAAoB,WAAW,WAAoB,CAAA,CCjB5D,MAAa,EAAoB,EAAqC,KAAK,CAO3E,SAAgB,EAAmB,CACjC,OACA,YAC6C,CAC7C,OACE,EAAC,EAAkB,SAAnB,CAA4B,MAAO,EAChC,WAC0B,CAAA,CCqCjC,SAAgB,EAAe,CAC7B,QACyC,CACzC,IAAM,EAAO,EAAW,EAAkB,CAqB1C,OAnBI,IAQA,QAAQ,IAAI,WAAa,eACxB,CAAC,OAAO,UAAU,EAAK,EAAI,EAAO,KAAO,EAAO,MAEjD,QAAQ,MACN,uCAAuC,OAAO,EAAK,CAAC,gKACrD,CAGH,EAAK,KAAO,GAGP,KCxDT,SAAgB,GAAuC,CACrD,MAAO,CAAE,KAAM,IAAA,GAAW"}

package/dist/esm/useRoute-BSPVVbLz.mjs

@@ -0,0 +1,2 @@
+import{useContext as e}from"preact/hooks";import{createContext as t}from"preact";const n=t(null),r=t(null),i=t(null);function a(t,n){return()=>{let r=e(t);if(!r)throw Error(`${n} must be used within a RouterProvider`);return r}}const o=a(n,`useRoute`),s=()=>{let e=o();if(!e.route)throw Error(`useRoute called with no active route. Did you forget to await router.start() before rendering, or is the router stopped/disposed?`);return e};export{a,r as i,i as n,n as r,s as t};
+//# sourceMappingURL=useRoute-BSPVVbLz.mjs.map

package/dist/esm/useRoute-BSPVVbLz.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRoute-BSPVVbLz.mjs","names":[],"sources":["../../src/context.ts","../../src/hooks/useRoute.tsx"],"sourcesContent":["import { createContext } from \"preact\";\nimport { useContext } from \"preact/hooks\";\n\nimport type { RouteContext as RouteContextType } from \"./types\";\nimport type { Router, Navigator } from \"@real-router/core\";\nimport type { Context } from \"preact\";\n\nexport const RouteContext = createContext<RouteContextType | null>(null);\n\nexport const RouterContext = createContext<Router | null>(null);\n\nexport const NavigatorContext = createContext<Navigator | null>(null);\n\nexport function createUseContextOrThrow<T>(\n  context: Context<T | null>,\n  hookName: string,\n): () => T {\n  return () => {\n    const value = useContext(context);\n\n    if (!value) {\n      throw new Error(`${hookName} must be used within a RouterProvider`);\n    }\n\n    return value;\n  };\n}\n","import { createUseContextOrThrow, RouteContext } from \"../context\";\n\nimport type { RouteContext as RouteContextType } from \"../types\";\nimport type { Params, State } from \"@real-router/core\";\n\nconst useRouteContextOrThrow = createUseContextOrThrow(\n  RouteContext,\n  \"useRoute\",\n);\n\nexport const useRoute = <P extends Params = Params>(): Omit<\n  RouteContextType<P>,\n  \"route\"\n> & { route: State<P> } => {\n  const routeContext = useRouteContextOrThrow();\n\n  if (!routeContext.route) {\n    throw new Error(\n      \"useRoute called with no active route. Did you forget to await router.start() before rendering, or is the router stopped/disposed?\",\n    );\n  }\n\n  return routeContext as Omit<RouteContextType<P>, \"route\"> & {\n    route: State<P>;\n  };\n};\n"],"mappings":"iFAOA,MAAa,EAAe,EAAuC,KAAK,CAE3D,EAAgB,EAA6B,KAAK,CAElD,EAAmB,EAAgC,KAAK,CAErE,SAAgB,EACd,EACA,EACS,CACT,UAAa,CACX,IAAM,EAAQ,EAAW,EAAQ,CAEjC,GAAI,CAAC,EACH,MAAU,MAAM,GAAG,EAAS,uCAAuC,CAGrE,OAAO,GCnBX,MAAM,EAAyB,EAC7B,EACA,WACD,CAEY,MAGc,CACzB,IAAM,EAAe,GAAwB,CAE7C,GAAI,CAAC,EAAa,MAChB,MAAU,MACR,oIACD,CAGH,OAAO"}

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "@real-router/preact",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "type": "commonjs",
   "description": "Preact integration for Real-Router",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.mjs",
   "types": "./dist/esm/index.d.mts",
+  "typesVersions": {
+    "*": {
+      "ssr": [
+        "./dist/cjs/ssr.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "@real-router/internal-source": "./src/index.ts",
@@ -15,6 +22,15 @@
       },
       "import": "./dist/esm/index.mjs",
       "require": "./dist/cjs/index.js"
+    },
+    "./ssr": {
+      "@real-router/internal-source": "./src/ssr.ts",
+      "types": {
+        "import": "./dist/esm/ssr.d.mts",
+        "require": "./dist/cjs/ssr.d.ts"
+      },
+      "import": "./dist/esm/ssr.mjs",
+      "require": "./dist/cjs/ssr.js"
     }
   },
   "files": [
@@ -48,9 +64,9 @@
   "license": "MIT",
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.52.0",
+    "@real-router/core": "^0.53.0",
     "@real-router/route-utils": "^0.2.2",
-    "@real-router/sources": "^0.8.1"
+    "@real-router/sources": "^0.8.2"
   },
   "devDependencies": {
     "@testing-library/dom": "10.4.1",
@@ -58,7 +74,8 @@
     "@testing-library/preact": "3.2.4",
     "@testing-library/user-event": "14.6.1",
     "preact": "10.25.4",
-    "@real-router/browser-plugin": "^0.17.1"
+    "preact-render-to-string": "6.6.7",
+    "@real-router/browser-plugin": "^0.17.2"
   },
   "peerDependencies": {
     "preact": ">=10.0.0"

package/src/RouterProvider.tsx

@@ -84,17 +84,30 @@ export const RouterProvider: FunctionComponent<RouteProviderProps> = ({
     };
   }, [router, viewTransitions]);
 
-  const navigator = useMemo(() => getNavigator(router), [router]);
+  // `getNavigator` is cached per-router in `@real-router/core` (WeakMap) —
+  // same router always returns the same Navigator ref. No `useMemo` needed.
+  const navigator = getNavigator(router);
+
+  // `createRouteSource` is NOT cached (per packages/sources/CLAUDE.md table).
+  // It must be stable across renders so `useSyncExternalStore`'s deps don't
+  // change identity and trigger an unsubscribe/resubscribe loop on every
+  // render. `useMemo([router])` gives one source per router-instance lifetime.
+  const store = useMemo(() => createRouteSource(router), [router]);
 
   // useSyncExternalStore manages the router subscription lifecycle:
   // subscribe connects to router on first listener, unsubscribes on last.
-  const store = useMemo(() => createRouteSource(router), [router]);
   const { route, previousRoute } = useSyncExternalStore(
     store.subscribe,
     store.getSnapshot,
     store.getSnapshot, // SSR: router returns same state on server and client
   );
 
+  // Stable-ref against parent re-renders: when parent re-renders RouterProvider
+  // without a route change (e.g. consumer re-renders the root), navigator /
+  // route / previousRoute references stay identical (useSyncExternalStore +
+  // Object.is bail-out). Without `useMemo` the object literal is fresh every
+  // render, propagating spurious re-renders to every `useRoute()` consumer.
+  // The memo bails out whenever the three deps are referentially equal.
   const routeContextValue = useMemo(
     () => ({ navigator, route, previousRoute }),
     [navigator, route, previousRoute],

package/src/components/Await.tsx

@@ -0,0 +1,99 @@
+import { useDeferred } from "../hooks/useDeferred";
+
+import type { ComponentChildren } from "preact";
+
+interface TrackedPromise<T> extends Promise<T> {
+  status?: "pending" | "fulfilled" | "rejected";
+  value?: T;
+  reason?: unknown;
+}
+
+/**
+ * Preact's `Suspense` (from `preact/compat`) catches a thrown thenable and
+ * re-runs the boundary's render once it settles. For deterministic re-renders
+ * we tag the promise with `.status` / `.value` / `.reason` on first access so
+ * the second render-pass can return the value synchronously instead of
+ * throwing again.
+ *
+ * The same tag layout is used by React 19's internal `use(promise)` cache,
+ * so promises that already carry the tag (e.g. emitted by a Suspense-aware
+ * data lib) are reused as-is.
+ */
+function track<T>(promise: Promise<T>): TrackedPromise<T> {
+  const tracked = promise as TrackedPromise<T>;
+
+  if (tracked.status !== undefined) {
+    return tracked;
+  }
+
+  tracked.status = "pending";
+  promise.then(
+    (value) => {
+      /* v8 ignore next 4 -- @preserve: the `.status === "pending"` guard
+         protects against external mutation between `track()` and the .then
+         microtask; covered branch is the always-true case in our control. */
+      if (tracked.status === "pending") {
+        tracked.status = "fulfilled";
+        tracked.value = value;
+      }
+    },
+    /* v8 ignore start -- @preserve: rejection .then handler — tested
+       end-to-end via the React adapter's e2e ssr-streaming Scenario 10
+       (id=4 reviews promise rejects on the wire); covering it in unit tests
+       requires Preact's Suspense to surface the rejection through render,
+       which doesn't compose cleanly with vitest's unhandled-rejection
+       detector. Behaviour is symmetric to the success handler above. */
+    (error: unknown) => {
+      if (tracked.status === "pending") {
+        tracked.status = "rejected";
+        tracked.reason = error;
+      }
+    },
+    /* v8 ignore stop */
+  );
+
+  return tracked;
+}
+
+export interface AwaitProps<T> {
+  /** Deferred key declared in the loader's `defer({ deferred: { <name>: ... } })`. */
+  readonly name: string;
+  /** Render the resolved value. Suspends while pending; throws inside the
+   * nearest Error Boundary on rejection. */
+  readonly children: (value: T) => ComponentChildren;
+}
+
+/**
+ * Reads `useDeferred(name)` and hands the resolved value to the render-prop
+ * via Preact's `<Suspense>`-throwing convention. Wrap in `<Streamed>` (or
+ * `<Suspense>` from `preact/compat`).
+ *
+ * ```tsx
+ * <Streamed fallback={<Spinner />}>
+ *   <Await<Review[]> name="reviews">
+ *     {(reviews) => <ReviewList items={reviews} />}
+ *   </Await>
+ * </Streamed>
+ * ```
+ */
+export function Await<T = unknown>({
+  name,
+  children,
+}: AwaitProps<T>): ComponentChildren {
+  const promise = useDeferred<T>(name);
+  const tracked = track(promise);
+
+  if (tracked.status === "fulfilled") {
+    return children(tracked.value as T);
+  }
+
+  if (tracked.status === "rejected") {
+    throw tracked.reason;
+  }
+
+  // Suspense catches the thrown thenable and waits for resolution. ESLint
+  // complains because Promises aren't Errors, but Preact's Suspense (like
+  // React's pre-`use()` Suspense convention) explicitly expects a thenable.
+  // eslint-disable-next-line @typescript-eslint/only-throw-error -- Suspense thenable convention
+  throw promise;
+}

package/src/components/ClientOnly.tsx

@@ -0,0 +1,25 @@
+import { useEffect, useState } from "preact/hooks";
+
+import type { ComponentChildren } from "preact";
+
+export interface ClientOnlyProps {
+  readonly children: ComponentChildren;
+  readonly fallback?: ComponentChildren;
+}
+
+export function ClientOnly({
+  children,
+  fallback = null,
+}: ClientOnlyProps): ComponentChildren {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    // SSR/hydration boundary: server emits the fallback branch, client matches
+    // it on first paint, then this effect flips state to swap in the children.
+    // The intentional re-render is what makes the markup match across renders.
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- intentional post-hydration swap
+    setMounted(true);
+  }, []);
+
+  return mounted ? children : fallback;
+}

package/src/components/HttpStatusCode.tsx

@@ -0,0 +1,82 @@
+import { useContext } from "preact/hooks";
+
+import { HttpStatusContext } from "./HttpStatusProvider";
+
+import type { ComponentChildren } from "preact";
+
+export interface HttpStatusCodeProps {
+  /** HTTP status to apply to the response. Common values: 404, 410, 451, 503. */
+  readonly code: number;
+}
+
+/**
+ * Render-time HTTP status declaration. Mount inside a route component (typical
+ * use case: a glob `*` route's NotFound page) when the status is decided by
+ * the rendered tree rather than a loader.
+ *
+ * Writes `code` to the nearest `<HttpStatusProvider>`'s sink during render and
+ * returns `null`. With no provider mounted (the standard client-side case)
+ * the component is a silent no-op — same component tree hydrates without
+ * touching the DOM or warning about mismatches.
+ *
+ * Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep
+ * working as before; this component covers render-time decisions only.
+ *
+ * Last write wins when several `<HttpStatusCode />` instances mount in the
+ * same render pass — sink reflects the last component that ran.
+ *
+ * ```tsx
+ * // entry-server.tsx
+ * import { renderToString } from "preact-render-to-string";
+ * import { createHttpStatusSink, HttpStatusProvider } from "@real-router/preact/ssr";
+ *
+ * const sink = createHttpStatusSink();
+ * const html = renderToString(
+ *   <HttpStatusProvider sink={sink}>
+ *     <RouterProvider router={router}>
+ *       <App />
+ *     </RouterProvider>
+ *   </HttpStatusProvider>,
+ * );
+ * response.status(sink.code ?? 200).send(html);
+ * ```
+ *
+ * **Streaming SSR (`renderToReadableStream`):** the response status MUST be
+ * sent before the first body byte flushes. If `<HttpStatusCode />` is mounted
+ * inside a late-resolving `<Suspense>` boundary, the sink write may happen
+ * AFTER the headers are already on the wire — the override is then lost.
+ * Mount the component in the shell (above every `<Suspense>` that could
+ * delay it). For non-streaming SSR (`renderToString` / `renderToStringAsync`)
+ * there is no such ordering concern.
+ *
+ * **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on
+ * `NaN`, `0`, negative values, or values `> 999` — this surfaces as a 5xx /
+ * dropped connection, not silent corruption. Pass a real HTTP status integer
+ * (commonly 4xx/5xx; 100-999 is what Node accepts).
+ */
+export function HttpStatusCode({
+  code,
+}: HttpStatusCodeProps): ComponentChildren {
+  const sink = useContext(HttpStatusContext);
+
+  if (sink) {
+    // Dev-only validation: Node's `res.end()` throws `Invalid status code` on
+    // NaN / 0 / negative / non-integer / >999. Surface the bad value at the
+    // source so the consumer can fix the routing logic, instead of waiting
+    // for the server to crash mid-response. Production builds (Vite, esbuild,
+    // tsdown all replace `process.env.NODE_ENV !== "production"` with `false`)
+    // strip the check.
+    if (
+      process.env.NODE_ENV !== "production" &&
+      (!Number.isInteger(code) || code < 100 || code > 999)
+    ) {
+      console.error(
+        `[real-router] <HttpStatusCode code={${String(code)}} /> received an invalid HTTP status code. Node's res.end() rejects values that are not an integer in [100, 999] — pass a real HTTP status (commonly 4xx/5xx).`,
+      );
+    }
+
+    sink.code = code;
+  }
+
+  return null;
+}

package/src/components/HttpStatusProvider.tsx

@@ -0,0 +1,22 @@
+import { createContext } from "preact";
+
+import type { HttpStatusSink } from "../utils/createHttpStatusSink";
+import type { ComponentChildren } from "preact";
+
+export const HttpStatusContext = createContext<HttpStatusSink | null>(null);
+
+export interface HttpStatusProviderProps {
+  readonly sink: HttpStatusSink;
+  readonly children: ComponentChildren;
+}
+
+export function HttpStatusProvider({
+  sink,
+  children,
+}: HttpStatusProviderProps): ComponentChildren {
+  return (
+    <HttpStatusContext.Provider value={sink}>
+      {children}
+    </HttpStatusContext.Provider>
+  );
+}