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

package/lib/index.js

@@ -0,0 +1,35 @@
+import z from "@qilin-agent/schemastery";
+//#region lib/types/config.js
+/** Cache limits shared by the Host configuration and browser document previews. */
+/** Deployment limits applied before Office preview registration. */
+const Config = z.object({
+	office: z.object({
+		maxCachedEntries: z.natural().min(1).max(Number.MAX_SAFE_INTEGER).default(8),
+		maxCachedBytes: z.natural().min(1).max(Number.MAX_SAFE_INTEGER).default(64 * 1024 * 1024),
+		maxPending: z.natural().min(1).max(Number.MAX_SAFE_INTEGER).default(8),
+		maxReaders: z.natural().min(1).max(Number.MAX_SAFE_INTEGER).default(32)
+	}),
+	excel: z.object({
+		maxBytes: z.natural().min(1).max(Number.MAX_SAFE_INTEGER).default(16 * 1024 * 1024),
+		maxCells: z.natural().min(1).max(Number.MAX_SAFE_INTEGER).default(25e4),
+		timeoutMs: z.natural().min(1).max(2147483647).default(15e3)
+	})
+});
+//#endregion
+//#region lib/types/index.js
+/**
+* Embed validated preview settings in browser pages.
+* @param ctx - Host context serving browser pages.
+* @param config - Cache limits adopted when the page loads.
+*/
+function apply(ctx, config) {
+	ctx.on("webserver/index-inject", (table) => {
+		table.push({
+			kind: "global",
+			name: "__QILIN_DOCUMENT_PREVIEW_CONFIG__",
+			value: config
+		});
+	});
+}
+//#endregion
+export { Config, apply };

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

@@ -0,0 +1,12 @@
+/** Shared indeterminate loading feedback for document reads and rendering. */
+import type { ReactNode } from 'react';
+/**
+ * @param props - localized status label, carried as the accessible name with
+ * no visible text, and optional placement style.
+ * @returns an animated, accessible loading status.
+ */
+export declare function LoadingIndicator({ label, className }: {
+    label: string;
+    className?: string | undefined;
+}): ReactNode;
+//# sourceMappingURL=LoadingIndicator.d.ts.map

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

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+import type { ObservableSnapshot } from '@qilin-agent/client-store';
+import type { InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore } from '@qilin-agent/client-ui-slots';
+import type { TextInjected } from './face.ts';
+import type { TextStore } from './store.ts';
+import type { DocumentPreviewDefinition } from './document/registry.ts';
+export { linesOf, loadedPages, lastLineLoaded, scrollToLine } from './text/lines.ts';
+export type { LoadedPage } from './text/lines.ts';
+/** Private registration inputs; the framework binds the registry source to useDocumentPreviews. */
+export interface TextPreviewInjected extends TextInjected {
+    readonly hooks: {
+        readonly documentPreviews: ObservableSnapshot<readonly DocumentPreviewDefinition[]>;
+    };
+    /**
+     * Append one viewer selection to this tab's Session composer draft.
+     * @param text - the fenced selection block.
+     * @returns whether the Session's input applied it.
+     */
+    readonly insertSelection: (text: string) => boolean;
+}
+/** The body's composed props: the tab, its navigation, the shared store and face, and copy. */
+export type TextPreviewProps = PropsRuntime<'sidebar.right.pane.tab'> & PropsRenderSlots<'sidebar.right.tab.document' | 'sidebar.right.tab.document.action' | 'sidebar.right.tab.document.actions' | 'sidebar.right.tab.document.unpreviewable'> & PropsStore<TextStore> & InjectFace<TextPreviewInjected> & PropsLocale<'sidebarDocumentPreview'>;
+/**
+ * The text type's body, registered under `sidebar.right.pane.tab` as `text`.
+ * @param props - composed slot props.
+ * @returns the content read so far with its controls, or a progress line.
+ */
+export declare function TextPreview({ useTabInfo, useResource, useStore, actions, loadPage, reloadPages, loadAll, reloadAll, prepareRenderer, useDocumentPreviews, renderSlot, t, addResource, setResources, insertSelection, }: TextPreviewProps): ReactNode;
+//# sourceMappingURL=TextPreview.d.ts.map

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

@@ -0,0 +1,14 @@
+/**
+ * The text type's chip title: the file type's coloured sheet before the name
+ * the registry captured at open time. Registered under
+ * `sidebar.right.pane.tab.title`; without it the chip would show the bare name.
+ */
+import type { ReactNode } from 'react';
+import type { PropsRuntime } from '@qilin-agent/client-ui-slots';
+/**
+ * The title as the chip and a floating panel's header show it.
+ * @param props - the tab information hook.
+ * @returns the type's 16px sheet followed by the tab's title text.
+ */
+export declare function TextTitle({ useTabInfo }: PropsRuntime<'sidebar.right.pane.tab.title'>): ReactNode;
+//# sourceMappingURL=TextTitle.d.ts.map

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

@@ -0,0 +1,9 @@
+/** Incrementally highlighted source; the document owner supplies the accumulated text and wrap preference. */
+import type { ReactNode } from 'react';
+import type { PropsLocale } from '@qilin-agent/client-ui-slots';
+import type { DocumentPreviewProps } from '../document/contract.ts';
+/** Document owner props and this renderer's localized controls. */
+export type CodeBodyProps = DocumentPreviewProps & PropsLocale<'sidebarCodePreview'>;
+/** @param props - accumulated document contents and framework props. @returns one stable CodeBlock, or no body for byte contents. */
+export declare function CodeBody({ resourceAddress, content, wrap, scrollportRef, t }: CodeBodyProps): ReactNode;
+//# sourceMappingURL=CodeBody.d.ts.map

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

@@ -0,0 +1,5 @@
+/** Code preview metadata and body registered through the public document extension points. */
+import type { Context } from '@qilin-agent/kylin';
+/** @param ctx - owning plugin context. Register localized metadata and the matching keyed document body. */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,9 @@
+/** Recognized suffixes shared by renderer selection and language hints. */
+export declare const CODE_EXTENSIONS: readonly string[];
+/**
+ * Select the shared highlighter's grammar for a filename.
+ * @param path - decoded source filename or path.
+ * @returns a supported grammar hint, or undefined for other suffixes.
+ */
+export declare function languageForPath(path: string): string | undefined;
+//# sourceMappingURL=languages.d.ts.map

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

@@ -0,0 +1,19 @@
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Code document implementation name and copy controls. */
+        sidebarCodePreview: keyof typeof zh;
+    }
+}
+/** Simplified Chinese dictionary and key source. */
+export declare const zh: {
+    title: string;
+    copy: string;
+    copied: string;
+};
+/** English dictionary with the same keys. */
+export declare const en: {
+    title: string;
+    copy: string;
+    copied: string;
+};
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1,37 @@
+/**
+ * Stage one of this package's registration: what the `text` tab type IS.
+ *
+ * The type claims every `qilin-resource://file/session/<sessionId>/<path>`
+ * address at the `fallback` band: it
+ * is the plain viewer that any more specific type for the same address should
+ * beat, the position VS Code's text editor holds among its editors. `canOpen`
+ * refuses an address `parseFileAddress` rejects or that has no Session at claim time, where an
+ * unclaimed address is the documented wiring error.
+ */
+import type { SidebarRightTabDefinition } from '@qilin-agent/client-ui-sidebar-right/client';
+import type { TranslateNS } from '@qilin-agent/client-locale/client';
+/** The tab kind this package owns. */
+export declare const TEXTPREVIEW_KIND = "text";
+/** This implementation's identity in the tab system: the key its body registers under. */
+export declare const TEXTPREVIEW_ID = "@qilin-agent/client-ui-sidebar-documentpreview";
+/**
+ * The tab title for one `file:` address: its decoded basename.
+ *
+ * The whole address stays the content identity, so two files with one name in
+ * different directories are two tabs; only the chip text is shortened. Decoding
+ * is per segment, matching how the address was built, so a name carrying `#`,
+ * `?`, or a space reads as itself.
+ * @param address - a `file:`-shaped address.
+ * @returns the decoded last path segment, or the address itself when it has none.
+ */
+export declare function basenameOf(address: string): string;
+/**
+ * The text type's registry definition.
+ *
+ * `title` names the open file, so the type cannot take its own name from it:
+ * the enable switch reads `label`.
+ * @param t - namespace-bound translate, read fresh on every label call.
+ * @returns the definition to register.
+ */
+export declare function textDefinition(t: TranslateNS<'sidebarDocumentPreview'>): SidebarRightTabDefinition;
+//# sourceMappingURL=definition.d.ts.map

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

@@ -0,0 +1,111 @@
+/** Document renderer slot: the owner supplies shared file state, renderers own their presentation. */
+import type { PropsRuntime, SlotHookFactory } from '@qilin-agent/client-ui-slots';
+import type { UseSidebarRightTabInfo } from '@qilin-agent/client-ui-sidebar-right/client';
+import type { RefCallback } from 'react';
+/** One loaded text window, retaining source line positions. */
+export interface DocumentTextPage {
+    readonly offset: number;
+    readonly text: string;
+    readonly lines: number;
+}
+/**
+ * Ordinary file contents, or a request for the selected renderer to load its content.
+ * Byte arrays are transient UI input, never persisted layout or Session data.
+ */
+export type DocumentContent = {
+    readonly kind: 'text';
+    readonly text: string;
+    readonly pages: readonly DocumentTextPage[];
+    readonly eof: boolean;
+} | {
+    readonly kind: 'bytes';
+    readonly data: Uint8Array<ArrayBuffer>;
+} | {
+    readonly kind: 'renderer';
+    /** Changes on reload or implementation replacement; retained contents belong to one revision. */
+    readonly revision: number;
+    /** Report the displayed source version; stale revisions cannot update the owner. @param version - loaded source version. */
+    readonly loaded: (version: string) => void;
+    /** End a failed load; a later file change can start another revision. */
+    readonly failed: () => void;
+    /** Cancel the current load and start a new revision. */
+    readonly reload: () => void;
+};
+/** Content and viewing inputs shared by document bodies and nested PDF presentation. */
+export interface DocumentBodyOwner {
+    /** Observe a file read by this renderer. @param address - complete file resource address. */
+    readonly addResource: (address: string) => void;
+    /** Replace this renderer's dependencies. @param addresses - complete file resource addresses. */
+    readonly setResources: (addresses: readonly string[]) => void;
+    /** Original file address, also readable through the standard useResource hook. */
+    readonly resourceAddress: string;
+    /** Ordinary file content or a renderer-owned loading request; text accumulates until eof. */
+    readonly content: DocumentContent;
+    /** The document toolbar's current wrapping preference. */
+    readonly wrap: boolean;
+    /** Report a renderer-owned scrollport; passing `null` restores the shared body as the owner. */
+    readonly scrollportRef: RefCallback<HTMLElement>;
+}
+declare module '@qilin-agent/client-ui-slots' {
+    interface SlotMap {
+        /** Document body selected by a registered implementation id. */
+        'sidebar.right.tab.document': {
+            kind: 'keyed';
+            scope: 'session';
+            owner: DocumentBodyOwner;
+            hookContext: UseSidebarRightTabInfo;
+            inject: {
+                hooks: {
+                    tabInfo: SlotHookFactory<'sidebar.right.tab.document', UseSidebarRightTabInfo>;
+                };
+            };
+        };
+        /**
+         * Header toolbar contributions acting on the previewed file, rendered
+         * after the preview's own controls once the file's Host path is known.
+         */
+        'sidebar.right.tab.document.actions': {
+            kind: 'list';
+            scope: 'session';
+            owner: DocumentFileOwner;
+        };
+        /**
+         * Empty-state contributions for a file this preview cannot render,
+         * rendered under the unsupported notice once the file's Host path is known.
+         */
+        'sidebar.right.tab.document.unpreviewable': {
+            kind: 'list';
+            scope: 'session';
+            owner: DocumentFileOwner;
+        };
+        /** Renderer-specific controls before the document toolbar's reload button. */
+        'sidebar.right.tab.document.action': {
+            kind: 'keyed';
+            scope: 'session';
+            owner: {
+                readonly content: DocumentContent;
+            };
+            hookContext: UseSidebarRightTabInfo;
+            inject: {
+                hooks: {
+                    tabInfo: SlotHookFactory<'sidebar.right.tab.document', UseSidebarRightTabInfo>;
+                };
+            };
+        };
+    }
+}
+/** The previewed file's Host identity, supplied to file-acting contributions. */
+export interface DocumentFileOwner {
+    /** Absolute path in the file's execution environment; native actions must verify a Host mapping. */
+    readonly absolutePath: string;
+}
+/** Standard input for every document body; entry-local stores and locale props can be intersected with it. */
+export type DocumentPreviewProps = PropsRuntime<'sidebar.right.tab.document'>;
+/**
+ * Forward the framework's tab reader to the selected document body.
+ * @param _standard - framework standard props.
+ * @param useTabInfo - enclosing tab's bound reader.
+ * @returns the same reader, without another subscription adapter.
+ */
+export declare const documentTabInfoFactory: SlotHookFactory<'sidebar.right.tab.document', UseSidebarRightTabInfo>;
+//# sourceMappingURL=contract.d.ts.map

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

@@ -0,0 +1,70 @@
+/** Shared text or byte reads, or content loading owned by the renderer. */
+export type DocumentLoadMode = 'text-pages' | 'bytes-complete' | 'renderer';
+/** One renderer implementation, independent of its component registration. */
+export interface DocumentPreviewDefinition {
+    /** Unique implementation name, also used as the document slot key. */
+    readonly id: string;
+    /** File suffixes without a leading dot; compound suffixes such as tar.gz are accepted. */
+    readonly extensions: readonly string[];
+    /**
+     * Suffixes among `extensions` whose bytes are not readable text; a file
+     * matching one loses the plain-text fallback among its viewer choices.
+     * Every entry must appear in `extensions`; `register` rejects strays.
+     */
+    readonly binaryExtensions?: readonly string[];
+    /** External implementations win over product implementations; defaults to extension. */
+    readonly priority?: 'builtin' | 'extension';
+    /** Localized implementation label, evaluated when the toolbar renders. @returns the visible name. */
+    readonly title: () => string;
+    /** Content delivery mode supplied by the document owner. */
+    readonly loading: DocumentLoadMode;
+    /** Whether the implementation consumes the document's wrap preference. */
+    readonly wrap?: boolean;
+}
+/**
+ * Rank an observed definition snapshot without consulting mutable service state.
+ * @param definitions - registered implementations in registration order.
+ * @param path - decoded filename or file path.
+ * @returns matching implementations, external band first, then longest suffix.
+ */
+export declare function matchingDocumentPreviews(definitions: readonly DocumentPreviewDefinition[], path: string): readonly DocumentPreviewDefinition[];
+/**
+ * Whether any registered implementation declares the filename's suffix binary.
+ * @param definitions - registered implementations.
+ * @param path - decoded filename or file path.
+ * @returns true when a declared binary suffix matches the filename.
+ */
+export declare function binaryDocumentPath(definitions: readonly DocumentPreviewDefinition[], path: string): boolean;
+/** Observable registry of all live implementations, including lower-priority alternatives. */
+export declare class DocumentPreviewRegistry {
+    private readonly registered;
+    private readonly listeners;
+    private snapshot;
+    /**
+     * Read the current registrations.
+     * @returns the same snapshot until a registration changes.
+     */
+    readonly getSnapshot: () => readonly DocumentPreviewDefinition[];
+    /**
+     * Observe registration changes.
+     * @param listener - registration-change observer.
+     * @returns its disposer.
+     */
+    readonly subscribe: (listener: () => void) => (() => void);
+    /**
+     * Register metadata separately from the matching keyed slot component.
+     * @param definition - unique implementation and recognized suffixes; every
+     * `binaryExtensions` entry must appear in `extensions`.
+     * @returns an idempotent disposer; duplicate live implementation names and
+     * binary suffixes outside `extensions` throw.
+     */
+    register(definition: DocumentPreviewDefinition): () => void;
+    /**
+     * List every matching implementation in automatic-selection order.
+     * @param path - decoded file path; matching never resolves filesystem access.
+     * @returns extension band first, then longest suffix, then registration order.
+     */
+    candidates(path: string): readonly DocumentPreviewDefinition[];
+    private publish;
+}
+//# sourceMappingURL=registry.d.ts.map

package/lib/types/client/document/resource-group.d.ts

@@ -0,0 +1,23 @@
+/** File-resource membership and invalidation for one document preview. */
+import type { Resources } from '@qilin-agent/client-resources/client';
+/** Forwards member metadata changes to one document preview. */
+export declare class ResourceGroup {
+    private readonly resources;
+    private readonly changed;
+    private readonly members;
+    /** @param resources - shared file sources. @param changed - marks the owning preview stale. */
+    constructor(resources: Resources, changed: () => void);
+    /**
+     * Subscribe once; initial metadata establishes the baseline for later changes.
+     * @param address - complete resource address.
+     */
+    add(address: string): void;
+    /**
+     * Release dependencies absent from the current document.
+     * @param addresses - complete membership of the latest document load.
+     */
+    set(addresses: readonly string[]): void;
+    /** Release every member when the preview tab ends. */
+    close(): void;
+}
+//# sourceMappingURL=resource-group.d.ts.map

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

@@ -0,0 +1,24 @@
+/**
+ * Filename suffix matching shared by the preview registry and the owner's
+ * unviewable list, so every consumer normalizes paths and suffixes alike.
+ */
+/**
+ * Normalize one declared suffix for comparison.
+ * @param extension - declared file suffix, with or without a leading dot.
+ * @returns the suffix lowercased with any leading dot dropped.
+ */
+export declare function normalizeSuffix(extension: string): string;
+/**
+ * The filename a path's suffixes are matched against.
+ * @param path - decoded filename or file path; `\` is accepted as a separator.
+ * @returns the lowercased final path segment.
+ */
+export declare function documentFileName(path: string): string;
+/**
+ * The longest declared suffix ending the filename.
+ * @param name - lowercased filename from {@link documentFileName}.
+ * @param extensions - declared suffixes; compound suffixes such as `tar.gz` are accepted.
+ * @returns the matched suffix's normalized length, or 0 when none matches.
+ */
+export declare function matchedSuffixLength(name: string, extensions: readonly string[]): number;
+//# sourceMappingURL=suffix.d.ts.map

package/lib/types/client/document/tab-lifetime.d.ts

@@ -0,0 +1,10 @@
+/** Document view state belongs to tab records, including while their bodies are hidden. */
+import type { Context } from '@qilin-agent/kylin';
+import type { TabId } from '@qilin-agent/client-ui-dockkit';
+/**
+ * Release retained view state on tab closure or plugin disposal.
+ * @param ctx - owning preview plugin context.
+ * @returns a callback accepting the tab, its lifetime signal, and its store's forget action; repeated holds share one listener.
+ */
+export declare function retainDocumentTabs(ctx: Context): (tabId: TabId, signal: AbortSignal, forget: (tabId: TabId) => void) => void;
+//# sourceMappingURL=tab-lifetime.d.ts.map

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

@@ -0,0 +1,7 @@
+/**
+ * Whether a filename's suffix is a known binary container that no renderer claims.
+ * @param path - decoded filename or file path.
+ * @returns true when the suffix belongs to the unviewable binary list.
+ */
+export declare function unviewableBinaryPath(path: string): boolean;
+//# sourceMappingURL=unviewable.d.ts.map

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

@@ -0,0 +1,22 @@
+/** Load the spreadsheet renderer only when a supported workbook is opened. */
+import { type ReactNode } from 'react';
+import type { PropsLocale } from '@qilin-agent/client-ui-slots';
+import type { DocumentPreviewProps } from '../document/contract.ts';
+import { type ExcelFormat } from './format.ts';
+import type { ExcelLimits } from './model.ts';
+/** Document input plus parser limits and localized copy. */
+export type ExcelBodyProps = DocumentPreviewProps & PropsLocale<'sidebarExcel'> & {
+    readonly limits: ExcelLimits;
+};
+/** Lazily loaded renderer input with the parser choice and main-bundle loading content. */
+export type LoadedExcelBodyProps = ExcelBodyProps & {
+    readonly format: ExcelFormat;
+    readonly loading: ReactNode;
+};
+/**
+ * Load the browser spreadsheet renderer for every registered format.
+ * @param props - Complete file bytes and standard document seats.
+ * @returns Localized loading state or Excel preview.
+ */
+export declare function LazyExcelBody(props: ExcelBodyProps): ReactNode;
+//# sourceMappingURL=LazyExcelBody.d.ts.map

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

@@ -0,0 +1,12 @@
+/** Format-specific parsing into one read-only FortuneSheet representation. */
+import type { ExcelFormat } from './format.ts';
+import type { ExcelLimits, ExcelPreview } from './model.ts';
+/**
+ * Decode spreadsheet bytes without recalculating saved formulas.
+ * @param bytes - Borrowed complete file bytes.
+ * @param format - Format selected by the registered filename suffix.
+ * @param limits - File and matrix allocation limits.
+ * @returns Display sheets and missing formula-cache count.
+ */
+export declare function convertExcel(bytes: Uint8Array<ArrayBuffer>, format: ExcelFormat, limits: ExcelLimits): Promise<ExcelPreview>;
+//# sourceMappingURL=convert.d.ts.map

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

@@ -0,0 +1,10 @@
+import { type ExcelLimits, type ExcelPreview } from './model.ts';
+/**
+ * Parse delimited UTF-8 or BOM-marked UTF-16 without type inference.
+ * @param bytes - Borrowed complete file bytes.
+ * @param format - Comma or tab-separated input.
+ * @param limits - Maximum worksheet area.
+ * @returns A single sheet with literal field values.
+ */
+export declare function convertDelimited(bytes: Uint8Array<ArrayBuffer>, format: 'csv' | 'tsv', limits: ExcelLimits): ExcelPreview;
+//# sourceMappingURL=delimited.d.ts.map

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

@@ -0,0 +1,7 @@
+/** Locale-independent spreadsheet parser failure categories. */
+export declare class ExcelPreviewError extends Error {
+    readonly code: 'invalid' | 'tooLarge' | 'timeout' | 'encoding';
+    /** @param code - User-actionable parser failure. */
+    constructor(code: 'invalid' | 'tooLarge' | 'timeout' | 'encoding', options?: ErrorOptions);
+}
+//# sourceMappingURL=error.d.ts.map

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

@@ -0,0 +1,11 @@
+/** Read-only spreadsheet surface backed by browser-parsed workbook data. */
+import { type ReactNode } from 'react';
+import type { LoadedExcelBodyProps } from './LazyExcelBody.tsx';
+/**
+ * Display stored spreadsheet values and formats without editing or recalculation.
+ * Keep the mounted workbook sized to its preview pane.
+ * @param props - Complete workbook bytes, limits, and locale.
+ * @returns An isolated spreadsheet surface with cancellable loading.
+ */
+export declare function ExcelBody({ content, format, limits, t, loading }: LoadedExcelBodyProps): ReactNode;
+//# sourceMappingURL=excel.d.ts.map

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

@@ -0,0 +1,9 @@
+/** File formats admitted by the spreadsheet preview. */
+export type ExcelFormat = 'xlsx' | 'xls' | 'csv' | 'tsv';
+/**
+ * Resolve a registered filename to its parser.
+ * @param path - Decoded file path.
+ * @returns The supported suffix; rejects unsupported filenames.
+ */
+export declare function excelFormat(path: string): ExcelFormat;
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1,10 @@
+/** Excel previews use ordinary authorized file bytes without Office conversion. */
+import type { Context } from '@qilin-agent/kylin';
+import type { Config } from '../../config.ts';
+/**
+ * Register the browser Excel viewer and its lifecycle-owned slot.
+ * @param ctx - Preview and locale registries.
+ * @param limits - Resolved parser limits.
+ */
+export declare function apply(ctx: Context, limits: Config['excel']): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,45 @@
+/** Locale-owned Excel preview controls and parser feedback. */
+export declare const zh: {
+    title: string;
+    language: string;
+    loading: string;
+    invalid: string;
+    tooLarge: string;
+    timeout: string;
+    encoding: string;
+    formulaWarning: string;
+    unsupportedNotice: string;
+    charts: string;
+    images: string;
+    shapes: string;
+    conditionalFormatting: string;
+    featureSeparator: string;
+    retry: string;
+};
+/** Excel preview dictionary keys. */
+export type ExcelPreviewKey = keyof typeof zh;
+/** English Excel preview copy. */
+export declare const en: {
+    title: string;
+    language: string;
+    loading: string;
+    invalid: string;
+    tooLarge: string;
+    timeout: string;
+    encoding: string;
+    formulaWarning: string;
+    unsupportedNotice: string;
+    charts: string;
+    images: string;
+    shapes: string;
+    conditionalFormatting: string;
+    featureSeparator: string;
+    retry: string;
+};
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Excel preview status and third-party locale selection. */
+        sidebarExcel: ExcelPreviewKey;
+    }
+}
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1,35 @@
+/** Shared display cells, resource limits, and parser failure categories. */
+import { type Cell, type Sheet, type SheetConfig } from '@fortune-sheet/core';
+/** Resource limits applied before allocating FortuneSheet's dense cell matrices. */
+export interface ExcelLimits {
+    /** Maximum source file bytes. */
+    maxBytes: number;
+    /** Maximum combined rectangular cell area across worksheets. */
+    maxCells: number;
+    /** Maximum time allowed for one parser Worker. */
+    timeoutMs: number;
+}
+/** Content categories reported in stable order when XLSX preview omits them. */
+export declare const EXCEL_UNSUPPORTED_FEATURES: readonly ["charts", "images", "shapes", "conditionalFormatting"];
+/** A detected workbook feature that the spreadsheet preview does not display. */
+export type ExcelUnsupportedFeature = typeof EXCEL_UNSUPPORTED_FEATURES[number];
+/** Preview data, missing formula results, and detected content that is not displayed. */
+export interface ExcelPreview {
+    sheets: Sheet[];
+    missingResults: number;
+    unsupportedFeatures: ExcelUnsupportedFeature[];
+}
+/**
+ * Retain an addressable A1 selection, including an A1 merge.
+ * @param config - Worksheet layout.
+ * @returns The initial selection used when activating a worksheet.
+ */
+export declare function initialSelection(config: SheetConfig): NonNullable<Sheet['luckysheet_select_save']>;
+/**
+ * Apply number formatting and default alignment without evaluating formulas.
+ * @param cell - Owned display cell to complete.
+ * @param numberFormat - Excel number format code.
+ * @returns The same cell with its display text and value type.
+ */
+export declare function formatCell(cell: Cell, numberFormat: string): Cell;
+//# sourceMappingURL=model.d.ts.map

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

@@ -0,0 +1,12 @@
+import type { ExcelFormat } from './format.ts';
+import { type ExcelLimits, type ExcelPreview } from './model.ts';
+/**
+ * Parse workbook bytes in a disposable Worker, copying the retained preview buffer.
+ * @param bytes - Borrowed complete file bytes.
+ * @param format - Format selected by the registered filename suffix.
+ * @param limits - File, matrix, and elapsed-time limits.
+ * @param signal - Document body's lifetime.
+ * @returns Parsed sheets; rejects with a locale key on parser failures.
+ */
+export declare function parseExcel(bytes: Uint8Array<ArrayBuffer>, format: ExcelFormat, limits: ExcelLimits, signal: AbortSignal): Promise<ExcelPreview>;
+//# sourceMappingURL=parse.d.ts.map

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker.d.ts.map

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

@@ -0,0 +1,18 @@
+/** Legacy BIFF workbooks mapped to saved values and basic spreadsheet layout. */
+import { type WorkBook } from 'xlsx';
+import { type ExcelLimits, type ExcelPreview } from './model.ts';
+/**
+ * Decode a binary XLS workbook without accepting renamed text or HTML files.
+ * @param bytes - Borrowed complete workbook bytes.
+ * @param limits - Maximum combined worksheet area.
+ * @returns Saved values, formulas, and supported workbook layout.
+ */
+export declare function convertXls(bytes: Uint8Array<ArrayBuffer>, limits: ExcelLimits): ExcelPreview;
+/**
+ * Map SheetJS values and optional BIFF layout metadata without retaining the workbook.
+ * @param workbook - Parsed legacy workbook.
+ * @param limits - Maximum combined worksheet area.
+ * @returns FortuneSheet display data.
+ */
+export declare function mapXlsWorkbook(workbook: WorkBook, limits: ExcelLimits): ExcelPreview;
+//# sourceMappingURL=xls.d.ts.map