@allbluecn/web-app 0.22.4 → 0.23.1

package/src/components/bug/__tests__/subgroup-header.test.tsx

@@ -15,16 +15,33 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
-// BUG 列表双层分组（任务 40）：子组头 depth 缩进/折叠回调 + 冻结组头改写
-// computeFrozenHeader 的同构回归断言（吸顶判定与 story 同一实现，防再次漂移）。
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+// BUG 列表双层分组（任务 40）：子组头 depth 缩进/折叠回调 + 吸附组头回归断言
+// （任务 22 起判定走共享 computeFrozenHeader——等价原生 sticky：活跃才渲染副本、
+// 被下个组头逐像素顶出、边界不留容差；旧「常驻冻结层 + threshold+1 容差」已迁离）。
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { render, screen, fireEvent, cleanup, act } from "@testing-library/react";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import { BugGroupHeader } from "../views/bug-list/group";
 import { computeFrozenHeader } from "@/components/shared-kit/list-kit/frozen-header";
-import type { BugGroupNode } from "../display/use-paged-bug-groups";
+import type { BugGroupNode, PagedBugGroupNode } from "../display/use-paged-bug-groups";
+import type { BugListItem } from "@/shared/bug/types";
+
+// BugList 渲染链裁剪：serverFn 桩（createServerFn 需 tanstackStart 插件编译）、
+// 行与批量工具栏裁掉（各自重 import 链）；组头/组尾保持真实渲染
+vi.mock("@/server/serverFns/bug", () => ({
+  bulkArchiveBugsFn: vi.fn(),
+  bulkDeleteBugsFn: vi.fn(),
+  bulkUpdateBugsFn: vi.fn(),
+  createBugFn: vi.fn(),
+  updateBugFn: vi.fn(),
+}));
+vi.mock("../views/bug-list/row", () => ({ BugListRow: () => null }));
+vi.mock("../views/bug-list/batch-toolbar", () => ({ BugBatchToolbar: () => null }));
+
+import { BugList } from "../views/bug-list";
+import { DEFAULT_BUG_DISPLAY_OPTIONS } from "@/shared/bug/display-types";
 
 const renderWithProviders = (ui: React.ReactElement) =>
   render(<TooltipProvider>{ui}</TooltipProvider>);
@@ -51,9 +68,6 @@ const baseHeaderProps = {
 };
 
 describe("BugGroupHeader 子组头（depth）", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
   afterEach(() => cleanup());
 
   it("depth=1 渲染缩进（pl-4）与子组底色（bg-muted/35）", () => {
@@ -97,15 +111,14 @@ describe("BugGroupHeader 子组头（depth）", () => {
 });
 
 // ---------------------------------------------------------------------------
-// 冻结组头同构回归：bug 列表吸顶判定必须消费共享 computeFrozenHeader
-// （任务 40 内联吸顶改写，与 story-list 同一实现；读源码断言防漂移——
-// install-commands-contract.test.ts 先例）。
+// 吸附组头共享实现契约（bug ↔ story ↔ kanban 三处统一，任务 22）：
+// 读源码断言防漂移（install-commands-contract.test.ts 先例）。
 // ---------------------------------------------------------------------------
 
 const indexSource = readFileSync(resolve(import.meta.dirname, "../views/bug-list/index.tsx"), "utf8");
 
-describe("冻结组头共享实现契约（bug ↔ story 同构）", () => {
-  it("bug-list/index.tsx 从 shared-kit 导入 computeFrozenHeader（不再内联 rangeExtractor+activeStickyRef 吸顶）", () => {
+describe("吸附组头共享实现契约（bug ↔ story 同构）", () => {
+  it("bug-list/index.tsx 从 shared-kit 导入 computeFrozenHeader（共享判定，不内联吸顶）", () => {
     expect(indexSource).toContain(
       'from "@/components/shared-kit/list-kit/frozen-header"',
     );
@@ -115,36 +128,185 @@ describe("冻结组头共享实现契约（bug ↔ story 同构）", () => {
     expect(indexSource).not.toContain("position: sticky");
   });
 
-  it("computeFrozenHeader 吸顶判定与 story 同构（threshold=scrollTop+1、子组 parent 归属）", () => {
-    // bug 双层扁平行布局（index → start）：
-    //   0 header(state=open)      0
-    //   1 subHeader(severity)    36
-    //   2 bug                    80
-    //   3 header(state=fixed)   200
-    const measurements = [{ start: 0 }, { start: 36 }, { start: 80 }, { start: 200 }];
-    const groupIdx = [0, 3];
-    const subIdx = [1];
-    const parentOfSub = new Map([[1, 0]]);
-
-    // 未滚动：激活首个主组、无子组
-    expect(computeFrozenHeader(0, measurements, groupIdx, subIdx, parentOfSub)).toEqual({
-      groupIdx: 0,
-      subIdx: null,
+  it("旧「常驻冻结层」形态必须清零：无固定 top 双层覆盖渲染（subIdx/groupIdx 旧字段）", () => {
+    // 任务 22 前的常驻冻结层：frozenHeader.subIdx/groupIdx + 固定 top 覆盖渲染
+    expect(indexSource).not.toContain("subIdx");
+    expect(indexSource).not.toContain("groupIdx");
+    // 新吸附层：数据槽存在 + 子组头吸附位钉在吸附主组头正下方（subPinTop=HEADER_ROW_HEIGHT）
+    expect(indexSource).toContain('data-slot="bug-frozen-headers"');
+    expect(indexSource).toContain("subPinTop: HEADER_ROW_HEIGHT");
+  });
+
+  it("computeFrozenHeader 双层判定与 bug 扁平布局对表（吸附/顶出/区段随动/切换）", () => {
+    // bug 双层扁平行布局（estimateSize 估高：header/subHeader 36、bug 44、tail 40）
+    //   0 header(open)      0
+    //   1 subHeader(critical) 36
+    //   2 bug                72
+    //   3 tail              116
+    //   4 subHeader(low)    156
+    //   5 bug               192
+    //   6 tail              236
+    //   7 header(fixed)     276
+    //   8 subHeader(critical) 312
+    //   9 bug               356
+    //  10 tail              400
+    const measurements = [
+      { start: 0, size: 36 },
+      { start: 36, size: 36 },
+      { start: 72, size: 44 },
+      { start: 116, size: 40 },
+      { start: 156, size: 36 },
+      { start: 192, size: 44 },
+      { start: 236, size: 40 },
+      { start: 276, size: 36 },
+      { start: 312, size: 36 },
+      { start: 356, size: 44 },
+      { start: 400, size: 40 },
+    ];
+    const levels = {
+      groupIndexes: [0, 7],
+      subIndexes: [1, 4, 8],
+      parentGroupOfSub: new Map<number, number>([
+        [1, 0],
+        [4, 0],
+        [8, 7],
+      ]),
+      pad: 0,
+      subPinTop: 36,
+    };
+    const compute = (scrollTop: number) => computeFrozenHeader(scrollTop, measurements, levels);
+
+    // 首屏：首个组头容器坐标恰为 0，边界不留容差地吸附；子组头吸附位 36 恰在组头正下方
+    expect(compute(0)).toEqual({
+      group: { index: 0, offset: 0 },
+      sub: { index: 1, offset: 0 },
     });
-    // +1 容差：start == scrollTop + 1 视为已到达（与 story 同一语义）
-    expect(computeFrozenHeader(35, measurements, groupIdx, subIdx, parentOfSub)).toEqual({
-      groupIdx: 0,
-      subIdx: 1,
+    // 下一个子组头（start 156）逼近：活跃子组头被逐像素顶出（56 - 36 - 36 = -16）
+    expect(compute(100)).toEqual({
+      group: { index: 0, offset: 0 },
+      sub: { index: 1, offset: -16 },
     });
-    // 跨到第二个主组：子组重置（不属于该主组）
-    expect(computeFrozenHeader(200, measurements, groupIdx, subIdx, parentOfSub)).toEqual({
-      groupIdx: 3,
-      subIdx: null,
+    // 组切换前一瞬（st=275）：主组头被 G2 顶出 -35；子组头随区段结束（G2 上缘）滑出 -71
+    expect(compute(275)).toEqual({
+      group: { index: 0, offset: -35 },
+      sub: { index: 4, offset: -71 },
     });
-    // 负 scrollTop（overscroll）钳制
-    expect(computeFrozenHeader(-5, measurements, groupIdx, subIdx, parentOfSub)).toEqual({
-      groupIdx: 0,
-      subIdx: null,
+    // 组切换边界（st=276）：新组头零跳变就位，子组头切换为其首个子组（归属门生效）
+    expect(compute(276)).toEqual({
+      group: { index: 7, offset: 0 },
+      sub: { index: 8, offset: 0 },
     });
+    // 滚过末尾：双层停在最后一组（无顶出源，offset 恒 0）
+    expect(compute(10000)).toEqual({
+      group: { index: 7, offset: 0 },
+      sub: { index: 8, offset: 0 },
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// BugList 吸附层行为（jsdom：行高走 estimateSize 精确值，scrollTop 直写 + rAF 节流）
+// ---------------------------------------------------------------------------
+
+function makeBugItem(id: string): BugListItem {
+  return { id } as unknown as BugListItem;
+}
+
+/** 双层分组夹具：布局与上方「对表」用例一致（starts 0/36/72/116/156/192/236/276/312/356/400） */
+const twoLevelGroups: PagedBugGroupNode[] = [
+  makeNode({
+    key: "open",
+    label: "待处理",
+    totalCount: 2,
+    items: [makeBugItem("b1"), makeBugItem("b2")],
+    subGroups: [
+      makeNode({ key: "critical", label: "严重", totalCount: 1, items: [makeBugItem("b1")] }),
+      makeNode({ key: "low", label: "较低", totalCount: 1, items: [makeBugItem("b2")] }),
+    ],
+  }),
+  makeNode({
+    key: "fixed",
+    label: "已修复",
+    totalCount: 1,
+    items: [makeBugItem("b3")],
+    subGroups: [
+      makeNode({ key: "critical", label: "严重", totalCount: 1, items: [makeBugItem("b3")] }),
+    ],
+  }),
+];
+
+const baseListProps = {
+  groups: twoLevelGroups,
+  isLoading: false,
+  displayFilters: DEFAULT_BUG_DISPLAY_OPTIONS,
+  users: [],
+  labels: [],
+  onRefresh: () => {},
+  onPatchBug: () => {},
+  onOpenBug: () => {},
+};
+
+async function scrollBugList(container: HTMLElement, top: number) {
+  const el = container.querySelector<HTMLElement>(".overflow-y-auto");
+  if (!el) throw new Error("scroll container not found");
+  Object.defineProperty(el, "scrollTop", { configurable: true, value: top });
+  await act(async () => {
+    fireEvent.scroll(el);
+    // 组件内 rAF 节流：排进同帧队列，等下一帧回调执行完
+    await new Promise((r) => requestAnimationFrame(r));
+  });
+}
+
+const frozenLayer = (container: HTMLElement) =>
+  container.querySelector<HTMLElement>('[data-slot="bug-frozen-headers"]');
+
+describe("BugList 吸附组头（共享 computeFrozenHeader）", () => {
+  afterEach(() => cleanup());
+
+  it("首屏即吸附（首个组头容器坐标恰为 0）：主/子双层满宽实色底色盒 offset 0", () => {
+    const { container } = renderWithProviders(<BugList {...baseListProps} />);
+    const layer = frozenLayer(container);
+    expect(layer).toBeTruthy();
+    const bands = layer!.querySelectorAll<HTMLElement>(":scope > div");
+    expect(bands.length).toBe(2);
+    // 子组头带在下（top 36 = HEADER_ROW_HEIGHT）、主组头带在上（top 0）
+    expect(bands[0]!.textContent).toContain("严重");
+    expect(bands[0]!.style.transform).toBe("translateY(0px)");
+    expect(bands[0]!.style.top).toBe("36px");
+    expect(bands[1]!.textContent).toContain("待处理");
+    expect(bands[1]!.style.transform).toBe("translateY(0px)");
+    // 满宽实色底色盒（与 BugGroupHeader sticky 变体同源，任务 22 单一来源）
+    expect(bands[0]!.className).toContain("bg-[color-mix(in_oklch,var(--muted)_35%,var(--card)_65%)]");
+    expect(bands[1]!.className).toContain("bg-[color-mix(in_oklch,var(--muted)_50%,var(--card)_50%)]");
+  });
+
+  it("下个组头逼近：主组头被顶出负值、子组头随区段结束滑出", async () => {
+    const { container } = renderWithProviders(<BugList {...baseListProps} />);
+    await scrollBugList(container, 275);
+    const bands = frozenLayer(container)!.querySelectorAll<HTMLElement>(":scope > div");
+    expect(bands[1]!.textContent).toContain("待处理");
+    expect(bands[1]!.style.transform).toBe("translateY(-35px)");
+    expect(bands[0]!.textContent).toContain("较低");
+    expect(bands[0]!.style.transform).toBe("translateY(-71px)");
+  });
+
+  it("组切换边界零跳变：新组头 offset 0 就位，子组头切换为新组首个子组", async () => {
+    const { container } = renderWithProviders(<BugList {...baseListProps} />);
+    await scrollBugList(container, 276);
+    const bands = frozenLayer(container)!.querySelectorAll<HTMLElement>(":scope > div");
+    expect(bands[1]!.textContent).toContain("已修复");
+    expect(bands[1]!.style.transform).toBe("translateY(0px)");
+    expect(bands[0]!.textContent).toContain("严重");
+    expect(bands[0]!.style.transform).toBe("translateY(0px)");
+  });
+
+  it("子组头被下个同级子组头顶出（组内滚动）", async () => {
+    const { container } = renderWithProviders(<BugList {...baseListProps} />);
+    await scrollBugList(container, 100);
+    const bands = frozenLayer(container)!.querySelectorAll<HTMLElement>(":scope > div");
+    expect(bands[1]!.textContent).toContain("待处理");
+    expect(bands[1]!.style.transform).toBe("translateY(0px)");
+    expect(bands[0]!.textContent).toContain("严重");
+    expect(bands[0]!.style.transform).toBe("translateY(-16px)");
   });
 });

package/src/components/bug/peek-panel.tsx

@@ -23,7 +23,7 @@
 // 与独立路由共用 BugDetailBody。
 import { useCallback, useEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
-import { useHotkey } from "@tanstack/react-hotkeys";
+import { useAppHotkeys, useHotkey } from "@tanstack/react-hotkeys";
 import { Skeleton } from "@/components/ui/skeleton";
 import { Dialog, DialogContent } from "@/components/ui/dialog";
 import { CalendarClock, Folder } from "lucide-react";
@@ -144,8 +144,10 @@ export function BugPeekPanel({
   }, [bugId]);
 
   // Esc 仅 side-peek 面板注册（side-dock 与 story/testcase 口径一致不注册；
-  // modal/full-screen 由 Dialog 自身 Esc → onOpenChange 关闭）
-  useHotkey("Escape", onClose, { enabled: isSidePeek });
+  // modal/full-screen 由 Dialog 自身 Esc → onOpenChange 关闭）。
+  // 声明即绑定：close-panel 条目单一来源（lib/hotkeys/registry.ts）
+  const hk = useAppHotkeys();
+  useHotkey(hk["close-panel"], onClose, { enabled: isSidePeek });
 
   const handleBugUpdate = useCallback(
     (next: BugDetail) => {

package/src/components/bug/views/bug-list/group.tsx

@@ -44,12 +44,22 @@ interface BugGroupHeaderProps {
   showSelect: boolean;
 }
 
+/**
+ * 组头吸附层底色单一来源（任务 22）：吸附层满宽底色盒（index.tsx）与
+ * BugGroupHeader 的 sticky 变体共用，防漂移。必须是实色（color-mix 两实色
+ * 变量）：吸附层要完全遮挡其下滚动的行，半透明底会透出下层内容。
+ */
+export const bugHeaderSurfaceClass = (depth: number) =>
+  depth === 0
+    ? "bg-[color-mix(in_oklch,var(--muted)_50%,var(--card)_50%)]"
+    : "bg-[color-mix(in_oklch,var(--muted)_35%,var(--card)_65%)]";
+
 export const BugGroupHeader = memo(function BugGroupHeader({ node, depth, collapsed, collapseKey, onToggle, onCreate, sticky, selectState, onToggleSelect, showSelect }: BugGroupHeaderProps) {
   const textColor = node.color?.split(" ").find((c) => c.startsWith("text")) ?? "text-muted-foreground";
 
   return (
-    // 冻结层用实色混底（50%/35% muted×card），原位行用透明度底——与 story 双层一致
-    <div className={cn("flex h-full items-center", sticky ? (depth === 0 ? "bg-[color-mix(in_oklch,var(--muted)_50%,var(--card)_50%)]" : "bg-[color-mix(in_oklch,var(--muted)_35%,var(--card)_65%)]") : depth === 0 ? "bg-muted/50" : "bg-muted/35", depth > 0 && "pl-4")}>
+    // 吸附层用实色混底（50%/35% muted×card），原位行用透明度底——与 story 双层一致
+    <div className={cn("flex h-full items-center", sticky ? bugHeaderSurfaceClass(depth) : depth === 0 ? "bg-muted/50" : "bg-muted/35", depth > 0 && "pl-4")}>
       {showSelect && (
         <Checkbox
           checked={selectState === true}

package/src/components/bug/views/bug-list/index.tsx

@@ -16,7 +16,7 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties } from "react";
-import { defaultRangeExtractor, useVirtualizer } from "@tanstack/react-virtual";
+import { useVirtualizer } from "@tanstack/react-virtual";
 import {
   bulkArchiveBugsFn,
   bulkDeleteBugsFn,
@@ -26,18 +26,19 @@ import { toast } from "@/components/ui/toast";
 import type { UserBrief } from "@/shared/story/types";
 import type { BugDisplayOptions, BugDisplayProperty } from "@/shared/bug/display-types";
 import type { BugGroupNode, BugPatch, PagedBugGroupNode } from "../../display/use-paged-bug-groups";
-import { BugGroupHeader, BugGroupTailRow } from "./group";
+import { BugGroupHeader, BugGroupTailRow, bugHeaderSurfaceClass } from "./group";
 import { BugListRow } from "./row";
 import { BugBatchToolbar } from "./batch-toolbar";
 import { computeGroupCheckState, toggleGroupSelection } from "./group-select";
-// 任务 40：吸顶判定消费共享 computeFrozenHeader（bug 侧首次与 story 统一冻结
-// 组头机制；对照 story-list/index.tsx 消费方式——吸附语义 threshold=scrollTop+1、
-// 冻结层覆盖式渲染在滚动容器外）。
-import { computeFrozenHeader, type FrozenHeader } from "@/components/shared-kit/list-kit/frozen-header";
+// 任务 22：吸附组头判定统一走共享 computeFrozenHeader（等价原生 sticky：活跃才
+// 渲染副本、被下个组头逐像素顶出、边界不留容差），替代旧的「滚动容器外常驻
+// 冻结层」（固定 top、无顶出、threshold+1 容差——违规存量；任务 40 为 story 同构引入）。
+import { computeFrozenHeader, type FrozenHeaderResult } from "@/components/shared-kit/list-kit/frozen-header";
 import { WavePhysicsLoader } from "@/components/shared-kit/loading/wave-physics-loader";
 import { useDeferredFlag } from "@/components/shared-kit/loading/use-deferred-flag";
 import { m } from "@/paraglide/messages.js";
 import { toastError } from "@/lib/toast-error";
+import { cn } from "@/lib/utils";
 
 const HEADER_ROW_HEIGHT = 36;
 const BUG_ROW_HEIGHT = 44;
@@ -280,13 +281,13 @@ export function BugList({ groups, isLoading = false, displayFilters, users, labe
     return tailHeights.current[row.key] ?? 40;
   }, [flatRows]);
 
-  // 吸顶判定（任务 40 前的内联 ref 自吸顶 + 行内 sticky 定位机制已移除，改
-  // 共享 computeFrozenHeader + 滚动容器外冻结层覆盖渲染，与 story 同构）。
-  // 冻结组头渲染在滚动容器外层，位置固定（组头 top:0、子组头 top:36），滚动时
-  // 唯一变化的是「当前活跃组头索引」——仅在跨越分组边界时改变。因此不存每帧
-  // 变化的 scrollTop，只存派生结果并去重：组内连续滚动零 setState 零整表重渲染。
-  const [frozenHeader, setFrozenHeader] = useState<FrozenHeader | null>(null);
-  const frozenHeaderRef = useRef<FrozenHeader | null>(null);
+  // 吸附组头（任务 22 前为滚动容器外常驻冻结层，任务 40 前为内联 ref 自吸顶）：
+  // computeFrozenHeader 派生活跃（主/子）组头及顶出位移。副本仍渲染在滚动容器
+  // 外层，但仅在组头越过吸附位后才出现，并被下一个组头逐像素顶出——与原生
+  // sticky 等价。不存每帧变化的 scrollTop，只存派生结果（index+offset 双值），
+  // ref 去重：组内连续滚动零 setState 零整表重渲染。
+  const [frozen, setFrozen] = useState<FrozenHeaderResult | null>(null);
+  const frozenRef = useRef<FrozenHeaderResult | null>(null);
   const frozenRafRef = useRef<number | null>(null);
 
   const rowVirtualizer = useVirtualizer({
@@ -294,49 +295,42 @@ export function BugList({ groups, isLoading = false, displayFilters, users, labe
     getScrollElement: () => scrollRef.current,
     estimateSize,
     overscan: OVERSCAN,
-    rangeExtractor: useCallback(
-      (range) => {
-        // 活跃（主/子）组头必须保持在虚拟化渲染窗口内，否则滚动容器外的冻结层
-        // 无内容可覆盖渲染（story 同款；此处只决定渲染集合，不承载吸顶判定）
-        const activeGroupIdx = [...groupHeaderIndexes].reverse().find((i) => range.startIndex >= i);
-        let activeSubIdx: number | null = null;
-        if (activeGroupIdx != null) {
-          const candidate = [...subGroupHeaderIndexes].reverse().find((i) => i <= range.startIndex);
-          if (candidate != null && parentGroupOfSub.get(candidate) === activeGroupIdx) {
-            activeSubIdx = candidate;
-          }
-        }
-        const idx = new Set(defaultRangeExtractor(range));
-        if (activeGroupIdx != null) idx.add(activeGroupIdx);
-        if (activeSubIdx != null) idx.add(activeSubIdx);
-        return [...idx].sort((a, b) => a - b);
-      },
-      [groupHeaderIndexes, subGroupHeaderIndexes, parentGroupOfSub],
-    ),
+    // 任务 22：不再用 rangeExtractor 强留活跃组头行——吸附层从 flatRows 数据
+    // 直接渲染（与 kanban 同构），在流行按虚拟窗口自然进出
     enabled: flatRows.length > 0,
   });
   const virtualRows = rowVirtualizer.getVirtualItems();
   const totalHeight = rowVirtualizer.getTotalSize();
   const remeasureRows = useCallback(() => rowVirtualizer.measure(), [rowVirtualizer]);
 
-  // 冻结组头派生：读取当前滚动位置算出活跃（主/子）组头，仅在结果变化时提交 state
+  // 吸附组头派生：读取当前滚动位置算出活跃（主/子）组头与顶出位移，仅在结果
+  // （index+offset 双值）变化时提交 state
   const recomputeFrozenHeader = useCallback(() => {
     frozenRafRef.current = null;
     const el = scrollRef.current;
     if (!el) return;
     // measurementsCache ?? []：虚拟化桩（测试/极端首帧）可能未提供测量缓存，
-    // computeFrozenHeader 对缺失测量返回 null（无冻结层），不抛错
-    const next = computeFrozenHeader(
-      el.scrollTop,
-      rowVirtualizer.measurementsCache ?? [],
-      groupHeaderIndexes,
-      subGroupHeaderIndexes,
+    // computeFrozenHeader 对缺失测量返回 null（无吸附层），不抛错
+    const next = computeFrozenHeader(el.scrollTop, rowVirtualizer.measurementsCache ?? [], {
+      groupIndexes: groupHeaderIndexes,
+      subIndexes: subGroupHeaderIndexes,
       parentGroupOfSub,
-    );
-    const prev = frozenHeaderRef.current;
-    if (prev?.groupIdx === next?.groupIdx && prev?.subIdx === next?.subIdx) return;
-    frozenHeaderRef.current = next;
-    setFrozenHeader(next);
+      // 滚动容器 overflow-y-auto 无上内边距：测量原点 = 滚动口顶
+      pad: 0,
+      // 子组头吸附在吸附主组头正下方（组头行高 36）
+      subPinTop: HEADER_ROW_HEIGHT,
+    });
+    const prev = frozenRef.current;
+    if (
+      prev?.group?.index === next.group?.index &&
+      prev?.group?.offset === next.group?.offset &&
+      prev?.sub?.index === next.sub?.index &&
+      prev?.sub?.offset === next.sub?.offset
+    ) {
+      return;
+    }
+    frozenRef.current = next;
+    setFrozen(next);
   }, [rowVirtualizer, groupHeaderIndexes, subGroupHeaderIndexes, parentGroupOfSub]);
 
   // rAF 节流：每帧最多重算一次（滚动事件可能一帧多次触发）
@@ -441,27 +435,23 @@ export function BugList({ groups, isLoading = false, displayFilters, users, labe
     return null;
   };
 
-  const renderFrozenHeader = (idx: number, top: number, depth: number, zIndex: number) => {
+  // 吸附层组头内容渲染：与在流组头同一渲染单元（BugGroupHeader sticky 实色变体），
+  // 保证吸附态与在流态视觉与交互完全一致。快捷创建不入吸附层（旧常驻层同口径）
+  const renderFrozenHeaderRow = (idx: number, depth: 0 | 1) => {
     const row = flatRows[idx];
     if (!row || (row.kind !== "header" && row.kind !== "subHeader")) return null;
     return (
-      <div
-        key={row.key}
-        className="absolute inset-x-0 overflow-hidden"
-        style={{ top, zIndex, height: HEADER_ROW_HEIGHT }}
-      >
-        <BugGroupHeader
-          node={row.node}
-          depth={depth}
-          collapsed={row.isCollapsed}
-          collapseKey={row.key}
-          onToggle={toggleCollapse}
-          sticky
-          selectState={computeGroupCheckState(groupBugIds.get(row.key) ?? [], selectedIds)}
-          onToggleSelect={() => toggleGroup(row.key)}
-          showSelect={selectedIds.size > 0}
-        />
-      </div>
+      <BugGroupHeader
+        node={row.node}
+        depth={depth}
+        collapsed={row.isCollapsed}
+        collapseKey={row.key}
+        onToggle={toggleCollapse}
+        sticky
+        selectState={computeGroupCheckState(groupBugIds.get(row.key) ?? [], selectedIds)}
+        onToggleSelect={() => toggleGroup(row.key)}
+        showSelect={selectedIds.size > 0}
+      />
     );
   };
 
@@ -483,11 +473,48 @@ export function BugList({ groups, isLoading = false, displayFilters, users, labe
           </div>
         )}
       </div>
-      {frozenHeader && (
-        <>
-          {frozenHeader.subIdx != null && renderFrozenHeader(frozenHeader.subIdx, HEADER_ROW_HEIGHT, 1, 9)}
-          {renderFrozenHeader(frozenHeader.groupIdx, 0, 0, 10)}
-        </>
+      {/* 吸附组头副本（任务 22，替代旧常驻冻结层）：仅在组头越过吸附位后渲染
+          （computeFrozenHeader），并被下一个组头逐像素顶出（translateY 负值），
+          与原生 sticky 等价。结构照 kanban 吸附层同款：
+          - 外层 pointer-events-none + overflow-hidden：顶出越界部分裁在滚动口顶
+          - 满宽实色底色盒（bugHeaderSurfaceClass，与 BugGroupHeader sticky 变体
+            同源）无纵向内边距——纵向范围 = 组头行自身盒子（高 HEADER_ROW_HEIGHT）
+          - 内容包 pointer-events-auto：组头可点（折叠/勾选），带外点击穿透
+          - 子组头层在下、主组头层在上（z 9/10）：组切换顶出阶段两层同带滑出，
+            露出主组头（旧常驻层 z 序，行为保持） */}
+      {frozen && (frozen.group || frozen.sub) && (
+        <div
+          data-slot="bug-frozen-headers"
+          className="pointer-events-none absolute inset-0 z-10 overflow-hidden"
+        >
+          {frozen.sub && (
+            <div
+              className={cn("absolute inset-x-0 z-[9]", bugHeaderSurfaceClass(1))}
+              style={{
+                top: HEADER_ROW_HEIGHT,
+                height: HEADER_ROW_HEIGHT,
+                transform: `translateY(${frozen.sub.offset}px)`,
+              }}
+            >
+              <div className="pointer-events-auto h-full">
+                {renderFrozenHeaderRow(frozen.sub.index, 1)}
+              </div>
+            </div>
+          )}
+          {frozen.group && (
+            <div
+              className={cn("absolute inset-x-0 top-0 z-10", bugHeaderSurfaceClass(0))}
+              style={{
+                height: HEADER_ROW_HEIGHT,
+                transform: `translateY(${frozen.group.offset}px)`,
+              }}
+            >
+              <div className="pointer-events-auto h-full">
+                {renderFrozenHeaderRow(frozen.group.index, 0)}
+              </div>
+            </div>
+          )}
+        </div>
       )}
       <BugBatchToolbar
         selectedCount={selectedIds.size}

package/src/components/command/command-palette.tsx

@@ -15,9 +15,10 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
-import { useState, useSyncExternalStore } from "react"
+import { useState } from "react"
+import { useSelector } from "@tanstack/react-store"
 import { useThemeMode } from "@/providers/theme-mode-provider"
-import { useHotkey, useHotkeys } from "@tanstack/react-hotkeys"
+import { useAppHotkeys, useHotkey, useHotkeys } from "@tanstack/react-hotkeys"
 import type { HotkeySequence } from "@tanstack/hotkeys"
 import {
   CommandMenu,
@@ -84,11 +85,10 @@ export function CommandPalette() {
   const { toggle } = useThemeMode()
   const [designDialogOpen, setDesignDialogOpen] = useState(false)
 
-  const open = useSyncExternalStore(
-    commandPaletteStore.subscribe,
-    commandPaletteStore.getSnapshot,
-    () => false,
-  )
+  // 任务 25：手写 store 迁官方 Store（见 command-palette-state.ts）。store
+  // 初始值模块级 false 且 SSR 期间不可变更，useSelector 以 get() 同时充当
+  // server snapshot，与旧 useSyncExternalStore(subscribe, get, () => false) 等价
+  const open = useSelector(commandPaletteStore)
 
   const { commands, execute } = useCommands({
     onAction: (id) => {
@@ -104,9 +104,10 @@ export function CommandPalette() {
     execute(cmd)
   }
 
-  useHotkey("Mod+K", toggleCommandPalette, { ignoreInputs: false })
+  const hk = useAppHotkeys()
+  useHotkey(hk["command-palette"], toggleCommandPalette, { ignoreInputs: false })
   useHotkey(
-    "Mod+Shift+L",
+    hk["toggle-theme"],
     () => {
       // FS-5.4：设计画布编辑器内 Mod+Shift+L 是「锁定」命令（canvas useEditCommands），
       // 全局主题切换在画布挂载时让位，避免双 handler 同时触发（锁定同时翻转主题）

package/src/components/design/canvas/document/frame-custom-presets.ts

@@ -71,7 +71,15 @@ function subscribe(listener: () => void): () => void {
   }
 }
 
-/** 订阅自定义画板预设列表；SSR 返回空数组避免 hydration 差异 */
+/**
+ * 订阅自定义画板预设列表；SSR 返回空数组避免 hydration 差异。
+ *
+ * 保留 useSyncExternalStore（任务 25 审计裁决）：getFrameCustomPresets 走
+ * ensureLoaded 读 window.localStorage，不能充当服务端快照；而官方
+ * useSelector 以 get() 同时充当 getServerSnapshot、不支持独立的
+ * getServerSnapshot——故此处无法迁 useSelector，必须保留原生
+ * useSyncExternalStore 以显式注入 `() => []` 服务端快照。
+ */
 export function useFrameCustomPresets(): FrameCustomPreset[] {
   return useSyncExternalStore(subscribe, getFrameCustomPresets, () => [])
 }