@kirkchinese/dsh-citeciter 0.4.3 → 0.6.0

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

@@ -0,0 +1,19 @@
+/** CiteCiter-owned accelerator parsing and listener installation. */
+export interface Accelerator {
+    readonly modifiers: ReadonlySet<'Control' | 'Alt' | 'Shift' | 'Meta'>;
+    readonly key: string;
+}
+/**
+ * Parse a `Modifier+Modifier+Key` accelerator string.
+ * @param accelerator - user-configured accelerator, e.g. `Control+Shift+C`.
+ * @returns normalized modifiers and the final key, or null when malformed.
+ */
+export declare function parseAccelerator(accelerator: string): Accelerator | null;
+/**
+ * Install a window-level keydown listener that reads the accelerator fresh on
+ * every keypress, so settings changes apply without re-registering.
+ * @param accelerator - current accelerator getter; an empty value disables the binding.
+ * @param handler - invoked once for each matching, non-editable, non-IME keypress.
+ * @returns disposer removing the listener.
+ */
+export declare function installDynamicAccelerator(accelerator: () => string | undefined, handler: () => void): () => void;

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

@@ -0,0 +1,33 @@
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { CiteCiterRequest, CiteCiterResponse, DocumentContent, DocumentSummary } from '../topic.ts';
+import type { CompanionFace } from './companion-controller.ts';
+import type { ReaderSelection } from './reader-selection.ts';
+export type ReaderDocumentsStatus = 'idle' | 'loading' | 'ready' | 'error';
+export interface ReaderSnapshot {
+    open: boolean;
+    documents: readonly DocumentSummary[];
+    documentsStatus: ReaderDocumentsStatus;
+    active: DocumentContent | null;
+    selection: ReaderSelection | null;
+    question: string;
+    creating: boolean;
+    error: string | null;
+}
+export interface ReaderFace {
+    getSnapshot(): ReaderSnapshot;
+    subscribe(listener: () => void): () => void;
+    setOpen(open: boolean): void;
+    refresh(): Promise<void>;
+    importFile(name: string, content: string): Promise<DocumentSummary | null>;
+    openDocument(documentId: string): Promise<void>;
+    setSelection(selection: ReaderSelection | null): void;
+    setQuestion(question: string): void;
+    createTopic(): Promise<void>;
+    dispose(): Promise<void>;
+}
+type RemoteRequest = (request: CiteCiterRequest, signal: AbortSignal) => Promise<RemoteResult<CiteCiterResponse>>;
+/** Initial Reader snapshot. */
+export declare function createInitialReaderSnapshot(): ReaderSnapshot;
+/** Bind the Reader store to the CiteCiter Remote and the companion Topic creator. */
+export declare function createReaderController(request: RemoteRequest, companion: CompanionFace, store?: import("@deepseek-ai/dsh-client-store").SnapshotStore<ReaderSnapshot>): ReaderFace;
+export {};

package/lib/types/client/reader-selection.d.ts

@@ -0,0 +1,12 @@
+/** Reader textarea selection facts resolved from the user-owned textarea value. */
+export interface ReaderSelection {
+    readonly displayText: string;
+    readonly prefixText: string;
+    readonly suffixText: string;
+}
+/**
+ * Resolve the current textarea selection into a verifiable document claim.
+ * @param textarea - read-only document textarea holding the complete loaded page.
+ * @returns trimmed quote with surrounding context, or null for a collapsed/empty selection.
+ */
+export declare function readTextareaSelection(textarea: HTMLTextAreaElement): ReaderSelection | null;

package/lib/types/client/request-guard.d.ts

@@ -1,3 +1,4 @@
+import type { TopicScenario } from '../topic.ts';
 import type { CiteSelection } from './types.ts';
 export type CreateMode = 'observer' | 'exact-fork' | 'exact-when-available';
 export interface RequestIntent {
@@ -11,7 +12,29 @@ export interface RequestIntent {
  * @param mode - resolved Topic creation mode.
  * @returns the pending intent key and request ID.
  */
-export declare function claimCreateTopicIntent(selection: CiteSelection, question: string, mode: CreateMode): Promise<RequestIntent>;
+export declare function claimCreateTopicIntent(selection: CiteSelection, question: string, mode: CreateMode, scenario?: TopicScenario): Promise<RequestIntent>;
+/**
+ * Claim the retry-stable request ID for one uncited Topic creation.
+ * @param sourceSessionId - owning DSH Session.
+ * @param question - normalized first question.
+ * @param scenario - requested Topic presentation.
+ * @returns the pending intent key and request ID.
+ */
+export declare function claimCreateFreeTopicIntent(sourceSessionId: string, question: string, scenario: Extract<TopicScenario, 'qa' | 'present'>): Promise<RequestIntent>;
+/** Document-range claim identity shared by the Reader entry point. */
+export interface DocumentClaimIntent {
+    readonly documentId: string;
+    readonly displayText: string;
+    readonly prefixText: string;
+    readonly suffixText: string;
+}
+/**
+ * Claim the retry-stable request ID for one pending document Topic creation.
+ * @param claim - document identity and verified-looking quote context.
+ * @param question - normalized first question.
+ * @returns the pending intent key and request ID.
+ */
+export declare function claimCreateDocumentIntent(claim: DocumentClaimIntent, question: string): Promise<RequestIntent>;
 /**
  * Claim the retry-stable request ID for one pending Topic follow-up.
  * @param topicSessionId - target private Topic Session.

package/lib/types/client/rich-content.d.ts

@@ -18,6 +18,12 @@ export type RichSegment = {
     readonly kind: 'html';
     readonly document: string;
 };
+/**
+ * Break CommonMark image openers without changing visible text or ordinary links.
+ * @param text - untrusted board Markdown or table source.
+ * @returns Markdown that cannot produce image nodes.
+ */
+export declare function neutralizeMarkdownImages(text: string): string;
 /**
  * Split complete safe rich fences from Markdown while preserving all prose.
  * @param text - current assistant response text.

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

@@ -1,4 +1,4 @@
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { CiteSelection } from './types.ts';
 /**
  * Resolve the current DOM selection into a CiteSelection.
@@ -9,14 +9,16 @@ import type { CiteSelection } from './types.ts';
  *
  * @param event - context-menu event whose pointer position anchors the menu.
  * @param sourceSessionId - current session identity captured with the DOM range.
+ * @param committedAssistantText - DSH Session projection used when a collapsed reasoning row anchors the range.
  * @returns validated selection metadata, or null when CiteCiter should ignore it.
  */
-export declare function readSelection(event: MouseEvent, sourceSessionId: SessionId): CiteSelection | null;
+export declare function readSelection(event: MouseEvent, sourceSessionId: SessionId, committedAssistantText?: string): CiteSelection | null;
 /**
  * Claim a context menu only after resolving a valid DSH assistant selection.
  *
  * @param event - context-menu event to validate and optionally cancel.
  * @param sourceSessionId - current source session captured with the selection.
+ * @param committedAssistantText - DSH Session projection used when a collapsed reasoning row anchors the range.
  * @returns validated selection metadata, or null while leaving the native menu untouched.
  */
-export declare function claimSelectionContextMenu(event: MouseEvent, sourceSessionId: SessionId): CiteSelection | null;
+export declare function claimSelectionContextMenu(event: MouseEvent, sourceSessionId: SessionId, committedAssistantText?: string): CiteSelection | null;

package/lib/types/client/topic-presentation.d.ts

@@ -0,0 +1,15 @@
+import type { TopicMessage } from '../topic.ts';
+/**
+ * Append a requested board reference without replacing text the user already wrote.
+ * @param draft - current Topic composer draft.
+ * @param prompt - explicit board reference requested by the user.
+ * @returns the combined composer value.
+ */
+export declare function appendBoardCitation(draft: string, prompt: string): string;
+/**
+ * Decide whether one Topic event belongs in the user-facing transcript.
+ * @param message - candidate projected Topic event.
+ * @param messages - complete ordered Topic transcript used to detect recovery.
+ * @returns whether the event should remain visible.
+ */
+export declare function isTopicMessageVisible(message: TopicMessage, messages: readonly TopicMessage[]): boolean;

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

@@ -1,6 +1,8 @@
-import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { ToolEvidenceProjection } from '../evidence-text.ts';
 /** One right-click selection inside a rendered assistant model call. */
-export interface CiteSelection {
+export interface AssistantCiteSelection {
+    readonly entryId: 'citeciter.entry.assistant';
     readonly sourceSessionId: SessionId;
     readonly displayText: string;
     readonly sourceHintText?: string;
@@ -13,15 +15,37 @@ export interface CiteSelection {
     readonly x: number;
     readonly y: number;
 }
+/** One right-click whole-card selection on a committed tool result. */
+export interface ToolCiteSelection {
+    readonly entryId: 'citeciter.entry.tool';
+    readonly sourceSessionId: SessionId;
+    readonly displayText: string;
+    readonly kind: 'tool-result';
+    readonly callId: string;
+    readonly projection: ToolEvidenceProjection;
+    readonly anchorKey: string;
+    readonly x: number;
+    readonly y: number;
+}
+/** One validated selection claimed by a CiteCiter client entry point. */
+export type CiteSelection = AssistantCiteSelection | ToolCiteSelection;
+/** One explicit request to append a blackboard reference to the Topic composer. */
+export interface BoardCitationRequest {
+    readonly id: number;
+    readonly topicSessionId: string;
+    readonly prompt: string;
+}
 export interface CiteOverlaySnapshot {
     readonly menuSelection: CiteSelection | null;
     readonly panelOpen: boolean;
+    readonly boardCitation: BoardCitationRequest | null;
 }
 /** Tiny observable state shared by the selection popover and independent dock. */
 export declare class CiteBus {
     private readonly reportListenerError;
     private snapshot;
     private readonly listeners;
+    private nextCitationId;
     /** @param reportListenerError - contains one failed browser subscriber. */
     constructor(reportListenerError: (error: unknown) => void);
     /** @returns stable overlay snapshot. */
@@ -32,5 +56,16 @@ export declare class CiteBus {
     setMenuSelection(selection: CiteSelection | null): void;
     /** Open or close the independent companion dock. */
     setPanelOpen(panelOpen: boolean): void;
+    /**
+     * Queue one user-requested board reference for the matching Topic composer.
+     * @param topicSessionId - Topic that owns the referenced board.
+     * @param prompt - composer text derived from the selected board element.
+     */
+    requestBoardCitation(topicSessionId: string, prompt: string): void;
+    /**
+     * Clear the citation only when the matching consumer handled it.
+     * @param id - monotonically assigned citation request identity.
+     */
+    clearBoardCitation(id: number): void;
     private notify;
 }

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

@@ -0,0 +1,59 @@
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { CiteCiterSettings } from '../topic.ts';
+type UpdateStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/** One newer package version returned by the validated Host check. */
+export interface AvailableUpdate {
+    readonly currentVersion: string;
+    readonly latestVersion: string;
+    readonly profile?: string;
+}
+/** Observable state shared by the update card and settings page. */
+export interface UpdateNoticeSnapshot {
+    available: AvailableUpdate | null;
+    checking: boolean;
+    copyStatus: 'idle' | 'copying' | 'copied' | 'error';
+    copyMessage: string | null;
+    notificationsEnabled: boolean;
+    preferenceReady: boolean;
+    preferencePersistence: 'host' | 'browser';
+    preferenceStatus: 'idle' | 'saving' | 'saved' | 'error';
+    preferenceMessage: string | null;
+}
+/** Initial root-scoped update-notice state. */
+export declare const INITIAL_UPDATE_SNAPSHOT: UpdateNoticeSnapshot;
+/** Browser APIs used by the update controller. */
+export interface UpdateBrowserEnvironment {
+    readonly document: Pick<Document, 'visibilityState' | 'addEventListener' | 'removeEventListener'>;
+    readonly sessionStorage: UpdateStorage;
+    readonly localStorage: UpdateStorage;
+    readonly clipboard: Pick<Clipboard, 'writeText'> | undefined;
+    readonly now: () => number;
+}
+/** Operations exposed to the update notice and settings page. */
+export interface UpdateController {
+    getSnapshot(): UpdateNoticeSnapshot;
+    subscribe(listener: () => void): () => void;
+    start(): Promise<void>;
+    copyUpdateCommand(): Promise<void>;
+    defer(): void;
+    setNotificationsEnabled(enabled: boolean): Promise<boolean>;
+    dispose(): Promise<void>;
+}
+/** Read a newer validated version, or null when the installed version is current. */
+export type CheckUpdate = (signal: AbortSignal) => Promise<AvailableUpdate | null>;
+/** @returns browser services without letting denied storage or clipboard getters break plugin mount. */
+export declare function createUpdateBrowserEnvironment(): UpdateBrowserEnvironment;
+/**
+ * Own update discovery, deferral, copy feedback, and preference persistence.
+ * @param settings - existing CiteCiter settings namespace scope.
+ * @param checkUpdate - validated Host version check; it never installs software.
+ * @param store - root-scoped observable state owned by the client runtime.
+ * @param environment - browser APIs, injectable for deterministic tests.
+ * @param reportCheckError - diagnostic sink for silent automatic-check failures.
+ * @returns the root-scoped update controller.
+ */
+export declare function createUpdateController(settings: SettingsScope<CiteCiterSettings>, checkUpdate: CheckUpdate, store: SnapshotStore<UpdateNoticeSnapshot>, environment?: UpdateBrowserEnvironment, reportCheckError?: (error: unknown) => void): UpdateController;
+/** @param version - validated latest package version. @param profile - active Desktop profile, or Web default. @returns the command shown and copied by the notice. */
+export declare function citeCiterUpdateCommand(version: string, profile?: string): string;
+export {};

package/lib/types/client/view-actions.d.ts

@@ -0,0 +1,26 @@
+/** Plain UI callbacks; subscriptions and disposal remain with the Client plugin. */
+import type { CompanionFace } from './companion-controller.ts';
+import type { ReaderFace } from './reader-controller.ts';
+import type { SettingsDocumentController } from './settings-document.ts';
+import type { CiteBus } from './types.ts';
+import type { UpdateController } from './update-controller.ts';
+/** Callbacks the Topic view may invoke. */
+export type CompanionActions = Omit<CompanionFace, 'getSnapshot' | 'subscribe' | 'dispose'>;
+/** Callbacks the document view may invoke. */
+export type ReaderActions = Omit<ReaderFace, 'getSnapshot' | 'subscribe' | 'dispose'>;
+/** Callbacks the settings view may invoke. */
+export type SettingsDocumentActions = Omit<SettingsDocumentController, 'getSnapshot' | 'subscribe' | 'dispose'>;
+/** Callbacks the update view may invoke. */
+export type UpdateActions = Omit<UpdateController, 'getSnapshot' | 'subscribe' | 'dispose'>;
+/** Overlay events used by rendered components. */
+export type OverlayActions = Pick<CiteBus, 'setMenuSelection' | 'setPanelOpen' | 'requestBoardCitation' | 'clearBoardCitation'>;
+/**
+ * Remove lifecycle and subscription methods from a plain controller's view props.
+ * @param controller - Client-owned controller with arrow-function callbacks.
+ * @returns callbacks separate from the observable supplied to inject.hooks.
+ */
+export declare function viewActions<T extends {
+    getSnapshot(): unknown;
+    subscribe(listener: () => void): () => void;
+    dispose(): Promise<void>;
+}>(controller: T): Omit<T, 'getSnapshot' | 'subscribe' | 'dispose'>;

package/lib/types/documents.d.ts

@@ -0,0 +1,45 @@
+import { type DocumentContent, type DocumentFormat, type DocumentSummary } from './topic.ts';
+/** Reader page budget keeps one document-get response comfortably bounded. */
+export declare const DOCUMENT_CONTENT_MAX_BYTES: number;
+interface DocumentRecordFile {
+    readonly schemaVersion: 1;
+    readonly documentId: string;
+    readonly title: string;
+    readonly format: DocumentFormat;
+    readonly size: number;
+    readonly importedAt: number;
+}
+/** Validate and persist one imported text document under the private library. */
+export declare class DocumentStore {
+    private readonly root;
+    /** @param root - private document library root. */
+    constructor(root?: string);
+    /**
+     * Persist one imported document and its normalized UTF-8 text.
+     * @param input - validated title, format, and content from the import boundary.
+     * @returns the durable document summary.
+     */
+    import(input: {
+        readonly title: string;
+        readonly format: DocumentFormat;
+        readonly content: string;
+    }): Promise<DocumentSummary>;
+    /**
+     * Read one stored document record and its complete normalized text.
+     * @param documentId - private document identity.
+     * @returns the record and content pair.
+     */
+    read(documentId: string): Promise<{
+        readonly record: DocumentRecordFile;
+        readonly content: string;
+    }>;
+    /** @returns all documents sorted by import time descending. */
+    list(): Promise<DocumentSummary[]>;
+    /**
+     * Return one bounded Reader page.
+     * @param documentId - private document identity.
+     * @returns the first content window, truncated when the text exceeds the page budget.
+     */
+    get(documentId: string): Promise<DocumentContent>;
+}
+export {};

package/lib/types/evidence-text.d.ts

@@ -0,0 +1,29 @@
+/** Shared tool-evidence text projections used by Host validation and Client claims. */
+/** Tool-result projection kinds carried by a tool EvidenceRef. */
+export type ToolEvidenceProjection = 'result-text' | 'terminal' | 'diff';
+/** One diff entry inside the opaque `tool/result.meta` written by dsh-tool-fs. */
+export interface FileDiffMetaEntry {
+    readonly path: string;
+    readonly oldText: string | null;
+    readonly newText: string;
+}
+/**
+ * Join the text blocks of one tool result into its citable projection.
+ * @param blocks - model-facing tool-result content blocks.
+ * @returns concatenated text blocks.
+ */
+export declare function projectToolResultText(blocks: readonly unknown[]): string;
+/**
+ * Project one diff payload from a tool-result presentation meta.
+ * @param meta - opaque tool-result meta carrying an optional `diffs` array.
+ * @returns deterministic whole-card diff text, or null when no valid diff exists.
+ */
+export declare function projectDiffMeta(meta: unknown): string | null;
+/**
+ * Resolve the citable whole-card projection for one tool result.
+ * @param projection - declared evidence projection kind.
+ * @param content - model-facing tool-result content blocks.
+ * @param meta - opaque presentation meta (diff payload for the diff projection).
+ * @returns projection text, or null when the payload cannot satisfy the kind.
+ */
+export declare function projectToolEvidence(projection: ToolEvidenceProjection, content: readonly unknown[], meta: unknown): string | null;

package/lib/types/index.d.ts

@@ -2,38 +2,37 @@
 import { Service, type Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import z from '@deepseek-ai/schemastery';
+import { type UpdateCheckResponse } from './update.ts';
 import { type CiteCiterRequest, type CiteCiterResponse } from './topic.ts';
 /** Cordis/Typert package identity. */
 export declare const name = "@kirkchinese/dsh-citeciter";
 /** Services required by the private Topic runtime. */
 export declare const inject: readonly ["llm", "sessionQuery", "subprocess"];
 /** Host settings identity shared with the browser settings scope. */
-export declare const CITECITER_SETTINGS_NS: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export declare const CITECITER_SETTINGS_NS: "citeciter";
 /** Native settings schema for new Topics and the companion panel. */
-export declare const CITECITER_SETTINGS_SCHEMA: z<Schemastery.ObjectS<{
-    defaultMode: z<"observer" | "exact-when-available", "observer" | "exact-when-available">;
-    includeSourceReasoning: z<boolean, boolean>;
-    allowSourceFiles: z<boolean, boolean>;
-    panelWidthPercent: z<number, number>;
-    reopenLastTopic: z<boolean, boolean>;
-}>, Schemastery.ObjectT<{
-    defaultMode: z<"observer" | "exact-when-available", "observer" | "exact-when-available">;
-    includeSourceReasoning: z<boolean, boolean>;
-    allowSourceFiles: z<boolean, boolean>;
-    panelWidthPercent: z<number, number>;
-    reopenLastTopic: z<boolean, boolean>;
-}>>;
+export declare const CITECITER_SETTINGS_SCHEMA: z<object>;
 /** Root-scoped Remote service owning one isolated DSH runtime. */
 export declare class CiteCiterHost extends TypertRemoteService {
     static inject: readonly ["llm", "sessionQuery", "subprocess"];
     private readonly topics;
+    private readonly updates;
+    private readonly service;
+    private releaseService;
     constructor(ctx: Context);
     /** Do not publish the Remote service until its private runtime is ready. */
     [Service.init](): Promise<void>;
+    /** Resolve one create/ask command into a committed Topic snapshot. */
+    private topicSnapshot;
     /** Validate and execute one strict Topic command. */
     request(rawRequest: CiteCiterRequest, signal: AbortSignal): Promise<CiteCiterResponse>;
+    /** Check npm for an installable stable version without changing this installation. */
+    checkUpdate(signal: AbortSignal): Promise<UpdateCheckResponse>;
 }
 /** Register optional settings and mount the Host Remote service. */
 export declare function apply(ctx: Context): Promise<void>;
-export type { CiteCiterRequest, CiteCiterResponse, CiteCiterSettings, CitationSelectionClaim, CitationDraft, CitationRecord, TopicSnapshot, TopicSummary, } from './topic.ts';
+export type { CiteCiterService } from './service.ts';
+export { updateCheckErrorCodeSchema, updateCheckResponseSchema } from './update.ts';
+export type { UpdateCheckErrorCode, UpdateCheckResponse } from './update.ts';
+export type { CiteCiterRequest, CiteCiterResponse, CiteCiterSettings, CitationSelectionClaim, CitationDraft, CitationEntry, CitationEvidence, CitationRecord, DocumentContent, DocumentEvidenceClaim, DocumentFormat, DocumentSummary, ToolEvidenceClaim, TopicMode, TopicScenario, TopicSnapshot, TopicSummary, } from './topic.ts';
 export default CiteCiterHost;

package/lib/types/observer.d.ts

@@ -1,5 +1,7 @@
-import { type JsonValue, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session';
-import { type CitationSelectionClaim, type CitationDraft } from './topic.ts';
+export { projectDiffMeta, projectToolEvidence, projectToolResultText, type ToolEvidenceProjection, } from './evidence-text.ts';
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session';
+import { type JsonValue } from '@deepseek-ai/dsh-util-values';
+import { type CitationEvidence, type CitationSelectionClaim, type CitationDraft, type DocumentEvidenceClaim, type ToolEvidenceClaim } from './topic.ts';
 /** One atomic live-preferred SessionQuery observation. */
 export interface ObserverSourceSnapshot {
     readonly session: Pick<SessionHeader, 'id' | 'cwd'>;
@@ -12,6 +14,14 @@ export interface ValidatedObserverCitation {
     readonly assistantVisibleText: string;
     readonly contentFingerprint: string;
 }
+/** One Host-verified tool-result evidence resolved from a browser claim. */
+export interface ValidatedToolEvidence {
+    readonly evidence: CitationEvidence;
+}
+/** One Host-verified document-range evidence resolved against the stored text. */
+export interface ValidatedDocumentEvidence {
+    readonly evidence: CitationEvidence;
+}
 /** Options for one bounded `read_source_session` result. */
 export interface SourceReadOptions {
     readonly fromSeq?: number;
@@ -35,6 +45,8 @@ export interface SourceReadResult {
 }
 /** Compute the SHA-256 identity carried by the current CitationDraft schema. */
 export declare function fingerprintCitationDraft(draft: Omit<CitationDraft, 'selectionFingerprint'>): string;
+/** Compute the SHA-256 identity of a canonical v4 Citation evidence record. */
+export declare function fingerprintCitationRecord(record: CitationEvidence): string;
 /** Resolve a browser selection claim against the authoritative committed assistant message. */
 export declare function resolveObserverCitation(source: ObserverSourceSnapshot, rawClaim: CitationSelectionClaim): ValidatedObserverCitation;
 /**
@@ -42,5 +54,19 @@ export declare function resolveObserverCitation(source: ObserverSourceSnapshot,
  * A matching `assistant/message` is sufficient; its step and turn may remain open.
  */
 export declare function validateObserverCitation(source: ObserverSourceSnapshot, rawDraft: CitationDraft): ValidatedObserverCitation;
+/**
+ * Resolve a whole-card tool-result claim against the committed `tool/result`.
+ * @param source - one atomic live-preferred SessionQuery observation.
+ * @param rawClaim - browser-submitted tool result identity, projection, and visible quote.
+ * @returns verified evidence with the full committed projection text.
+ */
+export declare function resolveToolEvidence(source: ObserverSourceSnapshot, rawClaim: ToolEvidenceClaim): ValidatedToolEvidence;
+/**
+ * Re-resolve a Reader selection against the authoritative stored document text.
+ * @param content - complete normalized document text.
+ * @param rawClaim - browser-submitted document identity and visible quote context.
+ * @returns verified evidence with document offsets in its entry.
+ */
+export declare function resolveDocumentEvidence(content: string, rawClaim: DocumentEvidenceClaim): ValidatedDocumentEvidence;
 /** Format one seq range without exposing chunks or exceeding the event-array byte budget. */
 export declare function formatSourceSessionRead(source: ObserverSourceSnapshot, options: SourceReadOptions): SourceReadResult;

package/lib/types/service.d.ts

@@ -0,0 +1,81 @@
+/** Public CiteCiter host service face (`ctx.citeciterRuntime`; `ctx.citeciter` stays the Typert Remote service) for other DSH plugins. */
+import type { CiteCiterRequest, CiteCiterResponse, TopicSnapshot, TopicSummary } from './topic.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        citeciterRuntime?: CiteCiterService;
+    }
+    interface Events {
+        /**
+         * A new Topic committed its metadata and answered its first question.
+         * @param payload.topic - the durable Topic summary.
+         * @mode emit
+         */
+        'citeciter/topic-created'(payload: {
+            topic: TopicSummary;
+        }): void;
+        /**
+         * An existing Topic committed a state change (follow-up, stop, rename,
+         * archive, or model route change).
+         * @param payload.topic - the durable Topic summary.
+         * @mode emit
+         */
+        'citeciter/topic-updated'(payload: {
+            topic: TopicSummary;
+        }): void;
+        /**
+         * A Topic was logically deleted; physical owner cleanup may still be pending.
+         * @param payload - deleted Topic identity and independent cleanup outcome.
+         * @mode emit
+         */
+        'citeciter/topic-deleted'(payload: Omit<Extract<CiteCiterResponse, {
+            kind: 'deleted';
+        }>, 'kind'>): void;
+    }
+}
+/** Command-style v1 host API: the same validated surface the browser Remote exposes. */
+export interface CiteCiterService {
+    /**
+     * Create one source-bound Topic, with or without a validated evidence claim.
+     * @param request - strict source or evidence create command.
+     * @param signal - caller cancellation.
+     * @returns the committed Topic snapshot.
+     */
+    create(request: Extract<CiteCiterRequest, {
+        action: 'create';
+    }>, signal?: AbortSignal): Promise<TopicSnapshot>;
+    /**
+     * Submit one follow-up question to a Topic.
+     * @param request - strict ask command.
+     * @param signal - caller cancellation.
+     * @returns the committed Topic snapshot.
+     */
+    ask(request: Extract<CiteCiterRequest, {
+        action: 'ask';
+    }>, signal?: AbortSignal): Promise<TopicSnapshot>;
+    /**
+     * Read one Topic snapshot.
+     * @param topicSessionId - private Topic Session identity.
+     * @param signal - caller cancellation.
+     * @returns the current Topic snapshot.
+     */
+    get(topicSessionId: string, signal?: AbortSignal): Promise<TopicSnapshot>;
+    /**
+     * List Topics grouped by their source session.
+     * @param sourceSessionId - source DSH Session identity.
+     * @param includeArchived - include archived Topics when true.
+     * @param signal - caller cancellation.
+     * @returns summaries sorted by update time descending.
+     */
+    list(sourceSessionId: string, includeArchived?: boolean, signal?: AbortSignal): Promise<TopicSummary[]>;
+    /**
+     * Permanently delete one Topic from CiteCiter's private JSONL store.
+     * @param request - strict delete command carrying the repeated target identity.
+     * @param signal - caller cancellation before logical deletion commits.
+     * @returns logical deletion identity and physical cleanup outcome.
+     */
+    delete(request: Extract<CiteCiterRequest, {
+        action: 'delete';
+    }>, signal?: AbortSignal): Promise<Extract<CiteCiterResponse, {
+        kind: 'deleted';
+    }>>;
+}