@khorsheed/dsh-file-preview 0.3.2 → 0.4.0

package/lib/types/client/definition.js

@@ -0,0 +1,93 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { parseFileAddress } from '@deepseek-ai/dsh-util-workspace-path';
+/** The tab kind this package owns. */
+export const FILE_PREVIEW_KIND = 'file-preview';
+/** This implementation's identity in the tab system, and the key its body registers under. */
+export const FILE_PREVIEW_ID = '@khorsheed/dsh-file-preview';
+/**
+ * Suffixes the detail view's preview stack renders: the change-history text
+ * set plus the image formats the pane's image arm serves. Everything else
+ * (pdf, archives, binaries) stays with the official document tab — the type's
+ * `canOpen` filters on this set before claiming an address.
+ */
+export const RENDERABLE_EXTENSIONS = [
+    'md', 'mdx', 'txt', 'log',
+    'json', 'jsonc', 'jsonl', 'csv', 'tsv', 'xml', 'svg',
+    'yaml', 'yml', 'toml', 'ini',
+    'ts', 'tsx', 'mts', 'cts', 'js', 'jsx', 'mjs', 'cjs',
+    'py', 'sh', 'bash', 'sql',
+    'html', 'htm', 'css', 'scss', 'less',
+    'go', 'rs', 'java', 'c', 'h', 'cpp', 'hpp', 'rb', 'php', 'swift', 'kt',
+    'vue', 'svelte', 'diff', 'patch',
+    'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'bmp', 'ico',
+];
+const RENDERABLE = new Set(RENDERABLE_EXTENSIONS);
+/**
+ * Whether the detail view can render this path's content (suffix match,
+ * case-insensitive, compound suffixes intentionally not special-cased).
+ * @param path - any file path spelling.
+ */
+export function renderablePath(path) {
+    const base = path.replaceAll('\\', '/').toLowerCase();
+    const name = base.slice(base.lastIndexOf('/') + 1);
+    const dot = name.lastIndexOf('.');
+    return dot > 0 && RENDERABLE.has(name.slice(dot + 1));
+}
+/**
+ * The type's glyph at the guide capsule's size: a document sheet with the
+ * change-history accent (the official files capsule's two-tone flat style,
+ * re-cut for "products with history").
+ */
+function ProductsGlyph({ size, className }) {
+    return (_jsxs("svg", { width: size, height: size, viewBox: "0 0 26 26", className: className, "aria-hidden": "true", children: [_jsx("path", { d: "M7 3.5h7.2c.5 0 .9.2 1.2.5l4.4 4.4c.3.3.5.7.5 1.2v12.1c0 1-.8 1.8-1.8 1.8H7c-1 0-1.8-.8-1.8-1.8V5.3c0-1 .8-1.8 1.8-1.8Z", fill: "#4f8ff7", opacity: "0.28" }), _jsx("path", { d: "M7 3.5h7.2c.5 0 .9.2 1.2.5l4.4 4.4c.3.3.5.7.5 1.2v12.1c0 1-.8 1.8-1.8 1.8H7c-1 0-1.8-.8-1.8-1.8V5.3c0-1 .8-1.8 1.8-1.8Z", fill: "none", stroke: "#4f8ff7", strokeWidth: "1.6" }), _jsx("path", { d: "M14.6 3.8v4.4c0 .6.5 1.1 1.1 1.1h4.4", fill: "none", stroke: "#4f8ff7", strokeWidth: "1.6" }), _jsx("line", { x1: "8.6", y1: "13.6", x2: "13.4", y2: "13.6", stroke: "#e5645f", strokeWidth: "1.7", strokeLinecap: "round" }), _jsx("line", { x1: "8.6", y1: "17.4", x2: "15.6", y2: "17.4", stroke: "#3fb27f", strokeWidth: "1.7", strokeLinecap: "round" })] }));
+}
+/**
+ * The tab chip text: the decoded basename for a claimed file address (the
+ * document tab's convention), the type label for a page open. Decoding is per
+ * segment, matching how the address was built, so a name carrying `#`, `?`,
+ * or a space reads as itself.
+ * @param address - the address being opened.
+ * @param fallback - the type label for non-file addresses.
+ */
+function chipTitle(address, fallback) {
+    if (!address.startsWith('dsh-resource://'))
+        return fallback();
+    const name = address.slice(address.lastIndexOf('/') + 1);
+    if (name === '')
+        return fallback();
+    try {
+        return decodeURIComponent(name);
+    }
+    catch {
+        // A malformed percent sequence is still a name; showing it raw beats refusing the address.
+        return name;
+    }
+}
+/**
+ * The file-preview type's registry definition.
+ * @param t - namespace-bound translate, read fresh on every label call.
+ * @returns the definition to register.
+ */
+export function filePreviewDefinition(t) {
+    return {
+        id: FILE_PREVIEW_ID,
+        kind: FILE_PREVIEW_KIND,
+        patterns: ['dsh-resource://file/**'],
+        // Claim every session-scoped file address the preview stack renders.
+        // Synchronous and deterministic by construction (no data dependency);
+        // unrenderable suffixes and session-less addresses decline, falling
+        // through to the official document tab (fallback band).
+        canOpen: (address) => {
+            const parsed = parseFileAddress(address);
+            return parsed?.scope === 'session' && renderablePath(parsed.path);
+        },
+        title: (address) => chipTitle(address, () => t('open')),
+        guide: [{
+                id: FILE_PREVIEW_KIND,
+                order: 20,
+                title: () => t('guide.title'),
+                description: () => t('guide.description'),
+                icon: ProductsGlyph,
+            }],
+    };
+}

package/lib/types/client/file-preview-store.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The file-preview tab's store: the session's touched-file list (one fetch,
+ * shared by every tab of this kind in the session) and each tab's selected
+ * path. Module level exports the factory only — a module-level handle would
+ * pin the store's identity in the module cache (a de-facto singleton
+ * surviving plugin reloads). register() receives the factory (exclusive use:
+ * the framework mints one instance per session), and the body derives its
+ * PropsStore share from the return type.
+ */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-store';
+import type { TabId } from '@deepseek-ai/dsh-client-ui-sidebar-right/client';
+import type { FilePreviewEntry, FilePreviewList } from '../types.ts';
+/** The tab body's state; fetched results are whole values, null until loaded. */
+export interface FilePreviewState {
+    /** The latest fetched file list, or null before the first successful load. */
+    list: readonly FilePreviewEntry[] | null;
+    /** Seq watermark of the loaded list. */
+    listAsOfSeq: number;
+    /** Bumped by the refresh action to re-trigger the list fetch. */
+    listRequestRev: number;
+    /** Whether a list fetch is in flight. */
+    listLoading: boolean;
+    /** Human-readable list-fetch failure, or null when idle. */
+    listError: string | null;
+    /** Each tab's selected path (tabs of this kind in one session select independently). */
+    selected: Record<string, string>;
+}
+/** Annotation twin of the actions literal below (drift fails assignability at defineStore). */
+export type FilePreviewActions = {
+    select: (draft: FilePreviewState, tabId: TabId, path: string) => void;
+    deselect: (draft: FilePreviewState, tabId: TabId) => void;
+    refreshList: (draft: FilePreviewState) => void;
+    setList: (draft: FilePreviewState, list: FilePreviewList) => void;
+    setListLoading: (draft: FilePreviewState, loading: boolean) => void;
+    setListError: (draft: FilePreviewState, error: string | null) => void;
+};
+/**
+ * Create the file-preview tab store handle.
+ * @returns the store handle (spec + type + identity + factory in one).
+ */
+export declare function createFilePreviewStore(): EngineStoreHandle<FilePreviewState, FilePreviewActions>;
+//# sourceMappingURL=file-preview-store.d.ts.map

package/lib/types/client/file-preview-store.js

@@ -0,0 +1,58 @@
+/**
+ * The file-preview tab's store: the session's touched-file list (one fetch,
+ * shared by every tab of this kind in the session) and each tab's selected
+ * path. Module level exports the factory only — a module-level handle would
+ * pin the store's identity in the module cache (a de-facto singleton
+ * surviving plugin reloads). register() receives the factory (exclusive use:
+ * the framework mints one instance per session), and the body derives its
+ * PropsStore share from the return type.
+ */
+import { defineStore } from '@deepseek-ai/dsh-client-store';
+const INITIAL = {
+    list: null,
+    listAsOfSeq: -1,
+    listRequestRev: 0,
+    listLoading: false,
+    listError: null,
+    selected: {},
+};
+/**
+ * Create the file-preview tab store handle.
+ * @returns the store handle (spec + type + identity + factory in one).
+ */
+export function createFilePreviewStore() {
+    return defineStore({
+        init: () => ({ ...INITIAL, selected: {} }),
+        actions: {
+            /**
+             * Select one file in one tab (its change history renders below the list).
+             * @param d - draft state.
+             * @param tabId - the selecting tab.
+             * @param path - the recorded display path.
+             */
+            select: (d, tabId, path) => { d.selected[tabId] = path; },
+            /**
+             * Clear one tab's selection (the detail view's back gesture).
+             * @param d - draft state.
+             * @param tabId - the tab going back to the list.
+             */
+            deselect: (d, tabId) => { delete d.selected[tabId]; },
+            /** Re-trigger the list fetch. @param d - draft state. */
+            refreshList: (d) => { d.listRequestRev += 1; },
+            /**
+             * Record a fetched list.
+             * @param d - draft state.
+             * @param list - the Remote's whole response.
+             */
+            setList: (d, list) => {
+                d.list = list.entries;
+                d.listAsOfSeq = list.asOfSeq;
+                d.listError = null;
+            },
+            /** @param d - draft state. @param loading - whether a fetch is in flight. */
+            setListLoading: (d, loading) => { d.listLoading = loading; },
+            /** @param d - draft state. @param error - the failure to show, or null. */
+            setListError: (d, error) => { d.listError = error; },
+        },
+    });
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Generated by scripts/sync-icon-artwork.mts from @deepseek-ai/dsh-client-ui-primitives
+ * (v0.1.7-rc.1, harness 46a7f68b09) — do not edit by hand. The 0.1.5 and rc.1 host lines
+ * share no icon export name, so the rc.1 artwork is inlined here: pure SVG,
+ * no host runtime identity, identical on every line. Re-run the generator
+ * after adding an icon import or bumping the harness checkout.
+ *
+ * @module @khorsheed/dsh-file-preview/client
+ */
+/** Shared props for every product icon component (mirrors the upstream IconProps). */
+export interface IconProps {
+    /** Square edge in px; defaults to the glyph's own drawn size. */
+    size?: number | undefined;
+    /** Extra class for layout placement; color rides currentColor. */
+    className?: string | undefined;
+}
+export declare const IconChevronDownOutlineMedium: ({ size, className }: IconProps) => import("react").JSX.Element;
+export declare const IconChevronUpOutlineMedium: ({ size, className }: IconProps) => import("react").JSX.Element;
+export declare const IconGlobeOutlineMedium: ({ size, className }: IconProps) => import("react").JSX.Element;
+export declare const IconRefreshOutlineMedium: ({ size, className }: IconProps) => import("react").JSX.Element;
+//# sourceMappingURL=icons.d.ts.map

package/lib/types/client/icons.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const IconChevronDownOutlineMedium = ({ size = 14, className }) => (_jsx("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: 1.3, children: _jsx("path", { d: "M4 6L7.29289 9.29289C7.68342 9.68342 8.31658 9.68342 8.70711 9.29289L12 6", stroke: "currentColor" }) }));
+export const IconChevronUpOutlineMedium = ({ size = 14, className }) => (_jsx("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: 1.3, children: _jsx("path", { d: "M12 10L8.70711 6.70711C8.31658 6.31658 7.68342 6.31658 7.29289 6.70711L4 10", stroke: "currentColor" }) }));
+export const IconGlobeOutlineMedium = ({ size = 14, className }) => (_jsxs("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: 1.3, children: [_jsx("path", { d: "M7.99986 14.0887C11.3626 14.0887 14.0886 11.3627 14.0886 7.99998C14.0886 4.63727 11.3626 1.91125 7.99986 1.91125C4.63715 1.91125 1.91113 4.63727 1.91113 7.99998C1.91113 11.3627 4.63715 14.0887 7.99986 14.0887Z", stroke: "currentColor" }), _jsx("path", { d: "M2.34619 8H13.6538", stroke: "currentColor", strokeLinecap: "square" }), _jsx("path", { d: "M7.99976 14.0889C9.23509 14.0889 10.1743 11.3629 10.1743 8.00006C10.1743 4.63739 9.23509 1.91138 7.99976 1.91138", stroke: "currentColor" }), _jsx("path", { d: "M7.99973 14.0889C6.76445 14.0889 5.8252 11.3629 5.8252 8.00006C5.8252 4.63739 6.76445 1.91138 7.99973 1.91138", stroke: "currentColor" })] }));
+export const IconRefreshOutlineMedium = ({ size = 16, className }) => (_jsxs("svg", { width: size, height: size, className: className, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: 1.3, children: [_jsx("path", { d: "M14.5001 8C14.5 9.28552 14.1188 10.5422 13.4045 11.611C12.6903 12.6799 11.6752 13.5129 10.4875 14.0049C9.29982 14.4968 7.99295 14.6255 6.73212 14.3747C5.4713 14.124 4.31314 13.505 3.4041 12.596C2.49514 11.687 1.87614 10.5288 1.62537 9.26798C1.37459 8.00716 1.50331 6.70028 1.99525 5.51261C2.48719 4.32494 3.32025 3.30981 4.3891 2.59557C5.45795 1.88134 6.71458 1.50008 8.0001 1.5C9.9001 1.5 11.7001 2.3 13.0001 3.6L14.5001 5.1", stroke: "currentColor" }), _jsx("path", { d: "M14.4999 1.5V5.1H10.8999", stroke: "currentColor" })] }));

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

@@ -0,0 +1,80 @@
+/**
+ * File-preview plugin, browser half: a pure additive surface over official
+ * extension points only. It registers a page-type right-Sidebar tab (the
+ * session's touched files as one full-height list, entered from the guide
+ * page), claiming `dsh-resource://file/**` addresses the preview stack renders
+ * at the extension band — which outranks the official document tab's fallback
+ * band on BOTH host lines (the rc.1 tab registry kept the band mechanism), so
+ * file clicks (the file tree, wrapped mentions, the turn card, the
+ * deliverables row) land in this package's own page with its full chrome;
+ * suffixes the stack declines (pdf, archives, binaries) fall through to the
+ * official document tab. A per-turn mutation card sits in the
+ * `conversation.chat.turnTail` slot (the bash captures the host half
+ * collects, S2). The filePreview Remote is mounted here through the official
+ * `ctx.remote.$mount` channel, so the plugin distributes as an independent
+ * package with no edits to core packages. Composing this plugin out of
+ * cordis.yml removes every surface it adds.
+ *
+ * Plan B — registering the content pane INTO the official document tab as its
+ * default renderer (rc.1's `documentPreviews` registry) plus the headless
+ * embedding of phase two — landed and was VETOED by the repo owner the same
+ * day (2026-09-24): the seam cost (the renderer loading protocol, the
+ * extension-band takeover semantics, the headless layout coupling) and the UX
+ * compromises (change history demoted to the renderer dropdown, the copy
+ * button floating over the search row) lost to the self-drawn page, which the
+ * address claim restores wholesale. The turn-tail convergence survives the
+ * veto and stays: on list-kind hosts (0.1.6-alpha.2+) the arm also shadows
+ * the official deliverables entry (a second registration under its cell id at
+ * `priority: -1` whose empty body wins the cell — the slot system's
+ * first-class shadowing; the official entry stays on the ledger so its
+ * declared `deliverables.file.actions` child slot never collapses), because
+ * the official present card duplicates our durable row with a model-curated
+ * subset and the official changes card is memory-resident. On a 0.1.5 host
+ * the slot is still the election chain; the registration probes the
+ * declaration kind and keeps the old preemptive shape (select + priority -1)
+ * there.
+ *
+ * Retired at the 0.1.5-rc.1 move (seam registry S1): the conversation.view
+ * tab, the shell.overlay drawer, and the mention capture-phase DOM
+ * interception — the right-Sidebar resource routing (openResource + the
+ * tab-type registry) covers all three openings. Retired with the plan-B
+ * revert (2026-09-24): the change-history renderer in the official document
+ * tab's dropdown (FileHistoryBody) — the change history lives only in this
+ * page's detail view again (the Content / 改动记录 toggle).
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { FilePreviewTab } from './FilePreviewTab.tsx';
+import { TurnFileRow } from './TurnFileRow.tsx';
+import { FILE_PREVIEW_ID, FILE_PREVIEW_KIND } from './definition.tsx';
+import type { FilePreviewRemote } from './contract.ts';
+export { DiffHistory } from './DiffHistory.tsx';
+export { FilePreviewTab, TurnFileRow };
+export { FILE_PREVIEW_ID, FILE_PREVIEW_KIND };
+/** Required services: slots, sessions (cwd for the row gestures), the remote
+ * channel, the locale, and the right-Sidebar faces (tab-type registry + the
+ * navigation service the turn card's outside-workspace gesture opens pages
+ * through). The
+ * `remote.filePreview` namespace is deliberately NOT an inject: this plugin
+ * both mounts the namespace (through `$mount` below) and consumes it, and the
+ * Cordis property proxy only resolves services declared in `inject` or
+ * provided by an ancestor fiber. Declaring it would deadlock the loader (the
+ * fiber waits for the service, which only this apply's `$mount` can provide);
+ * the property proxy cannot see the sibling namespace fiber `$mount` spawns.
+ * The mount is awaited and the namespace is then read back from the global
+ * store with `ctx.get`, which resolves any active provider in the same
+ * isolation scope. */
+export declare const inject: string[];
+/**
+ * Client plugin body: mount the Remote, register the dictionaries, the tab
+ * type, its body, and the per-turn file row.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: Context): Promise<() => Promise<void>>;
+/**
+ * Install every visible file-preview client surface after a successful host
+ * handshake. Tests can drive this boundary directly; disposal removes the
+ * dictionaries, the tab type/body, the turn row and its deliverables shadow,
+ * and the mention wrapper.
+ */
+export declare function installFilePreviewSurfaces(ctx: Context, remote: FilePreviewRemote): () => Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/index.js

@@ -0,0 +1,238 @@
+import { fileAddressFor, resolveWorkspacePath } from '@deepseek-ai/dsh-util-workspace-path';
+import { writeClipboard } from '@deepseek-ai/dsh-client-ui-primitives';
+import filePreviewRemote from '@khorsheed/dsh-file-preview/remote';
+import { FilePreviewTab } from './FilePreviewTab.js';
+import { TurnFileRow } from './TurnFileRow.js';
+import { createFilePreviewStore } from './file-preview-store.js';
+import { FILE_PREVIEW_ID, FILE_PREVIEW_KIND, filePreviewDefinition } from './definition.js';
+import { basename } from './path-utils.js';
+import { en, NS, zh } from './locales.js';
+import { wrapChatFileMentions } from './mentions-wrap.js';
+import { OpenInAppProbe, pickFileManager, pickIde } from './open-in-app.js';
+import { parentPath } from './path-utils.js';
+import { createTurnFilesLoader } from './turn-files-cache.js';
+import { selectTurnFiles } from './turn-files.js';
+export { DiffHistory } from './DiffHistory.js';
+export { FilePreviewTab, TurnFileRow };
+export { FILE_PREVIEW_ID, FILE_PREVIEW_KIND };
+/** The official deliverables card's turnTail cell id — the shadow target. */
+const DELIVERABLES_TURN_ENTRY = '@deepseek-ai/dsh-client-ui-deliverables';
+/**
+ * The deliverables shadow: the empty body that wins the official card's list
+ * cell at a lower priority, so the present/changes cards stop rendering while
+ * the official registration (and the child slot it declares) stays live.
+ */
+function DeliverablesShadow() {
+    return null;
+}
+/** Required services: slots, sessions (cwd for the row gestures), the remote
+ * channel, the locale, and the right-Sidebar faces (tab-type registry + the
+ * navigation service the turn card's outside-workspace gesture opens pages
+ * through). The
+ * `remote.filePreview` namespace is deliberately NOT an inject: this plugin
+ * both mounts the namespace (through `$mount` below) and consumes it, and the
+ * Cordis property proxy only resolves services declared in `inject` or
+ * provided by an ancestor fiber. Declaring it would deadlock the loader (the
+ * fiber waits for the service, which only this apply's `$mount` can provide);
+ * the property proxy cannot see the sibling namespace fiber `$mount` spawns.
+ * The mount is awaited and the namespace is then read back from the global
+ * store with `ctx.get`, which resolves any active provider in the same
+ * isolation scope. */
+export const inject = ['slots', 'sessions', 'remote', 'locale', 'sidebarRight', 'sidebarRightTabs'];
+/**
+ * Client plugin body: mount the Remote, register the dictionaries, the tab
+ * type, its body, and the per-turn file row.
+ * @param ctx - client root context.
+ */
+export async function apply(ctx) {
+    const disposers = [];
+    try {
+        disposers.push(await ctx.remote.$mount(filePreviewRemote));
+    }
+    catch (error) {
+        // A duplicate descriptor is a composition error. The capability probe
+        // below still decides whether any visible surface may exist.
+        /* v8 ignore next -- double-mount is a composition error, not a runtime path */
+        ctx.logger.error(error);
+    }
+    // The namespace is registered by $mount above; `ctx.remote.filePreview`
+    // cannot see it (the property proxy walks the fiber chain, and the namespace
+    // lives in the sibling fiber $mount spawned), so read it back from the global
+    // store once the mount has settled and hand the concrete handle to the
+    // inject closures, so a lazy `ctx.remote.filePreview` read at call time
+    // never trips the property proxy.
+    const remote = ctx.get('remote.filePreview');
+    if (remote === undefined) {
+        return async () => { await Promise.all(disposers.map(dispose => dispose())); };
+    }
+    try {
+        const capabilities = await remote.capabilities();
+        if (!capabilities.ok || capabilities.value.protocolVersion !== 1) {
+            return async () => { await Promise.all(disposers.map(dispose => dispose())); };
+        }
+    }
+    catch {
+        return async () => { await Promise.all(disposers.map(dispose => dispose())); };
+    }
+    const uninstall = installFilePreviewSurfaces(ctx, remote);
+    return async () => {
+        await uninstall();
+        await Promise.all(disposers.map(dispose => dispose()));
+    };
+}
+/**
+ * Install every visible file-preview client surface after a successful host
+ * handshake. Tests can drive this boundary directly; disposal removes the
+ * dictionaries, the tab type/body, the turn row and its deliverables shadow,
+ * and the mention wrapper.
+ */
+export function installFilePreviewSurfaces(ctx, remote) {
+    const disposers = [];
+    disposers.push(ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'file-preview: dictionaries'));
+    const t = ctx.locale.bind(NS);
+    // The turn card's host-fed loader: one RPC warms every turn rendered so far
+    // (the host returns the whole per-turn map, cached by the log watermark).
+    const turnFilesLoader = createTurnFilesLoader(remote);
+    // S1 tail: route prose-mention opens into the sidebar too. The wrap is
+    // in-place on ui-deliverables' provided object (see mentions-wrap.ts for
+    // why not provide/set). Ordering cannot ride the package edge alone — cordis
+    // only re-wakes fibers that DECLARE the service in `inject`
+    // (vendor/cordis reflect.ts notify), so a one-shot `ctx.get` here races the
+    // deliverables fiber's provide. A nested plugin whose inject names
+    // 'chatFileMentions' stays pending until the service appears (and re-runs on
+    // HMR re-provide, re-wrapping); in compositions without ui-deliverables it
+    // simply never activates, without blocking this plugin.
+    const mentionsFiber = ctx.plugin({
+        name: '@khorsheed/dsh-file-preview/mentions-wrap',
+        inject: ['chatFileMentions'],
+        apply: (sub) => {
+            wrapChatFileMentions(sub.chatFileMentions, {
+                // Mentions open at the canonical file address — the same
+                // `dsh-resource://file/session/<id>/<path>` content id the
+                // deliverables card's open resolves to, so one file is one tab (the
+                // page address `sidebar://file-preview` would mint a second tab for
+                // the same file). Our type claims the renderable ones on both host
+                // lines; the rest fall through to the official document tab. A throw
+                // (no mounted sidebar surface) falls back to the owner's openFile
+                // inside the wrap.
+                open: (sessionId, path) => {
+                    ctx.sidebarRight.openResource(fileAddressFor(sessionId, sessionCwd(sessionId), path));
+                },
+                label: (path) => t('mention.open', { name: basename(path) }),
+            });
+        },
+    });
+    disposers.push(() => mentionsFiber.dispose());
+    // Row gestures: copy always works (clipboard needs no host capability);
+    // folder/IDE gestures key off the once-per-page open-in-app probe — a host
+    // without the route (or a failed probe) reads as "no apps" and the buttons
+    // stay hidden. Folder open keeps the old drawer's semantics: reveal the
+    // file selected in the host file manager (host Remote), falling back to the
+    // official open route on the parent folder. IDE open is file-exact, which
+    // the official route refuses (directories only) — it rides the host half's
+    // `openExternal` instead.
+    const sessions = ctx.sessions;
+    const openInApps = new OpenInAppProbe();
+    const sessionCwd = (sessionId) => sessions.list.getSnapshot().byId[sessionId]?.cwd;
+    const revealFolder = (sessionId, path) => {
+        const resolved = resolveWorkspacePath(sessionCwd(sessionId), path);
+        const fallback = () => {
+            const fileManager = pickFileManager(openInApps.apps.getSnapshot() ?? []);
+            if (fileManager !== undefined)
+                void openInApps.open(fileManager, parentPath(resolved) || '.');
+        };
+        void remote.reveal(sessionId, path).then((result) => {
+            if (result.ok && result.value.revealed)
+                return;
+            fallback();
+        }).catch(fallback);
+    };
+    const openInIde = (sessionId, path, app) => {
+        const ide = app ?? pickIde(openInApps.apps.getSnapshot() ?? []);
+        if (ide === undefined)
+            return;
+        void remote.openExternal(sessionId, path, ide).catch(() => {
+            // A launch failure stays silent in the row; the native app surfaces its
+            // own error dialog when the path is unusable.
+        });
+    };
+    // Stage one of the right-Sidebar registration: the tab type (guide entry
+    // PLUS address claims — `dsh-resource://file/**` for every session-scoped
+    // path the preview stack renders; see definition.tsx). Unconditional on
+    // both host lines: the default 'extension' band outranks the official
+    // document tab's 'fallback'.
+    disposers.push(ctx.effect(() => ctx.sidebarRightTabs.register(filePreviewDefinition(t)), 'file-preview: tab type'));
+    // Stage two: the body under the type's id in the keyed pane seat.
+    disposers.push(ctx.effect(() => ctx.slots.inject('sidebar.right.pane.tab', () => ctx.slots.register({
+        name: 'sidebar.right.pane.tab',
+        key: FILE_PREVIEW_ID,
+        locale: NS,
+        store: createFilePreviewStore,
+        inject: (sessionId) => ({
+            listFiles: (sid) => remote.list(sid),
+            readFile: (sid, path) => remote.read(sid, path),
+            copyPath: (path) => writeClipboard(resolveWorkspacePath(sessionCwd(sessionId), path)),
+            revealFolder: (path) => { revealFolder(sessionId, path); },
+            openInIde: (path, app) => { openInIde(sessionId, path, app); },
+            loadOpenInApps: () => { void openInApps.load(); },
+            hooks: { openInApps: openInApps.apps },
+        }),
+    }, FilePreviewTab)), 'file-preview: tab body'));
+    // The turn card. Probe the declared slot kind inside inject (the callback
+    // only runs once the slot exists): a 0.1.6-alpha.2+ host declares a LIST —
+    // register a plain entry under the package id, plus the deliverables shadow
+    // (the convergence, user decision 2026-09-24: the official present card
+    // duplicates this row with a model-curated subset and the official changes
+    // card is memory-resident, so only this row renders). The shadow is the
+    // slot system's first-class mechanism, not a DOM hack: one cell (the
+    // official entry's id), two entries at distinct priorities, the lowest
+    // renders (ui-slots SlotCore.register pins the rule — a same-id
+    // same-priority registration throws with "register at a different priority
+    // to shadow it", and entriesOfSlot projects each cell to its lowest live
+    // entry). The official entry stays registered — its declared
+    // `deliverables.file.actions` child slot survives for ui-open-in-app's
+    // contributions — it just never renders. The row itself returns null until
+    // its fetch settles. A 0.1.5 host declares the election CHAIN — keep the
+    // old preemptive shape (select claims every turn; priority -1 elects
+    // ascending, ahead of the official entry's default 0). The alpha.2
+    // KindOptions for this key carry no chain fields, so the chain-branch call
+    // is duck-typed through `never` (the escape the spec bench already uses);
+    // the list branch stays fully typed and is what checks TurnFileRow's props
+    // contract.
+    disposers.push(ctx.slots.inject('conversation.chat.turnTail', () => {
+        const injectRow = () => ({
+            turnFiles: (sessionId, turn) => turnFilesLoader(sessionId, turn),
+        });
+        const spec = ctx.slots.spec('conversation.chat.turnTail');
+        if (spec?.kind === 'chain') {
+            return ctx.slots.register({
+                name: 'conversation.chat.turnTail',
+                priority: -1,
+                select: selectTurnFiles,
+                locale: NS,
+                inject: injectRow,
+            }, TurnFileRow);
+        }
+        const row = ctx.slots.register({
+            name: 'conversation.chat.turnTail',
+            id: FILE_PREVIEW_ID,
+            locale: NS,
+            inject: injectRow,
+        }, TurnFileRow);
+        // Lower than the official entry's default 0, so the empty body wins the
+        // cell; a same-priority second registration would throw instead.
+        const shadow = ctx.slots.register({
+            name: 'conversation.chat.turnTail',
+            id: DELIVERABLES_TURN_ENTRY,
+            priority: -1,
+        }, DeliverablesShadow);
+        return () => {
+            row();
+            shadow();
+        };
+    }));
+    return async () => {
+        for (const dispose of disposers.reverse())
+            await dispose();
+    };
+}

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

@@ -0,0 +1,16 @@
+/** `filePreview` namespace dictionaries (right-Sidebar tab + document renderer + turn card copy). */
+/** Dictionary namespace owned by this plugin. */
+export declare const NS = "filePreview";
+/** The file-preview dictionary key set (the source of truth for both locales). */
+export type FilePreviewKey = 'open' | 'view.search.placeholder' | 'view.search.noMatch' | 'preview.search.placeholder' | 'preview.search.noMatch' | 'preview.search.prev' | 'preview.search.next' | 'preview.htmlToggle' | 'preview.htmlSource' | 'preview.htmlRender' | 'preview.htmlScript' | 'preview.htmlScriptStop' | 'preview.scriptConfirm' | 'preview.scriptRun' | 'preview.scriptCancel' | 'preview.slowHint' | 'preview.fullscreen' | 'preview.exitFullscreen' | 'preview.staticHint' | 'turn.count' | 'json.copyValue' | 'json.copyJson' | 'json.copyPath' | 'json.copyPrettyJson' | 'json.copyCompactJson' | 'json.copied' | 'json.copyFailed' | 'json.collapseNode' | 'json.expandNode' | 'json.copyButtonTitle' | 'json.treeLabel' | 'markdown.copy' | 'markdown.copied' | 'markdown.footnotes' | 'diff.copy' | 'diff.copied' | 'diff.collapse' | 'diff.collapseAria' | 'diff.expand' | 'diff.expandAria' | 'diff.files' | 'diff.code' | 'diff.wrap' | 'diff.unwrap' | 'guide.title' | 'guide.description' | 'list.empty' | 'list.error' | 'list.loading' | 'list.outsideWorkspace' | 'list.refresh' | 'history.empty' | 'history.step' | 'history.step.count' | 'history.step.latest' | 'history.step.older' | 'history.step.newer' | 'detail.back' | 'mention.open' | 'action.chooseIDE' | 'action.copy' | 'action.copied' | 'action.copyPath' | 'action.openFolder' | 'action.openIDE' | 'action.reload' | 'detail.content' | 'detail.deleted' | 'detail.diff' | 'detail.noSelection' | 'detail.preview' | 'detail.source' | 'local.binary' | 'local.noSelection' | 'local.tooLarge' | 'local.unreadable' | 'search.hit' | 'search.next' | 'search.noMatch' | 'search.placeholder' | 'search.prev' | 'state.error' | 'state.loading';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The file-preview tab, document renderer, and turn card copy. */
+        'filePreview': FilePreviewKey;
+    }
+}
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: Record<FilePreviewKey, string>;
+/** English dictionary. */
+export declare const en: Record<FilePreviewKey, string>;
+//# sourceMappingURL=locales.d.ts.map