@nifrajs/web-svelte 0.1.0-alpha.1

package/src/error.ts

@@ -0,0 +1,15 @@
+/**
+ * `errorBoundary` — the Svelte `_error.tsx` boundary chain element. Svelte components are compiled (not
+ * JS closures), so unlike the other adapters this can't return a component bound to `fallback`. Instead
+ * it returns a **marker** that `Chain.svelte` recognises and renders as a `<svelte:boundary>` (Svelte
+ * 5.3+) with `fallback` as the `failed` snippet. Re-exported from `@nifrajs/web-svelte/client` so nifra's
+ * client codegen inserts it before the page in the matched chain.
+ */
+export interface NifraSvelteErrorBoundary {
+  readonly __nifraErrorBoundary: unknown
+}
+
+/** Wrap a route's `_error` component as a boundary marker for `Chain.svelte` to render. */
+export function errorBoundary(fallback: unknown): NifraSvelteErrorBoundary {
+  return { __nifraErrorBoundary: fallback }
+}

package/src/fetcher.ts

@@ -0,0 +1,66 @@
+import type { ClientRouter, Fetcher, FetcherState } from "@nifrajs/web"
+/**
+ * `@nifrajs/web-svelte/fetcher` — Svelte bindings for concurrent fetchers, as **Svelte stores** (plain
+ * `.ts`, no runes/compiler needed). `useFetcher(key)` returns a `Readable<FetcherState>` augmented with
+ * `load`/`submit` — read it reactively in a component with `$fetcher` (auto-subscription), call
+ * `fetcher.load(...)` / `fetcher.submit(...)` imperatively. `useFetchers()` returns the live collection
+ * as a store. The store's start/stop notifier subscribes to the agnostic store lazily (on the first
+ * `$`-subscription) and unsubscribes on the last — so lifecycle is tied to the component automatically.
+ *
+ * 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 stores hold an idle value
+ * (fetchers are client-only); the first client render starts from the same idle snapshot — no mismatch.
+ */
+import { type Readable, readable } from "svelte/store"
+
+// 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
+}
+
+const IDLE: FetcherState = { pending: false, data: undefined }
+const noopAsync = async (): Promise<void> => {}
+
+/** A fetcher store: a `Readable<FetcherState>` (read via `$`) plus imperative `load`/`submit`. */
+export type FetcherStore = Readable<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 a
+ * store of its state (`pending`/`data`/`actionData`/`submission`) augmented with `load`/`submit`.
+ * Multiple `useFetcher` calls with different keys run concurrently without disturbing the active route.
+ */
+export function useFetcher(key: string): FetcherStore {
+  const fetcher = mountedRouter?.fetcher(key)
+  const store = readable<FetcherState>(fetcher ? fetcher.snapshot() : IDLE, (set) => {
+    if (fetcher === undefined) return
+    set(fetcher.snapshot())
+    return fetcher.subscribe(() => set(fetcher.snapshot()))
+  })
+  return Object.assign(store, {
+    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. The store updates whenever any fetcher transitions or a
+ * new one is created.
+ */
+export function useFetchers(): Readable<readonly Fetcher[]> {
+  const router = mountedRouter
+  return readable<readonly Fetcher[]>(router ? router.fetchers() : [], (set) => {
+    if (router === undefined) return
+    set(router.fetchers())
+    return router.subscribeFetchers(() => set(router.fetchers()))
+  })
+}

package/src/i18n.ts

@@ -0,0 +1,23 @@
+/**
+ * `@nifrajs/web-svelte/i18n` — Svelte bindings for `@nifrajs/i18n`: the `<I18nProvider>` component (re-exported
+ * from `I18nProvider.svelte`) plus `useT()`, which reads the provided `Formatter` from Svelte context.
+ * Call `useT()` during a component's initialization (like any `getContext`).
+ */
+import type { Formatter } from "@nifrajs/i18n"
+import { getContext } from "svelte"
+
+export { default as I18nProvider, type I18nProviderProps } from "./I18nProvider.svelte"
+
+// Must match the string key `I18nProvider.svelte` passes to `setContext` (a string avoids a
+// `.svelte` → `.ts` import that wouldn't resolve once the .svelte is copied to dist).
+const I18N_KEY = "@nifrajs/web-svelte:i18n"
+
+/** Read the current {@link Formatter} (`{ locale, t, n, d }`). Throws if no `<I18nProvider>` is above.
+ * nifra switches locale by re-navigating, which re-runs the consuming component with the new catalog. */
+export function useT(): Formatter {
+  const get = getContext<(() => Formatter) | undefined>(I18N_KEY)
+  if (get === undefined) {
+    throw new Error("[nifra/web-svelte] useT() must be used within an <I18nProvider>")
+  }
+  return get()
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * @nifrajs/web-svelte — the Svelte 5 render adapter for @nifrajs/web (server side) + the `.svelte` compiler
+ * Bun-plugin. SSR via Svelte's `render` (svelte/server), which returns HTML strings (Svelte SSR is
+ * string-based, not a stream), wrapped in a one-chunk Web `ReadableStream` (the seam's shape). The
+ * layout-chain fold is the recursive `Chain.svelte`. Client hydration lives in `@nifrajs/web-svelte/client`.
+ * Svelte components compile from `.svelte` files, so this adapter ships a build plugin (like
+ * `@nifrajs/web-solid`'s Babel plugin) — there is no callable-component runtime.
+ */
+import type { RenderAdapter } from "@nifrajs/web"
+import { render } from "svelte/server"
+import Chain from "./Chain.svelte"
+
+// Re-export the compiler plugin for convenience. NOTE: the SSR preload must import it from
+// `@nifrajs/web-svelte/plugin` (not from here) — importing this module eagerly loads `Chain.svelte`,
+// which must be compiled by the already-registered plugin.
+export { svelteBunPlugin } from "./plugin.ts"
+
+// Svelte SSR yields a complete HTML string; the seam wants a stream, so emit it as one chunk.
+function oneChunk(html: string): ReadableStream<Uint8Array> {
+  const bytes = new TextEncoder().encode(html)
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes)
+      controller.close()
+    },
+  })
+}
+
+/** The Svelte server render adapter — pass to @nifrajs/web's `renderPage`. */
+export const svelteAdapter: RenderAdapter = {
+  // Svelte SSR is already synchronous + string-based, so this is the native shape: `renderToString`
+  // returns the body directly (renderPage buffers it on the non-deferred fast path), and
+  // `renderToStream` wraps the same string in a one-chunk stream for the deferred path. No streaming
+  // renderer to skip here — but going straight to a string avoids the per-request stream allocation.
+  renderToString(chain, props) {
+    return render(Chain, { props: { chain, props } }).body
+  },
+  renderToStream(chain, props) {
+    // `Chain` folds the layout chain (page innermost gets `props`; layouts wrap via their `children`
+    // snippet). Svelte's `render` returns { head, body }; the body goes into #root. (Svelte's dynamic
+    // `head` — from <svelte:head> — isn't surfaced through the seam's static `hydrationHead`; nifra's
+    // own meta/head API manages the document head instead.)
+    const { body } = render(Chain, { props: { chain, props } })
+    return oneChunk(body)
+  },
+  // Svelte's client `hydrate` reconciles against the existing DOM; no per-document bootstrap script is
+  // needed (contrast Solid's generateHydrationScript) — the seam allows the empty string.
+  hydrationHead() {
+    return ""
+  },
+}

package/src/mdx.ts

@@ -0,0 +1,72 @@
+import type { BunPlugin } from "bun"
+import { compile } from "svelte/compiler"
+
+/**
+ * `@nifrajs/web-svelte/mdx` — compile `.mdx` routes/files to **Svelte** components. Svelte has no JSX
+ * runtime, so (unlike the JSX-family `mdxBunPlugin`) MDX-for-Svelte goes through `mdsvex` — Svelte's
+ * own Markdown compiler — which produces a `.svelte` module, then the standard `svelte/compiler` runs
+ * (`generate: "server"` for SSR, `"client"` for the browser). Pass it to `buildClient`/`buildServer`'s
+ * `plugins` alongside `svelteBunPlugin` (one handles `.svelte`, this one `.mdx`). `mdsvex` is an
+ * optional peer, lazy-loaded at build time.
+ *
+ * `<style>` blocks inside MDX are scoped + bundled exactly like `svelteBunPlugin`'s (own CSS namespace
+ * so the two plugins don't collide).
+ */
+const MDSVEX_MODULE = "mdsvex" // non-literal so consumers don't need mdsvex's types to typecheck
+const STYLE_SUFFIX = "?svelte-mdx-css"
+const STYLE_NS = "nifra-svelte-mdx-css"
+
+interface Mdsvex {
+  compile(source: string, options?: Record<string, unknown>): Promise<{ code: string } | undefined>
+}
+
+/** Build a `Bun.build` plugin that loads `.mdx` files as Svelte components via mdsvex. `generate`:
+ * `"ssr"` for the server build, `"dom"` for the client (matches `svelteBunPlugin`). */
+export function svelteMdxBunPlugin(generate: "dom" | "ssr"): BunPlugin {
+  const cssByPath = new Map<string, string>()
+  return {
+    name: `nifra-svelte-mdx-${generate}`,
+    async setup(build) {
+      let mdsvexCompile: Mdsvex["compile"]
+      try {
+        mdsvexCompile = ((await import(MDSVEX_MODULE)) as Mdsvex).compile
+      } catch {
+        throw new Error(
+          "@nifrajs/web-svelte/mdx: compiling `.mdx` for Svelte needs the `mdsvex` package — install it (`bun add mdsvex`).",
+        )
+      }
+      build.onLoad({ filter: /\.mdx(\?|$)/ }, async (args) => {
+        const path = args.path.split("?")[0] ?? args.path
+        // 1. Markdown/MDX → Svelte source (mdsvex). `extensions` must include `.mdx` or mdsvex skips the
+        // file (returns undefined — it only processes its configured extensions, default `.svx`).
+        const pre = await mdsvexCompile(await Bun.file(path).text(), {
+          filename: path,
+          extensions: [".mdx", ".svx", ".md"],
+        })
+        if (!pre) throw new Error(`@nifrajs/web-svelte/mdx: mdsvex produced no output for ${path}`)
+        // 2. Svelte source → JS, exactly like `svelteBunPlugin`.
+        const { js, css } = compile(pre.code, {
+          generate: generate === "ssr" ? "server" : "client",
+          filename: path,
+          css: "external",
+        })
+        if (generate === "dom" && css?.code) {
+          cssByPath.set(path, css.code)
+          return {
+            contents: `${js.code}\nimport ${JSON.stringify(path + STYLE_SUFFIX)}\n`,
+            loader: "js",
+          }
+        }
+        return { contents: js.code, loader: "js" }
+      })
+      build.onResolve({ filter: /\?svelte-mdx-css$/ }, (args) => ({
+        path: args.path,
+        namespace: STYLE_NS,
+      }))
+      build.onLoad({ filter: /.*/, namespace: STYLE_NS }, (args) => ({
+        contents: cssByPath.get(args.path.slice(0, -STYLE_SUFFIX.length)) ?? "",
+        loader: "css",
+      }))
+    },
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,60 @@
+import type { BunPlugin } from "bun"
+import { compile } from "svelte/compiler"
+
+/**
+ * `@nifrajs/web-svelte/plugin` — the `.svelte` compiler Bun-plugin, in its OWN module (no `.svelte`
+ * imports). This matters for the SSR preload: `bun --preload` must register the plugin BEFORE any
+ * `.svelte` file is loaded. Importing it from the package root (`./index`) would eagerly load
+ * `Chain.svelte` (the adapter's fold) before the plugin is registered — so it lives here instead.
+ *
+ * `generate: "server"` for SSR, `"client"` for the browser (Svelte 5's client output is hydratable).
+ * Preload it for SSR (`bun --preload`) and pass it to `buildClient({ plugins: [...] })` for the client
+ * bundle. The compiler runs at build time, on `.svelte` files only.
+ *
+ * `<style>` blocks: Svelte scopes selectors (`.foo.svelte-<hash>`) and bakes the matching classes into
+ * the markup (both client + server output), so SSR HTML is already scoped. The **client** build emits
+ * the scoped stylesheet as a virtual `?svelte-css` module that `Bun.build`'s CSS bundler folds into the
+ * app stylesheet (served as a `<link>`); the SSR build drops it (the stylesheet ships from the client
+ * build — no double-emit). With `nifra dev`, `@sveltejs/vite-plugin-svelte` injects the CSS instead.
+ */
+const STYLE_SUFFIX = "?svelte-css"
+const STYLE_NS = "nifra-svelte-css"
+
+export function svelteBunPlugin(generate: "dom" | "ssr"): BunPlugin {
+  // Compiled scoped CSS per `.svelte` file (client build only) — read back by the virtual-module loader.
+  const cssByPath = new Map<string, string>()
+  return {
+    name: `nifra-svelte-${generate}`,
+    setup(build) {
+      // Match `.svelte`, tolerating a `?query` suffix (dev servers append one to bust Bun's import
+      // cache); strip it before reading the file off disk.
+      build.onLoad({ filter: /\.svelte(\?|$)/ }, async (args) => {
+        const path = args.path.split("?")[0] ?? args.path
+        const source = await Bun.file(path).text()
+        const { js, css } = compile(source, {
+          generate: generate === "ssr" ? "server" : "client",
+          filename: path,
+          css: "external", // emit the scoped stylesheet separately (not injected into the JS)
+        })
+        if (generate === "dom" && css?.code) {
+          cssByPath.set(path, css.code)
+          // Import the virtual style module so the bundler pulls the scoped CSS into the app stylesheet.
+          return {
+            contents: `${js.code}\nimport ${JSON.stringify(path + STYLE_SUFFIX)}\n`,
+            loader: "js",
+          }
+        }
+        return { contents: js.code, loader: "js" }
+      })
+      // Virtual CSS module: `<file>.svelte?svelte-css` → the compiled scoped stylesheet (css loader).
+      build.onResolve({ filter: /\?svelte-css$/ }, (args) => ({
+        path: args.path,
+        namespace: STYLE_NS,
+      }))
+      build.onLoad({ filter: /.*/, namespace: STYLE_NS }, (args) => ({
+        contents: cssByPath.get(args.path.slice(0, -STYLE_SUFFIX.length)) ?? "",
+        loader: "css",
+      }))
+    },
+  }
+}

package/src/query.ts

@@ -0,0 +1,66 @@
+import {
+  createQueryClient,
+  type QueryClient,
+  type QueryHandle,
+  type QueryState,
+} from "@nifrajs/web"
+/**
+ * `@nifrajs/web-svelte/query` — Svelte bindings for the keyed query-cache, as **Svelte stores** (plain
+ * `.ts`). `useQuery(key, fn)` returns a `Readable<QueryState<T>>` augmented with `refetch` — read it
+ * reactively with `$query`. The store fetches on mount (the start notifier fires on the first
+ * `$`-subscription) and subscribes to the cache entry; concurrent `useQuery`s with the same key share
+ * one entry + one in-flight fetch (dedup). `useQueryClient` exposes `invalidateQueries`.
+ *
+ * The query client is created lazily **client-side only** (the `typeof window` guard) — on the server
+ * there is none, so `useQuery` holds 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 { type Readable, readable } from "svelte/store"
+
+let client: QueryClient | undefined
+function getClient(): QueryClient | undefined {
+  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(): Pick<QueryClient, "invalidateQueries"> {
+  return getClient() ?? { invalidateQueries: () => {} }
+}
+
+// Stable idle snapshot for the server / pre-fetch render.
+const IDLE: QueryState<never> = Object.freeze({
+  status: "pending",
+  data: undefined,
+  error: undefined,
+  isFetching: false,
+  updatedAt: Number.NEGATIVE_INFINITY,
+})
+
+/** A query store: a `Readable<QueryState<T>>` (read via `$`) plus `refetch`. */
+export type QueryStore<T> = Readable<QueryState<T>> & {
+  /** Force a refetch (ignores `staleTime`). */
+  readonly refetch: () => Promise<T>
+}
+
+/**
+ * Subscribe to the keyed query for `key`, fetched via `fn`. Returns a store of `{ status, data, error,
+ * isFetching, updatedAt }` augmented with `refetch`. Fetches on mount (first `$`-subscription); SSR-idle.
+ */
+export function useQuery<T>(key: unknown, fn: () => Promise<T>): QueryStore<T> {
+  const handle: QueryHandle<T> | undefined = getClient()?.query<T>(key, fn)
+  const store = readable<QueryState<T>>(handle ? handle.snapshot() : IDLE, (set) => {
+    if (handle === undefined) return
+    set(handle.snapshot())
+    const unsubscribe = handle.subscribe(() => set(handle.snapshot()))
+    handle.fetch().catch(() => {}) // fetch on mount (the first subscriber attached)
+    return unsubscribe
+  })
+  const refetch = handle
+    ? handle.refetch
+    : ((async () => {
+        throw new Error("[nifra/web-svelte] useQuery.refetch called with no query client (server?)")
+      }) as () => Promise<T>)
+  return Object.assign(store, { refetch })
+}

package/src/svelte-shim.d.ts

@@ -0,0 +1,9 @@
+// `.svelte` files are compiled by `svelteBunPlugin` (or the consumer's Svelte bundler), not by tsc.
+// This ambient declaration lets the .ts adapter/client import them with a usable type. The default
+// export is a Svelte 5 `Component`; our helpers take a loose props bag (the chain + the loader props).
+declare module "*.svelte" {
+  import type { Component } from "svelte"
+
+  const component: Component<Record<string, unknown>>
+  export default component
+}