@nifrajs/web-solid 5.5.0 → 5.6.0

package/src/index.ts

@@ -4,14 +4,15 @@
  * hydration lives in `@nifrajs/web-solid/client` (Solid's browser build), and the Solid Babel
  * Bun-plugin in `@nifrajs/web-solid/plugin`.
  */
-import type { RenderAdapter } from "@nifrajs/web"
-import { sharedConfig } from "solid-js"
+import type { RenderAdapter, RenderProps, RenderStreamOptions, RouterState } from "@nifrajs/web"
+import { type JSX, sharedConfig } from "solid-js"
 import {
   generateHydrationScript,
   renderToStream as solidRenderToStream,
   renderToString as solidRenderToString,
 } from "solid-js/web"
 import { compose } from "./compose.ts"
+import { documentTree, KeepAliveView } from "./keep-alive-view.ts"
 
 const HYDRATION_HEAD = generateHydrationScript()
 
@@ -52,6 +53,27 @@ function redactingErrors<T>(app: () => T): () => T {
   }
 }
 
+const noRef = (): undefined => undefined
+
+/** The chain as the browser's keep-alive view renders it, in an app with a `keepAlive` route. */
+function documentView(chain: readonly unknown[], props: RenderProps, slots: readonly number[]) {
+  const state: RouterState = { routeId: "", params: {}, path: "", data: props.data, pending: false }
+  const tree = documentTree(chain, state, slots)
+  return (): JSX.Element =>
+    KeepAliveView({
+      tree: () => tree,
+      shown: props,
+      mount: { propsOf: () => props, chainOf: () => chain, entry: noRef, page: noRef },
+    })
+}
+
+const appOf = (chain: readonly unknown[], props: RenderProps, options?: RenderStreamOptions) =>
+  redactingErrors(
+    options?.slots === undefined
+      ? compose(chain, props)
+      : documentView(chain, props, options.slots),
+  )
+
 /** The Solid server render adapter - pass to @nifrajs/web's `renderPage`. */
 export const solidAdapter: RenderAdapter = {
   // Synchronous one-pass render for non-deferred pages (renderPage's buffered fast path). Solid's
@@ -60,11 +82,33 @@ export const solidAdapter: RenderAdapter = {
   // streaming machinery - the heaviest of the five renderers on Bun. A page that defer()s/Suspends
   // takes `renderToStream` below (progressive resolution needs it).
   renderToString(chain, props, options) {
-    const app = redactingErrors(compose(chain, props))
+    const app = appOf(chain, props, options)
     return options?.nonce === undefined
       ? solidRenderToString(app)
       : solidRenderToString(app, { nonce: options.nonce })
   },
+  // A partially prerendered hole's HTML: its own root under `renderId`, so its hydration keys and
+  // `createUniqueId`s never collide with the page's, and its JSX runs inside the render that keys it.
+  // Without a prefix (a fallback, never hydrated) it carries no hydration keys at all.
+  renderFragment(ui, options) {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a hole's render returns Solid output; the seam erases it to unknown.
+    const view = () => ui() as JSX.Element
+    // `renderToString` leaves its context in Solid's shared config; a page mid-render keeps its own.
+    const page = sharedConfig.context
+    try {
+      return options.idPrefix === undefined
+        ? solidRenderToString(() => {
+            // On the root context, so nodes resolved after `view` returns are unkeyed too.
+            if (sharedConfig.context !== undefined)
+              Reflect.set(sharedConfig.context, "noHydrate", true)
+            return view()
+          })
+        : solidRenderToString(view, { renderId: options.idPrefix })
+    } finally {
+      // Unset included: `context` is an optional property.
+      Reflect.set(sharedConfig, "context", page)
+    }
+  },
   renderToStream(chain, props, options) {
     // Solid's `renderToStream` streams `Uint8Array` chunks into a Web `WritableStream` via
     // `pipeTo` (fire-and-forget - returns void); pipe into a TransformStream and hand back the
@@ -72,7 +116,7 @@ export const solidAdapter: RenderAdapter = {
     // <head>) seeds client hydration. A render failure errors `ts.readable`, which `renderPage`
     // surfaces on the response body. The nonce reaches the resource and boundary scripts Solid streams.
     const ts = new TransformStream<Uint8Array, Uint8Array>()
-    const app = redactingErrors(compose(chain, props))
+    const app = appOf(chain, props, options)
     const stream =
       options?.nonce === undefined
         ? solidRenderToStream(app)

package/src/keep-alive-view.ts

@@ -0,0 +1,202 @@
+/**
+ * The view of an app with a `keepAlive` route: the page on screen and every kept page as a tree of
+ * slots (`slotTree` from `@nifrajs/web/keep-alive`), grouped by the layouts they share. The server
+ * renders it with the one page a document shows and the browser hydrates it, so both sides create the
+ * same components in the same order and Solid's hydration keys line up.
+ *
+ * A slot is keyed by its node's key, not the node object: a node is replaced whenever its state or its
+ * visibility changes, and keying on it would remount the page. A slot reads its node through a memo,
+ * so a hidden page, whose node the tree keeps, updates nothing while it is hidden.
+ */
+import type { RenderProps, RouterState } from "@nifrajs/web"
+import type { SlotNode } from "@nifrajs/web/keep-alive"
+import {
+  type Accessor,
+  type Component,
+  createComponent,
+  createComputed,
+  createMemo,
+  For,
+  type JSX,
+  on,
+  untrack,
+} from "solid-js"
+import { Dynamic } from "solid-js/web"
+import { PageContext, type PageSlot } from "./page-visibility.ts"
+import { RenderPropsContext, SearchContext } from "./router.ts"
+
+/** What the view renders with: one per mount, on the server or in the browser. */
+export interface KeepAliveViewMount {
+  /** The props of a state, as getters over it. */
+  readonly propsOf: (state: Accessor<RouterState>) => RenderProps
+  readonly chainOf: (state: RouterState) => readonly unknown[]
+  readonly entry: (key: string) => ((element: Element) => void) | undefined
+  readonly page: (key: string) => ((element: Element) => void) | undefined
+}
+
+export interface KeepAliveViewProps {
+  readonly tree: Accessor<readonly SlotNode[]>
+  /** The props of the state on screen, which the layouts every page shares render with. */
+  readonly shown: RenderProps
+  readonly mount: KeepAliveViewMount
+}
+
+type LayoutProps = {
+  readonly data: unknown
+  readonly boundaries?: RenderProps["boundaries"] | undefined
+  readonly children?: JSX.Element
+}
+
+const EMPTY_SEARCH: Readonly<Record<string, unknown>> = Object.freeze({})
+
+// The providers `compose` puts around a chain, for one slot's props.
+const withRouteContext = (props: RenderProps, children: () => JSX.Element): JSX.Element =>
+  createComponent(SearchContext.Provider, {
+    value: () => props.search ?? EMPTY_SEARCH,
+    get children() {
+      return createComponent(RenderPropsContext.Provider, {
+        value: props,
+        get children() {
+          return children()
+        },
+      })
+    },
+  })
+
+// The page's own chain from `depth` on: an `_error` boundary, then the page.
+const pageChain = (chain: readonly unknown[], depth: number, props: RenderProps): JSX.Element => {
+  if (depth >= chain.length - 1)
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a chain holds the route's modules' default exports, its last entry the page component
+    return createComponent(chain[chain.length - 1] as Component<RenderProps>, props)
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: an entry between the layouts and the page is the `_error` boundary component
+  return createComponent(chain[depth] as Component<LayoutProps>, {
+    get data() {
+      return props.layoutData?.[depth] ?? null
+    },
+    get boundaries() {
+      return props.boundaries
+    },
+    get children() {
+      return pageChain(chain, depth + 1, props)
+    },
+  })
+}
+
+const sameKeys = (a: readonly string[], b: readonly string[]): boolean =>
+  a.length === b.length && a.every((key, i) => key === b[i])
+
+function Level(props: {
+  readonly nodes: Accessor<readonly SlotNode[]>
+  readonly mount: KeepAliveViewMount
+}): JSX.Element {
+  const keys = createMemo(() => props.nodes().map((node) => node.key), [], { equals: sameKeys })
+  return createComponent(For, {
+    get each() {
+      return keys()
+    },
+    children: (key: string) =>
+      createComponent(Slot, { key, nodes: props.nodes, mount: props.mount }),
+  })
+}
+
+function Slot(props: {
+  readonly key: string
+  readonly nodes: Accessor<readonly SlotNode[]>
+  readonly mount: KeepAliveViewMount
+}): JSX.Element {
+  const { key, mount } = props
+  const find = (): SlotNode | undefined => props.nodes().find((node) => node.key === key)
+  const first = untrack(find)
+  if (first === undefined) throw new Error(`[nifra/web-solid] no slot node "${key}"`)
+  // The last node with this key stays while the slot is being removed with it.
+  const node = createMemo((last: SlotNode) => find() ?? last, first)
+  const state = createMemo(() => node().state)
+  const hidden = createMemo(() => node().hidden)
+  const slotProps = mount.propsOf(state)
+  // A key keeps its depth, its wrappers and its chain: a page's key is one instance of one route, a
+  // layout's key the layout every page under it shares.
+  const { depth } = first
+  const chain = mount.chainOf(first.state)
+  const content = (): JSX.Element =>
+    first.children === undefined
+      ? pageChain(chain, depth, slotProps)
+      : // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a chain entry above the page is a layout module's default export, a layout component
+        createComponent(chain[depth] as Component<LayoutProps>, {
+          get data() {
+            return slotProps.layoutData?.[depth] ?? null
+          },
+          get boundaries() {
+            return slotProps.boundaries
+          },
+          get children() {
+            return createComponent(Level, { nodes: () => node().children ?? [], mount })
+          },
+        })
+  if (!first.wrapped) return content()
+
+  const slot: PageSlot = { hidden, hide: new Set(), show: new Set() }
+  // A computation, not an effect: it runs as the tree changes, before the mount parks the page.
+  createComputed(
+    on(hidden, (now, before) => {
+      if (before === undefined || now === before) return
+      for (const callback of [...(now ? slot.hide : slot.show)]) callback()
+    }),
+  )
+  return createComponent(Dynamic, {
+    component: "slot",
+    "data-nifra-entry": "",
+    ref: mount.entry(key),
+    get children() {
+      return createComponent(Dynamic, {
+        component: "slot",
+        "data-nifra-page": "",
+        ref: mount.page(key),
+        get children() {
+          return createComponent(PageContext.Provider, {
+            value: slot,
+            get children() {
+              return withRouteContext(slotProps, content)
+            },
+          })
+        },
+      })
+    },
+  })
+}
+
+/** The keep-alive view. */
+export function KeepAliveView(props: KeepAliveViewProps): JSX.Element {
+  return withRouteContext(props.shown, () =>
+    createComponent(Level, { nodes: props.tree, mount: props.mount }),
+  )
+}
+
+/**
+ * The tree of a server render: the chain as one path of slot nodes, the entries at `slots` inside
+ * the slot wrappers, which is what the browser's first render builds from the same state.
+ */
+export function documentTree(
+  chain: readonly unknown[],
+  state: RouterState,
+  slots: readonly number[],
+): readonly SlotNode[] {
+  const page = chain.length - 1
+  let node: SlotNode = {
+    key: "\0page",
+    depth: page,
+    state,
+    hidden: false,
+    wrapped: slots.includes(page),
+  }
+  for (let depth = page - 1; depth >= 0; depth--) {
+    node = {
+      key: `\0layout${depth}`,
+      depth,
+      state,
+      hidden: false,
+      wrapped: slots.includes(depth),
+      children: [node],
+    }
+  }
+  return [node]
+}

package/src/keep-alive.ts

@@ -0,0 +1,76 @@
+/**
+ * @nifrajs/web-solid/keep-alive - the client mount of an app with a `keepAlive` route, which the
+ * generated client entry imports in place of `@nifrajs/web-solid/client` (whose exports it carries).
+ *
+ * One root renders the page on screen and every page the router keeps (`KeepAliveView`), grouped by
+ * the layouts they share; the DOM half takes a hidden page out of the document. A hidden page keeps
+ * running: `onPageHide`, `onPageShow` and `usePageVisibility` (from `@nifrajs/web-solid/router`) let
+ * it pause. Unlike the plain mount, a route change does not remount the root: Solid updates the tree
+ * in place, synchronously, so the DOM half runs right after each publish.
+ */
+import type { MountRouterOptions, RouterState } from "@nifrajs/web"
+import {
+  createSlotParking,
+  type KeepAliveRouter,
+  type KeepAliveTable,
+  type SlotNode,
+  slotTree,
+} from "@nifrajs/web/keep-alive"
+import { createMemo, createSignal } from "solid-js"
+import { hydrate as solidHydrate } from "solid-js/web"
+import { setMountedRouter } from "./fetcher.ts"
+import { KeepAliveView, type KeepAliveViewMount } from "./keep-alive-view.ts"
+import { routeProps } from "./route-props.ts"
+
+export * from "./client.ts"
+export { onPageHide, onPageShow, usePageVisibility } from "./page-visibility.ts"
+
+/** `mountRouter`'s options in a keep-alive app: the generated entry adds where the wrappers go. */
+export interface KeepAliveMountOptions extends MountRouterOptions {
+  readonly router: KeepAliveRouter
+  readonly keepAlive: KeepAliveTable
+}
+
+/**
+ * Hydrate the keep-alive view. Its first render matches the server's (the same view, with the slot
+ * wrappers the server rendered), so hydration claims the document as it is.
+ */
+export function mountRouter(options: KeepAliveMountOptions): void {
+  const { router, routes, searchSchemas, container, keepAlive: table } = options
+  const matchChains = options.matchChains ?? {}
+  setMountedRouter(router)
+  const parking = createSlotParking()
+  let committed: readonly SlotNode[] | undefined
+  router.beforePublish((next) => parking.before(slotTree(next, matchChains, table, committed)))
+
+  let current: readonly SlotNode[] = []
+  let publish: ((state: RouterState) => void) | undefined
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the generated entry passes the element the server rendered the app into
+  solidHydrate(() => {
+    const [state, setState] = createSignal(router.snapshot())
+    publish = (next) => setState(() => next)
+    const tree = createMemo(() => {
+      current = slotTree(state(), matchChains, table, current)
+      return current
+    })
+    const mount: KeepAliveViewMount = {
+      propsOf: (of) => routeProps(of, searchSchemas, matchChains, (read) => createMemo(read)),
+      chainOf: (of) => routes[of.routeId] ?? [],
+      entry: parking.entry,
+      page: parking.page,
+    }
+    return KeepAliveView({ tree, shown: mount.propsOf(state), mount })
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the generated entry passes the element the server rendered the app into
+  }, container as Element)
+  // Solid has updated the document by the time a publish returns: park what it hid, restore what it
+  // showed again.
+  const after = (): void => {
+    committed = current
+    parking.after(current)
+  }
+  after()
+  router.subscribe(() => {
+    publish?.(router.snapshot())
+    after()
+  })
+}

package/src/mdx.ts

@@ -9,7 +9,7 @@
 import { transformAsync } from "@babel/core"
 // @ts-expect-error - no type declarations published
 import presetTypeScript from "@babel/preset-typescript"
-import { normalizeFilePath, rewriteSsrImports } from "@nifrajs/web/plugins/kit"
+import { normalizeFilePath, requirePeer, rewriteSsrImports } from "@nifrajs/web/plugins/kit"
 // @ts-expect-error - no type declarations published
 import presetSolid from "babel-preset-solid"
 import type { BunPlugin } from "bun"
@@ -27,14 +27,10 @@ export function solidMdxBunPlugin(generate: "dom" | "ssr"): BunPlugin {
   return {
     name: `nifra-solid-mdx-${generate}`,
     async setup(build) {
-      let compile: MdxCompiler["compile"]
-      try {
-        compile = ((await import(MDX_MODULE)) as MdxCompiler).compile
-      } catch {
-        throw new Error(
-          "@nifrajs/web-solid/mdx: compiling `.mdx` needs the `@mdx-js/mdx` package - install it (`bun add @mdx-js/mdx`).",
-        )
-      }
+      const { compile } = await requirePeer<MdxCompiler>(MDX_MODULE, {
+        feature: "Solid MDX support",
+        install: "bun add @mdx-js/mdx",
+      })
       build.onLoad({ filter: /\.mdx(\?|$)/ }, async (args) => {
         const path = normalizeFilePath(args.path)
         // 1. MDX → JSX, with intrinsics provided by the Solid runtime (rendered via `<Dynamic>`).

package/src/page-visibility.ts

@@ -0,0 +1,53 @@
+/**
+ * Whether a page is on screen, for a `keepAlive` page that stays mounted while it is hidden. Pages read
+ * it through `@nifrajs/web-solid/router`; the keep-alive view provides it per kept slot.
+ */
+import { type Accessor, type Context, createContext, onCleanup, useContext } from "solid-js"
+
+/** What one kept slot provides: whether it is hidden, and the callbacks it runs as that changes. */
+export interface PageSlot {
+  readonly hidden: Accessor<boolean>
+  readonly hide: Set<() => void>
+  readonly show: Set<() => void>
+}
+
+// A `globalThis` singleton for the same reason as the router's contexts (see router.ts).
+const PAGE_CONTEXT_SLOT = Symbol.for("nifra.web-solid.page-context")
+// biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: only this module writes the registry key, and it writes a page context
+const pageContextSlot = globalThis as { [PAGE_CONTEXT_SLOT]?: Context<PageSlot | undefined> }
+export const PageContext = pageContextSlot[PAGE_CONTEXT_SLOT] ?? createContext<PageSlot>()
+pageContextSlot[PAGE_CONTEXT_SLOT] = PageContext
+
+const ALWAYS: Accessor<boolean> = () => true
+
+/**
+ * Whether the page this component renders in is on screen, as an accessor: `false` while it is kept
+ * hidden behind another page, where it keeps running. Always `true` on the server and on a page that
+ * does not keep alive.
+ */
+export function usePageVisibility(): Accessor<boolean> {
+  const slot = useContext(PageContext)
+  return slot === undefined ? ALWAYS : () => !slot.hidden()
+}
+
+const onVisibility = (kind: "hide" | "show", callback: () => void): void => {
+  const slot = useContext(PageContext)
+  if (slot === undefined) return
+  slot[kind].add(callback)
+  onCleanup(() => slot[kind].delete(callback))
+}
+
+/**
+ * Run `callback` each time the `keepAlive` page this component renders in is hidden behind another
+ * page, before it leaves the document. The page keeps running while it is hidden: pause its timers,
+ * sockets and media here. Call it while the component sets up; it is removed with the component. A
+ * no-op outside a kept page.
+ */
+export function onPageHide(callback: () => void): void {
+  onVisibility("hide", callback)
+}
+
+/** Run `callback` each time the `keepAlive` page this component renders in is shown again. */
+export function onPageShow(callback: () => void): void {
+  onVisibility("show", callback)
+}

package/src/ppr-client.ts

@@ -0,0 +1,77 @@
+import { type HoleRoot, holeHost } from "@nifrajs/web/internal/hole-runtime"
+import {
+  createComponent,
+  createEffect,
+  type JSX,
+  on,
+  onCleanup,
+  onMount,
+  sharedConfig,
+} from "solid-js"
+import { createStore, reconcile } from "solid-js/store"
+import { Dynamic, hydrate } from "solid-js/web"
+
+const isObject = (value: unknown): value is object => typeof value === "object" && value !== null
+
+/**
+ * A hole's host in the browser: once mounted, the PPR runtime's fill goes in, an interactive hole
+ * hydrates that server HTML as its own root from the frame's props, and each refill `fill` brings is
+ * applied in place. Object props reach the root as a store, so a refill updates it and keeps its
+ * state; any other value makes the root again.
+ */
+export function clientHost<Data>(
+  name: string,
+  render: (data: Data) => JSX.Element,
+  interactive: boolean,
+  attributes: Readonly<Record<string, string>>,
+  fill: () => unknown,
+): JSX.Element {
+  let host: HTMLElement | undefined
+  const element = createComponent(Dynamic, {
+    component: "div",
+    ref: (el: HTMLElement) => {
+      host = el
+    },
+    ...attributes,
+  })
+  onMount(() => {
+    const target = host
+    if (target === undefined) return
+    const root = (into: Element, data: unknown): HoleRoot => {
+      const [props, setProps] = createStore({ value: data })
+      let dispose: (() => void) | undefined
+      let left = false
+      const start = (): void => {
+        if (left) return
+        dispose = hydrate(
+          // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the server framed these props from this hole's own loader, through its output guard.
+          () => render(props.value as Data),
+          into,
+          { renderId: `nifra-${name}-` },
+        )
+      }
+      // Solid keeps one hydration context: a fill met while the page hydrates waits for it to end.
+      if (sharedConfig.context) queueMicrotask(start)
+      else start()
+      return {
+        update: (next) => {
+          if (!isObject(next) || !isObject(props.value)) return false
+          setProps("value", reconcile(next))
+          return true
+        },
+        dispose: () => {
+          left = true
+          dispose?.()
+        },
+      }
+    }
+    const driven = holeHost(name, target, interactive ? root : undefined)
+    createEffect(
+      on(fill, (next) => {
+        if (next !== undefined) driven.refill(next)
+      }),
+    )
+    onCleanup(() => driven.dispose())
+  })
+  return element
+}

package/src/ppr.ts

@@ -0,0 +1,86 @@
+import { initialHtml } from "@nifrajs/web/internal/hole-runtime"
+import { createComponent, createMemo, type JSX, untrack } from "solid-js"
+import { Dynamic, isServer } from "solid-js/web"
+import { Await } from "./await.ts"
+import { clientHost } from "./ppr-client.ts"
+
+/**
+ * The fields of a route's boundary declaration a hole renders from. `fallback` is a function: JSX
+ * evaluated at import is one DOM node, so every place that shows it would take it from the last.
+ */
+export interface HoleDefinition<Data> {
+  readonly name: string
+  readonly render: (data: Data) => JSX.Element
+  readonly fallback?: () => JSX.Element
+  readonly interactive?: boolean
+}
+
+/** The slice of a boundary state a hole reads: `ppr` marks a hole the shared shell left open, and
+ * `fill` that host's refill when the page reloads. */
+interface HoleState {
+  readonly status: "unresolved" | "pending" | "ready" | "error"
+  readonly data?: unknown
+  readonly ppr?: true
+  readonly fill?: unknown
+}
+
+export interface HoleProps<Data> {
+  readonly of: HoleDefinition<Data>
+  readonly state: HoleState | undefined
+  /** Shown when the hole's loader failed. Default: nothing. */
+  readonly error?: JSX.Element
+}
+
+/** An open hole's host: claimed by its hydration key like any element, never given children in the
+ * browser. On the server it holds a blocking render's HTML. */
+function openHost<Data>(hole: HoleDefinition<Data>, fill: () => unknown): JSX.Element {
+  const attributes = { "data-nifra-hole": hole.name, "aria-busy": "true" }
+  if (isServer) {
+    const initial = initialHtml(fill())
+    return createComponent(Dynamic, {
+      component: "div",
+      ...attributes,
+      ...(initial === "" ? {} : { innerHTML: initial }),
+    })
+  }
+  return clientHost(hole.name, hole.render, hole.interactive === true, attributes, fill)
+}
+
+/**
+ * Experimental: one `dynamic` or `shared` boundary of a partially prerendered page.
+ *
+ * In a shared shell the hole is an empty host Solid never fills: the PPR runtime puts the server's
+ * HTML into it, and an interactive hole then hydrates as its own root from the frame's props. When the
+ * page reloads, after an action or a live change, the same host takes the new fill in place: an
+ * interactive root gets the new props through its store and keeps its state. After a client
+ * navigation the hole renders like any streamed boundary.
+ */
+export function Hole<Data>(props: HoleProps<Data>): JSX.Element {
+  const open = createMemo(() => props.state?.ppr === true)
+  const fill = createMemo(() => (open() ? props.state?.fill : undefined))
+  const view = createMemo(() => {
+    // Only `open` is read for a host, so a refill keeps it.
+    if (open()) return untrack(() => openHost(props.of, fill))
+    const hole = props.of
+    const state = props.state
+    if (state === undefined) return untrack(() => hole.fallback?.())
+    if (state.status === "error") return props.error
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a ready state carries this boundary's loader output, through its output guard.
+    if (state.status === "ready") return untrack(() => hole.render(state.data as Data))
+    // A streamed hole's data is its deferred loader output, whatever status the payload names.
+    if (state.data === undefined) return untrack(() => hole.fallback?.())
+    return untrack(() =>
+      createComponent(Await<Data>, {
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a pending streamed state carries this boundary's deferred loader output.
+        resolve: state.data as Data,
+        get fallback() {
+          return hole.fallback?.()
+        },
+        errorFallback: () => props.error,
+        children: hole.render,
+      }),
+    )
+  })
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion lint/plugin/noChainedTypeAssertions: Solid inserts an accessor reactively, as its own Show returns one; its JSX.Element type leaves functions out.
+  return view as unknown as JSX.Element
+}

package/src/query.ts

@@ -1,8 +1,10 @@
-import type { QueryClient, QueryState } from "@nifrajs/web"
+import type { QueryClient, QueryOptions, QueryState } from "@nifrajs/web"
 import {
   createNoClientRefetch,
+  fetchOnMount,
   getQueryClientSingleton,
   IDLE_QUERY_STATE,
+  noop,
 } from "@nifrajs/web/internal/query-runtime"
 /**
  * `@nifrajs/web-solid/query` - Solid bindings for the keyed query-cache. `createQuery(key, fn)` bridges a
@@ -18,7 +20,7 @@ import { type Accessor, createSignal, onCleanup, onMount } from "solid-js"
 
 /** Access the query client to imperatively `invalidateQueries(keyOrPrefix)` (e.g. after a mutation). */
 export function useQueryClient(): Pick<QueryClient, "invalidateQueries"> {
-  return getQueryClientSingleton() ?? { invalidateQueries: () => {} }
+  return getQueryClientSingleton() ?? { invalidateQueries: noop }
 }
 
 /** A query's reactive state accessor plus `refetch`. */
@@ -32,18 +34,21 @@ export interface CreateQueryResult<T> {
 /**
  * Bind the keyed query for `key`, fetched via `fn`. Returns a reactive `state()` accessor + `refetch`.
  * Concurrent `createQuery`s with the same key share one cache entry + one in-flight fetch (dedup).
- * Fetches on mount; SSR-idle. Call inside a component (owns the subscription).
+ * Fetches on mount; SSR-idle. Call inside a component (owns the subscription). `options.live` names
+ * the live keys that refetch it.
  */
-export function createQuery<T>(key: unknown, fn: () => Promise<T>): CreateQueryResult<T> {
-  const handle = getQueryClientSingleton()?.query<T>(key, fn)
+export function createQuery<T>(
+  key: unknown,
+  fn: () => Promise<T>,
+  options?: QueryOptions,
+): CreateQueryResult<T> {
+  const handle = getQueryClientSingleton()?.query<T>(key, fn, options)
   const [state, setState] = createSignal<QueryState<T>>(
     handle ? handle.snapshot() : IDLE_QUERY_STATE,
   )
   if (handle !== undefined) {
     onCleanup(handle.subscribe(() => setState(() => handle.snapshot())))
-    onMount(() => {
-      handle.fetch().catch(() => {})
-    })
+    onMount(fetchOnMount(handle))
     return { state, refetch: handle.refetch }
   }
   return {