@henjicc/ai-sdk 0.2.8 → 0.3.0

package/docs//346/216/245/345/205/245/346/214/207/345/215/227//351/224/231/350/257/257/345/244/204/347/220/206.md

@@ -1,72 +1,72 @@
-# 错误处理
-
-SDK 有两层错误契约：生成/上传的 `AiRuntimeError.code`，以及 LLM 的
-`ProviderModelStepError.details` 分类。宿主显示用户可读提示，把原始细节放进经脱敏的调试日志；
-不要把 API key、Authorization header 或完整供应商 body 原样显示。
-
-在仓库根运行下列命令，会从 `packages/ai-sdk/src` 的真实 schema/callsites 穷举并检查本页：
-
-```bash
-node packages/ai-sdk/scripts/audit-integration-docs.cjs --check
-```
-
-## AiRuntimeError
-
-| code | 宿主提示/处理 |
-|---|---|
-| `api_key_missing` | 该生成供应商未配置密钥；打开凭据设置。 |
-| `missing_api_key` | 媒体上传依赖的供应商密钥缺失；补配后重新提交。 |
-| `cancelled` | 任务已取消；不作失败 toast，停止轮询。 |
-| `client_disposed` | client 已释放；修正宿主生命周期，不要自动重试。 |
-| `empty_result` | 供应商已响应但没有可用结果 URL；保留 taskId 与脱敏响应供排查。 |
-| `invalid_audio` | 实时识别没有收到可提交的音频；检查录音与分块生命周期。 |
-| `invalid_audio_chunk` | 音频块为空或不满足 PCM 字节对齐；宿主修正分块后再发送。 |
-| `invalid_data_uri` | 媒体 data URI 格式无效；让用户重新选择/导出文件。 |
-| `invalid_base64` | 媒体 base64 数据无效；让宿主重新编码文件。 |
-| `invalid_json` | 供应商返回非 JSON；不重放付费创建请求，保留 taskId 查询。 |
-| `invalid_media` | 文件识别收到空媒体；让用户重新选择或重新读取文件。 |
-| `invalid_parameter` | ASR 通用或供应商参数类型/范围无效；修正调用参数，不自动重试。 |
-| `invalid_provider_id` | 自定义 provider ID 为空；在注册前校验。 |
-| `invalid_response` | 响应缺少必需字段；提示协议不兼容并记录脱敏响应。 |
-| `invalid_route` | catalog 给出空路由；属于开发/版本错误。 |
-| `invalid_selector_result` | endpoint selector 没有返回字符串；属于开发/版本错误。 |
-| `provider_already_registered` | provider ID 已被另一 client 占用；使用唯一 ID 或先 `dispose()`。 |
-| `provider_http_error` | 供应商 HTTP 失败；按 status 引导检查参数/鉴权/服务。 |
-| `provider_network_error` | DNS/连接等网络失败；允许用户主动重试，不自动重放可能计费的 POST。 |
-| `provider_not_found` | 模型无法映射 provider；检查模型 ID/版本。 |
-| `provider_task_failed` | 供应商明确宣告任务失败；显示经脱敏原因，不继续轮询。 |
-| `provider_task_unreachable` | 状态查询连续 20 次失败；保留 taskId，让用户稍后手动续查。 |
-| `public_media_url_required` | 目标字段必须是公网 URL，但当前供应商没有可用官方上传路径。 |
-| `unknown_provider` | 调用了未注册 provider；核对 ID 或注册流程。 |
-| `unsupported_media_source` | 后端不能解析 `blob:` 等媒体引用；宿主先导出成受管字节。 |
-| `unsupported_media_type` | 上传端点不支持当前 MIME；转成文档允许的格式。 |
-| `unsupported_audio_format` | ASR 音频编码不受当前协议支持；按模型要求转换格式。 |
-| `unsupported_parameter` | 当前 P0 协议未实现该可选参数；宿主移除参数或选择其他模型。 |
-| `unsupported_provider` | 对同步 provider 调用了续轮询等不支持的生命周期。 |
-| `upload_failed` | 供应商官方上传失败/未返回 URL；引导重新选择或检查密钥。 |
-| `upload_timeout` | Fal 两段上传超过 120 秒；确认网络后由用户重新提交。 |
-| `upload_too_large` | 文件超过上传上限；显示精确限制并让用户压缩/换文件。 |
-
-## LLM 结构化错误
-
-`ProviderModelStepError.details` 固定字段为 `code/category/status/retryable/retryAfterMs/providerId/modelId/requestId/message`。
-供应商的 code 可动态透传；SDK 自己产生的固定 code 是 `API_KEY_MISSING`、`MODEL_REQUEST_TIMEOUT`、
-`MODEL_STEP_CANCELLED`、`PROVIDER_ERROR`。字符串协议 marker 为 `api_key_missing`、`model_step_failed`、
-`provider_error`、`task_cancelled`。
-
-| category | 建议提示 | SDK 默认 retryable |
-|---|---|---|
-| `authentication` | 鉴权失败，重新配置密钥 | 否 |
-| `billing` | 计费状态异常，检查账单/充值 | 否 |
-| `quota` | 供应商额度不足 | 否 |
-| `rate_limit` | 请求频率受限，按 `retryAfterMs` 等待 | 是 |
-| `server` | 供应商服务暂时不可用 | 是 |
-| `network` | 网络请求失败 | 是 |
-| `invalid_request` | 供应商拒绝了参数，显示脱敏 detail | 否 |
-| `context_overflow` | 上下文超限，缩短历史/附件 | 否 |
-| `content_filter` | 内容策略拒绝，调整输入 | 否 |
-| `cancelled` | 用户取消，不当成系统失败 | 否 |
-| `unknown` | 供应商请求失败，保留 requestId 供排查 | 否 |
-
-`retryable: true` 不等于宿主可以无脑重放一次完整付费请求。生成创建 POST 只在能证明尚未建连时有
-“安全预连接”重试；轮询 GET 和 LLM 模型步又有各自独立生命周期。
+# 错误处理
+
+SDK 有两层错误契约：生成/上传的 `AiRuntimeError.code`，以及 LLM 的
+`ProviderModelStepError.details` 分类。宿主显示用户可读提示，把原始细节放进经脱敏的调试日志；
+不要把 API key、Authorization header 或完整供应商 body 原样显示。
+
+在仓库根运行下列命令，会从 `packages/ai-sdk/src` 的真实 schema/callsites 穷举并检查本页：
+
+```bash
+node packages/ai-sdk/scripts/audit-integration-docs.cjs --check
+```
+
+## AiRuntimeError
+
+| code | 宿主提示/处理 |
+|---|---|
+| `api_key_missing` | 该生成供应商未配置密钥；打开凭据设置。 |
+| `missing_api_key` | 媒体上传依赖的供应商密钥缺失；补配后重新提交。 |
+| `cancelled` | 任务已取消；不作失败 toast，停止轮询。 |
+| `client_disposed` | client 已释放；修正宿主生命周期，不要自动重试。 |
+| `empty_result` | 供应商已响应但没有可用结果 URL；保留 taskId 与脱敏响应供排查。 |
+| `invalid_audio` | 实时识别没有收到可提交的音频；检查录音与分块生命周期。 |
+| `invalid_audio_chunk` | 音频块为空或不满足 PCM 字节对齐；宿主修正分块后再发送。 |
+| `invalid_data_uri` | 媒体 data URI 格式无效；让用户重新选择/导出文件。 |
+| `invalid_base64` | 媒体 base64 数据无效；让宿主重新编码文件。 |
+| `invalid_json` | 供应商返回非 JSON；不重放付费创建请求，保留 taskId 查询。 |
+| `invalid_media` | 文件识别收到空媒体；让用户重新选择或重新读取文件。 |
+| `invalid_parameter` | ASR 通用或供应商参数类型/范围无效；修正调用参数，不自动重试。 |
+| `invalid_provider_id` | 自定义 provider ID 为空；在注册前校验。 |
+| `invalid_response` | 响应缺少必需字段；提示协议不兼容并记录脱敏响应。 |
+| `invalid_route` | catalog 给出空路由；属于开发/版本错误。 |
+| `invalid_selector_result` | endpoint selector 没有返回字符串；属于开发/版本错误。 |
+| `provider_already_registered` | provider ID 已被另一 client 占用；使用唯一 ID 或先 `dispose()`。 |
+| `provider_http_error` | 供应商 HTTP 失败；按 status 引导检查参数/鉴权/服务。 |
+| `provider_network_error` | DNS/连接等网络失败；允许用户主动重试，不自动重放可能计费的 POST。 |
+| `provider_not_found` | 模型无法映射 provider；检查模型 ID/版本。 |
+| `provider_task_failed` | 供应商明确宣告任务失败；显示经脱敏原因，不继续轮询。 |
+| `provider_task_unreachable` | 状态查询连续 20 次失败；保留 taskId，让用户稍后手动续查。 |
+| `public_media_url_required` | 目标字段必须是公网 URL，但当前供应商没有可用官方上传路径。 |
+| `unknown_provider` | 调用了未注册 provider；核对 ID 或注册流程。 |
+| `unsupported_media_source` | 后端不能解析 `blob:` 等媒体引用；宿主先导出成受管字节。 |
+| `unsupported_media_type` | 上传端点不支持当前 MIME；转成文档允许的格式。 |
+| `unsupported_audio_format` | ASR 音频编码不受当前协议支持；按模型要求转换格式。 |
+| `unsupported_parameter` | 当前 P0 协议未实现该可选参数；宿主移除参数或选择其他模型。 |
+| `unsupported_provider` | 对同步 provider 调用了续轮询等不支持的生命周期。 |
+| `upload_failed` | 供应商官方上传失败/未返回 URL；引导重新选择或检查密钥。 |
+| `upload_timeout` | Fal 两段上传超过 120 秒；确认网络后由用户重新提交。 |
+| `upload_too_large` | 文件超过上传上限；显示精确限制并让用户压缩/换文件。 |
+
+## LLM 结构化错误
+
+`ProviderModelStepError.details` 固定字段为 `code/category/status/retryable/retryAfterMs/providerId/modelId/requestId/message`。
+供应商的 code 可动态透传；SDK 自己产生的固定 code 是 `API_KEY_MISSING`、`MODEL_REQUEST_TIMEOUT`、
+`MODEL_STEP_CANCELLED`、`PROVIDER_ERROR`。字符串协议 marker 为 `api_key_missing`、`model_step_failed`、
+`provider_error`、`task_cancelled`。
+
+| category | 建议提示 | SDK 默认 retryable |
+|---|---|---|
+| `authentication` | 鉴权失败，重新配置密钥 | 否 |
+| `billing` | 计费状态异常，检查账单/充值 | 否 |
+| `quota` | 供应商额度不足 | 否 |
+| `rate_limit` | 请求频率受限，按 `retryAfterMs` 等待 | 是 |
+| `server` | 供应商服务暂时不可用 | 是 |
+| `network` | 网络请求失败 | 是 |
+| `invalid_request` | 供应商拒绝了参数，显示脱敏 detail | 否 |
+| `context_overflow` | 上下文超限，缩短历史/附件 | 否 |
+| `content_filter` | 内容策略拒绝，调整输入 | 否 |
+| `cancelled` | 用户取消，不当成系统失败 | 否 |
+| `unknown` | 供应商请求失败，保留 requestId 供排查 | 否 |
+
+`retryable: true` 不等于宿主可以无脑重放一次完整付费请求。生成创建 POST 只在能证明尚未建连时有
+“安全预连接”重试；轮询 GET 和 LLM 模型步又有各自独立生命周期。

package/examples/form-renderer/README.md

@@ -1,17 +1,17 @@
-# form-renderer
-
-无框架、无 DOM 依赖的 `@henjicc/ai-sdk@0.2.8` 参数表单契约示例。它从 `client.catalog` 读取真实模型，使用
-`evaluateRuntimeCondition()` 处理显隐/禁用，使用 `getRuntimeMediaInputContract()` 生成媒体上传入口。
-示例只使用 `generation`、`catalog` 与 `runtime` 按需入口，保留完整 generation catalog，
-但不会带入 LLM/BigModel。
-
-```bash
-npm install
-npm start
-```
-
-入口会真实渲染 5 个差异模型，覆盖普通下拉与数值、条件显隐、动态 input limits、通用与特殊媒体、
-`composite` 宿主钩子。输出是最小 HTML 骨架，不包含痕迹AI 的名称、i18n、面板布局或专属组件。
-
-媒体控件只负责让宿主选择本地/受管资源，不能降级为 URL 文本框；实际上传仍由 SDK 在请求边界调用
-当前供应商的官方上传能力。`composite` 只输出 `data-control="custom"`，宿主按参数 ID 注入自己的组件。
+# form-renderer
+
+无框架、无 DOM 依赖的 `@henjicc/ai-sdk@0.3.0` 参数表单契约示例。它从 `client.catalog` 读取真实模型，使用
+`evaluateRuntimeCondition()` 处理显隐/禁用，使用 `getRuntimeMediaInputContract()` 生成媒体上传入口。
+示例只使用 `generation`、`catalog` 与 `runtime` 按需入口，保留完整 generation catalog，
+但不会带入 LLM/BigModel。
+
+```bash
+npm install
+npm start
+```
+
+入口会真实渲染 5 个差异模型，覆盖普通下拉与数值、条件显隐、动态 input limits、通用与特殊媒体、
+`composite` 宿主钩子。输出是最小 HTML 骨架，不包含痕迹AI 的名称、i18n、面板布局或专属组件。
+
+媒体控件只负责让宿主选择本地/受管资源，不能降级为 URL 文本框；实际上传仍由 SDK 在请求边界调用
+当前供应商的官方上传能力。`composite` 只输出 `data-control="custom"`，宿主按参数 ID 注入自己的组件。

package/examples/form-renderer/cli.ts

@@ -1,32 +1,32 @@
-import { createGenerationClient } from '@henjicc/ai-sdk/generation'
-import type { RuntimeContext } from '@henjicc/ai-sdk/runtime'
-
-import { renderMinimalModelForm } from './index.js'
-
-const runtime: RuntimeContext = {
-  transport: { fetch: async () => { throw new Error('form-renderer does not access the network') } },
-  credentials: { get: () => undefined },
-  media: { read: async () => { throw new Error('form-renderer does not read media') } },
-}
-
-const modelIds = [
-  'volcengine-seedream-5.0-lite',
-  'apimart-gemini-omni-flash',
-  'ppio-wan-2.7',
-  'apimart-midjourney',
-  'ppio-minimax-speech',
-] as const
-
-const client = createGenerationClient({ runtime })
-try {
-  const forms = modelIds.map((modelId) => renderMinimalModelForm(client, modelId))
-  console.log(JSON.stringify(forms.map((form) => ({
-    modelId: form.modelId,
-    controlCount: form.controls.length,
-    mediaKinds: [...new Set(form.controls.map((control) => control.mediaKind).filter(Boolean))],
-    customControlIds: form.customControlIds,
-    html: form.html,
-  })), null, 2))
-} finally {
-  client.dispose()
-}
+import { createGenerationClient } from '@henjicc/ai-sdk/generation'
+import type { RuntimeContext } from '@henjicc/ai-sdk/runtime'
+
+import { renderMinimalModelForm } from './index.js'
+
+const runtime: RuntimeContext = {
+  transport: { fetch: async () => { throw new Error('form-renderer does not access the network') } },
+  credentials: { get: () => undefined },
+  media: { read: async () => { throw new Error('form-renderer does not read media') } },
+}
+
+const modelIds = [
+  'volcengine-seedream-5.0-lite',
+  'apimart-gemini-omni-flash',
+  'ppio-wan-2.7',
+  'apimart-midjourney',
+  'ppio-minimax-speech',
+] as const
+
+const client = createGenerationClient({ runtime })
+try {
+  const forms = modelIds.map((modelId) => renderMinimalModelForm(client, modelId))
+  console.log(JSON.stringify(forms.map((form) => ({
+    modelId: form.modelId,
+    controlCount: form.controls.length,
+    mediaKinds: [...new Set(form.controls.map((control) => control.mediaKind).filter(Boolean))],
+    customControlIds: form.customControlIds,
+    html: form.html,
+  })), null, 2))
+} finally {
+  client.dispose()
+}

package/examples/form-renderer/index.ts

@@ -1,144 +1,144 @@
-import {
-  evaluateRuntimeCondition,
-  flattenRuntimeParams,
-  getRuntimeMediaInputContract,
-} from '@henjicc/ai-sdk/catalog'
-import type { GenerationClient } from '@henjicc/ai-sdk/generation'
-
-type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject
-type JsonObject = { [key: string]: JsonValue }
-type RuntimeParamDef = ReturnType<GenerationClient['catalog']['getParams']>[number]
-
-export type MinimalControlKind =
-  | 'text'
-  | 'textarea'
-  | 'number'
-  | 'select'
-  | 'switch'
-  | 'upload'
-  | 'custom'
-
-export interface MinimalRenderedControl {
-  id: string
-  kind: MinimalControlKind
-  value: JsonValue | undefined
-  disabled: boolean
-  source: 'param' | 'input-limits'
-  mediaKind?: 'image' | 'video' | 'audio' | 'file'
-}
-
-export interface MinimalRenderedForm {
-  modelId: string
-  controls: MinimalRenderedControl[]
-  customControlIds: string[]
-  html: string
-}
-
-/**
- * 无框架、无 DOM 依赖的最小 renderer，只用于证明 SDK 参数契约足以驱动消费方表单。
- * composite 只输出 data-control="custom" 钩子；痕迹AI 专属 panel/config 属于 presentation，
- * 宿主必须按 param id 注入自定义组件。
- */
-export function renderMinimalModelForm(
-  client: GenerationClient,
-  modelId: string,
-  values: JsonObject = {}
-): MinimalRenderedForm {
-  const model = client.catalog.get(modelId)
-  if (!model) throw new Error(`Unknown model: ${modelId}`)
-  const runtimeValues: JsonObject = {
-    ...client.catalog.getDefaultValues(modelId),
-    uploadedFilePaths: [],
-    uploadedVideoFilePaths: [],
-    uploadedAudioFilePaths: [],
-    images: [],
-    videos: [],
-    audios: [],
-    uploadedImages: [],
-    uploadedVideos: [],
-    uploadedAudios: [],
-    ...values,
-  }
-  const controls: MinimalRenderedControl[] = []
-
-  for (const param of flattenRuntimeParams(client.catalog.getParams(modelId))) {
-    if (!evaluateRuntimeCondition(param.visible?.condition, runtimeValues)) continue
-    controls.push({
-      id: param.id,
-      kind: controlKindForParam(param),
-      value: runtimeValues[param.id],
-      disabled: param.disabled !== undefined &&
-        evaluateRuntimeCondition(param.disabled.condition, runtimeValues),
-      source: 'param',
-      ...mediaKindForParam(param),
-    })
-  }
-
-  const media = getRuntimeMediaInputContract(model, runtimeValues)
-  for (const input of media.genericInputs) {
-    controls.push({
-      id: input.id,
-      kind: 'upload',
-      value: runtimeValues[input.id],
-      disabled: false,
-      source: 'input-limits',
-      mediaKind: input.kind,
-    })
-  }
-
-  controls.sort((left, right) => {
-    const leftParam = model.params.find((param) => param.id === left.id)
-    const rightParam = model.params.find((param) => param.id === right.id)
-    return (leftParam?.order ?? Number.MAX_SAFE_INTEGER) -
-      (rightParam?.order ?? Number.MAX_SAFE_INTEGER)
-  })
-
-  return {
-    modelId: model.meta.id,
-    controls,
-    customControlIds: controls.filter((control) => control.kind === 'custom').map((control) => control.id),
-    html: `<form data-model-id="${escapeHtml(model.meta.id)}">${controls.map(renderControlHtml).join('')}</form>`,
-  }
-}
-
-function controlKindForParam(param: RuntimeParamDef): MinimalControlKind {
-  switch (param.type) {
-    case 'text': return 'text'
-    case 'textarea': return 'textarea'
-    case 'number': return 'number'
-    case 'dropdown':
-    case 'radio':
-    case 'resolution':
-    case 'aspect-ratio': return 'select'
-    case 'switch': return 'switch'
-    case 'image-upload':
-    case 'video-upload':
-    case 'file-upload': return 'upload'
-    case 'composite': return 'custom'
-    case 'panel': return 'custom'
-  }
-}
-
-function mediaKindForParam(
-  param: RuntimeParamDef
-): Pick<MinimalRenderedControl, 'mediaKind'> | Record<string, never> {
-  if (param.type === 'image-upload') return { mediaKind: 'image' }
-  if (param.type === 'video-upload') return { mediaKind: 'video' }
-  if (param.type === 'file-upload') return { mediaKind: 'file' }
-  return {}
-}
-
-function renderControlHtml(control: MinimalRenderedControl): string {
-  const id = escapeHtml(control.id)
-  const media = control.mediaKind ? ` data-media-kind="${control.mediaKind}"` : ''
-  const disabled = control.disabled ? ' aria-disabled="true"' : ''
-  return `<div data-param-id="${id}" data-control="${control.kind}" data-source="${control.source}"${media}${disabled}></div>`
-}
-
-function escapeHtml(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('"', '&quot;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-}
+import {
+  evaluateRuntimeCondition,
+  flattenRuntimeParams,
+  getRuntimeMediaInputContract,
+} from '@henjicc/ai-sdk/catalog'
+import type { GenerationClient } from '@henjicc/ai-sdk/generation'
+
+type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject
+type JsonObject = { [key: string]: JsonValue }
+type RuntimeParamDef = ReturnType<GenerationClient['catalog']['getParams']>[number]
+
+export type MinimalControlKind =
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'select'
+  | 'switch'
+  | 'upload'
+  | 'custom'
+
+export interface MinimalRenderedControl {
+  id: string
+  kind: MinimalControlKind
+  value: JsonValue | undefined
+  disabled: boolean
+  source: 'param' | 'input-limits'
+  mediaKind?: 'image' | 'video' | 'audio' | 'file'
+}
+
+export interface MinimalRenderedForm {
+  modelId: string
+  controls: MinimalRenderedControl[]
+  customControlIds: string[]
+  html: string
+}
+
+/**
+ * 无框架、无 DOM 依赖的最小 renderer，只用于证明 SDK 参数契约足以驱动消费方表单。
+ * composite 只输出 data-control="custom" 钩子；痕迹AI 专属 panel/config 属于 presentation，
+ * 宿主必须按 param id 注入自定义组件。
+ */
+export function renderMinimalModelForm(
+  client: GenerationClient,
+  modelId: string,
+  values: JsonObject = {}
+): MinimalRenderedForm {
+  const model = client.catalog.get(modelId)
+  if (!model) throw new Error(`Unknown model: ${modelId}`)
+  const runtimeValues: JsonObject = {
+    ...client.catalog.getDefaultValues(modelId),
+    uploadedFilePaths: [],
+    uploadedVideoFilePaths: [],
+    uploadedAudioFilePaths: [],
+    images: [],
+    videos: [],
+    audios: [],
+    uploadedImages: [],
+    uploadedVideos: [],
+    uploadedAudios: [],
+    ...values,
+  }
+  const controls: MinimalRenderedControl[] = []
+
+  for (const param of flattenRuntimeParams(client.catalog.getParams(modelId))) {
+    if (!evaluateRuntimeCondition(param.visible?.condition, runtimeValues)) continue
+    controls.push({
+      id: param.id,
+      kind: controlKindForParam(param),
+      value: runtimeValues[param.id],
+      disabled: param.disabled !== undefined &&
+        evaluateRuntimeCondition(param.disabled.condition, runtimeValues),
+      source: 'param',
+      ...mediaKindForParam(param),
+    })
+  }
+
+  const media = getRuntimeMediaInputContract(model, runtimeValues)
+  for (const input of media.genericInputs) {
+    controls.push({
+      id: input.id,
+      kind: 'upload',
+      value: runtimeValues[input.id],
+      disabled: false,
+      source: 'input-limits',
+      mediaKind: input.kind,
+    })
+  }
+
+  controls.sort((left, right) => {
+    const leftParam = model.params.find((param) => param.id === left.id)
+    const rightParam = model.params.find((param) => param.id === right.id)
+    return (leftParam?.order ?? Number.MAX_SAFE_INTEGER) -
+      (rightParam?.order ?? Number.MAX_SAFE_INTEGER)
+  })
+
+  return {
+    modelId: model.meta.id,
+    controls,
+    customControlIds: controls.filter((control) => control.kind === 'custom').map((control) => control.id),
+    html: `<form data-model-id="${escapeHtml(model.meta.id)}">${controls.map(renderControlHtml).join('')}</form>`,
+  }
+}
+
+function controlKindForParam(param: RuntimeParamDef): MinimalControlKind {
+  switch (param.type) {
+    case 'text': return 'text'
+    case 'textarea': return 'textarea'
+    case 'number': return 'number'
+    case 'dropdown':
+    case 'radio':
+    case 'resolution':
+    case 'aspect-ratio': return 'select'
+    case 'switch': return 'switch'
+    case 'image-upload':
+    case 'video-upload':
+    case 'file-upload': return 'upload'
+    case 'composite': return 'custom'
+    case 'panel': return 'custom'
+  }
+}
+
+function mediaKindForParam(
+  param: RuntimeParamDef
+): Pick<MinimalRenderedControl, 'mediaKind'> | Record<string, never> {
+  if (param.type === 'image-upload') return { mediaKind: 'image' }
+  if (param.type === 'video-upload') return { mediaKind: 'video' }
+  if (param.type === 'file-upload') return { mediaKind: 'file' }
+  return {}
+}
+
+function renderControlHtml(control: MinimalRenderedControl): string {
+  const id = escapeHtml(control.id)
+  const media = control.mediaKind ? ` data-media-kind="${control.mediaKind}"` : ''
+  const disabled = control.disabled ? ' aria-disabled="true"' : ''
+  return `<div data-param-id="${id}" data-control="${control.kind}" data-source="${control.source}"${media}${disabled}></div>`
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('"', '&quot;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+}

package/examples/form-renderer/package.json

@@ -1,16 +1,16 @@
-{
-  "name": "@henjicc/ai-sdk-example-form-renderer",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "start": "npm run build && node dist/cli.js"
-  },
-  "dependencies": {
-    "@henjicc/ai-sdk": "0.2.8"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.9.2"
-  }
-}
+{
+  "name": "@henjicc/ai-sdk-example-form-renderer",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "npm run build && node dist/cli.js"
+  },
+  "dependencies": {
+    "@henjicc/ai-sdk": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.2"
+  }
+}

package/examples/form-renderer/tsconfig.json

@@ -1,14 +1,14 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "lib": ["ES2022", "DOM"],
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "skipLibCheck": true,
-    "outDir": "dist",
-    "rootDir": ".",
-    "types": ["node"]
-  },
-  "include": ["index.ts", "cli.ts"]
-}
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "types": ["node"]
+  },
+  "include": ["index.ts", "cli.ts"]
+}