dsh-sidenote 0.1.0

package/src/client/annotate/selection.ts

@@ -0,0 +1,203 @@
+/**
+ * Selection capture layer (Workitem 02): document-level listeners validate
+ * the live selection and publish the latest valid one to the floating
+ * toolbar through a small external-store controller. Mirrors the
+ * production-proven dsh-sidebar-qa contract, narrowed to assistant messages:
+ *
+ * - both selection endpoints must sit in the SAME `[data-chat-flow-kind=
+ *   "assistant-step"]` message node (跨消息划选不弹);
+ * - `[data-streaming]` messages (still streaming) are excluded;
+ * - `[data-dsh-better-sidebar]` and our own `[data-dsh-sidenote]` DOM are
+ *   excluded (与侧边栏 viewer 浮层互斥);
+ * - the text must be non-blank; over-length selections are admitted with the
+ *   quote truncated (见 format.ts), never rejected.
+ *
+ * These are DSH-internal DOM attributes rather than a public contract — an
+ * upstream redesign silently degrades the feature (no popup), never crashes.
+ */
+import { truncateQuote } from './format.ts'
+
+/** 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 const ASSISTANT_KIND = 'assistant-step'
+
+/** Selector roots our UI must never react to (sidebar viewer + our own root). */
+const EXCLUDED_ROOTS = '[data-dsh-better-sidebar], [data-dsh-sidenote]'
+
+/** Pure validation of one candidate selection (unit-tested without DOM). */
+export function isEligibleSelection(input: {
+  readonly blank: boolean
+  readonly sameMessage: boolean
+  readonly kind: string
+  readonly streaming: boolean
+  readonly excluded: boolean
+  readonly hasSession: boolean
+}): boolean {
+  return !input.blank
+    && input.sameMessage
+    && input.kind === ASSISTANT_KIND
+    && !input.streaming
+    && !input.excluded
+    && input.hasSession
+}
+
+/** Resolve the assistant message element owning a DOM node (text nodes → parent). */
+function messageOf(node: Node): HTMLElement | null {
+  const element = node.nodeType === Node.TEXT_NODE ? node.parentElement : (node as Element | null)
+  if (element === null || typeof element.closest !== 'function') return null
+  return element.closest<HTMLElement>(`[data-chat-flow-kind="${ASSISTANT_KIND}"]`)
+}
+
+/** Whether the message is still streaming (unfinished). */
+function isStreaming(message: HTMLElement): boolean {
+  return message.hasAttribute('data-streaming') || message.querySelector('[data-streaming]') !== null
+}
+
+/**
+ * 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 function occurrenceOf(anchor: HTMLElement, range: Range, text: string): number {
+  try {
+    const pre = document.createRange()
+    pre.selectNodeContents(anchor)
+    pre.setEnd(range.startContainer, range.startOffset)
+    const before = pre.toString()
+    let occurrence = 0
+    let at = before.indexOf(text)
+    while (at !== -1) {
+      occurrence += 1
+      at = before.indexOf(text, at + text.length)
+    }
+    return occurrence
+  } catch {
+    return 0
+  }
+}
+
+/** Capture and validate the current window selection, or null when invalid. */
+export function captureSelection(currentSessionId: string): SelectionSnapshot | null {
+  const sel = window.getSelection()
+  if (sel === null || sel.isCollapsed || sel.rangeCount === 0) return null
+  const anchorText = sel.toString()
+  const range = sel.getRangeAt(0)
+  const startMessage = messageOf(range.startContainer)
+  const endMessage = messageOf(range.endContainer)
+  const message = startMessage
+  const anchor = message?.closest<HTMLElement>('[data-chat-anchor-key]') ?? null
+  const eligible = isEligibleSelection({
+    blank: anchorText.trim() === '',
+    sameMessage: message !== null && message === endMessage,
+    kind: message?.dataset.chatFlowKind ?? '',
+    streaming: message !== null && isStreaming(message),
+    excluded: anchor !== null
+      ? anchor.closest(EXCLUDED_ROOTS) !== null
+      : message?.closest(EXCLUDED_ROOTS) !== null,
+    hasSession: currentSessionId !== '',
+  })
+  if (!eligible || message === null) return null
+  const rect = range.getBoundingClientRect()
+  return {
+    text: truncateQuote(anchorText),
+    anchorText,
+    anchorKey: anchor?.dataset.chatAnchorKey,
+    occurrence: anchor === null ? 0 : occurrenceOf(anchor, range, anchorText),
+    rect: { left: rect.left, top: rect.top, width: rect.width },
+    range: range.cloneRange(),
+    sessionId: currentSessionId,
+  }
+}
+
+export interface SelectionController {
+  getSnapshot(): SelectionState
+  subscribe(fn: () => void): () => void
+  clear(): void
+  dispose(): void
+}
+
+/** Debounce for selectionchange (ms). */
+const DEBOUNCE_MS = 200
+
+/** Create one selection controller (call once per plugin activation). */
+export function createSelectionController(getSessionId: () => string): SelectionController {
+  let selection: SelectionSnapshot | null = null
+  const listeners = new Set<() => void>()
+  let debounceTimer: number | undefined
+
+  // useSyncExternalStore requires a STABLE snapshot reference between
+  // notifications — a fresh object each call would loop React.
+  let state: SelectionState = { selection: null }
+
+  const notify = (): void => {
+    state = { selection }
+    for (const fn of [...listeners]) fn()
+  }
+
+  const recompute = (): void => {
+    let next: SelectionSnapshot | null = null
+    try {
+      next = captureSelection(getSessionId())
+    } catch {
+      next = null
+    }
+    const changed = (selection === null) !== (next === null)
+      || (selection !== null && next !== null && (
+        selection.anchorText !== next.anchorText
+        || selection.anchorKey !== next.anchorKey
+        || selection.sessionId !== next.sessionId
+        || selection.rect.top !== next.rect.top
+        || selection.rect.left !== next.rect.left
+        || selection.rect.width !== next.rect.width
+      ))
+    if (!changed) return
+    selection = next
+    notify()
+  }
+
+  const onSelectionChange = (): void => {
+    if (debounceTimer !== undefined) window.clearTimeout(debounceTimer)
+    debounceTimer = window.setTimeout(recompute, DEBOUNCE_MS)
+  }
+
+  document.addEventListener('selectionchange', onSelectionChange)
+  document.addEventListener('mouseup', recompute)
+  document.addEventListener('keyup', onSelectionChange)
+
+  return {
+    getSnapshot: () => state,
+    subscribe(fn: () => void): () => void {
+      listeners.add(fn)
+      return () => { listeners.delete(fn) }
+    },
+    clear(): void {
+      selection = null
+      notify()
+    },
+    dispose(): void {
+      document.removeEventListener('selectionchange', onSelectionChange)
+      document.removeEventListener('mouseup', recompute)
+      document.removeEventListener('keyup', onSelectionChange)
+      if (debounceTimer !== undefined) window.clearTimeout(debounceTimer)
+    },
+  }
+}

package/src/client/bridge.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 const sideChatBridge: { current: SideChatBridge | null } = { current: null }

package/src/client/index.tsx

@@ -0,0 +1,22 @@
+/**
+ * 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'
+import { attachLocale, type LocaleServiceLike } from './locales.ts'
+import { registerSideChat } from './sidechat/index.tsx'
+import { registerAnnotations } from './annotate/index.tsx'
+
+export const inject = ['betterSidebar', 'sessions', 'workspaces', 'slots', 'connection', 'locale']
+
+export function apply(ctx: Context): void {
+  // 跟随 DSH 通用设置里的语言（locale.preference，Host-backed，实时切换）。
+  attachLocale(ctx.locale as LocaleServiceLike | undefined)
+  registerSideChat(ctx)
+  registerAnnotations(ctx)
+}

package/src/client/locales.ts

@@ -0,0 +1,175 @@
+import { useSyncExternalStore } from 'react'
+
+/**
+ * dsh-sidenote 的双语层（zh/en），跟随 DSH 通用设置里的语言（`ctx.locale`，
+ * Host-backed locale.preference，实时切换）。模式照 better-sidebar
+ * `src/client/locales.ts`：attachLocale 挂服务，t() 读活动语言；
+ * 服务缺失（独立组合/测试）时回退浏览器语言。
+ */
+
+export const LOCALE_NS = 'dsh-sidenote'
+
+/** 英文词典（key 的权威清单）。 */
+export const en = {
+  menuTitle: 'Side chat',
+  tabBaseTitle: 'Side',
+
+  // SideChatPanel
+  codeCopy: 'Copy',
+  codeCopied: 'Copied',
+  forkErrorTitle: "Couldn't create the side chat",
+  forkErrorHint: 'The main session needs at least one completed turn to fork from. Close this tab with the × on the tab.',
+  missingTitle: 'Session no longer exists',
+  missingDetail: "This side chat's session was removed and can't be restored.",
+  missingHint: 'Close this tab with the × on the tab.',
+  preparing: 'Preparing the side chat…',
+  historyFailed: 'Failed to load the session history. Close and reopen this tab.',
+  emptyTitle: 'Side chat',
+  emptyText: 'Forked from the current session and evolves independently. Closing the tab removes it.',
+  thinking: 'Thinking',
+  writing: 'Writing…',
+  stopped: 'Stopped',
+  toolLabel: 'Tool',
+  failed: 'failed',
+  running: 'running…',
+  inputPlaceholder: 'Message… (Enter to send, Shift+Enter for a newline)',
+  modelLabel: 'Model: {name}',
+  modelFollowsMain: 'follows main session',
+  stopReply: 'Stop',
+  stopReplyTitle: 'Stop the current reply',
+  send: 'Send',
+
+  // /side command
+  cmdDesc: 'Open a side chat (forked from the current session)',
+  cmdNew: 'New side chat',
+  cmdNewDetail: 'Forked from the current session; evolves independently',
+  cmdFocus: 'Focus "{title}"',
+  cmdFocusDetail: 'Existing side chat',
+
+  // annotate overlay
+  addToConversation: 'Add to conversation',
+  askInSideChat: 'Ask in side chat',
+  toolbarAria: 'Selection annotations',
+  notePlaceholder: 'Add a note (optional)…',
+  confirmTitle: 'Confirm',
+  saveNoteAria: 'Save note',
+  sideNotePlaceholder: 'Add a note for the side chat (optional)…',
+  sideNoteAria: 'Side chat note',
+  confirmAskAria: 'Confirm and ask',
+  openSideFailed: "Couldn't open the side chat. Try again.",
+  deleteNote: 'Delete annotation',
+  cancel: 'Cancel',
+  save: 'Save',
+
+  // chip
+  chipOne: '1 annotation',
+  chipMany: '{n} annotations',
+  removeTitle: 'Remove annotation',
+  removeAria: 'Remove annotation {n}',
+
+  // model-facing quote format
+  noteLine: 'Note: {note}',
+  noNote: '(no note)',
+}
+
+export type CopyKey = keyof typeof en
+
+/** 中文词典（与 en 同 key）。 */
+export const zh: Record<CopyKey, string> = {
+  menuTitle: '侧边聊天',
+  tabBaseTitle: '侧边',
+
+  codeCopy: '复制',
+  codeCopied: '已复制',
+  forkErrorTitle: '无法创建侧边聊天',
+  forkErrorHint: '主会话需要至少一轮已完成的对话才能 fork。点击标签上的 × 可关闭此标签页。',
+  missingTitle: '会话已不存在',
+  missingDetail: '此侧边聊天的会话已被移除，无法恢复。',
+  missingHint: '点击标签上的 × 关闭此标签页。',
+  preparing: '正在准备侧边聊天…',
+  historyFailed: '会话历史加载失败，可关闭后重新打开此标签页。',
+  emptyTitle: '侧边聊天',
+  emptyText: '侧边聊天从当前会话 fork，独立演进；关闭标签页后消失。',
+  thinking: '思考过程',
+  writing: '正在输出…',
+  stopped: '已停止',
+  toolLabel: '工具',
+  failed: '失败',
+  running: '执行中…',
+  inputPlaceholder: '输入消息…（Enter 发送，Shift+Enter 换行）',
+  modelLabel: '模型：{name}',
+  modelFollowsMain: '跟随主会话',
+  stopReply: '停止',
+  stopReplyTitle: '停止当前回复',
+  send: '发送',
+
+  cmdDesc: '打开侧边聊天（从当前会话 fork）',
+  cmdNew: '新建侧边聊天',
+  cmdNewDetail: '从当前会话 fork，独立演进',
+  cmdFocus: '聚焦「{title}」',
+  cmdFocusDetail: '已存在的侧边聊天',
+
+  addToConversation: '添加到对话',
+  askInSideChat: '在侧边聊天中提问',
+  toolbarAria: '划选注释',
+  notePlaceholder: '这里可以写自己的注解…',
+  confirmTitle: '确认',
+  saveNoteAria: '确认注解',
+  sideNotePlaceholder: '给侧边聊天写个注解（可空）…',
+  sideNoteAria: '侧边聊天注解',
+  confirmAskAria: '确认并提问',
+  openSideFailed: '打开侧边聊天失败，请重试',
+  deleteNote: '删除注释',
+  cancel: '取消',
+  save: '保存',
+
+  chipOne: '1 条注释',
+  chipMany: '{n} 条注释',
+  removeTitle: '移除注释',
+  removeAria: '移除注释 {n}',
+
+  noteLine: '注解：{note}',
+  noNote: '（无注解）',
+}
+
+/** The DSH locale service face we consume (subset of LocaleRuntime). */
+export interface LocaleServiceLike {
+  getSnapshot(): { active: string }
+  subscribe(fn: () => void): () => void
+}
+
+let localeService: LocaleServiceLike | undefined
+
+/** Attach the DSH locale service (call once from the client apply). */
+export function attachLocale(service: LocaleServiceLike | undefined): void {
+  localeService = service
+}
+
+/** Subscribe to locale switches (component re-render driver). */
+export function subscribeLocale(fn: () => void): () => void {
+  return localeService?.subscribe(fn) ?? (() => {})
+}
+
+/** The active locale id：DSH 语言设置优先，缺失时回退浏览器语言。 */
+function activeLocale(): string {
+  return localeService?.getSnapshot().active
+    ?? (typeof navigator !== 'undefined' ? navigator.language : '')
+    ?? 'en'
+}
+
+/** Translate a copy key; `{name}` placeholders interpolate from `params`. */
+export function t(key: CopyKey, params?: Record<string, string | number>): string {
+  const dict = activeLocale().toLowerCase().startsWith('zh') ? zh : en
+  let text = dict[key]
+  if (params !== undefined) {
+    for (const [name, value] of Object.entries(params)) {
+      text = text.replaceAll(`{${name}}`, String(value))
+    }
+  }
+  return text
+}
+
+/** 语言切换时驱动组件重渲（useSyncExternalStore 标准接法）。 */
+export function useLocaleTick(): void {
+  useSyncExternalStore(subscribeLocale, () => localeService?.getSnapshot().active ?? 'en')
+}