@mica-js/editor 0.1.0 → 0.2.0

package/README.md

@@ -84,7 +84,11 @@ await editor.executeCommand('schematic.undo');
 
 可选 `voltageReferences: { VCC: 5 }` 为同名原理图网络配置固定板级电压，接地网络保持 0 V。电源标记只命名网络，电压由该选项显式提供。
 
-运行会话负责唯一帧调度器，以 25 ms 固定步长推进仿真；暂停时继续刷新 widget 而不推进仿真时间。话题数据通过两个 guest 之间的直连 RPC 通道传递，editor 配置绑定，不在 UI 线程转发 payload。位置、旋转和层级只属于编辑器；改变执行输入时先建立候选会话，全部准备成功后替换旧会话。文档与历史在准备失败时保持原值。
+Canvas Editor 自动为 Widget 音频创建并管理 `AudioContext`，无需宿主传入音频对象。`canvas.run` 恢复播放；`canvas.pause`、重置和切回编辑模式会暂停音频，单步保持静音。浏览器可能要求用户手势：建议从点击事件直接调用运行命令；自动运行被阻止时，在运行中的画布内点击或按键可再次解锁。浏览器不支持 Web Audio 时仍可使用编辑器，只是不播放声音；音频初始化或恢复错误通过 `onDidError` 报告。替换运行时或销毁编辑器会释放对应音频上下文。
+
+工厂选项 `stepMs` 同时设置每步仿真时长与目标帧周期，单位为毫秒，默认 `20`（50 FPS）；例如 `createCanvasEditor({ ...options, stepMs: 10 })` 对应每步 10 ms、目标 100 FPS。值必须为有限正数，转换后至少为 1 ps，且不得超过运行时时间范围。单步命令也使用此步长，创建后不能动态修改。
+
+运行会话负责唯一帧调度器，默认以 20 ms 固定步长推进仿真，目标帧率为 50 FPS。调度按单调时钟的绝对时间目标对齐，扣除执行耗时；单步过慢时跳过错过的时隙，不并发、不积压补步，因此过载时仿真慢于实时。暂停时仍按该节奏刷新 widget 而不推进仿真时间。话题数据通过两个 guest 之间的直连 RPC 通道传递，editor 配置绑定，不在 UI 线程转发 payload。位置、旋转和层级只属于编辑器；改变执行输入时先建立候选会话，全部准备成功后替换旧会话。文档与历史在准备失败时保持原值。
 
 library 的代码只在 sandbox 中执行，资源由 editor 通过只读文件系统预先读取。关闭 editor 会取消时钟、移除视图，并释放内部运行实例、RPC、bitmap 和 sandbox；外部 provider 保留宿主所有权。
 

package/dist/index.d.ts

@@ -128,6 +128,8 @@ export declare interface ICanvasEditorOptions {
     readonly fileSystem: IFileSystemProvider_2;
     readonly deviceLibrary: IDeviceLibrary_2;
     readonly widgetLibrary: IWidgetLibrary_2;
+    /** Simulation step and target frame period in milliseconds; defaults to 20. */
+    readonly stepMs?: number;
     readonly readOnly?: boolean;
     /** Fixed board voltages by exact schematic net name; ignored without a schematic. Ground stays zero. */
     readonly voltageReferences?: Readonly<Record<string, number>>;

package/dist/index.js

@@ -5529,22 +5529,33 @@ var CanvasRuntimeFactory = class {
 		let widgetWorker;
 		let simulation;
 		let widgets;
+		let audioContext;
 		try {
 			deviceWorker = createSimulationRuntimeGuestSandbox({ container });
 			simulation = await createSimulationRuntimeFromWorker(deviceWorker, { topicPort: channel.port1 });
 			widgetWorker = createWidgetHostGuestSandbox({ container });
-			widgets = createWidgetRuntime(await createWidgetSandboxFromWorker(widgetWorker, {
+			const sandbox = await createWidgetSandboxFromWorker(widgetWorker, {
 				container,
 				devicePort: channel.port2
-			}));
+			});
+			if (typeof globalThis.AudioContext === "function") audioContext = new AudioContext();
+			widgets = createWidgetRuntime(sandbox, { ...audioContext === void 0 ? {} : { audio: { context: audioContext } } });
+			widgets.audio.suspend();
 			const ownedSimulation = simulation;
 			const ownedWidgets = widgets;
 			let disposal;
 			return {
 				simulation,
 				widgets,
+				async resumeAudio() {
+					if (!disposal && audioContext?.state === "suspended") await audioContext.resume();
+				},
 				dispose() {
-					return disposal ??= Promise.allSettled([ownedWidgets.dispose(), ownedSimulation.dispose()]).then((results) => {
+					return disposal ??= Promise.allSettled([
+						ownedWidgets.dispose(),
+						ownedSimulation.dispose(),
+						audioContext?.close()
+					]).then((results) => {
 						const errors = results.filter((result) => result.status === "rejected").map((result) => result.reason);
 						if (errors.length) throw new AggregateError(errors, "Canvas runtimes failed to dispose.");
 					});
@@ -5553,7 +5564,11 @@ var CanvasRuntimeFactory = class {
 		} catch (error) {
 			channel.port1.close();
 			channel.port2.close();
-			await Promise.allSettled([widgets?.dispose() ?? widgetWorker?.terminate("Canvas initialization failed"), simulation?.dispose() ?? deviceWorker?.terminate("Canvas initialization failed")]);
+			await Promise.allSettled([
+				widgets?.dispose() ?? widgetWorker?.terminate("Canvas initialization failed"),
+				simulation?.dispose() ?? deviceWorker?.terminate("Canvas initialization failed"),
+				audioContext?.close()
+			]);
 			throw error;
 		}
 	}
@@ -5623,16 +5638,31 @@ var CanvasSession = class CanvasSession {
 	#simTime = timePs(0);
 	#running = false;
 	#timer;
+	#nextFrame;
 	#disposed = false;
 	#queue = Promise.resolve();
 	#disposal;
-	#step = toTimePs(25, "ms");
+	#frameMs;
+	#step;
+	#unlockAudio = () => {
+		const active = this.#active;
+		if (this.#disposed || !this.#running || !active) return;
+		active.runtimes.resumeAudio().catch((error) => {
+			if (!this.#disposed && this.#active === active) this.#errors.fire(error);
+		});
+	};
 	constructor(configuration, files, devices, widgets, factory) {
 		this.configuration = configuration;
 		this.files = files;
 		this.devices = devices;
 		this.widgets = widgets;
 		this.factory = factory;
+		this.#frameMs = configuration.stepMs ?? 20;
+		if (!Number.isFinite(this.#frameMs) || this.#frameMs <= 0) throw new Error("stepMs must be a positive finite number.");
+		this.#step = toTimePs(this.#frameMs, "ms");
+		if (this.#step <= 0) throw new Error("stepMs must represent at least one picosecond.");
+		configuration.container.addEventListener("pointerdown", this.#unlockAudio, true);
+		configuration.container.addEventListener("keydown", this.#unlockAudio, true);
 	}
 	get mode() {
 		return this.#mode;
@@ -5701,12 +5731,15 @@ var CanvasSession = class CanvasSession {
 		if (this.#mode !== "simulation") throw new Error("Switch to simulation mode before running.");
 		if (this.#running) return;
 		this.#running = true;
+		this.#active?.runtimes.widgets.audio.resume();
+		this.#unlockAudio();
 		this.#changes.fire();
 		this.#schedule();
 	}
 	pause() {
 		if (!this.#running) return;
 		this.#running = false;
+		this.#active?.runtimes.widgets.audio.suspend();
 		this.#changes.fire();
 	}
 	step() {
@@ -5722,9 +5755,12 @@ var CanvasSession = class CanvasSession {
 	dispose() {
 		if (this.#disposal) return this.#disposal;
 		this.#disposed = true;
+		this.configuration.container.removeEventListener("pointerdown", this.#unlockAudio, true);
+		this.configuration.container.removeEventListener("keydown", this.#unlockAudio, true);
 		this.pause();
 		if (this.#timer !== void 0) clearTimeout(this.#timer);
 		this.#timer = void 0;
+		this.#nextFrame = void 0;
 		this.#disposal = this.#queue.then(async () => {
 			const active = this.#active;
 			this.#active = void 0;
@@ -5814,13 +5850,18 @@ var CanvasSession = class CanvasSession {
 	}
 	#schedule() {
 		if (this.#disposed || !this.#active || this.#timer !== void 0) return;
+		const now = performance.now();
+		this.#nextFrame ??= now + this.#frameMs;
+		if (this.#nextFrame < now) this.#nextFrame += Math.ceil((now - this.#nextFrame) / this.#frameMs) * this.#frameMs;
 		this.#timer = setTimeout(() => {
 			this.#timer = void 0;
+			this.#nextFrame += this.#frameMs;
 			this.#enqueue(() => this.#advance(this.#running ? this.#step : timePs(0))).then(() => this.#schedule(), (error) => {
+				this.#nextFrame = void 0;
 				this.pause();
 				if (!this.#disposed) this.#errors.fire(error);
 			});
-		}, 25);
+		}, this.#nextFrame - now);
 	}
 	async #release(active) {
 		for (const subscription of active.subscriptions) subscription.dispose();
@@ -7094,6 +7135,7 @@ async function createCanvasEditor(options) {
 		uri,
 		...options.projectRoot === void 0 ? {} : { projectRoot: root },
 		container: options.container,
+		...options.stepMs === void 0 ? {} : { stepMs: options.stepMs },
 		...options.voltageReferences === void 0 ? {} : { voltageReferences: Object.freeze(structuredClone(options.voltageReferences)) }
 	});
 	services.set(ICommandService, new SyncDescriptor(Commands));