dsh-brief-sidebar 0.3.0 → 0.4.0

package/src/client/use-projection.ts

@@ -1,117 +1,117 @@
-/**
- * Reading a live session projection from the client Session Controller.
- *
- * better-sidebar tab bodies are NOT rendered inside a DSH slot, so the
- * framework's `useProjection` standard prop is not available to them. The
- * equivalent face is reachable directly: the client Session Controller is a
- * cordis service on the root context, and each session binding exposes its
- * projections store (`SessionFace.projections.faceOf(key)`), which is the very
- * observable `useProjection` resolves. Since it is a bare
- * `{ getSnapshot, subscribe }` source, `useSyncExternalStore` binds it as-is —
- * no local mirror, no folding, and the value reference only changes when the
- * Host pushes a frame.
- *
- * Everything here is resolved defensively: a host without the Session
- * Controller, or a session that is not open any more, degrades to "capability
- * absent" (undefined) rather than throwing inside a render.
- *
- * This module is key-agnostic; the per-projection knowledge (which key, how to
- * narrow the raw value) lives with the feature modules that call it.
- */
-import { useCallback, useMemo, useSyncExternalStore } from 'react'
-import type { Context } from '@deepseek-ai/cordis'
-
-/** Structural view of a projection face (`ObservableSnapshot<unknown>`). */
-export interface ProjectionFace {
-  getSnapshot(): unknown
-  subscribe(listener: () => void): () => void
-}
-
-/** Structural view of one session binding's projection store. */
-export interface ProjectionsLike {
-  faceOf(key: string): ProjectionFace
-}
-
-/** Structural view of the client Session Controller face this plugin uses. */
-export interface SessionsLike {
-  binding(id: string): { readonly session: { readonly projections: ProjectionsLike } } | undefined
-}
-
-/** A no-op unsubscribe, kept as one identity so effects never thrash. */
-const NO_SUBSCRIBE = (): void => {}
-
-/** A source that never has a value — the absent-capability face. */
-const ABSENT: ProjectionFace = { getSnapshot: () => undefined, subscribe: () => NO_SUBSCRIBE }
-
-/**
- * Whether a value really is a projection face.
- *
- * The store contract promises an identity-stable face for every key, so this
- * never fires against a healthy host. It exists because the fallback is worse
- * than the check: `useSyncExternalStore` would throw on a face-less key, and a
- * thrown render is a blank sidebar rather than a diagnosable "unavailable".
- */
-function isFace(value: unknown): value is ProjectionFace {
-  if (value === null || typeof value !== 'object') return false
-  const face = value as Partial<ProjectionFace>
-  return typeof face.getSnapshot === 'function' && typeof face.subscribe === 'function'
-}
-
-/**
- * Resolve one projection face for one session.
- *
- * `ctx.get('sessions')` is the safe accessor (a direct `ctx.sessions` read can
- * throw on a context that does not carry the service yet).
- *
- * @param ctx - the client root context handed to the tab body.
- * @param sessionId - the tab's session scope; undefined means "no session".
- * @param key - the projection key to resolve.
- * @returns the projection face, or {@link ABSENT} when unreachable.
- */
-export function resolveFace(ctx: Context | undefined, sessionId: string | undefined, key: string): ProjectionFace {
-  if (ctx === undefined || sessionId === undefined) return ABSENT
-  const sessions = ctx.get('sessions') as SessionsLike | undefined
-  if (sessions === undefined || typeof sessions.binding !== 'function') return ABSENT
-
-  const binding = sessions.binding(sessionId)
-  const projections = binding?.session?.projections
-  if (projections === undefined || typeof projections.faceOf !== 'function') return ABSENT
-
-  const face: unknown = projections.faceOf(key)
-  return isFace(face) ? face : ABSENT
-}
-
-/**
- * Read one frame of a projection without subscribing.
- *
- * The one-shot sibling of {@link useProjectionValue}, for consumers that are
- * not React components — the tab badge is a plain function called on every
- * tab-bar render, so it must neither hold a subscription nor allocate one.
- *
- * @param ctx - the client root context.
- * @param sessionId - the session whose projection is read.
- * @param key - the projection key to read.
- * @returns the raw snapshot: `undefined` while the capability is absent; the
- *   semantics of any other value belong to the projection's own contract.
- */
-export function projectionSnapshot(ctx: Context | undefined, sessionId: string | undefined, key: string): unknown {
-  return resolveFace(ctx, sessionId, key).getSnapshot()
-}
-
-/**
- * Subscribe to one session projection by key.
- *
- * @param ctx - the client root context.
- * @param sessionId - the session whose projection is shown.
- * @param key - the projection key to subscribe to.
- * @returns the raw snapshot value, identity-stable across frames the host did
- *   not change. Narrowing is the caller's job.
- */
-export function useProjectionValue(ctx: Context | undefined, sessionId: string | undefined, key: string): unknown {
-  const face = useMemo(() => resolveFace(ctx, sessionId, key), [ctx, sessionId, key])
-
-  const subscribe = useCallback((listener: () => void) => face.subscribe(listener), [face])
-  const getSnapshot = useCallback(() => face.getSnapshot(), [face])
-
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
-}
+/**
+ * Reading a live session projection from the client Session Controller.
+ *
+ * better-sidebar tab bodies are NOT rendered inside a DSH slot, so the
+ * framework's `useProjection` standard prop is not available to them. The
+ * equivalent face is reachable directly: the client Session Controller is a
+ * cordis service on the root context, and each session binding exposes its
+ * projections store (`SessionFace.projections.faceOf(key)`), which is the very
+ * observable `useProjection` resolves. Since it is a bare
+ * `{ getSnapshot, subscribe }` source, `useSyncExternalStore` binds it as-is —
+ * no local mirror, no folding, and the value reference only changes when the
+ * Host pushes a frame.
+ *
+ * Everything here is resolved defensively: a host without the Session
+ * Controller, or a session that is not open any more, degrades to "capability
+ * absent" (undefined) rather than throwing inside a render.
+ *
+ * This module is key-agnostic; the per-projection knowledge (which key, how to
+ * narrow the raw value) lives with the feature modules that call it.
+ */
+import { useCallback, useMemo, useSyncExternalStore } from 'react'
+import type { Context } from '@deepseek-ai/cordis'
+
+/** Structural view of a projection face (`ObservableSnapshot<unknown>`). */
+export interface ProjectionFace {
+  getSnapshot(): unknown
+  subscribe(listener: () => void): () => void
+}
+
+/** Structural view of one session binding's projection store. */
+export interface ProjectionsLike {
+  faceOf(key: string): ProjectionFace
+}
+
+/** Structural view of the client Session Controller face this plugin uses. */
+export interface SessionsLike {
+  binding(id: string): { readonly session: { readonly projections: ProjectionsLike } } | undefined
+}
+
+/** A no-op unsubscribe, kept as one identity so effects never thrash. */
+const NO_SUBSCRIBE = (): void => {}
+
+/** A source that never has a value — the absent-capability face. */
+const ABSENT: ProjectionFace = { getSnapshot: () => undefined, subscribe: () => NO_SUBSCRIBE }
+
+/**
+ * Whether a value really is a projection face.
+ *
+ * The store contract promises an identity-stable face for every key, so this
+ * never fires against a healthy host. It exists because the fallback is worse
+ * than the check: `useSyncExternalStore` would throw on a face-less key, and a
+ * thrown render is a blank sidebar rather than a diagnosable "unavailable".
+ */
+function isFace(value: unknown): value is ProjectionFace {
+  if (value === null || typeof value !== 'object') return false
+  const face = value as Partial<ProjectionFace>
+  return typeof face.getSnapshot === 'function' && typeof face.subscribe === 'function'
+}
+
+/**
+ * Resolve one projection face for one session.
+ *
+ * `ctx.get('sessions')` is the safe accessor (a direct `ctx.sessions` read can
+ * throw on a context that does not carry the service yet).
+ *
+ * @param ctx - the client root context handed to the tab body.
+ * @param sessionId - the tab's session scope; undefined means "no session".
+ * @param key - the projection key to resolve.
+ * @returns the projection face, or {@link ABSENT} when unreachable.
+ */
+export function resolveFace(ctx: Context | undefined, sessionId: string | undefined, key: string): ProjectionFace {
+  if (ctx === undefined || sessionId === undefined) return ABSENT
+  const sessions = ctx.get('sessions') as SessionsLike | undefined
+  if (sessions === undefined || typeof sessions.binding !== 'function') return ABSENT
+
+  const binding = sessions.binding(sessionId)
+  const projections = binding?.session?.projections
+  if (projections === undefined || typeof projections.faceOf !== 'function') return ABSENT
+
+  const face: unknown = projections.faceOf(key)
+  return isFace(face) ? face : ABSENT
+}
+
+/**
+ * Read one frame of a projection without subscribing.
+ *
+ * The one-shot sibling of {@link useProjectionValue}, for consumers that are
+ * not React components — the tab badge is a plain function called on every
+ * tab-bar render, so it must neither hold a subscription nor allocate one.
+ *
+ * @param ctx - the client root context.
+ * @param sessionId - the session whose projection is read.
+ * @param key - the projection key to read.
+ * @returns the raw snapshot: `undefined` while the capability is absent; the
+ *   semantics of any other value belong to the projection's own contract.
+ */
+export function projectionSnapshot(ctx: Context | undefined, sessionId: string | undefined, key: string): unknown {
+  return resolveFace(ctx, sessionId, key).getSnapshot()
+}
+
+/**
+ * Subscribe to one session projection by key.
+ *
+ * @param ctx - the client root context.
+ * @param sessionId - the session whose projection is shown.
+ * @param key - the projection key to subscribe to.
+ * @returns the raw snapshot value, identity-stable across frames the host did
+ *   not change. Narrowing is the caller's job.
+ */
+export function useProjectionValue(ctx: Context | undefined, sessionId: string | undefined, key: string): unknown {
+  const face = useMemo(() => resolveFace(ctx, sessionId, key), [ctx, sessionId, key])
+
+  const subscribe = useCallback((listener: () => void) => face.subscribe(listener), [face])
+  const getSnapshot = useCallback(() => face.getSnapshot(), [face])
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
+}

package/src/index.ts

@@ -1,32 +1,32 @@
-/**
- * Node half of the brief sidebar plugin.
- *
- * The Cordis loader needs an entry point for the profile row; the browser half
- * (`./client`, served by `dsh-client-modules`) renders the summary tab.
- *
- * Since the summary upgrade, this half owns ONE behaviour: contributing the
- * `dshSummaryDeliverables` projection unit (see `./projection/register`), which
- * folds successful mutation calls into a live produced-file feed. The
- * contribution is optional — `registerDeliverablesProjection` waits for the
- * `sessionProjections` service via `ctx.inject`, so a composition without the
- * registry still loads this profile row and simply hides the deliverables
- * section client-side.
- *
- * In particular this half still never touches the filesystem at load time: a
- * profile row is instantiated on the boot path, and a synchronous read there
- * would delay the host's startup. The fold is event-driven and stores paths
- * only.
- */
-import type { Context } from '@deepseek-ai/cordis'
-import { registerDeliverablesProjection } from './projection/register'
-
-/** Profile row identity. */
-export const name = 'dsh-brief-sidebar'
-
-/**
- * Node-face apply.
- * @param ctx - the host context the loader hands this profile row.
- */
-export function apply(ctx: Context): void {
-  registerDeliverablesProjection(ctx)
-}
+/**
+ * Node half of the brief sidebar plugin.
+ *
+ * The Cordis loader needs an entry point for the profile row; the browser half
+ * (`./client`, served by `dsh-client-modules`) renders the summary tab.
+ *
+ * Since the summary upgrade, this half owns ONE behaviour: contributing the
+ * `dshSummaryDeliverables` projection unit (see `./projection/register`), which
+ * folds successful mutation calls into a live produced-file feed. The
+ * contribution is optional — `registerDeliverablesProjection` waits for the
+ * `sessionProjections` service via `ctx.inject`, so a composition without the
+ * registry still loads this profile row and simply hides the deliverables
+ * section client-side.
+ *
+ * In particular this half still never touches the filesystem at load time: a
+ * profile row is instantiated on the boot path, and a synchronous read there
+ * would delay the host's startup. The fold is event-driven and stores paths
+ * only.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import { registerDeliverablesProjection } from './projection/register'
+
+/** Profile row identity. */
+export const name = 'dsh-brief-sidebar'
+
+/**
+ * Node-face apply.
+ * @param ctx - the host context the loader hands this profile row.
+ */
+export function apply(ctx: Context): void {
+  registerDeliverablesProjection(ctx)
+}