@kirkchinese/dsh-citeciter 0.6.0 → 0.8.0

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

@@ -0,0 +1,6 @@
+import type { NativeComposer } from '../native-composer.ts';
+/** Read and mutate the Host's authoritative inbox. Citer never owns a second queue. */
+export declare function NativeQueue({ sessionId, native }: {
+    readonly sessionId: string;
+    readonly native: NativeComposer;
+}): import("react").JSX.Element | null;

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

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react';
+/**
+ * Render plugin-owned floating content outside the shell's stacking context.
+ * The public slot still owns its React lifetime; unmounting removes the portal.
+ * Inline content keeps its original ancestry for the isolated dock adapter.
+ */
+export declare function OverlayPortal({ children, inline }: {
+    readonly children: ReactNode;
+    readonly inline?: boolean;
+}): ReactNode;

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

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

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

@@ -1,8 +1,14 @@
-import type { CompanionActions } from '../view-actions.ts';
+import type { AskUserQuestionAnswer } from '@deepseek-ai/dsh-user-questions';
 import type { PendingQuestion } from '../../topic.ts';
 export interface QuestionCardProps {
-    readonly companion: CompanionActions;
-    readonly pending: PendingQuestion;
+    readonly pending: {
+        readonly key: string;
+        readonly questions: readonly (PendingQuestion['questions'][number] & {
+            readonly detail?: string;
+        })[];
+    };
+    readonly onAnswer: (answer: AskUserQuestionAnswer) => Promise<unknown>;
+    readonly onCancel: () => Promise<unknown>;
 }
 /** Collect one standard DSH ask_user_question answer batch inside the private Topic. */
-export declare function QuestionCard({ companion, pending }: QuestionCardProps): import("react").JSX.Element | null;
+export declare function QuestionCard({ onAnswer, onCancel, pending }: QuestionCardProps): import("react").JSX.Element | null;

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

@@ -0,0 +1,5 @@
+/** Display only reasoning actually returned by the model. Expansion is local UI state; no model call or Session mutation occurs. */
+export declare function ReasoningDisclosure({ text, active }: {
+    readonly text: string;
+    readonly active: boolean;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,6 @@
+import { type DraftReference } from '../draft-references.ts';
+/** Removable draft chips and rendered previews. No model calls or source reads. */
+export declare function ReferenceAttachments({ references, onRemove }: {
+    readonly references: readonly DraftReference[];
+    readonly onRemove?: (id: string) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,6 @@
+/** Workspace actions remain reachable without a floating launcher over the composer. Callbacks own their dialogs and services. */
+export declare function TopicActions({ hasTopic, onSettings, onReader }: {
+    readonly hasTopic: boolean;
+    readonly onSettings: () => void;
+    readonly onReader: () => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,36 @@
+import { type FormEvent, type Ref, type ReactNode } from 'react';
+import type { ProviderOption, TopicModelConfig } from '../../topic.ts';
+import type { CompanionPhase } from '../companion-controller.ts';
+import { type PermissionMode } from './PermissionControl.tsx';
+import type { DeliveryMode } from '../native-composer.ts';
+import type { DraftReference } from '../draft-references.ts';
+/**
+ * Render the Topic draft and its submission controls without accessing services.
+ * @param props - controlled draft, model route, request state and user-action callbacks.
+ * @returns one form; model changes and sending remain owned by the Topic controller.
+ */
+export declare function TopicComposer({ question, placeholder, route, providers, phase, canSend, routeSaving, folded, inputRef, onExpand, onQuestion, onSubmit, onStop, onModel, onReasoning, attachments, permission, onPermission, onFiles, delivery, onDelivery, sources, onReference }: {
+    readonly sources: readonly DraftReference[];
+    readonly onReference: (reference: DraftReference) => void;
+    readonly permission: PermissionMode;
+    readonly onPermission: (mode: PermissionMode) => void;
+    readonly onFiles: (files: readonly File[]) => void;
+    readonly delivery: DeliveryMode;
+    readonly onDelivery: (mode: DeliveryMode) => void;
+    readonly attachments?: ReactNode;
+    readonly question: string;
+    readonly placeholder: string;
+    readonly route: TopicModelConfig | undefined;
+    readonly providers: readonly ProviderOption[];
+    readonly phase: CompanionPhase;
+    readonly canSend: boolean;
+    readonly routeSaving: boolean;
+    readonly folded: boolean;
+    readonly inputRef: Ref<HTMLTextAreaElement>;
+    readonly onExpand: () => void;
+    readonly onQuestion: (question: string) => void;
+    readonly onSubmit: (event: FormEvent, mode?: DeliveryMode) => void;
+    readonly onStop: () => void;
+    readonly onModel: (provider: string, model: string) => void;
+    readonly onReasoning: (effort: string | null) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,10 @@
+import type { PointerEventHandler, ReactNode } from 'react';
+/** Layout-only header: navigation, title and drag behavior are supplied by their independent controllers. */
+export declare function TopicHeader({ compact, onBack, onDrag, title, status, children }: {
+    readonly compact: boolean;
+    readonly onBack: () => void;
+    readonly onDrag: PointerEventHandler<HTMLElement>;
+    readonly title: ReactNode;
+    readonly status: string;
+    readonly children: ReactNode;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,9 @@
+import type { ProviderOption, TopicModelConfig } from '../../topic.ts';
+/** Model and reasoning hierarchy. Route changes are committed by the injected controller. */
+export declare function TopicModelControls({ providers, route, saving, onModel, onReasoning }: {
+    readonly providers: readonly ProviderOption[];
+    readonly route: TopicModelConfig;
+    readonly saving: boolean;
+    readonly onModel: (provider: string, model: string) => void;
+    readonly onReasoning: (effort: string | null) => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+import type { TopicSummary } from '../../topic.ts';
+/** Session-list navigation with search. Receives domain rows and callbacks, without service discovery. */
+export declare function TopicNavigation({ topics, activeId, archived, onOpen, onNew, onArchiveView, onSettings, onReader }: {
+    readonly topics: readonly TopicSummary[];
+    readonly activeId: string | undefined;
+    readonly archived: boolean;
+    readonly onOpen: (id: string) => void;
+    readonly onNew: () => void;
+    readonly onArchiveView: (archived: boolean) => void;
+    readonly onSettings: () => void;
+    readonly onReader: () => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,21 @@
+/**
+ * Render infrequent Topic management separately from the learning composer.
+ * @param props - current identity, operation status and management callbacks.
+ * @returns a controlled dialog; deletion is enabled only for legacy private logs or verified Citer-owned source storage.
+ */
+export declare function TopicSettingsDialog({ open, topic, archiving, deleting, error, onClose, onArchive, onDelete }: {
+    readonly open: boolean;
+    readonly topic: {
+        readonly sessionId: string;
+        readonly title: string;
+        readonly archived: boolean;
+        readonly hosted?: boolean | undefined;
+        readonly storage?: 'source' | undefined;
+    } | undefined;
+    readonly archiving: boolean;
+    readonly deleting: boolean;
+    readonly error: string | null;
+    readonly onClose: () => void;
+    readonly onArchive: (archived: boolean) => Promise<boolean>;
+    readonly onDelete: () => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,6 @@
+/** Inline rename committed by Enter or blur, cancelled by Escape. Double-click and F2 start editing. */
+export declare function TopicTitle({ id, title, onRename }: {
+    readonly id: string;
+    readonly title: string;
+    readonly onRename: (title: string) => Promise<boolean>;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,4 @@
+/** Read-only presentation of a committed user message. Attachments remain inspectable and formulas are rendered without mutating the durable prompt. */
+export declare function UserMessageBody({ text }: {
+    readonly text: string;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,7 @@
+import type { CompanionSnapshot } from '../companion-controller.ts';
+import type { CompanionActions } from '../view-actions.ts';
+/** Edit eight stable slots as one validated settings transaction. */
+export declare function WheelSettings({ snapshot, companion }: {
+    snapshot: CompanionSnapshot;
+    companion: CompanionActions;
+}): import("react").JSX.Element;

package/lib/types/client/dock-geometry.d.ts

@@ -7,15 +7,15 @@ export interface DockViewport {
     readonly caption: number;
     readonly percent: number;
 }
-/** The host keeps its conversation and details visible in both arrangements. */
+/** Wide windows reserve a column; compact windows navigate to a Citer page. */
 export interface DockGeometry {
-    readonly mode: 'columns' | 'rows';
+    readonly mode: 'columns' | 'page';
     readonly width: number;
     readonly height: number;
     readonly top: number;
 }
 /**
- * Reserve a separate column, or a bottom row when two readable columns cannot fit.
+ * Reserve a separate column, or the content area when two readable columns cannot fit.
  * CSS pixels already account for browser zoom and Windows display scaling.
  * @param viewport - measured host dimensions and the saved width preference.
  * @returns panel dimensions within the host, excluding its native caption.

package/lib/types/client/draft-references.d.ts

@@ -0,0 +1,20 @@
+import type { TopicSummary } from '../topic.ts';
+/** One unsent model-visible reference. Removing this value removes its serialized content. */
+export interface DraftReference {
+    readonly id: string;
+    readonly kind: 'source' | 'excerpt' | 'board';
+    readonly label: string;
+    readonly content: string;
+    readonly address?: string;
+}
+/** Build initial references without submitting them. Stable Topic-scoped IDs preserve menu focus during live snapshot refreshes. */
+export declare function topicDraftReferences(topic: TopicSummary, documentTitle?: string): readonly DraftReference[];
+/** Display a document filename while retaining the full title/path in its serialized content. Legacy ID-only references keep their generic label. */
+export declare function draftReferenceName(reference: DraftReference): string;
+/** Serialize the exact visible attachment collection only at manual submission. */
+export declare function serializeDraftReferences(question: string, references: readonly DraftReference[]): string;
+/** Present sent reference blocks as expandable attachments while retaining the exact serialized model input in the Session log. Unrecognized text is preserved. */
+export declare function parseSentReferences(text: string): {
+    readonly question: string;
+    readonly references: readonly DraftReference[];
+};

package/lib/types/client/file-download.d.ts

@@ -0,0 +1,16 @@
+import type { NativeComposer } from './native-composer.ts';
+/**
+ * Download one committed attachment on demand through its owning Session.
+ * @param sessionId - the exact Topic that authorizes the attachment read.
+ * @param id - the durable native attachment identity.
+ * @param name - suggested local filename; never used as a source filesystem path.
+ * @param load - native attachment reader, provided by the client controller.
+ * @returns the download action and its visible progress/error state.
+ * Repeated clicks share one request. Identity changes and unmount cancel UI effects
+ * and release the owned object URL without cancelling the host's shared reader.
+ */
+export declare function useFileDownload(sessionId: string, id: string, name: string, load: NativeComposer['attachment']): {
+    download: () => Promise<void>;
+    busy: boolean;
+    error: string | undefined;
+};

package/lib/types/client/file-drop.d.ts

@@ -0,0 +1,18 @@
+import { type DragEvent } from 'react';
+/**
+ * Isolate file drags inside one physical panel from document-level drop owners.
+ * @param open - whether the owning panel is mounted and available.
+ * @param enabled - whether a current Topic can receive attachments.
+ * @param onFiles - receive one dropped batch; never submits a model request.
+ * @returns the local invitation state and handlers to spread on the panel root.
+ * Global cancellation listeners exist only while open and are released on cleanup.
+ */
+export declare function useFileDrop(open: boolean, enabled: boolean, onFiles: (files: readonly File[]) => void): {
+    active: boolean;
+    handlers: {
+        onDragEnter: (event: DragEvent<HTMLElement>) => void;
+        onDragOver: (event: DragEvent<HTMLElement>) => void;
+        onDragLeave: (event: DragEvent<HTMLElement>) => void;
+        onDrop: (event: DragEvent<HTMLElement>) => void;
+    };
+};

package/lib/types/client/host-dock.d.ts

@@ -1,4 +1,4 @@
-/** Isolated, disposable layout adapter for DSH rc.1 and Desktop 2.0.5 frames. */
+/** Isolated, disposable layout adapter for DSH 0.1.5-rc.1 and Desktop 2.0.9 frames. */
 import { type RefObject } from 'react';
 import { type DockGeometry } from './dock-geometry.ts';
 /**
@@ -15,4 +15,4 @@ export declare function findContainingFrame(panel: HTMLElement | null): HTMLElem
  * @param percent - user's preferred fraction of the content viewport.
  * @returns measured panel placement; null when the host frame is unsupported.
  */
-export declare function useHostDock(panel: RefObject<HTMLElement | null>, open: boolean, percent: number): DockGeometry | null;
+export declare function useHostDock(panel: RefObject<HTMLElement | null>, open: boolean, percent: number, floating?: boolean): DockGeometry | null;

package/lib/types/client/learning-route.d.ts

@@ -0,0 +1,10 @@
+import type { TopicMessage } from '../topic.ts';
+/** Public todo states, projected from successful native todo_write results. */
+export interface LearningTodo {
+    readonly content: string;
+    readonly status: 'pending' | 'in_progress' | 'completed';
+}
+/** Read the last accepted plan; malformed historical tool arguments do not replace a valid plan. */
+export declare function learningTodos(messages: readonly TopicMessage[]): readonly LearningTodo[];
+/** One user-submitted learning request. Planning continues inside its ordinary Agent turn. */
+export declare function withLearningRoute(question: string, enabled: boolean): string;

package/lib/types/client/native-composer.d.ts

@@ -0,0 +1,18 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ComposerAttachment, DraftAttachmentId, DraftFileUploads } from '@deepseek-ai/dsh-client-ui-conversation/client';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { SessionFace, SessionSnapshot } from '@deepseek-ai/dsh-api-session-controller/client';
+export type DeliveryMode = 'queue' | 'steer';
+export interface NativeComposer {
+    readonly uploads: ObservableSnapshot<DraftFileUploads>;
+    retry(sessionId: string, id: DraftAttachmentId): void;
+    watch(sessionId: string, listener: (snapshot: SessionSnapshot) => void): () => void;
+    queue(sessionId: string, id: Parameters<SessionFace['updateQueue']>[0], action: Parameters<SessionFace['updateQueue']>[1]): Promise<void>;
+    /** Read an image or file through its owning Session's attachment authorization. */
+    attachment(sessionId: string, id: string): Promise<Blob>;
+    add(sessionId: string, files: readonly File[]): Promise<readonly ComposerAttachment[]>;
+    remove(id: DraftAttachmentId): void;
+    send(sessionId: string, text: string, attachments: readonly DraftAttachmentId[], mode: DeliveryMode): Promise<void>;
+}
+/** Adapt the installed conversation service's published composer methods; never reach its private input machine. */
+export declare function createNativeComposer(ctx: Context): NativeComposer;

package/lib/types/client/native-document.d.ts

@@ -0,0 +1,13 @@
+import type { ActionSource } from './action-controller.ts';
+import type { ReaderSelection } from './reader-selection.ts';
+/** Decode a complete Host-owned preview buffer. Reject binary, partial and oversized imports. */
+export declare function decodeNativeText(content: {
+    readonly kind: 'text';
+    readonly text: string;
+    readonly eof: boolean;
+} | {
+    readonly kind: 'bytes';
+    readonly data: Uint8Array;
+}): string;
+/** Capture the file address's own Session and immutable text, never the later active tab. */
+export declare function nativeDocumentSource(address: string, content: string, selection: ReaderSelection): ActionSource;

package/lib/types/client/panel-drag.d.ts

@@ -0,0 +1,10 @@
+import { type PointerEvent, type RefObject } from 'react';
+/** Pointer lifecycle survives reparenting between the host slot and the floating portal. */
+export declare function usePanelDrag(panel: RefObject<HTMLElement | null>, floating: boolean, setPresentation: (mode: 'side' | 'floating') => void): {
+    position: {
+        left: number;
+        top: number;
+    } | null;
+    dockTarget: boolean;
+    start: (event: PointerEvent<HTMLElement>) => void;
+};

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

@@ -11,6 +11,8 @@ export interface ReaderSnapshot {
     selection: ReaderSelection | null;
     question: string;
     creating: boolean;
+    importing: boolean;
+    loading: boolean;
     error: string | null;
 }
 export interface ReaderFace {
@@ -19,7 +21,11 @@ export interface ReaderFace {
     setOpen(open: boolean): void;
     refresh(): Promise<void>;
     importFile(name: string, content: string): Promise<DocumentSummary | null>;
+    /** Read a local text file; file access failures are displayed in the Reader. */
+    importLocalFile(file: Pick<File, 'name' | 'size' | 'text'>): Promise<void>;
     openDocument(documentId: string): Promise<void>;
+    /** Load a zero-based page of the active document, clearing its previous selection. */
+    openPage(page: number): Promise<void>;
     setSelection(selection: ReaderSelection | null): void;
     setQuestion(question: string): void;
     createTopic(): Promise<void>;

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

@@ -1,3 +1,4 @@
+import type { ActionModel } from '../actions.ts';
 import type { TopicScenario } from '../topic.ts';
 import type { CiteSelection } from './types.ts';
 export type CreateMode = 'observer' | 'exact-fork' | 'exact-when-available';
@@ -12,7 +13,7 @@ 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, scenario?: TopicScenario): Promise<RequestIntent>;
+export declare function claimCreateTopicIntent(selection: CiteSelection, question: string, mode: CreateMode, scenario?: TopicScenario, modelRoute?: ActionModel): Promise<RequestIntent>;
 /**
  * Claim the retry-stable request ID for one uncited Topic creation.
  * @param sourceSessionId - owning DSH Session.
@@ -34,7 +35,7 @@ export interface DocumentClaimIntent {
  * @param question - normalized first question.
  * @returns the pending intent key and request ID.
  */
-export declare function claimCreateDocumentIntent(claim: DocumentClaimIntent, question: string): Promise<RequestIntent>;
+export declare function claimCreateDocumentIntent(claim: DocumentClaimIntent, question: string, sourceSessionId?: string, modelRoute?: ActionModel): Promise<RequestIntent>;
 /**
  * Claim the retry-stable request ID for one pending Topic follow-up.
  * @param topicSessionId - target private Topic Session.

package/lib/types/client/submission-preference.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { DeliveryMode } from './native-composer.ts';
+/** Read the conversation-owned busy-Enter preference through the public settings mirror. The bound scope is disposed with ctx; this adapter never writes Host settings. */
+export declare function bindSubmissionPreference(ctx: Context): ObservableSnapshot<DeliveryMode>;

package/lib/types/client/transcript-position.d.ts

@@ -0,0 +1,6 @@
+import { type UIEvent } from 'react';
+/** Keep each Topic's reading position across portal moves, view changes and close/reopen. Follow new output only while the reader is near the end. */
+export declare function useTranscriptPosition(topicId: string, revision: unknown): {
+    ref: (node: HTMLDivElement | null) => void;
+    onScroll: (event: UIEvent<HTMLDivElement>) => void;
+};

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

@@ -1,5 +1,6 @@
 import type { SessionId } from '@deepseek-ai/dsh-session/types';
 import type { ToolEvidenceProjection } from '../evidence-text.ts';
+import type { PanelPresentation } from '../actions.ts';
 /** One right-click selection inside a rendered assistant model call. */
 export interface AssistantCiteSelection {
     readonly entryId: 'citeciter.entry.assistant';
@@ -36,11 +37,11 @@ export interface BoardCitationRequest {
     readonly prompt: string;
 }
 export interface CiteOverlaySnapshot {
-    readonly menuSelection: CiteSelection | null;
     readonly panelOpen: boolean;
+    readonly presentation: PanelPresentation;
     readonly boardCitation: BoardCitationRequest | null;
 }
-/** Tiny observable state shared by the selection popover and independent dock. */
+/** Observable panel presentation and board-citation requests; gestures have their own controller. */
 export declare class CiteBus {
     private readonly reportListenerError;
     private snapshot;
@@ -52,10 +53,10 @@ export declare class CiteBus {
     getSnapshot: () => CiteOverlaySnapshot;
     /** @param listener - observer. @returns disposer. */
     subscribe: (listener: () => void) => (() => void);
-    /** Show or dismiss the selection question popover. */
-    setMenuSelection(selection: CiteSelection | null): void;
     /** Open or close the independent companion dock. */
     setPanelOpen(panelOpen: boolean): void;
+    /** Change only the current workspace presentation, keeping its Topic and drafts. */
+    setPresentation(presentation: PanelPresentation): void;
     /**
      * Queue one user-requested board reference for the matching Topic composer.
      * @param topicSessionId - Topic that owns the referenced board.

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

@@ -13,7 +13,7 @@ export type SettingsDocumentActions = Omit<SettingsDocumentController, 'getSnaps
 /** 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'>;
+export type OverlayActions = Pick<CiteBus, 'setPanelOpen' | 'setPresentation' | 'requestBoardCitation' | 'clearBoardCitation'>;
 /**
  * Remove lifecycle and subscription methods from a plain controller's view props.
  * @param controller - Client-owned controller with arrow-function callbacks.

package/lib/types/client/wheel-gesture.d.ts

@@ -0,0 +1,13 @@
+import { type CiteAction, type WheelTrigger } from '../actions.ts';
+import type { ActionController, ActionSource } from './action-controller.ts';
+/** Owned reading surfaces provide captures without probing other plugins' private DOM. */
+export declare function createSelectionSurfaces(): {
+    register(element: HTMLElement, read: () => ActionSource | null): () => void;
+    read(target: EventTarget | null): ActionSource | null;
+};
+export type SelectionSurfaces = ReturnType<typeof createSelectionSurfaces>;
+/** Install hold/move/release gestures; returns a disposer removing every global listener. */
+export declare function installWheelGesture(controller: ActionController, read: (event: MouseEvent) => ActionSource | null, preferences: () => {
+    wheelTrigger?: WheelTrigger | undefined;
+    wheelSlots?: (CiteAction | null)[] | undefined;
+}): () => void;

package/lib/types/document-pages.d.ts

@@ -0,0 +1,4 @@
+/** Shared Host/Client page budget; full text stays in the document owner. */
+export declare const DOCUMENT_CONTENT_MAX_BYTES: number;
+/** Split UTF-8 text without breaking code points; concatenation exactly reproduces the input. */
+export declare function documentPages(content: string): string[];

package/lib/types/documents.d.ts

@@ -1,6 +1,5 @@
 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;
+export { DOCUMENT_CONTENT_MAX_BYTES } from './document-pages.ts';
 interface DocumentRecordFile {
     readonly schemaVersion: 1;
     readonly documentId: string;
@@ -12,8 +11,11 @@ interface DocumentRecordFile {
 /** Validate and persist one imported text document under the private library. */
 export declare class DocumentStore {
     private readonly root;
+    private readonly summaries;
     /** @param root - private document library root. */
     constructor(root?: string);
+    /** Read validated, immutable metadata without loading the document body. Missing documents return null; successful reads are cached for this store's lifetime. */
+    summary(documentId: string): Promise<DocumentSummary | null>;
     /**
      * Persist one imported document and its normalized UTF-8 text.
      * @param input - validated title, format, and content from the import boundary.
@@ -38,8 +40,8 @@ export declare class DocumentStore {
     /**
      * Return one bounded Reader page.
      * @param documentId - private document identity.
-     * @returns the first content window, truncated when the text exceeds the page budget.
+     * @param pageIndex - zero-based page; omitted requests the first page. Out-of-range pages are rejected.
+     * @returns a UTF-8-budgeted page and the total page count; Unicode code points are never split.
      */
-    get(documentId: string): Promise<DocumentContent>;
+    get(documentId: string, pageIndex?: number): Promise<DocumentContent>;
 }
-export {};

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

@@ -0,0 +1,15 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type AgentLoop from '@deepseek-ai/dsh-agent-loop';
+import type SessionStore from '@deepseek-ai/dsh-session';
+interface HostScope {
+    readonly ctx: Context;
+    dispose(): Promise<void>;
+}
+export interface HostAgentModules {
+    readonly AgentLoop: typeof AgentLoop;
+    readonly SessionStore: typeof SessionStore;
+    readonly createScope: (ctx: Context, key: object) => HostScope;
+}
+/** Resolve published runtime modules from the actual launcher, preserving Desktop's module identities across external-plugin fallback paths. */
+export declare function loadHostAgentModules(): Promise<HostAgentModules>;
+export {};

package/lib/types/host-session-adapter.d.ts

@@ -0,0 +1,31 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import { type SessionEvent } from '@deepseek-ai/dsh-session';
+import type { CiteCiterSettings, TopicMetadata } from './topic.ts';
+/** Host-owned session services; Citer owns only its scoped contributions and factory handles. */
+export declare class HostSessionAdapter {
+    private readonly ctx;
+    private readonly settings;
+    private readonly assemble;
+    private readonly storageRoot;
+    private readonly metadata;
+    private readonly scopes;
+    private readonly worlds;
+    private readonly access;
+    private disposal;
+    constructor(ctx: Context, settings: () => CiteCiterSettings, assemble: (scope: Context, agent: Agent, metadata: TopicMetadata) => Promise<void>, storageRoot: (metadata: TopicMetadata) => string);
+    /** Drain owned factories before removing their native checkpoint routes. */
+    private dispose;
+    /** Retain navigation metadata before the Host can resume this identity. */
+    remember(metadata: TopicMetadata): void;
+    /** Resolve the Topic's factory/persistence realm, retaining old candidate records without deleting Host files. */
+    context(metadata: TopicMetadata): Promise<Context>;
+    /** Release a complete owned Topic realm before deleting its files. */
+    retire(metadata: TopicMetadata): Promise<void>;
+    /** Compose a Topic on a native Agent without replacing its loop, tools or permission service. */
+    private attach;
+    /** Create a native Session with an explicit initial permission. Citer supplies an empty seed so removed references cannot leak through inherited history. No prompt is sent here. */
+    create(metadata: TopicMetadata, seed: readonly SessionEvent[], signal?: AbortSignal): Promise<AgentHandle>;
+    /** Resume with the Host's preset and preserve the user's logged permission. */
+    resume(metadata: TopicMetadata, signal?: AbortSignal): Promise<AgentHandle>;
+}

package/lib/types/index.d.ts

@@ -1,4 +1,4 @@
-/** Host entry for private Observer Topics and their browser Remote API. */
+/** Host entry for native Topics, legacy compatibility and the browser Remote API. */
 import { Service, type Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import z from '@deepseek-ai/schemastery';
@@ -6,15 +6,15 @@ 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"];
+/** Explicit dependencies for native session composition and legacy compatibility. */
+export declare const inject: readonly ["llm", "sessionQuery", "subprocess", "agents", "agentPresets", "sessionController", "systemPrompt", "tools", "sandboxPolicy", "sessions", "sessionPersistence", "sessionTitle", "attachments"];
 /** Host settings identity shared with the browser settings scope. */
 export declare const CITECITER_SETTINGS_NS: "citeciter";
 /** Native settings schema for new Topics and the companion panel. */
 export declare const CITECITER_SETTINGS_SCHEMA: z<object>;
-/** Root-scoped Remote service owning one isolated DSH runtime. */
+/** Root-scoped Remote service owning Topic metadata, native contributions and a legacy runtime. */
 export declare class CiteCiterHost extends TypertRemoteService {
-    static inject: readonly ["llm", "sessionQuery", "subprocess"];
+    static inject: readonly ["llm", "sessionQuery", "subprocess", "agents", "agentPresets", "sessionController", "systemPrompt", "tools", "sandboxPolicy", "sessions", "sessionPersistence", "sessionTitle", "attachments"];
     private readonly topics;
     private readonly updates;
     private readonly service;