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

package/dist/internal/resource-registry.d.ts

@@ -0,0 +1,9 @@
+import type { Disposable, MaybePromise, ResourceRegistry } from '../types.js';
+export declare class ResourceRegistryImpl implements ResourceRegistry {
+    private entries;
+    private nextId;
+    private allDisposed;
+    add(d: Disposable | (() => MaybePromise<void>)): Disposable;
+    disposeAll(): Promise<void>;
+}
+//# sourceMappingURL=resource-registry.d.ts.map

package/dist/internal/resource-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-registry.d.ts","sourceRoot":"","sources":["../../src/internal/resource-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAyB7E,qBAAa,oBAAqB,YAAW,gBAAgB;IAC5D,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,WAAW,CAAQ;IAE3B,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC,GAAG,UAAU;IAyBrD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAqBjC"}

package/dist/internal/trust-set.d.ts

@@ -0,0 +1,53 @@
+/**
+ * TrustSet — SEALED refcount membership of trusted webContents (P2).
+ *
+ * Refcount membership extracted from `DeckApp`'s former private `trustedWcRefs`
+ * (Map<wc, refcount>) so the same primitive can back both `DeckApp` and the
+ * domain-neutral `ControlBus` facade.
+ *
+ * SEALED WRITE MODEL: there is exactly ONE writer — `admit(wc, owner)`. It forces
+ * every trust lease to be OWNED by a `Scope`, so a lease can never outlive its
+ * owner and no un-owned / leaked lease is possible. The old public `add(wc)`
+ * (un-owned lease minting) and the `deleteEntry(wc)` imperative wipe are GONE:
+ *   - releasing a lease early → use the Disposable `admit` returns;
+ *   - releasing ALL of an owner's leases → close/reset that owner Scope (the
+ *     refcount-- disposers are owned by it, so its teardown zeroes them).
+ *
+ * Semantics (unchanged refcount core):
+ * - `admit(wc, owner)` increments the wc's refcount and owns the matching
+ *   refcount-- on `owner`; the entry is removed when the count reaches zero.
+ * - `isTrusted(id)` is true iff any live entry's `.id === id`.
+ * - `snapshot()` returns the live keys (used for event fanout).
+ *
+ * Idempotency note: each refcount-- disposer is one-shot and guarded by a
+ * `c === undefined` check — disposing a handle after the entry has already been
+ * dropped (e.g. via the owner's teardown) reads `refs.get(wc)`, sees `undefined`,
+ * and returns without touching the map, so a residual handle can never resurrect
+ * or mis-decrement a re-added entry.
+ *
+ * @internal
+ */
+import type { Disposable } from '../types.js';
+import type { MinimalWebContents } from './wire-transport.js';
+import type { Scope } from '../main/scope.js';
+/** Read-only trust index (gate + fanout). No write surface. */
+export interface TrustIndex {
+    /** true iff some live entry's `.id === id`. */
+    isTrusted(id: number): boolean;
+    /** live keys, for event fanout. */
+    snapshot(): readonly MinimalWebContents[];
+}
+/** Admit-capable trust set. The ONLY writer is `admit`, which forces an owner
+ *  Scope so a trust lease can never outlive its owner (no un-owned lease). */
+export interface TrustSet extends TrustIndex {
+    /**
+     * Admit `wc` to the trust set (refcount++). The refcount-- release is OWNED by
+     * `owner` (so `owner.reset()`/`close()` releases it automatically). Returns a
+     * one-shot Disposable that releases JUST this lease early (idempotent; never
+     * double-decrements, and a later `owner` teardown over an already-released
+     * lease is a safe no-op via the refs-undefined guard).
+     */
+    admit(wc: MinimalWebContents, owner: Scope): Disposable;
+}
+export declare function createTrustSet(): TrustSet;
+//# sourceMappingURL=trust-set.d.ts.map

package/dist/internal/trust-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-set.d.ts","sourceRoot":"","sources":["../../src/internal/trust-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IAC1B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAA;IAC9B,mCAAmC;IACnC,QAAQ,IAAI,SAAS,kBAAkB,EAAE,CAAA;CACzC;AAED;8EAC8E;AAC9E,MAAM,WAAW,QAAS,SAAQ,UAAU;IAC3C;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,EAAE,kBAAkB,EAAE,KAAK,EAAE,KAAK,GAAG,UAAU,CAAA;CACvD;AAED,wBAAgB,cAAc,IAAI,QAAQ,CAwCzC"}

package/dist/internal/wire-transport.d.ts

@@ -0,0 +1,159 @@
+/**
+ * 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
+ */
+import type { JsonValue, SenderPolicy } from '../types.js';
+import type { EventBus } from './event-bus.js';
+/**
+ * Framework-reserved invoke failure codes —— 全部带 `DECK_` 前缀，避免与
+ * host 自定义 code 冲突。Client / host 都不应抛同前缀。
+ */
+export declare const DECK_CODE: {
+    readonly UntrustedSender: "DECK_UNTRUSTED_SENDER";
+    readonly UntrustedFrame: "DECK_UNTRUSTED_FRAME";
+    readonly UnknownKind: "DECK_UNKNOWN_KIND";
+    readonly BadRequest: "DECK_BAD_REQUEST";
+    /** P4 Phase B — the grant gate denied a privileged command for this sender. */
+    readonly Forbidden: "DECK_FORBIDDEN";
+};
+/** Minimal RenderFrameHost identity used for main-frame discrimination. */
+export interface FrameRef {
+    readonly routingId: number;
+    readonly processId: number;
+}
+/**
+ * Per-invoke context threaded from {@link WireTransport.handleInvoke} into the
+ * host/simulator invoke seams. Constructed ONLY after the wire's trust gate +
+ * main-frame gate have both passed, so `senderId` is a real trusted webContents
+ * id (never undefined). Phase B's grant gate (in `ControlBus.dispatch`) reads
+ * this; Phase A just plumbs it through as a REQUIRED param so a missing call
+ * site is a COMPILE error, not a silent security downgrade.
+ */
+export interface InvokeCtx {
+    /** webContents id of the invoke sender (after the wire's trust + main-frame gates). */
+    readonly senderId: number;
+    /** sender frame ref; main-frame already validated. Kept for future per-frame use; may be null. */
+    readonly senderFrame: FrameRef | null;
+}
+export interface MinimalIpcMain {
+    handle(channel: string, handler: (event: {
+        sender: {
+            id: number;
+            mainFrame?: FrameRef | null;
+        };
+        senderFrame?: FrameRef | null;
+    }, ...args: unknown[]) => unknown | Promise<unknown>): void;
+    removeHandler(channel: string): void;
+}
+export interface MinimalWebContents {
+    readonly id: number;
+    isDestroyed(): boolean;
+    send(channel: string, payload: unknown): void;
+}
+export interface WireTransportDeps {
+    readonly ipcMain: MinimalIpcMain;
+    readonly bus: EventBus;
+    readonly senderPolicy: SenderPolicy;
+    /** 取当前 trusted webContents 快照；用于 event push 广播。lazy：每次 publish 重调。 */
+    readonly trustedWebContents: () => readonly MinimalWebContents[];
+    /** 路由 host kind 调用；handler 抛错由 WireTransport 接住 → InvokeFailure。
+     *  `ctx` 必填：携带已过 trust + main-frame gate 的 senderId（Phase B 授权门读它）。 */
+    readonly invokeHost: (name: string, args: readonly JsonValue[], ctx: InvokeCtx) => Promise<JsonValue>;
+    /** 路由 simulator kind 调用；同上（`ctx` 必填）。 */
+    readonly invokeSimulator: (name: string, args: readonly JsonValue[], ctx: InvokeCtx) => Promise<JsonValue>;
+    /**
+     * 已声明的 event name 集合，作为 wire fanout 的 allowlist。**必填，
+     * default-deny** —— 未在该集合内的 event name 不会跨进程下发（防止
+     * framework 内部代码意外调 `bus.publish('foo')` 时 leak 给 webview）。
+     * 调用方需保证每次返回的是当前 declared event 名字列表（lazy 快照，每次
+     * publish 重读）。
+     */
+    readonly declaredEvents: () => readonly string[];
+    /**
+     * OPTIONAL slot-token inbound: `__electron-deck:place` apply path. When
+     * provided, `start()` registers the `Place` handler (same trust + main-frame
+     * gate as invoke). On gate pass → `onPlace(senderId, slotToken, placement)`.
+     */
+    readonly onPlace?: (senderId: number, slotToken: string, placement: unknown) => void;
+    /**
+     * OPTIONAL slot-token inbound: `__electron-deck:layout-subscribe` per-wc
+     * replay request. When provided, `start()` registers the `LayoutSubscribe`
+     * handler (same gate). On gate pass → `onLayoutSubscribe(senderId)`.
+     */
+    readonly onLayoutSubscribe?: (senderId: number) => void;
+}
+export declare class WireTransport {
+    private readonly deps;
+    private state;
+    private busSubscription;
+    /** 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. */
+    private placeRegistered;
+    private layoutSubscribeRegistered;
+    /** 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). */
+    private onPlaceCb;
+    private onLayoutSubscribeCb;
+    constructor(deps: WireTransportDeps);
+    start(): void;
+    private tryRemoveHandler;
+    private registerPlaceHandler;
+    private unregisterPlaceHandler;
+    private registerLayoutSubscribeHandler;
+    private unregisterLayoutSubscribeHandler;
+    /**
+     * 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: (senderId: number, slotToken: string, placement: unknown) => void, onLayoutSubscribe: (senderId: number) => void): void;
+    dispose(): void;
+    private handleProbe;
+    /**
+     * 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.
+     */
+    private isMainFrameSender;
+    private handleInvoke;
+    /**
+     * `__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`).
+     */
+    private handlePlace;
+    /**
+     * `__electron-deck:layout-subscribe` inbound. Same gate as {@link handleInvoke}.
+     * On gate pass → `onLayoutSubscribe(senderId)`; else DROP silently.
+     */
+    private handleLayoutSubscribe;
+    private fanoutEvent;
+}
+//# sourceMappingURL=wire-transport.d.ts.map

package/dist/internal/wire-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-transport.d.ts","sourceRoot":"","sources":["../../src/internal/wire-transport.ts"],"names":[],"mappings":"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"}

package/dist/main/compositor.d.ts

@@ -0,0 +1,123 @@
+/**
+ * `Compositor` — engine-agnostic z-order planner for a window's native child
+ * views (foundation: the spikes in `.repro/electron-deck-spikes/`).
+ *
+ * It separates INTENT (mount / unmount / reorder a view into a zone, at a
+ * relative position) from APPLICATION (`commit()` computes the minimal sequence
+ * of host add/remove calls that transforms the host's current child order into
+ * the target order).
+ *
+ * The host's observable z-semantics this planner is built on (from the spikes):
+ *   - `addChildView` of an ALREADY-mounted child raises it to the top WITHOUT a
+ *     remove first and WITHOUT reloading it.
+ *   - `addChildView` of a NEW child appends it to the end (= topmost).
+ *   - A batch of remove/add in ONE synchronous tick re-lands at the target order
+ *     with zero renderer reloads.
+ *   - `addChildView` into a destroyed contentView throws synchronously.
+ *
+ * Ordering model. Every mounted view carries `(zone, orderKey, viewId)`. The
+ * total render order is that triple, ascending: lower zone renders BELOW higher
+ * zone (zones stack), `orderKey` orders within a zone, and `viewId` is a pure
+ * tiebreak so the order is deterministic even if two keys collide. `orderKey` is
+ * a FRACTIONAL key: reorder-before(X) sets the moved view's key to the midpoint
+ * between X's key and its in-zone predecessor's key, so a reorder is O(1) and
+ * perturbs no other view's key. When repeated midpoints exhaust float precision
+ * in a gap, the affected zone is RENUMBERED (rebalance) to evenly-spaced integer
+ * keys — invisible, because the renumber preserves the existing relative order.
+ *
+ * mount epoch. A genuinely-new mount gets a fresh monotonically-increasing
+ * `mountSeq` and lands at the top of its zone. Re-mounting a view that is STILL
+ * mounted is a pure no-op (same orderKey/mountSeq, zero host churn). But an
+ * `unmount(id)` followed by `mount(id)` is a NEW instance: it gets a new
+ * mountSeq and lands at the top — it never resumes the old slot.
+ *
+ * commit. We fold the batch of intents into the FINAL target state (last-state,
+ * not a write-log replay), then diff the host's current children against that
+ * target. The longest increasing subsequence (LIS) of views already in correct
+ * relative order — computed over the current∩target intersection — is left
+ * untouched; every other shared view is `removeChildView` + `addChildView`, and
+ * each brand-new view gets one explicit `addChildView`. All in one synchronous
+ * pass. On failure `commit()` throws a typed {@link CommitError}: a destroyed
+ * host with additions pending throws `host-destroyed` BEFORE touching native
+ * (applied:false); a native call that throws mid-apply is caught and the host is
+ * rolled back to its pre-apply snapshot, then `apply-failed` is thrown with
+ * whether the rollback recovered the snapshot. A no-op commit, and a destroyed
+ * host with only removals pending, are SILENT (teardown-friendly).
+ */
+/** A handle to a native child view. Identity is by `id`. */
+export type NativeViewRef = {
+    readonly id: string;
+};
+/**
+ * Typed failure thrown by {@link Compositor.commit}. `kind` distinguishes a
+ * preflight refusal (`host-destroyed`, native byte-for-byte pre-commit,
+ * `applied:false`) from a mid-apply native throw (`apply-failed`,
+ * `applied:'partial'`); for `apply-failed`, `recovered` reports whether the
+ * best-effort rollback restored the pre-apply snapshot order (`false` ⇒ native
+ * is untrusted and the host must be treated as dead).
+ */
+export declare class CommitError extends Error {
+    readonly kind: 'host-destroyed' | 'apply-failed';
+    readonly applied: false | 'partial';
+    readonly recovered?: boolean;
+    constructor(args: {
+        kind: 'host-destroyed' | 'apply-failed';
+        applied: false | 'partial';
+        recovered?: boolean;
+        message?: string;
+    });
+}
+/**
+ * The native content-view surface the Compositor drives. In production this is
+ * an Electron `contentView` (`addChildView` / `removeChildView`); in tests it is
+ * a faithful fake. `children()` returns the current order, LAST = topmost.
+ */
+export interface ContentViewHost {
+    /** Already-mounted ref → raise to top (no remove, no reload); new ref →
+     * append to the end (top). */
+    addChildView(v: NativeViewRef): void;
+    removeChildView(v: NativeViewRef): void;
+    readonly isDestroyed: boolean;
+    /** Current child order; LAST element is the topmost. */
+    children(): readonly NativeViewRef[];
+}
+export interface Compositor {
+    /** Idempotent attach. A view STILL mounted → pure no-op (unchanged
+     * orderKey/mountSeq, zero host calls). A new view (or one re-mounted after
+     * unmount) → fresh mountSeq, lands at the top (end) of its zone. */
+    mount(view: NativeViewRef, opts?: {
+        zone?: number;
+    }): void;
+    /** Detach a view. A subsequent mount of the same id is a NEW instance. */
+    unmount(viewId: string): void;
+    /** Move a view: `before` slots it immediately before that anchor (midpoint of
+     * the anchor and its predecessor); `before: null` sends it to the end (top)
+     * of the zone. `zone` moves it to a different zone. An illegal `before`
+     * (unknown / unmounted id, or one whose zone conflicts with an explicit
+     * `zone`) throws SYNCHRONOUSLY. */
+    reorder(viewId: string, opts: {
+        zone?: number;
+        before?: string | null;
+    }): void;
+    /** Apply the folded target state to the host with the minimal add/remove
+     * sequence (LIS-preserving). Returns void on success. Throws a typed
+     * {@link CommitError} on failure: `kind:'host-destroyed'` (applied:false) when
+     * the host is destroyed and there are ADDITIONS to apply — thrown BEFORE
+     * touching native; `kind:'apply-failed'` (applied:'partial') when a native
+     * call throws mid-apply, after a best-effort rollback to the pre-apply
+     * snapshot (`recovered` flags whether the snapshot was restored). A no-op
+     * commit, and a destroyed host with ONLY removals pending, are SILENT. */
+    commit(): void;
+    /** Fold the intent state to EMPTY and commit, removing every native view
+     * this window's compositor mounted from the host. The resulting commit is
+     * REMOVALS-ONLY, so it reuses {@link commit}'s teardown-friendly
+     * "destroyed host + only removals → silent" path (A1.2.1): on an
+     * already-destroyed host it makes zero host calls and throws nothing.
+     *
+     * Optional on the interface so a partial test double (or a caller that only
+     * needs mount/unmount/reorder/commit) still structurally satisfies
+     * `Compositor`; the real {@link createCompositor} always implements it. */
+    detachAll?(): void;
+}
+export declare function createCompositor(host: ContentViewHost): Compositor;
+//# sourceMappingURL=compositor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compositor.d.ts","sourceRoot":"","sources":["../../src/main/compositor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnD;;;;;;;GAOG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,cAAc,CAAA;IAChD,QAAQ,CAAC,OAAO,EAAE,KAAK,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;gBAChB,IAAI,EAAE;QACjB,IAAI,EAAE,gBAAgB,GAAG,cAAc,CAAA;QACvC,OAAO,EAAE,KAAK,GAAG,SAAS,CAAA;QAC1B,SAAS,CAAC,EAAE,OAAO,CAAA;QACnB,OAAO,CAAC,EAAE,MAAM,CAAA;KAChB;CAOD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;kCAC8B;IAC9B,YAAY,CAAC,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IACpC,eAAe,CAAC,CAAC,EAAE,aAAa,GAAG,IAAI,CAAA;IACvC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,wDAAwD;IACxD,QAAQ,IAAI,SAAS,aAAa,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,UAAU;IACzB;;wEAEoE;IACpE,KAAK,CAAC,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAC1D,0EAA0E;IAC1E,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B;;;;uCAImC;IACnC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAA;IAC9E;;;;;;;8EAO0E;IAC1E,MAAM,IAAI,IAAI,CAAA;IACd;;;;;;;;+EAQ2E;IAC3E,SAAS,CAAC,IAAI,IAAI,CAAA;CACnB;AAkBD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,CA2PlE"}

package/dist/main/connection.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Connection-layer primitive (`Connection` / `ConnectionRegistry`) described in
+ * packages/electron-deck/docs/foundation.md §4.
+ *
+ * A `Connection` is one trusted webContents (keyed by the unforgeable `wc.id`).
+ * It holds a single `DisposableRegistry` as its "lifetime segment" container.
+ * The segment tears down deterministically (LIFO) on hard-destroy
+ * (`wc.once('destroyed')`) or soft-reuse (`reset(id)`):
+ *   - hard destroy → dispose segment, fire 'closed' once, de-register.
+ *   - soft reset   → dispose segment, swap in a fresh registry, fire 'reset',
+ *                    connection stays alive & registered.
+ *
+ * §4.3: the terminal hook is `'destroyed'` (NOT `'render-process-gone'`), and
+ * `DisposableRegistry.disposeAll` is async (LIFO) — so close/reset are async.
+ */
+import type { WebContents } from 'electron';
+import { type Disposable } from './disposable.js';
+export interface Connection {
+    readonly id: number;
+    readonly webContents: WebContents;
+    readonly alive: boolean;
+    /** Register a resource cleaned up with the current lifetime segment; the
+     * returned Disposable releases it early. */
+    own(d: Disposable | (() => void)): Disposable;
+    /** Connection-level lifecycle events; returns an unsubscribe Disposable. */
+    on(ev: 'reset' | 'closed', cb: () => void): Disposable;
+}
+export interface ConnectionRegistry {
+    /** Build/fetch the connection for a (trusted) webContents; idempotent. */
+    acquire(wc: WebContents): Connection;
+    get(id: number): Connection | undefined;
+    all(): readonly Connection[];
+    /** Soft reuse: dispose the current segment, then swap in a fresh registry. */
+    reset(id: number): void;
+}
+export declare function createConnectionRegistry(): ConnectionRegistry;
+//# sourceMappingURL=connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/main/connection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAKrE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB;gDAC4C;IAC5C,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,UAAU,CAAA;IAC7C,4EAA4E;IAC5E,EAAE,CAAC,EAAE,EAAE,OAAO,GAAG,QAAQ,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,UAAU,CAAA;CACvD;AAED,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,EAAE,WAAW,GAAG,UAAU,CAAA;IACpC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;IACvC,GAAG,IAAI,SAAS,UAAU,EAAE,CAAA;IAC5B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAmBD,wBAAgB,wBAAwB,IAAI,kBAAkB,CAmJ7D"}

package/dist/main/debug-tap.d.ts

@@ -0,0 +1,55 @@
+/**
+ * debugTap (foundation.md §7) — a flag-gated ring buffer for observing an
+ * IPC / cross-wc bridge message stream.
+ *
+ * Hung on a dispatch chokepoint (e.g. bridge-router's SERVICE_INVOKE /
+ * RENDER_INVOKE / PUBLISH / API_RESPONSE handlers), it records per-message
+ * metadata — connection id / channel / direction / appSession / duration /
+ * error — into a bounded ring so a hidden panel (or a test) can inspect the
+ * last N messages when debugging the cross-wc state machine.
+ *
+ * Design constraints:
+ *  - Default OFF: `record()` is a near-free no-op when disabled, so the hot
+ *    path costs nothing in production unless the flag is set.
+ *  - Caller-supplied `ts`: the electron-deck package never calls `Date.now()`
+ *    (determinism / resumability), so each entry carries a timestamp the
+ *    caller stamps.
+ *  - Bounded: a finite ring (default 1000) evicts oldest-first; it never grows
+ *    without bound.
+ */
+export interface DebugTapEntry {
+    /** Caller-stamped timestamp (ms). The primitive never reads the clock. */
+    ts: number;
+    /** The channel / message kind (e.g. 'SERVICE_INVOKE', 'API_RESPONSE'). */
+    channel: string;
+    /** Ingress (main received) vs egress (main sent). */
+    direction: 'in' | 'out';
+    /** webContents.id of the connection this message is attributed to. */
+    connectionId?: number;
+    /** bridge-router app session this message routes within, if known. */
+    appSessionId?: string;
+    /** For request/response pairs: how long the handler took (ms). */
+    durationMs?: number;
+    /** Error message if the message produced a failure. */
+    error?: string;
+    /** Short human-readable summary of the payload (no large blobs). */
+    summary?: string;
+}
+export interface DebugTap {
+    /** Whether recording is on. When false, `record` is a no-op. */
+    readonly enabled: boolean;
+    /** Append one entry to the ring (no-op when disabled). */
+    record(entry: DebugTapEntry): void;
+    /** Snapshot of buffered entries, oldest → newest. Safe to retain/mutate. */
+    entries(): readonly DebugTapEntry[];
+    /** Empty the ring. */
+    clear(): void;
+}
+export interface DebugTapOptions {
+    /** Default false — the tap is OFF unless explicitly enabled. */
+    enabled?: boolean;
+    /** Max retained entries; oldest evicted past this. Default 1000. */
+    capacity?: number;
+}
+export declare function createDebugTap(options?: DebugTapOptions): DebugTap;
+//# sourceMappingURL=debug-tap.d.ts.map

package/dist/main/debug-tap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-tap.d.ts","sourceRoot":"","sources":["../../src/main/debug-tap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,EAAE,EAAE,MAAM,CAAA;IACV,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,SAAS,EAAE,IAAI,GAAG,KAAK,CAAA;IACvB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,0DAA0D;IAC1D,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAA;IAClC,4EAA4E;IAC5E,OAAO,IAAI,SAAS,aAAa,EAAE,CAAA;IACnC,sBAAsB;IACtB,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAID,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CA8BtE"}

package/dist/main/disposable.d.ts

@@ -0,0 +1,18 @@
+export interface Disposable {
+    dispose(): void | Promise<void>;
+}
+export type DisposeFn = () => void | Promise<void>;
+export declare function toDisposable(fn: DisposeFn): Disposable;
+export declare class DisposableRegistry implements Disposable {
+    private entries;
+    private _disposed;
+    /**
+     * Number of live entries. A wrapper's `dispose` splices its entry out and
+     * `disposeAll` clears the array, so `entries.length` is the live count.
+     */
+    get size(): number;
+    add(d: Disposable | DisposeFn): Disposable;
+    disposeAll(): Promise<void>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=disposable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"disposable.d.ts","sourceRoot":"","sources":["../../src/main/disposable.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAChC;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAElD,wBAAgB,YAAY,CAAC,EAAE,EAAE,SAAS,GAAG,UAAU,CAStD;AAOD,qBAAa,kBAAmB,YAAW,UAAU;IACnD,OAAO,CAAC,OAAO,CAAc;IAC7B,OAAO,CAAC,SAAS,CAAQ;IAEzB;;;OAGG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU;IAmBpC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBjC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAGzB"}

package/dist/main/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@dimina-kit/electron-deck/main` — main-process foundation primitives.
+ *
+ * The connection layer (foundation.md §4): one `Connection` per trusted
+ * webContents, owning a single `DisposableRegistry` lifetime segment that tears
+ * down deterministically on hard-destroy or soft-reuse. devtools (and qdmp)
+ * consume this as the substrate for connection-scoped resource ownership.
+ */
+export { createConnectionRegistry, type Connection, type ConnectionRegistry, } from './connection.js';
+export { DisposableRegistry, toDisposable, type Disposable, type DisposeFn, } from './disposable.js';
+export { createScope, type Scope } from './scope.js';
+export { createCompositor, CommitError, type Compositor, type ContentViewHost, type NativeViewRef, } from './compositor.js';
+export { createViewHandle, type ViewHandle, type ViewHandleDeps, type NativeView, type PlaceTarget, type Placement, type Bounds, } from './view-handle.js';
+export { createLogger, setLogLevel, type Logger } from './logger.js';
+export { createDebugTap, type DebugTap, type DebugTapEntry, type DebugTapOptions, } from './debug-tap.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/main/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,wBAAwB,EACxB,KAAK,UAAU,EACf,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,SAAS,GACf,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,MAAM,GACZ,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,EACL,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAA"}