@huanlin/dsh-plugin-input-history 0.1.0

package/lib/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":["capacity: number","parsed: unknown","historyStore: HistoryStore | null","en: Record<InputHistoryKey, string>","zh: Record<InputHistoryKey, string>","navCursor: number | null","savedDraft: string | null"],"sources":["../src/client/history.ts","../src/client/HistoryDock.tsx","../src/client/ime.ts","../src/client/dom.ts","../src/client/locales.ts","../src/client/index.ts"],"sourcesContent":["/**\n * Prompt history store — pure functions over a string array.\n *\n * The store is a FIFO list of unique prompt strings, persisted to\n * `localStorage`. Newest entries are at the end of the array. The\n * navigation cursor walks backwards from the end (ArrowUp = older,\n * ArrowDown = newer).\n *\n * The functions in this module are pure (no `localStorage` access) so\n * they can be unit-tested without jsdom. The `HistoryStore` class below\n * wires them to `localStorage` with try/catch containment — a quota\n * exception or a disabled storage (private mode) degrades gracefully to\n * an in-memory list that lives for the page lifetime.\n *\n * @module @huanlin/dsh-plugin-input-history/client/history\n */\n\n/** localStorage key (versioned; bump on schema changes to start fresh). */\nexport const STORAGE_KEY = 'dsh-plugin-input-history:v1'\n\n/** Default capacity when none is configured. */\nexport const DEFAULT_CAPACITY = 500\n\n/**\n * Append a prompt to the history.\n *\n * Rules:\n *   - Empty / whitespace-only strings are ignored (the InputBar already\n *     rejects them at submit, but defensive).\n *   - When the new entry equals the most recent one, it is a no-op\n *     (avoids stacking duplicates from rapid resends).\n *   - When the new entry already exists earlier in the history, that\n *     earlier occurrence is removed (recency wins; the prompt moves to\n *     the end). This mirrors terminal shell behaviour.\n *   - When the array would exceed `capacity`, the oldest entries are\n *     dropped from the front (FIFO).\n *\n * @param history - the current history array (newest at end).\n * @param prompt - the prompt to append.\n * @param capacity - the maximum number of entries to retain.\n * @returns the new history array (may be the same reference if no-op).\n */\nexport function appendHistory(\n  history: readonly string[],\n  prompt: string,\n  capacity: number = DEFAULT_CAPACITY,\n): string[] {\n  const trimmed = prompt.trim()\n  if (trimmed === '') return history as string[]\n  // Latest-equal with no earlier duplicate: true no-op (same reference).\n  // When an earlier duplicate exists, the filter below removes it so the\n  // entry moves to the end (recency wins).\n  const lastIndex = history.lastIndexOf(trimmed)\n  if (lastIndex !== -1 && lastIndex === history.length - 1 && history.indexOf(trimmed) === lastIndex) {\n    return history as string[]\n  }\n  // Remove any earlier occurrence (recency wins).\n  const filtered = history.filter(item => item !== trimmed)\n  filtered.push(trimmed)\n  // FIFO: drop oldest entries from the front.\n  const cap = Math.max(1, capacity)\n  if (filtered.length > cap) {\n    return filtered.slice(filtered.length - cap)\n  }\n  return filtered\n}\n\n/**\n * Navigation cursor for walking the history.\n *\n * The cursor is `null` when the user is not navigating (i.e. they are\n * typing a fresh draft). ArrowUp sets it to the last index, then\n * decrements; ArrowDown increments; when it would exceed `history.length\n * - 1`, it returns to `null` (meaning \"restore the in-progress draft\").\n *\n * @param current - the current cursor (null = not navigating).\n * @param total - the total number of history entries.\n * @param dir - `'up'` (older) or `'down'` (newer).\n * @returns the next cursor, or `null` when navigation falls off the\n *   newest end (caller should restore the saved draft).\n */\nexport function nextIndex(\n  current: number | null,\n  total: number,\n  dir: 'up' | 'down',\n): number | null {\n  if (total === 0) return null\n  if (dir === 'up') {\n    if (current === null) return total - 1\n    if (current <= 0) return 0\n    return current - 1\n  }\n  // dir === 'down'\n  if (current === null) return null\n  if (current >= total - 1) return null\n  return current + 1\n}\n\n/**\n * Read the history entry at a cursor, or `null` when the cursor is null.\n *\n * @param history - the history array.\n * @param cursor - the navigation cursor.\n * @returns the prompt at the cursor, or `null`.\n */\nexport function entryAt(\n  history: readonly string[],\n  cursor: number | null,\n): string | null {\n  if (cursor === null) return null\n  if (cursor < 0 || cursor >= history.length) return null\n  return history[cursor] ?? null\n}\n\n/**\n * History store bound to `localStorage`.\n *\n * The store reads once on construction (or on `reload()`) and keeps an\n * in-memory copy. Writes go to both memory and `localStorage` inside a\n * try/catch — a quota exception leaves the in-memory copy authoritative\n * for the rest of the page lifetime. This trades cross-tab consistency\n * for resilience: the store never throws on a write, and the worst case\n * is that a tab keeps its own view until refresh.\n *\n * Cross-tab sync is intentionally NOT implemented: prompt history is\n * append-mostly and a stale read across tabs is harmless (the next\n * append corrects it). Listening to the `storage` event would add\n * reactivity that the navigation UI does not need.\n */\nexport class HistoryStore {\n  private items: string[]\n  private readonly storage: Storage | null\n  private readonly key: string\n\n  /**\n   * @param capacity - maximum entries to retain (FIFO).\n   * @param storage - the storage backend (defaults to `localStorage` when available).\n   * @param key - the storage key (defaults to {@link STORAGE_KEY}).\n   */\n  constructor(\n    private readonly capacity: number = DEFAULT_CAPACITY,\n    storage?: Storage | null,\n    key: string = STORAGE_KEY,\n  ) {\n    this.storage = storage ?? safeLocalStorage()\n    this.key = key\n    this.items = this.readFromStorage()\n  }\n\n  /** Current history snapshot (newest at end). */\n  get list(): readonly string[] {\n    return this.items\n  }\n\n  /** Number of entries currently stored. */\n  get length(): number {\n    return this.items.length\n  }\n\n  /** Reload from storage (e.g. after a suspected external edit). Truncates to the current capacity. */\n  reload(): void {\n    const loaded = this.readFromStorage()\n    const cap = Math.max(1, this.capacity)\n    this.items = loaded.length > cap ? loaded.slice(loaded.length - cap) : loaded\n  }\n\n  /**\n   * Append a prompt and persist. See {@link appendHistory} for rules.\n   * @returns the new history snapshot.\n   */\n  append(prompt: string): readonly string[] {\n    this.items = appendHistory(this.items, prompt, this.capacity)\n    this.writeToStorage()\n    return this.items\n  }\n\n  /** Clear all history (used by tests and a future \"clear\" UI). */\n  clear(): void {\n    this.items = []\n    this.writeToStorage()\n  }\n\n  private readFromStorage(): string[] {\n    if (this.storage === null) return []\n    try {\n      const raw = this.storage.getItem(this.key)\n      if (raw === null) return []\n      const parsed: unknown = JSON.parse(raw)\n      if (!Array.isArray(parsed)) return []\n      return parsed.filter((item): item is string => typeof item === 'string')\n    } catch {\n      return []\n    }\n  }\n\n  private writeToStorage(): void {\n    if (this.storage === null) return\n    try {\n      this.storage.setItem(this.key, JSON.stringify(this.items))\n    } catch {\n      // Quota exceeded, private mode, or disabled storage: keep the\n      // in-memory copy authoritative for the rest of the page lifetime.\n    }\n  }\n}\n\n/** Safe accessor for `localStorage` that returns null on any failure. */\nfunction safeLocalStorage(): Storage | null {\n  try {\n    if (typeof localStorage === 'undefined') return null\n    return localStorage\n  } catch {\n    return null\n  }\n}\n","/**\n * HistoryDock — invisible dock entry that collects prompt history.\n *\n * Registers as a `conversation.composer.dock` list entry and renders an\n * `aria-hidden` anchor (zero layout footprint). The dock's only job is\n * history collection: every render reads `props.session.nodes` and\n * appends new user/steering text to the module-scope `HistoryStore`.\n *\n * The keydown listener that drives navigation lives in `apply` (module\n * scope), NOT in this dock — because the dock is session-scoped and\n * DSH treats blank sessions as \"hero\" (ConversationRoot.tsx:79-80),\n * which suppresses the dock entirely (`!hero` guard at line 156).\n * Moving the listener to `apply` ensures it is always attached,\n * regardless of hero/blank/active session state.\n *\n * @module @huanlin/dsh-plugin-input-history/client/HistoryDock\n */\n\nimport { useRef } from 'react'\nimport type { PropsRuntime, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'\n// Type-only: SlotMap merge for 'conversation.composer.dock' + SessionStandardProps.\nimport type {} from '@deepseek-ai/dsh-client-ui-conversation/client'\nimport { HistoryStore, DEFAULT_CAPACITY } from './history.ts'\n\n/** Full props: dock runtime share + locale seat. */\ntype HistoryDockProps = PropsRuntime<'conversation.composer.dock'> & PropsLocale<'dsh-plugin-input-history'>\n\n/**\n * Module-scope history store, initialized once on first dock mount.\n * Shared with the keydown listener in `apply` via `getHistoryStore()`.\n */\nlet historyStore: HistoryStore | null = null\n\n/** Get the shared history store (initializes lazily on first call). */\nexport function getHistoryStore(): HistoryStore {\n  if (historyStore === null) {\n    historyStore = new HistoryStore(DEFAULT_CAPACITY)\n  }\n  return historyStore\n}\n\n/**\n * Render the invisible history-collection dock entry.\n *\n * @param props - dock runtime share (InputZone owner + session kit) + locale seat.\n * @returns an `aria-hidden` anchor with zero layout footprint.\n */\nexport function HistoryDock({ session }: HistoryDockProps) {\n  const store = getHistoryStore()\n\n  // History collection: diff the last user/steering text against the\n  // previously-seen tail and append on change. Runs every render (cheap:\n  // O(n) over the tail nodes, breaks early once a user/steering node is\n  // found). The store dedupes internally, so re-appends are no-ops.\n  const lastSeenTextRef = useRef<string | null>(null)\n  const lastText = latestUserOrSteeringText(session.nodes)\n  if (lastText !== null && lastText !== lastSeenTextRef.current) {\n    lastSeenTextRef.current = lastText\n    store.append(lastText)\n  }\n\n  // `display: none` keeps the anchor out of layout and out of the\n  // a11y tree. The dock is purely a lifecycle anchor for history\n  // collection; the keydown listener lives in `apply`.\n  return <div aria-hidden style={{ display: 'none' }} data-dsh-plugin-input-history=\"\" />\n}\n\n/**\n * Extract the text of the latest `user` or `steering` node from a\n * conversation snapshot's nodes list.\n *\n * Returns the concatenated text of all `type: 'text'` content blocks.\n * Returns `null` when no user/steering node is present (e.g. a fresh\n * session with only a system/context message).\n *\n * @param nodes - the conversation snapshot's `nodes` array.\n */\nfunction latestUserOrSteeringText(\n  nodes: ReadonlyArray<{\n    kind: string\n    content?: ReadonlyArray<{ type: string; text?: string }>\n  }>,\n): string | null {\n  for (let i = nodes.length - 1; i >= 0; i--) {\n    const node = nodes[i]!\n    if (node.kind !== 'user' && node.kind !== 'steering') continue\n    const content = node.content\n    if (content === undefined) continue\n    let text = ''\n    for (const block of content) {\n      if (block.type === 'text' && typeof block.text === 'string') {\n        text += block.text\n      }\n    }\n    return text\n  }\n  return null\n}\n","/**\n * IME-composition key guard.\n *\n * While a Chinese/Japanese/Korean input method is composing (the user is\n * picking a candidate from the IME window), every pressed key BELONGS to\n * the input method: arrows move the candidate highlight, Enter/Space\n * confirm the composition, Escape cancels it. Page code must not process\n * those keys — a history-navigation handler that calls `preventDefault()`\n * on ArrowUp/ArrowDown during composition would silently break the IME:\n * candidates stop responding, the composition gets torn apart, and only\n * bare letters come out.\n *\n * The composition signal follows the DSH core convention (InputBar's IME\n * guard, issue #535): `isComposing` for modern engines, keyCode 229 as\n * the legacy signal engines emit without isComposing.\n *\n * @module @huanlin/dsh-plugin-input-history/client/ime\n */\n\n/** The pure decision: is this keyboard event part of an IME composition? */\nexport function isImeComposition(event: { isComposing: boolean; keyCode: number }): boolean {\n  return event.isComposing || event.keyCode === 229\n}\n","/**\n * DOM helpers for the composer textarea.\n *\n * The DSH InputBar's textarea is not exposed through any public API —\n * plugins cannot obtain a React ref or a slot-currency handle to it.\n * The two operations this plugin needs (locate the textarea, decide\n * whether the caret is on the first/last line of a multi-line draft) are\n * pure functions over DOM and string state, kept here for unit testing.\n *\n * The locator queries the stable (but undocumented) `data-composer-card`\n * attribute on the composer card root (`InputBar.tsx:629`) and returns\n * the descendant `<textarea>`. The attribute is internal to\n * `@deepseek-ai/dsh-client-ui-conversation` and may change across\n * upstream versions; the locator is the single point to update.\n *\n * @module @huanlin/dsh-plugin-input-history/client/dom\n */\n\n/** Caret line information for a multi-line textarea value. */\nexport interface CursorLineInfo {\n  /** 0-based index of the line the caret is on. */\n  readonly currentLine: number\n  /** Total number of lines in the value (>= 1). */\n  readonly totalLines: number\n  /** True when the caret is collapsed and on the first line. */\n  readonly atFirstLine: boolean\n  /** True when the caret is collapsed and on the last line. */\n  readonly atLastLine: boolean\n}\n\n/**\n * Compute the caret's line position in a textarea value.\n *\n * Lines are split on `\\n` (the textarea's own line break character). The\n * caret must be collapsed (`selectionStart === selectionEnd`) for the\n * `atFirstLine` / `atLastLine` flags to be true — a non-collapsed\n * selection spanning multiple lines should not trigger history navigation.\n *\n * @param value - the textarea's current value.\n * @param selectionStart - the textarea's `selectionStart`.\n * @param selectionEnd - the textarea's `selectionEnd` (defaults to `selectionStart`).\n * @returns the caret's line information.\n */\nexport function cursorLineInfo(\n  value: string,\n  selectionStart: number,\n  selectionEnd: number = selectionStart,\n): CursorLineInfo {\n  // Swap if reversed (the browser allows selectionStart > selectionEnd when\n  // the user drags upwards); clamp to value bounds.\n  const rawStart = Math.min(selectionStart, selectionEnd)\n  const rawEnd = Math.max(selectionStart, selectionEnd)\n  const clampedStart = Math.max(0, Math.min(rawStart, value.length))\n  const clampedEnd = Math.max(clampedStart, Math.min(rawEnd, value.length))\n  const collapsed = clampedStart === clampedEnd\n  const lines = value.split('\\n')\n  const totalLines = lines.length\n  let currentLine = 0\n  let runningLength = 0\n  for (let i = 0; i < totalLines; i++) {\n    const line = lines[i]!\n    // The caret at position `p` belongs to line `i` if `p` is in\n    // [runningLength, runningLength + line.length + 1) — the `+1` covers\n    // the position immediately after the line's last character, which is\n    // still on this line (right before the `\\n`). The very end of the\n    // value (after the last line's last char) belongs to the last line.\n    const lineEnd = runningLength + line.length\n    const isLastLine = i === totalLines - 1\n    const upperBound = isLastLine ? lineEnd + 1 : lineEnd + 1 // include the `\\n` position\n    if (clampedStart >= runningLength && clampedStart < upperBound) {\n      currentLine = i\n      break\n    }\n    runningLength = lineEnd + 1 // +1 for the `\\n`\n  }\n  return {\n    currentLine,\n    totalLines,\n    atFirstLine: collapsed && currentLine === 0,\n    atLastLine: collapsed && currentLine === totalLines - 1,\n  }\n}\n\n/**\n * Locate the DSH composer textarea in the current document.\n *\n * Walks from the event target up to find the closest `[data-composer-card]`\n * ancestor, then queries the descendant `<textarea>` inside it. Returns\n * `null` when the target is not inside the composer card (e.g. the user\n * is typing in another input or the textarea is momentarily absent).\n *\n * When called without an event target, falls back to a document-wide\n * query — used in tests and ad-hoc probing.\n *\n * @param from - the event target (or any node inside the composer card).\n * @returns the textarea element, or `null` when not found.\n */\nexport function findComposerTextarea(from?: EventTarget | null): HTMLTextAreaElement | null {\n  if (typeof document === 'undefined') return null\n  if (from === undefined) {\n    // No argument: document-wide query.\n    return document.querySelector<HTMLTextAreaElement>('[data-composer-card] textarea')\n  }\n  // `null` or an actual target: do NOT fall back to document-wide query.\n  if (from === null) return null\n  // `closest` is on Element; EventTarget may be a Text node or other\n  // non-Element node. Narrow with an instanceof check.\n  const card = from instanceof Element ? from.closest('[data-composer-card]') : null\n  if (card !== null) {\n    const ta = card.querySelector<HTMLTextAreaElement>('textarea')\n    if (ta !== null) return ta\n  }\n  return null\n}\n","/**\n * Locale dictionaries for dsh-plugin-input-history.\n *\n * The plugin renders nothing visible — the only user-facing copy is the\n * `aria-label` on the invisible dock anchor (for screen readers) and a\n * future settings row label.\n *\n * @module @huanlin/dsh-plugin-input-history/client/locales\n */\n\n/** All copy keys for the dsh-plugin-input-history namespace. */\nexport type InputHistoryKey =\n  | 'ariaLabel'\n  | 'restoredDraft'\n  | 'noHistory'\n\n/** Locale namespace id (matches the cordis.patch.yml plugin id). */\nexport const NS = 'dsh-plugin-input-history'\n\n/** English dictionary. */\nexport const en: Record<InputHistoryKey, string> = {\n  ariaLabel: 'Prompt history navigation (ArrowUp/ArrowDown)',\n  restoredDraft: 'Restored in-progress draft',\n  noHistory: 'No prompt history yet',\n}\n\n/** Chinese dictionary. */\nexport const zh: Record<InputHistoryKey, string> = {\n  ariaLabel: '提示词历史导航（上/下方向键）',\n  restoredDraft: '已恢复正在编辑的草稿',\n  noHistory: '暂无提示词历史',\n}\n","/**\n * dsh-plugin-input-history — browser half.\n *\n * Two registrations:\n *   - `conversation.composer.dock` list slot (id `dsh-plugin-input-history`,\n *     order 100) — renders an invisible anchor that collects history from\n *     `session.nodes` every render. The dock is session-scoped; DSH treats\n *     blank sessions as \"hero\" and suppresses the dock, so history\n *     collection only runs in active sessions. That is fine: the first\n *     message in a blank session is collected after the session becomes\n *     active (the message makes it non-blank).\n *   - A document-level `keydown` listener attached in `apply` (NOT in the\n *     dock component) — this ensures the listener is always active,\n *     including in hero/blank mode where the dock is suppressed. The\n *     listener uses the native `value` setter + `dispatchEvent('input')`\n *     to feed history text into the textarea, which triggers InputBar's\n *     `onChange` → `keyboard.setDraft` — the same path the user's typing\n *     takes.\n *\n * History is collected from `user` and `steering` conversation nodes as\n * they appear in any session's `ConversationSnapshot`, persisted to\n * `localStorage` (FIFO, 500 entries), and shared across all sessions\n * in the same browser profile.\n *\n * @module @huanlin/dsh-plugin-input-history/client\n */\n\nimport type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'\n// Type-only: pulls the locale plugin's Context merge (ctx.locale).\nimport type {} from '@deepseek-ai/dsh-client-locale/client'\n// Type-only: pulls the shell's SlotMap merge (conversation.composer.dock)\n// + SessionStandardProps (useInput, inputActions).\nimport type {} from '@deepseek-ai/dsh-client-ui-conversation/client'\nimport { HistoryDock, getHistoryStore } from './HistoryDock.tsx'\nimport { isImeComposition } from './ime.ts'\nimport { cursorLineInfo, findComposerTextarea } from './dom.ts'\nimport { nextIndex, entryAt } from './history.ts'\nimport { en, NS, zh, type InputHistoryKey } from './locales.ts'\n\ndeclare module '@deepseek-ai/dsh-client-ui-slots' {\n  interface LocaleNamespaceMap {\n    /** The dock's aria-label + future settings row copy. */\n    'dsh-plugin-input-history': InputHistoryKey\n  }\n}\n\n/** Required services: slots + locale. */\nexport const inject = ['slots', 'locale']\n\n/**\n * Navigation cursor + saved draft for the keydown listener. Module-scoped\n * because the listener is attached once in `apply` and must persist across\n * dock mount/unmount cycles.\n */\nlet navCursor: number | null = null\nlet savedDraft: string | null = null\n\n/**\n * Client plugin body: register the dock + attach the keydown listener.\n *\n * @param ctx - client root context.\n */\nexport function apply(ctx: ClientContext): void {\n  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-plugin-input-history: dictionaries')\n\n  // The dock collects history from session.nodes. It is session-scoped;\n  // in hero/blank mode it is suppressed, but the keydown listener below\n  // still works (it reads from the module-scope HistoryStore, which\n  // persists across dock mount/unmount cycles via localStorage).\n  ctx.slots.inject('conversation.composer.dock', () =>\n    ctx.slots.register(\n      {\n        name: 'conversation.composer.dock',\n        id: 'dsh-plugin-input-history',\n        order: 100,\n        locale: NS,\n      },\n      HistoryDock,\n    ),\n  )\n\n  // Attach the document-level keydown listener. This lives in `apply`\n  // (not in the dock component) so it stays active even when the dock is\n  // suppressed (hero/blank sessions — ConversationRoot.tsx:79-80 treats\n  // blank sessions as hero, and line 156 skips the dock render).\n  ctx.effect(() => {\n    if (typeof document === 'undefined') return () => {}\n    const handler = (event: KeyboardEvent): void => {\n      if (event.key !== 'ArrowUp' && event.key !== 'ArrowDown') return\n      if (isImeComposition(event)) return\n      if (event.defaultPrevented) return\n      const textarea = findComposerTextarea(event.target)\n      if (textarea === null) return\n      if (event.target !== textarea) return\n      // Skip if the textarea is readOnly or disabled — hero mode's\n      // workspace-picker trigger, or a submitting machine phase.\n      if (textarea.readOnly || textarea.disabled) return\n\n      const store = getHistoryStore()\n      const history = store.list\n\n      // Multi-line boundary check.\n      const info = cursorLineInfo(textarea.value, textarea.selectionStart, textarea.selectionEnd)\n      if (event.key === 'ArrowUp' && !info.atFirstLine) return\n      if (event.key === 'ArrowDown' && !info.atLastLine) return\n\n      const dir = event.key === 'ArrowUp' ? 'up' : 'down'\n      const next = nextIndex(navCursor, history.length, dir)\n\n      // Down off the newest end: restore the saved draft (if any).\n      if (next === null) {\n        const saved = savedDraft\n        navCursor = null\n        if (saved !== null) {\n          setNativeTextareaValue(textarea, saved)\n          savedDraft = null\n        }\n        event.preventDefault()\n        return\n      }\n\n      // Entering history: save the current draft the first time we\n      // navigate away from \"not navigating\".\n      if (navCursor === null && savedDraft === null) {\n        savedDraft = textarea.value\n      }\n\n      const entry = entryAt(history, next)\n      if (entry === null) return\n      navCursor = next\n      setNativeTextareaValue(textarea, entry)\n      event.preventDefault()\n    }\n    document.addEventListener('keydown', handler, false)\n    return () => {\n      document.removeEventListener('keydown', handler, false)\n    }\n  }, 'dsh-plugin-input-history: keydown listener')\n}\n\n/**\n * Set the textarea value via the native prototype setter and dispatch an\n * `input` event so React's controlled-component onChange fires.\n *\n * React 18 tracks the textarea's value internally; directly assigning\n * `textarea.value = x` does NOT trigger React's onChange because React's\n * value tracker compares against its last-seen value. Using the native\n * prototype setter bypasses React's tracker, and the dispatched `input`\n * event makes React detect the change and run InputBar's `onChange` →\n * `keyboard.setDraft(next)`. This is the same technique used by\n * browser automation libraries (Playwright, Testing Library) to simulate\n * user typing in React controlled inputs.\n *\n * @param textarea - the target textarea element.\n * @param value - the new value to set.\n */\nfunction setNativeTextareaValue(textarea: HTMLTextAreaElement, value: string): void {\n  const proto = window.HTMLTextAreaElement.prototype\n  const descriptor = Object.getOwnPropertyDescriptor(proto, 'value')\n  if (descriptor === undefined || descriptor.set === undefined) {\n    // Fallback: direct assignment (may not trigger React onChange in\n    // all browsers, but better than nothing).\n    textarea.value = value\n    return\n  }\n  descriptor.set.call(textarea, value)\n  textarea.dispatchEvent(new Event('input', { bubbles: true }))\n}\n"],"mappings":"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"}

package/lib/index.js

@@ -0,0 +1,12 @@
+//#region src/index.ts
+const name = "dsh-plugin-input-history";
+const inject = [];
+/**
+* Host apply — no-op. The history navigation is a pure client-side UI
+* contribution; no host-side resources are used.
+* @param _ctx - host context (unused).
+*/
+function apply(_ctx) {}
+
+//#endregion
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region src/invariant.ts
+const PACKAGE_NAME = "@huanlin/dsh-plugin-input-history";
+/** Cordis companion plugin name. */
+const name = "dsh-plugin-input-history-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the single `conversation.composer.dock` slot
+* registration is a registry-owned contribution whose disposal is proven
+* by the HMR-safety spec. The plugin's only mutable state is the
+* localStorage-backed history array, whose lifecycle is bounded by the
+* browser profile (not the cordis fiber) and whose write path is
+* last-writer-wins with try/catch containment.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+
+//#endregion
+export { apply, inject, name };

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

@@ -0,0 +1,31 @@
+/**
+ * HistoryDock — invisible dock entry that collects prompt history.
+ *
+ * Registers as a `conversation.composer.dock` list entry and renders an
+ * `aria-hidden` anchor (zero layout footprint). The dock's only job is
+ * history collection: every render reads `props.session.nodes` and
+ * appends new user/steering text to the module-scope `HistoryStore`.
+ *
+ * The keydown listener that drives navigation lives in `apply` (module
+ * scope), NOT in this dock — because the dock is session-scoped and
+ * DSH treats blank sessions as "hero" (ConversationRoot.tsx:79-80),
+ * which suppresses the dock entirely (`!hero` guard at line 156).
+ * Moving the listener to `apply` ensures it is always attached,
+ * regardless of hero/blank/active session state.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/HistoryDock
+ */
+import type { PropsRuntime, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import { HistoryStore } from './history.ts';
+/** Full props: dock runtime share + locale seat. */
+type HistoryDockProps = PropsRuntime<'conversation.composer.dock'> & PropsLocale<'dsh-plugin-input-history'>;
+/** Get the shared history store (initializes lazily on first call). */
+export declare function getHistoryStore(): HistoryStore;
+/**
+ * Render the invisible history-collection dock entry.
+ *
+ * @param props - dock runtime share (InputZone owner + session kit) + locale seat.
+ * @returns an `aria-hidden` anchor with zero layout footprint.
+ */
+export declare function HistoryDock({ session }: HistoryDockProps): import("react").JSX.Element;
+export {};

package/lib/types/client/HistoryDock.js

@@ -0,0 +1,83 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * HistoryDock — invisible dock entry that collects prompt history.
+ *
+ * Registers as a `conversation.composer.dock` list entry and renders an
+ * `aria-hidden` anchor (zero layout footprint). The dock's only job is
+ * history collection: every render reads `props.session.nodes` and
+ * appends new user/steering text to the module-scope `HistoryStore`.
+ *
+ * The keydown listener that drives navigation lives in `apply` (module
+ * scope), NOT in this dock — because the dock is session-scoped and
+ * DSH treats blank sessions as "hero" (ConversationRoot.tsx:79-80),
+ * which suppresses the dock entirely (`!hero` guard at line 156).
+ * Moving the listener to `apply` ensures it is always attached,
+ * regardless of hero/blank/active session state.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/HistoryDock
+ */
+import { useRef } from 'react';
+import { HistoryStore, DEFAULT_CAPACITY } from "./history.js";
+/**
+ * Module-scope history store, initialized once on first dock mount.
+ * Shared with the keydown listener in `apply` via `getHistoryStore()`.
+ */
+let historyStore = null;
+/** Get the shared history store (initializes lazily on first call). */
+export function getHistoryStore() {
+    if (historyStore === null) {
+        historyStore = new HistoryStore(DEFAULT_CAPACITY);
+    }
+    return historyStore;
+}
+/**
+ * Render the invisible history-collection dock entry.
+ *
+ * @param props - dock runtime share (InputZone owner + session kit) + locale seat.
+ * @returns an `aria-hidden` anchor with zero layout footprint.
+ */
+export function HistoryDock({ session }) {
+    const store = getHistoryStore();
+    // History collection: diff the last user/steering text against the
+    // previously-seen tail and append on change. Runs every render (cheap:
+    // O(n) over the tail nodes, breaks early once a user/steering node is
+    // found). The store dedupes internally, so re-appends are no-ops.
+    const lastSeenTextRef = useRef(null);
+    const lastText = latestUserOrSteeringText(session.nodes);
+    if (lastText !== null && lastText !== lastSeenTextRef.current) {
+        lastSeenTextRef.current = lastText;
+        store.append(lastText);
+    }
+    // `display: none` keeps the anchor out of layout and out of the
+    // a11y tree. The dock is purely a lifecycle anchor for history
+    // collection; the keydown listener lives in `apply`.
+    return _jsx("div", { "aria-hidden": true, style: { display: 'none' }, "data-dsh-plugin-input-history": "" });
+}
+/**
+ * Extract the text of the latest `user` or `steering` node from a
+ * conversation snapshot's nodes list.
+ *
+ * Returns the concatenated text of all `type: 'text'` content blocks.
+ * Returns `null` when no user/steering node is present (e.g. a fresh
+ * session with only a system/context message).
+ *
+ * @param nodes - the conversation snapshot's `nodes` array.
+ */
+function latestUserOrSteeringText(nodes) {
+    for (let i = nodes.length - 1; i >= 0; i--) {
+        const node = nodes[i];
+        if (node.kind !== 'user' && node.kind !== 'steering')
+            continue;
+        const content = node.content;
+        if (content === undefined)
+            continue;
+        let text = '';
+        for (const block of content) {
+            if (block.type === 'text' && typeof block.text === 'string') {
+                text += block.text;
+            }
+        }
+        return text;
+    }
+    return null;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * DOM helpers for the composer textarea.
+ *
+ * The DSH InputBar's textarea is not exposed through any public API —
+ * plugins cannot obtain a React ref or a slot-currency handle to it.
+ * The two operations this plugin needs (locate the textarea, decide
+ * whether the caret is on the first/last line of a multi-line draft) are
+ * pure functions over DOM and string state, kept here for unit testing.
+ *
+ * The locator queries the stable (but undocumented) `data-composer-card`
+ * attribute on the composer card root (`InputBar.tsx:629`) and returns
+ * the descendant `<textarea>`. The attribute is internal to
+ * `@deepseek-ai/dsh-client-ui-conversation` and may change across
+ * upstream versions; the locator is the single point to update.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/dom
+ */
+/** Caret line information for a multi-line textarea value. */
+export interface CursorLineInfo {
+    /** 0-based index of the line the caret is on. */
+    readonly currentLine: number;
+    /** Total number of lines in the value (>= 1). */
+    readonly totalLines: number;
+    /** True when the caret is collapsed and on the first line. */
+    readonly atFirstLine: boolean;
+    /** True when the caret is collapsed and on the last line. */
+    readonly atLastLine: boolean;
+}
+/**
+ * Compute the caret's line position in a textarea value.
+ *
+ * Lines are split on `\n` (the textarea's own line break character). The
+ * caret must be collapsed (`selectionStart === selectionEnd`) for the
+ * `atFirstLine` / `atLastLine` flags to be true — a non-collapsed
+ * selection spanning multiple lines should not trigger history navigation.
+ *
+ * @param value - the textarea's current value.
+ * @param selectionStart - the textarea's `selectionStart`.
+ * @param selectionEnd - the textarea's `selectionEnd` (defaults to `selectionStart`).
+ * @returns the caret's line information.
+ */
+export declare function cursorLineInfo(value: string, selectionStart: number, selectionEnd?: number): CursorLineInfo;
+/**
+ * Locate the DSH composer textarea in the current document.
+ *
+ * Walks from the event target up to find the closest `[data-composer-card]`
+ * ancestor, then queries the descendant `<textarea>` inside it. Returns
+ * `null` when the target is not inside the composer card (e.g. the user
+ * is typing in another input or the textarea is momentarily absent).
+ *
+ * When called without an event target, falls back to a document-wide
+ * query — used in tests and ad-hoc probing.
+ *
+ * @param from - the event target (or any node inside the composer card).
+ * @returns the textarea element, or `null` when not found.
+ */
+export declare function findComposerTextarea(from?: EventTarget | null): HTMLTextAreaElement | null;

package/lib/types/client/dom.js

@@ -0,0 +1,99 @@
+/**
+ * DOM helpers for the composer textarea.
+ *
+ * The DSH InputBar's textarea is not exposed through any public API —
+ * plugins cannot obtain a React ref or a slot-currency handle to it.
+ * The two operations this plugin needs (locate the textarea, decide
+ * whether the caret is on the first/last line of a multi-line draft) are
+ * pure functions over DOM and string state, kept here for unit testing.
+ *
+ * The locator queries the stable (but undocumented) `data-composer-card`
+ * attribute on the composer card root (`InputBar.tsx:629`) and returns
+ * the descendant `<textarea>`. The attribute is internal to
+ * `@deepseek-ai/dsh-client-ui-conversation` and may change across
+ * upstream versions; the locator is the single point to update.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/dom
+ */
+/**
+ * Compute the caret's line position in a textarea value.
+ *
+ * Lines are split on `\n` (the textarea's own line break character). The
+ * caret must be collapsed (`selectionStart === selectionEnd`) for the
+ * `atFirstLine` / `atLastLine` flags to be true — a non-collapsed
+ * selection spanning multiple lines should not trigger history navigation.
+ *
+ * @param value - the textarea's current value.
+ * @param selectionStart - the textarea's `selectionStart`.
+ * @param selectionEnd - the textarea's `selectionEnd` (defaults to `selectionStart`).
+ * @returns the caret's line information.
+ */
+export function cursorLineInfo(value, selectionStart, selectionEnd = selectionStart) {
+    // Swap if reversed (the browser allows selectionStart > selectionEnd when
+    // the user drags upwards); clamp to value bounds.
+    const rawStart = Math.min(selectionStart, selectionEnd);
+    const rawEnd = Math.max(selectionStart, selectionEnd);
+    const clampedStart = Math.max(0, Math.min(rawStart, value.length));
+    const clampedEnd = Math.max(clampedStart, Math.min(rawEnd, value.length));
+    const collapsed = clampedStart === clampedEnd;
+    const lines = value.split('\n');
+    const totalLines = lines.length;
+    let currentLine = 0;
+    let runningLength = 0;
+    for (let i = 0; i < totalLines; i++) {
+        const line = lines[i];
+        // The caret at position `p` belongs to line `i` if `p` is in
+        // [runningLength, runningLength + line.length + 1) — the `+1` covers
+        // the position immediately after the line's last character, which is
+        // still on this line (right before the `\n`). The very end of the
+        // value (after the last line's last char) belongs to the last line.
+        const lineEnd = runningLength + line.length;
+        const isLastLine = i === totalLines - 1;
+        const upperBound = isLastLine ? lineEnd + 1 : lineEnd + 1; // include the `\n` position
+        if (clampedStart >= runningLength && clampedStart < upperBound) {
+            currentLine = i;
+            break;
+        }
+        runningLength = lineEnd + 1; // +1 for the `\n`
+    }
+    return {
+        currentLine,
+        totalLines,
+        atFirstLine: collapsed && currentLine === 0,
+        atLastLine: collapsed && currentLine === totalLines - 1,
+    };
+}
+/**
+ * Locate the DSH composer textarea in the current document.
+ *
+ * Walks from the event target up to find the closest `[data-composer-card]`
+ * ancestor, then queries the descendant `<textarea>` inside it. Returns
+ * `null` when the target is not inside the composer card (e.g. the user
+ * is typing in another input or the textarea is momentarily absent).
+ *
+ * When called without an event target, falls back to a document-wide
+ * query — used in tests and ad-hoc probing.
+ *
+ * @param from - the event target (or any node inside the composer card).
+ * @returns the textarea element, or `null` when not found.
+ */
+export function findComposerTextarea(from) {
+    if (typeof document === 'undefined')
+        return null;
+    if (from === undefined) {
+        // No argument: document-wide query.
+        return document.querySelector('[data-composer-card] textarea');
+    }
+    // `null` or an actual target: do NOT fall back to document-wide query.
+    if (from === null)
+        return null;
+    // `closest` is on Element; EventTarget may be a Text node or other
+    // non-Element node. Narrow with an instanceof check.
+    const card = from instanceof Element ? from.closest('[data-composer-card]') : null;
+    if (card !== null) {
+        const ta = card.querySelector('textarea');
+        if (ta !== null)
+            return ta;
+    }
+    return null;
+}

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

@@ -0,0 +1,105 @@
+/**
+ * Prompt history store — pure functions over a string array.
+ *
+ * The store is a FIFO list of unique prompt strings, persisted to
+ * `localStorage`. Newest entries are at the end of the array. The
+ * navigation cursor walks backwards from the end (ArrowUp = older,
+ * ArrowDown = newer).
+ *
+ * The functions in this module are pure (no `localStorage` access) so
+ * they can be unit-tested without jsdom. The `HistoryStore` class below
+ * wires them to `localStorage` with try/catch containment — a quota
+ * exception or a disabled storage (private mode) degrades gracefully to
+ * an in-memory list that lives for the page lifetime.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/history
+ */
+/** localStorage key (versioned; bump on schema changes to start fresh). */
+export declare const STORAGE_KEY = "dsh-plugin-input-history:v1";
+/** Default capacity when none is configured. */
+export declare const DEFAULT_CAPACITY = 500;
+/**
+ * Append a prompt to the history.
+ *
+ * Rules:
+ *   - Empty / whitespace-only strings are ignored (the InputBar already
+ *     rejects them at submit, but defensive).
+ *   - When the new entry equals the most recent one, it is a no-op
+ *     (avoids stacking duplicates from rapid resends).
+ *   - When the new entry already exists earlier in the history, that
+ *     earlier occurrence is removed (recency wins; the prompt moves to
+ *     the end). This mirrors terminal shell behaviour.
+ *   - When the array would exceed `capacity`, the oldest entries are
+ *     dropped from the front (FIFO).
+ *
+ * @param history - the current history array (newest at end).
+ * @param prompt - the prompt to append.
+ * @param capacity - the maximum number of entries to retain.
+ * @returns the new history array (may be the same reference if no-op).
+ */
+export declare function appendHistory(history: readonly string[], prompt: string, capacity?: number): string[];
+/**
+ * Navigation cursor for walking the history.
+ *
+ * The cursor is `null` when the user is not navigating (i.e. they are
+ * typing a fresh draft). ArrowUp sets it to the last index, then
+ * decrements; ArrowDown increments; when it would exceed `history.length
+ * - 1`, it returns to `null` (meaning "restore the in-progress draft").
+ *
+ * @param current - the current cursor (null = not navigating).
+ * @param total - the total number of history entries.
+ * @param dir - `'up'` (older) or `'down'` (newer).
+ * @returns the next cursor, or `null` when navigation falls off the
+ *   newest end (caller should restore the saved draft).
+ */
+export declare function nextIndex(current: number | null, total: number, dir: 'up' | 'down'): number | null;
+/**
+ * Read the history entry at a cursor, or `null` when the cursor is null.
+ *
+ * @param history - the history array.
+ * @param cursor - the navigation cursor.
+ * @returns the prompt at the cursor, or `null`.
+ */
+export declare function entryAt(history: readonly string[], cursor: number | null): string | null;
+/**
+ * History store bound to `localStorage`.
+ *
+ * The store reads once on construction (or on `reload()`) and keeps an
+ * in-memory copy. Writes go to both memory and `localStorage` inside a
+ * try/catch — a quota exception leaves the in-memory copy authoritative
+ * for the rest of the page lifetime. This trades cross-tab consistency
+ * for resilience: the store never throws on a write, and the worst case
+ * is that a tab keeps its own view until refresh.
+ *
+ * Cross-tab sync is intentionally NOT implemented: prompt history is
+ * append-mostly and a stale read across tabs is harmless (the next
+ * append corrects it). Listening to the `storage` event would add
+ * reactivity that the navigation UI does not need.
+ */
+export declare class HistoryStore {
+    private readonly capacity;
+    private items;
+    private readonly storage;
+    private readonly key;
+    /**
+     * @param capacity - maximum entries to retain (FIFO).
+     * @param storage - the storage backend (defaults to `localStorage` when available).
+     * @param key - the storage key (defaults to {@link STORAGE_KEY}).
+     */
+    constructor(capacity?: number, storage?: Storage | null, key?: string);
+    /** Current history snapshot (newest at end). */
+    get list(): readonly string[];
+    /** Number of entries currently stored. */
+    get length(): number;
+    /** Reload from storage (e.g. after a suspected external edit). Truncates to the current capacity. */
+    reload(): void;
+    /**
+     * Append a prompt and persist. See {@link appendHistory} for rules.
+     * @returns the new history snapshot.
+     */
+    append(prompt: string): readonly string[];
+    /** Clear all history (used by tests and a future "clear" UI). */
+    clear(): void;
+    private readFromStorage;
+    private writeToStorage;
+}