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

package/dist/main/index.js

@@ -0,0 +1,152 @@
+import { a as createLogger, c as toDisposable, i as createScope, n as CommitError, o as setLogLevel, r as createCompositor, s as DisposableRegistry, t as createViewHandle } from "../view-handle-CR-yWNfr.js";
+//#region src/main/connection.ts
+var log = createLogger("connection");
+var NOOP_DISPOSABLE = { dispose() {} };
+function toDispose(d) {
+	return typeof d === "function" ? d : () => d.dispose();
+}
+function createConnectionRegistry() {
+	const byId = /* @__PURE__ */ new Map();
+	/**
+	* Dispose a resource handed to a dead connection's `own()` — immediately,
+	* exactly once, never delegating to a disposed segment (that would throw).
+	* Both sync throws and async rejections are caught/logged so a late teardown
+	* can never escape as an unhandledRejection in the Electron main process.
+	*/
+	function disposeLate(d) {
+		try {
+			const r = toDispose(d)();
+			if (r && typeof r.then === "function") r.catch((e) => log.error("late own() async disposer rejected", e));
+		} catch (e) {
+			log.error("late own() resource disposer threw", e);
+		}
+	}
+	/**
+	* A connection for an already-destroyed webContents. Not registered, never
+	* alive, never arms a `'destroyed'` hook (it would never fire on a dead wc —
+	* that path would otherwise mint a permanently-alive leaking zombie). `own()`
+	* disposes immediately so callers racing teardown still don't leak.
+	*/
+	function makeDeadConnection(wc) {
+		return {
+			id: wc.id,
+			webContents: wc,
+			get alive() {
+				return false;
+			},
+			own(d) {
+				disposeLate(d);
+				return NOOP_DISPOSABLE;
+			},
+			on() {
+				return NOOP_DISPOSABLE;
+			}
+		};
+	}
+	function build(wc) {
+		const id = wc.id;
+		let segment = new DisposableRegistry();
+		let alive = true;
+		const resetListeners = /* @__PURE__ */ new Set();
+		const closedListeners = /* @__PURE__ */ new Set();
+		function emit(ev) {
+			const set = ev === "reset" ? resetListeners : closedListeners;
+			for (const cb of [...set]) try {
+				cb();
+			} catch (e) {
+				log.error(`listener for "${ev}" threw`, e);
+			}
+		}
+		const connection = {
+			id,
+			webContents: wc,
+			get alive() {
+				return alive;
+			},
+			own(d) {
+				if (!alive) {
+					disposeLate(d);
+					return NOOP_DISPOSABLE;
+				}
+				return segment.add(d);
+			},
+			on(ev, cb) {
+				const set = ev === "reset" ? resetListeners : closedListeners;
+				set.add(cb);
+				let removed = false;
+				return { dispose() {
+					if (removed) return;
+					removed = true;
+					set.delete(cb);
+				} };
+			}
+		};
+		function reset() {
+			if (!alive) return;
+			const old = segment;
+			segment = new DisposableRegistry();
+			old.disposeAll().catch((e) => log.error("reset disposeAll threw", e));
+			emit("reset");
+		}
+		function close() {
+			if (!alive) return;
+			alive = false;
+			byId.delete(id);
+			segment.disposeAll().catch((e) => log.error("close disposeAll threw", e));
+			emit("closed");
+		}
+		wc.once("destroyed", () => {
+			close();
+		});
+		return {
+			connection,
+			reset,
+			close
+		};
+	}
+	function acquire(wc) {
+		const existing = byId.get(wc.id);
+		if (existing) return existing.connection;
+		if (wc.isDestroyed?.()) return makeDeadConnection(wc);
+		const handle = build(wc);
+		byId.set(wc.id, handle);
+		return handle.connection;
+	}
+	function reset(id) {
+		byId.get(id)?.reset();
+	}
+	return {
+		acquire,
+		get: (id) => byId.get(id)?.connection,
+		all: () => [...byId.values()].map((h) => h.connection),
+		reset
+	};
+}
+//#endregion
+//#region src/main/debug-tap.ts
+var DEFAULT_CAPACITY = 1e3;
+function createDebugTap(options = {}) {
+	const enabled = options.enabled ?? false;
+	const capacity = options.capacity && options.capacity > 0 ? Math.floor(options.capacity) : DEFAULT_CAPACITY;
+	let buffer = [];
+	return {
+		get enabled() {
+			return enabled;
+		},
+		record(entry) {
+			if (!enabled) return;
+			buffer.push(entry);
+			if (buffer.length > capacity) buffer.splice(0, buffer.length - capacity);
+		},
+		entries() {
+			return buffer.slice();
+		},
+		clear() {
+			buffer = [];
+		}
+	};
+}
+//#endregion
+export { CommitError, DisposableRegistry, createCompositor, createConnectionRegistry, createDebugTap, createLogger, createScope, createViewHandle, setLogLevel, toDisposable };
+
+//# sourceMappingURL=index.js.map

package/dist/main/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/main/connection.ts","../../src/main/debug-tap.ts"],"sourcesContent":["/**\n * Connection-layer primitive (`Connection` / `ConnectionRegistry`) described in\n * packages/electron-deck/docs/foundation.md §4.\n *\n * A `Connection` is one trusted webContents (keyed by the unforgeable `wc.id`).\n * It holds a single `DisposableRegistry` as its \"lifetime segment\" container.\n * The segment tears down deterministically (LIFO) on hard-destroy\n * (`wc.once('destroyed')`) or soft-reuse (`reset(id)`):\n *   - hard destroy → dispose segment, fire 'closed' once, de-register.\n *   - soft reset   → dispose segment, swap in a fresh registry, fire 'reset',\n *                    connection stays alive & registered.\n *\n * §4.3: the terminal hook is `'destroyed'` (NOT `'render-process-gone'`), and\n * `DisposableRegistry.disposeAll` is async (LIFO) — so close/reset are async.\n */\nimport type { WebContents } from 'electron'\n\nimport { DisposableRegistry, type Disposable } from './disposable.js'\nimport { createLogger } from './logger.js'\n\nconst log = createLogger('connection')\n\nexport interface Connection {\n  readonly id: number\n  readonly webContents: WebContents\n  readonly alive: boolean\n  /** Register a resource cleaned up with the current lifetime segment; the\n   * returned Disposable releases it early. */\n  own(d: Disposable | (() => void)): Disposable\n  /** Connection-level lifecycle events; returns an unsubscribe Disposable. */\n  on(ev: 'reset' | 'closed', cb: () => void): Disposable\n}\n\nexport interface ConnectionRegistry {\n  /** Build/fetch the connection for a (trusted) webContents; idempotent. */\n  acquire(wc: WebContents): Connection\n  get(id: number): Connection | undefined\n  all(): readonly Connection[]\n  /** Soft reuse: dispose the current segment, then swap in a fresh registry. */\n  reset(id: number): void\n}\n\ntype LifecycleEvent = 'reset' | 'closed'\n\nconst NOOP_DISPOSABLE: Disposable = { dispose() {} }\n\nfunction toDispose(d: Disposable | (() => void)): () => void | Promise<void> {\n  return typeof d === 'function' ? d : () => d.dispose()\n}\n\n/** Internal handle so the registry can drive a connection's lifecycle. */\ninterface ConnectionHandle {\n  connection: Connection\n  /** Dispose the current segment and swap in a fresh one; fire 'reset'. */\n  reset(): void\n  /** Terminal close: dispose segment, fire 'closed' once, de-register. */\n  close(): void\n}\n\nexport function createConnectionRegistry(): ConnectionRegistry {\n  const byId = new Map<number, ConnectionHandle>()\n\n  /**\n   * Dispose a resource handed to a dead connection's `own()` — immediately,\n   * exactly once, never delegating to a disposed segment (that would throw).\n   * Both sync throws and async rejections are caught/logged so a late teardown\n   * can never escape as an unhandledRejection in the Electron main process.\n   */\n  function disposeLate(d: Disposable | (() => void)): void {\n    try {\n      const r = toDispose(d)()\n      if (r && typeof (r as Promise<void>).then === 'function') {\n        ;(r as Promise<void>).catch((e) => log.error('late own() async disposer rejected', e))\n      }\n    } catch (e) {\n      log.error('late own() resource disposer threw', e)\n    }\n  }\n\n  /**\n   * A connection for an already-destroyed webContents. Not registered, never\n   * alive, never arms a `'destroyed'` hook (it would never fire on a dead wc —\n   * that path would otherwise mint a permanently-alive leaking zombie). `own()`\n   * disposes immediately so callers racing teardown still don't leak.\n   */\n  function makeDeadConnection(wc: WebContents): Connection {\n    return {\n      id: wc.id,\n      webContents: wc,\n      get alive() {\n        return false\n      },\n      own(d) {\n        disposeLate(d)\n        return NOOP_DISPOSABLE\n      },\n      on() {\n        return NOOP_DISPOSABLE\n      },\n    }\n  }\n\n  function build(wc: WebContents): ConnectionHandle {\n    const id = wc.id\n    // Current lifetime segment. Replaced wholesale on reset (never re-used\n    // after disposeAll, which permanently poisons the instance).\n    let segment = new DisposableRegistry()\n    let alive = true\n\n    const resetListeners = new Set<() => void>()\n    const closedListeners = new Set<() => void>()\n\n    function emit(ev: LifecycleEvent): void {\n      const set = ev === 'reset' ? resetListeners : closedListeners\n      // Isolate faults so one throwing listener can't block the rest (§9).\n      for (const cb of [...set]) {\n        try {\n          cb()\n        } catch (e) {\n          log.error(`listener for \"${ev}\" threw`, e)\n        }\n      }\n    }\n\n    const connection: Connection = {\n      id,\n      webContents: wc,\n      get alive() {\n        return alive\n      },\n      own(d) {\n        // Race safety (§8): after close, do not delegate to the disposed\n        // segment (that throws). Dispose the late resource immediately and\n        // hand back a harmless no-op handle.\n        if (!alive) {\n          disposeLate(d)\n          return NOOP_DISPOSABLE\n        }\n        return segment.add(d)\n      },\n      on(ev, cb) {\n        const set = ev === 'reset' ? resetListeners : closedListeners\n        set.add(cb)\n        let removed = false\n        return {\n          dispose() {\n            if (removed) return\n            removed = true\n            set.delete(cb)\n          },\n        }\n      },\n    }\n\n    function reset(): void {\n      if (!alive) return\n      // Dispose the old segment, then swap in a fresh registry BEFORE firing\n      // 'reset' so any listener (or subsequent own()) sees an open segment.\n      // disposeAll is async; old `own` handles become no-ops because they\n      // reference the now-replaced/released segment.\n      const old = segment\n      segment = new DisposableRegistry()\n      void old.disposeAll().catch((e) => log.error('reset disposeAll threw', e))\n      emit('reset')\n    }\n\n    function close(): void {\n      if (!alive) return\n      alive = false\n      byId.delete(id)\n      void segment.disposeAll().catch((e) => log.error('close disposeAll threw', e))\n      emit('closed')\n    }\n\n    // Hard destroy — the real terminal hook (§4.3). `once` auto-removes and the\n    // `alive` guard inside close() makes repeated triggers idempotent.\n    wc.once('destroyed', () => {\n      close()\n    })\n\n    return { connection, reset, close }\n  }\n\n  function acquire(wc: WebContents): Connection {\n    const existing = byId.get(wc.id)\n    if (existing) return existing.connection\n    // Re-acquiring an already-destroyed wc must not mint a live connection: its\n    // `'destroyed'` event already fired and won't fire again, so the connection\n    // would stay alive & registered forever (zombie + leak). Hand back a dead,\n    // unregistered connection instead.\n    if (wc.isDestroyed?.()) return makeDeadConnection(wc)\n    const handle = build(wc)\n    byId.set(wc.id, handle)\n    return handle.connection\n  }\n\n  function reset(id: number): void {\n    byId.get(id)?.reset()\n  }\n\n  return {\n    acquire,\n    get: (id) => byId.get(id)?.connection,\n    all: () => [...byId.values()].map((h) => h.connection),\n    reset,\n  }\n}\n","/**\n * debugTap (foundation.md §7) — a flag-gated ring buffer for observing an\n * IPC / cross-wc bridge message stream.\n *\n * Hung on a dispatch chokepoint (e.g. bridge-router's SERVICE_INVOKE /\n * RENDER_INVOKE / PUBLISH / API_RESPONSE handlers), it records per-message\n * metadata — connection id / channel / direction / appSession / duration /\n * error — into a bounded ring so a hidden panel (or a test) can inspect the\n * last N messages when debugging the cross-wc state machine.\n *\n * Design constraints:\n *  - Default OFF: `record()` is a near-free no-op when disabled, so the hot\n *    path costs nothing in production unless the flag is set.\n *  - Caller-supplied `ts`: the electron-deck package never calls `Date.now()`\n *    (determinism / resumability), so each entry carries a timestamp the\n *    caller stamps.\n *  - Bounded: a finite ring (default 1000) evicts oldest-first; it never grows\n *    without bound.\n */\n\nexport interface DebugTapEntry {\n  /** Caller-stamped timestamp (ms). The primitive never reads the clock. */\n  ts: number\n  /** The channel / message kind (e.g. 'SERVICE_INVOKE', 'API_RESPONSE'). */\n  channel: string\n  /** Ingress (main received) vs egress (main sent). */\n  direction: 'in' | 'out'\n  /** webContents.id of the connection this message is attributed to. */\n  connectionId?: number\n  /** bridge-router app session this message routes within, if known. */\n  appSessionId?: string\n  /** For request/response pairs: how long the handler took (ms). */\n  durationMs?: number\n  /** Error message if the message produced a failure. */\n  error?: string\n  /** Short human-readable summary of the payload (no large blobs). */\n  summary?: string\n}\n\nexport interface DebugTap {\n  /** Whether recording is on. When false, `record` is a no-op. */\n  readonly enabled: boolean\n  /** Append one entry to the ring (no-op when disabled). */\n  record(entry: DebugTapEntry): void\n  /** Snapshot of buffered entries, oldest → newest. Safe to retain/mutate. */\n  entries(): readonly DebugTapEntry[]\n  /** Empty the ring. */\n  clear(): void\n}\n\nexport interface DebugTapOptions {\n  /** Default false — the tap is OFF unless explicitly enabled. */\n  enabled?: boolean\n  /** Max retained entries; oldest evicted past this. Default 1000. */\n  capacity?: number\n}\n\nconst DEFAULT_CAPACITY = 1000\n\nexport function createDebugTap(options: DebugTapOptions = {}): DebugTap {\n  const enabled = options.enabled ?? false\n  const capacity =\n    options.capacity && options.capacity > 0 ? Math.floor(options.capacity) : DEFAULT_CAPACITY\n\n  // Simple bounded buffer: push to the tail, shift the head when over capacity.\n  // For the modest capacities debugTap targets this is plenty; the hot path is\n  // the disabled no-op, not eviction throughput.\n  let buffer: DebugTapEntry[] = []\n\n  return {\n    get enabled() {\n      return enabled\n    },\n    record(entry: DebugTapEntry): void {\n      if (!enabled) return\n      buffer.push(entry)\n      if (buffer.length > capacity) {\n        buffer.splice(0, buffer.length - capacity)\n      }\n    },\n    entries(): readonly DebugTapEntry[] {\n      // Return a copy so a retained snapshot is stable and callers can't mutate\n      // the live ring.\n      return buffer.slice()\n    },\n    clear(): void {\n      buffer = []\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/main/logger.d.ts

@@ -0,0 +1,15 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Create a tagged logger for a specific module.
+ * All output goes to console with structured prefix.
+ */
+export declare function createLogger(tag: string): Logger;
+export declare function setLogLevel(level: LogLevel): void;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/main/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/main/logger.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AA2BnD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CACjD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAehD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD"}

package/dist/main/scope.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `Scope` — engine-agnostic nested-lifetime primitive, generalizing the
+ * Connection/Disposable semantics in this package (foundation.md §4).
+ *
+ * A `Scope` owns a single "lifetime segment". Resources bound via `own()` and
+ * sub-scopes created via `child()` are released together — both on `reset()`
+ * (soft reuse: dispose the segment, open a fresh one, stay alive) and `close()`
+ * (terminal: dispose everything, die). Teardown is LIFO and, crucially,
+ * `reset()`/`close()` are COMPLETION FENCES: their Promise resolves (and the
+ * `'reset'`/`'closed'` listeners fire) only AFTER the underlying async
+ * disposeAll has fully finished — unlike `connection.ts`, which fires the
+ * teardown and forgets (`void ...disposeAll()`).
+ *
+ * Cross-layer LIFO: a scope's teardown disposes its child sub-scopes (deepest
+ * first, recursively) BEFORE its own directly-owned resources, so a grandchild
+ * tears down before a child, which tears down before the root.
+ */
+import { type Disposable } from './disposable.js';
+export interface Scope {
+    readonly alive: boolean;
+    /** Bind a resource to the current lifetime segment; released by both reset()
+     * and close() (LIFO). The returned Disposable releases it early (once). After
+     * the scope is closed, the resource is disposed immediately (leak protection)
+     * and a no-op handle is returned. */
+    own(d: Disposable | (() => void)): Disposable;
+    /** Create a sub-scope bound to the current segment: a parent reset()/close()
+     * cascades into it. A child close() does not affect the parent. */
+    child(): Scope;
+    /** Soft reuse: await LIFO disposeAll of the current segment (children first,
+     * then owned resources — async disposers truly complete), THEN open a fresh
+     * segment and fire 'reset'. Scope stays alive. */
+    reset(): Promise<void>;
+    /** Terminal: await LIFO disposeAll of the segment, mark dead, fire 'closed'
+     * once. Idempotent. */
+    close(): Promise<void>;
+    /** Subscribe to a lifecycle event; returns an unsubscribe Disposable. */
+    on(event: 'reset' | 'closed', cb: () => void): Disposable;
+    /**
+     * Re-parent `child` from THIS scope's current segment onto `newParent`'s
+     * current segment WITHOUT resetting or closing it. The child's own()ed
+     * resources stay live and neither 'reset' nor 'closed' fire on it; only the
+     * cascade ownership moves (who tears it down from now on).
+     *
+     * If `this` or `newParent` has a teardown in flight, adopt WAITS for that
+     * fence (it does not throw), then re-reads/re-validates against the fresh
+     * segment. Validation failures (dead this/newParent, non-direct-child, cycle)
+     * reject. On every path the child stays attached to EXACTLY one segment.
+     */
+    adopt(child: Scope, newParent: Scope): Promise<void>;
+}
+export declare function createScope(): Scope;
+//# sourceMappingURL=scope.d.ts.map

package/dist/main/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/main/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAsB,KAAK,UAAU,EAAkB,MAAM,iBAAiB,CAAA;AAKrF,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB;;;yCAGqC;IACrC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,UAAU,CAAA;IAC7C;uEACmE;IACnE,KAAK,IAAI,KAAK,CAAA;IACd;;sDAEkD;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB;2BACuB;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,yEAAyE;IACzE,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,UAAU,CAAA;IACzD;;;;;;;;;;OAUG;IACH,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrD;AAgGD,wBAAgB,WAAW,IAAI,KAAK,CA0SnC"}

package/dist/main/view-handle.d.ts

@@ -0,0 +1,131 @@
+/**
+ * `ViewHandle` — the per-view orchestrator (build-plan §2(a)/(b)/(d)). One handle
+ * owns ONE native view and threads it through a window's z-planner. It composes
+ * three INJECTED primitives and nothing else (no deck-app, no Electron):
+ *   - a {@link NativeView} (its `ref` + a `setBounds` sink) — the native surface;
+ *   - a {@link Scope} (`deps.scope`) — the view's home/native-view lifetime;
+ *   - a {@link PlaceTarget} = `{ compositor, windowScope }` — a window's
+ *     z-planner + lifetime, handed to {@link ViewHandle.placeIn}.
+ *
+ * Lifetime. `placeIn` adopts a `viewScope` that is a CHILD of the target
+ * window's `windowScope`, so closing the windowScope cascades into the handle
+ * (scope.ts cross-layer LIFO): the native view is detached and the placement
+ * sink goes inert.
+ *
+ * gap#1. The handle drives `setBounds` DIRECTLY on its native view; the
+ * Compositor stays a pure z-order planner (mount/unmount/commit only) and never
+ * sees geometry.
+ *
+ * A4 teardown order (build-plan §2(b)). The viewScope owns the native detach
+ * FIRST and the sink-disable LAST, so LIFO teardown runs the sink-disable
+ * (STEP0) BEFORE the detach (STEP1): a late `place` frame can never drive a
+ * native effect on a half-torn-down view.
+ *
+ * Cross-window move (build-plan §2(d) / A1.3.2). {@link ViewHandle.moveTo}
+ * migrates the view to another `{ compositor, windowScope }` as TWO independent
+ * Compositor commits, guarded by a per-view async mutex (THE migrationLock —
+ * each handle is one view). The current placement is a MUTABLE token so the
+ * detach `own()` and `applyPlacement` always follow the CURRENT window after a
+ * move. `rehome:true` re-parents the viewScope via {@link Scope.adopt} so
+ * lifetime follows display; without it, lifetime stays under the src window.
+ */
+import type { Scope } from './scope.js';
+import type { Compositor, NativeViewRef } from './compositor.js';
+/** A screen-space rectangle, in CSS px. Mirrors `@dimina-kit/view-anchor`'s
+ *  `Bounds` (electron-deck does not depend on view-anchor in this increment). */
+export interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Explicit visibility + geometry for a native view. Structurally identical to
+ * the `@dimina-kit/view-anchor` `Placement` export; mirrored locally so this
+ * increment adds no new package dependency.
+ */
+export type Placement = {
+    visible: true;
+    bounds: Bounds;
+} | {
+    visible: false;
+};
+/** The native surface a handle drives: its z-order identity (`ref`) plus the
+ *  `setBounds` sink the handle calls directly (gap#1). `destroy` (optional)
+ *  destroys the backing native view (its WebContents) — owned by the viewScope so
+ *  it runs on teardown AFTER the detach (keepAlive B3.1 lifetime/leak fix).
+ *  Optional so fakes that don't model a native WebContents stay valid.
+ *
+ *  `webContents` / `capturePage` (optional) expose the backing native view's
+ *  WebContents and a screenshot pass-through, so a handle accessor can recover
+ *  them without re-deriving the WebContentsView from the window's content view.
+ *  Optional so geometry-only fakes stay valid. */
+export interface NativeView {
+    readonly ref: NativeViewRef;
+    setBounds(b: Bounds): void;
+    destroy?(): void;
+    readonly webContents?: unknown;
+    capturePage?(): Promise<unknown>;
+}
+/** A window's z-planner + lifetime, handed to {@link ViewHandle.placeIn}. The
+ *  handle's per-placement teardown scope is a CHILD of `windowScope`. */
+export interface PlaceTarget {
+    compositor: Compositor;
+    windowScope: Scope;
+}
+export interface ViewHandle {
+    /** Mount the native view into the target window (mount + commit) and adopt a
+     *  per-placement viewScope under the target's `windowScope`. Chainable. */
+    placeIn(target: PlaceTarget, opts: {
+        zone?: number;
+    }): ViewHandle;
+    /** The placement sink. Drops frames once disposed (idempotent late IPC).
+     *  `visible:true` ensures mounted + drives `setBounds` directly; `visible:false`
+     *  detaches (unmount + commit) but keeps the native view alive. */
+    applyPlacement(p: Placement): void;
+    /**
+     * Cross-window move (build-plan §2(d) / A1.3.2). Migrate the view from its
+     * current placement (`src`) to `dest` as TWO independent Compositor commits,
+     * serialized by a per-view async mutex (migrationLock):
+     *
+     *     AT_SRC → DETACHED → AT_DEST                        (happy path)
+     *            └→ (src.commit throws) → AT_SRC              (rethrow, no side effect)
+     *     DETACHED → (dest.commit throws) → ROLLBACK → AT_SRC (rethrow dest error)
+     *                                                └→ CLOSED (src re-mount ALSO throws)
+     *
+     * On success the compositor token moves to `dest` (later `applyPlacement`
+     * drives the dest host). With `rehome:true`, the viewScope is re-parented under
+     * dest's `windowScope` (lifetime follows display). gap#2: moveTo moves DISPLAY
+     * (and, with rehome, LIFETIME) — it does NOT carry capability grants; the dest
+     * window's own control layer issues its own grant. Terminal (Promise<void>, not
+     * chainable).
+     */
+    moveTo(dest: PlaceTarget, opts: {
+        zone?: number;
+        rehome?: boolean;
+    }): Promise<void>;
+    /** Tear down this placement: run the viewScope's A4 owns (sink-disable then
+     *  native detach, via the LIFO completion fence). Idempotent. */
+    dispose(): Promise<void>;
+    /** The backing native view's WebContents (pass-through from {@link NativeView}).
+     *  Available immediately — the handle owns its view before any placeIn. */
+    readonly webContents: unknown;
+    /** The view's LIVE screen-space rect when it is currently placed AND visible;
+     *  `null` before the first placement, after `applyPlacement({visible:false})`,
+     *  and after `dispose()`. Tracks the last applied `visible:true` bounds. */
+    bounds(): Bounds | null;
+    /** Screenshot pass-through to the native view's `capturePage()`. */
+    capturePage(): Promise<unknown>;
+}
+export interface ViewHandleDeps {
+    nativeView: NativeView;
+    scope: Scope;
+    /** Optional bookkeeping hook, fired whenever the viewScope tears down (window-
+     *  close cascade OR explicit dispose). The deck-app uses it to drop the view
+     *  from its keepAlive group — a window-close cascades the viewScope directly
+     *  (NOT via the host wrapper's dispose), so group cleanup must hang off the
+     *  scope to fire on that path too (KA-2). Any order — it is pure bookkeeping. */
+    onDispose?(): void;
+}
+export declare function createViewHandle(deps: ViewHandleDeps): ViewHandle;
+//# sourceMappingURL=view-handle.d.ts.map

package/dist/main/view-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-handle.d.ts","sourceRoot":"","sources":["../../src/main/view-handle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEhE;iFACiF;AACjF,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAA;AAE9E;;;;;;;;;kDASkD;AAClD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;IAC3B,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,OAAO,CAAC,IAAI,IAAI,CAAA;IAChB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,WAAW,CAAC,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CACjC;AAED;yEACyE;AACzE,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,UAAU,CAAA;IACtB,WAAW,EAAE,KAAK,CAAA;CACnB;AAED,MAAM,WAAW,UAAU;IACzB;+EAC2E;IAC3E,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,CAAA;IACjE;;uEAEmE;IACnE,cAAc,CAAC,CAAC,EAAE,SAAS,GAAG,IAAI,CAAA;IAClC;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnF;qEACiE;IACjE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB;+EAC2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B;;gFAE4E;IAC5E,MAAM,IAAI,MAAM,GAAG,IAAI,CAAA;IACvB,oEAAoE;IACpE,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,UAAU,CAAA;IACtB,KAAK,EAAE,KAAK,CAAA;IACZ;;;;qFAIiF;IACjF,SAAS,CAAC,IAAI,IAAI,CAAA;CACnB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,UAAU,CAsUjE"}

package/dist/preload/index.cjs

@@ -0,0 +1,105 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let electron = require("electron");
+//#region src/shared/protocol.ts
+/** Bridge global 默认挂的全局名（contextBridge.exposeInMainWorld） */
+var DEFAULT_BRIDGE_GLOBAL = "__electronDeckBridge";
+/**
+* Slot-token LAYOUT bridge 默认挂的全局名。`exposeDeckLayoutBridge()` 默认暴露到
+* 此名，renderer 的 `createDeckLayoutClient({ bridge: window.__electronDeckLayoutBridge })`
+* 读取同名。单一来源避免 preload helper 与 client 之间字符串漂移。
+*/
+var DEFAULT_LAYOUT_BRIDGE_GLOBAL = "__electronDeckLayoutBridge";
+/** Bridge protocol semver；client 在 ready() 时校验 major 一致 */
+var BRIDGE_PROTOCOL_VERSION = "1.0.0";
+var DeckChannel = {
+	Invoke: "__electron-deck:invoke",
+	Event: "__electron-deck:event",
+	Probe: "__electron-deck:probe",
+	Place: "__electron-deck:place",
+	SlotGrant: "__electron-deck:slot-grant",
+	LayoutSubscribe: "__electron-deck:layout-subscribe"
+};
+//#endregion
+//#region src/preload/index.ts
+/**
+* 在 host preload 内调用，把 framework typed RPC + event push bridge 暴露到
+* webview window：
+*
+* ```ts
+* import { contextBridge, ipcRenderer } from 'electron'
+* import { exposeDeckBridge } from '@dimina-kit/electron-deck/preload'
+* exposeDeckBridge()
+* ```
+*
+* 见 `DeckBridge` 接口（`shared/protocol.ts`）。
+*/
+function exposeDeckBridge(options) {
+	if (typeof electron.contextBridge?.exposeInMainWorld !== "function" || typeof electron.ipcRenderer?.invoke !== "function") throw new Error("exposeDeckBridge: must be called from a preload script (electron contextBridge / ipcRenderer unavailable)");
+	const globalName = options?.globalName ?? "__electronDeckBridge";
+	if (globalThis[globalName] !== void 0) throw new Error(`Deck bridge already exposed at "${globalName}"`);
+	const bridge = {
+		version: BRIDGE_PROTOCOL_VERSION,
+		probe() {
+			return electron.ipcRenderer.invoke(DeckChannel.Probe);
+		},
+		invoke(req) {
+			return electron.ipcRenderer.invoke(DeckChannel.Invoke, req);
+		},
+		onEvent(listener) {
+			const wrapped = (_event, env) => {
+				listener(env);
+			};
+			electron.ipcRenderer.on(DeckChannel.Event, wrapped);
+			return () => {
+				electron.ipcRenderer.removeListener(DeckChannel.Event, wrapped);
+			};
+		}
+	};
+	electron.contextBridge.exposeInMainWorld(globalName, bridge);
+}
+/**
+* 在 host preload 内调用，把三条 slot-token LAYOUT channel（`slot-grant` PUSH /
+* `place` send / `layout-subscribe` invoke）封装成一个 `LayoutBridge`-shaped
+* 对象暴露到 webview window，供 renderer：
+*
+* ```ts
+* import { exposeDeckLayoutBridge } from '@dimina-kit/electron-deck/preload'
+* exposeDeckLayoutBridge()
+* // renderer:
+* createDeckLayoutClient({ bridge: window.__electronDeckLayoutBridge })
+* ```
+*
+* channel 名一律取自框架 `DeckChannel`（不手抄字符串）。`onSlotGrant` 返回一个
+* 纯 unsubscribe 函数（可跨 contextBridge），不是 Disposable 对象。
+*/
+function exposeDeckLayoutBridge(options) {
+	if (typeof electron.contextBridge?.exposeInMainWorld !== "function" || typeof electron.ipcRenderer?.on !== "function") throw new Error("exposeDeckLayoutBridge: must be called from a preload script (electron contextBridge / ipcRenderer unavailable)");
+	const globalName = options?.globalName ?? "__electronDeckLayoutBridge";
+	if (globalThis[globalName] !== void 0) throw new Error(`Deck layout bridge already exposed at "${globalName}"`);
+	electron.contextBridge.exposeInMainWorld(globalName, {
+		onSlotGrant(cb) {
+			const listener = (_event, grant) => {
+				cb(grant);
+			};
+			electron.ipcRenderer.on(DeckChannel.SlotGrant, listener);
+			return () => {
+				electron.ipcRenderer.removeListener(DeckChannel.SlotGrant, listener);
+			};
+		},
+		sendPlace(msg) {
+			electron.ipcRenderer.invoke(DeckChannel.Place, msg).catch(() => {});
+		},
+		subscribe() {
+			electron.ipcRenderer.invoke(DeckChannel.LayoutSubscribe).catch(() => {});
+		}
+	});
+}
+//#endregion
+exports.BRIDGE_PROTOCOL_VERSION = BRIDGE_PROTOCOL_VERSION;
+exports.DEFAULT_BRIDGE_GLOBAL = DEFAULT_BRIDGE_GLOBAL;
+exports.DEFAULT_LAYOUT_BRIDGE_GLOBAL = DEFAULT_LAYOUT_BRIDGE_GLOBAL;
+exports.DeckChannel = DeckChannel;
+exports.exposeDeckBridge = exposeDeckBridge;
+exports.exposeDeckLayoutBridge = exposeDeckLayoutBridge;
+
+//# sourceMappingURL=index.cjs.map

package/dist/preload/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/shared/protocol.ts","../../src/preload/index.ts"],"sourcesContent":["/**\n * Deck framework wire protocol —— main ↔ webview 之间的 channel 名 + 帧\n * 形态。SoT 在此，preload / client / main runtime 都从这里 import。\n *\n * 设计：把 declared `hostServices` / `simulatorApis` / `events` 三类全部走\n * **两个** 统一 channel，避免 channel name 爆炸 / 难以加 senderPolicy 白名单。\n * - `__electron-deck:invoke`  — webview → main RPC (ipcRenderer.invoke)\n * - `__electron-deck:event`   — main → webview event push (webContents.send)\n * - `__electron-deck:probe`   — webview → main 探活，bridge ready 检查\n *\n * 帧用 JSON 对象一层 envelope，便于扩展 + 校验。\n *\n * @internal\n */\n\nimport type { JsonValue } from '../types.js'\n\n/** Bridge global 默认挂的全局名（contextBridge.exposeInMainWorld） */\nexport const DEFAULT_BRIDGE_GLOBAL = '__electronDeckBridge'\n\n/**\n * Slot-token LAYOUT bridge 默认挂的全局名。`exposeDeckLayoutBridge()` 默认暴露到\n * 此名，renderer 的 `createDeckLayoutClient({ bridge: window.__electronDeckLayoutBridge })`\n * 读取同名。单一来源避免 preload helper 与 client 之间字符串漂移。\n */\nexport const DEFAULT_LAYOUT_BRIDGE_GLOBAL = '__electronDeckLayoutBridge'\n\n/** Bridge protocol semver；client 在 ready() 时校验 major 一致 */\nexport const BRIDGE_PROTOCOL_VERSION = '1.0.0'\n\nexport const DeckChannel = {\n\tInvoke: '__electron-deck:invoke',\n\tEvent: '__electron-deck:event',\n\tProbe: '__electron-deck:probe',\n\tPlace: '__electron-deck:place',\n\tSlotGrant: '__electron-deck:slot-grant',\n\tLayoutSubscribe: '__electron-deck:layout-subscribe',\n} as const\n\nexport type InvokeKind = 'host' | 'simulator'\n\nexport interface InvokeRequest {\n\treadonly kind: InvokeKind\n\treadonly name: string\n\treadonly args: readonly JsonValue[]\n}\n\nexport interface InvokeSuccess<R extends JsonValue = JsonValue> {\n\treadonly ok: true\n\treadonly result: R\n}\n\nexport interface InvokeFailure {\n\treadonly ok: false\n\treadonly error: {\n\t\treadonly remoteName: string\n\t\treadonly message: string\n\t\treadonly code?: string\n\t}\n}\n\nexport type InvokeResponse<R extends JsonValue = JsonValue> =\n\t| InvokeSuccess<R>\n\t| InvokeFailure\n\nexport interface EventEnvelope<P extends JsonValue = JsonValue> {\n\treadonly name: string\n\treadonly payload: P\n}\n\nexport interface ProbeResponse {\n\treadonly ready: true\n\treadonly version: typeof BRIDGE_PROTOCOL_VERSION\n}\n\n/**\n * Bridge global 暴露到 webview window 的 shape。preload 把它通过\n * `contextBridge.exposeInMainWorld(globalName, bridge)` 注入；webview-side\n * `createDeckClient()` 通过 `globalThis[globalName]` 读取。\n *\n * 注意所有方法必须是 contextBridge-friendly（plain values + serializable\n * arguments），不要把 Map / Set / Date / Promise.race 等 leak 进 bridge 接口。\n */\nexport interface DeckBridge {\n\treadonly version: typeof BRIDGE_PROTOCOL_VERSION\n\tprobe(): Promise<ProbeResponse>\n\tinvoke(req: InvokeRequest): Promise<InvokeResponse>\n\t/** 订阅 event channel；返回 unsubscribe 函数（不是 Disposable，因为要跨 contextBridge） */\n\tonEvent(listener: (env: EventEnvelope) => void): () => void\n}\n","import { contextBridge, ipcRenderer } from 'electron'\nimport {\n\tBRIDGE_PROTOCOL_VERSION,\n\tDEFAULT_BRIDGE_GLOBAL,\n\tDEFAULT_LAYOUT_BRIDGE_GLOBAL,\n\tDeckChannel,\n} from '../shared/protocol.js'\nimport type {\n\tEventEnvelope,\n\tInvokeRequest,\n\tInvokeResponse,\n\tProbeResponse,\n\tDeckBridge,\n} from '../shared/protocol.js'\nimport type { LayoutBridge, SlotGrant } from '../client/layout-client.js'\n\nexport interface ExposeBridgeOptions {\n\t/** 暴露到 window 的全局名，默认 `__electronDeckBridge` */\n\treadonly globalName?: string\n}\n\n/**\n * 在 host preload 内调用，把 framework typed RPC + event push bridge 暴露到\n * webview window：\n *\n * ```ts\n * import { contextBridge, ipcRenderer } from 'electron'\n * import { exposeDeckBridge } from '@dimina-kit/electron-deck/preload'\n * exposeDeckBridge()\n * ```\n *\n * 见 `DeckBridge` 接口（`shared/protocol.ts`）。\n */\nexport function exposeDeckBridge(options?: ExposeBridgeOptions): void {\n\tif (typeof contextBridge?.exposeInMainWorld !== 'function' || typeof ipcRenderer?.invoke !== 'function') {\n\t\tthrow new Error('exposeDeckBridge: must be called from a preload script (electron contextBridge / ipcRenderer unavailable)')\n\t}\n\n\tconst globalName = options?.globalName ?? DEFAULT_BRIDGE_GLOBAL\n\t// 自检 globalThis —— contextBridge 内部也维护去重，但我们抢先抛更明确的诊断\n\tconst g = globalThis as unknown as Record<string, unknown>\n\tif (g[globalName] !== undefined) {\n\t\tthrow new Error(`Deck bridge already exposed at \"${globalName}\"`)\n\t}\n\n\tconst bridge: DeckBridge = {\n\t\tversion: BRIDGE_PROTOCOL_VERSION,\n\t\tprobe(): Promise<ProbeResponse> {\n\t\t\treturn ipcRenderer.invoke(DeckChannel.Probe) as Promise<ProbeResponse>\n\t\t},\n\t\tinvoke(req: InvokeRequest): Promise<InvokeResponse> {\n\t\t\treturn ipcRenderer.invoke(DeckChannel.Invoke, req) as Promise<InvokeResponse>\n\t\t},\n\t\tonEvent(listener: (env: EventEnvelope) => void): () => void {\n\t\t\tconst wrapped = (_event: unknown, env: EventEnvelope): void => {\n\t\t\t\tlistener(env)\n\t\t\t}\n\t\t\tipcRenderer.on(DeckChannel.Event, wrapped)\n\t\t\treturn () => {\n\t\t\t\tipcRenderer.removeListener(DeckChannel.Event, wrapped)\n\t\t\t}\n\t\t},\n\t}\n\n\tcontextBridge.exposeInMainWorld(globalName, bridge)\n}\n\nexport interface ExposeLayoutBridgeOptions {\n\t/** 暴露到 window 的全局名，默认 `__electronDeckLayoutBridge` */\n\treadonly globalName?: string\n}\n\n/**\n * 在 host preload 内调用，把三条 slot-token LAYOUT channel（`slot-grant` PUSH /\n * `place` send / `layout-subscribe` invoke）封装成一个 `LayoutBridge`-shaped\n * 对象暴露到 webview window，供 renderer：\n *\n * ```ts\n * import { exposeDeckLayoutBridge } from '@dimina-kit/electron-deck/preload'\n * exposeDeckLayoutBridge()\n * // renderer:\n * createDeckLayoutClient({ bridge: window.__electronDeckLayoutBridge })\n * ```\n *\n * channel 名一律取自框架 `DeckChannel`（不手抄字符串）。`onSlotGrant` 返回一个\n * 纯 unsubscribe 函数（可跨 contextBridge），不是 Disposable 对象。\n */\nexport function exposeDeckLayoutBridge(options?: ExposeLayoutBridgeOptions): void {\n\tif (typeof contextBridge?.exposeInMainWorld !== 'function' || typeof ipcRenderer?.on !== 'function') {\n\t\tthrow new Error('exposeDeckLayoutBridge: must be called from a preload script (electron contextBridge / ipcRenderer unavailable)')\n\t}\n\n\tconst globalName = options?.globalName ?? DEFAULT_LAYOUT_BRIDGE_GLOBAL\n\tconst g = globalThis as unknown as Record<string, unknown>\n\tif (g[globalName] !== undefined) {\n\t\tthrow new Error(`Deck layout bridge already exposed at \"${globalName}\"`)\n\t}\n\n\tconst bridge: LayoutBridge = {\n\t\tonSlotGrant(cb: (grant: SlotGrant) => void): () => void {\n\t\t\tconst listener = (_event: unknown, grant: SlotGrant): void => {\n\t\t\t\tcb(grant)\n\t\t\t}\n\t\t\tipcRenderer.on(DeckChannel.SlotGrant, listener)\n\t\t\treturn () => {\n\t\t\t\tipcRenderer.removeListener(DeckChannel.SlotGrant, listener)\n\t\t\t}\n\t\t},\n\t\tsendPlace(msg): void {\n\t\t\tvoid ipcRenderer.invoke(DeckChannel.Place, msg).catch(() => {})\n\t\t},\n\t\tsubscribe(): void {\n\t\t\tvoid ipcRenderer.invoke(DeckChannel.LayoutSubscribe).catch(() => {})\n\t\t},\n\t}\n\n\tcontextBridge.exposeInMainWorld(globalName, bridge)\n}\n\nexport type {\n\tEventEnvelope,\n\tInvokeRequest,\n\tInvokeResponse,\n\tProbeResponse,\n\tDeckBridge,\n\tLayoutBridge,\n\tSlotGrant,\n}\nexport { BRIDGE_PROTOCOL_VERSION, DEFAULT_BRIDGE_GLOBAL, DEFAULT_LAYOUT_BRIDGE_GLOBAL, DeckChannel }\n"],"mappings":";;;;AAkBA,IAAa,wBAAwB;;;;;;AAOrC,IAAa,+BAA+B;;AAG5C,IAAa,0BAA0B;AAEvC,IAAa,cAAc;CAC1B,QAAQ;CACR,OAAO;CACP,OAAO;CACP,OAAO;CACP,WAAW;CACX,iBAAiB;AAClB;;;;;;;;;;;;;;;ACJA,SAAgB,iBAAiB,SAAqC;CACrE,IAAI,OAAO,SAAA,eAAe,sBAAsB,cAAc,OAAO,SAAA,aAAa,WAAW,YAC5F,MAAM,IAAI,MAAM,2GAA2G;CAG5H,MAAM,aAAa,SAAS,cAAA;CAG5B,IAAI,WAAE,gBAAgB,KAAA,GACrB,MAAM,IAAI,MAAM,mCAAmC,WAAW,EAAE;CAGjE,MAAM,SAAqB;EAC1B,SAAS;EACT,QAAgC;GAC/B,OAAO,SAAA,YAAY,OAAO,YAAY,KAAK;EAC5C;EACA,OAAO,KAA6C;GACnD,OAAO,SAAA,YAAY,OAAO,YAAY,QAAQ,GAAG;EAClD;EACA,QAAQ,UAAoD;GAC3D,MAAM,WAAW,QAAiB,QAA6B;IAC9D,SAAS,GAAG;GACb;GACA,SAAA,YAAY,GAAG,YAAY,OAAO,OAAO;GACzC,aAAa;IACZ,SAAA,YAAY,eAAe,YAAY,OAAO,OAAO;GACtD;EACD;CACD;CAEA,SAAA,cAAc,kBAAkB,YAAY,MAAM;AACnD;;;;;;;;;;;;;;;;AAsBA,SAAgB,uBAAuB,SAA2C;CACjF,IAAI,OAAO,SAAA,eAAe,sBAAsB,cAAc,OAAO,SAAA,aAAa,OAAO,YACxF,MAAM,IAAI,MAAM,iHAAiH;CAGlI,MAAM,aAAa,SAAS,cAAA;CAE5B,IAAI,WAAE,gBAAgB,KAAA,GACrB,MAAM,IAAI,MAAM,0CAA0C,WAAW,EAAE;CAqBxE,SAAA,cAAc,kBAAkB,YAAY;EAjB3C,YAAY,IAA4C;GACvD,MAAM,YAAY,QAAiB,UAA2B;IAC7D,GAAG,KAAK;GACT;GACA,SAAA,YAAY,GAAG,YAAY,WAAW,QAAQ;GAC9C,aAAa;IACZ,SAAA,YAAY,eAAe,YAAY,WAAW,QAAQ;GAC3D;EACD;EACA,UAAU,KAAW;GACpB,SAAK,YAAY,OAAO,YAAY,OAAO,GAAG,EAAE,YAAY,CAAC,CAAC;EAC/D;EACA,YAAkB;GACjB,SAAK,YAAY,OAAO,YAAY,eAAe,EAAE,YAAY,CAAC,CAAC;EACpE;CAG2C,CAAM;AACnD"}

package/dist/preload/index.d.ts

@@ -0,0 +1,43 @@
+import { BRIDGE_PROTOCOL_VERSION, DEFAULT_BRIDGE_GLOBAL, DEFAULT_LAYOUT_BRIDGE_GLOBAL, DeckChannel } from '../shared/protocol.js';
+import type { EventEnvelope, InvokeRequest, InvokeResponse, ProbeResponse, DeckBridge } from '../shared/protocol.js';
+import type { LayoutBridge, SlotGrant } from '../client/layout-client.js';
+export interface ExposeBridgeOptions {
+    /** 暴露到 window 的全局名，默认 `__electronDeckBridge` */
+    readonly globalName?: string;
+}
+/**
+ * 在 host preload 内调用，把 framework typed RPC + event push bridge 暴露到
+ * webview window：
+ *
+ * ```ts
+ * import { contextBridge, ipcRenderer } from 'electron'
+ * import { exposeDeckBridge } from '@dimina-kit/electron-deck/preload'
+ * exposeDeckBridge()
+ * ```
+ *
+ * 见 `DeckBridge` 接口（`shared/protocol.ts`）。
+ */
+export declare function exposeDeckBridge(options?: ExposeBridgeOptions): void;
+export interface ExposeLayoutBridgeOptions {
+    /** 暴露到 window 的全局名，默认 `__electronDeckLayoutBridge` */
+    readonly globalName?: string;
+}
+/**
+ * 在 host preload 内调用，把三条 slot-token LAYOUT channel（`slot-grant` PUSH /
+ * `place` send / `layout-subscribe` invoke）封装成一个 `LayoutBridge`-shaped
+ * 对象暴露到 webview window，供 renderer：
+ *
+ * ```ts
+ * import { exposeDeckLayoutBridge } from '@dimina-kit/electron-deck/preload'
+ * exposeDeckLayoutBridge()
+ * // renderer:
+ * createDeckLayoutClient({ bridge: window.__electronDeckLayoutBridge })
+ * ```
+ *
+ * channel 名一律取自框架 `DeckChannel`（不手抄字符串）。`onSlotGrant` 返回一个
+ * 纯 unsubscribe 函数（可跨 contextBridge），不是 Disposable 对象。
+ */
+export declare function exposeDeckLayoutBridge(options?: ExposeLayoutBridgeOptions): void;
+export type { EventEnvelope, InvokeRequest, InvokeResponse, ProbeResponse, DeckBridge, LayoutBridge, SlotGrant, };
+export { BRIDGE_PROTOCOL_VERSION, DEFAULT_BRIDGE_GLOBAL, DEFAULT_LAYOUT_BRIDGE_GLOBAL, DeckChannel };
+//# sourceMappingURL=index.d.ts.map

package/dist/preload/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/preload/index.ts"],"names":[],"mappings":"AACA,OAAO,EACN,uBAAuB,EACvB,qBAAqB,EACrB,4BAA4B,EAC5B,WAAW,EACX,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EACX,aAAa,EACb,aAAa,EACb,cAAc,EACd,aAAa,EACb,UAAU,EACV,MAAM,uBAAuB,CAAA;AAC9B,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAEzE,MAAM,WAAW,mBAAmB;IACnC,gDAAgD;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAgCpE;AAED,MAAM,WAAW,yBAAyB;IACzC,sDAAsD;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,IAAI,CA8BhF;AAED,YAAY,EACX,aAAa,EACb,aAAa,EACb,cAAc,EACd,aAAa,EACb,UAAU,EACV,YAAY,EACZ,SAAS,GACT,CAAA;AACD,OAAO,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,WAAW,EAAE,CAAA"}

package/dist/preload/index.js

@@ -0,0 +1,80 @@
+import { i as DeckChannel, n as DEFAULT_BRIDGE_GLOBAL, r as DEFAULT_LAYOUT_BRIDGE_GLOBAL, t as BRIDGE_PROTOCOL_VERSION } from "../protocol-BJqo-vP2.js";
+import { contextBridge, ipcRenderer } from "electron";
+//#region src/preload/index.ts
+/**
+* 在 host preload 内调用，把 framework typed RPC + event push bridge 暴露到
+* webview window：
+*
+* ```ts
+* import { contextBridge, ipcRenderer } from 'electron'
+* import { exposeDeckBridge } from '@dimina-kit/electron-deck/preload'
+* exposeDeckBridge()
+* ```
+*
+* 见 `DeckBridge` 接口（`shared/protocol.ts`）。
+*/
+function exposeDeckBridge(options) {
+	if (typeof contextBridge?.exposeInMainWorld !== "function" || typeof ipcRenderer?.invoke !== "function") throw new Error("exposeDeckBridge: must be called from a preload script (electron contextBridge / ipcRenderer unavailable)");
+	const globalName = options?.globalName ?? "__electronDeckBridge";
+	if (globalThis[globalName] !== void 0) throw new Error(`Deck bridge already exposed at "${globalName}"`);
+	const bridge = {
+		version: BRIDGE_PROTOCOL_VERSION,
+		probe() {
+			return ipcRenderer.invoke(DeckChannel.Probe);
+		},
+		invoke(req) {
+			return ipcRenderer.invoke(DeckChannel.Invoke, req);
+		},
+		onEvent(listener) {
+			const wrapped = (_event, env) => {
+				listener(env);
+			};
+			ipcRenderer.on(DeckChannel.Event, wrapped);
+			return () => {
+				ipcRenderer.removeListener(DeckChannel.Event, wrapped);
+			};
+		}
+	};
+	contextBridge.exposeInMainWorld(globalName, bridge);
+}
+/**
+* 在 host preload 内调用，把三条 slot-token LAYOUT channel（`slot-grant` PUSH /
+* `place` send / `layout-subscribe` invoke）封装成一个 `LayoutBridge`-shaped
+* 对象暴露到 webview window，供 renderer：
+*
+* ```ts
+* import { exposeDeckLayoutBridge } from '@dimina-kit/electron-deck/preload'
+* exposeDeckLayoutBridge()
+* // renderer:
+* createDeckLayoutClient({ bridge: window.__electronDeckLayoutBridge })
+* ```
+*
+* channel 名一律取自框架 `DeckChannel`（不手抄字符串）。`onSlotGrant` 返回一个
+* 纯 unsubscribe 函数（可跨 contextBridge），不是 Disposable 对象。
+*/
+function exposeDeckLayoutBridge(options) {
+	if (typeof contextBridge?.exposeInMainWorld !== "function" || typeof ipcRenderer?.on !== "function") throw new Error("exposeDeckLayoutBridge: must be called from a preload script (electron contextBridge / ipcRenderer unavailable)");
+	const globalName = options?.globalName ?? "__electronDeckLayoutBridge";
+	if (globalThis[globalName] !== void 0) throw new Error(`Deck layout bridge already exposed at "${globalName}"`);
+	contextBridge.exposeInMainWorld(globalName, {
+		onSlotGrant(cb) {
+			const listener = (_event, grant) => {
+				cb(grant);
+			};
+			ipcRenderer.on(DeckChannel.SlotGrant, listener);
+			return () => {
+				ipcRenderer.removeListener(DeckChannel.SlotGrant, listener);
+			};
+		},
+		sendPlace(msg) {
+			ipcRenderer.invoke(DeckChannel.Place, msg).catch(() => {});
+		},
+		subscribe() {
+			ipcRenderer.invoke(DeckChannel.LayoutSubscribe).catch(() => {});
+		}
+	});
+}
+//#endregion
+export { BRIDGE_PROTOCOL_VERSION, DEFAULT_BRIDGE_GLOBAL, DEFAULT_LAYOUT_BRIDGE_GLOBAL, DeckChannel, exposeDeckBridge, exposeDeckLayoutBridge };
+
+//# sourceMappingURL=index.js.map