dsh-draw 0.2.15 → 0.2.17

package/src/client/DrawResultCard.tsx

@@ -1,8 +1,14 @@
 /**
- * The keyed `image_generate` tool result card: engine/quota facts and the
- * regenerate action. The images themselves are the attachment content blocks
- * the shell already renders from the tool result, so the card only adds the
- * accounting line and the action — it never duplicates image transport.
+ * The keyed `image_generate` tool view: engine/quota facts and the regenerate
+ * action once the call settles, and an in-flight row of its own while the
+ * arguments are still arriving. The images themselves are the attachment
+ * content blocks the shell already renders from the tool result, so the card
+ * only adds the accounting line and the action — it never duplicates image
+ * transport.
+ *
+ * The Host dispatches this keyed entry in EVERY stage of the call, and a keyed
+ * cell that is occupied never reaches the owner fallback — so the earlier
+ * stages cannot be answered with nothing without blanking the row.
  *
  * The `tool.call.toolview` SlotMap member is declared locally (mirroring the
  * harness's own ui-tool contract declaration, which its package index does not
@@ -13,20 +19,30 @@
 
 import { createElement as h, useState, type ReactElement } from 'react'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import { presentDrawResult, type ToolCallBlock } from './present.ts'
+import { presentDrawResult, toolCallPhase, type ToolCallBlock, type ToolCallPhase } from './present.ts'
 
 /**
- * Standard owner currency for one keyed tool view (mirror of the harness
- * ui-tool contract `ToolCallOwnerProps`, which the package index does not
- * re-export — keep the shape identical so the declarations merge).
+ * Stage-specific tool data, mirror of the harness ui-tool contract
+ * `ToolCallPhaseProps`. The Host dispatches the SAME keyed entry in every
+ * stage, so the card's own contract must discriminate on `phase` exactly as
+ * the Host's does — a narrower declaration here hides the preparing owner
+ * rather than rejecting it (the slot is occupied for every stage).
  */
-export interface ToolCallOwnerProps {
-  /** Tool call identity, stable across running and settled forms. */
+export type ToolCallPhaseProps =
+  | { readonly phase: 'preparing'; readonly block: ToolCallBlock }
+  | { readonly phase: 'start'; readonly block: ToolCallBlock }
+  | { readonly phase: 'result'; readonly block: ToolCallBlock }
+
+/**
+ * Common owner currency declared beside the phase share, mirror of the
+ * harness ui-tool contract `ToolCallCommonProps` (which the package index
+ * does not re-export — keep the shape identical so the declarations merge).
+ */
+export interface ToolCallCommonProps {
+  /** Tool call identity, stable across all stages. */
   callId: string
   /** Wire tool name and keyed dispatch value. */
   toolName: string
-  /** Frozen running call or settled result node. */
-  block: ToolCallBlock
   /** Session workspace root for relative summaries. */
   cwd?: string
   /** Open a tool argument path through the host. */
@@ -35,6 +51,12 @@ export interface ToolCallOwnerProps {
   inspect?: () => void
 }
 
+/**
+ * Standard owner currency for one keyed tool view: the common share plus the
+ * stage share, mirroring the harness ui-tool contract `ToolCallOwnerProps`.
+ */
+export type ToolCallOwnerProps = ToolCallCommonProps & ToolCallPhaseProps
+
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface SlotMap {
     /** Keyed atomic tool-call view, dispatched by the wire tool name. */
@@ -55,17 +77,55 @@ export type DrawResultCardProps =
   & InjectFace<DrawResultCardInjected>
 
 /**
- * The keyed tool result card.
- * @param props - owner currency, locale, and injected bindings.
- * @returns the card element.
+ * The keyed tool view. Dispatched by the wire tool name in EVERY stage of the
+ * call, so the card owes a presentation to the in-flight stages too: returning
+ * an empty node would leave the row blank, because an occupied keyed cell
+ * never reaches the Host's own generic row.
+ *
+ * @param props - owner currency (common + stage shares), locale, and injected bindings.
+ * @returns the in-flight row, or the settled result card.
  */
 export function DrawResultCard(props: DrawResultCardProps): ReactElement {
+  // The owner's discriminant and the block are two statements of the same fact,
+  // and the block is the one the presenter reads — so the card classifies the
+  // stage from the block, through the same function the presenter uses. The
+  // owner's arm only breaks the tie in the impossible case of a `result` owner
+  // carrying a block that is not a settled node.
+  const phase = toolCallPhase(props.block)
+  if (phase !== 'result') {
+    const stage = props.phase === 'result' ? phase : props.phase
+    return h('div', { className: 'dshdraw-inflight', 'aria-busy': 'true', 'data-phase': stage },
+      h('span', { className: 'dshdraw-inflight-title' }, props.t('row.title')),
+      h('span', { className: 'dshdraw-sep', 'aria-hidden': 'true' }, '·'),
+      h('span', { className: 'dshdraw-inflight-summary' }, props.toolName),
+      h('span', { className: 'dshdraw-inflight-state' }, props.t(inFlightKey(stage))),
+    )
+  }
+  return h(DrawResultCardBody, props)
+}
+
+/** Locale key naming the stage of a call that has not settled yet. */
+function inFlightKey(phase: ToolCallPhase): 'row.preparing' | 'row.running' {
+  return phase === 'preparing' ? 'row.preparing' : 'row.running'
+}
+
+/**
+ * The settled result card: engine/quota facts and the regenerate action.
+ *
+ * @param props - the owner at its `result` stage, locale, and injected bindings.
+ * @returns the card element.
+ */
+function DrawResultCardBody(props: DrawResultCardProps): ReactElement {
   const { block, regenerate, t } = props
   const presented = presentDrawResult(block)
   const [busy, setBusy] = useState(false)
   const [failed, setFailed] = useState(false)
 
-  if (presented === undefined) return h('div', null)
+  if (presented === undefined) {
+    // The Host handed this card a settled node it does not own (a foreign call
+    // head after window truncation, or an error result) — nothing to add.
+    return h('div', null)
+  }
 
   const runRegenerate = async (): Promise<void> => {
     if (presented.args === undefined) return

package/src/client/locales.ts

@@ -15,6 +15,9 @@ export type DrawLocaleKey =
   | 'result.regenerate'
   | 'result.regenerating'
   | 'result.failed'
+  | 'row.title'
+  | 'row.preparing'
+  | 'row.running'
   | 'tab'
   | 'tab.engines'
   | 'tab.preferred'
@@ -40,6 +43,9 @@ export const en: Record<DrawLocaleKey, string> = {
   'result.regenerate': 'Regenerate',
   'result.regenerating': 'Regenerating…',
   'result.failed': 'Regenerate failed',
+  'row.title': 'Tool call',
+  'row.preparing': 'Preparing tool call',
+  'row.running': 'Running',
   'tab': 'Image generation',
   'tab.engines': 'Engines',
   'tab.preferred': 'preferred',
@@ -66,6 +72,9 @@ export const zh: Record<DrawLocaleKey, string> = {
   'result.regenerate': '重新生成',
   'result.regenerating': '正在重新生成…',
   'result.failed': '重新生成失败',
+  'row.title': '工具调用',
+  'row.preparing': '正在准备调用',
+  'row.running': '运行中',
   'tab': '图像生成',
   'tab.engines': '引擎',
   'tab.preferred': '首选',

package/src/client/present.ts

@@ -51,6 +51,88 @@ export type ToolCallBlock = RunningToolCallBlock | SettledToolResultBlock
 /** Settled tool-result node only. */
 export type ToolResultNode = SettledToolResultBlock
 
+/**
+ * The Host's tool-call-view stage discriminant. The Host splits the owner
+ * currency into `preparing` / `start` / `result`, each carrying its own stage
+ * block, and dispatches the SAME keyed entry in every stage — so a keyed card
+ * receives a preparing owner whose block has no `kind` and no `argsRaw`.
+ *
+ * {@link TOOL_CALL_PHASES} is the single source of truth for this union: the
+ * literal type is derived from the array, so a value and its type can never
+ * drift apart, and `scripts/verify-host-contract.mjs` compares the array
+ * against the Host's own `ToolCallPhaseProps` declaration.
+ */
+export const TOOL_CALL_PHASES = ['preparing', 'start', 'result'] as const
+
+/** One stage of the Host's tool-call view. */
+export type ToolCallPhase = (typeof TOOL_CALL_PHASES)[number]
+
+/**
+ * Classify a frozen tool block into its Host stage, mirroring the Host's own
+ * `toolCallPhase`: a settled node wins on `kind`, and the running family splits
+ * on `phase`. `ToolCallBlock` is structurally narrower than the Host union
+ * (`RunningToolCallBlock` declares no `phase` field), so the running arm is
+ * read through a structural probe rather than a declared member.
+ *
+ * @param block - the frozen tool block the owner delivered.
+ * @returns the stage this block belongs to.
+ */
+export function toolCallPhase(block: ToolCallBlock): ToolCallPhase {
+  if ('kind' in block) return 'result'
+  return (block as { phase?: unknown }).phase === 'preparing' ? 'preparing' : 'start'
+}
+
+/** How a card presents one stage of its own keyed tool call. */
+export interface PresentedToolCallPhase {
+  /** The Host stage this presentation covers. */
+  phase: ToolCallPhase
+  /**
+   * Whether this stage carries a settled result to present, or whether the
+   * card must render its own in-flight row for a call still arriving.
+   */
+  state: 'result' | 'in-flight'
+}
+
+/**
+ * Project the card's one appearance per Host stage.
+ *
+ * Only the `result` stage carries the engine/quota facts and the regenerate
+ * action. The earlier stages have no arguments and no result, and the keyed
+ * slot is OCCUPIED for them — the Host's own generic row is unreachable
+ * (the renderer falls back only for an empty cell) — so the card owning an
+ * in-flight row is what keeps the row visible while the call streams.
+ *
+ * A stage outside the declared vocabulary is reported loudly instead of being
+ * silently swept into `preparing`; the `switch` is exhaustive over
+ * {@link ToolCallPhase}, so a new stage fails the build before it can reach
+ * this default.
+ *
+ * @param phase - the stage classified from the owner's block.
+ * @returns the presentation this card owes that stage.
+ */
+export function presentToolCallPhase(phase: ToolCallPhase): PresentedToolCallPhase {
+  switch (phase) {
+    case 'result':
+      return { phase, state: 'result' }
+    case 'preparing':
+    case 'start':
+      return { phase, state: 'in-flight' }
+    default:
+      return exhaustiveToolCallPhase(phase)
+  }
+}
+
+/**
+ * Compile-time completeness check for the stage vocabulary: a new Host stage
+ * added to {@link ToolCallPhase} without a branch above fails the build here.
+ *
+ * @param phase - the unhandled stage.
+ * @returns never; throws at runtime.
+ */
+function exhaustiveToolCallPhase(phase: never): never {
+  throw new Error(`unhandled tool-call phase: ${JSON.stringify(phase)}`)
+}
+
 /** One image of the presented result card. */
 export interface PresentedImage {
   attachmentId: string
@@ -78,11 +160,19 @@ export interface PresentedDrawResult {
 /**
  * Project one settled `image_generate` tool block onto the card model.
  *
+ * The stage guard is explicit, not incidental: only the Host's `result` stage
+ * carries `kind`, and the preparing stage's block is an ordinary object, so
+ * an `undefined` return is the presenter's answer for every non-result stage
+ * as well as for a foreign tool, an error result, or a window-truncated call
+ * head. The card pairs that answer with {@link toolCallPhase} to render its
+ * in-flight row instead of an empty node.
+ *
  * @param block - the frozen tool-call block (running or settled).
  * @returns the presented model, or `undefined` when the block is not a settled
  *   image_generate result.
  */
 export function presentDrawResult(block: ToolCallBlock): PresentedDrawResult | undefined {
+  if (toolCallPhase(block) !== 'result') return undefined
   if (!('kind' in block) || block.kind !== 'tool-result' || block.isError) return undefined
   if (block.call?.name !== 'image_generate') return undefined
   const value = (block.meta as { engine?: unknown; model?: unknown; fallbackUsed?: unknown; images?: unknown; quota?: unknown; limits?: unknown } | undefined) ?? {}

package/src/client/styles.ts

@@ -31,6 +31,11 @@ export function installDrawStyles(): () => void {
 .dshdraw-figure img { max-width: 100%; border-radius: 6px; border: 1px solid var(--dsh-border, #d0d7de); }
 .dshdraw-figure figcaption { font-size: 11px; opacity: 0.75; overflow-wrap: anywhere; }
 .dshdraw-meta { font-size: 12px; opacity: 0.85; display: flex; flex-wrap: wrap; gap: 12px; }
+.dshdraw-inflight { display: flex; align-items: baseline; gap: 6px; flex-wrap: wrap; font-size: 13px; min-height: 20px; }
+.dshdraw-inflight .dshdraw-sep { opacity: 0.45; }
+.dshdraw-inflight-title { font-weight: 500; }
+.dshdraw-inflight-summary { opacity: 0.85; overflow-wrap: anywhere; }
+.dshdraw-inflight-state { font-size: 12px; opacity: 0.7; }
 .dshdraw-actions { display: flex; gap: 8px; }
 .dshdraw-button {
   border: 1px solid var(--dsh-border, #d0d7de); border-radius: 6px; background: transparent;

package/src/version.ts

@@ -8,4 +8,4 @@
  */
 
 /** Plugin version; must equal the `version` field in `package.json`. */
-export const PLUGIN_VERSION = '0.2.15'
+export const PLUGIN_VERSION = '0.2.17'