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

package/README.md

@@ -13,16 +13,34 @@
 | 音频 | mp3 / wav / m4a / flac 等；实时频谱；倍速、循环 |
 | HTML | 默认**允许脚本**；相对路径的 CSS / JS / 图片 / 视频 / `fetch` 都能加载；预览 / 源码切换；手机、平板、桌面宽度；脚本开关 |
 | 媒体画廊 | 缩略图网格；按视频 / 音频 / 图片 / 网页筛选、搜索、排序；可包含子文件夹；点开是带上一个 / 下一个（← →）的灯箱 |
+| 加入画布 | 画廊里点「多选」，勾选图片 / 视频 / 音频（Shift 连选、全选），点「加入画布」放进**影视工作台**当前打开的画布；没打开时先在侧栏打开它 |
 
-画廊在右侧栏的 **+ 菜单**里叫「媒体画廊」；每个播放器工具栏里的「画廊」按钮会直接打开它所在的文件夹。
+**在哪里打开**
 
-## 本版变更（0.1.3）
+- 在文件树里点开视频、音频或网页文件，就用本插件的播放器打开（文件预览顶部的切换菜单里可以换回内置预览）。
+- 媒体画廊：右侧栏「开始」页的「媒体画廊」、文件树顶部的「媒体画廊」按钮（打开当前文件夹），或文件预览顶部的「画廊」按钮（打开文件所在的文件夹）。
+
+「加入画布」需要同时启用影视工作台插件（`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.
-- **Withdrawn in 0.1.3** — the 「组件」 / plugin-centre entry 0.1.2 added to the preview toolbar and the gallery footer is gone, because it changed how the sidebar looked; it will be reconsidered after a redesign, and previewing, the gallery and the security notes are unaffected.
+- **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,6 +168,9 @@ window.__ModuleLoader__.load({
         h("rect", { key: "d", x: 9, y: 9, width: 5, height: 5, rx: 1, stroke: "currentColor", strokeWidth: 1.5 }),
       ]);
     }
+    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);
     }
@@ -174,9 +187,14 @@ 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); }
     }
 
@@ -201,7 +219,8 @@ window.__ModuleLoader__.load({
 
     function Shell(p) {
       return h("div", {
-        style: { display: "flex", flexDirection: "column", gap: "8px", padding: "10px", minWidth: 0, minHeight: 0, height: "100%", boxSizing: "border-box" },
+        // 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);
     }
 
@@ -209,7 +228,7 @@ window.__ModuleLoader__.load({
 
     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];
@@ -254,7 +273,7 @@ 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];
@@ -419,6 +438,28 @@ window.__ModuleLoader__.load({
       ]);
     }
 
+    // ── 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) {
@@ -434,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))" },
@@ -446,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,
@@ -505,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]);
@@ -555,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 = [];
@@ -578,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));
@@ -615,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),
@@ -645,43 +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");
         });
       });
     }
 
-    module.exports = { inject: inject, apply: apply };
+    // ── 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.3",
-  "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"
+    "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
+    }
   }
 }