dsh-sidenote 0.1.0

package/src/client/annotate/annotate.module.css

@@ -0,0 +1,301 @@
+/* Workitem 02 — 划选注释 overlay styles.
+   z-index 纪律：全部固定 50 — 高于正文与 better-sidebar 面板 (40)，低于 DSH
+   浮层栈 (100+)。颜色除品牌蓝角标外一律消费 DSH 令牌（皮肤跟随），缺省回退。 */
+
+.toolbar {
+  position: fixed;
+  transform: translate(-50%, -100%);
+  z-index: 50;
+  display: flex;
+  align-items: stretch;
+  background: var(--dsw-alias-bg-layer-1, #ffffff);
+  border: 1px solid var(--dsw-alias-border-l1, rgba(0, 0, 0, 0.08));
+  border-radius: 10px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.12);
+  overflow: hidden;
+  user-select: none;
+}
+
+.toolbarButton {
+  appearance: none;
+  border: none;
+  background: transparent;
+  color: var(--dsw-alias-label-primary, #1f2329);
+  font-size: 13px;
+  line-height: 20px;
+  padding: 7px 12px;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.toolbarButton + .toolbarButton {
+  border-left: 1px solid var(--dsw-alias-border-l1, rgba(0, 0, 0, 0.08));
+}
+
+.toolbarButton:hover {
+  background: var(--dsw-alias-interactive-bg-hover, rgba(0, 0, 0, 0.05));
+}
+
+.badge {
+  position: fixed;
+  transform: translate(0, -50%);
+  z-index: 50;
+  width: 18px;
+  height: 18px;
+  border: none;
+  border-radius: 999px;
+  background: #2f88ff;
+  color: #ffffff;
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 18px;
+  text-align: center;
+  padding: 0;
+  cursor: pointer;
+  box-shadow: 0 1px 4px rgba(47, 136, 255, 0.45);
+  user-select: none;
+}
+
+.badge:hover {
+  background: #1f78f0;
+}
+
+.highlight {
+  position: fixed;
+  z-index: 49;
+  background: rgba(47, 136, 255, 0.22);
+  border-radius: 2px;
+  pointer-events: none;
+}
+
+.editorNew {
+  position: fixed;
+  z-index: 50;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 8px 6px 12px;
+  background: var(--dsw-alias-bg-layer-1, #ffffff);
+  border: 1px solid var(--dsw-alias-border-l1, rgba(0, 0, 0, 0.08));
+  border-radius: 999px;
+  box-shadow: 0 6px 24px rgba(0, 0, 0, 0.14);
+}
+
+.editorEdit {
+  position: fixed;
+  z-index: 50;
+  display: flex;
+  flex-direction: column;
+  background: var(--dsw-alias-bg-layer-1, #ffffff);
+  border: 1px solid var(--dsw-alias-border-l1, rgba(0, 0, 0, 0.08));
+  border-radius: 14px;
+  box-shadow: 0 8px 28px rgba(0, 0, 0, 0.16);
+  overflow: hidden;
+}
+
+.editorInput {
+  flex: auto;
+  min-width: 0;
+  border: none;
+  outline: none;
+  background: transparent;
+  color: var(--dsw-alias-label-primary, #1f2329);
+  font-size: 13px;
+  line-height: 22px;
+}
+
+.editorTextarea {
+  border: none;
+  outline: none;
+  resize: none;
+  background: transparent;
+  color: var(--dsw-alias-label-primary, #1f2329);
+  font-size: 13px;
+  line-height: 20px;
+  padding: 10px 12px 4px;
+  font-family: inherit;
+}
+
+.editorInput::placeholder,
+.editorTextarea::placeholder {
+  color: var(--dsw-alias-label-caption, #8f959e);
+}
+
+.confirmButton {
+  flex: none;
+  width: 26px;
+  height: 26px;
+  border: none;
+  border-radius: 999px;
+  background: #1f2329;
+  color: #ffffff;
+  cursor: pointer;
+  display: grid;
+  place-items: center;
+  padding: 0;
+}
+
+.confirmButton:hover {
+  background: #000000;
+}
+
+.editorFooter {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px 8px;
+}
+
+.editorSpacer {
+  flex: auto;
+}
+
+.deleteButton {
+  width: 26px;
+  height: 26px;
+  border: none;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary, #8f959e);
+  cursor: pointer;
+  display: grid;
+  place-items: center;
+  padding: 0;
+}
+
+.deleteButton:hover {
+  background: var(--dsw-alias-interactive-bg-hover, rgba(0, 0, 0, 0.05));
+  color: var(--dsw-alias-state-error-primary, #d53f3f);
+}
+
+.cancelButton,
+.saveButton {
+  border: none;
+  border-radius: 999px;
+  font-size: 13px;
+  line-height: 20px;
+  padding: 4px 14px;
+  cursor: pointer;
+}
+
+.cancelButton {
+  background: var(--dsw-alias-interactive-bg-hover, rgba(0, 0, 0, 0.05));
+  color: var(--dsw-alias-label-primary, #1f2329);
+}
+
+.saveButton {
+  background: #1f2329;
+  color: #ffffff;
+}
+
+.saveButton:hover {
+  background: #000000;
+}
+
+/* ── composer chip (conversation.input.dock) ─────────────────────────────── */
+
+.chipWrap {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 4px;
+}
+
+.chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  border: 1px solid var(--dsw-alias-border-l1, rgba(0, 0, 0, 0.1));
+  border-radius: 999px;
+  background: var(--dsw-alias-bg-layer-1, #ffffff);
+  color: var(--dsw-alias-label-primary, #1f2329);
+  font-size: 12px;
+  line-height: 18px;
+  padding: 2px 10px;
+  cursor: pointer;
+  user-select: none;
+}
+
+.chip:hover {
+  background: var(--dsw-alias-interactive-bg-hover, rgba(0, 0, 0, 0.05));
+}
+
+.chipPanel {
+  margin: 0;
+  padding: 4px;
+  list-style: none;
+  min-width: 220px;
+  max-width: 420px;
+  border: 1px solid var(--dsw-alias-border-l1, rgba(0, 0, 0, 0.08));
+  border-radius: 12px;
+  background: var(--dsw-alias-bg-layer-1, #ffffff);
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.1);
+}
+
+.chipRow {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 6px;
+  border-radius: 8px;
+}
+
+.chipRow:hover {
+  background: var(--dsw-alias-interactive-bg-hover, rgba(0, 0, 0, 0.04));
+}
+
+.chipNumber {
+  flex: none;
+  width: 16px;
+  height: 16px;
+  border-radius: 999px;
+  background: #2f88ff;
+  color: #ffffff;
+  font-size: 10px;
+  font-weight: 600;
+  line-height: 16px;
+  text-align: center;
+}
+
+.chipText {
+  flex: auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 12px;
+  color: var(--dsw-alias-label-primary, #1f2329);
+}
+
+.chipNote {
+  color: var(--dsw-alias-label-tertiary, #8f959e);
+}
+
+.chipRemove {
+  flex: none;
+  width: 20px;
+  height: 20px;
+  border: none;
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary, #8f959e);
+  cursor: pointer;
+  display: grid;
+  place-items: center;
+  padding: 0;
+}
+
+.chipRemove:hover {
+  background: var(--dsw-alias-interactive-bg-hover, rgba(0, 0, 0, 0.08));
+  color: var(--dsw-alias-state-error-primary, #d53f3f);
+}
+
+/* bridge 失败的内联错误（编辑器保持打开，注解不丢）。 */
+.editorError {
+  position: absolute;
+  top: calc(100% + 4px);
+  left: 12px;
+  color: #e5484d;
+  font-size: 12px;
+  white-space: nowrap;
+}

package/src/client/annotate/chip.tsx

@@ -0,0 +1,115 @@
+/**
+ * The 「N 条注释」 composer chip (Workitem 02): a `conversation.input.dock`
+ * list entry (the official composer-attachment seat; todo dock lives at order
+ * 0, the queue strip at 20 — we sit between at 10). The chip counts the
+ * session's ACTIVE annotations, expands inline to preview/remove each one,
+ * and watches the owner-provided input snapshot for the send edge (draft
+ * non-empty → empty) to flip the annotations to 'sent' — the chip then
+ * disappears while the badges stay on the message flow.
+ */
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import type { ReactNode } from 'react'
+import { IconCloseOutline16, IconListPenOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { InputZone } from '../../context-types.ts'
+import { isSendEdge } from './format.ts'
+import type { AnnotationStore } from './model.ts'
+import { t, useLocaleTick } from '../locales.ts'
+import { AnnotateErrorBoundary } from './overlay.tsx'
+import css from './annotate.module.css'
+
+/** 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 function createAnnotationChip(store: AnnotationStore) {
+  function AnnotationChip(props: ChipProps): ReactNode {
+    useLocaleTick()
+    const sessionId = props.session.sessionId
+    useSyncExternalStore(
+      useCallback((cb: () => void) => store.subscribe(cb), [store]),
+      () => store.getSnapshot(),
+    )
+    const [expanded, setExpanded] = useState(false)
+
+    // 发送沿检测：草稿非空→空 且 伴随机器信号（提交相位/队列增长/running 启
+    // 动）——纯「草稿清空」不算发送（用户手动全选删除满足前者，但没有机器信
+    // 号，注释不应被误归档为已发送）。
+    // owner share 是 point-in-time 快照、由骨架负责重渲染——禁止订阅，只在
+    // effect 里比边沿。会话切换不重置：仅当两次渲染属于同一会话时才比较。
+    const previous = useRef({
+      sessionId,
+      draft: props.input.draft,
+      phase: props.input.phase,
+      queueLen: props.input.queue?.length ?? 0,
+      running: props.session.running,
+    })
+    useEffect(() => {
+      const prev = previous.current
+      previous.current = {
+        sessionId,
+        draft: props.input.draft,
+        phase: props.input.phase,
+        queueLen: props.input.queue?.length ?? 0,
+        running: props.session.running,
+      }
+      if (prev.sessionId !== sessionId) return
+      if (store.countActive(sessionId) === 0) return
+      if (!isSendEdge(prev.draft, props.input.draft)) return
+      const machineSignal = prev.phase !== 'plain'
+        || (props.input.queue?.length ?? 0) > prev.queueLen
+        || (props.session.running && !prev.running)
+      if (!machineSignal) return
+      store.markSessionSent(sessionId)
+    })
+
+    const active = store.listActive(sessionId)
+    if (active.length === 0) return null
+
+    return (
+      <div className={css.chipWrap}>
+        <button
+          type="button"
+          className={css.chip}
+          aria-expanded={expanded}
+          onClick={() => { setExpanded(open => !open) }}
+        >
+          <IconListPenOutline16 size={12} />
+          <span>{t(active.length === 1 ? 'chipOne' : 'chipMany', { n: active.length })}</span>
+        </button>
+        {expanded && (
+          <ul className={css.chipPanel}>
+            {active.map(annotation => (
+              <li key={annotation.id} className={css.chipRow}>
+                <span className={css.chipNumber}>{annotation.number}</span>
+                <span className={css.chipText} title={annotation.text}>
+                  {annotation.text}
+                  {annotation.note !== '' && <span className={css.chipNote}>（{annotation.note}）</span>}
+                </span>
+                <button
+                  type="button"
+                  className={css.chipRemove}
+                  title={t('removeTitle')}
+                  aria-label={t('removeAria', { n: annotation.number })}
+                  onClick={() => { store.remove(annotation.id) }}
+                >
+                  <IconCloseOutline16 size={12} />
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+      </div>
+    )
+  }
+
+  return function AnnotationChipEntry(props: ChipProps): ReactNode {
+    return (
+      <AnnotateErrorBoundary>
+        <AnnotationChip {...props} />
+      </AnnotateErrorBoundary>
+    )
+  }
+}

package/src/client/annotate/css.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CSS Modules type declarations (tsdown compiles `*.module.css` to a class-map
+ * default export; this mirror keeps `tsc --noEmit` honest). Scoped to the
+ * annotate module's needs — one wildcard declaration, no runtime footprint.
+ */
+declare module '*.module.css' {
+  const classes: Record<string, string>
+  export default classes
+}

package/src/client/annotate/draft.ts

@@ -0,0 +1,67 @@
+/**
+ * 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, ConversationService, SessionId, SessionInput } from '../../context-types.ts'
+import { buildQuoteBlock, nextManagedDraft } from './format.ts'
+import type { AnnotationStore } from './model.ts'
+
+/** The head (quote block + blank line) last written into each session's draft. */
+const managedHeads = new Map<SessionId, string>()
+
+/** Resolve the per-session input facade, degrading to undefined (never throws). */
+export function resolveInput(ctx: Context, sessionId: SessionId): SessionInput | undefined {
+  try {
+    const actx = ctx.sessions.scope(sessionId)
+    if (actx === undefined) return undefined
+    const conversation = ctx.get('conversation') as ConversationService | undefined
+    return conversation?.input.for(actx)
+  } catch {
+    return 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 function syncSessionDraft(ctx: Context, store: AnnotationStore, sessionId: SessionId): void {
+  try {
+    const input = resolveInput(ctx, sessionId)
+    if (input === undefined) return
+    const block = buildQuoteBlock(store.listActive(sessionId))
+    const lastHead = managedHeads.get(sessionId) ?? ''
+    const draft = input.state.getSnapshot().draft
+    const next = nextManagedDraft(draft, lastHead, block)
+    // block 为空（注释全部 sent/移除）时不覆写 managedHeads：submit 失败
+    // rollback 会把含旧前缀的草稿恢复回来，保留 lastHead 才能让下一次 sync
+    // 正常剥离它，否则新注释的前缀会叠在旧前缀之上（双重引用块）。
+    if (block !== '') managedHeads.set(sessionId, next.head)
+    if (next.draft === draft) return
+    input.setDraft(next.draft)
+  } catch (error) {
+    console.warn('[dsh-sidenote] draft sync failed:', error)
+  }
+}
+
+/** Re-sync every session holding annotations (store-change fan-out). */
+export function syncAllDrafts(ctx: Context, store: AnnotationStore): void {
+  for (const sessionId of store.sessions()) syncSessionDraft(ctx, store, sessionId)
+}
+
+/** Forget all managed heads (page-level lifecycle; plugin teardown/testing). */
+export function resetManagedHeads(): void {
+  managedHeads.clear()
+}

package/src/client/annotate/format.ts

@@ -0,0 +1,83 @@
+import { t } from '../locales.ts'
+
+/**
+ * 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 const SELECTION_LIMIT = 500
+
+/** Marker appended when a selection is truncated (参照 sidebar-qa 的省略号模式). */
+export const TRUNCATION_MARK = '…'
+
+/** Bound a quote to {@link SELECTION_LIMIT} characters, marking truncation. */
+export function truncateQuote(text: string, limit: number = SELECTION_LIMIT): string {
+  if (text.length <= limit) return text
+  return `${text.slice(0, limit)}${TRUNCATION_MARK}`
+}
+
+/** Quote one (possibly multi-line) text as `> `-prefixed lines. */
+export function quoteLines(text: string): string {
+  return text.split('\n').map(line => (line === '' ? '>' : `> ${line}`)).join('\n')
+}
+
+export interface QuoteItem {
+  readonly text: string
+  readonly note: string
+}
+
+/** One annotation's block: quoted original plus the note line. */
+export function formatQuoteItem(item: QuoteItem): string {
+  const noteLine = item.note.trim() === '' ? t('noNote') : t('noteLine', { note: item.note })
+  return `${quoteLines(item.text)}\n${noteLine}`
+}
+
+/** The full context block for every active annotation, in creation order. */
+export function buildQuoteBlock(items: readonly QuoteItem[]): string {
+  return items.map(formatQuoteItem).join('\n\n')
+}
+
+/** The 「在侧边聊天中提问」 seed: quote + optional note（与主对话注释同构）. */
+export function buildSideChatQuote(text: string, note = ''): string {
+  return formatQuoteItem({ text, note })
+}
+
+/**
+ * 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 function nextManagedDraft(
+  draft: string,
+  lastHead: string,
+  block: string,
+): { head: string; draft: string } {
+  const userText = lastHead !== '' && draft.startsWith(lastHead) ? draft.slice(lastHead.length) : draft
+  const head = block === '' ? '' : `${block}\n\n`
+  return { head, draft: head + userText }
+}
+
+/**
+ * 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 function isSendEdge(previousDraft: string, nextDraft: string): boolean {
+  return previousDraft.trim() !== '' && nextDraft.trim() === ''
+}

package/src/client/annotate/index.tsx

@@ -0,0 +1,66 @@
+/**
+ * Workitem 02 — 划选注释：selection listener + numbered badges + annotation
+ * editor + the composer「N 条注释」chip. Wiring only: one annotation store,
+ * one selection controller, one overlay React root (appended to document.body
+ * and marked `data-dsh-sidenote` so the listener excludes our own DOM), and
+ * one `conversation.input.dock` slot entry. 全部 additive、页面级生命周期,
+ * and every seam degrades to a logged no-op instead of crashing the host page.
+ *
+ * 整个模块包在一个 ctx.effect 里：HMR/插件禁用时 fiber 撤销即全部清理
+ * （store 退订、document 监听器移除、overlay unmount、host div 移除、受管
+ * 草稿头清空）——否则重挂后双重挂载（两层工具条、双份监听、新旧 store
+ * 分裂）。slot 注册的 disposer 由 cordis 服务代理路由进调用方 fiber，
+ * 无需手动回收。
+ */
+import { createRoot } from 'react-dom/client'
+import type { Context } from '../../context-types.ts'
+import { createAnnotationStore } from './model.ts'
+import { createSelectionController } from './selection.ts'
+import { AnnotateOverlay } from './overlay.tsx'
+import { createAnnotationChip } from './chip.tsx'
+import { resetManagedHeads, syncAllDrafts } from './draft.ts'
+
+export function registerAnnotations(ctx: Context): void {
+  ctx.effect(() => {
+    try {
+      const store = createAnnotationStore()
+      const controller = createSelectionController(() => ctx.sessions.list.getSnapshot().current ?? '')
+
+      // The overlay root: toolbar + badges + highlight + editor.
+      const host = document.createElement('div')
+      host.dataset.dshSidenote = ''
+      document.body.appendChild(host)
+      const root = createRoot(host)
+      root.render(<AnnotateOverlay ctx={ctx} store={store} controller={controller} />)
+
+      // 发送携带（受管草稿前缀块）: keep each session's composer draft headed by
+      // its active annotations' quote block; the chip clears on the send edge.
+      const offStore = store.subscribe(() => { syncAllDrafts(ctx, store) })
+
+      // The「N 条注释」chip: conversation.input.dock is the official composer
+      // attachment seat; slots.inject waits for the shell's declaration (the
+      // ui-conversation todo/queue docks register the same way)。disposer 由
+      // cordis 服务代理级联进本 fiber，随 effect 撤销自动回收。
+      ctx.slots.inject('conversation.input.dock', () => {
+        return ctx.slots.register({
+          name: 'conversation.input.dock',
+          id: 'dsh-sidenote-annotations',
+          order: 10,
+          registrant: 'dsh-sidenote',
+        }, createAnnotationChip(store))
+      })
+
+      return () => {
+        offStore()
+        controller.dispose()
+        resetManagedHeads()
+        // 同帧 render/unmount 会触发 React 警告——推迟到下一帧。
+        setTimeout(() => { root.unmount() })
+        host.remove()
+      }
+    } catch (error) {
+      console.error('[dsh-sidenote] annotate setup failed:', error)
+      return () => {}
+    }
+  }, 'dsh-sidenote: annotations')
+}