@nifrajs/web 2.13.0 → 3.1.0

package/src/internal/query-runtime.ts

@@ -0,0 +1,31 @@
+import type { QueryClient, QueryState } from "../query.ts"
+import { createQueryClient } from "../query.ts"
+
+/** Stable idle state shared by every framework query binding. */
+export const IDLE_QUERY_STATE: QueryState<never> = Object.freeze({
+  status: "pending",
+  data: undefined,
+  error: undefined,
+  isFetching: false,
+  updatedAt: Number.NEGATIVE_INFINITY,
+})
+
+let singleton: QueryClient | undefined
+
+/** Return the client-side query singleton, or undefined during SSR. */
+export function getQueryClientSingleton(): QueryClient | undefined {
+  // `typeof globalThis.window`, not `"window" in globalThis`: an SSR shim that assigns
+  // `globalThis.window = undefined` still satisfies the `in` check (the key exists), which would
+  // build a process-global cache on the server and leak state across requests. A real DOM window is
+  // a defined object; a shimmed-undefined one reads as `"undefined"` here and stays server-side.
+  if (typeof (globalThis as { window?: unknown }).window === "undefined") return undefined
+  if (singleton === undefined) singleton = createQueryClient({ now: () => Date.now() })
+  return singleton
+}
+
+/** Create the refetch fallback used when a binding has no client-side query cache. */
+export function createNoClientRefetch<T>(tag: string, operation: string): () => Promise<T> {
+  return async () => {
+    throw new Error(`${tag} ${operation} called with no query client (server?)`)
+  }
+}

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,8 +34,6 @@ 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 => {}
-
 /** Parse an island's inline `data-props` JSON; malformed/absent → `undefined` (never throws). */
 function readProps(el: HTMLElement): unknown {
   const raw = el.dataset.props
@@ -42,40 +45,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 +65,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 +88,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) {

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/render-seam.ts

@@ -6,6 +6,8 @@
  * without importing the document renderer through the root module. The singleton is stored on
  * globalThis because the Bun and Vite dev pipelines can evaluate two copies in one process.
  */
+
+import type { BoundaryStates } from "./boundary.ts"
 import type { Submission } from "./router.ts"
 
 /** The data handed to a route component. */
@@ -26,6 +28,8 @@ export interface RenderProps {
   readonly path?: string
   /** The route's typed, validated search params. */
   readonly search?: Record<string, unknown>
+  /** Neutral named-boundary states; adapters choose how each boundary's `render` UI is mounted. */
+  readonly boundaries?: BoundaryStates
 }
 
 /**
@@ -72,5 +76,7 @@ export const ROUTE_GLOBAL = "__NIFRA_ROUTE__"
 /** Global the server serializes an action's data return into (absent on GETs); the client reads it
  * so hydration after a native form POST matches the server-rendered markup. */
 export const ACTION_GLOBAL = "__NIFRA_ACTION__"
+/** Dynamic-boundary states for hydration; absent when a route declares no boundaries. */
+export const BOUNDARY_GLOBAL = "__NIFRA_BOUNDARIES__"
 /** Marker attribute used to find a non-default hydration container. */
 export const ROOT_ATTRIBUTE = "data-nifra-root"