createFlamoComponentApi

使用说明

定义一个 Component

Artifact 负责描述内容，Component API 负责把这份描述变成可复用的代码入口。先准备一个 Artifact 或 Artifact factory，再用 createFlamoComponentApi() 包装：

import { createFlamoComponentApi } from '@flamo/runtime';
import cardSource from './card.flamo.json' with { type: 'json' };

export const Card = createFlamoComponentApi(
  ({ title = 'Card' } = {}) => ({
    ...cardSource,
    metadata: {
      ...cardSource.metadata,
      name: title,
    },
  }),
);

factory 返回的仍是 Artifact 数据。createFlamoComponentApi() 会负责规范化它，并返回同时支持调用、创建、挂载和契约查询的 FlamoComponentApi。

如果 Artifact 内部声明了一个或多个组件边界，artifact.exports 记录这些公开边界，artifact.metadata.mainExport 指定默认边界。这里的 artifact.exports 是 Artifact 内的组件公开表，不要和 JavaScript 的 export 语法混淆。

导入并实例化

Component API 是 JavaScript 模块导出，可以像普通模块一样导入：

import { Card } from './Card.js';

// 只生成 Artifact，不启动运行态
const artifact = Card({ title: '账户卡片' });

// 使用 @flamo/runtime 的默认 Runtime 创建或挂载 Instance
const created = await Card.create({ title: '账户卡片' });
const mounted = await Card.mount('#preview', { title: '账户卡片' });

需要使用指定 Runtime 时，不调用 Component API 自带的 .create() / .mount()，而是先生成 Artifact，再交给目标 Runtime：

const props = { title: '账户卡片' };
const artifact = Card(props);
const instance = await runtime.create({ artifact, props });

// 或直接挂载
const mounted = await runtime.mount(container, artifact, { props });

runtime.create() 与 Card.create() 的区别

Card.create() 适合使用默认 Runtime 的组件消费代码；runtime.create() 适合编辑器、多画布或需要独立资源与实例注册表的宿主。使用自定义 Runtime 时，不要先调用 Card.create()，而应调用 Card(props) 取得 Artifact，再交给目标 Runtime。

导出边界

• 导出 Artifact：保存组件定义的数据，可用于传输、验证和版本化。
• 导出 Component API：导出 factory 与便捷方法，适合在 JavaScript/TypeScript 工程中复用。
• 导出 Instance 活引用：仅适合同一页面、同一 JavaScript realm 内的模块协作，必须由 owner 管理创建与销毁。
• 不把 Instance 当作发布物：它不能序列化、跨环境传输或供其他项目再次实例化；跨环境复用必须由目标 Runtime 根据 Artifact 或 Component API 重新创建。