@nifrajs/web-react 4.0.2 → 5.1.0

package/src/auth.ts

@@ -18,6 +18,7 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
 } from "react"
 
@@ -55,7 +56,18 @@ export function AuthSessionProvider(props: AuthSessionProviderProps): ReactNode
   const [seed, setSeed] = useState(props.initialSession)
   const [status, setStatus] = useState<AuthStatus>(seededStatus(props.initialSession))
   const [session, setSession] = useState<Session | null>(props.initialSession ?? null)
+  // A read applies only while it holds the latest generation; a newer read, a sign-out, a new client
+  // or seed, and unmount each take one. The record is never replaced, so a sign-out that settles
+  // after a client or seed change still clears the session the server ended.
+  const reads = useRef({ generation: 0, signingOut: 0, live: true, client })
+  if (reads.current.client !== client) {
+    // A new client keeps what is shown (a parent may build one per render); only answers to the
+    // previous client's reads are dropped.
+    reads.current.client = client
+    reads.current.generation++
+  }
   if (seed !== props.initialSession) {
+    reads.current.generation++
     // A render-phase update: React re-runs this component before any child sees the old session.
     setSeed(props.initialSession)
     setStatus(seededStatus(props.initialSession))
@@ -63,40 +75,35 @@ export function AuthSessionProvider(props: AuthSessionProviderProps): ReactNode
   }
   const refresh = useMemo(() => {
     return async (): Promise<void> => {
+      const state = reads.current
+      // A read made while signing out could answer with the session being ended.
+      if (state.signingOut > 0 || state.client !== client) return
+      const generation = ++state.generation
       try {
         const next = await client.getSession()
+        if (!state.live || state.generation !== generation) return
         setSession(next)
         setStatus(next === null ? "unauthenticated" : "authenticated")
       } catch {
         // A failed session read must fail closed as anonymous; leaving "loading" can strand the
         // subtree in an auth-pending state and make protected UI appear available by omission.
+        if (!state.live || state.generation !== generation) return
         setSession(null)
         setStatus("unauthenticated")
       }
     }
   }, [client])
   useEffect(() => {
-    let live = true
+    const state = reads.current
+    state.live = true
     if (props.initialSession === undefined) {
-      void client.getSession().then(
-        (next) => {
-          if (!live) return
-          setSession(next)
-          setStatus(next === null ? "unauthenticated" : "authenticated")
-        },
-        () => {
-          // Treat an unavailable session endpoint as anonymous rather than keeping auth state
-          // pending indefinitely or exposing stale authenticated UI.
-          if (!live) return
-          setSession(null)
-          setStatus("unauthenticated")
-        },
-      )
+      void refresh()
     }
     return () => {
-      live = false
+      state.live = false
+      state.generation++
     }
-  }, [client, props.initialSession])
+  }, [refresh, props.initialSession])
   const value = useMemo<AuthSession>(
     () => ({
       status,
@@ -104,7 +111,16 @@ export function AuthSessionProvider(props: AuthSessionProviderProps): ReactNode
       refresh,
       signIn: (providerId, options) => client.signIn(providerId, options),
       signOut: async (options) => {
-        await client.signOut(options)
+        const state = reads.current
+        state.signingOut++
+        state.generation++
+        try {
+          await client.signOut(options)
+        } finally {
+          state.signingOut--
+          state.generation++
+        }
+        if (!state.live) return
         // The server ended the session: the subtree must not go on showing it, whether a redirect is
         // pending or `redirect: false` keeps the page.
         setSession(null)

package/src/island.ts

@@ -30,7 +30,10 @@ export function Island({ id, props, strategy = "load", children }: IslandProps):
     "nifra-island",
     {
       "data-id": id,
-      "data-strategy": strategy,
+      // The runtime reads a media strategy as two attributes; React drops an object-valued one.
+      ...(typeof strategy === "string"
+        ? { "data-strategy": strategy }
+        : { "data-strategy": "media", "data-media": strategy.media }),
       // Omit `data-props` entirely when there are no props (keeps markup minimal + parse a no-op).
       ...(props === undefined ? {} : { "data-props": JSON.stringify(props) }),
     },

package/src/react-dom-server.ts

@@ -124,7 +124,7 @@ export function assertSingleReactCore(
     rendererReact = realpath(resolve("react", dirnamePortable(reactDomServerPath)))
     // The `react` the app's route components import - the core they call hooks on.
     componentsReact = realpath(resolve("react", appRoot()))
-    // @nifra-gate-reviewed: not a security gate. If either `react` cannot be resolved we cannot prove
+    // nifra-expect NF-S001: not a security gate. If either `react` cannot be resolved we cannot prove
     // a duplicate exists, so we skip the assertion rather than block a valid render.
   } catch {
     return

package/src/route-props.ts

@@ -17,6 +17,7 @@ export function routeProps(
   const rawSearch = q === -1 ? "" : state.path.slice(q)
   return {
     data: state.data,
+    ...(state.serverComponents === undefined ? {} : { serverComponents: state.serverComponents }),
     // Each layout's own loader data. Without it a layout renders `data: null` on the client while the
     // server rendered it with its data - a hydration mismatch on the first paint.
     ...(state.layoutData !== undefined ? { layoutData: state.layoutData } : {}),

package/src/server-components/client.ts

@@ -0,0 +1,176 @@
+import type {
+  ComponentClientAdapter,
+  ComponentClientRoot,
+  ComponentRecord,
+  CurrentComponent,
+} from "@nifrajs/web/server-components/client"
+import { bytesStream, decodeComponentBytes } from "@nifrajs/web/server-components/stream"
+import { createFromReadableStream } from "@vitejs/plugin-rsc/browser"
+import { createElement, type ReactNode, useLayoutEffect, useSyncExternalStore } from "react"
+import { flushSync } from "react-dom"
+import { createRoot, hydrateRoot } from "react-dom/client"
+
+// Flight's framework-facing lazy ABI is pinned with React/Flight in the compatibility gate.
+async function prepareTree(
+  value: unknown,
+  current: CurrentComponent,
+  seen = new Set<object>(),
+  depth = 0,
+): Promise<void> {
+  if (!current()) throw new Error("component_cancelled")
+  if (depth > 64 || seen.size > 16384) throw new Error("component_limit")
+  if (typeof value !== "object" || value === null || seen.has(value)) return
+  seen.add(value)
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Only this adapter produces its prepared tree and native root; component records and public props are validated before native preparation.
+  const node = value as Record<string, unknown>
+  if (node.$$typeof === Symbol.for("react.lazy")) {
+    const init = node._init
+    if (typeof init !== "function") throw new Error("component_protocol")
+    while (true) {
+      try {
+        await prepareTree(init(node._payload), current, seen, depth + 1)
+        break
+      } catch (pending) {
+        if (
+          typeof pending !== "object" ||
+          pending === null ||
+          !("then" in pending) ||
+          typeof pending.then !== "function"
+        )
+          throw pending
+        await pending
+        if (!current()) throw new Error("component_cancelled")
+      }
+    }
+  } else if ("then" in node && typeof node.then === "function") {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Only this adapter produces its prepared tree and native root; component records and public props are validated before native preparation.
+    await prepareTree(await (value as Promise<unknown>), current, seen, depth + 1)
+  } else if (Array.isArray(value)) {
+    await Promise.all(value.map((child) => prepareTree(child, current, seen, depth + 1)))
+  } else if (node.$$typeof === Symbol.for("react.transitional.element")) {
+    await prepareTree(node.type, current, seen, depth + 1)
+    await prepareTree(node.props, current, seen, depth + 1)
+  } else {
+    await Promise.all(
+      Object.values(node).map((child) => prepareTree(child, current, seen, depth + 1)),
+    )
+  }
+}
+
+class FlightRoot implements ComponentClientRoot {
+  readonly #host: Element
+  readonly #root: ReturnType<typeof createRoot>
+  readonly #listeners = new Set<() => void>()
+  #snapshot: ReactNode
+  #current: CurrentComponent
+  #committed: ReactNode = null
+  #disposed = false
+  #ready: () => void
+  readonly ready: Promise<void>
+  constructor(
+    host: Element,
+    tree: ReactNode,
+    record: ComponentRecord,
+    current: CurrentComponent,
+    fresh = false,
+  ) {
+    this.#host = host
+    this.#snapshot = tree
+    this.#current = current
+    let ready!: () => void
+    this.ready = new Promise<void>((resolve) => {
+      ready = resolve
+    })
+    this.#ready = ready
+    const store = this
+    function CurrentTree() {
+      const value = useSyncExternalStore(
+        (listener) => {
+          store.#listeners.add(listener)
+          return () => store.#listeners.delete(listener)
+        },
+        () => store.#snapshot,
+        () => tree,
+      )
+      const display = store.#current() ? value : store.#committed
+      useLayoutEffect(() => {
+        store.#committed = display
+        store.#ready()
+      })
+      return display
+    }
+    const options = {
+      identifierPrefix: `${record.instance}-`,
+      onRecoverableError() {
+        if (current()) throw new Error("component_failed")
+      },
+      onUncaughtError() {
+        store.#ready()
+        store.dispose()
+        throw new Error("component_failed")
+      },
+    }
+    if (fresh) {
+      this.#root = createRoot(host, options)
+      this.#root.render(createElement(CurrentTree))
+    } else this.#root = hydrateRoot(host, createElement(CurrentTree), options)
+  }
+  publish(tree: ReactNode, current: CurrentComponent): void {
+    if (this.#disposed || !current()) return
+    flushSync(() => {
+      if (!current()) return
+      this.#current = current
+      this.#snapshot = tree
+      for (const listener of this.#listeners) listener()
+    })
+  }
+  update(): never {
+    throw new Error("component_contract")
+  }
+  dispose(): void {
+    if (this.#disposed) return
+    this.#disposed = true
+    this.#root.unmount()
+    this.#listeners.clear()
+    this.#host.replaceChildren()
+    this.#ready()
+  }
+}
+export function reactComponentClient(): ComponentClientAdapter {
+  return {
+    name: "react",
+    async prepare(record, current) {
+      if (
+        typeof record.payload !== "object" ||
+        record.payload === null ||
+        Array.isArray(record.payload) ||
+        !Object.hasOwn(record.payload, "flight")
+      )
+        throw new Error("component_protocol")
+      const tree = await createFromReadableStream<ReactNode>(
+        // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Only this adapter produces its prepared tree and native root; component records and public props are validated before native preparation.
+        bytesStream(decodeComponentBytes((record.payload as Record<string, unknown>).flight)),
+      )
+      await prepareTree(tree, current)
+      if (!current()) throw new Error("component_cancelled")
+      return tree
+    },
+    async hydrate(host, record, tree, current) {
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Only this adapter produces its prepared tree and native root; component records and public props are validated before native preparation.
+      const root = new FlightRoot(host, tree as ReactNode, record, current)
+      await root.ready
+      return root
+    },
+    async create(host, record, tree, current) {
+      if (!current()) throw new Error("component_cancelled")
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Only this adapter produces its prepared tree and native root; component records and public props are validated before native preparation.
+      const root = new FlightRoot(host, tree as ReactNode, record, current, true)
+      await root.ready
+      return root
+    },
+    update(root, _record, tree, current) {
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Only this adapter produces its prepared tree and native root; component records and public props are validated before native preparation.
+      ;(root as FlightRoot).publish(tree as ReactNode, current)
+    },
+  }
+}

package/src/server-components/flight.ts

@@ -0,0 +1,87 @@
+import { readComponentBytes } from "@nifrajs/web/server-components/stream"
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder("utf-8", { fatal: true })
+function publicModel(value: unknown, depth = 0): unknown {
+  if (depth > 128) throw new Error("component_limit")
+  if (typeof value === "string" && value.startsWith("$F")) throw new Error("component_contract")
+  if (Array.isArray(value))
+    return (
+      value[0] === "$"
+        ? [...value.slice(0, 4), null, null, value[6] === 1 || value[6] === 2 ? value[6] : 0]
+        : value
+    ).map((item) => publicModel(item, depth + 1))
+  if (typeof value === "object" && value !== null)
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, publicModel(item, depth + 1)]),
+    )
+  return value
+}
+
+/** React 19.2.8 Flight framing: remove development owners/stacks/console records before transport. */
+export function publicFlight(bytes: Uint8Array): Uint8Array {
+  const rows: Uint8Array[] = []
+  let offset = 0
+  while (offset < bytes.length) {
+    const start = offset
+    while (offset < bytes.length && bytes[offset] !== 58) offset++
+    const id = decoder.decode(bytes.subarray(start, offset))
+    if (!/^[0-9a-f]*$/.test(id) || offset === bytes.length) throw new Error("component_protocol")
+    offset++
+    if (bytes[offset] === 84) {
+      const lengthStart = ++offset
+      while (offset < bytes.length && bytes[offset] !== 44) offset++
+      const encodedLength = decoder.decode(bytes.subarray(lengthStart, offset))
+      if (!/^[0-9a-f]+$/.test(encodedLength)) throw new Error("component_protocol")
+      const length = parseInt(encodedLength, 16)
+      offset++
+      if (offset + length > bytes.length) throw new Error("component_protocol")
+      offset += length
+      rows.push(bytes.slice(start, offset))
+      continue
+    }
+    const end = bytes.indexOf(10, offset)
+    if (end === -1) throw new Error("component_protocol")
+    const row = decoder.decode(bytes.subarray(offset, end))
+    offset = end + 1
+    if (/^[DNW]/.test(row)) continue
+    if (row.startsWith("E")) {
+      rows.push(
+        encoder.encode(
+          id +
+            ':E{"digest":"component_failed","message":"component_failed","name":"Error","stack":[],"env":"Server","owner":null}\n',
+        ),
+      )
+      continue
+    }
+    if (/^[[{"0-9tnf-]/.test(row)) {
+      let model: unknown
+      try {
+        model = JSON.parse(row)
+      } catch {
+        throw new Error("component_protocol")
+      }
+      rows.push(encoder.encode(`${id}:${JSON.stringify(publicModel(model))}\n`))
+    } else rows.push(bytes.slice(start, offset))
+  }
+  const size = rows.reduce((size, row) => size + row.length, 0)
+  const output = new Uint8Array(size)
+  let at = 0
+  for (const row of rows) {
+    output.set(row, at)
+    at += row.length
+  }
+  return output
+}
+export async function publicFlightStream(
+  stream: ReadableStream<Uint8Array>,
+  signal: AbortSignal,
+): Promise<ReadableStream<Uint8Array>> {
+  const bytes = publicFlight(await readComponentBytes(stream, signal))
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes)
+      controller.close()
+    },
+  })
+}

package/src/server-components/guard.ts

@@ -0,0 +1,199 @@
+import type { StandardSchemaV1 } from "@nifrajs/core/schema"
+import { guardComponentProps } from "@nifrajs/web/server-components/props"
+import {
+  type ComponentType,
+  cloneElement,
+  createElement,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+} from "react"
+
+interface ClientContract {
+  readonly reference: ComponentType<Record<string, unknown>>
+  readonly schema: StandardSchemaV1
+  readonly slots: readonly string[]
+}
+const contracts = new WeakMap<object, ClientContract>()
+const wrappers = new WeakMap<object, ClientContract>()
+const encoder = new TextEncoder()
+
+function failure(): Error {
+  const error = new Error("component_failed")
+  error.stack = ""
+  return error
+}
+
+function slot(value: unknown, depth = 0): ReactNode {
+  if (depth > 16) throw failure()
+  if (
+    value === undefined ||
+    value === null ||
+    typeof value === "boolean" ||
+    typeof value === "string" ||
+    (typeof value === "number" && Number.isFinite(value)) ||
+    isValidElement(value)
+  )
+    return value
+  if (Array.isArray(value) && value.length <= 128)
+    return value.map((item: unknown) => slot(item, depth + 1))
+  throw failure()
+}
+
+function publicProps(contract: ClientContract, raw: unknown): Promise<Record<string, unknown>> {
+  return (async () => {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw failure()
+    const dto: Record<string, unknown> = Object.create(null)
+    const slots: Record<string, ReactNode> = Object.create(null)
+    for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(raw))) {
+      if (!Object.hasOwn(descriptor, "value")) throw failure()
+      if (contract.slots.includes(name)) slots[name] = slot(descriptor.value)
+      else if (name !== "children" && name !== "ref" && name !== "key") dto[name] = descriptor.value
+    }
+    const projected = await guardComponentProps(contract.schema, dto)
+    if (typeof projected !== "object" || projected === null || Array.isArray(projected))
+      throw failure()
+    return { ...projected, ...slots }
+  })().catch(() => {
+    throw failure()
+  })
+}
+
+/** Called by generated facades. The actual native reference stays private to this module. */
+export function guardedClientReference(
+  reference: unknown,
+  schema: StandardSchemaV1,
+  slots: readonly string[] = [],
+): ComponentType<Record<string, unknown>> {
+  const Facade = (): never => {
+    throw failure()
+  }
+  contracts.set(Facade, {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+    reference: reference as ComponentType<Record<string, unknown>>,
+    schema,
+    slots,
+  })
+  return Facade
+}
+
+export function guardedClientElement(
+  type: unknown,
+  raw: unknown,
+  key?: unknown,
+): ReactNode | undefined {
+  if ((typeof type !== "object" && typeof type !== "function") || type === null) return undefined
+  const contract = contracts.get(type)
+  if (contract === undefined) return undefined
+  if (
+    key !== undefined &&
+    key !== null &&
+    !(
+      (typeof key === "string" && encoder.encode(key).length <= 128) ||
+      (typeof key === "number" && Number.isSafeInteger(key))
+    )
+  )
+    throw failure()
+  const props = publicProps(contract, raw ?? {})
+  const publicKey = typeof key === "string" || typeof key === "number" ? key : null
+  // Only a promise of projected props reaches React's element/debug metadata. Raw props stay in the guard closure.
+  const Guarded = async ({
+    value,
+  }: {
+    value: Promise<Record<string, unknown>>
+  }): Promise<ReactNode> =>
+    createElement(contract.reference, {
+      ...(await value),
+      key: publicKey,
+    })
+  wrappers.set(Guarded, contract)
+  return createElement(Guarded, {
+    value: props,
+    key: publicKey,
+  })
+}
+
+export function guardedCreateElement(
+  type: unknown,
+  props?: unknown,
+  ...children: ReactNode[]
+): ReactNode {
+  const raw =
+    children.length === 0
+      ? props
+      : {
+          // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+          ...(props as Record<string, unknown> | undefined),
+          children: children.length === 1 ? children[0] : children,
+        }
+  const key =
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+    typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>).key : undefined
+  const guarded = guardedClientElement(type, raw, key)
+  if (guarded !== undefined) return guarded
+  return createElement(
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+    type as ComponentType,
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+    props as Record<string, unknown> | null | undefined,
+    ...children,
+  )
+}
+
+export function guardedCloneElement(
+  element: ReactElement,
+  props?: unknown,
+  ...children: ReactNode[]
+): ReactNode {
+  const contract =
+    (typeof element.type === "object" || typeof element.type === "function") &&
+    element.type !== null
+      ? (wrappers.get(element.type) ?? contracts.get(element.type))
+      : undefined
+  if (contract === undefined)
+    return cloneElement(
+      element,
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+      props === null ? undefined : (props as Record<string, unknown> | undefined),
+      ...children,
+    )
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+  const previous = element.props as Record<string, unknown>
+  const value = Object.hasOwn(previous, "value")
+    ? // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+      (previous.value as Promise<Record<string, unknown>>)
+    : publicProps(contract, previous)
+  const raw = props ?? {}
+  if (
+    typeof raw !== "object" ||
+    raw === null ||
+    Array.isArray(raw) ||
+    Object.values(Object.getOwnPropertyDescriptors(raw)).some(
+      (descriptor) => !Object.hasOwn(descriptor, "value"),
+    )
+  )
+    throw failure()
+  const next = value.then((projected) =>
+    publicProps(contract, { ...projected, ...raw, ...(children.length === 0 ? {} : { children }) }),
+  )
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+  const rawKey = (raw as Record<string, unknown>).key ?? element.key
+  if (
+    rawKey !== null &&
+    !(
+      (typeof rawKey === "string" && encoder.encode(rawKey).length <= 128) ||
+      (typeof rawKey === "number" && Number.isSafeInteger(rawKey))
+    )
+  )
+    throw failure()
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+  const key = rawKey as string | number | null
+  const Guarded = async ({
+    value,
+  }: {
+    value: Promise<Record<string, unknown>>
+  }): Promise<ReactNode> => createElement(contract.reference, { ...(await value), key })
+  wrappers.set(Guarded, contract)
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Registered native references and projected props retain the pinned React ABI; key and prop vocabulary are checked before serialization.
+  return createElement(Guarded, { value: next, key: key as string | number | null })
+}

package/src/server-components/jsx-dev-runtime.ts

@@ -0,0 +1,27 @@
+import { Fragment, jsxDEV as nativeJsxDEV } from "react/jsx-dev-runtime"
+import { guardedClientElement } from "./guard.ts"
+
+export { Fragment }
+
+export function jsxDEV(
+  type: unknown,
+  props: unknown,
+  key: unknown,
+  isStaticChildren: boolean,
+  source?: { fileName: string; lineNumber: number; columnNumber: number },
+  self?: unknown,
+): unknown {
+  return (
+    guardedClientElement(type, props, key) ??
+    nativeJsxDEV(
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The guard handles registered client references; other elements use the unchanged native React development JSX ABI.
+      type as Parameters<typeof nativeJsxDEV>[0],
+      props,
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The guard handles registered client references; other elements use the unchanged native React development JSX ABI.
+      key as string | undefined,
+      isStaticChildren,
+      source,
+      self,
+    )
+  )
+}

package/src/server-components/jsx-runtime.ts

@@ -0,0 +1,19 @@
+import { Fragment, jsx as nativeJsx, jsxs as nativeJsxs } from "react/jsx-runtime"
+import { guardedClientElement } from "./guard.ts"
+
+export { Fragment }
+
+export function jsx(type: unknown, props: unknown, key?: unknown): unknown {
+  return (
+    guardedClientElement(type, props, key) ??
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The guard handles registered client references; other elements use the unchanged native React JSX ABI.
+    nativeJsx(type as Parameters<typeof nativeJsx>[0], props, key as string | undefined)
+  )
+}
+export function jsxs(type: unknown, props: unknown, key?: unknown): unknown {
+  return (
+    guardedClientElement(type, props, key) ??
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The guard handles registered client references; other elements use the unchanged native React JSX ABI.
+    nativeJsxs(type as Parameters<typeof nativeJsxs>[0], props, key as string | undefined)
+  )
+}

package/src/server-components/nested.props.ts

@@ -0,0 +1,2 @@
+import { t } from "@nifrajs/schema"
+export const NestedServerComponent = t.object({ instance: t.string(), html: t.string() })

package/src/server-components/nested.ts

@@ -0,0 +1,18 @@
+"use client"
+import { createElement, useRef } from "react"
+
+/** The outer Flight root preserves this host; the controller owns the complete nested range. */
+export function NestedServerComponent({
+  instance,
+  html,
+}: {
+  readonly instance: string
+  readonly html: string
+}) {
+  const initial = useRef({ __html: html })
+  return createElement("nifra-component", {
+    "data-nifra-component": instance,
+    // biome-ignore lint/security/noDangerouslySetInnerHtml: Parent rendering provides the verified server-owned nested range.
+    dangerouslySetInnerHTML: initial.current,
+  })
+}