@nifrajs/web-preact 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -16,3 +16,11 @@ bun add @nifrajs/web-preact
 - AI-readable: <https://nifra.dev/llms.txt>
 
 MIT
+
+## For AI agents
+
+Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+one cheap read instead of the whole corpus. For the wider framework: the repo's
+[`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
+[`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the
+done-gate, or `nifra mcp` to give the agent live project tools.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAYjD,8EAA8E;AAC9E,eAAO,MAAM,aAAa,EAAE,aAgB3B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAWjD,8EAA8E;AAC9E,eAAO,MAAM,aAAa,EAAE,aAqB3B,CAAA"}

package/dist/index.js

@@ -5,19 +5,23 @@
  * `@nifrajs/web-preact/client`. Preact uses `h()` render functions, so no JSX/build plugin is needed
  * (contrast `@nifrajs/web-solid`'s Babel plugin).
  */
-import { renderToString as preactRenderToString } from "preact-render-to-string";
-import { renderToReadableStream } from "preact-render-to-string/stream";
 import { compose } from "./compose.js";
+import { preactRenderToStream, preactRenderToString } from "./preact-render.js";
 /** The Preact server render adapter — pass to @nifrajs/web's `renderPage`. */
 export const preactAdapter = {
     // Synchronous one-pass render for non-deferred pages (renderPage's buffered fast path). The sync
     // `renderToString` emits the same markup as the stream renderer without the chunking machinery.
-    renderToString(chain, props) {
-        return preactRenderToString(compose(chain, props));
+    //
+    // Async because the renderer module is resolved lazily (from the consumer app's node_modules under Bun
+    // runtime SSR — see ./preact-render). `RenderAdapter.renderToString` permits a Promise; renderPage awaits.
+    async renderToString(chain, props) {
+        const { renderToString } = await preactRenderToString();
+        return renderToString(compose(chain, props));
     },
-    renderToStream(chain, props) {
+    async renderToStream(chain, props) {
         // `renderToReadableStream` yields a Web ReadableStream<Uint8Array>; <Suspense> boundaries
         // (preact/compat) stream as they resolve, mirroring the React adapter.
+        const { renderToReadableStream } = await preactRenderToStream();
         return renderToReadableStream(compose(chain, props));
     },
     // Preact reconciles against the existing DOM on hydrate (like React), so there's no per-document

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AACH,OAAO,EAAE,cAAc,IAAI,oBAAoB,EAAE,MAAM,yBAAyB,CAAA;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AACvE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAEtC,8EAA8E;AAC9E,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C,iGAAiG;IACjG,gGAAgG;IAChG,cAAc,CAAC,KAAK,EAAE,KAAK;QACzB,OAAO,oBAAoB,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IACpD,CAAC;IACD,cAAc,CAAC,KAAK,EAAE,KAAK;QACzB,0FAA0F;QAC1F,uEAAuE;QACvE,OAAO,sBAAsB,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IACtD,CAAC;IACD,iGAAiG;IACjG,kGAAkG;IAClG,aAAa;QACX,OAAO,EAAE,CAAA;IACX,CAAC;CACF,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAE/E,8EAA8E;AAC9E,MAAM,CAAC,MAAM,aAAa,GAAkB;IAC1C,iGAAiG;IACjG,gGAAgG;IAChG,EAAE;IACF,uGAAuG;IACvG,2GAA2G;IAC3G,KAAK,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK;QAC/B,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,oBAAoB,EAAE,CAAA;QACvD,OAAO,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IAC9C,CAAC;IACD,KAAK,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK;QAC/B,0FAA0F;QAC1F,uEAAuE;QACvE,MAAM,EAAE,sBAAsB,EAAE,GAAG,MAAM,oBAAoB,EAAE,CAAA;QAC/D,OAAO,sBAAsB,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IACtD,CAAC;IACD,iGAAiG;IACjG,kGAAkG;IAClG,aAAa;QACX,OAAO,EAAE,CAAA;IACX,CAAC;CACF,CAAA"}

package/dist/preact-render.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Resolve `preact-render-to-string` (+ its `/stream` subpath) so the renderer shares ONE `preact`
+ * module-global with the route components — the fix for the dual-Preact SSR crash (`undefined is not an
+ * object (evaluating '…__H')` / silently-empty hook output).
+ *
+ * WHY this exists: `preact-render-to-string` imports `options` and `h` from `preact` and mutates the
+ * shared `options` hooks; `preact/hooks` registers its render hook on the SAME `options` global. Under Bun
+ * **runtime** SSR (`nifra dev`, `nifra start`, `nifra_render`, all in-process), a static
+ * `import "preact-render-to-string"` in this adapter is resolved from THIS package's own (symlinked)
+ * node_modules — which can be a DIFFERENT physical `preact` than the consumer app's components import. Two
+ * `preact` copies → two `options` globals → the renderer walks one while `preact/hooks` wrote the other →
+ * the vnode never gets its hook-state list → the crash. Resolving the renderer from the consumer **app
+ * root** makes it pull the app's `preact` transitively, matching the components: one `options`, one core,
+ * no crash. (Empirically verified against a two-copy install fixture — see test/dual-preact.test.ts.)
+ *
+ * Guarding precisely so the PRODUCTION/BUILT path is untouched: when `Bun.resolveSync` is unavailable
+ * (Node / Deno / Cloudflare / Vercel / any bundled output), the build has already bundled a single
+ * `preact` + renderer, so the static `import` is correct AND the only thing that works without a Bun
+ * resolver. We fall back to it there. The app-root resolution runs ONLY under the Bun runtime.
+ */
+import type { VNode } from "preact";
+/** The slice of `preact-render-to-string` this adapter uses. */
+export interface PreactRenderToString {
+    renderToString(node: VNode): string;
+}
+/** The slice of `preact-render-to-string/stream`. */
+export interface PreactRenderToStream {
+    renderToReadableStream(node: VNode): ReadableStream<Uint8Array>;
+}
+/** Get `preact-render-to-string` bound to the consumer app's `preact`. Cached after the first call. */
+export declare function preactRenderToString(): Promise<PreactRenderToString>;
+/** Get `preact-render-to-string/stream` bound to the consumer app's `preact`. Cached after the first call. */
+export declare function preactRenderToStream(): Promise<PreactRenderToStream>;
+/** A `Bun.resolveSync`-shaped function (specifier, from) → absolute path. */
+type ResolveSync = (specifier: string, from: string) => string;
+/**
+ * Load a renderer subpath, preferring the app-root-resolved copy under the Bun runtime. Exported for unit
+ * tests: `resolve` defaults to the ambient `Bun.resolveSync` (undefined on non-Bun hosts), and a test can
+ * inject a stub that succeeds (re-root branch) or throws (fallback branch) to cover both deterministically
+ * without depending on the machine's node_modules layout.
+ */
+export declare function load<T>(specifier: "preact-render-to-string" | "preact-render-to-string/stream", resolve?: ResolveSync | undefined): Promise<T>;
+export {};
+//# sourceMappingURL=preact-render.d.ts.map

package/dist/preact-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preact-render.d.ts","sourceRoot":"","sources":["../src/preact-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAEnC,gEAAgE;AAChE,MAAM,WAAW,oBAAoB;IACnC,cAAc,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAAA;CACpC;AACD,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACnC,sBAAsB,CAAC,IAAI,EAAE,KAAK,GAAG,cAAc,CAAC,UAAU,CAAC,CAAA;CAChE;AAyBD,uGAAuG;AACvG,wBAAgB,oBAAoB,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAIpE;AAED,8GAA8G;AAC9G,wBAAgB,oBAAoB,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAIpE;AAED,6EAA6E;AAC7E,KAAK,WAAW,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;AAE9D;;;;;GAKG;AACH,wBAAsB,IAAI,CAAC,CAAC,EAC1B,SAAS,EAAE,yBAAyB,GAAG,gCAAgC,EACvE,OAAO,GAAE,WAAW,GAAG,SAA2B,GACjD,OAAO,CAAC,CAAC,CAAC,CAsBZ"}

package/dist/preact-render.js

@@ -0,0 +1,93 @@
+/**
+ * Resolve `preact-render-to-string` (+ its `/stream` subpath) so the renderer shares ONE `preact`
+ * module-global with the route components — the fix for the dual-Preact SSR crash (`undefined is not an
+ * object (evaluating '…__H')` / silently-empty hook output).
+ *
+ * WHY this exists: `preact-render-to-string` imports `options` and `h` from `preact` and mutates the
+ * shared `options` hooks; `preact/hooks` registers its render hook on the SAME `options` global. Under Bun
+ * **runtime** SSR (`nifra dev`, `nifra start`, `nifra_render`, all in-process), a static
+ * `import "preact-render-to-string"` in this adapter is resolved from THIS package's own (symlinked)
+ * node_modules — which can be a DIFFERENT physical `preact` than the consumer app's components import. Two
+ * `preact` copies → two `options` globals → the renderer walks one while `preact/hooks` wrote the other →
+ * the vnode never gets its hook-state list → the crash. Resolving the renderer from the consumer **app
+ * root** makes it pull the app's `preact` transitively, matching the components: one `options`, one core,
+ * no crash. (Empirically verified against a two-copy install fixture — see test/dual-preact.test.ts.)
+ *
+ * Guarding precisely so the PRODUCTION/BUILT path is untouched: when `Bun.resolveSync` is unavailable
+ * (Node / Deno / Cloudflare / Vercel / any bundled output), the build has already bundled a single
+ * `preact` + renderer, so the static `import` is correct AND the only thing that works without a Bun
+ * resolver. We fall back to it there. The app-root resolution runs ONLY under the Bun runtime.
+ */
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+const bunResolver = globalThis.Bun;
+const hasBunResolveSync = typeof bunResolver?.resolveSync === "function";
+// Cache the in-flight Promises (not the modules) so concurrent first renders share one import each.
+let cachedSync;
+let cachedStream;
+/**
+ * The consumer app root used to re-root the renderer. `nifra dev` / `nifra start` run with the CLI's
+ * `process.cwd()` set to the app directory, and `nifra_render`'s subprocess `process.chdir`es to the app
+ * dir before SSR, so `process.cwd()` is the app root on every Bun runtime SSR path. Read lazily so a host
+ * that `chdir`s after import still sees the right root.
+ */
+function appRoot() {
+    return process.cwd();
+}
+/** Get `preact-render-to-string` bound to the consumer app's `preact`. Cached after the first call. */
+export function preactRenderToString() {
+    if (cachedSync !== undefined)
+        return cachedSync;
+    cachedSync = load("preact-render-to-string");
+    return cachedSync;
+}
+/** Get `preact-render-to-string/stream` bound to the consumer app's `preact`. Cached after the first call. */
+export function preactRenderToStream() {
+    if (cachedStream !== undefined)
+        return cachedStream;
+    cachedStream = load("preact-render-to-string/stream");
+    return cachedStream;
+}
+/**
+ * Load a renderer subpath, preferring the app-root-resolved copy under the Bun runtime. Exported for unit
+ * tests: `resolve` defaults to the ambient `Bun.resolveSync` (undefined on non-Bun hosts), and a test can
+ * inject a stub that succeeds (re-root branch) or throws (fallback branch) to cover both deterministically
+ * without depending on the machine's node_modules layout.
+ */
+export async function load(specifier, resolve = bunResolverFn()) {
+    if (resolve !== undefined) {
+        // Bun runtime SSR: re-root to the app's copy so the renderer shares the components' `preact`.
+        // `preact-render-to-string` is a direct DEPENDENCY of this adapter (not a peer), so whether it sits at
+        // the app root depends on the installer's hoisting. When it's hoisted, app-root resolution re-roots
+        // its transitive `preact` to the app's copy (the fix). When it isn't resolvable from the app root, we
+        // fall through to this module's own (always-present) copy below rather than crashing.
+        try {
+            const resolved = resolve(specifier, appRoot());
+            return (await import(__rewriteRelativeImportExtension(resolved)));
+        }
+        catch {
+            // App-root resolution failed; use the specifier resolved from this module's own location below.
+        }
+    }
+    // Built bundle / Node / Deno / edge (or the Bun-resolve fallback above): the static specifier is
+    // bundled (or is the only copy present). A constant bare-specifier dynamic import lets the bundler
+    // include it; at runtime it resolves the copy visible to this package. Two explicit branches (not a
+    // variable specifier) keep the bundler's static analysis intact.
+    if (specifier === "preact-render-to-string/stream") {
+        return (await import("preact-render-to-string/stream"));
+    }
+    return (await import("preact-render-to-string"));
+}
+/** The ambient `Bun.resolveSync`, or undefined on a non-Bun host (where the static import is the only path). */
+function bunResolverFn() {
+    return hasBunResolveSync && bunResolver?.resolveSync !== undefined
+        ? bunResolver.resolveSync.bind(bunResolver)
+        : undefined;
+}
+//# sourceMappingURL=preact-render.js.map

package/dist/preact-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preact-render.js","sourceRoot":"","sources":["../src/preact-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;;;;;;;AAmBH,MAAM,WAAW,GAAI,UAA6C,CAAC,GAAG,CAAA;AACtE,MAAM,iBAAiB,GAAG,OAAO,WAAW,EAAE,WAAW,KAAK,UAAU,CAAA;AAExE,oGAAoG;AACpG,IAAI,UAAqD,CAAA;AACzD,IAAI,YAAuD,CAAA;AAE3D;;;;;GAKG;AACH,SAAS,OAAO;IACd,OAAO,OAAO,CAAC,GAAG,EAAE,CAAA;AACtB,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,oBAAoB;IAClC,IAAI,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAA;IAC/C,UAAU,GAAG,IAAI,CAAuB,yBAAyB,CAAC,CAAA;IAClE,OAAO,UAAU,CAAA;AACnB,CAAC;AAED,8GAA8G;AAC9G,MAAM,UAAU,oBAAoB;IAClC,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,YAAY,CAAA;IACnD,YAAY,GAAG,IAAI,CAAuB,gCAAgC,CAAC,CAAA;IAC3E,OAAO,YAAY,CAAA;AACrB,CAAC;AAKD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,SAAuE,EACvE,UAAmC,aAAa,EAAE;IAElD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,8FAA8F;QAC9F,uGAAuG;QACvG,oGAAoG;QACpG,sGAAsG;QACtG,sFAAsF;QACtF,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAA;YAC9C,OAAO,CAAC,MAAM,MAAM,kCAAC,QAAQ,EAAC,CAAM,CAAA;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,gGAAgG;QAClG,CAAC;IACH,CAAC;IACD,iGAAiG;IACjG,mGAAmG;IACnG,oGAAoG;IACpG,iEAAiE;IACjE,IAAI,SAAS,KAAK,gCAAgC,EAAE,CAAC;QACnD,OAAO,CAAC,MAAM,MAAM,CAAC,gCAAgC,CAAC,CAAM,CAAA;IAC9D,CAAC;IACD,OAAO,CAAC,MAAM,MAAM,CAAC,yBAAyB,CAAC,CAAM,CAAA;AACvD,CAAC;AAED,gHAAgH;AAChH,SAAS,aAAa;IACpB,OAAO,iBAAiB,IAAI,WAAW,EAAE,WAAW,KAAK,SAAS;QAChE,CAAC,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC;QAC3C,CAAC,CAAC,SAAS,CAAA;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/web-preact",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "Preact render adapter for @nifrajs/web — streaming SSR + hydration (no build plugin).",
   "keywords": [
     "bun",
@@ -70,9 +70,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/i18n": "workspace:*",
-    "@nifrajs/image": "workspace:*",
-    "@nifrajs/web": "workspace:*",
+    "@nifrajs/i18n": "0.1.0-alpha.2",
+    "@nifrajs/image": "0.1.0-alpha.2",
+    "@nifrajs/web": "0.1.0-alpha.3",
     "preact-render-to-string": "^6.5.0"
   },
   "peerDependencies": {

package/src/index.ts

@@ -6,20 +6,24 @@ import type { RenderAdapter } from "@nifrajs/web"
  * `@nifrajs/web-preact/client`. Preact uses `h()` render functions, so no JSX/build plugin is needed
  * (contrast `@nifrajs/web-solid`'s Babel plugin).
  */
-import { renderToString as preactRenderToString } from "preact-render-to-string"
-import { renderToReadableStream } from "preact-render-to-string/stream"
 import { compose } from "./compose.ts"
+import { preactRenderToStream, preactRenderToString } from "./preact-render.ts"
 
 /** The Preact server render adapter — pass to @nifrajs/web's `renderPage`. */
 export const preactAdapter: RenderAdapter = {
   // Synchronous one-pass render for non-deferred pages (renderPage's buffered fast path). The sync
   // `renderToString` emits the same markup as the stream renderer without the chunking machinery.
-  renderToString(chain, props) {
-    return preactRenderToString(compose(chain, props))
+  //
+  // Async because the renderer module is resolved lazily (from the consumer app's node_modules under Bun
+  // runtime SSR — see ./preact-render). `RenderAdapter.renderToString` permits a Promise; renderPage awaits.
+  async renderToString(chain, props) {
+    const { renderToString } = await preactRenderToString()
+    return renderToString(compose(chain, props))
   },
-  renderToStream(chain, props) {
+  async renderToStream(chain, props) {
     // `renderToReadableStream` yields a Web ReadableStream<Uint8Array>; <Suspense> boundaries
     // (preact/compat) stream as they resolve, mirroring the React adapter.
+    const { renderToReadableStream } = await preactRenderToStream()
     return renderToReadableStream(compose(chain, props))
   },
   // Preact reconciles against the existing DOM on hydrate (like React), so there's no per-document

package/src/preact-render.ts

@@ -0,0 +1,111 @@
+/**
+ * Resolve `preact-render-to-string` (+ its `/stream` subpath) so the renderer shares ONE `preact`
+ * module-global with the route components — the fix for the dual-Preact SSR crash (`undefined is not an
+ * object (evaluating '…__H')` / silently-empty hook output).
+ *
+ * WHY this exists: `preact-render-to-string` imports `options` and `h` from `preact` and mutates the
+ * shared `options` hooks; `preact/hooks` registers its render hook on the SAME `options` global. Under Bun
+ * **runtime** SSR (`nifra dev`, `nifra start`, `nifra_render`, all in-process), a static
+ * `import "preact-render-to-string"` in this adapter is resolved from THIS package's own (symlinked)
+ * node_modules — which can be a DIFFERENT physical `preact` than the consumer app's components import. Two
+ * `preact` copies → two `options` globals → the renderer walks one while `preact/hooks` wrote the other →
+ * the vnode never gets its hook-state list → the crash. Resolving the renderer from the consumer **app
+ * root** makes it pull the app's `preact` transitively, matching the components: one `options`, one core,
+ * no crash. (Empirically verified against a two-copy install fixture — see test/dual-preact.test.ts.)
+ *
+ * Guarding precisely so the PRODUCTION/BUILT path is untouched: when `Bun.resolveSync` is unavailable
+ * (Node / Deno / Cloudflare / Vercel / any bundled output), the build has already bundled a single
+ * `preact` + renderer, so the static `import` is correct AND the only thing that works without a Bun
+ * resolver. We fall back to it there. The app-root resolution runs ONLY under the Bun runtime.
+ */
+
+import type { VNode } from "preact"
+
+/** The slice of `preact-render-to-string` this adapter uses. */
+export interface PreactRenderToString {
+  renderToString(node: VNode): string
+}
+/** The slice of `preact-render-to-string/stream`. */
+export interface PreactRenderToStream {
+  renderToReadableStream(node: VNode): ReadableStream<Uint8Array>
+}
+
+// Narrow only the one Bun method we need (it isn't in the ambient lib types) so no `any` is introduced.
+// `resolveSync(specifier, from)` is the only lever that re-roots a BARE specifier — a runtime
+// `Bun.plugin` onResolve does NOT fire for bare specifiers like `preact-render-to-string` (verified).
+interface BunResolver {
+  resolveSync(specifier: string, from: string): string
+}
+const bunResolver = (globalThis as { Bun?: Partial<BunResolver> }).Bun
+const hasBunResolveSync = typeof bunResolver?.resolveSync === "function"
+
+// Cache the in-flight Promises (not the modules) so concurrent first renders share one import each.
+let cachedSync: Promise<PreactRenderToString> | undefined
+let cachedStream: Promise<PreactRenderToStream> | undefined
+
+/**
+ * The consumer app root used to re-root the renderer. `nifra dev` / `nifra start` run with the CLI's
+ * `process.cwd()` set to the app directory, and `nifra_render`'s subprocess `process.chdir`es to the app
+ * dir before SSR, so `process.cwd()` is the app root on every Bun runtime SSR path. Read lazily so a host
+ * that `chdir`s after import still sees the right root.
+ */
+function appRoot(): string {
+  return process.cwd()
+}
+
+/** Get `preact-render-to-string` bound to the consumer app's `preact`. Cached after the first call. */
+export function preactRenderToString(): Promise<PreactRenderToString> {
+  if (cachedSync !== undefined) return cachedSync
+  cachedSync = load<PreactRenderToString>("preact-render-to-string")
+  return cachedSync
+}
+
+/** Get `preact-render-to-string/stream` bound to the consumer app's `preact`. Cached after the first call. */
+export function preactRenderToStream(): Promise<PreactRenderToStream> {
+  if (cachedStream !== undefined) return cachedStream
+  cachedStream = load<PreactRenderToStream>("preact-render-to-string/stream")
+  return cachedStream
+}
+
+/** A `Bun.resolveSync`-shaped function (specifier, from) → absolute path. */
+type ResolveSync = (specifier: string, from: string) => string
+
+/**
+ * Load a renderer subpath, preferring the app-root-resolved copy under the Bun runtime. Exported for unit
+ * tests: `resolve` defaults to the ambient `Bun.resolveSync` (undefined on non-Bun hosts), and a test can
+ * inject a stub that succeeds (re-root branch) or throws (fallback branch) to cover both deterministically
+ * without depending on the machine's node_modules layout.
+ */
+export async function load<T>(
+  specifier: "preact-render-to-string" | "preact-render-to-string/stream",
+  resolve: ResolveSync | undefined = bunResolverFn(),
+): Promise<T> {
+  if (resolve !== undefined) {
+    // Bun runtime SSR: re-root to the app's copy so the renderer shares the components' `preact`.
+    // `preact-render-to-string` is a direct DEPENDENCY of this adapter (not a peer), so whether it sits at
+    // the app root depends on the installer's hoisting. When it's hoisted, app-root resolution re-roots
+    // its transitive `preact` to the app's copy (the fix). When it isn't resolvable from the app root, we
+    // fall through to this module's own (always-present) copy below rather than crashing.
+    try {
+      const resolved = resolve(specifier, appRoot())
+      return (await import(resolved)) as T
+    } catch {
+      // App-root resolution failed; use the specifier resolved from this module's own location below.
+    }
+  }
+  // Built bundle / Node / Deno / edge (or the Bun-resolve fallback above): the static specifier is
+  // bundled (or is the only copy present). A constant bare-specifier dynamic import lets the bundler
+  // include it; at runtime it resolves the copy visible to this package. Two explicit branches (not a
+  // variable specifier) keep the bundler's static analysis intact.
+  if (specifier === "preact-render-to-string/stream") {
+    return (await import("preact-render-to-string/stream")) as T
+  }
+  return (await import("preact-render-to-string")) as T
+}
+
+/** The ambient `Bun.resolveSync`, or undefined on a non-Bun host (where the static import is the only path). */
+function bunResolverFn(): ResolveSync | undefined {
+  return hasBunResolveSync && bunResolver?.resolveSync !== undefined
+    ? bunResolver.resolveSync.bind(bunResolver)
+    : undefined
+}