@deepseek-ai/dsh-client-ui-conversation 0.1.6-alpha.2 → 0.1.7-alpha.2

package/lib/index.js

@@ -10,18 +10,19 @@ const BUSY_ENTER_BEHAVIORS = ["queue", "steer"];
 /** Default preserves Enter-as-Queue for running conversations. */
 const DEFAULT_BUSY_ENTER_BEHAVIOR = "queue";
 /** Durable conversation schema; also the wire envelope the browser scope validates against. */
-const ConversationSettingsSchema = z.object({ [BUSY_ENTER_FIELD]: z.union([...BUSY_ENTER_BEHAVIORS]).default(DEFAULT_BUSY_ENTER_BEHAVIOR) });
+const ConversationSettingsFields = { [BUSY_ENTER_FIELD]: z.union([...BUSY_ENTER_BEHAVIORS]).default(DEFAULT_BUSY_ENTER_BEHAVIOR) };
+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() });
+/** 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, CONVERSATION_SETTINGS_NAMESPACE, DEFAULT_BUSY_ENTER_BEHAVIOR, apply };
+export { BUSY_ENTER_BEHAVIORS, BUSY_ENTER_FIELD, CONVERSATION_SETTINGS_NAMESPACE, Config, DEFAULT_BUSY_ENTER_BEHAVIOR, apply };

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

@@ -1,5 +1,6 @@
 import type { SessionEventLike } from '@deepseek-ai/dsh-api-session-controller/client';
 import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+import type { ConversationGroupData, ConversationGroupedView, ConversationGroupInput } from './groups.ts';
 /** Definition-local identity and lifecycle role extracted from one event. */
 export interface ConversationMatchResult {
     readonly id: string;
@@ -119,6 +120,12 @@ export interface ConversationViewSnapshotMap {
 export interface ConversationViewSnapshotStore {
     /** @param target - registered view target. @returns its current snapshot. */
     get<Target extends Extract<keyof ConversationViewSnapshotMap, string>>(target: Target): ConversationViewSnapshotMap[Target] | undefined;
+    /**
+     * Read grouping for an activated target without activating another target.
+     * @param target - registered View target.
+     * @returns its grouped reader, when a Group Definition is active.
+     */
+    grouped<Target extends string>(target: Target): ConversationGroupedView<ConversationGroupData<Target>> | undefined;
 }
 /** Immutable public view of an assembled business Context. */
 export interface ConversationNodeContext<State = unknown> {
@@ -222,6 +229,7 @@ export interface ConversationViewBuilder<Node extends ConversationViewNode = Con
     replace(input: {
         readonly nodes: readonly Node[];
         readonly timeline: ConversationTimelineSnapshot;
+        readonly changedTurns?: readonly number[];
     }): Snapshot;
     /**
      * Apply only Nodes whose materialized values changed in this transaction.
@@ -231,11 +239,22 @@ export interface ConversationViewBuilder<Node extends ConversationViewNode = Con
     apply(input: {
         readonly upserts: readonly Node[];
         readonly timeline: ConversationTimelineSnapshot;
+        readonly changedTurns?: readonly number[];
     }): Snapshot;
+    /** @returns the latest target-processed Node inputs; required only for a grouped target. */
+    groupInput?(): ConversationGroupInput<Node>;
+    /** Publish local sources after all target snapshots and grouping results have been installed. */
+    publish?(): void;
 }
 /** Registry contribution that creates an isolated builder when a Session first uses this target. */
 export interface ConversationViewDefinition<Node extends ConversationViewNode = ConversationViewNode, Snapshot = unknown> {
     readonly target: string;
+    /**
+     * Address a tool call in this target's inspector; absent for non-inspection views.
+     * @param callId - tool-call identity from the Session.
+     * @returns the target's opaque focus identity.
+     */
+    toolCallFocus?(callId: string): string;
     /** @returns a new Session-owned incremental builder. */
     create(): ConversationViewBuilder<Node, Snapshot>;
     /**

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

@@ -0,0 +1,116 @@
+/** Definition-owned grouping over a target's already materialized Nodes. */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { ConversationTimelineSnapshot, ConversationViewNode } from './conversation.ts';
+/** Existing Node identity, without allocating another execution Node. */
+export type NodeKey = Branded<'ConversationNodeKey'>;
+/** Definition-local group identity within one Session and target. */
+export type GroupKey = Branded<'ConversationGroupKey'>;
+/** One whole Node or a renderer-owned part of that Node. */
+export interface NodeReference {
+    readonly kind: 'node';
+    readonly key: NodeKey;
+    readonly groupPart?: string;
+}
+/** Root-list reference to a separately observed group. */
+export interface GroupReference {
+    readonly kind: 'group';
+    readonly key: GroupKey;
+}
+/** The two supported root rendering positions. */
+export type RenderEntry = NodeReference | GroupReference;
+/** Immutable group data and its ordered, non-nested Node references. */
+export interface GroupSnapshot<Data> {
+    readonly key: GroupKey;
+    readonly data: Data;
+    readonly members: readonly NodeReference[];
+}
+/**
+ * One atomic grouping update. Replacement input requires entries and a complete
+ * group replacement; apply input may omit entries to preserve the root list.
+ * Group removal never deletes source Nodes.
+ */
+export interface GroupUpdate<Data> {
+    /** Complete root sequence; only its Node references and referenced group members render. */
+    readonly entries?: readonly RenderEntry[];
+    readonly groups: {
+        readonly kind: 'replace';
+        readonly snapshots: readonly GroupSnapshot<Data>[];
+    } | {
+        readonly kind: 'apply';
+        readonly upserts: readonly GroupSnapshot<Data>[];
+        readonly removes: readonly GroupKey[];
+    };
+}
+/** Target-processed Node values before and after one update. */
+export interface NodeChange<Node> {
+    readonly previous: Node | undefined;
+    readonly current: Node;
+}
+/** Owning Turn and immediate neighbours in the target's visible Node order. */
+export interface GroupNodePosition {
+    readonly turn: number | undefined;
+    readonly previous: NodeKey | undefined;
+    readonly next: NodeKey | undefined;
+}
+interface GroupInputNodes<Node> {
+    readonly order: readonly NodeKey[];
+    /** @param key - target Node identity. @returns its current value during this synchronous update. */
+    readonly readNode: (key: NodeKey) => Node | undefined;
+    /** @param turn - owning Turn. @returns its visible keys in target order; empty when absent. */
+    readonly readTurn: (turn: number) => readonly NodeKey[];
+    /** @param key - target Node identity. @returns its visible position, or absence outside the target order. */
+    readonly readPosition: (key: NodeKey) => GroupNodePosition | undefined;
+    readonly timeline: ConversationTimelineSnapshot;
+}
+/** Target-local inputs; apply includes lifecycle changes without Node upserts. */
+export type ConversationGroupInput<Node> = GroupInputNodes<Node> & ({
+    readonly kind: 'replace';
+} | {
+    readonly kind: 'apply';
+    readonly changes: readonly NodeChange<Node>[];
+    readonly changedTurns: readonly number[];
+    /** Turns whose visible keys or immediate neighbours changed, including removal and cross-Turn moves. */
+    readonly changedTurnOrders: readonly number[];
+});
+/** Framework-owned State for one Session's registered Group Definition. */
+export interface ConversationGroupContext<State> {
+    readonly state: State;
+}
+/** Business grouping rules, driven after the target Builder has installed Nodes. */
+export interface ConversationGroupDefinition<Node extends ConversationViewNode = ConversationViewNode, State = unknown, Data = unknown> {
+    readonly kind: string;
+    readonly target: string;
+    /** @returns initial Session-local grouping State. */
+    create(): State;
+    /**
+     * Consume target Node changes, not raw Session events or presentation modes.
+     * @param context - current Session-local State.
+     * @param input - current target inputs; its readers are valid only during this call.
+     * @returns State adopted by the framework.
+     */
+    update(context: ConversationGroupContext<State>, input: ConversationGroupInput<Node>): State;
+    /**
+     * Materialize pending grouping changes without changing the business State.
+     * @param context - State adopted after update.
+     * @returns complete output for replace input; an update or null when unchanged for apply input.
+     */
+    buildGroups(context: ConversationGroupContext<State>): GroupUpdate<Data> | null;
+}
+/** Merge-extensible group data associated with each registered target. */
+export interface ConversationGroupDataMap {
+}
+/** Group data declared by a target; undeclared targets have no group payload. */
+export type ConversationGroupData<Target extends string> = Target extends keyof ConversationGroupDataMap ? ConversationGroupDataMap[Target] : never;
+/** Stable grouped reader; data-only updates preserve entries and member arrays. */
+export interface ConversationGroupedView<Data> {
+    readonly entries: readonly RenderEntry[];
+    /**
+     * Observe a group without subscribing to the root sequence.
+     * @param key - group identity within this target.
+     * @returns an identity-stable source, whose value is absent after removal.
+     */
+    groupSource(key: GroupKey): ObservableSnapshot<GroupSnapshot<Data> | undefined>;
+}
+export {};
+//# sourceMappingURL=groups.d.ts.map

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

@@ -204,6 +204,15 @@ export interface SessionInputResolver {
  * paste/…) stay InputBar-private and never ride this face.
  */
 export interface InputActions {
+    /** @returns a revision-guarded copy of the current editor selection. */
+    captureInsertion(): TokenSpan;
+    /**
+     * Insert asynchronous text without replacing subsequent edits or reference chips.
+     * @param text - plain text to insert in one undo step.
+     * @param span - captured selection and draft revision.
+     * @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). */
     setDraft(text: string): void;
     /** Append ordered browser-owned attachment ids; busy admission phases refuse. */

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

@@ -198,13 +198,9 @@ export interface CompactionSummaryNode {
     shadowedTokenCount: number | null;
 }
 /**
- * Fallback for surface events this UI version does not know: the documented
- * default arm of `SessionEventMap`, which is merge-extensible, so the
- * projection's switch cannot end in `assertNever`. No event produces this node
- * because `isAppendSurfaceEvent` admits only the four types in core's
- * `SurfaceEventType`, and each has its own arm (`system/message` is claimed by
- * a Chat Definition that renders no transcript row) — and it exists so widening
- * that set core-side degrades to a raw row instead of dropping the event silently.
+ * Fallback for unclaimed append-surface events. The merge-extensible
+ * SessionEventMap permits unfamiliar events to retain a raw presentation.
+ * Known unsupported developer events throw before fallback selection.
  */
 export interface UnknownSurfaceNode {
     kind: 'unknown';

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

@@ -56,8 +56,12 @@ export interface ComposerAttachmentsOwnerProps {
     attachments: readonly ComposerAttachment[];
     /** Whether a document-level file drop may add attachments now. */
     canAcceptDrop: boolean;
-    /** Add one dropped batch through the composer's validation path. */
-    onAddFiles: (files: readonly File[]) => void;
+    /**
+     * Add one dropped batch through the composer's validation path.
+     * @param files - dropped, pasted, or picked browser files in source order.
+     * @param directories - members of `files` the drop source identified as directories.
+     */
+    onAddFiles: (files: readonly File[], directories?: ReadonlySet<File>) => void;
     /** Remove one draft attachment through the Conversation service. */
     onRemoveAttachment: (id: DraftAttachmentId) => void;
     /** Current per-draft upload states for file-kind attachments. */
@@ -127,10 +131,19 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
                 view?: string;
             };
         };
+        /** Resident navigation container, including when no Session is selected. */
+        'conversation.header': {
+            kind: 'single';
+            scope: 'session-maybe';
+        };
         /** Strict per-Session title, actions, and View navigation. */
         'conversation.session.header': {
             kind: 'single';
             scope: 'session';
+            owner: {
+                /** Parent-owned visibility shared with the header container styling. */
+                hideChrome: boolean;
+            };
         };
         /** Optional replacement for one Session breadcrumb title. */
         'conversation.session.header.lineage': {
@@ -150,16 +163,10 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
             scope: 'session';
             owner: ConversationHeaderActionOwnerProps;
         };
-        /**
-         * Leading seat before the Session breadcrumbs, for window-chrome-adjacent
-         * controls (macOS desktop sidebar reopen and New Session while the sidebar
-         * is hidden). The seat is laid out only while its occupant renders
-         * something, and it stays mounted through the blank-session state so a
-         * hidden sidebar always keeps a reopen control on screen.
-         */
-        'conversation.session.header.leading': {
+        /** Global navigation before the Session title, available without a Session. */
+        'conversation.header.leading': {
             kind: 'single';
-            scope: 'session';
+            scope: 'root';
             owner: ConversationHeaderLeadingOwnerProps;
         };
         /**
@@ -229,6 +236,12 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
             kind: 'list';
             scope: 'session';
         };
+        /** Compact action after the model selector; it can expand across the toolbar while retaining the editor and submit action. */
+        'conversation.input.activity': {
+            kind: 'single';
+            scope: 'session';
+            owner: InputActivityOwnerProps;
+        };
         /** Resident composer body, including the no-Session inert state. */
         'conversation.composer.bar': {
             kind: 'single';
@@ -253,7 +266,11 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
             scope: 'session';
             owner: InputControlOwnerProps;
         };
-        /** Model selector inside the composer tool row. */
+        /**
+         * Model selector inside the composer tool row. When expanded controls cannot
+         * share a line, the row sets --dsh-composer-model-text-display to none and
+         * --dsh-composer-model-icon-display to block for an occupant's compact display.
+         */
         'conversation.input.model': {
             kind: 'single';
             scope: 'session';
@@ -344,7 +361,7 @@ export interface ConversationHeaderCornerOwnerProps {
     /** Marker field: the occupant receives no owner-specific values. */
     children?: never;
 }
-/** The leading seat's occupant derives its state from standard Session props. */
+/** The leading seat exposes global navigation independently of a Session. */
 export interface ConversationHeaderLeadingOwnerProps {
     /** Marker field: the occupant receives no owner-specific values. */
     children?: never;
@@ -365,6 +382,8 @@ export interface InputZone {
 }
 /** Conversation View entries obtain their data from registered standard hooks. */
 export interface ConvViewOwnerProps {
+    /** Open a tool call's inspector when an inspection target is available. */
+    inspectCall: ((callId: string) => void) | undefined;
     /** Focus request addressed to the selected View. */
     viewRequest: import('./views.ts').ConversationViewRequest | null;
     /** Select a View and address one opaque focus identity to it. */
@@ -388,6 +407,7 @@ export interface ConversationSessionInjected {
     /** Package-owned View roster source bound only for the Conversation body. */
     readonly hooks: {
         readonly conversationViews: ObservableSnapshot<readonly ViewTab[]>;
+        readonly inspectCall: ObservableSnapshot<ConvViewOwnerProps['inspectCall']>;
     };
     /** Bind input draft persistence to the Session-owned store instance. */
     bindDraftMirror: (write: (text: string) => void) => () => void;
@@ -426,7 +446,14 @@ export interface ComposerBarOwnerProps {
 /** Package-private operations injected into the resident composer bar. */
 export interface ComposerBarInjected {
     keyboard: ComposerKeyboard | undefined;
-    addFiles: ((files: readonly File[]) => string | null) | undefined;
+    /**
+     * Register one picked batch; resolves to the rejection copy or null. Where
+     * the browser shell reports host paths (the Desktop application), files
+     * and folders with a real path become `@path` references in the draft
+     * instead of uploads; `directories` names the members the drop source
+     * identified as directories.
+     */
+    addFiles: ((files: readonly File[], directories?: ReadonlySet<File>) => string | null) | undefined;
     removeAttachment: ((id: DraftAttachmentId) => void) | undefined;
     resolveDraftAttachments: ((ids: readonly DraftAttachmentId[]) => readonly ComposerAttachment[]) | undefined;
     /** Restart one failed file upload; absent without a session. */
@@ -451,8 +478,13 @@ export interface InputControlOwnerProps {
     /** Whether the composer currently refuses interaction. */
     locked: boolean;
 }
+/** A toolbar activity hides ordinary accessory controls while expanded; its occupant must release expansion on unmount. */
+export interface InputActivityOwnerProps extends InputControlOwnerProps {
+    /** @param active - whether the occupant needs the toolbar width before the submit action. */
+    onActiveChange: (active: boolean) => void;
+}
 /** Full props of the resident composer bar. */
-export type ComposerBarProps = PropsRuntime<'conversation.composer.bar'> & PropsRenderSlots<'conversation.input.attachments' | 'conversation.input.overlay' | 'conversation.input.permission' | 'conversation.input.left' | 'conversation.input.plan' | 'conversation.input.right' | 'conversation.input.model' | 'conversation.composer.dock'> & InjectFace<ComposerBarInjected> & PropsLocale<'conversation'>;
+export type ComposerBarProps = PropsRuntime<'conversation.composer.bar'> & PropsRenderSlots<'conversation.input.attachments' | 'conversation.input.overlay' | 'conversation.input.permission' | 'conversation.input.left' | 'conversation.input.plan' | 'conversation.input.right' | 'conversation.input.model' | 'conversation.input.activity' | 'conversation.composer.dock'> & InjectFace<ComposerBarInjected> & PropsLocale<'conversation'>;
 /** Owner values used to elect a composer takeover. */
 export interface ComposerChainProps {
     /** Current Session identity used by temporary business-owned entries. */
@@ -470,7 +502,7 @@ export interface HeroBrandMarkOwnerProps {
     className?: string | undefined;
 }
 /** Full props of the resident optional-Session Conversation shell. */
-export type ConversationSlotProps = PropsRuntime<'main.conversation'> & PropsRenderSlots<'conversation.session.header'> & PropsRenderFactories;
+export type ConversationSlotProps = PropsRuntime<'main.conversation'> & PropsRenderSlots<'conversation.header'> & PropsRenderFactories;
 /** Inputs shared by main and embedded Conversation content occurrences. */
 export interface ConversationContentInputProps {
     variant: 'main' | 'embedded';
@@ -494,8 +526,10 @@ export type ConversationViewsProps = FactoryLocalComponentPropsOf<'conversation.
 export type ConversationWidthControlsProps = FactoryLocalComponentPropsOf<'conversation.content', 'widthControls'>;
 /** Full props of the strict Session body. */
 export type ConversationSessionSlotProps = PropsRuntime<'conversation.session'> & PropsRenderSlots<'conversation.view'> & PropsStore<ConversationStore> & InjectFace<ConversationSessionInjected>;
+/** Full props of the resident navigation header. */
+export type ConversationHeaderProps = PropsRuntime<'conversation.header'> & PropsRenderSlots<'conversation.header.leading' | 'conversation.session.header'>;
 /** Full props of the strict Session header. */
-export type ConversationSessionHeaderSlotProps = PropsRuntime<'conversation.session.header'> & PropsRenderSlots<'conversation.session.header.lineage' | 'conversation.session.header.leading' | 'conversation.session.header.actions' | 'conversation.session.header.utilities' | 'conversation.session.header.corner'> & PropsStore<ConversationStore> & InjectFace<ConversationSessionHeaderInjected> & PropsLocale<'conversation'>;
+export type ConversationSessionHeaderSlotProps = PropsRuntime<'conversation.session.header'> & PropsRenderSlots<'conversation.session.header.lineage' | 'conversation.session.header.actions' | 'conversation.session.header.utilities' | 'conversation.session.header.corner'> & PropsStore<ConversationStore> & InjectFace<ConversationSessionHeaderInjected> & PropsLocale<'conversation'>;
 /** Full props of the draft-attachment renderer. */
 export type ComposerAttachmentsProps = PropsRuntime<'conversation.input.attachments'> & PropsLocale<'conversation'>;
 /** Owner share common to blank-session Workspace pickers. */

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

@@ -1,6 +1,7 @@
 import type { SessionAssistantSettlementEntry, SessionEventLikeEntry } from '@deepseek-ai/dsh-api-session-controller/client';
 import type { LlmAttemptId } from '@deepseek-ai/dsh-llm/brand';
 import type { ConversationNodeDefinition, ConversationPublication, ConversationViewDefinition, ConversationViewSnapshotMap, ConversationViewSnapshotStore } from '../contract/conversation.ts';
+import type { ConversationGroupData, ConversationGroupDefinition, ConversationGroupedView } from '../contract/groups.ts';
 /** Event Registry subset consumed by a Session-owned Assembler. */
 export interface ConversationEventDefinitions {
     /** @returns ordinary Definitions in registration order. */
@@ -13,6 +14,13 @@ export interface ConversationViewDefinitions {
     /** @returns view builder factories in registration order. */
     entries(): readonly ConversationViewDefinition[];
 }
+/** Registered grouping rules consumed by the target-neutral assembler. */
+export interface ConversationGroupDefinitions {
+    /** @returns grouping Definitions in registration order. */
+    entries(): readonly ConversationGroupDefinition[];
+    /** @param target - View target. @returns its optional Group Definition. */
+    forTarget(target: string): ConversationGroupDefinition | undefined;
+}
 /**
  * Session-owned incremental engine that assembles business Contexts from a
  * contiguous Event window and materializes registered view snapshots.
@@ -20,6 +28,7 @@ export interface ConversationViewDefinitions {
 export declare class ConversationNodeAssembler implements ConversationViewSnapshotStore {
     private readonly eventDefinitions;
     private readonly viewDefinitions;
+    private readonly groupDefinitions;
     private readonly contexts;
     private readonly contextsByKind;
     private readonly contextsBySeq;
@@ -31,6 +40,8 @@ export declare class ConversationNodeAssembler implements ConversationViewSnapsh
     private readonly revised;
     private readonly dependents;
     private readonly views;
+    private readonly groups;
+    private readonly pendingGroupStores;
     private readonly activeTargets;
     private hasMore;
     private replacePending;
@@ -38,8 +49,9 @@ export declare class ConversationNodeAssembler implements ConversationViewSnapsh
     /**
      * @param eventDefinitions - live Event Definition registry.
      * @param viewDefinitions - live view builder registry.
+     * @param groupDefinitions - optional registered grouping rules, independent of presentation modes.
      */
-    constructor(eventDefinitions: ConversationEventDefinitions, viewDefinitions: ConversationViewDefinitions);
+    constructor(eventDefinitions: ConversationEventDefinitions, viewDefinitions: ConversationViewDefinitions, groupDefinitions?: ConversationGroupDefinitions);
     /**
      * Replace the complete loaded window after open, resync, or gap repair.
      * @param entries - complete contiguous window.
@@ -91,6 +103,7 @@ export declare class ConversationNodeAssembler implements ConversationViewSnapsh
      */
     snapshot(target: string): unknown;
     get<Target extends Extract<keyof ConversationViewSnapshotMap, string>>(target: Target): ConversationViewSnapshotMap[Target] | undefined;
+    grouped<Target extends string>(target: Target): ConversationGroupedView<ConversationGroupData<Target>> | undefined;
     /**
      * Read targets whose owners classify their latest snapshot as visible activity.
      * @returns target ids contributing visible activity.
@@ -118,6 +131,8 @@ export declare class ConversationNodeAssembler implements ConversationViewSnapsh
     private refreshMatchLocations;
     private buildNode;
     private replaceView;
+    private updateView;
+    private publishViews;
     private buildTargetNodes;
     private buildTargetUpserts;
     private buildLocationData;

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

@@ -10,6 +10,7 @@ import type { ConversationPromptSnapshot, RequestPromptInspection, SystemPromptN
 import { type SystemPromptState } from '../contract/system-prompt.ts';
 import { ConversationEventRegistry } from './event-registry.ts';
 import { ConversationViewRegistry } from './view-registry.ts';
+import { ConversationGroupRegistry } from './group-registry.ts';
 /** Observable faces published for one Session's Conversation assembly. */
 export interface ConversationBinding {
     readonly snapshot: ObservableSnapshot<ConversationSnapshot>;
@@ -34,6 +35,8 @@ export declare class UiConversation extends Service {
     readonly events: ConversationEventRegistry;
     /** Registry of target View definitions. */
     readonly views: ConversationViewRegistry;
+    /** Business grouping rules over already materialized target Nodes. */
+    readonly groups: ConversationGroupRegistry;
     private readonly bindings;
     private readonly images;
     /**

package/lib/types/client/conversation/group-registry.d.ts

@@ -0,0 +1,30 @@
+/** Target-indexed business grouping registrations with the existing effect lifecycle. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ConversationViewNode } from '../contract/conversation.ts';
+import type { ConversationGroupData, ConversationGroupDefinition } from '../contract/groups.ts';
+import { ConversationDefinitionRegistry } from './definition-registry.ts';
+import type { ConversationViewRegistry } from './view-registry.ts';
+/** One Group Definition per target; registration never instantiates its Builder. */
+export declare class ConversationGroupRegistry extends ConversationDefinitionRegistry<ConversationGroupDefinition> {
+    private readonly views;
+    /**
+     * @param ctx - owning plugin context.
+     * @param views - registered target Builder definitions.
+     */
+    constructor(ctx: Context, views: ConversationViewRegistry);
+    /**
+     * Register grouping rules for an existing target.
+     * @param definition - business State and grouping output for the declared target data.
+     * @returns the effect-owned, idempotent registration disposer.
+     */
+    register<Node extends ConversationViewNode, State, Target extends string>(definition: ConversationGroupDefinition<Node, State, ConversationGroupData<Target>> & {
+        readonly target: Target;
+    }): () => void;
+    /**
+     * Find the grouping rules registered for one target.
+     * @param target - View target.
+     * @returns its grouping Definition, when registered.
+     */
+    forTarget(target: string): ConversationGroupDefinition | undefined;
+}
+//# sourceMappingURL=group-registry.d.ts.map

package/lib/types/client/conversation/group-store.d.ts

@@ -0,0 +1,29 @@
+/** Keyed group publication and incremental validation of rendering positions. */
+import { type ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { ConversationViewNode } from '../contract/conversation.ts';
+import type { ConversationGroupedView, GroupKey, GroupSnapshot, GroupUpdate, NodeKey, RenderEntry } from '../contract/groups.ts';
+/** Validates a complete batch before installing its group and root-list changes. */
+export declare class ConversationGroupStore<Data> implements ConversationGroupedView<Data> {
+    private root;
+    private rootGroups;
+    private readonly groups;
+    private readonly placements;
+    private readonly sources;
+    private readonly dirty;
+    /** @returns the identity-stable ordered root references. */
+    get entries(): readonly RenderEntry[];
+    groupSource(key: GroupKey): ObservableSnapshot<GroupSnapshot<Data> | undefined>;
+    /**
+     * Install one validated update without notifying readers.
+     * @param update - root replacement and complete or incremental group records.
+     * @param readNode - synchronous reader of the current target Nodes.
+     */
+    prepareAndInstall(update: GroupUpdate<Data>, readNode: (key: NodeKey) => ConversationViewNode | undefined): void;
+    /** Publish changed group sources after all related target data has been installed. */
+    publish(): void;
+    /** Remove grouping without deleting its source Nodes; publication remains deferred. */
+    clear(): void;
+    private collectRootGroups;
+    private collectChanges;
+}
+//# sourceMappingURL=group-store.d.ts.map

package/lib/types/client/conversation/location-index.d.ts

@@ -16,6 +16,7 @@ export declare class ConversationLocationIndex {
     private readonly turnDataStores;
     private readonly stepDataStores;
     private readonly dirtyDataStores;
+    private readonly changedTurns;
     private currentTurn;
     private currentStep;
     /**
@@ -23,6 +24,11 @@ export declare class ConversationLocationIndex {
      * @returns current timeline snapshot.
      */
     snapshot(): ConversationTimelineSnapshot;
+    /**
+     * Drain the Turn changes accumulated for one assembly flush.
+     * @returns Turn identities changed since the preceding drain.
+     */
+    takeChangedTurns(): readonly number[];
     /**
      * Replace all Definition-owned Location values while preserving reader identities.
      * @param entries - complete current set of Definition-owned Location values.

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

@@ -3,6 +3,8 @@ 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';
@@ -15,7 +17,7 @@ export { inspectRequestPrompt } from './contract/request-inspection.ts';
 export type { SystemPromptState, SystemPromptInspector } from './contract/system-prompt.ts';
 export type { ConversationStoreState, ConversationViewRequest, ViewTab } from './contract/views.ts';
 export { ConversationNodeAssembler } from './conversation/assembler.ts';
-export type { ConversationEventDefinitions, ConversationViewDefinitions, } 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';

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

@@ -1,7 +1,7 @@
 /**
  * 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
+ * token renders in the business accent. 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.
  */

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

@@ -28,8 +28,12 @@ export interface ComposerKeymapHandlers {
     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 files with directory metadata supplied by the clipboard entry API.
+     * @param files - browser files in clipboard order.
+     * @param directories - known directory members; absent when no entry identifies a directory.
+     */
+    intakeFiles(files: readonly File[], directories?: ReadonlySet<File>): void;
     /** Pasted plain text (sanitized insertion through the shell). */
     pasteText(text: string): void;
 }

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

@@ -88,6 +88,13 @@ export declare class DraftEditorRuntime {
      * @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.
@@ -96,6 +103,12 @@ export declare class DraftEditorRuntime {
      * @returns whether the range mapped and the edit applied.
      */
     insertReference(span: DetectSpan, ref: ReferenceInsert, tail: string): boolean;
+    /**
+     * Insert an ordered file-reference batch after the live selection without deleting it.
+     * @param references - validated references in source order.
+     * @returns whether the live insertion position accepted the batch.
+     */
+    insertFileReferences(references: readonly ReferenceInsert[]): boolean;
     /** Refresh claim-token decoration after the model's claim changes. */
     refreshClaimDecoration(): void;
     /**

package/lib/types/client/input/editor/view-binding.d.ts

@@ -11,7 +11,7 @@ interface DraftViewGate {
     running: boolean;
     steeringAvailable: boolean;
     busyEnter: BusyEnterBehavior;
-    intakeFiles: (files: readonly File[]) => void;
+    intakeFiles: (files: readonly File[], directories?: ReadonlySet<File>) => void;
     uploadsPending: boolean;
     showToast: (text: string) => void;
     t: ComposerBarProps['t'];