dsh-knit 0.16.0 → 0.18.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.
@@ -748,7 +748,7 @@ test('媒体:默认文档视图有三个类型按钮,但不出现媒体网
748
748
 
749
749
  const btns = byClass(nodes, 'knit-type-btn')
750
750
  assert.equal(btns.length, 3)
751
- assert.deepEqual(btns.map(textOf), ['文档', '图片与视频', '全部'])
751
+ assert.deepEqual(btns.map(textOf), ['文档', '媒体', '全部'])
752
752
  assert.equal(btns.find((b) => textOf(b) === '文档').props['aria-selected'], true)
753
753
  assert.equal(byClass(nodes, 'knit-media-grid').length, 0)
754
754
  assert.equal(byClass(nodes, 'knit-doc').length, 2)
@@ -840,7 +840,7 @@ test('媒体:「全部」分上下两区,文档上限 4、媒体一格不隐
840
840
  assert.equal(byExactClass(nodes, 'knit-section').length, 2, '文档区 + 媒体区,上下两区')
841
841
  assert.deepEqual(
842
842
  byExactClass(nodes, 'knit-section-title').map(textOf),
843
- ['文档', '图片与视频'],
843
+ ['文档', '媒体'],
844
844
  )
845
845
  assert.equal(byToken(nodes, 'knit-doc').length, 4, '文档区最多 4 条')
846
846
  // 载荷里 5 图 + 4 视频 = 9 个媒体:一格都不隐藏,纵向也**不封顶**(有多少行铺多少行)
@@ -957,7 +957,7 @@ test('媒体:只有媒体时「全部」的媒体区不截断、也不给「
957
957
  nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
958
958
 
959
959
  assert.equal(byExactClass(nodes, 'knit-section').length, 1, '只有媒体区')
960
- assert.deepEqual(byExactClass(nodes, 'knit-section-title').map(textOf), ['图片与视频'])
960
+ assert.deepEqual(byExactClass(nodes, 'knit-section-title').map(textOf), ['媒体'])
961
961
  assert.equal(byExactClass(nodes, 'knit-section-more').length, 0, '媒体区不截断,没有「查看全部」')
962
962
  assert.equal(byToken(nodes, 'knit-media-card').length, 9)
963
963
  })
@@ -1270,7 +1270,7 @@ test('样式:文档列表没有网格 —— 多列那套已整体删除,容
1270
1270
  assert.match(css, /\.knit-title\{flex:1 1 auto;min-width:0;font-weight:600;font-size:14px;line-height:1\.4;/)
1271
1271
  // 2026-10-01:`.knit-gapmark`(没号时的中性占位标记)与序号**共用同一条选择器**,
1272
1272
  // 所以「序号的行高必须等于标题行高」这条纪律自动覆盖它。
1273
- assert.match(css, /\.knit-num,\.knit-gapmark\{grid-column:1;font-size:10\.5px;line-height:19\.6px;/)
1273
+ assert.match(css, /\.knit-num,\.knit-gapmark\{grid-column:1;font-size:11px;line-height:19\.6px;/)
1274
1274
 
1275
1275
  // ⚠️ 行的**静止态没有底色**(2026-09-29 用户看了暗色主题之后要求:
1276
1276
  // 「深色模式下,文档列表没有选中,鼠标没有悬停,不需要有背景。或者是说,跟深色模式的最底下的
@@ -1436,7 +1436,7 @@ test('样式:预览面板底色恒为纯阅读底色,不靠底色分层;
1436
1436
  assert.ok(!css.includes('transition:background-color'))
1437
1437
  })
1438
1438
 
1439
- test('媒体:点类型按钮切到「图片与视频」会带 kind=media 重拉并记住偏好', async () => {
1439
+ test('媒体:点类型按钮切到「媒体」会带 kind=media 重拉并记住偏好', async () => {
1440
1440
  const { calls } = installFetch(kindResponder({ doc: listPayload(), media: mediaPayload() }))
1441
1441
  const { KnitBody } = loadClientModule().exports.__test
1442
1442
  harness.reset()
@@ -1445,7 +1445,7 @@ test('媒体:点类型按钮切到「图片与视频」会带 kind=media 重
1445
1445
  await harness.flush()
1446
1446
  nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1447
1447
 
1448
- byClass(nodes, 'knit-type-btn').find((b) => textOf(b) === '图片与视频').props.onClick()
1448
+ byClass(nodes, 'knit-type-btn').find((b) => textOf(b) === '媒体').props.onClick()
1449
1449
  nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
1450
1450
  await harness.flush()
1451
1451
  nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
@@ -1991,8 +1991,8 @@ test('样式:组与组之间只靠 16px 空间(不再画横线),序号
1991
1991
  // 字号:标题 14px / 行高 1.4 = 19.6px;序号的 line-height 必须与它同步,
1992
1992
  // 这是「序号与标题第一行垂直居中」的唯一手段(改一处必须改两处)
1993
1993
  assert.match(source, /\.knit-title\{flex:1 1 auto;min-width:0;font-weight:600;font-size:14px;line-height:1\.4;/)
1994
- assert.match(source, /\.knit-num,\.knit-gapmark\{grid-column:1;font-size:10\.5px;line-height:19\.6px;/)
1995
- assert.match(source, /\.knit-sum\{font-size:12px;line-height:19px;/)
1994
+ assert.match(source, /\.knit-num,\.knit-gapmark\{grid-column:1;font-size:11px;line-height:19\.6px;/)
1995
+ assert.match(source, /\.knit-sum\{font-size:12px;line-height:18px;/)
1996
1996
  })
1997
1997
 
1998
1998
  /* ── v0.15「使用情况」 ───────────────────────────────────────────────
@@ -2046,7 +2046,7 @@ test('使用情况:默认关 —— 请求里没有 usage=1,DOM 里也没有
2046
2046
  assert.equal(byExactClass(nodes, 'knit-usage').length, 0, '默认关:不显示那一行')
2047
2047
  })
2048
2048
 
2049
- test('使用情况:打开后请求带 usage=1,那一行只报事实(没有分数 / 百分比)', async () => {
2049
+ test('v0.18 使用情况:打开后请求带 usage=1,Lens 只报事实(没有分数 / 百分比)', async () => {
2050
2050
  const { calls } = installFetch(() => usagePayload())
2051
2051
  const { KnitBody } = loadClientModule().exports.__test
2052
2052
  harness.reset()
@@ -2069,16 +2069,21 @@ test('使用情况:打开后请求带 usage=1,那一行只报事实(没有
2069
2069
 
2070
2070
  assert.ok(calls.some((url) => url.includes('usage=1')), '打开后必须带 usage=1')
2071
2071
  const line = byExactClass(nodes, 'knit-usage')[0]
2072
- assert.ok(line, '打开后必须出现那一行')
2072
+ assert.ok(line, '打开后必须出现 Usage Lens')
2073
2073
  const text = textOf(line)
2074
- assert.match(text, /当前上下文 · Epoch 4/, '当前上下文的编号要如实说出来')
2075
- assert.match(text, /已读/, '先看的那篇被读了要如实说出来')
2076
- assert.match(text, /辅助 1\/2/)
2077
- assert.match(text, /读了 7 次/)
2078
- assert.match(text, /包外 2 篇/)
2079
- assert.match(text, /上下文换过 2 次/)
2074
+ assert.match(text, /使用情况/, 'Lens 标题')
2075
+ assert.match(text, /Epoch 4/, '当前上下文的编号要如实说出来')
2076
+ // 摘要行只留三件事实:读了几次 / 几篇包外 / 换过几次
2077
+ assert.match(text, /7 次读取/)
2078
+ assert.match(text, /2 篇包外/)
2079
+ assert.match(text, /上下文变化 2 次/)
2080
2080
  assert.ok(!text.includes('%'), '不许有百分比')
2081
2081
  assert.ok(!/评分|置信|分数/.test(text), '不许有评分 / 置信度这类词')
2082
+ // Coverage:三层各自的「已读 ÷ 本层总数」;v0.15 载荷没有 lifecycle ⇒ 全是未读
2083
+ assert.deepEqual(byExactClass(nodes, 'knit-cov-num').map(textOf), ['0 / 1', '0 / 2', '0 / 1'])
2084
+ const dots = dotsOf(nodes)
2085
+ assert.equal(dots.length, 4, '每一篇正文都要有一个状态点')
2086
+ assert.ok(dots.every((dot) => !String(dot.props.className).includes('on')), '没有记录就是未读')
2082
2087
  })
2083
2088
 
2084
2089
  test('样式:使用情况那一行是弱化文字 —— 没有卡片 / 进度条 / 品牌色', async () => {
@@ -2088,7 +2093,8 @@ test('样式:使用情况那一行是弱化文字 —— 没有卡片 / 进度
2088
2093
  fileURLToPath(new URL('../src/client/client.js', import.meta.url)),
2089
2094
  'utf8',
2090
2095
  )
2091
- assert.match(source, /\.knit-usage\{[^}]*font-size:10\.5px/)
2096
+ // v0.18 UI 迭代(md §四十七 的尺度表):这一块从 10.5px 提到 **12px**。
2097
+ assert.match(source, /\.knit-usage\{[^}]*font-size:12px/)
2092
2098
  assert.ok(!/\.knit-usage\{[^}]*background/.test(source), '不画卡片底色')
2093
2099
  assert.ok(!/\.knit-usage\{[^}]*knit-accent/.test(source), '不用品牌色')
2094
2100
  assert.ok(!/\.knit-usage\{[^}]*width:\s*\d/.test(source), '不是进度条')
@@ -2175,3 +2181,1098 @@ test('可见性:官方座位把契约的 `tab.visible` 一路传到 KnitBody',
2175
2181
  assert.equal(listCalls(calls).length, 1, '拿不到 visible 时要照旧取数')
2176
2182
  })
2177
2183
 
2184
+ /* ── v0.17 文档生命周期 ───────────────────────────────────────────────
2185
+ 五条纪律一起守:
2186
+ ① 文档行只多**一个弱化文字**(未读 / 已读 ×N / 读后已更新 / 修改后已重新读取)——
2187
+ 不抢标题、不加图标、不加颜色、不评分;
2188
+ ② 「最近读取」是**事实**(最近一次成功 read 的文件),不是「正在阅读」;
2189
+ ③ 上下文外读取默认折叠,展开才逐篇列出,且**只陈述**「不在包里但读过」;
2190
+ ④ 只展示**最近一次** Context Delta,符号只有 `+` / `-` / `↔`,绝不生成时间线;
2191
+ ⑤ 以上一切只在「使用情况」打开时出现 —— 关着时 DOM 与 v0.16 逐字一致。 */
2192
+
2193
+ /** 取节点直接子节点里 className **整段**匹配的那些。
2194
+ * 扁平节点列表里裸看 `.children` 会把兄弟行的节点也算进来,所以按父节点取。 */
2195
+ function kidsOf(node, className) {
2196
+ return (node.children || []).filter((n) => n && n.props && String(n.props.className || '') === className)
2197
+ }
2198
+
2199
+ /**
2200
+ * 一份带 v0.17 生命周期投影的载荷:四种状态各来一篇,外加包外两篇。
2201
+ * 每篇文档在行里的期望文案见 `LIFE_EXPECTED`。
2202
+ */
2203
+ function lifecyclePayload(overrides = {}) {
2204
+ const delta = overrides.delta || {
2205
+ appeared: [{ rel: 'docs/algo.md', tier: 'primary', rank: 1 }],
2206
+ disappeared: [{ rel: 'README.md', tier: 'related', rank: 4 }],
2207
+ moved: [{ rel: 'docs/eval.md', from: 'supporting', to: 'related' }],
2208
+ taskChanged: false,
2209
+ }
2210
+ return contextPayload({
2211
+ usage: {
2212
+ at: 1_700_000_000_000,
2213
+ epochId: 4,
2214
+ stats: {
2215
+ reads: 7,
2216
+ distinct: 3,
2217
+ outside: 2,
2218
+ outsideReads: ['docs/old-plan.md', 'docs/test-case.md'],
2219
+ firstReadTier: 'primary',
2220
+ firstReadRel: 'docs/algo.md',
2221
+ firstReadAt: 1,
2222
+ primaryRel: 'docs/algo.md',
2223
+ primaryFollowThrough: true,
2224
+ byTier: {
2225
+ primary: { total: 1, read: 1 },
2226
+ supporting: { total: 2, read: 1 },
2227
+ related: { total: 1, read: 0 },
2228
+ },
2229
+ supportingCoverage: 0.5,
2230
+ churn: { snapshots: 2, deltas: 2, retained: 2, appeared: 1, disappeared: 1, moved: 1, taskChanged: 0 },
2231
+ },
2232
+ delta,
2233
+ latestDelta: delta,
2234
+ recentRead: {
2235
+ rel: 'docs/eval.md',
2236
+ at: Date.now() - 12 * 60_000,
2237
+ seq: 42,
2238
+ epochId: 4,
2239
+ tier: 'supporting',
2240
+ rank: 2,
2241
+ inside: true,
2242
+ },
2243
+ // 宿主回的是**阅读顺序**(seq = 首次读);面板要按「读得最多」重排 ——
2244
+ // 另一个用例会刻意把这里的顺序反过来,验证排序真的发生在客户端。
2245
+ outsideDocs: overrides.outsideDocs || [
2246
+ { rel: 'docs/old-plan.md', count: 3, lastReadAt: 1, seq: 10 },
2247
+ { rel: 'docs/test-case.md', count: 1, lastReadAt: 2, seq: 20 },
2248
+ ],
2249
+ lifecycle: {
2250
+ 'docs/algo.md': { status: 'read', count: 3, lastReadAt: 1 },
2251
+ 'docs/eval.md': { status: 'reread_after_update', count: 2, lastReadAt: 2 },
2252
+ 'CHANGELOG.md': { status: 'updated_after_read', count: 1, lastReadAt: 3 },
2253
+ 'README.md': { status: 'unread', count: 0, lastReadAt: 0 },
2254
+ 'docs/old-plan.md': { status: 'read', count: 3, lastReadAt: 4 },
2255
+ 'docs/test-case.md': { status: 'read', count: 1, lastReadAt: 5 },
2256
+ },
2257
+ },
2258
+ })
2259
+ }
2260
+
2261
+ /** 分层视图里五行文档各自该显示的状态文字(顺序 = 屏幕顺序)。
2262
+ * v0.18 起「已读」只说次数:圈点已经把「读过」说完了,文字里再写一遍是重复。 */
2263
+ const LIFE_EXPECTED = ['×3', '修改后已重新读取', '读后已更新', '未读', '未读']
2264
+
2265
+ /** 同一屏里五行各自该显示的**状态点**(v0.18 UI 迭代起是 CSS 圆点,不是字符)。
2266
+ * `data-mark` 四态 = read / reread / updated / unread;它与上面的文字**同时**存在:
2267
+ * 只给点读不出「读了几次」,只给文字看不出「哪几篇同档」。 */
2268
+ const GLYPH_EXPECTED = ['read', 'reread', 'updated', 'unread', 'unread']
2269
+
2270
+ /** 预览面板里正在显示哪一篇(只看文件名那一格)。 */
2271
+ function openNameOf(nodes) {
2272
+ const name = byExactClass(nodes, 'knit-preview-name')[0]
2273
+ return name ? textOf(name) : ''
2274
+ }
2275
+
2276
+ /** Coverage 的状态点。className 可能是 `knit-cov-dot` 也可能是 `knit-cov-dot on`。
2277
+ * ⚠️ 不能用 `byClass`:它是**子串**匹配,会把容器 `.knit-cov-dots` 一起算进来。 */
2278
+ function dotsOf(nodes) {
2279
+ return nodes.filter((node) => node && node.props
2280
+ && String(node.props.className || '').split(' ').includes('knit-cov-dot'))
2281
+ }
2282
+
2283
+
2284
+ /**
2285
+ * 挂上面板并**打开「使用情况」**(数据到位后再点,与真实用法一致)。
2286
+ * @param {object} payload - 宿主载荷
2287
+ * @returns {Promise<{nodes:object[], render:Function, calls:string[]}>} 节点与重渲染
2288
+ */
2289
+ async function mountUsage(payload) {
2290
+ const { calls } = installFetch(() => payload)
2291
+ const { KnitBody } = loadClientModule().exports.__test
2292
+ harness.reset()
2293
+ harness.seed(['', 'relevance'])
2294
+ const render = () => harness.render(h(KnitBody, { sessionId: 's1' }))
2295
+ let nodes = render()
2296
+ await harness.flush()
2297
+ nodes = render()
2298
+ await harness.flush()
2299
+ nodes = render()
2300
+ const toggle = byExactClass(nodes, 'knit-btn').find((node) => textOf(node) === '使用情况')
2301
+ assert.ok(toggle, '头部必须有「使用情况」按钮')
2302
+ toggle.props.onClick()
2303
+ await harness.flush()
2304
+ nodes = render()
2305
+ await harness.flush()
2306
+ return { nodes: render(), render, calls }
2307
+ }
2308
+
2309
+ test('v0.17 生命周期:使用情况关着 —— 一个状态节点都不出现', async () => {
2310
+ const { calls } = installFetch(() => lifecyclePayload())
2311
+ const { KnitBody } = loadClientModule().exports.__test
2312
+ harness.reset()
2313
+ harness.seed(['', 'relevance'])
2314
+ const render = () => harness.render(h(KnitBody, { sessionId: 's1' }))
2315
+ render()
2316
+ await harness.flush()
2317
+ const nodes = render()
2318
+
2319
+ assert.ok(!calls.some((url) => url.includes('usage=1')), '关着就不该开闸')
2320
+ assert.equal(byExactClass(nodes, 'knit-life').length, 0, '关着不许有状态文字')
2321
+ assert.equal(byExactClass(nodes, 'knit-usage-more').length, 0, '关着不许有折叠区')
2322
+ assert.equal(byExactClass(nodes, 'knit-more-btn').length, 0, '关着不许有展开按钮')
2323
+ const rowText = byExactClass(nodes, 'knit-row1').map(textOf).join(' ')
2324
+ assert.ok(!/未读|已读|读后已更新|修改后已重新读取/.test(rowText), '关着时行里只有标题与时间')
2325
+ })
2326
+
2327
+ test('v0.18 生命周期:四种状态都落在文档行里,且只是一枚 glyph + 一段极短文字', async () => {
2328
+ const { nodes } = await mountUsage(lifecyclePayload())
2329
+
2330
+ const lives = byExactClass(nodes, 'knit-life')
2331
+ assert.deepEqual(lives.map(textOf), LIFE_EXPECTED, '四档事实状态按屏幕顺序逐行显示')
2332
+ // 状态文字是**弱化辅助信息**:没有图标、没有 aria、没有颜色、没有百分比
2333
+ for (const node of lives) {
2334
+ assert.deepEqual(Object.keys(node.props).sort(), ['className'], '状态文字只是一个 span')
2335
+ }
2336
+ // v0.18:状态**点**与状态**文字**同时存在(规格 §10 / §13)
2337
+ const glyphs = byExactClass(nodes, 'knit-glyph')
2338
+ // v0.18 UI 迭代:点从 `○ ● △ ↻` 字符改成 **CSS 圆点**(6px,与 Coverage 同一套语言),
2339
+ // 于是「哪一档」不再看字符、看 `data-mark`;只有「修改后已重新读取」仍留一个 ↻ 记号。
2340
+ const marks = byExactClass(nodes, 'knit-glyph-mark')
2341
+ assert.deepEqual(marks.map((node) => node.props['data-mark']), GLYPH_EXPECTED,
2342
+ '每一行正好一枚状态点,四档各归其位')
2343
+ assert.deepEqual(marks.map((node) => node.props['aria-hidden']), ['true', 'true', 'true', 'true', 'true'],
2344
+ '状态点本身是装饰 —— 「哪一档」由 aria-label 说出来,不让读屏念两遍')
2345
+ assert.deepEqual(glyphs.map(textOf), ['', '↻', '', '', ''],
2346
+ 'CSS 圆之后只有 reread 还带字符')
2347
+ for (const node of glyphs) {
2348
+ assert.equal(node.props.type, 'button', '状态点可点 → 必须是真 button')
2349
+ assert.ok(node.props['aria-label'], '状态点必须有 aria-label')
2350
+ assert.ok(node.props.title, '状态点必须有 tooltip')
2351
+ assert.equal(node.props.style, undefined, '状态点不带内联颜色')
2352
+ }
2353
+ assert.deepEqual(glyphs.map((node) => node.props['aria-label']), [
2354
+ '已读 ×3', '修改后已重新读取', '读后已更新', '未读', '未读',
2355
+ ], 'tooltip / aria-label 把这一档状态解释清楚')
2356
+ const allText = textOf(byExactClass(nodes, 'knit-usage')[0])
2357
+ assert.ok(!allText.includes('%'), '不许有百分比')
2358
+ assert.ok(!/评分|置信|分数|质量|命中率|漏召回/.test(allText), '不许把事实写成评分')
2359
+ // 圈点那一格原本是 Primary 的黑点:统计开着时让给状态点,一行只有一个标记
2360
+ assert.equal(byExactClass(nodes, 'knit-dot').length, 0, 'usage 开着时不再画 Primary 黑点')
2361
+ })
2362
+
2363
+ test('v0.18 生命周期:状态点在标题之前,行结构不变', async () => {
2364
+ const { nodes } = await mountUsage(lifecyclePayload())
2365
+
2366
+ const rows = byExactClass(nodes, 'knit-row1')
2367
+ assert.equal(rows.length, 5, '五行文档各一条 row1')
2368
+ for (const row of rows) {
2369
+ assert.equal(kidsOf(row, 'knit-title').length, 1, '一行只有一个标题')
2370
+ assert.equal(kidsOf(row, 'knit-time').length, 1, '一行只有一个时间')
2371
+ assert.equal(kidsOf(row, 'knit-life').length, 1, '一行只有一个状态文字')
2372
+ assert.equal(kidsOf(row, 'knit-glyph').length, 1, '一行只有一个状态点')
2373
+ const order = row.children.map((n) => String(n.props.className || ''))
2374
+ assert.ok(
2375
+ order.indexOf('knit-glyph') < order.indexOf('knit-title')
2376
+ && order.indexOf('knit-title') < order.indexOf('knit-life')
2377
+ && order.indexOf('knit-life') < order.indexOf('knit-time'),
2378
+ `状态点 / 标题 / 状态 / 时间的顺序不能乱:${order.join(' / ')}`,
2379
+ )
2380
+ }
2381
+ // 每行的前两个直接子节点仍然是「号 / 占位符 + 正文」(v0.15 起就钉住的形状)
2382
+ for (const doc of byClass(nodes, 'knit-doc')) {
2383
+ const classes = doc.children.map((n) => String(n.props.className || ''))
2384
+ assert.ok(
2385
+ classes[0] === 'knit-num' || classes[0] === 'knit-gapmark',
2386
+ `行首必须是号或占位符:${classes.join(' / ')}`,
2387
+ )
2388
+ assert.equal(classes[1], 'knit-body', '第二个直接子节点必须是正文')
2389
+ }
2390
+ })
2391
+
2392
+ test('v0.18 最近读取:一行可点的事实(谁 · 多久前 ›),不说「正在阅读」', async () => {
2393
+ const { nodes, render, calls } = await mountUsage(lifecyclePayload())
2394
+
2395
+ const rows = byExactClass(nodes, 'knit-read-row')
2396
+ assert.equal(rows.length, 1, '最近读取是**可点的一行**')
2397
+ const text = textOf(rows[0])
2398
+ assert.match(text, /docs\/eval\.md/, '最近一次**成功** read 的文件要如实说出来')
2399
+ assert.match(text, /12分钟前/, '多久前也要如实说')
2400
+ assert.equal(rows[0].props.type, 'button', '整行可点 → 真 button')
2401
+ assert.ok(!/正在阅读|当前正在|正在读/.test(text), 'Knit 证明不了「此刻正在读」')
2402
+ // 与摘要行并存,没有多出统计指标
2403
+ const allText = textOf(byExactClass(nodes, 'knit-usage')[0])
2404
+ assert.match(allText, /Epoch 4/)
2405
+ assert.match(allText, /7 次读取/)
2406
+ // 点它 = 直接打开那一篇:**点的那一下不敲宿主**(走已有的 requestPreview,
2407
+ // 而不是「先拉一次列表再打开」)。之后出现的请求是渲染 effect 自己的事。
2408
+ const before = calls.length
2409
+ rows[0].props.onClick()
2410
+ assert.equal(calls.length, before, '点它不直接请求列表')
2411
+ await harness.flush()
2412
+ const opened = render()
2413
+ assert.equal(openNameOf(opened), 'eval.md', '点最近读取就打开那一篇')
2414
+ })
2415
+
2416
+ test('v0.18 上下文外读取:默认折叠,展开才逐篇列出(按读得最多的排)', async () => {
2417
+ const { nodes, render } = await mountUsage(lifecyclePayload())
2418
+
2419
+ const buttons = byExactClass(nodes, 'knit-more-btn')
2420
+ const gapBtn = buttons.find((node) => textOf(node).includes('上下文外读取'))
2421
+ assert.ok(gapBtn, '包外读取要有一行可展开的统计')
2422
+ // v0.18 UI 迭代(md §三十四):菜单行是「label ── 数量 ›」三段,
2423
+ // 数量单独成一个 `.knit-more-meta`(右对齐),不再挤在标题字符串里。
2424
+ assert.equal(textOf(kidsOf(gapBtn, 'knit-more-label')[0]), '上下文外读取')
2425
+ assert.equal(textOf(kidsOf(gapBtn, 'knit-more-meta')[0]), '2', '数量是事实,单独一列')
2426
+ assert.equal(gapBtn.props['aria-expanded'], 'false', '默认折叠')
2427
+ assert.equal(byExactClass(nodes, 'knit-gap-list').length, 0, '折叠时不渲染明细节点')
2428
+ assert.equal(byExactClass(nodes, 'knit-out-row').length, 0, '折叠时一行明细都不许有')
2429
+
2430
+ gapBtn.props.onClick()
2431
+ const open = render()
2432
+ const list = byExactClass(open, 'knit-gap-list')
2433
+ assert.equal(list.length, 1, '展开后出现明细区')
2434
+ const rows = byExactClass(open, 'knit-out-row')
2435
+ assert.equal(rows.length, 2, '两篇包外文档各一行')
2436
+ assert.deepEqual(rows.map((row) => textOf(kidsOf(row, 'knit-out-rel')[0])),
2437
+ ['docs/old-plan.md', 'docs/test-case.md'], '读得多的(×3)排前面')
2438
+ assert.deepEqual(rows.map((row) => textOf(kidsOf(row, 'knit-out-count')[0])), ['×3', '×1'])
2439
+ // v0.18 UI 迭代(md §三十六):行首补两位序号(位置,不是评分)。
2440
+ assert.deepEqual(rows.map((row) => textOf(kidsOf(row, 'knit-out-num')[0])), ['01', '02'],
2441
+ '行首序号从左到右两位补齐')
2442
+ // 每一行都带生命周期,而且复用**同一份** v0.17 数据(不是第二套)。
2443
+ // ⚠️ 状态用**词**(已读),不用短次数 —— 左边 `×N` 已经说了一遍,再来一遍就渲染成
2444
+ // `docs/old-plan.md ×3 ×3`(2026-10-05 用真实会话载荷渲染时抓到)。
2445
+ assert.deepEqual(rows.map((row) => textOf(kidsOf(row, 'knit-life')[0])), ['已读', '已读'])
2446
+ for (const row of rows) {
2447
+ const shown = textOf(row).match(/×\d+/g) || []
2448
+ assert.equal(new Set(shown).size, shown.length, `次数在同一行里不许说两遍:${textOf(row)}`)
2449
+ }
2450
+ for (const row of rows) assert.equal(row.props.type, 'button', '每一行都是可点对象 → 真 button')
2451
+ // 只陈述事实:不评价 Knit 推荐得对不对
2452
+ const openText = textOf(rows[0]) + textOf(byExactClass(open, 'knit-usage')[0])
2453
+ assert.ok(!/漏掉|推荐错|绕过|不认可|低质量|命中率/.test(openText), '包外读取不是「Knit 漏了」')
2454
+ })
2455
+
2456
+ test('v0.18 上下文外读取:排序在客户端(count DESC),不是宿主给的阅读顺序', async () => {
2457
+ // 宿主 `outsideDocsOf` 回的是**首次读**的顺序(seq);面板要回答「哪几篇被反复读」
2458
+ const payload = lifecyclePayload({
2459
+ outsideDocs: [
2460
+ { rel: 'docs/test-case.md', count: 1, lastReadAt: 2, seq: 20 },
2461
+ { rel: 'docs/old-plan.md', count: 3, lastReadAt: 1, seq: 10 },
2462
+ ],
2463
+ })
2464
+ const { nodes, render } = await mountUsage(payload)
2465
+ byExactClass(nodes, 'knit-more-btn')
2466
+ .find((node) => textOf(node).includes('上下文外读取')).props.onClick()
2467
+ const open = render()
2468
+ assert.deepEqual(
2469
+ byExactClass(open, 'knit-out-row').map((row) => textOf(kidsOf(row, 'knit-out-rel')[0])),
2470
+ ['docs/old-plan.md', 'docs/test-case.md'],
2471
+ '读得多的排前面 —— 即使宿主把它放在后面',
2472
+ )
2473
+ })
2474
+
2475
+ test('v0.18 Context Delta:只展示最近一次,符号只有 + / - / ↔', async () => {
2476
+ const { nodes, render } = await mountUsage(lifecyclePayload())
2477
+
2478
+ const deltaBtn = byExactClass(nodes, 'knit-more-btn')
2479
+ .find((node) => textOf(node).includes('上下文变化'))
2480
+ assert.ok(deltaBtn, '有变化就要有一行摘要')
2481
+ // v0.18 UI 迭代(md §三十八):菜单行固定写「上下文变化 最近一次 ›」——
2482
+ // **按钮上不再写条数**(条数由展开后的行数与「还有 N 条」承担,见下面那条账目守卫)。
2483
+ assert.equal(textOf(kidsOf(deltaBtn, 'knit-more-label')[0]), '上下文变化')
2484
+ assert.equal(textOf(kidsOf(deltaBtn, 'knit-more-meta')[0]), '最近一次')
2485
+ assert.equal(deltaBtn.props['aria-expanded'], 'false', '默认折叠')
2486
+ const digest = byExactClass(nodes, 'knit-delta-row')
2487
+ assert.deepEqual(digest.map(textOf), [
2488
+ '+ docs/algo.md',
2489
+ '- README.md',
2490
+ '↔ docs/eval.md · 辅助 → 相关',
2491
+ ])
2492
+ // 进出换层共用一种行样式:不用颜色区分「好 / 坏」
2493
+ assert.equal(new Set(digest.map((row) => row.props.className)).size, 1)
2494
+ assert.equal(byExactClass(nodes, 'knit-delta-head').length, 0, '折叠时没有分组标题')
2495
+
2496
+ deltaBtn.props.onClick()
2497
+ const open = render()
2498
+ assert.deepEqual(byExactClass(open, 'knit-delta-head').map(textOf), ['进入', '离开', '换层'])
2499
+ // 展开后折叠摘要必须**让位**给分组:三行摘要 + 「还有 N 条」再叠上明细 = 同一件事讲两遍
2500
+ // (2026-10-05 用真实会话载荷渲染时抓到的重复)。
2501
+ const openRows = byExactClass(open, 'knit-delta-row').map(textOf)
2502
+ assert.deepEqual(openRows, ['+ docs/algo.md', '- README.md', '↔ docs/eval.md · 辅助 → 相关'])
2503
+ assert.equal(new Set(openRows).size, openRows.length, '展开后同一行不许出现两次')
2504
+ assert.ok(!openRows.some((row) => /还有/.test(row)), '展开后不再有折叠尾巴')
2505
+ const openText = textOf(byExactClass(open, 'knit-usage')[0])
2506
+ assert.ok(!/\d{2}:\d{2}/.test(openText), '不许出现时间线')
2507
+ })
2508
+
2509
+ test('v0.17 Context Delta:超过三条折叠成「还有 N 条」,任务变化只说一句', async () => {
2510
+ const many = {
2511
+ appeared: [
2512
+ { rel: 'a.md', tier: 'primary', rank: 1 },
2513
+ { rel: 'b.md', tier: 'related', rank: 2 },
2514
+ { rel: 'c.md', tier: 'related', rank: 3 },
2515
+ { rel: 'd.md', tier: 'related', rank: 4 },
2516
+ ],
2517
+ disappeared: [],
2518
+ moved: [],
2519
+ taskChanged: false,
2520
+ }
2521
+ const folded = await mountUsage(lifecyclePayload({ delta: many }))
2522
+ assert.deepEqual(byExactClass(folded.nodes, 'knit-delta-row').map(textOf), [
2523
+ '+ a.md', '+ b.md', '+ c.md', '还有 1 条',
2524
+ ])
2525
+ // 展开 = 折叠摘要让位给分组明细(否则第 4 条既在「还有 1 条」里、又单独列一遍)
2526
+ byExactClass(folded.nodes, 'knit-more-btn')
2527
+ .find((node) => textOf(node).includes('上下文变化')).props.onClick()
2528
+ const opened = folded.render()
2529
+ assert.deepEqual(byExactClass(opened, 'knit-delta-row').map(textOf),
2530
+ ['+ a.md', '+ b.md', '+ c.md', '+ d.md'], '展开后四条各出现一次,没有折叠尾巴')
2531
+
2532
+ const task = await mountUsage(lifecyclePayload({
2533
+ delta: { appeared: [{ rel: 'docs/algo.md', tier: 'primary', rank: 1 }], disappeared: [], moved: [], taskChanged: true },
2534
+ }))
2535
+ const text = byExactClass(task.nodes, 'knit-delta-row').map(textOf)
2536
+ assert.deepEqual(text, ['+ docs/algo.md', '任务上下文已更新'], '任务变化也是一句事实,不是时间线')
2537
+ // ⚠️ 展开后这一句**不许消失**:折叠摘要算上了它,只列 1 行就成了「说 2 条、列 1 行」
2538
+ // 的自相矛盾(2026-10-05 用真实载荷渲染时抓到)。
2539
+ const taskBtn = byExactClass(task.nodes, 'knit-more-btn')
2540
+ .find((node) => textOf(node).includes('上下文变化'))
2541
+ assert.equal(taskBtn.props['aria-expanded'], 'false', '默认折叠')
2542
+ taskBtn.props.onClick()
2543
+ assert.deepEqual(byExactClass(task.render(), 'knit-delta-row').map(textOf),
2544
+ ['+ docs/algo.md', '任务上下文已更新'], '展开后任务变化仍在,还是只出现一次')
2545
+ })
2546
+
2547
+ test('v0.18 Context Delta:展开后的行 + 组内尾巴必须说清**全部**变化', async () => {
2548
+ // 通用账目关系(不是针对某个夹具的定点断言):展开后的明细必须把这次变化的**全部**条目
2549
+ // 说清楚 —— 列出的行(不含尾巴)+ 每条尾巴里的数字 = 变化总数。
2550
+ // ⚠️ 这正是一次真实载荷渲染抓到的 bug 的通用式:按钮说 N 条、展开后却少列一行
2551
+ // (`taskChanged` 那一句只出现在折叠摘要里,展开就没了)。
2552
+ // ⚠️ v0.18 UI 迭代后按钮上**不再写条数**(菜单行固定是「上下文变化 最近一次」),
2553
+ // 所以基准从**载荷自己**算出来,不再读按钮文字。
2554
+ // 组内上限 `MAX_DELTA_GROUP = 5` 让这条账目多了一个分支,所以这里刻意给 8 条换层。
2555
+ const moved = Array.from({ length: 8 }, (_, i) => ({
2556
+ rel: `docs/m${i + 1}.md`,
2557
+ from: { tier: 'related', rank: i + 2 },
2558
+ to: { tier: 'supporting', rank: i + 1 },
2559
+ }))
2560
+ const { nodes, render } = await mountUsage(lifecyclePayload({
2561
+ delta: {
2562
+ appeared: [
2563
+ { rel: 'docs/algo.md', tier: 'primary', rank: 1 },
2564
+ { rel: 'docs/new.md', tier: 'related', rank: 9 },
2565
+ ],
2566
+ disappeared: [],
2567
+ moved,
2568
+ taskChanged: true,
2569
+ },
2570
+ }))
2571
+ const deltaBtn = byExactClass(nodes, 'knit-more-btn')
2572
+ .find((node) => textOf(node).includes('上下文变化'))
2573
+ assert.ok(!/\d/.test(textOf(deltaBtn)), '菜单行上不许再出现条数(数字)')
2574
+ // 2 篇进入 + 8 条换层 + 1 句任务变化 = 11
2575
+ const total = 2 + moved.length + 1
2576
+
2577
+ deltaBtn.props.onClick()
2578
+ const opened = render()
2579
+ const rows = byExactClass(opened, 'knit-delta-row').map(textOf)
2580
+ const tailOf = (row) => (row.match(/^还有 (\d+) 条$/) || [])[1]
2581
+ const tails = rows.map(tailOf).filter(Boolean).map(Number)
2582
+ const listed = rows.filter((row) => !tailOf(row))
2583
+ assert.deepEqual(byExactClass(opened, 'knit-delta-head').map(textOf), ['进入', '换层'],
2584
+ '这份夹具没有「离开」,所以不画空的「离开」标题')
2585
+ assert.deepEqual(tails, [3], '换层 8 条、组内只列 5 条 ⇒ 尾巴写「还有 3 条」')
2586
+ assert.ok(listed.some((row) => /任务上下文已更新/.test(row)),
2587
+ '任务变化没有分组标题可挂,但必须真的列出来')
2588
+ assert.equal(
2589
+ listed.length + tails.reduce((sum, n) => sum + n, 0),
2590
+ total,
2591
+ `列出的行 + 尾巴里的数字必须等于变化总数(实际列出 ${JSON.stringify(listed)})`,
2592
+ )
2593
+ })
2594
+
2595
+ test('v0.17 样式:状态与折叠区只用语义 token —— 没有卡片 / 固定色 / 边框', async () => {
2596
+ const { readFileSync } = await import('node:fs')
2597
+ const { fileURLToPath } = await import('node:url')
2598
+ const source = readFileSync(
2599
+ fileURLToPath(new URL('../src/client/client.js', import.meta.url)),
2600
+ 'utf8',
2601
+ )
2602
+ // 状态是弱化说明文字,颜色必须走 caption token(十六进制只能出现在 var() 兜底里)
2603
+ assert.match(source, /\.knit-life\{[^}]*color:var\(--dsw-alias-label-caption/)
2604
+ assert.ok(!/\.knit-life\{[^}]*color:\s*#[0-9a-fA-F]{3,6}/.test(source), '不许写死颜色')
2605
+ assert.ok(!/\.knit-life\{[^}]*background/.test(source), '状态不画底色')
2606
+ // 折叠按钮是纯文字按钮:无边框、无底色
2607
+ assert.match(source, /\.knit-more-btn\{[^}]*border:0/)
2608
+ assert.match(source, /\.knit-more-btn\{[^}]*background:none/)
2609
+ // 明细行共用一套中性样式,不用颜色区分「进 / 出」
2610
+ assert.match(source, /\.knit-gap-row,\.knit-delta-row\{[^}]*color:var\(--dsw-alias-label-caption/)
2611
+ assert.ok(!/\.knit-gap-row,\.knit-delta-row\{[^}]*border/.test(source), '不要全宽分割线')
2612
+ })
2613
+
2614
+ test('v0.17 生命周期:英文环境下状态与折叠文案都是英文', async () => {
2615
+ installFetch(() => lifecyclePayload())
2616
+ const { exports } = loadClientModule()
2617
+ // 词典是模块级状态:apply 到 en 之后整块面板都说英文(与真机一致)
2618
+ exports.apply(fakeCtx({ sidebarRightTabs: true, locale: 'en' }).ctx)
2619
+ const { KnitBody } = exports.__test
2620
+ harness.reset()
2621
+ harness.seed(['', 'relevance'])
2622
+ const render = () => harness.render(h(KnitBody, { sessionId: 's1' }))
2623
+ let nodes = render()
2624
+ await harness.flush()
2625
+ nodes = render()
2626
+ await harness.flush()
2627
+ nodes = render()
2628
+ const toggle = byExactClass(nodes, 'knit-btn').find((node) => textOf(node) === 'Usage')
2629
+ assert.ok(toggle, '英文环境下开关文案是 Usage')
2630
+ toggle.props.onClick()
2631
+ await harness.flush()
2632
+ nodes = render()
2633
+ await harness.flush()
2634
+ nodes = render()
2635
+
2636
+ assert.deepEqual(
2637
+ byExactClass(nodes, 'knit-life').map(textOf),
2638
+ ['×3', 'Re-read after update', 'Updated after read', 'Unread', 'Unread'],
2639
+ '四档状态文字在英文下也是英文',
2640
+ )
2641
+ assert.deepEqual(
2642
+ byExactClass(nodes, 'knit-glyph').map((node) => node.props['aria-label']),
2643
+ ['Read ×3', 'Re-read after update', 'Updated after read', 'Unread', 'Unread'],
2644
+ '状态点的 tooltip 也要翻译',
2645
+ )
2646
+ // v0.18 UI 迭代:菜单行是「label ── 数量 ›」三段,英文下 label 也必须是英文。
2647
+ const gapBtn = byExactClass(nodes, 'knit-more-btn')
2648
+ .find((node) => textOf(kidsOf(node, 'knit-more-label')[0]).includes('Reads outside context'))
2649
+ assert.ok(gapBtn, '包外明细的按钮文案也要翻译')
2650
+ assert.equal(textOf(kidsOf(gapBtn, 'knit-more-meta')[0]), '2', '数量与文案分开两段')
2651
+ const deltaBtn = byExactClass(nodes, 'knit-more-btn').find((node) => textOf(node).includes('Context changes'))
2652
+ assert.ok(deltaBtn, '变化摘要的按钮文案也要翻译')
2653
+ deltaBtn.props.onClick()
2654
+ const open = render()
2655
+ assert.deepEqual(byExactClass(open, 'knit-delta-head').map(textOf), ['Entered', 'Left', 'Moved tier'])
2656
+
2657
+ const allText = byExactClass(open, 'knit-usage').map(textOf).join(' ')
2658
+ assert.match(allText, /docs\/eval\.md/)
2659
+ assert.match(allText, /12 min ago/)
2660
+ assert.ok(!/[\u4e00-\u9fff]/.test(allText), '英文环境里一个汉字都不许有')
2661
+ })
2662
+
2663
+ /* ── v0.18:Context Usage Lens(2026-10-05 规格 §46–§49 的守卫)─────────
2664
+ 这一节的判据来自规格本身:信息架构(§47)、动画(§48)、回归保护(§49)。
2665
+ ⚠️ 全部只读现有事实:不新增采集、不新增持久化、不新增第二个滚动容器。 */
2666
+
2667
+ test('v0.18 纯函数:Coverage 派生、包外排序、Delta 分组', () => {
2668
+ const { coverageOf, groupOutsideDocs, groupDelta, lifeStatusOf, LIFE_GLYPH } =
2669
+ loadClientModule().exports.__test
2670
+
2671
+ // Coverage 的分母是**这一层真实有几篇**,不是 Context Pack 的 matched/total
2672
+ const cov = coverageOf(
2673
+ { primary: [{ rel: 'a.md' }], supporting: ['b.md', 'c.md'], related: [] },
2674
+ { 'a.md': { status: 'read', count: 3 } },
2675
+ )
2676
+ assert.deepEqual(cov.primary, { total: 1, read: 1, rels: [{ rel: 'a.md', read: true }] })
2677
+ assert.deepEqual(cov.supporting, {
2678
+ total: 2,
2679
+ read: 0,
2680
+ rels: [{ rel: 'b.md', read: false }, { rel: 'c.md', read: false }],
2681
+ })
2682
+ assert.deepEqual(cov.related, { total: 0, read: 0, rels: [] }, '没有那一层就是 0 / 0,不编')
2683
+ assert.equal(lifeStatusOf(null, 'a.md'), 'unread', '没有记录就是未读')
2684
+ assert.equal(lifeStatusOf({ 'a.md': { status: '天外飞仙' } }, 'a.md'), 'unread', '认不出的状态退回未读')
2685
+ assert.deepEqual(Object.keys(LIFE_GLYPH).sort(),
2686
+ ['read', 'reread_after_update', 'unread', 'updated_after_read'])
2687
+
2688
+ // 包外:读得最多的在前;同计数按最后读的时间(载荷里没有 lastRead.seq)
2689
+ assert.deepEqual(groupOutsideDocs([
2690
+ { rel: 'x.md', count: 1, lastReadAt: 100, seq: 1 },
2691
+ { rel: 'y.md', count: 3, lastReadAt: 50, seq: 2 },
2692
+ { rel: 'z.md', count: 1, lastReadAt: 200, seq: 3 },
2693
+ ]).map((row) => row.rel), ['y.md', 'z.md', 'x.md'])
2694
+ assert.deepEqual(groupOutsideDocs(null), [], '没有数据就是空列表')
2695
+
2696
+ // Delta:只拆「进 / 出 / 换层」,两种载荷(字符串 / 对象)都认
2697
+ const grouped = groupDelta({ appeared: ['a.md'], disappeared: [{ rel: 'b.md' }], moved: [] })
2698
+ assert.deepEqual(grouped.enter, [{ rel: 'a.md' }])
2699
+ assert.deepEqual(grouped.leave, [{ rel: 'b.md' }])
2700
+ assert.deepEqual(grouped.move, [])
2701
+ assert.deepEqual(groupDelta(null), { enter: [], leave: [], move: [] })
2702
+ })
2703
+
2704
+ test('v0.18 Coverage:三层各自的「已读 ÷ 本层总数」,点它定位到那一层', async () => {
2705
+ const { nodes, render } = await mountUsage(lifecyclePayload())
2706
+
2707
+ const cols = byExactClass(nodes, 'knit-cov-col')
2708
+ assert.deepEqual(cols.map((node) => textOf(kidsOf(node, 'knit-cov-name')[0])), ['主要', '辅助', '相关'])
2709
+ // 文本与视觉**同时**存在:只给点读不出「读了几篇」;没有百分比、没有进度条
2710
+ assert.deepEqual(cols.map((node) => textOf(kidsOf(node, 'knit-cov-num')[0])), ['1 / 1', '2 / 2', '0 / 1'])
2711
+ // v0.18 UI 迭代(md §十五 / §十六):状态点改成**真 CSS 圆**(6px,与文档行同一套语言),
2712
+ // 于是断言从「`○ ●` 字符」改成「有几个点是 on(=这一层读过)」。字符版已不存在。
2713
+ const dotStates = cols.map((node) => kidsOf(node, 'knit-cov-dots')[0].children
2714
+ .filter((dot) => dot && dot.props)
2715
+ .map((dot) => String(dot.props.className).includes(' on')))
2716
+ assert.deepEqual(dotStates, [[true], [true, true], [false]],
2717
+ '实心 = 这一篇读过、空心 = 没读过')
2718
+ assert.deepEqual(dotStates.map((flags) => flags.length), [1, 2, 1], '每层圆点数 = 本层篇数')
2719
+ assert.deepEqual(dotStates.map((flags) => flags.filter(Boolean).length), [1, 2, 0], '……其中实心几个')
2720
+ assert.deepEqual(cols.map((node) => node.props['aria-label']),
2721
+ ['主要上下文:1 / 1 篇已读', '辅助上下文:2 / 2 篇已读', '相关上下文:0 / 1 篇已读'],
2722
+ '读屏听到完整一句(md §六十三),但屏幕上不显示这句话')
2723
+ assert.ok(!textOf(byExactClass(nodes, 'knit-usage')[0]).includes('篇已读'),
2724
+ '无障碍文案不许出现在视觉里')
2725
+ for (const node of cols) assert.equal(node.props.type, 'button', '可点就必须是真 button')
2726
+
2727
+ // 点「辅助」→ 只点亮「辅助」那一层(替身里没有 DOM,定位落在 data-knit-tier 上)
2728
+ cols[1].props.onClick()
2729
+ const flashed = byClass(render(), 'knit-tier')
2730
+ .filter((node) => String(node.props.className).includes('flash'))
2731
+ assert.equal(flashed.length, 1, '点一层只点亮那一层')
2732
+ assert.equal(flashed[0].props['data-knit-tier'], 'supporting', '点的哪一层就亮哪一层')
2733
+
2734
+ // 高亮只是一下提示,自己会收掉(不靠 hover、不靠点别处)
2735
+ harness.tick()
2736
+ assert.equal(
2737
+ byClass(render(), 'knit-tier').filter((n) => String(n.props.className).includes('flash')).length,
2738
+ 0,
2739
+ )
2740
+ })
2741
+
2742
+ test('v0.18 Coverage:一份包可以没有 Primary —— 不画「0 / 0」的假层', async () => {
2743
+ const base = lifecyclePayload()
2744
+ const { nodes } = await mountUsage({ ...base, context: { ...base.context, primary: [] } })
2745
+ assert.deepEqual(
2746
+ byExactClass(nodes, 'knit-cov-col').map((node) => textOf(kidsOf(node, 'knit-cov-name')[0])),
2747
+ ['辅助', '相关'],
2748
+ 'Primary 缺席就整列不显示,而不是画一个 0 / 0 的假层',
2749
+ )
2750
+ })
2751
+
2752
+ test('v0.18 Lens 展开 / 收起:收起只收起细节,统计照样开着', async () => {
2753
+ const { nodes, render } = await mountUsage(lifecyclePayload())
2754
+
2755
+ const head = byExactClass(nodes, 'knit-lens-head')
2756
+ assert.equal(head.length, 1, 'Lens 有一行可点的标题')
2757
+ assert.equal(head[0].props.type, 'button', '标题行是真 button')
2758
+ assert.equal(head[0].props['aria-expanded'], 'true', '默认展开')
2759
+ assert.equal(byExactClass(nodes, 'knit-lens-body').length, 1)
2760
+
2761
+ head[0].props.onClick()
2762
+ const closed = render()
2763
+ assert.equal(byExactClass(closed, 'knit-lens-head')[0].props['aria-expanded'], 'false')
2764
+ assert.equal(byExactClass(closed, 'knit-lens-body').length, 0, '收起后不渲染细节')
2765
+ const text = textOf(byExactClass(closed, 'knit-usage')[0])
2766
+ assert.match(text, /使用情况/, '标题还在')
2767
+ assert.match(text, /Epoch 4/, 'Epoch 还在')
2768
+ assert.match(text, /7 次读取/, '摘要行还在 —— 收起的是细节,不是统计')
2769
+ assert.equal(byExactClass(closed, 'knit-cov-col').length, 0, '细节收起来了')
2770
+ })
2771
+
2772
+ test('v0.18 空使用情况:不画「0%」大卡,只报事实', async () => {
2773
+ const payload = lifecyclePayload()
2774
+ const empty = {
2775
+ ...payload,
2776
+ usage: {
2777
+ at: 1,
2778
+ epochId: 1,
2779
+ stats: {
2780
+ reads: 0,
2781
+ distinct: 0,
2782
+ outside: 0,
2783
+ outsideReads: [],
2784
+ firstReadTier: 'outside',
2785
+ firstReadRel: null,
2786
+ firstReadAt: null,
2787
+ primaryRel: null,
2788
+ primaryFollowThrough: false,
2789
+ byTier: { primary: { total: 1, read: 0 }, supporting: { total: 2, read: 0 }, related: { total: 1, read: 0 } },
2790
+ supportingCoverage: 0,
2791
+ churn: { snapshots: 0, deltas: 0, retained: 0, appeared: 0, disappeared: 0, moved: 0, taskChanged: 0 },
2792
+ },
2793
+ delta: null,
2794
+ latestDelta: null,
2795
+ recentRead: null,
2796
+ outsideDocs: [],
2797
+ lifecycle: {},
2798
+ },
2799
+ }
2800
+ const { nodes } = await mountUsage(empty)
2801
+ const text = textOf(byExactClass(nodes, 'knit-usage')[0])
2802
+ assert.match(text, /0 次读取/, '零就写零')
2803
+ assert.ok(!text.includes('%'), '不许有百分比')
2804
+ assert.match(text, /暂无记录/, '没有读取记录 = 一句「暂无记录」,不是一块空状态卡')
2805
+ assert.deepEqual(byExactClass(nodes, 'knit-cov-num').map(textOf), ['0 / 1', '0 / 2', '0 / 1'])
2806
+ assert.equal(byExactClass(nodes, 'knit-more-btn').length, 0, '没有包外、没有变化:一个折叠区都不出现')
2807
+ })
2808
+
2809
+ test('v0.18 小高度面板:矮下来不铺细节,滚动仍然只交给列表', async () => {
2810
+ const { readFileSync } = await import('node:fs')
2811
+ const { fileURLToPath } = await import('node:url')
2812
+ const source = readFileSync(
2813
+ fileURLToPath(new URL('../src/client/client.js', import.meta.url)),
2814
+ 'utf8',
2815
+ )
2816
+ // 规格 §31 / §46-E:面板矮时降级成 Summary + Coverage + 最近读取,变化摘要不铺开,
2817
+ // Outside / Delta 收成标题(点得开)。
2818
+ // ⚠️ 测试替身里拿不到 DOM ref,量不到高度 —— 这一条只能守**代码形状**,
2819
+ // 真机手感由 §46-E(面板拉到很矮)人眼确认。
2820
+ const { COMPACT_PANEL_PX } = loadClientModule().exports.__test
2821
+ assert.equal(COMPACT_PANEL_PX, 420, '降级阈值是 420px')
2822
+ const compactAt = source.indexOf('const compact = panelH > 0 && panelH < COMPACT_PANEL_PX')
2823
+ const linesAt = source.indexOf('const previewLines = compact ? [] :')
2824
+ assert.ok(compactAt > 0, '矮面板必须有明确的降级判据')
2825
+ assert.ok(linesAt > compactAt, 'compact 必须先算出来再用(TDZ + 先判后用)')
2826
+ // 量不到高度(0)时按「不矮」处理:首帧与替身里都照常展开,不是默认收起
2827
+ assert.match(source, /const COMPACT_PANEL_PX = 420/)
2828
+ })
2829
+
2830
+ test('v0.18 点状态点 / 包外行:打开那一篇,不重新请求列表', async () => {
2831
+ const { nodes, render, calls } = await mountUsage(lifecyclePayload())
2832
+
2833
+ // 状态点:点它 = 打开 / 选中这一篇(点的那一下不敲宿主)
2834
+ const before = calls.length
2835
+ byExactClass(nodes, 'knit-glyph')[0].props.onClick()
2836
+ assert.equal(calls.length, before, '点状态点不直接请求列表')
2837
+ await harness.flush()
2838
+ const opened = render()
2839
+ assert.equal(openNameOf(opened), 'algo.md', '点哪一篇的状态点就打开哪一篇')
2840
+ // **已经打开则保持原预览**:不重开、不重拉
2841
+ byExactClass(opened, 'knit-glyph')[0].props.onClick()
2842
+ await harness.flush()
2843
+ const again = render()
2844
+ assert.equal(openNameOf(again), 'algo.md')
2845
+ assert.equal(byExactClass(again, 'knit-preview').length, 1, '预览没有被关掉也没有重开')
2846
+
2847
+ // 包外行:展开只是显示(不敲宿主),点那一行同样只是换预览
2848
+ byExactClass(again, 'knit-more-btn')
2849
+ .find((node) => textOf(node).includes('上下文外读取')).props.onClick()
2850
+ const expanded = render()
2851
+ const beforeRow = calls.length
2852
+ byExactClass(expanded, 'knit-out-row')[0].props.onClick()
2853
+ assert.equal(calls.length, beforeRow, '点包外行不直接请求列表')
2854
+ await harness.flush()
2855
+ const outside = render()
2856
+ assert.equal(openNameOf(outside), 'old-plan.md', '点包外行就打开那一篇')
2857
+ })
2858
+
2859
+ test('v0.18 动效:数据没变,轮询不许让 Lens 重播任何动画', async () => {
2860
+ const { nodes, render } = await mountUsage(lifecyclePayload())
2861
+ const dots = (list) => dotsOf(list).map((node) => String(node.props.className))
2862
+ const before = dots(nodes)
2863
+ // 只是轮询 / 计时器走了一轮,数据一个字没变
2864
+ harness.tick()
2865
+ await harness.flush()
2866
+ harness.tick()
2867
+ await harness.flush()
2868
+ assert.deepEqual(dots(render()), before, '同样的数据 → 同样的 class → 补间不会被重播')
2869
+ })
2870
+
2871
+ test('v0.18 样式:Lens 只用语义 token、自己不滚动、减弱动效时不动', async () => {
2872
+ const { readFileSync } = await import('node:fs')
2873
+ const { fileURLToPath } = await import('node:url')
2874
+ const source = readFileSync(
2875
+ fileURLToPath(new URL('../src/client/client.js', import.meta.url)),
2876
+ 'utf8',
2877
+ )
2878
+ // v0.18 UI 迭代(md §十五 / §二十九):状态点**只是一枚中性圆点** ——
2879
+ // 真圆、空心(未读 border,已读 background)、只有中性 token。
2880
+ // ⚠️ Coverage 的圆点与文档行的 glyph 圆点必须是**同一套状态语言**:同一个直径、
2881
+ // 同一对 token。下面这条守卫就是防两处各画各的(人眼很难发现 1px 的差异)。
2882
+ // 直径不写死在守卫里,而是**比对两处**,再钉住当前定的那个值。
2883
+ const covDotSize = source.match(/\.knit-cov-dot\{[^}]*width:(\d+)px;height:(\d+)px;border-radius:50%/)
2884
+ const glyphMarkSize = source.match(/\.knit-glyph-mark\{[^}]*width:(\d+)px;height:(\d+)px;border-radius:50%/)
2885
+ assert.ok(covDotSize, 'Coverage 的状态点必须是真圆(有宽高 + 50% 圆角)')
2886
+ assert.ok(glyphMarkSize, '文档行的状态点必须是真圆(有宽高 + 50% 圆角)')
2887
+ assert.deepEqual([glyphMarkSize[1], glyphMarkSize[2]], [covDotSize[1], covDotSize[2]],
2888
+ '两处状态点必须是同一个直径(两处各画各的时候,1px 的差异人眼很难发现)')
2889
+ assert.equal(covDotSize[1], '6', '圆点直径是 6px(2026-10-06 用户定:9px 改成 6px)')
2890
+ assert.match(source, /\.knit-cov-dot\{[^}]*border:1px solid var\(--dsw-alias-label-caption/)
2891
+ assert.match(source, /\.knit-cov-dot\.on\{[^}]*background:var\(--dsw-alias-label-caption/)
2892
+ assert.match(source, /\.knit-glyph-mark\{[^}]*border:1px solid var\(--dsw-alias-label-caption/)
2893
+ assert.match(source, /\[data-mark="read"\]\{[^}]*background:var\(--dsw-alias-label-caption/,
2894
+ '「已读」在文档行里也是实心')
2895
+ assert.ok(!/\.knit-cov-dot\{[^}]*opacity/.test(source), '不再靠透明度表达状态')
2896
+ assert.ok(!/\.knit-cov-dot\{[^}]*transform/.test(source), '不再靠缩放表达状态')
2897
+ assert.ok(!/#(?:0f9d58|34a853|ea4335|db4437|f9ab00|fbbc04|4285f4|1a73e8)/i.test(source),
2898
+ '四态不许用绿 / 红 / 黄 / 蓝强调(读没读过不是好 / 坏)')
2899
+ assert.ok(!/\.knit-cov[^{]*\{[^}]*color:\s*#[0-9a-fA-F]{3,6}/.test(source), '不许写死颜色')
2900
+ assert.ok(!/\.knit-out-row[^{]*\{[^}]*color:\s*#[0-9a-fA-F]{3,6}/.test(source), '不许写死颜色')
2901
+ assert.match(source, /\.knit-glyph\{[^}]*color:var\(--dsw-alias-label-caption/, '状态点也是中性灰')
2902
+ assert.ok(!/\.knit-glyph\{[^}]*background:(?!none)/.test(source), '状态点不画底色 / 不加徽章')
2903
+ // **不新增第二个滚动容器**(窄侧栏里滚轮套滚轮很难用)
2904
+ assert.ok(!/\.knit-usage[^{]*\{[^}]*overflow-y:\s*(auto|scroll)/.test(source), 'Lens 自己不滚动')
2905
+ assert.ok(!/\.knit-lens[^{]*\{[^}]*overflow-y:\s*(auto|scroll)/.test(source), '细节区也不自己滚动')
2906
+ // 展开 / 收起走条件渲染,不用会自己重播的 animation
2907
+ assert.ok(!/\.knit-lens-body\{[^}]*animation/.test(source))
2908
+ // 「减弱动态效果」:状态点与高亮都不动(终态照常出现)
2909
+ assert.match(source, /prefers-reduced-motion: reduce\)\{[\s\S]*?\.knit-cov-dot\{transition:none/)
2910
+ assert.match(source, /prefers-reduced-motion: reduce\)\{[\s\S]*?\.knit-tier\.flash\{transition:none/)
2911
+ })
2912
+
2913
+ test('v0.18 定位手感:高亮时长与 CSS 同步;对比控件描边用官方分割线那一档', async () => {
2914
+ const { readFileSync } = await import('node:fs')
2915
+ const { fileURLToPath } = await import('node:url')
2916
+ const source = readFileSync(
2917
+ fileURLToPath(new URL('../src/client/client.js', import.meta.url)),
2918
+ 'utf8',
2919
+ )
2920
+ // ① 点 Coverage 层名之后的高亮:JS 常量与 CSS transition **必须是同一个数**。
2921
+ // 两者不同步时不会报任何错,只会看见「高亮已经取消、背景还在慢慢褪」的错帧。
2922
+ const flash = source.match(/const FLASH_MS = (\d+)/)
2923
+ assert.ok(flash, 'FLASH_MS 必须还在(高亮时长是它的唯一出处)')
2924
+ assert.equal(flash[1], '1200', '高亮 1200ms(2026-10-06 用户定:原 650ms 改成 1200ms)')
2925
+ const tierTransition = source.match(/\.knit-tier\{transition:background ([\d.]+)s/)
2926
+ assert.ok(tierTransition, '高亮背景必须有 transition(否则是硬闪一下)')
2927
+ assert.equal(Math.round(Number(tierTransition[1]) * 1000), Number(flash[1]),
2928
+ 'CSS transition 的秒数必须等于 FLASH_MS —— 改一个忘另一个只在真机上看得见')
2929
+ // ② 「相关 / 最新」与搜索框的描边:色用 --dsw-alias-border-l3、粗细用 0.5px,
2930
+ // 即 DSH 主区「对话」页签下面那条横线的同一档(官方 .wSkVaW_header 的
2931
+ // border-bottom: .5px solid rgba(0,0,0,.12),浅色下就是 border-l3)。
2932
+ // 退回 l4 会重一档(像两个输入框把内容框住);粗细写回 1px 则高分屏上比官方粗一倍
2933
+ // —— 色对上了粗细没对上,只看得见「比旁边那条横重」,看不出是哪里不对。
2934
+ // 两处都是 2026-10-06 用户看真机后提的。
2935
+ assert.match(source, /\.knit-seg\{[^}]*border:0\.5px solid var\(--dsw-alias-border-l3/,
2936
+ '「相关 / 最新」的外框用 border-l3、0.5px')
2937
+ assert.match(source,
2938
+ /\.knit-seg-btn \+ \.knit-seg-btn\{border-left:0\.5px solid var\(--dsw-alias-border-l3/,
2939
+ '「相关 / 最新」之间的分隔线也是同一档同粗(色或粗细差一点就会看得出来)')
2940
+ assert.match(source, /\.knit-filter\{[^}]*border:0\.5px solid var\(--dsw-alias-border-l3/,
2941
+ '搜索框描边用 border-l3、0.5px')
2942
+ assert.ok(!/\.knit-(?:seg|filter)\{[^}]*border[^;]*--dsw-alias-border-l4/.test(source),
2943
+ '这两个控件不许再退回 l4')
2944
+ assert.ok(!/\.knit-seg(-btn \+ \.knit-seg-btn)?\{[^}]*border[^;]*:1px solid var\(--dsw-alias-border-l3/
2945
+ .test(source), '这三个描边要么一起 0.5px,要么一起改 —— 不许只把其中一处写回 1px')
2946
+ })
2947
+
2948
+ test('v0.18 键盘与 aria:Lens 里每个可点元素都是真 button,且各自都有焦点环', async () => {
2949
+ // 规格 §59 第 13 步(keyboard & aria)。三件事各自会静默坏掉:
2950
+ // ① 写成 `div` + `onClick` ⇒ 键盘 Tab 到不了(鼠标能用、键盘不能用,人眼审最容易漏);
2951
+ // ② 没有 `type:'button'` ⇒ 拿到隐式 submit 语义;
2952
+ // ③ 没有 `:focus-visible` ⇒ 能 Tab 到但看不见焦点在哪(这一版新增的六处都得有)。
2953
+ const { readFileSync } = await import('node:fs')
2954
+ const { fileURLToPath } = await import('node:url')
2955
+ const source = readFileSync(
2956
+ fileURLToPath(new URL('../src/client/client.js', import.meta.url)),
2957
+ 'utf8',
2958
+ )
2959
+ const clickable = ['knit-lens-head', 'knit-cov-col', 'knit-read-row', 'knit-out-row', 'knit-more-btn', 'knit-glyph']
2960
+ for (const cls of clickable) {
2961
+ const at = source.indexOf(`className: '${cls}'`)
2962
+ assert.ok(at > 0, `${cls} 没渲染出来(改过类名?)`)
2963
+ // 紧邻它前面的那一次 h(...) 必须是 button —— 不是 div、不是 span
2964
+ const before = source.slice(Math.max(0, at - 160), at)
2965
+ const call = before.slice(before.lastIndexOf("h('"))
2966
+ assert.ok(call.startsWith("h('button'"), `${cls} 不是真 button(键盘到不了):${JSON.stringify(call.slice(0, 24))}`)
2967
+ assert.match(source.slice(at, at + 90), /type: 'button'/, `${cls} 缺少 type:'button'`)
2968
+ assert.match(
2969
+ source,
2970
+ new RegExp(`\\.${cls}:focus-visible\\{[^}]*outline:`),
2971
+ `${cls} 能 Tab 到却没有焦点环(看不见焦点在哪)`,
2972
+ )
2973
+ }
2974
+ // 三个折叠开关必须把展开态报出来(读屏靠 aria-expanded,不靠 › / ↑ 这两个字形)
2975
+ for (const flag of ['lensOpen', 'gapOpen', 'deltaOpen']) {
2976
+ assert.match(
2977
+ source,
2978
+ new RegExp(`'aria-expanded': ${flag} \\? 'true' : 'false'`),
2979
+ `${flag} 的折叠开关没有报 aria-expanded`,
2980
+ )
2981
+ }
2982
+ // 行内 glyph 有 title 就也要有 aria-label(只有 title 时读屏不一定念得出来)
2983
+ assert.match(source, /className: 'knit-glyph'[\s\S]{0,220}?'aria-label': glyph\.title/)
2984
+ })
2985
+
2986
+ /* ── v0.17:列表的进出动效(2026-10-03 用户拍板的那套手感)──────────────
2987
+ 用户原话:「新读取跟挤掉旧的未读的,这里的交互可能要优化,因为现在是一闪一闪的…
2988
+ 从当前的、如辅助上下文中新增,它应该是从低向上的…消失的时候从上到下,渐隐掉」。
2989
+ 补间在宿主浏览器里走 WAAPI(`Element.animate`),这里守的是**决定播什么**那部分:
2990
+ 差集怎么算、交错怎么排、幽灵行插哪儿。 */
2991
+
2992
+ /** 造一条「上一帧的位置」记录,形状与 `KnitBody` 里的 `motionRows` 一致。 */
2993
+ function motionRow(rel, tierKey, index, title) {
2994
+ return { rel, tierKey, index, doc: { rel, title: title || rel } }
2995
+ }
2996
+
2997
+ test('v0.17 动效:首屏与「换屏」都不播 —— 只有同一屏里多出来的行才算新来的', () => {
2998
+ const { planRowMotion } = loadClientModule().exports.__test
2999
+ const rows = [{ rel: 'a.md' }, { rel: 'b.md' }]
3000
+ // 第一次渲染没有上一帧可比:整屏一起飞进来会很吵(原型里首屏也刻意不播)
3001
+ assert.deepEqual(planRowMotion(null, 'doc|relevance|', rows), { entered: [], left: [] })
3002
+ // 换类型 / 换排序 / 搜索词变了 ⇒ 视图签名不同 ⇒ 照旧不播:那是「换屏」,不是「来了新的」
3003
+ const prev = { view: 'doc|relevance|', rows: [motionRow('a.md', 'primary', 0)] }
3004
+ assert.deepEqual(planRowMotion(prev, 'all|relevance|', rows), { entered: [], left: [] })
3005
+ })
3006
+
3007
+ test('v0.17 动效:新来的行按屏幕顺序交错飞入,交错有上限', () => {
3008
+ const T = loadClientModule().exports.__test
3009
+ const prev = { view: 'v', rows: [motionRow('a.md', 'primary', 0)] }
3010
+ assert.deepEqual(
3011
+ T.planRowMotion(prev, 'v', [{ rel: 'a.md' }, { rel: 'b.md' }, { rel: 'c.md' }, { rel: 'd.md' }]).entered,
3012
+ [
3013
+ { rel: 'b.md', delay: 0 },
3014
+ { rel: 'c.md', delay: T.MOTION_STAGGER_MS },
3015
+ { rel: 'd.md', delay: T.MOTION_STAGGER_MS * 2 },
3016
+ ],
3017
+ '交错的序号只数新来的行(第一篇的 delay 就是 0,不能当成「没排」)',
3018
+ )
3019
+ // 一次涌进来十几篇(换话题)时不排长队:越过上限的都落在同一拍上
3020
+ const many = Array.from({ length: 14 }, (_, i) => ({ rel: `m${i}.md` }))
3021
+ const delays = T.planRowMotion(prev, 'v', many).entered.map((row) => row.delay)
3022
+ assert.equal(delays.length, 14)
3023
+ assert.equal(Math.max(...delays), T.MOTION_STAGGER_MS * T.MOTION_STAGGER_MAX)
3024
+ assert.equal(
3025
+ delays.filter((d) => d === T.MOTION_STAGGER_MS * T.MOTION_STAGGER_MAX).length,
3026
+ 14 - T.MOTION_STAGGER_MAX,
3027
+ '封顶之后的都落在同一拍',
3028
+ )
3029
+ })
3030
+
3031
+ test('v0.17 动效:走了的行要带着它原来的位置与内容', () => {
3032
+ const { planRowMotion } = loadClientModule().exports.__test
3033
+ const prev = {
3034
+ view: 'v',
3035
+ rows: [motionRow('a.md', 'primary', 0, 'A'), motionRow('b.md', 'supporting', 0, 'B')],
3036
+ }
3037
+ const plan = planRowMotion(prev, 'v', [{ rel: 'a.md' }])
3038
+ assert.deepEqual(plan.entered, [])
3039
+ assert.deepEqual(plan.left.map((row) => row.rel), ['b.md'])
3040
+ assert.equal(plan.left[0].tierKey, 'supporting', '要知道它原来在哪个区')
3041
+ assert.equal(plan.left[0].index, 0, '要知道它原来在第几行')
3042
+ assert.equal(plan.left[0].doc.title, 'B', '幽灵行要用上一帧那份文档对象,不是只留个路径')
3043
+ })
3044
+
3045
+ test('v0.17 动效:同一篇只是换了层 —— 既不算飞入,也不算离开', () => {
3046
+ const { planRowMotion } = loadClientModule().exports.__test
3047
+ const prev = { view: 'v', rows: [motionRow('a.md', 'supporting', 1)] }
3048
+ assert.deepEqual(planRowMotion(prev, 'v', [motionRow('a.md', 'primary', 0)]), { entered: [], left: [] })
3049
+ })
3050
+
3051
+ test('v0.17 动效:幽灵行插回原位;还活着的不造幽灵;别的区一个都不插', () => {
3052
+ const { mergeGhostRows } = loadClientModule().exports.__test
3053
+ const docs = [{ rel: 'a.md' }, { rel: 'b.md' }]
3054
+ const ghost = (rel, index, tierKey) =>
3055
+ ({ rel, index, tierKey: tierKey || 'primary', doc: { rel, title: rel } })
3056
+
3057
+ assert.deepEqual(
3058
+ mergeGhostRows(docs, [ghost('x.md', 1)], 'primary').map((d) => d.rel),
3059
+ ['a.md', 'x.md', 'b.md'],
3060
+ '插回原来的位置 —— 否则看起来像「这篇跳到末尾才消失」',
3061
+ )
3062
+ assert.equal(mergeGhostRows(docs, [ghost('x.md', 1)], 'primary')[1].knitLeaving, true,
3063
+ '幽灵行要打上标记,DocRow 才会演离开')
3064
+ assert.deepEqual(
3065
+ mergeGhostRows([{ rel: 'a.md' }], [ghost('x.md', 0), ghost('y.md', 1)], 'primary').map((d) => d.rel),
3066
+ ['x.md', 'y.md', 'a.md'],
3067
+ '同一拍走掉两篇时各按上一帧的位置插回',
3068
+ )
3069
+ assert.deepEqual(mergeGhostRows(docs, [ghost('x.md', 9)], 'primary').map((d) => d.rel),
3070
+ ['a.md', 'b.md', 'x.md'], 'index 超出这一帧长度时落在末尾')
3071
+ assert.deepEqual(mergeGhostRows(docs, [ghost('a.md', 0)], 'primary').map((d) => d.rel),
3072
+ ['a.md', 'b.md'], '还活着的那篇不造幽灵(它只是换了层)')
3073
+ assert.equal(mergeGhostRows(docs, [ghost('x.md', 0, 'related')], 'primary'), docs,
3074
+ '别的区的幽灵不许插进这一区(没得插就原样返回)')
3075
+ assert.equal(mergeGhostRows(docs, [], 'primary'), docs, '没有幽灵时原样返回')
3076
+ assert.equal(mergeGhostRows(docs, null, 'primary'), docs, '没传幽灵也照样出数据')
3077
+ })
3078
+
3079
+ test('v0.17 动效:这套补间只在真机上跑 —— 测试进程里恒被挡掉', () => {
3080
+ const T = loadClientModule().exports.__test
3081
+ assert.equal(T.motionAllowed(), false,
3082
+ '替身没有 document ⇒ 一律不播(渲染树里不会多出 entering / leaving)')
3083
+ assert.ok(T.MOTION_EXIT_MS < T.MOTION_ENTER_MS, '离开要比进入利落:收起不能拖')
3084
+ assert.equal(T.MOTION_EASE, 'cubic-bezier(.22,1,.36,1)',
3085
+ '缓动照抄原型,不许在真客户端另调一套')
3086
+ })
3087
+
3088
+ test('v0.17 动效:CSS 里只有静态那两笔 —— 补间在 JS 里,不留第二套真相', async () => {
3089
+ const { readFileSync } = await import('node:fs')
3090
+ const { fileURLToPath } = await import('node:url')
3091
+ const source = readFileSync(fileURLToPath(new URL('../src/client/client.js', import.meta.url)), 'utf8')
3092
+ const start = source.indexOf('const CSS = `') + 'const CSS = `'.length
3093
+ const css = source.slice(start, source.indexOf('`', start)).replace(/\/\*[\s\S]*?\*\//g, '')
3094
+
3095
+ const leaving = css.match(/\.knit-doc\.leaving\{([^}]*)\}/)
3096
+ assert.ok(leaving, '必须有 .knit-doc.leaving 这条规则')
3097
+ assert.match(leaving[1], /pointer-events:none/, '幽灵行不吃指针事件(它已经在走了)')
3098
+ assert.match(leaving[1], /overflow:hidden/, '收起高度时要能裁掉内容')
3099
+ assert.ok(!leaving[1].includes('animation'),
3100
+ 'CSS 不许自己播关键帧:高度要按量出来的自然高度补间,写死会跳')
3101
+ assert.ok(!/@keyframes/.test(css), 'CSS 里不留 @keyframes —— 只有一套真相')
3102
+ assert.match(css, /@media \(prefers-reduced-motion: reduce\)\{[\s\S]*?\.knit-doc\{transition:none\}/,
3103
+ '系统要求减弱动态效果 ⇒ 连底色过渡一起去掉')
3104
+ })
3105
+
3106
+ test('v0.17 动效:换层 / 重排的位移按 FLIP 算 —— 亚像素抖动不当成「动过」', () => {
3107
+ const T = loadClientModule().exports.__test
3108
+ const { motionShift } = T
3109
+
3110
+ assert.equal(motionShift({ left: 10, top: 40 }, { left: 10, top: 40 }), null, '没动就不补间')
3111
+ assert.equal(motionShift({ left: 10, top: 40 }, { left: 10, top: 40.3 }), null,
3112
+ '亚像素抖动(浏览器缩放 / 滚动残留)不该让整屏一直在微微地飘')
3113
+ assert.deepEqual(motionShift({ left: 12, top: 120 }, { left: 12, top: 40 }),
3114
+ { dx: 0, dy: 80 },
3115
+ '正数=上一帧更靠右下:先把行往下拉回老位置,再补间归位')
3116
+ assert.deepEqual(motionShift({ left: 60, top: 40 }, { left: 12, top: 40 }),
3117
+ { dx: 48, dy: 0 }, '横向也是同一套:分栏里换列同样要飞过去')
3118
+ assert.equal(motionShift(null, { left: 0, top: 0 }), null, '没有上一帧(新行)不归 FLIP 管')
3119
+ assert.equal(motionShift({ left: 0, top: 0 }, null), null, '量不到这一帧就不敢补')
3120
+ assert.equal(motionShift({ left: 0, top: 0 }, { left: 0, top: 3 }, 4), null,
3121
+ '阈值可传:小于它一律算没动')
3122
+ assert.deepEqual(motionShift({ left: 0, top: 0 }, { left: 0, top: 3 }, 2), { dx: 0, dy: -3 },
3123
+ '超过阈值就照实补(负值=上一帧更靠左上)')
3124
+ assert.equal(motionShift({ left: 0, top: NaN }, { left: 0, top: 0 }), null,
3125
+ '矩形里出现 NaN(节点刚卸载)时宁可不播,也别补出一段乱飞')
3126
+ assert.ok(T.MOTION_MOVE_MS > 0 && T.MOTION_MOVE_EPS > 0 && T.MOTION_MOVE_EPS <= 1,
3127
+ 'FLIP 的时长与死区都得是正常量级')
3128
+ })
3129
+
3130
+ test('v0.17 动效:FLIP 给挪过位置的幸存行排补间 —— 进 / 出的行跳过,只补 transform', () => {
3131
+ const T = loadClientModule().exports.__test
3132
+ const { applyRowFlips } = T
3133
+
3134
+ // 鸭子类型的行节点:只实现 FLIP 真正会碰的那几个成员。
3135
+ const row = (rel, top, left) => ({
3136
+ rel,
3137
+ played: [],
3138
+ getAttribute: () => rel,
3139
+ getBoundingClientRect: () => ({ left: left || 0, top }),
3140
+ animate(frames, opts) {
3141
+ this.played.push({ frames, opts })
3142
+ return { finished: Promise.resolve() }
3143
+ },
3144
+ })
3145
+ const host = (...els) => ({ querySelectorAll: () => els })
3146
+
3147
+ // ① 换层 / 重排:先从老位置拉回来,再补到归位
3148
+ const moved = row('a.md', 40)
3149
+ const prev = new Map([['a.md', { left: 0, top: 120 }]])
3150
+ const after = applyRowFlips(host(moved), prev, new Set())
3151
+ assert.equal(moved.played.length, 1, '挪了位置就该补一段')
3152
+ assert.deepEqual(moved.played[0].frames, [
3153
+ { transform: 'translate(0px, 80px)' },
3154
+ { transform: 'translate(0px, 0px)' },
3155
+ ], '正数=上一帧更靠下:先把行拉到老位置,再补回新位置')
3156
+ assert.equal(moved.played[0].opts.duration, T.MOTION_MOVE_MS, '时长用同一个常量')
3157
+ assert.equal(moved.played[0].opts.easing, T.MOTION_EASE, '缓动与进 / 出补间同一套')
3158
+ assert.deepEqual([...after], [['a.md', { left: 0, top: 40 }]], '这一帧的矩形要留给下一帧')
3159
+
3160
+ // ② 正在进 / 出的行跳过(它们有自己的补间,叠一层会打架)
3161
+ const entering = row('b.md', 40)
3162
+ const ghost = row('c.md', 40)
3163
+ const skipped = applyRowFlips(host(entering, ghost), new Map([
3164
+ ['b.md', { left: 0, top: 120 }], ['c.md', { left: 0, top: 120 }],
3165
+ ]), new Set(['b.md', 'c.md']))
3166
+ assert.equal(entering.played.length + ghost.played.length, 0, '进 / 出的行一个都不补')
3167
+ assert.equal(skipped.size, 0,
3168
+ '进 / 出的行连位置都不记 —— 那一刻量到的是补间中间态,记下来下一帧会凭空飘一下')
3169
+
3170
+ // ③ 亚像素抖动不算动;④ 新来的行没得比
3171
+ const jitter = row('d.md', 40.3)
3172
+ const brandNew = row('e.md', 90)
3173
+ const quiet = applyRowFlips(host(jitter, brandNew), new Map([['d.md', { left: 0, top: 40 }]]), new Set())
3174
+ assert.equal(jitter.played.length, 0, '零点几像素不补 —— 否则整屏一直在微微地飘')
3175
+ assert.equal(brandNew.played.length, 0, '第一次出现的行归「飞入」管,FLIP 不接手')
3176
+ assert.deepEqual([...quiet.keys()], ['d.md', 'e.md'], '两行的位置都要记')
3177
+
3178
+ // ⑤ 环境不完整时一声不响(测试进程里就是这样)
3179
+ assert.equal(applyRowFlips(null, new Map(), new Set()).size, 0, '没有列表容器就什么都不做')
3180
+ assert.equal(applyRowFlips({}, null, null).size, 0, '容器不会查节点也照样返回空表')
3181
+ const noAnim = { getAttribute: () => 'f.md', getBoundingClientRect: () => ({ left: 0, top: 10 }) }
3182
+ const onlyMeasure = applyRowFlips({ querySelectorAll: () => [noAnim] },
3183
+ new Map([['f.md', { left: 0, top: 90 }]]), new Set())
3184
+ assert.equal(onlyMeasure.size, 1, '节点不认 WAAPI 时只记位置、不补间,不抛错')
3185
+ })
3186
+
3187
+ test('v0.17 动效:FLIP 量的是布局坐标 —— 滚动 / 悬停 / 容器变高都不算「行挪了位置」', () => {
3188
+ const T = loadClientModule().exports.__test
3189
+ const { applyRowFlips, rowLayoutPoint } = T
3190
+
3191
+ // 一行两套坐标:`offsetTop/offsetLeft` 是**布局坐标**(谁真挪了位置才动),
3192
+ // `getBoundingClientRect` 是**视口坐标**(容器一滚、容器自己一高一变、行上挂个 transform 都会动)。
3193
+ const row = (rel, top, left, viewTop, viewLeft) => ({
3194
+ rel,
3195
+ offsetTop: top,
3196
+ offsetLeft: left,
3197
+ played: [],
3198
+ getAttribute: () => rel,
3199
+ getBoundingClientRect: () => ({ left: viewLeft, top: viewTop }),
3200
+ animate(frames) { this.played.push(frames); return { finished: Promise.resolve() } },
3201
+ })
3202
+ const host = (...els) => ({
3203
+ querySelectorAll: () => els,
3204
+ getBoundingClientRect: () => ({ left: 0, top: 100 }),
3205
+ })
3206
+
3207
+ // ① 容器滚了 80px:视口矩形整体平移,布局坐标一动没动 ⇒ 一行都不许补。
3208
+ // 这就是用户那句「我没有输入任何的对话……文档列表就开始跳动」。
3209
+ const scrolled = row('a.md', 120, 0, 40, 0)
3210
+ const after = applyRowFlips(host(scrolled), new Map([['a.md', { left: 0, top: 120 }]]), new Set())
3211
+ assert.equal(scrolled.played.length, 0, '滚动不是「行换了位置」—— 拿视口矩形量会让整屏凭空补一段')
3212
+ assert.deepEqual([...after], [['a.md', { left: 0, top: 120 }]], '存下来的也必须是布局坐标')
3213
+
3214
+ // ② 鼠标正悬停在那行:`.knit-doc:hover{transform:translateX(-2px)}` 是死区 0.5px 的四倍,
3215
+ // 但那 2px 是 CSS 的事,不许被当成「这行挪了」再补一段(补了会跟悬停过渡打架)
3216
+ const hovered = row('b.md', 200, 0, 200, -2)
3217
+ applyRowFlips(host(hovered), new Map([['b.md', { left: 0, top: 200 }]]), new Set())
3218
+ assert.equal(hovered.played.length, 0, '悬停的 2px 不算位移')
3219
+
3220
+ // ③ 真的换了位置(换层 / 重排):补的差值取自布局坐标,不是视口矩形
3221
+ const moved = row('c.md', 160, 0, 40, -2)
3222
+ applyRowFlips(host(moved), new Map([['c.md', { left: 0, top: 120 }]]), new Set())
3223
+ assert.equal(moved.played.length, 1, '真挪了就补')
3224
+ assert.deepEqual(moved.played[0][0], { transform: 'translate(0px, -40px)' },
3225
+ '差值取自 offsetTop(120→160);取视口矩形(120→40)会补出 80px 的乱飞')
3226
+
3227
+ // ④ 节点没有 offset*(测试替身 / 已卸载)时才退回视口矩形,但要减掉容器那块、加回滚动量
3228
+ const noOffset = { getAttribute: () => 'd.md', getBoundingClientRect: () => ({ left: 0, top: 40 }) }
3229
+ const box = {
3230
+ querySelectorAll: () => [noOffset],
3231
+ getBoundingClientRect: () => ({ left: 0, top: 100 }),
3232
+ scrollTop: 80,
3233
+ }
3234
+ assert.deepEqual(rowLayoutPoint(box, noOffset), { left: 0, top: 20 },
3235
+ '视口 40 − 容器 100 + 滚动 80 = 20:还是布局坐标')
3236
+ assert.equal(rowLayoutPoint(box, null), null, '没有节点就是量不到')
3237
+ assert.equal(rowLayoutPoint({}, {}), null, '两套坐标都拿不到时宁可不补')
3238
+ })
3239
+
3240
+ test('v0.17 动效:FLIP 真的接在提交之后 —— 跳过进 / 出、落盘位置', async () => {
3241
+ const { readFileSync } = await import('node:fs')
3242
+ const { fileURLToPath } = await import('node:url')
3243
+ const source = readFileSync(fileURLToPath(new URL('../src/client/client.js', import.meta.url)), 'utf8')
3244
+ const mark = source.indexOf('/* ── 活下来的行换了位置:FLIP')
3245
+ assert.ok(mark > 0, 'KnitBody 的提交后 layout effect 里必须接上 FLIP')
3246
+ const code = source.slice(mark, source.indexOf('const withGhosts', mark))
3247
+ .replace(/\/\*[\s\S]*?\*\//g, '')
3248
+
3249
+ assert.match(code, /const skip = new Set\(\[\.\.\.motion\.entered\.keys\(\), \.\.\.motion\.ghosts\.keys\(\)\]\)/,
3250
+ '正在进 / 出的 rel 组成跳过表')
3251
+ assert.match(code, /store\.tweenUntil = Date\.now\(\) \+ MOTION_ENTER_MS \+ MOTION_STAGGER_MS/,
3252
+ '进 / 出补间在飞的那几百毫秒留一个「别量」的窗口(量到的是中间态)')
3253
+ assert.match(code, /const settled = motionOn[\s\S]*?store\.view === motionView/,
3254
+ '换屏(视图签名变了)/ 补间还在飞 / 没有行的时候,一个都不量 —— 换屏照补就是「整屏一起飞」')
3255
+ assert.match(code, /store\.positions = settled \? applyRowFlips\(listRef\.current, store\.positions, skip\) : new Map\(\)/,
3256
+ '量的是真列表容器,位置表跨帧传递;不量时清空 —— 别拿上一帧的旧坐标去比')
3257
+ })
3258
+
3259
+ test('v0.17 交互审:列表只在光标真的换了(且焦点在列表上)时跟手滚 —— 刷新不许动列表', async () => {
3260
+ const { readFileSync } = await import('node:fs')
3261
+ const { fileURLToPath } = await import('node:url')
3262
+ const source = readFileSync(fileURLToPath(new URL('../src/client/client.js', import.meta.url)), 'utf8')
3263
+ // ⚠️ 起点必须含 `/*` 本身:否则切片从注释**中间**开始,下面那句去注释的正则找不到配对的
3264
+ // `/*`,会把那段解释「为什么不能依赖 state.docs」的注释当成代码,于是这条测试自己误报。
3265
+ const mark = source.indexOf('/* 键盘焦点跟手滚进视口')
3266
+ assert.ok(mark > 0, 'KnitBody 里必须有「光标跟手滚进视口」那条 effect')
3267
+ const end = source.indexOf('// 预览高度:拖完就记住', mark)
3268
+ assert.ok(end > mark, '切片终点应是「预览高度」那条 effect 的注释')
3269
+ const code = source.slice(mark, end).replace(/\/\*[\s\S]*?\*\//g, '')
3270
+
3271
+ assert.match(code, /\}, \[cursor, query\]\)/, '依赖里只许有 cursor / query')
3272
+ assert.ok(!/state\.docs/.test(code),
3273
+ '不许依赖 state.docs:那是每 5 秒一次的新数组,会把列表每 5 秒拽回光标行一次'
3274
+ + '(用户的原话:「我没有输入任何的对话……文档列表就开始跳动」)')
3275
+ assert.match(code, /document\.activeElement/, '只在列表自己拿着键盘焦点时滚 —— 这条服务的是键盘导航')
3276
+ assert.match(code, /scrollIntoView\(\{ block: 'nearest' \}\)/, '滚的是最小距离,不是把行顶到最上面')
3277
+ })
3278
+