DSH plugin client resources: dsh-resource:// and useResource

The DSH plugin client resource model turns one address into live data any Web component can read: the package owning the content registers a protocol provider, and components subscribe by address. Its key constraint is that holders control lifetime — a subscribed useResource or a single pin keeps a resource alive; the first holder opens the provider's stream, and the last one to leave aborts it, drops the value and returns the snapshot to loading or none. That is also why unloading a tab body does not close its stream: the right sidebar pins each open tab's address for the tab's lifetime.

DSH plugin resource model: addresses, providers and readers

Bottom line: protocols own value types and register a single provider; components only know addresses.

1. ctx.resources: the resource service and the useResource global hook.
2. Protocol declaration: owners declare value types on ResourceProtocolMap.
3. One provider per protocol: a second registration throws.
4. Readers: components read the current state by address without knowing the producer.
5. First consumer: right sidebar tabs.

DSH plugin dsh-resource:// syntax: protocol as host

Bottom line: dsh-resource://<type>/…, the host must be a protocol key, and only canonical lowercase spellings are accepted.

1. file protocol scoping: session/<id> followed by a relative path, or absolute followed by a path without its leading slash.
2. Construct and parse: use fileAddressFor(sessionId, cwd, path) and parseFileAddress(address).
3. Read only scheme and host: protocolOf(address) returns the lowercase host.
4. String comparison: case variants are different records, so never hand-assemble addresses.

DSH plugin provider registration: a frame stream that honors signals

Bottom line: open returns a frame stream, the first frame is current state, and abort must stop it.

ctx.effect(() => ctx.resources.register<'note'>({
  protocol: 'note',
  async *open(address, { signal }) {
    yield await ctx.remote.notes.read(id, signal)
    for await (const change of ctx.remote.notes.follow(id, signal)) yield change
  },
}))

1. First frame is state: do not wait for the first change.
2. Failure is a frame: ok: false with a RemoteFailure; throwing in the stream is a programming error.
3. Honor abort: a provider ignoring signal runs until its next frame.
4. Registration timing: keep it in an effect so the protocol lives with the plugin.
5. Already-held addresses: registering opens their streams immediately; after the provider disposes they read as none.

DSH plugin reads: the four useResource states

Bottom line: none, loading, live and failed; failed keeps the last successful value so stale content can stay visible.

1. Subscribing is holding: a mounted component reads the latest value immediately if another holder keeps the resource open.
2. Failure presentation is yours: the model produces no user-facing copy.
3. Type parameter names the protocol: useResource<'file'>(address) types the value.
4. Most streams carry metadata: the file protocol returns file stats while content comes from another read.

DSH plugin holding and release: subscriptions and pinning

Bottom line: a resource lives while held; the last holder leaving aborts the stream, drops the value and returns to loading or none.

1. Two ways to hold: a subscribed useResource, or ctx.resources.pin(address, signal).
2. Pin semantics: keeps it open without subscribing until the signal aborts; an already-aborted signal pins nothing.
3. Sidebar usage: each open tab pins its address for the tab's lifetime, so switching tabs does not close streams.
4. Release consequences: abort the stream, drop the value and return to loading (with a provider) or none; later frames are discarded.
5. Bare observable: ctx.resources.source(address) is reference-stable per address, and reading its snapshot alone is not holding.

DSH plugin client resource troubleshooting

Bottom line: separate wrong address, missing provider and no holders.

1. Always none — the protocol has no provider, or the address is not a resource address (typos read as none too).
2. Always loading — the provider emitted no first frame, or all holders left.
3. Blank after failure — the consumer ignored failed; keep showing the stale value with a notice.
4. Stream dies when switching tabs — the address was not pinned.
5. Growing memory — each address record persists for the page, so reading many distinct addresses costs memory.
6. Repair status, stated honestly: the address rules, frame contract, four states and holding semantics follow the official Client resources page; confirm file protocol and Remote namespace details against the package docs.

Sources: Client resources, dsh-client-resources README, Right sidebar.