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

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

@@ -0,0 +1,20 @@
+/** Target-neutral Conversation state assembled from one Session event window. */
+import type { SessionSnapshot } from '@qilin-agent/api-session-controller/client';
+import type { ConversationViewSnapshotStore } from './conversation.ts';
+/** Latest registered target snapshots and their shell-level activity. */
+export interface ConversationSnapshot {
+    readonly views: ConversationViewSnapshotStore;
+    readonly activeTargets: ReadonlySet<string>;
+}
+/** Empty Conversation value used before a Session binding is available. */
+export declare const EMPTY_CONVERSATION_SNAPSHOT: ConversationSnapshot;
+/** Shell phase derived from Session lifecycle and registered target activity. */
+export type ConversationPhase = 'blank' | 'engaging' | 'active';
+/**
+ * Resolve the shell phase without adding Conversation data to the Session snapshot.
+ * @param session - current Session lifecycle state.
+ * @param conversation - current target-neutral Conversation state.
+ * @returns the phase used by the header, View ring, and composer layout.
+ */
+export declare function conversationPhase(session: SessionSnapshot, conversation: ConversationSnapshot): ConversationPhase;
+//# sourceMappingURL=snapshot.d.ts.map

package/lib/types/client/contract/system-prompt.d.ts

@@ -0,0 +1,35 @@
+/** Immutable system-only interpretation of the loaded Session surface. */
+import type { SessionEvent } from '@qilin-agent/session/types';
+import type { SystemPromptNode } from './request-inspection.ts';
+interface PositionedSystem {
+    readonly position: number;
+    readonly node: SystemPromptNode;
+}
+/** Prompt facts at one log prefix; earlier instances remain valid for historical cards. */
+export interface SystemPromptState {
+    /** Earliest relevant loaded event; older unindexed endpoints have unknown surface positions. */
+    readonly firstSeq: number;
+    /** Missing endpoint order makes the prompt unavailable until prepend replay supplies it. */
+    readonly uncertain: boolean;
+    /** Loaded system nodes in surface order, including empty dormant nodes. */
+    readonly nodes: readonly PositionedSystem[];
+    /** Surviving replacement endpoints only, mapped to inherited surface positions. */
+    readonly replacements: ReadonlyMap<number, number>;
+    /** Effective prompt and its change origin; empty text records removal, undefined means unavailable. */
+    readonly effective: SystemPromptNode | undefined;
+    /** System event at this position, if any; only this node may own an update card. */
+    readonly introduced: SystemPromptNode | undefined;
+}
+/** Pure interpretation supplied to target-owned Definitions through uiConversation. */
+export type SystemPromptInspector = (previous: SystemPromptState | undefined, event: SessionEvent) => SystemPromptState;
+/**
+ * Apply a system event or positional replacement without retaining ordinary messages.
+ * Replacement positions inherit their start endpoint, not their chronological seq.
+ * Unknown older endpoint order withholds the prompt until prepend replay resolves it.
+ * @param previous - Interpretation at the preceding relevant event in the loaded window.
+ * @param event - System message or surface replacement already admitted by Session.
+ * @returns Immutable surviving system facts and the effective nonempty prompt.
+ */
+export declare function inspectSystemPrompt(previous: SystemPromptState | undefined, event: SessionEvent): SystemPromptState;
+export {};
+//# sourceMappingURL=system-prompt.d.ts.map

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

@@ -0,0 +1,36 @@
+/** Conversation view and session-local presentation state. */
+/**
+ * One conversation view tab, projected from a 'conversation.view' slot
+ * entry's registration options (label falls back to the entry id).
+ */
+export interface ViewTab {
+    id: string;
+    label: string;
+}
+/** Per-session state owned by the target-neutral Conversation shell. */
+/** Conversation view and session-local presentation state. */
+/**
+ * One conversation view tab, projected from a 'conversation.view' slot
+ * entry's registration options (label falls back to the entry id).
+ */
+export interface ViewTab {
+    id: string;
+    label: string;
+}
+/** One-shot focus request addressed to a Conversation View. */
+export interface ConversationViewRequest {
+    /** Target `conversation.view` entry id. */
+    readonly view: string;
+    /** Target-owned opaque focus identity. */
+    readonly focus: string;
+}
+/** 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;
+    /** Preferred `conversation.view` entry id; null resolves to Chat when registered. */
+    view: string | null;
+    /** One-shot focus request addressed to the selected View. */
+    viewRequest: ConversationViewRequest | null;
+}
+//# sourceMappingURL=views.d.ts.map

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

@@ -0,0 +1,151 @@
+import type { SessionAssistantSettlementEntry, SessionEventLikeEntry } from '@qilin-agent/api-session-controller/client';
+import type { LlmAttemptId } from '@qilin-agent/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. */
+    entries(): readonly ConversationNodeDefinition[];
+    /** @returns unmatched-event fallback, when registered. */
+    fallbackEntry(): ConversationNodeDefinition | undefined;
+}
+/** View Registry subset consumed by a Session-owned Assembler. */
+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.
+ */
+export declare class ConversationNodeAssembler implements ConversationViewSnapshotStore {
+    private readonly eventDefinitions;
+    private readonly viewDefinitions;
+    private readonly groupDefinitions;
+    private readonly contexts;
+    private readonly contextsByKind;
+    private readonly contextsBySeq;
+    private readonly contextsByTarget;
+    private readonly inputs;
+    private readonly locationIndex;
+    private readonly dirty;
+    private readonly dirtyByTarget;
+    private readonly revised;
+    private readonly dependents;
+    private readonly views;
+    private readonly groups;
+    private readonly pendingGroupStores;
+    private readonly activeTargets;
+    private hasMore;
+    private replacePending;
+    private timelineDirty;
+    /**
+     * @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, groupDefinitions?: ConversationGroupDefinitions);
+    /**
+     * Read the current open turn without activating a View.
+     * @returns the latest turn number when its start is loaded and it remains open, otherwise undefined.
+     */
+    openTurn(): number | undefined;
+    /**
+     * Replace the complete loaded window after open, resync, or gap repair.
+     * @param entries - complete contiguous window.
+     * @param hasMore - whether older history remains outside the window.
+     * @returns immediate publication request.
+     */
+    replaceWindow(entries: readonly SessionEventLikeEntry[], hasMore: boolean): ConversationPublication;
+    /**
+     * Add one contiguous live tail event without scanning existing Contexts.
+     * @param record - appended Session event entry.
+     * @returns highest requested publication cadence.
+     */
+    append(record: SessionEventLikeEntry): ConversationPublication;
+    /**
+     * Retire one Assistant attempt's transient matches and apply its optional durable settlement.
+     * Empty Contexts retain their keys and published nodes until the loaded window is rebuilt;
+     * Definitions may hide those nodes when no start remains instead of withdrawing their identities.
+     * @param attemptId - process-local attempt whose transient presentation ended.
+     * @param entry - durable message or attempt event committed for the stream.
+     * @returns highest requested publication cadence.
+     */
+    settleAssistant(attemptId: LlmAttemptId, entry?: SessionAssistantSettlementEntry): ConversationPublication;
+    /**
+     * Add an older page while preserving existing Context and view identities.
+     * @param entries - newly loaded older Events.
+     * @param hasMore - whether history still precedes the expanded window.
+     * @returns highest requested publication cadence.
+     */
+    prepend(entries: readonly SessionEventLikeEntry[], hasMore: boolean): ConversationPublication;
+    /**
+     * Rebuild against the current Registry set after a low-frequency plugin change.
+     * @returns immediate publication request.
+     */
+    rebuildRegistry(): ConversationPublication;
+    /**
+     * Materialize dirty Contexts and advance every active view builder.
+     * @returns whether any view snapshot was rebuilt or incrementally applied.
+     */
+    flush(): boolean;
+    /**
+     * Add one target to the monotonic active set and materialize its current snapshot.
+     * Pending Context work is flushed before the first complete replacement.
+     * @param target - registered or subsequently registered view target.
+     * @returns whether any active target snapshot changed.
+     */
+    activateTarget(target: string): boolean;
+    /**
+     * Read the latest snapshot of a registered target.
+     * @param target - registered view target.
+     * @returns target snapshot, or undefined before registration or activation.
+     */
+    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.
+     */
+    activityTargets(): ReadonlySet<string>;
+    private sortedInputs;
+    private matchInput;
+    private collectInput;
+    private dispatchInput;
+    private createContext;
+    private acceptMatch;
+    private applyPendingMatches;
+    private replayContexts;
+    private refreshStarts;
+    private replayContext;
+    private indexTargetContext;
+    private markDirty;
+    private replaceDependencies;
+    private replayRevisedDependents;
+    private readerFor;
+    private previousContext;
+    /** Insert one newly discovered start into its Definition's ordered predecessor index. */
+    private indexStartedContext;
+    private indexStartedContexts;
+    private replayDependencies;
+    private refreshMatchLocations;
+    private buildNode;
+    private replaceView;
+    private updateView;
+    private publishViews;
+    private buildTargetNodes;
+    private buildTargetUpserts;
+    private buildLocationData;
+    private replaceLocationData;
+    private applyDirtyLocationData;
+    private resetViewBuilders;
+}
+//# sourceMappingURL=assembler.d.ts.map

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

@@ -0,0 +1,128 @@
+/** Per-Session target-neutral Conversation assembly. */
+import { Service, type Context } from '@qilin-agent/kylin';
+import type { ImageAttachmentRef } from '@qilin-agent/attachment';
+import type { ISessions, SessionBinding } from '@qilin-agent/api-session-controller/client';
+import type { SessionEvent, SessionId } from '@qilin-agent/session/types';
+import { type ObservableSnapshot } from '@qilin-agent/client-store';
+import type { ConversationViewSnapshotMap } from '../contract/conversation.ts';
+import type { ConversationSnapshot } from '../contract/snapshot.ts';
+import type { ConversationPromptSnapshot, RequestPromptInspection, SystemPromptNode } from '../contract/request-inspection.ts';
+import { type SystemPromptState } from '../contract/system-prompt.ts';
+import { ConversationEventRegistry } from './event-registry.ts';
+import { ConversationGroupRegistry } from './group-registry.ts';
+import { ConversationViewRegistry } from './view-registry.ts';
+/** Observable faces published for one Session's Conversation assembly. */
+export interface ConversationBinding {
+    readonly snapshot: ObservableSnapshot<ConversationSnapshot>;
+    /**
+     * Identity-stable source of the latest turn number, undefined unless its start is loaded and it remains open.
+     * Turn changes publish synchronously, including without an active View.
+     */
+    readonly openTurn: ObservableSnapshot<number | undefined>;
+    /**
+     * Add one selected target to the Session's monotonic active set.
+     * @param target - registered or subsequently registered Conversation target.
+     */
+    activate(target: string): void;
+    /**
+     * Resolve one target-owned snapshot source.
+     * The first subscriber activates the target unless shell selection already
+     * activated it; activation lasts for the remaining Session lifetime.
+     * @param target - registered Conversation target.
+     * @returns identity-stable source following the target.
+     */
+    target<Target extends Extract<keyof ConversationViewSnapshotMap, string>>(target: Target): ObservableSnapshot<ConversationViewSnapshotMap[Target] | undefined>;
+}
+/** Root service owning Conversation registries and per-Session bindings. */
+export declare class UiConversation extends Service {
+    private readonly sessions;
+    /** Registry of event matchers and target snapshot builders. */
+    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;
+    /**
+     * @param ctx - owning Client context.
+     * @param sessions - Session Controller object layer.
+     */
+    constructor(ctx: Context, sessions: ISessions);
+    /**
+     * Resolve the Conversation binding for one Controller binding or Session id.
+     * @param source - Session binding or identity.
+     * @returns stable Conversation binding.
+     */
+    binding(source: SessionBinding | SessionId): ConversationBinding;
+    /**
+     * Resolve one session-authorized durable image URL, cached per Session so
+     * every Conversation target shares one read and one browser URL.
+     * @param sessionId - Session authorization and lifetime scope.
+     * @param attachment - Durable image reference from a session event.
+     * @returns browser URL valid until the Session binding is released.
+     */
+    imageUrl(sessionId: SessionId, attachment: ImageAttachmentRef): Promise<string>;
+    /**
+     * Read a cached durable image URL synchronously when one is available.
+     * @param sessionId - Session authorization and lifetime scope.
+     * @param attachment - Durable image reference from a session event.
+     * @returns current preview or canonical URL, if cached.
+     */
+    peekImageUrl(sessionId: SessionId, attachment: ImageAttachmentRef): string | undefined;
+    /**
+     * Replace one Session's composer draft with `text` — the transcript
+     * "edit this message and resend" entry. Resolves the Session's resident
+     * input shell through the conversation service's input registry; no-op
+     * when the session has no shell. SessionId-explicit, like {@link imageUrl},
+     * so a call from any package needs no scope-addressed service inject.
+     * @param sessionId - target Session.
+     * @param text - full draft text.
+     */
+    fillDraft(sessionId: SessionId, text: string): void;
+    /**
+     * Append `text` after one Session's composer draft, leaving the draft's
+     * existing text and reference chips in place. Dispatched as the scoped
+     * insert event against the revision the draft is read at, so a concurrent
+     * edit makes the shell refuse the insert instead of splicing into moved
+     * text; a non-empty draft that does not already end in whitespace gains one
+     * separating newline. SessionId-explicit, like {@link fillDraft}, so a call
+     * from any package needs no scope-addressed service inject.
+     * @param sessionId - target Session.
+     * @param text - text to append.
+     * @returns whether the resident input shell applied the insert.
+     */
+    insertDraft(sessionId: SessionId, text: string): boolean;
+    /**
+     * Adopt an already-displayable URL for one durable reference (see
+     * HistoricalImageCache.seed): the transcript node then renders it without a
+     * byte round-trip.
+     * @param sessionId - Session authorization and lifetime scope.
+     * @param attachment - Durable image reference the URL displays.
+     * @param url - browser URL to adopt.
+     * @returns whether the cache took URL ownership.
+     */
+    seedImageUrl(sessionId: SessionId, attachment: ImageAttachmentRef, url: string): boolean;
+    /**
+     * Interpret a system message or surface replacement for target-owned prompt Definitions.
+     * @param previous - System facts at the preceding relevant loaded event.
+     * @param event - Durable system message or positional replacement.
+     * @returns Immutable prompt interpretation at this event.
+     */
+    inspectSystemPrompt(previous: SystemPromptState | undefined, event: SessionEvent): SystemPromptState;
+    /**
+     * Canonicalize one `request/header` event against the previous prompt state
+     * and the `system/message` node in force.
+     *
+     * A pure interpretation shared by the Chat and Trajectory Definitions, exposed
+     * as a service method because cross-plugin value imports are forbidden in
+     * client bundles.
+     * @param previous - prompt recorded by the preceding loaded header, if any.
+     * @param event - the `request/header` session event to interpret.
+     * @param system - effective prompt after loaded surface replacements, if any.
+     * @returns the canonical prompt snapshot and any model-visible change.
+     */
+    inspectRequestPrompt(previous: ConversationPromptSnapshot | undefined, event: SessionEvent<'request/header'>, system: SystemPromptNode | undefined): RequestPromptInspection;
+    private drop;
+}
+//# sourceMappingURL=assembly.d.ts.map

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

@@ -0,0 +1,33 @@
+import { type Context } from '@qilin-agent/kylin';
+/** Shared lifecycle and stable-entry storage for one Conversation Definition registry. */
+export declare abstract class ConversationDefinitionRegistry<Definition> {
+    protected readonly ctx: Context;
+    protected readonly definitions: Map<string, Definition>;
+    private listeners;
+    private cached;
+    /** @param ctx - Context whose effects own contributed Definitions. */
+    constructor(ctx: Context);
+    /**
+     * Return reference-stable Definitions in registration order.
+     * @returns current Definitions.
+     */
+    entries(): readonly Definition[];
+    /**
+     * Observe low-frequency registry changes.
+     * @param listener - synchronous invalidation callback.
+     * @returns unsubscribe callback.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Register one uniquely keyed Definition for the caller's lifetime.
+     * @param key - registry-local unique key.
+     * @param definition - contributed Definition.
+     * @param duplicateMessage - error raised when the key is already owned.
+     * @param effectName - Cordis effect diagnostic label.
+     * @returns idempotent disposer.
+     */
+    protected registerDefinition(key: string, definition: Definition, duplicateMessage: string, effectName: string): () => void;
+    /** Refresh cached entries and synchronously invalidate subscribers. */
+    protected refresh(): void;
+}
+//# sourceMappingURL=definition-registry.d.ts.map

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

@@ -0,0 +1,40 @@
+import type { ConversationMatchHandler, ConversationNodeDefinition, ConversationNodeDefinitionInput } from '../contract/conversation.ts';
+import { ConversationDefinitionRegistry } from './definition-registry.ts';
+/** A registered Definition and its event-type-selected handler. */
+export interface ConversationEventRoute {
+    readonly definition: ConversationNodeDefinition;
+    readonly match: ConversationMatchHandler;
+}
+/** Runtime registry of independently owned Conversation business Definitions. */
+export declare class ConversationEventRegistry extends ConversationDefinitionRegistry<ConversationNodeDefinition> {
+    private fallback;
+    private routes;
+    private unrestricted;
+    private readonly tables;
+    /**
+     * Register a uniquely named business Definition for the caller's lifetime.
+     * @param definition - Definition contribution.
+     * @returns idempotent disposer.
+     */
+    register(definition: ConversationNodeDefinitionInput): () => void;
+    /**
+     * Register the sole fallback used only when no ordinary Definition matches.
+     * @param input - fallback Definition.
+     * @returns idempotent disposer.
+     */
+    registerFallback(input: ConversationNodeDefinitionInput): () => void;
+    /**
+     * Return the current unmatched-event fallback.
+     * @returns installed fallback, when present.
+     */
+    fallbackEntry(): ConversationNodeDefinition | undefined;
+    /**
+     * Read precomputed candidates in registration order; the returned Set is borrowed read-only.
+     * @param type - current event type.
+     * @returns table handlers for this type together with all function-form handlers.
+     */
+    forEvent(type: string): ReadonlySet<ConversationEventRoute>;
+    private resolve;
+    protected refresh(): void;
+}
+//# sourceMappingURL=event-registry.d.ts.map

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 '@qilin-agent/kylin';
+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 '@qilin-agent/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/historical-images.d.ts

@@ -0,0 +1,49 @@
+/** Session-scoped durable image URL cache shared by Conversation targets. */
+import type { Context } from '@qilin-agent/kylin';
+import type { ImageAttachmentRef } from '@qilin-agent/attachment';
+import type { ISessions } from '@qilin-agent/api-session-controller/client';
+import type { SessionId } from '@qilin-agent/session/types';
+/** Resolve durable Conversation images and release their browser URLs with Session scope. */
+export declare class HistoricalImageCache {
+    private readonly sessions;
+    private readonly entries;
+    private readonly scopeDisposers;
+    private readonly urls;
+    private disposed;
+    /**
+     * @param ctx - Owning ui-conversation fiber.
+     * @param sessions - Session Controller object layer.
+     */
+    constructor(ctx: Context, sessions: ISessions);
+    /**
+     * Resolve and cache one session-authorized image URL.
+     * @param sessionId - Session authorization and lifetime scope.
+     * @param attachment - Durable image reference.
+     * @returns browser URL valid until the Session binding is released.
+     */
+    resolve(sessionId: SessionId, attachment: ImageAttachmentRef): Promise<string>;
+    /**
+     * Return an already-displayable URL without starting a read.
+     * @param sessionId - Session authorization and lifetime scope.
+     * @param attachment - Durable image reference.
+     * @returns current preview or canonical URL when cached.
+     */
+    peek(sessionId: SessionId, attachment: ImageAttachmentRef): string | undefined;
+    /**
+     * Adopt a submission preview while fetching the durable admitted bytes.
+     * The preview is available synchronously, then replaced and revoked when
+     * the canonical attachment read completes.
+     * @param sessionId - Session authorization and lifetime scope.
+     * @param attachment - Durable image reference the URL temporarily displays.
+     * @param url - browser URL to adopt.
+     * @returns whether the cache took ownership.
+     */
+    seed(sessionId: SessionId, attachment: ImageAttachmentRef, url: string): boolean;
+    private loadCanonical;
+    private assertLive;
+    private bindScope;
+    private release;
+    private releaseUrl;
+    private dispose;
+}
+//# sourceMappingURL=historical-images.d.ts.map

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

@@ -0,0 +1,91 @@
+import { type AssistantLiveChunkEvent, type SessionEventLike, type SessionEventLikeEntry } from '@qilin-agent/api-session-controller/client';
+import type { SessionEvent } from '@qilin-agent/session/types';
+import type { ConversationLocation, ConversationLocationData, ConversationTimelineSnapshot } from '../contract/conversation.ts';
+/** One Context's previous and next Location-data publication. */
+export interface ConversationLocationDataChange {
+    readonly owner: string;
+    readonly previous: ConversationLocationData | null;
+    readonly next: ConversationLocationData | null;
+}
+/** Session-owned Turn/Step timeline and event-to-Location index. */
+export declare class ConversationLocationIndex {
+    private coordinates;
+    private locations;
+    private seqsByTurn;
+    private timeline;
+    private readonly turnDataStores;
+    private readonly stepDataStores;
+    private readonly dirtyDataStores;
+    private readonly changedTurns;
+    private currentTurn;
+    private currentStep;
+    /**
+     * Return the current reference-stable timeline.
+     * @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.
+     * @returns whether any published Location data changed.
+     */
+    replaceData(entries: readonly {
+        readonly owner: string;
+        readonly data: ConversationLocationData;
+    }[]): boolean;
+    /**
+     * Apply changed Context publications without rebuilding Turn/Step membership.
+     * @param changes - incremental removals and replacements from published Contexts.
+     * @returns whether any published Location data changed.
+     */
+    applyData(changes: readonly ConversationLocationDataChange[]): boolean;
+    /** Publish committed Location-data changes to their keyed sources. */
+    publishData(): void;
+    /**
+     * Resolve the latest Location for one event.
+     * @param event - event already ingested into this index.
+     * @returns current Location, falling back to session when it has no Turn/Step affinity.
+     */
+    locationOf(event: SessionEventLike): ConversationLocation;
+    /**
+     * Rebuild timeline facts after replace/prepend or a boundary append.
+     * @param entries - complete current window in ascending seq order.
+     * @returns seqs whose resolved Location changed.
+     */
+    rebuild(entries: readonly SessionEventLikeEntry[]): ReadonlySet<number>;
+    /**
+     * Append one Turn/Step boundary while revisiting only the owning Turn.
+     * @param event - contiguous tail boundary event.
+     * @returns seqs whose immutable Location reference changed.
+     */
+    appendBoundary(event: SessionEvent): ReadonlySet<number>;
+    /**
+     * Index one non-boundary tail event without rescanning the window.
+     * @param event - contiguous appended event.
+     */
+    appendNonBoundary(event: SessionEventLike): void;
+    /**
+     * Remove indexed Assistant transients without rebuilding the Turn/Step timeline.
+     * @param events - transient events retired by one Assistant settlement.
+     */
+    removeAssistantTransients(events: readonly AssistantLiveChunkEvent[]): void;
+    /**
+     * Index one durable Assistant settlement inserted before an already visible tail.
+     * @param event - message or attempt settlement with explicit Turn and Step coordinates.
+     */
+    insertAssistantSettlement(event: SessionEvent<'assistant/message'> | SessionEvent<'assistant/attempt'>): void;
+    private indexTurnSeq;
+    private turnData;
+    private stepData;
+    private mutableTurnData;
+    private mutableStepData;
+    private createDataStore;
+    private storeFor;
+    private resolve;
+}
+//# sourceMappingURL=location-index.d.ts.map

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

@@ -0,0 +1,12 @@
+import type { ConversationViewDefinition } from '../contract/conversation.ts';
+import { ConversationDefinitionRegistry } from './definition-registry.ts';
+/** Runtime registry of per-target Conversation snapshot builders. */
+export declare class ConversationViewRegistry extends ConversationDefinitionRegistry<ConversationViewDefinition> {
+    /**
+     * Register a uniquely named view builder factory for the caller's lifetime.
+     * @param definition - target builder contribution.
+     * @returns idempotent disposer.
+     */
+    register(definition: ConversationViewDefinition): () => void;
+}
+//# sourceMappingURL=view-registry.d.ts.map