@deepseek-ai/dsh-client-ui-slots 0.0.1-rc.2 → 0.0.1-rc.3

package/README.i18n.yaml

@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-slots/README.md
 README.md: 7ee2a3d22c2a41b0e5c356c52d383a047cf99029
-README.zh.md: 793bb2d1f77e02e34a41fab16b2c2c64b78744dc
+README.zh.md: 0a61ec43d575429616ad5658228d1e9c93ef8462

package/README.zh.md

@@ -4,22 +4,22 @@
 
 Slot 注册表纯核心、slot 终端设计：SlotMap 声明合并、SlotCore 上唯一的 `register` 组合 API、四 share 组件 props 类型家族、store seat 类型家族，以及 renderer 安装约定。只使用 React 类型；该包不依赖 React，也不依赖 Cordis。
 
-一次 `register({ name, children?, store?, inject?, ...kind }, Component)` 调用会向已声明 slot 贡献一个组件，同时声明子 slot（声明 = 渲染授权 = 运行时规范，三者共用一张表）、store seat 以及注册方的业务表层。组件会在调用点依据 `ComposedProps` 接受检查；该类型是四个 share 的交集，每个 share 都从各自的唯一真源派生：
+一次 `register({ name, children?, store?, inject?, ...kind }, Component)` 调用会向已声明 slot 贡献一个组件，同时声明子 slot（声明 = 渲染授权 = 运行时规范，三者共用一张表）、store seat 以及注册方的业务表层。组件会在调用点依据 `ComposedProps` 接受类型检查；该类型是四个 share 的交集，每个 share 都从各自的唯一真源派生：
 
 | share | 类型 | 来源 |
 |---|---|---|
-| runtime | `PropsRuntime<K>` | SlotMap 条目：`owner`（父级 renderSlot 调用点）+ Session 标准工具包 + 全局 seat |
+| 运行时 | `PropsRuntime<K>` | SlotMap 条目：`owner`（父级 renderSlot 调用点）+ 会话标准工具包 + 全局 seat |
 | child render | `PropsRenderSlots<S>` | register 调用的 `children` key 集合（静态缩窄的 `renderSlot`） |
-| store | `PropsStore<H>` | 已声明 handle：`useStore` selector hook + 移除 draft 的 `actions` |
+| store | `PropsStore<H>` | 已声明 handle：`useStore` selector 钩子 + 移除 draft 的 `actions` |
 | business | `I` | 从 `inject` factory 返回值推断 |
 
 chain-kind slot 会反转键控路由：条目自行提名，而不是由分发点选择 `entryKey`。每次注册都携带一个纯 `ChainSelect` selector（另有可选的升序 `priority`，相同值按注册顺序处理）；第一个非 null 返回值选中其条目，并成为组件的 `matched` prop；全部返回 null 时则使用 owner 的 `renderSlotChain` fallback（`ChainRenderOpts`）。
 
-标准工具包接口（`SessionStandardProps`、`GlobalStandardProps`）在这里声明为空，由 runtime 包合并（与 SlotMap key 相同的 declare-merge 模式）。renderer 会把运行时 Session 和 Workspace observable source 绑定为 selector hook。Inject factory 参数从声明派生（`InjectParams`）：Session slot 获得 `sessionId`；声明 store 时追加 baked `actions`；没有其他参数，数据访问位于 apply 闭包的 ctx 中。
+标准工具包接口（`SessionStandardProps`、`GlobalStandardProps`）在这里声明为空，由运行时包合并（与 SlotMap key 相同的 declare-merge 模式）。renderer 会把运行时会话和 Workspace observable source 绑定为 selector 钩子。Inject factory 参数从声明派生（`InjectParams`）：会话 slot 获得 `sessionId`；声明 store 时追加 baked `actions`；没有其他参数，数据访问位于 apply 闭包的 ctx 中。
 
-store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于 runtime 包（引擎所属位置），并满足这里导出的 `DefineStore` 约定。引擎产物与 renderer host 约定携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React hook；hook 绑定属于渲染机制，只有 props 约定 hook 类型（`SnapshotSelectorHook`）位于这里。
+store 家族（输入 `defineStore` 规范／输出 `StoreHandle<T, A>`）为 store seat 建模：`init` 推断状态 schema；`actions` 是完整的 draft-transform 写入集合；`BakedActions` 移除 draft 参数，成为组件和 inject factory 收到的回调。`defineStore` 值实现位于运行时包（引擎所属位置），并满足这里导出的 `DefineStore` 约定。引擎产物与 renderer host 约定携带裸快照 source（`getSnapshot`／`subscribe`），绝不携带 React 钩子；钩子绑定属于渲染机制，只有 props 约定钩子类型（`SnapshotSelectorHook`）位于这里。
 
-`SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与折叠时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装约定（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
+`SlotCore` 在构造时预置 `'root'` slot，并强制执行加载时验证（注册未声明 slot、重复声明子项、在两个 scope 下使用同一个共享 handle、chain 注册缺少 `select`，这些情况都在 register 时抛出）。条目的 disposer 会递归移除其声明的子 slot：账本行、贡献和 store 挂载都会随同一生命周期结束而移除。每个 key 还携带一个 declaration epoch（声明代次），它只在声明与移除时递增；运行时将其用于 [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection)，且与普通条目版本相互独立。`renderer.ts` 携带安装约定（`SlotRenderer`、`SlotRendererHost`）以及 `StaleAuthorizationError`／`SlotOwnershipError`；实现在 web-react 中，安装则在外壳启动中完成。
 
 ## 模型体验
 

package/lib/index.js

@@ -32,7 +32,9 @@ const NO_ENTRIES = Object.freeze([]);
 * fire); {@link SlotCore.subscribeDeclaration} fires synchronously for each
 * declaration lifetime boundary; {@link SlotCore.subscribe} notifications
 * batch per microtask, so N same-tick mutations produce one notification per
-* touched key.
+* touched key. Entry crash reports ({@link SlotCore.reportEntryError}) ride
+* the same mutation channel when they abdicate, then notify
+* {@link SlotCore.onEntryError} synchronously.
 */
 var SlotCore = class {
 	records = /* @__PURE__ */ new Map();
@@ -41,6 +43,15 @@ var SlotCore = class {
 	handleScopes = /* @__PURE__ */ new Map();
 	dirty = /* @__PURE__ */ new Set();
 	flushScheduled = false;
+	/**
+	* Entries retired by an abdicating crash report
+	* ({@link SlotCore.reportEntryError}): excluded from
+	* {@link SlotCore.entriesOfSlot} projections for the rest of their
+	* registration's life, while the registration itself stays on the ledger
+	* (disposal authority remains with the registrant).
+	*/
+	abdicated = /* @__PURE__ */ new WeakSet();
+	entryErrorListeners = /* @__PURE__ */ new Set();
 	constructor() {
 		const root = this.record("root");
 		root.spec = {
@@ -54,18 +65,26 @@ var SlotCore = class {
 		const rec = this.records.get(options.name);
 		if (!rec?.spec) throw new Error(`slot "${options.name}" is not declared (a parent entry's children table must declare it)`);
 		const spec = rec.spec;
+		const priority = options.priority ?? 0;
+		const occupantHint = (occupant) => `at priority ${priority}${occupant.registrant !== void 0 ? ` (registered by ${occupant.registrant})` : ""} — register at a different priority to shadow it (lowest renders)`;
 		switch (spec.kind) {
-			case "single":
-				if (rec.entries.length > 0) throw new Error(`single slot "${options.name}" already has a registration`);
+			case "single": {
+				const occupant = rec.entries.find((e) => (e.options.priority ?? 0) === priority);
+				if (occupant) throw new Error(`single slot "${options.name}" already has a registration ${occupantHint(occupant)}`);
 				break;
-			case "keyed":
+			}
+			case "keyed": {
 				if (options.key === void 0) throw new Error(`keyed slot "${options.name}" requires options.key`);
-				if (rec.entries.some((e) => e.options.key === options.key)) throw new Error(`keyed slot "${options.name}" already has an entry for key "${options.key}"`);
+				const occupant = rec.entries.find((e) => e.options.key === options.key && (e.options.priority ?? 0) === priority);
+				if (occupant) throw new Error(`keyed slot "${options.name}" already has an entry for key "${options.key}" ${occupantHint(occupant)}`);
 				break;
-			case "list":
+			}
+			case "list": {
 				if (options.id === void 0) throw new Error(`list slot "${options.name}" requires options.id`);
-				if (rec.entries.some((e) => e.options.id === options.id)) throw new Error(`list slot "${options.name}" already has an entry with id "${options.id}"`);
+				const occupant = rec.entries.find((e) => e.options.id === options.id && (e.options.priority ?? 0) === priority);
+				if (occupant) throw new Error(`list slot "${options.name}" already has an entry with id "${options.id}" ${occupantHint(occupant)}`);
 				break;
+			}
 			case "chain":
 				if (options.select === void 0) throw new Error(`chain slot "${options.name}" requires options.select`);
 				break;
@@ -100,8 +119,7 @@ var SlotCore = class {
 			...options.registrant !== void 0 ? { registrant: options.registrant } : {}
 		};
 		const next = [...rec.entries, entry];
-		if (spec.kind === "list") next.sort((a, b) => (a.options.order ?? 0) - (b.options.order ?? 0));
-		if (spec.kind === "chain") next.sort((a, b) => (a.options.priority ?? 0) - (b.options.priority ?? 0));
+		next.sort(spec.kind === "list" ? (a, b) => (a.options.priority ?? 0) - (b.options.priority ?? 0) || (a.options.order ?? 0) - (b.options.order ?? 0) : (a, b) => (a.options.priority ?? 0) - (b.options.priority ?? 0));
 		rec.entries = next;
 		this.markDirty(options.name, rec);
 		if (options.children) {
@@ -110,6 +128,7 @@ var SlotCore = class {
 				const childRec = this.record(childKey);
 				childRec.spec = childSpec;
 				childRec.declaredBy = `an entry in "${options.name}"${options.registrant ? ` (${options.registrant})` : ""}`;
+				childRec.parent = options.name;
 				childRec.declarationEpoch += 1;
 				declarations.push([childKey, childRec]);
 			}
@@ -146,6 +165,34 @@ var SlotCore = class {
 		return this.records.get(key)?.entries ?? NO_ENTRIES;
 	}
 	/**
+	* Project a key's entries to its shadowing winners: the first live
+	* (non-abdicated) entry of each cell in priority order — single: the slot
+	* is one cell; keyed: one cell per `key`; list: one cell per `id` (winners
+	* keep ledger sequence; list renderers still refine display by `order`).
+	* Chain keys return the raw entries unchanged: election consumes every
+	* entry, shadowing does not apply. The raw {@link SlotCore.entries} view
+	* stays the inspection surface. Builds a fresh array per call — a render
+	* body read, not a uSES getSnapshot source.
+	* @param key - slot key (dynamic: the render machinery holds keys as strings).
+	* @returns the winning entry per occupied cell (empty while undeclared).
+	*/
+	entriesOfSlot(key) {
+		const rec = this.records.get(key);
+		if (!rec?.spec) return NO_ENTRIES;
+		const kind = rec.spec.kind;
+		if (kind === "chain") return rec.entries;
+		const heads = [];
+		const seenCells = /* @__PURE__ */ new Set();
+		for (const entry of rec.entries) {
+			if (this.abdicated.has(entry)) continue;
+			const cell = kind === "keyed" ? entry.options.key : kind === "list" ? entry.options.id : void 0;
+			if (seenCells.has(cell)) continue;
+			seenCells.add(cell);
+			heads.push(entry);
+		}
+		return heads;
+	}
+	/**
 	* Look up a slot's declared spec, narrowed by the SlotMap key.
 	* @param key - SlotMap key.
 	* @returns the spec, or undefined while undeclared.
@@ -164,6 +211,47 @@ var SlotCore = class {
 		return this.records.get(key)?.spec;
 	}
 	/**
+	* Export the current declaration topology without components or executable hooks.
+	* @param root - exact Slot key to select; omitted returns every live root.
+	* @returns selected live Slot trees, or an empty array when `root` is unavailable.
+	*/
+	snapshot(root) {
+		const build = (name, seen) => {
+			const record = this.records.get(name);
+			if (record?.spec === void 0 || seen.has(name)) return void 0;
+			const branch = new Set(seen);
+			branch.add(name);
+			const active = new Set(this.entriesOfSlot(name));
+			const children = [...this.records.entries()].filter(([, candidate]) => candidate.spec !== void 0 && candidate.parent === name).flatMap(([child]) => {
+				const node = build(child, branch);
+				return node === void 0 ? [] : [node];
+			});
+			return {
+				name,
+				kind: record.spec.kind,
+				scope: record.spec.scope,
+				...record.declaredBy === void 0 ? {} : { declaredBy: record.declaredBy },
+				occupants: record.entries.map((entry) => ({
+					...entry.registrant === void 0 ? {} : { registrant: entry.registrant },
+					...entry.options.key === void 0 ? {} : { key: entry.options.key },
+					...entry.options.id === void 0 ? {} : { id: entry.options.id },
+					...entry.options.order === void 0 ? {} : { order: entry.options.order },
+					priority: entry.options.priority ?? 0,
+					active: active.has(entry)
+				})),
+				children
+			};
+		};
+		if (root !== void 0) {
+			const node = build(root, /* @__PURE__ */ new Set());
+			return node === void 0 ? [] : [node];
+		}
+		return [...this.records.entries()].filter(([, record]) => record.spec !== void 0 && (record.parent === void 0 || this.records.get(record.parent)?.spec === void 0)).flatMap(([name]) => {
+			const node = build(name, /* @__PURE__ */ new Set());
+			return node === void 0 ? [] : [node];
+		});
+	}
+	/**
 	* Read the declaration lifetime of a key. Entry additions and removals do
 	* not change it; declaration creation and collapse each advance it.
 	* @param key - slot key.
@@ -226,6 +314,47 @@ var SlotCore = class {
 		};
 	}
 	/**
+	* Renderer crash report from an entry boundary. Always notifies
+	* {@link SlotCore.onEntryError} listeners; with `info.abdicate` set (the
+	* shadowing kinds — single/keyed/list) it first retires the entry from its
+	* cell, one-shot: the record's version bumps through the ordinary mutation
+	* channel so outlets re-project onto the cell's next survivor, and a
+	* repeat abdicating report no-ops entirely. Chain crashes report with
+	* `abdicate: false` — election alternatives resolve at select time, so the
+	* entry keeps its cell and only the notification fires. The registration
+	* itself stays on the ledger either way — raw {@link SlotCore.entries}
+	* still lists the entry and its disposer keeps working.
+	* @param key - slot key the entry rendered under.
+	* @param entry - the crashed entry.
+	* @param error - the crash cause, forwarded to listeners verbatim.
+	* @param info - `abdicate`: whether the crash retires the entry from its cell.
+	*/
+	reportEntryError(key, entry, error, info) {
+		if (info.abdicate) {
+			if (this.abdicated.has(entry)) return;
+			this.abdicated.add(entry);
+			const rec = this.records.get(key);
+			if (rec !== void 0) this.markDirty(key, rec);
+		}
+		for (const fn of [...this.entryErrorListeners]) fn(key, entry, error, { abdicated: info.abdicate });
+	}
+	/**
+	* Observe entry boundary crashes (every render-time entry failure the
+	* boundaries contain, abdicating or not) — the supervision seam for hosts
+	* mirroring contribution health. Fires synchronously per report, after the
+	* registry mutated for abdicating crashes (same listener discipline as
+	* {@link SlotCore.onMutate}).
+	* @param fn - called with the slot key, the crashed entry, the crash
+	* cause, and `abdicated`: whether the crash retired the entry from its cell.
+	* @returns unsubscribe.
+	*/
+	onEntryError(fn) {
+		this.entryErrorListeners.add(fn);
+		return () => {
+			this.entryErrorListeners.delete(fn);
+		};
+	}
+	/**
 	* Cascade for a removed entry: release its store mount and collapse every
 	* child slot it declared — specs clear, contributions empty (their stale
 	* disposers no-op), recursively down the declaration tree. One lifecycle
@@ -244,6 +373,7 @@ var SlotCore = class {
 			const doomed = childRec.entries;
 			childRec.spec = void 0;
 			childRec.declaredBy = void 0;
+			childRec.parent = void 0;
 			childRec.declarationEpoch += 1;
 			childRec.entries = NO_ENTRIES;
 			this.markDirty(childKey, childRec);
@@ -257,6 +387,7 @@ var SlotCore = class {
 			rec = {
 				spec: void 0,
 				declaredBy: void 0,
+				parent: void 0,
 				declarationEpoch: 0,
 				entries: NO_ENTRIES,
 				version: 0,

package/lib/invariant.js

@@ -10,7 +10,7 @@ const name = "client-ui-slots-invariant";
 const inject = ["invariants"];
 /**
 * No runtime invariant: a zero-dependency pure registry core — it emits no
-* cordis events itself (the runtime SlotsService wrapper owns the event
+* cordis events itself (the runtime SlotRegistry wrapper owns the event
 * bridge and its invariants); define/register/dispose sequencing is asserted
 * directly by this package's behavior specs.
 */

package/lib/types/index.d.ts

@@ -371,13 +371,20 @@ export type InjectParams<K extends keyof SlotMap & string, H> = ScopeOf<K> exten
  * without re-registration. Owners resolve through {@link resolveSlotLabel}.
  */
 export type SlotLabel = string | (() => string);
-/** Kind shape fields carried in register options (keyed dispatch key; list id/order/label; chain select/priority). */
+/**
+ * Kind shape fields carried in register options (keyed dispatch key; list
+ * id/order/label; chain select/priority; non-chain priority = cell shadowing rank).
+ */
 export type KindOptions<K extends keyof SlotMap & string, EntryKey extends EntryKeyOf<K>, M = never> = SlotMap[K]['kind'] extends 'keyed' ? {
     key: EntryKey;
+    /** Cell shadowing rank (ascending, default 0, lowest renders; same key + same priority throws — see {@link SlotCore.register}). */
+    priority?: number;
 } : SlotMap[K]['kind'] extends 'list' ? {
     id: string;
     order?: number;
     label?: SlotLabel;
+    /** Cell shadowing rank (ascending, default 0, lowest renders; same id + same priority throws — see {@link SlotCore.register}). */
+    priority?: number;
 } : SlotMap[K]['kind'] extends 'chain' ? {
     /** Routing selector, mandatory on chain entries; `M` (the component's `matched` prop) infers from its return. */
     select: ChainSelect<SlotMap[K] extends {
@@ -385,7 +392,13 @@ export type KindOptions<K extends keyof SlotMap & string, EntryKey extends Entry
     } ? O : object, M>;
     /** Explicit chain position (ascending, default 0, lower tries first); ties keep registration = assembly order. */
     priority?: number;
-} : object;
+} : {
+    /**
+     * Cell shadowing rank (ascending, default 0, lowest renders; a
+     * same-priority second registration throws — see {@link SlotCore.register}).
+     */
+    priority?: number;
+};
 /**
  * Compile-time presence check: an entry declaring children MUST consume
  * `renderSlot` (or `renderSlotChain` when its only children are chain slots)
@@ -451,6 +464,36 @@ export interface StoredEntry {
  * @returns the display string, or undefined when the entry declared none.
  */
 export declare function resolveSlotLabel(label: SlotLabel | undefined): string | undefined;
+/** JSON-safe live occupant returned by slot inspection. */
+export interface LiveSlotOccupant {
+    /** Plugin or package that registered the entry, when known. */
+    registrant?: string;
+    /** Keyed-slot cell. */
+    key?: string;
+    /** List-slot cell. */
+    id?: string;
+    /** List display order. */
+    order?: number;
+    /** Shadowing or chain priority. */
+    priority: number;
+    /** Whether the renderer currently selects this entry. */
+    active: boolean;
+}
+/** JSON-safe live slot declaration tree. */
+export interface LiveSlotNode {
+    /** Exact SlotMap key. */
+    name: string;
+    /** Slot cardinality. */
+    kind: SlotKind;
+    /** Runtime data scope. */
+    scope: SlotScope;
+    /** Diagnostic owner of this declaration. */
+    declaredBy?: string;
+    /** Current registrations in ledger order. */
+    occupants: LiveSlotOccupant[];
+    /** Slots declared by entries mounted in this slot. */
+    children: LiveSlotNode[];
+}
 /**
  * Pure slot registry (no cordis; event emission and the renderer installation contract
  * live in the runtime Service wrapper).
@@ -463,7 +506,9 @@ export declare function resolveSlotLabel(label: SlotLabel | undefined): string |
  * fire); {@link SlotCore.subscribeDeclaration} fires synchronously for each
  * declaration lifetime boundary; {@link SlotCore.subscribe} notifications
  * batch per microtask, so N same-tick mutations produce one notification per
- * touched key.
+ * touched key. Entry crash reports ({@link SlotCore.reportEntryError}) ride
+ * the same mutation channel when they abdicate, then notify
+ * {@link SlotCore.onEntryError} synchronously.
  */
 export declare class SlotCore {
     private records;
@@ -472,6 +517,15 @@ export declare class SlotCore {
     private handleScopes;
     private dirty;
     private flushScheduled;
+    /**
+     * Entries retired by an abdicating crash report
+     * ({@link SlotCore.reportEntryError}): excluded from
+     * {@link SlotCore.entriesOfSlot} projections for the rest of their
+     * registration's life, while the registration itself stays on the ledger
+     * (disposal authority remains with the registrant).
+     */
+    private abdicated;
+    private entryErrorListeners;
     constructor();
     /**
      * Contribute a component to a declared slot and (optionally) declare child
@@ -481,11 +535,18 @@ export declare class SlotCore {
      * re-checks nothing): registering into an undeclared slot throws; declaring
      * an already-declared child key throws (one declarer per slot — the message
      * names the first declarer); mounting one shared store handle under slots
-     * of different scopes throws. Kind constraints: single — duplicate
-     * registration throws; keyed — missing/duplicate `key` throws; list —
-     * missing/duplicate `id` throws; chain — missing `select` throws (the
+     * of different scopes throws. Kind constraints: keyed — missing `key`
+     * throws; list — missing `id` throws; chain — missing `select` throws (the
      * selector is the entry's routing seat, see {@link ChainSelect}).
      *
+     * Shadowing (single/keyed/list): entries sharing one cell (single — the
+     * slot itself; keyed — same `key`; list — same `id`) coexist at distinct
+     * priorities, sorted ascending with ties keeping registration order; the
+     * cell's lowest live entry renders ({@link SlotCore.entriesOfSlot}). A
+     * second registration at an occupied cell's exact priority (default 0)
+     * throws naming the occupant, so priority-less composition keeps the
+     * historical one-occupant-per-cell fail-loud.
+     *
      * Lifecycle: the disposer removes the contribution AND collapses every
      * declared child slot (child entries clear recursively; their stale
      * disposers become no-ops) — one lifecycle axis, no dangling state.
@@ -531,6 +592,19 @@ export declare class SlotCore {
      * @returns entries in registration (list: order) sequence.
      */
     entries(key: string): readonly StoredEntry[];
+    /**
+     * Project a key's entries to its shadowing winners: the first live
+     * (non-abdicated) entry of each cell in priority order — single: the slot
+     * is one cell; keyed: one cell per `key`; list: one cell per `id` (winners
+     * keep ledger sequence; list renderers still refine display by `order`).
+     * Chain keys return the raw entries unchanged: election consumes every
+     * entry, shadowing does not apply. The raw {@link SlotCore.entries} view
+     * stays the inspection surface. Builds a fresh array per call — a render
+     * body read, not a uSES getSnapshot source.
+     * @param key - slot key (dynamic: the render machinery holds keys as strings).
+     * @returns the winning entry per occupied cell (empty while undeclared).
+     */
+    entriesOfSlot(key: string): readonly StoredEntry[];
     /**
      * Look up a slot's declared spec, narrowed by the SlotMap key.
      * @param key - SlotMap key.
@@ -545,6 +619,12 @@ export declare class SlotCore {
      * @returns the wide-typed spec, or undefined while undeclared.
      */
     specDynamic(key: string): SlotSpec<SlotEntryDef> | undefined;
+    /**
+     * Export the current declaration topology without components or executable hooks.
+     * @param root - exact Slot key to select; omitted returns every live root.
+     * @returns selected live Slot trees, or an empty array when `root` is unavailable.
+     */
+    snapshot(root?: string): LiveSlotNode[];
     /**
      * Read the declaration lifetime of a key. Entry additions and removals do
      * not change it; declaration creation and collapse each advance it.
@@ -586,6 +666,38 @@ export declare class SlotCore {
      * @returns unsubscribe.
      */
     onMutate(fn: (key: string) => void): () => void;
+    /**
+     * Renderer crash report from an entry boundary. Always notifies
+     * {@link SlotCore.onEntryError} listeners; with `info.abdicate` set (the
+     * shadowing kinds — single/keyed/list) it first retires the entry from its
+     * cell, one-shot: the record's version bumps through the ordinary mutation
+     * channel so outlets re-project onto the cell's next survivor, and a
+     * repeat abdicating report no-ops entirely. Chain crashes report with
+     * `abdicate: false` — election alternatives resolve at select time, so the
+     * entry keeps its cell and only the notification fires. The registration
+     * itself stays on the ledger either way — raw {@link SlotCore.entries}
+     * still lists the entry and its disposer keeps working.
+     * @param key - slot key the entry rendered under.
+     * @param entry - the crashed entry.
+     * @param error - the crash cause, forwarded to listeners verbatim.
+     * @param info - `abdicate`: whether the crash retires the entry from its cell.
+     */
+    reportEntryError(key: string, entry: StoredEntry, error: unknown, info: {
+        abdicate: boolean;
+    }): void;
+    /**
+     * Observe entry boundary crashes (every render-time entry failure the
+     * boundaries contain, abdicating or not) — the supervision seam for hosts
+     * mirroring contribution health. Fires synchronously per report, after the
+     * registry mutated for abdicating crashes (same listener discipline as
+     * {@link SlotCore.onMutate}).
+     * @param fn - called with the slot key, the crashed entry, the crash
+     * cause, and `abdicated`: whether the crash retired the entry from its cell.
+     * @returns unsubscribe.
+     */
+    onEntryError(fn: (key: string, entry: StoredEntry, error: unknown, info: {
+        abdicated: boolean;
+    }) => void): () => void;
     /**
      * Cascade for a removed entry: release its store mount and collapse every
      * child slot it declared — specs clear, contributions empty (their stale

package/lib/types/renderer.d.ts

@@ -8,7 +8,7 @@ import type { SlotEntryDef, SlotSpec, StoredEntry, Translate } from './index.ts'
  * active-locale or registry change; the renderer re-derives each entry's `t`
  * from (namespace, revision), so a locale switch hands out NEW function
  * references and memoized components re-render naturally. Implemented by the
- * locale plugin, installed through the runtime SlotsService (installLocale).
+ * locale plugin, installed through the runtime SlotRegistry (installLocale).
  * Install before the first render that needs the seat: outlets bind their
  * revision subscription at mount, and a face appearing later has no channel
  * to notify already-mounted outlets (the locale plugin is immediately-tier
@@ -94,7 +94,7 @@ export interface RenderOpts {
     /** Opaque occurrence context consumed only by function-valued injected Hooks. */
     hookContext?: unknown;
 }
-/** Host API the runtime SlotsService presents to the installed renderer. */
+/** Host API the runtime SlotRegistry presents to the installed renderer. */
 export interface SlotRendererHost {
     /**
      * Subscribe to a key's registration changes (microtask-batched).
@@ -115,6 +115,29 @@ export interface SlotRendererHost {
      * @returns entries in registration (list: order) sequence.
      */
     entriesOf(key: string): readonly StoredEntry[];
+    /**
+     * Shadowing winners per cell for a key — the render read for single/keyed/
+     * list dispatch: the first live (non-abdicated) entry of each cell in
+     * priority order; chain keys pass through unchanged (election consumes
+     * every entry). Fresh array per call — a render-body read, not a uSES
+     * getSnapshot source.
+     * @param key - slot key.
+     * @returns the winning entry per occupied cell.
+     */
+    entriesOfSlot(key: string): readonly StoredEntry[];
+    /**
+     * Report an entry boundary crash. With `info.abdicate` (shadowing kinds)
+     * the entry retires from its cell, one-shot, so the next survivor renders;
+     * chain crashes report without abdicating. The registration stays on the
+     * ledger either way.
+     * @param key - slot key the entry rendered under.
+     * @param entry - the crashed entry.
+     * @param error - the crash cause.
+     * @param info - `abdicate`: whether the crash retires the entry from its cell.
+     */
+    reportEntryError(key: string, entry: StoredEntry, error: unknown, info: {
+        abdicate: boolean;
+    }): void;
     /**
      * Declared runtime spec from the declarations ledger.
      * @param key - slot key.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-slots",
   "description": "Slot registry pure core: SlotMap declaration merging, single register composition API, four-share props types, store-seat types, renderer install seam",
-  "version": "0.0.1-rc.2",
+  "version": "0.0.1-rc.3",
   "publishConfig": {
     "access": "restricted"
   },
@@ -28,7 +28,7 @@
   "license": "BSD-3-Clause",
   "devDependencies": {
     "@types/react": "~18.3.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
     "@deepseek-ai/cordis": "^4.0.1-rc.1"
   },
   "files": [
@@ -37,7 +37,7 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
     "@deepseek-ai/cordis": "^4.0.1-rc.1"
   }
 }