@huanlin/dsh-plugin-input-history 0.1.2 → 0.3.0

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

@@ -1,57 +1,81 @@
-/**
- * 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;
+/**
+ * DOM helpers for the Lexical composer surface.
+ *
+ * The DSH composer's text surface is a Lexical-bound contenteditable div,
+ * not a textarea: plugins cannot obtain a React ref or a slot-currency
+ * handle to it, and writing text goes through `inputActions.setDraft` (the
+ * public machine action), not the DOM. What remains DOM-bound is geometry
+ * and focus: locating the editable the keystroke targeted, detecting an
+ * open trigger menu, and deciding whether the collapsed caret sits on the
+ * first/last visual line of a multi-line draft.
+ *
+ * All markers queried here are internal to `@deepseek-ai/dsh-client-ui-conversation`
+ * (`InputBar.tsx` / `ComposerContentEditable.tsx`) or
+ * `@deepseek-ai/dsh-client-ui-input-trigger` (`MenuView.tsx`); they are
+ * stable but undocumented, and the locators below are the single point to
+ * update if upstream changes them.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/dom
+ */
+/** Line-boundary decision for a collapsed caret. */
+export interface LineBoundary {
+    /** True when the caret is collapsed and on the first visual line. */
+    readonly atFirstLine: boolean;
+    /** True when the caret is collapsed and on the last visual line. */
+    readonly atLastLine: boolean;
+}
+/**
+ * Pure decision over caret geometry: where a caret resting at `caretTop`
+ * sits relative to the box whose visual line tops are `lineTops` (ascending,
+ * one entry per visual line, viewport coordinates).
+ *
+ * @param caretTop - viewport `top` of the collapsed caret's box.
+ * @param lineTops - viewport `top` of each visual line, ascending.
+ * @param tolerance - px slop absorbing subpixel rounding between the caret
+ *   rect and its line's rect.
+ * @returns the boundary flags; an empty `lineTops` (empty editable) is
+ *   treated as a single virtual line, so both flags are true.
+ */
+export declare function boundaryFromLineTops(caretTop: number, lineTops: readonly number[], tolerance: number): LineBoundary;
+/**
+ * Locate the DSH composer editable the event targeted.
+ *
+ * Walks from the event target up to the closest `[data-composer-card]`
+ * ancestor, queries the `[data-composer-input]` contenteditable inside it,
+ * and confirms the target sits inside that editable (keystrokes on the
+ * card's buttons and chrome do not navigate history). Returns `null` when
+ * the target is not inside the composer editable.
+ *
+ * @param from - the event target (or any node inside the composer editable).
+ * @returns the editable element, or `null` when not found.
+ */
+export declare function findComposerEditable(from: EventTarget | null): HTMLElement | null;
+/**
+ * Detect an open trigger (slash-command / @-mention) menu inside the
+ * composer card that owns `editable`.
+ *
+ * While the menu is open, ArrowUp/ArrowDown move the highlighted row and
+ * must not recall history. The menu renders inside the same
+ * `[data-composer-card]` as the editable and carries the stable
+ * `data-trigger-menu` marker.
+ *
+ * @param editable - the composer editable element.
+ * @returns the menu element, or `null` when no menu is open.
+ */
+export declare function findTriggerMenu(editable: HTMLElement): Element | null;
+/**
+ * Decide the collapsed caret's line boundary inside the composer editable.
+ *
+ * Compares the caret's viewport box against the editable content's visual
+ * line boxes (`Range.getClientRects()` yields one rect per line fragment;
+ * fragments of the same visual line share a top within subpixel slop, so
+ * tops are deduped with a 2px threshold). A non-collapsed selection and a
+ * geometry-less environment (headless/jsdom) both return `null`, which the
+ * caller must treat as "do not navigate".
+ *
+ * @param editable - the composer editable element.
+ * @param tolerance - px slop between the caret rect and its line rect
+ *   (defaults to 4px).
+ * @returns the boundary flags, or `null` when they cannot be determined.
+ */
+export declare function caretLineBoundary(editable: HTMLElement, tolerance?: number): LineBoundary | null;

package/lib/types/client/dom.js

@@ -1,99 +1,142 @@
-/**
- * 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;
-}
+/**
+ * DOM helpers for the Lexical composer surface.
+ *
+ * The DSH composer's text surface is a Lexical-bound contenteditable div,
+ * not a textarea: plugins cannot obtain a React ref or a slot-currency
+ * handle to it, and writing text goes through `inputActions.setDraft` (the
+ * public machine action), not the DOM. What remains DOM-bound is geometry
+ * and focus: locating the editable the keystroke targeted, detecting an
+ * open trigger menu, and deciding whether the collapsed caret sits on the
+ * first/last visual line of a multi-line draft.
+ *
+ * All markers queried here are internal to `@deepseek-ai/dsh-client-ui-conversation`
+ * (`InputBar.tsx` / `ComposerContentEditable.tsx`) or
+ * `@deepseek-ai/dsh-client-ui-input-trigger` (`MenuView.tsx`); they are
+ * stable but undocumented, and the locators below are the single point to
+ * update if upstream changes them.
+ *
+ * @module @huanlin/dsh-plugin-input-history/client/dom
+ */
+/**
+ * Pure decision over caret geometry: where a caret resting at `caretTop`
+ * sits relative to the box whose visual line tops are `lineTops` (ascending,
+ * one entry per visual line, viewport coordinates).
+ *
+ * @param caretTop - viewport `top` of the collapsed caret's box.
+ * @param lineTops - viewport `top` of each visual line, ascending.
+ * @param tolerance - px slop absorbing subpixel rounding between the caret
+ *   rect and its line's rect.
+ * @returns the boundary flags; an empty `lineTops` (empty editable) is
+ *   treated as a single virtual line, so both flags are true.
+ */
+export function boundaryFromLineTops(caretTop, lineTops, tolerance) {
+    if (lineTops.length === 0)
+        return { atFirstLine: true, atLastLine: true };
+    return {
+        atFirstLine: caretTop <= lineTops[0] + tolerance,
+        atLastLine: caretTop >= lineTops[lineTops.length - 1] - tolerance,
+    };
+}
+/**
+ * Locate the DSH composer editable the event targeted.
+ *
+ * Walks from the event target up to the closest `[data-composer-card]`
+ * ancestor, queries the `[data-composer-input]` contenteditable inside it,
+ * and confirms the target sits inside that editable (keystrokes on the
+ * card's buttons and chrome do not navigate history). Returns `null` when
+ * the target is not inside the composer editable.
+ *
+ * @param from - the event target (or any node inside the composer editable).
+ * @returns the editable element, or `null` when not found.
+ */
+export function findComposerEditable(from) {
+    if (typeof document === 'undefined')
+        return null;
+    if (from === null || !(from instanceof Element))
+        return null;
+    const card = from.closest('[data-composer-card]');
+    if (card === null)
+        return null;
+    const editable = card.querySelector('[data-composer-input]');
+    if (editable === null)
+        return null;
+    return editable.contains(from) ? editable : null;
+}
+/**
+ * Detect an open trigger (slash-command / @-mention) menu inside the
+ * composer card that owns `editable`.
+ *
+ * While the menu is open, ArrowUp/ArrowDown move the highlighted row and
+ * must not recall history. The menu renders inside the same
+ * `[data-composer-card]` as the editable and carries the stable
+ * `data-trigger-menu` marker.
+ *
+ * @param editable - the composer editable element.
+ * @returns the menu element, or `null` when no menu is open.
+ */
+export function findTriggerMenu(editable) {
+    const card = editable.closest('[data-composer-card]');
+    return card === null ? null : card.querySelector('[data-trigger-menu]');
+}
+/**
+ * Decide the collapsed caret's line boundary inside the composer editable.
+ *
+ * Compares the caret's viewport box against the editable content's visual
+ * line boxes (`Range.getClientRects()` yields one rect per line fragment;
+ * fragments of the same visual line share a top within subpixel slop, so
+ * tops are deduped with a 2px threshold). A non-collapsed selection and a
+ * geometry-less environment (headless/jsdom) both return `null`, which the
+ * caller must treat as "do not navigate".
+ *
+ * @param editable - the composer editable element.
+ * @param tolerance - px slop between the caret rect and its line rect
+ *   (defaults to 4px).
+ * @returns the boundary flags, or `null` when they cannot be determined.
+ */
+export function caretLineBoundary(editable, tolerance = 4) {
+    const selection = window.getSelection();
+    if (selection === null || selection.rangeCount === 0)
+        return null;
+    if (!selection.isCollapsed)
+        return null;
+    const caretTop = caretTopOf(selection);
+    if (caretTop === null)
+        return null;
+    const lineTops = contentLineTops(editable);
+    if (lineTops === null)
+        return null;
+    return boundaryFromLineTops(caretTop, lineTops, tolerance);
+}
+/** Viewport `top` of the collapsed caret's box, or `null` when unmeasurable. */
+function caretTopOf(selection) {
+    const rects = selection.getRangeAt(0).getClientRects();
+    for (let i = 0; i < rects.length; i++) {
+        const rect = rects[i];
+        if (rect.height === 0 && rect.width === 0)
+            continue;
+        return rect.top;
+    }
+    // Some engines report a zero-box collapsed caret; the anchor's element
+    // box is the line the caret sits on (the same ruler InputBar's reveal uses).
+    const anchor = selection.anchorNode;
+    const el = anchor instanceof HTMLElement ? anchor : anchor?.parentElement;
+    return el === undefined || el === null ? null : el.getBoundingClientRect().top;
+}
+/** Ascending, deduped tops of the editable content's visual lines; `null` without geometry. Empty for an empty editable. */
+function contentLineTops(editable) {
+    const range = document.createRange();
+    range.selectNodeContents(editable);
+    const rects = range.getClientRects();
+    const tops = [];
+    for (let i = 0; i < rects.length; i++) {
+        const rect = rects[i];
+        if (rect.height === 0 && rect.width === 0)
+            continue;
+        const top = rect.top;
+        // Rects come in document order; fragments of one visual line differ by
+        // subpixel amounts, real lines by a full line height.
+        if (tops.length === 0 || Math.abs(top - tops[tops.length - 1]) > 2)
+            tops.push(top);
+    }
+    return tops;
+}

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

@@ -1,42 +1,34 @@
-/**
- * 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;
+/**
+ * dsh-plugin-input-history — browser half.
+ *
+ * One registration: the `conversation.composer.dock` list slot (id
+ * `dsh-plugin-input-history`, order 100) mounts the invisible dock entry
+ * that owns both plugin behaviors — prompt-history collection from the
+ * Chat target's user/steering nodes, and the capture-phase document
+ * keydown listener that navigates the composer draft through
+ * `inputActions.setDraft`. See [HistoryDock.tsx](./HistoryDock.tsx) for
+ * the data flow; the dock is session-scoped, so in hero/blank mode the
+ * plugin is dormant (no input machine exists there to drive).
+ *
+ * History is collected from `user` and `steering` chat nodes of any active
+ * session, 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 { Context } from '@deepseek-ai/cordis';
+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 + locale dictionaries.
+ *
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: Context): void;