@nifrajs/web 4.0.2 → 5.1.0

package/src/server-components/source.ts

@@ -0,0 +1,324 @@
+import { createHash } from "node:crypto"
+import { relative } from "node:path"
+import type * as TS from "typescript"
+import { ts } from "./typescript.ts"
+
+export interface CompiledComponentModule {
+  readonly code: string
+  readonly references: Readonly<Record<string, string>>
+}
+
+export function componentReference(file: string, root: string, name: string): string {
+  return (
+    "sc_" +
+    createHash("sha256")
+      .update(`${relative(root, file).replaceAll("\\", "/")}#${name}`)
+      .digest("hex")
+      .slice(0, 32)
+  )
+}
+
+export function sourceFile(source: string, file: string): TS.SourceFile {
+  return ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    /\.[jt]sx$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  )
+}
+
+function modifier(node: TS.Node, kind: TS.SyntaxKind): boolean {
+  return (
+    ts.canHaveModifiers(node) &&
+    (ts.getModifiers(node)?.some((item) => item.kind === kind) ?? false)
+  )
+}
+
+function literal(node: TS.Expression): unknown {
+  if (
+    ts.isAsExpression(node) ||
+    ts.isSatisfiesExpression(node) ||
+    ts.isParenthesizedExpression(node)
+  )
+    return literal(node.expression)
+  if (ts.isStringLiteral(node)) return node.text
+  if (!ts.isObjectLiteralExpression(node)) throw new Error("component_pipeline_literal")
+  const result: Record<string, unknown> = Object.create(null)
+  for (const member of node.properties) {
+    if (
+      !ts.isPropertyAssignment(member) ||
+      !(ts.isIdentifier(member.name) || ts.isStringLiteral(member.name))
+    )
+      throw new Error("component_pipeline_literal")
+    if (
+      Object.hasOwn(result, member.name.text) ||
+      ["__proto__", "prototype", "constructor"].includes(member.name.text)
+    )
+      throw new Error("component_pipeline_literal")
+    result[member.name.text] = literal(member.initializer)
+  }
+  return result
+}
+
+/** The `componentPipeline` a config module exports as a plain literal, read without running the
+ * module, or `undefined` when it exports none or one that is not a literal. */
+export function staticComponentPipeline(source: string, file: string): unknown {
+  let pipeline: unknown
+  for (const statement of sourceFile(source, file).statements) {
+    if (!ts.isVariableStatement(statement) || !modifier(statement, ts.SyntaxKind.ExportKeyword))
+      continue
+    for (const variable of statement.declarationList.declarations) {
+      if (
+        !ts.isIdentifier(variable.name) ||
+        variable.name.text !== "componentPipeline" ||
+        variable.initializer === undefined
+      )
+        continue
+      try {
+        pipeline = literal(variable.initializer)
+      } catch {
+        return undefined
+      }
+    }
+  }
+  return pipeline
+}
+
+export function directive(file: TS.SourceFile, value: string): boolean {
+  let found = false
+  const visit = (node: TS.Node): void => {
+    if (ts.isSourceFile(node) || ts.isBlock(node)) {
+      for (const statement of node.statements) {
+        if (!ts.isExpressionStatement(statement) || !ts.isStringLiteral(statement.expression)) break
+        if (statement.expression.text === value) found = true
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(file)
+  return found
+}
+
+export function exportedValues(file: TS.SourceFile): readonly string[] {
+  const names = new Set<string>()
+  for (const statement of file.statements) {
+    if (ts.isExportAssignment(statement)) {
+      names.add("default")
+      continue
+    }
+    if (ts.isExportDeclaration(statement)) {
+      if (statement.isTypeOnly) continue
+      if (statement.exportClause === undefined || !ts.isNamedExports(statement.exportClause))
+        throw new Error(
+          "[nifra/components] Native client modules require explicit, schema-registered component exports",
+        )
+      for (const element of statement.exportClause.elements)
+        if (!element.isTypeOnly) names.add(element.name.text)
+    }
+    if (!modifier(statement, ts.SyntaxKind.ExportKeyword)) continue
+    if (modifier(statement, ts.SyntaxKind.DefaultKeyword)) {
+      names.add("default")
+      continue
+    }
+    if (ts.isVariableStatement(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name))
+          throw new Error("[nifra/components] Destructured component exports are unsupported")
+        names.add(declaration.name.text)
+      }
+    } else if (
+      ts.isFunctionDeclaration(statement) ||
+      ts.isClassDeclaration(statement) ||
+      ts.isEnumDeclaration(statement)
+    ) {
+      if (statement.name !== undefined) names.add(statement.name.text)
+    }
+  }
+  return [...names]
+}
+
+export function compileComponentModule(
+  source: string,
+  file: string,
+  root: string,
+  environment: string,
+  kind: "server" | "island" = "server",
+): CompiledComponentModule {
+  const ast = sourceFile(source, file)
+  if (directive(ast, "use server"))
+    throw new Error(
+      "[nifra/components] Native use-server actions are unsupported; use a validated serverFn in a *.fn.ts module",
+    )
+  const factories = new Set<string>()
+  const namespaces = new Set<string>()
+  for (const statement of ast.statements) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      !ts.isStringLiteral(statement.moduleSpecifier) ||
+      statement.moduleSpecifier.text !==
+        (kind === "server"
+          ? "@nifrajs/web/server-components"
+          : "@nifrajs/web/server-components/islands")
+    )
+      continue
+    const bindings = statement.importClause?.namedBindings
+    if (bindings !== undefined && ts.isNamedImports(bindings)) {
+      for (const element of bindings.elements)
+        if (
+          (element.propertyName ?? element.name).text ===
+          (kind === "server" ? "defineServerComponent" : "defineClientIsland")
+        )
+          factories.add(element.name.text)
+    } else if (bindings !== undefined && ts.isNamespaceImport(bindings))
+      namespaces.add(bindings.name.text)
+  }
+  const definitions = new Map<string, TS.CallExpression>()
+  for (const statement of ast.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    for (const declaration of statement.declarationList.declarations) {
+      let expression = declaration.initializer
+      while (
+        expression !== undefined &&
+        (ts.isAsExpression(expression) ||
+          ts.isSatisfiesExpression(expression) ||
+          ts.isParenthesizedExpression(expression))
+      )
+        expression = expression.expression
+      if (
+        !ts.isIdentifier(declaration.name) ||
+        expression === undefined ||
+        !ts.isCallExpression(expression)
+      )
+        continue
+      const callee = expression.expression
+      if (
+        (ts.isIdentifier(callee) && factories.has(callee.text)) ||
+        (ts.isPropertyAccessExpression(callee) &&
+          ts.isIdentifier(callee.expression) &&
+          namespaces.has(callee.expression.text) &&
+          callee.name.text === (kind === "server" ? "defineServerComponent" : "defineClientIsland"))
+      ) {
+        if (expression.arguments.length !== 1)
+          throw new Error(
+            "[nifra/components] Component references are generated by the compiler; remove the handwritten reference",
+          )
+        definitions.set(declaration.name.text, expression)
+      }
+    }
+  }
+  const references: Record<string, string> = Object.create(null)
+  for (const statement of ast.statements) {
+    if (ts.isVariableStatement(statement) && modifier(statement, ts.SyntaxKind.ExportKeyword)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || !definitions.has(declaration.name.text))
+          throw new Error(
+            "[nifra/components] Only named defineServerComponent handles may be exported from *.component.server modules",
+          )
+        references[declaration.name.text] = componentReference(file, root, declaration.name.text)
+      }
+    } else if (ts.isExportDeclaration(statement) && !statement.isTypeOnly) {
+      if (
+        statement.moduleSpecifier !== undefined ||
+        statement.exportClause === undefined ||
+        !ts.isNamedExports(statement.exportClause)
+      )
+        throw new Error("[nifra/components] Re-export component handles through a separate barrel")
+      for (const element of statement.exportClause.elements) {
+        if (element.isTypeOnly) continue
+        const local = (element.propertyName ?? element.name).text
+        if (!definitions.has(local))
+          throw new Error("[nifra/components] A component module exported an unregistered value")
+        references[element.name.text] = componentReference(file, root, local)
+      }
+    } else if (
+      ts.isExportAssignment(statement) ||
+      (modifier(statement, ts.SyntaxKind.ExportKeyword) &&
+        !ts.isInterfaceDeclaration(statement) &&
+        !ts.isTypeAliasDeclaration(statement))
+    ) {
+      throw new Error(
+        "[nifra/components] Export named defineServerComponent handles from *.component.server modules",
+      )
+    }
+  }
+  if (Object.keys(references).length === 0)
+    throw new Error("[nifra/components] A component module has no recognized server component")
+  if (environment === "client" && kind === "server") {
+    return {
+      references,
+      code: Object.entries(references)
+        .map(
+          ([name, reference]) =>
+            `export const ${name} = Object.freeze({ reference: ${JSON.stringify(reference)} });`,
+        )
+        .join("\n"),
+    }
+  }
+  let code = source
+  for (const [name, call] of [...definitions].sort((a, b) => b[1].end - a[1].end)) {
+    const argument = call.arguments[0]
+    if (argument === undefined)
+      throw new Error("[nifra/components] Missing server component definition")
+    const at = argument.end
+    code =
+      code.slice(0, at) +
+      ", " +
+      JSON.stringify(componentReference(file, root, name)) +
+      code.slice(at)
+  }
+  return { code, references }
+}
+
+export function guardCreateElementCalls(source: string, file: string): string {
+  const ast = sourceFile(source, file)
+  const namespaces = new Set<string>()
+  const factories = new Set<string>()
+  for (const statement of ast.statements) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      !ts.isStringLiteral(statement.moduleSpecifier) ||
+      statement.moduleSpecifier.text !== "react"
+    )
+      continue
+    if (statement.importClause?.name !== undefined) namespaces.add(statement.importClause.name.text)
+    const bindings = statement.importClause?.namedBindings
+    if (bindings !== undefined && ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text)
+    if (bindings !== undefined && ts.isNamedImports(bindings))
+      for (const element of bindings.elements) {
+        if ((element.propertyName ?? element.name).text === "createElement")
+          factories.add(element.name.text)
+      }
+  }
+  const changes: Array<{ start: number; end: number }> = []
+  const visit = (node: TS.Node): void => {
+    if (ts.isCallExpression(node)) {
+      const expression = node.expression
+      const named = ts.isIdentifier(expression) && factories.has(expression.text)
+      const member =
+        ts.isPropertyAccessExpression(expression) &&
+        ts.isIdentifier(expression.expression) &&
+        namespaces.has(expression.expression.text) &&
+        expression.name.text === "createElement"
+      const computed =
+        ts.isElementAccessExpression(expression) &&
+        ts.isIdentifier(expression.expression) &&
+        namespaces.has(expression.expression.text) &&
+        ts.isStringLiteral(expression.argumentExpression) &&
+        expression.argumentExpression.text === "createElement"
+      if (named || member || computed)
+        changes.push({ start: expression.getStart(ast), end: expression.end })
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(ast)
+  if (changes.length === 0) return source
+  const identifier = `__nifra_guardedCreateElement_${createHash("sha256").update(file).digest("hex").slice(0, 12)}`
+  let code = source
+  for (const change of changes.sort((a, b) => b.start - a.start))
+    code = code.slice(0, change.start) + identifier + code.slice(change.end)
+  return (
+    `import { guardedCreateElement as ${identifier} } from "@nifrajs/web-react/server-components/guard";\n` +
+    code
+  )
+}

package/src/server-components/state.ts

@@ -0,0 +1,143 @@
+import { ServerComponentError } from "./error.ts"
+import { validateComponentHTML } from "./html.ts"
+import { COMPONENT_LIMITS, componentKey } from "./protocol.ts"
+import type { ComponentIsland, ComponentRecord, ComponentState } from "./types.ts"
+import { componentValue } from "./value.ts"
+
+const token = /^[A-Za-z0-9_-]{1,128}$/
+function object(
+  value: unknown,
+  fields: readonly string[],
+  optional: readonly string[] = [],
+): Record<string, unknown> {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    Array.isArray(value) ||
+    fields.some((field) => !Object.hasOwn(value, field)) ||
+    Object.keys(value).some((field) => !fields.includes(field) && !optional.includes(field))
+  )
+    throw new ServerComponentError("component_protocol", 400)
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
+  return value as Record<string, unknown>
+}
+export function componentToken(value: unknown): value is string {
+  return typeof value === "string" && token.test(value)
+}
+function island(value: unknown): ComponentIsland {
+  const item = object(value, ["reference", "key", "props", "renderId"], ["slots"])
+  if (!componentToken(item.reference) || !componentToken(item.renderId) || !componentKey(item.key))
+    throw new ServerComponentError("component_protocol", 400)
+  if (
+    item.slots !== undefined &&
+    (typeof item.slots !== "object" ||
+      item.slots === null ||
+      Array.isArray(item.slots) ||
+      Object.entries(item.slots).some(
+        ([key, html]) => !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) || typeof html !== "string",
+      ))
+  )
+    throw new ServerComponentError("component_protocol", 400)
+  if (item.slots !== undefined)
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
+    for (const html of Object.values(item.slots)) validateComponentHTML(html as string)
+  const result: ComponentIsland = {
+    reference: item.reference,
+    key: item.key,
+    renderId: item.renderId,
+    props: componentValue(item.props),
+  }
+  if (item.slots !== undefined) Object.assign(result, { slots: item.slots })
+  return result
+}
+export function parseComponentState(
+  value: unknown,
+  maxBytes: number = COMPONENT_LIMITS.documentBytes,
+  externalParent?: string | null,
+): ComponentState {
+  const bounded = componentValue(value, maxBytes)
+  const state = object(bounded, ["v", "build", "adapter", "owner", "scope", "records"])
+  if (
+    state.v !== 1 ||
+    !componentToken(state.build) ||
+    !componentToken(state.owner) ||
+    !componentToken(state.scope) ||
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
+    !["react", "vue", "svelte", "solid", "preact"].includes(state.adapter as string) ||
+    !Array.isArray(state.records) ||
+    state.records.length > COMPONENT_LIMITS.instances
+  )
+    throw new ServerComponentError("component_protocol", 400)
+  const ids = new Set<string>()
+  const islandIds = new Set<string>()
+  let instances = state.records.length
+  const records: ComponentRecord[] = state.records.map((value: unknown) => {
+    const record = object(
+      value,
+      ["instance", "reference", "key", "parent", "input", "html"],
+      ["payload", "islands"],
+    )
+    if (
+      !componentToken(record.instance) ||
+      ids.has(record.instance) ||
+      !componentToken(record.reference) ||
+      !componentKey(record.key) ||
+      (record.parent !== null && !componentToken(record.parent)) ||
+      typeof record.html !== "string"
+    )
+      throw new ServerComponentError("component_protocol", 400)
+    ids.add(record.instance)
+    validateComponentHTML(record.html)
+    if (
+      record.islands !== undefined &&
+      (!Array.isArray(record.islands) || record.islands.length > COMPONENT_LIMITS.instances)
+    )
+      throw new ServerComponentError("component_protocol", 400)
+    const islands =
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
+      record.islands === undefined ? undefined : (record.islands as unknown[]).map(island)
+    for (const island of islands ?? []) {
+      if (islandIds.has(island.renderId)) throw new ServerComponentError("component_protocol", 400)
+      islandIds.add(island.renderId)
+    }
+    instances += islands?.length ?? 0
+    if (instances > COMPONENT_LIMITS.instances)
+      throw new ServerComponentError("component_limit", 413)
+    const result: ComponentRecord = {
+      instance: record.instance,
+      reference: record.reference,
+      key: record.key,
+      // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
+      parent: record.parent as string | null,
+      html: record.html,
+      input: componentValue(record.input, COMPONENT_LIMITS.inputBytes),
+    }
+    if (record.payload !== undefined)
+      Object.assign(result, {
+        payload: componentValue(record.payload, COMPONENT_LIMITS.outputBytes),
+      })
+    if (islands !== undefined) Object.assign(result, { islands })
+    return result
+  })
+  // Refreshes contain a single child and may name its already mounted parent. Documents carry the full forest.
+  for (const record of records) {
+    const chain = new Set([record.instance])
+    let parent = record.parent
+    while (parent !== null) {
+      if (!ids.has(parent) && parent === externalParent) break
+      if (chain.has(parent) || !ids.has(parent) || chain.size >= 16)
+        throw new ServerComponentError("component_protocol", 400)
+      chain.add(parent)
+      parent = records.find((item) => item.instance === parent)?.parent ?? null
+    }
+  }
+  return {
+    v: 1,
+    build: state.build,
+    owner: state.owner,
+    scope: state.scope,
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: Object shape is checked before field inspection; each typed field follows its closed vocabulary check.
+    adapter: state.adapter as ComponentState["adapter"],
+    records,
+  }
+}

package/src/server-components/stream.ts

@@ -0,0 +1,71 @@
+import { ServerComponentError } from "./error.ts"
+import { COMPONENT_LIMITS } from "./protocol.ts"
+
+export function bytesStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes)
+      controller.close()
+    },
+  })
+}
+
+/** The bounded snapshot is shared by SSR and hydration; it never tees into an unread branch. */
+export async function readComponentBytes(
+  stream: ReadableStream<Uint8Array>,
+  signal: AbortSignal,
+  limit: number = COMPONENT_LIMITS.outputBytes,
+): Promise<Uint8Array> {
+  const reader = stream.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  const cancel = () => {
+    void reader.cancel().catch(() => {
+      /* Keep the primary read failure. */
+    })
+  }
+  signal.addEventListener("abort", cancel, { once: true })
+  try {
+    while (true) {
+      if (signal.aborted) throw new ServerComponentError("component_cancelled", 499)
+      const result = await reader.read()
+      if (result.done) break
+      if (result.value.length === 0) throw new ServerComponentError("component_protocol", 400)
+      size += result.value.length
+      if (size > limit) throw new ServerComponentError("component_limit", 413)
+      chunks.push(result.value)
+    }
+    if (signal.aborted) throw new ServerComponentError("component_cancelled", 499)
+    const bytes = new Uint8Array(size)
+    let offset = 0
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset)
+      offset += chunk.length
+    }
+    return bytes
+  } catch (error) {
+    await reader.cancel().catch(() => {
+      /* Keep the primary read failure. */
+    })
+    throw error
+  } finally {
+    signal.removeEventListener("abort", cancel)
+    reader.releaseLock()
+  }
+}
+
+export function encodeComponentBytes(bytes: Uint8Array): string {
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary)
+}
+
+export function decodeComponentBytes(value: unknown): Uint8Array {
+  if (
+    typeof value !== "string" ||
+    value.length > Math.ceil(COMPONENT_LIMITS.outputBytes / 3) * 4 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)
+  )
+    throw new ServerComponentError("component_protocol", 400)
+  return Uint8Array.from(atob(value), (item) => item.charCodeAt(0))
+}

package/src/server-components/trusted-html.ts

@@ -0,0 +1,21 @@
+import { validateComponentHTML } from "./html.ts"
+
+interface TrustedHTMLFactory {
+  createPolicy(
+    name: string,
+    rules: { createHTML(html: string): string },
+  ): { createHTML(html: string): unknown }
+}
+
+/** Explicit opt-in for native framework HTML sinks. Every accepted string is tokenized first. */
+export function installComponentTrustedTypesPolicy(): void {
+  // Trusted Types is not yet declared in all supported TypeScript DOM libraries.
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion lint/plugin/noChainedTypeAssertions: Trusted Types is optional on globalThis and absent from some DOM type libraries; the policy still validates HTML before insertion.
+  const factory = (globalThis as unknown as { trustedTypes?: TrustedHTMLFactory }).trustedTypes
+  factory?.createPolicy("default", {
+    createHTML(html) {
+      validateComponentHTML(html)
+      return html
+    },
+  })
+}

package/src/server-components/types.ts

@@ -0,0 +1,138 @@
+import type { StandardSchemaV1 } from "@nifrajs/core/server"
+import type { LoaderContext } from "../manifest.ts"
+
+export type ComponentKey = string | number
+export type ComponentValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly ComponentValue[]
+  | {
+      readonly [key: string]: ComponentValue
+    }
+
+export interface ServerComponentContext extends LoaderContext {
+  readonly signal: AbortSignal
+  readonly data: unknown
+  readonly layoutData: readonly unknown[]
+}
+
+export interface ServerComponentDefinition<Input, Props, View> {
+  readonly input: StandardSchemaV1<unknown, Input>
+  readonly props: StandardSchemaV1<unknown, Props>
+  readonly authorize: (ctx: ServerComponentContext, input: Input) => void | Promise<void>
+  readonly load: (ctx: ServerComponentContext, input: Input) => unknown | Promise<unknown>
+  readonly view: (args: {
+    readonly props: Props
+    readonly children?: readonly ComponentRecord[]
+  }) => View | Promise<View>
+  readonly capabilities?: readonly string[]
+}
+
+export interface ServerComponent<Input = unknown, Props = unknown, View = unknown> {
+  /** Compiler-generated opaque reference; application authors do not assign module URLs. */
+  readonly reference?: string
+  readonly view: (args: {
+    readonly props: Props
+    readonly children?: readonly ComponentRecord[]
+  }) => View | Promise<View>
+  readonly input: StandardSchemaV1<unknown, Input>
+  readonly props: StandardSchemaV1<unknown, Props>
+}
+
+export interface PreparedServerComponent<Props = unknown, View = unknown> {
+  readonly props: Props
+  readonly view: (args: {
+    readonly props: Props
+    readonly children?: readonly ComponentRecord[]
+  }) => View | Promise<View>
+}
+
+export interface ComponentRenderContext {
+  readonly reference: string
+  readonly instance: string
+  readonly signal: AbortSignal
+  readonly nonce?: string
+  readonly children?: readonly ComponentRecord[]
+}
+
+export interface ComponentRender {
+  readonly html: string
+  readonly payload?: ComponentValue
+  readonly islands?: readonly ComponentIsland[]
+}
+
+export interface ComponentIsland {
+  readonly reference: string
+  readonly key: ComponentKey
+  readonly props: ComponentValue
+  readonly renderId: string
+  readonly slots?: Readonly<Record<string, string>>
+}
+
+export interface ServerComponentRenderAdapter {
+  readonly name: "react" | "vue" | "svelte" | "solid" | "preact"
+  readonly version: 1
+  render(
+    view: unknown,
+    props: unknown,
+    context: ComponentRenderContext,
+  ): ComponentRender | Promise<ComponentRender>
+}
+
+export interface ComponentInstance {
+  readonly component: ServerComponentHandle
+  readonly key: ComponentKey
+  readonly input: unknown
+  readonly parent?: string
+}
+
+export interface ComponentOwner {
+  readonly components: readonly ServerComponentHandle[]
+  readonly capabilities?: readonly string[]
+  readonly instances: (
+    ctx: ServerComponentContext,
+  ) => readonly ComponentInstance[] | Promise<readonly ComponentInstance[]>
+  /** A public, non-secret token supplied by the application's auth integration. */
+  readonly scope: "anonymous" | ((ctx: ServerComponentContext) => string | Promise<string>)
+}
+
+export interface ServerComponentHandle {
+  readonly reference?: string
+  readonly input: StandardSchemaV1
+  readonly props: StandardSchemaV1
+  readonly view: (args: never) => unknown
+}
+
+export interface ComponentRecord extends ComponentRender {
+  readonly instance: string
+  readonly reference: string
+  readonly key: ComponentKey
+  readonly parent: string | null
+  readonly input: ComponentValue
+}
+
+export interface ComponentState {
+  readonly v: 1
+  readonly build: string
+  readonly adapter: "react" | "vue" | "svelte" | "solid" | "preact"
+  readonly owner: string
+  readonly scope: string
+  readonly records: readonly ComponentRecord[]
+}
+
+/** Optional seam passed to createWebApp; disabled applications have no runtime import of this feature. */
+export interface ServerComponentRuntime {
+  owns(routeId: string): boolean
+  capabilities(routeId: string): readonly string[]
+  classify(request: Request, routeId: string): import("./protocol.ts").ComponentRequest | undefined
+  execute(
+    routeId: string,
+    context: ServerComponentContext,
+    selection?: import("./protocol.ts").ComponentRequest,
+    nonce?: string,
+  ): Promise<ComponentState>
+  response(state: ComponentState, selection: import("./protocol.ts").ComponentRequest): Response
+  failure(error: unknown): Response
+}