fix: test/docs

packages/extensions/ui-cordis/src/client/CordisRunRow.tsx

@@ -41,17 +41,17 @@ export function CordisRunRow({
   const loaded = useLoaded(snapshot => snapshot)
   const latest = useRunCards(snapshot => snapshot)
   const activeRuns = useActiveRuns(snapshot => snapshot)
-  const successful = card.state === 'ok'
+  const key = card.state === 'ok'
     && card.pluginId !== null
     && card.packageId !== null
     && card.pluginRunId !== null
     && card.seq !== null
-  const key = successful ? cordisToolViewKey(card.pluginId!, card.packageId!) : null
-
+    ? cordisToolViewKey(card.pluginId, card.packageId)
+    : null
   useEffect(() => {
-    if (!successful || key === null) return
-    onObserveRunCard({ key, callId, seq: card.seq!, pluginRunId: card.pluginRunId! })
-  }, [callId, card.pluginRunId, card.seq, key, onObserveRunCard, successful])
+    if (key === null || card.seq === null || card.pluginRunId === null) return
+    onObserveRunCard({ key, callId, seq: card.seq, pluginRunId: card.pluginRunId })
+  }, [callId, card.pluginRunId, card.seq, key, onObserveRunCard])
 
   const row = card.pluginId === null
     ? undefined
@@ -72,15 +72,15 @@ export function CordisRunRow({
       ? 'superseded'
       : awaitingApproval
         ? 'awaiting-approval'
-      : attempt?.status === 'failed'
-        ? 'failed'
-      : row !== undefined && card.packageId !== null
-        ? cordisVisibleStatus(row, card.packageId, loaded)
-        : 'idle'
+        : attempt?.status === 'failed'
+          ? 'failed'
+          : row !== undefined && card.packageId !== null
+            ? cordisVisibleStatus(row, card.packageId, loaded)
+            : 'idle'
   const status = t(READING_LABELS[reading])
   const summary = card.errorSummary
     ?? (card.pluginId === null ? callId : `${card.pluginId}${card.packageId === null ? '' : ` · ${card.packageId}`}`)
-  const showBusiness = successful && reading === 'running' && key !== null
+  const showBusiness = reading === 'running' && key !== null
 
   return (
     <div
@@ -116,13 +116,13 @@ export function CordisRunRow({
         <div className={css.message}>{attempt.error.message}</div>
       )}
       {showBusiness && card.pluginId !== null && card.packageId !== null && card.pluginRunId !== null && (
-        <div className={css.business} data-cordis-business-view={key ?? undefined}>
+        <div className={css.business} data-cordis-business-view={key}>
           {renderSlot('tool.view.cordis', {
             pluginId: card.pluginId,
             packageId: card.packageId,
             pluginRunId: card.pluginRunId,
           }, {
-            entryKey: key ?? undefined,
+            entryKey: key,
             fallback: card.output === null ? null : <pre className={css.output}>{card.output}</pre>,
           })}
         </div>

packages/extensions/ui-cordis/src/client/card-model.ts

@@ -79,7 +79,11 @@ function metaObject(block: Block): Record<string, unknown> | null {
   return block.meta as Record<string, unknown>
 }
 
-/** Derive one Define card from its frozen call/result slice. */
+/**
+ * Derive one Define card from its frozen call/result slice.
+ * @param block - active or settled tool-call block.
+ * @returns normalized Define card fields.
+ */
 export function cordisDefineCard(block: Block): CordisDefineCard {
   const settled = 'kind' in block
   const argsRaw = (settled ? block.call?.argsRaw : block.argsRaw) ?? ''
@@ -102,7 +106,11 @@ export function cordisDefineCard(block: Block): CordisDefineCard {
   }
 }
 
-/** Derive one Run card and its successful activation metadata. */
+/**
+ * Derive one Run card and its successful activation metadata.
+ * @param block - active or settled tool-call block.
+ * @returns normalized Run card fields.
+ */
 export function cordisRunCard(block: Block): CordisRunCard {
   const settled = 'kind' in block
   const argsRaw = (settled ? block.call?.argsRaw : block.argsRaw) ?? ''

packages/extensions/ui-cordis/src/client/index.ts

@@ -126,7 +126,7 @@ export function apply(ctx: ClientContext): void {
       const store = runCards.forSession(sessionId)
       return {
         hooks: { inventory, loaded, runCards: store, activeRuns: runner.activeRuns },
-        onObserveRunCard: pointer => { store.observe(pointer) },
+        onObserveRunCard: (pointer) => { store.observe(pointer) },
       }
     },
   }, CordisRunRow))
@@ -139,7 +139,7 @@ export function apply(ctx: ClientContext): void {
     order: 1,
     candidates(session, { query }) {
       const rows = rowsOf(session.sessionId, query)
-      return Promise.resolve(rows.map(row => {
+      return Promise.resolve(rows.map((row) => {
         const packageId = row.nextPackageId ?? row.currentPackageId ?? row.packages.at(-1)?.packageId
         const pkg = packageId === undefined ? undefined : row.packages.find(candidate => candidate.packageId === packageId)
         return {

packages/extensions/ui-cordis/src/client/locales.ts

@@ -2,6 +2,7 @@
 
 export const NS = 'cordis'
 
+/** Simplified Chinese Cordis UI messages. */
 export const zh = {
   'row.defineTitle': '注册 Cordis 插件',
   'row.runTitle': '运行 Cordis 插件',
@@ -52,6 +53,7 @@ export const zh = {
   'body.copied': '已复制',
 } satisfies Record<string, string>
 
+/** Translation keys owned by the Cordis UI namespace. */
 export type CordisKey = keyof typeof zh
 
 declare module '@deepseek-ai/dsh-client-ui-slots' {
@@ -61,6 +63,7 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
   }
 }
 
+/** English Cordis UI messages. */
 export const en = {
   'row.defineTitle': 'Define Cordis Plugin',
   'row.runTitle': 'Run Cordis Plugin',

packages/extensions/ui-cordis/src/client/run-card-index.ts

@@ -47,7 +47,11 @@ function createStore(): CordisRunCardStore {
 export class CordisRunCardRegistry {
   private readonly sessions = new Map<SessionId, CordisRunCardStore>()
 
-  /** Return the persistent page-local Store for a session. */
+  /**
+   * Return the persistent page-local Store for a session.
+   * @param sessionId - session whose cards share supersession state.
+   * @returns the page-local Store retained for that session.
+   */
   forSession(sessionId: SessionId): CordisRunCardStore {
     let store = this.sessions.get(sessionId)
     if (store === undefined) {
@@ -58,7 +62,12 @@ export class CordisRunCardRegistry {
   }
 }
 
-/** Build the Package business-view key shared by registrations and Run cards. */
+/**
+ * Build the Package business-view key shared by registrations and Run cards.
+ * @param pluginId - stable Plugin identity.
+ * @param packageId - immutable Package identity.
+ * @returns the shared business-view key.
+ */
 export function cordisToolViewKey(
   pluginId: CordisDynamicPluginId,
   packageId: CordisDynamicPackageId,

packages/extensions/ui-cordis/src/client/status.ts

@@ -8,8 +8,16 @@ import type {
 /** The three product-visible lifecycle readings. */
 export type CordisVisibleStatus = 'idle' | 'client-pending' | 'running'
 
-/** Locate one immutable Package inside a Plugin row. */
-export function packageOf(row: DynamicCordisInventoryRow, packageId: CordisDynamicPackageId) {
+/**
+ * Locate one immutable Package inside a Plugin row.
+ * @param row - owning Plugin inventory row.
+ * @param packageId - immutable Package identity to locate.
+ * @returns the matching Package metadata, or `undefined` when absent.
+ */
+export function packageOf(
+  row: DynamicCordisInventoryRow,
+  packageId: CordisDynamicPackageId,
+): DynamicCordisInventoryRow['packages'][number] | undefined {
   return row.packages.find(pkg => pkg.packageId === packageId)
 }