@deepseek-ai/dsh-client-ui-dockkit 0.2.1-rc.5 → 0.2.2-alpha.3

package/README.i18n.yaml

@@ -15,14 +15,14 @@
   en: 42038fdc402b9c2a
   zh: 99890f8f908624ce
 /deepseek-ai-dsh-client-ui-dockkit/the-two-layers:
-  en: ea872ff2c2089037
-  zh: b3ec3a218eacd5c8
+  en: 718f52cfce426009
+  zh: e8282e2e3713d242
 /deepseek-ai-dsh-client-ui-dockkit/embedding-it:
-  en: 47b9852393643b6a
-  zh: ce5f2ab60eec9564
+  en: 53bbabeb910c6f77
+  zh: 51fb4f8fb78cfd02
 /deepseek-ai-dsh-client-ui-dockkit/interaction-rules-worth-keeping:
-  en: 7e5c1e9a9f9f244f
-  zh: 7e3a8fcef86bc7dd
+  en: cf2d00ce2b7d5719
+  zh: 5510420f8872e23a
 /deepseek-ai-dsh-client-ui-dockkit/build-shape:
   en: 21216ba5798d7f5f
   zh: ac505fdcd5c114d4

package/README.md

@@ -37,7 +37,11 @@ A docking layout kit: a split tree of tabbed panes with invertible operations, a
 - `planSettle` is the opt-in rule that keeps every docked pane populated after an intent: panes an intent emptied are merged away, and an emptied root pane is reseeded through the embedder's factory — withholding the factory keeps the merge and leaves the root pane empty. An embedder that wants empty panes simply does not call it, or calls it without a factory. `planDropTab` takes the same factory: with one, a sole tab released on its own pane's edge splits and the factory's tab backfills the pane it vacates (the dragged tab stays focused); without one that release changes nothing.
 - `DockController` is the intent layer and an observable source (`subscribe` + `getSnapshot`, whose reference only changes when the layout does).
 
-**The components** render a layout snapshot and report settled intents — one per gesture, never a drag frame. A drag previews in local state while the gesture's own facts stay in its closure; on release the net result leaves through one `DockIntents` call — a strip release reports the caret slot as drawn, the dragged chip counted, and `planPlaceTab` turns that into the reorder or the move. That is what lets an embedder record exactly one history entry per gesture. The strip follows the WAI-ARIA tabs pattern with manual activation: the selected chip is in the tab order; Left and Right (wrapping), Home, and End move focus between chips without selecting; Enter or Space selects the focused chip through the same intent as a click. A chip is a capsule carrying one control, its close; the context menu (a secondary press on the chip) carries the same close plus the embedder's items — a menu that would hold no item at all never shows — and renders in a portal positioned against the chip because the chip box clips its overflow on purpose (see below). After the chips sits the add control, which asks the embedder (`DockIntents.addTab`) to seat its seeded tab; the embedder's `canAddTab(paneId)` decides per pane whether the control is drawn at all. Copying a tab has no kit control — it is the embedder's API — and floating is the drag released clear of the surface.
+**The components** render a layout snapshot and report settled intents — one per gesture, never a drag frame. A drag previews in local state while the gesture's own facts stay in its closure; on release the net result leaves through one `DockIntents` call — a strip release reports a placement only when a caret is drawn, the dragged chip counted, and `planPlaceTab` turns that into the reorder or the move. That is what lets an embedder record exactly one history entry per gesture. The strip follows the WAI-ARIA tabs pattern with manual activation: the selected chip is in the tab order; Left and Right (wrapping), Home, and End move focus between chips without selecting; Enter or Space selects the focused chip through the same intent as a click. A chip is a capsule carrying one control, its close; the context menu (a secondary press on the chip) carries the same close plus the embedder's items — a menu that would hold no item at all never shows — and renders in a portal positioned against the chip because the chip box clips its overflow on purpose (see below). After the chips sits the add control, which asks the embedder (`DockIntents.addTab`) to seat its seeded tab; the embedder's `canAddTab(paneId)` decides per pane whether the control is drawn at all. Copying a tab has no kit control — it is the embedder's API — and floating is the drag released clear of the surface.
+
+Middle-clicking anywhere on a closable tab chip, including its close control, closes it through the same intent as its close button, without selecting it first. The chip owns the middle click and suppresses nested title content’s default action. Closing a background tab preserves the selected tab. Only the primary button starts tab dragging; a middle click while another mouse button is held does not close the tab.
+
+Strip slots that preserve the dragged tab’s position show no insertion caret and report no placement; the tab can still be dragged to split a pane or float.
 
 Tab context menus show the close action name without a shortcut hint: they act on the clicked tab, while shortcuts can target another focused pane. An unmodified Escape dismisses the foreground tab menu without closing the tab and returns focus from a menu item to its tab without drawing a focus outline. Tab and arrow navigation retain the tab’s visible focus indicator. Composition and held-key repeats do not dismiss it.
 
@@ -52,15 +56,19 @@ Everything host-specific arrives through props:
 | `TabRenderer` | one tab's body (`renderTab`), drawn flush to the pane's edges and the unbordered strip's bottom edge with the insets it chooses, and optionally what its chip or panel header shows as a title (`renderTabTitle`, falling back to the record's `title`); the embedder dispatches on `tab.kind` |
 | `DockIntents` | the settled results of every gesture |
 
-`DockController` satisfies `DockIntents` as written, so an embedding can pass it to `DockLayout` for retained Sidebar layouts or `DockSurface` for recursive split trees. An embedder that routes through its own store implements the same method names instead. Three props carry control policy rather than gestures: `canSplit` (surface-wide, the pane budget; disables the split control with `splitPaneDisabled`), `canAddTab(paneId)` (per pane, omits the add control; leave it out to draw one in every pane), and `canCloseTab(tabId)` (per tab, withholds the chip's close control and the menu's close item together; leave it out to keep every tab closable). Hiding the add control moves nothing else in the strip, and a withheld close moves nothing in the chip — the close control paints over the title's end rather than beside it. A pane's lone chip whose close is withheld draws quiet — no capsule, no hover fill — since there is nothing to select against and nothing to do to it. The kit adds one policy of its own, the room rule below, which disables a pane's split control with `splitPaneNarrow`; `onRoom(fits)` reports its readings so an embedder splitting programmatically can honour the same rule.
+`DockController` satisfies `DockIntents` as written, so an embedding can pass it to `DockLayout` for retained Sidebar layouts or `DockSurface` for recursive split trees. An embedder that routes through its own store implements the same method names instead. Three props carry control policy rather than gestures: `canSplit` (surface-wide, the pane budget; disables the split control with `splitPaneDisabled`), `canAddTab(paneId)` (per pane, omits the add control; leave it out to draw one in every pane), and `canCloseTab(tabId)` (per tab, withholds the chip's close control and the menu's close item and prevents middle-click closing; leave it out to keep every tab closable). Hiding the add control moves nothing else in the strip, and a withheld close moves nothing in the chip — the close control paints over the title's end rather than beside it. A pane's lone chip whose close is withheld draws quiet — no capsule, no hover fill — since there is nothing to select against and nothing to do to it. The kit adds one policy of its own, the room rule below, which disables a pane's split control with `splitPaneNarrow`; `onRoom(fits)` reports its readings so an embedder splitting programmatically can honour the same rule. A visible blocked split control supports click or tap to read its explanation without splitting or focusing the pane.
 
 `dropZones="horizontal"` offers two half-pane hints; once budget or width forbids another split, the whole body accepts a move. A hint is a dashed card inset 8px inside its region, showing the zone's glyph and `labels.dropZone[zone]`; the preview layer covers all tab-body content, while the card under the pointer takes the accent and its neighbour stays a quiet outline. `minPaneFraction` sets the preview minimum, and `planResizeSplit` accepts the same minimum for the committed operation. The Sidebar uses 0.2 and enforces two panes in its own store. The generic engine retains its tree and other split directions. `hideSplitWhenBlocked` hides a blocked split control — pane budget spent or pane too narrow — instead of rendering it disabled; its default is false.
 
+The split control wrapper exposes `data-dockkit-split-control` for embedder styling, independently of its element tag.
+
 A tab's `kind` is an opaque string. Seeded tabs are factories (`DockControllerOptions`), so what a fresh pane contains is the embedder's decision, not this package's. Content identity is the pair (`kind`, `contentId`): `findContentTab(state, contentId, kind?)` finds the tab showing it anywhere and `findPaneContentTab(state, paneId, contentId, kind?)` within one pane, and `planOpenContent` focuses that tab instead of opening another unless told `revealIfOpened: false`; an explicit `index` seats a new tab at a strip slot rather than at the end.
 
 `DockLayout`, used by the Sidebar, keeps each tab in a stable DOM cell across selection, pane moves and floating. It accepts one docked pane or two horizontal panes; CSS Grid resolves their widths. `keepMounted(tab)` retains visited bodies and `active` controls Session visibility without reparenting content.
 
-`DockSurface` is the docked area for the separate recursive renderer. Chrome around it — a rail, a collapsed presentation, any history controls — belongs to the embedder, which reads `state.expanded` and decides; the kit ships no undo/redo control of its own. Surface-wide controls the embedder does want on the surface go through the `chrome` prop, which the kit places at the far end of the top-right pane's tab strip (the last child of every row split, the first of every column split), so a surface needs no header row of its own. `FloatLayer` owns its own gestures and positions panels in viewport coordinates, so it may be mounted anywhere, including a portal. Both float renderers keep the header at least 20px below the Windows caption (20px below the viewport top in native fullscreen), including newly opened and restored panels. Dragging and resizing start at the displayed position.
+`DockSurface` is the docked area for the separate recursive renderer. Chrome around it — a rail, a collapsed presentation, any history controls — belongs to the embedder, which reads `state.expanded` and decides; the kit ships no undo/redo control of its own. Surface-wide controls the embedder does want on the surface go through the `chrome` prop, which the kit places at the far end of the top-right pane's tab strip (the last child of every row split, the first of every column split), so a surface needs no header row of its own. `FloatLayer` owns its own gestures and positions panels in viewport coordinates, so it may be mounted anywhere, including a portal. At rest both float renderers keep the header at least 20px below the Windows caption (20px below the viewport top in native fullscreen), including newly opened and restored panels. Dragging and resizing start at the displayed position.
+
+Floating panels stay inside the viewport. Each draws at its stored rectangle projected into the viewport, so a shrinking window pushes it in without recording an operation and a growing window returns it toward the stored position; a panel larger than the viewport draws at the viewport's size. A move follows the pointer one to one inside the viewport and resists past any edge, the top included, drawing at most 120px beyond it; its release records one `moveFloat` with the nearest legal rectangle, or only a raise when that is the legal rectangle of the press, then springs the panel there from where it was drawn, carrying the drawn velocity, staying within those 120px, and overshooting slightly inward. A press on the header or the resize corner during that return picks the panel up where it is drawn; a resize from there keeps its origin and springs it inside on release. A resize keeps the corner inside the viewport. At rest the stylesheet clamps every panel's position and size into the viewport once more, so a stale viewport reading still leaves it inside. Under `prefers-reduced-motion: reduce` a move clamps at the edge and nothing animates.
 
 <a id="interaction-rules-worth-keeping"></a>
 ## Interaction rules worth keeping
@@ -70,7 +78,7 @@ The split control accepts localized tooltip text, separate effective keys throug
 These are not stylistic; each one fixes a defect found in a real browser.
 
 - **Capture the pointer** when a gesture starts. Without it any scroll container the pointer crosses can claim the gesture, which the browser reports as a cancelled pointer and an abandoned drag. Capture is hardening — the window listeners carry the gesture either way, so an environment without the API still works.
-- **The chips give way; the strip's end controls never do.** The chip box is the strip's one shrinking part (`flex: 0 1 auto; min-width: 0; overflow-x: auto`): chips shrink down to an 80px floor and then scroll on the wheel with no scrollbar drawn, and the box fades its chips out over 24px at each side that hides some (`data-dockkit-strip-scroll`, written from the box's scroll reading after each commit, scroll, and resize). Whenever the active tab or the row of chips changes, the box scrolls so the active chip stands clear of the fade band; a chip already in view moves nothing. A chip's title is never ellipsized: `TabTitle` reads its text against its box and sets `data-dockkit-tab-clipped` while the text is wider, which fades the text out over its last 16px. A chip's close control shows while the chip is active, hovered, or holds focus, over the title's last 14px, which fade under it, so the chip is the same width either way. The two slots beside the active chip draw no hairline, so the filled capsule stands between bare chips. The add, split, and chrome controls are `flex: none`, so they keep their width and place in any pane at least as wide as they are (about 130px with the chrome, 72px without). The surface's `min-width: 0` and the pane's `overflow: hidden` stop a body's longest unwrapped line from widening the pane past its box, which is what carried the controls and the body's scrollbar off-screen.
+- **The chips give way; the strip's end controls never do.** The chip box is the strip's one shrinking part (`flex: 0 1 auto; min-width: 0; overflow-x: auto`): chips shrink down to an 80px floor and then scroll on the wheel with no scrollbar drawn, and the box fades its chips out over 24px at each side that hides some (`data-dockkit-strip-scroll`, written from the box's scroll reading after each commit, scroll, and resize). Whenever the active tab or the row of chips changes, the box scrolls so the active chip stands clear of the fade band; a chip already in view moves nothing. Where `DockLayout` draws a new strip for each newly selected tab, that strip first jumps to the offset the pane's previous strip recorded, so only the remaining distance animates; a strip with no recorded offset jumps straight to the active chip instead of scrolling from the row's start. A chip's title is never ellipsized: `TabTitle` reads its text against its box and sets `data-dockkit-tab-clipped` while the text is wider, which fades the text out over its last 16px. A chip's close control shows while the chip is active, hovered, or holds focus, over the title's last 14px, which fade under it, so the chip is the same width either way. The two slots beside the active chip draw no hairline, so the filled capsule stands between bare chips. The add, split, and chrome controls are `flex: none`, so they keep their width and place in any pane at least as wide as they are (about 130px with the chrome, 72px without). The surface's `min-width: 0` and the pane's `overflow: hidden` stop a body's longest unwrapped line from widening the pane past its box, which is what carried the controls and the body's scrollbar off-screen.
 - **The chip box scrolls, but never claims a gesture.** A horizontal scroller would take press-and-move for itself and cancel the pointer; the box, the chips, and the strip set `touch-action: none` and the gesture captures the pointer, so a press-and-move on a chip is a drag and only the wheel scrolls the box.
 - **A split needs room for two working halves.** A pane splits into equal halves, so each half must hold what cannot shrink: the strip's fixed part — measured as the strip's width minus the chip box and the fill, which is the padding, the gaps, and every control that pane draws (its own chrome included, so the top-right pane asks more) — plus one chip at its minimum — `.tab` declares `min-width: 80px` on a content-box, so its footprint is 80px plus 10px + 10px of padding, 100px, read from a rendered chip's computed style (the stylesheet figure when none can be read); the divider between the halves takes its rendered thickness (0 — its hairline paints over the seam without taking layout room, so a body's own rules run unbroken past it). A column split, which only an edge drop makes, needs each half to hold the strip (34px) plus a 48px body: one 13px secondary line at 1.6 line-height inside 12px of the body's own insets — the pane body itself is unpadded, so a tab's body reaches the strip's bottom edge and the pane's edges and draws its own. `halvesFit` in `geometry.ts` is the arithmetic; `measure.ts` reads the rectangles after every commit and whenever the surface resizes, because the layout state carries fractions, never pixels, and the engine's planners stay that way. A pane without room keeps its split control, disabled with `splitPaneNarrow` (hidden instead under `hideSplitWhenBlocked`), and offers no edge drop zone for that axis (the release is then not a move). Under `hideSplitWhenBlocked` the split control's own footprint — its box plus the strip's gap — is left out of the fixed part: hiding the control sheds exactly that footprint from the strip, so a reading that counted it would flip with the control's visibility and re-render forever; leaving it out is also what the half being asked about would carry, since a half too narrow to split hides its own control. A pane the user narrows afterwards — a divider or the embedder's column dragged — keeps its size: the rule only decides its next split.
 - **Focus lands on click, not on press.** A state change between `pointerdown` and the first `pointermove` rebuilds the pressed subtree, and a replaced element cancels the pointer. It also keeps a drag from recording a redundant focus operation first. Clicks on the chips, the strip's controls, and the embedder's chrome stop at the strip: the intent each reports already decides the active pane, or is the embedder's own, so the pane's click-to-focus records nothing extra. A floating panel's grip and corner report through their gesture the same way — a press released in place is a click that raises the panel, and a drag records only the move or resize, whose operation raises it — while a press on the panel's body raises it directly. A click on the pane that is active already, a click or key on that pane's selected chip, or a press on the panel that is active and on top already, changes nothing and records nothing.

package/README.zh.md

@@ -37,7 +37,11 @@ kind: "package-reference"
 - `planSettle` 是可选加入的规则，保证意图之后每个停靠格都有内容：被意图清空的格会被并掉，被清空的根格通过嵌入方的工厂重新播种——不传工厂则只并格、让根格保持为空。想要空格的嵌入方只需不调用它，或不带工厂调用。`planDropTab` 接受同一工厂：带工厂时，唯一 tab 放到本格边缘会分栏，工厂的 tab 回填它腾出的格（被拖的 tab 保持聚焦）；不带工厂时这种释放不改变任何东西。
 - `DockController` 是意图层，也是一个可观察源（`subscribe` + `getSnapshot`，其引用只在布局变化时才变）。
 
-**组件**渲染布局快照并上报已落定的意图——每次手势一条，绝不上报拖动帧。拖动过程中在本地状态里预览，手势自身的事实留在它的闭包里；松手时净结果通过一次 `DockIntents` 调用离开——在标签条上松手上报的是按绘制顺序数出的插入槽位（被拖的 chip 也计入），由 `planPlaceTab` 换算成重排或移动。正是这一点让嵌入方能为每次手势记录恰好一条历史。标签条遵循 WAI-ARIA tabs 模式的手动激活：选中的 chip 在 Tab 键序里；左右方向键（循环）、Home、End 只在 chip 之间移动焦点而不选中；Enter 或空格选中当前聚焦的 chip，走与点击相同的意图。chip 是一个胶囊，携带唯一的控件——它的关闭按钮；上下文菜单（在 chip 上的次键按下）携带同样的关闭项加上嵌入方的条目——一个连一项都没有的菜单绝不展示——并渲染在按 chip 定位的 portal 里，因为 chip 盒会故意裁掉溢出（见下文）。chip 之后是添加控件，它请嵌入方（`DockIntents.addTab`）安放其种子 tab；嵌入方的 `canAddTab(paneId)` 按格决定是否绘制该控件。复制 tab 没有套件控件——那是嵌入方的 API——而浮出就是把拖动松手在停靠区之外。
+**组件**渲染布局快照并上报已落定的意图——每次手势一条，绝不上报拖动帧。拖动过程中在本地状态里预览，手势自身的事实留在它的闭包里；松手时净结果通过一次 `DockIntents` 调用离开——在标签条上松手时，仅当定位条可见才上报插入槽位（被拖的 chip 也计入），由 `planPlaceTab` 换算成重排或移动。正是这一点让嵌入方能为每次手势记录恰好一条历史。标签条遵循 WAI-ARIA tabs 模式的手动激活：选中的 chip 在 Tab 键序里；左右方向键（循环）、Home、End 只在 chip 之间移动焦点而不选中；Enter 或空格选中当前聚焦的 chip，走与点击相同的意图。chip 是一个胶囊，携带唯一的控件——它的关闭按钮；上下文菜单（在 chip 上的次键按下）携带同样的关闭项加上嵌入方的条目——一个连一项都没有的菜单绝不展示——并渲染在按 chip 定位的 portal 里，因为 chip 盒会故意裁掉溢出（见下文）。chip 之后是添加控件，它请嵌入方（`DockIntents.addTab`）安放其种子 tab；嵌入方的 `canAddTab(paneId)` 按格决定是否绘制该控件。复制 tab 没有套件控件——那是嵌入方的 API——而浮出就是把拖动松手在停靠区之外。
+
+中键点击可关闭标签页 chip 的任意位置（包括关闭控件）时，通过与关闭按钮相同的意图关闭，无需先选中。chip 接管中键点击，并阻止嵌套标题内容的默认动作。关闭后台标签页会保留当前选中的标签页。只有主键会开始拖动标签页；其它鼠标按键仍按住时，中键点击不会关闭标签页。
+
+不改变所拖标签位置的标签条落点不显示插入定位条，也不上报放置操作；标签仍可拖出分栏或浮动。
 
 标签上下文菜单只显示关闭操作名，不显示快捷键：菜单操作针对被点击的标签，快捷键则可能作用于其他焦点分栏。无修饰键的 Esc 关闭前台标签菜单而不关闭标签，并将菜单项的焦点交还标签，不绘制焦点外轮廓线。Tab 和方向键导航保留标签页的可见焦点提示。输入法组合输入和长按重复事件不关闭菜单。
 
@@ -52,15 +56,19 @@ kind: "package-reference"
 | `TabRenderer` | 一个 tab 的正文（`renderTab`），贴着格的边缘和（不带边线的）tab 条底边绘制、自己决定留白，以及可选的 chip 或浮窗头部显示的标题（`renderTabTitle`，回退到记录的 `title`）；嵌入方按 `tab.kind` 分发 |
 | `DockIntents` | 每次手势落定的结果 |
 
-`DockController` 原样满足 `DockIntents`，因此嵌入方可将它交给 `DockLayout` 来保活 Sidebar 布局，或交给 `DockSurface` 来渲染递归分割树。经由自己 store 路由的嵌入方则实现同名方法。有三个 props 承载的是控制策略而非手势：`canSplit`（整面有效，即格预算；用 `splitPaneDisabled` 禁用分栏控件）、`canAddTab(paneId)`（按格，省略添加控件；不传则每格都画）与 `canCloseTab(tabId)`（按 tab，把 chip 的关闭控件和菜单的关闭项一并收起；不传则每个 tab 都可关闭）。隐藏添加控件不会移动 tab 条里的其它任何东西，收起关闭也不会移动 chip 里的任何东西——关闭控件压在标题末端之上而非并排。某格仅剩的一个 chip 在关闭被收起时画成安静样式——没有胶囊底色，没有悬停填充——因为既没有别的 tab 可供选择，也没有任何可对它做的事。套件自己再加一条策略，即下文的空间规则，它用 `splitPaneNarrow` 禁用某格的分栏控件；`onRoom(fits)` 上报其读数，让以编程方式分栏的嵌入方能遵守同一规则。
+`DockController` 原样满足 `DockIntents`，因此嵌入方可将它交给 `DockLayout` 来保活 Sidebar 布局，或交给 `DockSurface` 来渲染递归分割树。经由自己 store 路由的嵌入方则实现同名方法。有三个 props 承载的是控制策略而非手势：`canSplit`（整面有效，即格预算；用 `splitPaneDisabled` 禁用分栏控件）、`canAddTab(paneId)`（按格，省略添加控件；不传则每格都画）与 `canCloseTab(tabId)`（按 tab，把 chip 的关闭控件和菜单的关闭项一并收起，并禁止中键关闭；不传则每个 tab 都可关闭）。隐藏添加控件不会移动 tab 条里的其它任何东西，收起关闭也不会移动 chip 里的任何东西——关闭控件压在标题末端之上而非并排。某格仅剩的一个 chip 在关闭被收起时画成安静样式——没有胶囊底色，没有悬停填充——因为既没有别的 tab 可供选择，也没有任何可对它做的事。套件自己再加一条策略，即下文的空间规则，它用 `splitPaneNarrow` 禁用某格的分栏控件；`onRoom(fits)` 上报其读数，让以编程方式分栏的嵌入方能遵守同一规则。可见的禁用分栏控件支持鼠标或触摸点击查看原因，不会分栏或聚焦窗格。
 
 `dropZones="horizontal"` 提供左右两个半区提示；预算或宽度不允许再拆时，正文整格接收移动。提示是一张内缩 8px 的虚线卡片，显示该落区的图形和 `labels.dropZone[zone]`；预览层覆盖全部 tab 正文，指针所在的卡片取强调色，另一张保持安静的轮廓。`minPaneFraction` 控制预览的最小比例，`planResizeSplit` 接受相同最小值以约束提交；Sidebar使用0.2并在自己的store限制两格。通用引擎仍保留原有树与其它分割方向。 `hideSplitWhenBlocked` 在分栏被阻止时（窗格预算已满或格太窄）直接隐藏分栏控件而不是渲染禁用态，默认值为 false。
 
+分栏控件的包裹元素通过 `data-dockkit-split-control` 提供宿主样式入口，不依赖具体元素标签。
+
 tab 的 `kind` 是不透明字符串。种子 tab 是工厂（`DockControllerOptions`），因此新格里放什么由嵌入方决定，与本包无关。内容身份是二元组（`kind`、`contentId`）：`findContentTab(state, contentId, kind?)` 在任意位置找到展示它的 tab，`findPaneContentTab(state, paneId, contentId, kind?)` 在一个格内找；`planOpenContent` 会聚焦该 tab 而非再开一个，除非被告知 `revealIfOpened: false`；显式的 `index` 把新 tab 放到 tab 条的某个位置而非末尾。
 
 Sidebar 使用的 `DockLayout` 在选中项变化、跨格移动与浮动期间，把每个 tab 保留在稳定的 DOM 容器中。它接受一个停靠格或左右两个格，由 CSS Grid 计算宽度。`keepMounted(tab)` 保留已访问正文，`active` 控制 Session 可见性，不改变内容的父子关系。
 
-`DockSurface` 是独立递归渲染器的停靠区。它周围的 chrome——轨道、折叠形态、任何历史控件——属于嵌入方，由嵌入方读取 `state.expanded` 后自行决定；套件不自带撤销/重做控件。嵌入方确实想放到面上的整面控件通过 `chrome` prop 传入，套件把它放在右上格 tab 条的最末端（每个横向分裂的最后一个子节点、每个纵向分裂的第一个子节点），因此停靠面不需要自己的标题行。`FloatLayer` 拥有自己的手势并以视口坐标定位浮窗，因此可以挂在任何位置，包括 portal 里。 两种浮窗渲染器都让标题栏与 Windows 顶栏至少间隔 20px（原生全屏时距视口顶部 20px），新建和恢复的浮窗均适用。拖动和调整大小从实际显示位置开始。
+`DockSurface` 是独立递归渲染器的停靠区。它周围的 chrome——轨道、折叠形态、任何历史控件——属于嵌入方，由嵌入方读取 `state.expanded` 后自行决定；套件不自带撤销/重做控件。嵌入方确实想放到面上的整面控件通过 `chrome` prop 传入，套件把它放在右上格 tab 条的最末端（每个横向分裂的最后一个子节点、每个纵向分裂的第一个子节点），因此停靠面不需要自己的标题行。`FloatLayer` 拥有自己的手势并以视口坐标定位浮窗，因此可以挂在任何位置，包括 portal 里。 静止时两种浮窗渲染器都让标题栏与 Windows 顶栏至少间隔 20px（原生全屏时距视口顶部 20px），新建和恢复的浮窗均适用。拖动和调整大小从实际显示位置开始。
+
+浮窗始终留在视口内。每个浮窗绘制在其存储矩形投影到视口后的位置，因此窗口缩小时浮窗被推入且不记录操作，窗口变大时浮窗朝存储位置回移；大于视口的浮窗按视口尺寸绘制。移动时浮窗在视口内一比一跟随指针，越过任一边界（包括顶部）后受到阻力，最多越过边界 120px；松手时记录一次带最近合法矩形的 `moveFloat`，若该矩形就是按下时的合法矩形则只提升浮窗，再让浮窗从绘制位置以弹簧回到该矩形，携带绘制速度、不超出这 120px，并略微向内过冲。回弹过程中按下标题栏或缩放角都会从绘制位置接住浮窗；从那里缩放时保留原点，松手后再以弹簧收回视口。调整大小时右下角保持在视口内。静止时样式表会再次把每个浮窗的位置和尺寸钳制在视口内，因此即使视口读数过期，浮窗仍在视口内。在 `prefers-reduced-motion: reduce` 下，移动在边界处钳制且不播放动画。
 
 <a id="interaction-rules-worth-keeping"></a>
 ## 值得保留的交互规则
@@ -70,7 +78,7 @@ Sidebar 使用的 `DockLayout` 在选中项变化、跨格移动与浮动期间
 这些不是风格偏好；每一条都修复了在真实浏览器里发现的缺陷。
 
 - **手势开始时捕获指针。** 不捕获的话，指针经过的任何滚动容器都可能接管手势，浏览器会将其报告为指针取消和拖动中止。捕获是加固——无论如何都由 window 监听器承载手势，所以没有该 API 的环境照样可用。
-- **chip 让位；tab 条末端的控件永不让位。** chip 盒是 tab 条里唯一会收缩的部分（`flex: 0 1 auto; min-width: 0; overflow-x: auto`）：chip 先缩到 80px 下限，再在盒内随滚轮横向滚动、不画滚动条，且盒在每个藏有 chip 的一侧把 chip 在 24px 内渐隐（`data-dockkit-strip-scroll`，在每次提交、滚动与尺寸变化后由盒的滚动读数写入）。每当活动 tab 或 chip 的排列变化，盒会滚动到让活动 chip 避开渐隐带；已在视野内的 chip 不动。chip 的标题从不加省略号：`TabTitle` 拿文字宽度对照它的盒子，文字更宽时置 `data-dockkit-tab-clipped`，让文字在末端 16px 内渐隐。chip 的关闭控件在 chip 活动、悬停或持有焦点时显示，压在标题末端 14px 之上、标题在其下渐隐，因此 chip 宽度两种情况下都一样。活动 chip 两侧的槽不画细线，让填色胶囊立在裸 chip 之间。添加、分栏与 chrome 控件都是 `flex: none`，因此在任何不窄于它们自身的格里（带 chrome 约 130px，不带约 72px）都保持宽度与位置。停靠面的 `min-width: 0` 与格的 `overflow: hidden` 阻止正文里最长的不换行行把格撑出自己的盒子——正是那种情况把控件和正文滚动条推到了屏幕外。
+- **chip 让位；tab 条末端的控件永不让位。** chip 盒是 tab 条里唯一会收缩的部分（`flex: 0 1 auto; min-width: 0; overflow-x: auto`）：chip 先缩到 80px 下限，再在盒内随滚轮横向滚动、不画滚动条，且盒在每个藏有 chip 的一侧把 chip 在 24px 内渐隐（`data-dockkit-strip-scroll`，在每次提交、滚动与尺寸变化后由盒的滚动读数写入）。每当活动 tab 或 chip 的排列变化，盒会滚动到让活动 chip 避开渐隐带；已在视野内的 chip 不动。`DockLayout` 为每个新选中的 tab 画出新 tab 条时，新 tab 条先跳到该格上一条 tab 条记录的偏移，只让剩余距离带动画；没有记录偏移的 tab 条直接跳到活动 chip，而不是从排列起点滚动过去。chip 的标题从不加省略号：`TabTitle` 拿文字宽度对照它的盒子，文字更宽时置 `data-dockkit-tab-clipped`，让文字在末端 16px 内渐隐。chip 的关闭控件在 chip 活动、悬停或持有焦点时显示，压在标题末端 14px 之上、标题在其下渐隐，因此 chip 宽度两种情况下都一样。活动 chip 两侧的槽不画细线，让填色胶囊立在裸 chip 之间。添加、分栏与 chrome 控件都是 `flex: none`，因此在任何不窄于它们自身的格里（带 chrome 约 130px，不带约 72px）都保持宽度与位置。停靠面的 `min-width: 0` 与格的 `overflow: hidden` 阻止正文里最长的不换行行把格撑出自己的盒子——正是那种情况把控件和正文滚动条推到了屏幕外。
 - **chip 盒会滚动，但绝不认领手势。** 横向滚动容器会把按下并移动的手势据为己有并取消指针；盒、chip 与 tab 条都设 `touch-action: none`，手势又捕获了指针，所以在 chip 上按下并移动是拖动，只有滚轮滚动盒子。
 - **分栏需要给两个可用的半格留出空间。** 格被等分成两半，因此每一半都必须容得下不可收缩的部分：tab 条的固定部分——按 tab 条宽减去 chip 盒与填充条测得，即内边距、间隙以及该格绘制的每个控件（含它自己的 chrome，所以右上格要求更多）——加上一枚最小尺寸的 chip——`.tab` 在 content-box 上声明 `min-width: 80px`，所以它的足印是 80px 加 10px + 10px 内边距，即 100px，从已渲染 chip 的计算样式读取（读不到时用样式表数值）；两半之间的分隔条取其渲染厚度（0——它的细线画在接缝上、不占布局空间，因此正文自己画的分隔线能不断线地穿过接缝）。纵向分栏只由边缘落下产生，它要求每一半容得下 tab 条（34px）加 48px 正文：正文自留的 12px 内边距内一行 13px、行高 1.6 的次级文字——格的正文容器本身没有内边距，tab 的正文直接贴到 tab 条底边和格的边缘，由自己留白。`geometry.ts` 里的 `halvesFit` 是算术；`measure.ts` 在每次提交后与停靠面尺寸变化时读取矩形，因为布局状态只携带比例、从不携带像素，引擎的 planner 也保持如此。没有空间的格保留分栏控件，以 `splitPaneNarrow` 禁用（开启 `hideSplitWhenBlocked` 时改为隐藏），并且在该轴上不提供边缘落区（松手就不是移动）。开启 `hideSplitWhenBlocked` 时，分栏控件自己的占位——它的盒子加 tab 条的间隙——不计入固定部分：隐藏控件让 tab 条卸下的恰是这份占位，把它算进去的读数会随控件的可见性来回翻转、无限重渲染；不计入也正是被询问的那一半会承载的量，因为窄到无法分栏的一半会隐藏自己的控件。用户随后拖窄的格——通过拖动分隔条或嵌入方的列——会保持原尺寸：规则只决定它的下一次分栏。
 - **焦点落在 click 而不是按下。** 在 `pointerdown` 与第一次 `pointermove` 之间的状态变化会重建被按下的子树，而被替换的元素会取消指针。这也避免拖动先记录一条多余的焦点操作。chip、标签条各控件以及嵌入方 chrome 上的 click 都止于标签条：它们各自上报的意图已决定了活动格，或本就是嵌入方自己的事，所以格自身的点击聚焦不再多记一条。浮动面板的抓手与角柄同样通过手势上报——原地松开的按下是一次 click，抬起面板；真正的拖动只记录移动或缩放，由该操作自己抬起面板——而按在面板主体上则直接抬起它。点击本已活动的格、点击或按键选中该格本已选中的 chip，或按下本已活动且在最上层的面板，什么都不改变，也什么都不记录。

package/lib/components/dockkit.module.css

@@ -107,8 +107,10 @@
   transition: opacity 120ms ease-out;
 }
 
-.divider:hover::after {
-  opacity: 1;
+@media (hover: hover) {
+  .divider:hover::after {
+    opacity: 1;
+  }
 }
 
 .splitRow > .divider::after {
@@ -261,7 +263,8 @@
   min-width: 0;
   overflow-x: auto;
   overflow-y: hidden;
-  /* The scroll to a newly active chip glides rather than jumps. */
+  /* The scroll to a newly active chip glides; `jumpTo` in TabPanel.tsx
+     overrides this for the placements that must not animate. */
   scroll-behavior: smooth;
   scrollbar-width: none;
   touch-action: none;
@@ -406,12 +409,17 @@
    Later than the clipped mask, so a clipped chip showing its close fades
    under the close. A floating panel's header chip has no close, so it keeps
    the clipped mask alone. */
-.tab:not(.floatTitle):hover .tabTitle,
 .tab:not(.floatTitle):focus-within .tabTitle,
 .tabActive .tabTitle {
   mask-image: linear-gradient(to right, black calc(100% - 30px), transparent calc(100% - 14px));
 }
 
+@media (hover: hover) {
+  .tab:not(.floatTitle):hover .tabTitle {
+    mask-image: linear-gradient(to right, black calc(100% - 30px), transparent calc(100% - 14px));
+  }
+}
+
 /* A 20px icon button inset 4px from the chip's end, holding a 14px glyph in
    the tertiary ink, so it sits back from the title beside it. */
 .tabClose {
@@ -438,13 +446,19 @@
 
 /* Shown while the chip is hovered or holds focus, and always on the active
    chip: the tab in view is the one a reader closes next. */
-.tab:hover .tabClose,
 .tab:focus-within .tabClose,
 .tabActive .tabClose {
   opacity: 1;
   pointer-events: auto;
 }
 
+@media (hover: hover) {
+  .tab:hover .tabClose {
+    opacity: 1;
+    pointer-events: auto;
+  }
+}
+
 /* The chip's height and corner, so it reads as one more tab in the row. */
 .addTab {
   display: flex;
@@ -462,18 +476,20 @@
   cursor: pointer;
 }
 
-.addTab:hover {
-  color: var(--dsw-alias-label-primary);
-  background: var(--dsw-alias-interactive-bg-hover);
-}
+@media (hover: hover) {
+  .addTab:hover {
+    color: var(--dsw-alias-label-primary);
+    background: var(--dsw-alias-interactive-bg-hover);
+  }
 
-.tabClose:hover {
-  color: var(--dsw-alias-label-primary);
-  background: var(--dsw-alias-interactive-bg-hover);
-}
+  .tabClose:hover {
+    color: var(--dsw-alias-label-primary);
+    background: var(--dsw-alias-interactive-bg-hover);
+  }
 
-.tab:hover {
-  background: var(--dsw-alias-interactive-bg-hover);
+  .tab:hover {
+    background: var(--dsw-alias-interactive-bg-hover);
+  }
 }
 
 /* The active chip is the filled tab, in the tag fill; the rest are bare text. */
@@ -485,19 +501,31 @@
 /* A pane's lone unclosable chip is a label, not a choice: no tab, no
    hover fill — the primary ink on the pane's own ground. Its title never
    yields to a close control, so it keeps the clipped fade alone. */
-.tab.tabQuiet,
-.tab.tabQuiet:hover {
+.tab.tabQuiet {
   color: var(--dsw-alias-label-primary);
   background: transparent;
   cursor: default;
 }
 
+@media (hover: hover) {
+  .tab.tabQuiet:hover {
+    color: var(--dsw-alias-label-primary);
+    background: transparent;
+    cursor: default;
+  }
+}
+
 .tab.tabQuiet .tabTitle,
-.tab.tabQuiet:hover .tabTitle,
 .tab.tabQuiet:focus-within .tabTitle {
   mask-image: none;
 }
 
+@media (hover: hover) {
+  .tab.tabQuiet:hover .tabTitle {
+    mask-image: none;
+  }
+}
+
 .tab.tabQuiet .tabTitle[data-dockkit-tab-clipped] {
   mask-image: linear-gradient(to right, black calc(100% - 16px), transparent);
 }
@@ -529,8 +557,10 @@
   height: 15px;
 }
 
-.iconButton:hover:not(:disabled) {
-  background: var(--dsw-alias-interactive-bg-hover);
+@media (hover: hover) {
+  .iconButton:hover:not(:disabled) {
+    background: var(--dsw-alias-interactive-bg-hover);
+  }
 }
 
 .iconButton:disabled {
@@ -538,6 +568,10 @@
   cursor: default;
 }
 
+.iconButton[data-dockkit-split-blocked] {
+  pointer-events: none;
+}
+
 /*
  * Portalled beside the app root, so its stacking level is stated here: above the
  * floating panels (which the embedder draws at 60), because a menu opened from
@@ -569,8 +603,10 @@
   cursor: pointer;
 }
 
-.menuItem:hover {
-  background: var(--dsw-alias-interactive-bg-hover);
+@media (hover: hover) {
+  .menuItem:hover {
+    background: var(--dsw-alias-interactive-bg-hover);
+  }
 }
 
 /* No padding of its own: a tab's body reaches the pane's edges and the strip's
@@ -749,6 +785,15 @@
 
 .float {
   position: fixed;
+  /* A resting panel publishes its rectangle in these variables (`floatStyle`).
+     The clamp keeps its position and size inside the viewport and below the
+     caption floor even when the gesture hook read a stale viewport; `dvh`
+     follows `window.innerHeight` as the hook does. A gesture or return writes
+     left, top and the size inline instead. */
+  left: max(0px, min(var(--dsh-dockkit-float-x), 100vw - var(--dsh-dockkit-float-width)));
+  top: max(var(--dsh-dockkit-float-top, 0px), min(var(--dsh-dockkit-float-y), 100dvh - var(--dsh-dockkit-float-height)));
+  width: min(var(--dsh-dockkit-float-width), 100vw);
+  height: min(var(--dsh-dockkit-float-height), 100dvh - var(--dsh-dockkit-float-top, 0px));
   display: flex;
   flex-direction: column;
   /* The body inside is unpadded and reaches the edges, so the frame clips it
@@ -782,8 +827,10 @@
   cursor: inherit;
 }
 
-.tab.floatTitle:hover {
-  background: transparent;
+@media (hover: hover) {
+  .tab.floatTitle:hover {
+    background: transparent;
+  }
 }
 
 /* Mirrored so the filled pane sits at the right, where the docked surface is. */
@@ -828,11 +875,16 @@
   transition: opacity 120ms ease-out;
 }
 
-.float:hover .floatResize::after,
 .floatResize:active::after {
   opacity: 1;
 }
 
-.floatResize:hover::after {
-  border-color: var(--dsw-alias-label-tertiary);
+@media (hover: hover) {
+  .float:hover .floatResize::after {
+    opacity: 1;
+  }
+
+  .floatResize:hover::after {
+    border-color: var(--dsw-alias-label-tertiary);
+  }
 }