@deepseek-ai/dsh-client-ui-slots 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# 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

package/README.md

@@ -0,0 +1,35 @@
+# @deepseek-ai/dsh-client-ui-slots
+
+English | [中文](README.zh.md)
+
+Slot registry pure core, slot terminal design: SlotMap declaration merging, the single `register` composition API on SlotCore, the four-share component-props type family, the store-seat type family, and the renderer installation contract. React types only at runtime — the package is React-free and cordis-free.
+
+One `register({ name, children?, store?, inject?, ...kind }, Component)` call contributes a component into a declared slot and, in the same breath, declares child slots (declaration = render authorization = runtime spec, one table), a store seat, and the registrant's business face. The component is checked at the call site against `ComposedProps` — the intersection of four shares, each derived from its single source of truth:
+
+| share | type | source |
+|---|---|---|
+| runtime | `PropsRuntime<K>` | SlotMap entry: `owner` (parent's renderSlot call site) + session standard kit + global seat |
+| child render | `PropsRenderSlots<S>` | the register call's `children` key set (statically narrowed `renderSlot`) |
+| store | `PropsStore<H>` | the declared handle: `useStore` selector hook + draft-stripped `actions` |
+| business | `I` | inferred from the `inject` factory's return |
+
+Chain-kind slots invert keyed routing — entries self-nominate instead of the dispatch site picking an `entryKey`: each registration carries a pure `ChainSelect` selector (plus optional ascending `priority`, ties in registration order), the first non-null return elects its entry and becomes the component's `matched` prop, and all-null falls to the owner's `renderSlotChain` fallback (`ChainRenderOpts`).
+
+The standard-kit interfaces (`SessionStandardProps`, `GlobalStandardProps`) are declared empty here and merged by the runtime package (same declare-merge pattern as SlotMap keys). The renderer binds the runtime's session and workspace observable sources into selector hooks. Inject factory parameters derive from the declaration (`InjectParams`): session slots get `sessionId`, a declared store appends baked `actions`, nothing else — data access lives in the apply closure's ctx.
+
+The store family (`defineStore` spec in / `StoreHandle<T, A>` out) types the store seat: `init` infers the state schema, `actions` is the complete draft-transform write set, `BakedActions` strips the draft parameter into the callbacks components and inject factories receive. The `defineStore` value implementation lives in the runtime package (the engine's home) and satisfies the `DefineStore` contract exported here. Engine products and the renderer host contract carry bare snapshot sources (`getSnapshot`/`subscribe`), never React hooks — hook binding belongs to the render machinery; only the props-contract hook type (`SnapshotSelectorHook`) lives here.
+
+`SlotCore` seeds the a-priori `'root'` slot at construction and enforces load-time validation (undeclared-slot registration, duplicate child declaration, one shared handle under two scopes, a chain registration without `select` — all throw at register). An entry's disposer collapses its declared child slots recursively: ledger rows, contributions, and store mounts die on one lifecycle axis. Each key also carries a declaration epoch that advances only on declaration and collapse; the runtime uses it for [`ctx.slots.inject`](../runtime/README.md#slot-declaration-injection), independently from ordinary entry versions. `renderer.ts` carries the installation contract (`SlotRenderer`, `SlotRendererHost`) plus `StaleAuthorizationError`/`SlotOwnershipError`; the implementation lives in web-react, the installation in the shell boot.
+
+## Model Experience
+
+None, as the slot registry is browser-side UI plumbing; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **`isLive` scans all records linearly** — fine at UI-plugin registration counts (tens); revisit with an entry→record backref if ledgers ever grow hot.
+- **The `__renders` phantom anchor is visible on `PropsRenderSlots`** — the same accepted noise as the type-chain design's `__accepts`: generic method signatures compare loosely across key unions, so the contravariant marker is what enforces "component key set ⊆ children declaration".

package/README.zh.md

@@ -0,0 +1,35 @@
+# @deepseek-ai/dsh-client-ui-slots
+
+[English](README.md) | 中文
+
+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 都从各自的唯一真源派生：
+
+| share | 类型 | 来源 |
+|---|---|---|
+| runtime | `PropsRuntime<K>` | SlotMap 条目：`owner`（父级 renderSlot 调用点）+ Session 标准工具包 + 全局 seat |
+| child render | `PropsRenderSlots<S>` | register 调用的 `children` key 集合（静态缩窄的 `renderSlot`） |
+| store | `PropsStore<H>` | 已声明 handle：`useStore` selector hook + 移除 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 中。
+
+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`）位于这里。
+
+`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 中，安装则在外壳启动中完成。
+
+## 模型体验
+
+无。slot 注册表属于浏览器侧 UI 接线；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **`isLive` 会线性扫描所有记录**：在 UI 插件的注册规模（数十项）下没有问题；如果账本变得频繁访问，再使用条目→记录反向引用改进。
+- **`__renders` 幻象锚点在 `PropsRenderSlots` 上可见**：这是与类型链设计的 `__accepts` 相同且已接受的噪声；泛型方法签名在 key 联合之间比较宽松，因此必须依靠逆变标记强制执行「组件 key 集合 ⊆ children 声明」。

package/lib/index.js

@@ -0,0 +1,292 @@
+//#region lib/types/renderer.js
+/** Thrown when a retained renderSlot binding is invoked after its declaring entry was disposed. */
+var StaleAuthorizationError = class extends Error {};
+/**
+* Thrown when a renderSlot binding is invoked for a key outside its entry's
+* children declaration (plain-JS backstop; typed callers are narrowed
+* statically).
+*/
+var SlotOwnershipError = class extends Error {};
+//#endregion
+//#region lib/types/index.js
+/**
+* Resolve a possibly-thunked list label at read time (thunks follow the
+* active locale; owners projecting ledger rows call this instead of reading
+* `options.label` raw).
+* @param label - the stored label.
+* @returns the display string, or undefined when the entry declared none.
+*/
+function resolveSlotLabel(label) {
+	return typeof label === "function" ? label() : label;
+}
+const NO_ENTRIES = Object.freeze([]);
+/**
+* Pure slot registry (no cordis; event emission and the renderer installation contract
+* live in the runtime Service wrapper).
+*
+* The 'root' slot is the one a-priori declaration, seeded at construction
+* (single/root, declared by the framework) — the render tree's root hole.
+*
+* Change propagation contract: versions bump and {@link SlotCore.onMutate}
+* fires synchronously per mutation (registry state is consistent when they
+* 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.
+*/
+var SlotCore = class {
+	records = /* @__PURE__ */ new Map();
+	mutateListeners = /* @__PURE__ */ new Set();
+	/** Shared-handle scope ledger: handle → the scope it first mounted under + live mount count. */
+	handleScopes = /* @__PURE__ */ new Map();
+	dirty = /* @__PURE__ */ new Set();
+	flushScheduled = false;
+	constructor() {
+		const root = this.record("root");
+		root.spec = {
+			kind: "single",
+			scope: "root"
+		};
+		root.declaredBy = "(built-in)";
+		root.declarationEpoch = 1;
+	}
+	register(options, component) {
+		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;
+		switch (spec.kind) {
+			case "single":
+				if (rec.entries.length > 0) throw new Error(`single slot "${options.name}" already has a registration`);
+				break;
+			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}"`);
+				break;
+			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}"`);
+				break;
+			case "chain":
+				if (options.select === void 0) throw new Error(`chain slot "${options.name}" requires options.select`);
+				break;
+		}
+		if (options.children) for (const childKey of Object.keys(options.children)) {
+			const childRec = this.records.get(childKey);
+			if (childRec?.spec) throw new Error(`slot "${childKey}" is already declared (by ${childRec.declaredBy ?? "an unknown entry"})`);
+		}
+		if (options.store !== void 0 && typeof options.store !== "function") {
+			const pinned = this.handleScopes.get(options.store);
+			if (pinned && pinned.scope !== spec.scope) throw new Error(`store handle mounted under "${options.name}" (scope "${spec.scope}") is already mounted under scope "${pinned.scope}" — one handle, one scope`);
+			if (pinned) pinned.count += 1;
+			else this.handleScopes.set(options.store, {
+				scope: spec.scope,
+				count: 1
+			});
+		}
+		const entry = {
+			component,
+			options: {
+				...options.key !== void 0 ? { key: options.key } : {},
+				...options.id !== void 0 ? { id: options.id } : {},
+				...options.order !== void 0 ? { order: options.order } : {},
+				...options.label !== void 0 ? { label: options.label } : {},
+				...options.priority !== void 0 ? { priority: options.priority } : {}
+			},
+			...options.select !== void 0 ? { select: options.select } : {},
+			...options.inject !== void 0 ? { inject: options.inject } : {},
+			...options.children !== void 0 ? { children: options.children } : {},
+			...options.store !== void 0 ? { store: options.store } : {},
+			...options.locale !== void 0 ? { locale: options.locale } : {},
+			...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));
+		rec.entries = next;
+		this.markDirty(options.name, rec);
+		if (options.children) {
+			const declarations = [];
+			for (const [childKey, childSpec] of Object.entries(options.children)) {
+				const childRec = this.record(childKey);
+				childRec.spec = childSpec;
+				childRec.declaredBy = `an entry in "${options.name}"${options.registrant ? ` (${options.registrant})` : ""}`;
+				childRec.declarationEpoch += 1;
+				declarations.push([childKey, childRec]);
+			}
+			for (const [childKey, childRec] of declarations) this.markDirty(childKey, childRec);
+			for (const [, childRec] of declarations) this.notifyDeclaration(childRec);
+		}
+		return () => {
+			if (!rec.entries.includes(entry)) return;
+			rec.entries = rec.entries.filter((e) => e !== entry);
+			this.markDirty(options.name, rec);
+			this.releaseEntry(entry);
+		};
+	}
+	/**
+	* Whether a previously obtained entry is still registered (the render
+	* machinery's stale-authorization probe: a retained renderSlot binding
+	* whose entry left the ledger must not render).
+	* @param entry - a previously read entry.
+	* @returns false once the entry's registration was disposed.
+	*/
+	isLive(entry) {
+		for (const rec of this.records.values()) if (rec.entries.includes(entry)) return true;
+		return false;
+	}
+	/**
+	* Snapshot the registered entries for a key. Returns the cached array
+	* reference (stable between mutations — safe as a uSES getSnapshot source);
+	* empty for keys not (or no longer) declared, so renderers may probe ahead
+	* of plugin load order.
+	* @param key - slot key (dynamic: the render machinery holds keys as strings).
+	* @returns entries in registration (list: order) sequence.
+	*/
+	entries(key) {
+		return this.records.get(key)?.entries ?? NO_ENTRIES;
+	}
+	/**
+	* Look up a slot's declared spec, narrowed by the SlotMap key.
+	* @param key - SlotMap key.
+	* @returns the spec, or undefined while undeclared.
+	*/
+	spec(key) {
+		return this.records.get(key)?.spec;
+	}
+	/**
+	* Dynamic-key escape hatch for spec lookup — renderers resolving keys they
+	* only hold as strings (generic dispatch) use this wide form; statically
+	* keyed callers use {@link SlotCore.spec}.
+	* @param key - candidate slot key.
+	* @returns the wide-typed spec, or undefined while undeclared.
+	*/
+	specDynamic(key) {
+		return this.records.get(key)?.spec;
+	}
+	/**
+	* 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.
+	* @returns monotonic epoch (0 before the first declaration).
+	*/
+	declarationEpoch(key) {
+		return this.records.get(key)?.declarationEpoch ?? 0;
+	}
+	/**
+	* Subscribe to registration changes for a key (microtask-batched).
+	* Subscribing ahead of declaration is allowed; the declaration notifies.
+	* @param key - slot key.
+	* @param fn - change callback.
+	* @returns unsubscribe.
+	*/
+	subscribe(key, fn) {
+		const rec = this.record(key);
+		rec.listeners.add(fn);
+		return () => {
+			rec.listeners.delete(fn);
+		};
+	}
+	/**
+	* Subscribe to declaration lifetime boundaries for a key. Notifications
+	* are synchronous so declaration teardown finishes before a subsequent
+	* same-tick registration can observe stale resources. Ordinary entry
+	* mutations do not notify this surface. A children table commits every
+	* sibling declaration before its first notification.
+	* @param key - slot key.
+	* @param fn - declaration or collapse callback.
+	* @returns unsubscribe.
+	*/
+	subscribeDeclaration(key, fn) {
+		const rec = this.record(key);
+		rec.declarationListeners.add(fn);
+		return () => {
+			rec.declarationListeners.delete(fn);
+		};
+	}
+	/**
+	* Monotonic version for a key, bumped synchronously per mutation so a
+	* uSES getSnapshot read is never stale when its batched notification lands.
+	* @param key - slot key.
+	* @returns current version (0 for untouched keys).
+	*/
+	getVersion(key) {
+		return this.records.get(key)?.version ?? 0;
+	}
+	/**
+	* Hook every mutation (the runtime Service wrapper bridges this to ctx.emit).
+	* Fires synchronously per mutation, unbatched — event semantics need one
+	* emission per change.
+	* @param fn - called with the mutated key.
+	* @returns unsubscribe.
+	*/
+	onMutate(fn) {
+		this.mutateListeners.add(fn);
+		return () => {
+			this.mutateListeners.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
+	* axis: ledger rows, slots, contributions, and store mounts die together.
+	*/
+	releaseEntry(entry) {
+		if (entry.store !== void 0 && typeof entry.store !== "function") {
+			const pinned = this.handleScopes.get(entry.store);
+			if (pinned && --pinned.count === 0) this.handleScopes.delete(entry.store);
+		}
+		if (!entry.children) return;
+		for (const childKey of Object.keys(entry.children)) {
+			const childRec = this.records.get(childKey);
+			/* v8 ignore next -- defensive: declaring always creates the record */
+			if (!childRec) continue;
+			const doomed = childRec.entries;
+			childRec.spec = void 0;
+			childRec.declaredBy = void 0;
+			childRec.declarationEpoch += 1;
+			childRec.entries = NO_ENTRIES;
+			this.markDirty(childKey, childRec);
+			this.notifyDeclaration(childRec);
+			for (const dead of doomed) this.releaseEntry(dead);
+		}
+	}
+	record(key) {
+		let rec = this.records.get(key);
+		if (!rec) {
+			rec = {
+				spec: void 0,
+				declaredBy: void 0,
+				declarationEpoch: 0,
+				entries: NO_ENTRIES,
+				version: 0,
+				listeners: /* @__PURE__ */ new Set(),
+				declarationListeners: /* @__PURE__ */ new Set()
+			};
+			this.records.set(key, rec);
+		}
+		return rec;
+	}
+	markDirty(key, rec) {
+		rec.version += 1;
+		for (const fn of [...this.mutateListeners]) fn(key);
+		this.dirty.add(rec);
+		if (!this.flushScheduled) {
+			this.flushScheduled = true;
+			queueMicrotask(() => {
+				this.flush();
+			});
+		}
+	}
+	notifyDeclaration(rec) {
+		for (const fn of [...rec.declarationListeners]) fn();
+	}
+	flush() {
+		this.flushScheduled = false;
+		const dirty = [...this.dirty];
+		this.dirty.clear();
+		for (const rec of dirty) for (const fn of [...rec.listeners]) fn();
+	}
+};
+//#endregion
+export { SlotCore, SlotOwnershipError, StaleAuthorizationError, resolveSlotLabel };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-slots`.
+* @module @deepseek-ai/dsh-client-ui-slots/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-client-ui-slots";
+/** Cordis companion plugin name. */
+const name = "client-ui-slots-invariant";
+/** Service required before the companion can reserve package ownership. */
+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
+* bridge and its invariants); define/register/dispose sequencing is asserted
+* directly by this package's behavior specs.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };