dsh-plugin-core 0.31.0 → 0.33.0

package/dist/adv/explorer/preview/TextPreview.js

@@ -0,0 +1,122 @@
+// 文本 / markdown / 代码预览体。
+//
+//  - md 且非源码态 ⇒ 官方 MarkdownText（mdast 管线 + KaTeX）；
+//  - 其余（源码态 / 代码 / 纯文本）⇒ 官方 CodeBlock（Shiki，零 npm 依赖；
+//    大文件拖宽卡顿问题若真出现再议，不为此引 CodeMirror 全家桶进共享底座）；
+//  - read 分页累积，`!eof` 出「加载更多」；传了 maxBytes（HTML 源码态）则按字节截断、
+//    不出按钮、顶部出横幅。
+//
+// ⚠️ read 的第三个参数（range）口径：**首页 `{}`、翻页 `{offset}`，绝不带 `limit`**。
+//   远端对 range 按值校验，多塞 limit 会被拒（表现 = 每种文件都「加载失败」）；
+//   兄弟项目 dsh-task-dispatch-table 与本仓文档（types.ts / dsh-host.md / features/explorer.md）
+//   同为 `{}` + `{offset}` 两态，分页步长由远端定，不在这里猜。
+import { createElement as h, useCallback, useEffect, useRef, useState } from 'react';
+import { MarkdownText } from '../../../ui/official.js';
+import { CodeViewer } from '../../../ui/display/CodeViewer.js';
+import { Button } from '../../../ui/actions/Button.js';
+import { t } from '../../../utils/i18n.js';
+import { errView, isAborted, textPageOf } from '../types.js';
+import { formatBytes } from '../../../utils/number.js';
+import { markdownLabels } from './md-labels.js';
+import { ensureComponentStyles } from '../../../ui/infra/css.js';
+import { EXPLORER_CSS } from '../explorer-css.js';
+/** 定位到行时最多自动续翻的页数（远处行号不值得为它打一整圈往返；用户仍可手动「加载更多」）。 */
+const FOCUS_MAX_PAGES = 10;
+export function TextPreview(props) {
+    ensureComponentStyles('explorer', EXPLORER_CSS);
+    const tt = props.translate ?? t;
+    const [text, setText] = useState('');
+    const [truncated, setTruncated] = useState(false);
+    const [nextOffset, setNextOffset] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [failed, setFailed] = useState(null);
+    // 累计文本放 ref：翻页/截断判定要读「这一页加上之后的全文」，闭包 state 会是旧值。
+    const accRef = useRef('');
+    // 当前这一次读（含翻页）：新的一次开始 / 换文件 / 卸载都先 abort 上一次，迟到的结果不落状态。
+    const abortRef = useRef(null);
+    const load = useCallback(async (offset, append) => {
+        abortRef.current?.abort();
+        const controller = new AbortController();
+        abortRef.current = controller;
+        setLoading(true);
+        try {
+            // range 只两态：首页 `{}`、翻页 `{offset}`（见文件头口径说明）。
+            const parsed = textPageOf(await props.files.read(props.path, offset > 0 ? { offset } : {}, controller.signal));
+            if (controller.signal.aborted)
+                return null;
+            if (parsed === null) {
+                // 形状不对要说「返回数据不符合预期」，不能混进「加载失败」——混了就永远查不出是谁的锅。
+                console.warn('[dsh-plugin-core:explorer] read 返回体无法解析为文本页', props.path);
+                setFailed({ key: 'previewBadPayload' });
+                return null;
+            }
+            if ('failed' in parsed) {
+                setFailed(errView(parsed.failed));
+                return null;
+            }
+            setFailed(null);
+            const full = append ? accRef.current + parsed.text : parsed.text;
+            accRef.current = full;
+            setText(full);
+            const next = parsed.eof ? null : parsed.offset + parsed.lines;
+            if (props.maxBytes !== undefined) {
+                // 有上限：按 UTF-8 实字节（Blob.size）判超限，超了截断不出翻页钮。
+                if (parsed.eof) {
+                    setNextOffset(null);
+                }
+                else if (new Blob([full]).size >= props.maxBytes) {
+                    setTruncated(true);
+                    setNextOffset(null);
+                }
+                else {
+                    setNextOffset(next);
+                }
+                return null;
+            }
+            setNextOffset(next);
+            return next;
+        }
+        catch (error) {
+            if (isAborted(controller.signal, error))
+                return null;
+            setFailed(errView(error));
+            return null;
+        }
+        finally {
+            if (!controller.signal.aborted)
+                setLoading(false);
+        }
+    }, [props.files, props.path, props.maxBytes]);
+    useEffect(() => {
+        accRef.current = '';
+        setText('');
+        setTruncated(false);
+        setNextOffset(null);
+        setFailed(null);
+        void (async () => {
+            let next = await load(0, false);
+            // 目标行不在首屏 ⇒ 续读到覆盖它（或到 eof / 上限）。
+            for (let page = 0; next !== null && props.focusLine !== undefined && page < FOCUS_MAX_PAGES
+                && accRef.current.split('\n').length < props.focusLine; page += 1) {
+                next = await load(next, true);
+            }
+        })();
+        return () => {
+            abortRef.current?.abort();
+        };
+        // focusLine 变了 = 同一文件换个落点，重新从首页读一遍。
+    }, [load, props.focusLine]);
+    if (failed !== null)
+        return h('div', { className: 'dshpc-fb__note' }, tt(failed.key, failed.params));
+    if (text === '' && loading)
+        return h('div', { className: 'dshpc-fb__note' }, tt('explorerLoading'));
+    const rendered = props.markdown && !props.sourceView;
+    return h('div', { className: 'dshpc-fb__text', style: { display: 'flex', flexDirection: 'column', ...(rendered ? { padding: 'var(--dshpc-space-3)' } : {}) } }, truncated
+        ? h('div', { className: 'dshpc-fb__banner' }, tt('previewTruncated', { n: formatBytes(props.maxBytes ?? 0) }))
+        : null, rendered
+        ? h(MarkdownText, { text, labels: markdownLabels() })
+        : h('div', { style: { flex: '1 1 auto', minHeight: 0, display: 'flex' } }, h(CodeViewer, { text, path: props.path, t: tt, focusLine: props.focusLine })), nextOffset !== null && props.maxBytes === undefined
+        ? h('div', { className: 'dshpc-fb__more' }, h(Button, { variant: 'outline', size: 'sm', loading: loading, onClick: () => void load(nextOffset, true) }, tt('previewLoadMore')))
+        : null);
+}
+//# sourceMappingURL=TextPreview.js.map

package/dist/adv/explorer/preview/TextPreview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextPreview.js","sourceRoot":"","sources":["../../../../src/adv/explorer/preview/TextPreview.ts"],"names":[],"mappings":"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"}

package/dist/adv/explorer/preview/index.d.ts

@@ -0,0 +1,24 @@
+import { createElement as h } from 'react';
+import { type Translate } from '../../../utils/i18n.js';
+import { type OfficeToPdfFace } from '../types.js';
+import type { FsFace } from '../fs-face.js';
+export { BytesPreview, type BytesPreviewProps } from './BytesPreview.js';
+export { HtmlPreview, buildStaticHtml, type HtmlPreviewProps } from './HtmlPreview.js';
+export { OfficePreview, type OfficePreviewProps } from './OfficePreview.js';
+export { TextPreview, type TextPreviewProps } from './TextPreview.js';
+export interface FilePreviewProps {
+    /** 只读文件面（绝对路径）。 */
+    files: FsFace;
+    /** Office 预览要的会话；可省 ⇒ 预览体按宿主工作区快照自己挑一条。 */
+    sessionId?: string;
+    path: string;
+    /** 官方 remote.officeToPdf；未就位传 null ⇒ Office 文件出「不可用」空态。 */
+    officeToPdf?: OfficeToPdfFace | null;
+    /** true = 源码态（md/html 生效）。 */
+    sourceView?: boolean;
+    /** 打开即定位到这一行（1 起；只对文本/源码态生效）。 */
+    line?: number;
+    translate?: Translate;
+}
+export declare function FilePreview(props: FilePreviewProps): ReturnType<typeof h> | null;
+//# sourceMappingURL=index.d.ts.map

package/dist/adv/explorer/preview/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adv/explorer/preview/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,IAAI,CAAC,EAAE,MAAM,OAAO,CAAA;AAE1C,OAAO,EAAK,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAiB,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AACjE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAM3C,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACtF,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAErE,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,2DAA2D;IAC3D,WAAW,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;IACpC,8BAA8B;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CA0ChF"}

package/dist/adv/explorer/preview/index.js

@@ -0,0 +1,58 @@
+// 单文件预览分派：按扩展名选预览体（image/pdf/md/html/office/text），认不出 ⇒ 明确兜底。
+// md/html 的「渲染 ⇄ 源码」由面板工具条切 sourceView 传进来。
+import { createElement as h } from 'react';
+import { ensureControls } from '../../../ui/infra/css.js';
+import { t } from '../../../utils/i18n.js';
+import { previewInfoOf } from '../types.js';
+import { BytesPreview } from './BytesPreview.js';
+import { HtmlPreview } from './HtmlPreview.js';
+import { OfficePreview } from './OfficePreview.js';
+import { TextPreview } from './TextPreview.js';
+export { BytesPreview } from './BytesPreview.js';
+export { HtmlPreview, buildStaticHtml } from './HtmlPreview.js';
+export { OfficePreview } from './OfficePreview.js';
+export { TextPreview } from './TextPreview.js';
+export function FilePreview(props) {
+    ensureControls();
+    const tt = props.translate ?? t;
+    const info = previewInfoOf(props.path);
+    const sourceView = props.sourceView === true;
+    switch (info.kind) {
+        case 'image':
+        case 'pdf':
+            return h(BytesPreview, {
+                files: props.files,
+                path: props.path,
+                kind: info.kind,
+                mime: info.mime ?? 'application/octet-stream',
+                translate: tt,
+            });
+        case 'office':
+            return h(OfficePreview, {
+                officeToPdf: props.officeToPdf ?? null,
+                sessionId: props.sessionId,
+                path: props.path,
+                translate: tt,
+            });
+        case 'html':
+            return h(HtmlPreview, {
+                files: props.files,
+                path: props.path,
+                sourceView,
+                translate: tt,
+            });
+        case 'md':
+        case 'text':
+            return h(TextPreview, {
+                files: props.files,
+                path: props.path,
+                markdown: info.kind === 'md',
+                sourceView,
+                focusLine: props.line,
+                translate: tt,
+            });
+    }
+    // switch 已穷尽 PreviewKind；保留 return 满足 TS 控制流分析
+    return null;
+}
+//# sourceMappingURL=index.js.map

package/dist/adv/explorer/preview/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/adv/explorer/preview/index.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,4CAA4C;AAC5C,OAAO,EAAE,aAAa,IAAI,CAAC,EAAE,MAAM,OAAO,CAAA;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,EAAE,CAAC,EAAkB,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,aAAa,EAAwB,MAAM,aAAa,CAAA;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,EAAE,YAAY,EAA0B,MAAM,mBAAmB,CAAA;AACxE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAyB,MAAM,kBAAkB,CAAA;AACtF,OAAO,EAAE,aAAa,EAA2B,MAAM,oBAAoB,CAAA;AAC3E,OAAO,EAAE,WAAW,EAAyB,MAAM,kBAAkB,CAAA;AAiBrE,MAAM,UAAU,WAAW,CAAC,KAAuB;IACjD,cAAc,EAAE,CAAA;IAChB,MAAM,EAAE,GAAG,KAAK,CAAC,SAAS,IAAI,CAAC,CAAA;IAC/B,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACtC,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,KAAK,IAAI,CAAA;IAC5C,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,OAAO,CAAC;QACb,KAAK,KAAK;YACR,OAAO,CAAC,CAAC,YAAY,EAAE;gBACrB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,0BAA0B;gBAC7C,SAAS,EAAE,EAAE;aACd,CAAC,CAAA;QACJ,KAAK,QAAQ;YACX,OAAO,CAAC,CAAC,aAAa,EAAE;gBACtB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,IAAI;gBACtC,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,SAAS,EAAE,EAAE;aACd,CAAC,CAAA;QACJ,KAAK,MAAM;YACT,OAAO,CAAC,CAAC,WAAW,EAAE;gBACpB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,UAAU;gBACV,SAAS,EAAE,EAAE;aACd,CAAC,CAAA;QACJ,KAAK,IAAI,CAAC;QACV,KAAK,MAAM;YACT,OAAO,CAAC,CAAC,WAAW,EAAE;gBACpB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,QAAQ,EAAE,IAAI,CAAC,IAAI,KAAK,IAAI;gBAC5B,UAAU;gBACV,SAAS,EAAE,KAAK,CAAC,IAAI;gBACrB,SAAS,EAAE,EAAE;aACd,CAAC,CAAA;IACN,CAAC;IACD,+CAA+C;IAC/C,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/adv/explorer/preview/md-labels.d.ts

@@ -0,0 +1,3 @@
+import type { MarkdownLabels } from '../../../ui/official.js';
+export declare function markdownLabels(): MarkdownLabels;
+//# sourceMappingURL=md-labels.d.ts.map

package/dist/adv/explorer/preview/md-labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"md-labels.d.ts","sourceRoot":"","sources":["../../../../src/adv/explorer/preview/md-labels.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAG7D,wBAAgB,cAAc,IAAI,cAAc,CAS/C"}

package/dist/adv/explorer/preview/md-labels.js

@@ -0,0 +1,12 @@
+import { t } from '../../../utils/i18n.js';
+export function markdownLabels() {
+    return {
+        code: {
+            copyLabel: t('mdCopy'),
+            copiedLabel: t('mdCopied'),
+            toolbarLabels: { codeLabel: t('mdCode'), wrapLabel: t('mdWrap'), unwrapLabel: t('mdUnwrap') },
+        },
+        footnotes: t('mdFootnotes'),
+    };
+}
+//# sourceMappingURL=md-labels.js.map

package/dist/adv/explorer/preview/md-labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"md-labels.js","sourceRoot":"","sources":["../../../../src/adv/explorer/preview/md-labels.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAA;AAE1C,MAAM,UAAU,cAAc;IAC5B,OAAO;QACL,IAAI,EAAE;YACJ,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC;YACtB,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC;YAC1B,aAAa,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC,EAAE;SAC9F;QACD,SAAS,EAAE,CAAC,CAAC,aAAa,CAAC;KAC5B,CAAA;AACH,CAAC"}

package/dist/adv/explorer/preview-title-bar.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 预览态的第二排：文件名 + 渲染⇄源码切换 / 复制路径 / 刷新。
+ *
+ * 2026-11-03 从 `FileBrowser.ts` 拆出。档位照兄弟项目调用点：Segmented `sm` + 图标钮 `md`
+ * （核心 Segmented 高度由 CSS 定，不随档变）。
+ */
+import { type ReactNode } from 'react';
+import type { Translate } from '../../utils/i18n.js';
+export interface PreviewTitleBarProps {
+    translate: Translate;
+    /** 正在预览的文件绝对路径。 */
+    path: string;
+    /** md / html 才出「渲染 ⇄ 源码」。 */
+    switchable: boolean;
+    /** md 用 md 的 aria 文案，html 用 html 的。 */
+    isMarkdown: boolean;
+    /** 当前是否在看源码。 */
+    sourceView: boolean;
+    onSourceViewChange: (source: boolean) => void;
+    /** 刚复制过（图标切对勾）。 */
+    copied: boolean;
+    onCopyPath: () => void;
+    onReload: () => void;
+}
+export declare function PreviewTitleBar(props: PreviewTitleBarProps): ReactNode;
+//# sourceMappingURL=preview-title-bar.d.ts.map

package/dist/adv/explorer/preview-title-bar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-title-bar.d.ts","sourceRoot":"","sources":["../../../src/adv/explorer/preview-title-bar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAU1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAIpD,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,SAAS,CAAA;IACpB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAA;IACZ,6BAA6B;IAC7B,UAAU,EAAE,OAAO,CAAA;IACnB,uCAAuC;IACvC,UAAU,EAAE,OAAO,CAAA;IACnB,gBAAgB;IAChB,UAAU,EAAE,OAAO,CAAA;IACnB,kBAAkB,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAA;IAC7C,mBAAmB;IACnB,MAAM,EAAE,OAAO,CAAA;IACf,UAAU,EAAE,MAAM,IAAI,CAAA;IACtB,QAAQ,EAAE,MAAM,IAAI,CAAA;CACrB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,SAAS,CA2CtE"}

package/dist/adv/explorer/preview-title-bar.js

@@ -0,0 +1,48 @@
+/**
+ * 预览态的第二排：文件名 + 渲染⇄源码切换 / 复制路径 / 刷新。
+ *
+ * 2026-11-03 从 `FileBrowser.ts` 拆出。档位照兄弟项目调用点：Segmented `sm` + 图标钮 `md`
+ * （核心 Segmented 高度由 CSS 定，不随档变）。
+ */
+import { createElement as h } from 'react';
+import { IconButton } from '../../ui/actions/Button.js';
+import { MarqueeText } from '../../ui/display/MarqueeText.js';
+import { Segmented } from '../../ui/inputs/Segmented.js';
+import { IconCheckOutlineRegular, IconCopyOutlineRegular, IconRefreshOutlineRegular, } from '../../ui/official.js';
+import { ensureComponentStyles } from '../../ui/infra/css.js';
+import { EXPLORER_CSS } from './explorer-css.js';
+import { baseNameOfPath } from './types.js';
+export function PreviewTitleBar(props) {
+    ensureComponentStyles('explorer', EXPLORER_CSS);
+    const { translate: tt, path, switchable, isMarkdown, sourceView, onSourceViewChange, copied, onCopyPath, onReload } = props;
+    return h('div', { className: 'dshpc-fb__title' }, h(MarqueeText, {
+        text: baseNameOfPath(path),
+        title: path,
+        className: 'dshpc-fb__title-inner',
+        style: { flex: '1 1 auto', minWidth: 0 },
+    }), h('div', { className: 'dshpc-fb__actions' }, switchable
+        ? h(Segmented, {
+            size: 'sm',
+            label: isMarkdown ? tt('previewMdSwitchAria') : tt('previewHtmlSwitchAria'),
+            value: sourceView ? 'source' : 'render',
+            items: [
+                { value: 'render', label: tt('previewRender') },
+                { value: 'source', label: tt('previewSource') },
+            ],
+            onChange: (next) => onSourceViewChange(next === 'source'),
+        })
+        : null, h(IconButton, {
+        variant: 'plain',
+        size: 'md',
+        icon: copied ? h(IconCheckOutlineRegular, { size: 14 }) : h(IconCopyOutlineRegular, { size: 14 }),
+        label: tt('previewCopyPath'),
+        onClick: onCopyPath,
+    }), h(IconButton, {
+        variant: 'plain',
+        size: 'md',
+        icon: h(IconRefreshOutlineRegular, { size: 14 }),
+        label: tt('previewRefresh'),
+        onClick: onReload,
+    })));
+}
+//# sourceMappingURL=preview-title-bar.js.map

package/dist/adv/explorer/preview-title-bar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-title-bar.js","sourceRoot":"","sources":["../../../src/adv/explorer/preview-title-bar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,aAAa,IAAI,CAAC,EAAkB,MAAM,OAAO,CAAA;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAA;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AACxD,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAE7D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAmB3C,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,qBAAqB,CAAC,UAAU,EAAE,YAAY,CAAC,CAAA;IAC/C,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAA;IAC3H,OAAO,CAAC,CACN,KAAK,EACL,EAAE,SAAS,EAAE,iBAAiB,EAAE,EAChC,CAAC,CAAC,WAAW,EAAE;QACb,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC;QAC1B,KAAK,EAAE,IAAI;QACX,SAAS,EAAE,uBAAuB;QAClC,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC,EAAE;KACzC,CAAC,EACF,CAAC,CACC,KAAK,EACL,EAAE,SAAS,EAAE,mBAAmB,EAAE,EAClC,UAAU;QACR,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE;YACX,IAAI,EAAE,IAAI;YACV,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,uBAAuB,CAAC;YAC3E,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ;YACvC,KAAK,EAAE;gBACL,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE;gBAC/C,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE;aAChD;YACD,QAAQ,EAAE,CAAC,IAAY,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,KAAK,QAAQ,CAAC;SAClE,CAAC;QACJ,CAAC,CAAC,IAAI,EACV,CAAC,CAAC,UAAU,EAAE;QACZ,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,uBAAuB,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,sBAAsB,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACjG,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC;QAC5B,OAAO,EAAE,UAAU;KACpB,CAAC,EACF,CAAC,CAAC,UAAU,EAAE;QACZ,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,IAAI;QACV,IAAI,EAAE,CAAC,CAAC,yBAAyB,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QAChD,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC;QAC3B,OAAO,EAAE,QAAQ;KAClB,CAAC,CACD,CACF,CAAA;AACH,CAAC"}

package/dist/adv/explorer/types.d.ts

@@ -0,0 +1,259 @@
+import { extOf, mimeOf } from '../../utils/path.js';
+import type { UtilMessageKey } from '../../utils/i18n.js';
+export interface WorkspaceFilesFace {
+    /** 文本分页读。⚠️ `range` **必传**（官方按位置参数个数校验，省了会被远端拒），读全量传 `{}`。 */
+    read(sessionId: string, path: string, range: {
+        offset?: number;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<{
+        offset: number;
+        text: string;
+        lines: number;
+        eof: boolean;
+        absolutePath?: string;
+        version?: number | string;
+        bytes?: number;
+    }>;
+    /** 二进制读（`options` 同样必传，不传 range 即读全量）。 */
+    readBytes(sessionId: string, path: string, options: {
+        range?: {
+            offset?: number;
+            length?: number;
+        };
+    }, signal?: AbortSignal): Promise<{
+        offset: number;
+        data: Uint8Array;
+        eof: boolean;
+        bytes?: number;
+    }>;
+    /** 列举直接子项；list 一个文件会报 not-directory。 */
+    list(sessionId: string, path: string, signal?: AbortSignal): Promise<{
+        path: string;
+        entries: ReadonlyArray<{
+            name: string;
+            type: 'file' | 'directory' | 'other';
+            size?: number;
+        }>;
+        truncated: boolean;
+    }>;
+    /** 单文件 stat（可选：宿主过旧没有此方法时降级）。只认普通文件，目录会抛。 */
+    stat?(sessionId: string, path: string, signal?: AbortSignal): Promise<{
+        absolutePath: string;
+        version?: number | string;
+        bytes?: number;
+    }>;
+}
+/**
+ * 官方 `remote.officeToPdf` 的消费面（本地结构化声明，零 npm 依赖，同 WorkspaceFilesFace 做法）。
+ * 运行时服务由宿主提供（宿主装了 @deepseek-ai/dsh-office-to-pdf 才有）；未装 ⇒ 调用方传 null ⇒
+ * Office 文件呈现「预览不可用」，不发起请求、不崩。
+ */
+export interface OfficeToPdfFace {
+    render(sessionId: string, path: string, priority: 'foreground' | 'background', signal?: AbortSignal): Promise<unknown>;
+}
+export interface DirEntry {
+    name: string;
+    type: 'file' | 'directory' | 'other';
+    size?: number;
+}
+export interface Listing {
+    path: string;
+    entries: DirEntry[];
+    truncated: boolean;
+}
+export type PreviewKind = 'image' | 'pdf' | 'md' | 'html' | 'office' | 'text';
+export interface PreviewInfo {
+    kind: PreviewKind;
+    ext: string;
+    mime?: string;
+}
+/** HTML 静态预览的扩展名（与官方 htmlBodyDefinition 同款）。 */
+export declare const HTML_KINDS: readonly string[];
+/**
+ * Office 预览扩展名（官方 remote.officeToPdf 转 PDF 后再渲染）。
+ * ⚠️ 官方 OfficeExtension 还含 xls / xlsx，按兄弟项目 2026-10-05 拍板「Excel 向后讨论」不纳入。
+ */
+export declare const OFFICE_KINDS: readonly string[];
+/** 源码态读取上限（256K，UTF-8 边界安全由截断处处理）。 */
+export declare const SOURCE_MAX_BYTES: number;
+/**
+ * 按扩展名分发预览类型。**没有 unsupported 档**：认不出的扩展名一律按 text 走，
+ * 由 read 抛 not-text 落「不是文本文件」空态——官方 read 才是真源，不本地猜二进制清单。
+ */
+export declare function previewInfoOf(path: string): PreviewInfo;
+/** 只要 kind（兼容旧用法）；要 ext/mime 用 previewInfoOf。 */
+export declare function previewKindOf(path: string): PreviewKind;
+type Envelope = {
+    kind: 'ok';
+    payload: unknown;
+} | {
+    kind: 'error';
+    error: unknown;
+};
+export declare function unwrapEnvelope(result: unknown): Envelope;
+/** 失败分支判空（TS 收窄用）。 */
+export declare function isFailed(value: unknown): value is {
+    failed: unknown;
+};
+export type Listed = Listing | {
+    failed: unknown;
+};
+/** `list` 结果防御解析：返回 Listing 或失败/非法信封。 */
+export declare function listingOf(result: unknown): Listed | null;
+export type TextPage = {
+    text: string;
+    offset: number;
+    lines: number;
+    eof: boolean;
+} | {
+    failed: unknown;
+} | null;
+/** `read` 结果防御解析：page.text 必须是字符串，否则错误态（防渲染器内部抛错整页黑屏）。 */
+export declare function textPageOf(result: unknown): TextPage;
+export type BytesRead = Uint8Array | {
+    failed: unknown;
+} | null;
+/** `readBytes` 结果防御解析：data 必须是 Uint8Array，否则错误态。 */
+export declare function bytesOf(result: unknown): BytesRead;
+/** `stat` 结果防御解析：只取 absolutePath（信封剥壳同款；stat 仅认 regular file）。 */
+export declare function absolutePathOf(result: unknown): string | null;
+/** 剥 wire 命名空间前缀（如 `workspace-file/not-found` ⇒ `not-found`）。 */
+export declare function bareCode(raw: unknown): string;
+/** 错误视图：文案键 + 占位参数。 */
+export interface ErrView {
+    key: UtilMessageKey;
+    params?: Record<string, string | number>;
+}
+/** 任意抛错/reject ⇒ 文案键。官方 code 分支 + 未知回落，绝不按消息文本猜。 */
+export declare function errView(error: unknown): ErrView;
+/** 子项排序：目录在前，文件在后，各自按名称（不区分大小写）升序。 */
+export declare function sortEntries(entries: readonly DirEntry[]): DirEntry[];
+/**
+ * 0.2.0-rc.1 起官方 list **拒绝空路径** ⇒ 空串（= 工作区根）一律以 `'.'` 上线
+ * （`'.'` 按 cwd = 工作区根归一解析为根本身；响应里根的 path 仍是 `''`）。
+ */
+export declare function listPathOf(dir: string): string;
+export interface RequestToken {
+    readonly signal: AbortSignal;
+    /** true = 仍是最新一次（未被下一次 begin / abort 作废，且未被取消）。 */
+    current(): boolean;
+}
+export interface RequestGate {
+    /** 开一次新请求：先中止上一次，返回本次 token。 */
+    begin(): RequestToken;
+    /** 中止当前请求（卸载 / 关闭 / 换目标时用）。 */
+    abort(): void;
+}
+export declare function createRequestGate(): RequestGate;
+/**
+ * 这次失败是不是「我们主动取消的」。宿主两种表现都要静默：
+ * reject `AbortError`，或 resolve `{ ok:false, error }` 信封——调用方补传 signal 由这里判定。
+ */
+export declare function isAborted(signal: AbortSignal | undefined, error?: unknown): boolean;
+/** 宿主绝对路径形态（/ 开头或 Windows 盘符）。 */
+export declare function isAbsoluteish(p: string): boolean;
+/** 工作区相对拼接（根下直接 name，不补前导 /）。 */
+export declare function relJoin(dir: string, name: string): string;
+/**
+ * 选择器回传：`path` 一律**绝对路径**（用户 2026-11-03 定）。
+ * 仍需要相对语义的消费方用 `workspaceRel`（仅当目标落在某个工作区内才有）。
+ */
+export interface PickedPath {
+    path: string;
+    isDir: boolean;
+    /** 目标相对其所属工作区根的路径；不在任何工作区内 ⇒ 不出现。 */
+    workspaceRel?: string;
+    /** 所属工作区显示名；不在任何工作区内 ⇒ 不出现。 */
+    workspace?: string;
+}
+/** 选择器过滤：`exts` = 只要这些扩展名（小写无点）；`dirs` = 只要文件夹；都不传 = 不限。 */
+export interface PickFilter {
+    exts?: readonly string[];
+    dirs?: boolean;
+}
+export declare function matchesFilter(path: string, isDir: boolean, filter: PickFilter | undefined): boolean;
+/**
+ * 归一绝对路径：`\` → `/`、盘符大写、去尾斜杠。相对路径原样返回（由调用方决定 base）。
+ * FS 面的路径一律先过这里，避免 `D:\a` 与 `d:/a` 被当成两个目录。
+ */
+export declare function normalizePath(path: string): string;
+/** 把绝对路径剥回某个根之下（不在根下 ⇒ 原样返回）。根为 null ⇒ 原样返回。 */
+export declare function relativizeToDir(path: string, root: string | null): string;
+/**
+ * 面包屑段：把目录路径拆成可点层级（绝对路径保留前导 /；Windows 盘符单独成段）。
+ */
+export declare function crumbsOfDir(dir: string): {
+    label: string;
+    path: string;
+}[];
+/**
+ * 目标路径落在哪个工作区（**最长前缀**，不需要会话）。嵌套工作区取最具体的那个。
+ * 与 `workspaceAnchorForPath` 的区别：这里不要求该工作区有会话 —— 浏览已经不吃会话了。
+ */
+export declare function workspaceOfPath(path: string, items: readonly WorkspaceAnchorItem[]): WorkspaceAnchorItem | null;
+/** 文件/目录的显示名（末段）。 */
+export declare function baseNameOfPath(p: string): string;
+/** 父目录（无父 = 空串）。 */
+export declare function dirnameOf(p: string): string;
+/** 路径拼接（处理根与绝对/相对；沿用 utils/path 的 joinPath 语义）。 */
+export { joinPath } from '../../utils/path.js';
+/** mimeOf 再导出（预览体要用，避免各自 import utils）。 */
+export { extOf, mimeOf };
+/**
+ * 工作区锚点的候选结构（官方 `workspaces` 服务快照 `WorkspaceView` 的消费子集，
+ * 见 docs/design/external/dsh-host.md §11）。只要够必要的字段，谁都能传。
+ */
+export interface WorkspaceAnchorItem {
+    /** 工作区显示名（面包屑首段 / 传给 FileBrowser 的 rootName）。 */
+    title: string;
+    /**
+     * 工作区绝对路径（宿主 registry / `workspaces` 快照的 `path`，realpath 归一形态）。
+     * **按路径匹配的必需字段**：不传 = 该工作区不参与 `workspaceAnchorForPath` 匹配
+     * （仍可被 `pickWorkspaceAnchor` 按更新时间挑中）。
+     */
+    path?: string;
+    /** 本工作区名下的会话 id（追加序）；没有一个会话的工作区无法浏览。 */
+    sessionIds?: readonly string[];
+    /** 更新时间戳（毫秒/数字口径由宿主给）；用于「最近打开」排序。 */
+    updatedAt?: number;
+}
+export interface WorkspaceAnchor {
+    /** 该工作区的显示名。 */
+    title: string;
+    /** 用来 list / read 的会话 id（该工作区最近一个会话）。 */
+    sessionId: string;
+}
+/**
+ * 从宿主工作区清单里挑一个**真实浏览锚点**：最近更新过、且有会话的工作区。
+ *
+ * `workspaceFiles` 是会话作用域服务（list/read 都要 sessionId），所以「打开文件夹」必须先
+ * 落到一个真会话上 —— 这里是它的唯一落点。
+ *
+ * @param items 宿主工作区清单（真实快照）。
+ * @returns 锚点；清单为空 / 都没有会话则返回 null。
+ */
+export declare function pickWorkspaceAnchor(items: readonly WorkspaceAnchorItem[]): WorkspaceAnchor | null;
+/**
+ * 按**工作区 title** 取浏览锚点会话（`workspaceAnchors` 里该 title 最近一个会话）。
+ *
+ * 与 `workspaceAnchorForPath`（按路径匹配）互补：调用方有 title 归属信息时用这个
+ * （兄弟项目 `GET /options` 的 `Record<title, 会话id>` 同口径，无歧义）；
+ * 只有裸绝对路径时才走路径匹配。没有该 title / 没有会话 ⇒ null。
+ */
+export declare function anchorSessionForTitle(items: readonly WorkspaceAnchorItem[], title: string): string | null;
+/**
+ * 目标**绝对路径**落在哪个工作区 ⇒ 该工作区最近一个会话 id（list 的 sessionId）。
+ *
+ * 为什么需要：`workspaceFiles.list` 是会话作用域服务（按 sessionId 解析工作区根，目录 confinement
+ * 检查 `contains(root, target)`，官方 `lib/index.js:576-583`）。调用方只甩一个绝对路径进来时，
+ * 默认 sessionId 的工作区根未必含它 ⇒ 官方报 `outside-workspace` ⇒ 面板整条退化成只读。
+ * 这里把「路径 → 工作区 → 会话」的解析收敛到核心，调用方只需把宿主工作区清单（带 path）传进来。
+ *
+ * 口径：**最长前缀**赢（嵌套工作区取最具体的）；尾斜杠归一；字面大小写（宿主 path 与调用方
+ * 路径同源，不做大小写折叠——Windows 跨形态比较是调用方归一的责任）。
+ * shortcut: 只解一次（入口 path），不跟踪 dir 切换；跨工作区跳转由调用方经 onSelectWorkspace 处理。
+ *
+ * @returns 锚点；无 path 字段 / 都不匹配 / 命中工作区没有会话 ⇒ null（调用方回落默认 sessionId）。
+ */
+export declare function workspaceAnchorForPath(path: string, items: readonly WorkspaceAnchorItem[]): WorkspaceAnchor | null;
+//# sourceMappingURL=types.d.ts.map

package/dist/adv/explorer/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/adv/explorer/types.ts"],"names":[],"mappings":"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"}