@khorsheed/dsh-file-preview 0.3.2 → 0.4.0

package/lib/types/client/path-utils.js

@@ -0,0 +1,110 @@
+/** Pure path display helpers for the file-preview tab. */
+import { isAbsoluteWorkspacePath } from '@deepseek-ai/dsh-util-workspace-path';
+/** The last path segment; the path itself when it has no separator. */
+export function basename(path) {
+    const slash = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+    return slash < 0 ? path : path.slice(slash + 1);
+}
+/** Everything before the last path separator ('' when the path has none). */
+export function parentPath(path) {
+    const slash = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+    return slash <= 0 ? '' : path.slice(0, slash);
+}
+/**
+ * Sort touched files by their last recorded activity, newest first. The fold
+ * keeps first-seen order; the view presents latest-first so the agent's most
+ * recent work is at the top.
+ * @param entries - the fold's first-seen entries.
+ * @returns a new array sorted by descending last-occurrence seq.
+ */
+export function sortByLatest(entries) {
+    return [...entries].sort((a, b) => b.seq - a.seq);
+}
+/**
+ * Case-insensitive substring match of a search query against a file's display
+ * path (the whole path, so a directory name matches too). Empty and
+ * whitespace-only queries match nothing deliberately — the view treats them as
+ * "no search" and shows the unfiltered list.
+ * @param path - the entry's display path.
+ * @param query - the trimmed search term.
+ * @returns whether the path contains the query, ignoring case.
+ */
+export function matchesQuery(path, query) {
+    if (query.length === 0)
+        return false;
+    return path.toLowerCase().includes(query.toLowerCase());
+}
+/**
+ * Split a file name into [before, match, after] for the first case-insensitive
+ * occurrence of `query`, so the view can highlight the matched substring.
+ * @param name - the display name to search.
+ * @param query - the trimmed search term.
+ * @returns the three parts, or null when the name does not contain the query.
+ */
+export function highlightMatch(name, query) {
+    if (query.length === 0)
+        return null;
+    const at = name.toLowerCase().indexOf(query.toLowerCase());
+    if (at < 0)
+        return null;
+    return [name.slice(0, at), name.slice(at, at + query.length), name.slice(at + query.length)];
+}
+/** Strip a workspace root prefix for compact display; the path stands when unrelated. */
+export function relativeToCwd(path, cwd) {
+    if (cwd === undefined || cwd.length === 0)
+        return path;
+    if (path === cwd)
+        return basename(path);
+    const rooted = cwd.endsWith('/') ? cwd : `${cwd}/`;
+    return path.startsWith(rooted) ? path.slice(rooted.length) : path;
+}
+/**
+ * Whether the official document tab can render this path: the `file` resource
+ * is workspace-scoped (the host answers outside-workspace stats with
+ * `workspace-file/outside-workspace`), so only workspace-rooted paths get a
+ * `dsh-resource://file/...` open. Relative paths qualify (the host resolves
+ * them against the session root); an absolute path qualifies when the session
+ * cwd is known and contains it, or when the cwd is unknown — the host's own
+ * failure line is the honest answer there.
+ * @param cwd - the session's workspace root, when known.
+ * @param path - the recorded display path (absolute or workspace-relative).
+ * @returns whether `openResource` stands a chance of rendering the file.
+ */
+export function isWithinWorkspace(cwd, path) {
+    if (!isAbsoluteWorkspacePath(path))
+        return true;
+    if (cwd === undefined || cwd.length === 0)
+        return true;
+    const root = cwd.replace(/\\/g, '/').replace(/\/+$/, '');
+    const target = path.replace(/\\/g, '/');
+    return target === root || target.startsWith(`${root}/`);
+}
+/** Whether a path names an HTML document (`.html`/`.htm`), offered a
+ * sandboxed render view alongside the source view. */
+export function isHtmlPath(path) {
+    const dot = path.lastIndexOf('.');
+    if (dot < 0)
+        return false;
+    const ext = path.slice(dot).toLowerCase();
+    return ext === '.html' || ext === '.htm';
+}
+/** Map a file extension to a prism language name for CodeBlock, or undefined to auto-detect. */
+const LANGUAGE_BY_EXTENSION = {
+    '.ts': 'typescript', '.tsx': 'typescript', '.mts': 'typescript', '.cts': 'typescript',
+    '.js': 'javascript', '.jsx': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript',
+    '.json': 'json', '.jsonc': 'json', '.md': 'markdown', '.mdx': 'markdown',
+    '.yml': 'yaml', '.yaml': 'yaml', '.html': 'html', '.htm': 'html',
+    '.css': 'css', '.scss': 'scss', '.less': 'less', '.sh': 'bash', '.bash': 'bash',
+    '.py': 'python', '.sql': 'sql', '.xml': 'xml', '.toml': 'toml', '.ini': 'ini',
+    '.go': 'go', '.rs': 'rust', '.java': 'java', '.c': 'c', '.h': 'c',
+    '.cpp': 'cpp', '.hpp': 'cpp', '.rb': 'ruby', '.php': 'php', '.swift': 'swift',
+    '.kotlin': 'kotlin', '.vue': 'vue', '.svelte': 'svelte', '.dockerfile': 'docker',
+    '.graphql': 'graphql', '.proto': 'protobuf', '.diff': 'diff', '.patch': 'diff',
+};
+/** The prism language name for a path's extension, or undefined for auto-detection. */
+export function languageFor(path) {
+    const dot = path.lastIndexOf('.');
+    if (dot < 0)
+        return undefined;
+    return LANGUAGE_BY_EXTENSION[path.slice(dot).toLowerCase()];
+}

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

@@ -0,0 +1,27 @@
+import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PreviewRead, PreviewTranslator, StructuredLabels } from '@khorsheed/dsh-client-ui-content-preview/src/client/index.ts';
+import type { FilePreviewRead } from '../types.ts';
+/**
+ * Map one file-preview read onto the kernel's contract.
+ *
+ * The wire type carries `path` plus optional per-kind fields (like the
+ * local-files one), so the arms are spelled out rather than cast: an image read
+ * with no URL becomes `missing`/`unreadable` instead of an `<img>` with no
+ * source.
+ * @param read - the host's read result.
+ * @returns the kernel's normalized read.
+ */
+export declare function toPreviewRead(read: FilePreviewRead): PreviewRead;
+/**
+ * The pane's translator over this plugin's `filePreview` dictionary.
+ * @param t - the locale-bound translator for this plugin's namespace.
+ * @returns the kernel's translator.
+ */
+export declare function previewTranslator(t: TranslateNS<'filePreview'>): PreviewTranslator;
+/**
+ * The structured-render chrome for the kernel's JSON tree / CSV table / markdown.
+ * @param t - the locale-bound translator for this plugin's namespace.
+ * @returns the kernel's label object.
+ */
+export declare function structuredLabels(t: TranslateNS<'filePreview'>): StructuredLabels;
+//# sourceMappingURL=preview.d.ts.map

package/lib/types/client/preview.js

@@ -0,0 +1,72 @@
+/**
+ * Map one file-preview read onto the kernel's contract.
+ *
+ * The wire type carries `path` plus optional per-kind fields (like the
+ * local-files one), so the arms are spelled out rather than cast: an image read
+ * with no URL becomes `missing`/`unreadable` instead of an `<img>` with no
+ * source.
+ * @param read - the host's read result.
+ * @returns the kernel's normalized read.
+ */
+export function toPreviewRead(read) {
+    switch (read.kind) {
+        case 'text':
+            return {
+                kind: 'text',
+                path: read.path,
+                content: read.content ?? '',
+                ...(read.truncated === true ? { truncated: true } : {}),
+                ...(read.htmlScripted === true ? { htmlScripted: true } : {}),
+            };
+        case 'image':
+            return read.url === undefined
+                ? { kind: 'missing', path: read.path, reason: 'unreadable' }
+                : { kind: 'image', path: read.path, url: read.url, ...(read.size === undefined ? {} : { size: read.size }) };
+        case 'binary':
+            return { kind: 'binary', path: read.path, ...(read.size === undefined ? {} : { size: read.size }) };
+        case 'too-large':
+            return { kind: 'too-large', path: read.path, ...(read.size === undefined ? {} : { size: read.size }) };
+        case 'missing':
+            return { kind: 'missing', path: read.path };
+        case 'error':
+            return { kind: 'error', path: read.path, ...(read.message === undefined ? {} : { message: read.message }) };
+    }
+}
+/**
+ * The pane's translator over this plugin's `filePreview` dictionary.
+ * @param t - the locale-bound translator for this plugin's namespace.
+ * @returns the kernel's translator.
+ */
+export function previewTranslator(t) {
+    return (key, params) => t(key, params);
+}
+/** JsonTree chrome over this plugin's dictionary. */
+function jsonTreeLabels(t) {
+    return {
+        copyValue: t('json.copyValue'),
+        copyJson: t('json.copyJson'),
+        copyPath: t('json.copyPath'),
+        copyPrettyJson: t('json.copyPrettyJson'),
+        copyCompactJson: t('json.copyCompactJson'),
+        copied: t('json.copied'),
+        copyFailed: t('json.copyFailed'),
+        collapseNode: t('json.collapseNode'),
+        expandNode: t('json.expandNode'),
+        copyButtonTitle: action => t('json.copyButtonTitle', { action }),
+    };
+}
+/** MarkdownText chrome over this plugin's dictionary. */
+function markdownLabels(t) {
+    return {
+        code: { copyLabel: t('action.copy'), copiedLabel: t('action.copied') },
+        footnotes: t('markdown.footnotes'),
+    };
+}
+/**
+ * The structured-render chrome for the kernel's JSON tree / CSV table / markdown.
+ * @param t - the locale-bound translator for this plugin's namespace.
+ * @returns the kernel's label object.
+ */
+export function structuredLabels(t) {
+    return { json: jsonTreeLabels(t), markdown: markdownLabels(t) };
+}

package/lib/types/client/turn-files-cache.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Session-level cache in front of the `filePreview.turnFiles` RPC. One fetch
+ * warms every turn the response carries (the host returns the whole per-turn
+ * map up to its watermark, and the host itself caches the fold by that
+ * watermark), and every requested turn — including one the response reports
+ * empty — is pinned so a re-mount of the same card never refetches. A card for
+ * a newer, not-yet-seen turn triggers one refetch, which the host answers
+ * without refolding. Errors resolve to an empty list — the card just shows
+ * nothing.
+ * @module @khorsheed/dsh-file-preview
+ */
+import type { FilePreviewTurnFile } from '../types.ts';
+import type { SessionId } from '@deepseek-ai/dsh-api-remotes/client';
+import type { FilePreviewRemote } from './contract.ts';
+/**
+ * Build a turn-files loader bound to one mounted Remote (created per apply, so
+ * the cache never pins module-level identity across plugin reloads).
+ * @param remote - the mounted filePreview Remote handle.
+ * @returns a loader resolving one session's files for one turn.
+ */
+export declare function createTurnFilesLoader(remote: FilePreviewRemote): (sessionId: SessionId, turn: number) => Promise<readonly FilePreviewTurnFile[]>;
+/** The loader's function shape, shared with the inject face. */
+export type TurnFilesLoader = ReturnType<typeof createTurnFilesLoader>;
+//# sourceMappingURL=turn-files-cache.d.ts.map

package/lib/types/client/turn-files-cache.js

@@ -0,0 +1,39 @@
+/**
+ * Session-level cache in front of the `filePreview.turnFiles` RPC. One fetch
+ * warms every turn the response carries (the host returns the whole per-turn
+ * map up to its watermark, and the host itself caches the fold by that
+ * watermark), and every requested turn — including one the response reports
+ * empty — is pinned so a re-mount of the same card never refetches. A card for
+ * a newer, not-yet-seen turn triggers one refetch, which the host answers
+ * without refolding. Errors resolve to an empty list — the card just shows
+ * nothing.
+ * @module @khorsheed/dsh-file-preview
+ */
+/**
+ * Build a turn-files loader bound to one mounted Remote (created per apply, so
+ * the cache never pins module-level identity across plugin reloads).
+ * @param remote - the mounted filePreview Remote handle.
+ * @returns a loader resolving one session's files for one turn.
+ */
+export function createTurnFilesLoader(remote) {
+    const cache = new Map();
+    return (sessionId, turn) => {
+        const sessionCache = cache.get(sessionId);
+        if (sessionCache !== undefined && sessionCache.has(turn)) {
+            return Promise.resolve(sessionCache.get(turn) ?? []);
+        }
+        return remote.turnFiles(sessionId).then((result) => {
+            const merged = cache.get(sessionId) ?? new Map();
+            if (result.ok) {
+                for (const group of result.value.turns)
+                    merged.set(group.turn, group.files);
+            }
+            // Pin the requested turn's resolution (possibly empty) so the same card
+            // never refetches; newer turns still trigger one refetch each.
+            if (!merged.has(turn))
+                merged.set(turn, []);
+            cache.set(sessionId, merged);
+            return merged.get(turn) ?? [];
+        });
+    };
+}

package/lib/types/client/turn-files.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Turn-tail chain claim for the file-preview turn card — the 0.1.5 fallback
+ * path only. 0.1.6-alpha.2 re-kinded `conversation.chat.turnTail` from chain
+ * (election) to list (every entry renders; no selector exists), where the
+ * card coexists with the official cards and self-hides without data; this
+ * claim survives for the chain branch of the dual-host registration in
+ * index.ts. The card is an async thin shell: the host `filePreview.turnFiles`
+ * RPC is the SINGLE source of truth for every turn's mutations — write/edit
+ * calls, Code Mode dispatches, render-intent paths from result diff meta, and
+ * bash captures — so the card and the file-preview tab read the same host
+ * data. The claim is unconditional so the card claims every turn (priority
+ * -1, ahead of the official deliverables entry's default 0 — the chain elects
+ * ascending) and renders nothing until its fetch settles or the turn has no
+ * files.
+ */
+import type { TurnTailOwnerProps } from '@deepseek-ai/dsh-client-ui-chat/client';
+/**
+ * Claim every turn of the chain (the row decides visibility from its fetch).
+ * @param _owner - chain owner currency; unused — the claim never declines.
+ * @returns a non-null marker so this entry wins the election whenever the
+ *   earlier official entries declined the turn.
+ */
+export declare function selectTurnFiles(_owner: TurnTailOwnerProps): readonly [];
+/** Re-export for the row component's basename display. */
+export declare function basename(path: string): string;
+//# sourceMappingURL=turn-files.d.ts.map

package/lib/types/client/turn-files.js

@@ -0,0 +1,14 @@
+/**
+ * Claim every turn of the chain (the row decides visibility from its fetch).
+ * @param _owner - chain owner currency; unused — the claim never declines.
+ * @returns a non-null marker so this entry wins the election whenever the
+ *   earlier official entries declined the turn.
+ */
+export function selectTurnFiles(_owner) {
+    return [];
+}
+/** Re-export for the row component's basename display. */
+export function basename(path) {
+    const at = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'));
+    return at === -1 ? path : path.slice(at + 1);
+}

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "File Preview",
-    "description": "Read-only listing of session-written files with their current content."
+    "title": "Session Artifacts",
+    "description": "Preview files the agent wrote or edited and step through every change."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "文件预览",
-    "description": "只读列出会话写过、改过的文件并提供当前文本。"
+    "title": "会话产物",
+    "description": "预览 agent 写过、改过的文件，步进每一次改动。"
   }
 }

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@khorsheed/dsh-file-preview",
-  "description": "Read-only file-preview Remote service: lists the files a session wrote or edited and serves their current text content",
+  "description": "Session products preview, host+client in one: the read-only file-preview Remote service (the files a session wrote or edited, current content, per-change diffs) plus the right-sidebar 会话产物 tab, per-turn change cards, and the file detail view",
   "keywords": [
     "dsh",
     "dsh-plugin",
     "cordis",
     "file-preview"
   ],
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -24,6 +24,10 @@
       "types": "./lib/types/types.d.ts",
       "default": "./lib/types/types.js"
     },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
     "./typert": {
       "types": "./lib/typert.host.d.ts",
       "default": "./lib/typert.host.js"
@@ -49,14 +53,48 @@
   ],
   "license": "MIT",
   "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-chat": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-ui-sidebar-right": "^0.1.7-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-fs": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-native-command": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-typert-protocol": "^0.1.0-rc.6",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-api-remotes": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-locale": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-chat": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-primitives": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-sidebar-right": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-client-ui-slots": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
   },
   "dependencies": {
     "zod": "^4.4.3"
@@ -65,9 +103,22 @@
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-deliverables",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
+      ],
+      "platform": "web"
+    },
     "compat": {
       "minHost": "0.1.5-rc.1",
-      "verifiedHost": "0.1.5-rc.1"
+      "verifiedHost": "0.1.5-rc.1",
+      "notes": "单一形态双线一致：自建「会话产物」page 型右栏 tab（向导页进入 + extension 档认领 dsh-resource://file/** 可渲染后缀，压过官方 document tab 的 fallback 档——rc.1 的 tab-registry 保留 band 机制），文件树/mention/回合卡/产物行点击全部落自绘详情页（共享内容面板全 chrome + 内容/改动记录切换 + 复制路径/在文件夹/IDE 打开）；pdf/压缩包/二进制等 decline 后缀落回官方 document tab。方案 B（内容面注册进官方 documentPreviews 面做默认渲染器）与二期 headless 嵌入已于 2026-09-24 同日被仓主否决回退——接缝成本（renderer loading 协议/extension 档语义/headless 布局耦合）与 UX 妥协（改动记录塞进渲染器下拉、复制钮浮动压搜索行）不成立；改动记录维度（TurnFileRow + 详情页 DiffHistory）官方仍无对应物（workspace-changes 内存态、git-only、重启即失），维持自留并跟踪上游。turnTail 回合卡照常：0.1.6-alpha.2 起 list 槽臂同时注册官方 deliverables 条目的一等遮蔽（同 cell id、priority -1 空体胜出，官方条目在册故其子槽不塌），0.1.5 chain 槽臂保持 select + priority -1 抢占回退——均不涉及 rc.1 专有 API，minHost 不动。0.4.0 起宿主 Remote 与浏览器半同包（ui-file-preview 并入），headless 组合只装宿主半照常工作（client 面在 web 组合里经 dsh.client 发现）。"
     }
   }
 }