@mica-js/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DigitalEcho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @mica-js/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Device / Widget 作者 API、DDL 类型准备及 CLI 双文件构建。每个条目独立发布；一个工程可以维护多个条目。Vite 由 SDK 内部管理，作者使用 `mica build` 与 `mica prepare`。
+
+## 工程与产物
+
+源码使用固定入口：
+
+```text
+src/
+  devices/<id>/
+    device.json
+    model.ddl
+    index.ts            # 可选，省略时生成最小同步工厂
+  widgets/<id>/
+    widget.json
+    index.ts
+  shared/
+```
+
+构建结果只有以下文件，不生成归档、包清单或独立资源：
+
+```text
+dist/
+  devices/<id>/device.json
+  devices/<id>/device.js
+  widgets/<id>/widget.json
+  widgets/<id>/widget.js
+```
+
+目录名与元数据 `id` 一致，字符范围为字母、数字、中划线。身份与版本由条目 JSON 的 `id`、`version` 表达。Device JS 具名导出 `model`（共享 DeviceIR）与 `create`（同步适配器工厂）；Widget JS 默认导出同步实例工厂。每个 JS 独立打包依赖，宿主不解析 npm 导入或共享 chunk。模块装载及执行隔离由宿主负责。
+
+## 项目配置与命令
+
+工程根目录必须包含 `mica.config.ts`，空配置使用全部默认约定：
+
+```typescript
+import { defineConfig } from '@mica-js/sdk/config';
+
+export default defineConfig({});
+```
+
+CLI 从当前目录向上查找最近的 `mica.config.ts`，该文件所在目录就是项目根目录；`--root` 改变查找起点，`--config` 指定配置文件（相对于查找起点）。未找到配置时报告错误。IDE 可以仅通过文件是否存在识别项目；配置是可执行 TypeScript，只应在受信任的工程中加载。
+
+可选配置示例：
+
+```typescript
+export default defineConfig({
+  sourceDir: 'src',
+  outDir: 'dist',
+  base: '/components/',
+  alias: { '@': './src' },
+});
+```
+
+源码、输出及别名路径相对于项目根目录解析；输出目录必须与源码目录分离，避免构建清理覆盖源码。配置只接受 SDK 定义的字段，Vite 是内部构建引擎；作者不需要安装 Vite 或维护 `vite.config.ts`。
+
+```shell
+mica build
+mica prepare
+mica prepare --watch
+mica build --config ./mica.config.ts
+```
+
+`mica build` 准备 DDL 类型、校验元数据并独立打包每个条目，将双文件产物写入 `outDir`。预览宿主自行提供这些静态产物；组件源码变更后重新运行构建。
+
+内部打包复用 Vite 的 TS 与资源转换及别名解析。`?raw` 资源成为字符串，`?url` 等标准资源导入在库构建中内联。样式表等会额外输出文件的入口会构建失败；运行期模块导入、`import.meta` 引用同样拒绝。资源如何解码和使用由实现与宿主允许的 API 决定。
+
+## DDL 类型
+
+```typescript
+import type { Factory } from './model.ddl';
+
+const create: Factory = (ctx) => ({
+  sync(batch) {
+    // ctx.props、ctx.inputs、ctx.memory 和 batch.outputs 按该 DDL 精确投影。
+  },
+  dispose() {},
+});
+
+export default create;
+```
+
+TypeScript 配置需要 `allowArbitraryExtensions: true`、`moduleResolution: "Bundler"`（或其他支持该扩展声明的解析模式）。`mica prepare` 在每份 DDL 旁生成 `model.d.ddl.ts`，提供 `Props`、`PropertyInput`、`Inputs`、`Memory`、`Outputs`、`Context`、`Batch`、`Adapter`、`Factory` 别名。声明仅供编译期使用；`import type` 不产生 DDL 运行时导入。建议忽略 `**/*.d.ddl.ts`。
+
+```shell
+mica prepare
+mica prepare --watch
+mica prepare --root . --source-dir src
+```
+
+`mica build` 也运行类型准备。独立 `tsc` 前仍应先运行 `mica prepare`。失败时只清理带 SDK 生成标记的过期声明；作者维护的文件受到保护。所有工厂与适配器钩子遵循新版仿真规范的同步返回、数据所有权和实例生命周期合同。
+
+## JSON 元数据
+
+JSON 由作者完整维护，构建器只校验 JSON 自身结构以及 ID 与目录名；不从 DDL 提取属性或引脚，不做 JSON 与 DDL 的一致性检查，也不向发布 JSON 注入默认值。元数据的格式化可能改变空白。
+
+`@mica-js/sdk/metadata` 导出 `deviceMetadataSchema`、`widgetMetadataSchema`、`validateMetadata` 以及相应 TypeScript 类型。元数据不含 `formatVersion`、`icon`、`category`。字节属性的 JSON 默认编码尚未定义，因此 `bytes` 属性暂不接受 JSON `default`。
+
+`symbol` 描述静态矢量符号、引脚连接点和位号位置。X 向右、Y 向下，角度单位为度，正扫角顺时针。使用逻辑单位，建议 10 单位为默认网格间距；颜色使用主题角色。JSON 校验不证明符号引脚或属性与 DDL 一致。
+
+## 公开入口
+
+| 入口                    | 内容                                                               |
+| ----------------------- | ------------------------------------------------------------------ |
+| `@mica-js/sdk`          | `createDeviceLibrary`、`createBoard`、`SimulationError` 及宿主类型 |
+| `@mica-js/sdk/device`   | 器件上下文、工厂、批次、通道、话题与 JIT 类型                      |
+| `@mica-js/sdk/widget`   | Widget 工厂、上下文、绘制、输入、资源与音频类型                    |
+| `@mica-js/sdk/model`    | 共享 IR、Builder 与校验                                            |
+| `@mica-js/sdk/ddl`      | DDL 编译与类型投影                                                 |
+| `@mica-js/sdk/metadata` | Device / Widget Schema、类型与校验                                 |
+| `@mica-js/sdk/config`   | `defineConfig()`、`MicaConfig` 及项目配置发现与加载                |
+| `@mica-js/sdk/prepare`  | `prepare()`、声明监听工具                                          |
+
+浏览器作者入口不会引入 Vite 或 Node 构建依赖。最小工程见 [templates/basic](./templates/basic/)，使用前将其作为独立工程安装依赖。

package/dist/build/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/** Writable half of `process.stdout` / `process.stderr`, so tests can capture CLI output. */
+export interface CliStreams {
+    readonly out: {
+        write(chunk: string): unknown;
+    };
+    readonly err: {
+        write(chunk: string): unknown;
+    };
+}
+export interface CliArguments {
+    readonly command: 'prepare' | 'build';
+    readonly help: boolean;
+    readonly watch: boolean;
+    readonly root: string;
+    readonly config?: string;
+    readonly sourceDir?: string;
+}
+/** Parses SDK commands without reading or executing project configuration. */
+export declare function parseCliArguments(argv: readonly string[]): CliArguments;
+/** Runs one SDK command and returns its exit code. */
+export declare function runCli(argv: readonly string[], streams?: CliStreams): Promise<number>;

package/dist/build/cli.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { loadProjectConfig } from './config.js';
+import { relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { prepare, watchDevices } from './prepare.js';
+const USAGE = `Usage: mica <command> [options]
+
+Commands:
+  build              build standalone Device / Widget artifacts
+  prepare            generate model.d.ddl.ts declarations
+
+A mica.config.ts file identifies the project; it is discovered upwards from --root.
+
+Options:
+  --config <file>     explicit mica.config.ts, relative to --root
+  --root <dir>        discovery directory (default: current directory)
+  --source-dir <dir>  override the configured source directory
+  --watch            watch DDL definitions (prepare only)
+  -h, --help         show this help`;
+/** Parses SDK commands without reading or executing project configuration. */
+export function parseCliArguments(argv) {
+    // A bare `mica` only explains the command instead of guessing a package root.
+    let help = argv.length === 0;
+    let watch = false;
+    let root = process.cwd();
+    let sourceDir;
+    let config;
+    let command = 'prepare';
+    let index = 0;
+    const first = argv[0];
+    if (first !== undefined && !first.startsWith('-')) {
+        if (first !== 'prepare' && first !== 'build')
+            throw new Error(`Unknown command '${first}'.`);
+        command = first;
+        index = 1;
+    }
+    for (; index < argv.length; index++) {
+        const argument = argv[index];
+        const separator = argument.indexOf('=');
+        const flag = separator === -1 ? argument : argument.slice(0, separator);
+        const inline = separator === -1 ? undefined : argument.slice(separator + 1);
+        const flagValue = () => {
+            if (inline !== undefined) {
+                if (!inline)
+                    throw new Error(`Missing value for ${flag}.`);
+                return inline;
+            }
+            const next = argv[++index];
+            if (next === undefined || next.startsWith('-'))
+                throw new Error(`Missing value for ${flag}.`);
+            return next;
+        };
+        const bare = () => {
+            if (inline !== undefined)
+                throw new Error(`${flag} does not take a value.`);
+        };
+        switch (flag) {
+            case '-h':
+            case '--help':
+                bare();
+                help = true;
+                break;
+            case '--watch':
+                bare();
+                watch = true;
+                break;
+            case '--root':
+                root = resolve(flagValue());
+                break;
+            case '--source-dir':
+                sourceDir = flagValue();
+                break;
+            case '--config':
+                config = flagValue();
+                break;
+            default:
+                throw new Error(`Unknown argument '${argument}'.`);
+        }
+    }
+    if (watch && command !== 'prepare')
+        throw new Error('--watch is only supported by mica prepare.');
+    return {
+        command,
+        help,
+        watch,
+        root: resolve(root),
+        ...(sourceDir === undefined ? {} : { sourceDir }),
+        ...(config === undefined ? {} : { config }),
+    };
+}
+/** Runs one SDK command and returns its exit code. */
+export async function runCli(argv, streams = { out: process.stdout, err: process.stderr }) {
+    let options;
+    try {
+        options = parseCliArguments(argv);
+    }
+    catch (error) {
+        streams.err.write(`mica: ${messageOf(error)}\n\n${USAGE}\n`);
+        return 1;
+    }
+    if (options.help) {
+        streams.out.write(`${USAGE}\n`);
+        return 0;
+    }
+    try {
+        const project = await loadProjectConfig({
+            root: options.root,
+            ...(options.config === undefined ? {} : { config: options.config }),
+        });
+        const configured = {
+            ...project,
+            config: {
+                ...project.config,
+                ...(options.sourceDir === undefined ? {} : { sourceDir: options.sourceDir }),
+            },
+        };
+        if (options.command === 'build') {
+            const { buildProject } = await import('./project.js');
+            await buildProject(configured);
+            streams.out.write('mica build: complete\n');
+            return 0;
+        }
+        const preparation = { root: project.root, sourceDir: configured.config.sourceDir ?? 'src' };
+        return options.watch
+            ? await watchLoop(preparation, streams)
+            : await prepareOnce(preparation, streams);
+    }
+    catch (error) {
+        streams.err.write(`mica ${options.command}: ${messageOf(error)}\n`);
+        return 1;
+    }
+}
+async function prepareOnce(options, streams) {
+    try {
+        report(await prepare({ root: options.root, sourceDir: options.sourceDir }), streams);
+        return 0;
+    }
+    catch (error) {
+        streams.err.write(`mica prepare: ${messageOf(error)}\n`);
+        return 1;
+    }
+}
+function watchLoop(options, streams) {
+    return new Promise((settle) => {
+        let watcher;
+        try {
+            watcher = watchDevices({
+                root: options.root,
+                sourceDir: options.sourceDir,
+                onPrepare: (files) => report(files, streams),
+                onError: (error) => streams.err.write(`mica prepare: ${messageOf(error)}\n`),
+            });
+        }
+        catch (error) {
+            streams.err.write(`mica prepare: ${messageOf(error)}\n`);
+            settle(1);
+            return;
+        }
+        let closing = false;
+        const stop = () => {
+            // A second signal must not wait for a regeneration that may already be stuck.
+            if (closing)
+                process.exit(0);
+            closing = true;
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+            void watcher.dispose().then(() => settle(0), (error) => {
+                streams.err.write(`mica prepare: ${messageOf(error)}\n`);
+                settle(1);
+            });
+        };
+        process.on('SIGINT', stop);
+        process.on('SIGTERM', stop);
+        void watcher.ready.then(() => {
+            if (closing)
+                return;
+            const sourceRoot = resolve(options.root, options.sourceDir);
+            streams.out.write(`mica prepare: watching ${sourceRoot} for changes\n`);
+        });
+    });
+}
+function report(files, streams) {
+    for (const file of files)
+        streams.out.write(`${relative(process.cwd(), file)}\n`);
+    if (!files.length) {
+        streams.out.write('mica prepare: no device definitions found\n');
+        return;
+    }
+    const plural = files.length === 1 ? 'declaration' : 'declarations';
+    streams.out.write(`mica prepare: ${files.length} device ${plural} ready\n`);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isMainModule() {
+    const entry = process.argv[1];
+    if (entry === undefined)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule()) {
+    void runCli(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}

package/dist/build/config.d.ts

@@ -0,0 +1,16 @@
+export interface MicaConfig {
+    readonly sourceDir?: string;
+    readonly outDir?: string;
+    readonly base?: string;
+    readonly alias?: Readonly<Record<string, string>>;
+}
+export declare function defineConfig(config: MicaConfig): MicaConfig;
+export declare function findProjectConfig(root?: string, config?: string): Promise<string>;
+export declare function loadProjectConfig(options?: {
+    root?: string;
+    config?: string;
+}): Promise<{
+    root: string;
+    configFile: string;
+    config: MicaConfig;
+}>;

package/dist/build/config.js

@@ -0,0 +1,92 @@
+import { stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { loadConfigFromFile } from 'vite';
+export function defineConfig(config) {
+    return config;
+}
+const CONFIG_FILE = 'mica.config.ts';
+async function isFile(file) {
+    try {
+        return (await stat(file)).isFile();
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return false;
+        throw error;
+    }
+}
+export async function findProjectConfig(root = process.cwd(), config) {
+    const startingRoot = resolve(root);
+    if (config !== undefined) {
+        const file = resolve(startingRoot, config);
+        if (basename(file) !== CONFIG_FILE) {
+            throw new Error(`Mica project config must be named ${CONFIG_FILE}: ${file}`);
+        }
+        if (!(await isFile(file))) {
+            throw new Error(`Mica project config is not a file or does not exist: ${file}`);
+        }
+        return file;
+    }
+    let directory = startingRoot;
+    while (true) {
+        const file = join(directory, CONFIG_FILE);
+        if (await isFile(file))
+            return file;
+        const parent = dirname(directory);
+        if (parent === directory) {
+            throw new Error(`No ${CONFIG_FILE} project marker found from ${startingRoot} upward`);
+        }
+        directory = parent;
+    }
+}
+function invalid(field, expected) {
+    throw new Error(`Invalid Mica config ${field}: expected ${expected}`);
+}
+function plainObject(value, field) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+        return invalid(field, 'a plain object');
+    }
+    return value;
+}
+function knownKeys(value, keys, field) {
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== 'string' || !keys.includes(key)) {
+            invalid(`${field}.${String(key)}`, 'a supported config key');
+        }
+    }
+}
+function validateConfig(value) {
+    const config = plainObject(value, 'default export');
+    knownKeys(config, ['sourceDir', 'outDir', 'base', 'alias'], 'default export');
+    for (const field of ['sourceDir', 'outDir', 'base']) {
+        const entry = config[field];
+        if (entry !== undefined && (typeof entry !== 'string' || entry.trim().length === 0)) {
+            invalid(field, 'a nonempty string');
+        }
+    }
+    if (config.alias !== undefined) {
+        const aliases = plainObject(config.alias, 'alias');
+        for (const key of Reflect.ownKeys(aliases)) {
+            if (typeof key !== 'string' || typeof aliases[key] !== 'string') {
+                invalid(`alias.${String(key)}`, 'a string');
+            }
+        }
+    }
+    return {
+        ...config,
+        sourceDir: config.sourceDir ?? 'src',
+        outDir: config.outDir ?? 'dist',
+        base: config.base ?? '/',
+    };
+}
+export async function loadProjectConfig(options = {}) {
+    const configFile = await findProjectConfig(options.root, options.config);
+    const root = dirname(configFile);
+    const loaded = await loadConfigFromFile({ command: 'build', mode: 'production' }, configFile, root, 'silent', undefined, 'bundle');
+    if (!loaded)
+        throw new Error(`Unable to load Mica project config: ${configFile}`);
+    return { root, configFile, config: validateConfig(loaded.config) };
+}

package/dist/build/content.d.ts

@@ -0,0 +1,14 @@
+import { type AliasOptions } from 'vite';
+export interface ContentBuildOptions {
+    readonly root: string;
+    readonly sourceDir?: string;
+    readonly aliases?: AliasOptions;
+    readonly minify?: boolean;
+}
+export interface ContentFile {
+    readonly fileName: string;
+    readonly source: string;
+}
+export declare function modelExpression(value: unknown): string;
+/** Builds each registration separately so no shared chunk or runtime import escapes. */
+export declare function buildContent(options: ContentBuildOptions): Promise<readonly ContentFile[]>;

package/dist/build/content.js

@@ -0,0 +1,159 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { isBuiltin } from 'node:module';
+import { compileDDL } from '@mica-js/ddl';
+import { build, normalizePath } from 'vite';
+import { parseAst } from 'rolldown/parseAst';
+import { validateMetadata } from '../metadata/index.js';
+function assertSelfContained(code, label) {
+    const visit = (node) => {
+        if (node === null || typeof node !== 'object')
+            return;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                visit(child);
+            return;
+        }
+        const record = node;
+        if (record.type === 'ImportDeclaration' ||
+            record.type === 'ImportExpression' ||
+            ((record.type === 'ExportNamedDeclaration' || record.type === 'ExportAllDeclaration') &&
+                record.source) ||
+            (record.type === 'MetaProperty' && record.meta.name === 'import'))
+            throw new Error(`${label}: implementation contains a runtime module or asset reference`);
+        for (const child of Object.values(record))
+            visit(child);
+    };
+    visit(parseAst(code));
+}
+async function exists(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+// JSON alone loses the IR's non-finite numbers and negative zero.
+export function modelExpression(value) {
+    if (typeof value === 'number') {
+        if (Number.isNaN(value))
+            return 'NaN';
+        if (value === Infinity)
+            return 'Infinity';
+        if (value === -Infinity)
+            return '-Infinity';
+        return Object.is(value, -0) ? '-0' : String(value);
+    }
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (value instanceof Uint8Array)
+        return `new Uint8Array(${modelExpression(Array.from(value))})`;
+    if (Array.isArray(value))
+        return `[${value.map(modelExpression).join(',')}]`;
+    if (typeof value === 'object')
+        return `{${Object.entries(value)
+            .map(([key, item]) => `${key === '__proto__' ? '["__proto__"]' : JSON.stringify(key)}:${modelExpression(item)}`)
+            .join(',')}}`;
+    throw new TypeError(`Cannot serialize model value: ${typeof value}`);
+}
+/** Builds each registration separately so no shared chunk or runtime import escapes. */
+export async function buildContent(options) {
+    const files = [];
+    for (const kind of ['device', 'widget']) {
+        const category = `${kind}s`;
+        const directory = resolve(options.root, options.sourceDir ?? 'src', category);
+        const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        });
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory())
+                continue;
+            const id = entry.name;
+            const base = resolve(directory, id);
+            const jsonPath = resolve(base, `${kind}.json`);
+            const metadata = JSON.parse(await readFile(jsonPath, 'utf8'));
+            validateMetadata(metadata, kind, id);
+            let source;
+            const entryId = 'virtual:mica-content-entry';
+            if (kind === 'device') {
+                const ddlPath = resolve(base, 'model.ddl');
+                const model = await compileDDL(await readFile(ddlPath, 'utf8'), {
+                    uri: `mica:devices/${id}/model.ddl`,
+                });
+                const adapter = resolve(base, 'index.ts');
+                source = `export const model = ${modelExpression(model)};\n`;
+                source += (await exists(adapter))
+                    ? `export { default as create } from ${JSON.stringify(normalizePath(adapter))};\n`
+                    : 'export function create() { return { sync() {}, dispose() {} }; }\n';
+            }
+            else {
+                source = `export { default } from ${JSON.stringify(normalizePath(resolve(base, 'index.ts')))};\n`;
+            }
+            const bundled = await build({
+                configFile: false,
+                root: options.root,
+                publicDir: false,
+                logLevel: 'silent',
+                resolve: {
+                    ...(options.aliases === undefined ? {} : { alias: options.aliases }),
+                    conditions: ['source', 'module', 'browser', 'production'],
+                },
+                plugins: [
+                    {
+                        name: 'mica:content-entry',
+                        enforce: 'pre',
+                        resolveId(id) {
+                            if (isBuiltin(id))
+                                throw new Error(`Node built-ins are unavailable in content modules: ${id}`);
+                            if (id === entryId)
+                                return '\0' + entryId;
+                        },
+                        load(id) {
+                            if (id === '\0' + entryId)
+                                return source;
+                        },
+                    },
+                ],
+                build: {
+                    write: false,
+                    target: 'es2022',
+                    sourcemap: false,
+                    minify: options.minify ?? false,
+                    lib: { entry: entryId, formats: ['es'], fileName: () => `${kind}.js`, cssFileName: kind },
+                    rolldownOptions: {
+                        input: entryId,
+                        output: { codeSplitting: false },
+                        onwarn(warning, warn) {
+                            if (warning.code === 'UNRESOLVED_IMPORT')
+                                throw new Error(warning.message);
+                            warn(warning);
+                        },
+                    },
+                },
+            });
+            if ('close' in bundled)
+                throw new Error('Watch builds are not supported inside a content build');
+            const outputs = (Array.isArray(bundled) ? bundled : [bundled]).flatMap((result) => result.output);
+            const chunk = outputs[0];
+            if (outputs.length !== 1 ||
+                chunk?.type !== 'chunk' ||
+                chunk.imports.length ||
+                chunk.dynamicImports.some((name) => name !== chunk.fileName))
+                throw new Error(`${category}/${id}: implementation must produce exactly one self-contained JavaScript module (${outputs.map((item) => item.fileName).join(', ')}; imports: ${chunk?.type === 'chunk' ? [...chunk.imports, ...chunk.dynamicImports].join(', ') : 'n/a'})`);
+            assertSelfContained(chunk.code, `${category}/${id}`);
+            const expectedExports = kind === 'device' ? ['create', 'model'] : ['default'];
+            if (expectedExports.some((name) => !chunk.exports.includes(name)))
+                throw new Error(`${category}/${id}: missing implementation export`);
+            files.push({
+                fileName: `${category}/${id}/${kind}.json`,
+                source: `${JSON.stringify(metadata, null, 2)}\n`,
+            }, { fileName: `${category}/${id}/${kind}.js`, source: chunk.code });
+        }
+    }
+    return files;
+}