@deepseek-ai/dsh-client-resources 0.1.5-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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/resources/README.md
+README.md: 7c32293c8d4250b11f8beaaf473a62145c915bce
+README.zh.md: b53089a2449f379f43156f610b587656a998ece3

package/README.md

@@ -0,0 +1,108 @@
+---
+description: "Client resource model: protocol-registered providers turn URL addresses into live values that any slot component reads through the useResource standard hook."
+kind: "package-reference"
+---
+# @deepseek-ai/dsh-client-resources
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use client resources when a component knows live data only by URL address, such as a tab record, link, or mention, while another client package owns the data. Resource addresses use `dsh-resource://<type>/…`; protocols that need a scope encode it in the path. Components receive the current value and later updates through the public `useResource` hook. Unsupported protocols and non-resource schemes, such as `sidebar://guide`, resolve to no resource.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+  - [Read a resource](#read-a-resource)
+  - [Provide a protocol](#provide-a-protocol)
+  - [Hold a resource open](#hold-a-resource-open)
+- [Understand the implementation](#understand-the-implementation)
+  - [Lifecycle](#lifecycle)
+  - [Failures](#failures)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Nothing needs configuration to mount: the plugin provides `ctx.resources` and contributes the `resource` root keyed hook through `ctx.slots.provideRoot`, so every slot component receives it whatever its scope.
+
+<a id="read-a-resource"></a>
+### Read a resource
+
+Every slot component receives `useResource` in its props. `useResource<P>(address)` names the protocol as the type argument and returns `{ status, value, failure, reload }`: `none` when no provider is registered for the address's protocol (or the address is not a `dsh-resource://` URL), `loading` while the provider has not yielded, `live` with the latest `ok` frame's value, and `failed` when the latest frame reported a failure, with that failure beside the last value. `reload()` asks the provider for a fresh value and is a no-op without one. Subscribing through the hook is what holds the resource open; a component that mounts while another holder keeps the resource alive reads the latest value at once.
+
+<a id="provide-a-protocol"></a>
+### Provide a protocol
+
+The protocol's owning client package declares its value type in `ResourceProtocolMap` and registers one provider as an owned effect. `open` yields `RemoteResult` frames: the current content first and one frame per later change, with a failure as an `ok: false` frame rather than a throw; it must stop when `signal` aborts. `reload` is optional:
+
+```ts ignore-check
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface ResourceProtocolMap { note: NoteView }
+}
+
+export const inject = ['resources']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.resources.register<'note'>({
+    protocol: 'note',
+    async *open(address, { signal }) {
+      yield await readNote(address, signal)
+      for await (const change of followNote(address, signal)) yield change
+    },
+    reload(address) { requestReread(address) },
+  }), 'my-notes: note resource provider')
+}
+```
+
+A protocol has exactly one provider; a second registration throws. Registering a provider while addresses of its protocol are already held opens them; disposing it ends their streams and returns them to `none`.
+
+<a id="hold-a-resource-open"></a>
+### Hold a resource open
+
+`ctx.resources.pin(address, signal)` keeps a resource open without subscribing, until `signal` aborts. The right Sidebar pins every open tab's address for the tab record's lifetime, so switching tabs unmounts the body without closing its stream and switching back reads the latest value. `ctx.resources.source(address)` is the bare observable behind the hook, for callers outside React.
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<a id="lifecycle"></a>
+### Lifecycle
+
+One record per address holds a snapshot store, a holder count (hook subscribers plus pins), and the running stream's `AbortController`. The first holder opens the provider's stream; every later holder shares it; the last holder's release aborts the stream and resets the snapshot to idle (`loading` with a provider, `none` without). Records are kept for the page lifetime so `source()` stays reference-stable across React's render-then-subscribe window and a StrictMode remount. `reload` is one function per record and never changes.
+
+<a id="failures"></a>
+### Failures
+
+A failure is a frame, not a throw: a provider yields `{ ok: false, error }` and the resource turns `failed` with that error beside the last value; the next `ok` frame clears it. A stream that ends on its own keeps its last state. Frames that arrive after the release that aborted the stream are dropped, and the iterator is returned. A throw inside a provider's stream is a programming error and is not caught.
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as this package moves values between browser plugins and registers nothing model-facing.
+
+#### KV Cache effect
+
+None; resource streams do not assemble model requests.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Records live for the page lifetime** — an address's record stays in the registry after its last holder leaves; only its state is discarded. Memory grows with the number of distinct addresses ever read, not with reads.
+- **Providers own abort compliance** — the registry drops what a released stream still yields, but a provider that ignores `signal` keeps working until its next frame.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>
+
+**Runtime invariant:** No companion is published. Provider ownership and holder counts have one owner, the registry, with no independent runtime source to compare against; registration disposal and the open/close lifecycle are asserted by behavior specs.

package/README.zh.md

@@ -0,0 +1,108 @@
+---
+description: "客户端资源模型：按协议注册的提供方把 URL 地址变成活数据，任何 slot 组件都通过 useResource 标准 hook 读取。"
+kind: "package-reference"
+---
+# @deepseek-ai/dsh-client-resources
+
+[English](README.md) | 中文
+
+## 概述
+
+当组件只知道活数据的 URL 地址，而数据由另一个客户端包拥有时，请使用客户端资源；例如 tab 记录、链接或提及。资源地址使用 `dsh-resource://<type>/…`；需要作用域的协议把作用域编进路径。组件通过公开的 `useResource` hook 接收当前值与后续更新。不支持的协议与非资源 scheme（例如 `sidebar://guide`）不指向任何资源。
+
+## 目录
+
+- [使用本包](#use-this-package)
+  - [读取资源](#read-a-resource)
+  - [提供协议](#provide-a-protocol)
+  - [钉住资源](#hold-a-resource-open)
+- [理解实现](#understand-the-implementation)
+  - [生命周期](#lifecycle)
+  - [失败](#failures)
+- [模型体验](#model-experience)
+- [已知限制与暂缓事项](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+挂载无需任何配置：插件提供 `ctx.resources`，并通过 `ctx.slots.provideRoot` 贡献 `resource` 根 keyed hook，因此每个 slot 组件不论作用域都能收到它。
+
+<a id="read-a-resource"></a>
+### 读取资源
+
+每个 slot 组件都在 props 上收到 `useResource`。`useResource<P>(address)` 以类型参数命名协议，返回 `{ status, value, failure, reload }`：地址协议没有提供方（或地址不是 `dsh-resource://` URL）时为 `none`，提供方尚未产出值时为 `loading`，`live` 携带最新一个 `ok` 帧的值，`failed` 表示最新一帧报告了失败，失败放在最后一个值旁。`reload()` 请提供方给一个新值，没有提供方时是空操作。通过 hook 订阅就是钉住资源的方式；另一个持有者让资源保持存活时，新挂载的组件立刻读到最新值。
+
+<a id="provide-a-protocol"></a>
+### 提供协议
+
+协议所属的客户端包在 `ResourceProtocolMap` 声明其值类型，并以自有 effect 注册一个提供方。`open` 产出 `RemoteResult` 帧：先是当前内容，之后每次变化一帧，失败以 `ok: false` 帧而非抛错表达；必须在 `signal` 中止时停止。`reload` 可选：
+
+```ts ignore-check
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface ResourceProtocolMap { note: NoteView }
+}
+
+export const inject = ['resources']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.resources.register<'note'>({
+    protocol: 'note',
+    async *open(address, { signal }) {
+      yield await readNote(address, signal)
+      for await (const change of followNote(address, signal)) yield change
+    },
+    reload(address) { requestReread(address) },
+  }), 'my-notes: note resource provider')
+}
+```
+
+一个协议恰有一个提供方；第二次注册会抛错。提供方注册时若其协议的地址已被持有，则立即开流；提供方 dispose 时结束这些流并让它们回到 `none`。
+
+<a id="hold-a-resource-open"></a>
+### 钉住资源
+
+`ctx.resources.pin(address, signal)` 在不订阅的情况下让资源保持打开，直到 `signal` 中止。右侧 Sidebar 在 tab 记录的存续期内钉住每个已打开 tab 的地址，因此切换 tab 卸载正文不会关闭其流，切回时读到最新值。`ctx.resources.source(address)` 是 hook 背后的裸 observable，供 React 之外的调用方使用。
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<a id="lifecycle"></a>
+### 生命周期
+
+每个地址一条记录，持有一个快照 store、一个持有者计数（hook 订阅者加 pin）与运行中流的 `AbortController`。第一个持有者打开提供方的流；之后的持有者共享它；最后一个持有者释放时中止流并把快照重置为空闲（有提供方为 `loading`，没有为 `none`）。记录在页面存续期内保留，使 `source()` 在 React 渲染到订阅的窗口与 StrictMode 重挂载之间保持引用稳定。`reload` 每条记录一个函数，永不变化。
+
+<a id="failures"></a>
+### 失败
+
+失败是帧而非抛错：提供方产出 `{ ok: false, error }`，资源变为 `failed` 并把该错误放在最后一个值旁；下一个 `ok` 帧将其清除。自行结束的流保持其最后状态。在中止流的那次释放之后到达的帧都被丢弃，并归还迭代器。提供方流内的抛错是编程错误，不会被捕获。
+
+<a id="model-experience"></a>
+## 模型体验
+
+无，因为本包在浏览器插件之间搬运值，不注册任何面向模型的内容。
+
+#### KV Cache 影响
+
+无；资源流不会组装模型请求。
+
+## 已知限制与暂缓事项
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **记录在页面存续期内保留**——地址的记录在最后一个持有者离开后仍留在注册表中，只丢弃其状态。内存随读取过的不同地址数增长，而非随读取次数增长。
+- **中止合规由提供方负责**——注册表会丢弃已释放的流仍产出的帧，但忽略 `signal` 的提供方会一直工作到它的下一帧。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>
+
+**运行时不变式：** 不发布伴生入口。提供方归属与持有者计数只有注册表这一个拥有者，没有可供比对的独立运行时来源；注册的 dispose 与打开/关闭生命周期由行为测试断言。

package/lib/client.js

@@ -0,0 +1,192 @@
+window.__ModuleLoader__.load({
+	id: "@deepseek-ai/dsh-client-resources",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		let _deepseek_ai_dsh_client_store = require("@deepseek-ai/dsh-client-store");
+		/**
+		* The protocol key of one address: the host of a `dsh-resource://` URL, as the
+		* URL parser reads it (lower-cased). Any other string — another scheme, or one
+		* the URL parser rejects — names no protocol and is treated like an address
+		* whose protocol has no provider.
+		* @param address - the full address.
+		* @returns the protocol key, or `undefined` when the address is not a resource address.
+		*/
+		function protocolOf(address) {
+			let parsed;
+			try {
+				parsed = new URL(address);
+			} catch {
+				return;
+			}
+			if (parsed.protocol !== `dsh-resource:`) return void 0;
+			return parsed.hostname === "" ? void 0 : parsed.hostname.toLowerCase();
+		}
+		function idle(status, reload) {
+			return {
+				status,
+				value: void 0,
+				failure: void 0,
+				reload
+			};
+		}
+		/** The `ctx.resources` implementation. */
+		var ResourceRegistry = class {
+			ctx;
+			providers = /* @__PURE__ */ new Map();
+			records = /* @__PURE__ */ new Map();
+			/** @param ctx - Context whose effects own the registered providers. */
+			constructor(ctx) {
+				this.ctx = ctx;
+			}
+			register(provider) {
+				const runtime = provider;
+				const { protocol } = runtime;
+				if (this.providers.has(protocol)) throw new Error(`resources: protocol "${protocol}" already has a provider`);
+				const dispose = this.ctx.effect(() => {
+					this.providers.set(protocol, runtime);
+					for (const record of this.recordsOf(protocol)) this.attach(record);
+					return () => {
+						this.providers.delete(protocol);
+						for (const record of this.recordsOf(protocol)) this.detach(record);
+					};
+				}, `resources.register(${JSON.stringify(protocol)})`);
+				return () => {
+					dispose();
+				};
+			}
+			pin(address, signal) {
+				if (signal.aborted) return;
+				const record = this.record(address);
+				this.hold(record);
+				signal.addEventListener("abort", () => {
+					this.release(record);
+				}, { once: true });
+			}
+			source(address) {
+				return this.record(address).source;
+			}
+			record(address) {
+				let record = this.records.get(address);
+				if (record === void 0) {
+					record = this.create(address);
+					this.records.set(address, record);
+				}
+				return record;
+			}
+			create(address) {
+				const protocol = protocolOf(address);
+				const reload = () => {
+					this.providerOf(protocol)?.reload?.(address);
+				};
+				const store = (0, _deepseek_ai_dsh_client_store.createSnapshotStore)(idle(this.providerOf(protocol) === void 0 ? "none" : "loading", reload));
+				const record = {
+					address,
+					protocol,
+					store,
+					reload,
+					holders: 0,
+					controller: void 0,
+					source: {
+						getSnapshot: () => store.getSnapshot(),
+						subscribe: (listener) => {
+							const unsubscribe = store.subscribe(listener);
+							this.hold(record);
+							let active = true;
+							return () => {
+								if (!active) return;
+								active = false;
+								unsubscribe();
+								this.release(record);
+							};
+						}
+					}
+				};
+				return record;
+			}
+			providerOf(protocol) {
+				return protocol === void 0 ? void 0 : this.providers.get(protocol);
+			}
+			*recordsOf(protocol) {
+				for (const record of this.records.values()) if (record.protocol === protocol) yield record;
+			}
+			hold(record) {
+				record.holders += 1;
+				if (record.holders === 1) this.start(record);
+			}
+			release(record) {
+				record.holders -= 1;
+				if (record.holders > 0) return;
+				this.stop(record);
+				record.store.set(idle(this.providerOf(record.protocol) === void 0 ? "none" : "loading", record.reload));
+			}
+			/** The provider arrived: a held record opens its stream, an idle one turns `loading`. */
+			attach(record) {
+				if (record.holders > 0) {
+					this.start(record);
+					return;
+				}
+				record.store.set(idle("loading", record.reload));
+			}
+			/** The provider left: the stream ends and the record reports `none`. */
+			detach(record) {
+				this.stop(record);
+				record.store.set(idle("none", record.reload));
+			}
+			start(record) {
+				const provider = this.providerOf(record.protocol);
+				if (provider === void 0) return;
+				const controller = new AbortController();
+				record.controller = controller;
+				if (record.store.getSnapshot().status !== "loading") record.store.set(idle("loading", record.reload));
+				this.consume(record, provider, controller.signal);
+			}
+			stop(record) {
+				record.controller?.abort();
+				record.controller = void 0;
+			}
+			/** Failures arrive as frames; a throw inside the stream is left to surface. */
+			async consume(record, provider, signal) {
+				const stream = provider.open(record.address, { signal });
+				for await (const frame of stream) {
+					if (signal.aborted) break;
+					record.store.set(frame.ok ? {
+						status: "live",
+						value: frame.value,
+						failure: void 0,
+						reload: record.reload
+					} : {
+						status: "failed",
+						value: record.store.getSnapshot().value,
+						failure: frame.error,
+						reload: record.reload
+					});
+				}
+			}
+		};
+		//#endregion
+		//#region lib/types/client/index.js
+		/** Required browser services. */
+		const inject = ["slots"];
+		/**
+		* Client plugin body: provide `ctx.resources` and contribute the `resource`
+		* root keyed hook that reaches every slot component as `useResource`.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			const resources = new ResourceRegistry(ctx);
+			const disposeService = ctx.reflect.provide("resources", resources);
+			ctx.effect(() => () => {
+				disposeService();
+			}, "client-resources: service face");
+			ctx.slots.provideRoot({ keyedHooks: { resource: (address) => resources.source(address) } });
+		}
+		//#endregion
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Pure host half; the resource model lives in the browser export. */
+/** Host plugin body: the resource model contributes nothing to the host tree. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/types/client/contract.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The resource model's published face.
+ *
+ * A resource is one address, and a resource address is a
+ * `dsh-resource://<type>/…` URL: the host names the protocol. The protocol's
+ * owning client package registers one {@link ResourceProvider} that turns an
+ * address into a frame stream, and any slot component reads that stream through
+ * {@link UseResource}. A protocol that needs a scope (a session, a workspace)
+ * encodes it in the path, as `dsh-resource://file/session/<sessionId>/<absolute
+ * path>` does; the model itself knows only addresses. Addresses under any other
+ * scheme (`sidebar://guide`) are navigation addresses and name no resource.
+ * `ResourceProtocolMap` (declared
+ * in ui-slots) is the declaration-merged roster of protocol to value type, so a
+ * consumer names the protocol as a type argument and receives the owner's value
+ * type without importing the owner's runtime.
+ */
+import type { RemoteFailure, RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { ResourceProtocolMap } from '@deepseek-ai/dsh-client-ui-slots';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface GlobalStandardProps {
+        /** Live value of one address, resolved through the provider registered for its protocol. */
+        useResource: UseResource;
+    }
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Resource model: protocol providers, pins, and per-address live sources. */
+        resources: Resources;
+    }
+}
+/** Every protocol some client package has declared. */
+export type ResourceProtocol = Extract<keyof ResourceProtocolMap, string>;
+/**
+ * Where one resource stands. `none`: no provider is registered for the
+ * address's protocol, or the address is not a resource address. `loading`: a provider is open and has not yielded yet.
+ * `live`: `value` is the latest `ok` frame's value. `failed`: the latest frame
+ * reported a failure.
+ */
+export type ResourceStatus = 'none' | 'loading' | 'live' | 'failed';
+/** One address's current state, as `useResource` returns it. */
+export interface ResourceSnapshot<Value> {
+    readonly status: ResourceStatus;
+    /** The latest `ok` frame's value; kept through a later failure frame, absent before the first. */
+    readonly value: Value | undefined;
+    /** The latest frame's failure; present only while `status` is `failed`. */
+    readonly failure: RemoteFailure | undefined;
+    /** Ask the provider for a fresh frame; a no-op when its protocol has no provider or no `reload`. */
+    readonly reload: () => void;
+}
+/**
+ * Global standard hook: the current state of one address, typed by the
+ * protocol named as the type argument. Present on every slot component's
+ * props, whatever its scope.
+ */
+export type UseResource = <P extends ResourceProtocol>(address: string) => ResourceSnapshot<ResourceProtocolMap[P]>;
+/** What a provider's `open` receives beside the address. */
+export interface ResourceOpenContext {
+    /** Aborted when the last subscriber or pin releases the resource; the stream must end. */
+    readonly signal: AbortSignal;
+}
+/** One protocol's provider, registered through `ctx.resources.register`. */
+export interface ResourceProvider<P extends ResourceProtocol> {
+    /** The URL scheme this provider serves. */
+    readonly protocol: P;
+    /**
+     * Open one frame stream for an address. The first frame is the current
+     * content and every later frame one change. An `ok` frame replaces the value;
+     * a failure frame marks the resource `failed` with its error and keeps the
+     * last value. Ending the stream keeps the last state. A failure is always a
+     * frame: a throw inside the stream is a programming error and is not caught.
+     * @param address - the full address, a `dsh-resource://<type>/…` URL.
+     * @param ctx - the stream's abort signal.
+     * @returns the frame stream; it must stop once `ctx.signal` aborts.
+     */
+    open(address: string, ctx: ResourceOpenContext): AsyncIterable<RemoteResult<ResourceProtocolMap[P]>>;
+    /**
+     * Produce a fresh frame on the open stream. Absent when the protocol has no refresh.
+     * @param address - the full address, a `dsh-resource://<type>/…` URL.
+     */
+    reload?(address: string): void;
+}
+/**
+ * The `ctx.resources` service. One resource is one address; it stays open
+ * while at least one `source` subscriber or one pin holds it, and the
+ * provider's stream is aborted and the state discarded when the last holder
+ * releases.
+ */
+export interface Resources {
+    /**
+     * Register the provider for one protocol for the caller's lifetime.
+     * @param provider - the protocol's provider.
+     * @returns idempotent disposer, held inside the caller's own `ctx.effect`.
+     * @throws when the protocol already has a provider.
+     */
+    register<P extends ResourceProtocol>(provider: ResourceProvider<P>): () => void;
+    /**
+     * Hold one resource open without subscribing to it.
+     * @param address - the full address, a `dsh-resource://<type>/…` URL.
+     * @param signal - aborting it releases the pin; an already-aborted signal pins nothing.
+     */
+    pin(address: string, signal: AbortSignal): void;
+    /**
+     * The live source of one resource. Reference-stable for one address while
+     * the resource is held; the first subscriber or pin opens the provider's
+     * stream, and a subscriber arriving later reads the latest value at once.
+     * @param address - the full address, a `dsh-resource://<type>/…` URL.
+     * @returns the observable state; `getSnapshot` reads without holding the resource.
+     */
+    source(address: string): ObservableSnapshot<ResourceSnapshot<unknown>>;
+}
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Browser half: `ctx.resources` (protocol-registered providers, pinning, live
+ * sources) and the `useResource` global standard hook.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+export type { ResourceOpenContext, ResourceProtocol, ResourceProvider, Resources, ResourceSnapshot, ResourceStatus, UseResource, } from './contract.ts';
+export type { ResourceProtocolMap } from '@deepseek-ai/dsh-client-ui-slots';
+/** Required browser services. */
+export declare const inject: string[];
+/**
+ * Client plugin body: provide `ctx.resources` and contribute the `resource`
+ * root keyed hook that reaches every slot component as `useResource`.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/resources.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `ctx.resources`: the provider registry and the per-address states behind
+ * `useResource`.
+ *
+ * A record is kept for every address ever sourced and is never dropped; what
+ * the last release discards is its state (the stream is aborted and the
+ * snapshot returns to idle). Keeping the record keeps `source()` reference-stable
+ * across React's render-then-subscribe window and a StrictMode remount, where a
+ * recreated record would make every render resubscribe and restart the stream.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { ResourceProtocol, ResourceProvider, Resources, ResourceSnapshot } from './contract.ts';
+/**
+ * The one URL scheme resource addresses use: `dsh-resource://<type>/…`, where
+ * the host names the protocol. Other schemes (`sidebar://…`) are navigation
+ * addresses and name no resource.
+ */
+export declare const RESOURCE_SCHEME = "dsh-resource";
+/**
+ * The protocol key of one address: the host of a `dsh-resource://` URL, as the
+ * URL parser reads it (lower-cased). Any other string — another scheme, or one
+ * the URL parser rejects — names no protocol and is treated like an address
+ * whose protocol has no provider.
+ * @param address - the full address.
+ * @returns the protocol key, or `undefined` when the address is not a resource address.
+ */
+export declare function protocolOf(address: string): string | undefined;
+/** The `ctx.resources` implementation. */
+export declare class ResourceRegistry implements Resources {
+    private readonly ctx;
+    private readonly providers;
+    private readonly records;
+    /** @param ctx - Context whose effects own the registered providers. */
+    constructor(ctx: Context);
+    register<P extends ResourceProtocol>(provider: ResourceProvider<P>): () => void;
+    pin(address: string, signal: AbortSignal): void;
+    source(address: string): ObservableSnapshot<ResourceSnapshot<unknown>>;
+    private record;
+    private create;
+    private providerOf;
+    private recordsOf;
+    private hold;
+    private release;
+    /** The provider arrived: a held record opens its stream, an idle one turns `loading`. */
+    private attach;
+    /** The provider left: the stream ends and the record reports `none`. */
+    private detach;
+    private start;
+    private stop;
+    /** Failures arrive as frames; a throw inside the stream is left to surface. */
+    private consume;
+}
+//# sourceMappingURL=resources.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Pure host half; the resource model lives in the browser export. */
+/** Host plugin body: the resource model contributes nothing to the host tree. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@deepseek-ai/dsh-client-resources",
+  "description": "Unified client resource model: protocol-registered providers turn URL addresses into live values, consumed through the useResource global standard hook",
+  "version": "0.1.5-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/resources"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-client-store": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-client-test-runtime": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-alpha.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-alpha.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}