description	kind
Client resource model: protocol-registered providers turn URL addresses into live values that any slot component reads through the useResource standard hook.	package-reference

@deepseek-ai/dsh-client-resources

English | 中文

Summary

The resource model of the web client. A resource is one address, and a resource address is a dsh-resource://<type>/… URL whose host is the protocol key; the protocol's owning client package registers a provider that turns an address into a value stream, and any slot component reads that stream through the useResource global standard hook. A protocol that needs a scope encodes it in the path (dsh-resource://file/session/<sessionId>/<absolute path>); the model knows only addresses, and an address under any other scheme (sidebar://guide) names no resource. Use it when a component needs live data it only knows by address (a tab record, a link, a mention) and the data's owner is another client plugin.

Use this package
Understand the implementation
- Lifecycle
- Failures
Model Experience
Known Limitations and Deferred Work
Dev Note

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.

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.

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:

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.

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.

Understand the implementation

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.

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.

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

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.

Dev Note

Working context for maintainers — click to expand

None.

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.

README.md