@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.130

package/ds-canonical/references/certified-surfaces.md

@@ -0,0 +1,46 @@
+# Provider surface certification policy
+
+> This document explains the policy; it is not a certification ledger. The only machine-readable
+> status authority is `infra/governance/providers/certifications.json`, validated against
+> `infra/governance/schemas/provider-surface-certification.schema.json` and the exact runtime
+> profiles/evidence named by that control plane. A prose table, hook log, local development history,
+> or old canary may never upgrade a status.
+
+Every provider surface starts as `not-certified`. Repository projection tests prove deterministic
+generation only; they do not prove that a particular Claude Code, Codex, desktop, cloud, remote,
+CI, operating-system, architecture, path-class, or distribution-version target loaded and enforced
+the projection. Native hooks are feedback accelerators and are never the security boundary. Missing
+native events are recorded in the signed product manifest with the authoritative fallback
+`immutable-governance-check-and-protected-ci`.
+
+The current committed certification ledger intentionally remains `not-certified` for every real
+target because no independently signed, target-bound runtime evidence and no verified external
+required-check/readback chain have been activated in this repository. Historical experiments can
+guide a new probe, but cannot be replayed as current certification after the provider registry,
+runtime profile, hook contract, package, operating environment, or distribution version changes.
+
+The managed-CI executor cluster (trusted-execution plan, executor supply chain, activation
+bindings) was retired on 2026-08-04 with the activation-cluster removal — it never activated and
+had no live consumer. Managed broker execution is therefore permanently fail-closed: any receipt
+claiming `managed-ci-attested` dependency trust is rejected outright, and no hosted-runtime,
+transport, certification, or enforcement claim can be derived from the retired machinery.
+
+## Promotion rule
+
+A status may change only through the provider-neutral control plane:
+
+1. Run the registered clean-room probe on one exact target tuple: provider/surface, operating
+   system, Node platform, architecture, execution environment, distribution version, and path class.
+2. Bind all required instruction, skill, hook/event, hard-gate, package, and readback observations to
+   the current registry/profile/artifact digests.
+3. Obtain the required independent issuer signatures. Private signing material must stay outside the
+   repository and model environment.
+4. Verify expiry, revocation, issuer quorum, target matrix, managed-host identity, required-check
+   enforcement, and evidence provenance with the committed validators.
+5. Change the ledger and release state in the same reviewed transition. Any mismatch, stale evidence,
+   missing event, unsupported native Windows target, or absent external activation remains
+   `not-certified` (or `unsupported` where the schema permits it).
+
+Generation, schema validation, poison tests, local macOS execution, WSL2/devcontainer compatibility
+declarations, and a green provider-neutral checker are necessary controls, but none independently
+constitutes provider runtime certification.

package/ds-canonical/references/composition-fidelity.md

@@ -0,0 +1,47 @@
+# Composition Fidelity(SSOT,2026-05-27 初版 / 2026-06-02 conformance-model 修正)
+
+**目標**:驗證「DS components 在 consumer(ds-product-template / fork)被正確使用、沒違反設計原則 / SSOT token」。
+
+**2026-06-02 模型修正(per CF research + world-class benchmark + 專案 2026-05-27 自身結論)**:
+驗的是「**consumer 有沒有用對 DS(conformance)**」,**不是**「consumer 畫面跟 DS showcase 長得一模一樣(pixel-identity)」。後者對「內容刻意不同的產品範本」是 **false-positive 來源、世界級公認反 pattern**。
+
+## 對齊世界級(2026-06-02 WebFetch verified,修正初版未驗 benchmark)
+
+初版宣稱「Polaris/MUI/Carbon/Atlassian 都做 cross DS+consumer pixel diff」= **未驗證 + 不實**(M22/M26 違反)。實證(URL）:
+
+- **Consumer 用對 DS = 一律靜態 lint,非截圖**:Polaris [`stylelint-polaris`](https://polaris-react.shopify.com/tools/stylelint-polaris)(40+ rule promote DS adoption in consuming apps;「Please use a Polaris color token」)/ Atlassian [`@atlaskit/eslint-plugin-design-system`](https://atlassian.design/components/eslint-plugin-design-system/)(`ensure-design-token-usage` / `prefer-primitives` / `use-tokens-space`,帶 auto-fix）/ Carbon [`stylelint-plugin-carbon-tokens`](https://github.com/carbon-design-system/stylelint-plugin-carbon-tokens)(「enforce Carbon tokens ... rather than hard-coded values」)/ MUI(TS theme 型別 + eslint）。
+- **Visual regression = 同一個 story 跨 commit 比自己的 baseline**(抓 DS 改壞自己),非跨 repo 比不同畫面:[Chromatic](https://www.chromatic.com/docs/branching-and-baselines/)(「baseline = last known good state of the story ... from a previous commit on that same branch」)/ [Storybook](https://storybook.js.org/docs/writing-tests/visual-testing)（「compare rendered pixels of every story against known baselines」+ 測 component-in-isolation）。
+- **VR deterministic 鐵律**:seed 靜態 fixture + mask 動態區。產品 app 內容本質跟 DS showcase 不同 → 拿來 pixel 比必全紅 = 100% false positive。
+
+## 機制三層(conformance 主、pixel identity 窄)
+
+| 層 | 驗什麼 | 落地 |
+|---|---|---|
+| **1 marker(conformance 意圖)** | consumer wrap 高風險 primitive 必標 `// @story-baseline: <DS-path>#<export>` cite canonical | `check_consumer_app_invariants.sh(r2,2026-06-11 merge)`(P0)+ `check_story_invariants.sh` R7 |
+| **2 靜態 conformance(主防線)** | consumer 用對 token/primitive、沒 simplified mock、沒硬寫色值/字級/間距/shadow、沒 API-misuse | `check_consumer_app_invariants.sh(r3,2026-06-11 merge)`(P0,含 2026-06-02 Pattern 8 硬寫 token)+ `check_layout_space_magic_numbers.sh`(P0 間距)+ `check_story_invariants.sh` R8(P0,registry antiPattern)+ `check_chrome_header_avatar_canonical.sh` / `check_sidebar_menu_button_implicit_wrap.sh` |
+| **3 pixel/DOM identity(opt-in,窄用)** | 僅「忠實複製 replica」或「同 story 跨版本回歸」才比 render identity | `scripts/composition-fidelity-visual-diff.mjs`,**只比標了 `@composition-fidelity-mode` 的 mapping**;單獨 `@story-baseline` = conformance 不做 identity diff |
+
+**層 3 為何 opt-in(2026-06-02)**:`@story-baseline` 單獨 = conformance 意圖(交層 2 驗)。pixel/DOM identity 只在該 consumer story **額外標** `@composition-fidelity-mode: pixel|shell-only|structural` 才跑(用於忠實複製 / same-story 回歸)。0 個 opt-in → script exit 0(conformance 由層 2 保證)。**禁** 拿產品範本(內容刻意不同)去 pixel 比 DS showcase。
+
+## 層 3 用法(opt-in 時)
+
+```bash
+node scripts/composition-fidelity-visual-diff.mjs \
+  --ds-static=storybook-static \
+  --consumer-static=/path/to/ds-product-template/storybook-static \
+  --consumer-root=/path/to/ds-product-template --threshold-pct=0.5
+```
+
+掛在 `.github/workflows/composition-fidelity.yml`(checkout DS + ds-product-template,build 兩邊 storybook 後比對;**build-storybook 前必先 `build:lib`** 否則 storybook-config tsc 找不到 `@qijenchen/design-system` 型別 = TS2307)。**2026-06-11 cheap pre-step**:checkout 後先秒級 grep consumer `@composition-fidelity-mode` marker(regex 對齊 diff script L118),0 命中 → skip 整段 ~30 min dual build(script 對 0 mapping 必 vacuous exit 0);≥1 命中 → full gate。現役 opt-in sentinel = `apps/template/src/CompositionFidelityReplica.stories.tsx`(Button#IconOnly 忠實複製 replica,mode pixel,經 mirror 傳播到 ds-product-template),讓 gate 名實相符。
+
+## 不該做的事
+
+- ❌ **拿產品範本 demo 當 pixel-identity baseline 對 DS showcase 比**(內容刻意不同 = false positive,world-class 公認反 pattern)— 2026-06-02 改 identity opt-in 修正
+- ❌ baseline story 用 `Math.random()` 等非確定性產值(render 不可重現 → 任何 diff 都是 noise)— 2026-06-02 修 `sidebar.stories.tsx` PageContent
+- ❌ 把 baseline screenshots commit 進 consumer repo(stale)— fetch from DS Pages live
+- ❌ 抽樣 N stories(M-rule 不抽樣)
+
+## 歷史錨例
+
+- **2026-05-27**:user 抓 AppShell Avatar+Label drift。Root cause = stale build artifact(DS storybook-static built BEFORE fix commit)。Lesson:byte-identity ≠ visual ≠ deployed identity。
+- **2026-06-02**:CF check 從建立起 30 次全紅 = 把產品範本(App.tsx,Acme Product / 自訂 nav / dashboard 內容)硬比 DS `sidebar#IconCollapse`(Acme Inc / 不同 nav / 隨機亂數內容),pixel/DOM identity 物理上不可能。修法:層 3 改 opt-in、補層 2 靜態 conformance(Pattern 8 + R8 升 P0)、修 baseline 隨機亂數。對齊專案 2026-05-27 自身結論(memory `feedback_ai_ground_truth_unreliable_mechanical_primary`:render fidelity 由架構保障、template-vs-canonical pixel diff = noise 非 drift)。

package/ds-canonical/references/cva-patterns.md

@@ -1,6 +1,6 @@
-# cva 適用範圍 完整對照(從 CLAUDE.md 拆出)
+# cva 適用範圍 完整對照(historical provenance:從 provider-specific generated adapter CLAUDE.md 拆出)
 
-`.claude/rules/ui-development.md`「shadcn 元件規範」 留判斷法 + 禁止一句話;完整對照表和 documented 例外在本檔。
+Canonical `packages/design-system/ds-canonical/rules/ui-development.md`「shadcn 元件規範」留判斷法 + 禁止一句話;完整對照表和 documented 例外在本檔。
 
 ---
 

package/ds-canonical/references/drag-canonical.md

@@ -1,331 +1,87 @@
-# Drag & Drop Canonical(2026-05-06 v14.8 audit)
+# Drag & Drop Canonical
 
-**Status:** stale-pending-prune(2026-05-18 標記:Phase 1/2 fix plan propose 自 2026-05-06 後 12+ 天無 update,Path B 推薦未確認 ship verify;下次 `/knowledge-prune` 評估 update「現況 audit」表或 inactive 標記)
+**Status:** active；2026-08-01 依現行 code/spec 重驗。舊的 stale-prune 標記、未落地
+Path 比較與已修 bug 過程已由本次 knowledge-prune 收斂；歷史仍可由 Git 追溯。
 
-**Purpose**:統整世界級 drag-drop 實作慣例,作為 DS 內 TreeView / DataTable row drag / DataTable column reorder 的對齊基準。M26 webfetch 後產出,Phase 2(table 進階 tree-view 式 drag)的設計依據。
+## Authority boundary
 
----
+- 元件行為與 API：各元件 `*.spec.md` + production code。
+- 跨元件視覺與純函式：`packages/design-system/src/lib/drag-visual.ts`。
+- 本檔：解釋共同 invariant、現行能力差異與 future-reserved 邊界；不得覆寫 spec/code。
 
-## 1. 世界級實作分類
+TreeView、DataTable row 與 DataTable column 都使用 `@dnd-kit/core` 的
+`useDraggable` + `useDroppable` + `DragOverlay`，但合法 target 與 position 是各元件業務語意，
+不能為表面一致硬抽成同一 collision function。
 
-| Library / Product | 機制 | Drop indicator | 三位置 (before/after/inside) | Snap-back on no-drop |
-|---|---|---|---|---|
-| **Atlassian Pragmatic** | Native HTML5 drag-and-drop API | line bleed 4px outwards on left of target,via `@atlaskit/pragmatic-drag-and-drop-react-drop-indicator` | optional via edge detection package | YES — native HTML5 行為 |
-| **dnd-kit**(我們用)| Custom synthetic events(non-native) | DIY render via state | DIY computation | **依 collision detection 策略** |
-| **Notion table** | proprietary | single horizontal stroke between rows(藍)| no inside drop in tables(用 chevron + sidebar reparent) | YES — 原 row 留原位 + transition state |
-| **Notion blocks** | proprietary | single horizontal stroke + indent at depth | YES via cursor X axis | YES |
-| **AG Grid** | custom | `setRowDropPositionIndicator` API | YES via `treeData` mode | YES |
-| **Linear / Asana** | dnd-kit-based | horizontal stroke (sub-issue reparent) | YES (drop on parent issue) | YES |
-| **VS Code TreeView** | native + Electron | line indicator at depth | YES + cycle prevention | YES |
-| **react-sortable-tree / react-complex-tree** | DIY | + - icons or strokes | YES | YES |
-| **DevExtreme TreeList** | own | + icon for inside,--- for between | configurable `allowDropInsideItem` | YES |
+## 現行能力矩陣
 
----
-
-## 2. dnd-kit Collision Detection 4 大策略(canonical reference)
-
-**官方 docs(https://docs.dndkit.com/api-documentation/context-provider/collision-detection-algorithms)**:
-
-| Algorithm | over=null when? | 適用 case |
-|---|---|---|
-| `closestCenter` | **永遠不 null**(always finds nearest)| draggable items 有相同 size + 整齊排列(典型 list reorder) |
-| `closestCorners` | **永遠不 null** | 跟 closestCenter 類似,multi-corner 算法 |
-| `rectIntersection` | over=null 當 dragged rect 完全不跟 droppable rect 相交 | 需要明確「在 target 內」才算 over |
-| `pointerWithin` | over=null 當 pointer 不在任何 droppable rect 內 | **canonical for tree drag / list with cancel** — pointer-precise,允許 release 在 gap 取消 drop |
-
-**Best practice composite**(dnd-kit official recommendation):
-```ts
-const collisionDetection = (args) => {
-  const pointerCollisions = pointerWithin(args)
-  if (pointerCollisions.length > 0) return pointerCollisions
-  return rectIntersection(args)  // fallback for keyboard sensor
-}
-```
-
----
-
-## 3. 我們 DS 3 個 drag impl 現況 audit
-
-### 3.1 TreeView(基準 canonical)
-
-| 維度 | 現況 |
-|---|---|
-| Mechanism | dnd-kit `useDraggable` + `useDroppable`(non-Sortable) |
-| Collision | **不傳 `collisionDetection` prop** — dnd-kit 預設 `rectIntersection` |
-| Drop position | **手動算 cursor Y offset**(0-25 before / 25-75 inside / 75-100 after for folder; 0-50/50-100 for leaf)|
-| Indicator | absolute div `dropIndicatorRow.before/after/inside`(SSOT v14.5) |
-| Snap-back | ✓(若 release 不在 droppable rect,dropTarget=null,onDragEnd `targetId` undefined → consumer 不更動)|
-| Cycle prevention | 有(walk descendant,exclude self) |
-| Ghost | DragOverlay portal 半透 chip(`bg-surface border shadow-elevation-200`)|
-
-### 3.2 DataTable row drag(現況)
-
-| 維度 | 現況 | 跟 TreeView 一致? |
-|---|---|---|
-| Mechanism | dnd-kit `useSortable`(Sortable variant)| ✗ 不同 |
-| Collision | 自訂 `sameParentCollisionDetection` 用 `closestCenter` | **✗ closestCenter 永遠返回 over → 任何 release 都觸發 reorder**(user bug 2 root cause)|
-| Drop position | active vs over index(只 before/after)| ✗ TreeView 有 inside |
-| Indicator | absolute div `dropIndicatorRow.before/after`(v14.6 SSOT) | ✓ 視覺對齊 |
-| Snap-back | **✗ 不 work** — closestCenter 永遠有 over,釋放任何位置都 fire onRowReorder | ✗ |
-| Cycle prevention | 沒(top-level only,depth>0 沒 handle 不可拖)| N/A |
-| Ghost | DragOverlay portal cloned row HTML(`bg-surface-raised shadow`)| ✓ 同 pattern |
-
-### 3.3 DataTable column reorder(現況)
-
-| 維度 | 現況 | 跟 TreeView 一致? |
-|---|---|---|
-| Mechanism | dnd-kit `useSortable` + cloneElement wrap | ✗ 不同 |
-| Collision | `dndCollisionDetection` 中 column branch 用 `closestCenter` 過濾 type='column' droppables | ✗ |
-| Drop position | active vs over index(only before/after) | ✗ |
-| Indicator | pseudo `dropIndicatorColumn.pseudoBefore/After`(v14.5 SSOT)| ✓ 視覺對齊 |
-| Snap-back | **✗ 不 work** — closestCenter 同 row drag bug | ✗ |
-| Drop indicator visible? | **✗ user 報「ghost 顯示但 indicator line 沒出現」** — root cause 待 debug | ✗ |
-
----
-
-## 4. Root cause 分析(user 兩 bug)
-
-### Bug 1:Column drag — ghost 出來但 column 不動 + 無 indicator
-
-**Root cause CONFIRMED**(2026-05-06 v14.8 runtime debug):
-`reorderableColumnIds` 計算用 `c.id`,但 TanStack `accessor()` columns 沒 explicit `id` field
-(runtime 從 accessorKey 推導)→ map 結果全 ''  → filter 全濾掉 → `reorderableColumnIds = []`
-→ handleDragOver 中 `activeIdx === -1 || overIdx === -1` 永遠成立 → `setDropIndicator(null)`
-早 return → 永遠不 set indicator state → pseudo class 永不 apply。
-
-dnd-kit 本身沒問題:`over.id` 是正確的 'name' / 'category' / 'price'(從 useSortable id 來)。
-**問題 only in our reorderable lookup**。
-
-**Fix**:`reorderableColumnIds` map 加 fallback `cAny.accessorKey ?? ''`。同時 lookup `def`
-也用 same fallback。Verify 後 `reorderable= [name, category, stock, seller, updatedAt, price]` ✓
-indicator pseudo class apply ✓。
-
-### Bug 2:Nested row — 拉動就強制 reorder 不能 snap back
-
-**Root cause CONFIRMED**:
-- `closestCenter` 永遠返回最接近的 droppable
-- `sameParentCollisionDetection` 過濾 cross-parent 但同 parent siblings 仍永遠返回最近的
-- handleDragEnd `if (!over || active.id === over.id) return` — over 永遠非 null,active=over 只在 cursor 完全在 source 上才成立
-- 所以釋放在 row 中間任何位置都會觸發 reorder
+| 能力 | TreeView | DataTable row | DataTable column |
+|---|---|---|---|
+| Drag source | 整列；pointer activation 5px | top-level row handle；8px | header handle；8px |
+| Position | before / after / inside | before / after | before / after |
+| Target scope | 合法 tree node；排除 self/descendant/disabled | same-parent sibling；目前 UI 只開 top-level source | visible、non-system、non-locked column |
+| Collision | dnd-kit rect intersection + component position logic | pointerWithin → live DOM/rectIntersection fallback | pointerWithin → rectIntersection fallback |
+| No-op / cancel | 無合法 target 不 commit | source 範圍、相鄰 noop、cross-parent、gap 都不 commit | noop + 未跨 target midpoint 不 commit |
+| Keyboard | tree virtual-focus 的自建 modifier+arrow reorder | dnd-kit KeyboardSensor | dnd-kit KeyboardSensor |
+| Indicator | row line + inside highlight | row line | column pseudo line |
+| Overlay | node ghost | reconstructed full-row ghost | header ghost |
+
+補充：DataTable 的 column visibility panel、sort manager 等小型內部 sortable list 仍可使用
+`useSortable` + `closestCenter`。它們不是 DataTable canvas row/column drag，沒有「離開 target 應取消」
+的相同語意，因此不構成 SSOT drift。
+
+## 共同 invariant
+
+1. **原 source 留位、overlay 跟 cursor**：overlay 不可讓 source DOM 自動位移；
+   `snapToCursorModifier` 與 overlay reconstruction 由 `drag-visual.ts` owning。
+2. **無意圖不得 commit**：沒有合法 target、仍在 source、等價相鄰位置或未跨越 column midpoint
+   都是 no-op；禁止「一拉起就必換位置」。
+3. **Target 先過語意過濾**：row/column/tree droppable 不可互撞；same-parent、locked、disabled、
+   descendant 等限制先過濾，再做幾何 collision。
+4. **視覺只消費共享 primitive**：source opacity、row/column indicator、invalid cursor、ghost 重建與
+   no-op helper 由 `drag-visual.ts` 提供；元件不可另造平行 class。
+5. **Virtualization 要重測量**：DataTable droppable 使用 `MeasuringStrategy.Always`，必要時以目前
+   table root 內 live DOM rect fallback；禁止 document-wide、只看 Y 軸的 target 搜尋。
+6. **Pointer 與鍵盤都要可完成合法操作**：TreeView 因 `aria-activedescendant` 使用自建鍵盤分支；
+   DataTable 無 `SortableContext`，不可誤套 `sortableKeyboardCoordinates`。
+
+## Collision canonical
+
+需要「pointer 離開合法 target 就取消」的場景，先用 `pointerWithin`，鍵盤／非 pointer 再以
+`rectIntersection` fallback：
 
-**修法**(per dnd-kit canonical):switch to **pointerWithin composite collision detection**:
 ```ts
 const collisionDetection = (args) => {
-  // 先過濾 type / parent
-  const filtered = filterDroppables(args)
-  const pointerCollisions = pointerWithin({ ...args, droppableContainers: filtered })
-  if (pointerCollisions.length > 0) return pointerCollisions
-  return rectIntersection({ ...args, droppableContainers: filtered })  // keyboard fallback
-}
-```
-
----
-
-## 5. Phase 1 修法(unified 3 impls 跟 canonical 對齊)
-
-### F1. DataTable 換 `pointerWithin + rectIntersection` composite collision
-
-**Affected**:`dndCollisionDetection`(line 1957)+ `sameParentCollisionDetection`(line 1791)
-- 改用 `pointerWithin` first,fallback `rectIntersection`(keyboard)
-- Result:cursor 在 row gap / cell gap 釋放 → over=null → onRowReorder 不 fire → snap back
-
-### F2. DataTable column drag indicator root cause debug
-
-**步驟**:加 console.log 到 handleDragOver 觀察 over.id / dropIndicator state update,確認是 collision 問題還是 cloneElement re-render 問題。可能 fix:
-- 改用 `<div>` wrapper(不用 cloneElement)— 對齊 TreeView pattern
-- 或 verify React state batching 沒問題
-
-### F3. TreeView 維持(canonical baseline,3 impls 對齊它)
-
-無需改動。
-
----
-
-## 6. Phase 2 plan — Table row 進階 tree-view 式 drag
-
-### 6.1 設計目標
-
-對齊 TreeView 完整功能 + 對齊 Jira / Linear / Asana subtask reparent canonical:
-- 每個 row(任何 depth)有 drag handle
-- Drop position 3 種:before / after / inside(reparent)
-- Cross-parent move 允許
-- Cycle prevention(不可 drop into 自己 descendant)
-- 視覺對齊 SSOT(`drag-visual.ts` `dropIndicatorRow` + `dropIndicatorInside`)
-
-### 6.2 實作步驟(等 Phase 1 完成才開始)
-
-**6.2.1 State extension**:
-- `dropIndicator.side` type 加 `'inside'`
-- 已 partial done(side type 在 row drop indicator render 已支援)
-
-**6.2.2 handleDragOver — cursor Y 算 3 位置**(對齊 TreeView 邏輯):
-```ts
-const offsetY = cursorY - targetRect.top
-const ratio = offsetY / targetRect.height
-const hasChildren = (over.row.subRows ?? []).length > 0
-let position
-if (hasChildren) {
-  position = ratio < 0.25 ? 'before' : ratio > 0.75 ? 'after' : 'inside'
-} else {
-  position = ratio < 0.5 ? 'before' : 'after'
+  const eligible = filterSemanticTargets(args)
+  const pointer = pointerWithin(eligible)
+  return pointer.length > 0 ? pointer : rectIntersection(eligible)
 }
 ```
 
-**6.2.3 Drop handle on every depth**:
-- 砍 `(row.depth ?? 0) === 0` 條件 in `showDragHandle`
-
-**6.2.4 Cycle prevention**:
-- Build descendant set of dragged row
-- collisionDetection filter excludes descendants
-
-**6.2.5 Visual `inside` highlight**:
-- target row 加 `bg-primary-subtle`(SSOT `dropIndicatorInside`)
-
-**6.2.6 API breaking change**:
-- `onRowReorder(sourceId, targetId, position: 'before' | 'after' | 'inside')`
-- TS type 抓得到既有 consumer 缺漏
-
-### 6.3 Jira-style 特殊規則
-
-從 Jira webfetch 找到:
-- **Story / Task / Bug**:tied to global rank → drag/drop within epic 受限制(只 reorder)
-- **Sub-task**:not tied to global rank → 可自由 drop
-- **Cross-epic reparent**:UI 允許,可拖 task 到 epic panel(Cmd/Ctrl 多選)
-
-我們 table 不需處理 global rank,**全部 row 都 reparent 自由**(對齊 TreeView simpler pattern)。
-
----
-
-## 7. 不在世界級對齊內的設計決策(我們可選的)
-
-### 7.1 Drop indicator 厚度
-- TreeView 用 `h-0.5`(2px),Atlassian Pragmatic「line bleed 4px outwards」(總 4px outwards)
-- 我們選 2px(對齊 TreeView,SSOT 維持)
-
-### 7.2 Cursor 觸發距離(activationConstraint)
-- 我們設 `distance: 8`(8px move 才啟動 drag,避免 click 誤觸)
-- TreeView 同
-- Atlassian / Notion 慣例:5-8px
-
-### 7.3 Inside-drop highlight 顏色
-- TreeView / 我們:`bg-primary-subtle`
-- VS Code:full bg primary
-- Notion:no inside drop in tables
-
----
-
----
-
-## 8. TreeView library landscape(2026-05-06 v14.9 webfetch update)
-
-**重要發現**:**Radix / shadcn 都沒官方 TreeView**,community 自寫:
-
-| Library | Status | Drag/drop | Virtualization | Notes |
-|---|---|---|---|---|
-| **Radix UI Tree primitive** | issue #1456 feature request,未做 | N/A | N/A | 沒 |
-| **shadcn TreeView** | issue #4642 feature request,未做 | N/A | N/A | 沒 |
-| **react-arborist** | mature canonical | ✓ built-in | ✓ | 最 cited reference,但 opinionated full-featured |
-| **react-complex-tree** | mature | ✓ | partial | flex props-based |
-| **MrLightful/shadcn-tree-view** | community shadcn-style | partial | ✗ | shadcn-styled,輕 |
-| **ggoggam/shadcn-treeview** | community shadcn-style | ✓ + cross-tree | ✗ | 跨 tree drag |
-| **neigebaie/shadcn-ui-tree-view** | community shadcn-style | ✓ + multi-select | ✗ | range select / drag select |
-
-**結論**:**我們 TreeView 不是 reinventing**(沒官方可抄)。但有 3 個 community shadcn 風 impls 可參考。考慮:
-- Path A 維持現 custom impl(features 對齊我們 DS,但每個 drag bug 自修)
-- Path B 換 react-arborist(mature 但 opinionated,失去 visual customization 自由度)
-- Path C 借 community shadcn TreeView code 為 base,migrate 到我們 visual SSOT
-- Path D 維持自寫 + 每次 bug 對齊 react-arborist canonical(實際我們現在做的)
-
----
-
-## 9. Drag SSOT 收斂 audit(本 round 重點)
-
-**現況**:`drag-visual.ts` 已 SSOT 視覺。drag 行為邏輯散在 3 處:
-
-| 邏輯 | TreeView | DataTable row | DataTable column |
-|---|---|---|---|
-| Drop position 計算(cursor Y → before/after/inside) | TreeView 自寫 0-25/25-75/75-100 | 用 active vs over index 算 before/after | 同 row drag |
-| Collision detection 策略 | 不傳 `collisionDetection`(default rectIntersection)| pointerWithin + rectIntersection composite(v14.8 fix) | 同 row drag |
-| Cycle prevention | TreeView 自寫 walk descendant | 沒(top-level only) | 沒(無 nesting) |
-| Cross-parent rule | TreeView 自由 | 過濾 same-parent only | N/A |
-
-**抽 SSOT 機會**:
-- ✓ **`lib/drag-collision.ts`**:`pointerWithinComposite(args)` helper — TreeView + DataTable 都 consume
-- ✓ **`lib/drag-position.ts`**:`computeDropPosition(cursorY, targetRect, hasChildren)` helper — TreeView + Phase 2 DataTable advanced drag 都 consume
-- ⚠️ **Collision 內部 filter logic**(same-parent / drag-type)各自有業務語意,不抽
-
----
-
----
-
-## 10. Modern table drag impl 完整對照(2026-05-06 v14.12 webfetch)
-
-### 三大 paradigm
-
-| Paradigm | Library | Source 行為 | 其他 rows | Sortable list 自動 shift | 我們的元件 |
-|---|---|---|---|---|---|
-| **A. dnd-kit useSortable + SortableContext + DragOverlay** | `@dnd-kit/core` + `@dnd-kit/sortable` | source 跟 cursor 預測 drop 位置(dnd-kit 算 transform 給 source 跟 others 預示 drop) | shift transform 自動讓 space | ✓ free | **DataTable row + column** |
-| **B. dnd-kit useDraggable + useDroppable + DragOverlay**(分離 hook)| `@dnd-kit/core` 純 | source 留原位(transform 不套)| 不自動 shift,自管 | ✗ 需自管 | **TreeView** ✓ |
-| **C. Atlassian Pragmatic(native HTML5)**| `@atlassian/pragmatic-drag-and-drop` | source 留原位(browser native drag preview 跟 cursor)| 不自動 shift,自管 | ✗ 自管 | Jira / Trello / Confluence 用 |
-
-### dnd-kit 官方 docs 重點(direct quote 摘錄)
-
-> "For keeping the drag source element in place while dragging (rather than having it follow the cursor),
-> **use a drag overlay rather than transforming the original draggable source** element that is connected
-> to the useDraggable hook. You can update the position of the draggable source while dragging without
-> affecting the drag overlay."
-
-> "when implementing table row reordering with dnd-kit, you can use **two separate hooks with the same
-> id** — useDraggable + useDroppable — which gives the behavior of the row only becoming draggable from
-> the handle, AND source stays still."
-
-**= 我們 TreeView 已經用這 pattern。DataTable 要跟同模式 = paradigm B refactor**。
-
-### Atlassian Pragmatic Jira 真實視覺(深 dive 後修正前理解)
-
-Pragmatic 用 native HTML5 drag preview:
-- **Browser native drag preview** opacity 0.95 + box-shadow(無法 disable,瀏覽器 control)
-- **Source 不主動 transform** — 留 DOM 原位
-- **Drop indicator** 自管 render(line / border)
-- **Trello shadow indicator** = drop placeholder pattern(複雜,scale 不好)
-
-**= Source 留原位確實是 Jira pattern,但靠的是 native HTML5 drag preview + 不套 source transform**。
+`closestCenter` 適合「始終選最近一項」的緊密 sortable list；不可用於需要 gap/cross-scope
+cancel 的 DataTable canvas drag。
 
----
+## Future-reserved（保留，不是現行承諾）
 
-## 11. 我們 DataTable 走 Path 比較
+- DataTable nested row 的 cross-parent/inside reparent。
+- 把 position/collision 抽成跨元件 helper；只有出現第三個同語意 consumer 且完整 predicate 相同時才抽。
+- 更換 drag library。
 
-| Path | 改動 | 視覺結果 | Cost | Trade-off |
-|---|---|---|---|---|
-| **A 維持 v14.11**(dnd-kit useSortable canonical)| 0(現狀)| Source 跟其他 rows 都 shift 預測 drop 位置 | 0 | ✗ 不像 Jira;✓ free auto-shift visual |
-| **B 重構 useDraggable + useDroppable**(TreeView pattern)| ~150-250 行 refactor:砍 SortableContext / 重寫 collisionDetection / 自管 drop animation | Source 完全留原位;Ghost 跟 cursor;自管 indicator | 中-大 | ✓ 對齊 Jira / TreeView 一致;✗ 失 dnd-kit free shift,要自管 visual reorder |
-| **C 換 Atlassian Pragmatic** | 完全砍 dnd-kit + 重 onboard Pragmatic 全 API | Native HTML5 drag preview;Source 完全留原位 | 大(全 refactor)| ✓ Jira 同 stack;✗ 換 lib + 重學 + 跨 column / row / tree 重寫 |
+若啟動 nested reparent，必先更新 DataTable spec/API，補 descendant cycle prevention、inside target
+visual、pointer/keyboard parity、virtualized cases 與 consumer migration；目前
+`onRowReorder(sourceId, targetId, 'before' | 'after')` 不得被文件誤寫成支援 `inside`。
 
-### 我推薦 **Path B**(對齊 DS 內 TreeView):
-- TreeView 已用 `useDraggable + useDroppable` 同 stack
-- DataTable 換同 pattern → DS 內所有 drag 同 paradigm
-- Cost 中等(~200 行),對齊我們已有的 SSOT(`drag-visual.ts`)
-- 結果:Jira 風 source-stays-still + 我們 DS 一致設計語言
+## Historical closure
 
----
+- 2026-05 的 DataTable row/column 已從 `useSortable` Path A 遷移到
+  `useDraggable` + `useDroppable` Path B；舊比較不再是待決提案。
+- accessor-derived column id、強制 reorder、source-scope false target、virtualized stale rect、
+  ghost/cursor 偏移與 midpoint 問題均已有 production guard；現況以 code/spec/tests 為準。
+- `lib/drag-collision.ts`、`lib/drag-position.ts` 從未成為現行 authority，故不再以打勾清單冒充已落地。
 
-## Sources(M26 webfetch update)
+## Sources
 
-- [Atlassian Pragmatic D&D core](https://atlassian.design/components/pragmatic-drag-and-drop)
-- [Atlassian Pragmatic D&D design guidelines](https://atlassian.design/components/pragmatic-drag-and-drop/design-guidelines/)
 - [dnd-kit collision detection algorithms](https://docs.dndkit.com/api-documentation/context-provider/collision-detection-algorithms)
-- [dnd-kit issue: Transform null when no collision](https://github.com/clauderic/dnd-kit/issues/1773)
-- [dnd-kit cancel discussion #210](https://github.com/clauderic/dnd-kit/discussions/210)
-- [Notion Tables docs](https://www.notion.com/help/tables)
-- [AG Grid tree row dragging](https://www.ag-grid.com/react-data-grid/tree-data-row-dragging/)
-- [Syncfusion TreeView drag](https://ej2.syncfusion.com/react/documentation/treeview/drag-and-drop)
-- [react-sortable-tree](https://github.com/frontend-collective/react-sortable-tree)
-- [react-complex-tree](https://rct.lukasbach.com/docs/guides/drag-and-drop/)
-- [DevExtreme Tree List Local Reordering](https://js.devexpress.com/Demos/WidgetsGallery/Demo/TreeList/LocalReordering/React/Light/)
-- [Jira backlog drag subtasks](https://jira.atlassian.com/browse/JRACLOUD-24547)
-- [Radix UI Tree primitive feature request #1456](https://github.com/radix-ui/primitives/issues/1456)
-- [shadcn TreeView feature request #4642](https://github.com/shadcn-ui/ui/issues/4642)
-- [react-arborist canonical tree library](https://github.com/jameskerr/react-arborist)
-- [MrLightful/shadcn-tree-view](https://github.com/MrLightful/shadcn-tree-view)
-- [ggoggam/shadcn-treeview cross-tree drag](https://github.com/ggoggam/shadcn-treeview)
-- [neigebaie/shadcn-ui-tree-view multi-select](https://github.com/neigebaie/shadcn-ui-tree-view)
+- [dnd-kit drag overlay](https://docs.dndkit.com/api-documentation/draggable/drag-overlay)
+- [dnd-kit keyboard sensor](https://docs.dndkit.com/api-documentation/sensors/keyboard)
+- [Atlassian Pragmatic drag and drop](https://atlassian.design/components/pragmatic-drag-and-drop)