开始调用 Host API

本指南串起一个 v0.1 应用的最小完整路径：版本声明、方法授权、启动握手、调用、事件和清理。

1. 声明版本与最小能力

{
  "apiVersion": "0.1",
  "capabilities": [
    "host:env.snapshot",
    "host:store.get",
    "host:store.put",
    "host:capture.requestCamera"
  ],
  "events": ["env.change"],
  "apiLimits": {}
}

逐方法声明，不用裸模块名或通配符。声明 store.get 不会自动获得 store.put。

2. 加载 SDK

使用打包工具的应用安装并导入 v0.1 SDK：

npm install @appist/[email protected]

import { appist, CancellationController, HostError, HostVersionError } from '@appist/host-api';

正式发布应用应由打包工具把 SDK 编入 sealed guest；Host API 不暴露给外层 HTML 页面。仓库另提供 /sdk/v0.1/appist.js 浏览器全局产物，只用于开发工具或宿主嵌入：使用它的宿主必须在同一个 realm 先安装私有 binding。普通发布应用不得用 HTML <script> 标签加载它并期待访问 Host API，也不能为此把私有 binding 暴露到页面。

无论具体分发方式如何，Host API transport 都由 application.ist runtime 在 guest 启动前安装；应用不应自行构造 transport。浏览器全局入口只在页面尚未定义 globalThis.appist 时安装对象，不会覆盖已有值。

3. 启动前握手

const host = await appist.host({ apiVersion: '0.1' });

这是 v0.1 SDK 的实际入口。宿主在 guest 执行前比对版本与方法集；不支持时抛出 HostVersionError，不返回一个缺方法的半可用对象。握手成功表示宿主完整实现 v0.1 的 27 个方法和 15 个事件，不存在成员级的“部分支持”。

4. 调用与 HostError

try {
  const env = await host.env.snapshot();
  applyTheme(env.colorScheme);
} catch (error) {
  if (error instanceof HostError && error.code === 'limit-exceeded' && error.retryable) {
    scheduleLater();
  } else {
    showFailure(error instanceof Error ? error.message : 'unknown failure');
  }
}

只根据稳定 code 分支，不解析人类错误文本。只有成员页明确规定的用户关闭结果才返回 null，不应当成系统故障。

5. 事件

const off = host.events.on('env.change', async ({ changedFields }) => {
  const latest = await host.env.snapshot();
  updateChangedFields(latest, changedFields);
});

// 应用销毁时注销本地处理器。
off();

类型化事件传输在 guest 加载前已存在，不要为每个模块发明一套订阅 RPC。事件可以有界合并；方法返回值与重新读取的快照才是权威状态。

6. 取消与清理

const controller = new CancellationController();
const request = host.capture.requestCamera(
  { facing: 'user', maxWidth: 1280, maxHeight: 720 },
  { signal: controller.signal },
);
controller.abort();

CancellationController 在没有浏览器全局对象的 QuickJS guest 中也可用；若宿主提供标准 AbortController，其 signal 同样满足此接口。

取消不得留下 guest 无法释放的句柄。会话类资源仍然应显式调用 stop/closeSession；这些清理方法由句柄授权，不需要额外 capability。宿主在 guest 崩溃或视图销毁时还要做最终回收。

7. 原生 WASM 绑定

逻辑 API 不出现 ptr/len。原生绑定将线性内存区域验证后映射为 ByteSource/ByteSink：

uint8_t out[4096];
StoreGetResult result = host_store_get("settings", byte_sink(out, sizeof(out)));

宿主不得保留未约定的 guest 指针，也不得把输出截断后伪装成完整成功。