Repository navigation
v0.8.0 — 网页演示:笔记里就地跑可交互 HTML(2026-11-03)
动机
笔记里一直只能指向一个 HTML 演示(写个链接,点开去浏览器看),而这类东西的意义就在
"拖一下、看它变" —— 离开笔记、切窗口、再切回来,理解成本全在切换上。用户原话:
「就是插入 html 的网页演示……让网页能够在笔记里面直接显示,而不仅仅是插入路径」。
新功能
```embed <路径>围栏 → 就地沙箱 iframe:脚本真的执行(用户在 Analog IC 的
三电平 SAR 演示上验收:拖 ΔV 滑块,图跟着变)。路径相对笔记目录解析;也可写
title:/height:两行配置(path:/src:同义),高度 160–2400、默认 560。- 底边拖拽调高度,按文件记在
localStorage['dsh-notes:embed-size'](最近 200 条),
重开笔记仍是上次的高度;拖完不会因为"点了下别处"就把 iframe 重载。 - 条上三枚按钮:「源码」(光标回到围栏)、「刷新」(带 nonce 重载)、「在新标签打开」
(仅 http(s) 载体;桌面壳的自定义 scheme 下不显示)。 - 工具栏 21 → 22 键:插入组新增「插入网页演示」;右键「插入」子菜单同步加一条。
- 光标进入围栏 → 显示原始 markdown(与代码卡一致);移开 → 恢复 iframe。
安全模型(这是本版最需要知道的)
- 服务端是插件自己的
GET /dsh-notes/embed,不是官方/api/file:后者响应头是
Content-Security-Policy: sandbox; default-src 'none',HTML 进 iframe 后脚本/样式全被禁,
做不出交互。 - 响应头
EMBED_CSP:sandbox(不带allow-same-origin)+ 放行内联脚本/样式 + 断网
(default-src 'none'/connect-src 'none')+nosniff/no-referrer/no-store。
于是演示页拿不到parent.document、document.cookie、localStorage,也发不出网络请求 ——
演示页必须自包含(内联 CSS/JS、data:图片;CDN 与相对资源都不行)。 - 读取边界 = 当前工作区(笔记面板可切到别的已登记工作区,所以
workspaceKey一路从面板传到
路由);两边都用fs.processPath的 realpath 派生路径比对,挡..与符号链接逃逸;
只认.html/.htm,单文件上限 8MB。越界/非 HTML/缺失/超限在 iframe 里显示可读的错误页,
而不是一坨 JSON。 - 配置
htmlEmbed(默认true):关掉 = 该路由一律 403 错误页,其他功能不变。
实现要点(给后来改这块的人)
- 块级替换只能在
table.ts的 StateField 里做,且围栏要独占整行(被>引用/列表包住的
退回代码卡)。EmbedWidget.eq()刻意不比from(否则在块上方打字就重载 iframe)、也
不比"算出来的初始高度"(拖拽只改 localStorage),位置用view.posAtDOM(root, 0)现取。 - 纯逻辑独立成
embed-model.ts(解析/路径/URL/高度夹取)与embed-size.ts(高度记忆),
在 Node 里可测;Host 侧service.readEmbed(只读,readBytes缺失时退化readText)。 - 新增单测:317 条全绿(新增
embed-model/embed-size/service-embed,并扩了routes
与locale-guard)。
已知边界(不是 bug)
- 演示页滚出视口再滚回来,iframe 会被 CM6 重建、演示状态重置(没有做 keep-alive);
- iframe 获得焦点时编辑器快捷键不生效(点回正文即恢复);滚轮在 iframe 上滚的是演示页;
- 只支持自包含页面;需要 CDN / 相对资源 / 联网的演示,请用「在新标签打开」或直接在浏览器里看。
本次 Release 同时纳入此前未单独发版的 v0.7.1 / v0.7.2 / v0.7.3(公式字体、外部改动不丢位置 + 图片预留尺寸、历史兜底覆盖 notes/ 之外)——对应 CHANGELOG 里的同名段。