Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

feat(web): a floating launcher for the hidden right dock (#586)

Yaowei Zhenga9e65eb1bbfb
diff --git a/changelog/unreleased/2026-09-02-dock-floating-launcher.md b/changelog/unreleased/2026-09-02-dock-floating-launcher.md
new file mode 100644
index 00000000..662d30bc
--- /dev/null
+++ b/changelog/unreleased/2026-09-02-dock-floating-launcher.md
@@ -0,0 +1,67 @@
+# A floating shortcuts launcher
+
+- **Date:** 2026-09-02
+- **Type:** feature
+- **Scope:** `web`, `docs`
+- **PR:** [#586](https://github.com/Prism-Shadow/penguin-harness/pull/586)
+
+[中文版](2026-09-02-dock-floating-launcher.zh.md)
+
+The chat page gained an AssistiveTouch-style floating launcher for the workbench: while no dock
+surface is up, a translucent round button floats just inside the right edge of the conversation
+body under a short "Shortcuts" caption, and a click fans its entries out on a tight
+semicircular ring around it — one per dock panel plus a terminal, glyphs alone, their names read
+out by that same caption — and picking one opens that panel, at which point the launcher goes
+away. The workbench's panels had been reachable only through the toolbar's toggle, which a user
+could fail to notice altogether — on a phone most of all. The arc's last entry puts the launcher
+away for good, and an Appearance setting brings it back.
+
+## Details
+
+- Shows while the room it stands in for is free: on a desktop-width window that is the right dock
+ being hidden; below the breakpoint, where the two docks render as one merged bottom surface, it
+ is neither dock being open. Narrow layouts used to have no launcher at all.
+- Resting: a 44px translucent circle with backdrop blur and a soft shadow, quiet until hovered or
+ focused (a visible focus ring for keyboard users), showing a workbench glyph — a dashboard of
+ four tiles — with its name printed under it on the same glass: a bare glyph does not say what it
+ opens, and the ball's accessible name is that same word. It rests 32px in from the body's right
+ edge, far enough to read as floating rather than pinned and far enough that the caption stays
+ centred under it, the longest name it shows included. Neither the ball nor an entry carries a
+ tooltip: every name is already on screen. It sits inside the chat body — between the toolbar and
+ the composer — so neither it nor its caption ever covers either.
+- Click, Enter or Space fans out round entries: every kind in `PANEL_KINDS` through the shared
+ panel meta (a kind added later appears by itself), plus the terminal, which adopts a live shell
+ no conversation holds or starts one, exactly like the dock picker, and a last "hide launcher"
+ entry in the muted ink, so it reads as a lesser thing than the panels above it. A panel entry
+ names the right dock on a wide window and names none on a narrow one, where the store lands the
+ tab exactly where the toolbar's own panel buttons land it. They fall on a semicircular ring
+ centred on the ball and opening leftward — from straight above it, through straight left, to
+ straight below — spread evenly and in top-to-bottom order. The entries are glyphs alone, and
+ pointing at one or focusing it prints its name in the ball's caption: one name on screen instead
+ of seven pills floating around the ball, which is what had pushed the ring far enough out to stop
+ reading as one object. The ring rests 92px from the ball's centre and widens only where a trimmed
+ arc would otherwise crowd the entries together. Near the body's top or bottom the arc trims to the
+ span that still fits, keeping every entry inside the conversation. Arrow keys walk the
+ arc from top to bottom with the ball at the head of the sequence; Esc (refocusing the ball), a
+ press elsewhere, or scrolling folds it.
+- "Hide launcher" folds the fan, writes `penguin.dock.launcherHidden` and unmounts the ball under
+ its own click, leaving a toast that names where it comes back from. That preference is the one
+ the new **Shortcuts launcher** switch on the Appearance settings page reads and writes, so
+ the fan's entry and the switch are two views of the same choice; both apply on the spot, through
+ a small store the launcher's mount and the settings row subscribe to. A tolerant read means only
+ a deliberate "1" hides it — an absent or hand-edited value shows the launcher.
+- The pending-approval amber dot rides the ball — and the agents entry — under the same rule as the
+ toolbar's right-dock toggle, and is named in the ball's accessible name.
+- The ball drags along the edge with a small movement threshold, so a press stays a click; it
+ rubberbands off the edge and past the body's ends and springs back on release. The position is
+ one global preference, `penguin.dock.launcherY`, stored as a ratio of the chat body's height with
+ a tolerant parse (anything unusable falls back to the centre). The gesture is tracked on the
+ window, so it follows the pointer wherever it travels — over other controls included — instead
+ of stalling the moment pointer capture is lost; capture and `touch-action: none` are still what
+ keep a touch drag from scrolling the page under it. Both preferences are registered as browser
+ preferences in `lib/install-scope.ts`, so switching data roots keeps them.
+- `prefers-reduced-motion` disables the spring and the fan's animations: instant show and hide.
+- The decisions — visibility, clamping (which reserves the caption's height), the ratio round trip
+ and its parse, drag bounds, the arc's geometry and trimming, and the put-away preference and its
+ store — live in `features/dock/dock-launcher-state.ts` with unit tests
+ (`test/dock-launcher-state.test.ts`). The Web App docs and the design spec describe the launcher.
diff --git a/changelog/unreleased/2026-09-02-dock-floating-launcher.zh.md b/changelog/unreleased/2026-09-02-dock-floating-launcher.zh.md
new file mode 100644
index 00000000..2acddfb6
--- /dev/null
+++ b/changelog/unreleased/2026-09-02-dock-floating-launcher.zh.md
@@ -0,0 +1,21 @@
+# 快捷方式悬浮球
+
+- **Date:** 2026-09-02
+- **Type:** feature
+- **Scope:** `web`, `docs`
+- **PR:** [#586](https://github.com/Prism-Shadow/penguin-harness/pull/586)
+
+[English](2026-09-02-dock-floating-launcher.md)
+
+对话页新增了 AssistiveTouch 式的工作台浮动入口:没有停靠面占据屏幕时,一枚半透明圆形按钮浮在对话正文右缘内侧、下方带一行小字「快捷方式」,点击即以它为圆心向左展开紧挨着它的一圈入口——各停靠面板加终端各一枚,只有图标,名称由球下那行小字读出——选中即打开对应面板——停靠面一出现,浮动入口随之消失。此前工作台的面板只能经工具行上的开关打开,而用户可能根本注意不到那个按钮,窄屏上尤其如此。弧末另有一枚入口可把浮动球彻底收起,再由「外观」设置里的开关请回来。
+
+## 细节
+
+- 出现的条件是它所顶替的那块地方空着:桌面宽度下指右侧停靠栏收起;在两块停靠栏合并为一块底部面的窄屏下,指两块停靠栏都没有打开——此前窄屏下根本没有这枚按钮。
+- 静止态:44px 的半透明圆形,带毛玻璃与柔和阴影,悬停 / 聚焦前保持低调(键盘用户有可见焦点环),显示工作台图标——四块拼起来的面板格——球下方在同款玻璃底上印着它的名字,只有一枚图标说不出它开的是什么,可访问名也是这个词。它停在距正文右缘 32px 处,读作浮在正文上而不是贴死在边上;留出的这段距离也让球下的小字始终居中,最长的那个名称也放得下。圆球与各入口都不带 tooltip——名称已经在屏幕上。它位于对话正文内——工具行与输入区之间——因此连同小字都不会盖住二者。
+- 点击、Enter 或 Space 展开圆形入口:`PANEL_KINDS` 中的每种面板经共享的面板元信息生成(日后新增的种类自动出现),外加终端——与停靠栏选单一致,认领无人持有的活动 Shell,否则新建——弧末再加一枚 muted 色的「隐藏悬浮球」,读作比上面那些面板更轻的动作。面板入口在宽屏下点名右侧停靠栏,窄屏下不点名落点,由 store 按工具行面板按钮的同一口径决定。入口落在以球为圆心、向左展开的半圆弧上——自正上方经正左方到正下方,按角度均分、顺序自上而下。入口只有图标,指到或聚焦其中一枚,球下的小字就改显示它的名称:屏幕上只留一处名称,而不是七枚名称药丸浮在球周围——正是后者把这圈入口推得太远,看着不再像一个整体。这圈入口静止时距球心 92px,只有弧被上下缘收窄、入口挨得过近时才按需放大;球靠近正文上缘或下缘时,弧收窄为放得下的那一段,入口始终留在对话内。方向键沿弧自上而下移动焦点、球排在序列之首;Esc(焦点回到圆球)、点击别处或滚动即收起。
+- 「隐藏悬浮球」收起弧、写入 `penguin.dock.launcherHidden` 并在自己的点击下卸载浮动球,留在屏幕上的是一条提示,写明去哪儿把它请回来。这条偏好同时也是系统设置页「外观」新增的**快捷方式悬浮球**开关所读写的那一条,弧末入口与开关因此是同一个选择的两个视图;两处都即改即生效,经由一个小 store,浮动球的挂载与设置行都订阅它。读取容错:只有显式的 `1` 才算隐藏,缺失或被手改的值一律显示。
+- 待审批的琥珀小点随球显示(智能体入口上也有),规则与工具行右侧栏按钮一致,并计入圆球的可访问名。
+- 圆球可沿右缘拖动,小位移阈值让短按仍是点击;拖离边缘或拖过正文两端有阻尼,松手弹回。位置是一条全局偏好 `penguin.dock.launcherY`,以对话正文高度的比例存储并容错解析(无效值回落到居中)。拖动过程改由 window 上的监听跟踪,指针经过其他控件也照样跟随,不会因为指针捕获被夺走而卡在半路;指针捕获与 `touch-action: none` 仍是让触屏上的拖动不带着页面一起滚的那一层。两条偏好都在 `lib/install-scope.ts` 登记为浏览器偏好,换数据根不会丢。
+- `prefers-reduced-motion` 下不做弹簧与展开动画:即时显隐。
+- 各项决策——是否显示、钳制(含为小字预留的高度)、比例往返与解析、拖动边界、弧的几何与收窄,以及收起偏好与它的 store——集中在 `features/dock/dock-launcher-state.ts`,配有单元测试(`test/dock-launcher-state.test.ts`)。Web App 文档与设计文档已补充该入口的说明。
diff --git a/packages/docs/content/web-app.en.md b/packages/docs/content/web-app.en.md
index db0ed6a7..354764c2 100644
--- a/packages/docs/content/web-app.en.md
+++ b/packages/docs/content/web-app.en.md
@@ -83,6 +83,10 @@ Copy buttons across the app confirm at the button itself: the copy icon flips to
- When the model API rejects the Session's credentials (an authentication failure), the composer grays out and disables — recoverably: the Session pins only the model reference, and credentials come from the current Project config. The notice's primary button opens the Models page; saving a new API key there unlocks the composer by itself (open tabs unlock live via a `credentials_updated` event, and after a reload the composer stays unlocked because the credential update is newer than the recorded auth failure). A "Retry" button clears the state manually for another attempt (it re-arms if the key is still bad), a completed request always clears it, and "New Session" remains as the escape to a fresh draft. The disabled composer keeps its draft selectable, so a long message that failed to send can still be copied out.
- Terminals live in the docks beside the conversation: Ctrl+` shows or hides the terminal tabs (adopting or starting a shell when none is open), and Ctrl+W, with a terminal focused, closes that terminal — the same confirm-then-kill its tab's × runs, in the dock and on the standalone `/terminal` page alike — and never reaches the shell. Browsers reserve Ctrl+W for closing the browser tab and may act on it first; the desktop app delivers it to the terminal.
+### Shortcuts Launcher
+
+Whenever no side panel is on screen — the right panel closed on a desktop-width window, or neither panel open on a narrow one, where the two merge into a bottom sheet — a translucent round button carrying a workbench glyph floats 32px inside the right edge of the conversation, the region between the toolbar and the composer, with a short caption beneath it reading "Shortcuts", so the workbench's panels stay one click away even for someone who has never noticed the toolbar's toggle. Clicking it (or pressing Enter/Space on it) fans out one round entry per panel — agents, Workspace files, memory, Trace, messaging, and a terminal — on a tight semicircular ring around the button, opening leftward. The entries are glyphs alone; pointing at one, or focusing it, shows its name in the caption under the button, which stays centred beneath it — the room the button keeps from the edge is what holds even the longest name. Neither the button nor the entries carry a tooltip: their names are already on screen. Near the top or bottom of the conversation the arc shortens to the part that still fits. Picking an entry opens that panel — in the right side panel on a desktop-width window, in the bottom sheet on a narrow one — and the button disappears the moment the panel is open. The arc ends in a "Hide launcher" entry that puts the button away for good; a message says where it comes back from, and the **Shortcuts launcher** switch on the Appearance settings page turns it on again. Esc, a click elsewhere or scrolling folds the fan. The button drags up and down along the edge (a short press stays a click), following the pointer wherever it goes — over other controls included — and springs back onto the edge when released; it never covers the toolbar or the composer, and its position is remembered in the browser as one preference shared by every conversation. While the panel is closed and a subagent is waiting for an approval, the amber dot from the toolbar's toggle rides the button too.
+
### Files Panel
The files panel shows the Workspace as a directory tree on the left and a preview of the selected file on the right. A directory lists its contents the first time it is opened; the tree takes the arrow keys (up/down move, right opens a directory or steps into it, left closes it or steps out), the selected file is highlighted, and the breadcrumbs above read out the current directory — a path, not a row of links, since the tree beside them is what navigates; when the path outgrows the toolbar its leading segments collapse into a single `…`, keeping the current directory visible and Refresh and Upload on the same row; the root segment reads `.`, and the Workspace's absolute path lives in the Session details card rather than on this toolbar. A search box above the tree filters what the tree holds: matching is on the entry's name, a match keeps its parent directories visible and open, and a directory whose own name matches is shown with its contents. The tree is lazy, so the search reaches only the directories that have been opened at least once — when nothing in them matches it says so rather than looking empty; Esc clears the box. Opening or closing a directory grows its subtree out of its row, or shrinks it back into it, over about 200ms — the rows stay on screen until the collapse finishes; with reduced motion the change is immediate. A toolbar toggle hides or shows the tree (shown by default; the choice is remembered in the browser) and slides out of and back into the panel's left edge over about 200ms, the motion the docks themselves expand and collapse with; the divider between the two panes drags to set the tree's width (arrow keys nudge it while it has focus, and the width is remembered too), and a panel too narrow for both panes falls back to one column — the tree until a file is chosen, then the preview with a Back button. Markdown and HTML preview rendered with a Source toggle, text files inline with highlighting, images inline (click to zoom), PDF embedded; anything else is offered as a download. A file whose extension says nothing about its type (a `Makefile`, a `LICENSE`) is read as text when its bytes look like text.
diff --git a/packages/docs/content/web-app.zh.md b/packages/docs/content/web-app.zh.md
index e2b70f8c..cf54f7fc 100644
--- a/packages/docs/content/web-app.zh.md
+++ b/packages/docs/content/web-app.zh.md
@@ -82,6 +82,10 @@ penguin web
- 模型 API 拒绝该 Session 的凭据(鉴权失败)时,输入框会置灰禁用——但可恢复:Session 锁定的只是模型引用,凭据取自当前 Project 配置。提示条的主按钮跳转到模型配置页;在那里保存新的 API key 后输入框会自动解锁(已打开的标签页经 `credentials_updated` 事件即时解锁;刷新后也保持解锁,因为凭据更新时间晚于记录的鉴权失败时间)。「重试」按钮可手动清除该状态再试一次(key 仍无效时会重新变灰),一次成功的请求总会清除该状态,「新建会话」仍作为跳到全新草稿的出口。禁用态的输入框保留草稿且可选中——发送失败的长消息仍能复制出来。
- 终端位于对话两侧的停靠面板:Ctrl+` 显示或收起终端标签(没有打开的终端时会接管或新建一个 Shell),终端获得焦点时按 Ctrl+W 关闭该终端——与标签 × 相同,先确认、再结束 Shell,停靠面板与独立的 `/terminal` 页一致——按键不会到达 Shell。浏览器把 Ctrl+W 留给关闭浏览器标签页,可能先于页面响应;桌面应用会把它交给终端。
+### 快捷方式悬浮球
+
+没有面板占据屏幕时——桌面宽度下右侧停靠栏收起,窄屏下两块面板合并成的底部弹层没有打开——对话区(工具行与输入框之间的区域)右缘内侧 32px 处会浮着一枚半透明圆形按钮(球面是工作台图标)、下方带一行小字「快捷方式」,让工作台的各块面板始终一步可达——即使从未注意到工具行上的开关。点击它(或在其上按 Enter / Space)会以按钮为圆心向左展开一圈紧挨着它的圆形入口——智能体、Workspace 文件、记忆、轨迹、消息软件与终端各一枚,只有图标;指到或聚焦其中一枚时,按钮下方那行小字改显示它的名称;这行小字始终居中在按钮正下方,按钮与边缘留出的距离足以容下最长的那个名称。按钮与入口都不带 tooltip——名称已经写在屏幕上。按钮靠近对话区上下两端时,这段弧收窄为放得下的那一段。选中入口即打开对应面板——桌面宽度落在右侧停靠栏,窄屏落在底部弹层——面板一出现按钮就消失。弧末另有一枚「隐藏悬浮球」入口,选中即让按钮不再出现,并提示去哪儿恢复;设置页「外观」的**快捷方式悬浮球**开关可重新打开。Esc、点击别处或滚动都会收起这段弧。按钮可沿右缘上下拖动(短按仍是点击),拖动全程跟随指针——指针经过其他按钮也不会中断——松手回弹贴边;它不会盖住工具行或输入框,位置作为一条全局偏好记在浏览器里,所有对话共用。停靠栏收起期间若有子智能体等待审批,工具行开关上的琥珀色小点也会显示在这枚按钮上。
+
### 文件面板
文件面板左侧是 Workspace 的目录树,右侧是所选文件的预览。目录在首次展开时才加载内容;目录树支持方向键(上下移动、右键展开目录或进入其中、左键收起或回到上级),选中的文件高亮,工具栏的面包屑只读出当前目录的路径、不再可点——旁边就是目录树,导航交给它;路径长到工具栏放不下时,前导段折叠成一个「…」,当前目录始终可见,刷新 / 上传也不会被挤到第二行;根目录在面包屑里写作 `.`,Workspace 的绝对路径在会话详情卡片里,不在这条工具栏上。目录树上方的搜索框按条目名称过滤:命中项的上级目录一并保留并展开,名称本身命中的目录连同其内容一起显示。目录树是懒加载的,搜索只能覆盖至少展开过一次的目录——都不匹配时会明说,而不是显示成空树;按 Esc 清空搜索框。展开 / 折叠时子树以高度过渡动画展开或收起(约 200ms,折叠期间行仍可见直至收起完成;系统设为减少动态时即时)。工具栏按钮可隐藏或显示目录树(默认显示,选择记在浏览器本地),显隐时目录树以约 200ms 的宽度过渡滑出或滑入,与停靠面板展开 / 收起同款;两栏之间的分隔条可拖动调整目录树宽度(获得焦点后可用左右方向键微调,宽度同样记住);面板宽度容不下两栏时退化为单栏——先显示目录树,选中文件后换成带「返回列表」按钮的预览。Markdown 与 HTML 以渲染视图预览并可切换源码,文本文件内联高亮显示,图片内联显示(点击放大),PDF 内嵌;其余类型提示下载。扩展名看不出类型的文件(`Makefile`、`LICENSE` 之类)在内容看起来是文本时按文本处理。
diff --git a/packages/web/src/components/ui/icons.tsx b/packages/web/src/components/ui/icons.tsx
index 320be96b..1892d8fb 100644
--- a/packages/web/src/components/ui/icons.tsx
+++ b/packages/web/src/components/ui/icons.tsx
@@ -164,6 +164,17 @@ export function CloseButton({
/** Info circle: the app's 9-radius status circle with a bar and a dot inside it. */
export const INFO_ICON = "M12 21a9 9 0 1 0 0-18 9 9 0 0 0 0 18zM12 11v5m0-8h.01";
+/**
+ * Window with a bottom pane / a right pane: the two dock edges. Drawn by the chat toolbar's
+ * pull-open buttons and the dock header's move-dock buttons, so one mark stands for one edge
+ * everywhere.
+ */
+export const PANEL_BOTTOM_ICON = "M4 5h16v14H4zM4 14h16";
+export const PANEL_RIGHT_ICON = "M4 5h16v14H4zM14 5v14";
+
+/** A dashboard of four tiles: the workbench the floating launcher opens. */
+export const WORKBENCH_ICON = "M3 3h7v9H3zM14 3h7v5h-7zM14 12h7v9h-7zM3 16h7v5H3z";
+
/**
* File glyphs, shared by every place a file operation is marked — the file summary card, the
* memory-changes card, the context panel's file ranking — so a read, an edit and a write look
diff --git a/packages/web/src/components/ui/sheet.tsx b/packages/web/src/components/ui/sheet.tsx
index cc150461..e2225860 100644
--- a/packages/web/src/components/ui/sheet.tsx
+++ b/packages/web/src/components/ui/sheet.tsx
@@ -27,6 +27,7 @@
import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
import type { PointerEvent as ReactPointerEvent, ReactNode } from "react";
import { CloseButton } from "./icons";
+import { usePrefersReducedMotion } from "./use-reduced-motion";
import { SPRING_DEFAULT, SPRING_MOMENTUM, createSpringDriver } from "../../lib/spring";
import type { SpringDriver } from "../../lib/spring";
import { nearestSnap, project, rubberband } from "../../lib/sheet-physics";
@@ -49,19 +50,6 @@ export interface SheetProps {
children: ReactNode;
}
-function usePrefersReducedMotion(): boolean {
- const [reduced, setReduced] = useState(
- () => window.matchMedia("(prefers-reduced-motion: reduce)").matches,
- );
- useEffect(() => {
- const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
- const onChange = (e: MediaQueryListEvent) => setReduced(e.matches);
- mq.addEventListener("change", onChange);
- return () => mq.removeEventListener("change", onChange);
- }, []);
- return reduced;
-}
-
export function Sheet({ open, snap, onSnapChange, onClose, title, children }: SheetProps) {
// Don't unmount immediately when open=false: unmount only after the exit animation finishes (onSettle).
const [mounted, setMounted] = useState(open);
diff --git a/packages/web/src/components/ui/use-reduced-motion.ts b/packages/web/src/components/ui/use-reduced-motion.ts
new file mode 100644
index 00000000..f6de6bc6
--- /dev/null
+++ b/packages/web/src/components/ui/use-reduced-motion.ts
@@ -0,0 +1,22 @@
+/**
+ * Whether the reader asked their system to reduce motion, as live state.
+ *
+ * `styles.css` already disables the app's CSS animations under that preference, so this hook is
+ * for the motion CSS cannot reach: a spring driven frame by frame in JS. Its callers replace the
+ * animation with the resting state it would have ended on — the sheet snaps to its target, the
+ * dock launcher's ball jumps home and its fan opens and folds without one.
+ */
+import { useEffect, useState } from "react";
+
+const QUERY = "(prefers-reduced-motion: reduce)";
+
+export function usePrefersReducedMotion(): boolean {
+ const [reduced, setReduced] = useState(() => window.matchMedia(QUERY).matches);
+ useEffect(() => {
+ const mq = window.matchMedia(QUERY);
+ const onChange = (event: MediaQueryListEvent) => setReduced(event.matches);
+ mq.addEventListener("change", onChange);
+ return () => mq.removeEventListener("change", onChange);
+ }, []);
+ return reduced;
+}
diff --git a/packages/web/src/features/chat/chat-page.tsx b/packages/web/src/features/chat/chat-page.tsx
index 79ed8c7e..36d3a6d2 100644
--- a/packages/web/src/features/chat/chat-page.tsx
+++ b/packages/web/src/features/chat/chat-page.tsx
@@ -111,6 +111,7 @@ import { SubagentsView } from "./subagents-view";
import { TracePanel } from "../traces/trace-panel";
import { MessagingPanel } from "../messaging/messaging-panel";
import { DockPanel } from "../dock/dock-panel";
+import { DockLauncher } from "../dock/dock-launcher";
import { useDockMount } from "../dock/use-dock-mount";
import { panelLabel } from "../dock/panel-meta";
// importing it also registers the global Ctrl+` hotkey with the app bundle
@@ -2075,7 +2076,10 @@ export function ChatPage() {
// ChatInput always mounts in the same JSX slot, so it isn't unmounted and
// recreated when the first message arrives (preserving draft/focus).
<>
- <div className="min-h-0 flex-1">
+ {/* `relative`: the floating dock launcher below anchors to this body —
+ the region between the toolbar and the composer — so clamping to
+ it keeps the launcher off both. */}
+ <div className="relative min-h-0 flex-1">
{emptyChat ? (
<div className="flex h-full items-center justify-center px-4">
<p className="text-lg font-medium text-gray-400 dark:text-gray-500">
@@ -2113,6 +2117,9 @@ export function ChatPage() {
}
/>
)}
+ {/* The right dock's floating launcher: rides this body's right edge
+ while that dock is hidden, and opens its panels in one click. */}
+ <DockLauncher agentsPending={anySubagentPending} />
</div>
<div className="shrink-0 border-t border-gray-200 bg-white px-3 pb-[calc(0.75rem+env(safe-area-inset-bottom))] pt-3 md:pb-3 dark:border-gray-800 dark:bg-gray-950">
<div className="mx-auto max-w-3xl">
diff --git a/packages/web/src/features/chat/panels-toolbar.tsx b/packages/web/src/features/chat/panels-toolbar.tsx
index 245bc0cf..4eb88bb2 100644
--- a/packages/web/src/features/chat/panels-toolbar.tsx
+++ b/packages/web/src/features/chat/panels-toolbar.tsx
@@ -12,6 +12,7 @@
import { useSyncExternalStore } from "react";
import { S } from "../../lib/strings";
import { GlyphIcon } from "../../components/ui/glyph-icon";
+import { PANEL_BOTTOM_ICON, PANEL_RIGHT_ICON } from "../../components/ui/icons";
import { ICON_SIZE } from "../../lib/icon-scale";
import { toneDot } from "../../lib/tone";
import {
@@ -23,10 +24,6 @@ import {
type DockPosition,
} from "../dock/dock-state";
-/** Window with a bottom pane / a right pane: the two pull-open buttons. */
-const PANEL_BOTTOM_ICON = "M4 5h16v14H4zM4 14h16";
-const PANEL_RIGHT_ICON = "M4 5h16v14H4zM14 5v14";
-
export interface PanelsToolbarProps {
/** A pending approval inside a subagent: amber dot beside the agents tab's dock button. */
agentsPending: boolean;
diff --git a/packages/web/src/features/dock/dock-launcher-state.ts b/packages/web/src/features/dock/dock-launcher-state.ts
new file mode 100644
index 00000000..8923636c
--- /dev/null
+++ b/packages/web/src/features/dock/dock-launcher-state.ts
@@ -0,0 +1,340 @@
+/**
+ * The decisions behind the chat page's floating dock launcher (dock-launcher.tsx), kept
+ * free of the DOM so they are unit-testable: whether the launcher shows at all, where the
+ * ball rests along the chat body's right edge (one global preference, stored as a ratio of
+ * the body's height), how far a drag may pull it, and where on the arc its entries sit.
+ *
+ * Two global preferences live here: `penguin.dock.launcherY` (where it rests) and
+ * `penguin.dock.launcherHidden` (whether the user put it away at all). Both are registered
+ * as browser preferences in lib/install-scope.ts, so switching data roots keeps them.
+ *
+ * Coordinates are the ball's TOP offset within the chat body — the region between the
+ * toolbar and the composer — and its horizontal offset from the resting edge: 0 on the
+ * edge, negative when pulled into the conversation.
+ */
+import { rubberband } from "../../lib/sheet-physics";
+
+/** localStorage key of the resting position: the ball's centre as a ratio of the body's height. */
+export const LAUNCHER_Y_KEY = "penguin.dock.launcherY";
+/** localStorage key of the put-it-away preference; only LAUNCHER_HIDDEN_ON counts as hidden. */
+export const LAUNCHER_HIDDEN_KEY = "penguin.dock.launcherHidden";
+const LAUNCHER_HIDDEN_ON = "1";
+const LAUNCHER_HIDDEN_OFF = "0";
+/** The ball's diameter (px). */
+export const LAUNCHER_SIZE = 44;
+/** Room kept between the ball and the body's top and bottom edges (px). */
+export const LAUNCHER_EDGE_MARGIN = 12;
+/** Where the ball rests until the user moves it: centred on the body's height. */
+export const DEFAULT_LAUNCHER_RATIO = 0.5;
+/**
+ * The always-visible caption below the ball (px): its gap to the ball plus the pill's own
+ * height. It hangs outside the ball's box, so the vertical clamp has to reserve it or the
+ * caption would be the first thing the composer covers.
+ */
+export const LAUNCHER_CAPTION_HEIGHT = 26;
+
+/** A fan entry's diameter (px), one rung under the ball so the fan reads as its offspring. */
+export const FAN_ENTRY_SIZE = 36;
+/**
+ * The ring's radius at rest (px): how far an entry's centre sits from the ball's centre
+ * while the whole semicircle is available.
+ *
+ * The floor is the tightest packing that arc produces. Seven entries — five panel kinds,
+ * the terminal, and the hide entry — spread evenly over a semicircle leave a chord of
+ * 2R·sin(step / 2) between neighbours, with step = pi / 6, so keeping FAN_ENTRY_GAP of air
+ * around the 36px circles needs 44 / (2·sin 15°) ≈ 85px. 92 is that with a few pixels to
+ * spare (a chord of ≈ 48px, some 12px of air), and it keeps the ring close enough to the
+ * ball to read as one object. The arc only ever grows from here, and only where a trimmed
+ * span would otherwise crowd the entries together.
+ */
+export const FAN_MIN_RADIUS = 92;
+/** Air kept between two neighbouring entries' circles (px). */
+export const FAN_ENTRY_GAP = 8;
+/**
+ * The widest the ring may grow (px). Real geometry never asks for this much — a ball parked
+ * against the body's top edge, the tightest span seven entries ever get, settles at ≈ 161px.
+ * It is there for a body barely taller than the entries themselves, where no radius can
+ * space them apart (the arc that fits keeps a bounded length however far the ring is pushed
+ * out) and the solver below would otherwise run away with them off the left of the screen.
+ * The ceiling is the narrow layout's width: on a ~320px phone the ball's centre sits 54px
+ * from the edge, so an entry's far side, R + 18, has to fit the 266px left of it.
+ */
+export const FAN_MAX_RADIUS = 240;
+/** Room kept between an entry and the body's top or bottom edge (px). */
+const FAN_EDGE_PAD = 4;
+/**
+ * How many times the radius and the span are solved against each other before the last
+ * pass is taken as-is. Each depends on the other — a wider radius trims the span, a
+ * narrower span demands a wider radius — and the loop converges from below within three.
+ */
+const FAN_RADIUS_PASSES = 12;
+/** Growth below this (px) counts as converged: the ring then takes the radius the last pass asked for. */
+const FAN_RADIUS_TOLERANCE = 1e-3;
+
+/** How far the ball can be pulled off its edge mid-drag (px; the rubberband's asymptote). */
+const HORIZONTAL_REACH = 40;
+/** How far the ball can be pulled past the body's top or bottom mid-drag (px). */
+const VERTICAL_REACH = 56;
+
+export interface LauncherVisibility {
+ /** The right dock occupies its edge (open — showing its tabs or its picker). */
+ rightDockVisible: boolean;
+ /** The bottom dock is open; below the breakpoint it is the surface both docks merge into. */
+ bottomDockVisible: boolean;
+ /** Below the desktop breakpoint the docks merge into one bottom surface. */
+ narrow: boolean;
+ /** The user put the launcher away (`penguin.dock.launcherHidden`). */
+ hidden: boolean;
+}
+
+/**
+ * The launcher stands in for whichever dock surface is away, so it shows exactly while
+ * that surface's room is free. Wide: the right dock is the one it opens into, so only that
+ * dock's state counts. Narrow: the two docks render as ONE merged bottom surface, and the
+ * launcher would sit on top of it, so it shows only while neither dock is open. Either way
+ * the put-it-away preference wins over the layout.
+ */
+export function shouldShowLauncher({
+ rightDockVisible,
+ bottomDockVisible,
+ narrow,
+ hidden,
+}: LauncherVisibility): boolean {
+ if (hidden) return false;
+ return narrow ? !rightDockVisible && !bottomDockVisible : !rightDockVisible;
+}
+
+/**
+ * The ball's travel: the lowest and highest top offsets that keep it inside the body with
+ * the margin. The caption hangs below the ball, so the bottom end reserves it too.
+ */
+export function launcherBounds(bodyHeight: number): { min: number; max: number } {
+ const min = LAUNCHER_EDGE_MARGIN;
+ const max = bodyHeight - LAUNCHER_SIZE - LAUNCHER_CAPTION_HEIGHT - LAUNCHER_EDGE_MARGIN;
+ return { min, max: Math.max(min, max) };
+}
+
+/** Where a top offset settles: inside the bounds; a body too short for the margins pins it at the top one. */
+export function clampLauncherTop(top: number, bodyHeight: number): number {
+ const { min, max } = launcherBounds(bodyHeight);
+ if (!Number.isFinite(top)) return min;
+ return Math.min(max, Math.max(min, top));
+}
+
+function clampRatio(ratio: number): number {
+ return Math.min(1, Math.max(0, ratio));
+}
+
+/** The resting top offset for a stored ratio (the ball's centre over the body's height). */
+export function launcherTopFromRatio(ratio: number, bodyHeight: number): number {
+ return clampLauncherTop(ratio * bodyHeight - LAUNCHER_SIZE / 2, bodyHeight);
+}
+
+/** The ratio to store for a settled top offset; a body with no height keeps the default. */
+export function launcherRatioFromTop(top: number, bodyHeight: number): number {
+ if (!(bodyHeight > 0)) return DEFAULT_LAUNCHER_RATIO;
+ return clampRatio((clampLauncherTop(top, bodyHeight) + LAUNCHER_SIZE / 2) / bodyHeight);
+}
+
+/**
+ * A stored ratio, made safe to use: a finite number is clamped into [0, 1]; anything else
+ * (absent, malformed, hand-edited) is null, and the caller falls back to the default.
+ */
+export function parseLauncherRatio(raw: string | null | undefined): number | null {
+ if (raw === null || raw === undefined || raw.trim() === "") return null;
+ const value = Number(raw);
+ return Number.isFinite(value) ? clampRatio(value) : null;
+}
+
+/** The storage the launcher reads and writes — localStorage, or a stub in tests. */
+export type LauncherStorage = Pick<Storage, "getItem" | "setItem">;
+
+function defaultStorage(): LauncherStorage | null {
+ try {
+ return typeof localStorage === "undefined" ? null : localStorage;
+ } catch {
+ return null; // the accessor itself throws where site data is blocked
+ }
+}
+
+/** The stored resting ratio, or the default when nothing usable is stored. */
+export function readLauncherRatio(storage: LauncherStorage | null = defaultStorage()): number {
+ try {
+ return parseLauncherRatio(storage?.getItem(LAUNCHER_Y_KEY)) ?? DEFAULT_LAUNCHER_RATIO;
+ } catch {
+ return DEFAULT_LAUNCHER_RATIO;
+ }
+}
+
+export function writeLauncherRatio(
+ ratio: number,
+ storage: LauncherStorage | null = defaultStorage(),
+): void {
+ try {
+ storage?.setItem(LAUNCHER_Y_KEY, String(clampRatio(ratio)));
+ } catch {
+ // Private-mode storage failures only cost persistence.
+ }
+}
+
+// ------------------------------------------------------------- put away, and brought back
+//
+// A tiny store rather than a plain read, because two places far apart render from it: the
+// launcher's own mount on the chat page, and the Appearance switch that turns it back on.
+// Either can write it, and both have to follow the other. The version counter is the
+// useSyncExternalStore snapshot; callers then read the value with readLauncherHidden().
+
+let hiddenVersion = 0;
+const hiddenListeners = new Set<() => void>();
+/**
+ * The live value, read from storage once and kept in memory afterwards: the launcher is
+ * rendered from the chat page, which re-renders on every streamed token, and that is no
+ * place for a synchronous storage read. Like the dock layout store, this means a change
+ * made in another tab is not seen until a reload.
+ */
+let hiddenCache: boolean | null = null;
+
+export function subscribeLauncherHidden(listener: () => void): () => void {
+ hiddenListeners.add(listener);
+ return () => void hiddenListeners.delete(listener);
+}
+
+export function launcherHiddenVersion(): number {
+ return hiddenVersion;
+}
+
+function hiddenIn(storage: LauncherStorage | null): boolean {
+ try {
+ return storage?.getItem(LAUNCHER_HIDDEN_KEY) === LAUNCHER_HIDDEN_ON;
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Whether the user put the launcher away. Only the stored "1" hides it; anything else —
+ * absent, stale, hand-edited — shows it. An explicit storage bypasses the cache.
+ */
+export function readLauncherHidden(storage?: LauncherStorage | null): boolean {
+ if (storage !== undefined) return hiddenIn(storage);
+ if (hiddenCache === null) hiddenCache = hiddenIn(defaultStorage());
+ return hiddenCache;
+}
+
+/** Puts the launcher away or brings it back, and tells everything rendering from it. */
+export function writeLauncherHidden(hidden: boolean, storage?: LauncherStorage | null): void {
+ const target = storage === undefined ? defaultStorage() : storage;
+ try {
+ target?.setItem(LAUNCHER_HIDDEN_KEY, hidden ? LAUNCHER_HIDDEN_ON : LAUNCHER_HIDDEN_OFF);
+ } catch {
+ // Private-mode storage failures only cost persistence; this session still updates.
+ }
+ if (storage === undefined) hiddenCache = hidden;
+ hiddenVersion += 1;
+ for (const listener of hiddenListeners) listener();
+}
+
+/**
+ * Where the ball follows the pointer mid-drag. Along the edge it tracks the pointer inside
+ * the bounds and rubberbands past them; off the edge it rubberbands from the first pixel,
+ * so the ball reads as attached to the edge it snaps back to on release.
+ */
+export function dragPosition(
+ startTop: number,
+ dx: number,
+ dy: number,
+ bodyHeight: number,
+): { x: number; top: number } {
+ const { min, max } = launcherBounds(bodyHeight);
+ const raw = startTop + dy;
+ const top =
+ raw < min
+ ? min - rubberband(min - raw, VERTICAL_REACH)
+ : raw > max
+ ? max + rubberband(raw - max, VERTICAL_REACH)
+ : raw;
+ const x = Math.sign(dx) * rubberband(Math.abs(dx), HORIZONTAL_REACH);
+ return { x, top };
+}
+
+/** One entry's place on the ring: an offset from the ball's centre. */
+export interface FanSlot {
+ /** Horizontal offset (px). Never positive — the arc opens leftward, away from the edge. */
+ x: number;
+ /** Vertical offset (px); negative above the ball's centre. */
+ y: number;
+}
+
+function clampUnit(value: number): number {
+ return Math.min(1, Math.max(-1, value));
+}
+
+/**
+ * The stretch of the leftward semicircle a ring of this radius may use, as angles from 0 at
+ * straight up to pi at straight down: an entry may not rise above the body's top nor sink
+ * below its bottom, which bounds cos(angle) from both sides and trims the arc toward
+ * whichever end has room. A body shorter than one entry collapses the span to its midpoint.
+ */
+function fanSpan(
+ centerY: number,
+ bodyHeight: number,
+ radius: number,
+): { start: number; end: number } {
+ const half = FAN_ENTRY_SIZE / 2 + FAN_EDGE_PAD;
+ // acos decreases, so the upper bound on cos gives the smallest angle and vice versa.
+ const start = Math.acos(clampUnit((centerY - half) / radius));
+ const end = Math.acos(clampUnit((centerY + half - bodyHeight) / radius));
+ if (end < start) {
+ const mid = (start + end) / 2;
+ return { start: mid, end: mid };
+ }
+ return { start, end };
+}
+
+/**
+ * The radius the ring takes here. It rests at FAN_MIN_RADIUS and grows only as far as the
+ * entries need to stay apart: neighbours an angular step apart are a chord of
+ * 2R·sin(step / 2) from each other, which has to clear an entry's diameter plus the gap.
+ * Growing the radius trims the span, which widens the step it takes again, so the two are
+ * solved against each other — each pass starts from the radius the previous one asked for,
+ * and FAN_MAX_RADIUS stops a body too short for any spacing to work.
+ */
+function fanRadius(centerY: number, bodyHeight: number, count: number): number {
+ let radius = FAN_MIN_RADIUS;
+ for (let pass = 0; pass < FAN_RADIUS_PASSES; pass += 1) {
+ const { start, end } = fanSpan(centerY, bodyHeight, radius);
+ const step = (end - start) / (count - 1);
+ if (!(step > 0)) return radius;
+ const needed = (FAN_ENTRY_SIZE + FAN_ENTRY_GAP) / (2 * Math.sin(step / 2));
+ if (needed >= FAN_MAX_RADIUS) return FAN_MAX_RADIUS;
+ // The passes climb toward the fixed point from below, so the LAST radius asked for is the
+ // one to keep once the climb has all but stopped — returning the previous one would leave
+ // the chord a hair short of the gap.
+ if (needed <= radius + FAN_RADIUS_TOLERANCE) return Math.max(radius, needed);
+ radius = needed;
+ }
+ return radius;
+}
+
+/**
+ * Where the fan's entries sit, as offsets from the ball's centre.
+ *
+ * Angles run from 0 at straight up, through pi/2 at straight left, to pi at straight down,
+ * so `x = -R·sin(angle)` and `y = -R·cos(angle)`. The usable span is the part of that
+ * semicircle that fits inside the chat body — near the body's top what is left is the
+ * stretch from straight left round to below, near its bottom the stretch from above round
+ * to straight left, and in between the whole semicircle. Entries divide that span evenly
+ * and come back in DOM order from top to bottom, so keyboard order is visual order.
+ */
+export function fanLayout(top: number, bodyHeight: number, count: number): FanSlot[] {
+ if (count <= 0) return [];
+ const centerY = top + LAUNCHER_SIZE / 2;
+ const radius = count > 1 ? fanRadius(centerY, bodyHeight, count) : FAN_MIN_RADIUS;
+ const { start, end } = fanSpan(centerY, bodyHeight, radius);
+ const step = count > 1 ? (end - start) / (count - 1) : 0;
+ const first = count > 1 ? start : (start + end) / 2;
+ return Array.from({ length: count }, (_, index) => {
+ const angle = first + index * step;
+ return { x: -radius * Math.sin(angle), y: -radius * Math.cos(angle) };
+ });
+}
diff --git a/packages/web/src/features/dock/dock-launcher.tsx b/packages/web/src/features/dock/dock-launcher.tsx
new file mode 100644
index 00000000..1b5ec258
--- /dev/null
+++ b/packages/web/src/features/dock/dock-launcher.tsx
@@ -0,0 +1,578 @@
+/**
+ * The floating launcher for the workbench — an AssistiveTouch-style ball floating clear of
+ * the chat body's right edge while no dock surface is up, so the dock's panels stay
+ * discoverable for a user who never notices the toolbar's toggle. The ball carries a short
+ * caption, and a click fans out one round button per panel kind (plus the terminal) onto a
+ * tight ring centred on it and opening leftward. The entries are glyphs alone; the caption
+ * under the ball is where their names are read — it shows the hovered or focused entry's
+ * name — because seven name pills floating around the ball is what pushed the ring far
+ * enough out to stop reading as one object. Nothing carries a tooltip: every name is already
+ * on screen. Picking an entry opens its panel: in the right dock on a wide window, in the
+ * merged bottom surface on a narrow one, which makes that surface visible and unmounts the
+ * launcher. The arc's last entry puts the launcher away for good, remembered as a global
+ * preference and turned back on from Appearance settings. The ball drags along the edge —
+ * another global preference, a ratio of the body's height — and springs back onto it when
+ * let go; Esc, a press elsewhere or a scroll folds the fan.
+ *
+ * Mounted inside the chat body, the region between the toolbar and the composer: clamping
+ * to its own container is what keeps it off both, and its right edge is the chat column's
+ * (the dock row's, while the dock is hidden). The position is written to the node directly
+ * — a transform driven by two spring drivers — rather than through React state, because a
+ * drag moves it every frame. The decisions live in dock-launcher-state.ts.
+ */
+import {
+ useCallback,
+ useEffect,
+ useLayoutEffect,
+ useRef,
+ useState,
+ useSyncExternalStore,
+} from "react";
+import type {
+ CSSProperties,
+ FocusEvent as ReactFocusEvent,
+ KeyboardEvent as ReactKeyboardEvent,
+ ReactNode,
+} from "react";
+import { S } from "../../lib/strings";
+import { GlyphIcon } from "../../components/ui/glyph-icon";
+import { CloseIcon, NAV_ICONS, WORKBENCH_ICON } from "../../components/ui/icons";
+import { toastInfo } from "../../components/ui/toast";
+import { usePrefersReducedMotion } from "../../components/ui/use-reduced-motion";
+import { ICON_SIZE } from "../../lib/icon-scale";
+import { toneDot, toneInk } from "../../lib/tone";
+import { scrollMovesAnchor } from "../../lib/context-menu";
+import { SPRING_DEFAULT, SPRING_MOMENTUM, createSpringDriver } from "../../lib/spring";
+import type { SpringDriver } from "../../lib/spring";
+import { subscribeTerminals, terminalApiSupported } from "../terminal/terminal-list";
+import { openTerminalInDock } from "./dock-terminal";
+import { panelGlyph, panelLabel } from "./panel-meta";
+import {
+ PANEL_KINDS,
+ dockVersion,
+ isDockVisible,
+ isNarrow,
+ openPanel,
+ subscribeDock,
+} from "./dock-state";
+import { usePointerDrag } from "./use-pointer-drag";
+import {
+ FAN_ENTRY_SIZE,
+ LAUNCHER_CAPTION_HEIGHT,
+ LAUNCHER_SIZE,
+ clampLauncherTop,
+ dragPosition,
+ fanLayout,
+ launcherHiddenVersion,
+ launcherRatioFromTop,
+ launcherTopFromRatio,
+ readLauncherHidden,
+ readLauncherRatio,
+ shouldShowLauncher,
+ subscribeLauncherHidden,
+ writeLauncherHidden,
+ writeLauncherRatio,
+} from "./dock-launcher-state";
+
+/**
+ * The ball's inset from the body's right edge (px): the ball floats well clear of the edge
+ * rather than sitting against it, and that room is what keeps the caption centred. A caption
+ * centred under the ball may be up to LAUNCHER_SIZE + 2·EDGE_INSET − 12 ≈ 96px wide before
+ * it touches the body's edge — wider than the longest name it shows ("Hide launcher"), so
+ * nothing has to slide sideways to stay inside.
+ */
+const EDGE_INSET = 32;
+/** Movement that turns a press into a drag (px); under it the press is a click. */
+const DRAG_THRESHOLD = 4;
+/** The fan's exit animation, after which its entries unmount (`.launcher-fan-out` in styles.css). */
+const FAN_EXIT_MS = 140;
+/**
+ * Delay between one entry's entrance and the next, the topmost entry first (ms). Short
+ * enough that the ring arrives as one shape rather than as a trickle of circles.
+ */
+const FAN_STAGGER_MS = 16;
+/** Gap between the ball and its caption (px); the pill takes the rest of LAUNCHER_CAPTION_HEIGHT. */
+const CAPTION_GAP = 4;
+
+export interface DockLauncherProps {
+ /** A pending approval inside a subagent: the amber dot rides the ball and the agents entry. */
+ agentsPending: boolean;
+}
+
+/** Renders the ball while no dock surface holds its room and the user has not put it away. */
+export function DockLauncher({ agentsPending }: DockLauncherProps) {
+ useSyncExternalStore(subscribeDock, dockVersion);
+ useSyncExternalStore(subscribeLauncherHidden, launcherHiddenVersion);
+ const terminalSupported = useSyncExternalStore(subscribeTerminals, terminalApiSupported);
+ const narrow = isNarrow();
+ const visible = shouldShowLauncher({
+ rightDockVisible: isDockVisible("right"),
+ bottomDockVisible: isDockVisible("bottom"),
+ narrow,
+ hidden: readLauncherHidden(),
+ });
+ if (!visible) return null;
+ return (
+ <LauncherBall
+ agentsPending={agentsPending}
+ terminalSupported={terminalSupported}
+ narrow={narrow}
+ />
+ );
+}
+
+interface FanState {
+ /** "closing" keeps the entries mounted through their exit animation. */
+ phase: "open" | "closing";
+ /** The geometry the arc was laid out for, frozen at the moment it opened. */
+ top: number;
+ bodyHeight: number;
+}
+
+interface FanEntry {
+ key: string;
+ label: string;
+ glyph: ReactNode;
+ badge: boolean;
+ testId: string;
+ choose: () => void;
+}
+
+// Every entry's box sits on the ball's centre; --fan-x / --fan-y carry it out to its place
+// on the arc, as both the resting transform and the entrance animation's end state.
+const ENTRY_CLASS =
+ "absolute flex items-center justify-center rounded-full border border-gray-200/80 bg-white/90 text-gray-600 shadow-[0_2px_8px_rgba(0,0,0,0.10)] backdrop-blur-md transition-colors duration-150 hover:bg-white hover:text-gray-900 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-bg)] dark:border-white/10 dark:bg-gray-900/90 dark:text-gray-300 dark:hover:bg-gray-800 dark:hover:text-gray-100";
+
+/**
+ * The one always-visible name, under the ball: a small pill on the same glass, with no
+ * colour of its own, so it follows the ball's resting-to-hover ink. It reads out whichever
+ * entry is hovered or focused, and the launcher's own caption the rest of the time.
+ */
+const CAPTION_CLASS =
+ "pointer-events-none absolute whitespace-nowrap rounded-md border border-gray-200/80 bg-white/85 px-1.5 py-0.5 text-[11px] font-medium leading-4 shadow-[0_1px_4px_rgba(0,0,0,0.08)] backdrop-blur-md transition-colors duration-150 dark:border-white/10 dark:bg-gray-900/85";
+
+const BALL_CLASS =
+ "anim-pop relative flex touch-none select-none items-center justify-center rounded-full border border-gray-200/80 text-gray-500 shadow-[0_2px_10px_rgba(0,0,0,0.10)] backdrop-blur-md transition-[background-color,color,opacity,box-shadow] duration-150 hover:bg-white/95 hover:text-gray-800 hover:opacity-100 hover:shadow-[0_4px_16px_rgba(0,0,0,0.14)] focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-bg)] dark:border-white/10 dark:text-gray-400 dark:hover:bg-gray-800/95 dark:hover:text-gray-100";
+
+function LauncherBall({
+ agentsPending,
+ terminalSupported,
+ narrow,
+}: {
+ agentsPending: boolean;
+ terminalSupported: boolean;
+ /** Below the breakpoint the docks merge, so an entry names no dock and lets the store pick. */
+ narrow: boolean;
+}) {
+ const reducedMotion = usePrefersReducedMotion();
+ const reducedMotionRef = useRef(reducedMotion);
+ reducedMotionRef.current = reducedMotion;
+
+ const rootRef = useRef<HTMLDivElement | null>(null);
+ const ballRef = useRef<HTMLButtonElement | null>(null);
+ const fanRef = useRef<HTMLDivElement | null>(null);
+ /** The resting position — the stored preference — as a ratio of the body's height. */
+ const ratioRef = useRef(readLauncherRatio());
+ const bodyHeightRef = useRef(0);
+ const draggingRef = useRef(false);
+ const [dragging, setDragging] = useState(false);
+ /** Set by a completed drag so the click the browser fires on release does not toggle the fan. */
+ const suppressClick = useRef(false);
+
+ // ---------------------------------------------------------------------------- position
+ // Two spring drivers write the wrapper's transform directly: x is the pull off the edge
+ // (0 at rest, negative into the conversation), y the top offset within the body.
+ const drivers = useRef<{ x: SpringDriver; y: SpringDriver } | null>(null);
+ if (drivers.current === null) {
+ const apply = () => {
+ const root = rootRef.current;
+ const d = drivers.current;
+ if (root && d) root.style.transform = `translate(${d.x.value}px, ${d.y.value}px)`;
+ };
+ drivers.current = { x: createSpringDriver(0, apply), y: createSpringDriver(0, apply) };
+ }
+ useEffect(
+ () => () => {
+ drivers.current?.x.dispose();
+ drivers.current?.y.dispose();
+ },
+ [],
+ );
+
+ // --------------------------------------------------------------------------------- fan
+ const [fan, setFanState] = useState<FanState | null>(null);
+ /**
+ * The entry the pointer or focus is on, read out by the caption under the ball. Null is
+ * nothing pointed at, and the caption falls back to the launcher's own word.
+ */
+ const [hoveredName, setHoveredName] = useState<string | null>(null);
+ // Mirrored in a ref so event handlers that fire before the next render read the latest.
+ const fanNow = useRef<FanState | null>(null);
+ const exitTimer = useRef(0);
+ const setFan = useCallback((next: FanState | null) => {
+ fanNow.current = next;
+ setFanState(next);
+ }, []);
+ useEffect(() => () => window.clearTimeout(exitTimer.current), []);
+
+ const openFan = useCallback(() => {
+ window.clearTimeout(exitTimer.current);
+ setFan({
+ phase: "open",
+ top: drivers.current?.y.value ?? 0,
+ bodyHeight: bodyHeightRef.current,
+ });
+ }, [setFan]);
+
+ /** Folds the fan; `refocus` returns focus to the ball (Esc) so a keyboard user is not stranded. */
+ const closeFan = useCallback(
+ (refocus: boolean) => {
+ setHoveredName(null);
+ const current = fanNow.current;
+ if (current !== null && current.phase === "open") {
+ if (reducedMotionRef.current) {
+ setFan(null);
+ } else {
+ setFan({ ...current, phase: "closing" });
+ window.clearTimeout(exitTimer.current);
+ exitTimer.current = window.setTimeout(() => setFan(null), FAN_EXIT_MS);
+ }
+ }
+ if (refocus) ballRef.current?.focus();
+ },
+ [setFan],
+ );
+
+ const fanOpen = fan?.phase === "open";
+
+ // Dismissal while open: a press elsewhere; Esc (capture, stopped — a dialog underneath
+ // must not close with it); the user scrolling anywhere (wheel / touch, which a stream
+ // auto-following a reply never fires); a scroll that moved the launcher itself.
+ useEffect(() => {
+ if (!fanOpen) return;
+ const root = rootRef.current;
+ const inside = (target: EventTarget | null): boolean =>
+ target instanceof Node && root?.contains(target) === true;
+ const onPointerDown = (event: MouseEvent) => {
+ if (!inside(event.target)) closeFan(false);
+ };
+ const onKey = (event: KeyboardEvent) => {
+ if (event.key !== "Escape") return;
+ event.stopPropagation();
+ closeFan(true);
+ };
+ const onUserScroll = (event: Event) => {
+ if (!inside(event.target)) closeFan(false);
+ };
+ const onScroll = (event: Event) => {
+ if (scrollMovesAnchor(event.target as Node | null, root)) closeFan(false);
+ };
+ window.addEventListener("mousedown", onPointerDown);
+ window.addEventListener("keydown", onKey, true);
+ window.addEventListener("wheel", onUserScroll, { capture: true, passive: true });
+ window.addEventListener("touchmove", onUserScroll, { capture: true, passive: true });
+ window.addEventListener("scroll", onScroll, true);
+ return () => {
+ window.removeEventListener("mousedown", onPointerDown);
+ window.removeEventListener("keydown", onKey, true);
+ window.removeEventListener("wheel", onUserScroll, { capture: true });
+ window.removeEventListener("touchmove", onUserScroll, { capture: true });
+ window.removeEventListener("scroll", onScroll, true);
+ };
+ }, [fanOpen, closeFan]);
+
+ // ----------------------------------------------------------------------------- caption
+ const captionText = hoveredName ?? S.dock.launcherCaption;
+
+ // The body's height bounds the travel: measured on mount and on every resize, and the
+ // ball re-placed from its stored ratio (unless a drag is holding it) — a taller or
+ // shorter body moves the resting point, and a fan opened for the old geometry folds.
+ useLayoutEffect(() => {
+ const body = rootRef.current?.parentElement;
+ const d = drivers.current;
+ if (!body || !d) return;
+ let lastHeight = -1;
+ const place = () => {
+ const height = body.clientHeight;
+ if (height === lastHeight) return;
+ lastHeight = height;
+ bodyHeightRef.current = height;
+ if (!draggingRef.current) d.y.set(launcherTopFromRatio(ratioRef.current, height));
+ closeFan(false);
+ };
+ place();
+ const observer = new ResizeObserver(place);
+ observer.observe(body);
+ return () => observer.disconnect();
+ }, [closeFan]);
+
+ // -------------------------------------------------------------------------------- drag
+
+ /**
+ * Lets go of the ball: back onto the edge and inside the body. A completed drag stores
+ * where it landed; an abandoned gesture (pointercancel) returns to the stored spot.
+ */
+ const settle = useCallback((persist: boolean) => {
+ draggingRef.current = false;
+ setDragging(false);
+ const d = drivers.current;
+ if (!d) return;
+ const bodyHeight = bodyHeightRef.current;
+ let top: number;
+ if (persist) {
+ top = clampLauncherTop(d.y.value, bodyHeight);
+ ratioRef.current = launcherRatioFromTop(top, bodyHeight);
+ writeLauncherRatio(ratioRef.current);
+ } else {
+ top = launcherTopFromRatio(ratioRef.current, bodyHeight);
+ }
+ if (reducedMotionRef.current) {
+ d.y.set(top);
+ d.x.set(0);
+ return;
+ }
+ d.y.animateTo(top, SPRING_DEFAULT);
+ d.x.animateTo(0, SPRING_MOMENTUM);
+ }, []);
+
+ const dragProps = usePointerDrag<{ startTop: number; clientX: number; clientY: number }>({
+ threshold: DRAG_THRESHOLD,
+ begin: (event) => {
+ const d = drivers.current;
+ if (!d) return null;
+ // Gesture takeover: an in-flight snap-back stops where it is and the press continues from there.
+ const [top] = d.y.stop();
+ d.x.stop();
+ return { startTop: top, clientX: event.clientX, clientY: event.clientY };
+ },
+ onMove: (event, payload) => {
+ const d = drivers.current;
+ if (!d) return;
+ if (!draggingRef.current) {
+ draggingRef.current = true;
+ setDragging(true);
+ closeFan(false);
+ }
+ const { x, top } = dragPosition(
+ payload.startTop,
+ event.clientX - payload.clientX,
+ event.clientY - payload.clientY,
+ bodyHeightRef.current,
+ );
+ d.x.set(x);
+ d.y.set(top);
+ },
+ onEnd: (_payload, dragged) => {
+ if (!dragged) {
+ // A press without movement: the click handler toggles the fan; a snap-back the
+ // press interrupted resumes.
+ settle(false);
+ return;
+ }
+ suppressClick.current = true;
+ settle(true);
+ },
+ onCancel: () => settle(false),
+ });
+
+ const onBallClick = () => {
+ if (suppressClick.current) {
+ suppressClick.current = false;
+ return;
+ }
+ if (fanNow.current?.phase === "open") closeFan(false);
+ else openFan();
+ };
+
+ // ---------------------------------------------------------------------------- keyboard
+
+ // Arrow keys walk the arc from top to bottom — the entries are in that order in the DOM —
+ // with the ball at the head of the sequence and wrap-around; Home/End jump to its ends.
+ const onRootKeyDown = (event: ReactKeyboardEvent<HTMLDivElement>) => {
+ const current = fanNow.current;
+ if (current?.phase !== "open") return;
+ if (!["ArrowUp", "ArrowDown", "Home", "End"].includes(event.key)) return;
+ const ball = ballRef.current;
+ const entries = [...(fanRef.current?.querySelectorAll<HTMLButtonElement>("button") ?? [])];
+ if (!ball || entries.length === 0) return;
+ const column = [ball, ...entries];
+ const index = column.indexOf(document.activeElement as HTMLButtonElement);
+ let next: number;
+ if (event.key === "Home") next = 0;
+ else if (event.key === "End") next = column.length - 1;
+ else if (index === -1) next = event.key === "ArrowDown" ? 0 : column.length - 1;
+ else next = (index + (event.key === "ArrowDown" ? 1 : -1) + column.length) % column.length;
+ event.preventDefault();
+ column[next]?.focus();
+ };
+
+ // Tabbing out of the launcher folds the fan. Only a move to another element counts: a
+ // null relatedTarget is the window losing focus, or a browser that does not focus
+ // buttons on click — folding there would unmount an entry under its own click.
+ const onRootBlur = (event: ReactFocusEvent<HTMLDivElement>) => {
+ const next = event.relatedTarget;
+ if (next instanceof Node && !rootRef.current?.contains(next)) closeFan(false);
+ };
+
+ // ------------------------------------------------------------------------------ render
+
+ // Wide: the launcher stands in for the right dock, so it names that dock. Narrow: the two
+ // render as one merged surface, so it names none and the store lands the tab where the
+ // toolbar's own panel buttons land it.
+ const target = narrow ? undefined : "right";
+ const entries: FanEntry[] = PANEL_KINDS.map((kind) => ({
+ key: kind,
+ label: panelLabel(kind),
+ glyph: panelGlyph(kind, ICON_SIZE.iconButton),
+ badge: kind === "agents" && agentsPending,
+ testId: `dock-launcher-open-${kind}`,
+ // The dock becomes visible with the tab, and the launcher unmounts with it.
+ choose: () => openPanel(kind, target),
+ }));
+ if (terminalSupported) {
+ entries.push({
+ key: "terminal",
+ label: S.terminal.title,
+ glyph: <GlyphIcon d={NAV_ICONS.terminal} size={ICON_SIZE.iconButton} />,
+ badge: false,
+ testId: "dock-launcher-open-terminal",
+ // The dock picker's terminal action: adopt a live shell no conversation holds, or
+ // start one. Async, so the fan folds first.
+ choose: () => {
+ closeFan(false);
+ void openTerminalInDock(target);
+ },
+ });
+ }
+ entries.push({
+ key: "hide",
+ label: S.dock.launcherHide,
+ // The close cross at its own 14px grid — a two-stroke mark aliases when scaled off it —
+ // in the muted ink, so it reads as a lesser thing than the panels above it.
+ glyph: <CloseIcon className={toneInk.muted} />,
+ badge: false,
+ testId: "dock-launcher-hide",
+ // Writing the preference unmounts the launcher under its own click, so the toast is
+ // what is left on screen: it says where the ball comes back from.
+ choose: () => {
+ closeFan(false);
+ writeLauncherHidden(true);
+ toastInfo(S.dock.launcherHiddenToast);
+ },
+ });
+
+ const label = agentsPending ? `${S.dock.launcher} · ${S.dock.launcherPending}` : S.dock.launcher;
+ // Where each entry sits on the arc, for the geometry the fan opened with. The count is
+ // the one being rendered, so a terminal appearing or leaving mid-fan re-spreads the arc.
+ const slots = fan === null ? [] : fanLayout(fan.top, fan.bodyHeight, entries.length);
+
+ return (
+ <div
+ ref={rootRef}
+ data-testid="dock-launcher"
+ data-fan={fan?.phase ?? "closed"}
+ onKeyDown={onRootKeyDown}
+ onBlur={onRootBlur}
+ className="absolute top-0 z-30"
+ style={{ right: EDGE_INSET, width: LAUNCHER_SIZE, height: LAUNCHER_SIZE }}
+ >
+ {fan !== null && (
+ // A zero-size anchor on the ball's centre: the entries are placed by their own
+ // transforms, so nothing here may size or clip the arc.
+ <div
+ ref={fanRef}
+ role="group"
+ aria-label={S.dock.launcherPanels}
+ data-testid="dock-launcher-fan"
+ className="absolute left-1/2 top-1/2 h-0 w-0"
+ >
+ {entries.map((entry, index) => {
+ // One slot per entry by construction; the guard is only the index type's.
+ const slot = slots[index];
+ if (slot === undefined) return null;
+ return (
+ <button
+ key={entry.key}
+ type="button"
+ data-testid={entry.testId}
+ // The glyph carries no text, so the name lives in the accessible name and in
+ // the caption under the ball, which reads out whatever is pointed at. No
+ // tooltip: it would only repeat the caption a few pixels away.
+ aria-label={entry.label}
+ onClick={entry.choose}
+ onMouseEnter={() => setHoveredName(entry.label)}
+ onMouseLeave={() => setHoveredName((name) => (name === entry.label ? null : name))}
+ onFocus={() => setHoveredName(entry.label)}
+ onBlur={() => setHoveredName((name) => (name === entry.label ? null : name))}
+ className={`${ENTRY_CLASS} ${
+ fan.phase === "closing" ? "launcher-fan-out" : "launcher-fan-in"
+ }`}
+ style={
+ {
+ width: FAN_ENTRY_SIZE,
+ height: FAN_ENTRY_SIZE,
+ left: -FAN_ENTRY_SIZE / 2,
+ top: -FAN_ENTRY_SIZE / 2,
+ transform: "translate(var(--fan-x), var(--fan-y))",
+ // Entrance runs down the arc from the top; the exit runs all at once.
+ animationDelay: fan.phase === "closing" ? "0ms" : `${index * FAN_STAGGER_MS}ms`,
+ "--fan-x": `${slot.x.toFixed(1)}px`,
+ "--fan-y": `${slot.y.toFixed(1)}px`,
+ } as CSSProperties
+ }
+ >
+ {entry.glyph}
+ {entry.badge && (
+ <span
+ aria-hidden
+ className={`absolute -right-0.5 -top-0.5 h-2 w-2 rounded-full ring-2 ring-white dark:ring-gray-950 ${toneDot.attention}`}
+ />
+ )}
+ </button>
+ );
+ })}
+ </div>
+ )}
+ <button
+ ref={ballRef}
+ type="button"
+ {...dragProps}
+ onClick={onBallClick}
+ // No tooltip: the caption under the ball already says what it opens, and the drag is
+ // discovered by dragging.
+ aria-label={label}
+ aria-expanded={fanOpen}
+ data-testid="dock-launcher-ball"
+ style={{ width: LAUNCHER_SIZE, height: LAUNCHER_SIZE }}
+ className={`${BALL_CLASS} ${
+ fanOpen || dragging
+ ? "bg-white/95 text-gray-800 opacity-100 dark:bg-gray-800/95 dark:text-gray-100"
+ : "bg-white/75 opacity-80 dark:bg-gray-900/75"
+ } ${dragging ? "cursor-grabbing" : "cursor-pointer"}`}
+ >
+ <GlyphIcon d={WORKBENCH_ICON} size={ICON_SIZE.sectionMark} />
+ {/* The caption hangs below the ball's circle: the launcher's own word at rest, the
+ pointed-at entry's name while the fan is open. It is the visible readout only —
+ every button carries its own accessible name — so it is hidden from assistive
+ technology and never folded into the ball's. Its height is spelled from the
+ constant the vertical clamp reserves, so the two cannot drift apart. */}
+ <span
+ aria-hidden
+ className={`${CAPTION_CLASS} left-1/2 -translate-x-1/2`}
+ style={{
+ top: LAUNCHER_SIZE + CAPTION_GAP,
+ height: LAUNCHER_CAPTION_HEIGHT - CAPTION_GAP,
+ }}
+ >
+ {captionText}
+ </span>
+ {agentsPending && (
+ <span
+ aria-hidden
+ className={`absolute right-0.5 top-0.5 h-2.5 w-2.5 rounded-full ring-2 ring-white dark:ring-gray-950 ${toneDot.attention}`}
+ />
+ )}
+ </button>
+ </div>
+ );
+}
diff --git a/packages/web/src/features/dock/dock-panel.tsx b/packages/web/src/features/dock/dock-panel.tsx
index a0bbaa5d..8720cc3e 100644
--- a/packages/web/src/features/dock/dock-panel.tsx
+++ b/packages/web/src/features/dock/dock-panel.tsx
@@ -33,7 +33,12 @@ import {
} from "react";
import type { ReactNode } from "react";
import { S } from "../../lib/strings";
-import { CloseIcon, NAV_ICONS } from "../../components/ui/icons";
+import {
+ CloseIcon,
+ NAV_ICONS,
+ PANEL_BOTTOM_ICON,
+ PANEL_RIGHT_ICON,
+} from "../../components/ui/icons";
import { ConfirmModal } from "../../components/ui/confirm-modal";
import { Dropdown } from "../../components/ui/dropdown";
import { GlyphIcon } from "../../components/ui/glyph-icon";
@@ -92,9 +97,6 @@ import { usePointerDrag } from "./use-pointer-drag";
/** Plus: the add-tab trigger. */
const ADD_ICON = "M12 5v14M5 12h14";
-/** Window with a bottom pane / a right pane: the move-dock buttons. */
-const PANEL_BOTTOM_ICON = "M4 5h16v14H4zM4 14h16";
-const PANEL_RIGHT_ICON = "M4 5h16v14H4zM14 5v14";
/** Box with an arrow escaping to the top right: detach to its own window. */
const DETACH_ICON = "M14 4h6v6M20 4l-8 8M10 6H5a1 1 0 0 0-1 1v12a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-5";
@@ -434,9 +436,13 @@ export function DockPanel({
return id ? { id } : null;
},
onMove: (event, { id }) => {
+ // The gesture is tracked on the window, so the strip comes from its ref rather than
+ // from the event's target — which is wherever the pointer has travelled to.
+ const stripEl = stripRef.current;
+ if (!stripEl) return;
// Out of the strip (with a little slack): the gesture becomes "move to the other
// edge" — the same overlay as moving a dock, with the preview showing the landing.
- const strip = event.currentTarget.getBoundingClientRect();
+ const strip = stripEl.getBoundingClientRect();
if (event.clientY < strip.top - 20 || event.clientY > strip.bottom + 20) {
setTabDrag({ active: true, candidate: dockDropCandidate(event.clientX, event.clientY) });
return;
@@ -444,7 +450,7 @@ export function DockPanel({
setTabDrag({ active: false, candidate: null });
// Within the strip: live reorder against the other tabs' midpoints.
- const tabEls = [...event.currentTarget.querySelectorAll<HTMLElement>("[data-tab-id]")];
+ const tabEls = [...stripEl.querySelectorAll<HTMLElement>("[data-tab-id]")];
const currentIds = tabEls.map((el) => el.dataset.tabId as string);
const others = tabEls.filter((el) => el.dataset.tabId !== id);
let insertAt = others.length;
diff --git a/packages/web/src/features/dock/use-pointer-drag.ts b/packages/web/src/features/dock/use-pointer-drag.ts
index 6c18c4f4..8101f641 100644
--- a/packages/web/src/features/dock/use-pointer-drag.ts
+++ b/packages/web/src/features/dock/use-pointer-drag.ts
@@ -1,17 +1,38 @@
/**
- * Shared pointer-drag state machine for the dock's gestures (header move, tab drag,
- * boundary resize): capture on pointerdown so a fast pull can never escape the surface, a
- * movement threshold separating taps from drags, and latest-callback refs so `onEnd`
- * never sees stale state. Spread the returned props on the gesture's surface.
+ * Shared pointer-drag state machine for the dock's gestures (header move, tab drag, boundary
+ * resize) and the context gauge's threshold cutter: a movement threshold separating taps from
+ * drags, and latest-callback refs so `onEnd` never sees stale state. Spread the returned props
+ * on the gesture's surface.
+ *
+ * The press is taken on the element; everything after it runs on WINDOW listeners. An
+ * element-bound `pointermove` stops arriving the moment pointer capture is lost — a control
+ * under the pointer taking it, a frame, a re-render of the captured node — and the gesture then
+ * froze mid-drag: the pointer went on moving, nothing followed it, and no `pointerup` ever
+ * reached the element to end it, so the surface stayed stuck in its dragging look. Window
+ * listeners keep tracking wherever the pointer travels, and a release anywhere ends the gesture
+ * through `onEnd`. Capture is still requested on the press, best-effort, because it is what
+ * keeps a fast pull from selecting text or scrolling the page under it; losing it costs nothing.
*/
-import { useMemo, useRef } from "react";
+import { useEffect, useMemo, useRef } from "react";
+
+interface DragState<T> {
+ payload: T;
+ /** Only this pointer's events belong to the gesture; another finger's are ignored. */
+ pointerId: number;
+ x: number;
+ y: number;
+ started: boolean;
+ /** Drops the gesture's listeners and its capture, and clears the state. Idempotent. */
+ release: () => void;
+}
export function usePointerDrag<T>(options: {
/** Resolves the drag payload from the initial event; null refuses the gesture. */
begin: (event: React.PointerEvent<HTMLElement>) => T | null;
/** px of movement that turns the press into a drag (0 = immediately). */
threshold?: number;
- onMove?: (event: React.PointerEvent<HTMLElement>, payload: T) => void;
+ /** Movement, as the native event: the gesture is tracked on the window, not on the element. */
+ onMove?: (event: PointerEvent, payload: T) => void;
/** Release: `dragged` distinguishes a completed drag from a plain tap. */
onEnd?: (payload: T, dragged: boolean) => void;
/** Abandoned gesture (pointercancel): clear visuals, apply nothing. */
@@ -19,36 +40,92 @@ export function usePointerDrag<T>(options: {
}) {
const latest = useRef(options);
latest.current = options;
- const state = useRef<{ payload: T; x: number; y: number; started: boolean } | null>(null);
+ const state = useRef<DragState<T> | null>(null);
+
+ // An unmount mid-gesture would otherwise leave the window listening for a pointer nothing
+ // is following any more.
+ useEffect(() => () => state.current?.release(), []);
return useMemo(
() => ({
onPointerDown: (event: React.PointerEvent<HTMLElement>) => {
if (event.button !== 0) return;
+ // A second press while a gesture is live (another finger, a release the window never
+ // saw): abandon the old one rather than leave its visuals stuck.
+ const running = state.current;
+ if (running) {
+ running.release();
+ latest.current.onCancel?.();
+ }
const payload = latest.current.begin(event);
if (payload === null) return;
- state.current = { payload, x: event.clientX, y: event.clientY, started: false };
- event.currentTarget.setPointerCapture(event.pointerId);
- },
- onPointerMove: (event: React.PointerEvent<HTMLElement>) => {
- const drag = state.current;
- if (!drag) return;
- if (!drag.started) {
- const threshold = latest.current.threshold ?? 5;
- if (Math.hypot(event.clientX - drag.x, event.clientY - drag.y) < threshold) return;
- drag.started = true;
+ const element = event.currentTarget;
+ const pointerId = event.pointerId;
+ let captured = false;
+
+ const onMove = (native: PointerEvent) => {
+ const drag = state.current;
+ if (!drag || native.pointerId !== drag.pointerId) return;
+ if (!drag.started) {
+ const threshold = latest.current.threshold ?? 5;
+ if (Math.hypot(native.clientX - drag.x, native.clientY - drag.y) < threshold) return;
+ drag.started = true;
+ }
+ latest.current.onMove?.(native, drag.payload);
+ };
+ const onUp = (native: PointerEvent) => {
+ const drag = state.current;
+ if (!drag || native.pointerId !== drag.pointerId) return;
+ drag.release();
+ latest.current.onEnd?.(drag.payload, drag.started);
+ };
+ const onPointerCancel = (native: PointerEvent) => {
+ const drag = state.current;
+ if (!drag || native.pointerId !== drag.pointerId) return;
+ drag.release();
+ latest.current.onCancel?.();
+ };
+ // Capture taken away mid-gesture. Nothing ends here: the window listeners carry the
+ // gesture on, and there is simply no capture left to release.
+ const onLostCapture = () => {
+ captured = false;
+ };
+ const release = () => {
+ state.current = null;
+ window.removeEventListener("pointermove", onMove, true);
+ window.removeEventListener("pointerup", onUp, true);
+ window.removeEventListener("pointercancel", onPointerCancel, true);
+ element.removeEventListener("lostpointercapture", onLostCapture);
+ if (!captured) return;
+ captured = false;
+ try {
+ element.releasePointerCapture(pointerId);
+ } catch {
+ // The pointer is already gone; there is nothing left to release.
+ }
+ };
+
+ state.current = {
+ payload,
+ pointerId,
+ x: event.clientX,
+ y: event.clientY,
+ started: false,
+ release,
+ };
+ // Capture phase: a handler that stops propagation somewhere in between must not be
+ // able to strand the gesture.
+ window.addEventListener("pointermove", onMove, true);
+ window.addEventListener("pointerup", onUp, true);
+ window.addEventListener("pointercancel", onPointerCancel, true);
+ element.addEventListener("lostpointercapture", onLostCapture);
+ try {
+ element.setPointerCapture(pointerId);
+ captured = true;
+ } catch {
+ // A pointer the browser has already finished with refuses capture; the gesture
+ // runs on the window listeners either way.
}
- latest.current.onMove?.(event, drag.payload);
- },
- onPointerUp: (event: React.PointerEvent<HTMLElement>) => {
- const drag = state.current;
- state.current = null;
- event.currentTarget.releasePointerCapture?.(event.pointerId);
- if (drag) latest.current.onEnd?.(drag.payload, drag.started);
- },
- onPointerCancel: () => {
- state.current = null;
- latest.current.onCancel?.();
},
}),
[],
diff --git a/packages/web/src/features/settings/appearance-section.tsx b/packages/web/src/features/settings/appearance-section.tsx
index fae4c677..819b3c92 100644
--- a/packages/web/src/features/settings/appearance-section.tsx
+++ b/packages/web/src/features/settings/appearance-section.tsx
@@ -3,10 +3,19 @@
* user menu. Everything applies on the spot (the theme store persists per browser), so
* there is no Save button. The terminal keeps its own theme row because plenty of people
* pin a dark terminal inside a light app; it follows the app unless pinned (see
- * TerminalThemeMode).
+ * TerminalThemeMode). The workbench launcher's row is here rather than with the chat's own
+ * settings because it is the same kind of choice: whether a piece of chrome is drawn.
*/
+import { useSyncExternalStore } from "react";
import { S } from "../../lib/strings";
import { Segmented } from "../../components/ui/segmented";
+import { Switch } from "../../components/ui/switch";
+import {
+ launcherHiddenVersion,
+ readLauncherHidden,
+ subscribeLauncherHidden,
+ writeLauncherHidden,
+} from "../dock/dock-launcher-state";
import { useTheme } from "../../state/theme";
import type { FontScale, TerminalThemeMode, ThemeMode } from "../../state/theme";
import { AccentPicker, PrefRow } from "./setting-row";
@@ -22,6 +31,9 @@ export function AppearanceSection() {
terminalMode,
setTerminalMode,
} = useTheme();
+ // The fan's "hide launcher" entry writes the same preference, so this row follows it.
+ useSyncExternalStore(subscribeLauncherHidden, launcherHiddenVersion);
+ const launcherShown = !readLauncherHidden();
const themeOptions: ReadonlyArray<{ value: ThemeMode; label: string }> = [
{ value: "light", label: S.settings.themeLight },
@@ -54,6 +66,9 @@ export function AppearanceSection() {
<PrefRow label={S.settings.accent} info={S.settings.accentInfo}>
<AccentPicker value={accent} onChange={setAccent} />
</PrefRow>
+ <PrefRow label={S.settings.launcher} info={S.settings.launcherInfo}>
+ <Switch checked={launcherShown} onChange={(shown) => writeLauncherHidden(!shown)} />
+ </PrefRow>
</div>
);
}
diff --git a/packages/web/src/lib/install-scope.ts b/packages/web/src/lib/install-scope.ts
index 34914799..eefb5b7b 100644
--- a/packages/web/src/lib/install-scope.ts
+++ b/packages/web/src/lib/install-scope.ts
@@ -137,6 +137,18 @@ export const KEY_RULES: readonly KeyRule[] = [
scope: "browser",
why: "Side-panel width in px; its own module calls it a layout preference, not session data.",
},
+ {
+ kind: "exact",
+ key: "penguin.dock.launcherY",
+ scope: "browser",
+ why: "Where the floating dock launcher rests along the chat body's edge; chrome layout, holds no entity.",
+ },
+ {
+ kind: "exact",
+ key: "penguin.dock.launcherHidden",
+ scope: "browser",
+ why: "Whether the floating dock launcher shows at all; an appearance choice of this browser, and losing it would put a dismissed button back.",
+ },
{
kind: "exact",
key: "penguin.files.treeVisible",
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index 44c94f2e..ebea021c 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -100,6 +100,12 @@ export const en: Strings = {
killConfirmTitle: "Close this terminal?",
killConfirmBody: (name: string): string =>
`This ends the shell "${name}" — it cannot be restored.`,
+ launcher: "Shortcuts",
+ launcherCaption: "Shortcuts",
+ launcherPending: "a subagent awaits approval",
+ launcherPanels: "Shortcuts",
+ launcherHide: "Hide launcher",
+ launcherHiddenToast: "Launcher hidden — turn it back on in Settings › Appearance",
},
tracePanel: {
@@ -172,6 +178,9 @@ export const en: Strings = {
fontLarge: "L",
accent: "Accent",
accentInfo: "Interface accent color.",
+ launcher: "Shortcuts launcher",
+ launcherInfo:
+ "The round button floating on the conversation's right edge that fans out shortcuts to the workbench's panels and the terminal. Turning it off here removes it; the fan's \"Hide launcher\" entry does the same.",
currencyInfo: "Display currency for prices; storage is always USD.",
changePasswordInfo: "Change this account's sign-in password.",
accentNames: {
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 40c26f05..a9c52f0c 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -109,6 +109,20 @@ export const zh = {
/** Terminal tab ×: ends the shell for real, so it asks first. `name` is the tab label. */
killConfirmTitle: "关闭此终端?",
killConfirmBody: (name: string): string => `将结束 Shell「${name}」的进程,无法恢复。`,
+ /**
+ * The floating launcher on the chat body's right edge while the right dock is hidden.
+ * `launcherCaption` is printed under the ball at rest — the same words as the ball's
+ * accessible name — and gives way to the pointed-at entry's name while the fan is open.
+ */
+ launcher: "快捷方式",
+ launcherCaption: "快捷方式",
+ /** Appended to the launcher's accessible name while its amber dot shows. */
+ launcherPending: "子智能体有待审批",
+ /** The fan of entries the launcher opens (its accessible group name). */
+ launcherPanels: "快捷方式",
+ /** The fan's last entry: puts the launcher away until Appearance settings bring it back. */
+ launcherHide: "隐藏悬浮球",
+ launcherHiddenToast: "悬浮球已隐藏,可在 设置 › 外观 中重新开启",
},
/** The Trace dock panel (the current conversation's Trace files). */
@@ -179,6 +193,9 @@ export const zh = {
fontLarge: "大",
accent: "主题色",
accentInfo: "界面强调色。",
+ launcher: "快捷方式悬浮球",
+ launcherInfo:
+ "在对话正文右缘浮动的圆形按钮,展开后是工作台各块面板与终端的快捷方式;这里关掉后它就不再出现,展开里的「隐藏悬浮球」同样会关掉它。",
currencyInfo: "价格显示币种;存储始终为美元。",
changePasswordInfo: "更改当前账号的登录密码。",
accentNames: {
diff --git a/packages/web/src/styles.css b/packages/web/src/styles.css
index 394604ba..e851d184 100644
--- a/packages/web/src/styles.css
+++ b/packages/web/src/styles.css
@@ -255,6 +255,39 @@
.anim-fade {
animation: fade-in 120ms ease-out both;
}
+
+/* The dock launcher's fan (features/dock/dock-launcher.tsx): entries spring out of the ball
+ onto their places on the arc with a slight overshoot, and fold back into it without one.
+ Every entry's box sits ON the ball's centre; `--fan-x` / `--fan-y` are its own offset from
+ there, set per entry, and that translate is also the entry's resting inline transform — so
+ the reduced-motion block below, which drops the animation outright, leaves each entry
+ standing on the arc instead of collapsed onto the ball or hidden. */
+@keyframes launcher-fan-in {
+ from {
+ opacity: 0;
+ transform: translate(0, 0) scale(0.5);
+ }
+ to {
+ opacity: 1;
+ transform: translate(var(--fan-x, 0px), var(--fan-y, 0px));
+ }
+}
+@keyframes launcher-fan-out {
+ from {
+ opacity: 1;
+ transform: translate(var(--fan-x, 0px), var(--fan-y, 0px));
+ }
+ to {
+ opacity: 0;
+ transform: translate(0, 0) scale(0.5);
+ }
+}
+.launcher-fan-in {
+ animation: launcher-fan-in 260ms cubic-bezier(0.34, 1.56, 0.64, 1) both;
+}
+.launcher-fan-out {
+ animation: launcher-fan-out 140ms ease-in both;
+}
/* Message item entrance. */
.anim-msg {
animation: msg-in 180ms ease-out both;
diff --git a/packages/web/test/dock-launcher-state.test.ts b/packages/web/test/dock-launcher-state.test.ts
new file mode 100644
index 00000000..747e5146
--- /dev/null
+++ b/packages/web/test/dock-launcher-state.test.ts
@@ -0,0 +1,342 @@
+/**
+ * The floating dock launcher's decisions (features/dock/dock-launcher-state.ts): when it
+ * shows, how its resting position clamps to the chat body and round-trips through the
+ * stored ratio, whether the user put it away, how a drag is bounded, and where on the ring
+ * its entries land.
+ */
+import { describe, expect, it } from "vitest";
+import {
+ DEFAULT_LAUNCHER_RATIO,
+ FAN_ENTRY_GAP,
+ FAN_ENTRY_SIZE,
+ FAN_MAX_RADIUS,
+ FAN_MIN_RADIUS,
+ LAUNCHER_CAPTION_HEIGHT,
+ LAUNCHER_EDGE_MARGIN,
+ LAUNCHER_HIDDEN_KEY,
+ LAUNCHER_SIZE,
+ LAUNCHER_Y_KEY,
+ clampLauncherTop,
+ dragPosition,
+ fanLayout,
+ launcherHiddenVersion,
+ launcherRatioFromTop,
+ launcherTopFromRatio,
+ parseLauncherRatio,
+ readLauncherHidden,
+ readLauncherRatio,
+ shouldShowLauncher,
+ subscribeLauncherHidden,
+ writeLauncherHidden,
+ writeLauncherRatio,
+} from "../src/features/dock/dock-launcher-state";
+import type {
+ FanSlot,
+ LauncherStorage,
+ LauncherVisibility,
+} from "../src/features/dock/dock-launcher-state";
+
+const BODY = 600;
+const MAX_TOP = BODY - LAUNCHER_SIZE - LAUNCHER_CAPTION_HEIGHT - LAUNCHER_EDGE_MARGIN;
+
+function fakeStorage(initial: Record<string, string> = {}): LauncherStorage & {
+ map: Map<string, string>;
+} {
+ const map = new Map(Object.entries(initial));
+ return {
+ map,
+ getItem: (key) => map.get(key) ?? null,
+ setItem: (key, value) => void map.set(key, value),
+ };
+}
+
+describe("visibility", () => {
+ const at = (v: Partial<LauncherVisibility>): boolean =>
+ shouldShowLauncher({
+ rightDockVisible: false,
+ bottomDockVisible: false,
+ narrow: false,
+ hidden: false,
+ ...v,
+ });
+
+ it("shows on a wide layout while the right dock — the one it opens into — is hidden", () => {
+ expect(at({})).toBe(true);
+ expect(at({ bottomDockVisible: true })).toBe(true);
+ });
+
+ it("hides while the right dock is on screen", () => {
+ expect(at({ rightDockVisible: true })).toBe(false);
+ });
+
+ it("shows on a narrow layout while neither dock is up", () => {
+ expect(at({ narrow: true })).toBe(true);
+ });
+
+ it("hides behind the narrow merged surface, whichever dock put it there", () => {
+ expect(at({ narrow: true, rightDockVisible: true })).toBe(false);
+ expect(at({ narrow: true, bottomDockVisible: true })).toBe(false);
+ });
+
+ it("stays away once the user put it away, whatever the layout", () => {
+ expect(at({ hidden: true })).toBe(false);
+ expect(at({ hidden: true, narrow: true })).toBe(false);
+ });
+});
+
+describe("put away", () => {
+ it('hides only on the stored "1"; anything else — absent, stale, garbage — shows it', () => {
+ expect(readLauncherHidden(fakeStorage({ [LAUNCHER_HIDDEN_KEY]: "1" }))).toBe(true);
+ expect(readLauncherHidden(fakeStorage())).toBe(false);
+ expect(readLauncherHidden(fakeStorage({ [LAUNCHER_HIDDEN_KEY]: "0" }))).toBe(false);
+ expect(readLauncherHidden(fakeStorage({ [LAUNCHER_HIDDEN_KEY]: "yes" }))).toBe(false);
+ });
+
+ it("writes both states and notifies subscribers, so both renderers of it follow", () => {
+ const storage = fakeStorage();
+ let seen = 0;
+ const stop = subscribeLauncherHidden(() => {
+ seen += 1;
+ });
+ const before = launcherHiddenVersion();
+ writeLauncherHidden(true, storage);
+ expect(readLauncherHidden(storage)).toBe(true);
+ writeLauncherHidden(false, storage);
+ expect(readLauncherHidden(storage)).toBe(false);
+ expect(seen).toBe(2);
+ expect(launcherHiddenVersion()).toBe(before + 2);
+ stop();
+ writeLauncherHidden(true, storage);
+ expect(seen).toBe(2);
+ });
+
+ it("survives a storage that throws, and still tells this session", () => {
+ const broken: LauncherStorage = {
+ getItem: () => {
+ throw new Error("blocked");
+ },
+ setItem: () => {
+ throw new Error("blocked");
+ },
+ };
+ expect(readLauncherHidden(broken)).toBe(false);
+ const before = launcherHiddenVersion();
+ expect(() => writeLauncherHidden(true, broken)).not.toThrow();
+ expect(launcherHiddenVersion()).toBe(before + 1);
+ });
+});
+
+describe("clamping", () => {
+ it("keeps a top offset inside the body with the edge margin and the caption", () => {
+ expect(clampLauncherTop(200, BODY)).toBe(200);
+ expect(clampLauncherTop(-50, BODY)).toBe(LAUNCHER_EDGE_MARGIN);
+ expect(clampLauncherTop(5000, BODY)).toBe(MAX_TOP);
+ });
+
+ it("pins the ball at the top margin when the body is too short for it", () => {
+ expect(clampLauncherTop(30, 40)).toBe(LAUNCHER_EDGE_MARGIN);
+ });
+
+ it("leaves room below the ball for its caption, on top of the margin", () => {
+ const ballBottom = clampLauncherTop(5000, BODY) + LAUNCHER_SIZE;
+ expect(BODY - ballBottom).toBe(LAUNCHER_CAPTION_HEIGHT + LAUNCHER_EDGE_MARGIN);
+ });
+
+ it("treats a non-finite offset as the top margin", () => {
+ expect(clampLauncherTop(Number.NaN, BODY)).toBe(LAUNCHER_EDGE_MARGIN);
+ });
+});
+
+describe("ratio round trip", () => {
+ it("centres the ball for the default ratio", () => {
+ const top = launcherTopFromRatio(DEFAULT_LAUNCHER_RATIO, BODY);
+ expect(top + LAUNCHER_SIZE / 2).toBe(BODY / 2);
+ });
+
+ it("clamps the extremes to the margins", () => {
+ expect(launcherTopFromRatio(0, BODY)).toBe(LAUNCHER_EDGE_MARGIN);
+ expect(launcherTopFromRatio(1, BODY)).toBe(MAX_TOP);
+ });
+
+ it("recovers the ratio a top offset was derived from", () => {
+ for (const ratio of [0.2, 0.5, 0.8]) {
+ expect(launcherRatioFromTop(launcherTopFromRatio(ratio, BODY), BODY)).toBeCloseTo(ratio, 6);
+ }
+ });
+
+ it("falls back to the default ratio for a body with no height", () => {
+ expect(launcherRatioFromTop(100, 0)).toBe(DEFAULT_LAUNCHER_RATIO);
+ });
+});
+
+describe("stored ratio", () => {
+ it("parses a decimal and clamps it into [0, 1]", () => {
+ expect(parseLauncherRatio("0.25")).toBe(0.25);
+ expect(parseLauncherRatio("1.7")).toBe(1);
+ expect(parseLauncherRatio("-2")).toBe(0);
+ });
+
+ it("rejects anything that is not a number", () => {
+ expect(parseLauncherRatio(null)).toBeNull();
+ expect(parseLauncherRatio(undefined)).toBeNull();
+ expect(parseLauncherRatio("")).toBeNull();
+ expect(parseLauncherRatio("middle")).toBeNull();
+ expect(parseLauncherRatio("Infinity")).toBeNull();
+ });
+
+ it("reads back what it wrote, under the one global key", () => {
+ const storage = fakeStorage();
+ writeLauncherRatio(0.3, storage);
+ expect(storage.map.get(LAUNCHER_Y_KEY)).toBe("0.3");
+ expect(readLauncherRatio(storage)).toBe(0.3);
+ });
+
+ it("falls back to the default when the entry is missing or malformed", () => {
+ expect(readLauncherRatio(fakeStorage())).toBe(DEFAULT_LAUNCHER_RATIO);
+ expect(readLauncherRatio(fakeStorage({ [LAUNCHER_Y_KEY]: "{}" }))).toBe(DEFAULT_LAUNCHER_RATIO);
+ });
+
+ it("survives a storage that throws", () => {
+ const broken: LauncherStorage = {
+ getItem: () => {
+ throw new Error("blocked");
+ },
+ setItem: () => {
+ throw new Error("blocked");
+ },
+ };
+ expect(readLauncherRatio(broken)).toBe(DEFAULT_LAUNCHER_RATIO);
+ expect(() => writeLauncherRatio(0.4, broken)).not.toThrow();
+ });
+});
+
+describe("drag", () => {
+ it("tracks the pointer along the edge while inside the bounds", () => {
+ expect(dragPosition(200, 0, 40, BODY)).toEqual({ x: 0, top: 240 });
+ });
+
+ it("rubberbands past the body's ends instead of stopping or escaping", () => {
+ const past = dragPosition(MAX_TOP, 0, 300, BODY);
+ expect(past.top).toBeGreaterThan(MAX_TOP);
+ expect(past.top).toBeLessThan(MAX_TOP + 60);
+ const further = dragPosition(MAX_TOP, 0, 600, BODY);
+ expect(further.top).toBeGreaterThan(past.top);
+ const above = dragPosition(LAUNCHER_EDGE_MARGIN, 0, -300, BODY);
+ expect(above.top).toBeLessThan(LAUNCHER_EDGE_MARGIN);
+ expect(above.top).toBeGreaterThan(LAUNCHER_EDGE_MARGIN - 60);
+ });
+
+ it("lets the ball be pulled off the edge only a damped distance", () => {
+ const pulled = dragPosition(200, -120, 0, BODY);
+ expect(pulled.x).toBeLessThan(0);
+ expect(pulled.x).toBeGreaterThan(-40);
+ expect(Math.abs(pulled.x)).toBeLessThan(120);
+ expect(dragPosition(200, 120, 0, BODY).x).toBeGreaterThan(0);
+ });
+
+ it("settles a released drag back inside the body", () => {
+ const { top } = dragPosition(MAX_TOP, 0, 300, BODY);
+ expect(clampLauncherTop(top, BODY)).toBe(MAX_TOP);
+ });
+});
+
+describe("fan layout", () => {
+ /** Five panel kinds, the terminal, and the hide entry. */
+ const COUNT = 7;
+ const TALL = 900;
+ /** The ball centred in a body tall enough for the whole semicircle. */
+ const MIDDLE = TALL / 2 - LAUNCHER_SIZE / 2;
+ const ENTRY_RADIUS = FAN_ENTRY_SIZE / 2;
+ /** The least distance two neighbouring entries' centres may be from each other. */
+ const MIN_SPACING = FAN_ENTRY_SIZE + FAN_ENTRY_GAP;
+
+ /** The slot's angle on the arc: 0 straight up, pi/2 straight left, pi straight down. */
+ const angleOf = (slot: FanSlot): number => Math.atan2(-slot.x, -slot.y);
+ /** The ring the slots were laid out on. */
+ const radiusOf = (slots: FanSlot[]): number => Math.hypot(slots[0]!.x, slots[0]!.y);
+
+ function expectInside(slots: FanSlot[], top: number, bodyHeight: number): void {
+ const centerY = top + LAUNCHER_SIZE / 2;
+ for (const slot of slots) {
+ expect(centerY + slot.y - ENTRY_RADIUS).toBeGreaterThanOrEqual(0);
+ expect(centerY + slot.y + ENTRY_RADIUS).toBeLessThanOrEqual(bodyHeight);
+ }
+ }
+
+ /** No two entries closer than a diameter plus the gap — the rule the radius is solved for. */
+ function expectApart(slots: FanSlot[]): void {
+ for (let i = 1; i < slots.length; i += 1) {
+ const previous = slots[i - 1]!;
+ const slot = slots[i]!;
+ expect(Math.hypot(slot.x - previous.x, slot.y - previous.y)).toBeGreaterThanOrEqual(
+ // The radius is solved iteratively; a thousandth of a pixel is the solver's own tolerance.
+ MIN_SPACING - 1e-3,
+ );
+ }
+ }
+
+ it("spreads the entries evenly over the whole semicircle in the middle of a tall body", () => {
+ const angles = fanLayout(MIDDLE, TALL, COUNT).map(angleOf);
+ expect(angles[0]).toBeCloseTo(0, 6);
+ expect(angles.at(-1)).toBeCloseTo(Math.PI, 6);
+ const step = Math.PI / (COUNT - 1);
+ for (let i = 1; i < angles.length; i += 1) {
+ expect(angles[i]! - angles[i - 1]!).toBeCloseTo(step, 6);
+ }
+ });
+
+ it("puts every entry on one circle, left of the ball, in top-to-bottom order", () => {
+ const slots = fanLayout(MIDDLE, TALL, COUNT);
+ let previousY = -Infinity;
+ for (const slot of slots) {
+ expect(Math.hypot(slot.x, slot.y)).toBeCloseTo(FAN_MIN_RADIUS, 6);
+ expect(slot.x).toBeLessThanOrEqual(0);
+ expect(slot.y).toBeGreaterThan(previousY);
+ previousY = slot.y;
+ }
+ expectApart(slots);
+ });
+
+ it("rests at the smallest radius mid-body and widens only where the arc is trimmed", () => {
+ expect(radiusOf(fanLayout(MIDDLE, TALL, COUNT))).toBeCloseTo(FAN_MIN_RADIUS, 6);
+ // Against the body's top edge the usable arc is about half a semicircle, so the same
+ // entries need a wider ring to keep their spacing.
+ expect(radiusOf(fanLayout(LAUNCHER_EDGE_MARGIN, TALL, COUNT))).toBeGreaterThan(FAN_MIN_RADIUS);
+ });
+
+ it("stops widening the ring in a body too short to space the entries at all", () => {
+ // A body barely taller than the entries has no radius that spaces them: the arc that
+ // still fits keeps a bounded length however far the ring is pushed out.
+ const short = 200;
+ const slots = fanLayout(clampLauncherTop(short / 2, short), short, COUNT);
+ expect(radiusOf(slots)).toBeLessThanOrEqual(FAN_MAX_RADIUS);
+ expectInside(slots, clampLauncherTop(short / 2, short), short);
+ });
+
+ it("trims the arc's top near the body's top, keeping every entry inside and apart", () => {
+ const slots = fanLayout(LAUNCHER_EDGE_MARGIN, TALL, COUNT);
+ expectInside(slots, LAUNCHER_EDGE_MARGIN, TALL);
+ expectApart(slots);
+ // What is left runs from around straight left down to straight below the ball.
+ expect(angleOf(slots[0]!)).toBeGreaterThan(Math.PI / 3);
+ expect(angleOf(slots.at(-1)!)).toBeCloseTo(Math.PI, 6);
+ });
+
+ it("trims the arc's bottom near the body's bottom, keeping every entry inside and apart", () => {
+ const top = clampLauncherTop(TALL, TALL);
+ const slots = fanLayout(top, TALL, COUNT);
+ expectInside(slots, top, TALL);
+ expectApart(slots);
+ expect(angleOf(slots[0]!)).toBeCloseTo(0, 6);
+ expect(angleOf(slots.at(-1)!)).toBeLessThan(Math.PI - 0.1);
+ });
+
+ it("centres a lone entry on the span and puts a pair at its ends", () => {
+ const [only] = fanLayout(MIDDLE, TALL, 1);
+ expect(angleOf(only!)).toBeCloseTo(Math.PI / 2, 6);
+ expect(Math.hypot(only!.x, only!.y)).toBeCloseTo(FAN_MIN_RADIUS, 6);
+ const pair = fanLayout(MIDDLE, TALL, 2);
+ expect(pair.map(angleOf)).toEqual([expect.closeTo(0, 6), expect.closeTo(Math.PI, 6)]);
+ expect(fanLayout(MIDDLE, TALL, 0)).toEqual([]);
+ });
+});
diff --git a/packages/web/test/icon-scale.test.ts b/packages/web/test/icon-scale.test.ts
index 3e743c00..00ec327e 100644
--- a/packages/web/test/icon-scale.test.ts
+++ b/packages/web/test/icon-scale.test.ts
@@ -60,6 +60,17 @@ describe("one glyph, one home", () => {
expect(occurrences("M9 5l7 7-7 7")).toEqual(["components/ui/chevron.tsx"]);
});
+ // The two dock edges are drawn from two places at once — the chat toolbar's pull-open
+ // buttons and the dock header's move-dock buttons — which is exactly how the marks above
+ // accumulated their copies.
+ it("draws the bottom-dock mark in exactly one place", () => {
+ expect(occurrences("M4 5h16v14H4zM4 14h16")).toEqual(["components/ui/icons.tsx"]);
+ });
+
+ it("draws the right-dock mark in exactly one place", () => {
+ expect(occurrences("M4 5h16v14H4zM14 5v14")).toEqual(["components/ui/icons.tsx"]);
+ });
+
it("draws the background-task trace in exactly one place", () => {
// Three surfaces draw it now — a session row, the chat header pill and a backgrounded
// tool row — which is how the paths above ended up hand-typed five times each.
diff --git a/packages/web/test/install-scope.test.ts b/packages/web/test/install-scope.test.ts
index c7ec5151..27996d46 100644
--- a/packages/web/test/install-scope.test.ts
+++ b/packages/web/test/install-scope.test.ts
@@ -79,6 +79,8 @@ function populated(): ReturnType<typeof memStorage> {
"penguin.sidebarSortMode": "manual",
"penguin.sidebarNavGroupCollapsed": "collapsed",
"penguin.steerMode": "followup",
+ "penguin.dock.launcherY": "0.25",
+ "penguin.dock.launcherHidden": "1",
"penguin.files.treeVisible": "0",
"penguin.files.treeWidth": "220",
"penguin.files.editorWrap": "1",
@@ -103,6 +105,8 @@ const PREFERENCE_KEYS = [
"penguin.sidebarSortMode",
"penguin.sidebarNavGroupCollapsed",
"penguin.steerMode",
+ "penguin.dock.launcherY",
+ "penguin.dock.launcherHidden",
"penguin.files.treeVisible",
"penguin.files.treeWidth",
"penguin.files.editorWrap",