@kirkchinese/dsh-citeciter 0.9.0-beta.2 → 0.9.0-beta.3

package/lib/{typert-common-g1lnIG8u.js → typert-common-B3cX-hWj.js}

@@ -1,4 +1,4 @@
-import { d as citeCiterRequestSchema, f as citeCiterResponseSchema, r as updateCheckResponseSchema } from "./update-B_0nN1_f.js";
+import { d as citeCiterRequestSchema, f as citeCiterResponseSchema, r as updateCheckResponseSchema } from "./update-CGteMuNJ.js";
 //#region lib/types/typert-codec.js
 /** Official Typert lazily resolves schemas after module registration. */
 function strictCodec(typeSymbol, schema) {

package/lib/typert.host.js

@@ -1,5 +1,5 @@
-import { S as topicSummarySchema, c as citationDraftSchema, d as citeCiterRequestSchema, f as citeCiterResponseSchema, l as citationRecordSchema, r as updateCheckResponseSchema, x as topicSnapshotSchema } from "./update-B_0nN1_f.js";
-import { n as updateCheckDescriptor, r as namedSchema, t as citeCiterRequestDescriptor } from "./typert-common-g1lnIG8u.js";
+import { S as topicSummarySchema, c as citationDraftSchema, d as citeCiterRequestSchema, f as citeCiterResponseSchema, l as citationRecordSchema, r as updateCheckResponseSchema, x as topicSnapshotSchema } from "./update-CGteMuNJ.js";
+import { n as updateCheckDescriptor, r as namedSchema, t as citeCiterRequestDescriptor } from "./typert-common-B3cX-hWj.js";
 //#region lib/types/typert.host.js
 /** Handwritten strict Host contribution matching the single Remote decorator. */
 const TYPERT = {

package/lib/typert.remote-client.js

@@ -1,4 +1,4 @@
-import { n as updateCheckDescriptor, t as citeCiterRequestDescriptor } from "./typert-common-g1lnIG8u.js";
+import { n as updateCheckDescriptor, t as citeCiterRequestDescriptor } from "./typert-common-B3cX-hWj.js";
 //#region lib/types/typert.remote-client.js
 /** Browser contribution mounted by the CiteCiter Client fiber. */
 const TYPERT_REMOTE = {

package/lib/types/actions.d.ts

@@ -61,5 +61,12 @@ export declare const DEFAULT_WHEEL_SLOTS: readonly (CiteAction | null)[];
  * @returns `draft` for questions the user writes, otherwise the preference.
  */
 export declare function actionDelivery(action: CiteAction, preference: ActionDelivery | undefined): ActionDelivery;
+/**
+ * Explain a preset action the host refused to send, which then moves into the composer.
+ * The composer already explains a missing model, so that reason is not repeated.
+ * @param reason - the host's refusal message.
+ * @returns one message for the panel.
+ */
+export declare function undeliveredActionMessage(reason: string): string;
 /** Combine a mode and optional user question without hidden system state. */
 export declare function actionQuestion(action: CiteAction, question: string): string;

package/lib/types/blackboard-tool.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Create the blackboard_animate tool. A successful call validates the timeline against the current
+ * board and records it; the board keeps one timeline, replaced by the next successful call.
+ * @returns a tool definition for one Topic tool registry.
+ */
+export declare function createBlackboardAnimateTool(): import("@deepseek-ai/dsh-tools").ToolDefinition;
 /**
  * Create the blackboard_apply tool. A successful call only validates and records the batch;
  * the board itself is replayed from committed results.

package/lib/types/board-animation.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Board animation timelines: a declarative spec of verbs, keyframes, SVG paths and restricted
+ * parametric expressions over existing board elements, plus a pure sampler shared by the Host
+ * validator, the browser player and frame capture. Coordinates are canvas percentages.
+ */
+import { z } from 'zod';
+export declare const ANIMATION_MAX_TRACKS = 40;
+export declare const ANIMATION_MAX_BEATS = 20;
+export declare const ANIMATION_MAX_FRAMES = 40;
+export declare const ANIMATION_MAX_DURATION_MS = 30000;
+declare const easingSchema: z.ZodEnum<{
+    linear: "linear";
+    "ease-in": "ease-in";
+    "ease-out": "ease-out";
+    "ease-in-out": "ease-in-out";
+}>;
+export type AnimationEasing = z.infer<typeof easingSchema>;
+/** One verb applied to one board element. */
+export declare const animationTrackSchema: z.ZodObject<{
+    target: z.ZodString;
+    verb: z.ZodEnum<{
+        appear: "appear";
+        disappear: "disappear";
+        move: "move";
+        scale: "scale";
+        rotate: "rotate";
+        highlight: "highlight";
+        reveal: "reveal";
+        follow: "follow";
+        keyframes: "keyframes";
+        parametric: "parametric";
+    }>;
+    startMs: z.ZodOptional<z.ZodNumber>;
+    endMs: z.ZodOptional<z.ZodNumber>;
+    easing: z.ZodOptional<z.ZodEnum<{
+        linear: "linear";
+        "ease-in": "ease-in";
+        "ease-out": "ease-out";
+        "ease-in-out": "ease-in-out";
+    }>>;
+    to: z.ZodOptional<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strict>>;
+    scale: z.ZodOptional<z.ZodNumber>;
+    degrees: z.ZodOptional<z.ZodNumber>;
+    direction: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+        up: "up";
+        down: "down";
+    }>>;
+    path: z.ZodOptional<z.ZodString>;
+    orient: z.ZodOptional<z.ZodBoolean>;
+    frames: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        atMs: z.ZodNumber;
+        x: z.ZodOptional<z.ZodNumber>;
+        y: z.ZodOptional<z.ZodNumber>;
+        opacity: z.ZodOptional<z.ZodNumber>;
+        scale: z.ZodOptional<z.ZodNumber>;
+        rotate: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+    x: z.ZodOptional<z.ZodString>;
+    y: z.ZodOptional<z.ZodString>;
+    t: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, z.core.$strict>;
+export type AnimationTrack = z.infer<typeof animationTrackSchema>;
+/** One complete timeline as written by the model. */
+export declare const animationSpecSchema: z.ZodObject<{
+    durationMs: z.ZodNumber;
+    loop: z.ZodOptional<z.ZodBoolean>;
+    beats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        atMs: z.ZodNumber;
+        caption: z.ZodString;
+    }, z.core.$strict>>>;
+    tracks: z.ZodArray<z.ZodObject<{
+        target: z.ZodString;
+        verb: z.ZodEnum<{
+            appear: "appear";
+            disappear: "disappear";
+            move: "move";
+            scale: "scale";
+            rotate: "rotate";
+            highlight: "highlight";
+            reveal: "reveal";
+            follow: "follow";
+            keyframes: "keyframes";
+            parametric: "parametric";
+        }>;
+        startMs: z.ZodOptional<z.ZodNumber>;
+        endMs: z.ZodOptional<z.ZodNumber>;
+        easing: z.ZodOptional<z.ZodEnum<{
+            linear: "linear";
+            "ease-in": "ease-in";
+            "ease-out": "ease-out";
+            "ease-in-out": "ease-in-out";
+        }>>;
+        to: z.ZodOptional<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strict>>;
+        scale: z.ZodOptional<z.ZodNumber>;
+        degrees: z.ZodOptional<z.ZodNumber>;
+        direction: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            right: "right";
+            up: "up";
+            down: "down";
+        }>>;
+        path: z.ZodOptional<z.ZodString>;
+        orient: z.ZodOptional<z.ZodBoolean>;
+        frames: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            atMs: z.ZodNumber;
+            x: z.ZodOptional<z.ZodNumber>;
+            y: z.ZodOptional<z.ZodNumber>;
+            opacity: z.ZodOptional<z.ZodNumber>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            rotate: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+        x: z.ZodOptional<z.ZodString>;
+        y: z.ZodOptional<z.ZodString>;
+        t: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AnimationSpec = z.infer<typeof animationSpecSchema>;
+/** The board's current timeline: the spec of the latest successful call, keyed by that call. */
+export declare const boardTimelineSchema: z.ZodObject<{
+    id: z.ZodString;
+    spec: z.ZodObject<{
+        durationMs: z.ZodNumber;
+        loop: z.ZodOptional<z.ZodBoolean>;
+        beats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            atMs: z.ZodNumber;
+            caption: z.ZodString;
+        }, z.core.$strict>>>;
+        tracks: z.ZodArray<z.ZodObject<{
+            target: z.ZodString;
+            verb: z.ZodEnum<{
+                appear: "appear";
+                disappear: "disappear";
+                move: "move";
+                scale: "scale";
+                rotate: "rotate";
+                highlight: "highlight";
+                reveal: "reveal";
+                follow: "follow";
+                keyframes: "keyframes";
+                parametric: "parametric";
+            }>;
+            startMs: z.ZodOptional<z.ZodNumber>;
+            endMs: z.ZodOptional<z.ZodNumber>;
+            easing: z.ZodOptional<z.ZodEnum<{
+                linear: "linear";
+                "ease-in": "ease-in";
+                "ease-out": "ease-out";
+                "ease-in-out": "ease-in-out";
+            }>>;
+            to: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strict>>;
+            scale: z.ZodOptional<z.ZodNumber>;
+            degrees: z.ZodOptional<z.ZodNumber>;
+            direction: z.ZodOptional<z.ZodEnum<{
+                left: "left";
+                right: "right";
+                up: "up";
+                down: "down";
+            }>>;
+            path: z.ZodOptional<z.ZodString>;
+            orient: z.ZodOptional<z.ZodBoolean>;
+            frames: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                atMs: z.ZodNumber;
+                x: z.ZodOptional<z.ZodNumber>;
+                y: z.ZodOptional<z.ZodNumber>;
+                opacity: z.ZodOptional<z.ZodNumber>;
+                scale: z.ZodOptional<z.ZodNumber>;
+                rotate: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>>;
+            x: z.ZodOptional<z.ZodString>;
+            y: z.ZodOptional<z.ZodString>;
+            t: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type BoardTimeline = z.infer<typeof boardTimelineSchema>;
+type Expression = (t: number) => number;
+/**
+ * Compile a restricted arithmetic expression of `t`: numbers, `+ - * / ^`, parentheses,
+ * the constants pi, e, tau and a fixed set of Math functions. Nothing else is accepted.
+ * @throws an Error naming the first unexpected token.
+ */
+export declare function compileExpression(source: string): Expression;
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/** A sampled path: points with cumulative arc length. */
+export interface SampledPath {
+    readonly points: readonly Point[];
+    readonly lengths: readonly number[];
+    readonly total: number;
+}
+/**
+ * Sample an SVG path (M L H V C S Q T A Z, absolute and relative) into a polyline.
+ * @throws an Error for unsupported commands or malformed numbers.
+ */
+export declare function samplePath(d: string): SampledPath;
+/** Position and tangent angle (degrees) at a fraction of a sampled path's length. */
+export declare function pointAlong(path: SampledPath, fraction: number): {
+    readonly x: number;
+    readonly y: number;
+    readonly angle: number;
+};
+/** Render-ready transform of one element at one time. */
+export interface ElementFrame {
+    /** Translation in canvas percent. */
+    readonly dx: number;
+    readonly dy: number;
+    readonly scale: number;
+    readonly rotate: number;
+    readonly opacity: number;
+    /** Hidden fraction (0-100) clipped from `clipSide`. */
+    readonly clip: number;
+    readonly clipSide: 'left' | 'right' | 'top' | 'bottom';
+    /** Highlight glow strength, 0-1. */
+    readonly glow: number;
+}
+type Prop = 'dx' | 'dy' | 'scale' | 'rotate' | 'opacity' | 'clip' | 'glow' | 'slideX' | 'slideY';
+interface Segment {
+    readonly start: number;
+    readonly end: number;
+    /** Value shown before the segment starts when it is the first for its property. */
+    readonly before?: number;
+    readonly at: (t: number, from: number) => number;
+}
+interface CompiledElement {
+    readonly segments: ReadonlyMap<Prop, readonly Segment[]>;
+    /** Value of each segment's property at its start, from the segments before it. */
+    readonly from: ReadonlyMap<Segment, number>;
+    readonly clipSide: ElementFrame['clipSide'];
+}
+/** A timeline compiled against the board element envelopes it animates. */
+export interface CompiledTimeline {
+    readonly durationMs: number;
+    readonly loop: boolean;
+    readonly beats: readonly {
+        readonly atMs: number;
+        readonly caption: string;
+    }[];
+    readonly elements: ReadonlyMap<string, CompiledElement>;
+}
+/** Envelope fields a timeline needs from each target. */
+export interface AnimationTargetEnvelope {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/**
+ * Validate and compile a timeline against the current board.
+ * @param spec - parsed timeline spec.
+ * @param targets - current board element envelopes.
+ * @returns the compiled timeline.
+ * @throws an Error describing the first invalid track.
+ */
+export declare function compileTimeline(spec: AnimationSpec, targets: readonly AnimationTargetEnvelope[]): CompiledTimeline;
+/**
+ * Sample every animated element at one time.
+ * @param timeline - compiled timeline.
+ * @param atMs - time within the timeline; clamped to its duration.
+ * @returns frames keyed by element id; elements without tracks are absent.
+ */
+export declare function sampleTimeline(timeline: CompiledTimeline, atMs: number): Map<string, ElementFrame>;
+/** Caption of the latest beat at or before a time, or null. */
+export declare function beatAt(timeline: CompiledTimeline, atMs: number): string | null;
+export {};

package/lib/types/board-capture-protocol.d.ts

@@ -29,10 +29,10 @@ export declare const boardCaptureJobSchema: z.ZodObject<{
             focused: z.ZodBoolean;
             animation: z.ZodOptional<z.ZodObject<{
                 name: z.ZodEnum<{
+                    highlight: "highlight";
                     "fade-in": "fade-in";
                     "slide-in": "slide-in";
                     pulse: "pulse";
-                    highlight: "highlight";
                 }>;
                 durationMs: z.ZodNumber;
                 iterations: z.ZodNumber;
@@ -40,6 +40,66 @@ export declare const boardCaptureJobSchema: z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>>;
         invalid: z.ZodNumber;
+        timeline: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            spec: z.ZodObject<{
+                durationMs: z.ZodNumber;
+                loop: z.ZodOptional<z.ZodBoolean>;
+                beats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    atMs: z.ZodNumber;
+                    caption: z.ZodString;
+                }, z.core.$strict>>>;
+                tracks: z.ZodArray<z.ZodObject<{
+                    target: z.ZodString;
+                    verb: z.ZodEnum<{
+                        appear: "appear";
+                        disappear: "disappear";
+                        move: "move";
+                        scale: "scale";
+                        rotate: "rotate";
+                        highlight: "highlight";
+                        reveal: "reveal";
+                        follow: "follow";
+                        keyframes: "keyframes";
+                        parametric: "parametric";
+                    }>;
+                    startMs: z.ZodOptional<z.ZodNumber>;
+                    endMs: z.ZodOptional<z.ZodNumber>;
+                    easing: z.ZodOptional<z.ZodEnum<{
+                        linear: "linear";
+                        "ease-in": "ease-in";
+                        "ease-out": "ease-out";
+                        "ease-in-out": "ease-in-out";
+                    }>>;
+                    to: z.ZodOptional<z.ZodObject<{
+                        x: z.ZodNumber;
+                        y: z.ZodNumber;
+                    }, z.core.$strict>>;
+                    scale: z.ZodOptional<z.ZodNumber>;
+                    degrees: z.ZodOptional<z.ZodNumber>;
+                    direction: z.ZodOptional<z.ZodEnum<{
+                        left: "left";
+                        right: "right";
+                        up: "up";
+                        down: "down";
+                    }>>;
+                    path: z.ZodOptional<z.ZodString>;
+                    orient: z.ZodOptional<z.ZodBoolean>;
+                    frames: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        atMs: z.ZodNumber;
+                        x: z.ZodOptional<z.ZodNumber>;
+                        y: z.ZodOptional<z.ZodNumber>;
+                        opacity: z.ZodOptional<z.ZodNumber>;
+                        scale: z.ZodOptional<z.ZodNumber>;
+                        rotate: z.ZodOptional<z.ZodNumber>;
+                    }, z.core.$strict>>>;
+                    x: z.ZodOptional<z.ZodString>;
+                    y: z.ZodOptional<z.ZodString>;
+                    t: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+        }, z.core.$strict>>>;
     }, z.core.$strict>;
+    atMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export type BoardCaptureJob = z.infer<typeof boardCaptureJobSchema>;

package/lib/types/board-capture.d.ts

@@ -2,6 +2,8 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { BoardSnapshot } from './board.ts';
 import type { BoardCaptureJob } from './board-capture-protocol.ts';
+/** Most frames one blackboard_view call may request. */
+export declare const BOARD_VIEW_MAX_FRAMES = 6;
 /** Correlates one model-requested render with one client reply; bytes become a durable DSH attachment. */
 export declare class BoardCaptureBroker {
     private readonly pending;

package/lib/types/board.d.ts

@@ -74,10 +74,10 @@ export declare const boardOpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     op: z.ZodLiteral<"animate">;
     id: z.ZodString;
     animation: z.ZodEnum<{
+        highlight: "highlight";
         "fade-in": "fade-in";
         "slide-in": "slide-in";
         pulse: "pulse";
-        highlight: "highlight";
     }>;
     durationMs: z.ZodOptional<z.ZodNumber>;
     iterations: z.ZodOptional<z.ZodNumber>;
@@ -135,10 +135,10 @@ export declare const boardBatchSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.Zod
     op: z.ZodLiteral<"animate">;
     id: z.ZodString;
     animation: z.ZodEnum<{
+        highlight: "highlight";
         "fade-in": "fade-in";
         "slide-in": "slide-in";
         pulse: "pulse";
-        highlight: "highlight";
     }>;
     durationMs: z.ZodOptional<z.ZodNumber>;
     iterations: z.ZodOptional<z.ZodNumber>;
@@ -205,10 +205,10 @@ export declare const boardSnapshotSchema: z.ZodObject<{
         focused: z.ZodBoolean;
         animation: z.ZodOptional<z.ZodObject<{
             name: z.ZodEnum<{
+                highlight: "highlight";
                 "fade-in": "fade-in";
                 "slide-in": "slide-in";
                 pulse: "pulse";
-                highlight: "highlight";
             }>;
             durationMs: z.ZodNumber;
             iterations: z.ZodNumber;
@@ -216,6 +216,65 @@ export declare const boardSnapshotSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>>;
     invalid: z.ZodNumber;
+    timeline: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        spec: z.ZodObject<{
+            durationMs: z.ZodNumber;
+            loop: z.ZodOptional<z.ZodBoolean>;
+            beats: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                atMs: z.ZodNumber;
+                caption: z.ZodString;
+            }, z.core.$strict>>>;
+            tracks: z.ZodArray<z.ZodObject<{
+                target: z.ZodString;
+                verb: z.ZodEnum<{
+                    appear: "appear";
+                    disappear: "disappear";
+                    move: "move";
+                    scale: "scale";
+                    rotate: "rotate";
+                    highlight: "highlight";
+                    reveal: "reveal";
+                    follow: "follow";
+                    keyframes: "keyframes";
+                    parametric: "parametric";
+                }>;
+                startMs: z.ZodOptional<z.ZodNumber>;
+                endMs: z.ZodOptional<z.ZodNumber>;
+                easing: z.ZodOptional<z.ZodEnum<{
+                    linear: "linear";
+                    "ease-in": "ease-in";
+                    "ease-out": "ease-out";
+                    "ease-in-out": "ease-in-out";
+                }>>;
+                to: z.ZodOptional<z.ZodObject<{
+                    x: z.ZodNumber;
+                    y: z.ZodNumber;
+                }, z.core.$strict>>;
+                scale: z.ZodOptional<z.ZodNumber>;
+                degrees: z.ZodOptional<z.ZodNumber>;
+                direction: z.ZodOptional<z.ZodEnum<{
+                    left: "left";
+                    right: "right";
+                    up: "up";
+                    down: "down";
+                }>>;
+                path: z.ZodOptional<z.ZodString>;
+                orient: z.ZodOptional<z.ZodBoolean>;
+                frames: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    atMs: z.ZodNumber;
+                    x: z.ZodOptional<z.ZodNumber>;
+                    y: z.ZodOptional<z.ZodNumber>;
+                    opacity: z.ZodOptional<z.ZodNumber>;
+                    scale: z.ZodOptional<z.ZodNumber>;
+                    rotate: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>>>;
+                x: z.ZodOptional<z.ZodString>;
+                y: z.ZodOptional<z.ZodString>;
+                t: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type BoardSnapshot = z.infer<typeof boardSnapshotSchema>;
 /** Empty snapshot used before any board commit. */

package/lib/types/client/board-timeline.d.ts

@@ -0,0 +1,30 @@
+import { type CSSProperties } from 'react';
+import type { CompiledTimeline, ElementFrame } from '../board-animation.ts';
+/**
+ * Inline style for one sampled element frame. Translation is converted from canvas percent
+ * to the element's own percent, so no layout measurement is needed.
+ * @param frame - sampled frame.
+ * @param size - the element envelope's width and height in canvas percent.
+ */
+export declare function frameStyle(frame: ElementFrame, size: {
+    readonly w: number;
+    readonly h: number;
+}): CSSProperties;
+/** Playback state of one board timeline. */
+export interface TimelinePlayer {
+    readonly t: number;
+    readonly playing: boolean;
+    readonly toggle: () => void;
+    readonly seek: (atMs: number) => void;
+}
+/**
+ * Drive a compiled timeline with requestAnimationFrame. A new timeline plays once when motion is
+ * allowed; otherwise it rests on its final frame. A frozen time (frame capture) never plays.
+ * @param timeline - compiled timeline, or null.
+ * @param key - identity of the timeline; a new key restarts playback.
+ * @param options - whether to autoplay and an optional frozen time.
+ */
+export declare function useTimelinePlayer(timeline: CompiledTimeline | null, key: string | null, options: {
+    readonly autoplay: boolean;
+    readonly frozenAt?: number | undefined;
+}): TimelinePlayer;

package/lib/types/client/companion-controller.d.ts

@@ -7,7 +7,7 @@ import type { ChatSnapshot } from '@deepseek-ai/dsh-client-ui-chat/client';
 import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
 import { type CiteCiterRequest, type CiteCiterResponse, type CiteCiterSettings, type ProviderOption, type QuestionAnswer, type TopicSnapshot, type TopicSummary } from '../topic.ts';
 import { type DocumentClaimIntent } from './request-guard.ts';
-import type { ActionDelivery, ActionModel } from '../actions.ts';
+import { type ActionDelivery, type ActionModel } from '../actions.ts';
 import type { CiteSelection } from './types.ts';
 import { type DraftReference } from './draft-references.ts';
 export type CompanionPhase = 'idle' | 'creating' | 'ready' | 'running' | 'stopping' | 'stopped' | 'error';

package/lib/types/client/components/BoardCaptureSurface.d.ts

@@ -1,8 +1,10 @@
 import type { BoardSnapshot } from '../../board.ts';
 /** Reuses the exact board renderer when its visible tab is closed; no synthetic drawing or extra conversation is created. */
-export declare function BoardCaptureSurface({ id, sessionId, board, reply }: {
+export declare function BoardCaptureSurface({ id, sessionId, board, atMs, reply }: {
     readonly id: string;
     readonly sessionId: string;
     readonly board: BoardSnapshot | undefined;
+    /** Timeline time to freeze; frames always render offscreen so playback state cannot leak in. */
+    readonly atMs?: number | undefined;
     readonly reply: (sessionId: string, id: string, png?: string, error?: string) => Promise<void>;
 }): import("react").JSX.Element;

package/lib/types/client/components/BoardView.d.ts

@@ -5,10 +5,12 @@ import { type BoardElementState, type BoardSnapshot } from '../../board.ts';
  * @param props - snapshot, motion preference, optional compact reading mode and citation action.
  * @returns the safe blackboard canvas.
  */
-export declare function BoardView({ snapshot, animations, onQuoteElement, compact, sessionId, }: {
+export declare function BoardView({ snapshot, animations, onQuoteElement, compact, sessionId, frameAtMs, }: {
     readonly snapshot: BoardSnapshot | undefined;
     readonly animations: boolean;
     readonly onQuoteElement?: (element: BoardElementState) => void;
     readonly compact?: boolean;
     readonly sessionId?: string;
+    /** Freeze the board's timeline at this time, for frame capture. */
+    readonly frameAtMs?: number;
 }): import("react").JSX.Element;

package/lib/types/client/components/PermissionControl.d.ts

@@ -1,6 +1,6 @@
 import type { CiteCiterSettings } from '../../topic.ts';
 export type PermissionMode = NonNullable<CiteCiterSettings['defaultPermission']>;
-/** Explicit permission selection; receives the Host's effective value. */
+/** Explicit permission selection in the host's menu; receives the Host's effective value. */
 export declare function PermissionControl({ value, onChange }: {
     readonly value: PermissionMode;
     readonly onChange: (mode: PermissionMode) => void;

package/lib/types/client/components/TopicActions.d.ts

@@ -11,7 +11,7 @@ export interface TopicMenu {
     readonly onArchive: (archived: boolean) => void;
     readonly onDelete: () => void;
 }
-/** The "⋯" menu: rename, learning route, document reader, archive and permanent deletion. */
+/** The "⋯" menu in the host's menu: rename, learning route, document reader, archive and permanent deletion. */
 export declare function TopicActions({ menu }: {
     readonly menu: TopicMenu;
 }): import("react").JSX.Element;

package/lib/types/client/components/TopicModelControls.d.ts

@@ -1,5 +1,5 @@
 import type { ProviderOption, TopicModelConfig } from '../../topic.ts';
-/** Model and reasoning hierarchy. Route changes are committed by the injected controller. */
+/** Model and reasoning choices in the host's menu. Route changes are committed by the injected controller. */
 export declare function TopicModelControls({ providers, route, saving, onModel, onReasoning }: {
     readonly providers: readonly ProviderOption[];
     readonly route: TopicModelConfig;

package/lib/types/host-agent-modules.d.ts

@@ -1,6 +1,7 @@
 import type { Context, Plugin } from '@deepseek-ai/cordis';
 import type AgentLoop from '@deepseek-ai/dsh-agent-loop';
 import type SessionStore from '@deepseek-ai/dsh-session';
+import type { Config as JsonlPersistenceConfig } from '@deepseek-ai/dsh-session-persistence-jsonl';
 import type SessionTitleService from '@deepseek-ai/dsh-session-title';
 interface HostScope {
     readonly ctx: Context;
@@ -17,6 +18,8 @@ export interface SessionTitleLlmConfig {
 export interface HostAgentModules {
     readonly AgentLoop: typeof AgentLoop;
     readonly SessionStore: typeof SessionStore;
+    /** DSH's JSONL session persistence, which registers `ctx.sessionPersistence`. */
+    readonly SessionPersistence: Plugin<JsonlPersistenceConfig>;
     readonly SessionTitleService: typeof SessionTitleService;
     /** DSH's own first-prompt model title provider, the one `dsh-base` mounts for host sessions. */
     readonly SessionTitleProvider: Plugin<SessionTitleLlmConfig>;
@@ -27,7 +30,7 @@ export interface HostAgentModules {
  * File URLs bypass peer routing and can create a second private scope identity,
  * particularly when Electron ASAR paths use different casing on Windows.
  * Bare imports also leave CLI symlinks and Desktop packaging to the host resolver.
- * @returns the host's AgentLoop, SessionStore, title service and provider, and scope factory.
+ * @returns the host's AgentLoop, SessionStore, session persistence, title service and provider, and scope factory.
  */
 export declare function loadHostAgentModules(): Promise<HostAgentModules>;
 export {};

package/lib/types/line-diff.d.ts

@@ -0,0 +1,12 @@
+/** A small, bounded line diff for rendering edit payloads that carry old and new text. */
+/**
+ * Render a unified-style line diff (hunks only, no file headers).
+ * @param oldText - previous text.
+ * @param newText - replacement text.
+ * @param options - context lines around changes and the LCS size limit.
+ * @returns hunks text, an empty string when both texts have identical lines, or null when the changed region exceeds the limit.
+ */
+export declare function unifiedLineDiff(oldText: string, newText: string, options?: {
+    readonly context?: number;
+    readonly maxCells?: number;
+}): string | null;

package/lib/types/message-projection.d.ts

@@ -6,6 +6,7 @@ interface ContextMessage {
     source: {
         kind: string;
         plugin?: string;
+        form?: unknown;
     };
 }
 /** Project the installed SDK's validated log. 0.1.7 split plugin context into developer/message. */