@hydraharness/harness-client-ui-conversation 0.1.1-rc.6

package/lib/types/client/input/contract.d.ts

@@ -0,0 +1,340 @@
+/**
+ * Frozen input-machine contract. Types
+ * only. Three-tier visibility: business packages see InputState via the
+ * InputZone currency; the scoped input events carry the mutation verbs; the
+ * conversation wiring layer alone sees the full SessionInput. InputMachine
+ * (machine.ts) is package-private and never exported.
+ */
+import type { ClientContext, SnapshotStore } from '@hydraharness/harness-client-runtime/client';
+import type { Branded } from '@hydraharness/harness-brand';
+import type { ArbitrateKey, ArbitrateOutcome, CommandClaim, ConsumeTokenRequest, PickOutcome, ReferenceInsert, SubmitOutcome, TokenSpan } from '@hydraharness/harness-client-ui-input-trigger/client';
+import type { QueueRow } from '../contract/queue.ts';
+import type { InputSubmitMode } from '../contract/composer-submission.ts';
+/** Browser-runtime identity of one unsent image draft. */
+export type DraftAttachmentId = Branded<'DraftAttachmentId'>;
+/**
+ * The scoped-event application verbs: the hub's bail listeners call these,
+ * and the boolean answer IS the event's bail value (true ⟺ the machine
+ * accepted after phase and span/bare-token guards).
+ */
+export interface InputTarget {
+    /** Replace the trigger span with claim.token and enter claimed (span-CAS'd). */
+    beginCommand(claim: CommandClaim, span: TokenSpan): boolean;
+    /** Replace the trigger span with one reference occurrence (span-CAS'd). */
+    insertReference(ref: ReferenceInsert, span: TokenSpan): boolean;
+}
+/** Per-session input facade owned by the conversation wiring layer. */
+export interface SessionInput extends InputTarget, InputActions {
+    /**
+     * THE complexity sink: enter adjudication, submit transaction, and the default sink live inside.
+     * @param mode - delivery intent retained through asynchronous adjudication and serialization.
+     */
+    submit(mode?: InputSubmitMode): void;
+    /**
+     * Surface a notice outside the machine's own effect stream: detached
+     * command results and business notifications render through here.
+     * Session-routed — resolving the facade via SessionInputResolver.for(actx) lands
+     * the notice on that session's composer, so a result arriving after a
+     * session switch still reaches its own session.
+     * @param level - severity tier.
+     * @param text - notice body.
+     */
+    notify(level: 'info' | 'error', text: string): void;
+    /** Input state store (InputZone currency + decorations read here). */
+    readonly state: SnapshotStore<InputState>;
+}
+/** Session-addressed access to the per-session input facade. */
+export interface SessionInputResolver {
+    /** Resolve the facade for one session-scope ctx. */
+    for(actx: ClientContext): SessionInput;
+}
+/**
+ * The public input action face provided to every session-scope slot
+ * component: two stable-identity void callbacks, mirroring the
+ * useStore+actions convention. Command-style handles (track/arbitrate/space/
+ * undo/paste/…) stay InputBar-private and never ride this face.
+ */
+export interface InputActions {
+    /** Single public draft write path (full next draft; occurrence math via diff scan). */
+    setDraft(text: string): void;
+    /** Append ordered browser-owned image ids; busy admission phases refuse. */
+    addImages(ids: readonly DraftAttachmentId[]): boolean;
+    /** Remove one browser-owned image id; busy admission phases refuse. */
+    removeImage(id: DraftAttachmentId): void;
+    /** Drop ids whose browser-owned objects no longer exist. */
+    pruneImages(ids: readonly DraftAttachmentId[]): void;
+    /** Append browser-selected text attachments without changing the draft. */
+    addBrowserAnnotations?(ids: readonly DraftAttachmentId[]): boolean;
+    /** Remove one browser-selected text attachment. */
+    removeBrowserAnnotation?(id: DraftAttachmentId): void;
+    /** Drop browser-selected text ids whose objects no longer exist. */
+    pruneBrowserAnnotations?(ids: readonly DraftAttachmentId[]): void;
+    /** Update the optional user comment carried by one browser annotation. */
+    updateBrowserAnnotationComment?(id: DraftAttachmentId, comment: string): void;
+    /** Enter submission (adjudication / claim transaction / default sink inside). */
+    submit(): void;
+}
+/** One surfaced notice (command results, adjudication failures). seq keys re-render of repeats. */
+export interface InputNotice {
+    readonly level: 'info' | 'error';
+    readonly text: string;
+    readonly seq: number;
+}
+/**
+ * The InputBar-exclusive keyboard/DOM command face: synchronous
+ * returns and event-handler semantics that must not enter the public provide
+ * channel. Handed to the composer-bar entry through its own inject —
+ * package-internal, never across a plugin boundary. The session shell
+ * satisfies it structurally.
+ */
+export interface ComposerKeyboard {
+    /** Live machine state for event-handler reads (render reads go through useInput). */
+    readonly snapshot: InputState;
+    /** Draft write with the DOM-observed edit shape (narrows occurrence math). */
+    setDraft(text: string, editRange?: EditRange): void;
+    /** Submit with an explicit delivery mode resolved by the keyboard policy. */
+    submit(mode: InputSubmitMode): void;
+    /**
+     * Steer every still-pending queued message into the running turn (the
+     * empty-draft accelerated-Enter gesture; the queue dock's per-row steer
+     * button is the same operation applied to the whole queue).
+     */
+    steerQueue(): void;
+    undo(): void;
+    redo(): void;
+    /** Paste over the selection (sync components ride the same transaction). */
+    pasteBegin(text: string, selection: EditSelection, components?: readonly PasteComponent[], generation?: number): void;
+    /** Caret/selection gestures the machine cannot observe end the paste attempt. */
+    invalidatePaste(): void;
+    /** Feed a draft/caret change through trigger detection (guard derived from phase). */
+    track(draft: string, caret: number): void;
+    /** Keyboard arbitration while the menu is open ('pass' when no pipeline). */
+    arbitrate(key: ArbitrateKey, composing: boolean): ArbitrateOutcome;
+    /** Space adjudication; true = the input applied a claim — caller preventDefaults. */
+    space(): boolean;
+    /** Dismiss the popupSelect shell (any interaction outside the box). */
+    dismissPopup(): void;
+}
+/** One independently addressable row projected from the transient queue snapshot. */
+export type QueuedMessage = QueueRow;
+/** Guard union of the scoped consume-token event, checked by the machine. */
+export type ConsumeTokenGuard = ConsumeTokenRequest['guard'];
+/** Half-open [start, end) range/selection in draft character coordinates. */
+export interface EditSelection {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * One edit applied to the previous draft: [start, end) in the PREVIOUS
+ * draft's coordinates was replaced by insertedLength characters. Supplied by
+ * the wiring layer when the DOM event exposes the edit shape; absent, the
+ * machine recovers it with a prefix/suffix common-scan diff.
+ */
+export interface EditRange extends EditSelection {
+    readonly insertedLength: number;
+}
+/**
+ * One reference occurrence backed by its complete inline display text in the
+ * draft. Identity is occurrenceId — same-named
+ * references stay independently addressable. label/appearance/clipboardText are the
+ * owner's insert-time projections, cached so the chip survives owner loss
+ * (invalid flips instead of dropping the occurrence).
+ */
+export interface Occurrence {
+    /** Machine-minted stable identity (monotonic per machine). */
+    readonly occurrenceId: number;
+    /** Owning source name (serializer routing key). */
+    readonly source: string;
+    /** Owner-scoped reference id. */
+    readonly ref: string;
+    /** Display-text offset in the draft. */
+    readonly offset: number;
+    /** Display-text length; the occurrence occupies exactly [offset, offset+length). */
+    readonly length: number;
+    /** Inline display label (insert-time cache). */
+    readonly label: string;
+    /** Optional domain glyph (insert-time cache). */
+    readonly appearance?: ReferenceInsert['appearance'];
+    /** Clipboard / persistence projection, e.g. `/name` (insert-time cache, never the model form). */
+    readonly clipboardText: string;
+    /** Owner-resolution failure flag: chip renders invalid; serialization must fail. */
+    readonly invalid?: boolean;
+}
+/** One sync-matched paste component; start/end are relative to the pasted text. */
+export interface PasteComponent extends EditSelection {
+    readonly reference: ReferenceInsert;
+}
+/**
+ * Live paste-match attempt published while async matching may still upgrade
+ * pasted tokens (the clipboard round-trip). Any non-paste transaction,
+ * submit start, invalidate-paste, or release ends it; a paste-upgrade keeps
+ * it current (later tokens re-CAS against the advanced draftRev).
+ */
+export interface PasteAttemptState {
+    /** Machine-minted attempt identity (paste-upgrade must match it). */
+    readonly attemptId: number;
+    /** Pasted range in the draft as of the paste transaction. */
+    readonly insertedRange: EditSelection;
+    /** Caller-supplied projection generation echoed back (the controller drops cross-generation results). */
+    readonly generation: number;
+}
+/**
+ * InputMachine construction knobs. The machine never reads an ambient clock:
+ * `now` is the only time source, injected by the shell (tests inject a
+ * fake). The default clock is constant, i.e. consecutive single-char typing
+ * always coalesces until a non-typing transaction intervenes.
+ */
+export interface InputMachineOptions {
+    /** Single-char typing undo-merge window in ms (default 1000). */
+    readonly mergeWindowMs?: number;
+    /** Monotonic clock for typing-merge decisions (default: constant 0). */
+    readonly now?: () => number;
+}
+/** Published input state (the currency; per-session). */
+export interface InputState {
+    readonly draft: string;
+    /** Ordered runtime-only image ids; bytes and URLs stay in ConversationController. */
+    readonly imageIds: readonly DraftAttachmentId[];
+    /** Ordered runtime-only browser text-file ids; bytes stay in ConversationController. */
+    readonly browserAnnotationIds?: readonly DraftAttachmentId[];
+    /** Runtime-only comments keyed by browser annotation id. */
+    readonly browserAnnotationComments?: Readonly<Record<string, string>>;
+    /** Monotonic draft revision (span CAS compares against this). */
+    readonly draftRev: number;
+    readonly phase: 'plain' | 'adjudicating' | 'claimed' | 'submitting';
+    /** Present exactly while claimed/submitting (claim snapshot during flight; submit closure withheld). */
+    readonly claim?: {
+        readonly token: string;
+        readonly hint?: string;
+        readonly images?: boolean;
+    };
+    /** Reference occurrence table, sorted by offset. */
+    readonly occurrences: readonly Occurrence[];
+    /** Live paste-match attempt (absent when no paste is matchable). */
+    readonly paste?: PasteAttemptState;
+    /** Read-only transient inbox projection (`session/queue`, including pending steering). */
+    readonly queue: readonly QueuedMessage[];
+}
+/**
+ * One in-flight submission attempt: the ONLY id concept in the submit plane.
+ * Created on enter; carried by adjudicated/submit-settled events; stale
+ * attempts are dropped (anti-backwash). release/session teardown aborts the
+ * current attempt, keeping the promise bounded.
+ */
+export interface SubmitAttempt {
+    readonly seq: number;
+    readonly signal: AbortSignal;
+    /** Draft at enter time; settlement clears it only after acceptance. */
+    readonly draftSnapshot: string;
+    /** Default-message delivery intent retained while slash adjudication is pending. */
+    readonly mode: InputSubmitMode;
+}
+/**
+ * InputMachine input events (the machine's single write path). Every draft
+ * mutation is one transaction: draft edit, occurrence reconciliation, and
+ * undo-log push are atomic inside dispatch(). Events carrying `at` stamp the
+ * injected clock reading; only single-char typing coalescing reads it.
+ */
+export type InputEvent = 
+/** Full next draft from the textarea; editRange narrows the occurrence math (absent → diff scan). */
+{
+    readonly type: 'draft-changed';
+    readonly draft: string;
+    readonly editRange?: EditRange;
+} | {
+    readonly type: 'begin-command';
+    readonly claim: CommandClaim;
+    readonly span: TokenSpan;
+}
+/** Place one inline reference at the span and mint the occurrence (scoped insert-reference event payload). */
+ | {
+    readonly type: 'insert-ref';
+    readonly reference: ReferenceInsert;
+    readonly span: TokenSpan;
+}
+/** Delete a settled command token; success is observable as a draftRev advance. */
+ | {
+    readonly type: 'consume-token';
+    readonly guard: ConsumeTokenGuard;
+}
+/** Owner-resolution result: exactly the listed occurrences are invalid (style bit; not a transaction). */
+ | {
+    readonly type: 'set-invalid';
+    readonly invalidIds: readonly number[];
+} | {
+    readonly type: 'undo';
+} | {
+    readonly type: 'redo';
+}
+/**
+ * Paste text replacing the selection, one transaction. Hot-snapshot sync
+ * matches ride in as components (chips minted inside the SAME transaction:
+ * one undo returns to pre-paste); a PasteMatchAttempt opens for the async
+ * remainder. Component ranges must be disjoint and inside the pasted text.
+ */
+ | {
+    readonly type: 'paste-begin';
+    readonly text: string;
+    readonly selection: EditSelection;
+    readonly components?: readonly PasteComponent[];
+    readonly generation?: number;
+}
+/** Async match landed: upgrade one pasted token to a chip as an INDEPENDENT transaction (undo #1 → text, undo #2 → pre-paste). */
+ | {
+    readonly type: 'paste-upgrade';
+    readonly attemptId: number;
+    readonly span: TokenSpan;
+    readonly reference: ReferenceInsert;
+}
+/** Shell-observed attempt killers the machine cannot see itself (caret/selection ops, Slash interaction updates). */
+ | {
+    readonly type: 'invalidate-paste';
+} | {
+    readonly type: 'enter';
+    readonly mode: InputSubmitMode;
+} | {
+    readonly type: 'adjudicated';
+    readonly attempt: SubmitAttempt;
+    readonly outcome: PickOutcome;
+} | {
+    readonly type: 'adjudication-failed';
+    readonly attempt: SubmitAttempt;
+    readonly message: string;
+} | {
+    readonly type: 'submit-settled';
+    readonly attempt: SubmitAttempt;
+    readonly ok: boolean;
+    readonly outcome?: SubmitOutcome;
+    readonly message?: string;
+}
+/** Commit an image-only send whose empty draft did not need an attempt. */
+ | {
+    readonly type: 'send-committed';
+} | {
+    readonly type: 'release';
+};
+/**
+ * InputMachine output effects (executed by the SessionInput shell; the
+ * machine stays pure). Draft/occurrence mutations carry no effect — the
+ * shell publishes the state store after every dispatch.
+ */
+export type InputEffect = {
+    readonly type: 'adjudicate';
+    readonly attempt: SubmitAttempt;
+    readonly draft: string;
+} | {
+    readonly type: 'begin-submit';
+    readonly attempt: SubmitAttempt;
+    readonly claim: CommandClaim;
+    readonly args: string;
+} | {
+    readonly type: 'default-sink';
+    readonly attempt: SubmitAttempt;
+    readonly draft: string;
+    readonly mode: InputSubmitMode;
+} | {
+    readonly type: 'notice';
+    readonly level: 'info' | 'error';
+    readonly text: string;
+};
+//# sourceMappingURL=contract.d.ts.map

package/lib/types/client/input/decorations.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Draft decoration pure core (references render from occurrence ranges; the
+ * claim token renders as a mirror-layer
+ * highlight, the claim hint as ghost text). Zero React — the skeleton renders
+ * the instructions; tests drive this directly.
+ */
+import type { InputState } from './contract.ts';
+/** The claim-token highlight range (always draft-leading while the watch holds). */
+export interface TokenRange {
+    readonly start: number;
+    readonly end: number;
+}
+/** One structured inline-reference render instruction. */
+export interface ChipRender {
+    /** Stable render key (same-labeled chips stay independent). */
+    readonly occurrenceId: number;
+    /** Display-text offset in the draft. */
+    readonly offset: number;
+    /** Display-text length in the draft. */
+    readonly length: number;
+    /** Exact inline text whose native glyph metrics determine layout. */
+    readonly text: string;
+    readonly label: string;
+    /** Optional domain glyph beside the label. */
+    readonly appearance?: 'session' | 'file' | 'folder';
+    /** Owner-resolution failure styling bit. */
+    readonly invalid: boolean;
+}
+/**
+ * One plain-text reference range (the plain-text-reference decision;
+ * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
+ * a `/name` or `@name` token
+ * whose name is on the trigger's lexicon. Pure derivation — editing the text
+ * out of match shape simply drops the range next scan.
+ */
+export interface TextRefRange {
+    readonly start: number;
+    readonly end: number;
+    readonly trigger: '/' | '@';
+    /** Optional icon domain for syntax-recognizable plain references. */
+    readonly appearance?: 'folder';
+}
+/** Decoration product: claim token range + chip instructions + text-ref ranges + the ghost hint. */
+export interface DraftDecorations {
+    /** Claim token range while claimed/submitting and the prefix watch holds; null otherwise. */
+    readonly token: TokenRange | null;
+    /** Chip render instructions in draft order (occurrence table is offset-sorted). */
+    readonly chips: readonly ChipRender[];
+    /** Scan-derived lexicon tokens and syntax-recognizable folder ranges. */
+    readonly textRefs: readonly TextRefRange[];
+    /** Ghost hint shown while the claim's args are blank; null otherwise. */
+    readonly hint: string | null;
+}
+/**
+ * Scan the draft for plain-text reference tokens against the hot lexicons.
+ * Word-boundary discipline: the trigger must sit at the draft
+ * start or after whitespace ('x/name' never matches); the name must be an
+ * exact lexicon member.
+ * @param draft - draft text.
+ * @param lexicon - per-trigger name lists (a missing trigger scans nothing).
+ * @returns matched ranges in draft order.
+ */
+export declare function scanTextRefs(draft: string, lexicon: ReadonlyMap<'/' | '@', readonly string[]>): TextRefRange[];
+/**
+ * Derive the mirror-layer decorations from the input state.
+ * @param state - published input state.
+ * @param lexicon - optional per-trigger reference lexicons (plain-text-reference scan).
+ * @returns token range, chip instructions, text-ref ranges, and the ghost hint.
+ */
+export declare function deriveDecorations(state: InputState, lexicon?: ReadonlyMap<'/' | '@', readonly string[]>): DraftDecorations;
+//# sourceMappingURL=decorations.d.ts.map

package/lib/types/client/input/facade.d.ts

@@ -0,0 +1,261 @@
+/**
+ * SessionInput shell over the pure input machine: the sole machine caller
+ * and effect executor. Owns the InputState store (machine state + the queue
+ * overlay), the notice channel, and the submit transaction plumbing
+ * (adjudicate via the session's InputTriggerController; claim.submit; default
+ * sink). Package-private; the hub alone constructs it and wires the scoped
+ * event listeners onto it.
+ */
+import type { ClientContext, ObservableSnapshot, SnapshotStore } from '@hydraharness/harness-client-runtime/client';
+import type { ArbitrateKey, ArbitrateOutcome, CommandClaim, ConsumeTokenRequest, ReferenceInsert, InputTriggerController, SubmitImageAttachment, SubmitOutcome, TokenSpan } from '@hydraharness/harness-client-ui-input-trigger/client';
+import type { DraftAttachmentId, EditRange, EditSelection, InputActions, InputNotice, InputState, PasteComponent, QueuedMessage, SessionInput } from './contract.ts';
+import type { InputSubmitMode } from '../contract/composer-submission.ts';
+/** Popup face the shell needs (dismissal only; typed structurally to avoid a value import). */
+export interface PopupDismissFace {
+    dismiss(): void;
+}
+/**
+ * Construction dependencies of one facade. The slash/popup faces are THUNKS: the
+ * shell is created inside the sessions provide materialization (before the
+ * scope record is queryable), where `slash.sessionOf`/`command.popupFor`
+ * cannot resolve yet — resolution defers to first interactive use.
+ */
+export interface SessionInputDeps {
+    /** Session-scope ctx handed to claim.submit transactions. */
+    actx: ClientContext;
+    /** Enter adjudication face resolver; absent/undefined answer = every '/' line falls to the default sink. */
+    inputTriggers?: (() => InputTriggerController | undefined) | undefined;
+    /** PopupSelect shell face resolver (dismissal on submit lock / escape). */
+    popup?: (() => PopupDismissFace | undefined) | undefined;
+    /** Queue read face; overlaid onto InputState.queue (absent = empty). */
+    queue?: ObservableSnapshot<readonly QueuedMessage[]> | undefined;
+    /**
+     * Steer every still-pending queued message into the running turn, in FIFO
+     * order (the empty-draft accelerated-Enter gesture); absent = unsupported.
+     */
+    steerQueue?: (() => void) | undefined;
+    /** The plain-message sink (send choreography / materialize fork — the hub owns it). */
+    defaultSink(text: string, imageIds: readonly DraftAttachmentId[], mode: InputSubmitMode, signal: AbortSignal, browserAnnotationIds?: readonly DraftAttachmentId[]): Promise<SubmitOutcome>;
+    /** Command-plane image plumbing (the hub owns the conversation face and the copy). */
+    commandImages: {
+        /** Resolve ordered draft ids to wire payloads without sending them; rejects when an id no longer resolves. */
+        serialize(ids: readonly DraftAttachmentId[]): Promise<readonly SubmitImageAttachment[]>;
+        /** Free consumed draft images after a successful command submit. */
+        release(ids: readonly DraftAttachmentId[]): void;
+        /** Localized composer notice for a claimed command that does not accept images. */
+        unsupportedNotice(token: string): string;
+    };
+    /** Optional notice for commands that cannot consume browser text files. */
+    commandAttachments?: {
+        unsupportedNotice(token: string): string;
+    };
+    /** Optional owner-side mutation for browser annotation comments. */
+    browserAnnotations?: {
+        updateComment(id: DraftAttachmentId, comment: string): void;
+    };
+}
+/**
+ * The per-session input facade: scoped-event application verbs +
+ * setDraft/submit + the published InputState store.
+ */
+export declare class SessionInputShell implements SessionInput {
+    private readonly deps;
+    /** Published machine state + queue overlay (the InputZone currency source). */
+    readonly state: SnapshotStore<InputState>;
+    /** Latest surfaced notice (null after clear); the bar renders errors as banners and information inline. */
+    readonly notices: SnapshotStore<InputNotice | null>;
+    /** The public provide-channel action face (one stable identity per session). */
+    readonly actions: InputActions;
+    private readonly core;
+    private noticeSeq;
+    private lastMirroredDraft;
+    private imageIds;
+    private browserAnnotationIds;
+    private readonly browserAnnotationComments;
+    /** One image-only send at a time: Enter during the Host round-trip is a no-op. */
+    private imageSendInFlight;
+    private disposed;
+    /** Draft persistence mirror (chat store write; receives the clipboard projection, never display-only ranges). */
+    private mirrorFn;
+    constructor(deps: SessionInputDeps);
+    /**
+     * Single draft write path (all mutation rides machine events).
+     * @param text - the full next draft.
+     * @param editRange - the DOM-observed edit shape, when the caller knows it
+     * (narrows the machine's occurrence math; absent → diff scan).
+     */
+    setDraft(text: string, editRange?: EditRange): void;
+    /** Append ordered image ids unless an admission transaction is locked. */
+    addImages(ids: readonly DraftAttachmentId[]): boolean;
+    /**
+     * Remove one image id from this draft. Busy admission phases refuse, like
+     * {@link addImages}: a removal landing while a command submit serializes
+     * would otherwise vanish from the rail yet still ride the in-flight send.
+     */
+    removeImage(id: DraftAttachmentId): void;
+    /**
+     * Keep only image ids that still resolve in the browser attachment registry.
+     * @param available - live registry ids.
+     */
+    pruneImages(available: readonly DraftAttachmentId[]): void;
+    /** Append browser-selected text ids unless an admission transaction is locked. */
+    addBrowserAnnotations(ids: readonly DraftAttachmentId[]): boolean;
+    /** Remove one browser-selected text id from this draft. */
+    removeBrowserAnnotation(id: DraftAttachmentId): void;
+    /**
+     * Keep only browser-selected text ids whose local objects still exist.
+     * @param available - live registry ids.
+     */
+    pruneBrowserAnnotations(available: readonly DraftAttachmentId[]): void;
+    /** Update one browser annotation comment and notify the owner/UI. */
+    updateBrowserAnnotationComment(id: DraftAttachmentId, comment: string): void;
+    /**
+     * Clear the draft as a successful-send commit: no undo unit is recorded and
+     * the undo history is cut, so Ctrl/Cmd-Z cannot resurrect sent content
+     * (the command path gets the same discipline from submit-settled success).
+     * @param imageIds - admitted image ids to remove from this draft.
+     * @param browserAnnotationIds - admitted browser annotation ids to remove.
+     */
+    commitSend(imageIds: readonly DraftAttachmentId[], browserAnnotationIds?: readonly DraftAttachmentId[]): void;
+    /** Undo the latest transaction (InputBar intercepts the platform chord). */
+    undo(): void;
+    /** Redo the latest undone transaction. */
+    redo(): void;
+    /**
+     * Paste text over the selection in one transaction, with any hot-snapshot
+     * sync matches componentized inside it.
+     * @param text - pasted plain text.
+     * @param selection - replaced selection in draft coordinates.
+     * @param components - sync-matched reference components (disjoint, inside `text`).
+     * @param generation - projection generation for late async-upgrade guards.
+     */
+    pasteBegin(text: string, selection: EditSelection, components?: readonly PasteComponent[], generation?: number): void;
+    /** End the live paste-match attempt (caret/selection ops and Slash updates the machine cannot see). */
+    invalidatePaste(): void;
+    /**
+     * Enter adjudication + submit transaction + default sink. Effects fan out
+     * from the machine; this method only feeds the event. Lock entry
+     * (adjudicating/submitting) force-closes the transient layers: the popup
+     * dismisses and the menu tracks frozen.
+     */
+    submit(mode?: InputSubmitMode): void;
+    /**
+     * Feed a draft/caret change through trigger detection (guard derived from
+     * the machine phase).
+     * @param draft - live draft text.
+     * @param caret - caret position in draft coordinates.
+     */
+    track(draft: string, caret: number): void;
+    /**
+     * Keyboard arbitration while the menu is open.
+     * @param key - the intercepted key.
+     * @param composing - IME composition guard state.
+     * @returns the menu's verdict; 'pass' when no pipeline is mounted.
+     */
+    arbitrate(key: ArbitrateKey, composing: boolean): ArbitrateOutcome;
+    /**
+     * Steer every still-pending queued message into the running turn (the
+     * empty-draft accelerated-Enter gesture). Execution belongs to the hub's
+     * queue choreography; absent dep = the gesture falls back to the machine's
+     * empty-draft no-op.
+     */
+    steerQueue(): void;
+    /**
+     * Space adjudication over the controller's hot state.
+     * @returns true = a claim/insert was applied — the caller preventDefaults.
+     */
+    space(): boolean;
+    /** Dismiss the popupSelect shell (any interaction outside the box). */
+    dismissPopup(): void;
+    /**
+     * Hot plain-text reference lexicon source for the decoration scan
+     * (the plain-text-reference decision;
+     * see .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
+     * delegates to the controller's aggregated store. Stable
+     * identity per shell; without a pipeline the snapshot is the empty Map and
+     * subscribers never fire.
+     */
+    readonly lexicon: ObservableSnapshot<ReadonlyMap<'/' | '@', readonly string[]>>;
+    /**
+     * Apply one command claim (scoped begin-command event listener body).
+     * @param claim - the command claim from the pick path.
+     * @param span - pick-time span snapshot.
+     * @returns whether the machine accepted (phase + span CAS passed and the draft mutated).
+     */
+    beginCommand(claim: CommandClaim, span: TokenSpan): boolean;
+    /**
+     * Apply one reference insertion (scoped insert-reference event listener body).
+     * @param ref - the reference insertion from the pick path.
+     * @param span - pick-time span snapshot.
+     * @returns whether the machine accepted.
+     */
+    insertReference(ref: ReferenceInsert, span: TokenSpan): boolean;
+    /**
+     * Consume one command token after business success (scoped consume-token
+     * event listener body). Span guard: revision CAS then splice; bare-token
+     * guard: trimmed-draft equality then clear.
+     * @param guard - exact span or bare-token guard.
+     * @returns whether the token was consumed.
+     */
+    consumeToken(guard: ConsumeTokenRequest['guard']): boolean;
+    /**
+     * Insert plain reference text over the pick-time span (scoped insert-text
+     * event listener body; plain-text-reference decision, web-input-machine
+     * note). Same CAS-then-splice shape as the
+     * consume-token span branch: the machine sees an ordinary draft-changed
+     * transaction (one undo step), no occurrence is minted — the chip look is
+     * a scan-derived decoration, never state.
+     * @param text - the plain reference text to splice in (e.g. `/name `).
+     * @param span - pick-time span snapshot (draftRev CAS).
+     * @param keepCompleting - re-track at the caret after the splice so an open
+     * token (a directory pick's trailing slash) reopens the menu.
+     * @returns whether the text was applied.
+     */
+    insertText(text: string, span: TokenSpan, keepCompleting?: boolean): boolean;
+    /**
+     * Surface a notice from outside the machine (detached command results).
+     * @param level - severity tier.
+     * @param text - notice body.
+     */
+    notify(level: 'info' | 'error', text: string): void;
+    /** Teardown: abort any in-flight attempt and stop accepting async settlements. */
+    dispose(): void;
+    /** Read the live machine state (guard derivation reads here). */
+    get snapshot(): InputState;
+    /**
+     * Bind the draft persistence mirror (chat store write). Adopt-on-bind: the
+     * store draft may hold a persisted value from a previous mount; the caller
+     * seeds it via setDraft BEFORE binding, and afterwards every machine-adopted
+     * draft mirrors out.
+     * @param write - store draft write.
+     * @returns the unbind disposer.
+     */
+    bindMirror(write: (text: string) => void): () => void;
+    private run;
+    private execute;
+    /**
+     * Prompt serialization before the sink: expand each
+     * inline reference range to its owner's model form via the session controller's
+     * codec routing. Owner missing / serialize failure / disposal blocks the
+     * send — notice + draft and chips retained, never a silent downgrade to
+     * the clipboard text. Chip-free drafts skip the async detour.
+     */
+    private sinkSerialized;
+    /** Settle one admission attempt; successful sends consume only their captured images. */
+    private settleSubmit;
+    /** Enter adjudication: poll the session controller; failure = notice + draft retained (never a silent downgrade). */
+    private adjudicate;
+    /**
+     * The submit transaction: claim.submit against the session scope; ok maps
+     * from the outcome kind. An accepting claim receives the serialized draft
+     * images, which are cleared and released only on a success outcome; a
+     * failure (serialize, transport, or handler error) keeps draft and images
+     * for correction.
+     */
+    private beginSubmit;
+    /** Late-settlement guard: superseded attempts and disposed facades drop silently. */
+    private dead;
+    private compose;
+    private publish;
+}
+//# sourceMappingURL=facade.d.ts.map