@dimina-kit/electron-deck 0.1.0-dev.20260616102751 → 0.1.0-dev.20260624040247

package/dist/{electron-deck-DfFKeFEC.js → electron-deck-C9_Yu3fd.js}

@@ -363,7 +363,7 @@ function createCapabilityRegistry() {
 //#endregion
 //#region src/internal/wire-transport.ts
 /**
-* WireTransport — main 端的真 Electron wire 桥接（Phase 3b）。
+* WireTransport — main 端的真 Electron wire 桥接。
 *
 * 责任：
 * - 在 `ipcMain.handle('__electron-deck:invoke')` / `'__electron-deck:probe'` 上路由
@@ -388,7 +388,7 @@ var DECK_CODE = {
 	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. */
+	/** The grant gate denied a privileged command for this sender. */
 	Forbidden: "DECK_FORBIDDEN"
 };
 var WireTransport = class {
@@ -766,8 +766,8 @@ 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
+* 形态，便于测试驱动 lifecycle 转换。加 wireTransport 注入
+* 后可接真 ipcMain；加 electron 注入后可装配 mainWindow / toolbarView
 * / declared windows。两者都不注入时退化为同进程内存 fake。
 *
 * @internal
@@ -780,21 +780,21 @@ var DeckApp = class {
 	ipc = new InMemoryTypedIpcRegistry();
 	fwListeners = /* @__PURE__ */ new Map();
 	trustSet = createTrustSet();
-	/** P4 Phase B — privileged-command grant registry. The policy gates
+	/** 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.*`
+	/** 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
+	/** 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
+	/** The live wire senderPolicy, reused by buildRuntime so
 	*  `context._senderPolicy` reflects real trust instead of a `() => true` stub. */
 	wireSenderPolicy = null;
 	mainWindow = null;
@@ -802,23 +802,19 @@ var DeckApp = class {
 	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
+	* The root lifetime scope of the app + a shadow map mirroring `trackedWindows`,
+	* keyed by each window's webContents, carrying a per-window child Scope. 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
+	* 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`.
+	* the wc leaves the trust set.
 	* A wc can be trusted more than once (framework auto-trust + host
 	* `windows.trust`), so `leases` is a Set.
 	*/
@@ -826,13 +822,13 @@ var DeckApp = class {
 	pendingWindowCreated = [];
 	pendingLoadFailed = [];
 	/**
-	* host-view slice 1 — per-window native-view substrate, keyed by the window's
+	* 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
+	* 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
@@ -840,7 +836,7 @@ var DeckApp = class {
 	*/
 	adoptedWindows = /* @__PURE__ */ new Map();
 	/**
-	* C1/C4 — per-registered-window {@link DeckWindow} facade + its per-window
+	* 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
@@ -848,13 +844,13 @@ var DeckApp = class {
 	* decision latch (mirrors the main-window `closingDecisionPromise`).
 	*/
 	windowRegistrations = /* @__PURE__ */ new Map();
-	/** C1 — the framework-built main window's control wc, so `runtime.windows.main`
+	/** 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. */
+	/** Monotonic id source for `runtime.view` native views. */
 	viewSeq = 0;
 	/**
-	* P2 — provenance map for `runtime.scopes.create()` sessions: maps an opaque
+	* 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`
@@ -863,7 +859,7 @@ var DeckApp = class {
 	*/
 	sessions = /* @__PURE__ */ new WeakMap();
 	/**
-	* keepAlive B3.2 — opt-in per-group LRU of HIDDEN keep-alive views. Group key is
+	* keepAlive「opt-in helper：runtime.view({ keepAlive })」 — 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
@@ -871,13 +867,13 @@ var DeckApp = class {
 	* without `keepAlive` never participate.
 	*/
 	keepAliveGroups = /* @__PURE__ */ new Map();
-	/** C3: wcs that already have the `did-start-navigation` grant-reset hook bound,
+	/** 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):
+	* slot-token registry (view-handle.md「slot-token 握手」/ capability-and-lifecycle.md「anchor slotToken 原子下发」):
 	* 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,
@@ -891,9 +887,9 @@ var DeckApp = class {
 	/** 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). */
+	/** 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
+	/** 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
@@ -998,7 +994,7 @@ var DeckApp = class {
 		return this.shutdownPromise;
 	}
 	/**
-	* @internal Phase 4 windows.trust() / framework 内部添加 trusted webContents.
+	* @internal 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
@@ -1008,14 +1004,14 @@ var DeckApp = class {
 		return this.trustSet.admit(wc, this.rootScope);
 	}
 	/**
-	* unified-lifetime P1b: admit `wc` to the trust set under `windowScope`. Gets
+	* 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.
+	* → ref-count zeroes → the wc leaves the set (driven by Scope teardown,
+	* covering partially-built windows too). Idempotent registry cleanup is owned
+	* by the wcScope.
 	*/
 	admitTrust(wc, windowScope) {
 		if (wc.isDestroyed()) return { dispose: () => {} };
@@ -1044,7 +1040,7 @@ var DeckApp = class {
 		} };
 	}
 	/**
-	* C3 (P0 security) — bind the main-frame cross-document navigation grant-reset
+	* 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
@@ -1071,7 +1067,7 @@ var DeckApp = class {
 		});
 	}
 	/**
-	* C1 — build the {@link DeckWindow} facade over a registered window and record
+	* 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
@@ -1121,7 +1117,7 @@ var DeckApp = class {
 	/**
 	* 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
+	* handle (the `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
@@ -1133,7 +1129,7 @@ var DeckApp = class {
 		return win;
 	}
 	/**
-	* C4 — run a registered window's per-window close deciders (registration order;
+	* 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
@@ -1156,7 +1152,7 @@ var DeckApp = class {
 		return "close";
 	}
 	/**
-	* C4 — arm the per-window cancelable close-decision machine on a CREATED /
+	* 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 +
@@ -1192,26 +1188,26 @@ var DeckApp = class {
 		});
 	}
 	/**
-	* @internal unified-lifetime P0 accessors (observation-only). The live shadow
-	* map mirroring `trackedWindows`, the root Scope, and a consistency assertion.
+	* @internal Lifetime accessors. 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. */
+	/** @internal The root lifetime Scope. */
 	__rootScope() {
 		return this.rootScope;
 	}
-	/** @internal unified-lifetime P1b: the per-trusted-wc trust records. */
+	/** @internal The per-trusted-wc trust records. */
 	__wcRecords() {
 		return this.wcRecords;
 	}
-	/** @internal P4 Phase B: the live capability policy (grant gate reads it). */
+	/** @internal 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
+	* @internal Lifetime invariant: the shadow's per-window set
 	* (the `window` of each entry) must equal `trackedWindows` membership. Throws
 	* if violated; no-op otherwise.
 	*/
@@ -1234,12 +1230,11 @@ var DeckApp = class {
 		}
 	}
 	/**
-	* host-view slice 1 — build a per-window {@link ViewSubstrate}. The
+	* 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.
+	* `win.destroy` own, so LIFO teardown runs detachAll BEFORE destroy.
 	*/
 	createWindowSubstrate(win, windowScope) {
 		const wcvById = /* @__PURE__ */ new Map();
@@ -1407,7 +1402,7 @@ var DeckApp = class {
 			});
 		}
 	}
-	/** Phase 4 race fix：在 wireTransport.start 之后再 loadURL/loadFile。 */
+	/** 在 wireTransport.start 之后再 loadURL/loadFile，避免 preload 先于 ipcMain handler 注册触发 invoke。 */
 	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)) {
@@ -1417,7 +1412,7 @@ var DeckApp = class {
 		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,
+	* 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).
@@ -1485,7 +1480,7 @@ var DeckApp = class {
 		} });
 	}
 	/**
-	* The two-route boundary's privileged-name predicate (§A5-1.2 硬约束). A
+	* The two-route boundary's privileged-name predicate (「两条 invoke 路由的硬边界」). 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`
@@ -1495,7 +1490,7 @@ var DeckApp = class {
 		return name.startsWith("layout.");
 	}
 	/**
-	* KA-4: warn ONCE about an invalid `keepAlive.max` (negative / non-integer /
+	* 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.
 	*/
@@ -1541,7 +1536,7 @@ var DeckApp = class {
 		return win;
 	}
 	/**
-	* P3 — register an EXTERNALLY-created window into the framework so
+	* 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
@@ -1555,7 +1550,7 @@ var DeckApp = class {
 	*     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),
+	*     `prependListener` (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
@@ -1602,12 +1597,11 @@ var DeckApp = class {
 		return registration;
 	}
 	/**
-	* unified-lifetime P1b: synchronously revoke BOTH trust leases AND capability
+	* 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
+	* so both authorizations are gone the instant the window is destroyed,
+	* 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
@@ -1625,8 +1619,8 @@ var DeckApp = class {
 		}
 	}
 	/**
-	* Arm the wire's slot-token inbound channels (idempotent). P5 eager-arm:
-	* called once at framework start() (bindWireTransport, right after
+	* Arm the wire's slot-token inbound channels (idempotent). 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
@@ -1678,7 +1672,7 @@ var DeckApp = class {
 		this.emitFrameworkEvent("window-closed", { window: win });
 	}
 	/**
-	* v2 — notify the backend that the framework has edge-trusted one of its
+	* 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
@@ -2155,8 +2149,8 @@ async function runWithTimeout(work, timeoutMs) {
 *
 * - 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 撑住进程，
+*   resolve。不接 Electron 时，resolve 后 framework 仍持有运行时；
+*   接 Electron app lifecycle 后，由 Electron event loop 撑住进程，
 *   `electronDeck()` 同样 resolve（host 的 main 文件不需 await 阻塞）。
 *
 * backend host（如 devtools）走 `electronDeck({ backend })`——backend 是
@@ -2292,4 +2286,4 @@ function validateHandlerMap(fieldName, value) {
 //#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
+//# sourceMappingURL=electron-deck-C9_Yu3fd.js.map