@nifrajs/web-preact 0.1.0-alpha.1

package/dist/query.js

@@ -0,0 +1,58 @@
+import { createQueryClient, } from "@nifrajs/web";
+/**
+ * `@nifrajs/web-preact/query` — Preact bindings for the keyed query-cache. `useQuery(key, fn)` subscribes a
+ * component to a query (via `useSyncExternalStore` from preact/compat) and fetches on mount / key change;
+ * `useQueryClient` exposes `invalidateQueries` for after a mutation. Imports only `preact/compat` +
+ * `preact/hooks` + `@nifrajs/web`, so route components use it on the server *and* client. No JSX.
+ *
+ * The query client is created lazily **client-side only** (the `typeof window` guard) — on the server
+ * there is none, so `useQuery` renders the idle/pending state (queries are client-first; loaders are
+ * the SSR data source). The first client render uses the same idle snapshot, so no mismatch.
+ */
+import { useSyncExternalStore } from "preact/compat";
+import { useEffect } from "preact/hooks";
+let client;
+function getClient() {
+    if (typeof window === "undefined")
+        return undefined; // SSR → no client (queries render idle)
+    if (client === undefined)
+        client = createQueryClient({ now: () => Date.now() });
+    return client;
+}
+/** Access the query client to imperatively `invalidateQueries(keyOrPrefix)` (e.g. after a mutation). */
+export function useQueryClient() {
+    return getClient() ?? { invalidateQueries: () => { } };
+}
+// Stable idle snapshot for the server / pre-fetch render (stable ref → no loop, no hydration mismatch).
+const IDLE = Object.freeze({
+    status: "pending",
+    data: undefined,
+    error: undefined,
+    isFetching: false,
+    updatedAt: Number.NEGATIVE_INFINITY,
+});
+const idleSnapshot = () => IDLE;
+const noopSubscribe = () => () => { };
+const noopAsync = async () => {
+    throw new Error("[nifra/web-preact] useQuery.refetch called with no query client (server?)");
+};
+/**
+ * Subscribe to the keyed query for `key`, fetched via `fn`. Returns `{ status, data, error, isFetching,
+ * updatedAt, isPending, refetch }`. Concurrent `useQuery`s with the same key share one cache entry +
+ * one in-flight fetch (dedup). Refetches on mount and when the key changes; SSR-idle.
+ */
+export function useQuery(key, fn) {
+    const handle = getClient()?.query(key, fn);
+    const state = useSyncExternalStore(handle?.subscribe ?? noopSubscribe, handle ? handle.snapshot : idleSnapshot);
+    // Fetch on mount + whenever the key changes (the handle is stable per key, so it changes with the key).
+    useEffect(() => {
+        if (handle !== undefined)
+            handle.fetch().catch(() => { });
+    }, [handle]);
+    return {
+        ...state,
+        isPending: state.status === "pending",
+        refetch: handle ? handle.refetch : noopAsync,
+    };
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,GAIlB,MAAM,cAAc,CAAA;AACrB;;;;;;;;;GASG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAExC,IAAI,MAA+B,CAAA;AACnC,SAAS,SAAS;IAChB,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO,SAAS,CAAA,CAAC,wCAAwC;IAC5F,IAAI,MAAM,KAAK,SAAS;QAAE,MAAM,GAAG,iBAAiB,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;IAC/E,OAAO,MAAM,CAAA;AACf,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,cAAc;IAC5B,OAAO,SAAS,EAAE,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAA;AACvD,CAAC;AAED,wGAAwG;AACxG,MAAM,IAAI,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC5C,MAAM,EAAE,SAAS;IACjB,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,SAAS;IAChB,UAAU,EAAE,KAAK;IACjB,SAAS,EAAE,MAAM,CAAC,iBAAiB;CACpC,CAAC,CAAA;AACF,MAAM,YAAY,GAAG,GAAsB,EAAE,CAAC,IAAI,CAAA;AAClD,MAAM,aAAa,GAAG,GAAiB,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC,CAAA;AAClD,MAAM,SAAS,GAAG,KAAK,IAAoB,EAAE;IAC3C,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAA;AAC9F,CAAC,CAAA;AAUD;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAI,GAAY,EAAE,EAAoB;IAC5D,MAAM,MAAM,GAA+B,SAAS,EAAE,EAAE,KAAK,CAAI,GAAG,EAAE,EAAE,CAAC,CAAA;IACzE,MAAM,KAAK,GAAG,oBAAoB,CAChC,MAAM,EAAE,SAAS,IAAI,aAAa,EAClC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CACxC,CAAA;IACD,wGAAwG;IACxG,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAC1D,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IACZ,OAAO;QACL,GAAG,KAAK;QACR,SAAS,EAAE,KAAK,CAAC,MAAM,KAAK,SAAS;QACrC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAE,SAA8B;KACnE,CAAA;AACH,CAAC"}

package/dist/read-deferred.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `readDeferred` — Preact's analogue of React 19's `use()` for a deferred promise (preact/compat has
+ * no `use`). Reads a React-style tagged thenable synchronously: returns the value if fulfilled, throws
+ * the reason if rejected, else throws the promise so `<Suspense>` awaits it. The core tags
+ * `status`/`value`/`reason` via the streamed `__nifraResolve`/`__nifraReject`; this also self-tags on
+ * settle so a server re-render (which has no `__nifraResolve`) reads "fulfilled" and stops re-throwing
+ * the already-resolved promise. Pure + isomorphic — no `preact` import, so it unit-tests directly.
+ */
+export type Thenable<T> = Promise<T> & {
+    status?: "pending" | "fulfilled" | "rejected";
+    value?: T;
+    reason?: unknown;
+};
+export declare function readDeferred<T>(promise: Thenable<T>): T;
+//# sourceMappingURL=read-deferred.d.ts.map

package/dist/read-deferred.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-deferred.d.ts","sourceRoot":"","sources":["../src/read-deferred.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG;IACrC,MAAM,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,CAAA;IAC7C,KAAK,CAAC,EAAE,CAAC,CAAA;IACT,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAiBvD"}

package/dist/read-deferred.js

@@ -0,0 +1,18 @@
+export function readDeferred(promise) {
+    if (promise.status === "fulfilled")
+        return promise.value;
+    if (promise.status === "rejected")
+        throw promise.reason;
+    if (promise.status === undefined) {
+        promise.status = "pending";
+        promise.then((v) => {
+            promise.status = "fulfilled";
+            promise.value = v;
+        }, (e) => {
+            promise.status = "rejected";
+            promise.reason = e;
+        });
+    }
+    throw promise; // pending — <Suspense> awaits it; the self-tag above wakes the re-render.
+}
+//# sourceMappingURL=read-deferred.js.map

package/dist/read-deferred.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-deferred.js","sourceRoot":"","sources":["../src/read-deferred.ts"],"names":[],"mappings":"AAcA,MAAM,UAAU,YAAY,CAAI,OAAoB;IAClD,IAAI,OAAO,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC,KAAU,CAAA;IAC7D,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU;QAAE,MAAM,OAAO,CAAC,MAAM,CAAA;IACvD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAA;QAC1B,OAAO,CAAC,IAAI,CACV,CAAC,CAAC,EAAE,EAAE;YACJ,OAAO,CAAC,MAAM,GAAG,WAAW,CAAA;YAC5B,OAAO,CAAC,KAAK,GAAG,CAAC,CAAA;QACnB,CAAC,EACD,CAAC,CAAC,EAAE,EAAE;YACJ,OAAO,CAAC,MAAM,GAAG,UAAU,CAAA;YAC3B,OAAO,CAAC,MAAM,GAAG,CAAC,CAAA;QACpB,CAAC,CACF,CAAA;IACH,CAAC;IACD,MAAM,OAAO,CAAA,CAAC,0EAA0E;AAC1F,CAAC"}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@nifrajs/web-preact",
+  "version": "0.1.0-alpha.1",
+  "description": "Preact render adapter for @nifrajs/web — streaming SSR + hydration (no build plugin).",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "bun": "./src/client.ts",
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./await": {
+      "bun": "./src/await.ts",
+      "types": "./dist/await.d.ts",
+      "default": "./dist/await.js"
+    },
+    "./fetcher": {
+      "bun": "./src/fetcher.ts",
+      "types": "./dist/fetcher.d.ts",
+      "default": "./dist/fetcher.js"
+    },
+    "./query": {
+      "bun": "./src/query.ts",
+      "types": "./dist/query.d.ts",
+      "default": "./dist/query.js"
+    },
+    "./i18n": {
+      "bun": "./src/i18n.ts",
+      "types": "./dist/i18n.d.ts",
+      "default": "./dist/i18n.js"
+    },
+    "./image": {
+      "bun": "./src/image.ts",
+      "types": "./dist/image.d.ts",
+      "default": "./dist/image.js"
+    },
+    "./content": {
+      "bun": "./src/content.ts",
+      "types": "./dist/content.d.ts",
+      "default": "./dist/content.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nifrajs/i18n": "workspace:*",
+    "@nifrajs/image": "workspace:*",
+    "@nifrajs/web": "workspace:*",
+    "preact-render-to-string": "^6.5.0"
+  },
+  "peerDependencies": {
+    "preact": "^10.19.0"
+  },
+  "devDependencies": {
+    "preact": "^10.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/web-preact"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/await.ts

@@ -0,0 +1,78 @@
+import type { Deferred } from "@nifrajs/web"
+import type { ComponentChildren, VNode } from "preact"
+/**
+ * `@nifrajs/web-preact/await` — the `<Await>` primitive for deferred loader data (`defer()`). Isomorphic
+ * and imports only `preact`/`preact/compat` + a type from `@nifrajs/web` (never the server renderer), so
+ * route components can use it without dragging server code into the client bundle. No JSX (the package
+ * builds with plain `tsc`).
+ *
+ * Preact's compat has no React 19 `use()` hook, so `readDeferred` (in `./read-deferred`) reads the
+ * React-style thenable the core tags (`status`/`value`/`reason`, via the streamed
+ * `__nifraResolve`/`__nifraReject`) synchronously: on the client a settled deferred renders its content
+ * directly into the boundary the server streamed (no re-suspend, no fallback flash). While pending it
+ * throws the promise so `<Suspense>` streams the fallback (server) / shows it until settle (client).
+ */
+import { Component, createElement, Suspense } from "preact/compat"
+import { readDeferred, type Thenable } from "./read-deferred.ts"
+
+export interface AwaitProps<T> {
+  /** A `Deferred<T>` from a loader's `defer(...)`, or an already-resolved value (client nav). */
+  readonly resolve: Deferred<T> | T
+  readonly fallback?: ComponentChildren
+  /** Rendered if the deferred rejects (the streamed `__nifraReject`). Without it the error
+   * propagates to the nearest error boundary. */
+  readonly errorFallback?: (error: unknown) => ComponentChildren
+  readonly children: (value: T) => ComponentChildren
+}
+
+// Catches the rejection `readDeferred` throws when the deferred rejects → renders `errorFallback`. A
+// class is required (error boundaries have no hook form). Local so `<Await>` is self-contained.
+class AwaitBoundary extends Component<
+  { fallback: (error: unknown) => ComponentChildren; children?: ComponentChildren },
+  { caught: boolean; error: unknown }
+> {
+  override state: { caught: boolean; error: unknown } = { caught: false, error: undefined }
+  static override getDerivedStateFromError(error: unknown): { caught: boolean; error: unknown } {
+    return { caught: true, error }
+  }
+  override render(): ComponentChildren {
+    return this.state.caught ? this.props.fallback(this.state.error) : this.props.children
+  }
+}
+
+function isDeferred<T>(value: Deferred<T> | T): value is Deferred<T> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { __nifra_deferred?: unknown }).__nifra_deferred === true
+  )
+}
+
+// Type-erased (non-generic) so `createElement` infers cleanly; `Await<T>` casts at the call site.
+function Resolved(props: {
+  marker: Deferred<unknown>
+  render: (value: unknown) => ComponentChildren
+}): ComponentChildren {
+  return props.render(readDeferred(props.marker.promise as Thenable<unknown>))
+}
+
+/**
+ * Render deferred loader data: show `fallback` until the `Deferred` settles (streamed in by the
+ * server), then `children(value)`. An already-resolved `resolve` (a client navigation awaited it)
+ * renders immediately. Pairs with a loader's `defer(...)`.
+ */
+export function Await<T>(props: AwaitProps<T>): VNode | ComponentChildren {
+  if (!isDeferred(props.resolve)) return props.children(props.resolve)
+  const suspense = createElement(
+    Suspense,
+    { fallback: props.fallback },
+    createElement(Resolved, {
+      marker: props.resolve,
+      // safe: the registry promise resolves to T; Resolved is type-erased to satisfy createElement.
+      render: props.children as (value: unknown) => ComponentChildren,
+    }),
+  )
+  return props.errorFallback
+    ? createElement(AwaitBoundary, { fallback: props.errorFallback }, suspense)
+    : suspense
+}

package/src/client.ts

@@ -0,0 +1,43 @@
+import type { MountRouterOptions, RenderProps } from "@nifrajs/web"
+/**
+ * @nifrajs/web-preact/client — Preact client runtime. `hydrate` hydrates a single SSR'd route;
+ * `mountRouter` hydrates a stateful Router that subscribes to the agnostic store (via
+ * `useSyncExternalStore` from preact/compat) and re-renders the matched chain on every client
+ * navigation (no full reload). Kept in its own entry so server code (preact-render-to-string) stays
+ * out of the client bundle.
+ */
+import { type FunctionComponent, h, hydrate as preactHydrate } from "preact"
+import { useSyncExternalStore } from "preact/compat"
+import { compose } from "./compose.ts"
+import { setMountedRouter } from "./fetcher.ts"
+
+// The `_error` boundary chain element — defined in its own (DOM-free) module, re-exported here so
+// nifra's client codegen resolves it from `@nifrajs/web-preact/client` alongside `mountRouter`.
+export { errorBoundary } from "./error.ts"
+
+/** Hydrate a server-rendered Preact layout `chain` (with the loader `props`) inside `container`. */
+export function hydrate(chain: readonly unknown[], props: RenderProps, container: unknown): void {
+  preactHydrate(compose(chain, props), container as Element)
+}
+
+/**
+ * Hydrate a stateful Preact Router. `useSyncExternalStore` (preact/compat) subscribes to the
+ * agnostic store and re-renders the matched layout chain on each store change — so client
+ * navigations swap routes without a full reload. Preact's compat `useSyncExternalStore` is 2-arg
+ * (no `getServerSnapshot`); `router.snapshot` is deterministic, so hydration matches the SSR markup.
+ */
+export function mountRouter(options: MountRouterOptions): void {
+  const { router, routes, container } = options
+  setMountedRouter(router) // expose it to useFetcher/useFetchers (same page, client-only)
+  const Router: FunctionComponent = () => {
+    const state = useSyncExternalStore(router.subscribe, router.snapshot)
+    return compose(routes[state.routeId] ?? [], {
+      data: state.data,
+      actionData: state.actionData,
+      pending: state.pending,
+      // The in-flight submission (for optimistic UI) — spread only when present.
+      ...(state.submission ? { submission: state.submission } : {}),
+    })
+  }
+  preactHydrate(h(Router, null), container as Element)
+}

package/src/compose.ts

@@ -0,0 +1,23 @@
+import type { RenderProps } from "@nifrajs/web"
+import { type ComponentType, h, type VNode } from "preact"
+
+/**
+ * Fold a layout chain (outermost layout → page) into a single Preact tree: the page (innermost)
+ * receives `props` (the loader data); each layout wraps the child via its `children` (Preact passes
+ * the 3rd `h` arg as `props.children`). Shared by the server adapter (renderToReadableStream) and
+ * the client (hydrate / mountRouter) — the Preact analogue of the React adapter's `compose`.
+ */
+export function compose(chain: readonly unknown[], props: RenderProps): VNode {
+  const last = chain.length - 1
+  // The chain holds opaque framework components; cast at this plumbing boundary. The page gets the
+  // loader props (typed via ComponentType<RenderProps>), then we widen `h`'s VNode<Attributes &
+  // RenderProps> to the uniform VNode the fold accumulates into. Preact's VNode<P> is invariant in P
+  // under exactOptionalPropertyTypes, so the widen needs the explicit `as VNode` (a comparability
+  // cast — Attributes & RenderProps is assignable to {}, so this is not an unsafe coercion).
+  let node: VNode = h(chain[last] as ComponentType<RenderProps>, props) as VNode
+  for (let i = last - 1; i >= 0; i--) {
+    // children passed as the 3rd arg — Preact's canonical form (mirrors the React adapter).
+    node = h(chain[i] as ComponentType, null, node)
+  }
+  return node
+}

package/src/content.ts

@@ -0,0 +1,28 @@
+/**
+ * `@nifrajs/web-preact/content` — render pre-rendered HTML (e.g. a `@nifrajs/content` collection entry's
+ * `.html`) into the DOM via `dangerouslySetInnerHTML`. Pairs with content collections:
+ * `<Content html={entry.html} />`.
+ *
+ * Security: injects raw HTML, so `html` MUST be trusted (your own Markdown/content, rendered at
+ * build/server time) — never pass user-supplied HTML without sanitizing it first.
+ */
+import { createElement, type JSX, type VNode } from "preact"
+
+export interface ContentProps
+  extends Omit<JSX.HTMLAttributes<HTMLElement>, "dangerouslySetInnerHTML"> {
+  /** Trusted, pre-rendered HTML (e.g. `entry.html`). */
+  readonly html: string
+  /** Wrapper element (default `"div"`). */
+  readonly as?: string
+}
+
+/** Render trusted HTML into a wrapper element. Extra props (`class`, `id`, `style`, …) pass through. */
+export function Content({ html, as, ...rest }: ContentProps): VNode {
+  // Typed intermediate (like `<Image>`) keeps the inferred `VNode` generic stable under
+  // exactOptionalPropertyTypes (a bare object literal infers an over-specific, non-assignable VNode).
+  const props: JSX.HTMLAttributes<HTMLElement> = {
+    ...rest,
+    dangerouslySetInnerHTML: { __html: html },
+  }
+  return createElement(as ?? "div", props)
+}

package/src/error.ts

@@ -0,0 +1,33 @@
+/**
+ * `errorBoundary` — the Preact error-boundary chain element for nifra's `_error.tsx`. Its own module
+ * (imports only `preact`) so it's unit-testable off the DOM and the client codegen can import it from
+ * `@nifrajs/web-preact/client` (which re-exports it).
+ */
+import { Component, type ComponentChildren, createElement, type FunctionComponent } from "preact"
+
+/**
+ * Build an error-boundary chain element bound to `fallback` (a route's `_error` component). nifra's
+ * client codegen inserts it before the page in the matched chain; a render error in the subtree renders
+ * `fallback` with `{ data: { name, message } }` instead of crashing the app. DOM-transparent (it renders
+ * its children directly — no wrapper element), so it adds no markup and never disturbs hydration.
+ */
+export function errorBoundary(fallback: unknown): unknown {
+  type Props = { children?: ComponentChildren }
+  type State = { error: Error | null }
+  return class NifraErrorBoundary extends Component<Props, State> {
+    constructor(props: Props) {
+      super(props)
+      this.state = { error: null }
+    }
+    static override getDerivedStateFromError(error: Error): State {
+      return { error }
+    }
+    override render(): ComponentChildren {
+      const { error } = this.state
+      if (error === null) return this.props.children
+      // `fallback` is the route's `_error` default export — opaque to the core, a component here.
+      const Fallback = fallback as FunctionComponent<{ data: { name: string; message: string } }>
+      return createElement(Fallback, { data: { name: error.name, message: error.message } })
+    }
+  }
+}

package/src/fetcher.ts

@@ -0,0 +1,67 @@
+import type { ClientRouter, Fetcher, FetcherState } from "@nifrajs/web"
+/**
+ * `@nifrajs/web-preact/fetcher` — Preact bindings for concurrent fetchers. `useFetcher(key)` subscribes a
+ * component to an independent {@link Fetcher} (via `useSyncExternalStore` from preact/compat) and
+ * returns its reactive state plus `load`/`submit`; `useFetchers()` subscribes to the whole live
+ * collection. Imports only `preact/compat` + `@nifrajs/web` types, so route components can use it on the
+ * server *and* client. No JSX (the package builds with plain `tsc`).
+ *
+ * The router that owns the fetchers is the one `mountRouter` hydrated — it registers itself here via
+ * `setMountedRouter`. On the server (no mount) there is no router, so the hooks return an idle state
+ * (fetchers are client-only). Preact's compat `useSyncExternalStore` is 2-arg (no `getServerSnapshot`);
+ * with no router the `getSnapshot` already returns idle, so the first client render after `mountRouter`
+ * matches the SSR markup — no hydration mismatch.
+ */
+import { useSyncExternalStore } from "preact/compat"
+
+// The active client router (set by `mountRouter`). Module-scoped: the browser mounts one app per
+// page, and fetchers never exist on the server. Shared with `client.ts`'s `mountRouter`.
+let mountedRouter: ClientRouter | undefined
+
+/** Register (or clear) the router that owns fetchers — called by `mountRouter`. Not for app use. */
+export function setMountedRouter(router: ClientRouter | undefined): void {
+  mountedRouter = router
+}
+
+// Stable idle values for the server / pre-mount snapshot (stable refs → no `useSyncExternalStore`
+// loop, no hydration mismatch).
+const IDLE: FetcherState = { pending: false, data: undefined }
+const NO_FETCHERS: readonly Fetcher[] = []
+const noopSubscribe = (): (() => void) => () => {}
+const noopAsync = async (): Promise<void> => {}
+const idleSnapshot = (): FetcherState => IDLE
+const noFetchers = (): readonly Fetcher[] => NO_FETCHERS
+
+/** A fetcher's reactive {@link FetcherState} plus its imperative `load`/`submit`. */
+export interface FetcherHandle extends FetcherState {
+  /** Load a route path's loader data into this fetcher (concurrent; doesn't touch the active view). */
+  readonly load: (path: string) => Promise<void>
+  /** Submit an action into this fetcher (concurrent); honors `X-Nifra-Revalidate`. */
+  readonly submit: (action: string, body: NonNullable<RequestInit["body"]>) => Promise<void>
+}
+
+/**
+ * Subscribe to the independent fetcher for `key` (created lazily, stable across renders). Returns its
+ * state (`pending`/`data`/`actionData`/`submission`) + `load`/`submit`. Multiple `useFetcher` calls
+ * with different keys run concurrently without disturbing the active route or each other.
+ */
+export function useFetcher(key: string): FetcherHandle {
+  const fetcher = mountedRouter?.fetcher(key)
+  const state = useSyncExternalStore(
+    fetcher?.subscribe ?? noopSubscribe,
+    fetcher?.snapshot ?? idleSnapshot,
+  )
+  return { ...state, load: fetcher?.load ?? noopAsync, submit: fetcher?.submit ?? noopAsync }
+}
+
+/**
+ * Subscribe to the whole live fetcher collection — for a global busy view (e.g. "3 saving…"). Read
+ * each entry's `.snapshot()` for its state. Re-renders whenever any fetcher transitions or a new one
+ * is created.
+ */
+export function useFetchers(): readonly Fetcher[] {
+  return useSyncExternalStore(
+    mountedRouter?.subscribeFetchers ?? noopSubscribe,
+    mountedRouter?.fetchers ?? noFetchers,
+  )
+}

package/src/i18n.ts

@@ -0,0 +1,47 @@
+/**
+ * `@nifrajs/web-preact/i18n` — Preact bindings for `@nifrajs/i18n`. `<I18nProvider locale messages>` builds a
+ * `Formatter` (memoized) and provides it; `useT()` reads it. Both `locale` + `messages` are
+ * serializable, so a loader returns them, the page renders with the negotiated catalog on the server,
+ * and the client rebuilds the same formatter from the same props (no mismatch). Uses `preact` +
+ * `preact/hooks` — no JSX.
+ */
+import { createFormatter, type Formatter, type Messages } from "@nifrajs/i18n"
+import { type ComponentChildren, createContext, createElement, type VNode } from "preact"
+import { useContext, useMemo } from "preact/hooks"
+
+const I18nContext = createContext<Formatter | null>(null)
+
+// Preact's `createElement` overloads don't reconcile a typed `Context.Provider` (required `value`)
+// under `exactOptionalPropertyTypes` — overload resolution drops `value` and infers the props as `{}`.
+// The call is correct at runtime (proven by the tests), so invoke it through a precisely-typed element
+// factory that states the real contract (`{ value }` + children), rather than scatter `any`.
+const createProvider = createElement as (
+  type: typeof I18nContext.Provider,
+  props: { value: Formatter | null },
+  children?: ComponentChildren,
+) => VNode
+
+export interface I18nProviderProps {
+  readonly locale: string
+  readonly messages: Messages
+  readonly children?: ComponentChildren
+}
+
+/** Provide a {@link Formatter} (built from `locale` + `messages`) to the subtree. Memoized on
+ * `locale`/`messages`, so switching locale rebuilds it and re-renders consumers. */
+export function I18nProvider(props: I18nProviderProps): VNode {
+  const formatter = useMemo(
+    () => createFormatter(props.locale, props.messages),
+    [props.locale, props.messages],
+  )
+  return createProvider(I18nContext.Provider, { value: formatter }, props.children)
+}
+
+/** Read the current {@link Formatter} (`{ locale, t, n, d }`). Throws if no `<I18nProvider>` is above. */
+export function useT(): Formatter {
+  const formatter = useContext(I18nContext)
+  if (formatter === null) {
+    throw new Error("[nifra/web-preact] useT() must be used within an <I18nProvider>")
+  }
+  return formatter
+}

package/src/image.ts

@@ -0,0 +1,42 @@
+/**
+ * `@nifrajs/web-preact/image` — a CLS-safe responsive Preact `<Image>`. A thin wrapper over `resolveImage`
+ * from `@nifrajs/image`: it computes the responsive `<img>` attributes (`src`/`srcset`/`sizes`/`width`/
+ * `height`/`loading`/`decoding`/`fetchpriority` — Preact uses lowercase HTML attribute names, so it
+ * spreads `toHtmlAttrs`) and forwards any extra DOM props (`class`, `style`, `id`, `data-*`, handlers).
+ * Resizing is delegated to the `loader` (an image CDN); nifra bundles no codec. No JSX (`h`).
+ */
+import { type ImageLoader, type ImageProps, resolveImage, toHtmlAttrs } from "@nifrajs/image"
+import { h, type JSX, type VNode } from "preact"
+
+/** Attributes `resolveImage` computes — callers can't override them via DOM passthrough. */
+type ComputedAttrs =
+  | "src"
+  | "srcset"
+  | "sizes"
+  | "width"
+  | "height"
+  | "alt"
+  | "loading"
+  | "decoding"
+  | "fetchpriority"
+
+export interface ImageComponentProps
+  extends ImageProps,
+    Omit<JSX.IntrinsicElements["img"], ComputedAttrs | keyof ImageProps> {
+  /** CDN URL builder. Defaults to the identity loader (no transform — still CLS-safe + lazy). */
+  readonly loader?: ImageLoader
+}
+
+/**
+ * Render a responsive, CLS-safe `<img>`. `width`+`height` are required (reserve layout space);
+ * `priority` marks the LCP image (`eager` + `fetchpriority="high"`). Extra DOM props pass through.
+ */
+export function Image(props: ImageComponentProps): VNode {
+  // Strip the nifra-only props (not valid DOM attributes) before forwarding the rest to <img>.
+  const { loader, widths, quality, priority, ...rest } = props
+  const attrs = toHtmlAttrs(resolveImage(props, loader))
+  // `attrs` wins over the raw src/width/height/alt/sizes/loading still present in `rest`. The typed
+  // local pins Preact's `h` to its string-tag overload (spreads skip excess-property checks).
+  const imgProps: JSX.IntrinsicElements["img"] = { ...rest, ...attrs }
+  return h("img", imgProps)
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+import type { RenderAdapter } from "@nifrajs/web"
+/**
+ * @nifrajs/web-preact — the Preact render adapter for @nifrajs/web (server side). Streaming SSR via
+ * `renderToReadableStream` from `preact-render-to-string/stream` (a Web `ReadableStream<Uint8Array>`,
+ * the seam's native shape); the layout-chain fold is in `./compose`. Client hydration lives in
+ * `@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"
+
+/** 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))
+  },
+  renderToStream(chain, props) {
+    // `renderToReadableStream` yields a Web ReadableStream<Uint8Array>; <Suspense> boundaries
+    // (preact/compat) stream as they resolve, mirroring the React adapter.
+    return renderToReadableStream(compose(chain, props))
+  },
+  // Preact reconciles against the existing DOM on hydrate (like React), so there's no per-document
+  // bootstrap script — the seam allows the empty string (contrast Solid's generateHydrationScript).
+  hydrationHead() {
+    return ""
+  },
+}