@vibedev-si/dsh-media-viewer 0.1.2 → 0.2.0

package/README.md

@@ -13,16 +13,34 @@
 | 音频 | mp3 / wav / m4a / flac 等；实时频谱；倍速、循环 |
 | HTML | 默认**允许脚本**；相对路径的 CSS / JS / 图片 / 视频 / `fetch` 都能加载；预览 / 源码切换；手机、平板、桌面宽度；脚本开关 |
 | 媒体画廊 | 缩略图网格；按视频 / 音频 / 图片 / 网页筛选、搜索、排序；可包含子文件夹；点开是带上一个 / 下一个（← →）的灯箱 |
+| 加入画布 | 画廊里点「多选」，勾选图片 / 视频 / 音频（Shift 连选、全选），点「加入画布」放进**影视工作台**当前打开的画布；没打开时先在侧栏打开它 |
 
-画廊在右侧栏的 **+ 菜单**里叫「媒体画廊」；每个播放器工具栏里的「画廊」按钮会直接打开它所在的文件夹。
+**在哪里打开**
 
-## 本版新增（0.1.2）
+- 在文件树里点开视频、音频或网页文件，就用本插件的播放器打开（文件预览顶部的切换菜单里可以换回内置预览）。
+- 媒体画廊：右侧栏「开始」页的「媒体画廊」、文件树顶部的「媒体画廊」按钮（打开当前文件夹），或文件预览顶部的「画廊」按钮（打开文件所在的文件夹）。
 
-新增「组件」入口：在预览工具栏里可直接打开 **VibeDev 插件中心**，了解或补齐影视工作台与 VibeDev 账号插件（打不开插件中心时会给出可复制的包名）；已安装或应用内置的组件不会重复推荐。
+「加入画布」需要同时启用影视工作台插件（`dsh-film-studio`）：文件由工作台复制进项目的 `assets/`，在画布中央排成节点，整批一次撤销。两个插件只通过一个页面事件 `vibedev-film:add-media` 联系，没装工作台时画廊会直接提示。
+
+## 本版变更（0.2.0）
+
+- **不再依赖 `dsh-better-sidebar`**：预览器、画廊和入口都直接用 DSH 自带的右侧栏（DSH 0.2.1-alpha.2 及以后），应用更新不会再因为第三方插件没跟上而失效。
+  - 视频、音频、HTML 注册为 DSH 的文件预览；画廊是右侧栏的一个页面。
+  - 装了 `dsh-better-sidebar` 时，播放器也会注册进它的编辑器（它会先接管所有文件），画廊仍是同一个。
+  - 宿主侧只需要 Web 服务和会话，受信主机从 DSH 新旧两种启动服务中按实际提供的读取（DSH 0.2.1-alpha.2 把 `webRuntime` 改名为 `webStartup` 后，0.1.x 无法加载）。
+- **画廊多选与加入画布**（原 0.1.4 未单独发布，并入本版）。
+- **更稳的播放**：
+  - 视频缩略图截取一帧后就释放播放器；
+  - 播放请求分段返回、不进浏览器缓存。
+  - 页面上视频多时，浏览器每个主机只有 6 个连接，不再出现后面的视频一直转圈、不发请求的情况。
+
+## 0.1.3
+
+撤回了 0.1.2 加进预览工具栏和画廊底部的「组件 / 插件中心」入口，它影响了侧栏观感，等重新设计后再考虑；预览、画廊与安全说明不受影响。
 
 ## 安装
 
-**前置依赖：[`dsh-better-sidebar`](https://www.npmjs.com/package/dsh-better-sidebar)**（≥ 0.24.0）。它接管了右侧栏的文件打开，本插件通过它的 `registerFileViewer` / `registerTab` 接入。没装它，本插件不会生效。
+需要 DSH 0.2.1-alpha.2 或更新版本（VibeDev Next 已满足）。不需要其他插件；`dsh-better-sidebar` 可装可不装。
 
 在 VibeDev / DSH 的插件管理里按包名 `@vibedev-si/dsh-media-viewer` 安装即可，或用命令行：
 
@@ -32,16 +50,11 @@ dsh plugin --profile <你的 profile 名> add @vibedev-si/dsh-media-viewer
 
 安装后**刷新页面**。
 
-> **从旧包名迁移**：本插件原先以无作用域的 `dsh-media-viewer` 发布（0.1.0），现已迁到官方作用域 `@vibedev-si/dsh-media-viewer`，旧包名已标记弃用。已装旧包的用户请卸载后改装新包名；功能与代码完全相同。
-
-## 为什么需要它
-
-`dsh-better-sidebar` 内置的 `/sidebar/file`、`/sidebar/html` 路由：
+> **从旧包名迁移**：本插件原先以无作用域的 `dsh-media-viewer` 发布（0.1.0），现已迁到官方作用域 `@vibedev-si/dsh-media-viewer`，旧包名已标记弃用。已装旧包的用户请卸载后改装新包名。
 
-- 有 **20MB 上限**，整文件读入内存，不支持 HTTP Range，所以大视频打不开、也不能拖进度条；
-- 安全围栏会拒绝沙箱 iframe 里的子资源请求（它们带 `Sec-Fetch-Site: cross-site`），所以带样式、脚本、视频的 HTML 只能加载一半。
+## 为什么自带 `/mp` 路由
 
-本插件自带 `/mp/*` 路由解决这两点，并在沙箱里保持对 GUI 的隔离。
+DSH 自带预览读取整个文件；`dsh-better-sidebar` 的 `/sidebar/file`、`/sidebar/html` 有 20MB 上限、不支持 HTTP Range，安全围栏还会拒绝沙箱 iframe 里的子资源请求。本插件自带 `/mp/*` 路由：大视频可以流式播放、拖进度条，带样式、脚本、视频的 HTML 能完整加载，并在沙箱里保持对 GUI 的隔离。
 
 ## 安全
 
@@ -63,22 +76,21 @@ dsh plugin --profile <你的 profile 名> add @vibedev-si/dsh-media-viewer
 ## 开发
 
 ```sh
-npm test    # host 路由：Range、越界、符号链接、Host 伪造、沙箱子资源
+npm test    # host 路由（Range、分段、越界、符号链接、Host 伪造、沙箱子资源）与宿主接口登记
 ```
 
 client 是无需构建的纯 JS（`client.js`），host 是 `index.js`，没有构建步骤。
 
 ## English
 
-**@vibedev-si/dsh-media-viewer** adds inline previews to the [`dsh-better-sidebar`](https://www.npmjs.com/package/dsh-better-sidebar) right column, which requires it (≥ 0.24.0):
+**@vibedev-si/dsh-media-viewer** adds inline previews to the DSH right sidebar (DSH 0.2.1-alpha.2 or later) and needs no other plugin:
 
 - **Video** — mp4 / webm / mov / mkv…, seekable, playback speed, loop, no file-size cap (HTTP Range streaming).
 - **Audio** — mp3 / wav / m4a / flac…, live spectrum, playback speed, loop.
 - **HTML** — scripts allowed by default; relative CSS / JS / images / video / `fetch()` all load; preview ⇄ source, phone / tablet / desktop widths, script toggle. Runs in an opaque-origin sandboxed iframe, so a previewed page cannot reach the GUI.
-- **Media gallery** — thumbnail grid for a folder with type filters, search, sort, optional recursion, and a lightbox with ← / → navigation.
-- **Related components (0.1.2)** — a 「组件」 entry in the preview toolbar opens the **VibeDev plugin centre** from the sidebar to learn about or add the film workbench and the VibeDev account plugin (and falls back to a copyable package name); components already installed or shipped by the app are never recommended again.
+- **Media gallery** — a right-sidebar page: thumbnail grid for a folder with type filters, search, sort, optional recursion, a lightbox with ← / → navigation, and multi-select to add media to the Film Studio canvas.
 
-Why it exists: the built-in `/sidebar/file` and `/sidebar/html` routes cap files at 20 MB, read them fully into memory, have no Range support, and their fence rejects the `cross-site` sub-resource requests a sandboxed iframe makes. This plugin ships its own `/mp/*` routes instead. Install it by package name from your DSH plugin manager, or `dsh plugin --profile <name> add @vibedev-si/dsh-media-viewer`, then reload the page.
+0.2.0 stands on the host's own surfaces (document previews, the right sidebar's page registry, the file tree and document toolbars) instead of `dsh-better-sidebar`; when that plugin is installed the players also register inside its editor, which claims files first. Install it by package name from your DSH plugin manager, or `dsh plugin --profile <name> add @vibedev-si/dsh-media-viewer`, then reload the page.
 
 ## License
 

package/client.js

@@ -1,9 +1,10 @@
 /*!
  * dsh-media-viewer — client half (browser bundle, no build step).
  *
- * Registers with dsh-better-sidebar through `ctx.betterSidebar`:
- *   - file viewers: video (mp4/webm/mov/...), audio (mp3/wav/...), html
- *   - a tab: "媒体画廊", a thumbnail grid of the media in a folder
+ * Registers on the host's own right sidebar (DSH 0.2.1-alpha.2 and later):
+ *   - document previews: video (mp4/webm/mov/...), audio (mp3/wav/...), html
+ *   - a page: "媒体画廊", a thumbnail grid of the media in a folder
+ * and, when dsh-better-sidebar is installed, the same viewers and tab inside it.
  *
  * Bundle format: the official DSH client-bundle shape, a CommonJS-style
  * factory registered through window.__ModuleLoader__.load. `react` is resolved
@@ -59,6 +60,15 @@ window.__ModuleLoader__.load({
         segs.map(encodeURIComponent).join("/") + (query ? "?" + query : "");
     }
 
+    /**
+     * The URL a player streams. A document preview passes the file's version as `nonce`: the browser shares one media
+     * resource per URL within a page, and one held by a gallery thumbnail or the lightbox can leave a second player of
+     * the same file waiting with no request at all.
+     */
+    function playUrl(props, abs) {
+      return fileUrl(props.scope, abs, props.nonce ? "v=" + encodeURIComponent(props.nonce) : "");
+    }
+
     function fmtSize(n) {
       if (n == null) return "";
       if (n < 1024) return n + " B";
@@ -158,11 +168,8 @@ window.__ModuleLoader__.load({
         h("rect", { key: "d", x: 9, y: 9, width: 5, height: 5, rx: 1, stroke: "currentColor", strokeWidth: 1.5 }),
       ]);
     }
-    function IconTools(size) {
-      return svg(size, [
-        h("rect", { key: "a", x: 2, y: 2, width: 12, height: 12, rx: 3, stroke: "currentColor", strokeWidth: 1.5 }),
-        pathEl("M8 5.4v5.2M5.4 8h5.2", { key: "b" }),
-      ]);
+    function IconCheck(size) {
+      return svg(size, [pathEl("m3.5 8.3 2.9 2.9 6.1-6.4", { key: "a" })]);
     }
     function kindIcon(kind, size) {
       return kind === "video" ? IconVideo(size) : kind === "audio" ? IconAudio(size) : kind === "html" ? IconHtml(size) : IconImage(size);
@@ -180,13 +187,18 @@ window.__ModuleLoader__.load({
       ]);
     }
 
+    /**
+     * Open the gallery on a file's folder. The host's own right sidebar does it (a native page tab); a view hosted by
+     * dsh-better-sidebar keeps opening its tab there, as before 0.2.0.
+     */
     function openGallery(props, abs) {
       try {
-        props.ctx.betterSidebar.openTab({ type: "mp:gallery", path: dirName(abs), title: baseName(dirName(abs)) || "媒体画廊" }, props.scope);
+        if (typeof props.openGallery === "function") props.openGallery(dirName(abs));
+        else props.ctx.betterSidebar.openTab({ type: "mp:gallery", path: dirName(abs), title: baseName(dirName(abs)) || "媒体画廊" }, props.scope);
       } catch (e) { console.error("[dsh-media-viewer] open gallery failed", e); }
     }
 
-    function CommonActions(props, abs, url, toolsOpen, onTools) {
+    function CommonActions(props, abs, url) {
       var out = [
         h("a", { key: "new", href: url, target: "_blank", rel: "noopener", style: btn(), title: "在新窗口打开" }, "新窗口"),
         h("a", { key: "dl", href: fileUrl(props.scope, abs, "download=1"), download: baseName(abs), style: btn(), title: "下载原文件" }, "下载"),
@@ -194,9 +206,6 @@ window.__ModuleLoader__.load({
       if (!props.hideGallery) {
         out.push(h(Btn, { key: "gal", title: "浏览所在文件夹的全部媒体", onClick: function () { openGallery(props, abs); } }, [IconGrid(12), "画廊"]));
       }
-      if (typeof onTools === "function") {
-        out.push(h(Btn, { key: "tools", active: toolsOpen === true, title: "相关组件与插件中心", onClick: onTools }, [IconTools(12), "组件"]));
-      }
       return out;
     }
 
@@ -209,326 +218,30 @@ window.__ModuleLoader__.load({
     }
 
     function Shell(p) {
-      var kids = p.children ? (Array.isArray(p.children) ? p.children.slice() : [p.children]) : [];
-      if (p.tools) kids.push(p.tools);
       return h("div", {
-        style: { display: "flex", flexDirection: "column", gap: "8px", padding: "10px", minWidth: 0, minHeight: 0, height: "100%", boxSizing: "border-box" },
-      }, kids);
-    }
-
-    // ── companion components (the plugin centre is the way to the rest) ─────
-    //
-    // What the Host actually has comes from its plugin inventory — a bundle the profile
-    // installed, or one the application ships itself. Every service below is read
-    // optionally and strictly, so a Host without a plugin manager, a panel layout, or the
-    // plugin navigation contract keeps this viewer working and simply shows the manual
-    // spec. Nothing here installs anything: the centre and the Plugins page own every
-    // install, approval and progress step, and nothing is read before a surface is opened.
-
-    /** The VibeDev components by package name; the centre is the way to all of them. */
-    var SUITE = { account: "@vibedev-si/dsh-vibedev", center: "@vibedev-si/dsh-ecosystem", film: "dsh-film" };
-    /** The main panel the VibeDev plugin centre registers its page under. */
-    var CENTER_PANEL = "vibedev-center";
-    /** The package a person can add on the Plugins page when nothing can open the centre. */
-    var CENTER_SPEC = SUITE.center;
-    /**
-     * The components this viewer's own work leans on, in the order the card lists them.
-     * A bundle already installed or shipped by the app is never named (see `bundlePresent`),
-     * and the viewer never recommends itself.
-     */
-    var COMPANIONS = [
-      { package: SUITE.account, line: "VibeDev 账号：用余额生成图片、视频和音频，模型请求走 VibeDev 网关。" },
-      { package: SUITE.film, line: "影视工作台：剧本、分镜画布和导演台，把这个文件夹里的媒体排成片子。" },
-    ];
-    /** The card's own copy, in the one language this bundle's UI uses. */
-    var SUITE_COPY = {
-      missingTitle: "相关组件",
-      missingIntro: "这些组件和右侧栏预览配合使用，装好后出现在它们各自的页面里。",
-      toolsTitle: "插件中心",
-      toolsIntro: "插件中心里可以浏览其余组件。",
-      keep: "这里只做提示：不会自动安装，也不会改动已装的东西；安装与授权都在插件中心里完成。",
-      open: "打开插件中心",
-      manual: "打不开插件中心时，可在「插件」页按包名安装：",
-      copy: "复制包名",
-      copied: "已复制",
-      tools: "组件",
-    };
-
-    /** A value read as a record, without trusting its declared type. */
-    function asRecord(v) { return typeof v === "object" && v !== null ? v : undefined; }
-
-    /** One property of a service, read without letting a hostile getter throw into the viewer. */
-    function safeGet(target, name) {
-      var record = asRecord(target);
-      if (record === undefined) return undefined;
-      try { return record[name]; } catch (e) { return undefined; }
-    }
-
-    /** One optional service, read strictly: absent (never throwing) on a Host that does not have it. */
-    function serviceOf(ctx, name) {
-      if (!ctx || typeof ctx.get !== "function") return undefined;
-      try { return ctx.get(name); } catch (e) { return undefined; }
-    }
-
-    /** The optional services the card uses, from the strict store first and the property proxy second. */
-    function suiteServices(ctx) {
-      var remote = asRecord(serviceOf(ctx, "remote") || safeGet(ctx, "remote"));
-      return {
-        manager: asRecord(serviceOf(ctx, "remote.pluginManager") || safeGet(remote, "pluginManager")),
-        slots: asRecord(serviceOf(ctx, "slots") || safeGet(ctx, "slots")),
-        layout: asRecord(serviceOf(ctx, "layout") || safeGet(ctx, "layout")),
-        navigation: asRecord(serviceOf(ctx, "pluginNavigation") || safeGet(ctx, "pluginNavigation")),
-        remote: remote,
-      };
-    }
-
-    /** Whether the Host already has a bundle: the profile installed it, or the application provides it itself. */
-    function bundlePresent(bundle) {
-      return bundle.installed === true || (bundle.removable === false && !bundle.source);
-    }
-
-    /**
-     * The present package names of one inventory answer, or undefined when the answer is not a
-     * readable list. An answer this cannot read is never read as "nothing is present": a refusal
-     * envelope, another shape, or a missing value means the caller knows nothing, not that every
-     * component is missing.
-     */
-    function presentFrom(answer) {
-      var record = asRecord(answer);
-      if (record === undefined || record.ok === false) return undefined;
-      if (!Array.isArray(record.value)) return undefined;
-      var names = [];
-      for (var i = 0; i < record.value.length; i++) {
-        var bundle = asRecord(record.value[i]);
-        if (!bundle || !bundlePresent(bundle)) continue;
-        if (typeof bundle.name === "string" && bundle.name !== "" && names.indexOf(bundle.name) < 0) names.push(bundle.name);
-      }
-      return names;
-    }
-
-    /**
-     * Read the Host's plugin inventory once. A manager that cannot answer — absent, throwing,
-     * rejecting, or answering an envelope that is not a readable list — is not an inventory of
-     * nothing: `ok: false` makes the card offer the centre and claim no component is missing.
-     */
-    function readPresence(ctx) {
-      var manager = suiteServices(ctx).manager;
-      var list = safeGet(manager, "listBundles");
-      if (typeof list !== "function") return Promise.resolve({ ok: false, present: [] });
-      try {
-        return Promise.resolve(list.call(manager)).then(
-          function (answer) {
-            var present = presentFrom(answer);
-            return present === undefined ? { ok: false, present: [] } : { ok: true, present: present };
-          },
-          function () { return { ok: false, present: [] }; });
-      } catch (e) {
-        return Promise.resolve({ ok: false, present: [] });
-      }
-    }
-
-    /** Hear about installs, removals and activations; a Host without the event bus returns a no-op. */
-    function observePresence(ctx, listener) {
-      var remote = suiteServices(ctx).remote;
-      var on = safeGet(remote, "$on");
-      if (typeof on !== "function") return function () {};
-      try {
-        var off = on.call(remote, "plugin-manager/changed", listener);
-        return typeof off === "function" ? function () { off(); } : function () {};
-      } catch (e) {
-        return function () {};
-      }
-    }
-
-    /**
-     * The centre's main panel, where this Host registered one. A slots entry keeps its
-     * identity in `options` (`options.key` is the panel id the layout selects); older
-     * shapes kept `key`/`id` at the top level, which is still read as a fallback.
-     */
-    function centerPanel(ctx) {
-      var slots = suiteServices(ctx).slots;
-      var entries = safeGet(slots, "entries");
-      if (typeof entries !== "function") return undefined;
-      var listed;
-      try { listed = entries.call(slots, "main"); } catch (e) { return undefined; }
-      if (!Array.isArray(listed)) return undefined;
-      for (var i = 0; i < listed.length; i++) {
-        var record = asRecord(listed[i]);
-        var options = asRecord(safeGet(record, "options"));
-        var key = options ? (safeGet(options, "key") !== undefined ? safeGet(options, "key") : safeGet(options, "id"))
-          : (record ? (safeGet(record, "key") !== undefined ? safeGet(record, "key") : safeGet(record, "id")) : undefined);
-        if (key === CENTER_PANEL) return CENTER_PANEL;
-      }
-      return undefined;
-    }
-
-    /**
-     * Send the person to the centre, or to the Host's own way of installing it. A panel that
-     * is gone, a layout that refuses, and a missing navigation contract each fall through to
-     * the next, and the last answer is the spec a person can paste into the Plugins page.
-     */
-    function openCenter(ctx) {
-      var services = suiteServices(ctx);
-      var panel = centerPanel(ctx);
-      var selectPanel = safeGet(services.layout, "selectPanel");
-      if (panel !== undefined && typeof selectPanel === "function") {
-        try { selectPanel.call(services.layout, panel); return { kind: "center" }; } catch (e) { /* the panel is gone */ }
-      }
-      var navigation = services.navigation;
-      var openBundle = safeGet(navigation, "openBundle");
-      if (typeof openBundle === "function") {
-        try { openBundle.call(navigation, SUITE.center); return { kind: "plugins" }; } catch (e) { /* no Plugins panel here */ }
-      }
-      var openInstall = safeGet(navigation, "openInstall");
-      if (typeof openInstall === "function") {
-        try { openInstall.call(navigation, { spec: CENTER_SPEC }); return { kind: "plugins" }; } catch (e) { /* nothing could open */ }
-      }
-      return { kind: "manual", spec: CENTER_SPEC };
-    }
-
-    /** Which of `wanted` this Host does not have yet, in the order the surface lists them. */
-    function missingFrom(present, wanted) {
-      return wanted.filter(function (want) { return present.indexOf(want.package) < 0; });
-    }
-
-    /** What the card says: the absent components, or the one way to the rest. An unreadable inventory claims nothing. */
-    function suiteHint(read, wanted) {
-      if (!read.ok) return { kind: "tools", missing: [] };
-      var missing = missingFrom(read.present, wanted);
-      if (missing.length === 0) return { kind: "tools", missing: [] };
-      return {
-        kind: "missing",
-        missing: missing.map(function (want) { return { package: want.package, line: want.line }; }),
-      };
-    }
-
-    /** Write text through the browser's clipboard, where the page has one. */
-    function writeClipboard(text) {
-      var clipboard = typeof navigator !== "undefined" && navigator ? safeGet(navigator, "clipboard") : undefined;
-      var write = safeGet(clipboard, "writeText");
-      if (typeof write !== "function") return Promise.resolve(false);
-      try {
-        return Promise.resolve(write.call(clipboard, text)).then(function () { return true; }, function () { return false; });
-      } catch (e) {
-        return Promise.resolve(false);
-      }
-    }
-
-    /** One read of what this Host has, shared by every card this bundle renders. */
-    function createSuiteStore(ctx, wanted) {
-      var snapshot = { read: false, found: { ok: false, present: [] }, hint: { kind: "tools", missing: [] } };
-      var listeners = [];
-      function publish(next) {
-        snapshot = next;
-        var copy = listeners.slice();
-        for (var i = 0; i < copy.length; i++) copy[i]();
-      }
-      function read() {
-        return readPresence(ctx).then(function (found) {
-          publish({ read: true, found: found, hint: suiteHint(found, wanted) });
-        });
-      }
-      return {
-        subscribe: function (listener) {
-          listeners.push(listener);
-          return function () {
-            var at = listeners.indexOf(listener);
-            if (at >= 0) listeners.splice(at, 1);
-          };
-        },
-        getSnapshot: function () { return snapshot; },
-        open: function () { return openCenter(ctx); },
-        copy: writeClipboard,
-        /** Start the first read and every later refresh; the returned disposer releases both. */
-        start: function () {
-          void read();
-          return observePresence(ctx, function () { void read(); });
-        },
-      };
-    }
-
-    /**
-     * The companion components this Host lacks, and the one quiet way into the plugin centre.
-     * It renders nothing until its own read settled, installs nothing, and opens nothing by
-     * itself: every line here is a statement about the Host, and the button is the only action.
-     */
-    function SuiteCard(props) {
-      var store = useMemo(function () {
-        return props.store || createSuiteStore(props.ctx, COMPANIONS);
-      }, [props.ctx, props.store]);
-      var st = useState(store.getSnapshot()), snap = st[0], setSnap = st[1];
-      var mn = useState(null), manual = mn[0], setManual = mn[1];
-      var cp = useState(false), copied = cp[0], setCopied = cp[1];
-
-      useEffect(function () {
-        // Subscribe before the first read: a change published during it must still reach this card.
-        var off = store.subscribe(function () { setSnap(store.getSnapshot()); });
-        var stop = store.start();
-        return function () { off(); stop(); };
-      }, [store]);
-
-      if (!snap.read) return null;
-      var missing = snap.hint.kind === "missing";
-      var kids = [
-        h("div", { key: "t", style: { fontSize: "12px", fontWeight: 600 } }, missing ? SUITE_COPY.missingTitle : SUITE_COPY.toolsTitle),
-        h("div", { key: "i", style: { fontSize: "11px", color: C.muted, lineHeight: 1.6 } }, missing ? SUITE_COPY.missingIntro : SUITE_COPY.toolsIntro),
-      ];
-      for (var i = 0; i < snap.hint.missing.length; i++) {
-        var line = snap.hint.missing[i];
-        kids.push(h("div", { key: "m:" + line.package, style: { fontSize: "12px", lineHeight: 1.6 } }, line.line));
-      }
-      kids.push(h("div", { key: "k", style: { fontSize: "11px", color: C.muted, lineHeight: 1.6 } }, SUITE_COPY.keep));
-      kids.push(h("div", { key: "a", style: { display: "flex", flexWrap: "wrap", gap: "6px", paddingTop: "2px" } }, [
-        h(Btn, {
-          key: "open", active: missing, title: "打开插件中心",
-          onClick: function () {
-            var target = store.open();
-            setCopied(false);
-            setManual(target.kind === "manual" ? { spec: target.spec } : null);
-          },
-        }, SUITE_COPY.open),
-      ]));
-      if (manual) {
-        kids.push(h("div", { key: "mn", style: { fontSize: "11px", color: C.muted, lineHeight: 1.6 } }, SUITE_COPY.manual));
-        kids.push(h("code", {
-          key: "spec",
-          style: { fontSize: "12px", padding: "2px 6px", borderRadius: "6px", background: C.softer, border: "1px solid " + C.line, userSelect: "text", alignSelf: "flex-start" },
-        }, manual.spec));
-        kids.push(h("div", { key: "cp", style: { display: "flex", flexWrap: "wrap", gap: "6px" } }, [
-          h(Btn, {
-            key: "copy", title: "复制包名",
-            onClick: function () { void store.copy(manual.spec).then(function (written) { setCopied(written); }); },
-          }, copied ? SUITE_COPY.copied : SUITE_COPY.copy),
-        ]));
-      }
-      return h("div", {
-        "data-mp-companions": "1",
-        style: {
-          display: "flex", flexDirection: "column", gap: "5px", flex: "none", boxSizing: "border-box",
-          padding: "9px 10px", borderRadius: "8px", border: "1px dashed " + C.line, background: C.softer, color: C.fg,
-        },
-      }, kids);
+        // The host's document pane sets a monospace face for code; the player's labels are ordinary UI text.
+        style: { display: "flex", flexDirection: "column", gap: "8px", padding: "10px", minWidth: 0, minHeight: 0, height: "100%", boxSizing: "border-box", fontFamily: "system-ui, -apple-system, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif" },
+      }, p.children);
     }
 
     // ── video ───────────────────────────────────────────────────────────────
 
     function VideoView(props) {
       var abs = absOf(props.scope, props.path);
-      var url = fileUrl(props.scope, abs);
+      var url = playUrl(props, abs);
       var vref = useRef(null);
       var st = useState(1), rate = st[0], setRate = st[1];
       var lp = useState(false), loop = lp[0], setLoop = lp[1];
       var er = useState(null), err = er[0], setErr = er[1];
       var du = useState(null), dur = du[0], setDur = du[1];
       var dims = useState(null), dim = dims[0], setDim = dims[1];
-      var tl = useState(false), tools = tl[0], setTools = tl[1];
 
       useEffect(function () { setErr(null); setDur(null); setDim(null); }, [url]);
       useEffect(function () { if (vref.current) vref.current.playbackRate = rate; }, [rate, url]);
 
       var info = [dur != null ? fmtDur(dur) : null, dim ? dim : null, extOf(abs).toUpperCase()].filter(Boolean).join(" · ");
 
-      return h(Shell, { key: "root", tools: tools ? h(SuiteCard, { ctx: props.ctx }) : null }, [
+      return h(Shell, null, [
         h("div", { key: "stage", style: { flex: "1 1 auto", minHeight: 0, display: "flex", background: "#000", borderRadius: "8px", overflow: "hidden" } },
           err
             ? h("div", { style: { margin: "auto", padding: "20px", textAlign: "center", color: "#ddd", fontSize: "13px", lineHeight: 1.7 } }, [
@@ -551,7 +264,7 @@ window.__ModuleLoader__.load({
         h(Bar, { key: "bar", title: baseName(abs) + (info ? "  ·  " + info : ""), path: abs }, [
           h(RatePicker, { key: "rate", rate: rate, set: setRate }),
           h(Btn, { key: "loop", active: loop, title: "循环播放", onClick: function () { setLoop(!loop); } }, "循环"),
-          CommonActions(props, abs, url, tools, function () { setTools(!tools); }),
+          CommonActions(props, abs, url),
         ]),
       ]);
     }
@@ -560,14 +273,13 @@ window.__ModuleLoader__.load({
 
     function AudioView(props) {
       var abs = absOf(props.scope, props.path);
-      var url = fileUrl(props.scope, abs);
+      var url = playUrl(props, abs);
       var aref = useRef(null);
       var cref = useRef(null);
       var st = useState(1), rate = st[0], setRate = st[1];
       var lp = useState(false), loop = lp[0], setLoop = lp[1];
       var er = useState(null), err = er[0], setErr = er[1];
       var du = useState(null), dur = du[0], setDur = du[1];
-      var tl = useState(false), tools = tl[0], setTools = tl[1];
 
       useEffect(function () { setErr(null); setDur(null); }, [url]);
       useEffect(function () { if (aref.current) aref.current.playbackRate = rate; }, [rate, url]);
@@ -618,7 +330,7 @@ window.__ModuleLoader__.load({
         };
       }, [url]);
 
-      return h(Shell, { key: "root", tools: tools ? h(SuiteCard, { ctx: props.ctx }) : null }, [
+      return h(Shell, null, [
         h("div", {
           key: "stage",
           style: {
@@ -640,7 +352,7 @@ window.__ModuleLoader__.load({
         h(Bar, { key: "bar", title: baseName(abs) + "  ·  " + [dur != null ? fmtDur(dur) : null, extOf(abs).toUpperCase()].filter(Boolean).join(" · "), path: abs }, [
           h(RatePicker, { key: "rate", rate: rate, set: setRate }),
           h(Btn, { key: "loop", active: loop, title: "循环播放", onClick: function () { setLoop(!loop); } }, "循环"),
-          CommonActions(props, abs, url, tools, function () { setTools(!tools); }),
+          CommonActions(props, abs, url),
         ]),
       ]);
     }
@@ -662,7 +374,6 @@ window.__ModuleLoader__.load({
       var vp = useState("fit"), view = vp[0], setView = vp[1];
       var rk = useState(0), reloadKey = rk[0], setReloadKey = rk[1];
       var sr = useState({ state: "idle", text: "" }), source = sr[0], setSource = sr[1];
-      var tl = useState(false), tools = tl[0], setTools = tl[1];
 
       var frameRef = useRef(null);
 
@@ -712,7 +423,7 @@ window.__ModuleLoader__.load({
         }));
       }
 
-      return h(Shell, { key: "root", tools: tools ? h(SuiteCard, { ctx: props.ctx }) : null }, [
+      return h(Shell, null, [
         stage,
         h(Bar, { key: "bar", title: baseName(abs), path: abs }, [
           h(Btn, { key: "m1", active: mode === "render", title: "渲染预览", onClick: function () { setMode("render"); } }, "预览"),
@@ -722,11 +433,33 @@ window.__ModuleLoader__.load({
           }) : null,
           h(Btn, { key: "js", active: scripts, title: scripts ? "脚本已允许，点击关闭（页面将重新加载）" : "脚本已禁用，点击允许", onClick: function () { setScripts(!scripts); } }, scripts ? "脚本 开" : "脚本 关"),
           h(Btn, { key: "rl", title: "重新加载", onClick: function () { setReloadKey(reloadKey + 1); } }, "刷新"),
-          CommonActions(props, abs, url, tools, function () { setTools(!tools); }),
+          CommonActions(props, abs, url),
         ]),
       ]);
     }
 
+    // ── add to the film canvas ──────────────────────────────────────────────
+
+    /** What the 影视工作台 (dsh-film-studio) canvas takes: images, videos and audio. */
+    function canAddToCanvas(it) { return it.kind === "image" || it.kind === "video" || it.kind === "audio"; }
+
+    /**
+     * Hand files to the open 影视工作台 canvas. The two plugins only share a DOM
+     * event: the workbench sets `detail.accepted` while handling it, so "not
+     * accepted" means the workbench plugin is not installed or not enabled.
+     * @param paths - absolute file paths.
+     * @param sessionId - the gallery's session (the workbench opens there if needed).
+     * @returns a promise of `{ ok, added?, failed?, message? }`.
+     */
+    function addToCanvas(paths, sessionId) {
+      return new Promise(function (resolve) {
+        var detail = { paths: paths, sessionId: sessionId, accepted: false, respond: resolve };
+        try { window.dispatchEvent(new CustomEvent("vibedev-film:add-media", { detail: detail })); }
+        catch (e) { resolve({ ok: false, message: String(e && e.message || e) }); return; }
+        if (!detail.accepted) resolve({ ok: false, message: "没有找到影视工作台：请先安装并启用「影视工作台」插件（dsh-film-studio）" });
+      });
+    }
+
     // ── gallery ─────────────────────────────────────────────────────────────
 
     function Thumb(p) {
@@ -742,11 +475,56 @@ window.__ModuleLoader__.load({
         return function () { io.disconnect(); };
       }, []);
 
+      // A video thumbnail keeps its <video> only until one frame is captured, then shows that frame as an image: a
+      // player left on the page holds a connection, and a grid of them would leave none for anything else. Hovering
+      // brings a muted player back for the preview.
+      var ps = useState(null), poster = ps[0], setPoster = ps[1];
+      var hv = useState(false), hover = hv[0], setHover = hv[1];
+      // Native listeners, plus a look at the state the element is already in: a frame can be ready before React's
+      // media handlers see it, and a missed event left the player on the page for good.
+      useEffect(function () {
+        var v = vid.current;
+        if (!vis || hover || poster || it.kind !== "video" || !v) return undefined;
+        var done = false;
+        function capture() {
+          if (done) return;
+          done = true;
+          try {
+            var w = Math.min(480, v.videoWidth || 480), hh = Math.round(w * ((v.videoHeight || 270) / (v.videoWidth || 480)));
+            var cv = document.createElement("canvas");
+            cv.width = w; cv.height = hh;
+            cv.getContext("2d").drawImage(v, 0, 0, w, hh);
+            setPoster(cv.toDataURL("image/jpeg", 0.72));
+          } catch (err) { setPoster("none"); }
+        }
+        // The frame at 0.5 s: the media fragment usually lands there already; otherwise seek, and take it once there.
+        function settle() {
+          if (v.readyState < 2) return;
+          if (v.currentTime > 0.05 || !(v.duration > 0.6)) capture();
+          else if (!v.seeking) { try { v.currentTime = 0.5; } catch (err) { capture(); } }
+        }
+        v.addEventListener("loadeddata", settle);
+        v.addEventListener("canplay", settle);
+        v.addEventListener("seeked", settle);
+        settle();
+        return function () {
+          done = true;
+          v.removeEventListener("loadeddata", settle);
+          v.removeEventListener("canplay", settle);
+          v.removeEventListener("seeked", settle);
+        };
+      }, [vis, hover, poster]);
+
       var url = fileUrl(scope, it.abs);
       var inner;
+      var fill = { width: "100%", height: "100%", objectFit: "cover", background: "#000" };
       if (!vis) inner = null;
       else if (it.kind === "image") inner = h("img", { src: url, loading: "lazy", draggable: false, style: { width: "100%", height: "100%", objectFit: "cover" } });
-      else if (it.kind === "video") inner = h("video", { ref: vid, src: url + "#t=0.5", muted: true, preload: "metadata", playsInline: true, style: { width: "100%", height: "100%", objectFit: "cover", background: "#000" } });
+      else if (it.kind === "video" && poster && poster !== "none" && !hover) inner = h("img", { src: poster, draggable: false, alt: "", style: fill });
+      else if (it.kind === "video") inner = h("video", {
+        key: hover ? "play" : "frame", ref: vid, src: url + (hover ? "" : "#t=0.5"), muted: true, preload: "metadata", playsInline: true,
+        autoPlay: hover, loop: hover, style: fill,
+      });
       else inner = h("div", {
         style: { width: "100%", height: "100%", display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "center", gap: "6px",
           background: it.kind === "audio" ? "linear-gradient(145deg, rgba(124,92,255,.35), rgba(34,211,238,.25))" : "linear-gradient(145deg, rgba(255,140,60,.28), rgba(255,80,120,.2))" },
@@ -754,8 +532,8 @@ window.__ModuleLoader__.load({
 
       return h("div", {
         ref: ref,
-        onMouseEnter: function () { var v = vid.current; if (v) { v.currentTime = 0; var pr = v.play(); if (pr && pr.catch) pr.catch(function () {}); } },
-        onMouseLeave: function () { var v = vid.current; if (v) { v.pause(); v.currentTime = 0.5; } },
+        onMouseEnter: function () { if (it.kind === "video") setHover(true); },
+        onMouseLeave: function () { if (it.kind === "video") setHover(false); },
         style: { position: "relative", width: "100%", aspectRatio: "16 / 10", background: C.soft, overflow: "hidden", borderRadius: "8px 8px 0 0" },
       }, [
         inner,
@@ -813,6 +591,18 @@ window.__ModuleLoader__.load({
       var sz = useState(210), size = sz[0], setSize = sz[1];
       var se = useState(-1), sel = se[0], setSel = se[1];
       var tk = useState(0), tick = tk[0], setTick = tk[1];
+      // Multi-select for "加入画布": picked files are keyed by absolute path, so a
+      // pick survives filtering, searching and re-sorting.
+      var pk = useState(false), picking = pk[0], setPicking = pk[1];
+      var pd = useState({}), picked = pd[0], setPicked = pd[1];
+      var bz = useState(false), adding = bz[0], setAdding = bz[1];
+      var nt = useState(null), notice = nt[0], setNotice = nt[1];
+      var lastPick = useRef(-1);
+      useEffect(function () {
+        if (!notice) return undefined;
+        var timer = setTimeout(function () { setNotice(null); }, notice.kind === "error" ? 8000 : 4000);
+        return function () { clearTimeout(timer); };
+      }, [notice]);
 
       // Follow a re-seeded tab (opened again for another folder).
       useEffect(function () { setCur(seed); }, [seed]);
@@ -863,6 +653,41 @@ window.__ModuleLoader__.load({
 
       useEffect(function () { setSel(-1); }, [cur, recursive, filter, query]);
 
+      var pickedPaths = Object.keys(picked);
+      function togglePick(it, index, range) {
+        if (!canAddToCanvas(it)) return;
+        setPicked(function (prev) {
+          var next = Object.assign({}, prev);
+          if (range && lastPick.current >= 0) {
+            var from = Math.min(lastPick.current, index), to = Math.max(lastPick.current, index);
+            for (var i = from; i <= to; i++) if (items[i] && canAddToCanvas(items[i])) next[items[i].abs] = true;
+          } else if (next[it.abs]) delete next[it.abs];
+          else next[it.abs] = true;
+          return next;
+        });
+        lastPick.current = index;
+      }
+      function pickAll() {
+        var next = Object.assign({}, picked);
+        items.forEach(function (it) { if (canAddToCanvas(it)) next[it.abs] = true; });
+        setPicked(next);
+      }
+      function stopPicking() { setPicking(false); setPicked({}); lastPick.current = -1; }
+      function addPicked() {
+        if (adding || pickedPaths.length === 0) return;
+        setAdding(true);
+        addToCanvas(pickedPaths, scope.sessionId).then(function (result) {
+          setAdding(false);
+          if (result.ok) {
+            var failed = (result.failed || []).length;
+            setNotice({ kind: failed ? "warn" : "ok", text: "已加入画布 " + (result.added || 0) + " 个" + (failed ? "，" + failed + " 个未加入：" + result.failed.map(function (f) { return baseName(f.path) + "（" + f.reason + "）"; }).join("、") : "") });
+            stopPicking();
+          } else {
+            setNotice({ kind: "error", text: result.message || "加入画布失败" });
+          }
+        });
+      }
+
       var dir = data ? data.dir : cur;
       var root = data ? data.cwd : "";
       var crumbs = [];
@@ -886,8 +711,25 @@ window.__ModuleLoader__.load({
             ]);
           }),
           h("span", { key: "sp", style: { flex: 1 } }),
+          h(Btn, { key: "pick", active: picking, title: picking ? "退出多选" : "多选文件，加入影视工作台的画布", onClick: function () { if (picking) stopPicking(); else setPicking(true); } }, [IconCheck(12), picking ? "退出多选" : "多选"]),
           h(Btn, { key: "rf", title: "重新扫描文件夹", onClick: function () { setTick(tick + 1); } }, "刷新"),
         ]),
+        picking ? h("div", { key: "pickbar", style: { display: "flex", alignItems: "center", gap: "6px", fontSize: "12px", flexWrap: "wrap" } }, [
+          h("span", { key: "n", style: { color: C.muted } }, "已选 " + pickedPaths.length + " 个（Shift 连选）"),
+          h(Btn, { key: "all", title: "选中当前列表里能加入画布的全部文件", onClick: pickAll }, "全选"),
+          h(Btn, { key: "none", title: "清空选择", disabled: pickedPaths.length === 0, onClick: function () { setPicked({}); lastPick.current = -1; } }, "清空"),
+          h("span", { key: "sp", style: { flex: 1 } }),
+          h("button", {
+            key: "add", type: "button", disabled: adding || pickedPaths.length === 0, onClick: addPicked,
+            title: "加入当前打开着的影视工作台画布（没有打开时会先在侧栏打开它）",
+            style: btn({ background: C.accent, borderColor: C.accent, color: "#fff", fontWeight: 600, opacity: adding || pickedPaths.length === 0 ? 0.5 : 1, cursor: adding || pickedPaths.length === 0 ? "default" : "pointer" }),
+          }, adding ? "正在加入…" : "加入画布（" + pickedPaths.length + "）"),
+        ]) : null,
+        notice ? h("div", {
+          key: "notice", role: notice.kind === "error" ? "alert" : "status",
+          style: { fontSize: "12px", lineHeight: 1.5, padding: "5px 8px", borderRadius: "6px",
+            background: notice.kind === "error" ? "rgba(229,72,77,.14)" : notice.kind === "warn" ? "rgba(245,166,35,.16)" : "rgba(48,164,108,.14)" },
+        }, notice.text) : null,
         h("div", { key: "r2", style: { display: "flex", alignItems: "center", gap: "5px", flexWrap: "wrap" } }, [
           FILTERS.map(function (f) {
             return h("button", { key: f.id, type: "button", onClick: function () { setFilter(f.id); }, style: chip(filter === f.id) }, f.label + " " + (counts[f.id] || 0));
@@ -923,7 +765,16 @@ window.__ModuleLoader__.load({
           ]);
         });
         var cards = items.map(function (it, i) {
-          return h("div", { key: it.abs, onClick: function () { setSel(i); }, title: it.rel, style: { cursor: "pointer", borderRadius: "8px", border: "1px solid " + C.line, overflow: "hidden", display: "flex", flexDirection: "column", minWidth: 0 } }, [
+          var addable = canAddToCanvas(it);
+          var chosen = !!picked[it.abs];
+          return h("div", {
+            key: it.abs,
+            onClick: function (e) { if (picking) togglePick(it, i, e.shiftKey); else setSel(i); },
+            title: picking && !addable ? "网页不能加入画布" : it.rel,
+            "aria-pressed": picking ? chosen : undefined,
+            style: { position: "relative", cursor: picking && !addable ? "not-allowed" : "pointer", borderRadius: "8px", border: chosen ? "2px solid " + C.accent : "1px solid " + C.line, margin: chosen ? "-1px" : 0, overflow: "hidden", display: "flex", flexDirection: "column", minWidth: 0, opacity: picking && !addable ? 0.45 : 1 },
+          }, [
+            picking && addable ? h("span", { key: "chk", "aria-hidden": "true", style: { position: "absolute", right: "6px", top: "6px", zIndex: 1, width: "18px", height: "18px", borderRadius: "5px", display: "flex", alignItems: "center", justifyContent: "center", background: chosen ? C.accent : "rgba(0,0,0,.45)", border: "1.5px solid #fff", color: "#fff" } }, chosen ? IconCheck(11) : null) : null,
             h(Thumb, { key: "t", item: it, scope: scope }),
             h("div", { key: "m", style: { padding: "5px 8px 6px", fontSize: "12px", minWidth: 0 } }, [
               h("div", { key: "n", style: { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", fontWeight: 600 } }, recursive ? it.rel : it.name),
@@ -942,8 +793,6 @@ window.__ModuleLoader__.load({
       return h("div", { style: { position: "relative", height: "100%", display: "flex", flexDirection: "column", overflow: "hidden", minWidth: 0 } }, [
         header,
         body,
-        // The card sits at the foot of the gallery: a statement about the Host, never a launch ad.
-        h("div", { key: "tools", style: { flex: "none", padding: "0 10px 10px" } }, h(SuiteCard, { ctx: props.ctx })),
         sel >= 0 && items[sel]
           ? h(Lightbox, {
               key: "lb", ctx: props.ctx, store: props.store, scope: scope, item: items[sel], index: sel, total: items.length,
@@ -955,55 +804,202 @@ window.__ModuleLoader__.load({
       ]);
     }
 
-    // ── registration ────────────────────────────────────────────────────────
+    // ── the host's own right sidebar (DSH 0.2.1-alpha.2 and later) ──────────
+    //
+    // Since 0.2.0 the viewer stands on the host's public surfaces only, so an app update never strands it behind a
+    // third-party plugin that has not caught up:
+    //   - video / audio / HTML bodies: `ctx.documentPreviews` + the keyed `sidebar.right.tab.document` seat
+    //     (content loading "renderer": the body streams the file from our own /mp route);
+    //   - the gallery: a page type in `ctx.sidebarRightTabs` + the keyed `sidebar.right.pane.tab` seat;
+    //   - "画廊" buttons: the document toolbar (`sidebar.right.tab.document.actions`) and the file tree
+    //     (`sidebar.right.tab.files.actions`).
+
+    var PACKAGE = "@vibedev-si/dsh-media-viewer";
+    var GALLERY_ID = PACKAGE + "/gallery";
+    var GALLERY_KIND = "vibedev-media-gallery";
+    var PREVIEWS = [
+      { id: PACKAGE + "/video", title: "视频播放器", exts: VIDEO_EXTS, binary: true, view: VideoView },
+      { id: PACKAGE + "/audio", title: "音频播放器", exts: AUDIO_EXTS, binary: true, view: AudioView },
+      { id: PACKAGE + "/html", title: "网页预览（允许脚本）", exts: HTML_EXTS, binary: false, view: HtmlView },
+    ];
 
-    var inject = ["betterSidebar"];
+    /** `dsh-resource://file/session/<id>/<path>` → `{ sessionId, path }` (the host's address grammar). */
+    function parseSessionAddress(address) {
+      var prefix = "dsh-resource://file/session/";
+      if (typeof address !== "string" || address.indexOf(prefix) !== 0) return null;
+      var rest = address.slice(prefix.length).split(/[?#]/)[0].split("/");
+      if (rest.length < 2 || !rest[0]) return null;
+      try {
+        return { sessionId: decodeURIComponent(rest[0]), path: rest.slice(1).map(decodeURIComponent).join("/") };
+      } catch (e) { return null; }
+    }
 
-    function apply(ctx) {
-      // Each registration returns a disposer; wrapping in ctx.effect makes
-      // cordis call it on teardown (HMR / plugin disable) so re-activation
-      // does not throw "already registered".
-      ctx.effect(function () {
-        return ctx.betterSidebar.registerFileViewer({
-          id: "mp:video", title: "视频播放器", icon: IconVideo, exts: VIDEO_EXTS, priority: 10, fetchStrategy: "none", component: VideoView,
+    /** The host's right sidebar, when it is there (read lazily: it may mount after this plugin). */
+    function sidebarOf(ctx) {
+      try { return ctx.get ? ctx.get("sidebarRight") : undefined; } catch (e) { return undefined; }
+    }
+
+    /** Open (or re-aim) the gallery page in the session on screen. */
+    function openGalleryPage(ctx, dir) {
+      var sidebar = sidebarOf(ctx);
+      if (!sidebar) return;
+      sidebar.openTab(GALLERY_KIND, { params: { path: dir || "" }, revealIfOpened: true });
+    }
+
+    function Notice(text) {
+      return h("div", { style: { margin: "auto", padding: "24px", textAlign: "center", color: C.muted, fontSize: "13px", lineHeight: 1.7 } }, text);
+    }
+
+    /**
+     * One document body: the file's host path and version come from the standard `useResource`; the view streams the
+     * file itself, and reports the version it shows so the host's "file changed" bar works as for its own previews.
+     */
+    function documentBody(View) {
+      return function MediaDocumentBody(props) {
+        var info = props.useTabInfo ? props.useTabInfo() : null;
+        var meta = props.useResource ? props.useResource(props.resourceAddress) : { status: "none" };
+        var file = parseSessionAddress(props.resourceAddress);
+        var content = props.content;
+        var abs = meta && meta.value ? meta.value.absolutePath : undefined;
+        var version = meta && meta.value ? meta.value.version : undefined;
+        var revision = content && content.kind === "renderer" ? content.revision : 0;
+        useEffect(function () {
+          if (content && content.kind === "renderer" && abs) content.loaded(version === undefined ? "" : String(version));
+        }, [revision, abs, version]);
+        if (!file) return Notice("这个文件不在会话的工作区里，无法预览");
+        if (!abs) return Notice(meta && meta.status === "failed" ? "读取文件信息失败" : "正在读取文件…");
+        return h(View, {
+          key: String(revision),
+          scope: { sessionId: file.sessionId, cwd: "" },
+          path: abs,
+          nonce: (version === undefined ? "" : String(version)) + "." + revision,
+          // The document toolbar already carries "画廊" (sidebar.right.tab.document.actions).
+          hideGallery: true,
+          openGallery: function (dir) {
+            var actions = info && info.tab && info.tab.actions;
+            if (actions && actions.openTab) actions.openTab(GALLERY_KIND, { params: { path: dir || "" }, revealIfOpened: true });
+          },
         });
+      };
+    }
+
+    /** The gallery as a host page: its folder arrives as the navigation's `params.path`. */
+    function GalleryPage(props) {
+      var info = props.useTabInfo ? props.useTabInfo() : null;
+      var tab = info && info.tab;
+      var params = (tab && tab.navigation && tab.navigation.params) || {};
+      var sessionId = props.sessionId || (tab && tab.sessionId) || "";
+      if (!sessionId) return Notice("请先打开一个会话");
+      return h(GalleryTab, {
+        ctx: props.ctx,
+        scope: { sessionId: sessionId, cwd: "" },
+        tab: { path: typeof params.path === "string" ? params.path : "" },
+        visible: tab ? tab.visible !== false : true,
       });
+    }
+
+    function GuideIcon(p) { return IconGrid((p && p.size) || 16); }
+
+    /** "画廊" in the document toolbar: only for files the gallery shows. */
+    function documentAction(ctx) {
+      return function GalleryDocumentAction(props) {
+        var abs = props.absolutePath || "";
+        if (kindOf(abs) === "other") return null;
+        return h(Btn, { title: "浏览所在文件夹的全部媒体", onClick: function () { openGalleryPage(ctx, dirName(abs)); } }, [IconGrid(12), "画廊"]);
+      };
+    }
+
+    /** "媒体画廊" beside the file tree's reload control: the folder the tree shows. */
+    function filesAction(ctx) {
+      return function GalleryFilesAction(props) {
+        return h(Btn, { title: "以缩略图浏览这个文件夹里的视频、音频、图片和网页", onClick: function () { openGalleryPage(ctx, props.absolutePath || ""); } }, [IconGrid(12), "媒体画廊"]);
+      };
+    }
+
+    function registerNative(ctx) {
       ctx.effect(function () {
-        return ctx.betterSidebar.registerFileViewer({
-          id: "mp:audio", title: "音频播放器", icon: IconAudio, exts: AUDIO_EXTS, priority: 10, fetchStrategy: "none", component: AudioView,
+        return ctx.sidebarRightTabs.register({
+          id: GALLERY_ID,
+          kind: GALLERY_KIND,
+          title: function () { return "媒体画廊"; },
+          guide: [{ id: "gallery", order: 60, title: function () { return "媒体画廊"; }, description: function () { return "以缩略图浏览文件夹里的视频、音频、图片和网页"; }, icon: GuideIcon }],
         });
-      });
+      }, "dsh-media-viewer: gallery type");
       ctx.effect(function () {
-        return ctx.betterSidebar.registerFileViewer({
-          id: "mp:html", title: "网页预览（允许脚本）", icon: IconHtml, exts: HTML_EXTS, priority: 10, fetchStrategy: "none", component: HtmlView,
+        return ctx.slots.inject("sidebar.right.pane.tab", function () {
+          return ctx.slots.register({ name: "sidebar.right.pane.tab", key: GALLERY_ID, inject: function (sessionId) { return { ctx: ctx, sessionId: sessionId }; } }, GalleryPage);
         });
-      });
+      }, "dsh-media-viewer: gallery body");
       ctx.effect(function () {
-        return ctx.betterSidebar.registerTab({
-          id: "mp:gallery",
-          title: "媒体画廊",
-          description: "以缩略图浏览文件夹里的视频、音频、图片和网页",
-          icon: IconGrid,
-          order: 60,
-          dedupeKey: function (tab) { return tab.path || "mp:gallery"; },
-          component: GalleryTab,
+        return ctx.slots.inject("sidebar.right.tab.files.actions", function () {
+          return ctx.slots.register({ name: "sidebar.right.tab.files.actions", id: GALLERY_ID }, filesAction(ctx));
+        });
+      }, "dsh-media-viewer: file tree action");
+      ctx.effect(function () {
+        return ctx.slots.inject("sidebar.right.tab.document.actions", function () {
+          return ctx.slots.register({ name: "sidebar.right.tab.document.actions", id: GALLERY_ID }, documentAction(ctx));
+        });
+      }, "dsh-media-viewer: document action");
+      // Document previews are optional: without the host's preview package there is nothing to register them with.
+      ctx.inject(["documentPreviews"], function (scope) {
+        PREVIEWS.forEach(function (preview) {
+          scope.effect(function () {
+            return scope.documentPreviews.register({
+              id: preview.id, extensions: preview.exts, binaryExtensions: preview.binary ? preview.exts : [],
+              priority: "extension", title: function () { return preview.title; }, loading: "renderer", wrap: false,
+            });
+          }, "dsh-media-viewer: " + preview.id + " metadata");
+          scope.effect(function () {
+            return scope.slots.inject("sidebar.right.tab.document", function () {
+              return scope.slots.register({ name: "sidebar.right.tab.document", key: preview.id }, documentBody(preview.view));
+            });
+          }, "dsh-media-viewer: " + preview.id + " body");
         });
       });
     }
 
-    // The loader reads `inject` and `apply`; `__suite` is the companion-components core, kept
-    // exported so test/suite.test.mjs can drive it and the card through a fake loader and React.
-    module.exports = {
-      inject: inject,
-      apply: apply,
-      __suite: {
-        SUITE: SUITE, CENTER_PANEL: CENTER_PANEL, CENTER_SPEC: CENTER_SPEC, COMPANIONS: COMPANIONS,
-        suiteServices: suiteServices, bundlePresent: bundlePresent, presentFrom: presentFrom,
-        readPresence: readPresence, observePresence: observePresence, centerPanel: centerPanel,
-        openCenter: openCenter, missingFrom: missingFrom, suiteHint: suiteHint,
-        createSuiteStore: createSuiteStore, SuiteCard: SuiteCard,
-      },
-    };
+    // ── dsh-better-sidebar, when it is installed ────────────────────────────
+    //
+    // Better Sidebar's editor claims every file address ahead of the host's previews, so with it installed the media
+    // views must also live inside it (as they did before 0.2.0). Optional: nothing waits for it.
+
+    function registerBetterSidebar(ctx) {
+      // The gallery stays the host's own page (one 媒体画廊, not two); the viewers' "画廊" button opens it.
+      function withNativeGallery(View) {
+        return function (props) {
+          return h(View, Object.assign({}, props, { openGallery: function (dir) { openGalleryPage(ctx, dir); } }));
+        };
+      }
+      ctx.inject(["betterSidebar"], function (scope) {
+        // Each registration returns a disposer; wrapping it in scope.effect lets cordis dispose it on teardown.
+        scope.effect(function () {
+          return scope.betterSidebar.registerFileViewer({
+            id: "mp:video", title: "视频播放器", icon: IconVideo, exts: VIDEO_EXTS, priority: 10, fetchStrategy: "none", component: withNativeGallery(VideoView),
+          });
+        });
+        scope.effect(function () {
+          return scope.betterSidebar.registerFileViewer({
+            id: "mp:audio", title: "音频播放器", icon: IconAudio, exts: AUDIO_EXTS, priority: 10, fetchStrategy: "none", component: withNativeGallery(AudioView),
+          });
+        });
+        scope.effect(function () {
+          return scope.betterSidebar.registerFileViewer({
+            id: "mp:html", title: "网页预览（允许脚本）", icon: IconHtml, exts: HTML_EXTS, priority: 10, fetchStrategy: "none", component: withNativeGallery(HtmlView),
+          });
+        });
+      });
+    }
+
+    // ── registration ────────────────────────────────────────────────────────
+
+    var inject = ["slots", "sidebarRightTabs"];
+
+    function apply(ctx) {
+      registerNative(ctx);
+      registerBetterSidebar(ctx);
+    }
+
+    module.exports = { inject: inject, apply: apply, internals: { parseSessionAddress: parseSessionAddress, GALLERY_KIND: GALLERY_KIND, PREVIEWS: PREVIEWS } };
     return module.exports;
   },
 });

package/index.js

@@ -36,8 +36,22 @@ import { basename, extname, resolve } from 'node:path'
 
 export const name = '@vibedev-si/dsh-media-viewer'
 
-/** Services required before mounting. */
-export const inject = ['webServer', 'sessions', 'webRuntime']
+/**
+ * Services required before mounting. The extra trusted hosts come from `webStartup` (DSH 0.2.1-alpha.2 and later)
+ * or `webRuntime` (earlier releases), read when present: requiring either one left the plugin pending on the other.
+ */
+export const inject = ['webServer', 'sessions']
+
+/** The deployment's extra trusted hosts (loopback is always trusted), from whichever startup service this host has. */
+export function trustedHostsOf(ctx) {
+  for (const service of ['webStartup', 'webRuntime']) {
+    try {
+      const value = typeof ctx.get === 'function' ? ctx.get(service) : ctx[service]
+      if (Array.isArray(value?.trustedHosts)) return value.trustedHosts
+    } catch { /* not provided by this host */ }
+  }
+  return []
+}
 
 // ── content types ───────────────────────────────────────────────────────────
 
@@ -246,18 +260,35 @@ function parseRange(raw, size) {
   return { start, end: Math.min(end, size - 1) }
 }
 
-function serveFile(req, res, path, size, type, extra) {
+/**
+ * The most an open-ended media range (`bytes=N-`) gets in one response. A player asks for the rest of the file, reads
+ * what it needs (just the metadata for preload=metadata) and then stops reading, which leaves the response unfinished
+ * and its connection taken. A page that also keeps its own streams open runs out of the browser's six connections per
+ * host, and the next video waits with no request at all. A small capped 206 is read to its end, frees the connection,
+ * and the player asks again from where it stopped.
+ */
+export const MEDIA_CHUNK_BYTES = 256 * 1024
+
+/** @param chunk - cap for an open-ended range, for media playback; undefined serves what was asked. */
+function serveFile(req, res, path, size, type, extra, chunk) {
   const base = {
     'content-type': type,
     'accept-ranges': 'bytes',
-    'cache-control': 'no-cache',
+    // no-store, not no-cache: a stored response keeps the browser cache's single-writer lock on the URL while a
+    // player holds its stream (a gallery thumbnail, the lightbox), and every other player of the same file then waits
+    // forever. Local files need no cache.
+    'cache-control': 'no-store',
     'x-content-type-options': 'nosniff',
     'referrer-policy': 'no-referrer',
     'content-security-policy': SANDBOX_CSP,
     'cross-origin-resource-policy': 'cross-origin',
     ...extra,
   }
-  const range = parseRange(header(req.headers, 'range'), size)
+  const asked = header(req.headers, 'range')
+  const range = parseRange(asked, size)
+  if (range && !range.unsatisfiable && chunk !== undefined && /^bytes=\s*\d*-\s*$/i.test(asked ?? '')) {
+    range.end = Math.min(range.end, range.start + chunk - 1)
+  }
   if (range?.unsatisfiable) {
     res.writeHead(416, { ...base, 'content-range': `bytes */${size}` })
     res.end()
@@ -342,7 +373,7 @@ async function listMedia(root, recursive) {
 // ── plugin body ─────────────────────────────────────────────────────────────
 
 export function apply(ctx) {
-  const trustedHosts = () => ctx.webRuntime.trustedHosts
+  const trustedHosts = () => trustedHostsOf(ctx)
 
   ctx.effect(() => ctx.webServer.register({
     kind: 'prefix',
@@ -381,7 +412,8 @@ export function apply(ctx) {
             res.end()
             return
           }
-          serveFile(req, res, real, info.size, type, extra)
+          const playback = url.searchParams.get('download') !== '1' && /^(video|audio)\//.test(type)
+          serveFile(req, res, real, info.size, type, extra, playback ? MEDIA_CHUNK_BYTES : undefined)
           return
         }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vibedev-si/dsh-media-viewer",
-  "version": "0.1.2",
-  "description": "右侧栏媒体预览：直接预览视频、音频和 HTML（大文件可拖进度条，HTML 默认允许脚本），并提供文件夹媒体画廊，需配合 dsh-better-sidebar · Inline video, audio and HTML preview plus a folder media gallery in the dsh-better-sidebar right column — range-streamed large files, sandboxed HTML with working relative assets",
+  "version": "0.2.0",
+  "description": "右侧栏媒体预览：直接预览视频、音频和 HTML（大文件可拖进度条，HTML 默认允许脚本），文件夹媒体画廊（多选后加入影视工作台画布）；用 DSH 自带的右侧栏，装了 dsh-better-sidebar 时也在其中可用 · Inline video, audio and HTML preview plus a folder media gallery in the host's own right sidebar (and inside dsh-better-sidebar when installed) — range-streamed large files, sandboxed HTML with working relative assets",
   "type": "module",
   "main": "index.js",
   "icon": "./icon.svg",
@@ -26,14 +26,14 @@
     "dsh-plugin",
     "deepseek-harness",
     "vibedev",
-    "dsh-better-sidebar",
-    "better-sidebar",
+    "right-sidebar",
     "video",
     "audio",
     "html",
     "preview",
     "gallery",
-    "file-viewer"
+    "file-viewer",
+    "dsh-better-sidebar"
   ],
   "author": "CrisLIUning",
   "license": "MIT",
@@ -53,7 +53,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "test": "node test/route.test.mjs && node test/tokens.test.mjs && node test/suite.test.mjs"
+    "test": "node test/route.test.mjs && node test/tokens.test.mjs && node test/add-to-canvas.test.mjs && node test/host-surface.test.mjs"
   },
   "peerDependencies": {
     "dsh-better-sidebar": ">=0.24.0"
@@ -64,9 +64,16 @@
     },
     "client": {
       "inject": [
-        "@deepseek-ai/dsh-client-runtime"
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-sidebar-documentpreview"
       ],
       "platform": "web"
     }
+  },
+  "peerDependenciesMeta": {
+    "dsh-better-sidebar": {
+      "optional": true
+    }
   }
 }