@vibedev-si/dsh-media-viewer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrisLIUning
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# @vibedev-si/dsh-media-viewer · 右侧栏媒体预览
+
+> 在右侧栏**直接预览视频、音频和 HTML**，并提供**文件夹媒体画廊**。
+> Inline video / audio / HTML preview and a folder media gallery for the DSH right sidebar.
+
+之前点开 `.mp4`、`.wav`、`.html` 只能看到"无法预览"或一个下载面板；装上它之后，这些文件在右侧栏里直接就能播放和渲染。
+
+## 功能
+
+| 能力 | 说明 |
+|---|---|
+| 视频 | mp4 / webm / mov / mkv 等；可拖进度条；倍速、循环；**不限文件大小**（Range 流式传输） |
+| 音频 | mp3 / wav / m4a / flac 等；实时频谱；倍速、循环 |
+| HTML | 默认**允许脚本**；相对路径的 CSS / JS / 图片 / 视频 / `fetch` 都能加载；预览 / 源码切换；手机、平板、桌面宽度；脚本开关 |
+| 媒体画廊 | 缩略图网格；按视频 / 音频 / 图片 / 网页筛选、搜索、排序；可包含子文件夹；点开是带上一个 / 下一个（← →）的灯箱 |
+
+画廊在右侧栏的 **+ 菜单**里叫「媒体画廊」；每个播放器工具栏里的「画廊」按钮会直接打开它所在的文件夹。
+
+## 安装
+
+**前置依赖：[`dsh-better-sidebar`](https://www.npmjs.com/package/dsh-better-sidebar)**（≥ 0.24.0）。它接管了右侧栏的文件打开，本插件通过它的 `registerFileViewer` / `registerTab` 接入。没装它，本插件不会生效。
+
+在 VibeDev / DSH 的插件管理里按包名 `@vibedev-si/dsh-media-viewer` 安装即可，或用命令行：
+
+```sh
+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` 路由：
+
+- 有 **20MB 上限**，整文件读入内存，不支持 HTTP Range，所以大视频打不开、也不能拖进度条；
+- 安全围栏会拒绝沙箱 iframe 里的子资源请求（它们带 `Sec-Fetch-Site: cross-site`），所以带样式、脚本、视频的 HTML 只能加载一半。
+
+本插件自带 `/mp/*` 路由解决这两点，并在沙箱里保持对 GUI 的隔离。
+
+## 安全
+
+- Host 头必须是回环地址或受信任主机（防 DNS rebinding）。
+- 所有路径必须落在**当前会话工作目录**内（符号链接解析之后也一样）。
+- HTML 在**不透明来源**沙箱 iframe 中运行（无 `allow-same-origin`），无法访问 GUI 的 `parent` / `localStorage` / `cookie`。
+- 文件路由只对"子资源类型"的请求放宽 cross-site，且需要有效的会话 id；列表接口始终严格同源。
+- 每个响应都带 CSP `sandbox`，即使在新窗口里直接打开也保持不透明来源。
+
+> HTML 默认允许脚本。预览**不可信**的 HTML 时，请点工具栏的「脚本 开」关掉脚本。
+
+## 已知限制
+
+- HTML 里以 `/` 开头的根相对路径（如 `/logo.png`）会指向 GUI 服务器根，加载不到；请用相对路径。
+- 浏览器本身不支持的编码（常见：H.265 / HEVC）无法播放，会提示并给出下载链接。
+- 画廊单次最多列出 3000 个文件，递归最深 6 层，跳过 `node_modules` 与 `.git`。
+- 目前主要在 Windows 上测试；路径处理按 Windows / POSIX 两种写法实现，但 macOS / Linux 尚未实机验证。
+
+## 开发
+
+```sh
+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):
+
+- **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.
+
+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.
+
+## License
+
+[MIT](./LICENSE) © CrisLIUning

package/client.js

@@ -0,0 +1,680 @@
+/*!
+ * 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
+ *
+ * Bundle format: the official DSH client-bundle shape, a CommonJS-style
+ * factory registered through window.__ModuleLoader__.load. `react` is resolved
+ * from the shell's module table; everything else is inlined.
+ */
+window.__ModuleLoader__.load({
+  id: "@vibedev-si/dsh-media-viewer",
+  factory: (require) => {
+    var module = { exports: {} };
+    "use strict";
+
+    var R = require("react");
+    var h = R.createElement;
+    var useState = R.useState;
+    var useEffect = R.useEffect;
+    var useRef = R.useRef;
+    var useMemo = R.useMemo;
+    var useCallback = R.useCallback;
+
+    // ── file kinds ──────────────────────────────────────────────────────────
+
+    var VIDEO_EXTS = ["mp4", "m4v", "webm", "ogv", "mov", "qt", "mkv", "avi", "wmv", "flv", "mpeg", "mpg", "3gp", "m2ts"];
+    var AUDIO_EXTS = ["mp3", "wav", "m4a", "aac", "oga", "ogg", "opus", "flac", "weba", "aif", "aiff"];
+    var HTML_EXTS = ["html", "htm"];
+    var IMAGE_EXTS = ["png", "jpg", "jpeg", "gif", "webp", "svg", "bmp", "ico", "avif"];
+
+    function extOf(p) {
+      var m = /\.([^.\\/]+)$/.exec(p || "");
+      return m ? m[1].toLowerCase() : "";
+    }
+    function kindOf(p) {
+      var e = extOf(p);
+      if (VIDEO_EXTS.indexOf(e) >= 0) return "video";
+      if (AUDIO_EXTS.indexOf(e) >= 0) return "audio";
+      if (HTML_EXTS.indexOf(e) >= 0) return "html";
+      if (IMAGE_EXTS.indexOf(e) >= 0) return "image";
+      return "other";
+    }
+    function isAbs(p) { return /^([A-Za-z]:[\\/]|[\\/])/.test(p); }
+    function absOf(scope, p) {
+      if (isAbs(p)) return p;
+      var c = (scope && scope.cwd) || "";
+      return c ? c.replace(/[\\/]+$/, "") + "/" + p : p;
+    }
+    function baseName(p) { return (p || "").split(/[\\/]/).filter(Boolean).pop() || p; }
+    function dirName(p) { return (p || "").replace(/[\\/][^\\/]*$/, ""); }
+
+    /** Path-encoded route URL (relative assets of an HTML page resolve inside it). */
+    function fileUrl(scope, abs, query) {
+      var unc = /^[\\/]{2}[^\\/]/.test(abs);
+      var segs = abs.split(/[\\/]+/).filter(Boolean);
+      return "/mp/f/" + encodeURIComponent(scope.sessionId) + "/" + (unc ? "/" : "") +
+        segs.map(encodeURIComponent).join("/") + (query ? "?" + query : "");
+    }
+
+    function fmtSize(n) {
+      if (n == null) return "";
+      if (n < 1024) return n + " B";
+      if (n < 1048576) return (n / 1024).toFixed(0) + " KB";
+      if (n < 1073741824) return (n / 1048576).toFixed(1) + " MB";
+      return (n / 1073741824).toFixed(2) + " GB";
+    }
+    function fmtTime(ms) {
+      if (!ms) return "";
+      var d = new Date(ms);
+      function p(x) { return x < 10 ? "0" + x : "" + x; }
+      return d.getFullYear() + "-" + p(d.getMonth() + 1) + "-" + p(d.getDate()) + " " + p(d.getHours()) + ":" + p(d.getMinutes());
+    }
+    function fmtDur(s) {
+      if (!isFinite(s)) return "";
+      s = Math.round(s);
+      var m = Math.floor(s / 60), r = s % 60;
+      return m + ":" + (r < 10 ? "0" + r : r);
+    }
+
+    // ── styling helpers ─────────────────────────────────────────────────────
+
+    var C = {
+      muted: "var(--dsw-alias-label-secondary, #8b90a0)",
+      link: "var(--dsw-alias-link-normal, #4c8dff)",
+      line: "rgba(127,127,127,.28)",
+      soft: "rgba(127,127,127,.10)",
+      softer: "rgba(127,127,127,.06)",
+      accent: "#7c5cff",
+    };
+
+    var btnBase = {
+      display: "inline-flex", alignItems: "center", gap: "4px", padding: "3px 9px",
+      fontSize: "12px", lineHeight: "18px", borderRadius: "6px", cursor: "pointer",
+      border: "1px solid " + C.line, background: "transparent", color: "inherit",
+      textDecoration: "none", whiteSpace: "nowrap", flex: "none",
+    };
+    function btn(extra) {
+      var o = {};
+      for (var k in btnBase) o[k] = btnBase[k];
+      if (extra) for (var j in extra) o[j] = extra[j];
+      return o;
+    }
+    function Btn(p) {
+      return h("button", {
+        type: "button", title: p.title, onClick: p.onClick, disabled: p.disabled,
+        style: btn(p.active ? { background: C.accent, borderColor: C.accent, color: "#fff" } : p.disabled ? { opacity: 0.5, cursor: "default" } : null),
+      }, p.children);
+    }
+
+    function svg(size, children) {
+      return h("svg", { width: size, height: size, viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", style: { flex: "none" } }, children);
+    }
+    function pathEl(d, extra) {
+      var o = { d: d, stroke: "currentColor", strokeWidth: 1.5, strokeLinecap: "round", strokeLinejoin: "round" };
+      if (extra) for (var k in extra) o[k] = extra[k];
+      return h("path", o);
+    }
+    function IconVideo(size) {
+      return svg(size, [
+        h("rect", { key: "a", x: 1.5, y: 3, width: 13, height: 10, rx: 2, stroke: "currentColor", strokeWidth: 1.5 }),
+        h("path", { key: "b", d: "m6.5 5.9 3.9 2.1-3.9 2.1z", fill: "currentColor" }),
+      ]);
+    }
+    function IconAudio(size) {
+      return svg(size, [
+        pathEl("M6 11.5V3.5l7-1.5v8", { key: "a" }),
+        h("circle", { key: "b", cx: 4.5, cy: 11.5, r: 1.8, stroke: "currentColor", strokeWidth: 1.5 }),
+        h("circle", { key: "c", cx: 11.5, cy: 10, r: 1.8, stroke: "currentColor", strokeWidth: 1.5 }),
+      ]);
+    }
+    function IconHtml(size) {
+      return svg(size, [pathEl("m5.5 4.5-3.2 3.5 3.2 3.5M10.5 4.5l3.2 3.5-3.2 3.5M9 3l-2 10", { key: "a" })]);
+    }
+    function IconImage(size) {
+      return svg(size, [
+        h("rect", { key: "a", x: 1.5, y: 2.5, width: 13, height: 11, rx: 2, stroke: "currentColor", strokeWidth: 1.5 }),
+        h("circle", { key: "b", cx: 5.5, cy: 6, r: 1.2, fill: "currentColor" }),
+        pathEl("m2 12 4-3.5 3 2.5 2-1.5 3 2.5", { key: "c" }),
+      ]);
+    }
+    function IconFolder(size) {
+      return svg(size, [pathEl("M1.8 4.2c0-.7.5-1.2 1.2-1.2h3l1.5 1.7H13c.7 0 1.2.5 1.2 1.2v6.1c0 .7-.5 1.2-1.2 1.2H3c-.7 0-1.2-.5-1.2-1.2z", { key: "a" })]);
+    }
+    function IconGrid(size) {
+      return svg(size, [
+        h("rect", { key: "a", x: 2, y: 2, width: 5, height: 5, rx: 1, stroke: "currentColor", strokeWidth: 1.5 }),
+        h("rect", { key: "b", x: 9, y: 2, width: 5, height: 5, rx: 1, stroke: "currentColor", strokeWidth: 1.5 }),
+        h("rect", { key: "c", x: 2, y: 9, width: 5, height: 5, rx: 1, stroke: "currentColor", strokeWidth: 1.5 }),
+        h("rect", { key: "d", x: 9, y: 9, width: 5, height: 5, rx: 1, stroke: "currentColor", strokeWidth: 1.5 }),
+      ]);
+    }
+    function kindIcon(kind, size) {
+      return kind === "video" ? IconVideo(size) : kind === "audio" ? IconAudio(size) : kind === "html" ? IconHtml(size) : IconImage(size);
+    }
+
+    // ── shared pieces ───────────────────────────────────────────────────────
+
+    /** Header row: title (ellipsis) + actions. */
+    function Bar(p) {
+      return h("div", {
+        style: { display: "flex", alignItems: "center", gap: "6px", flex: "none", fontSize: "12px", minWidth: 0, flexWrap: "wrap" },
+      }, [
+        h("span", { key: "t", title: p.path, style: { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", flex: "1 1 120px", minWidth: 0, color: C.muted } }, p.title),
+        p.children,
+      ]);
+    }
+
+    function openGallery(props, abs) {
+      try {
+        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) {
+      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: "下载原文件" }, "下载"),
+      ];
+      if (!props.hideGallery) {
+        out.push(h(Btn, { key: "gal", title: "浏览所在文件夹的全部媒体", onClick: function () { openGallery(props, abs); } }, [IconGrid(12), "画廊"]));
+      }
+      return out;
+    }
+
+    var RATES = [0.5, 1, 1.5, 2];
+
+    function RatePicker(p) {
+      return RATES.map(function (r) {
+        return h(Btn, { key: r, active: p.rate === r, title: "播放速度 " + r + "x", onClick: function () { p.set(r); } }, r + "x");
+      });
+    }
+
+    function Shell(p) {
+      return h("div", {
+        style: { display: "flex", flexDirection: "column", gap: "8px", padding: "10px", minWidth: 0, minHeight: 0, height: "100%", boxSizing: "border-box" },
+      }, p.children);
+    }
+
+    // ── video ───────────────────────────────────────────────────────────────
+
+    function VideoView(props) {
+      var abs = absOf(props.scope, props.path);
+      var url = fileUrl(props.scope, 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];
+
+      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, 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 } }, [
+                h("div", { key: 1 }, "浏览器无法解码这个视频"),
+                h("div", { key: 2, style: { color: "#999", fontSize: "12px" } }, err),
+                h("div", { key: 3, style: { marginTop: "8px" } }, h("a", { href: fileUrl(props.scope, abs, "download=1"), download: baseName(abs), style: { color: C.link } }, "下载后用本地播放器打开")),
+              ])
+            : h("video", {
+                key: url, ref: vref, src: url, controls: true, loop: loop, preload: "metadata", playsInline: true,
+                style: { width: "100%", height: "100%", objectFit: "contain", background: "#000", outline: "none" },
+                onLoadedMetadata: function (e) {
+                  setDur(e.target.duration);
+                  if (e.target.videoWidth) setDim(e.target.videoWidth + "×" + e.target.videoHeight);
+                },
+                onError: function (e) {
+                  var code = e.target && e.target.error ? e.target.error.code : 0;
+                  setErr(code === 4 ? "格式或编码不受支持（常见于 H.265 / 非标准封装）" : "加载失败（错误码 " + code + "）");
+                },
+              })),
+        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),
+        ]),
+      ]);
+    }
+
+    // ── audio ───────────────────────────────────────────────────────────────
+
+    function AudioView(props) {
+      var abs = absOf(props.scope, props.path);
+      var url = fileUrl(props.scope, 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];
+
+      useEffect(function () { setErr(null); setDur(null); }, [url]);
+      useEffect(function () { if (aref.current) aref.current.playbackRate = rate; }, [rate, url]);
+
+      // Spectrum bars. Same-origin media, so the analyser is allowed to read it.
+      useEffect(function () {
+        var a = aref.current, cv = cref.current;
+        if (!a || !cv) return undefined;
+        var ac, an, data, raf = 0, dead = false;
+        function draw() {
+          if (dead) return;
+          raf = requestAnimationFrame(draw);
+          var g = cv.getContext("2d");
+          var w = cv.width, hh = cv.height;
+          g.clearRect(0, 0, w, hh);
+          var n = data.length, bw = w / n;
+          an.getByteFrequencyData(data);
+          var grad = g.createLinearGradient(0, hh, 0, 0);
+          grad.addColorStop(0, "#7c5cff");
+          grad.addColorStop(1, "#22d3ee");
+          g.fillStyle = grad;
+          for (var i = 0; i < n; i++) {
+            var bh = Math.max(2, (data[i] / 255) * hh);
+            g.fillRect(i * bw + 1, hh - bh, Math.max(1, bw - 2), bh);
+          }
+        }
+        function start() {
+          if (ac) { if (ac.state === "suspended") ac.resume(); return; }
+          try {
+            var AC = window.AudioContext || window.webkitAudioContext;
+            ac = new AC();
+            var src = ac.createMediaElementSource(a);
+            an = ac.createAnalyser();
+            an.fftSize = 128;
+            an.smoothingTimeConstant = 0.8;
+            src.connect(an);
+            an.connect(ac.destination);
+            data = new Uint8Array(an.frequencyBinCount);
+            draw();
+          } catch (e) { /* visualiser is decoration; playback must not depend on it */ }
+        }
+        a.addEventListener("play", start);
+        return function () {
+          dead = true;
+          cancelAnimationFrame(raf);
+          a.removeEventListener("play", start);
+          try { if (ac) ac.close(); } catch (e) { /* ignore */ }
+        };
+      }, [url]);
+
+      return h(Shell, null, [
+        h("div", {
+          key: "stage",
+          style: {
+            flex: "1 1 auto", minHeight: 0, display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "center",
+            gap: "14px", padding: "16px", borderRadius: "10px", background: "linear-gradient(145deg, rgba(124,92,255,.14), rgba(34,211,238,.10))",
+          },
+        }, [
+          h("div", { key: "ic", style: { width: "72px", height: "72px", borderRadius: "50%", display: "flex", alignItems: "center", justifyContent: "center", background: "linear-gradient(135deg,#7c5cff,#22d3ee)", color: "#fff" } }, IconAudio(34)),
+          h("div", { key: "nm", style: { fontSize: "14px", fontWeight: 600, textAlign: "center", wordBreak: "break-all" } }, baseName(abs)),
+          h("canvas", { key: "cv", ref: cref, width: 320, height: 64, style: { width: "100%", maxWidth: "320px", height: "64px" } }),
+          err
+            ? h("div", { key: "er", style: { color: C.muted, fontSize: "12px" } }, err)
+            : h("audio", {
+                key: url, ref: aref, src: url, controls: true, loop: loop, preload: "metadata", style: { width: "100%", maxWidth: "420px" },
+                onLoadedMetadata: function (e) { setDur(e.target.duration); },
+                onError: function () { setErr("这个音频浏览器无法解码"); },
+              }),
+        ]),
+        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),
+        ]),
+      ]);
+    }
+
+    // ── html ────────────────────────────────────────────────────────────────
+
+    var VIEWPORTS = [
+      { id: "fit", label: "自适应", w: null },
+      { id: "phone", label: "手机 390", w: 390 },
+      { id: "pad", label: "平板 768", w: 768 },
+      { id: "desk", label: "桌面 1280", w: 1280 },
+    ];
+
+    function HtmlView(props) {
+      var abs = absOf(props.scope, props.path);
+      var url = fileUrl(props.scope, abs);
+      var md = useState("render"), mode = md[0], setMode = md[1];
+      var sc = useState(true), scripts = sc[0], setScripts = sc[1];
+      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 frameRef = useRef(null);
+
+      useEffect(function () { setMode("render"); setSource({ state: "idle", text: "" }); }, [url]);
+
+      // Navigate the frame only after it exists WITH its sandbox attribute.
+      // The iframe is re-keyed whenever url / reloadKey / scripts change, so
+      // this runs against the fresh element each time.
+      useEffect(function () {
+        if (mode === "render" && frameRef.current) frameRef.current.src = url + "?v=" + reloadKey;
+      }, [mode, url, reloadKey, scripts]);
+
+      useEffect(function () {
+        if (mode !== "source") return undefined;
+        var ctl = new AbortController();
+        setSource({ state: "loading", text: "" });
+        fetch(url + "?v=" + reloadKey, { signal: ctl.signal })
+          .then(function (r) { if (!r.ok) throw new Error("HTTP " + r.status); return r.text(); })
+          .then(function (t) { setSource({ state: "ok", text: t.length > 2000000 ? t.slice(0, 2000000) + "\n\n… (已截断，文件过大)" : t }); })
+          .catch(function (e) { if (e.name !== "AbortError") setSource({ state: "error", text: String(e.message || e) }); });
+        return function () { ctl.abort(); };
+      }, [mode, url, reloadKey]);
+
+      var sandbox = "allow-popups allow-downloads allow-modals allow-forms allow-pointer-lock" + (scripts ? " allow-scripts" : "");
+      var vw = VIEWPORTS.filter(function (v) { return v.id === view; })[0].w;
+
+      var stage;
+      if (mode === "source") {
+        stage = h("pre", {
+          style: { margin: 0, padding: "10px", flex: "1 1 auto", minHeight: 0, overflow: "auto", fontSize: "12px", lineHeight: 1.55, whiteSpace: "pre", tabSize: 2, fontFamily: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace", background: C.softer, borderRadius: "8px" },
+        }, source.state === "loading" ? "加载中…" : source.state === "error" ? "读取失败：" + source.text : source.text);
+      } else {
+        stage = h("div", {
+          style: { flex: "1 1 auto", minHeight: 0, overflow: "auto", display: "flex", justifyContent: "center", background: vw ? C.soft : "transparent", borderRadius: "8px" },
+        }, h("iframe", {
+          key: url + ":" + reloadKey + ":" + (scripts ? "s" : "n"),
+          ref: frameRef,
+          // NO src here: the browser snapshots the sandbox flags when the
+          // frame first navigates, so `src` must be assigned only after the
+          // element exists with its sandbox attribute (see the effect above).
+          title: baseName(abs),
+          sandbox: sandbox,
+          allow: "autoplay; fullscreen; clipboard-write",
+          allowFullScreen: true,
+          referrerPolicy: "no-referrer",
+          style: { width: vw ? vw + "px" : "100%", maxWidth: "none", height: "100%", border: "1px solid " + C.line, borderRadius: "8px", background: "#fff", flex: "none" },
+        }));
+      }
+
+      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"); } }, "预览"),
+          h(Btn, { key: "m2", active: mode === "source", title: "查看源码", onClick: function () { setMode("source"); } }, "源码"),
+          mode === "render" ? VIEWPORTS.map(function (v) {
+            return h(Btn, { key: v.id, active: view === v.id, title: "预览宽度：" + v.label, onClick: function () { setView(v.id); } }, v.label);
+          }) : 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),
+        ]),
+      ]);
+    }
+
+    // ── gallery ─────────────────────────────────────────────────────────────
+
+    function Thumb(p) {
+      var it = p.item, scope = p.scope;
+      var ref = useRef(null);
+      var vs = useState(false), vis = vs[0], setVis = vs[1];
+      var vid = useRef(null);
+      useEffect(function () {
+        var el = ref.current;
+        if (!el || typeof IntersectionObserver === "undefined") { setVis(true); return undefined; }
+        var io = new IntersectionObserver(function (es) { if (es[0].isIntersecting) { setVis(true); io.disconnect(); } }, { rootMargin: "240px" });
+        io.observe(el);
+        return function () { io.disconnect(); };
+      }, []);
+
+      var url = fileUrl(scope, it.abs);
+      var inner;
+      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 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))" },
+      }, [kindIcon(it.kind, 28), h("span", { key: "e", style: { fontSize: "11px", opacity: 0.8, fontWeight: 600 } }, it.ext.toUpperCase())]);
+
+      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; } },
+        style: { position: "relative", width: "100%", aspectRatio: "16 / 10", background: C.soft, overflow: "hidden", borderRadius: "8px 8px 0 0" },
+      }, [
+        inner,
+        h("span", { key: "badge", style: { position: "absolute", left: "6px", top: "6px", display: "inline-flex", alignItems: "center", gap: "3px", padding: "1px 6px", borderRadius: "10px", fontSize: "10px", background: "rgba(0,0,0,.55)", color: "#fff" } }, [kindIcon(it.kind, 10), it.ext.toUpperCase()]),
+      ]);
+    }
+
+    var FILTERS = [
+      { id: "all", label: "全部" },
+      { id: "video", label: "视频" },
+      { id: "audio", label: "音频" },
+      { id: "image", label: "图片" },
+      { id: "html", label: "网页" },
+    ];
+    var SIZES = [{ id: 150, label: "小" }, { id: 210, label: "中" }, { id: 300, label: "大" }];
+
+    function Lightbox(p) {
+      var it = p.item;
+      var vprops = { ctx: p.ctx, store: p.store, scope: p.scope, path: it.abs, title: it.name, hideGallery: true };
+      var body;
+      if (it.kind === "video") body = h(VideoView, vprops);
+      else if (it.kind === "audio") body = h(AudioView, vprops);
+      else if (it.kind === "html") body = h(HtmlView, vprops);
+      else body = h("div", { style: { height: "100%", display: "flex", padding: "10px", boxSizing: "border-box" } },
+        h("img", { src: fileUrl(p.scope, it.abs), style: { margin: "auto", maxWidth: "100%", maxHeight: "100%", objectFit: "contain" } }));
+
+      var nav = { position: "absolute", top: "50%", transform: "translateY(-50%)", width: "30px", height: "56px", border: "none", borderRadius: "6px", background: "rgba(127,127,127,.35)", color: "inherit", cursor: "pointer", fontSize: "18px", zIndex: 2 };
+      return h("div", {
+        style: { position: "absolute", inset: 0, zIndex: 20, display: "flex", flexDirection: "column", background: "var(--dsw-alias-bg-primary, var(--dsw-alias-surface-primary, #fff))" },
+      }, [
+        h("div", { key: "top", style: { display: "flex", alignItems: "center", gap: "8px", padding: "8px 10px", borderBottom: "1px solid " + C.line, fontSize: "12px", flex: "none" } }, [
+          h(Btn, { key: "x", title: "返回画廊 (Esc)", onClick: p.onClose }, "← 返回"),
+          h("span", { key: "t", style: { flex: 1, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap", fontWeight: 600 } }, it.name),
+          h("span", { key: "n", style: { color: C.muted } }, (p.index + 1) + " / " + p.total + "  ·  " + fmtSize(it.size)),
+        ]),
+        h("div", { key: "body", style: { position: "relative", flex: "1 1 auto", minHeight: 0 } }, [
+          p.index > 0 ? h("button", { key: "prev", type: "button", title: "上一个 (←)", onClick: p.onPrev, style: Object.assign({ left: "4px" }, nav) }, "‹") : null,
+          p.index < p.total - 1 ? h("button", { key: "next", type: "button", title: "下一个 (→)", onClick: p.onNext, style: Object.assign({ right: "4px" }, nav) }, "›") : null,
+          h("div", { key: "c", style: { position: "absolute", inset: 0 } }, body),
+        ]),
+      ]);
+    }
+
+    function GalleryTab(props) {
+      var scope = props.scope;
+      var seed = (props.tab && props.tab.path) || "";
+      var cu = useState(seed), cur = cu[0], setCur = cu[1];
+      var rc = useState(false), recursive = rc[0], setRecursive = rc[1];
+      var dt = useState(null), data = dt[0], setData = dt[1];
+      var ls = useState(true), loading = ls[0], setLoading = ls[1];
+      var er = useState(null), error = er[0], setError = er[1];
+      var fl = useState("all"), filter = fl[0], setFilter = fl[1];
+      var qs = useState(""), query = qs[0], setQuery = qs[1];
+      var so = useState("mtime"), sort = so[0], setSort = so[1];
+      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];
+
+      // Follow a re-seeded tab (opened again for another folder).
+      useEffect(function () { setCur(seed); }, [seed]);
+
+      useEffect(function () {
+        var ctl = new AbortController();
+        setLoading(true);
+        setError(null);
+        var q = "sessionId=" + encodeURIComponent(scope.sessionId) + (cur ? "&dir=" + encodeURIComponent(cur) : "") + (recursive ? "&recursive=1" : "");
+        fetch("/mp/list?" + q, { signal: ctl.signal })
+          .then(function (r) { return r.json().then(function (j) { if (!r.ok || !j.ok) throw new Error((j && j.error && j.error.message) || "HTTP " + r.status); return j; }); })
+          .then(function (j) { setData(j); setLoading(false); })
+          .catch(function (e) { if (e.name !== "AbortError") { setError(String(e.message || e)); setLoading(false); } });
+        return function () { ctl.abort(); };
+      }, [scope.sessionId, cur, recursive, tick]);
+
+      var items = useMemo(function () {
+        if (!data) return [];
+        var q = query.trim().toLowerCase();
+        var list = data.files.filter(function (f) {
+          return (filter === "all" || f.kind === filter) && (q === "" || f.rel.toLowerCase().indexOf(q) >= 0);
+        });
+        list.sort(function (a, b) {
+          if (sort === "name") return a.rel.localeCompare(b.rel, "zh", { numeric: true });
+          if (sort === "size") return b.size - a.size;
+          return b.mtime - a.mtime;
+        });
+        return list;
+      }, [data, filter, query, sort]);
+
+      var counts = useMemo(function () {
+        var c = { all: 0, video: 0, audio: 0, image: 0, html: 0 };
+        if (data) data.files.forEach(function (f) { c.all++; c[f.kind]++; });
+        return c;
+      }, [data]);
+
+      // Keyboard: Esc / arrows while the lightbox is open.
+      useEffect(function () {
+        if (sel < 0 || props.visible === false) return undefined;
+        function onKey(e) {
+          if (e.key === "Escape") { setSel(-1); e.stopPropagation(); }
+          else if (e.key === "ArrowLeft") setSel(function (s) { return Math.max(0, s - 1); });
+          else if (e.key === "ArrowRight") setSel(function (s) { return Math.min(items.length - 1, s + 1); });
+        }
+        window.addEventListener("keydown", onKey, true);
+        return function () { window.removeEventListener("keydown", onKey, true); };
+      }, [sel, items.length, props.visible]);
+
+      useEffect(function () { setSel(-1); }, [cur, recursive, filter, query]);
+
+      var dir = data ? data.dir : cur;
+      var root = data ? data.cwd : "";
+      var crumbs = [];
+      if (data) {
+        var rel = data.dir.replace(/\\/g, "/").slice(data.cwd.replace(/\\/g, "/").length).split("/").filter(Boolean);
+        var acc = data.cwd;
+        crumbs.push({ name: baseName(data.cwd) || data.cwd, abs: data.cwd });
+        rel.forEach(function (seg) { acc = acc.replace(/[\\/]+$/, "") + "/" + seg; crumbs.push({ name: seg, abs: acc }); });
+      }
+
+      var chip = function (active) {
+        return btn(active ? { background: C.accent, borderColor: C.accent, color: "#fff" } : null);
+      };
+
+      var header = h("div", { key: "head", style: { flex: "none", display: "flex", flexDirection: "column", gap: "7px", padding: "9px 10px", borderBottom: "1px solid " + C.line } }, [
+        h("div", { key: "r1", style: { display: "flex", alignItems: "center", gap: "4px", fontSize: "12px", flexWrap: "wrap", minWidth: 0 } }, [
+          crumbs.map(function (c, i) {
+            return h(R.Fragment, { key: c.abs }, [
+              i > 0 ? h("span", { key: "s", style: { color: C.muted } }, "/") : null,
+              h("button", { key: "b", type: "button", onClick: function () { setCur(c.abs); }, title: c.abs, style: { border: "none", background: "transparent", color: i === crumbs.length - 1 ? "inherit" : C.link, cursor: "pointer", padding: "1px 3px", fontSize: "12px", fontWeight: i === crumbs.length - 1 ? 600 : 400 } }, c.name),
+            ]);
+          }),
+          h("span", { key: "sp", style: { flex: 1 } }),
+          h(Btn, { key: "rf", title: "重新扫描文件夹", onClick: function () { setTick(tick + 1); } }, "刷新"),
+        ]),
+        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));
+          }),
+          h("input", { key: "q", type: "search", placeholder: "搜索文件名", value: query, onChange: function (e) { setQuery(e.target.value); }, style: { flex: "1 1 110px", minWidth: "90px", padding: "3px 8px", fontSize: "12px", borderRadius: "6px", border: "1px solid " + C.line, background: "transparent", color: "inherit" } }),
+        ]),
+        h("div", { key: "r3", style: { display: "flex", alignItems: "center", gap: "10px", fontSize: "12px", flexWrap: "wrap", color: C.muted } }, [
+          h("label", { key: "rec", style: { display: "inline-flex", alignItems: "center", gap: "4px", cursor: "pointer" } }, [
+            h("input", { key: "i", type: "checkbox", checked: recursive, onChange: function (e) { setRecursive(e.target.checked); } }), "包含子文件夹",
+          ]),
+          h("label", { key: "so", style: { display: "inline-flex", alignItems: "center", gap: "4px" } }, [
+            "排序",
+            h("select", { key: "s", value: sort, onChange: function (e) { setSort(e.target.value); }, style: { fontSize: "12px", background: "transparent", color: "inherit", border: "1px solid " + C.line, borderRadius: "5px", padding: "1px 4px" } }, [
+              h("option", { key: 1, value: "mtime" }, "最近修改"), h("option", { key: 2, value: "name" }, "名称"), h("option", { key: 3, value: "size" }, "大小"),
+            ]),
+          ]),
+          h("span", { key: "sz", style: { display: "inline-flex", alignItems: "center", gap: "4px" } }, ["缩略图", SIZES.map(function (s) {
+            return h("button", { key: s.id, type: "button", onClick: function () { setSize(s.id); }, style: chip(size === s.id) }, s.label);
+          })]),
+          h("span", { key: "ct", style: { marginLeft: "auto" } }, items.length + " 项" + (data && data.truncated ? "（已达上限，结果被截断）" : "")),
+        ]),
+      ]);
+
+      var body;
+      if (error) {
+        body = h("div", { key: "body", style: { margin: "auto", padding: "24px", textAlign: "center", color: C.muted, fontSize: "13px", lineHeight: 1.7 } }, ["读取文件夹失败", h("br", { key: "b" }), error]);
+      } else if (!data && loading) {
+        body = h("div", { key: "body", style: { margin: "auto", color: C.muted, fontSize: "13px" } }, "扫描中…");
+      } else {
+        var dirCards = recursive ? [] : data.dirs.map(function (d) {
+          return h("button", { key: "d:" + d.abs, type: "button", onClick: function () { setCur(d.abs); }, title: d.abs, style: { display: "flex", alignItems: "center", gap: "8px", padding: "10px", borderRadius: "8px", border: "1px dashed " + C.line, background: C.softer, color: "inherit", cursor: "pointer", textAlign: "left", fontSize: "12px", minWidth: 0 } }, [
+            IconFolder(16), h("span", { key: "n", style: { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" } }, d.name),
+          ]);
+        });
+        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 } }, [
+            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),
+              h("div", { key: "i", style: { color: C.muted, fontSize: "11px", marginTop: "1px" } }, fmtSize(it.size) + "  ·  " + fmtTime(it.mtime)),
+            ]),
+          ]);
+        });
+        body = h("div", { key: "body", style: { flex: "1 1 auto", minHeight: 0, overflow: "auto", padding: "10px" } }, [
+          dirCards.length > 0 ? h("div", { key: "dirs", style: { display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(150px, 1fr))", gap: "8px", marginBottom: "10px" } }, dirCards) : null,
+          cards.length > 0
+            ? h("div", { key: "grid", style: { display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(" + size + "px, 1fr))", gap: "10px", opacity: loading ? 0.55 : 1 } }, cards)
+            : h("div", { key: "empty", style: { padding: "40px 10px", textAlign: "center", color: C.muted, fontSize: "13px" } }, data.files.length === 0 ? "这个文件夹里没有视频、音频、图片或网页文件" : "没有符合筛选条件的文件"),
+        ]);
+      }
+
+      return h("div", { style: { position: "relative", height: "100%", display: "flex", flexDirection: "column", overflow: "hidden", minWidth: 0 } }, [
+        header,
+        body,
+        sel >= 0 && items[sel]
+          ? h(Lightbox, {
+              key: "lb", ctx: props.ctx, store: props.store, scope: scope, item: items[sel], index: sel, total: items.length,
+              onClose: function () { setSel(-1); },
+              onPrev: function () { setSel(Math.max(0, sel - 1)); },
+              onNext: function () { setSel(Math.min(items.length - 1, sel + 1)); },
+            })
+          : null,
+      ]);
+    }
+
+    // ── registration ────────────────────────────────────────────────────────
+
+    var inject = ["betterSidebar"];
+
+    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,
+        });
+      });
+      ctx.effect(function () {
+        return ctx.betterSidebar.registerFileViewer({
+          id: "mp:audio", title: "音频播放器", icon: IconAudio, exts: AUDIO_EXTS, priority: 10, fetchStrategy: "none", component: AudioView,
+        });
+      });
+      ctx.effect(function () {
+        return ctx.betterSidebar.registerFileViewer({
+          id: "mp:html", title: "网页预览（允许脚本）", icon: IconHtml, exts: HTML_EXTS, priority: 10, fetchStrategy: "none", component: HtmlView,
+        });
+      });
+      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,
+        });
+      });
+    }
+
+    module.exports = { inject: inject, apply: apply };
+    return module.exports;
+  },
+});

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# @vibedev-si/dsh-media-viewer bundle patch: one `insert` row mounting the plugin.
+# The entry `name` must equal the package name so the client-modules scan
+# resolves the package's ./client bundle and serves it at
+# /plugins/@vibedev-si/dsh-media-viewer/client.js.
+- insert:
+    - id: media-viewer
+      name: '@vibedev-si/dsh-media-viewer'

package/icon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#7C5CFF"/>
+      <stop offset="1" stop-color="#22D3EE"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="14" fill="url(#g)"/>
+  <rect x="10" y="12" width="44" height="30" rx="6" fill="#FFFFFF"/>
+  <path d="M28 20v14l12-7z" fill="#7C5CFF"/>
+  <rect x="10" y="47" width="12" height="7" rx="2.5" fill="#FFFFFF" opacity="0.95"/>
+  <rect x="26" y="47" width="12" height="7" rx="2.5" fill="#FFFFFF" opacity="0.8"/>
+  <rect x="42" y="47" width="12" height="7" rx="2.5" fill="#FFFFFF" opacity="0.6"/>
+</svg>

package/index.js

@@ -0,0 +1,407 @@
+/**
+ * dsh-media-viewer — host half.
+ *
+ * Two routes, both under the single prefix `/mp`:
+ *
+ *   GET|HEAD /mp/f/<sessionId>/<absolute path segments>
+ *       Streams one file from the session working directory. Supports HTTP
+ *       Range (206), so <video>/<audio> can seek, and has NO size cap (the
+ *       built-in /sidebar/file route reads whole files into memory and refuses
+ *       anything over 20MB).
+ *       The path is encoded into the URL PATH (not the query) so that a
+ *       previewed HTML page's relative assets (./style.css, clip.mp4, img/a.png)
+ *       resolve back into this same route with the session intact.
+ *
+ *   GET /mp/list?sessionId=<id>[&dir=<path>][&recursive=1]
+ *       JSON listing of the media files (video/audio/image/html) in a folder,
+ *       for the gallery tab.
+ *
+ * Security posture:
+ *  - Host header must be loopback or a configured trusted authority (DNS
+ *    rebinding defence), same as the /api gateway.
+ *  - Every path must resolve (symlinks included) inside the session's working
+ *    directory.
+ *  - The listing route and top-level document loads keep the strict
+ *    same-origin fence. The FILE route relaxes exactly one rule: a sandboxed
+ *    preview iframe has an opaque origin, so its sub-resource requests carry
+ *    `Sec-Fetch-Site: cross-site` and `Origin: null`. Those are accepted for
+ *    sub-resource destinations only, and only for a live session id, which
+ *    acts as the capability.
+ *  - Every file response carries a CSP `sandbox` directive, so even a
+ *    top-level load of an HTML file stays in an opaque origin.
+ */
+import { createReadStream } from 'node:fs'
+import { readdir, realpath, stat } from 'node:fs/promises'
+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']
+
+// ── content types ───────────────────────────────────────────────────────────
+
+const TYPES = {
+  // video
+  '.mp4': 'video/mp4', '.m4v': 'video/mp4', '.webm': 'video/webm', '.ogv': 'video/ogg',
+  '.mov': 'video/quicktime', '.qt': 'video/quicktime', '.mkv': 'video/x-matroska',
+  '.avi': 'video/x-msvideo', '.wmv': 'video/x-ms-wmv', '.flv': 'video/x-flv',
+  '.mpeg': 'video/mpeg', '.mpg': 'video/mpeg', '.3gp': 'video/3gpp', '.m2ts': 'video/mp2t',
+  // audio
+  '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.m4a': 'audio/mp4', '.aac': 'audio/aac',
+  '.oga': 'audio/ogg', '.ogg': 'audio/ogg', '.opus': 'audio/ogg', '.flac': 'audio/flac',
+  '.weba': 'audio/webm', '.aif': 'audio/aiff', '.aiff': 'audio/aiff',
+  // image
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.svg': 'image/svg+xml', '.bmp': 'image/bmp', '.ico': 'image/x-icon',
+  '.avif': 'image/avif',
+  // web
+  '.html': 'text/html; charset=utf-8', '.htm': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8', '.json': 'application/json; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8', '.md': 'text/plain; charset=utf-8',
+  '.vtt': 'text/vtt; charset=utf-8', '.srt': 'text/plain; charset=utf-8',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf',
+  '.wasm': 'application/wasm',
+}
+
+const KINDS = {
+  video: new Set(['.mp4', '.m4v', '.webm', '.ogv', '.mov', '.qt', '.mkv', '.avi', '.wmv', '.flv', '.mpeg', '.mpg', '.3gp', '.m2ts']),
+  audio: new Set(['.mp3', '.wav', '.m4a', '.aac', '.oga', '.ogg', '.opus', '.flac', '.weba', '.aif', '.aiff']),
+  image: new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.bmp', '.ico', '.avif']),
+  html: new Set(['.html', '.htm']),
+}
+
+function kindOfExt(ext) {
+  for (const kind of Object.keys(KINDS)) if (KINDS[kind].has(ext)) return kind
+  return undefined
+}
+
+const SANDBOX_CSP = "sandbox allow-scripts allow-popups allow-downloads allow-modals allow-forms; object-src 'none'"
+
+// ── browser-trust fence ─────────────────────────────────────────────────────
+
+const header = (headers, key) => (typeof headers[key] === 'string' ? headers[key] : undefined)
+
+function parseAuthority(authority) {
+  try { return new URL(`http://${authority}`) } catch { return undefined }
+}
+
+function isLoopbackHostname(hostname) {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  const parts = hostname.split('.')
+  return parts.length === 4 && parts[0] === '127'
+    && parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255)
+}
+
+function isTrustedAuthority(hostUrl, trustedHosts) {
+  return trustedHosts.some((entry) => {
+    const entryUrl = parseAuthority(entry)
+    if (entryUrl === undefined) return false
+    return entryUrl.port === '' ? entryUrl.hostname === hostUrl.hostname : entryUrl.host === hostUrl.host
+  })
+}
+
+/** Sub-resource destinations a previewed page legitimately requests. */
+const SUBRESOURCE_DESTS = new Set([
+  '', 'image', 'script', 'style', 'video', 'audio', 'track', 'font', 'manifest',
+  'worker', 'sharedworker', 'empty', 'iframe', 'frame', 'object', 'embed',
+])
+
+/**
+ * @param relaxed - true for the file route: also admit opaque-origin
+ *   (sandboxed iframe) sub-resource requests.
+ */
+function trusted(req, trustedHosts, relaxed) {
+  const host = header(req.headers, 'host')
+  if (host === undefined) return false
+  const hostUrl = parseAuthority(host)
+  if (hostUrl === undefined) return false
+  if (!isLoopbackHostname(hostUrl.hostname) && !isTrustedAuthority(hostUrl, trustedHosts)) return false
+
+  const site = header(req.headers, 'sec-fetch-site')
+  const origin = header(req.headers, 'origin')
+  if (site === 'cross-site') {
+    if (!relaxed) return false
+    if (!SUBRESOURCE_DESTS.has(header(req.headers, 'sec-fetch-dest') ?? '')) return false
+    return origin === undefined || origin === 'null'
+  }
+  if (origin === undefined) return true
+  if (relaxed && origin === 'null') return true
+  try { return new URL(origin).hostname === hostUrl.hostname } catch { return false }
+}
+
+// ── paths ───────────────────────────────────────────────────────────────────
+
+class HttpError extends Error {
+  constructor(status, message) {
+    super(message)
+    this.status = status
+  }
+}
+
+const norm = (v) => v.replace(/[\\/]+/g, '/').replace(/\/$/, '')
+
+function isWithin(base, target) {
+  const b = norm(base)
+  const t = norm(target)
+  if (process.platform === 'win32') {
+    const lb = b.toLowerCase()
+    const lt = t.toLowerCase()
+    return lt === lb || lt.startsWith(`${lb}/`)
+  }
+  return t === b || t.startsWith(`${b}/`)
+}
+
+function requireAbsolute(path) {
+  if (!path.startsWith('/') && !/^[A-Za-z]:[\\/]/.test(path)) {
+    throw new HttpError(400, `"${path}" is not an absolute path`)
+  }
+  return resolve(path)
+}
+
+/** `/mp/f/<sid>/<segments>` -> { sessionId, path }. UNC marker and drive letter handled like better-sidebar. */
+function decodeFilePath(pathname) {
+  const PREFIX = '/mp/f/'
+  if (!pathname.startsWith(PREFIX)) throw new HttpError(404, 'not a file route')
+  let segments
+  try {
+    segments = pathname.slice(PREFIX.length).split('/').map((s) => decodeURIComponent(s))
+  } catch {
+    throw new HttpError(400, 'malformed URL encoding')
+  }
+  const [sessionId, ...rest] = segments
+  if (!sessionId) throw new HttpError(400, 'sessionId is required')
+  const unc = rest[0] === ''
+  const tail = unc ? rest.slice(1) : rest
+  if (tail.length === 0 || tail.some((s) => s === '')) throw new HttpError(400, 'file path is required')
+  let path
+  if (unc) path = `//${tail.join('/')}`
+  else if (/^[A-Za-z]:$/.test(tail[0])) path = tail.join('/')
+  else path = `/${tail.join('/')}`
+  return { sessionId, path }
+}
+
+/** The live session's authoritative working directory. */
+function liveCwd(ctx, sessionId) {
+  const cwd = ctx.sessions.get(sessionId)?.header?.cwd
+  if (typeof cwd !== 'string' || cwd === '') {
+    throw new HttpError(409, 'session is not attached; reload the page and reopen the file')
+  }
+  return cwd
+}
+
+/** Resolve `target` and prove (symlinks included) that it lives inside `cwd`. */
+async function confine(cwd, target) {
+  const abs = requireAbsolute(target)
+  if (!isWithin(cwd, abs)) throw new HttpError(403, 'path is outside the session working directory')
+  let real
+  let realCwd
+  try {
+    real = await realpath(abs)
+    realCwd = await realpath(cwd)
+  } catch {
+    throw new HttpError(404, 'not found')
+  }
+  if (!isWithin(realCwd, real)) throw new HttpError(403, 'path resolves outside the session working directory')
+  return real
+}
+
+// ── responses ───────────────────────────────────────────────────────────────
+
+function sendJson(res, status, body) {
+  const buf = Buffer.from(JSON.stringify(body))
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': String(buf.length),
+    'cache-control': 'no-store',
+  })
+  res.end(buf)
+}
+
+function sendError(res, error) {
+  const status = error instanceof HttpError ? error.status : 500
+  if (res.headersSent) { res.destroy(); return }
+  sendJson(res, status, { ok: false, error: { message: error?.message ?? String(error) } })
+}
+
+/** Single `Range: bytes=` header -> {start,end} | null | {unsatisfiable:true}. */
+function parseRange(raw, size) {
+  if (raw === undefined) return null
+  const m = /^bytes=(.+)$/i.exec(raw.trim())
+  if (!m) return null
+  const spec = m[1].split(',')[0].trim()
+  if (spec === '') return null
+  if (spec.startsWith('-')) {
+    const suffix = Number(spec.slice(1))
+    if (!Number.isFinite(suffix) || suffix <= 0) return null
+    return suffix >= size ? { start: 0, end: size - 1 } : { start: size - suffix, end: size - 1 }
+  }
+  const dash = spec.indexOf('-')
+  if (dash === -1) return null
+  const start = spec.slice(0, dash) === '' ? 0 : Number(spec.slice(0, dash))
+  const end = spec.slice(dash + 1) === '' ? size - 1 : Number(spec.slice(dash + 1))
+  if (!Number.isInteger(start) || start < 0 || !Number.isInteger(end)) return null
+  if (start >= size) return { unsatisfiable: true }
+  return { start, end: Math.min(end, size - 1) }
+}
+
+function serveFile(req, res, path, size, type, extra) {
+  const base = {
+    'content-type': type,
+    'accept-ranges': 'bytes',
+    'cache-control': 'no-cache',
+    '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)
+  if (range?.unsatisfiable) {
+    res.writeHead(416, { ...base, 'content-range': `bytes */${size}` })
+    res.end()
+    return
+  }
+  const stream = (opts) => {
+    const s = createReadStream(path, opts)
+    s.on('error', () => res.destroy())
+    res.on('close', () => s.destroy())
+    s.pipe(res)
+  }
+  if (range) {
+    res.writeHead(206, { ...base, 'content-range': `bytes ${range.start}-${range.end}/${size}`, 'content-length': String(range.end - range.start + 1) })
+    if (req.method === 'HEAD') { res.end(); return }
+    stream({ start: range.start, end: range.end })
+    return
+  }
+  res.writeHead(200, { ...base, 'content-length': String(size) })
+  if (req.method === 'HEAD') { res.end(); return }
+  stream({})
+}
+
+// ── listing ─────────────────────────────────────────────────────────────────
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.svn', '.hg'])
+const MAX_ENTRIES = 3000
+const MAX_DEPTH = 6
+
+async function statMany(items) {
+  const out = []
+  for (let i = 0; i < items.length; i += 32) {
+    const chunk = items.slice(i, i + 32)
+    const rows = await Promise.all(chunk.map(async (it) => {
+      try {
+        const info = await stat(it.abs)
+        return { ...it, size: info.size, mtime: info.mtimeMs }
+      } catch {
+        return undefined
+      }
+    }))
+    for (const r of rows) if (r) out.push(r)
+  }
+  return out
+}
+
+async function listMedia(root, recursive) {
+  const files = []
+  const dirs = []
+  let truncated = false
+  const queue = [{ abs: root, depth: 0 }]
+  while (queue.length > 0 && !truncated) {
+    const { abs, depth } = queue.shift()
+    let names
+    try {
+      names = await readdir(abs, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const d of names) {
+      const child = resolve(abs, d.name)
+      if (d.isDirectory()) {
+        if (depth === 0) dirs.push({ name: d.name, abs: child })
+        if (recursive && depth < MAX_DEPTH && !SKIP_DIRS.has(d.name)) queue.push({ abs: child, depth: depth + 1 })
+      } else if (d.isFile()) {
+        const kind = kindOfExt(extname(d.name).toLowerCase())
+        if (kind === undefined) continue
+        if (files.length >= MAX_ENTRIES) { truncated = true; break }
+        files.push({ name: d.name, abs: child, kind })
+      }
+    }
+  }
+  const rows = await statMany(files)
+  const rootNorm = norm(root)
+  for (const r of rows) {
+    r.rel = norm(r.abs).slice(rootNorm.length).replace(/^\//, '')
+    r.ext = extname(r.name).slice(1).toLowerCase()
+  }
+  dirs.sort((a, b) => a.name.localeCompare(b.name, 'zh'))
+  return { files: rows, dirs: dirs.filter((d) => !SKIP_DIRS.has(d.name)), truncated }
+}
+
+// ── plugin body ─────────────────────────────────────────────────────────────
+
+export function apply(ctx) {
+  const trustedHosts = () => ctx.webRuntime.trustedHosts
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix',
+    path: '/mp',
+    handler: async (req, res) => {
+      try {
+        const url = new URL(req.url ?? '/', 'http://dsh.internal')
+        const isFile = url.pathname.startsWith('/mp/f/')
+
+        if (!trusted(req, trustedHosts(), isFile)) throw new HttpError(403, 'forbidden')
+
+        if (req.method === 'OPTIONS' && isFile) {
+          res.writeHead(204, {
+            'access-control-allow-origin': '*',
+            'access-control-allow-methods': 'GET, HEAD, OPTIONS',
+            'access-control-allow-headers': 'range, if-range',
+            'access-control-max-age': '600',
+          })
+          res.end()
+          return
+        }
+        if (req.method !== 'GET' && !(req.method === 'HEAD' && isFile)) throw new HttpError(405, 'method not allowed')
+
+        if (isFile) {
+          const { sessionId, path } = decodeFilePath(url.pathname)
+          const real = await confine(liveCwd(ctx, sessionId), path)
+          const info = await stat(real)
+          if (!info.isFile()) throw new HttpError(400, 'not a file')
+          const type = TYPES[extname(real).toLowerCase()] ?? 'application/octet-stream'
+          const extra = { 'access-control-allow-origin': '*', 'access-control-expose-headers': 'content-length, content-range, accept-ranges' }
+          if (url.searchParams.get('download') === '1') {
+            extra['content-disposition'] = `attachment; filename*=UTF-8''${encodeURIComponent(basename(real))}`
+          }
+          if (info.size === 0) {
+            res.writeHead(200, { 'content-type': type, 'content-length': '0', 'content-security-policy': SANDBOX_CSP, ...extra })
+            res.end()
+            return
+          }
+          serveFile(req, res, real, info.size, type, extra)
+          return
+        }
+
+        if (url.pathname === '/mp/list') {
+          const sessionId = url.searchParams.get('sessionId')
+          if (!sessionId) throw new HttpError(400, 'sessionId is required')
+          const cwd = liveCwd(ctx, sessionId)
+          const dirParam = url.searchParams.get('dir')
+          const dir = await confine(cwd, dirParam ? resolve(cwd, dirParam) : cwd)
+          const info = await stat(dir)
+          if (!info.isDirectory()) throw new HttpError(400, 'not a directory')
+          const { files, dirs, truncated } = await listMedia(dir, url.searchParams.get('recursive') === '1')
+          sendJson(res, 200, { ok: true, cwd: resolve(cwd), dir, files, dirs, truncated })
+          return
+        }
+
+        throw new HttpError(404, 'unknown route')
+      } catch (error) {
+        sendError(res, error)
+      }
+    },
+  }), 'dsh-media-viewer: /mp file + list routes')
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@vibedev-si/dsh-media-viewer",
+  "version": "0.1.0",
+  "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",
+  "type": "module",
+  "main": "index.js",
+  "icon": "./icon.svg",
+  "files": [
+    "index.js",
+    "client.js",
+    "icon.svg",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./index.js",
+    "./client": {
+      "default": "./client.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "vibedev",
+    "dsh-better-sidebar",
+    "better-sidebar",
+    "video",
+    "audio",
+    "html",
+    "preview",
+    "gallery",
+    "file-viewer"
+  ],
+  "author": "CrisLIUning",
+  "license": "MIT",
+  "homepage": "https://github.com/VibeDev-Si/dsh-media-viewer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VibeDev-Si/dsh-media-viewer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/VibeDev-Si/dsh-media-viewer/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "node test/route.test.mjs"
+  },
+  "peerDependencies": {
+    "dsh-better-sidebar": ">=0.24.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    }
+  }
+}