dsh-sidenote 0.1.0

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region src/index.ts
+/** Plugin identity for cordis.yml rows. */
+const name = "dsh-sidenote";
+function apply(_ctx) {}
+//#endregion
+export { apply, name };

package/lib/types/client/annotate/anchor.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Badge anchoring (Workitem 02): resolve a live DOM Range for an annotation.
+ *
+ * The range captured at creation time dies when React re-renders the message
+ * (session switch, streaming rebuilds, fork/delete). We therefore re-anchor
+ * on demand: find the message element by `data-chat-anchor-key`, locate the
+ * Nth occurrence of the anchor text in its text nodes, and rebuild the range.
+ * Anchor loss is acceptable (页面级临时语义) — the badge simply skips a
+ * render; nothing here may throw into the page.
+ */
+import type { Annotation } from './model.ts';
+/** The badge anchor point: right edge of the selection rects, first-line height. */
+export interface BadgeAnchor {
+    /** max(rect.right) across the selection's client rects. */
+    readonly right: number;
+    /** Vertical center of the FIRST line's rect. */
+    readonly centerY: number;
+}
+/**
+ * Resolve a live range for an annotation: the cached range while its nodes
+ * are still connected, otherwise a re-anchored one (cached on success).
+ * Returns null when the anchor is gone — callers skip rendering, never throw.
+ */
+export declare function resolveRange(annotation: Annotation, cache: Map<number, Range>): Range | null;
+/**
+ * The badge anchor point of a range: 选区矩形右缘 (max right edge across
+ * client rects — the message column's right edge for full-line selections,
+ * the selection's text end for inline ones) at 选区首行高度 (first rect's
+ * vertical center). Null when the range lays out to nothing.
+ */
+export declare function badgeAnchorOf(range: Range): BadgeAnchor | null;
+/** Client rects of a range for the active-highlight overlay (empty on failure). */
+export declare function highlightRectsOf(range: Range): readonly {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}[];
+/** 角标碰撞半径（px）：同点位的角标必须错开才可点击。 */
+export declare const BADGE_COLLISION_RADIUS = 18;
+/** 碰撞时向下错开的步长（px，大于角标直径）。 */
+export declare const BADGE_SPREAD_STEP = 24;
+/**
+ * 角标落点错开：与已放置角标（|Δx|、|Δy| 均小于碰撞半径）冲突时按
+ * BADGE_SPREAD_STEP 逐级下移——同一选区/相邻行的多个注释角标不再叠罗汉
+ * （叠放时上层角标拦截下层角标的点击）。
+ */
+export declare function spreadBadgePoint(point: {
+    x: number;
+    y: number;
+}, placed: readonly {
+    x: number;
+    y: number;
+}[]): {
+    x: number;
+    y: number;
+};

package/lib/types/client/annotate/chip.d.ts

@@ -0,0 +1,11 @@
+import type { ReactNode } from 'react';
+import type { InputZone } from '../../context-types.ts';
+import type { AnnotationStore } from './model.ts';
+/** Props the dock skeleton hands us: the InputZone owner share (point-in-time). */
+interface ChipProps {
+    readonly session: InputZone['session'];
+    readonly input: InputZone['input'];
+}
+/** Create the slot component bound to one store instance. */
+export declare function createAnnotationChip(store: AnnotationStore): (props: ChipProps) => ReactNode;
+export {};

package/lib/types/client/annotate/draft.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Managed draft prefix (Workitem 02 发送携带的降级方案): while a session has
+ * active annotations, their formatted quote block is maintained at the very
+ * top of the composer draft; the user's own text follows it, so sending
+ * naturally carries the context. The composer chip clears on the send edge
+ * (draft non-empty → empty), the annotations flip to 'sent', and the prefix
+ * dissolves with the already-cleared draft.
+ *
+ * insertReference spike conclusion: the U+FFFC chip path is NOT viable from a
+ * plugin — `SessionInput.insertReference` requires a span CAS'd against the
+ * live draftRev (a trigger-pipeline concept), and chip serialization routes
+ * through the source owner's ReferenceCodec, which is package-internal to
+ * ui-input-trigger with no plugin-facing registry. An unowned source would
+ * mark the occurrence invalid and fail the whole submit. Hence this file.
+ */
+import type { Context, SessionId, SessionInput } from '../../context-types.ts';
+import type { AnnotationStore } from './model.ts';
+/** Resolve the per-session input facade, degrading to undefined (never throws). */
+export declare function resolveInput(ctx: Context, sessionId: SessionId): SessionInput | undefined;
+/**
+ * Rewrite one session's draft so its managed head matches the active
+ * annotations. A no-op when nothing would change (the common case while the
+ * user types their own message below the head).
+ */
+export declare function syncSessionDraft(ctx: Context, store: AnnotationStore, sessionId: SessionId): void;
+/** Re-sync every session holding annotations (store-change fan-out). */
+export declare function syncAllDrafts(ctx: Context, store: AnnotationStore): void;
+/** Forget all managed heads (page-level lifecycle; plugin teardown/testing). */
+export declare function resetManagedHeads(): void;

package/lib/types/client/annotate/format.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Quote-block formatting and the managed-draft math (Workitem 02). Pure and
+ * dependency-free for unit testing — the shapes here ARE the contract for
+ * 「发送给模型的数据形态」:
+ *
+ *   > 原文片段 1
+ *   注解：xxx
+ *
+ *   > 原文片段 2
+ *   （无注解）
+ *
+ *   用户消息正文
+ */
+/** Selected-text bound admitted into one annotation (超长截断 + 标记). */
+export declare const SELECTION_LIMIT = 500;
+/** Marker appended when a selection is truncated (参照 sidebar-qa 的省略号模式). */
+export declare const TRUNCATION_MARK = "\u2026";
+/** Bound a quote to {@link SELECTION_LIMIT} characters, marking truncation. */
+export declare function truncateQuote(text: string, limit?: number): string;
+/** Quote one (possibly multi-line) text as `> `-prefixed lines. */
+export declare function quoteLines(text: string): string;
+export interface QuoteItem {
+    readonly text: string;
+    readonly note: string;
+}
+/** One annotation's block: quoted original plus the note line. */
+export declare function formatQuoteItem(item: QuoteItem): string;
+/** The full context block for every active annotation, in creation order. */
+export declare function buildQuoteBlock(items: readonly QuoteItem[]): string;
+/** The 「在侧边聊天中提问」 seed: quote + optional note（与主对话注释同构）. */
+export declare function buildSideChatQuote(text: string, note?: string): string;
+/**
+ * Recompute a session composer draft from its managed head.
+ *
+ * The managed head (quote block + one blank line) is maintained at the very
+ * top of the draft while annotations are active; the user's own text follows
+ * it untouched. `lastHead` is the head we last wrote: when the draft still
+ * starts with it we strip exactly that span; otherwise the user meddled with
+ * the head region and the whole draft is treated as user text (the fresh head
+ * is simply re-prepended — a documented, non-crashing degradation).
+ */
+export declare function nextManagedDraft(draft: string, lastHead: string, block: string): {
+    head: string;
+    draft: string;
+};
+/**
+ * The send-edge predicate: the composer draft flipping non-empty → empty
+ * while annotations were attached is the reliable「发送后」signal (submit
+ * clears the draft as a commit; queueing does too). Whitespace-only drafts
+ * count as empty.
+ */
+export declare function isSendEdge(previousDraft: string, nextDraft: string): boolean;

package/lib/types/client/annotate/index.d.ts

@@ -0,0 +1,2 @@
+import type { Context } from '../../context-types.ts';
+export declare function registerAnnotations(ctx: Context): void;

package/lib/types/client/annotate/model.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The annotation store: per-session numbered selection annotations. Pure
+ * (DOM-free, React-free) so the whole lifecycle is unit-testable. One instance
+ * per plugin activation; page-level lifecycle — nothing is persisted.
+ *
+ * Numbering: a per-session monotonic counter assigns each annotation its
+ * display number at creation (①②… rendered as plain digits). Numbers are
+ * never reused and never re-packed on delete — 删除不重排.
+ *
+ * State machine per annotation: 'active' (counts in the composer chip, rides
+ * the managed draft prefix) → 'sent' (the message it was attached to went
+ * out; badge stays on the message flow but the chip no longer counts it).
+ */
+export interface Annotation {
+    /** Store-unique identity (monotonic across sessions). */
+    readonly id: number;
+    /** Per-session display number assigned at creation; never reused. */
+    readonly number: number;
+    readonly sessionId: string;
+    /** `data-chat-anchor-key` of the owning message (re-anchor key). */
+    readonly anchorKey: string | undefined;
+    /** Truncated quote text (what the model and the chip see). */
+    readonly text: string;
+    /** Full selection text (re-anchor needle; untruncated). */
+    readonly anchorText: string;
+    /** 0-based ordinal of the quote's occurrence inside the anchor element. */
+    readonly occurrence: number;
+    /** User-written note; '' means 纯引用. */
+    readonly note: string;
+    readonly state: 'active' | 'sent';
+    readonly createdAt: number;
+}
+export interface AnnotationDraft {
+    readonly sessionId: string;
+    readonly anchorKey: string | undefined;
+    readonly text: string;
+    readonly anchorText: string;
+    readonly occurrence: number;
+    readonly note: string;
+}
+export interface AnnotationStore {
+    /** Monotonic version, referentially stable between mutations (uSES-ready). */
+    getSnapshot(): number;
+    subscribe(fn: () => void): () => void;
+    /** Create an active annotation; returns it (id/number assigned). */
+    add(draft: AnnotationDraft): Annotation;
+    setNote(id: number, note: string): void;
+    remove(id: number): void;
+    /** Flip every active annotation of the session to 'sent' (send edge). */
+    markSessionSent(sessionId: string): void;
+    get(id: number): Annotation | undefined;
+    /** All annotations of a session in creation order (active + sent). */
+    list(sessionId: string): readonly Annotation[];
+    listActive(sessionId: string): readonly Annotation[];
+    countActive(sessionId: string): number;
+    /** Sessions currently holding any annotation (draft-sync fan-out). */
+    sessions(): readonly string[];
+}
+export declare function createAnnotationStore(now?: () => number): AnnotationStore;

package/lib/types/client/annotate/overlay.d.ts

@@ -0,0 +1,27 @@
+import { Component } from 'react';
+import type { ReactNode } from 'react';
+import type { Context } from '../../context-types.ts';
+import type { AnnotationStore } from './model.ts';
+import type { SelectionController } from './selection.ts';
+interface OverlayProps {
+    readonly ctx: Context;
+    readonly store: AnnotationStore;
+    readonly controller: SelectionController;
+}
+/** Crash guard: a render failure must never take the host page down. */
+export declare class AnnotateErrorBoundary extends Component<{
+    children: ReactNode;
+}, {
+    failed: boolean;
+}> {
+    state: {
+        failed: boolean;
+    };
+    static getDerivedStateFromError(): {
+        failed: boolean;
+    };
+    componentDidCatch(error: unknown): void;
+    render(): ReactNode;
+}
+export declare function AnnotateOverlay(props: OverlayProps): ReactNode;
+export {};

package/lib/types/client/annotate/selection.d.ts

@@ -0,0 +1,49 @@
+/** One validated selection, ready for the toolbar. */
+export interface SelectionSnapshot {
+    /** Truncated quote (sent to the model / stored on the annotation). */
+    readonly text: string;
+    /** Full selection text (re-anchor needle). */
+    readonly anchorText: string;
+    /** `data-chat-anchor-key` of the owning message, when present. */
+    readonly anchorKey: string | undefined;
+    /** 0-based ordinal of this selection among identical texts in the anchor. */
+    readonly occurrence: number;
+    /** Bounding box for toolbar placement. */
+    readonly rect: {
+        readonly left: number;
+        readonly top: number;
+        readonly width: number;
+    };
+    /** A live clone of the selection range (badge anchor until re-render). */
+    readonly range: Range;
+    readonly sessionId: string;
+}
+export interface SelectionState {
+    readonly selection: SelectionSnapshot | null;
+}
+/** The assistant message node kind (v1 实测纠正值 — 勿引旧值 `assistant`). */
+export declare const ASSISTANT_KIND = "assistant-step";
+/** Pure validation of one candidate selection (unit-tested without DOM). */
+export declare function isEligibleSelection(input: {
+    readonly blank: boolean;
+    readonly sameMessage: boolean;
+    readonly kind: string;
+    readonly streaming: boolean;
+    readonly excluded: boolean;
+    readonly hasSession: boolean;
+}): boolean;
+/**
+ * The 0-based ordinal of the selection's text among its occurrences in the
+ * anchor element — the disambiguator for repeated phrases (re-anchor key).
+ */
+export declare function occurrenceOf(anchor: HTMLElement, range: Range, text: string): number;
+/** Capture and validate the current window selection, or null when invalid. */
+export declare function captureSelection(currentSessionId: string): SelectionSnapshot | null;
+export interface SelectionController {
+    getSnapshot(): SelectionState;
+    subscribe(fn: () => void): () => void;
+    clear(): void;
+    dispose(): void;
+}
+/** Create one selection controller (call once per plugin activation). */
+export declare function createSelectionController(getSessionId: () => string): SelectionController;

package/lib/types/client/bridge.d.ts

@@ -0,0 +1,19 @@
+/**
+ * In-plugin bridge between the annotate module (Workitem 02/03) and the
+ * sidechat module (Workitem 01). The sidechat module installs an
+ * implementation on activation; annotate's 「在侧边聊天中提问」 button calls
+ * it when present. Module-level singleton by design: exactly one sidechat
+ * module and one annotate module exist per activation.
+ */
+import type { SessionId } from '../context-types.ts';
+export interface SideChatBridge {
+    /**
+     * Open (or focus) a side chat forked from `sessionId`, seeding its composer
+     * draft with `draftText` (quoted selection + annotation). Returns false
+     * when no side chat could be opened (caller keeps its own flow).
+     */
+    askInSideChat(sessionId: SessionId, draftText: string): boolean;
+}
+export declare const sideChatBridge: {
+    current: SideChatBridge | null;
+};

package/lib/types/client/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Client half of dsh-sidenote: the side-chat tabs (Workitem 01) and the
+ * selection annotations (Workitem 02). Thin consumer of dsh-better-sidebar —
+ * it builds no panel chrome (portal/resize/collapse/persistence); the panel
+ * container is entirely better-sidebar's.
+ *
+ * Requires the `betterSidebar` service (hard peer dependency): inject keeps
+ * the plugin inactive until better-sidebar provides it.
+ */
+import type { Context } from '../context-types.ts';
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,77 @@
+/**
+ * dsh-sidenote 的双语层（zh/en），跟随 DSH 通用设置里的语言（`ctx.locale`，
+ * Host-backed locale.preference，实时切换）。模式照 better-sidebar
+ * `src/client/locales.ts`：attachLocale 挂服务，t() 读活动语言；
+ * 服务缺失（独立组合/测试）时回退浏览器语言。
+ */
+export declare const LOCALE_NS = "dsh-sidenote";
+/** 英文词典（key 的权威清单）。 */
+export declare const en: {
+    menuTitle: string;
+    tabBaseTitle: string;
+    codeCopy: string;
+    codeCopied: string;
+    forkErrorTitle: string;
+    forkErrorHint: string;
+    missingTitle: string;
+    missingDetail: string;
+    missingHint: string;
+    preparing: string;
+    historyFailed: string;
+    emptyTitle: string;
+    emptyText: string;
+    thinking: string;
+    writing: string;
+    stopped: string;
+    toolLabel: string;
+    failed: string;
+    running: string;
+    inputPlaceholder: string;
+    modelLabel: string;
+    modelFollowsMain: string;
+    stopReply: string;
+    stopReplyTitle: string;
+    send: string;
+    cmdDesc: string;
+    cmdNew: string;
+    cmdNewDetail: string;
+    cmdFocus: string;
+    cmdFocusDetail: string;
+    addToConversation: string;
+    askInSideChat: string;
+    toolbarAria: string;
+    notePlaceholder: string;
+    confirmTitle: string;
+    saveNoteAria: string;
+    sideNotePlaceholder: string;
+    sideNoteAria: string;
+    confirmAskAria: string;
+    openSideFailed: string;
+    deleteNote: string;
+    cancel: string;
+    save: string;
+    chipOne: string;
+    chipMany: string;
+    removeTitle: string;
+    removeAria: string;
+    noteLine: string;
+    noNote: string;
+};
+export type CopyKey = keyof typeof en;
+/** 中文词典（与 en 同 key）。 */
+export declare const zh: Record<CopyKey, string>;
+/** The DSH locale service face we consume (subset of LocaleRuntime). */
+export interface LocaleServiceLike {
+    getSnapshot(): {
+        active: string;
+    };
+    subscribe(fn: () => void): () => void;
+}
+/** Attach the DSH locale service (call once from the client apply). */
+export declare function attachLocale(service: LocaleServiceLike | undefined): void;
+/** Subscribe to locale switches (component re-render driver). */
+export declare function subscribeLocale(fn: () => void): () => void;
+/** Translate a copy key; `{name}` placeholders interpolate from `params`. */
+export declare function t(key: CopyKey, params?: Record<string, string | number>): string;
+/** 语言切换时驱动组件重渲（useSyncExternalStore 标准接法）。 */
+export declare function useLocaleTick(): void;

package/lib/types/client/sidechat/SideChatPanel.d.ts

@@ -0,0 +1,2 @@
+import type { TabComponentProps } from '../../context-types.ts';
+export declare function SideChatPanel(props: TabComponentProps): import("react").JSX.Element;

package/lib/types/client/sidechat/composer.d.ts

@@ -0,0 +1,26 @@
+import type { Context, SessionFace, SessionInput } from '../../context-types.ts';
+/**
+ * 解析 childId 会话的 input 草稿机；任何一步缺失/抛错返回 null
+ * （调用方走降级路径）。
+ */
+export declare function resolveSessionInput(ctx: Context, childId: string): SessionInput | null;
+/** 读草稿机的当前草稿（容错）。 */
+export declare function readInputDraft(input: SessionInput): string;
+/** composer 对外脸：machine 标记实际落点（true = input 机器，false = 自绘降级）。 */
+export interface Composer {
+    readonly machine: boolean;
+    readonly draft: string;
+    readonly sendError: string | null;
+    setDraft(text: string): void;
+    /** 拼接一段外部文本（桥接注入的引文草稿）。 */
+    appendDraft(text: string): void;
+    /** 发送当前草稿（空草稿 no-op）。 */
+    submit(): void;
+}
+/**
+ * 面板 composer hook。机器路径：草稿住在 input 机器的 store 里（随会话持久、
+ * 与主输入框同语义），submit 走机器事务（序列化/裁决/默认 sink 全在机器内）。
+ * 降级路径：草稿住本地 state，发送直连 session.prompt([...], 'queue')，
+ * 失败时回填草稿并报错。
+ */
+export declare function useComposer(ctx: Context, session: SessionFace | undefined, childId: string | undefined): Composer;

package/lib/types/client/sidechat/index.d.ts

@@ -0,0 +1,2 @@
+import type { Context } from '../../context-types.ts';
+export declare function registerSideChat(ctx: Context): void;

package/lib/types/client/sidechat/model.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 侧边聊天的纯逻辑层：Tab 编号标题、meta 序列化/解析容错、状态树遍历、
+ * 会话快照 → 消息流折叠、面板相位判定。全部无副作用，单测直接覆盖。
+ *
+ * 数据源事实（权威注释）：
+ * - SidebarState 真实形态是 splits/bottomSplits 两棵 split/leaf 树
+ *   （dsh-better-sidebar src/client/state.ts），leaf.tabs 持有 SidebarTab。
+ * - ConversationSnapshot.nodes 是 ConversationNode 联合（kind 判别），
+ *   partial/runningCalls 承载在途流式输出（dsh-client-runtime
+ *   lib/types/client/sessions/conversation.d.ts）。
+ */
+import type { ConversationSnapshot, Context, SidebarTab } from '../../context-types.ts';
+/** Tab 类型 id（better-sidebar 注册表键；带包前缀防冲突）。 */
+export declare const SIDE_TAB_TYPE = "dsh-sidenote:side";
+/** 多实例 Tab id：`side:<uuid>`（terminal/browser 的 createTab 铸 id 先例）。 */
+export declare function mintSideTabId(): string;
+/**
+ * 标题编号：首个「侧边」；并存时新 Tab「侧边 N」（N = 既有最大编号 + 1，
+ * 从标题解析）——关掉「侧边」再新建不会重名复用「侧边 2」。
+ * @param existingTitles - 创建时刻同会话侧边聊天 Tab 的标题集。
+ */
+export declare function sideTabTitle(existingTitles: readonly string[]): string;
+/** 侧边聊天寄存在 SidebarTab.meta 上的插件自有 JSON。 */
+export interface SideChatMeta {
+    /** fork 出的子会话 id；缺省 = 尚未 fork（刚创建）。 */
+    childId?: string;
+    /** fork 来源主会话 id（面板归属校验用；面板天然落在其 sidebar 状态里）。 */
+    parentSessionId?: string;
+    /** 桥接（WI-03 划选提问）写入的待注入草稿；面板应用后清除。 */
+    pendingDraft?: string;
+}
+/**
+ * 容错解析 tab.meta：布局持久化里的 meta 来自上一版本的自己，字段缺失或
+ * 类型漂移一律降级为缺省，绝不抛错（刷新恢复路径不许崩）。
+ */
+export declare function parseSideChatMeta(meta: unknown): SideChatMeta;
+/** 清除 meta.pendingDraft（其余字段原样保留）。 */
+export declare function clearPendingDraft(meta: SideChatMeta): SideChatMeta;
+/** 枚举侧栏状态（splits + bottomSplits 两棵树）里的全部 Tab。 */
+export declare function collectTabs(state: unknown): SidebarTab[];
+/** 枚举当前并存的侧边聊天 Tab（树顺序 = 打开顺序的近似）。 */
+export declare function collectSideTabs(state: unknown): SidebarTab[];
+/** 并存数（createTab 编号标题的输入）。 */
+export declare function countSideTabs(state: unknown): number;
+/**
+ * blank 着陆页会话没有已完成 turn，fork 必败（host 返回 fork-unavailable）
+ * ——+ 菜单与 /side 命令的 available 用它禁用入口；面板内错误态兜底。
+ * 摘要求知（列表未就绪）时放行，交给 fork 错误态。
+ */
+export declare function canForkFrom(ctx: Context, sessionId: string): boolean;
+/**
+ * 面板相位：
+ * - forking：无 childId，fork 编排进行中（或等待 effect 起跑）；
+ * - fork-error：fork/归档失败（blank 会话无已完成 turn 等）；
+ * - loading：有 childId，列表未就绪或 binding 尚未可解析；
+ * - missing：列表就绪后子会话不在列（会话已不存在）；
+ * - chat：binding 解析成功，正常聊天。
+ */
+export type PanelPhase = 'forking' | 'fork-error' | 'loading' | 'missing' | 'chat';
+export declare function phaseOf(input: {
+    childId: string | undefined;
+    forkError: string | null;
+    bound: boolean;
+    listPhase: 'pending' | 'ready' | undefined;
+    listed: boolean;
+}): PanelPhase;
+/** 注入草稿的拼接规则：空草稿直接落文本，否则换行追加（引文+问题的自然形态）。 */
+export declare function appendDraftText(draft: string, text: string): string;
+/** 面板渲染用的消息视图（自绘；工具卡片等复杂节点降级为简洁块）。 */
+export interface ChatMessage {
+    /** React key（节点 seq / 在途 callId 派生，稳定）。 */
+    key: string;
+    role: 'user' | 'assistant' | 'tool' | 'notice' | 'error';
+    /** markdown 正文（assistant）或纯文本（其他）。 */
+    text: string;
+    /** assistant 的思考内容（折叠渲染）；缺省 = 无。 */
+    reasoning?: string;
+    /** tool 角色的工具名。 */
+    toolName?: string;
+    /** tool 角色的失败标记。 */
+    isError?: boolean;
+    /** 流式中（partial / runningCalls）。 */
+    streaming?: boolean;
+    /** 被打断冻结的 assistant 输出（渲染「已停止」标记）。 */
+    interrupted?: boolean;
+}
+/** 工具结果正文截断上限（面板是窄栏，超长输出不撑爆 DOM）。 */
+export declare const TOOL_TEXT_LIMIT = 4000;
+export declare function truncateText(text: string, max: number): string;
+/** ContentBlock[] → 纯文本：text 块拼接；image 块降级占位；其余忽略。 */
+export declare function contentTextOf(content: unknown): string;
+/**
+ * 单个 ConversationNode → ChatMessage；返回 null = 面板不渲染
+ * （context 注入、未知面事件、已取消的重试等对读者无信息的节点）。
+ */
+export declare function nodeToMessage(node: unknown): ChatMessage | null;
+/**
+ * ConversationSnapshot → 渲染消息列表：终态节点 + 在途工具调用 + 流式部分。
+ * 快照缺省（未绑定）时为空列表。
+ */
+export declare function transcriptOf(snapshot: ConversationSnapshot | undefined | null): ChatMessage[];

package/lib/types/client/sidechat/open.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 「新建或聚焦一个侧边聊天 Tab」的共享编排：桥接（WI-03 划选提问
+ * askInSideChat）与 /side 斜杠命令共用。
+ *
+ * 聚焦策略：同一主会话并存多个时聚焦最后一个（最近打开的）。
+ * 草稿注入：目标 Tab 已 fork 且 input 机器可达 → 直接写机器草稿；
+ * 否则写 meta.pendingDraft 移交面板（面板在 composer 就绪后应用并清除）。
+ */
+import type { Context, SidebarTab } from '../../context-types.ts';
+/** 从最新快照读一个 Tab（meta 合并写入前的读取面；布局即注册表）。 */
+export declare function readTab(ctx: Context, tabId: string): SidebarTab | undefined;
+/**
+ * 为 sessionId 新建或聚焦一个侧边聊天 Tab；draftText 给出时写入其草稿。
+ * @returns false = 未能打开（调用方保持自己的流程）。
+ */
+export declare function openOrFocusSideChat(ctx: Context, sessionId: string, draftText?: string): boolean;

package/lib/types/client/sidechat/slash.d.ts

@@ -0,0 +1,12 @@
+/**
+ * /side 斜杠命令（spike 落点）：经 client 侧 `ctx.commandUi.register`
+ * （dsh-client-ui-commands 的 CommandContribution，ui 形态 popupSelect）
+ * 注册。popupSelect 是该注册面唯一的 UI 形态 —— 菜单行被选中后弹一个
+ * 选项壳，选项 = 新建 + 当前会话已并存的侧边聊天（聚焦）。
+ *
+ * 服务经 ctx.get 惰性解析（commandUi 不在 inject 清单里）：服务缺失、
+ * 注册抛错（如与 host 命令撞名）都降级为「只有 Tab 入口」，绝不影响面板。
+ */
+import type { Context } from '../../context-types.ts';
+/** 注册 /side 命令；不可行时静默降级（返回 undefined）。 */
+export declare function registerSideCommand(ctx: Context): void;