@huanlin/dsh-plugin-input-history 0.1.0

package/lib/types/client/history.js

@@ -0,0 +1,203 @@
+/**
+ * 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 const STORAGE_KEY = 'dsh-plugin-input-history:v1';
+/** Default capacity when none is configured. */
+export 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 function appendHistory(history, prompt, capacity = DEFAULT_CAPACITY) {
+    const trimmed = prompt.trim();
+    if (trimmed === '')
+        return history;
+    // Latest-equal with no earlier duplicate: true no-op (same reference).
+    // When an earlier duplicate exists, the filter below removes it so the
+    // entry moves to the end (recency wins).
+    const lastIndex = history.lastIndexOf(trimmed);
+    if (lastIndex !== -1 && lastIndex === history.length - 1 && history.indexOf(trimmed) === lastIndex) {
+        return history;
+    }
+    // Remove any earlier occurrence (recency wins).
+    const filtered = history.filter(item => item !== trimmed);
+    filtered.push(trimmed);
+    // FIFO: drop oldest entries from the front.
+    const cap = Math.max(1, capacity);
+    if (filtered.length > cap) {
+        return filtered.slice(filtered.length - cap);
+    }
+    return filtered;
+}
+/**
+ * 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 function nextIndex(current, total, dir) {
+    if (total === 0)
+        return null;
+    if (dir === 'up') {
+        if (current === null)
+            return total - 1;
+        if (current <= 0)
+            return 0;
+        return current - 1;
+    }
+    // dir === 'down'
+    if (current === null)
+        return null;
+    if (current >= total - 1)
+        return null;
+    return current + 1;
+}
+/**
+ * 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 function entryAt(history, cursor) {
+    if (cursor === null)
+        return null;
+    if (cursor < 0 || cursor >= history.length)
+        return null;
+    return history[cursor] ?? 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 class HistoryStore {
+    capacity;
+    items;
+    storage;
+    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 = DEFAULT_CAPACITY, storage, key = STORAGE_KEY) {
+        this.capacity = capacity;
+        this.storage = storage ?? safeLocalStorage();
+        this.key = key;
+        this.items = this.readFromStorage();
+    }
+    /** Current history snapshot (newest at end). */
+    get list() {
+        return this.items;
+    }
+    /** Number of entries currently stored. */
+    get length() {
+        return this.items.length;
+    }
+    /** Reload from storage (e.g. after a suspected external edit). Truncates to the current capacity. */
+    reload() {
+        const loaded = this.readFromStorage();
+        const cap = Math.max(1, this.capacity);
+        this.items = loaded.length > cap ? loaded.slice(loaded.length - cap) : loaded;
+    }
+    /**
+     * Append a prompt and persist. See {@link appendHistory} for rules.
+     * @returns the new history snapshot.
+     */
+    append(prompt) {
+        this.items = appendHistory(this.items, prompt, this.capacity);
+        this.writeToStorage();
+        return this.items;
+    }
+    /** Clear all history (used by tests and a future "clear" UI). */
+    clear() {
+        this.items = [];
+        this.writeToStorage();
+    }
+    readFromStorage() {
+        if (this.storage === null)
+            return [];
+        try {
+            const raw = this.storage.getItem(this.key);
+            if (raw === null)
+                return [];
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed))
+                return [];
+            return parsed.filter((item) => typeof item === 'string');
+        }
+        catch {
+            return [];
+        }
+    }
+    writeToStorage() {
+        if (this.storage === null)
+            return;
+        try {
+            this.storage.setItem(this.key, JSON.stringify(this.items));
+        }
+        catch {
+            // Quota exceeded, private mode, or disabled storage: keep the
+            // in-memory copy authoritative for the rest of the page lifetime.
+        }
+    }
+}
+/** Safe accessor for `localStorage` that returns null on any failure. */
+function safeLocalStorage() {
+    try {
+        if (typeof localStorage === 'undefined')
+            return null;
+        return localStorage;
+    }
+    catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * IME-composition key guard.
+ *
+ * While a Chinese/Japanese/Korean input method is composing (the user is
+ * picking a candidate from the IME window), every pressed key BELONGS to
+ * the input method: arrows move the candidate highlight, Enter/Space
+ * confirm the composition, Escape cancels it. Page code must not process
+ * those keys — a history-navigation handler that calls `preventDefault()`
+ * on ArrowUp/ArrowDown during composition would silently break the IME:
+ * candidates stop responding, the composition gets torn apart, and only
+ * bare letters come out.
+ *
+ * The composition signal follows the DSH core convention (InputBar's IME
+ * guard, issue #535): `isComposing` for modern engines, keyCode 229 as
+ * the legacy signal engines emit without isComposing.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/ime
+ */
+/** The pure decision: is this keyboard event part of an IME composition? */
+export declare function isImeComposition(event: {
+    isComposing: boolean;
+    keyCode: number;
+}): boolean;

package/lib/types/client/ime.js

@@ -0,0 +1,22 @@
+/**
+ * IME-composition key guard.
+ *
+ * While a Chinese/Japanese/Korean input method is composing (the user is
+ * picking a candidate from the IME window), every pressed key BELONGS to
+ * the input method: arrows move the candidate highlight, Enter/Space
+ * confirm the composition, Escape cancels it. Page code must not process
+ * those keys — a history-navigation handler that calls `preventDefault()`
+ * on ArrowUp/ArrowDown during composition would silently break the IME:
+ * candidates stop responding, the composition gets torn apart, and only
+ * bare letters come out.
+ *
+ * The composition signal follows the DSH core convention (InputBar's IME
+ * guard, issue #535): `isComposing` for modern engines, keyCode 229 as
+ * the legacy signal engines emit without isComposing.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/ime
+ */
+/** The pure decision: is this keyboard event part of an IME composition? */
+export function isImeComposition(event) {
+    return event.isComposing || event.keyCode === 229;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * dsh-plugin-input-history — browser half.
+ *
+ * Two registrations:
+ *   - `conversation.composer.dock` list slot (id `dsh-plugin-input-history`,
+ *     order 100) — renders an invisible anchor that collects history from
+ *     `session.nodes` every render. The dock is session-scoped; DSH treats
+ *     blank sessions as "hero" and suppresses the dock, so history
+ *     collection only runs in active sessions. That is fine: the first
+ *     message in a blank session is collected after the session becomes
+ *     active (the message makes it non-blank).
+ *   - A document-level `keydown` listener attached in `apply` (NOT in the
+ *     dock component) — this ensures the listener is always active,
+ *     including in hero/blank mode where the dock is suppressed. The
+ *     listener uses the native `value` setter + `dispatchEvent('input')`
+ *     to feed history text into the textarea, which triggers InputBar's
+ *     `onChange` → `keyboard.setDraft` — the same path the user's typing
+ *     takes.
+ *
+ * History is collected from `user` and `steering` conversation nodes as
+ * they appear in any session's `ConversationSnapshot`, persisted to
+ * `localStorage` (FIFO, 500 entries), and shared across all sessions
+ * in the same browser profile.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type InputHistoryKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The dock's aria-label + future settings row copy. */
+        'dsh-plugin-input-history': InputHistoryKey;
+    }
+}
+/** Required services: slots + locale. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register the dock + attach the keydown listener.
+ *
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/index.js

@@ -0,0 +1,147 @@
+/**
+ * dsh-plugin-input-history — browser half.
+ *
+ * Two registrations:
+ *   - `conversation.composer.dock` list slot (id `dsh-plugin-input-history`,
+ *     order 100) — renders an invisible anchor that collects history from
+ *     `session.nodes` every render. The dock is session-scoped; DSH treats
+ *     blank sessions as "hero" and suppresses the dock, so history
+ *     collection only runs in active sessions. That is fine: the first
+ *     message in a blank session is collected after the session becomes
+ *     active (the message makes it non-blank).
+ *   - A document-level `keydown` listener attached in `apply` (NOT in the
+ *     dock component) — this ensures the listener is always active,
+ *     including in hero/blank mode where the dock is suppressed. The
+ *     listener uses the native `value` setter + `dispatchEvent('input')`
+ *     to feed history text into the textarea, which triggers InputBar's
+ *     `onChange` → `keyboard.setDraft` — the same path the user's typing
+ *     takes.
+ *
+ * History is collected from `user` and `steering` conversation nodes as
+ * they appear in any session's `ConversationSnapshot`, persisted to
+ * `localStorage` (FIFO, 500 entries), and shared across all sessions
+ * in the same browser profile.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client
+ */
+import { HistoryDock, getHistoryStore } from "./HistoryDock.js";
+import { isImeComposition } from "./ime.js";
+import { cursorLineInfo, findComposerTextarea } from "./dom.js";
+import { nextIndex, entryAt } from "./history.js";
+import { en, NS, zh } from "./locales.js";
+/** Required services: slots + locale. */
+export const inject = ['slots', 'locale'];
+/**
+ * Navigation cursor + saved draft for the keydown listener. Module-scoped
+ * because the listener is attached once in `apply` and must persist across
+ * dock mount/unmount cycles.
+ */
+let navCursor = null;
+let savedDraft = null;
+/**
+ * Client plugin body: register the dock + attach the keydown listener.
+ *
+ * @param ctx - client root context.
+ */
+export function apply(ctx) {
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-plugin-input-history: dictionaries');
+    // The dock collects history from session.nodes. It is session-scoped;
+    // in hero/blank mode it is suppressed, but the keydown listener below
+    // still works (it reads from the module-scope HistoryStore, which
+    // persists across dock mount/unmount cycles via localStorage).
+    ctx.slots.inject('conversation.composer.dock', () => ctx.slots.register({
+        name: 'conversation.composer.dock',
+        id: 'dsh-plugin-input-history',
+        order: 100,
+        locale: NS,
+    }, HistoryDock));
+    // Attach the document-level keydown listener. This lives in `apply`
+    // (not in the dock component) so it stays active even when the dock is
+    // suppressed (hero/blank sessions — ConversationRoot.tsx:79-80 treats
+    // blank sessions as hero, and line 156 skips the dock render).
+    ctx.effect(() => {
+        if (typeof document === 'undefined')
+            return () => { };
+        const handler = (event) => {
+            if (event.key !== 'ArrowUp' && event.key !== 'ArrowDown')
+                return;
+            if (isImeComposition(event))
+                return;
+            if (event.defaultPrevented)
+                return;
+            const textarea = findComposerTextarea(event.target);
+            if (textarea === null)
+                return;
+            if (event.target !== textarea)
+                return;
+            // Skip if the textarea is readOnly or disabled — hero mode's
+            // workspace-picker trigger, or a submitting machine phase.
+            if (textarea.readOnly || textarea.disabled)
+                return;
+            const store = getHistoryStore();
+            const history = store.list;
+            // Multi-line boundary check.
+            const info = cursorLineInfo(textarea.value, textarea.selectionStart, textarea.selectionEnd);
+            if (event.key === 'ArrowUp' && !info.atFirstLine)
+                return;
+            if (event.key === 'ArrowDown' && !info.atLastLine)
+                return;
+            const dir = event.key === 'ArrowUp' ? 'up' : 'down';
+            const next = nextIndex(navCursor, history.length, dir);
+            // Down off the newest end: restore the saved draft (if any).
+            if (next === null) {
+                const saved = savedDraft;
+                navCursor = null;
+                if (saved !== null) {
+                    setNativeTextareaValue(textarea, saved);
+                    savedDraft = null;
+                }
+                event.preventDefault();
+                return;
+            }
+            // Entering history: save the current draft the first time we
+            // navigate away from "not navigating".
+            if (navCursor === null && savedDraft === null) {
+                savedDraft = textarea.value;
+            }
+            const entry = entryAt(history, next);
+            if (entry === null)
+                return;
+            navCursor = next;
+            setNativeTextareaValue(textarea, entry);
+            event.preventDefault();
+        };
+        document.addEventListener('keydown', handler, false);
+        return () => {
+            document.removeEventListener('keydown', handler, false);
+        };
+    }, 'dsh-plugin-input-history: keydown listener');
+}
+/**
+ * Set the textarea value via the native prototype setter and dispatch an
+ * `input` event so React's controlled-component onChange fires.
+ *
+ * React 18 tracks the textarea's value internally; directly assigning
+ * `textarea.value = x` does NOT trigger React's onChange because React's
+ * value tracker compares against its last-seen value. Using the native
+ * prototype setter bypasses React's tracker, and the dispatched `input`
+ * event makes React detect the change and run InputBar's `onChange` →
+ * `keyboard.setDraft(next)`. This is the same technique used by
+ * browser automation libraries (Playwright, Testing Library) to simulate
+ * user typing in React controlled inputs.
+ *
+ * @param textarea - the target textarea element.
+ * @param value - the new value to set.
+ */
+function setNativeTextareaValue(textarea, value) {
+    const proto = window.HTMLTextAreaElement.prototype;
+    const descriptor = Object.getOwnPropertyDescriptor(proto, 'value');
+    if (descriptor === undefined || descriptor.set === undefined) {
+        // Fallback: direct assignment (may not trigger React onChange in
+        // all browsers, but better than nothing).
+        textarea.value = value;
+        return;
+    }
+    descriptor.set.call(textarea, value);
+    textarea.dispatchEvent(new Event('input', { bubbles: true }));
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Locale dictionaries for dsh-plugin-input-history.
+ *
+ * The plugin renders nothing visible — the only user-facing copy is the
+ * `aria-label` on the invisible dock anchor (for screen readers) and a
+ * future settings row label.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/locales
+ */
+/** All copy keys for the dsh-plugin-input-history namespace. */
+export type InputHistoryKey = 'ariaLabel' | 'restoredDraft' | 'noHistory';
+/** Locale namespace id (matches the cordis.patch.yml plugin id). */
+export declare const NS = "dsh-plugin-input-history";
+/** English dictionary. */
+export declare const en: Record<InputHistoryKey, string>;
+/** Chinese dictionary. */
+export declare const zh: Record<InputHistoryKey, string>;

package/lib/types/client/locales.js

@@ -0,0 +1,23 @@
+/**
+ * Locale dictionaries for dsh-plugin-input-history.
+ *
+ * The plugin renders nothing visible — the only user-facing copy is the
+ * `aria-label` on the invisible dock anchor (for screen readers) and a
+ * future settings row label.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/locales
+ */
+/** Locale namespace id (matches the cordis.patch.yml plugin id). */
+export const NS = 'dsh-plugin-input-history';
+/** English dictionary. */
+export const en = {
+    ariaLabel: 'Prompt history navigation (ArrowUp/ArrowDown)',
+    restoredDraft: 'Restored in-progress draft',
+    noHistory: 'No prompt history yet',
+};
+/** Chinese dictionary. */
+export const zh = {
+    ariaLabel: '提示词历史导航（上/下方向键）',
+    restoredDraft: '已恢复正在编辑的草稿',
+    noHistory: '暂无提示词历史',
+};

package/lib/types/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * dsh-plugin-input-history — host plugin entry.
+ *
+ * Client-only plugin: the host half has no runtime work. The browser half
+ * (`./client`) registers an invisible entry in `conversation.composer.dock`
+ * that attaches a document-level `keydown` listener and implements
+ * terminal-style prompt history navigation (ArrowUp/ArrowDown) over the
+ * composer textarea.
+ *
+ * History is collected from `user` and `steering` conversation nodes as
+ * they appear in any session's `ConversationSnapshot`, persisted to
+ * `localStorage` (FIFO, capacity 500), and shared across all sessions
+ * in the same browser profile.
+ *
+ * @module @huanlin/dsh-plugin-input-history
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "dsh-plugin-input-history";
+export declare const inject: string[];
+/**
+ * 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).
+ */
+export declare function apply(_ctx: Context): void;

package/lib/types/index.js

@@ -0,0 +1,26 @@
+/**
+ * dsh-plugin-input-history — host plugin entry.
+ *
+ * Client-only plugin: the host half has no runtime work. The browser half
+ * (`./client`) registers an invisible entry in `conversation.composer.dock`
+ * that attaches a document-level `keydown` listener and implements
+ * terminal-style prompt history navigation (ArrowUp/ArrowDown) over the
+ * composer textarea.
+ *
+ * History is collected from `user` and `steering` conversation nodes as
+ * they appear in any session's `ConversationSnapshot`, persisted to
+ * `localStorage` (FIFO, capacity 500), and shared across all sessions
+ * in the same browser profile.
+ *
+ * @module @huanlin/dsh-plugin-input-history
+ */
+export const name = 'dsh-plugin-input-history';
+export 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).
+ */
+export function apply(_ctx) {
+    // Client-only plugin: all work happens in src/client/index.ts.
+}

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@huanlin/dsh-plugin-input-history`.
+ *
+ * @module @huanlin/dsh-plugin-input-history/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "dsh-plugin-input-history-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/types/invariant.js

@@ -0,0 +1,26 @@
+/**
+ * Package-owned invariant companion for `@huanlin/dsh-plugin-input-history`.
+ *
+ * @module @huanlin/dsh-plugin-input-history/invariant
+ */
+const PACKAGE_NAME = '@huanlin/dsh-plugin-input-history';
+/** Cordis companion plugin name. */
+export const name = 'dsh-plugin-input-history-invariant';
+/** Service required before the companion can reserve package ownership. */
+export 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.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */