dsh-sidenote 0.1.0

package/lib/types/context-types.d.ts

@@ -0,0 +1,335 @@
+/**
+ * Structural mirror of the runtime surfaces dsh-sidenote consumes.
+ *
+ * Third-party plugins resolve outside the DSH monorepo's single cordis
+ * instance, so upstream `declare module 'cordis'` augmentations never reach
+ * our `Context` type. We mirror the runtime shapes here instead — drift from
+ * upstream is contained to this file. Each section names its authority (the
+ * upstream .d.ts it mirrors); extend sections as features need more surface,
+ * keeping the mirror honest (only declare what actually exists at runtime).
+ *
+ * Authorities:
+ * - betterSidebar: dsh-better-sidebar `src/client/service.ts` (+ docs/external-plugin-guide.md)
+ * - sessions/workspaces: `@deepseek-ai/dsh-client-runtime` lib/types/client/contract/{sessions,session,workspaces}.d.ts
+ *   (local checkout: <dsh install>/node_modules/@deepseek-ai/dsh-client-runtime/lib/types/client/...)
+ * - conversation input / slots: `@deepseek-ai/dsh-client-ui-conversation` / `dsh-client-ui-slots` type surfaces
+ */
+import type { Context as CordisContext } from 'cordis';
+import type { ReactNode } from 'react';
+export type SessionId = string;
+/** Minimal observable snapshot shape (identity-stable, useSyncExternalStore-ready). */
+export interface ObservableSnapshot<T> {
+    getSnapshot(): T;
+    subscribe(listener: () => void): () => void;
+}
+export interface SessionScope {
+    sessionId: SessionId;
+    cwd?: string;
+}
+/** A live sidebar tab instance. `meta` is plugin-owned JSON persisted with the layout. */
+export interface SidebarTab {
+    id: string;
+    type: string;
+    title: string;
+    path?: string;
+    meta?: unknown;
+}
+/**
+ * 侧栏状态 = splits/bottomSplits 两棵 split/leaf 树（权威：dsh-better-sidebar
+ * src/client/state.ts）：leaf 持有 tabs；split 递归分栏。
+ */
+export interface SidebarLeafNode {
+    kind: 'leaf';
+    id: string;
+    tabs: SidebarTab[];
+    active: string | null;
+}
+export interface SidebarSplitNode {
+    kind: 'split';
+    id: string;
+    dir: 'row' | 'col';
+    sizes: number[];
+    children: SidebarTreeNode[];
+}
+export type SidebarTreeNode = SidebarLeafNode | SidebarSplitNode;
+export interface SidebarState {
+    /** 右侧面板的 split 树。 */
+    splits: SidebarTreeNode;
+    /** 底部面板的 split 树。 */
+    bottomSplits: SidebarTreeNode;
+}
+export interface SidebarSnapshot {
+    sessionId?: SessionId;
+    state?: SidebarState;
+    prefs?: Record<string, unknown>;
+}
+/** better-sidebar's store handle (external tabs treat it as opaque). */
+export type SidebarStore = unknown;
+export interface TabComponentProps {
+    ctx: Context;
+    store: SidebarStore;
+    scope: SessionScope;
+    tab: SidebarTab;
+    visible: boolean;
+}
+export interface TabDescriptor {
+    id: string;
+    title: string | (() => string);
+    icon?: ReactNode | ((size: number) => ReactNode);
+    order?: number;
+    hidden?: boolean;
+    available?: (ctx: Context, scope: SessionScope, state: SidebarState) => boolean;
+    single?: boolean;
+    dedupeKey?: (tab: SidebarTab) => string | undefined;
+    createTab?: (state: SidebarState) => {
+        tab: SidebarTab;
+        patch?: Partial<SidebarState>;
+    } | null;
+    badge?: (ctx: Context, scope: SessionScope, state: SidebarState) => string | number | null | undefined;
+    onOpen?: (tab: SidebarTab, scope: SessionScope) => void;
+    onActivate?: (tab: SidebarTab, scope: SessionScope) => void;
+    onClose?: (tab: SidebarTab, scope: SessionScope) => void;
+    component: (props: TabComponentProps) => ReactNode;
+}
+export interface OpenTabSeed {
+    type: string;
+    title?: string;
+    path?: string;
+    id?: string;
+    url?: string;
+    meta?: unknown;
+}
+export interface BetterSidebarService {
+    readonly version: string;
+    readonly features: readonly string[];
+    registerTab(descriptor: TabDescriptor): () => void;
+    openTab(seed: OpenTabSeed, scope?: SessionScope): void;
+    closeTab(tabId: string, scope?: SessionScope): void;
+    activateTab(tabId: string, scope?: SessionScope): void;
+    updateTab(tabId: string, patch: {
+        title?: string;
+        path?: string;
+        meta?: unknown;
+    }): void;
+    getTab(id: string): TabDescriptor | undefined;
+    getTabs(): readonly TabDescriptor[];
+    isTabEnabled(id: string): boolean;
+    getSnapshot(): SidebarSnapshot;
+    subscribeState(listener: () => void): () => void;
+    subscribe(listener: () => void): () => void;
+}
+export interface SessionListSnapshot {
+    /** Currently selected session id. */
+    current?: SessionId;
+    [key: string]: unknown;
+}
+export interface ForkOptions {
+    sessionId: SessionId;
+    atSeq?: number;
+    increaseTitle?: boolean;
+}
+/** Text plus browser-owned parts; text covers everything we send today. */
+export type PromptContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * Conversation read model (subset). Extend from
+ * dsh-client-runtime `lib/types/client/sessions/conversation.d.ts` as needed —
+ * the real shape has chat/nodes/partial/queue/running and more.
+ */
+export interface ConversationSnapshot {
+    sessionId: SessionId;
+    nodes: readonly unknown[];
+    running: boolean;
+    [key: string]: unknown;
+}
+export interface ISession {
+    readonly sessionId: SessionId;
+    prompt(content: PromptContentPart[], mode: 'queue' | 'steer'): Promise<unknown>;
+    cancel(): Promise<unknown>;
+    rename(title: string): Promise<unknown>;
+    loadOlder(): Promise<void>;
+    command(line: string): Promise<unknown>;
+}
+export type SessionFace = ISession & ObservableSnapshot<ConversationSnapshot>;
+export interface SessionBinding {
+    session: SessionFace;
+}
+export interface SessionsService {
+    list: ObservableSnapshot<SessionListSnapshot>;
+    fork(opts: ForkOptions): Promise<SessionId>;
+    binding(id: SessionId): SessionBinding | undefined;
+    scope(id: SessionId): Context | undefined;
+    open(id: SessionId): void;
+}
+export interface WorkspacesService {
+    archiveSession(sessionId: SessionId): Promise<void>;
+}
+export interface SessionInput {
+    setDraft(text: string): void;
+    submit(mode?: string): void;
+    notify(level: string, text: string): void;
+}
+export interface ConversationService {
+    input: {
+        for(ctx: Context): SessionInput | undefined;
+    };
+}
+/** 会话的当前模型选择（`session.models` 的 current 字段）。 */
+export interface ModelSelection {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+export interface SessionModelsResult {
+    current: ModelSelection;
+    routable: boolean;
+    groups: readonly unknown[];
+}
+export interface RpcEnvelope<T> {
+    result: {
+        ok: true;
+        value: T;
+    } | {
+        ok: false;
+        error: {
+            message?: string;
+        };
+    };
+}
+export interface ConnectionSessionsApi {
+    models(payload: {
+        sessionId: SessionId;
+    }): Promise<RpcEnvelope<SessionModelsResult>>;
+    selectModel(payload: {
+        sessionId: SessionId;
+        provider: string;
+        model: string;
+        reasoningEffort?: string;
+    }): Promise<RpcEnvelope<{
+        selected: ModelSelection;
+    }>>;
+}
+export interface ConnectionService {
+    api: {
+        sessions: ConnectionSessionsApi;
+    };
+}
+export interface LocaleService {
+    getSnapshot(): {
+        active: string;
+    };
+    subscribe(fn: () => void): () => void;
+}
+export interface Context extends CordisContext {
+    betterSidebar: BetterSidebarService;
+    sessions: SessionsService;
+    workspaces: WorkspacesService;
+    connection: ConnectionService;
+    locale: LocaleService;
+}
+/**
+ * 会话列表快照补全（权威：dsh-client-runtime
+ * lib/types/client/sessions/service.d.ts 的 SessionListState）：
+ * phase 标「首次成功拉取」就绪边；byId 含已归档行（归档过滤在
+ * workspace UI 层，store 本身携带全部行）。
+ */
+export interface SessionListSnapshot {
+    phase?: 'pending' | 'ready';
+    byId?: Record<string, {
+        blank?: boolean;
+    } | undefined>;
+}
+/**
+ * 会话快照补全（权威：dsh-client-runtime sessions/conversation.d.ts）：
+ * openState 是历史窗口生命周期（cold = 未开窗口）；partial/runningCalls
+ * 承载在途流式输出。面板折叠函数对三者全部容错（缺省按空处理）。
+ */
+export interface ConversationSnapshot {
+    openState?: 'cold' | 'loading' | 'open' | 'error';
+    partial?: unknown;
+    runningCalls?: readonly unknown[];
+}
+/**
+ * input 草稿机的 state store（权威：dsh-client-ui-conversation
+ * input/contract.d.ts 的 SessionInput.state）——完整声明见下方 annotate 扩展节
+ * （接口合并；draft 字段两侧都依赖）。
+ */
+export interface Context {
+    /**
+     * 惰性非追踪服务读（运行时事实：context proxy 的 reflect.get）——
+     * 读取不在 inject 清单里的服务（conversation / commandUi）的唯一通道。
+     * （`ctx.effect` 无需镜像：公开 cordis 包的 fiber.d.ts 已通过接口合并
+     * 提供 `effect(execute, label?)`。）
+     */
+    get(name: string): unknown;
+}
+/** Registration options subset passed to `ctx.slots.register` (same shape better-sidebar mirrors). */
+export interface SlotRegisterOptions {
+    name: string;
+    key?: string;
+    id?: string;
+    order?: number;
+    label?: string | (() => string);
+    select?: (owner: unknown) => unknown;
+    priority?: number;
+    locale?: string;
+    registrant?: string;
+    inject?: (...args: any[]) => Record<string, unknown>;
+    children?: Record<string, unknown>;
+}
+/** The client slots service face (register returns the disposer). */
+export interface SlotsService {
+    register(options: SlotRegisterOptions, component: unknown): () => void;
+    /** Run a callback for each declaration lifetime of a slot (no-op while undeclared). */
+    inject(key: string, callback: () => (() => void) | void): () => void;
+}
+/** Published composer input state (subset of the real InputState). */
+export interface InputStateSnapshot {
+    readonly draft: string;
+    readonly phase: string;
+    readonly queue?: readonly unknown[];
+}
+/** Session input snapshot as exposed on `InputZone.input`. */
+export interface ConversationSnapshotLite {
+    sessionId: SessionId;
+    running: boolean;
+}
+/** Owner share of the `conversation.input.dock` slot (point-in-time snapshots). */
+export interface InputZone {
+    readonly session: ConversationSnapshotLite;
+    readonly input: InputStateSnapshot;
+}
+/**
+ * U+FFFC reference-chip insert (spike result: NOT used — serialization of the
+ * chip 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 submit. Mirrored
+ * here only to document the probe target).
+ */
+export interface ReferenceInsert {
+    readonly source: string;
+    readonly ref: string;
+    readonly label: string;
+    readonly clipboardText: string;
+}
+export interface TokenSpan {
+    readonly start: number;
+    readonly end: number;
+    readonly draftRev: number;
+}
+export interface Context {
+    /** The slot registry (provided by dsh-client-runtime, mounted before this plugin). */
+    slots: SlotsService;
+}
+/** SessionInput completion for annotate: the live state store + the (unused) chip insert face. */
+export interface SessionInput {
+    /** Input state store (draft reads + subscribe for the send-edge watch). */
+    readonly state: ObservableSnapshot<InputStateSnapshot>;
+    /** Spike-only mirror; see {@link ReferenceInsert}. Not called by annotate. */
+    insertReference(ref: ReferenceInsert, span: TokenSpan): boolean;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * dsh-sidenote host half: currently empty by design — every feature is
+ * client-side (sessions RPC + the betterSidebar service). A host half would
+ * only appear for capabilities the client cannot reach (none today).
+ */
+import type { Context } from './context-types.ts';
+/** Plugin identity for cordis.yml rows. */
+export declare const name = "dsh-sidenote";
+export declare function apply(_ctx: Context): void;

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "dsh-sidenote",
+  "version": "0.1.0",
+  "description": "DSH web plugin: Codex-style side chat (fork the current session into a persistent side panel) + selection annotations with numbered badges and a composer chip. A thin consumer of dsh-better-sidebar. / Codex 风格侧边聊天 + 划选注释的 DSH 插件。",
+  "type": "module",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "cordis": "^4.0.0-rc.7",
+    "dsh-better-sidebar": "^0.12.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "cordis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "@types/node": "^24.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.1",
+    "cordis": "^4.0.0-rc.7",
+    "lightningcss": "^1.32.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.8",
+    "@playwright/test": "^1.50.0"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "dsh",
+    "deepseek-harness",
+    "dsh-better-sidebar",
+    "side-chat",
+    "annotation",
+    "ai-coding",
+    "deepseek"
+  ],
+  "homepage": "https://github.com/g-yixuan/dsh-sidenote#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/g-yixuan/dsh-sidenote.git"
+  },
+  "bugs": "https://github.com/g-yixuan/dsh-sidenote/issues",
+  "author": "gyixuan",
+  "scripts": {
+    "build": "node -e \"fs.rmSync('lib',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsdown",
+    "typecheck": "tsc --noEmit",
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "test:mount": "bash scripts/e2e-mount.sh",
+    "pretest:mount": "pnpm build && pnpm pack"
+  }
+}

package/src/client/annotate/anchor.ts

@@ -0,0 +1,158 @@
+/**
+ * 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
+}
+
+/** Find the message element for an anchor key (connected DOM only). */
+function findAnchorElement(anchorKey: string): HTMLElement | null {
+  try {
+    const el = document.querySelector<HTMLElement>(
+      `[data-chat-anchor-key="${CSS.escape(anchorKey)}"]`,
+    )
+    return el !== null && el.isConnected ? el : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Rebuild a range covering the `occurrence`-th appearance of `text` inside
+ * `root`'s text nodes. Falls back to the LAST occurrence when the ordinal is
+ * out of range（消息内容变短时，最后一次出现更可能是原选区）.
+ */
+function rangeOfOccurrence(root: HTMLElement, text: string, occurrence: number): Range | null {
+  if (text === '') return null
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT)
+  const haystack = root.textContent ?? ''
+  let start = -1
+  let at = haystack.indexOf(text)
+  let seen = 0
+  while (at !== -1) {
+    if (seen === occurrence) { start = at; break }
+    seen += 1
+    at = haystack.indexOf(text, at + text.length)
+  }
+  if (start === -1 && occurrence > 0) {
+    // Ordinal out of range — fall back to the last known occurrence.
+    start = haystack.lastIndexOf(text)
+  }
+  if (start === -1) return null
+  const end = start + text.length
+  let offset = 0
+  let startNode: Text | null = null
+  let startOffset = 0
+  let endNode: Text | null = null
+  let endOffset = 0
+  for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+    const length = (node.textContent ?? '').length
+    const next = offset + length
+    if (startNode === null && start < next) {
+      startNode = node as Text
+      startOffset = start - offset
+    }
+    if (startNode !== null && end <= next) {
+      endNode = node as Text
+      endOffset = end - offset
+      break
+    }
+    offset = next
+  }
+  if (startNode === null || endNode === null) return null
+  const range = document.createRange()
+  range.setStart(startNode, startOffset)
+  range.setEnd(endNode, endOffset)
+  return range
+}
+
+/**
+ * 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 function resolveRange(annotation: Annotation, cache: Map<number, Range>): Range | null {
+  try {
+    const cached = cache.get(annotation.id)
+    if (cached !== undefined && cached.startContainer.isConnected) return cached
+    cache.delete(annotation.id)
+    if (annotation.anchorKey === undefined || annotation.anchorText === '') return null
+    const anchor = findAnchorElement(annotation.anchorKey)
+    if (anchor === null) return null
+    const range = rangeOfOccurrence(anchor, annotation.anchorText, annotation.occurrence)
+    if (range !== null) cache.set(annotation.id, range)
+    return range
+  } catch {
+    return 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 function badgeAnchorOf(range: Range): BadgeAnchor | null {
+  try {
+    const rects = range.getClientRects()
+    if (rects.length === 0) return null
+    let right = -Infinity
+    for (const rect of rects) right = Math.max(right, rect.right)
+    const first = rects[0]
+    if (first === undefined || !Number.isFinite(right)) return null
+    return { right, centerY: first.top + first.height / 2 }
+  } catch {
+    return null
+  }
+}
+
+/** Client rects of a range for the active-highlight overlay (empty on failure). */
+export function highlightRectsOf(range: Range): readonly { left: number; top: number; width: number; height: number }[] {
+  try {
+    const out: { left: number; top: number; width: number; height: number }[] = []
+    for (const rect of range.getClientRects()) {
+      if (rect.width <= 0 || rect.height <= 0) continue
+      out.push({ left: rect.left, top: rect.top, width: rect.width, height: rect.height })
+    }
+    return out
+  } catch {
+    return []
+  }
+}
+
+/** 角标碰撞半径（px）：同点位的角标必须错开才可点击。 */
+export const BADGE_COLLISION_RADIUS = 18
+/** 碰撞时向下错开的步长（px，大于角标直径）。 */
+export const BADGE_SPREAD_STEP = 24
+
+/**
+ * 角标落点错开：与已放置角标（|Δx|、|Δy| 均小于碰撞半径）冲突时按
+ * BADGE_SPREAD_STEP 逐级下移——同一选区/相邻行的多个注释角标不再叠罗汉
+ * （叠放时上层角标拦截下层角标的点击）。
+ */
+export function spreadBadgePoint(
+  point: { x: number; y: number },
+  placed: readonly { x: number; y: number }[],
+): { x: number; y: number } {
+  let out = point
+  for (let guard = 0; guard < 50; guard++) {
+    const collides = placed.some(p => Math.abs(p.x - out.x) < BADGE_COLLISION_RADIUS && Math.abs(p.y - out.y) < BADGE_COLLISION_RADIUS)
+    if (!collides) return out
+    out = { x: out.x, y: out.y + BADGE_SPREAD_STEP }
+  }
+  return out
+}