dsh-rewind-plugin 0.20.0 → 0.21.1

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

@@ -1,301 +0,0 @@
-/**
- * dsh-rewind portal half: the per-user-message ↶ rewind button, rendered as a
- * React portal inside the message's `MessageIconActions` row.
- *
- * Why portals (aligned with the copy button's own rendering): the copy button
- * is a React child of the actions row, painted in the same commit as the
- * bubble. A pure-DOM `appendChild` (the earlier approach) lands one microtask
- * later and re-runs a full-transcript scan on EVERY mutation, which can push
- * the paint of a newly sent bubble — the "occasional hiccup before the bubble
- * shows". Portals let React own the button lifecycle (mount/unmount with the
- * row, no orphaned buttons, no manual re-attach after harness re-renders),
- * and the target collection is coalesced (one refresh per mutation batch) and
- * diffed (no setState churn when nothing changed).
- *
- * Mount point: the plugin registers a session-scoped bridge into the harness's
- * `conversation.session.header.actions` list slot. The bridge renders NO
- * header UI — it only portals buttons into the user rows of the session the
- * harness mounts it for. That slot is the harness-native way to get a
- * per-session React mount without touching any source; the registration is
- * typed structurally (see `SlotsLike`) so the plugin never imports the
- * conversation UI package's types and survives its version drift.
- *
- * COUPLING NOTE — HIGH. There is no harness interface for a per-user-message
- * action (see docs/compat/audit.md): `MessageIconActions.extraActions` and the
- * `conversation.chat.assistant-actions` slot are wired for assistant messages
- * only, and no per-user-message action slot exists. So this portal targets
- * undocumented internal structure — the `data-chat-flow-kind`,
- * `data-chat-anchor-key`, `data-composer-input`, `data-composer-card` and
- * `data-pending-steering` attributes plus the `anchorSeq` field read in
- * `client/hidden.ts`. Those are harness-internal and may change with the UI;
- * this module (and `hidden.ts`) must be re-adapted to follow, and is the
- * migration target when a first-class user-action slot or an official renderer
- * hook surface appears. The coupling is accepted deliberately because a
- * standards-conformant alternative does not exist today; it is not a defect to
- * be removed while the DOM-portal approach stands.
- *
- * Re-verified against 0.1.6-alpha.2: the five remaining anchors still exist (the
- * anchor key and flow kind still come from `ChatNodeSeat`, values `user` /
- * `steering`); only `data-time-hover-root` is gone, and nothing read it.
- *
- * @module dsh-rewind/client/portals
- */
-import { type ReactNode } from 'react';
-import type { SessionFace } from '@deepseek-ai/dsh-api-session-controller/client';
-import { type ChatOf, type ChatWatch, type HiddenChat, type MessageImageRef } from './hidden.ts';
-import type { RewindKey } from './locales.ts';
-type Translate = (key: RewindKey, params?: Record<string, unknown>) => string;
-/** One portal target: the actions row of a user/steering seat + its durable node. */
-export type PortalTarget = {
-    readonly kind: 'durable';
-    /** The seat's chat node key (React reconciliation + diff identity). */
-    readonly key: string;
-    /** The row's actions container (React portal target). */
-    readonly container: HTMLElement;
-    readonly seq: number;
-    readonly time: number;
-    readonly preview: string;
-} | {
-    readonly kind: 'pending';
-    /** `pending:${itemId}` — stable per inbox occurrence. */
-    readonly key: string;
-    /** The row's actions container (React portal target). */
-    readonly container: HTMLElement;
-    /** The host inbox occurrence the retract button addresses. */
-    readonly itemId: string;
-    /** Complete editable text; null when the message contains no text block. */
-    readonly text: string | null;
-    readonly preview: string;
-};
-/** Capabilities the session-scoped bridge receives from the plugin apply(). */
-export interface RewindBridgeDeps {
-    readonly sessionOf: (sessionId: string) => SessionFace | undefined;
-    /**
-     * Chat reader on the `uiConversation` "chat" view: every chat
-     * snapshot read goes through it. See `chatSnapshotOf` in hidden.ts.
-     */
-    readonly chatOf: ChatOf;
-    /**
-     * Subscribe to one session's live chat-update signal, so the composer refill
-     * waiting on an executed rewind's chat node can be woken when the chat
-     * snapshot changes. Passed through to `waitForCommand`.
-     */
-    readonly watchChat: ChatWatch;
-    /**
-     * Whether a session is the one the MAIN VIEW currently retains — the alpha.2
-     * replacement for the removed `SessionListState.current` (see
-     * `isMainViewSession` in index.ts). A predicate rather than "the current
-     * session id", so a multi-window client can never refill the wrong composer.
-     */
-    readonly isMainViewSession: (sessionId: string) => boolean;
-    readonly t: Translate;
-    readonly subscribeLocale: (cb: () => void) => () => void;
-    /**
-     * Session-aware composer writer (see `writeComposer`): the
-     * `conversation.input` facade `setDraft` when reachable, else the DOM fill.
-     * Session-scoped so the refill only lands in the session that just rewound.
-     */
-    readonly setComposerText: (sessionId: string, text: string) => boolean;
-    /**
-     * Session-aware image restorer (see `restoreImages` in index.ts): re-adds
-     * a withdrawn message's durable image references to that session's
-     * composer draft so a rewind of an image-bearing message does not lose
-     * the pictures. Optional — absent degrades to the text-only refill.
-     */
-    readonly restoreImages?: (sessionId: string, images: readonly MessageImageRef[]) => Promise<void>;
-}
-/** Structural face of the runtime slot service (see the module doc). */
-export interface SlotsLike {
-    inject(key: string, install: () => () => void): () => void;
-    /**
-     * One slot registration. `Face` is the injected business face the renderer
-     * decomposes (its `hooks` compartment is rebound as a `use<Name>` selector
-     * hook); `Props` is the COMPOSED props a component receives — the slot's
-     * runtime owner share, the locale seat, and that face — which is what the
-     * component is typed against, never the face alone.
-     */
-    register<P, Face = P>(entry: {
-        readonly name: string;
-        readonly id?: string;
-        readonly order?: number;
-        readonly key?: string;
-        readonly locale?: string;
-        readonly inject?: () => Face;
-    }, component: (props: P) => ReactNode): () => void;
-}
-/**
- * The session input facade's write face (structural, so the plugin
- * never imports the conversation UI package). `setDraft` replaces the whole
- * composer draft through the harness's own Lexical editor — the correct way
- * to restore the withdrawn text.
- */
-interface ComposerDraftWriter {
-    setDraft(text: string): void;
-    /**
-     * Return the keyboard to the composer with the caret it last held (the
-     * facade's own `focus`). Optional so the DOM fallback and older faces still
-     * restore the text.
-     */
-    focus?(): void;
-}
-/**
- * Fill the dsh composer with `text` through the `contenteditable`
- * DOM path. Used by `setComposerText` (the harness-facade-aware writer) as the
- * last-resort and by `runRewindAndFill` to put the withdrawn target message
- * back into the composer after a rewind. Best-effort — no composer match means
- * false, never a throw.
- */
-export declare function fillComposer(text: string): boolean;
-/**
- * Composer write: prefer the harness facade's `setDraft` (correct whole-draft
- * replace), then degrade to the DOM `fillComposer` (contenteditable). A facade
- * that throws (session teardown) is treated as absent so the DOM path still
- * restores the text. Never throws.
- * @param text - the withdrawn target message text.
- * @param facade - the session input draft writer, when reachable.
- * @returns whether a channel applied the text.
- */
-export declare function writeComposer(text: string, facade: ComposerDraftWriter | undefined): boolean;
-/**
- * Execute one rewind from the popover and, when it settles successfully,
- * put the withdrawn target message's text back into the composer so the
- * user can edit and re-send.
- *
- * THE COMPOSER FILL IS EVENT-DRIVEN: it runs only when THIS page performed
- * the rewind (the user clicked confirm moments ago). It must NEVER scan
- * loaded history for rewind commands: a session window opens with only
- * the tail page and grows via loadOlder, so a "command already in the
- * snapshot" cannot be told apart from "command executed in this page" —
- * the old baseline heuristic refilled withdrawn text into the composer
- * after switching sessions or restarting dsh.
- */
-export declare function runRewindAndFill(session: SessionFace, seq: number, mode: 'chat' | 'both', isMainViewSession: (sessionId: string) => boolean, chatOf: ChatOf, watchChat: ChatWatch, setComposerText: (sessionId: string, text: string) => boolean, restoreImages?: (sessionId: string, images: readonly MessageImageRef[]) => Promise<void>): Promise<void>;
-/**
- * Locate the actions container of a user/steering seat row — the element the
- * ↶ button portals into (the copy/branch IconActions row).
- *
- * The finder is STRUCTURAL on purpose: `MessageIconActions` marks this container
- * with `data-clock`, which names clock placement rather than the action row (the
- * old `data-time-hover-root` marker lived on the per-turn tail footer and is
- * gone in 0.1.6-alpha.2), so the container is located as the direct holder of
- * the copy `<button>` (the `MessageIconActions` container, which mounts that
- * button as a direct child).
- *
- * Returns undefined when no qualifying container is found; the caller refuses
- * to portal (never a crash, never a wrong attachment). Exported as a test seam
- * (see `collectTargets`) so the row-shape finder is exercised directly for
- * both durable and pending row shapes without a full React portal render.
- */
-export declare function actionsContainerOf(row: HTMLElement | undefined): HTMLElement | undefined;
-/**
- * Collect the portal targets of one session: user rows × snapshot nodes.
- * Exported as a test seam — the DOM→targets pairing that drives the ↶ button
- * is otherwise only reachable through a full React portal render.
- */
-export declare function collectTargets(chat: HiddenChat): readonly PortalTarget[];
-/**
- * The session-kind slice the durable-target gate reads — the session
- * snapshot's `subagent` cell, the Harness's own runtime signal for a
- * direct-subagent (child) session. Typed structurally so the plugin never
- * imports the session-controller snapshot contract.
- */
-export interface SessionKindLike {
-    /** Non-null exactly while this Session is addressed as a subagent child. */
-    readonly subagent: unknown;
-}
-/**
- * Whether a session is rewind-inert: a direct-subagent (child) session.
- *
- * The Harness refuses every generic Session RPC for a subagent-owned identity
- * (`session/agent-busy`, "use subagent delivery for this child session"), so
- * `/rewind` can never execute there — the command's own admission is the
- * refusal, before any handler runs. A wired-up ↶ button in such a session is
- * therefore dead UI that closes its popover and does nothing
- * (SiriLee/dsh-rewind#26). This mirrors the Harness's own slash-command
- * directory (which returns no commands for an addressed child), the pending
- * path's `collectPendingTargets` gate, and the Host's `isSubagentSession`
- * skips: a child session gets no rewind surface and records no snapshot.
- */
-export declare function isRewindInertSession(snapshot: SessionKindLike): boolean;
-/**
- * Collect the durable (sent-message) rewind targets of one session: none at all
- * for a rewind-inert subagent session, otherwise `collectTargets`' DOM→target
- * pairing. Kept separate from `collectTargets` so the session-kind gate is a
- * pure, directly testable decision.
- * @param snapshot - the session snapshot carrying the `subagent` cell.
- * @param chat - the session's chat snapshot, or undefined while unavailable.
- */
-export declare function collectDurableTargets(snapshot: SessionKindLike, chat: HiddenChat | undefined): readonly PortalTarget[];
-/**
- * The pending bubble row's compared text and its message-attachment block
- * count, read from a CLONE (the live row is never touched).
- *
- * Both the actions container and the message-attachment block are excluded from
- * the text: the copy button's Tooltip mounts its label inside that button, and
- * the attachment block renders text of its own (a file name/size, a lone
- * image's loading label) that no inbox row reproduces. The block is counted
- * instead, as the attachment half of the match key (`matchPendingRows`).
- *
- * The clone's counterpart is taken by query position, not by position among the
- * row's children: the harness renders the attachment block BEFORE the message
- * bubble, so "drop the first child" would drop the message text.
- *
- * @param row - one rendered `[data-pending-steering]` row.
- * @returns the compared text and the attachment block count.
- */
-export declare function bubbleTextOf(row: HTMLElement): {
-    readonly text: string;
-    readonly attachments: number;
-};
-interface RewindPortalsProps extends RewindBridgeDeps {
-    readonly sessionId: string;
-}
-/**
- * Session-scoped portal bridge: renders the ↶ button of every user message
- * row of the session the harness mounts it for. The refresh is coalesced
- * (one pass per microtask window via queueMicrotask) and diffed (setState is
- * skipped when the target set is unchanged), so the plugin never runs a
- * synchronous full-transcript scan inside a commit microtask.
- *
- * The refresh is driven by the three inputs its targets are made of: the chat
- * snapshot's visible order, the session's `inbox` projection (the pending
- * occurrences — see `syncInboxSubscription`), and the DOM (row/actions mounts,
- * via the scoped observer).
- */
-export declare function RewindPortals({ sessionId, sessionOf, chatOf, isMainViewSession, watchChat, t, subscribeLocale, setComposerText, restoreImages }: RewindPortalsProps): ReactNode;
-/** The current composer draft: the contenteditable `textContent`.
- * Empty when the composer is absent. Exported as a test seam (the
- * empty-composer guard in `retractPending`). */
-export declare function composerText(): string;
-/**
- * Withdraw one pre-sent (pending steering) message and every steering message
- * after it (the rollback point's "future"), WITHOUT interrupting the run.
- *
- * The message is still in the agent's next-step inbox, so the loop has not
- * claimed it into any request: removing it cannot change what the model is
- * generating. Stopping the run first (the durable-rewind rule) would throw
- * away in-flight work — a long tool call, a partial answer — for an edit the
- * model can never observe (SiriLee/dsh-rewind#27). Only the durable rewind
- * needs a stop, because it cuts the model-visible surface.
- *
- * 1. Remove the target and its future (steering only; queued stays) through
- *    the session's own `updateQueue` channel, oldest first.
- * 2. Put the target's own images back, then its text when the composer is
- *    empty (the empty-composer guard, so a draft is never clobbered).
- *
- * The realistic failure is `queue-item-not-found`: a step boundary claimed
- * the whole next-step batch a moment ago, so the message is now durable and
- * the durable row's regular rewind button takes over with no gap. Nothing is
- * removed then, and the composer is NOT refilled — refilling would invite a
- * duplicate send of a message the model has already received.
- */
-export declare function retractPending(session: SessionFace, itemId: string, text: string | null, setComposerText: (sessionId: string, text: string) => boolean, restoreImages?: (sessionId: string, images: readonly MessageImageRef[]) => Promise<void>): Promise<void>;
-/**
- * Build the slot-entry component for the plugin apply(): a tiny bridge that
- * injects the apply-time capabilities (session resolution, locale, rewind
- * runner) into the module-level `RewindPortals`.
- */
-export declare function createRewindBridge(deps: RewindBridgeDeps): (props: {
-    readonly sessionId: string;
-}) => ReactNode;
-export {};