docs(dx): JSDoc sweep — undocumented dev-facing helpers (audit PR 1)

Re-baselined the TS DX audit against post-#685 main (#685 already documented
tools/action/view/ask + made view/ask generic). Close the remaining
missing-summary holes on the dev-facing surface:

- chat: isUserMessage/isAssistantMessage/isToolMessage/isSystemMessage,
  getInterrupt, isTyping, mockAgent — summaries + @PARAM + @example
- render: provideViews, signalStateStore — summaries + @PARAM + @example

Regenerated chat/render api-docs.json; updated the findings doc with a
post-#685 re-baseline note. Comment-only; chat + render build green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: blove

apps/website/content/docs/chat/api/api-docs.json

@@ -7793,21 +7793,23 @@
   {
     "name": "getInterrupt",
     "kind": "function",
-    "description": "",
+    "description": "Read the agent's current human-in-the-loop interrupt, if any.",
     "signature": "getInterrupt(agent: Agent<>): AgentInterrupt | undefined",
     "params": [
       {
         "name": "agent",
         "type": "Agent<>",
-        "description": "",
+        "description": "The agent to inspect.",
         "optional": false
       }
     ],
     "returns": {
       "type": "AgentInterrupt | undefined",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nconst interrupt = getInterrupt(agent);\nif (interrupt) agent.resume('approved');\n```"
+    ]
   },
   {
     "name": "getMessageType",
@@ -7871,97 +7873,107 @@
   {
     "name": "isAssistantMessage",
     "kind": "function",
-    "description": "",
+    "description": "Type guard narrowing a Message to `role: 'assistant'`.",
     "signature": "isAssistantMessage(m: Message): m is Message & { role: \"assistant\" }",
     "params": [
       {
         "name": "m",
         "type": "Message",
-        "description": "",
+        "description": "The message to test.",
         "optional": false
       }
     ],
     "returns": {
       "type": "m is Message & { role: \"assistant\" }",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nconst reply = agent.messages().findLast(isAssistantMessage);\n```"
+    ]
   },
   {
     "name": "isSystemMessage",
     "kind": "function",
-    "description": "",
+    "description": "Type guard narrowing a Message to `role: 'system'`.",
     "signature": "isSystemMessage(m: Message): m is Message & { role: \"system\" }",
     "params": [
       {
         "name": "m",
         "type": "Message",
-        "description": "",
+        "description": "The message to test.",
         "optional": false
       }
     ],
     "returns": {
       "type": "m is Message & { role: \"system\" }",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nconst visible = agent.messages().filter((m) => !isSystemMessage(m));\n```"
+    ]
   },
   {
     "name": "isToolMessage",
     "kind": "function",
-    "description": "",
+    "description": "Type guard narrowing a Message to `role: 'tool'` (a tool result turn).",
     "signature": "isToolMessage(m: Message): m is Message & { role: \"tool\" }",
     "params": [
       {
         "name": "m",
         "type": "Message",
-        "description": "",
+        "description": "The message to test.",
         "optional": false
       }
     ],
     "returns": {
       "type": "m is Message & { role: \"tool\" }",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nif (isToolMessage(m)) console.log(m.toolCallId);\n```"
+    ]
   },
   {
     "name": "isTyping",
     "kind": "function",
-    "description": "",
+    "description": "Whether the agent should show a \"typing\" indicator — it is loading and has\nnot yet started streaming the assistant's reply.",
     "signature": "isTyping(agent: Agent<>): boolean",
     "params": [
       {
         "name": "agent",
         "type": "Agent<>",
-        "description": "",
+        "description": "The agent to inspect.",
         "optional": false
       }
     ],
     "returns": {
       "type": "boolean",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\n\\@if (isTyping(agent)) { <chat-typing-indicator [agent]=\"agent\" /> }\n```"
+    ]
   },
   {
     "name": "isUserMessage",
     "kind": "function",
-    "description": "",
+    "description": "Type guard narrowing a Message to `role: 'user'`.",
     "signature": "isUserMessage(m: Message): m is Message & { role: \"user\" }",
     "params": [
       {
         "name": "m",
         "type": "Message",
-        "description": "",
+        "description": "The message to test.",
         "optional": false
       }
     ],
     "returns": {
       "type": "m is Message & { role: \"user\" }",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nconst userTurns = agent.messages().filter(isUserMessage);\n```"
+    ]
   },
   {
     "name": "messageContent",
@@ -7985,21 +7997,23 @@
   {
     "name": "mockAgent",
     "kind": "function",
-    "description": "",
+    "description": "Build an in-memory Agent for tests and stories — no transport, no\nnetwork. Every field is a writable signal so a test can drive UI states\n(loading, error, interrupts, tool calls, subagents) deterministically.",
     "signature": "mockAgent(opts: MockAgentOptions): MockAgent<>",
     "params": [
       {
         "name": "opts",
         "type": "MockAgentOptions",
-        "description": "",
+        "description": "Initial values for the mock's signals; all optional.",
         "optional": true
       }
     ],
     "returns": {
       "type": "MockAgent<>",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nconst agent = mockAgent({\n  messages: [{ id: '1', role: 'assistant', content: 'Hi' }],\n  isLoading: true,\n});\n```"
+    ]
   },
   {
     "name": "normalizeEnvelopeArgs",

apps/website/content/docs/render/api/api-docs.json

@@ -781,40 +781,44 @@
   {
     "name": "provideViews",
     "kind": "function",
-    "description": "",
+    "description": "Register a ViewRegistry for the render engine so generative-UI specs\ncan resolve element `type`s to Angular components. Provide at the application\n(or a feature route's) environment injector.",
     "signature": "provideViews(registry: ViewRegistry): EnvironmentProviders",
     "params": [
       {
         "name": "registry",
         "type": "ViewRegistry",
-        "description": "",
+        "description": "Map of spec element types to the components that render them,\n  typically built with `views()` / `withViews()`.",
         "optional": false
       }
     ],
     "returns": {
       "type": "EnvironmentProviders",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nbootstrapApplication(App, {\n  providers: [provideViews(views({ metric: MetricCardComponent }))],\n});\n```"
+    ]
   },
   {
     "name": "signalStateStore",
     "kind": "function",
-    "description": "",
+    "description": "Create a signal-backed StateStore for a generative-UI surface —\nholds the bound state that spec `$bindState` paths read and interactive\nelements write, with path-addressable get/set and change subscriptions.",
     "signature": "signalStateStore(initialState: StateModel): StateStore",
     "params": [
       {
         "name": "initialState",
         "type": "StateModel",
-        "description": "",
+        "description": "Optional starting state object.",
         "optional": true
       }
     ],
     "returns": {
       "type": "StateStore",
       "description": ""
     },
-    "examples": []
+    "examples": [
+      "```ts\nconst store = signalStateStore({ count: 0 });\nstore.set('count', 1);\n```"
+    ]
   },
   {
     "name": "toRenderRegistry",

docs/superpowers/specs/2026-06-19-ts-dx-audit-findings.md

@@ -3,6 +3,8 @@
 **Date:** 2026-06-19 · **Scope:** `@threadplane/chat`, `ag-ui`, `langgraph`, `render` (302 public exports)
 **Method:** TypeDoc extraction (`api-docs.json`) for JSDoc/signature grading across all exports + real `tsserver` quick-info probing for hover/inference on the authoring surface + source confirmation. See `2026-06-19-ts-dx-audit-design.md`.
 
+> **Re-baselined 2026-06-19 (post #685).** The original grades were extracted from `api-docs.json` generated *before* PR #685 ("TypeScript DX pass") merged. #685 already implemented the headline items: `view`/`ask` are now generic with `AcceptComponent<S,C>` so component inputs are checked against the schema (**F4 done**), and `tools`/`action`/`view`/`ask` carry full `@param`/`@example`/`@returns` JSDoc (**F1/F2 done for client-tools**); `provideChat` and `AgentError`/`toAgentError` were documented too. The remaining gap is narrower — undocumented secondary functions (message type-guards, `getInterrupt`, `mockAgent`, `provideViews`, `signalStateStore`, `bridgeCitationsState`, `extractCitations`) and `@example`-less wiring APIs (`provideAgent`/`injectAgent` on both adapters, `injectRenderHost`). PR 1 on this branch (`docs/ts-dx-audit`) closes the missing-summary holes first.
+
 ## Executive summary
 
 The public **type shapes and hovers are in good condition** — the IDE quick-info for the headline authoring APIs is clean and readable, and generic inference works where it's been wired (`action<S>`). The gap is almost entirely **inline guidance (JSDoc)** and a few **surface-hygiene + inference** items.

libs/chat/src/lib/agent/message.ts

@@ -44,18 +44,58 @@ export interface Message {
   toolCallIds?: string[];
 }
 
+/**
+ * Type guard narrowing a {@link Message} to `role: 'user'`.
+ *
+ * @param m The message to test.
+ * @returns `true` (and narrows `m`) when the message was sent by the user.
+ * @example
+ * ```ts
+ * const userTurns = agent.messages().filter(isUserMessage);
+ * ```
+ */
 export function isUserMessage(m: Message): m is Message & { role: 'user' } {
   return m.role === 'user';
 }
 
+/**
+ * Type guard narrowing a {@link Message} to `role: 'assistant'`.
+ *
+ * @param m The message to test.
+ * @returns `true` (and narrows `m`) when the message came from the assistant.
+ * @example
+ * ```ts
+ * const reply = agent.messages().findLast(isAssistantMessage);
+ * ```
+ */
 export function isAssistantMessage(m: Message): m is Message & { role: 'assistant' } {
   return m.role === 'assistant';
 }
 
+/**
+ * Type guard narrowing a {@link Message} to `role: 'tool'` (a tool result turn).
+ *
+ * @param m The message to test.
+ * @returns `true` (and narrows `m`) when the message is a tool result.
+ * @example
+ * ```ts
+ * if (isToolMessage(m)) console.log(m.toolCallId);
+ * ```
+ */
 export function isToolMessage(m: Message): m is Message & { role: 'tool' } {
   return m.role === 'tool';
 }
 
+/**
+ * Type guard narrowing a {@link Message} to `role: 'system'`.
+ *
+ * @param m The message to test.
+ * @returns `true` (and narrows `m`) when the message is a system message.
+ * @example
+ * ```ts
+ * const visible = agent.messages().filter((m) => !isSystemMessage(m));
+ * ```
+ */
 export function isSystemMessage(m: Message): m is Message & { role: 'system' } {
   return m.role === 'system';
 }

libs/chat/src/lib/primitives/chat-interrupt/chat-interrupt.component.ts

@@ -14,6 +14,18 @@ import type { AgentInterrupt } from '../../agent/agent-interrupt';
 import { CHAT_HOST_TOKENS } from '../../styles/chat-tokens';
 import { CHAT_INTERRUPT_STYLES } from '../../styles/chat-interrupt.styles';
 
+/**
+ * Read the agent's current human-in-the-loop interrupt, if any.
+ *
+ * @param agent The agent to inspect.
+ * @returns The pending {@link AgentInterrupt}, or `undefined` when the agent is
+ *   not currently waiting on an interrupt.
+ * @example
+ * ```ts
+ * const interrupt = getInterrupt(agent);
+ * if (interrupt) agent.resume('approved');
+ * ```
+ */
 export function getInterrupt(agent: Agent): AgentInterrupt | undefined {
   return agent.interrupt?.();
 }

libs/chat/src/lib/primitives/chat-typing-indicator/chat-typing-indicator.component.ts

@@ -5,6 +5,18 @@ import type { Agent } from '../../agent';
 import { CHAT_HOST_TOKENS } from '../../styles/chat-tokens';
 import { CHAT_TYPING_INDICATOR_STYLES } from '../../styles/chat-typing-indicator.styles';
 
+/**
+ * Whether the agent should show a "typing" indicator — it is loading and has
+ * not yet started streaming the assistant's reply.
+ *
+ * @param agent The agent to inspect.
+ * @returns `true` while the agent is awaiting a response but no assistant text
+ *   has streamed yet; `false` once tokens arrive or the agent is idle.
+ * @example
+ * ```ts
+ * \@if (isTyping(agent)) { <chat-typing-indicator [agent]="agent" /> }
+ * ```
+ */
 export function isTyping(agent: Agent): boolean {
   if (!agent.isLoading()) return false;
   const msgs = agent.messages();

libs/chat/src/lib/testing/mock-agent.ts

@@ -63,6 +63,21 @@ export interface MockAgentOptions {
   events$?: Observable<AgentEvent>;
 }
 
+/**
+ * Build an in-memory {@link Agent} for tests and stories — no transport, no
+ * network. Every field is a writable signal so a test can drive UI states
+ * (loading, error, interrupts, tool calls, subagents) deterministically.
+ *
+ * @param opts Initial values for the mock's signals; all optional.
+ * @returns A {@link MockAgent} satisfying the full `Agent` contract.
+ * @example
+ * ```ts
+ * const agent = mockAgent({
+ *   messages: [{ id: '1', role: 'assistant', content: 'Hi' }],
+ *   isLoading: true,
+ * });
+ * ```
+ */
 export function mockAgent(opts: MockAgentOptions = {}): MockAgent {
   const messages  = signal<Message[]>(opts.messages ?? []);
   const status    = signal<AgentStatus>(opts.status ?? 'idle');

libs/render/src/lib/provide-views.ts

@@ -4,6 +4,21 @@ import type { ViewRegistry } from './views';
 
 export const VIEW_REGISTRY = new InjectionToken<ViewRegistry>('VIEW_REGISTRY');
 
+/**
+ * Register a {@link ViewRegistry} for the render engine so generative-UI specs
+ * can resolve element `type`s to Angular components. Provide at the application
+ * (or a feature route's) environment injector.
+ *
+ * @param registry Map of spec element types to the components that render them,
+ *   typically built with `views()` / `withViews()`.
+ * @returns Environment providers to spread into `providers` / `provideChat`.
+ * @example
+ * ```ts
+ * bootstrapApplication(App, {
+ *   providers: [provideViews(views({ metric: MetricCardComponent }))],
+ * });
+ * ```
+ */
 export function provideViews(registry: ViewRegistry) {
   return makeEnvironmentProviders([
     { provide: VIEW_REGISTRY, useValue: registry },

libs/render/src/lib/signal-state-store.ts

@@ -34,6 +34,19 @@ function setByPath(obj: unknown, segments: string[], value: unknown): unknown {
   return record;
 }
 
+/**
+ * Create a signal-backed {@link StateStore} for a generative-UI surface —
+ * holds the bound state that spec `$bindState` paths read and interactive
+ * elements write, with path-addressable get/set and change subscriptions.
+ *
+ * @param initialState Optional starting state object.
+ * @returns A {@link StateStore} bridging Angular signals to the render engine.
+ * @example
+ * ```ts
+ * const store = signalStateStore({ count: 0 });
+ * store.set('count', 1);
+ * ```
+ */
 export function signalStateStore(initialState: StateModel = {}): StateStore {
   const state = signal<StateModel>(initialState);
   const listeners = new Set<() => void>();