开始调用 Host API

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

1. 声明版本与最小能力

{
  "apiVersion": "0.1",
  "capabilities": [
    "host:env.snapshot",
    "host:store.get",
    "host:store.put"
  ]
}

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

2. 启动前握手

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

这是规范的逻辑 JS 绑定。宿主在 guest 执行前比对版本与方法集；不支持时以 version-mismatch 终止，不返回一个缺方法的半可用对象。

3. 调用与 HostError

try {
  const env = await host.env.snapshot();
  applyTheme(env.colorScheme);
} catch (error) {
  if (error.code === 'limit-exceeded' && error.retryable) {
    scheduleLater();
  } else {
    showFailure(error.code);
  }
}

只根据稳定 code 分支，不解析人类错误文本。用户关闭选择器或确认框通常返回 null，不应当成系统故障。

4. 事件

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

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

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

5. 取消与清理

const controller = new AbortController();
const request = host.net.fetch(spec, controller.signal);
controller.abort();

取消不得留下 guest 无法释放的句柄。会话类资源仍然应显式调用 stop/closeSession；宿主在 guest 崩溃或视图销毁时还要做最终回收。

6. 原生 WASM 绑定

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

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

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