@crazx/dsh-client-ui-conversation 0.1.5-alpha.1.zw.3

package/lib/index.js

@@ -0,0 +1,27 @@
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/submission-settings.js
+/** Busy-Enter preference 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";
+/** 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";
+/** 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) });
+//#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, CONVERSATION_SETTINGS_NAMESPACE, DEFAULT_BUSY_ENTER_BEHAVIOR, 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 '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type ConversationKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-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 '@deepseek-ai/dsh-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 '@deepseek-ai/dsh-client-store';
+import type { SessionId } from '@deepseek-ai/dsh-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 '../../submission-settings.ts';
+export type { BusyEnterBehavior } from '../../submission-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-provenance.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 ContextProvenanceView {
+    /** 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-provenance.d.ts.map

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

@@ -0,0 +1,256 @@
+import type { SessionEventLike } from '@deepseek-ai/dsh-api-session-controller/client';
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+/** Definition-local identity and lifecycle role extracted from one event. */
+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>;
+}
+/** 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;
+}
+/** One scalar event accepted as a Context's unique start. */
+export type ConversationStartMatch = ConversationMatchOf<SessionEvent, '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;
+}
+/** 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 unique 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 one post-start update Match.
+     * @param context - Context with its current State.
+     * @param match - update Match in ascending log 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;
+    }): 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;
+    }): Snapshot;
+}
+/** 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