@qilin-agent/client-ui-conversation 3.1.4 → 3.1.6

package/lib/index.js

@@ -26,21 +26,25 @@ const CONTENT_WIDTH_STEP = 20;
 /** Content width before the user picks one. */
 const DEFAULT_CONTENT_WIDTH = 0;
 /** Durable conversation schema; also the wire envelope the browser scope validates against. */
-const ConversationSettingsSchema = z.object({
+const ConversationSettingsFields = {
 	[BUSY_ENTER_FIELD]: z.union([...BUSY_ENTER_BEHAVIORS]).default(DEFAULT_BUSY_ENTER_BEHAVIOR),
 	[CONTENT_WIDTH_FIELD]: z.natural().max(CONTENT_WIDTH_MAX).default(0)
-});
+};
+z.object(ConversationSettingsFields);
 //#endregion
 //#region lib/types/index.js
-/** Host registration for browser conversation preferences. */
-/**
-* Register the durable conversation section when a settings provider exists.
-* @param ctx - Host context whose optional settings service owns the section.
+/** Live preferences projected to the browser. */
+const Config = z.object({
+	[BUSY_ENTER_FIELD]: ConversationSettingsFields[BUSY_ENTER_FIELD].volatile(),
+	[CONTENT_WIDTH_FIELD]: ConversationSettingsFields[CONTENT_WIDTH_FIELD].volatile()
+});
+/** Host preferences are consumed through the configuration form projection.
+* @param ctx Plugin context used for optional settings presentation.
 */
 function apply(ctx) {
-	ctx.inject(["settings"], (settingsCtx) => {
-		settingsCtx.settings.register(CONVERSATION_SETTINGS_NAMESPACE, ConversationSettingsSchema);
+	ctx.inject(["settings"], (child) => {
+		child.effect(() => child.settings.configure({ auto: false }, ctx.fiber));
 	});
 }
 //#endregion
-export { BUSY_ENTER_BEHAVIORS, BUSY_ENTER_FIELD, CONTENT_WIDTH_ADAPTIVE, CONTENT_WIDTH_FIELD, CONTENT_WIDTH_MAX, CONTENT_WIDTH_MIN, CONTENT_WIDTH_STEP, CONVERSATION_SETTINGS_NAMESPACE, DEFAULT_BUSY_ENTER_BEHAVIOR, DEFAULT_CONTENT_WIDTH, apply };
+export { BUSY_ENTER_BEHAVIORS, BUSY_ENTER_FIELD, CONTENT_WIDTH_ADAPTIVE, CONTENT_WIDTH_FIELD, CONTENT_WIDTH_MAX, CONTENT_WIDTH_MIN, CONTENT_WIDTH_STEP, CONVERSATION_SETTINGS_NAMESPACE, Config, DEFAULT_BUSY_ENTER_BEHAVIOR, DEFAULT_CONTENT_WIDTH, apply };

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

@@ -5,6 +5,16 @@ import type { ConversationGroupData, ConversationGroupedView, ConversationGroupI
 export interface ConversationMatchResult {
     readonly id: string;
     readonly role: 'start' | 'update';
+    /**
+     * Claim this event on the Definition's target: no other Definition of the
+     * same target receives it, and that target's unmatched-event fallback does
+     * not run. Definitions of other targets and Definitions without a target
+     * still receive it. Two claims on one target, or a claim from a Definition
+     * without a target, throw during dispatch. A claim returned by the fallback
+     * itself has no effect, because the fallback runs only when no Definition of
+     * its target matched.
+     */
+    readonly exclusive?: true;
 }
 /** Merge-extensible business values published against one Turn. */
 export interface ConversationTurnDataMap {

package/lib/types/client/contract/draft-editor.d.ts

@@ -16,6 +16,29 @@ export interface ReferenceInsert {
     readonly appearance?: 'session' | 'file' | 'folder';
     readonly clipboardText: string;
 }
+/** Persisted reference data without the current editor's occurrence identity. */
+export type DraftReference = Omit<Occurrence, 'occurrenceId'>;
+/**
+ * Persisted command chip opening a draft. The claim itself (its submit
+ * closure) is not persisted; the input rebuilds it from the token through the
+ * trigger pipeline when the draft is restored.
+ */
+export interface DraftCommand {
+    /** Claim token with its argument separator, e.g. `/goal `; the draft text starts with the token without the separator. */
+    readonly token: string;
+}
+/**
+ * Editor-independent content. Reference spans are ordered, non-overlapping UTF-16
+ * ranges whose text equals clipboardText and that follow a leading command
+ * token; runtime node identities are excluded.
+ */
+export interface DraftSnapshot {
+    readonly text: string;
+    readonly references: readonly DraftReference[];
+    readonly command?: DraftCommand;
+}
+/** Plain initial text or an existing document with explicit reference identities. */
+export type DraftInput = string | DraftSnapshot;
 /** Keyboard keys intercepted by an open trigger menu. */
 export type ArbitrateKey = 'up' | 'down' | 'enter' | 'escape' | 'tab' | 'tabBack';
 /** Trigger-menu keyboard routing result. */

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

@@ -7,6 +7,7 @@
  * here is the submit plane (phase, claim, attempt) alone.
  */
 import type { Context } from '@qilin-agent/kylin';
+import type { SessionBinding } from '@qilin-agent/api-session-controller/client';
 import type { InboxState } from '@qilin-agent/agent/types';
 import type { ObservableSnapshot, SnapshotStore } from '@qilin-agent/client-store';
 import type { Branded } from '@qilin-agent/brand';
@@ -35,7 +36,7 @@ export interface SubmitOutcome {
 export interface CommandClaim {
     /** Catalog command name without the leading slash (the key of per-command composer copy such as `hint.*`). */
     readonly name: string;
-    /** Inserted command text with its argument separator; the bare complete name also retains the claim. */
+    /** Command spelling followed by its argument separator; the composer shows the spelling as a chip and inserts the separator after it. */
     readonly token: string;
     readonly hint?: string;
     readonly attachments?: boolean;
@@ -109,6 +110,13 @@ export interface InputTriggerController {
     adjudicate(line: string, signal: AbortSignal, envelope: {
         readonly attachments: number;
     }): Promise<PickOutcome>;
+    /**
+     * Resolve the claim a persisted command chip names without acting on it.
+     * @param token - command spelling without its argument separator, e.g. '/goal'.
+     * @param signal - restore-attempt abort.
+     * @returns the claim, or undefined when no source claims the token; rejects when catalog warmup fails.
+     */
+    resolveClaim(token: string, signal: AbortSignal): Promise<CommandClaim | undefined>;
     /**
      * @param source - chip owner, or undefined for a text reference.
      * @param reference - source id and glyph.
@@ -154,14 +162,14 @@ export type DraftAttachmentId = Branded<'DraftAttachmentId'>;
  * applied the edit after phase and span guards).
  */
 export interface InputTarget {
-    /** Replace the trigger span with claim.token and enter claimed (span-CAS'd). */
+    /** Replace the leading trigger span with a command chip and enter claimed (span-CAS'd). */
     beginCommand(claim: CommandClaim, span: TokenSpan): boolean;
     /** Replace the trigger span with one reference chip (span-CAS'd). */
     insertReference(ref: ReferenceInsert, span: TokenSpan): boolean;
 }
 /** Per-session input facade owned by the conversation wiring layer. */
 export interface SessionInput extends InputTarget {
-    /** Replace the whole draft (persisted-draft seed and programmatic writes). */
+    /** Replace the whole draft with plain text, removing inline reference chips. */
     setDraft(text: string): void;
     /** Append ordered browser-owned attachment ids; busy admission phases refuse. */
     addAttachments(ids: readonly DraftAttachmentId[]): boolean;
@@ -196,7 +204,21 @@ export interface SessionInput extends InputTarget {
 export interface SessionInputResolver {
     /** Resolve the facade for one session-scope ctx. */
     for(actx: Context): SessionInput;
+    /**
+     * Prepare the exact retained Session before navigation publishes it.
+     * @param binding - target Session generation, already retained by the caller.
+     * @param options - content to adopt and explicit permission to replace existing text.
+     * @returns applied, preserved, or blocked by a pending submission or disposal.
+     */
+    requestDraftInitialization(binding: SessionBinding, options: DraftInitializationOptions): DraftInitializationResult;
 }
+/** Initial text for a target Session; attachments remain under their existing owner. */
+export interface DraftInitializationOptions {
+    readonly prompt?: string;
+    readonly clearPreviousDraft?: boolean;
+}
+/** An initialization request never waits for a React mount or a remote catalog. */
+export type DraftInitializationResult = 'applied' | 'preserved' | 'blocked';
 /**
  * The public input action face provided to every session-scope slot
  * component: stable-identity void callbacks, mirroring the
@@ -213,8 +235,10 @@ export interface InputActions {
      * @returns false when the draft changed or submission locked the editor.
      */
     insertText(text: string, span: TokenSpan): boolean;
-    /** Replace the whole draft (persisted-draft seed and programmatic writes). */
+    /** Replace the whole draft with plain text, removing inline reference chips. */
     setDraft(text: string): void;
+    /** Write the current semantic document through the mounted persistence callback. */
+    persistDraft(): void;
     /** Append ordered browser-owned attachment ids; busy admission phases refuse. */
     addAttachments(ids: readonly DraftAttachmentId[]): boolean;
     /** Remove one browser-owned attachment id; busy admission phases refuse. */
@@ -272,15 +296,15 @@ export interface SubmitAttempt {
 /**
  * Submit-machine input events (the machine's single write path). Text
  * mutation lives in the editor; the machine only observes the draft through
- * event payloads (claim integrity, enter snapshots, settlement decisions).
+ * event payloads (leading command chip, enter snapshots, settlement decisions).
  */
 export type InputEvent = 
-/** Clipboard projection changed: the claimed integrity watch runs (zero effects). */
+/** Editor content changed; carries the claim of the leading command chip, if any (zero effects). */
 {
     readonly type: 'draft-changed';
-    readonly draft: string;
+    readonly command: CommandClaim | undefined;
 }
-/** The editor applied a claim-token replacement: enter claimed. */
+/** The editor inserted a command chip: enter claimed. */
  | {
     readonly type: 'claim';
     readonly claim: CommandClaim;
@@ -299,12 +323,12 @@ export type InputEvent =
     readonly attempt: SubmitAttempt;
     readonly message: string;
 }
-/** Settlement carries the live clipboard projection for suffix-retention and claim re-entry decisions. */
+/** Settlement carries the leading command chip's claim, which the claim follows after a failure. */
  | {
     readonly type: 'submit-settled';
     readonly attempt: SubmitAttempt;
     readonly ok: boolean;
-    readonly draft: string;
+    readonly command: CommandClaim | undefined;
     readonly outcome?: SubmitOutcome;
     readonly message?: string;
 }

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

@@ -122,8 +122,9 @@ export type ModelRetryNode = LlmRetryEventData & {
     retryState: 'scheduled' | 'started' | 'cancelled';
 };
 /**
- * Durable terminal failure for a turn that ended with an error reason; the
- * turn's settled retry chain renders separately and never replaces this node.
+ * Durable terminal notice for a turn that ended with an error, a sign-out
+ * cancellation, or an interruption by a QiLin stop; the turn's settled retry
+ * chain renders separately and never replaces this node.
  */
 export interface TurnErrorNode {
     kind: 'turn-error';
@@ -135,7 +136,11 @@ export interface TurnErrorNode {
     step: number;
     /** Sanitized provider message; empty when a known code owns localized copy. */
     message: string;
-    /** Stable provider failure code, when recorded. */
+    /**
+     * Stable provider failure code when recorded, or a Client display code:
+     * `ACCOUNT_SIGNED_OUT` for a sign-out cancellation, `INTERRUPTED` for a turn
+     * closed after QiLin stopped.
+     */
     code?: string;
 }
 /** Durable notice for a turn ended by the per-request output-token cap. */

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

@@ -11,7 +11,7 @@ import type { SessionId } from '@qilin-agent/session/types';
 import type { WorkspaceId } from '@qilin-agent/workspace/types';
 import type { ComposerBlock } from './composer-blocks.ts';
 import type { DraftAttachmentId, InputActions, InputNotice, InputState } from './input.ts';
-import type { ComposerKeyboard, EditSelection } from './draft-editor.ts';
+import type { ComposerKeyboard, DraftSnapshot, EditSelection } from './draft-editor.ts';
 import type { createConversationStore } from '../stores.ts';
 import type { BusyEnterBehavior } from './composer-submission.ts';
 import type { ConversationSnapshot } from './snapshot.ts';
@@ -211,6 +211,11 @@ declare module '@qilin-agent/client-ui-slots' {
             scope: 'session-maybe';
             owner: HeroAgentPresetOwnerProps;
         };
+        /** Compact options right-aligned in the New Session row after the workspace and preset controls; rendered only with a Session. */
+        'conversation.hero.options': {
+            kind: 'list';
+            scope: 'session';
+        };
         /** Full-width entries above the composer card. */
         'conversation.input.dock': {
             kind: 'list';
@@ -312,6 +317,10 @@ declare module '@qilin-agent/client-ui-slots' {
                     kind: 'single';
                     scope: 'session-maybe';
                 };
+                'conversation.hero.options': {
+                    kind: 'list';
+                    scope: 'session';
+                };
             };
             inject: ConversationInjected;
             locale: 'conversation';
@@ -414,7 +423,7 @@ export interface ConversationSessionInjected {
         readonly conversationViews: ObservableSnapshot<readonly ViewTab[]>;
     };
     /** Bind input draft persistence to the Session-owned store instance. */
-    bindDraftMirror: (write: (text: string) => void) => () => void;
+    bindDraftPersistence: (write: (draft: DraftSnapshot) => void) => () => void;
     /** Select and activate one View while addressing an opaque focus request to it. */
     openView: (view: string, focus: string) => void;
 }

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

@@ -1,4 +1,5 @@
 /** Conversation view and session-local presentation state. */
+import type { DraftInput } from './draft-editor.ts';
 /**
  * One conversation view tab, projected from a 'conversation.view' slot
  * entry's registration options (label falls back to the entry id).
@@ -27,7 +28,7 @@ export interface ConversationViewRequest {
 /** The conversation store's own state: the composer draft, the selected View, and one pending focus request. */
 export interface ConversationStoreState {
     /** Composer draft (persisted; survives session switches and reloads). */
-    draft: string;
+    draft: DraftInput;
     /** Preferred `conversation.view` entry id; null resolves to Chat when registered. */
     view: string | null;
     /** One-shot focus request addressed to the selected View. */

package/lib/types/client/conversation/assembler.d.ts

@@ -43,6 +43,9 @@ export declare class ConversationNodeAssembler implements ConversationViewSnapsh
     private readonly groups;
     private readonly pendingGroupStores;
     private readonly activeTargets;
+    /** Matches of the event in dispatch, kept by index; dispatch is not reentrant and reuses both arrays. */
+    private readonly matchedDefinitions;
+    private readonly matchedResults;
     private hasMore;
     private replacePending;
     private timelineDirty;

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

@@ -0,0 +1,22 @@
+import type { DraftInput, DraftSnapshot, Occurrence } from './contract/draft-editor.ts';
+/**
+ * Copy input into the semantic draft representation without editor runtime identities.
+ * @param input - plain text or caller-owned structured content.
+ * @returns an owned snapshot ready for editor import.
+ */
+export declare function resolveDraftInput(input: DraftInput): DraftSnapshot;
+/**
+ * Decode persisted drafts, accepting the earlier plain-string representation.
+ * @param value - JSON value read from browser storage.
+ * @returns the decoded draft, or undefined for invalid data.
+ */
+export declare function parseStoredDraft(value: unknown): DraftSnapshot | undefined;
+/**
+ * Export reference identities without their editor-local occurrence ids.
+ * @param text - current clipboard projection.
+ * @param occurrences - matching reference projections from the same document revision.
+ * @param commandToken - claim token of the command chip opening the document, if any.
+ * @returns an editor-independent snapshot.
+ */
+export declare function snapshotDraft(text: string, occurrences: readonly Occurrence[], commandToken?: string): DraftSnapshot;
+//# sourceMappingURL=draft.d.ts.map

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

@@ -25,8 +25,8 @@ export type { ConversationLocationDataChange } from './conversation/location-ind
 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 { BeginCommandRequest, CommandClaim, ConsumeTokenRequest, DraftAttachmentId, DraftInitializationOptions, DraftInitializationResult, InputActions, InputState, InsertReferenceRequest, InsertTextRequest, PickOutcome, SessionInput, SessionInputResolver, SubmitAttachment, SubmitOutcome, } from './contract/input.ts';
+export type { ArbitrateKey, ArbitrateOutcome, DraftInput, DraftReference, DraftSnapshot, ReferenceInsert, TokenSpan } from './contract/draft-editor.ts';
 export type { ComposerBlock, ComposerBlocks } from './contract/composer-blocks.ts';
 declare module '@qilin-agent/kylin' {
     interface Context {

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

@@ -25,7 +25,7 @@ export interface TextRefRange {
  * 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).
+ * @param lexicon - per-trigger name lists; missing catalogs match no named tokens.
  * @returns matched ranges in draft order.
  */
 export declare function scanTextRefs(draft: string, lexicon: ReadonlyMap<'/' | '@', readonly string[]>): TextRefRange[];

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

@@ -0,0 +1,13 @@
+import type { ReactNode } from 'react';
+/** Display inputs of the command chip. */
+export interface CommandChipProps {
+    /** Claimed token without its argument separator, e.g. `/goal`. */
+    readonly token: string;
+}
+/**
+ * Render the claimed command chip.
+ * @param props - the token to display.
+ * @returns the chip body.
+ */
+export declare function CommandChip({ token }: CommandChipProps): ReactNode;
+//# sourceMappingURL=CommandChip.d.ts.map

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

@@ -0,0 +1,87 @@
+/**
+ * CommandChipNode: the claimed slash command as one atomic Lexical decorator
+ * on the document's leading seat. The node carries the claim it was inserted
+ * for, so a history restore of the node restores the claim with it.
+ * `getTextContent()` answers the token without its argument separator; the
+ * separator is an ordinary text node after the chip. The detect projection
+ * counts the chip as one U+FFFC; see projection.ts.
+ */
+import type { JSX } from 'react';
+import type { LexicalEditor, LexicalNode, NodeKey, SerializedLexicalNode, Spread } from 'lexical';
+import { DecoratorNode } from 'lexical';
+import type { CommandClaim } from '../../contract/input.ts';
+/** JSON form of one command chip (Lexical node serialization contract). */
+export type SerializedCommandChipNode = Spread<{
+    text: string;
+}, SerializedLexicalNode>;
+/** One claimed command as an atomic decorator node. */
+export declare class CommandChipNode extends DecoratorNode<JSX.Element> {
+    /** The claim this chip anchors; its submit closure has no JSON form. */
+    __claim: CommandClaim;
+    /** 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 and claim.
+     */
+    static clone(node: CommandChipNode): CommandChipNode;
+    /**
+     * Rebuild one chip from its JSON form. JSON cannot carry the claim's
+     * submit closure, so an imported command is its literal token text.
+     * @param json - serialized chip.
+     * @returns a plain text node holding the token.
+     */
+    static importJSON(json: SerializedCommandChipNode): LexicalNode;
+    /**
+     * @param claim - the command claim the chip anchors.
+     * @param key - Lexical clone-path key; absent for fresh nodes.
+     */
+    constructor(claim: CommandClaim, key?: NodeKey);
+    /** Serialize to the JSON node form (the token text alone). */
+    exportJSON(): SerializedCommandChipNode;
+    /**
+     * Mount the chip's host element; the decorator portal renders into it.
+     * @returns an inline, non-editable span carrying the test/e2e anchor.
+     */
+    createDOM(): HTMLElement;
+    /** Host element never changes shape. */
+    updateDOM(): boolean;
+    /** The chip sits in the text line. */
+    isInline(): boolean;
+    /**
+     * Arrows step across the chip and the default character deletion removes
+     * it whole, for the reason documented on ReferenceChipNode.isKeyboardSelectable;
+     * registerCommandChipSelection inserts the selecting step before that deletion.
+     */
+    isKeyboardSelectable(): boolean;
+    /** Clipboard / persistence projection: the token without its separator. */
+    getTextContent(): string;
+    /** The claim this chip anchors. */
+    getClaim(): CommandClaim;
+    /** React face rendered into the host element by the decorator portal. */
+    decorate(): JSX.Element;
+}
+/**
+ * Mint one chip node for a claim.
+ * @param claim - the command claim.
+ * @returns the fresh node.
+ */
+export declare function $createCommandChipNode(claim: CommandClaim): CommandChipNode;
+/**
+ * Command chip type guard.
+ * @param node - any node or nullish.
+ * @returns whether the node is a CommandChipNode.
+ */
+export declare function $isCommandChipNode(node: LexicalNode | null | undefined): node is CommandChipNode;
+/**
+ * Keep command chips on the leading seat. A chip anywhere but the first
+ * child of the first block (text, a line break, or a block inserted before
+ * it) becomes its literal token, which releases the claim. Inserting a
+ * sibling before the chip or moving it to another block marks the chip dirty;
+ * a block inserted before the chip's block marks only that block dirty.
+ * @param editor - the shell-owned editor.
+ * @returns the unregister disposer.
+ */
+export declare function registerCommandChipSeat(editor: LexicalEditor): () => void;
+//# sourceMappingURL=command-chip-node.d.ts.map

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

@@ -0,0 +1,20 @@
+/**
+ * Two-step command chip deletion. A character deletion whose direction
+ * reaches the command chip from a collapsed caret first selects the chip; the
+ * next deletion in that direction removes it. Deletions arrive as the
+ * character-deletion command (Backspace, Delete, and the platform shortcuts
+ * the engine maps to them) or as a deletion input event, which some platforms
+ * apply without that command. A key that produces no character deletion, a
+ * click, blur, or a caret that no longer touches the chip clears the
+ * selection. The selected state is presentation on the chip's host and the
+ * root element; the editor selection stays a collapsed range beside the chip,
+ * so typing and arrows keep their plain-text behavior.
+ */
+import type { LexicalEditor } from 'lexical';
+/**
+ * Register two-step deletion for the command chip.
+ * @param editor - the shell-owned editor.
+ * @returns the unregister disposer, which also clears a selected chip.
+ */
+export declare function registerCommandChipSelection(editor: LexicalEditor): () => void;
+//# sourceMappingURL=command-chip-selection.d.ts.map

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

@@ -9,6 +9,7 @@
  */
 import type { LexicalNode, NodeKey, Point } from 'lexical';
 import type { Occurrence } from '../../contract/draft-editor.ts';
+import type { CommandClaim } from '../../contract/input.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. */
@@ -75,6 +76,8 @@ export interface EditorProjection {
     } | null;
     /** Collapsed caret in detect coordinates; null while the selection is absent or ranged. */
     readonly caret: number | null;
+    /** Claim of the command chip opening the document; undefined without one. */
+    readonly command: CommandClaim | undefined;
 }
 /**
  * Fold one selection point to a detect offset.

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

@@ -1,7 +1,8 @@
 /** 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 { DraftReference, ReferenceInsert } from '../../contract/draft-editor.ts';
+import type { CommandClaim } from '../../contract/input.ts';
 import type { EditorProjection } from './projection.ts';
 import type { DetectSpan } from './span-map.ts';
 type Lexicon = ReadonlyMap<'/' | '@', readonly string[]>;
@@ -9,7 +10,6 @@ type Lexicon = ReadonlyMap<'/' | '@', readonly string[]>;
 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;
 }
@@ -24,6 +24,7 @@ export declare class DraftEditorRuntime {
     private occurrenceSeq;
     /** Live lexicon subscription disposer; undefined until the controller resolves. */
     private lexiconOff;
+    private lexiconSource;
     /** @param deps - model callbacks used by editor listeners and transforms. */
     constructor(deps: DraftEditorRuntimeDeps);
     /**
@@ -44,12 +45,10 @@ export declare class DraftEditorRuntime {
      */
     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.
+     * Reconnect decorations when the optional trigger provider changes.
+     * The rescan reads the current editor and does not replace its content.
      */
-    private ensureLexiconSubscription;
+    refreshLexiconSubscription(): void;
     /**
      * Re-project inside the existing editor update callback.
      * @returns the projection preceding this read.
@@ -103,19 +102,28 @@ export declare class DraftEditorRuntime {
      * @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;
+    /**
+     * Replace a span with a command chip followed by the claim token's
+     * argument separator, unless the separator already follows.
+     * @param span - detect-coordinate range.
+     * @param claim - the command claim the chip anchors.
+     * @param tail - the character following the range before editing.
+     * @param mergeHistory - merge into the previous history entry (a restored
+     * draft's chip is part of its seed, not an undoable step).
+     * @returns whether the range mapped and the edit applied.
+     */
+    insertCommand(span: DetectSpan, claim: CommandClaim, tail: string, mergeHistory?: boolean): boolean;
     /**
      * 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.
+     * Import semantic content or a model-selected failure snapshot with fresh reference nodes.
      * @param draft - clipboard text.
      * @param occurrences - reference occurrences in clipboard order.
      */
-    restoreDraft(draft: string, occurrences: readonly Occurrence[]): void;
+    restoreDraft(draft: string, occurrences: readonly DraftReference[]): void;
     /** Cut the editor's undo history after a committed clear or restoration. */
     clearHistory(): void;
 }

package/lib/types/client/input/editor/text-ref.d.ts

@@ -28,17 +28,12 @@ export declare class TextRefNode extends TextNode {
     canInsertTextBefore(): boolean;
 }
 /**
- * Register the plain-text reference entity transform. The claim decoration
- * has precedence on the leading-token seat: while a command claim holds, the
- * claimed token must stay a plain TextNode (transforms register per concrete
- * node class, so a TextRefNode would never receive the TextNode claim
- * transform and the warn color would be lost).
+ * Register the plain-text reference entity transform.
  * @param editor - the shell-owned editor.
  * @param lexiconOf - live per-trigger name-roll accessor (the controller's aggregated store).
- * @param activeToken - live claim token accessor; null while unclaimed.
  * @returns the unregister disposer.
  */
-export declare function registerTextRefDecoration(editor: LexicalEditor, lexiconOf: () => ReadonlyMap<'/' | '@', readonly string[]>, activeToken: () => string | null): () => void;
+export declare function registerTextRefDecoration(editor: LexicalEditor, lexiconOf: () => ReadonlyMap<'/' | '@', readonly string[]>): () => void;
 /**
  * Force a re-scan of the whole document (transforms only visit dirty nodes;
  * a lexicon roll change dirties nothing on its own). Queued, not discrete —