@dimina-kit/electron-deck 0.1.0-dev.20260610082053

package/dist/electron-deck-DfFKeFEC.js

@@ -0,0 +1,2295 @@
+import { n as DeckRemoteError, r as EventNotBoundError } from "./errors-NE2ig7L5.js";
+import { i as DeckChannel, t as BRIDGE_PROTOCOL_VERSION } from "./protocol-BJqo-vP2.js";
+import { i as createScope, r as createCompositor, t as createViewHandle } from "./view-handle-CR-yWNfr.js";
+import { randomUUID } from "node:crypto";
+//#region src/events.ts
+var internals = /* @__PURE__ */ new WeakMap();
+var HostEventImpl = class {
+	name;
+	constructor(name) {
+		this.name = name;
+		internals.set(this, {
+			publisher: null,
+			listeners: /* @__PURE__ */ new Set()
+		});
+	}
+	publish(payload) {
+		const it = internals.get(this);
+		if (!it || it.publisher === null) throw new EventNotBoundError(this.name);
+		it.publisher(payload);
+		for (const l of it.listeners) try {
+			l(payload);
+		} catch (e) {
+			console.error(`[electron-deck] HostEvent "${this.name}" listener threw:`, e);
+		}
+	}
+	on(listener) {
+		const it = internals.get(this);
+		if (!it) throw new TypeError(`HostEvent "${this.name}" has no internals — was it produced by defineEvent()?`);
+		it.listeners.add(listener);
+		return { dispose: () => {
+			it.listeners.delete(listener);
+		} };
+	}
+};
+function defineEvent(name) {
+	if (typeof name !== "string" || name.length === 0) throw new TypeError("defineEvent(name): name must be a non-empty string");
+	return new HostEventImpl(name);
+}
+/**
+* 校验 `ev` 是否真的来自 `defineEvent()`。判定方式是 WeakMap 身份，而非
+* `instanceof` —— 这样跨 vm.Context（同 module instance）也能工作。
+*
+* @internal
+*/
+function isHostEvent(ev) {
+	if (ev === null || typeof ev !== "object") return false;
+	return internals.has(ev);
+}
+/** @internal framework 在 Bind 阶段调；同实例重复 bind 覆盖前任 */
+function bindHostEvent(event, publisher) {
+	const it = internals.get(event);
+	if (!it) throw new TypeError("bindHostEvent: argument is not a HostEvent produced by defineEvent()");
+	it.publisher = publisher;
+}
+/** @internal framework 在 Cleanup 阶段调 */
+function unbindHostEvent(event) {
+	const it = internals.get(event);
+	if (it) {
+		it.publisher = null;
+		it.listeners.clear();
+	}
+}
+//#endregion
+//#region src/internal/event-bus.ts
+/**
+* Framework-internal event bus。
+*
+* 责任：
+* - `bindDeclaredEvents(events)`：在 Bind 阶段调；对每个声明的 HostEvent，调用
+*   framework binder，让该 event 的 `publish()` 走 bus。
+* - `publish(name, payload)`：通知 `subscribe(name, ...)` 注册的所有 listener。
+* - `subscribe(name, listener)`：返回 `Disposable`，dispose 后停止通知。
+* - `unbindAll()`：解绑所有 declared event publisher + 清空 subscribers。
+*
+* @internal
+*/
+var EventBus = class {
+	subscribers = /* @__PURE__ */ new Map();
+	allSubscribers = /* @__PURE__ */ new Set();
+	inFlight = /* @__PURE__ */ new Set();
+	boundEvents = [];
+	bindDeclaredEvents(events) {
+		for (const ev of events) {
+			bindHostEvent(ev, (payload) => this.publish(ev.name, payload));
+			this.boundEvents.push(ev);
+		}
+	}
+	publish(name, payload) {
+		if (this.inFlight.has(name)) {
+			console.error(`[electron-deck] reentrant publish on "${name}" dropped (listener republished the same event synchronously)`);
+			return;
+		}
+		this.inFlight.add(name);
+		try {
+			const subs = this.subscribers.get(name);
+			if (subs && subs.size > 0) {
+				const snapshot = Array.from(subs);
+				for (const l of snapshot) try {
+					l(payload);
+				} catch (e) {
+					console.error(`[electron-deck] subscriber for "${name}" threw:`, e);
+				}
+			}
+			if (this.allSubscribers.size > 0) {
+				const snapshot = Array.from(this.allSubscribers);
+				for (const l of snapshot) try {
+					l(name, payload);
+				} catch (e) {
+					console.error(`[electron-deck] catch-all subscriber threw on "${name}":`, e);
+				}
+			}
+		} finally {
+			this.inFlight.delete(name);
+		}
+	}
+	subscribe(name, listener) {
+		let subs = this.subscribers.get(name);
+		if (!subs) {
+			subs = /* @__PURE__ */ new Set();
+			this.subscribers.set(name, subs);
+		}
+		subs.add(listener);
+		const set = subs;
+		return { dispose: () => {
+			set.delete(listener);
+		} };
+	}
+	/**
+	* 订阅所有 channel 的 publish —— framework wire-transport 把 declared
+	* HostEvent.publish() 桥到 webContents.send 时用。
+	*/
+	subscribeAll(listener) {
+		this.allSubscribers.add(listener);
+		return { dispose: () => {
+			this.allSubscribers.delete(listener);
+		} };
+	}
+	unbindAll() {
+		for (const ev of this.boundEvents) unbindHostEvent(ev);
+		this.boundEvents = [];
+		this.subscribers.clear();
+		this.allSubscribers.clear();
+	}
+};
+//#endregion
+//#region src/internal/ipc-registry-memory.ts
+/**
+* In-memory `TypedIpcRegistry` impl —— Phase 2 不接真 Electron `ipcMain`，提
+* 供 main-process 同进程 `handle` / `on` / `send` / `invoke` 的 fake。
+*
+* - `handle` / `invoke` 与 `on` / `send` 是**独立 channel space**：send 只触
+*   发 on listener；invoke 只调 handle handler；同 channel 名互不影响。
+* - audience / validator option Phase 2 不强制，仅 accept；Phase 3 接 trusted
+*   sender set 时再实施。
+*
+* @internal
+*/
+var InMemoryTypedIpcRegistry = class {
+	handlers = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Map();
+	handle(channel, handler, _options) {
+		if (this.handlers.has(channel)) throw new Error(`channel already handled: "${channel}"`);
+		const cast = handler;
+		this.handlers.set(channel, cast);
+		return { dispose: () => {
+			if (this.handlers.get(channel) === cast) this.handlers.delete(channel);
+		} };
+	}
+	on(channel, listener) {
+		let set = this.listeners.get(channel);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.listeners.set(channel, set);
+		}
+		const cast = listener;
+		set.add(cast);
+		const ref = set;
+		return { dispose: () => {
+			ref.delete(cast);
+		} };
+	}
+	send(_target, channel, payload) {
+		const set = this.listeners.get(channel);
+		if (!set) return;
+		const snapshot = Array.from(set);
+		for (const l of snapshot) try {
+			l(payload);
+		} catch (e) {
+			console.error(`[electron-deck] ipc on "${channel}" listener threw:`, e);
+		}
+	}
+	/** @internal main-internal helper used by Phase 2 setup tests / framework */
+	async invoke(channel, ...args) {
+		const handler = this.handlers.get(channel);
+		if (!handler) throw new Error(`no handler for channel: "${channel}"`);
+		return await handler(...args);
+	}
+};
+//#endregion
+//#region src/internal/trust-set.ts
+function createTrustSet() {
+	const refs = /* @__PURE__ */ new Map();
+	return {
+		admit(wc, owner) {
+			const cur = refs.get(wc) ?? 0;
+			refs.set(wc, cur + 1);
+			let disposed = false;
+			const lease = owner.own({ dispose: () => {
+				if (disposed) return;
+				disposed = true;
+				const c = refs.get(wc);
+				if (c === void 0) return;
+				if (c <= 1) refs.delete(wc);
+				else refs.set(wc, c - 1);
+			} });
+			let released = false;
+			return { dispose: () => {
+				if (released) return;
+				released = true;
+				lease.dispose();
+			} };
+		},
+		isTrusted(id) {
+			for (const wc of refs.keys()) if (wc.id === id) return true;
+			return false;
+		},
+		snapshot() {
+			return Array.from(refs.keys());
+		}
+	};
+}
+//#endregion
+//#region src/internal/lifecycle-manager.ts
+var ORDER = [
+	"init",
+	"bind",
+	"setup",
+	"ready",
+	"drain",
+	"cleanup",
+	"destroy",
+	"quit"
+];
+var LifecyclePhaseError = class extends Error {
+	from;
+	to;
+	constructor(from, to) {
+		super(`Illegal lifecycle transition: ${from} → ${to}`);
+		this.name = "LifecyclePhaseError";
+		this.from = from;
+		this.to = to;
+	}
+};
+function phaseOrder(p) {
+	const idx = ORDER.indexOf(p);
+	if (idx === -1) throw new Error(`unknown lifecycle phase: ${String(p)}`);
+	return idx;
+}
+var LifecycleManager = class {
+	current = "init";
+	enter(to) {
+		const fromOrder = phaseOrder(this.current);
+		if (phaseOrder(to) !== fromOrder + 1) throw new LifecyclePhaseError(this.current, to);
+		this.current = to;
+	}
+	assertAtLeast(p) {
+		if (phaseOrder(this.current) < phaseOrder(p)) throw new Error(`lifecycle assertion failed: current=${this.current}, required >= ${p}`);
+	}
+	/**
+	* Abnormal-path setter：setup throw / 紧急 shutdown 跳过中间 phase 直达
+	* 指定 teardown phase。不做顺序校验，仅 framework 内部使用。
+	*
+	* @internal
+	*/
+	_force(to) {
+		this.current = to;
+	}
+};
+//#endregion
+//#region src/internal/resource-registry.ts
+var ResourceRegistryImpl = class {
+	entries = [];
+	nextId = 1;
+	allDisposed = false;
+	add(d) {
+		const underlying = typeof d === "function" ? d : () => d.dispose();
+		if (this.allDisposed) {
+			runQuietly(underlying);
+			return { dispose: () => {} };
+		}
+		const id = this.nextId++;
+		const entry = {
+			id,
+			dispose: underlying
+		};
+		this.entries.push(entry);
+		let disposedThis = false;
+		return { dispose: async () => {
+			if (disposedThis) return;
+			disposedThis = true;
+			const idx = this.entries.findIndex((e) => e.id === id);
+			if (idx !== -1) this.entries.splice(idx, 1);
+			await underlying();
+		} };
+	}
+	async disposeAll() {
+		if (this.allDisposed) return;
+		this.allDisposed = true;
+		const toDispose = this.entries.slice().reverse();
+		this.entries = [];
+		const errors = [];
+		for (const entry of toDispose) try {
+			await entry.dispose();
+		} catch (e) {
+			errors.push(e);
+		}
+		if (errors.length > 0) throw new AggregateError(errors, `ResourceRegistry.disposeAll: ${errors.length} dispose(s) failed`);
+	}
+};
+function runQuietly(fn) {
+	try {
+		const r = fn();
+		if (r && typeof r.then === "function") return r.catch(() => {});
+		return;
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/host/capability.ts
+function createCapabilityRegistry() {
+	const entries = /* @__PURE__ */ new Set();
+	return {
+		policy: { allows(senderId, name) {
+			for (const e of entries) if (e.grant.senderId === senderId && e.grant.commands.has(name)) return true;
+			return false;
+		} },
+		issue(grant) {
+			let revoked = false;
+			const off1 = grant.senderScope.on("reset", () => revoke());
+			const off2 = grant.senderScope.on("closed", () => revoke());
+			function revoke() {
+				if (revoked) return;
+				revoked = true;
+				entries.delete(entry);
+				off1.dispose();
+				off2.dispose();
+			}
+			const entry = {
+				grant,
+				revoke
+			};
+			entries.add(entry);
+			return { dispose: revoke };
+		},
+		revokeBySenderId(senderId) {
+			const matching = [];
+			for (const e of entries) if (e.grant.senderId === senderId) matching.push(e);
+			for (const e of matching) e.revoke();
+		}
+	};
+}
+//#endregion
+//#region src/internal/wire-transport.ts
+/**
+* WireTransport — main 端的真 Electron wire 桥接（Phase 3b）。
+*
+* 责任：
+* - 在 `ipcMain.handle('__electron-deck:invoke')` / `'__electron-deck:probe'` 上路由
+*   webview → main 的 RPC 请求，按 `senderPolicy` gating + kind 派发到 host /
+*   simulator handler，序列化成 `InvokeResponse` 帧。
+* - 订阅 framework `EventBus`，把 declared `HostEvent.publish(payload)` 通过
+*   `webContents.send('__electron-deck:event', envelope)` 推送给所有 trusted
+*   webContents。
+*
+* 该类只持有 deps 引用，不直接 import 'electron'；测试用 plain DI 注入 fake。
+* 生命周期一次性：start → dispose 后不能再 start（避免 listener 泄露 / 句柄
+* 双重注册）；hot-restart 由 host 重新构造新实例。
+*
+* @internal
+*/
+/**
+* Framework-reserved invoke failure codes —— 全部带 `DECK_` 前缀，避免与
+* host 自定义 code 冲突。Client / host 都不应抛同前缀。
+*/
+var DECK_CODE = {
+	UntrustedSender: "DECK_UNTRUSTED_SENDER",
+	UntrustedFrame: "DECK_UNTRUSTED_FRAME",
+	UnknownKind: "DECK_UNKNOWN_KIND",
+	BadRequest: "DECK_BAD_REQUEST",
+	/** P4 Phase B — the grant gate denied a privileged command for this sender. */
+	Forbidden: "DECK_FORBIDDEN"
+};
+var WireTransport = class {
+	deps;
+	state = "idle";
+	busSubscription = null;
+	/** Whether the optional Place / LayoutSubscribe handlers were registered
+	*  (either eagerly at start() via deps, or lazily via armSlotChannels) — so
+	*  dispose() only removes channels it actually registered. */
+	placeRegistered = false;
+	layoutSubscribeRegistered = false;
+	/** Effective slot callbacks. Populated from deps at start() (eager path, used
+	*  by the wire unit tests) OR by {@link armSlotChannels} (lazy path, used by
+	*  deck-app so an app with no anchored views registers only Invoke + Probe). */
+	onPlaceCb = null;
+	onLayoutSubscribeCb = null;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	start() {
+		if (this.state === "started") throw new Error("WireTransport already started");
+		if (this.state === "disposed") throw new Error("WireTransport already disposed (single-use lifecycle); construct a new instance to restart");
+		this.state = "started";
+		const cleanups = [];
+		try {
+			this.deps.ipcMain.handle(DeckChannel.Probe, () => this.handleProbe());
+			cleanups.push(() => this.tryRemoveHandler(DeckChannel.Probe));
+			this.deps.ipcMain.handle(DeckChannel.Invoke, (event, ...args) => this.handleInvoke(event?.sender?.id, event?.senderFrame, event?.sender?.mainFrame, args[0]));
+			cleanups.push(() => this.tryRemoveHandler(DeckChannel.Invoke));
+			if (this.deps.onPlace) {
+				this.onPlaceCb = this.deps.onPlace;
+				this.registerPlaceHandler();
+				cleanups.push(() => this.unregisterPlaceHandler());
+			}
+			if (this.deps.onLayoutSubscribe) {
+				this.onLayoutSubscribeCb = this.deps.onLayoutSubscribe;
+				this.registerLayoutSubscribeHandler();
+				cleanups.push(() => this.unregisterLayoutSubscribeHandler());
+			}
+			this.busSubscription = this.deps.bus.subscribeAll((name, payload) => {
+				this.fanoutEvent(name, payload);
+			});
+			cleanups.push(() => {
+				if (this.busSubscription) {
+					this.busSubscription.dispose();
+					this.busSubscription = null;
+				}
+			});
+		} catch (err) {
+			for (let i = cleanups.length - 1; i >= 0; i -= 1) try {
+				cleanups[i]?.();
+			} catch (cleanupErr) {
+				console.error("[electron-deck] start() rollback cleanup failed:", cleanupErr);
+			}
+			this.state = "idle";
+			throw err;
+		}
+	}
+	tryRemoveHandler(channel) {
+		try {
+			this.deps.ipcMain.removeHandler(channel);
+		} catch (e) {
+			console.error(`[electron-deck] removeHandler(${channel}) failed:`, e);
+		}
+	}
+	registerPlaceHandler() {
+		if (this.placeRegistered) return;
+		this.deps.ipcMain.handle(DeckChannel.Place, (event, ...args) => this.handlePlace(event?.sender?.id, event?.senderFrame, event?.sender?.mainFrame, args[0]));
+		this.placeRegistered = true;
+	}
+	unregisterPlaceHandler() {
+		if (!this.placeRegistered) return;
+		this.placeRegistered = false;
+		this.tryRemoveHandler(DeckChannel.Place);
+	}
+	registerLayoutSubscribeHandler() {
+		if (this.layoutSubscribeRegistered) return;
+		this.deps.ipcMain.handle(DeckChannel.LayoutSubscribe, (event) => this.handleLayoutSubscribe(event?.sender?.id, event?.senderFrame, event?.sender?.mainFrame));
+		this.layoutSubscribeRegistered = true;
+	}
+	unregisterLayoutSubscribeHandler() {
+		if (!this.layoutSubscribeRegistered) return;
+		this.layoutSubscribeRegistered = false;
+		this.tryRemoveHandler(DeckChannel.LayoutSubscribe);
+	}
+	/**
+	* Lazily register the slot-token inbound channels (`Place` + `LayoutSubscribe`)
+	* on an already-started wire, wiring them to the given callbacks. Idempotent:
+	* subsequent calls just refresh the callbacks (the handlers are registered
+	* once). deck-app calls this on the FIRST anchored `placeIn`, so an app with
+	* no anchored views never registers these channels (keeping the wire's
+	* handler footprint at Invoke + Probe until a slot is actually minted).
+	*/
+	armSlotChannels(onPlace, onLayoutSubscribe) {
+		this.onPlaceCb = onPlace;
+		this.onLayoutSubscribeCb = onLayoutSubscribe;
+		if (this.state !== "started") return;
+		this.registerPlaceHandler();
+		this.registerLayoutSubscribeHandler();
+	}
+	dispose() {
+		if (this.state !== "started") {
+			this.state = "disposed";
+			return;
+		}
+		this.state = "disposed";
+		try {
+			this.deps.ipcMain.removeHandler(DeckChannel.Invoke);
+		} catch (e) {
+			console.error("[electron-deck] removeHandler(invoke) failed:", e);
+		}
+		try {
+			this.deps.ipcMain.removeHandler(DeckChannel.Probe);
+		} catch (e) {
+			console.error("[electron-deck] removeHandler(probe) failed:", e);
+		}
+		if (this.placeRegistered) {
+			this.placeRegistered = false;
+			try {
+				this.deps.ipcMain.removeHandler(DeckChannel.Place);
+			} catch (e) {
+				console.error("[electron-deck] removeHandler(place) failed:", e);
+			}
+		}
+		if (this.layoutSubscribeRegistered) {
+			this.layoutSubscribeRegistered = false;
+			try {
+				this.deps.ipcMain.removeHandler(DeckChannel.LayoutSubscribe);
+			} catch (e) {
+				console.error("[electron-deck] removeHandler(layout-subscribe) failed:", e);
+			}
+		}
+		if (this.busSubscription) {
+			this.busSubscription.dispose();
+			this.busSubscription = null;
+		}
+	}
+	handleProbe() {
+		return {
+			ready: true,
+			version: BRIDGE_PROTOCOL_VERSION
+		};
+	}
+	/**
+	* Defense-in-depth main-frame check (mirrors devtools' verified
+	* `isMainFrameSender`). A trusted webContents may embed a sub-frame of
+	* arbitrary origin; only its top frame should reach gated invoke, so a
+	* sub-frame can't spoof the trusted sender id.
+	*
+	* - NEITHER field modeled → frame-unaware stub → not a real frame boundary;
+	*   the sender-id gate is the boundary → allow (back-compat with the legacy
+	*   `{ sender: { id } }` stubs).
+	* - either null (incl. a real event whose `senderFrame` resolved to null after
+	*   navigate-after-send / frame destruction, or a partial/malformed event) →
+	*   fail-closed → reject.
+	* - main frame (routingId + processId match) → allow; else (sub frame) reject.
+	*/
+	isMainFrameSender(senderFrame, main) {
+		if (senderFrame === void 0 && main === void 0) return true;
+		if (senderFrame == null || main == null) return false;
+		return senderFrame.routingId === main.routingId && senderFrame.processId === main.processId;
+	}
+	async handleInvoke(senderId, senderFrame, mainFrame, rawReq) {
+		const validation = validateRequest(rawReq);
+		if (!validation.ok) return failure(validation.name, validation.message, DECK_CODE.BadRequest);
+		const req = validation.req;
+		if (typeof senderId !== "number" || !this.deps.senderPolicy.isTrusted(senderId)) return failure(req.name, `untrusted sender (id=${String(senderId)})`, DECK_CODE.UntrustedSender);
+		if (!this.isMainFrameSender(senderFrame, mainFrame)) return failure(req.name, `untrusted frame (sender id=${String(senderId)})`, DECK_CODE.UntrustedFrame);
+		const ctx = {
+			senderId,
+			senderFrame: senderFrame ?? null
+		};
+		try {
+			if (req.kind === "host") return {
+				ok: true,
+				result: await this.deps.invokeHost(req.name, req.args, ctx)
+			};
+			if (req.kind === "simulator") return {
+				ok: true,
+				result: await this.deps.invokeSimulator(req.name, req.args, ctx)
+			};
+			return failure(req.name, `unknown invoke kind: ${String(req.kind)}`, DECK_CODE.UnknownKind);
+		} catch (err) {
+			return serializeError(req.name, err);
+		}
+	}
+	/**
+	* `__electron-deck:place` inbound. Same gate as {@link handleInvoke}
+	* (trust + main-frame). On any failure (malformed payload, untrusted sender,
+	* sub-frame) → DROP silently (return undefined; never call `onPlace`).
+	*/
+	handlePlace(senderId, senderFrame, mainFrame, rawMsg) {
+		if (rawMsg === null || typeof rawMsg !== "object" || Array.isArray(rawMsg)) return;
+		const msg = rawMsg;
+		if (typeof msg.slotToken !== "string") return;
+		if (typeof senderId !== "number" || !this.deps.senderPolicy.isTrusted(senderId)) return;
+		if (!this.isMainFrameSender(senderFrame, mainFrame)) return;
+		this.onPlaceCb?.(senderId, msg.slotToken, msg.placement);
+	}
+	/**
+	* `__electron-deck:layout-subscribe` inbound. Same gate as {@link handleInvoke}.
+	* On gate pass → `onLayoutSubscribe(senderId)`; else DROP silently.
+	*/
+	handleLayoutSubscribe(senderId, senderFrame, mainFrame) {
+		if (typeof senderId !== "number" || !this.deps.senderPolicy.isTrusted(senderId)) return;
+		if (!this.isMainFrameSender(senderFrame, mainFrame)) return;
+		this.onLayoutSubscribeCb?.(senderId);
+	}
+	fanoutEvent(name, payload) {
+		if (this.state !== "started") return;
+		if (!this.deps.declaredEvents().includes(name)) {
+			console.warn(`[electron-deck] dropping undeclared event "${name}" from wire fanout`);
+			return;
+		}
+		const env = {
+			name,
+			payload
+		};
+		let targets;
+		try {
+			targets = this.deps.trustedWebContents();
+		} catch (e) {
+			console.error("[electron-deck] trustedWebContents() threw:", e);
+			return;
+		}
+		for (const wc of targets) {
+			if (wc.isDestroyed()) continue;
+			try {
+				wc.send(DeckChannel.Event, env);
+			} catch (e) {
+				console.error(`[electron-deck] webContents.send("${DeckChannel.Event}") failed for wc#${wc.id}:`, e);
+			}
+		}
+	}
+};
+function validateRequest(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return {
+		ok: false,
+		name: "unknown",
+		message: "invoke request must be a plain object"
+	};
+	const { kind, name, args } = raw;
+	if (typeof kind !== "string") return {
+		ok: false,
+		name: typeof name === "string" ? name : "unknown",
+		message: "invoke request.kind must be a string"
+	};
+	if (typeof name !== "string") return {
+		ok: false,
+		name: "unknown",
+		message: "invoke request.name must be a string"
+	};
+	if (!Array.isArray(args)) return {
+		ok: false,
+		name,
+		message: "invoke request.args must be an array"
+	};
+	return {
+		ok: true,
+		req: {
+			kind,
+			name,
+			args
+		}
+	};
+}
+function failure(remoteName, message, code) {
+	return {
+		ok: false,
+		error: {
+			remoteName,
+			message,
+			code
+		}
+	};
+}
+function serializeError(invokeName, err) {
+	if (err instanceof DeckRemoteError) return failure(err.remoteName ?? invokeName, err.message, err.code);
+	if (err instanceof Error) {
+		const errAny = err;
+		const code = typeof errAny.code === "string" ? errAny.code : void 0;
+		return failure(invokeName, err.message, code);
+	}
+	let message;
+	try {
+		message = String(err);
+	} catch {
+		message = "unknown error (failed to stringify)";
+	}
+	return failure(invokeName, message);
+}
+//#endregion
+//#region src/host/control-bus.ts
+/**
+* ControlBus — a thin, domain-neutral facade over the existing
+* {@link WireTransport} + {@link EventBus} + an injectable refcount
+* {@link TrustSet}.
+*
+* Three verbs, no new gating logic of its own:
+*
+*  - `command(name, handler)` : webview → main RPC. The facade owns the single
+*    command table and exposes {@link ControlBus.dispatch}; the wire's
+*    `invokeHost` (and `invokeSimulator`) seam calls `dispatch(name, args)` so a
+*    real webview→main invoke (after the wire's sender + main-frame gate) lands on
+*    the registered handler. Callers never see the wire `kind`. Trust + main-frame
+*    gating are entirely the wire's (`handleInvoke`): a trusted main-frame sender
+*    reaches the handler, an untrusted sender → `DECK_UNTRUSTED_SENDER`, a
+*    sub-frame → `DECK_UNTRUSTED_FRAME`.
+*  - `event(name)` : main → webview push, default-deny. `name` is added to the
+*    declared-event allowlist the wire reads; `publish` goes through `bus.publish`
+*    → wire fanout (undeclared names are dropped by the wire). `dispose` revokes
+*    the declaration.
+*  - `trust(wc, owner)` : delegates to `trustSet.admit` (refcount membership owned
+*    by `owner` Scope, so the lease is released when the owner tears down).
+*
+* Real wiring (Bug C): the command table is the SOLE command authority. The
+* production caller builds the {@link WireTransport} with
+* `invokeHost = (name, args) => controlBus.dispatch(name, args)` (and the same
+* for `invokeSimulator`, since the facade hides the kind), and `declaredEvents`
+* reading {@link ControlBus.declaredEvents}. So a real IPC invoke reaches the
+* command handler through the wire — not a private test-only seam. Any
+* config-declared host services register into this SAME table via `command()`,
+* so there is one namespace (the host keeps names unique), never two registries
+* that can collide.
+*
+* @internal exported via `/host`.
+*/
+function createControlBus(deps) {
+	const { bus, trustSet, policy } = deps;
+	const commandRegistry = /* @__PURE__ */ new Map();
+	const declaredEventSet = /* @__PURE__ */ new Set();
+	return {
+		command(name, handler) {
+			commandRegistry.set(name, handler);
+			let disposed = false;
+			return { dispose: () => {
+				if (disposed) return;
+				disposed = true;
+				if (commandRegistry.get(name) === handler) commandRegistry.delete(name);
+			} };
+		},
+		event(name) {
+			declaredEventSet.add(name);
+			let disposed = false;
+			return {
+				publish: (payload) => {
+					bus.publish(name, payload);
+				},
+				dispose: () => {
+					if (disposed) return;
+					disposed = true;
+					declaredEventSet.delete(name);
+				}
+			};
+		},
+		trust(wc, owner) {
+			return trustSet.admit(wc, owner);
+		},
+		async dispatch(name, args, ctx) {
+			const handler = commandRegistry.get(name);
+			if (!handler) throw new Error(`no command registered: ${name}`);
+			if (policy && !policy.allows(ctx.senderId, name)) throw new DeckRemoteError(name, `forbidden: ${name}`, DECK_CODE.Forbidden);
+			return handler(...args);
+		},
+		declaredEvents() {
+			return Array.from(declaredEventSet);
+		}
+	};
+}
+//#endregion
+//#region src/internal/deck-app.ts
+var SIMULATOR_CHANNEL_PREFIX = "__electron-deck:simulator:";
+var HOST_CHANNEL_PREFIX = "__electron-deck:host:";
+var DEFAULT_MAIN_WIDTH = 1024;
+var DEFAULT_MAIN_HEIGHT = 768;
+/**
+* Framework-internal "app" object —— `electronDeck(config)` 顶层入口的 plain-class
+* 形态，便于 Phase 2 测试驱动 lifecycle 转换。Phase 3b 加 wireTransport 注入
+* 后可接真 ipcMain；Phase 4 加 electron 注入后可装配 mainWindow / toolbarView
+* / declared windows。两者都不注入时退化为同进程内存 fake。
+*
+* @internal
+*/
+var DeckApp = class {
+	config;
+	lifecycle = new LifecycleManager();
+	registry = new ResourceRegistryImpl();
+	bus = new EventBus();
+	ipc = new InMemoryTypedIpcRegistry();
+	fwListeners = /* @__PURE__ */ new Map();
+	trustSet = createTrustSet();
+	/** P4 Phase B — privileged-command grant registry. The policy gates
+	*  ControlBus.dispatch; grants are minted via `runtime.grants.issue`. */
+	capability = createCapabilityRegistry();
+	/** P4 Phase B — the grant-gated command bus for PRIVILEGED `layout.*`
+	*  commands. Constructed in `bindWireTransport` with the capability policy
+	*  injected, so `dispatch` default-DENIES any command lacking a live grant.
+	*  Privileged commands are registered via `runtime.layout.command`; ordinary
+	*  domain APIs stay on the un-gated `InMemoryTypedIpcRegistry`. */
+	controlBus = null;
+	/** v2 — per-webContents backend `onWindowTrusted` Disposable, so a window's
+	*  trust mirror is undone when THAT window closes (not only at teardown). */
+	backendTrustDisposables = /* @__PURE__ */ new Map();
+	options;
+	wireTransport = null;
+	/** v2 — the live wire senderPolicy, reused by buildRuntime so
+	*  `context._senderPolicy` reflects real trust instead of a `() => true` stub. */
+	wireSenderPolicy = null;
+	mainWindow = null;
+	toolbarView = null;
+	declaredWindows = /* @__PURE__ */ new Map();
+	trackedWindows = /* @__PURE__ */ new Set();
+	/**
+	* unified-lifetime P0 (observation-only, zero-regression). The root lifetime
+	* scope of the app + a shadow map mirroring `trackedWindows`, keyed by each
+	* window's webContents, carrying a per-window child Scope. P0 is PURELY
+	* OBSERVATIONAL: these windowScopes own NO resources (no destroy/trust/wire is
+	* moved onto them), so `rootScope.close()` during shutdown is a no-op for app
+	* behaviour — it exists only to lay the foundation P1 will take over. The
+	* shadow's key set is kept in lock-step with `trackedWindows` at every
+	* maintenance point.
+	*/
+	rootScope = createScope();
+	lifetimeShadow = /* @__PURE__ */ new Map();
+	/**
+	* unified-lifetime P1b: per-trusted-webContents trust record. `wcScope` is a
+	* child of the owning window's `windowScope`; it OWNS the wc's trust ref-count
+	* lease(s). When the window closes, `windowScope.close()` cascades into this
+	* `wcScope` (children-first LIFO), disposing every lease → ref-count hits 0 →
+	* the wc leaves the trust set. This replaces the imperative `deleteEntry`.
+	* A wc can be trusted more than once (framework auto-trust + host
+	* `windows.trust`), so `leases` is a Set.
+	*/
+	wcRecords = /* @__PURE__ */ new Map();
+	pendingWindowCreated = [];
+	pendingLoadFailed = [];
+	/**
+	* host-view slice 1 — per-window native-view substrate, keyed by the window's
+	* webContents (same key discipline as `lifetimeShadow`). Created at both
+	* window-construction sites; dropped in `handleSubWindowClosed`.
+	*/
+	windowSubstrates = /* @__PURE__ */ new Map();
+	/**
+	* P3 — per-adopted-window registration handle, keyed by the adopted window's
+	* webContents. `runtime.windows.adopt` is idempotent by wc identity: a second
+	* adopt of the same window returns this stored Disposable (no double-admit, no
+	* second substrate). The entry is removed when the registration is disposed
+	* (early un-adopt) or the window's windowScope closes.
+	*/
+	adoptedWindows = /* @__PURE__ */ new Map();
+	/**
+	* C1/C4 — per-registered-window {@link DeckWindow} facade + its per-window
+	* close deciders, keyed by the window's control wc. Populated by
+	* {@link registerWindow} for framework-created and adopted windows, plus the
+	* framework-built main window. `deciders` is an ORDERED list run in
+	* registration order on a close attempt; `closing` is the per-window in-flight
+	* decision latch (mirrors the main-window `closingDecisionPromise`).
+	*/
+	windowRegistrations = /* @__PURE__ */ new Map();
+	/** C1 — the framework-built main window's control wc, so `runtime.windows.main`
+	*  can resolve its {@link DeckWindow}. Null under an `ownsWindows:true` backend. */
+	mainControlWc = null;
+	/** host-view slice 1 — monotonic id source for `runtime.view` native views. */
+	viewSeq = 0;
+	/**
+	* P2 — provenance map for `runtime.scopes.create()` sessions: maps an opaque
+	* {@link DeckSession} to its internal `rootScope.child()` Scope. A WeakMap so a
+	* dropped session is GC'd; the framework holds the scope's lifetime via
+	* rootScope anyway (the session scope is a rootScope child). `runtime.view`
+	* resolves a passed session through this map — a foreign/raw Scope is absent
+	* and therefore REJECTED.
+	*/
+	sessions = /* @__PURE__ */ new WeakMap();
+	/**
+	* keepAlive B3.2 — opt-in per-group LRU of HIDDEN keep-alive views. Group key is
+	* `lru:${max}` (all `keepAlive:{policy:'lru',max:N}` views share one group per
+	* `max`). Each group holds an ORDERED list of HIDDEN view ids (front = least
+	* recently visible = first to evict) + a map from view id to its host handle so
+	* an eviction can dispose it (→ its WebContents is destroyed). Views created
+	* without `keepAlive` never participate.
+	*/
+	keepAliveGroups = /* @__PURE__ */ new Map();
+	/** C3: wcs that already have the `did-start-navigation` grant-reset hook bound,
+	*  so {@link bindNavigationGrantReset} is idempotent — a wc admitted to trust
+	*  more than once (e.g. constructed `autoTrust:false` then `windows.trust()`ed,
+	*  or un-adopted then re-adopted) never accumulates duplicate nav listeners. */
+	navHookBound = /* @__PURE__ */ new WeakSet();
+	/**
+	* slot-token registry (build-plan §2(e) / capability-and-lifecycle §A5-2):
+	* each anchored `placeIn` mints an unguessable token bound to (viewId, slotId,
+	* authorizedWcId). The `__electron-deck:place` apply path looks the token up,
+	* checks the sender is the authorized wc (anti-spoof), validates the placement,
+	* then `apply`s it. `resend` re-pushes the slot-grant (layout-subscribe replay).
+	*/
+	slotTokens = /* @__PURE__ */ new Map();
+	slotSeq = 0;
+	_runtime = null;
+	startCalled = false;
+	shutdownPromise = null;
+	/** Set when shutdown is driven by the `will-quit` handler — the app is already
+	*  quitting, so `doShutdown()` must NOT re-`app.quit()` (re-entrant quit). */
+	quitInitiated = false;
+	/** v2 close machine: non-null while a close decision is awaiting (in-flight latch). */
+	closingDecisionPromise = null;
+	/** v2 close machine: set once a 'close' decision is committed (guards the
+	*  window between decision-resolve and the 'closed' event). Never resets. */
+	shuttingDown = false;
+	/** Idempotency latch for {@link runShutdownCleanup}: the cleanup body
+	*  (beforeClose → backend.onShutdown → rootScope.close) must run AT MOST ONCE.
+	*  Both `doShutdown` (single-flight via shutdownPromise) AND `cleanupOnError`
+	*  (which bypasses that promise) reach here; and `rootScope.close()` inside the
+	*  body can synchronously fire a framework window's `'closed'` → `shutdown()`
+	*  re-entry. Without this latch that re-entry would invoke `backend.onShutdown`
+	*  a second time.
+	*
+	*  This is a JOIN, not a boolean early-return: a re-entrant caller AWAITS the
+	*  SAME in-flight cleanup promise instead of returning immediately. A plain
+	*  `if (ran) return` let a concurrent shutdown skip past an in-flight cleanup
+	*  and force `app.quit()` mid-teardown (truncation). Never resets. */
+	cleanupPromise = null;
+	constructor(config, options = {}) {
+		this.config = config;
+		this.options = options;
+		this.rootScope.own(() => {
+			this.bus.unbindAll();
+		});
+		this.rootScope.own(async () => {
+			try {
+				await this.registry.disposeAll();
+			} catch (e) {
+				console.error("[electron-deck] registry.disposeAll failed:", e);
+			}
+		});
+	}
+	get phase() {
+		return this.lifecycle.current;
+	}
+	get runtime() {
+		if (this._runtime === null) throw new Error("DeckApp.runtime is unavailable before setup phase");
+		return this._runtime;
+	}
+	async start() {
+		if (this.startCalled) throw new Error("DeckApp.start() already called");
+		this.startCalled = true;
+		validateConfig(this.config);
+		const hasWebviewContent = !!(this.config.toolbar || this.config.windows);
+		if (this.options.electron && hasWebviewContent && !this.options.wireTransport) throw new Error("DeckAppOptions: wireTransport.ipcMain is required when config has toolbar or windows");
+		const app = this.options.electron?.app;
+		if (app) {
+			if (this.config.app?.singleInstance && typeof app.requestSingleInstanceLock === "function") {
+				if (!app.requestSingleInstanceLock()) {
+					try {
+						app.quit();
+					} catch {}
+					return;
+				}
+			}
+			if (this.options.backend?.beforeReady) await this.options.backend.beforeReady(app);
+			else if (this.config.app?.name) try {
+				app.setName(this.config.app.name);
+			} catch {}
+			await app.whenReady();
+			this.bindAppLifecycle(app);
+		}
+		try {
+			this.lifecycle.enter("bind");
+			this.bindDeclarativeFields();
+			this.assembleElectron();
+			this.bindWireTransport();
+			this.loadAssembledSources();
+			this.lifecycle.enter("setup");
+			this._runtime = this.buildRuntime();
+			if (this.options.backend) await this.options.backend.assemble(this._runtime);
+			if (this.config.setup) await this.config.setup(this._runtime);
+			this.lifecycle.enter("ready");
+		} catch (err) {
+			await this.cleanupOnError();
+			throw err;
+		}
+	}
+	/**
+	* Process-level Electron lifecycle bindings (post-whenReady, independent of
+	* `ownsWindows` — these are app events, not window events):
+	* - `will-quit` → framework teardown (idempotent via `shutdownPromise`).
+	* - `window-all-closed` → bound ONLY when `quitOnAllWindowsClosed` is set
+	*   (opt-in; omitted leaves Electron's default / the consumer's own handler).
+	* - `second-instance` → backend hook, bound only under `singleInstance`.
+	*/
+	bindAppLifecycle(app) {
+		app.on("will-quit", () => {
+			this.quitInitiated = true;
+			this.shutdown();
+		});
+		const quitOnAllClosed = this.config.app?.quitOnAllWindowsClosed;
+		if (quitOnAllClosed !== void 0) app.on("window-all-closed", () => {
+			if (quitOnAllClosed) try {
+				app.quit();
+			} catch {}
+		});
+		if (this.config.app?.singleInstance) app.on("second-instance", () => {
+			this.options.backend?.onSecondInstance?.();
+		});
+	}
+	shutdown() {
+		if (this.shutdownPromise) return this.shutdownPromise;
+		this.shutdownPromise = this.doShutdown();
+		return this.shutdownPromise;
+	}
+	/**
+	* @internal Phase 4 windows.trust() / framework 内部添加 trusted webContents.
+	* Backend-owned / untracked-window fallback: there is no framework windowScope
+	* for these (the backend manages their lifetime), so the trust lease is owned
+	* by `rootScope` as an app-shutdown backstop. The backend still disposes the
+	* returned handle early when it untrusts / destroys its own window.
+	*/
+	_trustWebContents(wc) {
+		return this.trustSet.admit(wc, this.rootScope);
+	}
+	/**
+	* unified-lifetime P1b: admit `wc` to the trust set under `windowScope`. Gets
+	* or creates the wc's `wcScope` (a child of `windowScope`), takes a fresh
+	* `trustSet.admit(wc, wcScope)` ref-count lease OWNED BY that wcScope, and returns a
+	* one-shot host-facing Disposable that releases just THIS lease early. On
+	* `wcScope.close()` (window-close cascade) every still-held lease is disposed
+	* → ref-count zeroes → the wc leaves the set (equivalent to the old
+	* `deleteEntry`, but driven by Scope teardown and covering partially-built
+	* windows too). Idempotent registry cleanup is owned by the wcScope.
+	*/
+	admitTrust(wc, windowScope) {
+		if (wc.isDestroyed()) return { dispose: () => {} };
+		let rec = this.wcRecords.get(wc);
+		if (!rec) {
+			const wcScope = windowScope.child();
+			rec = {
+				wcScope,
+				leases: /* @__PURE__ */ new Set(),
+				windowScope
+			};
+			this.wcRecords.set(wc, rec);
+			wcScope.own(() => {
+				this.wcRecords.delete(wc);
+			});
+		}
+		const record = rec;
+		const lease = this.trustSet.admit(wc, record.wcScope);
+		record.leases.add(lease);
+		let released = false;
+		return { dispose: () => {
+			if (released) return;
+			released = true;
+			record.leases.delete(lease);
+			lease.dispose();
+		} };
+	}
+	/**
+	* C3 (P0 security) — bind the main-frame cross-document navigation grant-reset
+	* hook on a control `wc`. On a MAIN-FRAME CROSS-DOCUMENT navigation
+	* (`isMainFrame && !isInPlace`) this SYNCHRONOUSLY revokes the wc's capability
+	* grants (`capability.revokeBySenderId`) and slot tokens, so the navigated-to
+	* document can't inherit the prior page's privileges. Trust is LEFT INTACT (the
+	* wc stays the framework's control surface) — we deliberately do NOT tear down
+	* its `wcScope`, because that would dispose the trust lease and force an async
+	* re-admit gap that breaks `runtime.grants.issue`. In-place (hash/pushState) and
+	* sub-frame navigations are ignored; the initial document load is a no-op (no
+	* grants exist yet).
+	*
+	* Must be called AFTER {@link admitTrust} so the wc's `wcScope` exists. The
+	* `wc.on` guard tolerates the minimal fakes that lack an EventEmitter surface.
+	*/
+	bindNavigationGrantReset(wc) {
+		const on = wc.on;
+		if (typeof on !== "function") return;
+		if (this.navHookBound.has(wc)) return;
+		this.navHookBound.add(wc);
+		on.call(wc, "did-start-navigation", (_event, _url, isInPlace, isMainFrame) => {
+			if (isMainFrame !== true || isInPlace === true) return;
+			if (!this.wcRecords.get(wc)) return;
+			this.capability.revokeBySenderId(wc.id);
+			this.revokeSlotTokensForWc(wc.id);
+		});
+	}
+	/**
+	* C1 — build the {@link DeckWindow} facade over a registered window and record
+	* it (so `runtime.windows.create()` / `runtime.windows.main` can return it and
+	* the per-window close machine can find its deciders). `newSession()` mints a
+	* window-rooted {@link DeckSession} (a `windowScope.child()` registered in the
+	* SAME provenance WeakMap as `runtime.scopes.create()`); `onClose()` appends a
+	* per-window decider.
+	*/
+	buildDeckWindow(win, controlWc, windowScope) {
+		const deckWindow = {
+			window: win,
+			controlWc,
+			newSession: () => {
+				const scope = windowScope.child();
+				const session = {
+					reset: () => scope.reset(),
+					dispose: () => scope.close()
+				};
+				this.sessions.set(session, scope);
+				return session;
+			},
+			onClose: (decider) => {
+				const rec = this.windowRegistrations.get(controlWc);
+				if (!rec) return { dispose: () => {} };
+				rec.deciders.push(decider);
+				let removed = false;
+				return { dispose: () => {
+					if (removed) return;
+					removed = true;
+					const i = rec.deciders.indexOf(decider);
+					if (i >= 0) rec.deciders.splice(i, 1);
+				} };
+			}
+		};
+		this.windowRegistrations.set(controlWc, {
+			window: win,
+			controlWc,
+			windowScope,
+			deckWindow,
+			deciders: [],
+			closing: null,
+			committedClose: false
+		});
+		windowScope.own(() => {
+			this.windowRegistrations.delete(controlWc);
+		});
+		return deckWindow;
+	}
+	/**
+	* Resolve a window argument that may be either a raw `BrowserWindow` (the
+	* historical `runtime.view().placeIn(window)` shape) OR a {@link DeckWindow}
+	* handle (the C1 `runtime.windows.create()` return). A DeckWindow exposes the
+	* underlying window via `.window` and has no `.webContents` of its own; a raw
+	* window has `.webContents`. Unwrap so the substrate lookup keys off the real
+	* control webContents either way — keeping the `placeIn(deckWindow)` and
+	* `placeIn(deckWindow.window)` call shapes both valid (additive, no break).
+	*/
+	resolveWindowArg(win) {
+		const maybe = win;
+		if (maybe && maybe.webContents === void 0 && maybe.window !== void 0) return maybe.window;
+		return win;
+	}
+	/**
+	* C4 — run a registered window's per-window close deciders (registration order;
+	* any `'keep'` vetoes), with an in-flight latch so a re-entrant close during a
+	* pending decision decides ONCE. A throw / rejection fails CLOSED. Returns the
+	* committed decision, or `null` when the decision is still in flight / there are
+	* no deciders (caller falls back). Mirrors the main-window decision machine.
+	*/
+	async runWindowCloseDeciders(controlWc) {
+		const rec = this.windowRegistrations.get(controlWc);
+		if (!rec) return "close";
+		const deciders = rec.deciders.slice();
+		for (const decide of deciders) {
+			let decision;
+			try {
+				decision = await decide();
+			} catch (err) {
+				console.error("[electron-deck] per-window onClose decider threw; closing:", err);
+				decision = "close";
+			}
+			if (decision === "keep") return "keep";
+		}
+		return "close";
+	}
+	/**
+	* C4 — arm the per-window cancelable close-decision machine on a CREATED /
+	* adopted window. On a `close` attempt: `preventDefault`, dispatch the
+	* per-window deciders behind an in-flight latch (re-entrant closes swallowed),
+	* and on a `'close'` decision `win.destroy()` (→ `'closed'` → revoke +
+	* windowScope cascade). A `'keep'` clears the latch so the next close re-decides.
+	* Only armed when at least one decider can exist (i.e. the window has a
+	* registration) — windows with no per-window deciders fall through to Electron's
+	* default close (the framework does not preventDefault).
+	*/
+	armSubWindowCloseMachine(win, controlWc) {
+		win.on("close", (e) => {
+			const rec = this.windowRegistrations.get(controlWc);
+			if (!rec || rec.deciders.length === 0) return;
+			e?.preventDefault?.();
+			if (rec.closing) return;
+			if (rec.committedClose) return;
+			let settle;
+			rec.closing = new Promise((res) => {
+				settle = res;
+			});
+			this.runWindowCloseDeciders(controlWc).then((d) => settle(d), (err) => {
+				console.error("[electron-deck] per-window close decision rejected; closing:", err);
+				settle("close");
+			});
+			rec.closing.then((decision) => {
+				if (decision === "keep") {
+					rec.closing = null;
+					return;
+				}
+				rec.committedClose = true;
+				rec.closing = null;
+				if (!win.isDestroyed()) win.destroy();
+			});
+		});
+	}
+	/**
+	* @internal unified-lifetime P0 accessors (observation-only). The live shadow
+	* map mirroring `trackedWindows`, the root Scope, and a consistency assertion.
+	*/
+	__lifetimeShadow() {
+		return this.lifetimeShadow;
+	}
+	/** @internal unified-lifetime P0: the root lifetime Scope. */
+	__rootScope() {
+		return this.rootScope;
+	}
+	/** @internal unified-lifetime P1b: the per-trusted-wc trust records. */
+	__wcRecords() {
+		return this.wcRecords;
+	}
+	/** @internal P4 Phase B: the live capability policy (grant gate reads it). */
+	__capabilityPolicy() {
+		return this.capability.policy;
+	}
+	/**
+	* @internal unified-lifetime P0 invariant (A): the shadow's per-window set
+	* (the `window` of each entry) must equal `trackedWindows` membership. Throws
+	* if violated; no-op otherwise.
+	*/
+	__assertLifetimeConsistent() {
+		const shadowWindows = /* @__PURE__ */ new Set();
+		for (const entry of this.lifetimeShadow.values()) shadowWindows.add(entry.window);
+		if (shadowWindows.size !== this.trackedWindows.size) throw new Error(`lifetime shadow inconsistent: shadow has ${shadowWindows.size} windows, trackedWindows has ${this.trackedWindows.size}`);
+		for (const win of this.trackedWindows) if (!shadowWindows.has(win)) throw new Error("lifetime shadow inconsistent: a trackedWindows member is absent from the shadow");
+	}
+	bindDeclarativeFields() {
+		if (this.config.events) this.bus.bindDeclaredEvents(this.config.events);
+		if (this.config.simulatorApis) for (const [name, handler] of Object.entries(this.config.simulatorApis)) {
+			const d = this.ipc.handle(`${SIMULATOR_CHANNEL_PREFIX}${name}`, handler);
+			this.registry.add(d);
+		}
+		if (this.config.hostServices) for (const [name, handler] of Object.entries(this.config.hostServices)) {
+			if (name.startsWith("layout.")) throw new Error(`config.hostServices: "layout.*" names are reserved for privileged ControlBus commands (use runtime.layout.command); got: ${name}`);
+			const d = this.ipc.handle(`${HOST_CHANNEL_PREFIX}${name}`, handler);
+			this.registry.add(d);
+		}
+	}
+	/**
+	* host-view slice 1 — build a per-window {@link ViewSubstrate}. The
+	* `ContentViewHost` adapts `win.contentView` and tracks the Compositor-managed
+	* z-order in `order` (the minimal `contentView` has no `children()`). The
+	* substrate's `detachAll` is owned on `windowScope` AFTER the window's
+	* `win.destroy` own, so LIFO teardown runs detachAll (STEP1) BEFORE destroy
+	* (STEP4) — the A4 ordering.
+	*/
+	createWindowSubstrate(win, windowScope) {
+		const wcvById = /* @__PURE__ */ new Map();
+		const order = [];
+		const compositor = createCompositor({
+			addChildView: (ref) => {
+				const wcv = wcvById.get(ref.id);
+				if (!wcv) return;
+				win.contentView.addChildView(wcv);
+				const i = order.indexOf(ref.id);
+				if (i >= 0) order.splice(i, 1);
+				order.push(ref.id);
+			},
+			removeChildView: (ref) => {
+				const wcv = wcvById.get(ref.id);
+				if (!wcv) return;
+				win.contentView.removeChildView(wcv);
+				const i = order.indexOf(ref.id);
+				if (i >= 0) order.splice(i, 1);
+			},
+			get isDestroyed() {
+				return win.isDestroyed();
+			},
+			children: () => order.map((id) => ({ id }))
+		});
+		windowScope.own(() => {
+			compositor.detachAll?.();
+		});
+		return {
+			compositor,
+			windowScope,
+			registerView: (id, wcv) => {
+				wcvById.set(id, wcv);
+			},
+			unregisterView: (id) => {
+				wcvById.delete(id);
+				const i = order.indexOf(id);
+				if (i >= 0) order.splice(i, 1);
+			}
+		};
+	}
+	assembleElectron() {
+		const electron = this.options.electron;
+		if (!electron) return;
+		if (this.options.backend?.ownsWindows) return;
+		const appCfg = this.config.app ?? {};
+		const winCfg = appCfg.window ?? {};
+		const mainOpts = {
+			...appCfg.name !== void 0 ? { title: appCfg.name } : {},
+			...appCfg.icon !== void 0 ? { icon: appCfg.icon } : {},
+			width: winCfg.width ?? DEFAULT_MAIN_WIDTH,
+			height: winCfg.height ?? DEFAULT_MAIN_HEIGHT
+		};
+		if (winCfg.minWidth !== void 0) mainOpts.minWidth = winCfg.minWidth;
+		if (winCfg.minHeight !== void 0) mainOpts.minHeight = winCfg.minHeight;
+		if (winCfg.show !== void 0) mainOpts.show = winCfg.show;
+		if (winCfg.backgroundColor !== void 0) mainOpts.backgroundColor = winCfg.backgroundColor;
+		const backendPrefs = this.options.backend?.mainWindowWebPreferences?.();
+		if (winCfg.webPreferences || backendPrefs) mainOpts.webPreferences = {
+			...winCfg.webPreferences,
+			...backendPrefs
+		};
+		const main = new electron.BrowserWindow(mainOpts);
+		this.mainWindow = main;
+		this.trackedWindows.add(main);
+		const mainWindowScope = this.rootScope.child();
+		mainWindowScope.own(() => {
+			if (!main.isDestroyed()) main.destroy();
+		});
+		this.lifetimeShadow.set(main.webContents, {
+			window: main,
+			windowScope: mainWindowScope
+		});
+		this.windowSubstrates.set(main.webContents, this.createWindowSubstrate(main, mainWindowScope));
+		const mainWcId = main.webContents.id;
+		main.on("closed", () => {
+			this.revokeWindowTrust(mainWindowScope);
+			this.revokeSlotTokensForWc(mainWcId);
+		});
+		this.options.backend?.onMainWindowCreated?.(main, electron);
+		this.admitTrust(main.webContents, mainWindowScope);
+		const mainControlWc = main.webContents;
+		this.bindNavigationGrantReset(mainControlWc);
+		this.buildDeckWindow(main, mainControlWc, mainWindowScope);
+		this.mainControlWc = mainControlWc;
+		this._notifyBackendTrusted(main.webContents);
+		this.pendingWindowCreated.push({
+			window: main,
+			role: "main"
+		});
+		main.on("resize", () => {
+			this.options.backend?.repositionOverlays?.(main);
+			if (!this.toolbarView || !this.config.toolbar) return;
+			const b = main.getContentBounds();
+			this.toolbarView.setBounds({
+				x: 0,
+				y: 0,
+				width: b.width,
+				height: this.config.toolbar.height
+			});
+		});
+		main.on("close", (e) => {
+			e?.preventDefault?.();
+			if (this.closingDecisionPromise) return;
+			if (this.shuttingDown) return;
+			let settle;
+			this.closingDecisionPromise = new Promise((res) => {
+				settle = res;
+			});
+			let decide;
+			const mainReg = this.windowRegistrations.get(mainControlWc);
+			if (mainReg && mainReg.deciders.length > 0) decide = this.runWindowCloseDeciders(mainControlWc);
+			else try {
+				decide = this.options.backend?.onMainWindowClose?.() ?? "close";
+			} catch (err) {
+				console.error("[electron-deck] onMainWindowClose threw (sync); closing:", err);
+				decide = "close";
+			}
+			Promise.resolve(decide).then((d) => settle(d === "keep" ? "keep" : "close"), (err) => {
+				console.error("[electron-deck] onMainWindowClose threw; closing:", err);
+				settle("close");
+			});
+			this.closingDecisionPromise.then((decision) => {
+				if (decision === "keep") {
+					this.closingDecisionPromise = null;
+					return;
+				}
+				this.shuttingDown = true;
+				this.closingDecisionPromise = null;
+				if (!main.isDestroyed()) main.destroy();
+			});
+		});
+		main.on("closed", () => {
+			this.revokeWindowTrust(mainWindowScope);
+			mainWindowScope.close().catch((e) => {
+				console.error("[electron-deck] mainWindowScope.close() failed:", e);
+			}).finally(() => {
+				this.shutdown();
+			});
+		});
+		if (this.config.toolbar) {
+			const tb = this.config.toolbar;
+			const view = new electron.WebContentsView({ webPreferences: { preload: tb.preloadPath } });
+			this.toolbarView = view;
+			main.contentView.addChildView(view);
+			const bounds = main.getContentBounds();
+			view.setBounds({
+				x: 0,
+				y: 0,
+				width: bounds.width,
+				height: tb.height
+			});
+			this.admitTrust(view.webContents, mainWindowScope);
+			this.pendingWindowCreated.push({
+				window: main,
+				role: "toolbar"
+			});
+		}
+		if (this.config.windows) for (const [key, contrib] of Object.entries(this.config.windows)) {
+			const win = this.constructWindow(contrib, true, true);
+			this.declaredWindows.set(key, win);
+			this.pendingWindowCreated.push({
+				window: win,
+				role: "host"
+			});
+		}
+	}
+	/** Phase 4 race fix：在 wireTransport.start 之后再 loadURL/loadFile。 */
+	loadAssembledSources() {
+		if (this.toolbarView && this.config.toolbar) this.safeLoad(this.toolbarView.webContents, this.config.toolbar.source);
+		if (this.config.windows) for (const [key, contrib] of Object.entries(this.config.windows)) {
+			const win = this.declaredWindows.get(key);
+			if (win) this.safeLoad(win.webContents, contrib.source);
+		}
+		if (this.mainWindow && this.config.app?.source) this.safeLoad(this.mainWindow.webContents, this.config.app.source);
+	}
+	/**
+	* #3 R5/C2 — load is best-effort: log + emit `load-failed` if it rejects,
+	* but never let start() reject because of a renderer load issue (we'd
+	* leave the host blocked indefinitely while the framework is otherwise
+	* happy).
+	*/
+	safeLoad(wc, source) {
+		if ("url" in source) wc.loadURL(source.url).catch((err) => {
+			console.error(`[electron-deck] loadURL("${source.url}") failed:`, err);
+			this.surfaceLoadFailed(source, err);
+		});
+		else wc.loadFile(source.file).catch((err) => {
+			console.error(`[electron-deck] loadFile("${source.file}") failed:`, err);
+			this.surfaceLoadFailed(source, err);
+		});
+	}
+	/**
+	* D1 fix: load-failed 在 listener 注册之前到达时 buffer 到 pendingLoadFailed；
+	* 第一个 listener 注册时 splice 消费整个队列。已有 listener 时直接 emit。
+	*/
+	surfaceLoadFailed(source, error) {
+		const listeners = this.fwListeners.get("load-failed");
+		if (listeners && listeners.size > 0) {
+			this.emitFrameworkEvent("load-failed", {
+				source,
+				error
+			});
+			return;
+		}
+		this.pendingLoadFailed.push({
+			source,
+			error
+		});
+	}
+	bindWireTransport() {
+		const wireOpts = this.options.wireTransport;
+		if (!wireOpts) return;
+		const trustedWebContents = wireOpts.trustedWebContents ?? (() => this.trustSet.snapshot());
+		const defaultSenderPolicy = wireOpts.trustedWebContents ? { isTrusted: (id) => {
+			for (const wc of wireOpts.trustedWebContents()) if (wc.id === id) return true;
+			return false;
+		} } : { isTrusted: (id) => this.trustSet.isTrusted(id) };
+		const senderPolicy = wireOpts.senderPolicy ?? defaultSenderPolicy;
+		this.wireSenderPolicy = senderPolicy;
+		this.controlBus = createControlBus({
+			bus: this.bus,
+			trustSet: this.trustSet,
+			policy: this.capability.policy
+		});
+		const transport = new WireTransport({
+			ipcMain: wireOpts.ipcMain,
+			bus: this.bus,
+			senderPolicy,
+			trustedWebContents,
+			invokeHost: (name, args, ctx) => {
+				if (this.isPrivilegedCommandName(name)) return this.controlBus.dispatch(name, args, ctx);
+				return this.ipc.invoke(`${HOST_CHANNEL_PREFIX}${name}`, ...args);
+			},
+			invokeSimulator: (name, args, _ctx) => this.ipc.invoke(`${SIMULATOR_CHANNEL_PREFIX}${name}`, ...args),
+			declaredEvents: () => this.config.events ? this.config.events.map((ev) => ev.name) : []
+		});
+		transport.start();
+		this.wireTransport = transport;
+		this.ensureSlotChannelsArmed();
+		this.registry.add({ dispose: () => {
+			transport.dispose();
+		} });
+	}
+	/**
+	* The two-route boundary's privileged-name predicate (§A5-1.2 硬约束). A
+	* PRIVILEGED command name — by convention `layout.*` — routes through the
+	* grant-gated {@link ControlBus} (`controlBus.dispatch`). Ordinary domain
+	* APIs (any other name) stay on the un-gated declarative `hostServices`
+	* route. Privileged names MUST NOT be registered in `hostServices`.
+	*/
+	isPrivilegedCommandName(name) {
+		return name.startsWith("layout.");
+	}
+	/**
+	* KA-4: warn ONCE about an invalid `keepAlive.max` (negative / non-integer /
+	* NaN). Such a view is not keep-alive-managed (the group is skipped); warning
+	* once avoids log spam when many views share the same bad config.
+	*/
+	warnedInvalidKeepAliveMax = false;
+	warnInvalidKeepAliveMax(max) {
+		if (this.warnedInvalidKeepAliveMax) return;
+		this.warnedInvalidKeepAliveMax = true;
+		console.warn(`[electron-deck] runtime.view keepAlive.max must be a non-negative integer (got: ${max}); the view is NOT keep-alive-managed (no eviction).`);
+	}
+	constructWindow(opts, autoTrust, deferLoad = false) {
+		const electron = this.options.electron;
+		if (!electron) throw new Error("DeckApp.constructWindow called without electron injection");
+		const browserOpts = {};
+		if (opts.title !== void 0) browserOpts.title = opts.title;
+		if (opts.width !== void 0) browserOpts.width = opts.width;
+		if (opts.height !== void 0) browserOpts.height = opts.height;
+		if (opts.modal !== void 0) browserOpts.modal = opts.modal;
+		if (opts.preloadPath !== void 0) browserOpts.webPreferences = { preload: opts.preloadPath };
+		if ("parent" in opts && opts.parent !== void 0) browserOpts.parent = opts.parent;
+		const win = new electron.BrowserWindow(browserOpts);
+		this.trackedWindows.add(win);
+		const wc = win.webContents;
+		const windowScope = this.rootScope.child();
+		windowScope.own(() => {
+			if (!win.isDestroyed()) win.destroy();
+		});
+		this.lifetimeShadow.set(wc, {
+			window: win,
+			windowScope
+		});
+		this.windowSubstrates.set(wc, this.createWindowSubstrate(win, windowScope));
+		win.on("closed", () => {
+			this.handleSubWindowClosed(win, wc);
+		});
+		if (autoTrust) {
+			this.admitTrust(wc, windowScope);
+			this._notifyBackendTrusted(win.webContents);
+			this.bindNavigationGrantReset(wc);
+		}
+		this.buildDeckWindow(win, wc, windowScope);
+		this.armSubWindowCloseMachine(win, wc);
+		if (!deferLoad) this.safeLoad(win.webContents, opts.source);
+		return win;
+	}
+	/**
+	* P3 — register an EXTERNALLY-created window into the framework so
+	* `runtime.view().placeIn(win)` works for it: a `rootScope.child()`
+	* windowScope, a per-window {@link ViewSubstrate}, and the TRUST lifecycle —
+	* mirroring {@link constructWindow}'s registration, but for a window the host
+	* built (e.g. under `ownsWindows:true`). The framework holds NO windowScope /
+	* substrate / trust for such a window until this call.
+	*
+	* Ordering MIRRORS the framework's own windows (constructWindow / main-window):
+	*  1) build the windowScope (child of rootScope so shutdown cascades it),
+	*  2) build + register the per-window substrate (so placeIn can resolve it),
+	*  3) for `ownership:'transfer'` ONLY, OWN `() => win.destroy()` on the
+	*     windowScope so app shutdown destroys the window; for `'observe'` the host
+	*     keeps lifetime control (the framework never destroys it),
+	*  4) arm trust+grant+slot-token revocation as the FIRST `'closed'` listener via
+	*     `prependListener` (codex R2 — runs before any external `'closed'` listener),
+	*  5) `admitTrust` AFTER the revoke listener is registered (constructWindow order).
+	*
+	* Idempotent by webContents identity: a second adopt of the same window returns
+	* the existing registration. Throws if the window/webContents is destroyed.
+	*/
+	adoptWindow(win, opts) {
+		const wc = win.webContents;
+		if (win.isDestroyed?.() || wc.isDestroyed?.()) throw new Error("runtime.windows.adopt: window is already destroyed");
+		const existing = this.adoptedWindows.get(wc);
+		if (existing) return existing;
+		if (this.windowSubstrates.has(wc)) throw new Error("runtime.windows.adopt: window is already framework-tracked (cannot adopt a framework-owned window)");
+		const windowScope = this.rootScope.child();
+		if (opts?.ownership === "transfer") windowScope.own(() => {
+			if (!win.isDestroyed()) win.destroy();
+		});
+		this.windowSubstrates.set(wc, this.createWindowSubstrate(win, windowScope));
+		const adoptedWcId = wc.id;
+		const revoke = () => {
+			this.revokeWindowTrust(windowScope);
+			this.revokeSlotTokensForWc(adoptedWcId);
+		};
+		if (typeof win.prependListener === "function") win.prependListener("closed", revoke);
+		else win.on("closed", revoke);
+		this.admitTrust(wc, windowScope);
+		this.bindNavigationGrantReset(wc);
+		this.buildDeckWindow(win, wc, windowScope);
+		this.armSubWindowCloseMachine(win, wc);
+		windowScope.own(() => {
+			this.windowSubstrates.delete(wc);
+			this.adoptedWindows.delete(wc);
+			this.revokeSlotTokensForWc(adoptedWcId);
+		});
+		let disposed = false;
+		const registration = { dispose: () => {
+			if (disposed) return;
+			disposed = true;
+			this.revokeWindowTrust(windowScope);
+			this.revokeSlotTokensForWc(adoptedWcId);
+			windowScope.close().catch((e) => {
+				console.error("[electron-deck] adopted windowScope.close() failed:", e);
+			});
+		} };
+		this.adoptedWindows.set(wc, registration);
+		return registration;
+	}
+	/**
+	* unified-lifetime P1b: synchronously revoke BOTH trust leases AND capability
+	* grants for every wc admitted under `windowScope` (the window's control wc +
+	* any siblings like the toolbar wc). Called from the window's 'closed' handler
+	* so both authorizations are gone the instant the window is destroyed —
+	* matching the old synchronous `deleteEntry` timing and closing every
+	* async-cascade race (a destroyed wc can never be observed trusted OR granted
+	* by a later shutdown/beforeClose, nor by a NEW window that reuses the same
+	* wc.id before the async scope cascade revokes it). The leases are ALSO owned
+	* by their wcScope, so the async `windowScope.close()` still runs (it disposes
+	* the already-disposed leases idempotently, plus win.destroy + wcRecords
+	* cleanup) and remains the teardown/partial-init fallback for paths where no
+	* 'closed' fires (cleanupOnError, shutdown of a never-closed window).
+	* `lease.dispose()` is synchronous (trustSet ref-count--) and one-shot, so no
+	* double-decrement; `revokeBySenderId` is likewise idempotent, so the grant's
+	* own async `senderScope.on('closed')` revoke later becomes a no-op.
+	*/
+	revokeWindowTrust(windowScope) {
+		for (const [wc, rec] of this.wcRecords) if (rec.windowScope === windowScope) {
+			for (const lease of rec.leases) lease.dispose();
+			this.capability.revokeBySenderId(wc.id);
+		}
+	}
+	/**
+	* Arm the wire's slot-token inbound channels (idempotent). P5 eager-arm:
+	* called once at framework start() (bindWireTransport, right after
+	* transport.start()) so a layout client can subscribe before the first
+	* anchored placeIn; the anchored `placeIn` call site is now a redundant no-op
+	* (kept for safety). No-op when there's no wire transport (main-internal-only
+	* builds can't serve a renderer slot anyway).
+	*/
+	ensureSlotChannelsArmed() {
+		this.wireTransport?.armSlotChannels((senderId, slotToken, placement) => this.handleSlotPlace(senderId, slotToken, placement), (senderId) => this.handleLayoutSubscribe(senderId));
+	}
+	/**
+	* slot-token apply path (`__electron-deck:place`). The token is the credential:
+	* look it up, verify the sender IS the wc the token was granted to (anti-spoof),
+	* validate the placement, then apply. Any failure → DROP (silent).
+	*/
+	handleSlotPlace(senderId, slotToken, placement) {
+		const entry = this.slotTokens.get(slotToken);
+		if (!entry) return;
+		if (entry.authorizedWcId !== senderId) return;
+		if (!isValidPlacement(placement)) return;
+		entry.apply(placement);
+	}
+	/**
+	* Per-wc layout-subscribe replay (`__electron-deck:layout-subscribe`). When the
+	* authorized control wc (re)subscribes (e.g. after reload), re-push every grant
+	* it owns so it can re-bind its DOM slots. A DIFFERENT wc's subscribe never
+	* receives another wc's grants.
+	*/
+	handleLayoutSubscribe(senderId) {
+		for (const entry of this.slotTokens.values()) if (entry.authorizedWcId === senderId) entry.resend();
+	}
+	/** Drop every slot token authorized to `wcId` (window-close / shutdown hygiene). */
+	revokeSlotTokensForWc(wcId) {
+		for (const [token, entry] of this.slotTokens) if (entry.authorizedWcId === wcId) this.slotTokens.delete(token);
+	}
+	handleSubWindowClosed(win, wc) {
+		this.trackedWindows.delete(win);
+		this.windowSubstrates.delete(wc);
+		this.revokeSlotTokensForWc(wc.id);
+		const shadowEntry = this.lifetimeShadow.get(wc);
+		if (shadowEntry) {
+			this.lifetimeShadow.delete(wc);
+			this.revokeWindowTrust(shadowEntry.windowScope);
+			shadowEntry.windowScope.close();
+		}
+		for (const [key, w] of this.declaredWindows) if (w === win) {
+			this.declaredWindows.delete(key);
+			break;
+		}
+		this.backendTrustDisposables.get(wc)?.dispose();
+		this.emitFrameworkEvent("window-closed", { window: win });
+	}
+	/**
+	* v2 — notify the backend that the framework has edge-trusted one of its
+	* (framework-built) webContents, so the backend can mirror it into the domain
+	* trust set. The returned Disposable is disposed when THAT window closes
+	* ({@link handleSubWindowClosed}) — honouring the contract "framework disposes
+	* on untrust / window destroy" — and is also added to the registry as a
+	* teardown safety net (e.g. the main window, which dies with the app). The
+	* wrapper is one-shot so the two paths don't double-dispose.
+	*/
+	_notifyBackendTrusted(wc) {
+		const hook = this.options.backend?.onWindowTrusted;
+		if (!hook) return;
+		const d = hook(wc);
+		if (!d) return;
+		const key = wc;
+		let disposed = false;
+		const once = { dispose: () => {
+			if (disposed) return;
+			disposed = true;
+			this.backendTrustDisposables.delete(key);
+			d.dispose();
+		} };
+		this.backendTrustDisposables.set(key, once);
+		this.registry.add(once);
+	}
+	emitFrameworkEvent(event, payload) {
+		const set = this.fwListeners.get(event);
+		if (!set || set.size === 0) return;
+		for (const fn of Array.from(set)) try {
+			fn(payload);
+		} catch (err) {
+			console.error(`[electron-deck] framework listener for "${event}" threw:`, err);
+		}
+	}
+	async cleanupOnError() {
+		this.lifecycle._force("cleanup");
+		await this.runShutdownCleanup();
+		this.lifecycle._force("destroy");
+		this.lifecycle._force("quit");
+	}
+	async doShutdown() {
+		if (this.lifecycle.current === "quit") return;
+		if (this.lifecycle.current === "ready") {
+			this.lifecycle.enter("drain");
+			this.lifecycle.enter("cleanup");
+		} else this.lifecycle._force("cleanup");
+		await this.runShutdownCleanup();
+		this.lifecycle._force("destroy");
+		this.lifecycle._force("quit");
+		if (!this.quitInitiated) try {
+			this.options.electron?.app?.quit();
+		} catch (e) {
+			console.error("[electron-deck] app.quit() failed:", e);
+		}
+	}
+	runShutdownCleanup() {
+		if (this.cleanupPromise) return this.cleanupPromise;
+		this.cleanupPromise = this.doShutdownCleanup();
+		return this.cleanupPromise;
+	}
+	async doShutdownCleanup() {
+		if (this.config.lifecycle?.beforeClose) {
+			const timeoutMs = this.config.lifecycle.timeoutMs ?? 1e4;
+			try {
+				await runWithTimeout(this.config.lifecycle.beforeClose(), timeoutMs);
+			} catch (e) {
+				console.error("[electron-deck] lifecycle.beforeClose failed/timed out:", e);
+			}
+		}
+		const onShutdown = this.options.backend?.onShutdown;
+		if (onShutdown) try {
+			await onShutdown.call(this.options.backend);
+		} catch (e) {
+			console.error("[electron-deck] backend.onShutdown failed:", e);
+		}
+		await this.rootScope.close();
+		this.mainWindow = null;
+		this.toolbarView = null;
+		this.trackedWindows.clear();
+		this.declaredWindows.clear();
+		this.lifetimeShadow.clear();
+		this.windowSubstrates.clear();
+		this.adoptedWindows.clear();
+		this.wcRecords.clear();
+		this.slotTokens.clear();
+		this.keepAliveGroups.clear();
+	}
+	buildRuntime() {
+		const { ipc, registry, fwListeners } = this;
+		const electronModule = this.options.electron;
+		const wireIpcMain = this.options.wireTransport?.ipcMain;
+		const electronUnavailable = (field) => {
+			throw new Error(`runtime.${field} is unavailable in this build (no Electron)`);
+		};
+		const rawIpcMainUnavailable = () => {
+			throw new Error("runtime.rawIpcMain is unavailable (no wireTransport.ipcMain injected)");
+		};
+		const context = {
+			settings: { theme: "light" },
+			theme: "light",
+			_registry: this.registry,
+			_senderPolicy: this.wireSenderPolicy ?? { isTrusted: () => false }
+		};
+		const trackedWindows = this.trackedWindows;
+		const declaredWindows = this.declaredWindows;
+		const getMainWindow = () => this.mainWindow;
+		const getToolbarView = () => this.toolbarView;
+		const constructWindow = (opts, autoTrust) => {
+			const win = this.constructWindow(opts, autoTrust);
+			this.emitFrameworkEvent("window-created", {
+				window: win,
+				role: "host"
+			});
+			return win;
+		};
+		const getMainDeckWindow = () => {
+			if (!this.mainControlWc) return null;
+			return this.windowRegistrations.get(this.mainControlWc)?.deckWindow ?? null;
+		};
+		const emitPendingFor = (event) => {
+			if (event === "window-created") {
+				if (this.pendingWindowCreated.length === 0) return;
+				const queue = this.pendingWindowCreated.splice(0);
+				for (const item of queue) this.emitFrameworkEvent("window-created", {
+					window: item.window,
+					role: item.role
+				});
+			} else if (event === "load-failed") {
+				if (this.pendingLoadFailed.length === 0) return;
+				const queue = this.pendingLoadFailed.splice(0);
+				for (const item of queue) this.emitFrameworkEvent("load-failed", {
+					source: item.source,
+					error: item.error
+				});
+			}
+		};
+		return {
+			get electron() {
+				if (!electronModule) return electronUnavailable("electron");
+				return electronModule;
+			},
+			get mainWindow() {
+				const mw = getMainWindow();
+				if (!mw) return electronUnavailable("mainWindow");
+				return mw;
+			},
+			get toolbarView() {
+				return getToolbarView() ?? null;
+			},
+			ipc,
+			get rawIpcMain() {
+				if (!wireIpcMain) return rawIpcMainUnavailable();
+				return wireIpcMain;
+			},
+			call: {
+				simulator: async (name, ...args) => ipc.invoke(`${SIMULATOR_CHANNEL_PREFIX}${name}`, ...args),
+				host: async (name, ...args) => ipc.invoke(`${HOST_CHANNEL_PREFIX}${name}`, ...args)
+			},
+			windows: {
+				create: (opts) => {
+					if (!electronModule) return electronUnavailable("windows.create");
+					const wc = constructWindow(opts, opts.autoTrust ?? true).webContents;
+					const reg = this.windowRegistrations.get(wc);
+					if (!reg) throw new Error("runtime.windows.create: DeckWindow registration missing (internal invariant)");
+					return reg.deckWindow;
+				},
+				get main() {
+					return getMainDeckWindow();
+				},
+				get: (id) => {
+					const w = declaredWindows.get(id);
+					return w ? w : void 0;
+				},
+				all: () => {
+					const result = [];
+					for (const w of trackedWindows) if (!w.isDestroyed()) result.push(w);
+					return result;
+				},
+				trust: (win) => {
+					const wc = win.webContents;
+					const tracked = this.lifetimeShadow.get(wc);
+					if (tracked) {
+						const lease = this.admitTrust(wc, tracked.windowScope);
+						this.bindNavigationGrantReset(wc);
+						return lease;
+					}
+					return this._trustWebContents(wc);
+				},
+				adopt: (win, opts) => {
+					const w = win;
+					return this.adoptWindow(w, opts);
+				}
+			},
+			view: (opts) => {
+				if (!electronModule) return electronUnavailable("view");
+				let displayScope = this.rootScope;
+				if (opts.scope !== void 0) {
+					const resolved = this.sessions.get(opts.scope);
+					if (!resolved) throw new Error("runtime.view: `scope` must be a DeckSession from runtime.scopes.create() (a foreign/raw Scope is rejected)");
+					displayScope = resolved;
+				}
+				const wcv = new electronModule.WebContentsView({});
+				this.safeLoad(wcv.webContents, opts.source);
+				const viewId = `view:${++this.viewSeq}`;
+				let rootCloseReg = null;
+				let rootCloseDisarmed = false;
+				const disarmRootClose = () => {
+					rootCloseDisarmed = true;
+					rootCloseReg?.dispose();
+					rootCloseReg = null;
+				};
+				if (displayScope === this.rootScope) rootCloseReg = this.rootScope.own(() => {
+					if (rootCloseDisarmed) return;
+					const wc = wcv.webContents;
+					if (wc && !wc.isDestroyed()) wc.close?.();
+				});
+				const closeNativeWc = () => {
+					const wc = wcv.webContents;
+					if (wc && !wc.isDestroyed()) wc.close?.();
+				};
+				const nativeView = {
+					ref: { id: viewId },
+					setBounds: (b) => wcv.setBounds(b),
+					destroy: closeNativeWc,
+					webContents: wcv.webContents,
+					capturePage: () => {
+						const wc = wcv.webContents;
+						if (!wc || wc.isDestroyed?.()) return Promise.reject(/* @__PURE__ */ new Error("ViewHandle.capturePage: native view destroyed"));
+						return wc.capturePage();
+					}
+				};
+				const keepAlive = opts.keepAlive;
+				const keepAliveMaxValid = keepAlive ? Number.isInteger(keepAlive.max) && keepAlive.max >= 0 : false;
+				if (keepAlive && !keepAliveMaxValid) this.warnInvalidKeepAliveMax(keepAlive.max);
+				const groupKey = keepAlive && keepAliveMaxValid ? `lru:${keepAlive.max}` : null;
+				const keepAliveGroup = () => {
+					let g = this.keepAliveGroups.get(groupKey);
+					if (!g) {
+						g = {
+							hidden: [],
+							handles: /* @__PURE__ */ new Map()
+						};
+						this.keepAliveGroups.set(groupKey, g);
+					}
+					return g;
+				};
+				const removeFromKeepAliveGroup = (id) => {
+					if (!groupKey) return;
+					const group = this.keepAliveGroups.get(groupKey);
+					if (!group) return;
+					group.handles.delete(id);
+					const i = group.hidden.indexOf(id);
+					if (i >= 0) group.hidden.splice(i, 1);
+					if (group.handles.size === 0) this.keepAliveGroups.delete(groupKey);
+				};
+				const inner = createViewHandle({
+					nativeView,
+					scope: displayScope,
+					onDispose: () => removeFromKeepAliveGroup(viewId)
+				});
+				let placedSubstrate = null;
+				let slotToken;
+				let placed = false;
+				const mintSlotToken = (controlWc, anchor) => {
+					this.ensureSlotChannelsArmed();
+					const authorizedWcId = controlWc.id;
+					const token = randomUUID();
+					slotToken = token;
+					++this.slotSeq;
+					const grant = {
+						viewId,
+						slotId: anchor,
+						slotToken: token
+					};
+					const resend = () => {
+						controlWc.send(DeckChannel.SlotGrant, grant);
+					};
+					this.slotTokens.set(token, {
+						viewId,
+						slotId: anchor,
+						authorizedWcId,
+						resend,
+						apply: (p) => {
+							hostHandle.applyPlacement(p);
+						}
+					});
+					resend();
+				};
+				const hostHandle = {
+					placeIn: (win, placeOpts) => {
+						if (placed) throw new Error("DeckViewHandle.placeIn: view already placed — use moveTo() to migrate");
+						const controlWc = this.resolveWindowArg(win).webContents;
+						const wc = controlWc;
+						const substrate = this.windowSubstrates.get(wc);
+						if (!substrate) throw new Error("runtime.view().placeIn: window is not framework-tracked");
+						substrate.registerView(viewId, wcv);
+						placedSubstrate = substrate;
+						inner.placeIn({
+							compositor: substrate.compositor,
+							windowScope: substrate.windowScope
+						}, { zone: placeOpts.zone });
+						placed = true;
+						disarmRootClose();
+						const anchor = placeOpts.anchor;
+						if (typeof anchor === "string" && anchor.length > 0) mintSlotToken(controlWc, anchor);
+						return hostHandle;
+					},
+					moveTo: async (win, moveOpts) => {
+						const destWin = this.resolveWindowArg(win);
+						const destControlWc = destWin.webContents;
+						const destWc = destControlWc;
+						const destSub = this.windowSubstrates.get(destWc);
+						if (!destSub) throw new Error("runtime.view().moveTo: window is not framework-tracked");
+						const srcSub = placedSubstrate;
+						destSub.registerView(viewId, wcv);
+						try {
+							await inner.moveTo({
+								compositor: destSub.compositor,
+								windowScope: destSub.windowScope
+							}, {
+								zone: moveOpts.zone,
+								rehome: moveOpts.rehome
+							});
+						} catch (e) {
+							try {
+								if (!destWin.isDestroyed()) {
+									const destChildren = destWin.contentView.children;
+									if (destChildren == null || destChildren.includes(wcv)) destWin.contentView.removeChildView(wcv);
+								}
+							} catch (cleanupErr) {
+								console.error("[electron-deck] moveTo dest detach failed (original error rethrown):", cleanupErr);
+							}
+							try {
+								destSub.unregisterView(viewId);
+							} catch (cleanupErr) {
+								console.error("[electron-deck] moveTo dest unregister failed (original error rethrown):", cleanupErr);
+							}
+							throw e;
+						}
+						if (srcSub && srcSub !== destSub) srcSub.unregisterView(viewId);
+						placedSubstrate = destSub;
+						if (groupKey) {
+							const group = this.keepAliveGroups.get(groupKey);
+							if (group) {
+								const hi = group.hidden.indexOf(viewId);
+								if (hi >= 0) group.hidden.splice(hi, 1);
+							}
+						}
+						if (slotToken) {
+							this.slotTokens.delete(slotToken);
+							slotToken = void 0;
+						}
+						const anchor = moveOpts.anchor;
+						if (typeof anchor === "string" && anchor.length > 0) mintSlotToken(destControlWc, anchor);
+					},
+					applyPlacement: (p) => {
+						inner.applyPlacement(p);
+						if (groupKey) {
+							const group = keepAliveGroup();
+							const dropFromHidden = () => {
+								const i = group.hidden.indexOf(viewId);
+								if (i >= 0) group.hidden.splice(i, 1);
+							};
+							if (p.visible) dropFromHidden();
+							else {
+								if (!group.hidden.includes(viewId)) group.hidden.push(viewId);
+								while (keepAlive && group.hidden.length > keepAlive.max) {
+									const victimId = group.hidden.shift();
+									const victim = group.handles.get(victimId);
+									if (victim) victim.dispose();
+								}
+							}
+						}
+						return hostHandle;
+					},
+					dispose: async () => {
+						await inner.dispose();
+						disarmRootClose();
+						closeNativeWc();
+						placedSubstrate?.unregisterView(viewId);
+						if (slotToken) this.slotTokens.delete(slotToken);
+						removeFromKeepAliveGroup(viewId);
+					},
+					get webContents() {
+						return inner.webContents;
+					},
+					bounds: () => inner.bounds(),
+					capturePage: () => inner.capturePage()
+				};
+				if (groupKey) keepAliveGroup().handles.set(viewId, hostHandle);
+				if (displayScope !== this.rootScope) displayScope.own(() => hostHandle.dispose().catch((e) => {
+					console.error("[electron-deck] view session-scope dispose failed:", e);
+				}));
+				return hostHandle;
+			},
+			scopes: { create: () => {
+				const scope = this.rootScope.child();
+				const session = {
+					reset: () => scope.reset(),
+					dispose: () => scope.close()
+				};
+				this.sessions.set(session, scope);
+				return session;
+			} },
+			grants: { issue: (controlWc, opts) => {
+				const wc = controlWc;
+				const rec = this.wcRecords.get(wc);
+				if (!rec) throw new Error("runtime.grants.issue: webContents is not trusted (no wcScope to bind the grant to)");
+				const targetScope = opts.targetScope ? this.sessions.get(opts.targetScope) : void 0;
+				return this.capability.issue({
+					senderId: wc.id,
+					senderScope: rec.wcScope,
+					targetScope,
+					commands: new Set(opts.commands)
+				});
+			} },
+			layout: { command: (name, handler) => {
+				if (!name.startsWith("layout.")) throw new Error(`runtime.layout.command: privileged command names must start with "layout." (got: ${name})`);
+				return this.controlBus.command(name, handler);
+			} },
+			context,
+			on: (event, listener) => {
+				let set = fwListeners.get(event);
+				const isFirst = !set;
+				if (!set) {
+					set = /* @__PURE__ */ new Set();
+					fwListeners.set(event, set);
+				}
+				const cast = listener;
+				set.add(cast);
+				if (isFirst) emitPendingFor(event);
+				const ref = set;
+				return { dispose: () => {
+					ref.delete(cast);
+				} };
+			},
+			add: (d) => registry.add(d)
+		};
+	}
+};
+/**
+* Validate an inbound `__electron-deck:place` placement before applying it.
+* `{visible:false}` is always OK; `{visible:true, bounds:{x,y,width,height}}`
+* requires width≥0 && height≥0 — x/y may be ANY finite number (negative origin
+* is legitimate for scroll-follow). Anything else is rejected.
+*/
+function isValidPlacement(placement) {
+	if (placement === null || typeof placement !== "object") return false;
+	const p = placement;
+	if (p.visible === false) return true;
+	if (p.visible !== true) return false;
+	const b = p.bounds;
+	if (b === null || typeof b !== "object") return false;
+	const { x, y, width, height } = b;
+	if (typeof x !== "number" || !Number.isFinite(x)) return false;
+	if (typeof y !== "number" || !Number.isFinite(y)) return false;
+	if (typeof width !== "number" || !Number.isFinite(width) || width < 0) return false;
+	if (typeof height !== "number" || !Number.isFinite(height) || height < 0) return false;
+	return true;
+}
+async function runWithTimeout(work, timeoutMs) {
+	let timer;
+	const timeout = new Promise((_, rej) => {
+		timer = setTimeout(() => rej(/* @__PURE__ */ new Error(`timed out after ${timeoutMs}ms`)), timeoutMs);
+	});
+	try {
+		return await Promise.race([Promise.resolve(work), timeout]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+//#endregion
+//#region src/electron-deck.ts
+/**
+* `electronDeck(config, options?)` 是 framework 唯一入口（见 README §3）。
+*
+* - Invalid config → reject `TypeError`，phase 不前进
+* - Valid config → 装配 runtime + 调 `config.setup(runtime)` await 完成 →
+*   resolve。Phase 2 不接 Electron，resolve 后 framework 仍持有运行时；
+*   Phase 4 接 Electron app lifecycle 后，由 Electron event loop 撑住进程，
+*   `electronDeck()` 同样 resolve（host 的 main 文件不需 await 阻塞）。
+*
+* backend host（如 devtools）走 `electronDeck({ backend })`——backend 是
+* {@link DeckConfig} 的字段，不再需要空 `{}` + options。
+*
+* `options` 是测试 / 非 Electron 环境用的注入点（见 {@link DeckOptions}）。
+* 生产路径不传 options：framework `await import('electron')` 取真 `ipcMain` /
+* `BrowserWindow` / `WebContentsView`。
+*/
+async function electronDeck(config, options) {
+	validateConfig(config);
+	const resolved = await resolveAppOptions(options);
+	if (config.backend) resolved.backend = config.backend;
+	await new DeckApp(config, resolved).start();
+}
+/**
+* Synchronous launch handle for `electronDeck`.
+*
+* `electronDeck(config)` is `async` and internally `await app.start()` →
+* `await app.whenReady()`. A host ESM main entry doing `await electronDeck(config)`
+* SUSPENDS module evaluation on the whenReady gate — but Electron's `ready` only
+* fires once module evaluation finishes, so the gate never resolves: HARD DEADLOCK.
+*
+* `startElectronDeck` returns a plain handle SYNCHRONOUSLY (NOT a thenable), so a
+* host's top-level `await handle.ready` never sits on the whenReady gate. Assembly
+* still runs STRICTLY AFTER `app.whenReady()` resolves (gating intact inside
+* `app.start()`); `handle.ready` resolves with the {@link Runtime}; `handle.dispose()`
+* tears the app down even if called before the in-flight start finished.
+*
+* Invalid config throws a `TypeError` synchronously (matching `electronDeck`'s
+* validate-first contract) — the error surfaces, never silently deadlocks.
+*/
+function startElectronDeck(config, options) {
+	validateConfig(config);
+	let app = null;
+	const startPromise = (async () => {
+		const resolved = await resolveAppOptions(options);
+		if (config.backend) resolved.backend = config.backend;
+		app = new DeckApp(config, resolved);
+		await app.start();
+		return app;
+	})();
+	const ready = startPromise.then((a) => a.runtime);
+	ready.catch(() => {});
+	return {
+		ready,
+		async dispose() {
+			const started = await startPromise.catch(() => null);
+			if (started) await started.shutdown();
+			else if (app) await app.shutdown();
+		}
+	};
+}
+/**
+* 把公共 `DeckOptions` 解析成 internal {@link DeckAppOptions} —— 在
+* 显式注入不足时 lazy `import('electron')` 兜底。
+*
+* 决策 matrix：
+* - `electron` + `ipcMain` 都显式注入 → 不 lazy import（测试 / production override）
+* - 任一缺失 → `await import('electron')`，用 imported module 兜底缺失字段
+*
+* vitest 下 `await import('electron')` 解析到安装包 entry stub（导出可执行路径
+* 字符串），所以 `ipcMain` / `BrowserWindow` 都是 undefined。我们检测到关键
+* 字段缺失会显式 reject，提示注入 options。
+*/
+async function resolveAppOptions(opts) {
+	if (opts?.electron && opts?.ipcMain) return buildAppOptions(opts.electron, opts.ipcMain, opts);
+	let imported;
+	try {
+		imported = await import("electron");
+	} catch (e) {
+		throw new Error("electronDeck(): unable to load electron — pass options.electron / options.ipcMain for non-Electron environments. Underlying: " + String(e), { cause: e });
+	}
+	const m = imported;
+	const resolvedElectron = opts?.electron ?? asMinimalElectron(m);
+	const resolvedIpcMain = opts?.ipcMain ?? m.ipcMain;
+	if (!resolvedIpcMain || !resolvedElectron.BrowserWindow || !resolvedElectron.WebContentsView) throw new Error("electronDeck(): loaded \"electron\" but it does not expose the main-process surface (ipcMain / BrowserWindow / WebContentsView). This typically means you are running outside an Electron main process (e.g. vitest under node). Pass options.electron and options.ipcMain to inject a fake.");
+	return buildAppOptions(resolvedElectron, resolvedIpcMain, opts);
+}
+function asMinimalElectron(m) {
+	return m;
+}
+function buildAppOptions(electron, ipcMain, opts) {
+	const out = {
+		electron,
+		wireTransport: { ipcMain }
+	};
+	if (opts?.trustedWebContents) out.wireTransport.trustedWebContents = opts.trustedWebContents;
+	if (opts?.senderPolicy) out.wireTransport.senderPolicy = opts.senderPolicy;
+	return out;
+}
+/**
+* Pure validation：不依赖 Electron / IPC / 任何 framework state，可单独 unit
+* test。每一条检查对应 doc §3.3 字段约束。
+*
+* 验证语义保证：通过 validateConfig 的 config 不会在 framework Bind 阶段被拒。
+* 含 HostEvent 来源、source 互斥、map vs array 等所有"shape 就绪"检查。
+*
+* @internal exported for tests
+*/
+function validateConfig(config) {
+	if (config === null || typeof config !== "object") throw new TypeError("electronDeck(config): config must be an object");
+	if (config.backend !== void 0) {
+		const backend = config.backend;
+		if (backend === null || typeof backend !== "object" || typeof backend.assemble !== "function") throw new TypeError("config.backend must be a RuntimeBackend (an object with an assemble() function)");
+	}
+	if (config.simulatorApis !== void 0) validateHandlerMap("simulatorApis", config.simulatorApis);
+	if (config.hostServices !== void 0) validateHandlerMap("hostServices", config.hostServices);
+	if (config.events !== void 0) {
+		if (!Array.isArray(config.events)) throw new TypeError("events must be an array of HostEvent (from defineEvent())");
+		for (const ev of config.events) if (!isHostEvent(ev)) throw new TypeError("events: every entry must be a HostEvent produced by defineEvent() — duck-typed shapes are rejected to avoid bind-time failures");
+		const names = /* @__PURE__ */ new Set();
+		for (const ev of config.events) {
+			if (names.has(ev.name)) throw new Error(`events: duplicate HostEvent name "${ev.name}"`);
+			names.add(ev.name);
+		}
+	}
+	if (config.toolbar !== void 0) {
+		const { source, preloadPath, height } = config.toolbar;
+		if (source === null || typeof source !== "object") throw new TypeError("toolbar.source must be { url } or { file }");
+		const hasUrl = "url" in source && typeof source.url === "string";
+		const hasFile = "file" in source && typeof source.file === "string";
+		if (hasUrl && hasFile) throw new TypeError("toolbar.source must be either { url } or { file }, not both");
+		if (!hasUrl && !hasFile) throw new TypeError("toolbar.source must be { url } or { file }");
+		if (typeof preloadPath !== "string" || preloadPath.length === 0) throw new TypeError("toolbar.preloadPath is required and must be a non-empty string");
+		if (typeof height !== "number" || !Number.isFinite(height) || height <= 0) throw new TypeError("toolbar.height is required and must be a positive finite number");
+	}
+}
+function validateHandlerMap(fieldName, value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${fieldName} must be an object of handlers`);
+	for (const [name, handler] of Object.entries(value)) if (typeof handler !== "function") throw new TypeError(`${fieldName}["${name}"] must be a function`);
+}
+//#endregion
+export { WireTransport as a, InMemoryTypedIpcRegistry as c, createControlBus as i, EventBus as l, startElectronDeck as n, createCapabilityRegistry as o, validateConfig as r, createTrustSet as s, electronDeck as t, defineEvent as u };
+
+//# sourceMappingURL=electron-deck-DfFKeFEC.js.map