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

package/lib/index.js

@@ -0,0 +1,46 @@
+import z from "@qilin-agent/schemastery";
+//#region lib/types/conversation-settings.js
+/** Conversation preferences stored in the Host user-settings document. */
+/** Settings namespace owned by the conversation plugin. */
+const CONVERSATION_SETTINGS_NAMESPACE = "ui-conversation";
+/** Field carrying the delivery mode for plain Enter while an agent is busy. */
+const BUSY_ENTER_FIELD = "busyEnter";
+/** Field carrying the transcript content width. */
+const CONTENT_WIDTH_FIELD = "contentWidth";
+/** Busy-Enter behaviors accepted at settings and input boundaries. */
+const BUSY_ENTER_BEHAVIORS = ["queue", "steer"];
+/** Default preserves Enter-as-Queue for running conversations. */
+const DEFAULT_BUSY_ENTER_BEHAVIOR = "queue";
+/**
+* Content width that leaves the transcript to the layout's adaptive clamp
+* (`clamp(680px, 64% of the column, 920px)`); any other value is an explicit
+* width in px.
+*/
+const CONTENT_WIDTH_ADAPTIVE = 0;
+/** Narrowest explicit content width (px); the layout center-column floor. */
+const CONTENT_WIDTH_MIN = 640;
+/** Widest persistable content width (px), bounding a hand-edited settings document. */
+const CONTENT_WIDTH_MAX = 2400;
+/** Increment one stepper click moves the content width (px). */
+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({
+	[BUSY_ENTER_FIELD]: z.union([...BUSY_ENTER_BEHAVIORS]).default(DEFAULT_BUSY_ENTER_BEHAVIOR),
+	[CONTENT_WIDTH_FIELD]: z.natural().max(CONTENT_WIDTH_MAX).default(0)
+});
+//#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.
+*/
+function apply(ctx) {
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.register(CONVERSATION_SETTINGS_NAMESPACE, ConversationSettingsSchema);
+	});
+}
+//#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 };

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

@@ -0,0 +1,25 @@
+/** Registers the target-neutral Conversation assembly, shell, input, and docks. */
+import type { Context } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+import { type ConversationKey } from './locales.ts';
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Conversation shell, composer, queue, and dock copy. */
+        conversation: ConversationKey;
+    }
+}
+/** Services required by the Conversation plugin. */
+export declare const inject: string[];
+/** Conversation runtime configuration. */
+export interface Config {
+    /** Maximum generic-file uploads allowed to run concurrently in browser Workers. */
+    maxConcurrentFileUploads?: number;
+}
+/** Validated Conversation runtime configuration. */
+export declare const Config: z<Config>;
+/**
+ * Mount the Conversation core and target-neutral presentation.
+ * @param ctx - Client root context.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=apply.d.ts.map

package/lib/types/client/context-occupancy.d.ts

@@ -0,0 +1,14 @@
+import type { ContextPressureProjection } from '@qilin-agent/token-meter/client';
+/** Context usage rendered by conversation and Chat status surfaces. */
+export interface ContextOccupancy {
+    percent: number;
+    usedTokens: number;
+    contextWindow: number;
+}
+/**
+ * Resolve bounded display occupancy from independently updated pressure fields.
+ * @param pressure - latest token-meter projection.
+ * @returns occupancy, or null until numerator and capacity are known.
+ */
+export declare function contextOccupancy(pressure: ContextPressureProjection | undefined): ContextOccupancy | null;
+//# sourceMappingURL=context-occupancy.d.ts.map

package/lib/types/client/contract/composer-blocks.d.ts

@@ -0,0 +1,28 @@
+import type { SnapshotStore } from '@qilin-agent/client-store';
+import type { SessionId } from '@qilin-agent/session/types';
+/** Why one session's composer is inert. */
+export interface ComposerBlock {
+    /** Localized placeholder owned by the plugin that raised the block. */
+    readonly reason: string;
+}
+/** The registry face other plugins reach through `ctx.conversation.blocks`. */
+export interface ComposerBlocks {
+    /**
+     * Raise or clear this session's block.
+     * @param sessionId - Session whose composer is affected.
+     * @param block - Block to raise, or undefined to clear it.
+     */
+    set(sessionId: SessionId, block: ComposerBlock | undefined): void;
+    /**
+     * Resolve the observable block state for one Session.
+     * @param sessionId - Session to observe.
+     * @returns Identity-stable block store.
+     */
+    storeFor(sessionId: SessionId): SnapshotStore<ComposerBlock | undefined>;
+    /**
+     * Drop one Session's store.
+     * @param sessionId - Session being released.
+     */
+    forget(sessionId: SessionId): void;
+}
+//# sourceMappingURL=composer-blocks.d.ts.map

package/lib/types/client/contract/composer-submission.d.ts

@@ -0,0 +1,8 @@
+/** Composer submission vocabulary shared by the input and settings domains. */
+import type { BusyEnterBehavior } from '../../conversation-settings.ts';
+export type { BusyEnterBehavior } from '../../conversation-settings.ts';
+/** Delivery mode requested for one ordinary composer message. */
+export type InputSubmitMode = BusyEnterBehavior;
+/** Keyboard gesture whose delivery mode the submission policy resolves. */
+export type ComposerSubmitGesture = 'enter' | 'accelerated';
+//# sourceMappingURL=composer-submission.d.ts.map

package/lib/types/client/contract/context-producer.d.ts

@@ -0,0 +1,29 @@
+/** Shared types for target-owned context-source projections. */
+/**
+ * Which model-facing role a logged non-user message plays.
+ *
+ * `recall` marks material lifted out of another session's log; `inject` marks
+ * every other producer-supplied context. Mid-turn steering is the third role
+ * the transcript distinguishes, but it has its own event and node kind
+ * (`steering/message` / `SteeringMessageNode`) and never reaches here.
+ */
+export type ContextRole = 'inject' | 'recall';
+/** Role and producer name presented for one logged non-user message. */
+export interface ContextProducerView {
+    /** The role this context plays in the model-facing conversation. */
+    role: ContextRole;
+    /**
+     * Producer name for the row header, taken from the durable source: the
+     * instruction paths, the referenced session titles, the plugin id, or the
+     * bare source kind for a producer this UI version does not know. Null only
+     * when the source carries no readable kind at all.
+     */
+    label: string | null;
+}
+/**
+ * One durable context form this UI version knows how to present. Target
+ * projections map absent or unknown forms to their opaque presentation so
+ * logs written by older, newer, or foreign producers remain visible.
+ */
+export type KnownContextForm = 'instructions' | 'catalog' | 'snapshot' | 'notice' | 'relay' | 'recall';
+//# sourceMappingURL=context-producer.d.ts.map

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

@@ -0,0 +1,279 @@
+import type { SessionEventLike } from '@qilin-agent/api-session-controller/client';
+import type { SessionEvent } from '@qilin-agent/session/types';
+import type { ConversationGroupData, ConversationGroupedView, ConversationGroupInput } from './groups.ts';
+/** Definition-local identity; start permits initialization when no earlier start is present. */
+export interface ConversationMatchResult {
+    readonly id: string;
+    readonly role: 'start' | 'update';
+}
+/** Merge-extensible business values published against one Turn. */
+export interface ConversationTurnDataMap {
+}
+/** Merge-extensible business values published against one Step. */
+export interface ConversationStepDataMap {
+}
+/** Observable value for one independently owned Location-data key. */
+export interface ConversationLocationDataSource<Value> {
+    /** @returns the current value. */
+    readonly getSnapshot: () => Value;
+    /** @param listener - callback for value changes. @returns the unsubscribe function. */
+    readonly subscribe: (listener: () => void) => () => void;
+}
+/** Stable keyed reader for independently owned Location business values. */
+export interface ConversationLocationDataStore<DataMap extends object> {
+    /**
+     * Read one business value without exposing another owner's mutable State.
+     * @param key - declaration-merged business key.
+     * @returns latest immutable value, when its owning Context has published one.
+     */
+    get<Key extends keyof DataMap & string>(key: Key): Readonly<DataMap[Key]> | undefined;
+    /**
+     * Observe one business value without subscribing to unrelated Location keys.
+     * @param key - declaration-merged business key.
+     * @returns identity-stable source for the current value.
+     */
+    source<Key extends keyof DataMap & string>(key: Key): ConversationLocationDataSource<Readonly<DataMap[Key]> | undefined>;
+}
+interface ConversationLocationDataValue {
+    readonly kind: 'turn' | 'step';
+    readonly turn: number;
+    readonly step?: number;
+    readonly key: string;
+    readonly value: unknown;
+}
+type RegisteredTurnData<DataMap extends object> = {
+    [Key in Extract<keyof DataMap, string>]: {
+        readonly kind: 'turn';
+        readonly turn: number;
+        readonly key: Key;
+        readonly value: DataMap[Key];
+    };
+}[Extract<keyof DataMap, string>];
+type RegisteredStepData<DataMap extends object> = {
+    [Key in Extract<keyof DataMap, string>]: {
+        readonly kind: 'step';
+        readonly turn: number;
+        readonly step: number;
+        readonly key: Key;
+        readonly value: DataMap[Key];
+    };
+}[Extract<keyof DataMap, string>];
+type ConversationLocationDataOf<TurnData extends object, StepData extends object> = [
+    keyof TurnData | keyof StepData
+] extends [never] ? ConversationLocationDataValue : RegisteredTurnData<TurnData> | RegisteredStepData<StepData>;
+/** One Definition-owned value attached to an Engine-owned Turn or Step. */
+export type ConversationLocationData = ConversationLocationDataOf<ConversationTurnDataMap, ConversationStepDataMap>;
+/** Immutable resolved boundary for one Agent step. */
+export interface StepLocation {
+    readonly turn: number;
+    readonly step: number;
+    readonly start: SessionEvent<'step/start'> | undefined;
+    readonly end: SessionEvent<'step/end'> | undefined;
+    readonly status: 'open' | 'closed' | 'unknown';
+    /** Stable reader for Step-scoped business values. */
+    readonly data: ConversationLocationDataStore<ConversationStepDataMap>;
+}
+/** Immutable resolved boundary for one Agent turn. */
+export interface TurnLocation {
+    readonly turn: number;
+    readonly start: SessionEvent<'turn/start'> | undefined;
+    readonly end: SessionEvent<'turn/end'> | undefined;
+    readonly status: 'open' | 'closed' | 'unknown';
+    readonly steps: readonly StepLocation[];
+    /** Stable reader for Turn-scoped business values. */
+    readonly data: ConversationLocationDataStore<ConversationTurnDataMap>;
+}
+/**
+ * Extract a stable business identity using only the current event.
+ * @param event - durable or transient Client event.
+ * @returns identity and lifecycle role, or null when unrelated.
+ */
+export type ConversationMatchHandler = (event: SessionEventLike) => ConversationMatchResult | null;
+/** Registration accepts a function or an immutable table of own event-type handlers. */
+export type ConversationNodeDefinitionInput<State = unknown> = Omit<ConversationNodeDefinition<State>, 'match'> & {
+    readonly match: ConversationMatchHandler | Readonly<Record<string, ConversationMatchHandler>>;
+};
+/** Engine-owned placement of one matched event in the Session hierarchy. */
+export type ConversationLocation = {
+    readonly kind: 'session';
+} | {
+    readonly kind: 'turn';
+    readonly turn: TurnLocation;
+} | {
+    readonly kind: 'step';
+    readonly turn: TurnLocation;
+    readonly step: StepLocation;
+} | {
+    readonly kind: 'unresolved';
+};
+interface ConversationMatchOf<Event extends SessionEventLike, Role extends ConversationMatchResult['role']> {
+    readonly event: Event;
+    readonly role: Role;
+    readonly location: ConversationLocation;
+}
+/** A durable or transient event that can initialize its Context. */
+export type ConversationStartMatch = ConversationMatchOf<SessionEventLike, 'start'>;
+/** One event accepted by a Definition, with its lifecycle role and resolved Location. */
+export type ConversationMatch = ConversationStartMatch | ConversationMatchOf<SessionEventLike, 'update'>;
+/** Target-neutral identity returned by a business Definition. */
+export interface ConversationViewNode {
+    readonly key: string;
+    readonly kind: string;
+    readonly id: string;
+    readonly target: string;
+    readonly data: unknown;
+}
+/** Merge-extensible immutable snapshots published by registered view targets. */
+export interface ConversationViewSnapshotMap {
+}
+/** Stable reader over the latest snapshot of every registered view target. */
+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> {
+    readonly key: string;
+    readonly kind: string;
+    readonly id: string;
+    readonly matches: readonly ConversationMatch[];
+    readonly start: ConversationStartMatch | undefined;
+    readonly state: State | undefined;
+    readonly current: ReadonlyMap<string, ConversationViewNode | null>;
+}
+/** Read-only predecessor returned to a Definition's start function. */
+export interface ConversationPreviousContext<State = unknown> {
+    readonly key: string;
+    readonly kind: string;
+    readonly id: string;
+    readonly startSeq: number;
+    readonly state: Readonly<State>;
+    readonly matches: readonly ConversationMatch[];
+}
+/** Strictly-backward Context lookup available while a start is evaluated. */
+export interface ConversationContextReader {
+    /**
+     * Find the active Context of `kind` with the greatest start seq below the
+     * current start event.
+     * @param kind - Definition kind to query.
+     * @returns the nearest predecessor, or undefined when absent in the current window.
+     */
+    previous<State>(kind: string): ConversationPreviousContext<State> | undefined;
+}
+/** Requested cadence; `animation-frame` materializes after three browser animation frames. */
+export type ConversationPublication = 'none' | 'animation-frame' | 'immediate';
+/** Engine-owned Location data publication phase. */
+export type ConversationLocationDataScope = 'step' | 'turn';
+/** One independently registered business Event-to-Node state machine. */
+export interface ConversationNodeDefinition<State = unknown> {
+    readonly kind: string;
+    /** Sole view target owned by this Definition; omitted for state-only Contexts. */
+    readonly target?: string;
+    /**
+     * Extract this Definition's stable business identity from one event.
+     * @param event - standard or compact Client history event; no Context or history access is available.
+     * @returns identity and lifecycle role, or null when unrelated.
+     */
+    match(event: SessionEventLike): ConversationMatchResult | null;
+    /**
+     * Create State from the earliest currently loaded start Match.
+     * @param context - complete evidence currently collected for the Context.
+     * @param match - the start Match.
+     * @param reader - strictly-backward read-only Context lookup.
+     * @returns the State adopted by the engine.
+     */
+    start(context: ConversationNodeContext<State>, match: ConversationStartMatch, reader: ConversationContextReader): State;
+    /**
+     * Apply a later Match, including another event marked start.
+     * @param context - Context with its current State.
+     * @param match - subsequent Match in ascending event order.
+     * @returns the State adopted by the engine.
+     */
+    update(context: ConversationNodeContext<State> & {
+        readonly state: State;
+    }, match: ConversationMatch): State;
+    /**
+     * Select publication cadence for one accepted Match.
+     * @param match - accepted Match.
+     * @returns requested cadence; omission defaults to immediate.
+     */
+    publication?(match: ConversationMatch): ConversationPublication;
+    /**
+     * Publish this Definition's read-only business value for one Location phase.
+     * The Engine evaluates every Definition first for Step and then for Turn,
+     * owns replacement/removal, and rejects another Context trying to publish
+     * the same Location key.
+     * @param context - latest complete Context.
+     * @param scope - Location hierarchy level currently being materialized.
+     * @param previous - value from the preceding materialization; return it when unchanged.
+     * @returns current Location value, preserving value identity while unchanged,
+     * or null while unavailable.
+     */
+    buildLocationData?(context: ConversationNodeContext<State>, scope: ConversationLocationDataScope, previous: ConversationLocationData | null): ConversationLocationData | null;
+    /**
+     * Materialize one final Node for this Definition's declared view target.
+     * @param context - latest complete Context.
+     * @returns final Node, or null when this Context is not currently visible.
+     */
+    buildViewNode?(context: ConversationNodeContext<State>): ConversationViewNode | null;
+}
+/** Reference-stable Turn/Step facts published beside view Nodes. */
+export interface ConversationTimelineSnapshot {
+    readonly turnOrder: readonly number[];
+    readonly turns: ReadonlyMap<number, TurnLocation>;
+}
+/** Per-Session incremental builder for one view target. */
+export interface ConversationViewBuilder<Node extends ConversationViewNode = ConversationViewNode, Snapshot = unknown> {
+    readonly empty: Snapshot;
+    /**
+     * Replace the low-frequency complete materialized Node set.
+     * @param input - complete Nodes and current timeline.
+     * @returns next view snapshot.
+     */
+    replace(input: {
+        readonly nodes: readonly Node[];
+        readonly timeline: ConversationTimelineSnapshot;
+        readonly changedTurns?: readonly number[];
+    }): Snapshot;
+    /**
+     * Apply only Nodes whose materialized values changed in this transaction.
+     * @param input - changed Nodes and current timeline.
+     * @returns next view snapshot.
+     */
+    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;
+    /** @returns a new Session-owned incremental builder. */
+    create(): ConversationViewBuilder<Node, Snapshot>;
+    /**
+     * Decide whether this target contributes visible Conversation activity.
+     * @param snapshot - latest target-owned snapshot.
+     * @returns whether the shell should treat this target as active.
+     */
+    isActive?(snapshot: Snapshot): boolean;
+}
+/**
+ * Build a stable collision-free key for one Definition-local business identity.
+ * @param kind - Definition kind.
+ * @param id - Definition-local business identity.
+ * @returns engine-owned Context key.
+ */
+export declare function conversationContextKey(kind: string, id: string): string;
+export {};
+//# sourceMappingURL=conversation.d.ts.map

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

@@ -0,0 +1,102 @@
+/** Editor-facing ranges, reference projections, and the composer keyboard interface. */
+import type { LexicalEditor } from 'lexical';
+import type { InputState } from './input.ts';
+import type { InputSubmitMode } from './composer-submission.ts';
+/** Pick-time draft span guarded by the input revision. */
+export interface TokenSpan {
+    readonly start: number;
+    readonly end: number;
+    readonly draftRev: number;
+}
+/** Structured reference inserted by an input-trigger source. */
+export interface ReferenceInsert {
+    readonly source: string;
+    readonly ref: string;
+    readonly label: string;
+    readonly appearance?: 'session' | 'file' | 'folder';
+    readonly clipboardText: string;
+}
+/** Keyboard keys intercepted by an open trigger menu. */
+export type ArbitrateKey = 'up' | 'down' | 'enter' | 'escape' | 'tab' | 'tabBack';
+/** Trigger-menu keyboard routing result. */
+export type ArbitrateOutcome = 'consumed' | 'pick-highlighted' | 'pass';
+/**
+ * The InputBar-exclusive keyboard/DOM command face: synchronous
+ * returns and event-handler semantics that must not enter the public provide
+ * channel. Handed to the composer-bar entry through its own inject —
+ * package-internal, never across a plugin boundary. The session shell
+ * satisfies it structurally. Text editing itself rides the shell's Lexical
+ * editor (exposed here for the contenteditable binding); the members below
+ * are the submit-plane and trigger-pipeline verbs the editor does not own.
+ */
+export interface ComposerKeyboard {
+    /** Live machine state for event-handler reads (render reads go through useInput). */
+    readonly snapshot: InputState;
+    /** The shell-owned Lexical editor the composer binds its contenteditable to. */
+    readonly editor: LexicalEditor;
+    /** Submit with an explicit delivery mode resolved by the submission policy (Enter gestures and the primary Send button). */
+    submit(mode: InputSubmitMode): void;
+    /**
+     * Steer every still-pending queued message into the running turn (the
+     * empty-draft accelerated-Enter gesture; the queue dock's per-row steer
+     * button is the same operation applied to the whole queue).
+     */
+    steerQueue(): void;
+    /** Insert pasted plain text over the current editor selection (reference-placeholder-sanitized). */
+    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.
+     */
+    caretSpan(): EditSelection;
+    /** Keyboard arbitration while the menu is open ('pass' when no pipeline). */
+    arbitrate(key: ArbitrateKey, composing: boolean): ArbitrateOutcome;
+    /** Space adjudication; true = the input applied a claim — caller preventDefaults. */
+    space(): boolean;
+    /** Dismiss the popupSelect shell (any interaction outside the box). */
+    dismissPopup(): void;
+    /**
+     * Bind the mounted composer's file action and live intake availability.
+     * @param picker - availability query and native file-dialog opener.
+     * @returns the unbind disposer.
+     */
+    bindFilePicker(picker: {
+        available(): boolean;
+        open(): void;
+    }): () => void;
+}
+/** Half-open [start, end) range/selection in detect-projection coordinates. */
+export interface EditSelection {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * One reference occurrence projected from the editor's chip nodes, in
+ * clipboard-text coordinates. Identity is occurrenceId — a stable per-shell
+ * assignment per chip NodeKey, so same-named references stay independently
+ * addressable and survive undo. label/appearance/clipboardText are the
+ * owner's insert-time projections cached on the node (invalid flips instead
+ * of dropping the occurrence).
+ */
+export interface Occurrence {
+    /** Shell-assigned stable identity (monotonic per shell, keyed by NodeKey). */
+    readonly occurrenceId: number;
+    /** Owning source name (serializer routing key). */
+    readonly source: string;
+    /** Owner-scoped reference id. */
+    readonly ref: string;
+    /** Offset in the clipboard-text projection. */
+    readonly offset: number;
+    /** Length in the clipboard-text projection; the occurrence occupies exactly [offset, offset+length). */
+    readonly length: number;
+    /** Inline display label (insert-time cache). */
+    readonly label: string;
+    /** Optional domain glyph (insert-time cache). */
+    readonly appearance?: ReferenceInsert['appearance'];
+    /** Clipboard / persistence projection, e.g. `/name` (insert-time cache, never the model form). */
+    readonly clipboardText: string;
+    /** Owner-resolution failure flag: the chip renders the failure treatment. */
+    readonly invalid?: boolean;
+}
+//# sourceMappingURL=draft-editor.d.ts.map

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 '@qilin-agent/brand';
+import type { ObservableSnapshot } from '@qilin-agent/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