@qilin-agent/client-ui-sidebar-documentpreview 0.0.0-stage → 3.1.4

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

@@ -0,0 +1,16 @@
+/** Missing-font notice and a non-modal details panel for one source version. */
+import { type ReactNode } from 'react';
+import type { PropsLocale } from '@qilin-agent/client-ui-slots';
+/** Notice inputs supplied by the document owner and Office locale registration. */
+export type FontNoticeProps = PropsLocale<'sidebarOffice'> & {
+    readonly resourceAddress: string;
+    readonly sourceVersion: string;
+    readonly fonts: readonly string[];
+};
+/**
+ * Show missing fonts; dismissal applies to the same source version while this component stays mounted.
+ * @param props - source identity, converted content, and localized copy.
+ * @returns a collapsible notice and its anchored details, or nothing when fonts are available.
+ */
+export declare function FontNotice({ resourceAddress, sourceVersion, fonts, t }: FontNoticeProps): ReactNode;
+//# sourceMappingURL=FontNotice.d.ts.map

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

@@ -0,0 +1,44 @@
+/** Office owns source loading, conversion failures, and font notices around the shared PDF view. */
+import { type ReactNode } from 'react';
+import type { PropsLocale, PropsRenderSlots, PropsStore } from '@qilin-agent/client-ui-slots';
+import type { RemoteFailure } from '@qilin-agent/api-remotes/client';
+import type { TabId } from '@qilin-agent/client-ui-dockkit';
+import type { UseSidebarRightTabInfo } from '@qilin-agent/client-ui-sidebar-right/client';
+import type { DocumentBodyOwner, DocumentPreviewProps } from '../document/contract.ts';
+import type { ReadOfficeDocument } from './cache.ts';
+import type { OfficeStore } from './store.ts';
+declare module '@qilin-agent/client-ui-slots' {
+    interface SlotMap {
+        /** PDF presentation supplied with Office-owned converted bytes. */
+        'sidebar.right.tab.document.office.pdf': {
+            kind: 'keyed';
+            scope: 'session';
+            owner: DocumentBodyOwner;
+            hookContext: UseSidebarRightTabInfo;
+            inject: {
+                hooks: {
+                    tabInfo: SlotHookFactory<'sidebar.right.tab.document', UseSidebarRightTabInfo>;
+                };
+            };
+        };
+    }
+}
+/** Office loading callbacks supplied by the registration's services. */
+export interface OfficeBodyInjected {
+    readonly read: ReadOfficeDocument;
+    /** @param failure - declared file-read failure or conversion exception message. @returns localized display text. */
+    readonly describeFailure: (failure: RemoteFailure | {
+        readonly message: string;
+    }) => string;
+    /** @param tab - owning tab. @param signal - tab lifetime, including hidden bodies. */
+    readonly retainTab: (tab: TabId, signal: AbortSignal) => void;
+}
+/** Office body inputs and its private PDF child. */
+export type OfficeBodyProps = DocumentPreviewProps & PropsStore<OfficeStore> & OfficeBodyInjected & PropsLocale<'sidebarOffice'> & PropsRenderSlots<'sidebar.right.tab.document.office.pdf'>;
+/**
+ * Load one Office revision and preserve its result while its tab remains open.
+ * @param props - renderer loading request, tab state, conversion callbacks, and PDF slot.
+ * @returns conversion status or the font notice and PDF scrollport.
+ */
+export declare function OfficeBody(props: OfficeBodyProps): ReactNode;
+//# sourceMappingURL=OfficeBody.d.ts.map

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

@@ -0,0 +1,70 @@
+/** Session-authorized, version-checked Office bytes shared by concurrent preview reads. */
+import type { OfficeToPdfPriority, OfficeToPdfGeneration } from '@qilin-agent/office-to-pdf/types';
+import type { RemoteResult } from '@qilin-agent/api-remotes/client';
+import type { WorkspaceFileStat } from '@qilin-agent/api-workspace-files/types';
+import type { DocumentFileBytes, SessionFile } from '../rpc.ts';
+/** PDF bytes and conversion metadata owned by Office preview. */
+export type OfficeFileBytes = DocumentFileBytes & {
+    readonly missingFonts: readonly string[];
+    readonly generation: OfficeToPdfGeneration;
+};
+/**
+ * Load authorized PDF contents for one Office source.
+ * @param file - Session and source path.
+ * @param signal - this reader's lifetime.
+ * @returns converted PDF bytes or a declared source-access failure.
+ */
+export type ReadOfficeDocument = (file: SessionFile, signal: AbortSignal) => Promise<RemoteResult<OfficeFileBytes>>;
+/** Authorized cached reads carry explicit scheduling intent to the Host. */
+export type ReadOfficeBytes = (file: SessionFile, signal: AbortSignal, priority: OfficeToPdfPriority) => ReturnType<ReadOfficeDocument>;
+type Result = Awaited<ReturnType<ReadOfficeDocument>>;
+type Stat = (file: SessionFile, signal: AbortSignal) => Promise<RemoteResult<WorkspaceFileStat>>;
+/** Bounded successful results; each caller reauthorizes and checks source freshness before reuse. */
+export declare class OfficePreviewCache {
+    private readonly stat;
+    private readonly convert;
+    private readonly maxEntries;
+    private readonly maxBytes;
+    private readonly maxPending;
+    private readonly maxReaders;
+    private readonly currentGeneration;
+    private readonly busy;
+    private readonly ready;
+    private readonly pending;
+    private bytes;
+    private readers;
+    private generation;
+    private generationQuery;
+    private acceptedQuery;
+    private readonly superseded;
+    private readonly lifetime;
+    private readonly tasks;
+    private readonly reads;
+    /**
+     * @param stat - authorized source metadata lookup.
+     * @param convert - Host render Remote returning binary PDF bytes borrowed read-only by callers.
+     * @param maxEntries - maximum completed results retained.
+     * @param maxBytes - maximum retained PDF byteLength.
+     * @param maxPending - maximum unsettled Host conversion requests, including cancellation teardown.
+     * @param maxReaders - maximum readers, including metadata lookups.
+     * @param generation - current Host renderer generation, checked before cached reuse.
+     * @param busy - localized capacity failure.
+     */
+    constructor(stat: Stat, convert: ReadOfficeBytes, maxEntries: number, maxBytes: number, maxPending: number, maxReaders: number, currentGeneration: (signal: AbortSignal) => Promise<RemoteResult<OfficeToPdfGeneration>>, busy: () => Error);
+    /**
+     * Share a conversion without letting one caller cancel another caller's work.
+     * Renderer replacement retries authorization once; repeated replacement reports localized capacity failure.
+     * @param file - Session authorization scope and source path.
+     * @param signal - this caller's lifetime.
+     * @param priority - foreground preview or speculative read.
+     * @returns current PDF bytes borrowed read-only, or a declared source-read failure; cancellation rejects.
+     */
+    read(file: SessionFile, signal: AbortSignal, priority?: OfficeToPdfPriority): Promise<Result>;
+    private lookup;
+    private lookupGeneration;
+    /** Clear retained bytes, cancel outstanding conversions, and await their completion. */
+    dispose(): Promise<void>;
+    private retain;
+}
+export {};
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1,16 @@
+/** Office preview registration backed by authorized Host rendering and the existing PDF body. */
+import type { Context } from '@qilin-agent/kylin';
+import { type OfficePreviewKey } from './locales.ts';
+import type { Config } from '../../config.ts';
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        sidebarOffice: OfficePreviewKey;
+    }
+}
+/**
+ * Register Office previews with versioned PDF reuse and missing-font notices.
+ * @param ctx - Client renderer registry, localized copy, and optional Host Remotes.
+ * @param config - Resolved Office preview cache limits.
+ */
+export declare function apply(ctx: Context, config: Config['office']): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,43 @@
+/** Office preview copy and Host render configuration guidance. */
+export declare const zh: {
+    title: string;
+    loading: string;
+    retry: string;
+    missingFonts: string;
+    showMore: string;
+    dismissNotice: string;
+    missingFontsTitle: string;
+    missingFontsDescription: string;
+    missingFontsCount: string;
+    closeDetails: string;
+    unavailable: string;
+    invalid: string;
+    tooLarge: string;
+    failed: string;
+    timeout: string;
+    busy: string;
+    changed: string;
+};
+/** Office preview locale keys. */
+export type OfficePreviewKey = keyof typeof zh;
+/** English translations checked against the Chinese key set. */
+export declare const en: {
+    title: string;
+    loading: string;
+    retry: string;
+    missingFonts: string;
+    showMore: string;
+    dismissNotice: string;
+    missingFontsTitle: string;
+    missingFontsDescription: string;
+    missingFontsCount: string;
+    closeDetails: string;
+    unavailable: string;
+    invalid: string;
+    tooLarge: string;
+    failed: string;
+    timeout: string;
+    busy: string;
+    changed: string;
+};
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1,32 @@
+/** Loaded Office previews survive body remounts until reload or tab closure. */
+import { type EngineStoreHandle } from '@qilin-agent/client-store';
+import type { TabId } from '@qilin-agent/client-ui-dockkit';
+import type { OfficeFileBytes } from './cache.ts';
+/** One requested source revision and its settled preview. */
+export interface OfficeView {
+    readonly revision: number;
+    readonly file?: OfficeFileBytes;
+    readonly failure?: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+/** Office-owned content, isolated by tab identity. */
+export interface OfficeState {
+    byTab: Record<TabId, OfficeView>;
+}
+type OfficeActions = {
+    loading: (state: OfficeState, tab: TabId, revision: number) => void;
+    complete: (state: OfficeState, tab: TabId, revision: number, file: OfficeFileBytes) => void;
+    failed: (state: OfficeState, tab: TabId, revision: number, failure: NonNullable<OfficeView['failure']>) => void;
+    forget: (state: OfficeState, tab: TabId) => void;
+};
+/**
+ * Retain Office contents across body remounts within a Session.
+ * @returns the tab-content store declaration.
+ */
+export declare function createOfficeStore(): EngineStoreHandle<OfficeState, OfficeActions>;
+/** Store declaration used by the Office body. */
+export type OfficeStore = ReturnType<typeof createOfficeStore>;
+export {};
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1,10 @@
+/** Load the PDF renderer only after a PDF body is mounted. */
+import { type ReactNode } from 'react';
+import type { PdfBodyProps } from './pdf.tsx';
+/**
+ * Suspend while the package-local PDF chunk arrives.
+ * @param props - PDF body props supplied by the document slot.
+ * @returns the deferred PDF renderer.
+ */
+export declare function LazyPdfBody(props: PdfBodyProps): ReactNode;
+//# sourceMappingURL=LazyPdfBody.d.ts.map

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

@@ -0,0 +1,26 @@
+/** Build-owned, same-version PDF.js resources; all binary assets are decoded locally. */
+import workerSource from 'pdfjs-dist/build/pdf.worker.min.mjs?raw';
+export { workerSource };
+/** Resource kinds used by PDF.js 6's BinaryDataFactory requests. */
+export type PdfAssetKind = 'cMapUrl' | 'standardFontDataUrl' | 'wasmUrl';
+/** Original filenames mapped to base64, in the same PDF.js version as the worker. */
+export type PdfAssetMap = Readonly<Record<PdfAssetKind, Readonly<Record<string, string>>>>;
+declare global {
+    /** Inline artifact data supplied by the package-local build configuration. */
+    const __QILIN_PDFJS_ASSETS__: PdfAssetMap;
+}
+/** Public methods required by PDF.js's BinaryDataFactory option. */
+export interface PdfBinaryDataFactory {
+    /** @param request - PDF.js resource kind and exact filename. @returns independent transferable resource bytes. */
+    fetch(request: {
+        readonly kind: PdfAssetKind;
+        readonly filename: string;
+    }): Promise<Uint8Array>;
+}
+/**
+ * Capture this build's binary assets without network fallbacks.
+ * @param assets - build-inlined base64 resources, read only when a PDF is opened.
+ * @returns the constructor passed to PDF.js getDocument.
+ */
+export declare function createPdfBinaryDataFactory(assets?: PdfAssetMap): new () => PdfBinaryDataFactory;
+//# sourceMappingURL=assets.d.ts.map

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

@@ -0,0 +1,38 @@
+/** Canvas rendering with cancellation and page cleanup, shared by the PDF body and real-library smoke. */
+import type { PDFDocumentProxy, PDFPageProxy, PageViewport } from 'pdfjs-dist';
+/** The document operations used by one mounted PDF body. */
+export type PdfDocument = Pick<PDFDocumentProxy, 'numPages' | 'getPage'>;
+/** One in-flight PDF load and its complete cleanup operation. */
+export interface PdfSession {
+    readonly document: Promise<PdfDocument>;
+    /**
+     * Cancel loading and rendering, destroy the document, and release its worker.
+     * Library teardown failures are logged after native resources are released.
+     * @returns cleanup completion without rejection.
+     */
+    dispose(): Promise<void>;
+}
+/** Page geometry expressed in CSS pixels. */
+export interface PdfPageSize {
+    readonly width: number;
+    readonly height: number;
+}
+/** Optional DOM text rendering that shares the canvas page's cleanup barrier. */
+export type RenderPdfText = (page: PDFPageProxy, viewport: PageViewport) => {
+    readonly promise: Promise<void>;
+    cancel(): void;
+};
+/**
+ * Render one page into an exclusively owned canvas. Cancellation cannot write
+ * dimensions after a delayed getPage; active render tasks are cancelled and
+ * awaited before the page is cleaned up.
+ * @param document - loaded pdfjs document.
+ * @param pageNumber - 1-based selected page.
+ * @param canvas - canvas owned by this render only.
+ * @param signal - render lifetime.
+ * @param pixelRatio - device pixel ratio multiplied by the settled document zoom.
+ * @param renderText - optional selectable text layer sharing this page and viewport.
+ * @returns the page's CSS dimensions after rendering completes.
+ */
+export declare function renderPdfPage(document: PdfDocument, pageNumber: number, canvas: HTMLCanvasElement, signal: AbortSignal, pixelRatio: number, renderText?: RenderPdfText): Promise<PdfPageSize>;
+//# sourceMappingURL=document.d.ts.map

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

@@ -0,0 +1,8 @@
+/** Structured PDF worker failures; the renderer's locale owns visible explanations. */
+export declare class PdfWorkerFailure extends Error {
+    /** Distinguishes Worker startup/transport failures from document parsing errors. */
+    readonly kind = "worker";
+    /** @param cause - native error or messageerror event, retained for diagnostics. */
+    constructor(cause: Event);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1,27 @@
+/** Builtin PDF registration through document metadata and the keyed body slot. */
+import type { Context } from '@qilin-agent/kylin';
+import type { DocumentPreviewDefinition } from '../document/registry.ts';
+import type { PdfBodyInjected } from './pdf.tsx';
+import type { BoundActions } from '@qilin-agent/client-store';
+import type { SessionId } from '@qilin-agent/session/types';
+import { type PdfStore } from './store.ts';
+/** PDF metadata and keyed body share this package-local implementation identity. */
+export declare const PDF_BODY_ID = "@qilin-agent/client-ui-sidebar-documentpreview/pdf";
+/**
+ * Describe the builtin PDF renderer independently from its keyed body slot.
+ * @param title - locale-owned implementation name.
+ * @returns the complete-file PDF registration.
+ */
+export declare function pdfBodyDefinition(title: () => string): DocumentPreviewDefinition;
+/** @param ctx - context carrying the locale, document registry, and slot registry. */
+export declare function apply(ctx: Context): void;
+/**
+ * Retain PDF viewing state for a document entry's tab lifetime.
+ * @param ctx - owning registration context.
+ * @returns the store and injection shared by ordinary and Office PDF registrations.
+ */
+export declare function pdfBodyRegistration(ctx: Context): {
+    store: PdfStore;
+    inject: (sessionId: SessionId, actions: BoundActions<PdfStore>) => PdfBodyInjected;
+};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,45 @@
+/** Copy owned by the PDF renderer. */
+export declare const zh: {
+    title: string;
+    pageImage: string;
+    loading: string;
+    rendering: string;
+    failed: string;
+    password: string;
+    workerFailed: string;
+    unsupported: string;
+    retry: string;
+    zoomControls: "缩放控件";
+    zoomMenu: "选择缩放比例";
+    zoomOut: "缩小";
+    zoomIn: "放大";
+    zoomFitWidth: "适应宽度";
+    zoomValue: "{percent}%";
+};
+/** PDF translation keys shared by both dictionaries. */
+export type PdfLocaleKey = keyof typeof zh;
+/** English PDF-renderer dictionary. */
+export declare const en: {
+    title: string;
+    pageImage: string;
+    loading: string;
+    rendering: string;
+    failed: string;
+    password: string;
+    workerFailed: string;
+    unsupported: string;
+    retry: string;
+    zoomControls: string;
+    zoomMenu: string;
+    zoomOut: string;
+    zoomIn: string;
+    zoomFitWidth: string;
+    zoomValue: string;
+};
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** PDF page, loading, and failure messages. */
+        sidebarPdf: PdfLocaleKey;
+    }
+}
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1,29 @@
+/** PDF page presentation; binary content and tab information come from the document owner. */
+import { type ComponentType, type ReactNode } from 'react';
+import type { PropsLocale, PropsStore } from '@qilin-agent/client-ui-slots';
+import type { TabId } from '@qilin-agent/client-ui-dockkit';
+import type { DocumentPreviewProps } from '../document/contract.ts';
+import type { PdfStore } from './store.ts';
+import type { ZoomViewportProps } from '../zoom/ZoomViewport.tsx';
+/** A record's viewing preferences survive body unmounts and leave with the tab. */
+export interface PdfBodyInjected {
+    /**
+     * Retain viewing preferences until the tab record ends.
+     * @param tabId - owning tab.
+     * @param signal - tab-record lifetime, not body visibility.
+     */
+    readonly retainTab: (tabId: TabId, signal: AbortSignal) => void;
+    /** Main-bundle viewport reused by the lazy PDF body. */
+    readonly ZoomViewport: ComponentType<ZoomViewportProps>;
+    /** Main-bundle class implementing fit-width and fixed-size surfaces. */
+    readonly zoomSurfaceClass: string;
+}
+/** Standard document props plus the PDF entry's locale, viewing store, and lifetime callback. */
+export type PdfBodyProps = DocumentPreviewProps & PropsLocale<'sidebarPdf'> & PropsStore<PdfStore> & PdfBodyInjected;
+/**
+ * Present a PDF with tab-local viewing preferences and component-owned rendering resources.
+ * @param props - complete bytes and framework-owned tab/store/locale seats.
+ * @returns the PDF reader.
+ */
+export declare function PdfBody(props: PdfBodyProps): ReactNode;
+//# sourceMappingURL=pdf.d.ts.map

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

@@ -0,0 +1,14 @@
+import type { PdfSession } from './document.ts';
+import { PdfWorkerFailure } from './errors.ts';
+/**
+ * Open complete PDF bytes with an explicitly owned Worker. Startup failure
+ * never falls back to main-thread PDF parsing. Disposal keeps the Worker alive
+ * for PDF.js teardown, except after a fatal worker error, then terminates the
+ * native Worker and revokes its source URL.
+ * @param data - complete PDF bytes retained by the preview; the worker receives a copy.
+ * @param signal - document/body lifetime.
+ * @param reportFailure - reports a fatal Worker failure, including failures after document loading.
+ * @returns the pending document and idempotent asynchronous cleanup.
+ */
+export declare function openPdf(data: Uint8Array<ArrayBuffer>, signal: AbortSignal, reportFailure: (error: PdfWorkerFailure) => void): PdfSession;
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +1,27 @@
+/** Restorable PDF viewing preferences; document objects and canvases remain component-local. */
+import { type EngineStoreHandle } from '@qilin-agent/client-store';
+import type { TabId } from '@qilin-agent/client-ui-dockkit';
+import type { ZoomPreference } from '../zoom/types.ts';
+/** One tab's last visible page and optional PDF zoom preference. */
+export interface PdfView {
+    readonly page: number;
+    readonly zoom?: ZoomPreference;
+}
+/** Page state isolated by the owning tab record. */
+export interface PdfState {
+    byTab: Record<TabId, PdfView>;
+}
+type PdfActions = {
+    page: (draft: PdfState, tabId: TabId, page: number) => void;
+    zoom: (draft: PdfState, tabId: TabId, zoom: ZoomPreference) => void;
+    forget: (draft: PdfState, tabId: TabId) => void;
+};
+/**
+ * Declare the last visible page and zoom preference isolated by tab identity.
+ * @returns a store declaration instantiated by the document slot for each Session.
+ */
+export declare function createPdfStore(): EngineStoreHandle<PdfState, PdfActions>;
+/** Store declaration used by the PDF body registration. */
+export type PdfStore = ReturnType<typeof createPdfStore>;
+export {};
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1,10 @@
+/** PDF.js's viewer owns selection boundaries and copy normalization; the overlay follows its canvas. */
+import 'pdfjs-dist';
+import type { RenderPdfText } from './document.ts';
+/**
+ * Create a selectable overlay in a component-owned host.
+ * @param host - absolute overlay matching the displayed canvas dimensions.
+ * @returns renderer whose cancellation also releases its resize observer and DOM.
+ */
+export declare function pdfTextRenderer(host: HTMLDivElement): RenderPdfText;
+//# sourceMappingURL=text.d.ts.map

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

@@ -0,0 +1,77 @@
+/**
+ * The paged read this type performs, bound to the Client Remote.
+ *
+ * Content is the consumer's business: the `file` resource carries metadata only,
+ * and the text arrives here one page of lines at a time. The endpoint takes a
+ * session and a workspace path while a tab carries a `qilin-resource://file/`
+ * session address, so this module also owns that translation.
+ */
+import type { RemoteResult } from '@qilin-agent/api-remotes/client';
+import type { SessionId } from '@qilin-agent/session/types';
+import type { WorkspaceFileBytes, WorkspaceFileRange, WorkspaceFileText } from '@qilin-agent/api-workspace-files/types';
+/** The slice of the Client Remote this package calls. */
+export interface WorkspaceFilesReadRemote {
+    readonly workspaceFiles: {
+        /**
+         * Read one page of lines.
+         * @param sessionId - the session whose workspace resolves `path`.
+         * @param path - workspace path, absolute or relative to the workspace root.
+         * @param range - 1-based start line; the Host's page cap applies when `limit` is absent.
+         * @param signal - cancels the call.
+         * @returns the page, or the failure the Host declares.
+         */
+        read(sessionId: SessionId, path: string, range: WorkspaceFileRange, signal?: AbortSignal): Promise<RemoteResult<WorkspaceFileText>>;
+    };
+}
+/**
+ * The read one page performs, injected so the face stays host-free.
+ *
+ * The session travels with the call because the endpoint resolves the workspace
+ * root from it: the same path means different files in different sessions. A
+ * Remote call does not reject: the result carries the failure.
+ */
+export type ReadWorkspaceFilePage = (sessionId: SessionId, path: string, offset: number, signal: AbortSignal) => Promise<RemoteResult<WorkspaceFileText>>;
+/** The file one tab reads: the session the read runs under and the path handed to the Host. */
+export interface SessionFile {
+    /** The Session whose workspace resolves relative paths. */
+    readonly sessionId: SessionId;
+    /** The path the Host receives, absolute or relative to the addressed Session's workspace. */
+    readonly path: string;
+}
+/**
+ * The session and path one `qilin-resource://file/…` address names.
+ *
+ * A `session` address names its own session and a relative or absolute path, so
+ * a tab addressed into another session reads from that session. An `absolute`
+ * address carries no session and cannot be read here. The registry routes only
+ * session-scoped `file` addresses to this type, so an address `parseFileAddress`
+ * rejects or that carries no session is a programming error and throws.
+ * @param address - a tab's `qilin-resource://file/…` address.
+ * @returns the session and the path to hand the endpoint.
+ */
+export declare function hostFileOf(address: string): SessionFile;
+/**
+ * Bind the paged read to one Remote face. The page length is the Host's
+ * configured cap, so no `limit` travels.
+ * @param remote - the Client Remote carrying the `workspaceFiles` namespace.
+ * @returns the read the face performs.
+ */
+export declare function createReadPage(remote: WorkspaceFilesReadRemote): ReadWorkspaceFilePage;
+/** Complete document bytes borrowed read-only by renderers; copy before transferring to a Worker. */
+export type DocumentFileBytes = Omit<WorkspaceFileBytes, 'data'> & {
+    readonly data: Uint8Array<ArrayBuffer>;
+};
+/**
+ * Read a complete file through the Host endpoint.
+ * @param file - Session and path decoded from the tab address.
+ * @param signal - owning tab lifetime.
+ * @returns complete binary bytes, including declared failures.
+ */
+export type ReadDocumentBytes = (file: SessionFile, signal: AbortSignal) => Promise<RemoteResult<DocumentFileBytes>>;
+/**
+ * Decode one successful Remote byte result for document renderers.
+ * @param file - Host byte result with base64 data.
+ * @returns the same metadata with native bytes; malformed base64 throws.
+ */
+export declare function documentFileBytes(file: WorkspaceFileBytes): DocumentFileBytes;
+//# sourceMappingURL=rpc.d.ts.map

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

@@ -0,0 +1,53 @@
+/**
+ * The text a viewer selection contributes to the conversation draft.
+ * Everything here is string math — no React, no ctx — so the unit tests cover
+ * it directly.
+ *
+ * Insert shape:
+ * - Selection of at most {@link SELECTION_LIMIT} characters: a fenced block
+ *   whose info line is the viewer's path with the selected line span, and
+ *   whose body is the selected text.
+ * - Longer selection: the info line alone, because an empty fence in the draft
+ *   costs a keystroke to delete and says nothing the line does not.
+ * - The path is the tab address's own path, which is already the
+ *   workspace-relative spelling when the file is inside the Session workspace.
+ * - A single-line selection writes `path:12`; a multi-line one writes
+ *   `path:12-15`. The rendered preview cannot map its DOM back to source
+ *   lines, so the lines come from {@link linesOfSelection} — a best-effort
+ *   reverse search that reports nothing on an ambiguous or missing hit.
+ */
+/** Longest selected text inserted with its content, in UTF-16 code units. */
+export declare const SELECTION_LIMIT = 500;
+/** The source line span one selection maps to, 1-based and inclusive. */
+export interface SelectionLines {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * The fenced block's info line: the viewer's path, followed by the line or
+ * line range when the selection mapped to source lines.
+ * @param path - the path the viewer opened.
+ * @param lines - the mapped source span, absent when the lookup reported none.
+ * @returns `rel`, `rel:12`, or `rel:12-15`.
+ */
+export declare function headerOf(path: string, lines?: SelectionLines): string;
+/**
+ * The text one selection appends to the composer draft.
+ * @param path - the path the viewer opened.
+ * @param lines - the mapped source span, absent when the lookup reported none.
+ * @param selected - the selected text as the DOM reported it.
+ * @returns the fenced block, or the info line alone for an oversized selection.
+ */
+export declare function buildSelectionInsert(path: string, lines: SelectionLines | undefined, selected: string): string;
+/**
+ * Reverse-map a rendered selection back to source lines. The preview's
+ * selection is plain text with block boundaries flattened to `\n`, so one
+ * trailing newline is stripped first and the rest is a substring search: only
+ * an exactly-once occurrence yields lines, because the reported ones must not
+ * point a reader at the wrong place.
+ * @param source - the file's text as the viewer read it.
+ * @param selected - the selected text as the DOM reported it.
+ * @returns the mapped span, or null when the hit is ambiguous or missing.
+ */
+export declare function linesOfSelection(source: string, selected: string): SelectionLines | null;
+//# sourceMappingURL=selection-payload.d.ts.map