dsh-taskboard 0.1.0

package/src/client/board/TaskFormModal.tsx

@@ -0,0 +1,257 @@
+/**
+ * The task form modal — create and edit in one polished dialog: header with
+ * icon / subtitle / close, a sectioned field grid (title, project, model,
+ * urgency tri-picker with hints, description, prompt, execution-mode
+ * segmented picker, cron with presets and a live next-run preview), and a
+ * footer bar carrying the validation hint and the actions. Esc closes;
+ * the title input is focused on open.
+ *
+ * @module dsh-taskboard/client/board/TaskFormModal
+ */
+import { useEffect, useRef, useState, type ReactNode } from 'react'
+import type { BoardController } from '../controller.ts'
+import type { Urgency } from '../../shared/protocol.ts'
+import { nextCronTime, parseCron } from '../../shared/protocol.ts'
+import { fmtTime } from './TaskBoard.tsx'
+
+/** One row of the configured model catalog (from llm.models). */
+export interface CatalogModel { provider: string; model: string; name?: string }
+
+/** Urgency segmented options with a one-line hint each. */
+const URGENCY_OPTIONS: ReadonlyArray<{ value: Urgency; label: string; hint: string }> = [
+  { value: 'urgent', label: '紧急', hint: '优先处理' },
+  { value: 'normal', label: '一般', hint: '正常排期' },
+  { value: 'relaxed', label: '不急', hint: '有空再做' },
+]
+
+/** Cron presets offered in the scheduled mode. */
+const CRON_PRESETS: ReadonlyArray<{ label: string; cron: string }> = [
+  { label: '每天 09:00', cron: '0 9 * * *' },
+  { label: '每小时', cron: '0 * * * *' },
+  { label: '每 10 分钟', cron: '*/10 * * * *' },
+  { label: '每周一 09:00', cron: '0 9 * * 1' },
+]
+
+/** Field shell: label + control, optionally spanning the full grid row. */
+function Field({ label, required = false, full = false, children }: {
+  label: string
+  required?: boolean
+  full?: boolean
+  children: ReactNode
+}) {
+  return (
+    <label className="dsh-atb-field" data-span={full ? 'full' : undefined}>
+      <span className="dsh-atb-field-label">
+        {label}
+        {required && <em className="dsh-atb-req">*</em>}
+      </span>
+      {children}
+    </label>
+  )
+}
+
+/**
+ * The form modal. Without `task` it composes a new task; with `task` it
+ * edits that record (project, urgency, execution, model included — the GUI
+ * is the owner surface).
+ * @param controller - the controller.
+ * @param task - the task being edited (create mode when absent).
+ */
+export function TaskFormModal({ controller, task }: { controller: BoardController; task?: TaskRecordLike }) {
+  const state = controller.getSnapshot()
+  const editing = task !== undefined
+  const [title, setTitle] = useState(task?.title ?? '')
+  const [description, setDescription] = useState(task?.description ?? '')
+  const [prompt, setPrompt] = useState(task?.prompt ?? '')
+  const [workspaceId, setWorkspaceId] = useState(task?.workspaceId ?? state.filters.workspaceId ?? state.workspaces[0]?.id ?? '')
+  const [urgency, setUrgency] = useState<Urgency>(task?.urgency ?? 'normal')
+  const [mode, setMode] = useState<'claim' | 'scheduled'>(task?.execution.mode === 'scheduled' ? 'scheduled' : 'claim')
+  const [cron, setCron] = useState(task?.execution.cron ?? '0 9 * * *')
+  const [catalog, setCatalog] = useState<CatalogModel[]>([])
+  const [model, setModel] = useState(task?.model !== undefined ? JSON.stringify(task.model) : '')
+  const titleRef = useRef<HTMLInputElement>(null)
+
+  // Focus the title and close on Esc while the dialog is open.
+  useEffect(() => {
+    titleRef.current?.focus()
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key === 'Escape') controller.closeForm()
+    }
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  }, [controller])
+
+  // Model catalog: the plugin face provides it when the runtime is up.
+  useEffect(() => {
+    const face = (controller as unknown as { modelCatalog?: () => Promise<CatalogModel[]> }).modelCatalog
+    if (face === undefined) return
+    void face().then(setCatalog).catch(() => setCatalog([]))
+  }, [controller])
+
+  // Live cron validation + next-run preview (same math as the host).
+  const cronMatch = mode === 'scheduled' ? parseCron(cron.trim()) : null
+  const nextRun = cronMatch !== null ? nextCronTime(cronMatch, Date.now()) : null
+  const cronBad = mode === 'scheduled' && (cronMatch === null || nextRun === null)
+  const valid = title.trim().length > 0 && workspaceId !== '' && !cronBad
+
+  const submit = (): void => {
+    if (!valid) return
+    const picked = model !== '' ? (JSON.parse(model) as { provider: string; model: string }) : undefined
+    if (editing) {
+      void controller.update(task.id, task.version, {
+        title,
+        description,
+        prompt,
+        urgency,
+        workspaceId,
+        execution: mode === 'scheduled' ? { mode, cron: cron.trim() } : { mode },
+        // '' in edit mode clears the pinned model back to the default.
+        model: picked ?? null,
+      })
+    } else {
+      void controller.create({
+        title,
+        workspaceId,
+        urgency,
+        description: description.length > 0 ? description : undefined,
+        prompt: prompt.length > 0 ? prompt : undefined,
+        execution: mode === 'scheduled' ? { mode, cron: cron.trim() } : { mode },
+        model: picked,
+      })
+    }
+  }
+
+  const hint = !valid
+    ? (title.trim().length === 0 ? '请填写标题' : workspaceId === '' ? '请选择项目' : 'Cron 表达式无效（分 时 日 月 周）')
+    : mode === 'scheduled' && nextRun !== null
+      ? `下次运行 ${fmtTime(nextRun)}`
+      : editing
+        ? `保存后版本 v${task.version} → v${task.version + 1}`
+        : '创建后项目内会话可认领执行'
+
+  return (
+    <div className="dsh-atb-modal-backdrop" onClick={e => { if (e.target === e.currentTarget) controller.closeForm() }}>
+      <div className="dsh-atb-modal" data-mode={editing ? 'edit' : 'create'} role="dialog" aria-modal="true" aria-label={editing ? '编辑任务' : '新建任务'}>
+        <div className="dsh-atb-modal-head">
+          <span className="dsh-atb-modal-headicon">{editing ? '✎' : '✚'}</span>
+          <div className="dsh-atb-modal-headtext">
+            <h3>{editing ? '编辑任务' : '新建任务'}</h3>
+            <p>{editing ? '调整任务内容与执行配置' : '推入看板，项目内会话可认领执行'}</p>
+          </div>
+          <button type="button" className="dsh-atb-modal-close" aria-label="关闭" onClick={() => controller.closeForm()}>✕</button>
+        </div>
+
+        <div className="dsh-atb-modal-body">
+          <Field label="标题" required full>
+            <input ref={titleRef} value={title} onChange={e => setTitle(e.target.value)} placeholder="一句话说清要做什么" maxLength={200} />
+          </Field>
+
+          <Field label="项目" required>
+            <select value={workspaceId} onChange={e => setWorkspaceId(e.target.value)}>
+              {state.workspaces.map(ws => <option key={ws.id} value={ws.id}>{ws.title || ws.path}</option>)}
+            </select>
+          </Field>
+
+          <Field label="模型（默认 = 会话默认模型）">
+            <select value={model} onChange={e => setModel(e.target.value)}>
+              <option value="">默认模型</option>
+              {catalog.map(m => (
+                <option key={`${m.provider}/${m.model}`} value={JSON.stringify({ provider: m.provider, model: m.model })}>
+                  {m.name ?? m.model}（{m.provider}）
+                </option>
+              ))}
+            </select>
+          </Field>
+
+          <Field label="紧急度" full>
+            <div className="dsh-atb-urgency-picker">
+              {URGENCY_OPTIONS.map(o => (
+                <button
+                  key={o.value}
+                  type="button"
+                  className="dsh-atb-urgency-opt"
+                  data-urgency={o.value}
+                  data-on={urgency === o.value}
+                  onClick={() => setUrgency(o.value)}
+                >
+                  <span className="dsh-atb-urgency-name"><span className="dsh-atb-dot" data-urgency={o.value} />{o.label}</span>
+                  <span className="dsh-atb-urgency-hint">{o.hint}</span>
+                </button>
+              ))}
+            </div>
+          </Field>
+
+          <Field label={editing ? '描述' : '描述（可选）'} full>
+            <textarea value={description} onChange={e => setDescription(e.target.value)} placeholder="需求细节、验收标准…" />
+          </Field>
+
+          <Field label={editing ? '执行 Prompt' : '执行 Prompt（可选，默认 = 标题+描述）'} full>
+            <textarea value={prompt} onChange={e => setPrompt(e.target.value)} placeholder="发给执行会话的完整指令" />
+          </Field>
+
+          <Field label="执行方式" full>
+            <div className="dsh-atb-mode-picker">
+              <button type="button" className="dsh-atb-mode-opt" data-on={mode === 'claim'} onClick={() => setMode('claim')}>
+                <span className="dsh-atb-mode-name">🤝 认领制</span>
+                <span className="dsh-atb-mode-hint">项目内会话认领</span>
+              </button>
+              <button type="button" className="dsh-atb-mode-opt" data-on={mode === 'scheduled'} onClick={() => setMode('scheduled')}>
+                <span className="dsh-atb-mode-name">⏰ 定时执行</span>
+                <span className="dsh-atb-mode-hint">到点自动开跑</span>
+              </button>
+            </div>
+          </Field>
+
+          {mode === 'scheduled' && (
+            <Field label="Cron 表达式" required full>
+              <input
+                className={cronBad ? 'dsh-atb-input-bad' : undefined}
+                value={cron}
+                onChange={e => setCron(e.target.value)}
+                placeholder="分 时 日 月 周"
+                spellCheck={false}
+              />
+              <span className="dsh-atb-cron-presets">
+                {CRON_PRESETS.map(p => (
+                  <button
+                    key={p.cron}
+                    type="button"
+                    className="dsh-atb-cron-preset"
+                    data-on={cron.trim() === p.cron}
+                    onClick={() => setCron(p.cron)}
+                  >
+                    {p.label}
+                  </button>
+                ))}
+                {!cronBad && nextRun !== null && <span className="dsh-atb-cron-next">下次 {fmtTime(nextRun)}</span>}
+              </span>
+            </Field>
+          )}
+        </div>
+
+        <div className="dsh-atb-modal-foot">
+          <span className="dsh-atb-modal-hint" data-tone={valid ? undefined : 'bad'}>{hint}</span>
+          <span className="dsh-atb-modal-footbtns">
+            <button type="button" className="dsh-atb-btn" onClick={() => controller.closeForm()}>取消</button>
+            <button type="button" className="dsh-atb-btn" data-primary="true" disabled={!valid} onClick={submit}>
+              {editing ? '保存修改' : '创建任务'}
+            </button>
+          </span>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/** The record shape this form edits (narrow structural type to avoid a value import). */
+interface TaskRecordLike {
+  id: string
+  version: number
+  title: string
+  description: string
+  prompt: string
+  workspaceId: string
+  urgency: Urgency
+  execution: { mode: 'claim' | 'scheduled'; cron?: string }
+  model?: { provider: string; model: string }
+}

package/src/client/board-mount.tsx

@@ -0,0 +1,92 @@
+/**
+ * Board view mounting: a container appended inside the `[data-pane=
+ * "conversation"]` grid item (a trailing child React never manages), with a
+ * stylesheet rule hiding the conversation content while the board is active.
+ * Toggling rides a data attribute on <html> — no React involvement in the
+ * shell.
+ *
+ * @module dsh-taskboard/client/board-mount
+ */
+import { createRoot, type Root } from 'react-dom/client'
+import type { BoardController } from './controller.ts'
+import { TaskBoard } from './board/TaskBoard.tsx'
+
+/** The injected board container. */
+export const BOARD_VIEW_SELECTOR = '[data-dsh-atb-view]'
+
+const CONVERSATION_COLUMN_SELECTOR = '[data-pane="conversation"]'
+const ACTIVE_ATTR = 'data-dsh-atb-active'
+/** Sibling panels' activation attributes, evicted when this board opens. */
+const OTHER_ACTIVE_ATTRS = ['data-dsh-taskboard-active', 'data-dsh-ssh-active']
+/** Cross-plugin activation event; detail is the activating panel name. */
+const ACTIVATE_EVENT = 'dsh-panel-activate'
+// 'taskboard' is the family ui-task-board panel's event name; stay distinct to keep eviction working.
+const PANEL_NAME = 'dsh-taskboard'
+
+/** Find the center column. */
+function conversationColumn(): HTMLElement | undefined {
+  return document.querySelector<HTMLElement>(CONVERSATION_COLUMN_SELECTOR) ?? undefined
+}
+
+/**
+ * Mount the board React tree and bind visibility to the controller.
+ * @param controller - the controller.
+ * @returns disposer.
+ */
+export function mountBoard(controller: BoardController): () => void {
+  let root: Root | undefined
+  let container: HTMLDivElement | undefined
+
+  const ensure = (): void => {
+    if (container !== undefined) return
+    const column = conversationColumn()
+    if (column === undefined) return
+    container = document.createElement('div')
+    container.dataset.dshAtbView = ''
+    container.className = 'dsh-atb-view'
+    column.appendChild(container)
+    root = createRoot(container)
+    root.render(<TaskBoard controller={controller} />)
+  }
+
+  const waitObserver = new MutationObserver(() => { ensure() })
+  waitObserver.observe(document.body, { childList: true, subtree: true })
+
+  const applyActive = (): void => {
+    if (controller.getSnapshot().boardOpen) {
+      for (const attr of OTHER_ACTIVE_ATTRS) document.documentElement.removeAttribute(attr)
+      document.documentElement.setAttribute(ACTIVE_ATTR, '')
+      document.dispatchEvent(new CustomEvent(ACTIVATE_EVENT, { detail: PANEL_NAME }))
+    } else {
+      document.documentElement.removeAttribute(ACTIVE_ATTR)
+    }
+  }
+  const onOtherActivate = (event: Event): void => {
+    const detail = (event as CustomEvent).detail
+    if (detail !== PANEL_NAME && controller.getSnapshot().boardOpen) {
+      controller.closeBoard()
+    }
+  }
+  const SIDEBAR_ROW_SELECTOR = '[class*="sessionRow"], [class*="projectRow"], [class*="searchResultRow"], [class*="searchResultWorkspace"], [class*="newSession"]'
+  const onClickSidebarRow = (event: MouseEvent): void => {
+    if (!controller.getSnapshot().boardOpen) return
+    const target = event.target as HTMLElement | null
+    if (target === null) return
+    if (target.closest(SIDEBAR_ROW_SELECTOR) !== null) controller.closeBoard()
+  }
+  document.addEventListener('click', onClickSidebarRow, true)
+  document.addEventListener(ACTIVATE_EVENT, onOtherActivate)
+  const unsubscribe = controller.subscribe(applyActive)
+  applyActive()
+  ensure()
+
+  return () => {
+    document.removeEventListener('click', onClickSidebarRow, true)
+    document.removeEventListener(ACTIVATE_EVENT, onOtherActivate)
+    waitObserver.disconnect()
+    unsubscribe()
+    document.documentElement.removeAttribute(ACTIVE_ATTR)
+    root?.unmount()
+    container?.remove()
+  }
+}

package/src/client/controller.ts

@@ -0,0 +1,241 @@
+/**
+ * The board controller: framework-free state holder the React views render
+ * from. Owns the ledger snapshot, workspace listing, view state (open,
+ * filters, selection, modals), and the SSE subscription with gap-triggered
+ * full refetch. Every mutation goes through the route client and lands in the
+ * snapshot through the SSE change stream or the explicit refetch.
+ *
+ * @module dsh-taskboard/client/controller
+ */
+import type { ChangeEvent, UpdateTaskBody, WorkspaceView } from '../shared/api.ts'
+import type { TaskLedger, TaskRecord, Urgency } from '../shared/protocol.ts'
+import { emptyLedger } from '../shared/protocol.ts'
+import type { TaskboardClient } from './api.ts'
+
+/** View filters over the ledger. */
+export interface BoardFilters {
+  /** Selected project id; undefined = all projects. */
+  workspaceId?: string
+  /** Selected urgency chips (empty = all). */
+  urgencies: Urgency[]
+}
+
+/** Controller snapshot the views render. */
+export interface ControllerState {
+  boardOpen: boolean
+  ledger: TaskLedger
+  workspaces: WorkspaceView[]
+  filters: BoardFilters
+  /** Selected task id (detail view); undefined closes the detail. */
+  selectedId?: string
+  /** Task form modal visible (create when editingId is unset). */
+  composerOpen: boolean
+  /** Task being edited in the form modal; unset = create mode. */
+  editingId?: string
+  /** Secondary (canceled/archived/trashed) tab visible. */
+  secondaryOpen: boolean
+  /** Transient error surface (action failures); cleared on next success. */
+  error?: string
+}
+
+/** Instantiate the default state. */
+function initialState(): ControllerState {
+  return {
+    boardOpen: false,
+    ledger: emptyLedger(),
+    workspaces: [],
+    filters: { urgencies: [] },
+    composerOpen: false,
+    secondaryOpen: false,
+  }
+}
+
+/**
+ * The board controller.
+ */
+export class BoardController {
+  private state: ControllerState = initialState()
+  private readonly subscribers = new Set<() => void>()
+  private disposed = false
+  private disposeStream: (() => void) | undefined
+  private refreshInFlight: Promise<void> | undefined
+
+  /** @param client - the route client. */
+  constructor(private readonly client: TaskboardClient) {}
+
+  /** Current snapshot (render input). */
+  getSnapshot(): ControllerState {
+    return this.state
+  }
+
+  /** Subscribe; returns unsubscribe. */
+  subscribe(fn: () => void): () => void {
+    this.subscribers.add(fn)
+    return () => this.subscribers.delete(fn)
+  }
+
+  private emit(): void {
+    if (this.disposed) return
+    for (const fn of this.subscribers) fn()
+  }
+
+  private setState(patch: Partial<ControllerState>): void {
+    this.state = { ...this.state, ...patch }
+    this.emit()
+  }
+
+  /** Start subscriptions; call once after construction. */
+  start(): void {
+    void this.refresh()
+    this.disposeStream = this.client.stream(
+      (change: ChangeEvent) => {
+        this.setState({ ledger: { ...this.state.ledger, revision: change.revision } })
+        // Any change invalidates the full snapshot; refetch (cheap, local).
+        void this.refresh()
+      },
+      () => { void this.refresh() },
+    )
+  }
+
+  /** Full refetch (state + workspaces + open detail). */
+  async refresh(): Promise<void> {
+    if (this.refreshInFlight !== undefined) return this.refreshInFlight
+    this.refreshInFlight = (async () => {
+      try {
+        const [ledger, workspaces] = await Promise.all([
+          this.client.state(),
+          this.client.workspaces(),
+        ])
+        let selected: TaskRecord | undefined
+        if (this.state.selectedId !== undefined) {
+          selected = ledger.tasks.find(t => t.id === this.state.selectedId)
+        }
+        this.setState({ ledger, workspaces, error: undefined, selectedId: selected === undefined ? undefined : this.state.selectedId })
+      } catch (error) {
+        this.setState({ error: error instanceof Error ? error.message : String(error) })
+      } finally {
+        this.refreshInFlight = undefined
+      }
+    })()
+    return this.refreshInFlight
+  }
+
+  /** Stop everything. */
+  dispose(): void {
+    this.disposed = true
+    this.disposeStream?.()
+    this.subscribers.clear()
+  }
+
+  // ------------------------------------------------------------------ view
+  /** Open the board (sidebar entry). */
+  openBoard(): void { this.setState({ boardOpen: true }) }
+
+  /** Close the board. */
+  closeBoard(): void { this.setState({ boardOpen: false }) }
+
+  /** Toggle the board. */
+  toggleBoard(): void { this.setState({ boardOpen: !this.state.boardOpen }) }
+
+  /** Set the project filter. */
+  setWorkspaceFilter(workspaceId?: string): void {
+    this.setState({ filters: { ...this.state.filters, workspaceId } })
+  }
+
+  /** Toggle one urgency chip. */
+  toggleUrgency(urgency: Urgency): void {
+    const set = new Set(this.state.filters.urgencies)
+    if (set.has(urgency)) set.delete(urgency)
+    else set.add(urgency)
+    this.setState({ filters: { ...this.state.filters, urgencies: [...set] } })
+  }
+
+  /** Select a task (open detail). */
+  select(id?: string): void { this.setState({ selectedId: id }) }
+
+  /** Show/hide the task form (create mode when opening). */
+  setComposer(open: boolean): void { this.setState({ composerOpen: open, editingId: undefined }) }
+
+  /** Open the form modal editing an existing task. */
+  openEditor(id: string): void { this.setState({ composerOpen: true, editingId: id }) }
+
+  /** Close the form modal whatever its mode. */
+  closeForm(): void { this.setState({ composerOpen: false, editingId: undefined }) }
+
+  /** Toggle the secondary tab. */
+  toggleSecondary(): void { this.setState({ secondaryOpen: !this.state.secondaryOpen }) }
+
+  // ---------------------------------------------------------------- writes
+  /** Create a task (composer submit). */
+  async create(body: Parameters<TaskboardClient['create']>[0]): Promise<void> {
+    try {
+      await this.client.create(body)
+      this.setState({ composerOpen: false, error: undefined })
+      await this.refresh()
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
+  /** Edit task fields (form modal submit; the GUI is the owner surface). */
+  async update(id: string, ifVersion: number, body: Omit<UpdateTaskBody, 'ifVersion'>): Promise<void> {
+    try {
+      await this.client.update(id, { ifVersion, ...body })
+      this.setState({ composerOpen: false, editingId: undefined, error: undefined })
+      await this.refresh()
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
+  /** Move a task (user surface: done allowed). */
+  async move(id: string, ifVersion: number, status: string): Promise<void> {
+    try {
+      await this.client.move(id, { ifVersion, status })
+      await this.refresh()
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
+  /** Toggle the blocked marker. */
+  async toggleBlocked(task: TaskRecord): Promise<void> {
+    try {
+      await this.client.update(task.id, { ifVersion: task.version, blocked: !task.blocked })
+      await this.refresh()
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
+  /** Append a user comment. */
+  async comment(id: string, body: string): Promise<void> {
+    try {
+      await this.client.comment(id, body)
+      await this.refresh()
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
+  /** Trigger a manual run (fresh in-project session, pinned model). */
+  async run(id: string): Promise<void> {
+    try {
+      await this.client.run(id)
+      await this.refresh()
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+
+  /** Soft-delete (agent parity) then optional purge. */
+  async remove(id: string, ifVersion: number, purge: boolean): Promise<void> {
+    try {
+      await this.client.remove(id, purge ? { purge: true } : { ifVersion })
+      if (purge) this.setState({ selectedId: undefined })
+      await this.refresh()
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Browser half entry for dsh-taskboard: wires the route client and the
+ * board controller, exposes the model catalog (via the runtime's llm.models
+ * RPC when the connection service is present), mounts the sidebar entry and
+ * the board view.
+ *
+ * Failure policy: DOM mounting problems are logged, never thrown — the web
+ * shell fails the whole boot when a plugin apply throws.
+ *
+ * Export shape: `name` / `inject` / `apply`, no default.
+ *
+ * @module dsh-taskboard/client
+ */
+import { createClient } from './api.ts'
+import { BoardController } from './controller.ts'
+import { injectStyles } from './styles.ts'
+import { mountSidebarEntry } from './sidebar-entry.ts'
+import { mountBoard } from './board-mount.tsx'
+
+/** Client plugin name. */
+export const name = 'dsh-taskboard/client'
+
+/** Required client services (fiber inject waiting). */
+export const inject = ['connection']
+
+/** Narrow connection face for the model catalog. */
+interface ConnectionFace {
+  api: {
+    llm: {
+      models(payload: Record<string, never>): Promise<{ result: { ok: true; value: { groups: Array<{ id: string; name: string; models: Array<{ id: string; name?: string }> }> } } | { ok: false } }>
+    }
+  }
+}
+
+/** Effect-hook face the runner provides on the client context. */
+interface ClientContextFace {
+  get?(name: string): unknown
+  effect?(fn: () => unknown, label?: string): void
+}
+
+/**
+ * Mount the client half.
+ * @param ctx - the client context (connection injected).
+ */
+export function apply(ctx: ClientContextFace): void {
+  try {
+    injectStyles()
+    const client = createClient()
+    const controller = new BoardController(client)
+
+    // Model catalog for the composer: llm.models over the connection RPC.
+    const connection = ctx.get?.('connection') as ConnectionFace | undefined
+    if (connection !== undefined) {
+      type CatalogRow = { provider: string; model: string; name?: string }
+      ;(controller as unknown as { modelCatalog?: () => Promise<CatalogRow[]> }).modelCatalog = async (): Promise<CatalogRow[]> => {
+        const response = await connection.api.llm.models({})
+        if (!response.result.ok) return []
+        const out: CatalogRow[] = []
+        for (const group of response.result.value.groups) {
+          for (const model of group.models) {
+            out.push({ provider: group.id, model: model.id, name: model.name })
+          }
+        }
+        return out
+      }
+    }
+
+    controller.start()
+    const disposers: Array<() => void> = []
+    try {
+      disposers.push(mountSidebarEntry(controller))
+      disposers.push(mountBoard(controller))
+    } catch (error) {
+      // DOM failures degrade the board, never the GUI.
+      console.error('[dsh-taskboard] mount failed:', error)
+    }
+    // cordis effect semantics: the callback runs immediately and its RETURN
+    // VALUE is the disposer (family-plugin precedent: () => () => {...}).
+    // A single-layer arrow here executes the teardown immediately.
+    ctx.effect?.(() => () => {
+      for (const d of disposers.splice(0)) d()
+      controller.dispose()
+    }, 'dsh-taskboard: client mount')
+  } catch (error) {
+    console.error('[dsh-taskboard] client half failed to start:', error)
+  }
+}