@q253595422/dsh-imagegen-video 1.15.3 → 1.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,77 @@ Attribution for third-party code is in [NOTICE](./NOTICE).
5
5
 
6
6
  ## Releases
7
7
 
8
+ ### 1.16.0 — 视频历史有封面了,侧栏不再猜宿主的类名
9
+
10
+ - **视频历史此前没有封面,这是设计遗漏。** The host never generated a poster
11
+ frame when saving a clip, and `poster` was only populated when the upstream
12
+ happened to return `last_frame_url` — so every row rendered the same film
13
+ glyph. New `src/video-poster.ts` + `src/video-tools.ts` extract a frame with
14
+ the local ffmpeg at 10% of the duration (frame 0 is routinely a black frame
15
+ or a transition), scale it to 320px wide, and store it as
16
+ `<clip名>-poster.jpg`. `src/video-store.ts` gains `StoredVideoFile.posterFile`
17
+ and serves it through the existing `poster` field, so
18
+ `VideoHistoryFile.poster` keeps its meaning — an upstream URL or a same-origin
19
+ host-extracted one, either way just an `<img src>`.
20
+ - **老记录惰性回填,且这一次请求内做完。** Three defects stacked here:
21
+ `BACKFILL_BATCH = 3` left the rest to "the next request"; the panel's
22
+ `initialDataRequestedRef` let `loadInitialData()` run only once per panel
23
+ lifetime on HEAD, so that request never came; and one unreadable clip blocked
24
+ the head of the queue forever. Now `drainVideoPosters()` empties the backlog
25
+ within the request, `posterFailures` (`src/video-store.ts:348`) remembers
26
+ clips that fail so they cost one slot instead of all of them, and the drain's
27
+ fixed point is `attempted === 0` rather than `filled === 0` — a batch whose
28
+ three slots were all unreadable clips fills nothing yet must not stop the
29
+ drain. `src/routes.ts:2501` keeps the drain unawaited but adds the `.catch`
30
+ an unawaited rejection needs: the host's fail-loud handler would otherwise
31
+ turn one unwritable index into `proc.exit(1)`.
32
+ - **侧栏插件条目不再猜宿主的 class 名。** `sidebar-entry.ts` matched
33
+ `[class*="logoRow"]`-style guesses; the host re-hashes CSS Module class names
34
+ every release, and a selector that stops matching fails silently — the entry
35
+ simply disappears. It now reads the slot anchors the host writes into the DOM
36
+ (`[data-slot="sidebar.workspaces"]`, `sidebar.brand.mark`/`.name`,
37
+ `sidebar.footer.action`, `sidebar.settings`), which are a contract rather than
38
+ a build artifact. The middle-column takeover moves the same way:
39
+ `MAIN_SLOT_ANCHOR = '[data-slot="main"]'` plus `boxAncestor()`, which skips
40
+ the `display: contents` anchor itself for the ancestor that actually paints a
41
+ box.
42
+ - **主题切换不再读 OS 偏好。** `surface-theme.ts` watched
43
+ `prefers-color-scheme`, but DSH resolves `system` itself and writes the answer
44
+ onto `body[data-ds-dark-theme]` — the media query was a second source of truth
45
+ that could disagree with the palette actually painted, leaving nav text
46
+ unreadable after a switch. It now observes only the attributes the host
47
+ writes.
48
+ - **拖拽监听不再泄漏。** The chat divider's drag bound three window listeners
49
+ and `cursor`/`user-select` on `<html>` that nothing released after the element
50
+ was destroyed. `stopResizerDragWatch` is now held and released by the mount
51
+ lifetime.
52
+ - **「看起来像原生」变成可检查的规则。** New `docs/native-ui-contract.md`
53
+ (319 lines) plus `scripts/verify-native-ui.mjs` (347 lines) enforcing eight
54
+ rules — literal colors, literal shadows, hardcoded radii, off-scale font
55
+ sizes, `prefers-color-scheme`, tokens DSH does not define, `[class*=]`
56
+ guessing, and theme read from the DOM. Wired into `pnpm test` after
57
+ `verify-reproducible`. 18 `*.module.css` files under `src/client/` were
58
+ migrated onto the tokens.
59
+ - **`pnpm studio:preview`** builds the whole panel into a single-file preview
60
+ bundle and shoots light and dark states in a real Chrome with five in-page
61
+ audits. The 6MB artifact is gitignored.
62
+ - **Dependency:** `@deepseek-ai/dsh-client-ui-primitives`
63
+ `0.1.2-alpha.2` → `0.2.1-rc.2` (the version the host actually ships; the old
64
+ one hardcoded 14px/18px radii where the new one uses
65
+ `var(--dsw-radius-md)`/`var(--dsw-radius-sm)`), plus the `0.2.1-rc.2` dev
66
+ dependencies it needs at pack time — `primitives@0.2.1` ships an empty
67
+ `dependencies` and degrades to unresolved globals if they are not declared.
68
+ - **Cost, stated plainly:** the video row's thumbnail box goes from 54×54 to
69
+ 52×52. `.historyThumbPlaceholder[data-video-thumb]` has had a 1px border since
70
+ HEAD, but `.panel *`'s `box-sizing: border-box` cannot reach it (the history
71
+ list is portalled into the sidebar host, outside the `.panel` subtree, and the
72
+ host ships no universal reset) — so 54×54 was the measured size all along.
73
+ Adding the rule makes clip rows match image rows; the net effect is that
74
+ video rows are 2px smaller. `.pptBadge` contrast goes 2.79:1 → 5.53:1.
75
+ - Full detail, including the end-to-end measurement that the first listing is
76
+ always 0/10 covered and only the client's follow-up read makes the posters
77
+ appear, is in `docs/releases/v1.16.0.md`.
78
+
8
79
  ### 1.15.3 — 视频工作室不再是死路
9
80
 
10
81
  - **生视频标签页此前无法返回生图。** The shell hides the image config sidebar
@@ -0,0 +1,80 @@
1
+ # v1.16.0 — 视频历史有封面了,侧栏不再猜宿主的类名
2
+
3
+ 一句话概括:视频历史的每一行现在有自己的缩略图;侧栏与中间栏的接管从「猜宿主 class 名」改成「读宿主声明的锚点」,不会再因为宿主改一次样式哈希就静默失效。附带一份把「看起来像原生」写成可检查规则的契约,和它的执行器。
4
+
5
+ ## 为什么
6
+
7
+ 这一版处理三类问题。它们都不是新写出来的功能坏了,而是**这一层本来就没写**,或者**写的方法依赖了一个会变的东西**。
8
+
9
+ **第一类:视频历史从来没有封面,这是设计遗漏。** `ImageGenPanel.tsx:583` 在 HEAD 上的注释写着「A clip has no poster frame of its own」——也就是说,前端早就知道这一行只能显示胶片图标,并且把这件事当成了既定事实。宿主侧保存 clip 时从不生成封面帧,`poster` 字段只在「上游偶尔返回 `last_frame_url`」时才有值,其余时候永远是空的。用户看到的就是一列长得一样的胶片图标,分不出哪条是哪条。
10
+
11
+ **第二类:靠猜类名接管宿主界面。** 侧栏插件条目原先用 `[class*="logoRow"]` 这类选择器找位置。宿主每次发版,CSS Module 的 class 名都会重新哈希,猜中的名字下一次构建就可能不存在——而选择器匹配不到时不会有任何报错,只会静默失效:用户看到的是插件条目消失,而不是一条错误。中间栏的接管同理,旧逻辑匹配 `[class*="centerCol"]`。这两个地方都把宿主的**构建期产物**当成了**接口**。
12
+
13
+ **第三类:视频封面的回填永远做不完。** 这是三个缺陷叠在一起,单独看都不致命:
14
+
15
+ - 回填每批只补 `BACKFILL_BATCH = 3` 条,剩下的指望「下一次请求」接手;
16
+ - 但前端 `initialDataRequestedRef` 让 `loadInitialData()` 在 HEAD 上一个面板生命周期只跑一次——开关面板不卸载组件、ref 不重置,第二次请求在正常路径下永远不会发生;
17
+ - 一条读不出来的 clip 会卡在队首,每批都被选中、每批都失败,把后面所有 clip 堵死。
18
+
19
+ 叠起来的结果是:30 条历史里最多 27 条永久没有封面,且没有自愈路径。
20
+
21
+ ## 做了什么
22
+
23
+ - **宿主侧抽帧存盘。** 新增 `src/video-poster.ts`(103 行)与 `src/video-tools.ts`(149 行):用本机 `ffmpeg` 从已落盘的 mp4 里抽一帧,缩到 320 宽存成 JPEG,命名 `<clip名>-poster.jpg`。抽帧位置在**时长的 10%** 而不是首帧——首帧常是黑场或转场,10 个真实 clip 的实测支持了这个选择。320 宽是因为这些图只出现在约 64px 的行缩略图里,再大是浪费。`ffmpeg` 的发现路径来自 `clip-compose.ts` 原有的 `localVideoToolDirs()`(宿主 PATH 不含 `~/.local/bin`,只能用绝对候选路径),这次提取为 `src/video-tools.ts` 供两处共用,`clip-compose.ts` 改为从它导入。
24
+ - **封面进存储与接口。** `src/video-store.ts`(+229 行)新增 `StoredVideoFile.posterFile`;`toWire()` 里 `poster ?? (posterFile ? fileUrl(posterFile) : undefined)`,所以 `VideoHistoryFile.poster` 的语义不变——可能是上游 URL,也可能是宿主抽帧后的同源 URL,前端只当 `<img src>` 用。`readVideoFile()` 的正则多认一个 `-poster.(jpg|jpeg)` 分支,原有的 mp4/webm/mov/mkv 分支一字未改(路径穿越仍然被拒)。
25
+ - **老记录惰性回填。** `backfillVideoPosters()` 每次 `historyList` 时补一批;`drainVideoPosters()` 在这一次请求内把积压排空,不再依赖第二次请求。
26
+ - **失败不再永久堵队。** 模块级 `posterFailures: Set<string>`(`src/video-store.ts:348`)记住抽帧失败的文件名:失败的跳过,同一文件名成功的清除记忆。这样一条坏 clip 只占一次名额。
27
+ - **drain 的收敛判据是「有没有尝试」,不是「有没有成功」。** 这个判据错过一次:按 `filled > 0` 循环时,如果第一批 3 个名额恰好全被不可修复的 clip 占满,`filled === 0` 会让 drain 误判为到达终点而退出,后面健康的 clip 一条都碰不到。现在私有 `backfillVideoPostersDetailed()` 返回 `{ filled, attempted }`,`attempted === 0`(没有任何条目被选中)才是唯一真正的不动点。导出的 `backfillVideoPosters()` 仍是 `Promise<number>`,签名未动。
28
+ - **回填的失败不再能拖垮宿主。** `src/routes.ts:2501` 的 `drainVideoPosters()` 不 await,但必须带 `.catch`:unawaited rejection 会落到进程级 `unhandledRejection`,而宿主的 fail-loud handler 会把它变成 `proc.exit(1)`——一个写不进的索引文件就能让整个宿主退出,只为了一个装饰性的缩略图。
29
+ - **侧栏条目改从锚点解析。** `src/client/sidebar-entry.ts`(+289)不再猜 `[class*="logoRow"]`,改为读宿主写进 DOM 的 slot 锚点:`[data-slot="sidebar.workspaces"]`、`[data-slot="sidebar.brand.mark"|"sidebar.brand.name"]`、`[data-slot="sidebar.footer.action"]`、`[data-slot="sidebar.settings"]`。这些锚点是 `@deepseek-ai/dsh-client-ui-renderer` 的输出契约(`<div data-slot="<key>" style="display: contents">`);class 名是构建期哈希,不是契约。
30
+ - **中间栏接管同样改锚点。** `src/client/mount.tsx`(+152)新增 `MAIN_SLOT_ANCHOR = '[data-slot="main"]'` 与 `boxAncestor()`——后者跳过 `display: contents` 的锚点本身,取真正画盒子的祖先。旧逻辑匹配 `[class*="centerCol"]`。另加 `data-dsh-imagegen-center-col` 自有标记,让样式表只依赖自己的属性而不是宿主的。
31
+ - **主题切换不再读 OS 偏好。** `src/client/surface-theme.ts` 原先监听 `prefers-color-scheme`,但 DSH 自己解析 `system` 并把结果写到 `body[data-ds-dark-theme]` 上,媒体查询是**第二个真相来源**,可能和实际画出来的调色板打架。改为只监听宿主真正写的属性(`data-ds-dark-theme`、`data-ds-theme-source`、`style.color-scheme`、`class`、`data-theme`)。
32
+ - **拖拽监听不再泄漏。** 聊天分隔条拖拽中绑的三个 window 监听和 `<html>` 上的 `cursor`/`user-select`,在元素销毁后无人解绑。新增 `stopResizerDragWatch`,由 mount 生命周期持有释放权。
33
+ - **契约与执行器。** 新增 `docs/native-ui-contract.md`(319 行)把「什么叫看起来像原生」写成可检查的规则:圆角按角色选 token、字号必须落在宿主刻度上、颜色只能取 `--dsw-alias-*`、不许猜宿主 class 名。`scripts/verify-native-ui.mjs`(347 行)是它的执行器,8 条规则:`no-literal-color`、`no-literal-shadow`、`radius-from-token`、`font-size-on-scale`、`no-os-theme-query`、`token-must-exist`、`no-dom-class-guessing`、`theme-from-service`。已接进 `pnpm test`,位置在 `verify-reproducible` 之后、`smoke` 之前。
34
+ - **单命令预览。** 新增 `scripts/studio-preview.{tsx,ts,mjs}` 与 `studio-preview-shot.mjs`:`pnpm studio:preview` 把整个面板构建成单文件预览包,再用真 Chrome 出明暗两态截图并做五类页内审计。产物 `/.studio-preview/` 已进 `.gitignore`(6MB 预览包不进仓库)。
35
+ - **18 个 CSS Module 文件**按契约迁到 token:圆角取 `--dsw-radius-*`、阴影取 `--dsw-shadow-lv*` / `--dsw-elevation-*`、颜色取 `--dsw-alias-*`、字号落到宿主刻度。
36
+
37
+ ## 依赖升级
38
+
39
+ `@deepseek-ai/dsh-client-ui-primitives` 从 `0.1.2-alpha.2` 升到 `0.2.1-rc.2`——插件原先声明的是旧版,宿主实际提供的是新版。差别是真实的:旧版 `Button.module.css` 硬编码 `14px/18px` 圆角,新版是 `var(--dsw-radius-md)` / `var(--dsw-radius-sm)`(12px / 8px),与契约一致。
40
+
41
+ 同批新增 `dsh-util-code-language`、`dsh-util-workspace-path` 两个 `0.2.1-rc.2` 的 devDependencies,并把 0.2.1 运行时需要的打包依赖显式补进 devDependencies。**这条是真陷阱**:`primitives@0.2.1` 的 `dependencies` 是空的,全部放在 `devDependencies` 里,单独打包会退化成未解析的全局变量。同批还显式声明了一批 0.2.1 系列的打包依赖,此处不逐个归因。
42
+
43
+ ## 验证
44
+
45
+ ```
46
+ pnpm typecheck EXIT=0
47
+ pnpm build EXIT=0
48
+ DSH_ASAR_DIR=… node scripts/verify-native-ui.mjs PASS native-UI contract: no violations. EXIT=0
49
+ pnpm test EXIT=0 UI CONTRACTS VERIFIED
50
+ ```
51
+
52
+ drain 的收敛判据做过负向验证:把判据换回 `filled > 0`,30 条好 clip + 6 条坏 clip 在队首的场景下覆盖数从 30/36 掉到 0/36,改回来恢复 30/36。断言承重。
53
+
54
+ 端到端链路实测(这条链跨宿主与前端两侧,单看一侧验不到):
55
+
56
+ ```
57
+ first response: 0/10 covered
58
+ refetch @2000ms: 10/10 covered
59
+ refetch @5000ms: 10/10 covered
60
+
61
+ 30 条上限:
62
+ first response: 0/30 covered
63
+ refetch @2000ms: 30/30 covered
64
+ ```
65
+
66
+ 封面文件本身:`readVideoFile(poster)` → `{"mime":"image/jpeg","size":10366}`,JPEG magic 为 `ff d8`,路径穿越 `../index.json` 被拒。
67
+
68
+ ## 影响面
69
+
70
+ **升级后第一次打开面板,视频历史会先显示一列胶片图标,然后变成封面。** 这是设计如此,不是卡住:宿主只在把列表响应写回之后才开始抽帧,所以第一次响应永远是 0 封面;前端在回填完成后补取一次列表,缩略图才会浮现。10 个 clip 实测抽帧约 1.3s。如果前端不补取,用户看到的就是 10 个胶片图标——这一版的两侧一起才构成完整链路。
71
+
72
+ **视频行的缩略图盒子从 54×54 变成 52×52。** `.historyThumbPlaceholder[data-video-thumb]` 从 HEAD 起就带 `border: 1px solid var(--dsw-alias-border-l1)`,但 `.panel *` 的 `box-sizing: border-box` 够不到它——历史列表被 `createPortal` 到宿主侧栏,在 `.panel` 子树之外,而宿主自己的 CSS 里 universal box-sizing 规则数是 0。所以 HEAD 上它本来就是 54×54(内容盒 52 + 左右各 1px),只是没人量过。这一版补了 `box-sizing: border-box`,让视频行与图片行的缩略图盒真正相等。净效果:**视频行比之前小 2px。**
73
+
74
+ **`.pptBadge` 的对比度从 3.92:1 修到 5.53:1**(amber-600 底 + amber-900 字)。原先是 `#d95732` 底 + 白字,2.79:1,低于 3:1。
75
+
76
+ **老数据**:`~/.dsh/dsh-imagegen/videos/` 现有的 clip 在升级后首次列历史时被惰性回填,索引格式不变,只多一个可选字段。
77
+
78
+ **不改变的**:`VideoHistoryFile.poster` 的接口语义;`readVideoFile()` 原有的四种视频扩展名分支与路径穿越防护;其余挂载点不受 slot 锚点改动影响。
79
+
80
+ **已知代价**:抽帧失败的文件名只在进程内记忆,重启后会被重试一次——这是有意的,因为失败可能是暂时的(磁盘满、ffmpeg 正被占用)。