@qilin-agent/client-ui-conversation 0.0.0-stage → 3.1.4

package/lib/types/client/image-labels.d.ts

@@ -0,0 +1,23 @@
+/** Attachment error and limit copy owned by the conversation input flow. */
+import type { ImageAttachmentLimits } from '@qilin-agent/attachment';
+import type { Translate } from '@qilin-agent/client-ui-slots';
+import type { ConversationKey } from './locales.ts';
+/**
+ * Byte count as user-facing megabytes (`10MB`, `2.5MB`).
+ * @param bytes - the byte count.
+ * @returns the rounded megabyte text.
+ */
+export declare function imageSizeText(bytes: number): string;
+/**
+ * Product copy for a host attachment rejection (the `details.reason` of
+ * `session/attachment-invalid` or `subagent/attachment-invalid`).
+ * User-solvable reasons name the limit and the way out;
+ * reasons the user cannot act on fold into one send-failed line carrying the
+ * reason code for a bug report.
+ * @param t - the conversation-namespace translate.
+ * @param reason - the wire `details.reason` code.
+ * @param limits - projected limits interpolated into count/size copy, when known.
+ * @returns the banner text.
+ */
+export declare function attachmentErrorText(t: Translate<ConversationKey>, reason: string, limits?: ImageAttachmentLimits): string;
+//# sourceMappingURL=image-labels.d.ts.map

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

@@ -0,0 +1,39 @@
+/** Browser Conversation assemble core, React adapter, shell, and input plugin. */
+export { apply, Config, inject } from './apply.ts';
+export type { Config as ConversationConfig } from './apply.ts';
+export { UiConversation } from './conversation/assembly.ts';
+export type { ConversationBinding } from './conversation/assembly.ts';
+export type { ConversationGroupRegistry } from './conversation/group-registry.ts';
+export type { ConversationGroupContext, ConversationGroupData, ConversationGroupDataMap, ConversationGroupDefinition, ConversationGroupedView, ConversationGroupInput, GroupKey, GroupNodePosition, GroupReference, GroupSnapshot, GroupUpdate, NodeChange, NodeKey, NodeReference, RenderEntry, } from './contract/groups.ts';
+export { ConversationController, UnsupportedImageMediaTypeError } from './service.ts';
+export type { IConversation } from './service.ts';
+export type { ConversationContextReader, ConversationLocation, ConversationLocationData, ConversationLocationDataScope, ConversationLocationDataSource, ConversationLocationDataStore, ConversationMatch, ConversationMatchResult, ConversationNodeContext, ConversationNodeDefinition, ConversationPreviousContext, ConversationPublication, ConversationStartMatch, ConversationStepDataMap, ConversationTimelineSnapshot, ConversationTurnDataMap, ConversationViewBuilder, ConversationViewDefinition, ConversationViewNode, ConversationViewSnapshotMap, ConversationViewSnapshotStore, StepLocation, TurnLocation, } from './contract/conversation.ts';
+export { EMPTY_CONVERSATION_SNAPSHOT, conversationPhase } from './contract/snapshot.ts';
+export type { ConversationPhase, ConversationSnapshot, } from './contract/snapshot.ts';
+export type { AssistantBlock, AssistantMessageNode, AssistantProviderMetadataView, AssistantRequestConfig, AssistantTiming, CommandNode, CompactionSummaryNode, ContextMessageNode, ConversationNode, ModelRetryNode, PartialAssistant, PreparingToolCall, RunningToolCall, StartedToolCall, SteeringMessageNode, TodoItem, ToolArgs, ToolCallBlock, ToolResultNode, TurnErrorNode, TurnMaxTokensNode, UnknownSurfaceNode, UserMessageNode, } from './contract/records.ts';
+export type { ContextProducerView, ContextRole, KnownContextForm, } from './contract/context-producer.ts';
+export type { ConversationPromptSnapshot, RequestInspectionSnapshot, RequestPromptChange, RequestPromptInspection, RequestPromptInspector, RequestView, SystemPromptNode, } from './contract/request-inspection.ts';
+export { inspectRequestPrompt } from './contract/request-inspection.ts';
+export type { SystemPromptState, SystemPromptInspector } from './contract/system-prompt.ts';
+export type { ConversationStoreState, ViewTab } from './contract/views.ts';
+export { ConversationNodeAssembler } from './conversation/assembler.ts';
+export type { ConversationEventDefinitions, ConversationGroupDefinitions, ConversationViewDefinitions, } from './conversation/assembler.ts';
+export { ConversationDefinitionRegistry } from './conversation/definition-registry.ts';
+export { ConversationEventRegistry } from './conversation/event-registry.ts';
+export { ConversationLocationIndex } from './conversation/location-index.ts';
+export type { ConversationLocationDataChange } from './conversation/location-index.ts';
+export { ConversationViewRegistry } from './conversation/view-registry.ts';
+export type { ConversationKey } from './locales.ts';
+export type { ComposerAttachment, ComposerAttachmentsOwnerProps, ComposerAttachmentsProps, ComposerFileAttachment, ComposerImageAttachment, DraftFileUpload, DraftFileUploads, ComposerBarInjected, ComposerBarOwnerProps, ComposerBarProps, ComposerChainProps, ConversationHeaderActionOwnerProps, ConversationHeaderCornerOwnerProps, ConversationHeaderLineageOwnerProps, ConversationContentInputProps, ConversationContentProps, ConversationInjected, ConversationSessionHeaderInjected, ConversationSessionHeaderSlotProps, ConversationSessionInjected, ConversationSessionSlotProps, ConversationSlotProps, ConversationViewsProps, ConversationWidthControlsInputProps, ConversationWidthControlsProps, ConversationStore, ConvViewOwnerProps, ConvViewProps, EmptyWorkspaceOwnerProps, HeroAgentPresetOwnerProps, HeroBrandMarkOwnerProps, InputControlOwnerProps, InputZone, MessageImageLoader, MessageImageSource, MessageImagesOwnerProps, RenderMessageImages, UseConversation, UseConversationViews, } from './contract/slots.ts';
+export type { BeginCommandRequest, CommandClaim, ConsumeTokenRequest, DraftAttachmentId, InputActions, InputState, InsertReferenceRequest, InsertTextRequest, PickOutcome, SessionInput, SessionInputResolver, SubmitAttachment, SubmitOutcome, } from './contract/input.ts';
+export type { ArbitrateKey, ArbitrateOutcome, ReferenceInsert, TokenSpan } from './contract/draft-editor.ts';
+export type { ComposerBlock, ComposerBlocks } from './contract/composer-blocks.ts';
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        /** Scope-addressed Conversation actions and per-Session input registry. */
+        conversation: import('./service.ts').IConversation;
+        /** Target-neutral Conversation registries and per-Session assembly. */
+        uiConversation: import('./conversation/assembly.ts').UiConversation;
+    }
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * Composer blocks: the one way another plugin stops a session's input.
+ *
+ * The composer cannot read the plugins that would know — the dependency runs
+ * ui-model-selection → ui-conversation, never back — so a blocker pushes here and the
+ * bar reads its own session's store. A block carries the localized reason it
+ * exists, because the plugin that raised it owns that copy; the composer only
+ * knows how to render an inert textarea with a placeholder, exactly as it
+ * already does for a session with no workspace.
+ *
+ * This is an affordance, not enforcement: the Host refuses a prompt it cannot
+ * route regardless of what any client disables.
+ */
+import { type SnapshotStore } from '@qilin-agent/client-store';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { ComposerBlock, ComposerBlocks } from '../contract/composer-blocks.ts';
+/** The per-session composer-block registry (one instance per plugin fiber). */
+export declare class ComposerBlockRegistry implements ComposerBlocks {
+    private readonly stores;
+    /** @inheritdoc */
+    set(sessionId: SessionId, block: ComposerBlock | undefined): void;
+    /** @inheritdoc */
+    storeFor(sessionId: SessionId): SnapshotStore<ComposerBlock | undefined>;
+    /** @inheritdoc */
+    forget(sessionId: SessionId): void;
+}
+//# sourceMappingURL=blocks.d.ts.map

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

@@ -0,0 +1,32 @@
+/**
+ * Plain-text reference scan (the plain-text-reference decision;
+ * see .agents/notes/archived/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md):
+ * a `/name` or `@name` token whose name is on the trigger's lexicon, and
+ * syntax-recognizable `@dir/` folder tokens. Pure derivation — the editor's
+ * text-ref entity transform consumes these ranges; editing the text out of
+ * match shape simply drops the range next scan.
+ */
+/**
+ * One plain-text reference range (the plain-text-reference decision;
+ * see .agents/notes/archived/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: '/' | '@';
+}
+/**
+ * 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; a `/name` token must end at whitespace or the draft
+ * end ('/name/x' is a path, '/name。' is prose).
+ * @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[];
+//# sourceMappingURL=decorations.d.ts.map

package/lib/types/client/input/editor/ComposerContentEditable.d.ts

@@ -0,0 +1,16 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import type { LexicalEditor } from 'lexical';
+/** Host props: the editor binding plus the div passthroughs the bar owns. */
+export interface ComposerContentEditableProps extends HTMLAttributes<HTMLDivElement> {
+    /** The shell-owned editor; null renders the same div unbound and inert. */
+    readonly editor: LexicalEditor | null;
+    /** Whether the user may edit (readOnly/disabled states fold in here). */
+    readonly editable: boolean;
+}
+/**
+ * Render the composer's editable surface.
+ * @param props - editor binding, editability, and div passthroughs.
+ * @returns the resident contenteditable div.
+ */
+export declare function ComposerContentEditable({ editor, editable, ...rest }: ComposerContentEditableProps): ReactNode;
+//# sourceMappingURL=ComposerContentEditable.d.ts.map

package/lib/types/client/input/editor/DecoratorPortals.d.ts

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+import type { LexicalEditor } from 'lexical';
+/** Portal-loop props. */
+export interface DecoratorPortalsProps {
+    /** The bound editor; null (no-session) renders nothing. */
+    readonly editor: LexicalEditor | null;
+}
+/**
+ * Render every decorator's React face into its editor host element.
+ * @param props - the editor to observe.
+ * @returns the live portal set.
+ */
+export declare function DecoratorPortals({ editor }: DecoratorPortalsProps): ReactNode;
+//# sourceMappingURL=DecoratorPortals.d.ts.map

package/lib/types/client/input/editor/DraftEditor.d.ts

@@ -0,0 +1,27 @@
+/** Stateless text-area presentation over the InputBar's borrowed editor. */
+import type { KeyboardEventHandler, ReactNode, RefObject } from 'react';
+import type { LexicalEditor } from 'lexical';
+import type { InputState } from '../../contract/input.ts';
+/** Text-area values and the scrollport reference retained by InputBar. */
+export interface DraftEditorProps {
+    readonly classNames: Readonly<Record<string, string>>;
+    readonly editor: LexicalEditor | null;
+    readonly scrollRef: RefObject<HTMLDivElement>;
+    readonly editable: boolean;
+    readonly editorDisabled: boolean;
+    readonly phase: InputState['phase'] | 'inert';
+    readonly placeholderText: string;
+    readonly ariaLabel: string;
+    readonly workspaceTrigger: boolean;
+    readonly workspacePickerOpen: boolean;
+    readonly onWorkspaceKeyDown: KeyboardEventHandler<HTMLDivElement>;
+    readonly hint: string | null;
+    readonly showPlaceholder: boolean;
+}
+/**
+ * Render the existing scrollport, editable surface, placeholder, and chip portals.
+ * @param props - borrowed editor and presentation values; this component owns no Hooks.
+ * @returns the existing text-area DOM without an additional wrapper.
+ */
+export declare function DraftEditor({ classNames: css, editor, scrollRef, editable, editorDisabled, phase, placeholderText, ariaLabel, workspaceTrigger, workspacePickerOpen, onWorkspaceKeyDown, hint, showPlaceholder, }: DraftEditorProps): ReactNode;
+//# sourceMappingURL=DraftEditor.d.ts.map

package/lib/types/client/input/editor/ReferenceChip.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import type { ReferenceIconKind } from '@qilin-agent/client-ui-primitives';
+/** Display inputs of one chip (the node's cached owner projections). */
+export interface ReferenceChipProps {
+    readonly label: string;
+    /** Domain glyph; absent renders the trigger marker instead of an icon. */
+    readonly appearance?: ReferenceIconKind | undefined;
+    /** Owner-resolution failure styling bit. */
+    readonly invalid: boolean;
+}
+/**
+ * Render one inline reference chip.
+ * @param props - label, optional domain glyph, and the invalid bit.
+ * @returns the chip body (icon + truncating label).
+ */
+export declare function ReferenceChip({ label, appearance, invalid }: ReferenceChipProps): ReactNode;
+//# sourceMappingURL=ReferenceChip.d.ts.map

package/lib/types/client/input/editor/chip-node.d.ts

@@ -0,0 +1,110 @@
+/**
+ * ReferenceChipNode: one inline reference as an atomic Lexical decorator.
+ * The node IS the occurrence — NodeKey carries identity, the node carries
+ * the owner's insert-time projections (label/appearance/clipboardText), and
+ * `getTextContent()` answers the clipboard/persistence projection so native
+ * copy and the draft mirror stay correct without expansion code. The detect
+ * projection (trigger scanning and TokenSpan coordinates) counts every chip
+ * as one U+FFFC instead; see projection.ts.
+ */
+import type { JSX } from 'react';
+import type { EditorConfig, LexicalNode, NodeKey, SerializedLexicalNode, Spread } from 'lexical';
+import { DecoratorNode } from 'lexical';
+import type { ReferenceInsert } from '../../contract/draft-editor.ts';
+/** JSON form of one chip (Lexical node serialization contract). */
+export type SerializedReferenceChipNode = Spread<{
+    source: string;
+    ref: string;
+    label: string;
+    appearance?: ReferenceInsert['appearance'];
+    clipboardText: string;
+    invalid: boolean;
+}, SerializedLexicalNode>;
+/** One inline reference occurrence as an atomic decorator node. */
+export declare class ReferenceChipNode extends DecoratorNode<JSX.Element> {
+    /** Owning source name (serializer routing key). */
+    __source: string;
+    /** Owner-scoped reference id. */
+    __ref: string;
+    /** Inline display label (insert-time cache). */
+    __label: string;
+    /** Optional domain glyph (insert-time cache). */
+    __appearance: ReferenceInsert['appearance'];
+    /** Clipboard / persistence projection, e.g. `/name` (never the model form). */
+    __clipboardText: string;
+    /** Owner-resolution failure flag: chip renders invalid; serialization must fail. */
+    __invalid: boolean;
+    /** Lexical node registry type tag. */
+    static getType(): string;
+    /**
+     * Clone with identity (Lexical writable-copy contract).
+     * @param node - node to clone.
+     * @returns a copy carrying the same NodeKey.
+     */
+    static clone(node: ReferenceChipNode): ReferenceChipNode;
+    /**
+     * Rebuild one chip from its JSON form.
+     * @param json - serialized chip.
+     * @returns a fresh node (new key).
+     */
+    static importJSON(json: SerializedReferenceChipNode): ReferenceChipNode;
+    /**
+     * @param insert - the owner's reference insertion (display projections included).
+     * @param invalid - owner-resolution failure bit (defaults valid).
+     * @param key - Lexical clone-path key; absent for fresh nodes.
+     */
+    constructor(insert: Omit<ReferenceInsert, 'appearance'> & {
+        appearance?: ReferenceInsert['appearance'];
+    }, invalid?: boolean, key?: NodeKey);
+    /** Serialize to the JSON node form. */
+    exportJSON(): SerializedReferenceChipNode;
+    /**
+     * Mount the chip's host element; the decorator portal renders into it.
+     * @returns an inline, non-editable span carrying the test/e2e anchor.
+     */
+    createDOM(_config: EditorConfig): HTMLElement;
+    /** Host element never changes shape. */
+    updateDOM(): boolean;
+    /** Chips sit in the text line. */
+    isInline(): boolean;
+    /**
+     * No keyboard-selected intermediate state: arrows step across the chip in
+     * one move and Backspace/Delete remove it whole (the placeholder semantics
+     * of the old textarea). `true` would put a NodeSelection between the
+     * keystroke and the caret — a state the plain-text binding's handlers all
+     * ignore, deadlocking arrows, typing, and deletion at the chip edge.
+     */
+    isKeyboardSelectable(): boolean;
+    /** Clipboard / persistence projection (native copy reads this). */
+    getTextContent(): string;
+    /**
+     * Flip the owner-resolution failure bit.
+     * @param invalid - next bit; no-op writes are the caller's concern.
+     */
+    setInvalid(invalid: boolean): void;
+    /** Owner-resolution failure bit. */
+    isInvalid(): boolean;
+    /** Owning source name. */
+    getSource(): string;
+    /** Owner-scoped reference id. */
+    getReference(): string;
+    /** Inline display label. */
+    getLabel(): string;
+    /** Optional domain glyph. */
+    getAppearance(): ReferenceInsert['appearance'];
+    /** React face rendered into the host element by the decorator portal. */
+    decorate(): JSX.Element;
+}
+/**
+ * Mint one chip node from a reference insertion.
+ * @param insert - the owner's reference insertion.
+ * @returns the fresh node.
+ */
+export declare function $createReferenceChipNode(insert: ReferenceInsert): ReferenceChipNode;
+/**
+ * Chip type guard.
+ * @param node - any node or nullish.
+ * @returns whether the node is a ReferenceChipNode.
+ */
+export declare function $isReferenceChipNode(node: LexicalNode | null | undefined): node is ReferenceChipNode;
+//# sourceMappingURL=chip-node.d.ts.map

package/lib/types/client/input/editor/claim-decor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Claim-token highlight: while a command claim holds, the draft's leading
+ * token renders in the warn color. A TextNode transform keeps the token in
+ * its own styled node (splitting when typing merges text into it), and the
+ * shell nudges the first leaf dirty when the claim flips so entering and
+ * leaving claimed restyles without a text edit.
+ */
+import type { LexicalEditor } from 'lexical';
+/**
+ * Register the claim-token styling transform.
+ * @param editor - the shell-owned editor.
+ * @param activeToken - live claim token accessor; null while unclaimed.
+ * @returns the unregister disposer.
+ */
+export declare function registerClaimDecoration(editor: LexicalEditor, activeToken: () => string | null): () => void;
+/**
+ * Nudge the token seat dirty so the transform restyles after a claim flip
+ * (claims change phase without a text edit; transforms only run on dirty
+ * nodes).
+ * @param editor - the shell-owned editor.
+ */
+export declare function refreshClaimDecoration(editor: LexicalEditor): void;
+//# sourceMappingURL=claim-decor.d.ts.map

package/lib/types/client/input/editor/keymap.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Composer keymap over the Lexical command layer: menu arbitration
+ * (arrows/escape/enter), space adjudication, the Enter submit gesture, and
+ * paste routing. Registered at CRITICAL priority so it decides before
+ * @lexical/plain-text's own Enter/paste defaults; a handler returning false
+ * falls through to those defaults (Shift+Enter's line break, ordinary
+ * spaces, text paste the bar routes itself).
+ *
+ * IME guard: a composition-closing Enter/Space must not submit or adjudicate.
+ * KeyboardEvent.isComposing covers most engines; Safari delivers the closing
+ * keydown AFTER compositionend, so a root-element composition watch holds the
+ * guard for 10ms more (the old textarea's proven window); keyCode
+ * 229 is the legacy signal engines emit without isComposing.
+ * The root's composition attribute suppresses placeholders until both the
+ * native composition and the editor's final text reconciliation finish.
+ */
+import type { LexicalEditor } from 'lexical';
+import type { ArbitrateKey, ArbitrateOutcome } from '../../contract/draft-editor.ts';
+/** The bar-supplied behavior behind each intercepted gesture. */
+export interface ComposerKeymapHandlers {
+    /** Keyboard arbitration while the menu is open ('pass' when no pipeline). */
+    arbitrate(key: ArbitrateKey, composing: boolean): ArbitrateOutcome;
+    /** Space adjudication; true = a claim was applied — the keystroke is consumed. */
+    space(): boolean;
+    /** Dismiss the popupSelect shell (Escape layering: an open overlay closes first). */
+    dismissPopup(): void;
+    /** Whether Enter may submit right now (locked/busy states refuse). */
+    canSubmit(): boolean;
+    /** The Enter gesture after every guard passed; `accelerated` = Ctrl/Cmd held. */
+    submit(accelerated: boolean): void;
+    /** Pasted files (image intake). */
+    intakeFiles(files: readonly File[]): void;
+    /** Pasted plain text (sanitized insertion through the shell). */
+    pasteText(text: string): void;
+}
+/**
+ * Register the composer keymap on one editor.
+ * @param editor - the shell-owned editor.
+ * @param handlers - bar-supplied behavior.
+ * @returns the unregister disposer.
+ */
+export declare function registerComposerKeymap(editor: LexicalEditor, handlers: ComposerKeymapHandlers): () => void;
+//# sourceMappingURL=keymap.d.ts.map

package/lib/types/client/input/editor/projection.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Composer editor projections: one EditorState, three pure text views.
+ * detectText feeds trigger detection and TokenSpan coordinates (every chip
+ * counts as one U+FFFC — the opaque-reference invariant); clipboardText
+ * feeds persistence, the InputState draft, and submit-plane decisions
+ * (chips expand to their clipboard projection); the model form is not a
+ * text view here — submit serializes chip nodes through their owner codec.
+ * All $-functions must run inside `editor.read()` / `editor.update()`.
+ */
+import type { LexicalNode, NodeKey, Point } from 'lexical';
+import type { Occurrence } from '../../contract/draft-editor.ts';
+/** The detect-projection stand-in for one chip (object replacement character). */
+export declare const ATOMIC_CHAR = "\uFFFC";
+/** One leaf (or gap) of the composer document in projection coordinates. */
+export interface ComposerSegment {
+    /** text/linebreak carry a node; chip is atomic; gap is the newline between block elements. */
+    readonly kind: 'text' | 'chip' | 'linebreak' | 'gap';
+    /** The backing node; null only for gap. */
+    readonly node: LexicalNode | null;
+    readonly detectStart: number;
+    readonly detectLength: number;
+    readonly clipboardStart: number;
+    readonly clipboardLength: number;
+    /** gap only: the block elements this newline separates. */
+    readonly gapBetween?: {
+        readonly before: NodeKey;
+        readonly after: NodeKey;
+    };
+}
+/** One walk's product: segments plus the indexes point mapping needs. */
+export interface ComposerLayout {
+    readonly segments: readonly ComposerSegment[];
+    readonly detectLength: number;
+    readonly detectText: string;
+    readonly clipboardText: string;
+    /** Leaf node key → its segment (text/chip/linebreak). */
+    readonly byKey: ReadonlyMap<NodeKey, ComposerSegment>;
+    /** Element key → ordered child keys (root and every block element). */
+    readonly children: ReadonlyMap<NodeKey, readonly NodeKey[]>;
+    /** Element key → detect bounds of its content (gaps excluded). */
+    readonly bounds: ReadonlyMap<NodeKey, {
+        readonly start: number;
+        readonly end: number;
+    }>;
+}
+/**
+ * Walk the composer document once, producing every projection segment in
+ * document order. Blocks (paragraphs) contribute a one-newline gap between
+ * one another in both text projections.
+ * @returns the layout for this EditorState.
+ */
+export declare function $composerLayout(): ComposerLayout;
+/**
+ * Fold one clipboard-projection offset to its detect-projection twin.
+ * Offsets inside a chip's clipboard expansion snap to the chip's trailing
+ * edge; callers only pass boundaries that were once a document end (submit
+ * snapshots), which never split a chip.
+ * @param layout - the current walk product.
+ * @param clipboardOffset - offset into the clipboard projection.
+ * @returns the detect offset covering the same document position.
+ */
+export declare function detectOffsetOfClipboardOffset(layout: ComposerLayout, clipboardOffset: number): number;
+/** The published projection product consumed by the shell every update. */
+export interface EditorProjection {
+    /** Trigger/TokenSpan coordinate text (chip = one U+FFFC). */
+    readonly detectText: string;
+    /** Persistence/InputState draft text (chip = clipboardText). */
+    readonly clipboardText: string;
+    /** InputState-compatible occurrence view (clipboardText coordinates). */
+    readonly occurrences: readonly Occurrence[];
+    /** Range selection in detect coordinates (ordered); null while absent or non-range. */
+    readonly selection: {
+        readonly start: number;
+        readonly end: number;
+    } | null;
+    /** Collapsed caret in detect coordinates; null while the selection is absent or ranged. */
+    readonly caret: number | null;
+}
+/**
+ * Fold one selection point to a detect offset.
+ * @param layout - the current walk product.
+ * @param point - selection anchor/focus point.
+ * @returns detect offset, or null when the point references an unknown node.
+ */
+export declare function $detectOffsetOfPoint(layout: ComposerLayout, point: Point): number | null;
+/**
+ * Project the composer document and its caret.
+ * @param idOf - stable occurrence-id assignment per chip NodeKey (the shell
+ * owns the map so ids survive across projections of the same node).
+ * @returns the three-view projection product.
+ */
+export declare function $projectComposer(idOf: (key: NodeKey) => number): EditorProjection;
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/client/input/editor/reference-activation.d.ts

@@ -0,0 +1,10 @@
+import type { LexicalEditor } from 'lexical';
+import type { ReferenceInsert } from '../../contract/draft-editor.ts';
+/**
+ * Install preview activation for atomic chips and editable reference tokens.
+ * @param editor - composer editor.
+ * @param open - live source routing; false preserves ordinary editor handling.
+ * @returns command disposer.
+ */
+export declare function registerReferenceActivation(editor: LexicalEditor, open: (source: string | undefined, reference: Pick<ReferenceInsert, 'ref' | 'appearance'>) => boolean): () => void;
+//# sourceMappingURL=reference-activation.d.ts.map

package/lib/types/client/input/editor/runtime.d.ts

@@ -0,0 +1,123 @@
+/** The Composer model's private Lexical editor, projections, and node operations. */
+import type { ObservableSnapshot } from '@qilin-agent/client-store';
+import type { LexicalEditor } from 'lexical';
+import type { Occurrence, ReferenceInsert } from '../../contract/draft-editor.ts';
+import type { EditorProjection } from './projection.ts';
+import type { DetectSpan } from './span-map.ts';
+type Lexicon = ReadonlyMap<'/' | '@', readonly string[]>;
+/** Model callbacks read at the same editor registration and update points. */
+interface DraftEditorRuntimeDeps {
+    readonly onUpdate: () => void;
+    readonly openReference: (source: string | undefined, reference: Pick<ReferenceInsert, 'ref' | 'appearance'>) => boolean;
+    readonly activeClaimToken: () => string | null;
+    readonly lexicon: () => Lexicon;
+    readonly resolveLexicon: () => ObservableSnapshot<Lexicon> | undefined;
+}
+/** One model-owned editor; registration and disposal remain with its model. */
+export declare class DraftEditorRuntime {
+    private readonly deps;
+    /** The editor bound by the Composer's contenteditable host. */
+    readonly editor: LexicalEditor;
+    private projected;
+    /** Stable occurrence ids per chip NodeKey (undo restores keys, so ids survive it too). */
+    private readonly occurrenceIds;
+    private occurrenceSeq;
+    /** Live lexicon subscription disposer; undefined until the controller resolves. */
+    private lexiconOff;
+    /** @param deps - model callbacks used by editor listeners and transforms. */
+    constructor(deps: DraftEditorRuntimeDeps);
+    /**
+     * Install editor behavior after the model holds this runtime.
+     * @returns unregister callback that also detaches the editor root.
+     */
+    register(): () => void;
+    /** The latest committed editor projection. */
+    get projection(): EditorProjection;
+    /**
+     * Run one editor edit whose result is observable on return. At the top
+     * level this is a discrete update. Inside this editor's own update —
+     * command handlers land here synchronously (space/enter picks, paste) —
+     * $-functions are already legal, and wrapping them in update() would DEFER
+     * them past the synchronous bail answer (and a nested discrete throws);
+     * the body runs directly and the outer update commits it.
+     * @param fn - the $-edit body.
+     */
+    private applyEdit;
+    /**
+     * Subscribe the text-ref re-scan to the controller's lexicon once the
+     * controller resolves. The deps thunk cannot resolve at construction (the
+     * shell is created inside the sessions provide materialization), so the
+     * first interactive updates retry until it can.
+     */
+    private ensureLexiconSubscription;
+    /**
+     * Re-project inside the existing editor update callback.
+     * @returns the projection preceding this read.
+     */
+    refreshProjection(): EditorProjection;
+    private occurrenceIdOf;
+    /**
+     * Replace the whole draft (persisted-draft seed and programmatic writes).
+     * Placeholder-sanitized; newlines split paragraphs; the caret lands at the
+     * end. Merged into history so a seed is not an undoable step of its own.
+     * @param text - the full next draft.
+     */
+    setDraft(text: string): void;
+    /**
+     * Insert pasted plain text over the current editor selection
+     * (placeholder-sanitized). The paste event's own default is suppressed by
+     * the caller; PASTE_TAG makes the paste its own history boundary, so one
+     * undo never removes both the paste and typing inside the merge window.
+     * @param text - pasted plain text.
+     */
+    paste(text: string): void;
+    /**
+     * The live selection as a detect-coordinate span (menu-launcher synthetic
+     * hits replace it on pick); an absent selection answers a collapsed span at
+     * the document end.
+     * @returns the ordered [start, end) span in detect coordinates.
+     */
+    caretSpan(): {
+        start: number;
+        end: number;
+    };
+    /**
+     * Replace a mapped span without applying the model's phase or revision guards.
+     * @param span - detect-coordinate range.
+     * @param text - inserted text.
+     * @returns whether the range mapped and the edit applied.
+     */
+    replaceText(span: DetectSpan, text: string): boolean;
+    /**
+     * Insert an asynchronous text result as one independent undo operation.
+     * @param span - owner-validated insertion range.
+     * @param text - text sanitized with the same rules as paste.
+     * @returns whether the range mapped and the edit applied.
+     */
+    insertAsyncText(span: DetectSpan, text: string): boolean;
+    /**
+     * Insert a reference chip with the existing trailing-space rule.
+     * @param span - detect-coordinate range.
+     * @param ref - reference fields.
+     * @param tail - the character following the range before editing.
+     * @returns whether the range mapped and the edit applied.
+     */
+    insertReference(span: DetectSpan, ref: ReferenceInsert, tail: string): boolean;
+    /** Refresh claim-token decoration after the model's claim changes. */
+    refreshClaimDecoration(): void;
+    /**
+     * Clear committed content using the model's suffix decision inside the editor update.
+     * @param prefixLength - returns the clipboard-prefix length to remove, or null to clear the root.
+     */
+    clearCommittedDraft(prefixLength: (clipboardText: string) => number | null): void;
+    /**
+     * Rebuild one model-selected failure snapshot, creating fresh reference nodes.
+     * @param draft - clipboard text.
+     * @param occurrences - reference occurrences in clipboard order.
+     */
+    restoreDraft(draft: string, occurrences: readonly Occurrence[]): void;
+    /** Cut the editor's undo history after a committed clear or restoration. */
+    clearHistory(): void;
+}
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/lib/types/client/input/editor/span-map.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Detect-coordinate span application: the one place that maps a TokenSpan's
+ * numeric [start, end) back onto Lexical points and applies an edit there.
+ * Every slash/input-* event (begin-command, insert-reference, insert-text,
+ * consume-token) lands through here; revision CAS stays with the caller —
+ * this module only maps and edits. All functions
+ * must run inside `editor.update()`.
+ */
+import type { LexicalNode } from 'lexical';
+/** Half-open [start, end) range in detect coordinates (TokenSpan's plane). */
+export interface DetectSpan {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Select one detect span (collapsed spans place the caret). Exposed for the
+ * shell's caret placement and tests; the replace helpers below build on it.
+ * @param span - detect span to select.
+ * @returns whether both endpoints mapped.
+ */
+export declare function $selectDetectSpan(span: DetectSpan): boolean;
+/**
+ * Replace one detect span with plain text (empty text deletes the span).
+ * The caret lands after the insertion.
+ * @param span - detect span to replace.
+ * @param text - replacement text.
+ * @returns whether the span mapped and the edit applied.
+ */
+export declare function $replaceDetectSpanWithText(span: DetectSpan, text: string): boolean;
+/**
+ * Replace one detect span with nodes (chip insertion path). The caret lands
+ * after the last inserted node.
+ * @param span - detect span to replace.
+ * @param nodes - replacement nodes in order.
+ * @returns whether the span mapped and the edit applied.
+ */
+export declare function $replaceDetectSpanWithNodes(span: DetectSpan, nodes: readonly LexicalNode[]): boolean;
+//# sourceMappingURL=span-map.d.ts.map