@nifrajs/web 2.14.1 → 3.2.0

package/src/islands.ts

@@ -15,8 +15,13 @@
  * the route's `islandScripts`.
  */
 
-/** When an island's enhancer runs. Default `load`. */
-export type IslandStrategy = "load" | "idle" | "visible"
+import {
+  type IslandStrategy,
+  MAX_MEDIA_QUERY_LENGTH,
+  scheduleTrigger,
+} from "@nifrajs/island-trigger"
+
+export { type IslandStrategy, MAX_MEDIA_QUERY_LENGTH, scheduleTrigger }
 
 /** Optional teardown an enhancer returns (remove listeners/observers); run on `dispose()`. */
 export type IslandCleanup = () => void
@@ -29,7 +34,27 @@ export type IslandCleanup = () => void
 // biome-ignore lint/suspicious/noConfusingVoidType: `void` = "no cleanup returned", like React's EffectCallback - cleanup is optional.
 export type IslandEnhancer<P = unknown> = (el: HTMLElement, props: P) => IslandCleanup | void
 
-const NOOP = (): void => {}
+/**
+ * Author a typed enhancer. Pure identity at runtime (zero cost, tree-shaken away) - its only job is
+ * to pin the `data-props` shape so `el` and `props` are typed inside the body and the enhancer is
+ * assignable to `mountIslands`. Prefer this over an inline arrow whenever an island reads props:
+ *
+ *   const counter = defineIsland<{ start: number }>((el, props) => {
+ *     let n = props.start                       // props typed, no cast
+ *     const out = el.querySelector("output")!
+ *     const onClick = () => { out.textContent = String(++n) }
+ *     el.querySelector("button")?.addEventListener("click", onClick)
+ *     return () => el.querySelector("button")?.removeEventListener("click", onClick)
+ *   })
+ *   mountIslands({ counter })
+ *
+ * The props type is a contract, not a validator - `data-props` is JSON authored by your own SSR, so
+ * it is trusted framing, not user input. Keep the enhancer body imperative: read the DOM, wire
+ * listeners, return cleanup. No hidden reactivity to get wrong.
+ */
+export function defineIsland<P = unknown>(enhancer: IslandEnhancer<P>): IslandEnhancer<P> {
+  return enhancer
+}
 
 /** Parse an island's inline `data-props` JSON; malformed/absent → `undefined` (never throws). */
 function readProps(el: HTMLElement): unknown {
@@ -42,40 +67,6 @@ function readProps(el: HTMLElement): unknown {
   }
 }
 
-/** Run `run` per the island's strategy; returns a disposer that cancels a not-yet-fired trigger. */
-function whenStrategy(el: HTMLElement, strategy: IslandStrategy, run: () => void): () => void {
-  if (strategy === "idle") {
-    const ric = globalThis.requestIdleCallback
-    if (ric === undefined) {
-      const t = setTimeout(run, 1)
-      return () => clearTimeout(t)
-    }
-    const handle = ric(run)
-    return () => globalThis.cancelIdleCallback?.(handle)
-  }
-  if (strategy === "visible") {
-    // No IntersectionObserver (old engine / SSR smoke) → degrade to immediate, never skip the island.
-    if (typeof IntersectionObserver === "undefined") {
-      run()
-      return NOOP
-    }
-    const io = new IntersectionObserver((entries, obs) => {
-      for (const entry of entries) {
-        if (entry.isIntersecting) {
-          obs.disconnect()
-          run()
-          return
-        }
-      }
-    })
-    io.observe(el)
-    return () => io.disconnect()
-  }
-  // "load" (and any unknown value) → run immediately on mount.
-  run()
-  return NOOP
-}
-
 /**
  * Find every `<nifra-island data-id>` under `root` (default `document`) and enhance each with the
  * matching enhancer, honoring its `data-strategy`. An island whose `id` has no enhancer is left as
@@ -96,8 +87,20 @@ export function mountIslands(
     if (enhancer === undefined) continue // no enhancer for this id → leave it as inert SSR markup
     const props = readProps(el)
     const strategyAttr = el.dataset.strategy
-    const strategy: IslandStrategy =
-      strategyAttr === "idle" || strategyAttr === "visible" ? strategyAttr : "load"
+    const strategy: IslandStrategy | undefined =
+      strategyAttr === "idle" || strategyAttr === "visible" || strategyAttr === "load"
+        ? strategyAttr
+        : strategyAttr === "media" &&
+            el.dataset.media !== undefined &&
+            el.dataset.media.length > 0 &&
+            el.dataset.media.length <= MAX_MEDIA_QUERY_LENGTH
+          ? { media: el.dataset.media }
+          : strategyAttr === undefined
+            ? "load"
+            : undefined
+    // Invalid media markers remain inert rather than silently becoming eager. Their SSR content stays
+    // usable, and untrusted HTML cannot turn an oversized query into an unexpected trigger.
+    if (strategy === undefined) continue
     const run = (): void => {
       try {
         const cleanup = enhancer(el, props)
@@ -107,7 +110,7 @@ export function mountIslands(
         console.error(`[nifra/islands] enhancer "${id}" failed:`, err)
       }
     }
-    disposers.push(whenStrategy(el, strategy, run))
+    disposers.push(scheduleTrigger(strategy, run, { target: el }))
   }
   return () => {
     for (const dispose of disposers) {
@@ -119,3 +122,66 @@ export function mountIslands(
     }
   }
 }
+
+/** Unsubscribe one bus handler; calling twice is a no-op. Also returned so an enhancer can hand it
+ * straight back as its `IslandCleanup`. */
+export type IslandBusUnsubscribe = () => void
+
+/**
+ * A typed publish/subscribe channel for coordinating islands that must talk to each other without a
+ * shared reactive store - a cart badge reacting to an "add to cart" island, a filter island driving
+ * a results island. Create ONE bus in your mount entry and close over it in each enhancer; there is
+ * no implicit global, so concurrent renders and tests never cross-talk.
+ *
+ *   type Events = { "cart:add": { sku: string }; "cart:count": number }
+ *   const bus = createIslandBus<Events>()
+ *   mountIslands({
+ *     addBtn: defineIsland((el) => {
+ *       const onClick = () => bus.emit("cart:add", { sku: el.dataset.sku! })
+ *       el.addEventListener("click", onClick)
+ *       return () => el.removeEventListener("click", onClick)
+ *     }),
+ *     badge: defineIsland((el) => bus.on("cart:count", (n) => { el.textContent = String(n) })),
+ *   })
+ *
+ * `on` returns its own unsubscribe, so an enhancer whose only job is to listen can `return bus.on(...)`
+ * directly as its cleanup. A handler that throws is isolated - it never blocks the other subscribers
+ * or the `emit` caller. Synchronous, in-memory, no DOM dependency (safe to construct under SSR); it
+ * carries no history, so a subscriber only sees events emitted after it subscribed.
+ */
+export function createIslandBus<
+  Events extends Record<string, unknown> = Record<string, unknown>,
+>(): {
+  emit<K extends keyof Events>(type: K, detail: Events[K]): void
+  on<K extends keyof Events>(type: K, handler: (detail: Events[K]) => void): IslandBusUnsubscribe
+} {
+  const channels = new Map<keyof Events, Set<(detail: never) => void>>()
+  return {
+    emit(type, detail) {
+      const handlers = channels.get(type)
+      if (handlers === undefined) return
+      // Snapshot so a handler that (un)subscribes mid-dispatch cannot corrupt this iteration.
+      for (const handler of [...handlers]) {
+        try {
+          ;(handler as (d: Events[typeof type]) => void)(detail)
+        } catch (err) {
+          console.error(`[nifra/islands] bus handler for "${String(type)}" failed:`, err)
+        }
+      }
+    },
+    on(type, handler) {
+      let handlers = channels.get(type)
+      if (handlers === undefined) {
+        handlers = new Set()
+        channels.set(type, handlers)
+      }
+      handlers.add(handler as (detail: never) => void)
+      return () => {
+        const set = channels.get(type)
+        if (set === undefined) return
+        set.delete(handler as (detail: never) => void)
+        if (set.size === 0) channels.delete(type)
+      }
+    },
+  }
+}

package/src/manifest.ts

@@ -5,6 +5,7 @@
  * portable (no fs, no DOM) and fully unit-testable. Edge deploys pre-build the manifest.
  */
 import type { StandardSchemaV1 } from "@nifrajs/core/server"
+import type { BoundaryDescriptor, BoundaryRegistration } from "./boundary.ts"
 
 /** Context passed to a route `loader`. The `api` + `env` are injected by `createWebApp` and typed
  * per-route via `@nifrajs/client`'s `LoaderArgs<Api, Env>` (here they are opaque to the agnostic core). */
@@ -30,11 +31,51 @@ export type Loader = (ctx: LoaderContext) => unknown | Promise<unknown>
 
 /**
  * A route's optional mutation, run on POST. Shares the loader context (params/request/api);
- * read the form/JSON body off `request`. Returns either a `Response` (e.g. a redirect -
- * passed straight through) or data, surfaced to the page component as `actionData`.
+ * read the form/JSON body off `request`. Returns either a control-flow value (a `redirect()`, a
+ * `status(...)` render, or a hand-rolled `Response` - all passed straight through) or data,
+ * surfaced to the page component as `actionData`.
  */
 export type Action = (ctx: LoaderContext) => unknown | Promise<unknown>
 
+/** The body a client action may prepare for the server action. The server must validate it again. */
+export type ClientRequestBody = NonNullable<RequestInit["body"]>
+
+/** Safe, client-visible context for a client loader. It intentionally exposes no Request or headers. */
+export interface ClientLoaderArgs {
+  readonly url: string
+  readonly params: Readonly<Record<string, string>>
+  readonly signal: AbortSignal
+  /** Lazily obtains the server loader result; repeated calls share one per-navigation request. */
+  readonly serverLoader: () => Promise<unknown>
+}
+
+/** A client-only post-hydration data loader. Its return value replaces the route's rendered data. */
+export type ClientLoader = (args: ClientLoaderArgs) => unknown | Promise<unknown>
+
+/** Safe, client-visible context for a client action. No secrets or raw request headers cross this seam. */
+export interface ClientActionArgs extends ClientLoaderArgs {
+  readonly body: ClientRequestBody
+}
+
+/** Client action preparation. `body` is sent as untrusted input; `optimisticData` is never sent. */
+export interface ClientActionResult {
+  readonly body?: ClientRequestBody
+  readonly optimisticData?: unknown
+}
+
+/** A client-only action wrapper; it never replaces the server action. */
+export type ClientAction = (
+  args: ClientActionArgs,
+) => ClientActionResult | void | Promise<ClientActionResult | void>
+
+/** Client hooks populated by the generated route entry after a route chunk loads. */
+export interface ClientRouteHooks {
+  readonly clientLoader?: ClientLoader
+  readonly clientAction?: ClientAction
+  /** Neutral boundary descriptors needed for soft-navigation interception; no server loader crosses. */
+  readonly boundaries?: readonly BoundaryDescriptor[]
+}
+
 /**
  * One `<link>` tag's attributes for a route/layout's `meta.link`. The common HTML `<link>` attributes
  * are spelled out and **optional** so a typed partial like `{ rel, href, hreflang }` is assignable -
@@ -191,6 +232,12 @@ export interface RouteModule {
   readonly default: unknown
   readonly loader?: Loader
   readonly action?: Action
+  /** Optional client-only loader. It runs after hydration and on client navigations. */
+  readonly clientLoader?: ClientLoader
+  /** Optional client-only submit wrapper. The server action remains mandatory for mutations. */
+  readonly clientAction?: ClientAction
+  /** Named async boundaries owned by this route. The adapter renders their neutral state seam. */
+  readonly boundaries?: readonly BoundaryRegistration[]
   /** A Standard Schema validating this route's URL search params. When present, `ctx.search` is parsed +
    * validated against it (failing closed to the schema's defaults on invalid input); type it into the
    * loader with `LoaderArgs<Api, Env, typeof searchSchema>`. */
@@ -249,7 +296,7 @@ export interface RouteModule {
  * overrides an inner layout, which overrides an outer one). See `mergeHeads` in `@nifrajs/web`. */
 export interface LayoutEntry {
   readonly file: string
-  readonly load: () => Promise<{ default: unknown; meta?: MetaInput }>
+  readonly load: () => Promise<RouteModule>
 }
 
 /** One matched route: pattern, nested layout ids (outermost → innermost), source file, loader. */

package/src/module-graph.ts

@@ -44,6 +44,11 @@ export interface ClientModuleGraph {
   readonly chunks: Readonly<Record<string, GraphChunk>>
 }
 
+/** Module ids are graph identifiers, not filesystem paths exposed to an OS API. Bun uses `\\` on
+ * Windows, while Rollup and the guards use `/` for suffix matching and stable diagnostics. Normalize at
+ * each adapter boundary so every consumer sees one graph shape. */
+const normalizeModuleId = (id: string): string => id.replaceAll("\\", "/")
+
 /** The slice of Bun's metafile this seam consumes. Not yet in `@types/bun`; shape per the docs. */
 export interface BunMetafileLike {
   readonly inputs?: Readonly<
@@ -66,14 +71,23 @@ export interface BunMetafileLike {
  */
 export function fromBunMetafile(meta: BunMetafileLike | undefined): ClientModuleGraph {
   const modules: Record<string, GraphModule> = {}
-  for (const [id, input] of Object.entries(meta?.inputs ?? {})) {
-    modules[id] = { imports: input.imports ?? [] }
+  for (const [rawId, input] of Object.entries(meta?.inputs ?? {})) {
+    const id = normalizeModuleId(rawId)
+    modules[id] = {
+      imports: (input.imports ?? []).map((im) => ({
+        ...(im.path === undefined ? {} : { path: normalizeModuleId(im.path) }),
+        ...(im.original === undefined ? {} : { original: im.original }),
+      })),
+    }
   }
   const chunks: Record<string, GraphChunk> = {}
-  for (const [path, output] of Object.entries(meta?.outputs ?? {})) {
+  for (const [rawPath, output] of Object.entries(meta?.outputs ?? {})) {
+    const path = normalizeModuleId(rawPath)
     chunks[path] = {
-      ...(output.entryPoint !== undefined ? { entryPoint: output.entryPoint } : {}),
-      modules: Object.keys(output.inputs ?? {}),
+      ...(output.entryPoint !== undefined
+        ? { entryPoint: normalizeModuleId(output.entryPoint) }
+        : {}),
+      modules: Object.keys(output.inputs ?? {}).map(normalizeModuleId),
     }
   }
   return { modules, chunks }
@@ -117,11 +131,11 @@ export function fromRollupBundle(
     // Assets (CSS, copied files) have no module graph; `type` is absent only on hand-built test inputs,
     // which are always chunks, so treat "not explicitly an asset" as a chunk.
     if (output.type === "asset") continue
-    const moduleIds = output.moduleIds ?? []
+    const moduleIds = (output.moduleIds ?? []).map(normalizeModuleId)
     // Start from the real modules; `node:` builtins get appended below.
     const chunkModules: string[] = [...moduleIds]
     for (const id of moduleIds) {
-      const imports = importsOf(id).map((path) => ({ path }))
+      const imports = importsOf(id).map((path) => ({ path: normalizeModuleId(path) }))
       if (modules[id] === undefined) modules[id] = { imports }
       // The guards locate a leak by finding the builtin IN a chunk's module list - Bun BUNDLES the `node:`
       // polyfill, so the builtin appears there as an input. Rollup EXTERNALIZES `node:`, so it never lands
@@ -135,10 +149,10 @@ export function fromRollupBundle(
         if (modules[im.path] === undefined) modules[im.path] = { imports: [] }
       }
     }
-    chunks[fileName] = {
+    chunks[normalizeModuleId(fileName)] = {
       // `facadeModuleId` is null for a shared/common chunk (no single entry) - omit it then, matching
       // how a non-entry Bun output omits `entryPoint`, so the guards' entry set stays the real entries.
-      ...(output.facadeModuleId ? { entryPoint: output.facadeModuleId } : {}),
+      ...(output.facadeModuleId ? { entryPoint: normalizeModuleId(output.facadeModuleId) } : {}),
       modules: chunkModules,
     }
   }

package/src/nano.ts

@@ -0,0 +1,246 @@
+/**
+ * `@nifrajs/web/nano` - the smallest state layer that still lets an island drive a keyed list.
+ *
+ * The islands lane (`@nifrajs/web/islands`) is imperative and correct-by-construction, but it has no
+ * state primitive: every DOM update is hand-written, and a list means rebuilding the whole container.
+ * nano adds a small, closed set of primitives and stops:
+ *
+ *   - `signal(v)`  - a current-value cell you read with `.get()` and write with `.set()`.
+ *   - `computed(fn, [deps])` - a derived cell. Its dependencies are DECLARED, never auto-tracked.
+ *   - `resource(fetcher, [deps])` - an async cell with an explicit pending/error/ready value. This is
+ *     nano's answer to "suspense": no thrown promise, no magic boundary, just a value you can bind.
+ *   - `bind` / `bindList` / `bindResource` - explicit, one-directional DOM bindings that each return
+ *     their teardown.
+ *
+ * The design rule is the whole point: every reactive edge is a call you can see - a `bind(...)` or a
+ * `computed(fn, [deps])`. There is no re-render scope, no VDOM, no template compiler, and no effect
+ * that silently subscribes to whatever it happened to read. That is what removes the three failure
+ * modes an AI (or a human) hits in a framework - stale closures, wrong effect deps, hydration
+ * mismatch - and, just as importantly, it is what makes every remaining mistake STATICALLY
+ * detectable: a missing dep is `[deps]` that doesn't list a signal the body reads; a leak is a `bind`
+ * whose cleanup isn't returned. A framework's reactivity can't be linted like that; nano's can.
+ *
+ * Where nano stops: no client router and no nested/composable view state (a component tree that mounts
+ * and unmounts its own children). When an app needs those, it has outgrown a vanilla page - reach for
+ * a framework adapter (`@nifrajs/web-preact`), not more nano.
+ *
+ * Browser code: it touches the DOM and is meant to run in an island enhancer, never under SSR.
+ */
+
+/** A value you can read now and be told about later. Both `signal` and `computed` are `Readable`, so
+ * `bind`/`bindList` accept either. */
+export interface Readable<T> {
+  get(): T
+  subscribe(listener: (value: T) => void): () => void
+}
+
+/** A writable cell. `set` notifies subscribers only when the value actually changes (`Object.is`), so
+ * a redundant write costs nothing. */
+export interface Signal<T> extends Readable<T> {
+  set(value: T): void
+}
+
+/** Notify a snapshot of the current listeners, so a listener that (un)subscribes mid-dispatch does not
+ * corrupt the walk. A throwing listener is isolated - it never blocks the others. */
+function notify<T>(listeners: Set<(value: T) => void>, value: T): void {
+  for (const listener of [...listeners]) {
+    try {
+      listener(value)
+    } catch (error) {
+      console.error("[nifra/nano] a subscriber threw:", error)
+    }
+  }
+}
+
+/** A current-value cell. `signal(0)` -> `.get()` reads, `.set(1)` writes and notifies. */
+export function signal<T>(initial: T): Signal<T> {
+  let value = initial
+  const listeners = new Set<(value: T) => void>()
+  return {
+    get: () => value,
+    set(next: T) {
+      if (Object.is(next, value)) return
+      value = next
+      notify(listeners, value)
+    },
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+  }
+}
+
+/**
+ * A derived cell. `computed(() => a.get() + b.get(), [a, b])` recomputes whenever a declared
+ * dependency changes and notifies its own subscribers when the derived value changes.
+ *
+ * The `deps` array is mandatory and explicit ON PURPOSE - it is the contract a linter checks against
+ * the signals the body reads (`NF-C023`). Auto-tracking would remove the array but reintroduce the
+ * exact "why didn't this update" bug that makes framework reactivity hard to get right.
+ */
+export function computed<T>(compute: () => T, deps: readonly Readable<unknown>[]): Readable<T> {
+  let value = compute()
+  const listeners = new Set<(value: T) => void>()
+  const recompute = (): void => {
+    const next = compute()
+    if (Object.is(next, value)) return
+    value = next
+    notify(listeners, value)
+  }
+  // A computed with a live subscriber must itself be subscribed to its deps; to keep the prototype
+  // simple it subscribes eagerly for its whole life (fine for the island-scoped, few-signal case).
+  for (const dep of deps) dep.subscribe(recompute)
+  return {
+    get: () => value,
+    subscribe(listener) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+  }
+}
+
+/** The three states of an async cell. A discriminated union on `status` so a consumer must handle
+ * every branch - there is no "value that might secretly be loading", the failure mode of ad-hoc
+ * `isLoading` booleans. `value`/`error` are narrowed by `status`. */
+export type ResourceState<T> =
+  | { readonly status: "pending"; readonly value: undefined; readonly error: undefined }
+  | { readonly status: "ready"; readonly value: T; readonly error: undefined }
+  | { readonly status: "error"; readonly value: undefined; readonly error: unknown }
+
+/** An async cell: a `Readable` of `ResourceState<T>` plus `refetch()`. This is nano's answer to
+ * "suspense" - an explicit pending/error/ready value, never a thrown promise or a magic boundary. */
+export interface Resource<T> extends Readable<ResourceState<T>> {
+  refetch(): void
+}
+
+/**
+ * An async derived cell. `resource(fetcher, [deps])` runs `fetcher` immediately and again whenever a
+ * declared dependency changes, exposing the result as an explicit `{ status, value, error }`.
+ *
+ * Two footguns are handled here so they cannot be got wrong by hand:
+ *   - Races: each run holds a generation; a stale run's resolution is dropped, and its `AbortSignal` is
+ *     aborted, so an earlier-started-later-finishing fetch never overwrites a newer one.
+ *   - Deps: like `computed`, dependencies are DECLARED (`NF-C023` checks the fetcher's `.get()` reads
+ *     against the array). A `resource` that reads a signal its deps omit won't refetch when it changes.
+ */
+export function resource<T>(
+  fetcher: (signal: AbortSignal) => Promise<T>,
+  deps: readonly Readable<unknown>[] = [],
+): Resource<T> {
+  const state = signal<ResourceState<T>>({ status: "pending", value: undefined, error: undefined })
+  let generation = 0
+  let controller: AbortController | undefined
+  const run = (): void => {
+    const mine = ++generation
+    controller?.abort()
+    controller = new AbortController()
+    const active = controller
+    state.set({ status: "pending", value: undefined, error: undefined })
+    fetcher(active.signal).then(
+      (value) => {
+        if (mine === generation) state.set({ status: "ready", value, error: undefined })
+      },
+      (error) => {
+        // A stale run (superseded) or one we aborted must not surface as an error state.
+        if (mine === generation && !active.signal.aborted)
+          state.set({ status: "error", value: undefined, error })
+      },
+    )
+  }
+  for (const dep of deps) dep.subscribe(run)
+  run()
+  return {
+    get: () => state.get(),
+    subscribe: (listener) => state.subscribe(listener),
+    refetch: run,
+  }
+}
+
+/**
+ * Bind one element to a source: `apply(el, value)` runs once immediately and again on every change.
+ * Returns the unsubscribe - hand it back as the island's cleanup (or collect several).
+ *
+ *   bind(count, remaining, (el, n) => { el.textContent = String(n) })
+ */
+export function bind<T>(
+  el: HTMLElement,
+  source: Readable<T>,
+  apply: (el: HTMLElement, value: T) => void,
+): () => void {
+  apply(el, source.get())
+  return source.subscribe((value) => apply(el, value))
+}
+
+/** How a `bindList` turns items into keyed DOM. `key` MUST be stable and unique per item (never the
+ * array index) - it is what lets add/remove/reorder touch only the changed rows. */
+export interface BindListOptions<T> {
+  key(item: T): string | number
+  create(item: T): HTMLElement
+  update?(el: HTMLElement, item: T): void
+}
+
+/**
+ * Bind a list signal to a container with keyed reconciliation: new items are `create`d, surviving
+ * items are `update`d in place (keeping focus, scroll, and selection), removed items are detached,
+ * and the children are ordered to match the array. Returns the unsubscribe.
+ *
+ * This is the one imperative task too error-prone to hand-write each time - it is why nano exists on
+ * top of islands rather than leaving you to rebuild the container on every change.
+ */
+export function bindList<T>(
+  source: Readable<readonly T[]>,
+  container: HTMLElement,
+  options: BindListOptions<T>,
+): () => void {
+  let nodes = new Map<string | number, HTMLElement>()
+  const render = (items: readonly T[]): void => {
+    const next = new Map<string | number, HTMLElement>()
+    for (const item of items) {
+      const key = options.key(item)
+      const el = nodes.get(key) ?? options.create(item)
+      options.update?.(el, item)
+      next.set(key, el)
+    }
+    for (const [key, el] of nodes) if (!next.has(key)) el.remove()
+    // Append in item order; appending an already-attached node MOVES it, so the final order matches.
+    for (const item of items) container.appendChild(next.get(options.key(item)) as HTMLElement)
+    nodes = next
+  }
+  render(source.get())
+  return source.subscribe(render)
+}
+
+/** How a `bindResource` maps each async state to the DOM. `ready` is required (there is always a
+ * success shape to render); `pending`/`error` are optional. Every branch is explicit - no hidden
+ * "still loading" state can slip through as a rendered `undefined`. */
+export interface BindResourceHandlers<T> {
+  ready(el: HTMLElement, value: T): void
+  pending?(el: HTMLElement): void
+  error?(el: HTMLElement, error: unknown): void
+}
+
+/**
+ * Bind an element to a `resource`, dispatching on `status`. Like `bind`, it applies immediately and
+ * on every change and returns the unsubscribe - collect it (a discarded disposer is `NF-C021`).
+ *
+ *   bindResource(el, user, {
+ *     pending: (n) => { n.textContent = "Loading…" },
+ *     ready: (n, u) => { n.textContent = u.name },
+ *     error: (n) => { n.textContent = "Failed to load" },
+ *   })
+ */
+export function bindResource<T>(
+  el: HTMLElement,
+  source: Readable<ResourceState<T>>,
+  handlers: BindResourceHandlers<T>,
+): () => void {
+  return bind(el, source, (node, state) => {
+    if (state.status === "pending") handlers.pending?.(node)
+    else if (state.status === "error") handlers.error?.(node, state.error)
+    else handlers.ready(node, state.value)
+  })
+}

package/src/plugins/css-modules.ts

@@ -20,7 +20,7 @@
  * Not handled: the bare `:global`/`:local` *switch* form and `composes:` - out of scope by design.
  */
 import type { BunPlugin } from "bun"
-import { createStylesheetEmitter, hash8, reproduciblePath } from "./kit.ts"
+import { createStylesheetEmitter, hash8, normalizeFilePath, reproduciblePath } from "./kit.ts"
 
 const STYLE_NS = "nifra-css-module"
 
@@ -425,7 +425,7 @@ export function cssModulesBunPlugin(generate: "dom" | "ssr"): BunPlugin {
     setup(build) {
       const stylesheet = createStylesheetEmitter(build, STYLE_NS)
       build.onLoad({ filter: /\.module\.css(\?|$)/ }, async (args) => {
-        const path = args.path.split("?")[0] ?? args.path
+        const path = normalizeFilePath(args.path)
         const source = await Bun.file(path).text()
         // Hash scoped names off the cwd-relative path so they're reproducible across machines/CI.
         const { exports, css } = transformCssModule(source, reproduciblePath(path))