@nifrajs/web-react 4.0.2 → 5.0.0

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,
+  })
+}

package/src/server-components/outlet.ts

@@ -0,0 +1,109 @@
+import {
+  type ComponentClientAdapter,
+  ComponentController,
+  type ServerComponent as ComponentHandle,
+  type ComponentKey,
+  type ComponentState,
+  resolveComponentRecord,
+} from "@nifrajs/web/server-components/client"
+import { createElement, useLayoutEffect, useRef } from "react"
+
+declare const __NIFRA_COMPONENT_BROWSER__: boolean
+function lazyClient(): ComponentClientAdapter {
+  let pending: Promise<ComponentClientAdapter> | undefined
+  const client = () => {
+    if (typeof __NIFRA_COMPONENT_BROWSER__ === "boolean" && !__NIFRA_COMPONENT_BROWSER__)
+      throw new Error("component_contract")
+    pending ??= import("./client.ts").then((module) => module.reactComponentClient())
+    return pending
+  }
+  return {
+    name: "react",
+    prepare: async (...args) => (await client()).prepare(...args),
+    hydrate: async (...args) => (await client()).hydrate(...args),
+    create: async (...args) => {
+      const create = (await client()).create
+      if (create === undefined) throw new Error("component_contract")
+      return create(...args)
+    },
+    update: async (...args) => (await client()).update(...args),
+  }
+}
+export interface ServerComponentProps<Input, Props, View> {
+  readonly state: ComponentState
+  readonly component: ComponentHandle<Input, Props, View>
+  readonly instanceKey: ComponentKey
+  readonly input: NoInfer<Input>
+  readonly parent?: string
+  readonly controller?: ComponentController | undefined
+  readonly clientAdapter?: ComponentClientAdapter
+  readonly onError?: (code: string) => void
+}
+export function ServerComponent<Input, Props, View>(
+  props: ServerComponentProps<Input, Props, View>,
+) {
+  const record = resolveComponentRecord(
+    props.state,
+    props.component,
+    props.instanceKey,
+    props.input,
+    props.parent ?? null,
+  )
+  return createElement(ComponentRange, {
+    key: record.instance,
+    state: props.state,
+    record,
+    controller: props.controller,
+    clientAdapter: props.clientAdapter,
+    onError: props.onError,
+  })
+}
+function ComponentRange(props: {
+  readonly state: ComponentState
+  readonly record: import("@nifrajs/web/server-components/client").ComponentRecord
+  readonly controller?: ComponentController | undefined
+  readonly clientAdapter?: ComponentClientAdapter | undefined
+  readonly onError?: ((code: string) => void) | undefined
+}) {
+  const record = props.record
+  const host = useRef<HTMLElement>(null)
+  // React owns the shell; the independently hydrated native root is an unassociated child.
+  const initial = useRef({
+    __html: `<nifra-component data-nifra-component="${record.instance}">${record.html}</nifra-component>`,
+  })
+  const active = useRef<ComponentController | undefined>(undefined)
+  const lifecycle = useRef(props)
+  lifecycle.current = props
+  useLayoutEffect(() => {
+    const options = lifecycle.current
+    const element = host.current?.firstElementChild
+    if (!(element instanceof HTMLElement) || element.localName !== "nifra-component") return
+    const controller =
+      options.controller ??
+      new ComponentController({
+        state: options.state,
+        adapter: options.clientAdapter ?? lazyClient(),
+        onError: (code) => lifecycle.current.onError?.(code),
+      })
+    active.current = controller
+    void controller
+      .mount(element, record.instance)
+      .catch(() => lifecycle.current.onError?.("component_failed"))
+    return () => {
+      void (
+        options.controller === undefined
+          ? controller.dispose()
+          : controller.unmount(record.instance)
+      ).catch(() => lifecycle.current.onError?.("component_failed"))
+    }
+  }, [record.instance])
+  useLayoutEffect(() => {
+    if (active.current !== undefined)
+      void active.current.adopt(props.state).catch(() => props.onError?.("component_failed"))
+  }, [props.state, props.onError])
+  return createElement("nifra-component-outlet", {
+    ref: host,
+    // biome-ignore lint/security/noDangerouslySetInnerHtml: Record HTML passed the shared component policy before an outlet can resolve it.
+    dangerouslySetInnerHTML: initial.current,
+  })
+}

package/src/server-components/rsc.ts

@@ -0,0 +1,39 @@
+import type { ComponentRenderContext, ServerComponentHandle } from "@nifrajs/web/server-components"
+import { guardComponentProps } from "@nifrajs/web/server-components/props"
+import { renderToReadableStream } from "@vitejs/plugin-rsc/rsc/server"
+import { type ComponentType, createElement } from "react"
+import { publicFlightStream } from "./flight.ts"
+
+/** Export this renderer from the compiler's RSC entry, which owns React's server condition. */
+export function createReactComponentRenderer(components: readonly ServerComponentHandle[]) {
+  const references = new Map(components.map((component) => [component.reference, component]))
+  if (references.size !== components.length || references.has(undefined))
+    throw new Error("component_contract")
+  return async (
+    reference: string,
+    props: unknown,
+    context: ComponentRenderContext,
+  ): Promise<ReadableStream<Uint8Array>> => {
+    const component = references.get(reference)
+    if (component === undefined) throw new Error("component_unavailable")
+    const projected = await guardComponentProps(component.props, props)
+    const stream = renderToReadableStream(
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: The renderer resolves an allowlisted definition and guards its public props before invoking that definition.
+      createElement(component.view as ComponentType<{ props: unknown; children: unknown }>, {
+        props: projected,
+        // biome-ignore lint/correctness/noChildrenProp: Server views receive verified record metadata through their declared children prop.
+        children: context.children ?? [],
+      }),
+      {
+        signal: context.signal,
+        // React development debug metadata can contain server-only props; it has no public transport.
+        debugChannel: { writable: new WritableStream<Uint8Array>({ write() {} }) },
+        filterStackFrame: () => false,
+        onError() {
+          return "component_failed"
+        },
+      },
+    )
+    return publicFlightStream(stream, context.signal)
+  }
+}