From f15a6ec42696dd9ed5241df28ce87c259e5d9e80 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Sun, 5 Jul 2026 14:03:15 +0800
Subject: [PATCH 01/10] feat(ui): establish Base UI style-hook convention
 (data-slot + native state attrs) (#520 PR5 item 23)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Foundation commit for PR5 — the convention the disclosure / tooltip /
number-field / input migrations in the following commits follow.

data-slot: add data-slot="<name>" to all 20 Base UI wrappers in ui.tsx
(Button / Separator / Checkbox / DialogBackdrop / DialogPopup / Select
Trigger/List/Popup/Group/GroupLabel/Separator/Item / FieldDescription /
Label / Switch / Toggle / ToggleGroup / RadioGroup / Radio / Progress).
The ./primitives/ wrappers (accordion / alert / badge / …) already do
this; ui.tsx wrappers did not. data-slot is a stable CSS targeting hook
that survives className drift. Base UI does not emit data-slot itself, so
the wrapper owns it. No CSS targets these yet — this is forward-looking
convention, a visual no-op.

State-attribute form: adopt Base UI's native attribute-presence form
([data-active] / [data-open] / [data-checked] / [data-selected] /
[data-pressed] / [data-highlighted] / [data-disabled]), NOT the
attribute-value form ([data-active="true"]). Maka's renderer CSS has
zero state-attribute selectors today, so there is nothing to break and no
override layer to maintain. A per-component hook map (Tabs data-active /
Select data-[highlighted]/data-[selected] / Checkbox/Switch/Radio
data-[checked] / Toggle data-[pressed] / Dialog/Tooltip/Popover data-[open])
is documented in a doc comment at the top of ui.tsx, along with the
whitelisted CSS var hooks (--anchor-* / --available-* / --active-tab-*).
className(state) function form is deferred — add only when a migration in
this PR actually needs state-based classes.

style-hook-convention-contract.test.ts locks the data-slot rule: every
ui.tsx wrapper that forwards to a <Base*> component must carry data-slot,
and the convention doc comment must stay present. Hand-written native
elements (legacy Input / Textarea / Badge) are out of scope until they
retire onto a Base UI primitive (input canonical, commit 5).

Verification: 1972/1972 desktop tests pass (+4 contract). typecheck clean.
renderer build clean. Visual no-op (data-slot is an attribute; no CSS
targets it yet).
---
 .../style-hook-convention-contract.test.ts    | 107 ++++++++++++++++++
 packages/ui/src/ui.tsx                        |  78 +++++++++++--
 2 files changed, 173 insertions(+), 12 deletions(-)
 create mode 100644 apps/desktop/src/main/__tests__/style-hook-convention-contract.test.ts

diff --git a/apps/desktop/src/main/__tests__/style-hook-convention-contract.test.ts b/apps/desktop/src/main/__tests__/style-hook-convention-contract.test.ts
new file mode 100644
index 0000000000..b976bbc6a1
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/style-hook-convention-contract.test.ts
@@ -0,0 +1,107 @@
+/**
+ * PR-STYLE-HOOK-CONVENTION-0 (issue #520 PR5 item 23, 2026-07-05):
+ * every Base UI wrapper in `packages/ui/src/ui.tsx` exposes a `data-slot`
+ * attribute so CSS can target `[data-slot="..."]` (a stable hook that
+ * survives className drift), matching the `./primitives/` wrappers that
+ * already do this (accordion / alert / badge / …). New wrappers
+ * (Collapsible / Tooltip / NumberField / …) follow the same rule.
+ *
+ * Boolean state hooks adopt Base UI's native attribute-presence form
+ * (`[data-active]` / `[data-open]` / `[data-checked]` / `[data-selected]` /
+ * `[data-pressed]` / `[data-highlighted]` / `[data-disabled]`), NOT the
+ * attribute-value form (`[data-active="true"]`). Maka's renderer CSS has
+ * zero state-attribute selectors today, so adopting Base UI's form breaks
+ * nothing and avoids an override layer. The per-component hook map lives in
+ * the doc comment at the top of ui.tsx.
+ *
+ * This contract locks the data-slot rule: a wrapper that forwards props to a
+ * `Base*` Base UI component must carry `data-slot`. It does NOT lock the
+ * state-attribute decision (that is a "don't override" rule, enforced by the
+ * absence of `[data-active="true"]`-style overrides, which the existing
+ * CSS-scan contracts already cover indirectly).
+ */
+
+import { strict as assert } from 'node:assert';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { describe, it } from 'node:test';
+import { REPO_ROOT } from './css-test-helpers.js';
+
+const UI_FILE = resolve(REPO_ROOT, 'packages/ui/src/ui.tsx');
+
+/** A top-level wrapper declaration: `export const X = forwardRef...` /
+ *  `const X = forwardRef...` / `export function X(...)` at column 0. */
+const WRAPPER_DECL_RE = /^(?:export (?:const|function)|const) [A-Z][A-Za-z0-9]*\b/gm;
+
+/** A Base UI component JSX tag: `<BaseButton`, `<BaseCheckbox.Root`, etc. */
+const BASE_TAG_RE = /<Base[A-Z][A-Za-z]*\b/;
+
+/** Split ui.tsx into wrapper blocks (each starts at a top-level wrapper
+ *  declaration and runs until the next one). Returns the block text + the
+ *  leading declaration name for labeling. */
+function wrapperBlocks(source: string): Array<{ name: string; body: string }> {
+  const matches = [...source.matchAll(WRAPPER_DECL_RE)];
+  const blocks: Array<{ name: string; body: string }> = [];
+  for (let i = 0; i < matches.length; i++) {
+    const start = matches[i].index;
+    const end = i + 1 < matches.length ? matches[i + 1].index : source.length;
+    const body = source.slice(start, end);
+    const name = matches[i][0].replace(/^(?:export )?(?:const|function) /, '');
+    blocks.push({ name, body });
+  }
+  return blocks;
+}
+
+describe('PR-STYLE-HOOK-CONVENTION-0 contract', () => {
+  it('every ui.tsx wrapper that forwards to a Base* component carries data-slot', async () => {
+    const source = await readFile(UI_FILE, 'utf8');
+    const blocks = wrapperBlocks(source);
+    const offenders: string[] = [];
+    for (const { name, body } of blocks) {
+      // Only wrappers that render a `<Base*>` Base UI component are in scope.
+      // Hand-written native elements (the legacy Input / Textarea <input> /
+      // <textarea>, and Badge <span>) are out of the rule until they retire
+      // onto a Base UI primitive.
+      if (!BASE_TAG_RE.test(body)) continue;
+      // The wrapper must carry at least one data-slot on the Base root it
+      // forwards to. (Sub-parts like BaseSwitch.Thumb / BaseCheckbox.Indicator
+      // are not required here — only the root wrapper.)
+      if (!/data-slot=/.test(body)) {
+        offenders.push(`${name}: forwards to a Base UI component but has no data-slot — add data-slot="<name>" to the Base root`);
+      }
+    }
+    assert.deepEqual(offenders, [], `Offenders:\n  ${offenders.join('\n  ')}`);
+  });
+
+  it('ui.tsx documents the style-hook convention (state-attribute form + hook map + data-slot rule)', async () => {
+    const source = await readFile(UI_FILE, 'utf8');
+    // The convention doc comment at the top of ui.tsx. Pinning the heading
+    // keeps the decision from being silently deleted.
+    assert.match(source, /Base UI style-hook convention/, 'ui.tsx must document the style-hook convention');
+    assert.match(source, /attribute-presence form/, 'the doc must state the state-attribute form decision');
+    assert.match(source, /data-active/, 'the doc must list the per-component hook map');
+  });
+});
+
+describe('style-hook convention negative cases', () => {
+  it('wrapperBlocks splits on top-level wrapper declarations', () => {
+    const src = 'export const Button = forwardRef(function Button() { return <BaseButton data-slot="button" />; });\nexport const Badge = function Badge() { return <span />; }';
+    const blocks = wrapperBlocks(src);
+    assert.equal(blocks.length, 2);
+    assert.equal(blocks[0].name, 'Button');
+    assert.equal(blocks[1].name, 'Badge');
+    assert.ok(BASE_TAG_RE.test(blocks[0].body), 'Button block has a Base tag');
+    assert.ok(!BASE_TAG_RE.test(blocks[1].body), 'Badge block has no Base tag');
+  });
+
+  it('a Base wrapper without data-slot is flagged, a native wrapper is spared', () => {
+    const src = 'export const Good = forwardRef(function Good() { return <BaseX data-slot="x" {...props} />; });\nexport const Bad = forwardRef(function Bad() { return <BaseY {...props} />; });\nexport const Native = function Native() { return <input />; }';
+    const blocks = wrapperBlocks(src);
+    const offenders: string[] = [];
+    for (const { name, body } of blocks) {
+      if (!BASE_TAG_RE.test(body)) continue;
+      if (!/data-slot=/.test(body)) offenders.push(name);
+    }
+    assert.deepEqual(offenders, ['Bad'], 'Bad (Base, no data-slot) flagged; Good (Base, data-slot) and Native (no Base) spared');
+  });
+});
\ No newline at end of file
diff --git a/packages/ui/src/ui.tsx b/packages/ui/src/ui.tsx
index 51681c676b..bd5c219d77 100644
--- a/packages/ui/src/ui.tsx
+++ b/packages/ui/src/ui.tsx
@@ -18,6 +18,36 @@ import { cn } from './utils.js';
 
 export { cn } from './utils.js';
 
+// === Base UI style-hook convention (#520 PR5 item 23) =========================
+// Every Base UI wrapper in this file exposes `data-slot="<name>"` so CSS can
+// target `[data-slot="..."]` (a stable hook that survives className drift);
+// the shared primitives in `./primitives/` already do this (accordion / alert /
+// badge / …), and new wrappers (Collapsible / Tooltip / NumberField / …) follow
+// the same rule. Hand-written native elements (the legacy `Input` / `Textarea`
+// below, and `Badge`) are out of this rule until they retire onto a Base UI
+// primitive.
+//
+// Boolean state hooks adopt Base UI's NATIVE attribute-presence form —
+// `[data-active]`, `[data-open]`, `[data-checked]`, `[data-selected]`,
+// `[data-pressed]`, `[data-highlighted]`, `[data-disabled]` — NOT the
+// attribute-value form `[data-active="true"]`. Maka's renderer CSS has zero
+// state-attribute selectors today, so adopting Base UI's form breaks nothing
+// and avoids maintaining an override layer. Per-component map:
+//   Tabs        data-active                 (primitives/tabs.tsx)
+//   Select      data-[highlighted] / data-[selected]
+//   Checkbox    data-[checked] / data-[disabled]
+//   Switch      data-[checked] / data-[disabled]
+//   Toggle      data-[pressed] / data-[disabled]
+//   Radio       data-[checked] / data-[disabled]
+//   Dialog      data-[open]                 (open state on the root)
+//   Tooltip / Popover  data-[open]
+//   Progress    (no boolean state)
+// CSS var hooks whitelisted for theming: `--anchor-*` (popups),
+// `--available-*` (popup max-height), `--active-tab-*` (Tabs indicator).
+// `className(state)` function form: deferred — add only when a migration in
+// this PR actually needs state-based classes; do not pre-design it.
+// ===========================================================================
+
 // PR-UIBUTTON-NAV-SIZE-0 (round 12/30): refactored so each
 // `size` variant owns its h-* / px-* / text-* utilities.
 // Previously these were baked into the base layer, which meant
@@ -78,6 +108,7 @@ export const Button = forwardRef<HTMLElement, ButtonProps>(function Button(
     <BaseButton
       ref={ref}
       className={cn(buttonVariants({ variant, size }), className)}
+      data-slot="button"
       {...props}
     />
   );
@@ -158,6 +189,7 @@ export const Separator = forwardRef<HTMLDivElement, React.ComponentPropsWithoutR
         orientation === 'horizontal' ? 'h-px w-full' : 'h-full w-px',
         className,
       )}
+      data-slot="separator"
       {...props}
     />
   );
@@ -177,6 +209,7 @@ export const Checkbox = forwardRef<
         'data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50',
         className,
       )}
+      data-slot="checkbox"
       {...props}
     >
       <BaseCheckbox.Indicator className="grid place-items-center">
@@ -206,27 +239,33 @@ const MODAL_POPUP_CLASS =
   'fixed left-1/2 top-1/2 z-50 grid max-h-[85dvh] w-[min(92vw,640px)] -translate-x-1/2 -translate-y-1/2 overflow-hidden rounded-xl bg-popover text-popover-foreground shadow-maka-panel';
 
 type ModalContentProps = React.ComponentPropsWithoutRef<typeof BaseDialog.Popup> & { showClose?: boolean };
+type ModalSlotPrefix = 'dialog' | 'alert-dialog';
+
+type ModalBackdropProps = { className?: string; 'data-slot'?: string };
+type ModalCloseProps = { className?: string; 'aria-label'?: string; 'data-slot'?: string; children?: React.ReactNode };
 
 function createModalContent(primitives: {
   Portal: React.ComponentType<{ children?: React.ReactNode }>;
-  Backdrop: React.ComponentType<{ className?: string }>;
+  Backdrop: React.ComponentType<ModalBackdropProps>;
   Popup: React.ForwardRefExoticComponent<React.ComponentPropsWithoutRef<typeof BaseDialog.Popup> & React.RefAttributes<HTMLDivElement>>;
-  Close: React.ComponentType<{ className?: string; 'aria-label'?: string; children?: React.ReactNode }>;
+  Close: React.ComponentType<ModalCloseProps>;
   defaultShowClose: boolean;
+  slotPrefix: ModalSlotPrefix;
 }) {
   return forwardRef<HTMLDivElement, ModalContentProps>(function ModalContent(
     { className, children, showClose = primitives.defaultShowClose, ...props },
     ref,
   ) {
-    const { Portal, Backdrop, Popup, Close } = primitives;
+    const { Portal, Backdrop, Popup, Close, slotPrefix } = primitives;
     return (
       <Portal>
-        <Backdrop className={MODAL_BACKDROP_CLASS} />
-        <Popup ref={ref} className={cn(MODAL_POPUP_CLASS, className)} {...props}>
+        <Backdrop className={MODAL_BACKDROP_CLASS} data-slot={`${slotPrefix}-backdrop`} />
+        <Popup ref={ref} className={cn(MODAL_POPUP_CLASS, className)} data-slot={`${slotPrefix}-popup`} {...props}>
           {showClose && (
             <Close
               className={cn(buttonVariants({ variant: 'quiet', size: 'icon-sm' }), 'absolute right-3 top-3')}
               aria-label="关闭"
+              data-slot={`${slotPrefix}-close`}
             >
               <X aria-hidden="true" />
             </Close>
@@ -244,6 +283,7 @@ export const DialogContent = createModalContent({
   Popup: BaseDialog.Popup,
   Close: BaseDialog.Close,
   defaultShowClose: true,
+  slotPrefix: 'dialog',
 });
 
 // AlertDialog — the alert variant locks modal + disables pointer dismissal,
@@ -256,6 +296,7 @@ export const AlertDialogContent = createModalContent({
   Popup: BaseAlertDialog.Popup,
   Close: BaseAlertDialog.Close,
   defaultShowClose: false,
+  slotPrefix: 'alert-dialog',
 });
 
 // Tabs: re-export the shared tab spec primitive (#499 P0-3). The tab spec
@@ -276,6 +317,7 @@ export const SelectTrigger = forwardRef<HTMLButtonElement, React.ComponentPropsW
     <BaseSelect.Trigger
       ref={ref}
       className={cn(buttonVariants({ variant: 'outline' }), 'justify-between', className)}
+      data-slot="select-trigger"
       {...props}
     >
       {children}
@@ -289,6 +331,12 @@ export const SelectTrigger = forwardRef<HTMLButtonElement, React.ComponentPropsW
 export const SelectValue = BaseSelect.Value;
 export const SelectPortal = BaseSelect.Portal;
 export const SelectPositioner = BaseSelect.Positioner;
+export const SelectList = forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof BaseSelect.List>>(function SelectList(
+  { className, ...props },
+  ref,
+) {
+  return <BaseSelect.List ref={ref} className={cn('max-h-[var(--available-height)] overflow-y-auto py-1', className)} data-slot="select-list" {...props} />;
+});
 export const SelectPopup = forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof BaseSelect.Popup>>(function SelectPopup(
   { className, ...props },
   ref,
@@ -300,25 +348,25 @@ export const SelectPopup = forwardRef<HTMLDivElement, React.ComponentPropsWithou
   // read as "can't select". Pin the popup to `--z-overlay` (300)
   // so it always floats above the modal it was triggered from
   // (WAWQAQ msg `d3ea9a33` 2026-06-26).
-  return <BaseSelect.Popup ref={ref} className={cn('z-[var(--z-overlay)] min-w-40 rounded-md bg-popover p-1 text-popover-foreground shadow-maka-panel', className)} {...props} />;
+  return <BaseSelect.Popup ref={ref} className={cn('z-[var(--z-overlay)] min-w-40 rounded-md bg-popover p-1 text-popover-foreground shadow-maka-panel', className)} data-slot="select-popup" {...props} />;
 });
 export const SelectGroup = forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof BaseSelect.Group>>(function SelectGroup(
   { className, ...props },
   ref,
 ) {
-  return <BaseSelect.Group ref={ref} className={cn('py-1', className)} {...props} />;
+  return <BaseSelect.Group ref={ref} className={cn('py-1', className)} data-slot="select-group" {...props} />;
 });
 export const SelectGroupLabel = forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof BaseSelect.GroupLabel>>(function SelectGroupLabel(
   { className, ...props },
   ref,
 ) {
-  return <BaseSelect.GroupLabel ref={ref} className={cn('px-2 py-1 text-xs font-medium text-foreground-secondary', className)} {...props} />;
+  return <BaseSelect.GroupLabel ref={ref} className={cn('px-2 py-1 text-xs font-medium text-foreground-secondary', className)} data-slot="select-group-label" {...props} />;
 });
 export const SelectSeparator = forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof BaseSelect.Separator>>(function SelectSeparator(
   { className, ...props },
   ref,
 ) {
-  return <BaseSelect.Separator ref={ref} className={cn('my-1 h-px bg-border', className)} {...props} />;
+  return <BaseSelect.Separator ref={ref} className={cn('my-1 h-px bg-border', className)} data-slot="select-separator" {...props} />;
 });
 
 export const SelectItem = forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof BaseSelect.Item>>(function SelectItem(
@@ -329,6 +377,7 @@ export const SelectItem = forwardRef<HTMLDivElement, React.ComponentPropsWithout
     <BaseSelect.Item
       ref={ref}
       className={cn('grid cursor-default grid-cols-[1rem_1fr] items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none data-[highlighted]:bg-muted data-[selected]:text-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50', className)}
+      data-slot="select-item"
       {...props}
     >
       <span className="flex h-4 w-4 items-center justify-center" aria-hidden="true">
@@ -354,13 +403,13 @@ export const FieldDescription = forwardRef<HTMLParagraphElement, React.Component
   { className, ...props },
   ref,
 ) {
-  return <BaseField.Description ref={ref} className={cn('text-xs text-foreground-secondary', className)} {...props} />;
+  return <BaseField.Description ref={ref} className={cn('text-xs text-foreground-secondary', className)} data-slot="field-description" {...props} />;
 });
 export const Label = forwardRef<HTMLLabelElement, React.ComponentPropsWithoutRef<typeof BaseField.Label>>(function Label(
   { className, ...props },
   ref,
 ) {
-  return <BaseField.Label ref={ref} className={cn('text-sm font-medium text-foreground', className)} {...props} />;
+  return <BaseField.Label ref={ref} className={cn('text-sm font-medium text-foreground', className)} data-slot="label" {...props} />;
 });
 
 // =============================================================
@@ -380,6 +429,7 @@ export const Switch = forwardRef<
         'data-[checked]:bg-control data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50',
         className,
       )}
+      data-slot="switch"
       {...props}
     >
       <BaseSwitch.Thumb className="block h-4 w-4 translate-x-0.5 rounded-full bg-background shadow transition-transform data-[checked]:translate-x-[1.125rem]" />
@@ -405,6 +455,7 @@ export const Toggle = forwardRef<
         'data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
         className,
       )}
+      data-slot="toggle"
       {...props}
     />
   );
@@ -418,6 +469,7 @@ export const ToggleGroup = forwardRef<
     <BaseToggleGroup
       ref={ref}
       className={cn('inline-flex items-center gap-1 rounded-md bg-muted p-1', className)}
+      data-slot="toggle-group"
       {...props}
     />
   );
@@ -431,7 +483,7 @@ export const RadioGroup = forwardRef<
   HTMLDivElement,
   React.ComponentPropsWithoutRef<typeof BaseRadioGroup>
 >(function RadioGroup({ className, ...props }, ref) {
-  return <BaseRadioGroup ref={ref} className={cn('grid gap-2', className)} {...props} />;
+  return <BaseRadioGroup ref={ref} className={cn('grid gap-2', className)} data-slot="radio-group" {...props} />;
 });
 
 export const Radio = forwardRef<
@@ -447,6 +499,7 @@ export const Radio = forwardRef<
         'data-[checked]:border-control data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50',
         className,
       )}
+      data-slot="radio"
       {...props}
     >
       <BaseRadio.Indicator className="grid place-items-center">
@@ -468,6 +521,7 @@ export const Progress = forwardRef<
     <BaseProgress.Root
       ref={ref}
       className={cn('relative h-2 w-full overflow-hidden rounded-full bg-muted', className)}
+      data-slot="progress"
       {...props}
     >
       <BaseProgress.Track className="absolute inset-0 overflow-hidden">

From 8d8b6139855a5b5da5faafea38508e1146d94b64 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Sun, 5 Jul 2026 14:17:35 +0800
Subject: [PATCH 02/10] feat(ui): migrate disclosure sites to Base UI
 Collapsible (#520 PR5 item 17)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Migrate the four native <details>/<summary> disclosure sites onto Base UI
Collapsible, following the style-hook convention (item 23). The code comments
at the sites already said "future Base UI Accordion path"; all four are
independent single sections (not grouped), so Collapsible (not Accordion) is
the right primitive.

Sites:
- chat-view.tsx turn-thinking (maka-turn-thinking): uncontrolled, default
  closed.
- chat-view.tsx reasoning-panel (maka-reasoning-panel): controlled open state
  moves from reading e.currentTarget.open off the native toggle event to
  Collapsible's open + onOpenChange props (default-open behavior preserved).
- permission-dialog.tsx permission-raw (maka-permission-raw): uncontrolled.
- tool-activity.tsx tool card ([data-slot="tool"]): uncontrolled with
  defaultOpen = isOpenByDefault(status); the data-slot="tool" hook overrides
  the Collapsible wrapper's default data-slot="collapsible" via prop spread,
  so the existing [data-slot="tool"] CSS keeps working.

New primitive: packages/ui/src/primitives/collapsible.tsx wraps Base UI
Collapsible Root/Trigger/Panel with data-slot="collapsible" /
"collapsible-trigger" / "collapsible-panel". The Trigger carries a button
chrome reset (appearance-none / bg-transparent / border-0 / p-0 / font
inherit) so the summary row's clean look is preserved — native <summary> had
no background/border/padding, but <button> does. Exported from the barrel as
PrimitiveCollapsible / PrimitiveCollapsibleTrigger / PrimitiveCollapsiblePanel.

CSS retargeting (the DOM changed: <summary> -> <button> trigger, <details
open> -> Collapsible with data-panel-open on the trigger):
- .maka-turn-thinking summary / [open] > summary::before ->
  [data-slot="collapsible-trigger"] / [data-slot="collapsible-trigger"][data-panel-open]::before
- .maka-permission-raw > summary / [open] > summary::before ->
  [data-slot="collapsible-trigger"] / [data-panel-open] variants
- .maka-reasoning-panel-header marker resets dropped (button has no native
  marker); [open] .maka-reasoning-panel-chevron ->
  [data-slot="collapsible-trigger"][data-panel-open] .maka-reasoning-panel-chevron
- [data-slot="tool"] > summary ::-webkit-details-marker / ::marker resets
  dropped (button trigger has no native marker).
- list-style: none rules dropped (no list marker on a button).

TDD: disclosure-collapsible-contract.test.ts written first (RED: sites still
used <details>, no primitive). GREEN: primitive + 4 migrations + CSS
retarget. The contract bans <details>/<summary> (incl. in comments) in the
three migrated files and requires a Collapsible import; it also pins the
primitive's data-slot on Root/Trigger/Panel.

Existing tests updated: border-width-converge-contract TRIANGLE_CARET_SELECTORS
(the chevron ::before border-width: 4px 0 4px 5px moved from summary::before to
[data-slot="collapsible-trigger"]::before); chat-marker-cascade-contract
(.maka-turn-thinking summary -> [data-slot="collapsible-trigger"]);
chat-tool-card-cascade-contract (the marker-reset residue on
[data-slot="tool"] > summary is gone — the trigger is a button now).

Verification: 1975/1975 desktop tests pass (+4 disclosure contract; the 3
existing contracts updated). typecheck clean. Screenshots vs clean main (PR4):
turn-narrative 0.09% (the summary->button swap's tiny pixel difference — button
baseline, the CollapsiblePanel wrapper), first-run 0%. No regression.
---
 .../border-width-converge-contract.test.ts    |  6 +-
 .../chat-marker-cascade-contract.test.ts      |  2 +-
 .../chat-tool-card-cascade-contract.test.ts   | 10 +--
 .../disclosure-collapsible-contract.test.ts   | 69 +++++++++++++++++++
 apps/desktop/src/renderer/maka-tokens.css     | 26 +++----
 .../src/renderer/styles/reasoning-panel.css   | 11 +--
 .../src/renderer/styles/settings/form.css     | 14 ++--
 packages/ui/src/chat-view.tsx                 | 41 ++++++-----
 packages/ui/src/index.ts                      |  6 ++
 packages/ui/src/permission-dialog.tsx         | 15 ++--
 packages/ui/src/primitives/collapsible.tsx    | 69 +++++++++++++++++++
 packages/ui/src/tool-activity.tsx             | 57 +++++++--------
 12 files changed, 233 insertions(+), 93 deletions(-)
 create mode 100644 apps/desktop/src/main/__tests__/disclosure-collapsible-contract.test.ts
 create mode 100644 packages/ui/src/primitives/collapsible.tsx

diff --git a/apps/desktop/src/main/__tests__/border-width-converge-contract.test.ts b/apps/desktop/src/main/__tests__/border-width-converge-contract.test.ts
index 844c75b695..c3b4872783 100644
--- a/apps/desktop/src/main/__tests__/border-width-converge-contract.test.ts
+++ b/apps/desktop/src/main/__tests__/border-width-converge-contract.test.ts
@@ -83,9 +83,9 @@ const BARE_PX_RE = /(?<![\w-])-?\d+(?:\.\d+)?px(?![\w-])/;
  *  any other selector is still caught — add a new caret here only after
  *  confirming it is geometry, not a stroke. */
 const TRIANGLE_CARET_SELECTORS = new Set([
-  '.maka-turn-thinking summary::before',
+  '.maka-turn-thinking [data-slot="collapsible-trigger"]::before',
   '.maka-bubble-assistant li.task-list-item > input[type="checkbox"]:checked::after',
-  '.maka-permission-raw > summary::before',
+  '.maka-permission-raw [data-slot="collapsible-trigger"]::before',
 ]);
 
 const BORDER_STYLE_KEYWORDS = new Set([
@@ -211,7 +211,7 @@ describe('border-width whitelist negative cases', () => {
 
   it('findCssOffenders allows triangle caret geometry on allowlisted selectors, flags multi-value and single bare-px elsewhere', () => {
     // Known caret selectors: multi-value geometry is allowed.
-    assert.deepEqual(findCssOffenders('.maka-turn-thinking summary::before {\n  border-width: 4px 0 4px 5px;\n}', 't'), [], 'allowlisted caret: 4px 0 4px 5px must pass');
+    assert.deepEqual(findCssOffenders('.maka-turn-thinking [data-slot="collapsible-trigger"]::before {\n  border-width: 4px 0 4px 5px;\n}', 't'), [], 'allowlisted caret: 4px 0 4px 5px must pass');
     assert.deepEqual(findCssOffenders('.maka-bubble-assistant li.task-list-item > input[type="checkbox"]:checked::after {\n  border-width: 0 2px 2px 0;\n}', 't'), [], 'allowlisted caret: 0 2px 2px 0 must pass');
     // Non-allowlisted selector: a multi-value bare px is a stroke drift, not
     // triangle geometry — a heuristic that spared ALL multi-value would miss it.
diff --git a/apps/desktop/src/main/__tests__/chat-marker-cascade-contract.test.ts b/apps/desktop/src/main/__tests__/chat-marker-cascade-contract.test.ts
index f059b3b9c1..84d9f8d4bb 100644
--- a/apps/desktop/src/main/__tests__/chat-marker-cascade-contract.test.ts
+++ b/apps/desktop/src/main/__tests__/chat-marker-cascade-contract.test.ts
@@ -51,7 +51,7 @@ describe('chat Marker shell migration contract (#332 PR2)', () => {
       // `.maka-turn-thinking` is explicitly deferred (pseudo-element chevron +
       // @starting-style fade don't reduce to leaf utilities); it stays authored.
       '.maka-turn-thinking',
-      '.maka-turn-thinking summary',
+      '.maka-turn-thinking [data-slot="collapsible-trigger"]',
     ]) {
       assert.ok(css.includes(selector), `out-of-scope turn rule "${selector}" must be preserved`);
     }
diff --git a/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts b/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts
index 31e0380a4a..9fa4f34b10 100644
--- a/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts
+++ b/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts
@@ -22,8 +22,10 @@ import { REPO_ROOT, TOKENS_FILE, readAllRendererCss, stripCssComments } from './
  *   2. the running status dot's `@keyframes maka-tool-pulse` ring frames — an
  *      animation can't be a leaf-literal and `getComputedStyle` reads a phase-
  *      dependent value, so the breath is pinned here + by the `chat.tsx` literal;
- *   3. native `<summary>` marker reset — re-keyed off the retired `.maka-tool`
- *      class onto the governed `[data-slot="tool"]` hook.
+ *   3. the `[data-slot="tool"]` base residue (opacity/transform/border-color
+ *      transition) — the native `<summary>` marker reset that used to live here is
+ *      gone after the disclosure → Collapsible migration (the trigger is a button
+ *      with no native marker).
  */
 describe('chat tool-card migration contract (#332 PR3b)', () => {
   it('retires the bespoke tool-card shell selectors (without touching error/preview/maka-code)', async () => {
@@ -90,7 +92,7 @@ describe('chat tool-card migration contract (#332 PR3b)', () => {
     }
   });
 
-  it('keeps only the marker reset residue, re-keyed onto [data-slot="tool"]', async () => {
+  it('keeps the tool-card base residue on [data-slot="tool"]', async () => {
     const tokens = stripCssComments(await readFile(TOKENS_FILE, 'utf8'));
     assert.ok(
       !tokens.includes('.maka-tool {') && !tokens.includes('@starting-style {\n    .maka-tool'),
@@ -101,8 +103,6 @@ describe('chat tool-card migration contract (#332 PR3b)', () => {
       '[data-slot="tool"] {',
       'transform: translateY(0)',
       'transition: border-color var(--duration-base) var(--ease-out-strong);',
-      '[data-slot="tool"] > summary::-webkit-details-marker { display: none; }',
-      "[data-slot=\"tool\"] > summary::marker { content: ''; }",
     ]) {
       assert.ok(
         tokens.includes(residue),
diff --git a/apps/desktop/src/main/__tests__/disclosure-collapsible-contract.test.ts b/apps/desktop/src/main/__tests__/disclosure-collapsible-contract.test.ts
new file mode 100644
index 0000000000..8ec540d0a6
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/disclosure-collapsible-contract.test.ts
@@ -0,0 +1,69 @@
+/**
+ * PR-DISCLOSURE-COLLAPSIBLE-0 (issue #520 PR5 item 17, 2026-07-05):
+ * the four disclosure sites (turn-thinking, reasoning-panel, permission-raw,
+ * tool-activity) migrate off native `<details>`/`<summary>` onto Base UI
+ * Collapsible. The code comments at the sites already said "future Base UI
+ * Accordion path"; all four are independent single sections (not grouped),
+ * so Collapsible (not Accordion) is the right primitive.
+ *
+ * Why migrate: native `<details>` gives free keyboard a11y but no CSS hook for
+ * the open/closed animation state, no controlled-open API for the reasoning
+ * panel's "default open, first click sticks" behavior (which today reads
+ * `e.currentTarget.open` from the toggle event), and no `data-slot` for the
+ * style-hook convention. Base UI Collapsible gives `data-[open]` state, a
+ * controlled `open` prop, and the `data-slot` hook.
+ *
+ * This contract locks the migration: the three files that held the four
+ * `<details>` sites must not carry `<details>`/`<summary>` (not even in
+ * comments — a stale "wrapped in a <details>" comment is a regression
+ * signal), and must import Collapsible. The Collapsible primitive itself
+ * must wrap Base UI Collapsible with the data-slot convention (item 23).
+ */
+
+import { strict as assert } from 'node:assert';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { describe, it } from 'node:test';
+import { REPO_ROOT } from './css-test-helpers.js';
+
+const MIGRATED_FILES = [
+  'packages/ui/src/chat-view.tsx',
+  'packages/ui/src/permission-dialog.tsx',
+  'packages/ui/src/tool-activity.tsx',
+];
+
+const COLLAPSIBLE_PRIMITIVE = 'packages/ui/src/primitives/collapsible.tsx';
+
+/** A Collapsible import: from the @maka/ui barrel, the primitives path, or
+ *  @base-ui/react/collapsible directly. */
+const COLLAPSIBLE_IMPORT_RE = /import\s+\{[^}]*\bCollapsible\b[^}]*\}\s+from\s+['"][^'"]*(?:@maka\/ui|primitives\/collapsible|@base-ui\/react\/collapsible)[^'"]*['"]/;
+
+describe('PR-DISCLOSURE-COLLAPSIBLE-0 contract', () => {
+  it('the disclosure sites use Base UI Collapsible (no native <details>/<summary>)', async () => {
+    for (const rel of MIGRATED_FILES) {
+      const src = await readFile(resolve(REPO_ROOT, rel), 'utf8');
+      assert.ok(!/<details\b/.test(src), `${rel}: must not use native <details> (migrate to Base UI Collapsible; also drop stale <details> mentions in comments)`);
+      assert.ok(!/<summary\b/.test(src), `${rel}: must not use native <summary> (use Collapsible.Trigger)`);
+      assert.match(src, COLLAPSIBLE_IMPORT_RE, `${rel}: must import Collapsible from @maka/ui / primitives/collapsible / @base-ui/react/collapsible`);
+    }
+  });
+
+  it('primitives/collapsible.tsx wraps Base UI Collapsible with data-slot on Root / Trigger / Panel', async () => {
+    const src = await readFile(resolve(REPO_ROOT, COLLAPSIBLE_PRIMITIVE), 'utf8');
+    assert.match(src, /@base-ui\/react\/collapsible/, 'must import from @base-ui/react/collapsible');
+    for (const slot of ['collapsible', 'collapsible-trigger', 'collapsible-panel']) {
+      assert.match(src, new RegExp(`data-slot="${slot}"`), `must expose data-slot="${slot}" (style-hook convention, item 23)`);
+    }
+  });
+});
+
+describe('disclosure-collapsible negative cases', () => {
+  it('flags a native <details> and a missing Collapsible import', () => {
+    const withDetails = 'import { Collapsible } from "@maka/ui";\nexport function X() { return <details><summary>h</summary>b</details>; }';
+    assert.ok(/<details\b/.test(withDetails), '<details> must be detected');
+    const noImport = 'export function X() { return null; }';
+    assert.ok(!COLLAPSIBLE_IMPORT_RE.test(noImport), 'no Collapsible import must not match');
+    const withImport = 'import { Collapsible } from "@maka/ui";\nexport function X() { return <Collapsible.Root />; }';
+    assert.ok(COLLAPSIBLE_IMPORT_RE.test(withImport), 'a Collapsible import must match');
+  });
+});
\ No newline at end of file
diff --git a/apps/desktop/src/renderer/maka-tokens.css b/apps/desktop/src/renderer/maka-tokens.css
index c4e52e62f7..da20db3d4d 100644
--- a/apps/desktop/src/renderer/maka-tokens.css
+++ b/apps/desktop/src/renderer/maka-tokens.css
@@ -1221,24 +1221,22 @@
     color: var(--foreground-secondary);
   }
 
-  .maka-turn-thinking summary {
+  .maka-turn-thinking [data-slot="collapsible-trigger"] {
     display: flex;
     align-items: center;
     gap: var(--space-2);
     font-weight: var(--font-weight-semibold);
     color: var(--focus-ring);
     letter-spacing: var(--tracking-wide);
-    list-style: none;
     /* `cursor: pointer` intentionally omitted — native macOS reserves
-       the hand cursor for links; `<details>` summaries are button-like
-       controls and use the default arrow. Enforced by
+       the hand cursor for links; the Collapsible trigger is a button-like
+       control and uses the default arrow. Enforced by
        `cursor-convention-contract.test.ts`. */
   }
 
   /* Replace the default disclosure triangle with a custom chevron
      that rotates smoothly on toggle. */
-  .maka-turn-thinking summary::-webkit-details-marker { display: none; }
-  .maka-turn-thinking summary::before {
+  .maka-turn-thinking [data-slot="collapsible-trigger"]::before {
     content: '';
     flex-shrink: 0;
     width: 0;
@@ -1248,7 +1246,7 @@
     border-color: transparent transparent transparent currentColor;
     transition: transform var(--duration-emphasized) var(--ease-out-strong);
   }
-  .maka-turn-thinking[open] > summary::before {
+  .maka-turn-thinking [data-slot="collapsible-trigger"][data-panel-open]::before {
     transform: rotate(90deg);
   }
 
@@ -1724,13 +1722,12 @@
   /* ---- Tool activity ---------------------------------------------- */
 
   /* The tool-activity card shell (the inline section + count pill, the
-     `<details>` card, its `<summary>` header row, the body / intent, and the
+     Collapsible card, its trigger header row, the body / intent, and the
      args `<pre>` override) moved onto the `@maka/ui` chat substrate's
      `toolVariants` literalize table (issue #332 PR3b —
      packages/ui/src/primitives/chat.tsx). What stays here is the irreducible
      residue that escapes the computed-style proof, re-keyed on the governed
-     `[data-slot="tool"]` hook instead of the retired `.maka-tool` class: the
-     native `<summary>` marker reset (pseudo-elements with no leaf-utility form).
+     `[data-slot="tool"]` hook instead of the retired `.maka-tool` class.
      The running status dot's `@keyframes maka-tool-pulse` (below) likewise stays
      because it is a functional status animation. */
   [data-slot="tool"] {
@@ -1738,11 +1735,10 @@
     transform: translateY(0);
     transition: border-color var(--duration-base) var(--ease-out-strong);
   }
-  /* Native <details>/<summary> marker reset — the summary IS the header row
-     (laid out by `toolVariants({ part: 'header' })`), so the default disclosure
-     triangle is suppressed. */
-  [data-slot="tool"] > summary::-webkit-details-marker { display: none; }
-  [data-slot="tool"] > summary::marker { content: ''; }
+  /* The Collapsible trigger is the header row (laid out by
+     `toolVariants({ part: 'header' })`); as a real <button> it has no native
+     disclosure marker, so the marker-reset rules the native <summary> needed
+     are gone. */
 
   @keyframes maka-tool-pulse {
     0%, 100% { box-shadow: 0 0 0 3px oklch(from var(--status-running) l c h / 0.15); }
diff --git a/apps/desktop/src/renderer/styles/reasoning-panel.css b/apps/desktop/src/renderer/styles/reasoning-panel.css
index 59e591e747..e412eafb47 100644
--- a/apps/desktop/src/renderer/styles/reasoning-panel.css
+++ b/apps/desktop/src/renderer/styles/reasoning-panel.css
@@ -4,7 +4,7 @@
 
      Renders live `ThinkingDeltaEvent.text` accumulated per session in
      `thinkingBySession`. Visible above the streaming answer bubble while
-     the model is reasoning. Collapsible `<details>` wrapper for keyboard
+     the model is reasoning. Base UI Collapsible wrapper for keyboard
      a11y. Default-open so users see the live reasoning; clicking the
      header collapses.
   ============================================================================= */
@@ -19,7 +19,6 @@
     border-color: oklch(from var(--info) l c h / 0.32);
   }
 .maka-reasoning-panel-header {
-    list-style: none;
     display: flex;
     align-items: center;
     gap: var(--space-1-5);
@@ -31,12 +30,6 @@
     user-select: none;
     transition: background var(--duration-base) var(--ease-out-strong);
   }
-.maka-reasoning-panel-header::-webkit-details-marker {
-    display: none;
-  }
-.maka-reasoning-panel-header::marker {
-    content: '';
-  }
 .maka-reasoning-panel-header:hover {
     background: oklch(from var(--info) l c h / 0.08);
   }
@@ -97,7 +90,7 @@
     color: var(--muted-foreground);
     transition: transform var(--duration-base) var(--ease-out-strong);
   }
-.maka-reasoning-panel[open] .maka-reasoning-panel-chevron {
+.maka-reasoning-panel [data-slot="collapsible-trigger"][data-panel-open] .maka-reasoning-panel-chevron {
     transform: rotate(90deg);
   }
 .maka-reasoning-panel-body {
diff --git a/apps/desktop/src/renderer/styles/settings/form.css b/apps/desktop/src/renderer/styles/settings/form.css
index fe2cbde695..75404d80d9 100644
--- a/apps/desktop/src/renderer/styles/settings/form.css
+++ b/apps/desktop/src/renderer/styles/settings/form.css
@@ -54,8 +54,7 @@
   background: var(--foreground-2);
 }
 
-.maka-permission-raw > summary {
-  list-style: none;
+.maka-permission-raw [data-slot="collapsible-trigger"] {
   display: flex;
   align-items: center;
   gap: var(--space-1-5);
@@ -64,13 +63,10 @@
   font-size: var(--font-size-caption);
 }
 
-.maka-permission-raw > summary::-webkit-details-marker { display: none; }
-.maka-permission-raw > summary::marker { content: ''; }
-
 /* Rotating disclosure triangle (same recipe as .maka-turn-thinking):
-   without it the bordered summary row read as a text input, not a
+   without it the bordered trigger row read as a text input, not a
    collapsible section. */
-.maka-permission-raw > summary::before {
+.maka-permission-raw [data-slot="collapsible-trigger"]::before {
   content: '';
   flex-shrink: 0;
   width: 0;
@@ -81,11 +77,11 @@
   transition: transform var(--duration-base) var(--ease-out-strong);
 }
 
-.maka-permission-raw[open] > summary::before {
+.maka-permission-raw [data-slot="collapsible-trigger"][data-panel-open]::before {
   transform: rotate(90deg);
 }
 
-.maka-permission-raw[open] > summary {
+.maka-permission-raw [data-slot="collapsible-trigger"][data-panel-open] {
   border-bottom: var(--border-width-hairline) solid var(--border);
 }
 
diff --git a/packages/ui/src/chat-view.tsx b/packages/ui/src/chat-view.tsx
index f75a3693d9..4bb6e5960f 100644
--- a/packages/ui/src/chat-view.tsx
+++ b/packages/ui/src/chat-view.tsx
@@ -25,6 +25,7 @@ import { deriveCapabilityAuditReport, isDeepResearchSession } from '@maka/core';
 import { materializeChat, materializeTools, materializeTurns, type ToolActivityItem, type TurnViewModel } from './materialize.js';
 import { Button as UiButton } from './ui.js';
 import { Alert, AlertDescription } from './primitives/alert.js';
+import { Collapsible, CollapsibleTrigger, CollapsiblePanel } from './primitives/collapsible.js';
 import { Bubble, Marker, markerVariants, Message } from './primitives/chat.js';
 import type { NavSelection } from './nav-selection.js';
 import { EmptyState } from './empty-state.js';
@@ -1033,18 +1034,20 @@ const TurnView = memo(function TurnView(props: {
         >
           <div className="flex flex-col">
             {turn.assistantThinking && (
-              <details className="maka-turn-thinking">
-                <summary>
+              <Collapsible className="maka-turn-thinking">
+                <CollapsibleTrigger>
                   <span>查看思考过程</span>
                   <span className="maka-turn-thinking-note">模型推理草稿，不是最终答案</span>
-                </summary>
-                <div className="maka-turn-thinking-body">
-                  <Markdown text={turn.assistantThinking} />
-                  <div className="maka-turn-thinking-actions">
-                    <MessageCopyButton text={turn.assistantThinking} label="复制思考过程" />
+                </CollapsibleTrigger>
+                <CollapsiblePanel>
+                  <div className="maka-turn-thinking-body">
+                    <Markdown text={turn.assistantThinking} />
+                    <div className="maka-turn-thinking-actions">
+                      <MessageCopyButton text={turn.assistantThinking} label="复制思考过程" />
+                    </div>
                   </div>
-                </div>
-              </details>
+                </CollapsiblePanel>
+              </Collapsible>
             )}
             {/* PR109d-c: aborted turn body gets a muted "(已中断)" prefix
                 + Ban icon so the user can see this turn was cancelled
@@ -1304,7 +1307,7 @@ const STATUS_FOOTER_ICON: Record<TurnFooterActionMeta['id'], ReactNode> = {
  *
  * Default-open during streaming so the user sees the live reasoning;
  * collapses to a single-line summary if user clicks the header. The
- * panel itself is wrapped in a `<details>` for native keyboard a11y
+ * panel itself is wrapped in a Base UI Collapsible for keyboard a11y
  * (Space/Enter toggles).
  *
  * `live=true` means thinking is still streaming (no text yet). Adds
@@ -1413,20 +1416,20 @@ function ReasoningPanel(props: { text: string; live: boolean; truncated: boolean
   // on the next stream-driven re-render (the smoother re-renders at
   // ~60Hz while the stream is live, so any reconciliation drift is
   // immediately visible to the user). Owning the open state via
-  // useState + onToggle makes the panel uncontrolled-from-React's-view:
+  // useState + onOpenChange makes the panel uncontrolled-from-React's-view:
   // the user's collapse sticks because we only write `open` from our
-  // own state, which we only mutate from the onToggle callback.
+  // own state, which we only mutate from the onOpenChange callback.
   // Default-open at mount so users see the reasoning by default; first
   // click toggles to closed and that sticks.
   const [open, setOpen] = useState(true);
   return (
-    <details
+    <Collapsible
       className="maka-reasoning-panel"
       data-live={props.live ? 'true' : undefined}
       open={open}
-      onToggle={(e) => setOpen((e.currentTarget as HTMLDetailsElement).open)}
+      onOpenChange={(v) => setOpen(v)}
     >
-      <summary className="maka-reasoning-panel-header">
+      <CollapsibleTrigger className="maka-reasoning-panel-header">
         {props.live && <span className="maka-reasoning-panel-dot" aria-hidden="true" />}
         <span className="maka-reasoning-panel-label">
           {props.live ? '正在思考…' : '思考过程'}
@@ -1445,9 +1448,11 @@ function ReasoningPanel(props: { text: string; live: boolean; truncated: boolean
           </span>
         )}
         <span className="maka-reasoning-panel-chevron" aria-hidden="true">›</span>
-      </summary>
-      <pre className="maka-reasoning-panel-body">{displayed}</pre>
-    </details>
+      </CollapsibleTrigger>
+      <CollapsiblePanel>
+        <pre className="maka-reasoning-panel-body">{displayed}</pre>
+      </CollapsiblePanel>
+    </Collapsible>
   );
 }
 
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 4075fb9824..d705128eb2 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -61,6 +61,12 @@ export * from './primitives/settings-select.js';
 export * from './primitives/settings-switch.js';
 export * from './primitives/input-group.js';
 export * from './primitives/toolbar.js';
+export {
+  Collapsible as PrimitiveCollapsible,
+  CollapsibleTrigger as PrimitiveCollapsibleTrigger,
+  CollapsiblePanel as PrimitiveCollapsiblePanel,
+  CollapsiblePrimitive as PrimitiveCollapsiblePrimitive,
+} from './primitives/collapsible.js';
 export {
   Tabs as PrimitiveTabs,
   TabsList as PrimitiveTabsList,
diff --git a/packages/ui/src/permission-dialog.tsx b/packages/ui/src/permission-dialog.tsx
index 6da399032d..a9ce396d7d 100644
--- a/packages/ui/src/permission-dialog.tsx
+++ b/packages/ui/src/permission-dialog.tsx
@@ -3,6 +3,7 @@ import type { PermissionRequestEvent, PermissionResponse } from '@maka/core';
 import { derivePermissionRequestHealth, formatPermissionRequestWait } from '@maka/core';
 import { AlertOctagon, AlertTriangle, FileEdit, GitMerge, Globe, HelpCircle, ShieldAlert, Terminal, Wifi } from './icons.js';
 import { Alert, AlertDescription } from './primitives/alert.js';
+import { Collapsible, CollapsibleTrigger, CollapsiblePanel } from './primitives/collapsible.js';
 import { Badge, Button as UiButton, Checkbox, AlertDialogContent, AlertDialogRoot } from './ui.js';
 import { redactSecrets } from './redact.js';
 import { formatRedactedJson } from './tool-format.js';
@@ -128,10 +129,12 @@ export function PermissionDialog(props: {
           {props.request.hint && (
             <div className="maka-permission-hint" role="note">{props.request.hint}</div>
           )}
-          <details className="maka-permission-raw">
-            <summary>查看完整参数</summary>
-            <pre className="maka-code">{formatRedactedJson(props.request.args)}</pre>
-          </details>
+          <Collapsible className="maka-permission-raw">
+            <CollapsibleTrigger>查看完整参数</CollapsibleTrigger>
+            <CollapsiblePanel>
+              <pre className="maka-code">{formatRedactedJson(props.request.args)}</pre>
+            </CollapsiblePanel>
+          </Collapsible>
           <label className="permissionRemember">
             <Checkbox
               checked={rememberForTurn}
@@ -185,7 +188,7 @@ export function PermissionDialog(props: {
  * One-line summary for a browser_* action. Names the concrete action (open /
  * read / click / type) so the prompt reads as a real browser step, not an opaque
  * tool call — reinforcing that a browser grant spans reads AND acts. The typed
- * text and full args stay in the raw `<details>` block below.
+ * text and full args stay in the raw Collapsible block below.
  */
 function renderBrowserSummary(toolName: string, args: Record<string, unknown>): ReactNode {
   const ref = typeof args.ref === 'string' ? args.ref : '';
@@ -211,7 +214,7 @@ function renderBrowserSummary(toolName: string, args: Record<string, unknown>):
 /**
  * Per-tool human-readable summary of what the request will do, used at the
  * top of the permission dialog body. Falls back to undefined if we can't
- * recognize the tool — the raw args `<details>` block is always available.
+ * recognize the tool — the raw args Collapsible block is always available.
  */
 function renderPermissionSummary(request: PermissionRequestEvent): ReactNode | undefined {
   const args = (request.args ?? {}) as Record<string, unknown>;
diff --git a/packages/ui/src/primitives/collapsible.tsx b/packages/ui/src/primitives/collapsible.tsx
new file mode 100644
index 0000000000..1ae027ed62
--- /dev/null
+++ b/packages/ui/src/primitives/collapsible.tsx
@@ -0,0 +1,69 @@
+"use client";
+
+import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible";
+import { cn } from "../utils.js";
+import type React from "react";
+
+// Base UI Collapsible wrappers for the four disclosure sites that used native
+// `<details>`/`<summary>` (turn-thinking, reasoning-panel, permission-raw,
+// tool-activity — all independent single sections, so Collapsible not
+// Accordion). The `data-slot` hooks follow the style-hook convention (item 23)
+// so CSS can target `[data-slot="collapsible"]` / `[data-slot="collapsible-trigger"]`
+// / `[data-slot="collapsible-panel"]` and read the Base UI native `[data-open]`
+// state attribute on the root.
+//
+// Migration note: native `<details>` rendered the summary + body inline; Base UI
+// Collapsible.Trigger is a real `<button>`, so the summary row must be
+// click-targetable (it already was — the `<summary>` was the toggle). The
+// reasoning panel's "default open, first click sticks" behavior moves from
+// reading `e.currentTarget.open` off the toggle event to Collapsible's
+// controlled `open` + `onOpenChange` props.
+
+export function Collapsible({
+  className,
+  ...props
+}: CollapsiblePrimitive.Root.Props): React.ReactElement {
+  return (
+    <CollapsiblePrimitive.Root
+      className={cn("flex flex-col", className)}
+      data-slot="collapsible"
+      {...props}
+    />
+  );
+}
+
+export function CollapsibleTrigger({
+  className,
+  ...props
+}: CollapsiblePrimitive.Trigger.Props): React.ReactElement {
+  return (
+    <CollapsiblePrimitive.Trigger
+      className={cn(
+        // Button chrome reset: native <summary> had no background/border/
+        // padding/font-family, but <button> does, so reset to a clean slate
+        // and let the call site's className own layout + color. cursor stays
+        // default (macOS reserves the hand for links; see
+        // cursor-convention-contract.test.ts).
+        "flex w-full select-none items-center outline-none appearance-none bg-transparent border-0 p-0 [font:inherit] [text-align:inherit]",
+        className,
+      )}
+      data-slot="collapsible-trigger"
+      {...props}
+    />
+  );
+}
+
+export function CollapsiblePanel({
+  className,
+  ...props
+}: CollapsiblePrimitive.Panel.Props): React.ReactElement {
+  return (
+    <CollapsiblePrimitive.Panel
+      className={cn("overflow-hidden", className)}
+      data-slot="collapsible-panel"
+      {...props}
+    />
+  );
+}
+
+export { CollapsiblePrimitive };
\ No newline at end of file
diff --git a/packages/ui/src/tool-activity.tsx b/packages/ui/src/tool-activity.tsx
index 7a1d063790..4638de03f6 100644
--- a/packages/ui/src/tool-activity.tsx
+++ b/packages/ui/src/tool-activity.tsx
@@ -5,6 +5,7 @@ import { useClipboardCopyFeedback } from './clipboard-feedback.js';
 import { detectUiLocale } from './locale-helpers.js';
 import { type ToolActivityItem, type ToolOutputChunk } from './materialize.js';
 import { Alert, AlertAction, AlertDescription, AlertTitle } from './primitives/alert.js';
+import { Collapsible, CollapsibleTrigger, CollapsiblePanel } from './primitives/collapsible.js';
 import { LiveIndicator, previewVariants, streamVariants, toolVariants } from './primitives/chat.js';
 import { redactSecrets } from './redact.js';
 import { Button as UiButton, cn } from './ui.js';
@@ -109,44 +110,46 @@ export function ToolActivity(props: { items: ToolActivityItem[] }) {
         const errored = item.status === 'errored';
         const permissionDenied = isPermissionDeniedToolResult(item.result);
         return (
-          <details
+          <Collapsible
             key={item.toolUseId}
             data-slot="tool"
             className={toolVariants({ part: 'item' })}
             data-status={item.status}
-            open={isOpenByDefault(item.status)}
+            defaultOpen={isOpenByDefault(item.status)}
           >
-            <summary className={toolVariants({ part: 'header' })}>
+            <CollapsibleTrigger className={toolVariants({ part: 'header' })}>
               <span className={toolVariants({ part: 'dot' })} data-status={item.status} aria-hidden="true" />
               <span className={toolVariants({ part: 'name' })}>{resolveToolDisplayName(item)}</span>
               <span className={toolVariants({ part: 'meta' })}>
                 {duration && <span className={toolVariants({ part: 'duration' })}>{duration}</span>}
                 <span className={toolVariants({ part: 'status-label' })}>{STATUS_LABEL[item.status]}</span>
               </span>
-            </summary>
-            <div className={toolVariants({ part: 'body' })}>
-              {errored && <ToolErrorBanner result={item.result} />}
-              {item.intent && !permissionDenied && <p className={toolVariants({ part: 'intent' })}>{formatToolIntent(item.intent)}</p>}
-              {item.args !== undefined && !permissionDenied && (
-                <pre className={`maka-code ${toolVariants({ part: 'args' })}`}>{formatRedactedJson(item.args)}</pre>
-              )}
-              {item.outputChunks && item.outputChunks.length > 0 && (
-                <ToolOutputStream
-                  chunks={item.outputChunks}
-                  live={item.status === 'running' || item.status === 'pending'}
-                  interrupted={item.status === 'interrupted'}
-                  truncated={item.outputTruncated === true}
-                />
-              )}
-              {item.result && !permissionDenied && (
-                isConnectorTool(item.toolName) && item.result.kind === 'json' ? (
-                  <LoadToolResultPreview args={item.args} value={item.result.value} />
-                ) : (
-                  <ToolResultPreview content={item.result} />
-                )
-              )}
-            </div>
-          </details>
+            </CollapsibleTrigger>
+            <CollapsiblePanel>
+              <div className={toolVariants({ part: 'body' })}>
+                {errored && <ToolErrorBanner result={item.result} />}
+                {item.intent && !permissionDenied && <p className={toolVariants({ part: 'intent' })}>{formatToolIntent(item.intent)}</p>}
+                {item.args !== undefined && !permissionDenied && (
+                  <pre className={`maka-code ${toolVariants({ part: 'args' })}`}>{formatRedactedJson(item.args)}</pre>
+                )}
+                {item.outputChunks && item.outputChunks.length > 0 && (
+                  <ToolOutputStream
+                    chunks={item.outputChunks}
+                    live={item.status === 'running' || item.status === 'pending'}
+                    interrupted={item.status === 'interrupted'}
+                    truncated={item.outputTruncated === true}
+                  />
+                )}
+                {item.result && !permissionDenied && (
+                  isConnectorTool(item.toolName) && item.result.kind === 'json' ? (
+                    <LoadToolResultPreview args={item.args} value={item.result.value} />
+                  ) : (
+                    <ToolResultPreview content={item.result} />
+                  )
+                )}
+              </div>
+            </CollapsiblePanel>
+          </Collapsible>
         );
       })}
     </section>

From eeb15f65ca52766c815458316732183f595718b2 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Sun, 5 Jul 2026 14:29:07 +0800
Subject: [PATCH 03/10] feat(ui): migrate icon-action tooltips to Base UI
 Tooltip (#520 PR5 item 20)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Migrate the clearest icon-only-action button tooltips off the native title=
attribute (an unstyled, delayed browser tooltip) onto Base UI Tooltip,
which gives a themed, positioned, hover+focus tooltip matching the app.

Sites (13 buttons across 3 files):
- app-shell-chrome-actions.tsx: search / sidebar / new-task / feedback /
  command-palette / help / health (7).
- browser-panel.tsx: back / forward / refresh / close (4).
- artifact-pane.tsx: the collapse toggle (1); the delete button's redundant
  title= is dropped instead (it already shows a visible 删除 label, so a
  tooltip would be a duplicate).

New primitive: packages/ui/src/primitives/tooltip.tsx wraps Base UI Tooltip
Root / Trigger / Content with data-slot="tooltip" / "tooltip-trigger" /
"tooltip-content". TooltipContent collapses Portal + Positioner + Popup
(the DialogContent shape) with a themed look (popover bg/corner/shadow +
z-overlay). The Trigger forwards via Base UI's render prop
(<TooltipTrigger render={<Button …/>} …props>…children…</TooltipTrigger>),
which merges the Trigger's props + children into the rendered Button — Base
UI v1 uses render, not the Radix asChild prop. Exported from the barrel as
Tooltip / TooltipTrigger / TooltipContent (no ui.tsx wrapper, so direct
names). aria-label stays on the button (accessible name); the TooltipContent
is the visual hover hint.

TDD: tooltip-converge-contract.test.ts written first (RED: the 3 files still
carried native title=, no primitive). GREEN: primitive + 13 migrations. The
contract bans a title= JSX attribute in the 3 migrated files and requires
a Tooltip import; it pins the primitive's data-slot on Root/Trigger/Content.
The regex \btitle= matches JSX attributes but not JS `const title =` (the
space before =).

Scope note: the longer tail of title= usages (truncation spans like
memory-settings path + chat-model-switcher chip, SelectTrigger titles,
status-badge icons, OnboardingHero's submit button) are tooltip-eligible but
each needs a label-vs-tooltip judgment and are not swept in this commit —
deferred to a follow-up. label-prop components (SettingRow / MetricCard /
SetupHero / Section) render title as visible text and are NOT tooltips;
they stay.

Existing tests updated: app-region-hygiene-contract's
extractStaticUiButtonClassNames now also matches the
<TooltipTrigger render={<UiButton/>}> shape (the className moved from the
UiButton element to the TooltipTrigger that renders it); search-modal-
lifecycle's shell-search-button regex now matches </TooltipTrigger> (the
UiButton is the render target, self-closing).

Verification: 1979/1979 desktop tests pass (+4 tooltip contract). typecheck
clean (render prop, not asChild). renderer build clean. Screenshots vs clean
main (PR4): turn-narrative 0.09% (the disclosure commit's residual; tooltips
are hover-only so rest state is unchanged), first-run 0%.
---
 .../app-region-hygiene-contract.test.ts       |   9 +-
 .../search-modal-lifecycle-contract.test.ts   |   2 +-
 .../tooltip-converge-contract.test.ts         |  77 ++++++++
 .../src/renderer/app-shell-chrome-actions.tsx | 173 +++++++++---------
 apps/desktop/src/renderer/artifact-pane.tsx   |  41 +++--
 apps/desktop/src/renderer/browser-panel.tsx   | 105 ++++++-----
 packages/ui/src/index.ts                      |   5 +
 packages/ui/src/primitives/tooltip.tsx        |  62 +++++++
 8 files changed, 321 insertions(+), 153 deletions(-)
 create mode 100644 apps/desktop/src/main/__tests__/tooltip-converge-contract.test.ts
 create mode 100644 packages/ui/src/primitives/tooltip.tsx

diff --git a/apps/desktop/src/main/__tests__/app-region-hygiene-contract.test.ts b/apps/desktop/src/main/__tests__/app-region-hygiene-contract.test.ts
index 5b307a2781..2091df108d 100644
--- a/apps/desktop/src/main/__tests__/app-region-hygiene-contract.test.ts
+++ b/apps/desktop/src/main/__tests__/app-region-hygiene-contract.test.ts
@@ -187,7 +187,14 @@ function findRulesWithDeclaration(
 
 function extractStaticUiButtonClassNames(src: string): string[] {
   const classes = new Set<string>();
-  const uiButtonBlocks = src.match(/<UiButton\b[\s\S]*?<\/UiButton>/g) ?? [];
+  // A topbar UiButton appears either as a direct element
+  // (<UiButton>…</UiButton>) or, after the Tooltip migration, as the
+  // render target of a TooltipTrigger
+  // (<TooltipTrigger render={<UiButton …/>} className="…">…</TooltipTrigger>).
+  const uiButtonBlocks = [
+    ...(src.match(/<UiButton\b[\s\S]*?<\/UiButton>/g) ?? []),
+    ...(src.match(/<TooltipTrigger\b[\s\S]*?render=\{<UiButton\b[\s\S]*?<\/TooltipTrigger>/g) ?? []),
+  ];
   for (const block of uiButtonBlocks) {
     const match = block.match(/\bclassName="([^"]+)"/);
     assert.ok(
diff --git a/apps/desktop/src/main/__tests__/search-modal-lifecycle-contract.test.ts b/apps/desktop/src/main/__tests__/search-modal-lifecycle-contract.test.ts
index 00368103e3..11dcc7bbfc 100644
--- a/apps/desktop/src/main/__tests__/search-modal-lifecycle-contract.test.ts
+++ b/apps/desktop/src/main/__tests__/search-modal-lifecycle-contract.test.ts
@@ -116,7 +116,7 @@ describe('SearchModal lifecycle contract (PR-SIDEBAR-IA-0 Phase 3 P0 fixup)', ()
 
   it('returns focus to the sidebar Search trigger when the modal closes', async () => {
     const main = await readRendererShellCombinedSource();
-    const shellSearchButton = main.match(/className="maka-shell-topbar-button"[\s\S]*?data-maka-search-trigger="true"[\s\S]*?<\/UiButton>/)?.[0] ?? '';
+    const shellSearchButton = main.match(/className="maka-shell-topbar-button"[\s\S]*?data-maka-search-trigger="true"[\s\S]*?<\/TooltipTrigger>/)?.[0] ?? '';
     const closeSearchModal = main.match(/function closeSearchModal\(options\?: \{ restoreFocus\?: boolean \}\) \{[\s\S]*?\n  \}/)?.[0] ?? '';
 
     assert.match(
diff --git a/apps/desktop/src/main/__tests__/tooltip-converge-contract.test.ts b/apps/desktop/src/main/__tests__/tooltip-converge-contract.test.ts
new file mode 100644
index 0000000000..c27b8b725d
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/tooltip-converge-contract.test.ts
@@ -0,0 +1,77 @@
+/**
+ * PR-TOOLTIP-CONVERGE-0 (issue #520 PR5 item 20, 2026-07-05):
+ * the icon-only-action button tooltips migrate off the native `title=`
+ * attribute (an unstyled, delayed browser tooltip) onto Base UI Tooltip,
+ * which gives a themed, positioned, hover+focus tooltip matching the app.
+ *
+ * Scope of this commit: the clearest icon-only-action buttons — the app
+ * shell chrome actions (search / sidebar / new-task / feedback / command-
+ * palette / help / health), the browser-panel nav (back / forward / refresh
+ * / close), and the artifact-pane collapse / delete. These are unambiguous
+ * icon-only buttons where `title=` is a hover hint, not a visible label.
+ *
+ * Out of scope (deferred to a follow-up): the longer tail of `title=` usages
+ * that need per-site judgment (label-prop components like SettingRow /
+ * MetricCard / SetupHero render `title` as visible text — those are NOT
+ * tooltips and stay; truncation spans, SelectTrigger titles, status-badge
+ * icons, and OnboardingHero's submit button ARE tooltip-eligible but each
+ * needs a label-vs-tooltip check, so they are not swept in this commit).
+ *
+ * The contract: the three migrated files must not carry a `title=` JSX
+ * attribute (the tooltip text moves into `<TooltipContent>{...}`) and must
+ * import Tooltip; the primitive must wrap Base UI Tooltip with the data-slot
+ * convention (item 23).
+ */
+
+import { strict as assert } from 'node:assert';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { describe, it } from 'node:test';
+import { REPO_ROOT } from './css-test-helpers.js';
+
+const MIGRATED_FILES = [
+  'apps/desktop/src/renderer/app-shell-chrome-actions.tsx',
+  'apps/desktop/src/renderer/browser-panel.tsx',
+  'apps/desktop/src/renderer/artifact-pane.tsx',
+];
+
+const TOOLTIP_PRIMITIVE = 'packages/ui/src/primitives/tooltip.tsx';
+
+/** A JSX `title=` attribute (title immediately followed by `=`). JS
+ *  `const title =` has a space before `=` so it does not match. */
+const TITLE_ATTR_RE = /\btitle=/;
+
+/** A Tooltip import from the barrel / primitives / @base-ui. */
+const TOOLTIP_IMPORT_RE = /import\s+\{[^}]*\bTooltip\b[^}]*\}\s+from\s+['"][^'"]*(?:@maka\/ui|primitives\/tooltip|@base-ui\/react\/tooltip)[^'"]*['"]/;
+
+describe('PR-TOOLTIP-CONVERGE-0 contract', () => {
+  it('the icon-action tooltip files use Base UI Tooltip (no native title= attribute)', async () => {
+    for (const rel of MIGRATED_FILES) {
+      const src = await readFile(resolve(REPO_ROOT, rel), 'utf8');
+      assert.ok(!TITLE_ATTR_RE.test(src), `${rel}: must not use native title= (migrate icon-action tooltips to Base UI Tooltip)`);
+      assert.match(src, TOOLTIP_IMPORT_RE, `${rel}: must import Tooltip from @maka/ui / primitives/tooltip / @base-ui/react/tooltip`);
+    }
+  });
+
+  it('primitives/tooltip.tsx wraps Base UI Tooltip with data-slot on Root / Trigger / Content', async () => {
+    const src = await readFile(resolve(REPO_ROOT, TOOLTIP_PRIMITIVE), 'utf8');
+    assert.match(src, /@base-ui\/react\/tooltip/, 'must import from @base-ui/react/tooltip');
+    for (const slot of ['tooltip', 'tooltip-trigger', 'tooltip-content']) {
+      assert.match(src, new RegExp(`data-slot="${slot}"`), `must expose data-slot="${slot}" (style-hook convention, item 23)`);
+    }
+  });
+});
+
+describe('tooltip-converge negative cases', () => {
+  it('TITLE_ATTR_RE matches JSX title= but not JS const title =', () => {
+    assert.ok(TITLE_ATTR_RE.test('<Button title="x">'), 'JSX title="x" must match');
+    assert.ok(TITLE_ATTR_RE.test('title={label}'), 'JSX title={...} must match');
+    assert.ok(!TITLE_ATTR_RE.test('const title = "x"'), 'JS const title = must not match');
+  });
+
+  it('TOOLTIP_IMPORT_RE matches a Tooltip import and spares a missing one', () => {
+    assert.ok(TOOLTIP_IMPORT_RE.test('import { Tooltip } from "@maka/ui";'), 'barrel import must match');
+    assert.ok(TOOLTIP_IMPORT_RE.test("import { Tooltip } from './primitives/tooltip.js';"), 'primitives import must match');
+    assert.ok(!TOOLTIP_IMPORT_RE.test('import { Button } from "@maka/ui";'), 'no Tooltip import must not match');
+  });
+});
\ No newline at end of file
diff --git a/apps/desktop/src/renderer/app-shell-chrome-actions.tsx b/apps/desktop/src/renderer/app-shell-chrome-actions.tsx
index d0b61f3376..5eaf985d43 100644
--- a/apps/desktop/src/renderer/app-shell-chrome-actions.tsx
+++ b/apps/desktop/src/renderer/app-shell-chrome-actions.tsx
@@ -1,5 +1,5 @@
 import { CircleGauge, Grid3X3, HelpCircle, MessageCircleQuestion, PanelLeftClose, PanelLeftOpen, Search, SquarePen } from '@maka/ui/icons';
-import { Button as UiButton } from '@maka/ui';
+import { Button as UiButton, Tooltip, TooltipContent, TooltipTrigger } from '@maka/ui';
 
 export function AppShellTopbarActions(props: {
   sidebarCollapsed: boolean;
@@ -13,46 +13,49 @@ export function AppShellTopbarActions(props: {
       className={`maka-shell-topbar-rail ${props.sidebarCollapsed ? 'is-collapsed' : 'is-expanded'}`}
       aria-label="窗口快捷操作"
     >
-      <UiButton
-        className="maka-shell-topbar-button"
-        variant="quiet"
-        size="icon-sm"
-        type="button"
-        data-maka-search-trigger="true"
-        onClick={props.onOpenSearchModal}
-        aria-label="搜索对话"
-        title="搜索对话"
-      >
-        <Search size={16} strokeWidth={1.65} aria-hidden="true" />
-      </UiButton>
-      <UiButton
-        className="maka-shell-topbar-button"
-        variant="quiet"
-        size="icon-sm"
-        type="button"
-        onClick={props.sidebarCollapsed ? props.onExpandSidebar : props.onCollapseSidebar}
-        aria-label={props.sidebarCollapsed ? '展开侧边栏' : '收起侧边栏'}
-        aria-expanded={!props.sidebarCollapsed}
-        title={props.sidebarCollapsed ? '展开侧边栏' : '收起侧边栏'}
-      >
-        {props.sidebarCollapsed ? (
-          <PanelLeftOpen size={16} strokeWidth={1.65} aria-hidden="true" />
-        ) : (
-          <PanelLeftClose size={16} strokeWidth={1.65} aria-hidden="true" />
-        )}
-      </UiButton>
-      {props.sidebarCollapsed && (
-        <UiButton
+      <Tooltip>
+        <TooltipTrigger
+          render={<UiButton variant="quiet" size="icon-sm" />}
+          type="button"
           className="maka-shell-topbar-button"
-          variant="quiet"
-          size="icon-sm"
+          data-maka-search-trigger="true"
+          onClick={props.onOpenSearchModal}
+          aria-label="搜索对话"
+        >
+          <Search size={16} strokeWidth={1.65} aria-hidden="true" />
+        </TooltipTrigger>
+        <TooltipContent>搜索对话</TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger
+          render={<UiButton variant="quiet" size="icon-sm" />}
           type="button"
-          onClick={props.onCreateSession}
-          aria-label="新任务"
-          title="新任务"
+          className="maka-shell-topbar-button"
+          onClick={props.sidebarCollapsed ? props.onExpandSidebar : props.onCollapseSidebar}
+          aria-label={props.sidebarCollapsed ? '展开侧边栏' : '收起侧边栏'}
+          aria-expanded={!props.sidebarCollapsed}
         >
-          <SquarePen size={16} strokeWidth={1.65} aria-hidden="true" />
-        </UiButton>
+          {props.sidebarCollapsed ? (
+            <PanelLeftOpen size={16} strokeWidth={1.65} aria-hidden="true" />
+          ) : (
+            <PanelLeftClose size={16} strokeWidth={1.65} aria-hidden="true" />
+          )}
+        </TooltipTrigger>
+        <TooltipContent>{props.sidebarCollapsed ? '展开侧边栏' : '收起侧边栏'}</TooltipContent>
+      </Tooltip>
+      {props.sidebarCollapsed && (
+        <Tooltip>
+          <TooltipTrigger
+            render={<UiButton variant="quiet" size="icon-sm" />}
+            type="button"
+            className="maka-shell-topbar-button"
+            onClick={props.onCreateSession}
+            aria-label="新任务"
+          >
+            <SquarePen size={16} strokeWidth={1.65} aria-hidden="true" />
+          </TooltipTrigger>
+          <TooltipContent>新任务</TooltipContent>
+        </Tooltip>
       )}
     </div>
   );
@@ -66,50 +69,54 @@ export function AppShellWorkspaceTopActions(props: {
 }) {
   return (
     <div className="maka-workspace-top-actions" role="toolbar" aria-label="工作区辅助操作">
-      <UiButton
-        className="maka-workspace-icon-action"
-        variant="quiet"
-        size="icon-sm"
-        type="button"
-        onClick={props.onOpenFeedback}
-        aria-label="问题反馈"
-        title="问题反馈 · 打开关于与环境信息"
-      >
-        <MessageCircleQuestion size={15} strokeWidth={1.7} aria-hidden="true" />
-      </UiButton>
-      <UiButton
-        className="maka-workspace-icon-action"
-        variant="quiet"
-        size="icon-sm"
-        type="button"
-        onClick={props.onOpenPalette}
-        aria-label="打开命令面板"
-        title="打开命令面板"
-      >
-        <Grid3X3 size={15} strokeWidth={1.7} aria-hidden="true" />
-      </UiButton>
-      <UiButton
-        className="maka-workspace-icon-action"
-        variant="quiet"
-        size="icon-sm"
-        type="button"
-        onClick={props.onOpenHelp}
-        aria-label="打开帮助"
-        title="打开帮助"
-      >
-        <HelpCircle size={15} strokeWidth={1.7} aria-hidden="true" />
-      </UiButton>
-      <UiButton
-        className="maka-workspace-icon-action"
-        variant="quiet"
-        size="icon-sm"
-        type="button"
-        onClick={props.onOpenHealth}
-        aria-label="打开健康中心"
-        title="打开健康中心"
-      >
-        <CircleGauge size={15} strokeWidth={1.7} aria-hidden="true" />
-      </UiButton>
+      <Tooltip>
+        <TooltipTrigger
+          render={<UiButton variant="quiet" size="icon-sm" />}
+          type="button"
+          className="maka-workspace-icon-action"
+          onClick={props.onOpenFeedback}
+          aria-label="问题反馈"
+        >
+          <MessageCircleQuestion size={15} strokeWidth={1.7} aria-hidden="true" />
+        </TooltipTrigger>
+        <TooltipContent>问题反馈 · 打开关于与环境信息</TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger
+          render={<UiButton variant="quiet" size="icon-sm" />}
+          type="button"
+          className="maka-workspace-icon-action"
+          onClick={props.onOpenPalette}
+          aria-label="打开命令面板"
+        >
+          <Grid3X3 size={15} strokeWidth={1.7} aria-hidden="true" />
+        </TooltipTrigger>
+        <TooltipContent>打开命令面板</TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger
+          render={<UiButton variant="quiet" size="icon-sm" />}
+          type="button"
+          className="maka-workspace-icon-action"
+          onClick={props.onOpenHelp}
+          aria-label="打开帮助"
+        >
+          <HelpCircle size={15} strokeWidth={1.7} aria-hidden="true" />
+        </TooltipTrigger>
+        <TooltipContent>打开帮助</TooltipContent>
+      </Tooltip>
+      <Tooltip>
+        <TooltipTrigger
+          render={<UiButton variant="quiet" size="icon-sm" />}
+          type="button"
+          className="maka-workspace-icon-action"
+          onClick={props.onOpenHealth}
+          aria-label="打开健康中心"
+        >
+          <CircleGauge size={15} strokeWidth={1.7} aria-hidden="true" />
+        </TooltipTrigger>
+        <TooltipContent>打开健康中心</TooltipContent>
+      </Tooltip>
     </div>
   );
-}
+}
\ No newline at end of file
diff --git a/apps/desktop/src/renderer/artifact-pane.tsx b/apps/desktop/src/renderer/artifact-pane.tsx
index 75d8a8f191..4835f85c65 100644
--- a/apps/desktop/src/renderer/artifact-pane.tsx
+++ b/apps/desktop/src/renderer/artifact-pane.tsx
@@ -69,6 +69,9 @@ import {
   Toolbar,
   ToolbarGroup,
   ToolbarSeparator,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
   formatBytes,
   useToast,
 } from '@maka/ui';
@@ -381,24 +384,25 @@ export function ArtifactPane(props: { sessionId: string | undefined }) {
       onKeyDown={handlePaneKeyDown}
     >
       <header className="maka-artifact-pane-header">
-        <Button
-          type="button"
-          variant="quiet"
-          size="icon-sm"
-          className="maka-artifact-pane-collapse"
-          onClick={() => setCollapsed((current) => !current)}
-          // @kenji a11y gate #3: aria-expanded reflects the actual visible
-          // content state (true when pane shows list + preview + toolbar,
-          // false when collapsed to chevron rail). aria-pressed retained
-          // since this is still a toggle button (a screen reader announces
-          // both "pressed" + "expanded" meaningfully).
-          aria-pressed={collapsed}
-          aria-expanded={!collapsed}
-          aria-label={collapsed ? '展开生成文件面板' : '折叠生成文件面板'}
-          title={collapsed ? '展开生成文件面板' : '折叠生成文件面板'}
-        >
-          {collapsed ? <ChevronLeft size={16} /> : <ChevronRight size={16} />}
-        </Button>
+        <Tooltip>
+          <TooltipTrigger
+            render={<Button variant="quiet" size="icon-sm" />}
+            type="button"
+            className="maka-artifact-pane-collapse"
+            onClick={() => setCollapsed((current) => !current)}
+            // @kenji a11y gate #3: aria-expanded reflects the actual visible
+            // content state (true when pane shows list + preview + toolbar,
+            // false when collapsed to chevron rail). aria-pressed retained
+            // since this is still a toggle button (a screen reader announces
+            // both "pressed" + "expanded" meaningfully).
+            aria-pressed={collapsed}
+            aria-expanded={!collapsed}
+            aria-label={collapsed ? '展开生成文件面板' : '折叠生成文件面板'}
+          >
+            {collapsed ? <ChevronLeft size={16} /> : <ChevronRight size={16} />}
+          </TooltipTrigger>
+          <TooltipContent>{collapsed ? '展开生成文件面板' : '折叠生成文件面板'}</TooltipContent>
+        </Tooltip>
         {!collapsed && (
           <>
             <span className="maka-artifact-pane-title">生成文件</span>
@@ -562,7 +566,6 @@ export function ArtifactPane(props: { sessionId: string | undefined }) {
                   variant="destructive"
                   size="sm"
                   className="maka-artifact-toolbar-button maka-artifact-toolbar-destructive"
-                  title="删除"
                   onClick={() => void runArtifactAction(`${selected.id}:delete`, () => deleteArtifact(selected.id))}
                   disabled={artifactActionBusy}
                   data-pending={pendingArtifactAction === `${selected.id}:delete` ? 'true' : undefined}
diff --git a/apps/desktop/src/renderer/browser-panel.tsx b/apps/desktop/src/renderer/browser-panel.tsx
index cd5a0d9f4a..698f7c5533 100644
--- a/apps/desktop/src/renderer/browser-panel.tsx
+++ b/apps/desktop/src/renderer/browser-panel.tsx
@@ -24,6 +24,9 @@ import {
   EmptyMedia,
   EmptyTitle,
   Input,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
   useToast,
 } from '@maka/ui';
 
@@ -152,44 +155,47 @@ export function BrowserPanel(props: { sessionId: string; hidden: boolean }) {
   return (
     <div className="maka-browser-panel" aria-label="嵌入式浏览器">
       <div className="maka-browser-toolbar">
-        <Button
-          type="button"
-          variant="quiet"
-          size="icon-sm"
-          className="maka-browser-navbtn"
-          aria-label="浏览器后退"
-          title="后退"
-          disabled={!state.canGoBack}
-          onClick={() => void window.maka.browser.back(sessionId)}
-        >
-          <ChevronLeft size={16} aria-hidden />
-        </Button>
-        <Button
-          type="button"
-          variant="quiet"
-          size="icon-sm"
-          className="maka-browser-navbtn"
-          aria-label="浏览器前进"
-          title="前进"
-          disabled={!state.canGoForward}
-          onClick={() => void window.maka.browser.forward(sessionId)}
-        >
-          <ChevronRight size={16} aria-hidden />
-        </Button>
-        <Button
-          type="button"
-          variant="quiet"
-          size="icon-sm"
-          className="maka-browser-navbtn"
-          aria-label={state.loading ? '停止加载页面' : '刷新页面'}
-          title={state.loading ? '停止' : '刷新'}
-          disabled={!state.hasPage && !state.loading}
-          onClick={() =>
-            state.loading ? void window.maka.browser.stop(sessionId) : void window.maka.browser.reload(sessionId)
-          }
-        >
-          {state.loading ? <X size={16} aria-hidden /> : <RotateCw size={16} aria-hidden />}
-        </Button>
+        <Tooltip>
+          <TooltipTrigger
+            render={<Button variant="quiet" size="icon-sm" />}
+            type="button"
+            className="maka-browser-navbtn"
+            aria-label="浏览器后退"
+            disabled={!state.canGoBack}
+            onClick={() => void window.maka.browser.back(sessionId)}
+          >
+            <ChevronLeft size={16} aria-hidden />
+          </TooltipTrigger>
+          <TooltipContent>后退</TooltipContent>
+        </Tooltip>
+        <Tooltip>
+          <TooltipTrigger
+            render={<Button variant="quiet" size="icon-sm" />}
+            type="button"
+            className="maka-browser-navbtn"
+            aria-label="浏览器前进"
+            disabled={!state.canGoForward}
+            onClick={() => void window.maka.browser.forward(sessionId)}
+          >
+            <ChevronRight size={16} aria-hidden />
+          </TooltipTrigger>
+          <TooltipContent>前进</TooltipContent>
+        </Tooltip>
+        <Tooltip>
+          <TooltipTrigger
+            render={<Button variant="quiet" size="icon-sm" />}
+            type="button"
+            className="maka-browser-navbtn"
+            aria-label={state.loading ? '停止加载页面' : '刷新页面'}
+            disabled={!state.hasPage && !state.loading}
+            onClick={() =>
+              state.loading ? void window.maka.browser.stop(sessionId) : void window.maka.browser.reload(sessionId)
+            }
+          >
+            {state.loading ? <X size={16} aria-hidden /> : <RotateCw size={16} aria-hidden />}
+          </TooltipTrigger>
+          <TooltipContent>{state.loading ? '停止' : '刷新'}</TooltipContent>
+        </Tooltip>
         <Input
           className="maka-browser-address"
           type="text"
@@ -212,17 +218,18 @@ export function BrowserPanel(props: { sessionId: string; hidden: boolean }) {
             }
           }}
         />
-        <Button
-          type="button"
-          variant="quiet"
-          size="icon-sm"
-          className="maka-browser-navbtn"
-          aria-label="关闭浏览器页面"
-          title="关闭页面"
-          onClick={() => void window.maka.browser.close(sessionId)}
-        >
-          <X size={16} aria-hidden />
-        </Button>
+        <Tooltip>
+          <TooltipTrigger
+            render={<Button variant="quiet" size="icon-sm" />}
+            type="button"
+            className="maka-browser-navbtn"
+            aria-label="关闭浏览器页面"
+            onClick={() => void window.maka.browser.close(sessionId)}
+          >
+            <X size={16} aria-hidden />
+          </TooltipTrigger>
+          <TooltipContent>关闭页面</TooltipContent>
+        </Tooltip>
       </div>
       <div className="maka-browser-strip" ref={stripRef}>
         {!state.hasPage && (
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index d705128eb2..754baac333 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -67,6 +67,11 @@ export {
   CollapsiblePanel as PrimitiveCollapsiblePanel,
   CollapsiblePrimitive as PrimitiveCollapsiblePrimitive,
 } from './primitives/collapsible.js';
+export {
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+} from './primitives/tooltip.js';
 export {
   Tabs as PrimitiveTabs,
   TabsList as PrimitiveTabsList,
diff --git a/packages/ui/src/primitives/tooltip.tsx b/packages/ui/src/primitives/tooltip.tsx
new file mode 100644
index 0000000000..465be9b282
--- /dev/null
+++ b/packages/ui/src/primitives/tooltip.tsx
@@ -0,0 +1,62 @@
+"use client";
+
+import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip";
+import { cn } from "../utils.js";
+import type React from "react";
+
+// Base UI Tooltip wrappers for the icon-only-action buttons that used the
+// native `title=` attribute (an unstyled, delayed browser tooltip). Base UI
+// Tooltip gives a themed, positioned, hover+focus tooltip matching the app.
+// The `data-slot` hooks follow the style-hook convention (item 23).
+//
+// Usage:
+//   <Tooltip>
+//     <TooltipTrigger asChild><Button>…</Button></TooltipTrigger>
+//     <TooltipContent>{label}</TooltipContent>
+//   </Tooltip>
+//
+// TooltipContent collapses Portal + Positioner + Popup (the same shape
+// DialogContent uses for the dialog) so the call site is one component. The
+// Popup carries the themed tooltip look (popover bg/corner/shadow); the
+// Positioner owns placement + the z-layer.
+
+export function Tooltip({
+  ...props
+}: TooltipPrimitive.Root.Props): React.ReactElement {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />;
+}
+
+export function TooltipTrigger({
+  className,
+  ...props
+}: TooltipPrimitive.Trigger.Props): React.ReactElement {
+  return (
+    <TooltipPrimitive.Trigger
+      className={className}
+      data-slot="tooltip-trigger"
+      {...props}
+    />
+  );
+}
+
+export function TooltipContent({
+  className,
+  ...props
+}: Omit<TooltipPrimitive.Popup.Props, "render"> & React.HTMLAttributes<HTMLDivElement>): React.ReactElement {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Positioner sideOffset={6}>
+        <TooltipPrimitive.Popup
+          className={cn(
+            "z-[var(--z-overlay)] max-w-[min(90vw,320px)] rounded-md bg-popover px-2 py-1 text-xs text-popover-foreground shadow-maka-panel",
+            className,
+          )}
+          data-slot="tooltip-content"
+          {...props}
+        />
+      </TooltipPrimitive.Positioner>
+    </TooltipPrimitive.Portal>
+  );
+}
+
+export { TooltipPrimitive };
\ No newline at end of file

From a3c1fda78258361a606a2e99769a28213adafa12 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Sun, 5 Jul 2026 14:36:39 +0800
Subject: [PATCH 04/10] feat(ui): migrate port inputs to Base UI NumberField
 (#520 PR5 item 21)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Migrate the two gateway/proxy port inputs off the native Input +
Number(event.currentTarget.value) hand-conversion onto Base UI NumberField,
which binds value: number | null directly and parses numeric input itself.

Sites:
- general-settings-page proxy port: value={proxyDraft.port || null}
  (0 renders empty, matching the old String(port || '')), onValueChange
  writes v ?? 0 (empty -> 0, matching the old Number(value) || 0).
- open-gateway-settings-page gateway port: value={gatewayDraft.port}
  (0 renders "0", matching String(port)), onValueChange writes v ?? 3939
  (empty -> 3939, matching Number(value) || 3939). inputMode="numeric" stays
  on the input.

New primitive: packages/ui/src/primitives/number-field.tsx wraps Base UI
NumberField Root / Input with data-slot="number-field" / "number-field-input".
NumberFieldInput carries the maka standalone-input look via the shared
inputClasses export (the same classes the native ui.tsx Input used), so the
port inputs keep their look; unstyled gives the bare form for any future
Field/InputGroup embedding. Exported from the barrel as NumberField /
NumberFieldInput (no ui.tsx wrapper, so direct names, like Tooltip).

To share the maka input styling without duplicating it, ui.tsx exports
inputClasses + bareFieldClasses (const -> export const); the number-field
primitive imports them. (The input-canonical commit, item 22, will move
these into primitives/input.tsx and update this import.)

TDD: number-field-converge-contract.test.ts written first (RED: the two
files still carried Number(event.currentTarget.value), no primitive). GREEN:
primitive + 2 migrations. The contract bans the hand-conversion
(Number(event.currentTarget.value)) and requires a NumberField import; it
pins the primitive's data-slot on Root/Input. The hand-convert regex is
specific (Number(event.currentTarget.value)) so a different Number() call is
not flagged.

Existing test updated: settings-network-gateway-contract's two port-input
assertions now pin the NumberField form (value={...|| null} / value={...} +
onValueChange={(v) => update...({ port: v ?? default })}) instead of the old
String(value) + onChange Number(event.currentTarget.value). The intent —
"port input renders from the local draft while persisting in the background"
— is preserved; only the binding form changed. The "port input must not
lock after each digit" doesNotMatch still passes (the NumberFieldInput is not
disabled while saving).

Verification: 1982/1982 desktop tests pass (+3 number-field contract).
typecheck clean. renderer build clean. Screenshots: the port inputs are in
general/open-gateway settings (no capture scenario), so the captured
scenarios show no change — settings-appearance 0.0136 (PR4's settings-nav
snap residual) and turn-narrative 0.0009 (the disclosure commit's residual);
commit 4 adds 0. The port inputs keep their look via the shared inputClasses.
---
 .../number-field-converge-contract.test.ts    | 61 +++++++++++++++++++
 .../settings-network-gateway-contract.test.ts |  4 +-
 .../settings/general-settings-page.tsx        |  6 +-
 .../settings/open-gateway-settings-page.tsx   | 11 ++--
 packages/ui/src/index.ts                      |  4 ++
 packages/ui/src/primitives/number-field.tsx   | 46 ++++++++++++++
 packages/ui/src/ui.tsx                        |  4 +-
 7 files changed, 124 insertions(+), 12 deletions(-)
 create mode 100644 apps/desktop/src/main/__tests__/number-field-converge-contract.test.ts
 create mode 100644 packages/ui/src/primitives/number-field.tsx

diff --git a/apps/desktop/src/main/__tests__/number-field-converge-contract.test.ts b/apps/desktop/src/main/__tests__/number-field-converge-contract.test.ts
new file mode 100644
index 0000000000..f98619728e
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/number-field-converge-contract.test.ts
@@ -0,0 +1,61 @@
+/**
+ * PR-NUMBER-FIELD-CONVERGE-0 (issue #520 PR5 item 21, 2026-07-05):
+ * the two gateway/proxy port inputs migrate off the native `Input` +
+ * `Number(event.currentTarget.value)` hand-conversion onto Base UI
+ * NumberField, which binds `value: number | null` directly and parses
+ * numeric input itself (no manual string→number, no `|| default` fallback
+ * gymnastics).
+ *
+ * Sites:
+ * - general-settings-page proxy port (default 0 on empty).
+ * - open-gateway-settings-page gateway port (default 3939 on empty).
+ *
+ * The contract: the two files must not carry the `Number(event.currentTarget
+ * .value)` hand-conversion and must import NumberField; the primitive must
+ * wrap Base UI NumberField with the data-slot convention (item 23).
+ */
+
+import { strict as assert } from 'node:assert';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { describe, it } from 'node:test';
+import { REPO_ROOT } from './css-test-helpers.js';
+
+const MIGRATED_FILES = [
+  'apps/desktop/src/renderer/settings/general-settings-page.tsx',
+  'apps/desktop/src/renderer/settings/open-gateway-settings-page.tsx',
+];
+
+const NUMBER_FIELD_PRIMITIVE = 'packages/ui/src/primitives/number-field.tsx';
+
+/** The hand-conversion the migration removes. */
+const HAND_CONVERT_RE = /Number\(event\.currentTarget\.value\)/;
+
+/** A NumberField import from the barrel / primitives / @base-ui. */
+const NUMBER_FIELD_IMPORT_RE = /import\s+\{[^}]*\bNumberField\b[^}]*\}\s+from\s+['"][^'"]*(?:@maka\/ui|primitives\/number-field|@base-ui\/react\/number-field)[^'"]*['"]/;
+
+describe('PR-NUMBER-FIELD-CONVERGE-0 contract', () => {
+  it('the port-input files use Base UI NumberField (no Number(event.currentTarget.value) hand-conversion)', async () => {
+    for (const rel of MIGRATED_FILES) {
+      const src = await readFile(resolve(REPO_ROOT, rel), 'utf8');
+      assert.ok(!HAND_CONVERT_RE.test(src), `${rel}: must not hand-convert Number(event.currentTarget.value) — use Base UI NumberField (value: number | null, onValueChange)`);
+      assert.match(src, NUMBER_FIELD_IMPORT_RE, `${rel}: must import NumberField from @maka/ui / primitives/number-field / @base-ui/react/number-field`);
+    }
+  });
+
+  it('primitives/number-field.tsx wraps Base UI NumberField with data-slot on Root / Input', async () => {
+    const src = await readFile(resolve(REPO_ROOT, NUMBER_FIELD_PRIMITIVE), 'utf8');
+    assert.match(src, /@base-ui\/react\/number-field/, 'must import from @base-ui/react/number-field');
+    for (const slot of ['number-field', 'number-field-input']) {
+      assert.match(src, new RegExp(`data-slot="${slot}"`), `must expose data-slot="${slot}" (style-hook convention, item 23)`);
+    }
+  });
+});
+
+describe('number-field negative cases', () => {
+  it('HAND_CONVERT_RE matches the hand-conversion, not other Number() uses', () => {
+    assert.ok(HAND_CONVERT_RE.test('Number(event.currentTarget.value)'), 'the hand-conversion must match');
+    assert.ok(!HAND_CONVERT_RE.test('Number(123)'), 'a plain Number(123) must not match');
+    assert.ok(!HAND_CONVERT_RE.test('const n = Number("x")'), 'a different Number() call must not match');
+  });
+});
\ No newline at end of file
diff --git a/apps/desktop/src/main/__tests__/settings-network-gateway-contract.test.ts b/apps/desktop/src/main/__tests__/settings-network-gateway-contract.test.ts
index 9a04c46c6e..9db9661aed 100644
--- a/apps/desktop/src/main/__tests__/settings-network-gateway-contract.test.ts
+++ b/apps/desktop/src/main/__tests__/settings-network-gateway-contract.test.ts
@@ -58,7 +58,7 @@ describe('Settings network and gateway persistence contract', () => {
     );
     assert.match(
       networkBlock,
-      /value=\{String\(proxyDraft\.port \|\| ''\)\}[\s\S]*onChange=\{\(event\) => void updateProxy\(\{ port: Number\(event\.currentTarget\.value\) \|\| 0 \}\)\}/,
+      /value=\{proxyDraft\.port \|\| null\}[\s\S]*onValueChange=\{\(v\) => void updateProxy\(\{ port: v \?\? 0 \}\)\}/,
       'Network proxy port input must render from the local draft while persisting in the background',
     );
     assert.match(
@@ -231,7 +231,7 @@ describe('Settings network and gateway persistence contract', () => {
     );
     assert.match(
       gatewayBlock,
-      /value=\{String\(gatewayDraft\.port\)\}[\s\S]*onChange=\{\(event\) => void updateGateway\(\{ port: Number\(event\.currentTarget\.value\) \|\| 3939 \}\)\}/,
+      /value=\{gatewayDraft\.port\}[\s\S]*onValueChange=\{\(v\) => void updateGateway\(\{ port: v \?\? 3939 \}\)\}/,
       'Open Gateway port input must render from the local draft while persisting in the background',
     );
     assert.doesNotMatch(
diff --git a/apps/desktop/src/renderer/settings/general-settings-page.tsx b/apps/desktop/src/renderer/settings/general-settings-page.tsx
index 212aed0dbb..b906f8a313 100644
--- a/apps/desktop/src/renderer/settings/general-settings-page.tsx
+++ b/apps/desktop/src/renderer/settings/general-settings-page.tsx
@@ -11,6 +11,8 @@ import type { TestProxyInput } from '@maka/core/settings/network-settings';
 import {
   Button,
   Input,
+  NumberField,
+  NumberFieldInput,
   Menu,
   MenuTrigger,
   ModelPicker,
@@ -355,7 +357,9 @@ function NetworkProxySection(props: {
             </label>
             <label>
               <span>端口</span>
-              <Input value={String(proxyDraft.port || '')} onChange={(event) => void updateProxy({ port: Number(event.currentTarget.value) || 0 })} placeholder="7890" aria-label="代理端口" />
+              <NumberField value={proxyDraft.port || null} onValueChange={(v) => void updateProxy({ port: v ?? 0 })}>
+                <NumberFieldInput placeholder="7890" aria-label="代理端口" />
+              </NumberField>
             </label>
           </div>
 
diff --git a/apps/desktop/src/renderer/settings/open-gateway-settings-page.tsx b/apps/desktop/src/renderer/settings/open-gateway-settings-page.tsx
index dce988bab0..484a9b84bd 100644
--- a/apps/desktop/src/renderer/settings/open-gateway-settings-page.tsx
+++ b/apps/desktop/src/renderer/settings/open-gateway-settings-page.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useRef, useState } from 'react';
 import type { AppSettings, OpenGatewayRuntimeStatus, UpdateAppSettingsResult } from '@maka/core';
-import { Button, Input, SettingsSelect, SettingsSwitch as Switch, Textarea, useToast } from '@maka/ui';
+import { Button, Input, NumberField, NumberFieldInput, SettingsSelect, SettingsSwitch as Switch, Textarea, useToast } from '@maka/ui';
 import { PasswordInput } from './password-input';
 import { MetricCard } from './settings-metric-card';
 import { SettingsRows, SettingRow } from './settings-rows';
@@ -232,12 +232,9 @@ export function OpenGatewaySettingsPage(props: {
         </label>
         <label>
           <span>端口</span>
-          <Input
-            value={String(gatewayDraft.port)}
-            inputMode="numeric"
-            onChange={(event) => void updateGateway({ port: Number(event.currentTarget.value) || 3939 })}
-            aria-label="开放网关端口"
-          />
+          <NumberField value={gatewayDraft.port} onValueChange={(v) => void updateGateway({ port: v ?? 3939 })}>
+            <NumberFieldInput inputMode="numeric" aria-label="开放网关端口" />
+          </NumberField>
         </label>
         <label>
           <span>访问 token</span>
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 754baac333..9720899629 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -72,6 +72,10 @@ export {
   TooltipTrigger,
   TooltipContent,
 } from './primitives/tooltip.js';
+export {
+  NumberField,
+  NumberFieldInput,
+} from './primitives/number-field.js';
 export {
   Tabs as PrimitiveTabs,
   TabsList as PrimitiveTabsList,
diff --git a/packages/ui/src/primitives/number-field.tsx b/packages/ui/src/primitives/number-field.tsx
new file mode 100644
index 0000000000..f97dae2993
--- /dev/null
+++ b/packages/ui/src/primitives/number-field.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import { NumberField as NumberFieldPrimitive } from "@base-ui/react/number-field";
+import { cn } from "../utils.js";
+import { bareFieldClasses, inputClasses } from "../ui.js";
+import type React from "react";
+
+// Base UI NumberField wrappers for the gateway/proxy port inputs that
+// hand-converted with Number(event.currentTarget.value). Base UI binds
+// value: number | null directly and parses numeric input itself, so the
+// call site drops the manual string→number + `|| default` fallback.
+//
+// NumberFieldInput carries the maka standalone-input look (the same
+// inputClasses the native ui.tsx Input used) via the shared `inputClasses`
+// export, and the `unstyled` flag gives the bare form for any future
+// Field/InputGroup embedding. data-slot follows the style-hook convention
+// (item 23).
+
+export function NumberField({
+  className,
+  ...props
+}: NumberFieldPrimitive.Root.Props): React.ReactElement {
+  return (
+    <NumberFieldPrimitive.Root
+      className={cn("flex min-h-9 w-full", className)}
+      data-slot="number-field"
+      {...props}
+    />
+  );
+}
+
+export function NumberFieldInput({
+  className,
+  unstyled = false,
+  ...props
+}: NumberFieldPrimitive.Input.Props & { unstyled?: boolean }): React.ReactElement {
+  return (
+    <NumberFieldPrimitive.Input
+      className={cn(unstyled ? bareFieldClasses : inputClasses, className)}
+      data-slot="number-field-input"
+      {...props}
+    />
+  );
+}
+
+export { NumberFieldPrimitive };
\ No newline at end of file
diff --git a/packages/ui/src/ui.tsx b/packages/ui/src/ui.tsx
index bd5c219d77..3b849fa684 100644
--- a/packages/ui/src/ui.tsx
+++ b/packages/ui/src/ui.tsx
@@ -141,14 +141,14 @@ export function Badge({ className, variant, ...props }: BadgeProps) {
   return <span className={cn(badgeVariants({ variant }), className)} {...props} />;
 }
 
-const inputClasses = [
+export const inputClasses = [
   'flex min-h-9 w-full rounded-sm border border-input bg-[oklch(from_var(--foreground)_l_c_h_/_0.02)] px-3 py-2 text-sm text-foreground shadow-sm',
   'placeholder:text-foreground-secondary/70',
   'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
   'disabled:cursor-not-allowed disabled:opacity-50',
 ].join(' ');
 
-const bareFieldClasses = [
+export const bareFieldClasses = [
   'appearance-none rounded-none border-0 bg-transparent p-0 text-inherit shadow-none outline-none [font:inherit]',
   'focus-visible:outline-none focus-visible:ring-0 focus-visible:ring-offset-0',
   'disabled:cursor-not-allowed disabled:opacity-60',

From 84a908a757312da23dae88cdc0743a3d37d69f1b Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Sun, 5 Jul 2026 16:47:25 +0800
Subject: [PATCH 05/10] fix(ui): control tool-activity Collapsible open from
 item.status (#543 review P2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The disclosure migration made tool-activity's tool cards `defaultOpen={isOpenByDefault(item.status)}` (uncontrolled — open is decided once on first render). That regressed the pre-Collapsible `<details open={isOpenByDefault(status)}>` behavior, which re-evaluated open every render: a card that defaults open while pending/running no longer auto-collapsed when it settled to completed/interrupted.

Restore the status-following behavior with a controlled state machine:
- Extract the per-item card into a `ToolActivityCard` component (hooks can't
  live in the `.map` callback).
- `useState(isOpenByDefault(item.status))` seeds open; `useEffect` re-syncs it
  to `isOpenByDefault(item.status)` on every `[item.status]` change, so a
  pending/running card collapses when it settles.
- `onOpenChange={setOpen}` lets the user still toggle the card in between;
  the next status change re-syncs. (The pre-Collapsible `<details>` let the
  user toggle too, but only as a side effect of React not re-rendering — the
  state machine makes that intentional and predictable.)

TDD: disclosure-collapsible-contract gains an assertion that tool-activity
must NOT use `defaultOpen`, must use `onOpenChange`, and must re-sync via
`useEffect` on `[item.status]`. RED first (defaultOpen was present, no
onOpenChange, no re-sync), then GREEN. (maka has no React testing-library /
react-test-renderer, so the behavior is locked structurally + verified by
hand; the rerender-act path is out of scope.)

Verification: 2009/2009 desktop tests pass (+1 contract assertion). typecheck
clean. turn-narrative screenshot unchanged (0.09% — the disclosure commit's
summary→button residual; the card state is fixed by the scenario seed, and
controlled-open matches the pre-Collapsible behavior at that fixed state).
---
 .../disclosure-collapsible-contract.test.ts   |  14 +++
 packages/ui/src/tool-activity.tsx             | 111 ++++++++++--------
 2 files changed, 77 insertions(+), 48 deletions(-)

diff --git a/apps/desktop/src/main/__tests__/disclosure-collapsible-contract.test.ts b/apps/desktop/src/main/__tests__/disclosure-collapsible-contract.test.ts
index 8ec540d0a6..e3342b1151 100644
--- a/apps/desktop/src/main/__tests__/disclosure-collapsible-contract.test.ts
+++ b/apps/desktop/src/main/__tests__/disclosure-collapsible-contract.test.ts
@@ -55,6 +55,20 @@ describe('PR-DISCLOSURE-COLLAPSIBLE-0 contract', () => {
       assert.match(src, new RegExp(`data-slot="${slot}"`), `must expose data-slot="${slot}" (style-hook convention, item 23)`);
     }
   });
+
+  it('tool-activity Collapsible is controlled (open follows item.status), not defaultOpen', async () => {
+    // A `defaultOpen` card decides open only on first render, so a card that
+    // defaults open while pending/running would NOT auto-collapse when it
+    // settles to completed/interrupted — the pre-Collapsible `<details
+    // open={isOpenByDefault(status)}>` re-evaluated open every render. The
+    // controlled form (open + onOpenChange, re-synced via useEffect on
+    // [item.status]) restores that: status change collapses/expands the card,
+    // the user can still toggle in between.
+    const src = await readFile(resolve(REPO_ROOT, 'packages/ui/src/tool-activity.tsx'), 'utf8');
+    assert.ok(!/defaultOpen=/.test(src), 'tool-activity must not use defaultOpen (a running card that defaults open would not auto-collapse when it settles); use controlled open that follows item.status');
+    assert.match(src, /\bonOpenChange\b/, 'tool-activity Collapsible must be controlled via onOpenChange');
+    assert.match(src, /useEffect\([^]*\[item\.status\]/, 'tool-activity must re-sync open when item.status changes (useEffect on [item.status])');
+  });
 });
 
 describe('disclosure-collapsible negative cases', () => {
diff --git a/packages/ui/src/tool-activity.tsx b/packages/ui/src/tool-activity.tsx
index 4638de03f6..4fc5ccddb2 100644
--- a/packages/ui/src/tool-activity.tsx
+++ b/packages/ui/src/tool-activity.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { type ToolResultContent } from '@maka/core';
 import { AlertOctagon, Check, Copy, X } from './icons.js';
 import { useClipboardCopyFeedback } from './clipboard-feedback.js';
@@ -105,57 +105,72 @@ export function ToolActivity(props: { items: ToolActivityItem[] }) {
         <strong>工具调用</strong>
         <span className={toolVariants({ part: 'count' })} aria-label={`${props.items.length} 次调用`}>{props.items.length}</span>
       </header>
-      {props.items.map((item) => {
-        const duration = formatDuration(item.durationMs);
-        const errored = item.status === 'errored';
-        const permissionDenied = isPermissionDeniedToolResult(item.result);
-        return (
-          <Collapsible
-            key={item.toolUseId}
-            data-slot="tool"
-            className={toolVariants({ part: 'item' })}
-            data-status={item.status}
-            defaultOpen={isOpenByDefault(item.status)}
-          >
-            <CollapsibleTrigger className={toolVariants({ part: 'header' })}>
-              <span className={toolVariants({ part: 'dot' })} data-status={item.status} aria-hidden="true" />
-              <span className={toolVariants({ part: 'name' })}>{resolveToolDisplayName(item)}</span>
-              <span className={toolVariants({ part: 'meta' })}>
-                {duration && <span className={toolVariants({ part: 'duration' })}>{duration}</span>}
-                <span className={toolVariants({ part: 'status-label' })}>{STATUS_LABEL[item.status]}</span>
-              </span>
-            </CollapsibleTrigger>
-            <CollapsiblePanel>
-              <div className={toolVariants({ part: 'body' })}>
-                {errored && <ToolErrorBanner result={item.result} />}
-                {item.intent && !permissionDenied && <p className={toolVariants({ part: 'intent' })}>{formatToolIntent(item.intent)}</p>}
-                {item.args !== undefined && !permissionDenied && (
-                  <pre className={`maka-code ${toolVariants({ part: 'args' })}`}>{formatRedactedJson(item.args)}</pre>
-                )}
-                {item.outputChunks && item.outputChunks.length > 0 && (
-                  <ToolOutputStream
-                    chunks={item.outputChunks}
-                    live={item.status === 'running' || item.status === 'pending'}
-                    interrupted={item.status === 'interrupted'}
-                    truncated={item.outputTruncated === true}
-                  />
-                )}
-                {item.result && !permissionDenied && (
-                  isConnectorTool(item.toolName) && item.result.kind === 'json' ? (
-                    <LoadToolResultPreview args={item.args} value={item.result.value} />
-                  ) : (
-                    <ToolResultPreview content={item.result} />
-                  )
-                )}
-              </div>
-            </CollapsiblePanel>
-          </Collapsible>
-        );
-      })}
+      {props.items.map((item) => (
+        <ToolActivityCard key={item.toolUseId} item={item} />
+      ))}
     </section>
   );
 }
 
+function ToolActivityCard({ item }: { item: ToolActivityItem }) {
+  const duration = formatDuration(item.durationMs);
+  const errored = item.status === 'errored';
+  const permissionDenied = isPermissionDeniedToolResult(item.result);
+  // Controlled open that follows item.status: a card that defaults open while
+  // pending/running auto-collapses when it settles to completed/interrupted
+  // (restoring the pre-Collapsible native-disclosure behavior, where
+  // open={isOpenByDefault(status)} re-evaluated every render). The user can
+  // still toggle in between — onOpenChange updates local state, and the next
+  // status change re-syncs. See disclosure-collapsible-contract: defaultOpen
+  // is banned here.
+  const [open, setOpen] = useState(isOpenByDefault(item.status));
+  useEffect(() => {
+    setOpen(isOpenByDefault(item.status));
+  }, [item.status]);
+  return (
+    <Collapsible
+      data-slot="tool"
+      className={toolVariants({ part: 'item' })}
+      data-status={item.status}
+      open={open}
+      onOpenChange={setOpen}
+    >
+      <CollapsibleTrigger className={toolVariants({ part: 'header' })}>
+        <span className={toolVariants({ part: 'dot' })} data-status={item.status} aria-hidden="true" />
+        <span className={toolVariants({ part: 'name' })}>{resolveToolDisplayName(item)}</span>
+        <span className={toolVariants({ part: 'meta' })}>
+          {duration && <span className={toolVariants({ part: 'duration' })}>{duration}</span>}
+          <span className={toolVariants({ part: 'status-label' })}>{STATUS_LABEL[item.status]}</span>
+        </span>
+      </CollapsibleTrigger>
+      <CollapsiblePanel>
+        <div className={toolVariants({ part: 'body' })}>
+          {errored && <ToolErrorBanner result={item.result} />}
+          {item.intent && !permissionDenied && <p className={toolVariants({ part: 'intent' })}>{formatToolIntent(item.intent)}</p>}
+          {item.args !== undefined && !permissionDenied && (
+            <pre className={`maka-code ${toolVariants({ part: 'args' })}`}>{formatRedactedJson(item.args)}</pre>
+          )}
+          {item.outputChunks && item.outputChunks.length > 0 && (
+            <ToolOutputStream
+              chunks={item.outputChunks}
+              live={item.status === 'running' || item.status === 'pending'}
+              interrupted={item.status === 'interrupted'}
+              truncated={item.outputTruncated === true}
+            />
+          )}
+          {item.result && !permissionDenied && (
+            isConnectorTool(item.toolName) && item.result.kind === 'json' ? (
+              <LoadToolResultPreview args={item.args} value={item.result.value} />
+            ) : (
+              <ToolResultPreview content={item.result} />
+            )
+          )}
+        </div>
+      </CollapsiblePanel>
+    </Collapsible>
+  );
+}
+
 /**
  * PR-UI-12 — live stdout/stderr stream from PR-REAL-4 `tool_output_delta`.
  *

From a6adb77223f2a20e089bd7ed326ce1d2259b4ae4 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Sun, 5 Jul 2026 16:48:46 +0800
Subject: [PATCH 06/10] fix(ui): export Collapsible directly from barrel + fix
 tooltip doc (#543 review P3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two unrelated P3 nits from review, both one-line-ish:

1. Collapsible barrel export was aliased `as PrimitiveCollapsible` (the old
   Tabs/Accordion convention), while the other new-in-PR5 primitives (Tooltip,
   NumberField) export directly. The disclosure-collapsible-contract regex
   allowed `@maka/ui` as an import path, but the barrel didn't actually export
   `Collapsible` under that name — a phantom-pass path. Export
   Collapsible/CollapsibleTrigger/CollapsiblePanel directly (drop the
   `Primitive*` aliases and the `CollapsiblePrimitive` re-export — nothing
   consumes them, and Tooltip/NumberField don't export their Primitive either).
   The internal sites keep importing via `./primitives/collapsible.js` (the
   in-package convention — alert/chat/etc. all use relative primitive paths),
   so the `@maka/ui` path is now genuinely available rather than phantom.

2. tooltip.tsx usage doc showed `<TooltipTrigger asChild>` (Radix), but this
   PR's convention is Base UI v1's `render` prop. Fix the example to
   `render={<Button />}` and note that the Trigger merges its props + children
   into the rendered element, so the next person doesn't copy the comment and
   hit the same typecheck failure the migration hit.

Verification: 2009/2009 desktop tests pass. typecheck clean. No visual change
(barrel export names + a doc comment).
---
 packages/ui/src/index.ts               | 7 +++----
 packages/ui/src/primitives/tooltip.tsx | 5 ++++-
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index 9720899629..9ae2653163 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -62,10 +62,9 @@ export * from './primitives/settings-switch.js';
 export * from './primitives/input-group.js';
 export * from './primitives/toolbar.js';
 export {
-  Collapsible as PrimitiveCollapsible,
-  CollapsibleTrigger as PrimitiveCollapsibleTrigger,
-  CollapsiblePanel as PrimitiveCollapsiblePanel,
-  CollapsiblePrimitive as PrimitiveCollapsiblePrimitive,
+  Collapsible,
+  CollapsibleTrigger,
+  CollapsiblePanel,
 } from './primitives/collapsible.js';
 export {
   Tooltip,
diff --git a/packages/ui/src/primitives/tooltip.tsx b/packages/ui/src/primitives/tooltip.tsx
index 465be9b282..29a4e20734 100644
--- a/packages/ui/src/primitives/tooltip.tsx
+++ b/packages/ui/src/primitives/tooltip.tsx
@@ -11,10 +11,13 @@ import type React from "react";
 //
 // Usage:
 //   <Tooltip>
-//     <TooltipTrigger asChild><Button>…</Button></TooltipTrigger>
+//     <TooltipTrigger render={<Button />}>…</TooltipTrigger>
 //     <TooltipContent>{label}</TooltipContent>
 //   </Tooltip>
 //
+// Base UI v1 uses the `render` prop (not Radix `asChild`): the Trigger merges
+// its own props + children into the rendered element.
+//
 // TooltipContent collapses Portal + Positioner + Popup (the same shape
 // DialogContent uses for the dialog) so the call site is one component. The
 // Popup carries the themed tooltip look (popover bg/corner/shadow); the

From f46189aaec9885a7e7eb092107cfe82fa548c194 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Sun, 5 Jul 2026 16:50:38 +0800
Subject: [PATCH 07/10] fix(ui): add Base UI Tooltip to artifact delete button
 (#543 review P3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The tooltip migration dropped the delete button's native `title="删除"` (the
button is icon-only at rest — the visible 删除/删除中… label is visually
hidden via .maka-artifact-toolbar-destructive-label, kept only for screen
readers). The screen-reader path was preserved, but mouse users lost the
hover hint.

Wrap the delete button in a Base UI Tooltip (same shape as the artifact-pane
collapse button already migrated in this PR): TooltipTrigger renders the
destructive Button, TooltipContent mirrors the 删除/删除中… label for hover.
The visually-hidden span still carries the SR label; the two are complementary,
not redundant.

Verification: 2009/2009 desktop tests pass. typecheck clean. turn-narrative
screenshot unchanged (0.09% — the disclosure commit's residual; the delete
button's tooltip is hover-only, and the button's rest appearance is unchanged).
---
 apps/desktop/src/renderer/artifact-pane.tsx | 35 +++++++++++----------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/apps/desktop/src/renderer/artifact-pane.tsx b/apps/desktop/src/renderer/artifact-pane.tsx
index 4835f85c65..b4196a443b 100644
--- a/apps/desktop/src/renderer/artifact-pane.tsx
+++ b/apps/desktop/src/renderer/artifact-pane.tsx
@@ -561,22 +561,25 @@ export function ArtifactPane(props: { sessionId: string | undefined }) {
               </ToolbarGroup>
               <ToolbarSeparator className="maka-artifact-toolbar-separator" orientation="vertical" />
               <ToolbarGroup className="maka-artifact-toolbar-group maka-artifact-toolbar-danger-group">
-                <Button
-                  type="button"
-                  variant="destructive"
-                  size="sm"
-                  className="maka-artifact-toolbar-button maka-artifact-toolbar-destructive"
-                  onClick={() => void runArtifactAction(`${selected.id}:delete`, () => deleteArtifact(selected.id))}
-                  disabled={artifactActionBusy}
-                  data-pending={pendingArtifactAction === `${selected.id}:delete` ? 'true' : undefined}
-                  aria-busy={pendingArtifactAction === `${selected.id}:delete` ? 'true' : undefined}
-                >
-                  <Trash2 size={14} aria-hidden="true" />
-                  {/* Icon-only at rest: the visible label wrapped the toolbar
-                      onto a second line at 1280 pane width, stranding 删除
-                      alone bottom-right. Label stays for screen readers. */}
-                  <span className="maka-artifact-toolbar-destructive-label">{pendingArtifactAction === `${selected.id}:delete` ? '删除中…' : '删除'}</span>
-                </Button>
+                <Tooltip>
+                  <TooltipTrigger
+                    render={<Button type="button" variant="destructive" size="sm" className="maka-artifact-toolbar-button maka-artifact-toolbar-destructive" />}
+                    onClick={() => void runArtifactAction(`${selected.id}:delete`, () => deleteArtifact(selected.id))}
+                    disabled={artifactActionBusy}
+                    data-pending={pendingArtifactAction === `${selected.id}:delete` ? 'true' : undefined}
+                    aria-busy={pendingArtifactAction === `${selected.id}:delete` ? 'true' : undefined}
+                  >
+                    <Trash2 size={14} aria-hidden="true" />
+                    {/* Icon-only at rest: the visible label wrapped the toolbar
+                        onto a second line at 1280 pane width, stranding 删除
+                        alone bottom-right. The label span stays for screen
+                        readers (visually hidden); the Tooltip mirrors it for
+                        mouse hover, replacing the native hover tooltip this
+                        button lost in the tooltip migration. */}
+                    <span className="maka-artifact-toolbar-destructive-label">{pendingArtifactAction === `${selected.id}:delete` ? '删除中…' : '删除'}</span>
+                  </TooltipTrigger>
+                  <TooltipContent>{pendingArtifactAction === `${selected.id}:delete` ? '删除中…' : '删除'}</TooltipContent>
+                </Tooltip>
               </ToolbarGroup>
             </Toolbar>
           )}

From 3419a582e04ec7a98abddb1b3725034e9ebfee84 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Sun, 5 Jul 2026 17:12:33 +0800
Subject: [PATCH 08/10] fix(ui): put tool-card open divider on Collapsible
 trigger (#543 review P2)

The disclosure migration left the tool-card open-state divider pinned to the
old native selector `[&[open]>summary]`. After migrating the card to Base UI
Collapsible, the real DOM is a root with `[data-open]` and a button trigger with
`data-slot="collapsible-trigger"`, so the old selector no longer matched and
open tool-card headers could lose the body divider.

Use the Base UI / ShadCN-style ownership instead of a root-owned child selector:
- the card root exposes a named group (`group/tool`) alongside the Base UI
  `[data-open]` state,
- the styled trigger/header part declares the divider with
  `group-data-[open]/tool:[border-bottom:1px_solid_var(--border)]`,
- stale native-disclosure comments are removed.

TDD: chat-tool-card-cascade-contract first failed because chat.tsx still kept
`[open]>summary`; it now requires the named group + trigger-owned divider and
bans the old selector from source/comments.

Verification: related contracts pass (12/12), desktop tests pass (2009/2009),
typecheck clean, renderer build succeeds and generated CSS contains the named
group data selector.
---
 .../chat-tool-card-cascade-contract.test.ts   | 32 +++++++++++++++----
 packages/ui/src/primitives/chat.tsx           | 32 +++++++++----------
 2 files changed, 41 insertions(+), 23 deletions(-)

diff --git a/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts b/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts
index 9fa4f34b10..bfcb682e42 100644
--- a/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts
+++ b/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts
@@ -45,7 +45,7 @@ describe('chat tool-card migration contract (#332 PR3b)', () => {
       '.maka-tool-body',
       '.maka-tool-intent',
       '.maka-tool-count',
-      // the `<details>` card base + its status / open / summary selectors
+      // the retired native-disclosure card base + status/open selectors
       '.maka-tool {',
       '.maka-tool >',
       '.maka-tool[open]',
@@ -176,12 +176,32 @@ describe('chat tool-card migration contract (#332 PR3b)', () => {
       );
     }
     // The open/collapsed divider — the one card surface that differs by state
-    // (the collapsed default has no bottom border). The computed-diff proves both
-    // states, but that harness is manual (no CI), so pin the `[open]>summary`
-    // literal here as the automated guard.
+    // (the collapsed default has no bottom border). Keep the state on the
+    // Base UI root, but declare the border on the styled part itself: root is a
+    // named group, trigger/header reads `[data-open]` from that group. This is
+    // closer to the Base UI / ShadCN convention than a parent-child selector on
+    // the root.
     assert.ok(
-      block.includes('[&[open]>summary]:[border-bottom:1px_solid_var(--border)]'),
-      'item must keep the `[open]>summary` divider literal (collapsed default has none)',
+      !rawSrc.includes('[open]>summary'),
+      'tool card source must not keep the old native details `[open]>summary` selector, even in comments',
+    );
+    const itemStart = block.indexOf('item:');
+    const headerStart = block.indexOf('header:', itemStart);
+    const dotStart = block.indexOf('dot:', headerStart);
+    assert.ok(itemStart !== -1 && headerStart !== -1 && dotStart !== -1, 'toolVariants item/header/dot parts must stay parseable');
+    const itemBlock = block.slice(itemStart, headerStart);
+    const headerBlock = block.slice(headerStart, dotStart);
+    assert.ok(
+      itemBlock.includes('group/tool'),
+      'tool card root must expose a named group so styled parts can read Base UI [data-open]',
+    );
+    assert.ok(
+      !itemBlock.includes('border-bottom'),
+      'tool card root must not own the open-state divider; put the border on the trigger/header part',
+    );
+    assert.ok(
+      headerBlock.includes('group-data-[open]/tool:[border-bottom:1px_solid_var(--border)]'),
+      'tool card header must add the divider from the Base UI [data-open] group state',
     );
     // Anti-drift: pin the distinctive literals and ban the semantic-scale
     // forms they would be swapped for. Radius uses the `--radius-surface`
diff --git a/packages/ui/src/primitives/chat.tsx b/packages/ui/src/primitives/chat.tsx
index e065329c0b..9cca8dca3e 100644
--- a/packages/ui/src/primitives/chat.tsx
+++ b/packages/ui/src/primitives/chat.tsx
@@ -396,13 +396,11 @@ export function LiveIndicator({
  * that carries its own `motion-reduce:` guards — the dot and card need no
  * per-element motion utilities; the same global rules cover them as before.)
  *
- * The single consumer (`ToolActivity`) keeps its semantic tags and applies these
- * by `className`. `toolVariants` is kept OFF the package barrel for the same
- * reason as `markerVariants` / `streamVariants`: the only consumer imports it by
- * relative path, so the part set stays an internal, freely-removable styling
- * detail. The `<details>` card stays native HTML here — the eventual Base UI
- * Disclosure path (the intended convergence target for this card AND the
- * `.maka-turn-thinking` block) is a later structural pass, not this lift.
+ * The single consumer (`ToolActivity`) renders a Base UI Collapsible and applies
+ * these by `className`. `toolVariants` is kept OFF the package barrel for the
+ * same reason as `markerVariants` / `streamVariants`: the only consumer imports
+ * it by relative path, so the part set stays an internal, freely-removable
+ * styling detail.
  *
  * NOTE: the args `<pre>` keeps the shared `.maka-code` inline-code base (used by
  * Markdown / artifact previews too — out of scope); the `args` part below is only
@@ -429,24 +427,24 @@ const toolVariants = cva("", {
       count:
         "inline-flex items-center justify-center min-w-[22px] h-[18px] px-1.5 py-0 rounded-[var(--radius-pill)] bg-[var(--foreground-5)] text-[color:var(--foreground-secondary)] text-[11px] [font-variant-numeric:tabular-nums]",
       // `.maka-tool` (effective: the later `padding: 0` rule wins over `8px 12px`)
-      // + `.toolItem` + the `[open]>summary` divider + the `[data-status]` border /
-      // background / opacity swaps. `[border: …]` / `[border-color: …]` are arbitrary
-      // so the status overrides touch only the color, never width/style. The
-      // `<summary>` marker reset stays a residue keyed on `[data-slot="tool"]`
-      // (see docstring).
+      // + `.toolItem` + the `[data-status]` border / background / opacity swaps.
+      // `[border: …]` / `[border-color: …]` are arbitrary so the status overrides
+      // touch only the color, never width/style. `group/tool` exposes Base UI
+      // `[data-open]` to the trigger/header part without root-owned child
+      // selectors.
       item:
-        "[border:1px_solid_var(--border)] rounded-[var(--radius-surface)] bg-[var(--foreground-2)] p-0 mt-2 [font-family:var(--font-mono)] text-[12.5px] text-[color:var(--foreground-secondary)] overflow-hidden [box-shadow:var(--shadow-minimal-flat)]"
-        + " [&[open]>summary]:[border-bottom:1px_solid_var(--border)]"
+        "[border:1px_solid_var(--border)] rounded-[var(--radius-surface)] bg-[var(--foreground-2)] p-0 mt-2 [font-family:var(--font-mono)] text-[12.5px] text-[color:var(--foreground-secondary)] overflow-hidden [box-shadow:var(--shadow-minimal-flat)] group/tool"
         // `waiting_permission` border tint — see `WP_CARD_BORDER` above (String.raw).
         + " " + WP_CARD_BORDER
         + " data-[status=running]:[border-color:oklch(from_var(--status-running)_l_c_h_/_0.4)]"
         + " data-[status=completed]:[border-color:var(--border)]"
         + " data-[status=errored]:[border-color:oklch(from_var(--destructive)_l_c_h_/_0.4)] data-[status=errored]:bg-[oklch(from_var(--destructive)_l_c_h_/_0.04)]"
         + " data-[status=interrupted]:[border-color:var(--border)] data-[status=interrupted]:bg-[var(--foreground-3)] data-[status=interrupted]:opacity-[0.7]",
-      // `.maka-tool > summary` (list-style + padding) + `.maka-tool-header` (the
-      // 8px · name · meta grid). Folded together since the summary IS the header.
+      // The Collapsible trigger/header: 8px · name · meta grid. The open-state
+      // divider is declared on the styled part itself, reading `[data-open]` from
+      // the named root group.
       header:
-        "list-none grid grid-cols-[8px_minmax(0,1fr)_auto] items-center gap-2.5 px-3 py-2 text-[color:var(--foreground-secondary)]",
+        "list-none grid grid-cols-[8px_minmax(0,1fr)_auto] items-center gap-2.5 px-3 py-2 text-[color:var(--foreground-secondary)] group-data-[open]/tool:[border-bottom:1px_solid_var(--border)]",
       // `.maka-tool-status-dot` (+ the `[data-status]` color swaps; running adds
       // the box-shadow ring + `maka-tool-pulse` breath — keyframe stays in CSS).
       dot:

From 12e549c099460363b6f93e21436c42a52a2ee6bd Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Sun, 5 Jul 2026 17:48:59 +0800
Subject: [PATCH 09/10] fix(ui): use Collapsible trigger data-panel-open for
 tool divider (#543 review P3)

Base UI Collapsible.Trigger already exposes `data-panel-open` when its panel is
open, so the previous named root group (`group/tool` +
`group-data-[open]/tool`) was more machinery than this divider needs.

Keep the Base UI / ShadCN ownership principle but make it smaller: the styled
trigger/header part now owns the divider directly via
`data-[panel-open]:[border-bottom:1px_solid_var(--border)]`, and the root drops
`group/tool`.

TDD: chat-tool-card-cascade-contract first failed because the source still used
the root group path; it now bans both the old native `[open]>summary` selector
and the root group open-state path, and requires the trigger-level
`data-[panel-open]` divider.

Verification: related contracts pass (12/12), desktop tests pass (2009/2009),
typecheck clean, renderer build succeeds, generated CSS contains the
`data-[panel-open]` utility and no `group-data-[open]/tool` / `group\/tool`
selector. turn-narrative screenshot remains at the existing 0.09% disclosure
residual.
---
 .../chat-tool-card-cascade-contract.test.ts   | 21 +++++++++++--------
 packages/ui/src/primitives/chat.tsx           | 11 ++++------
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts b/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts
index bfcb682e42..0d8d0b2b5c 100644
--- a/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts
+++ b/apps/desktop/src/main/__tests__/chat-tool-card-cascade-contract.test.ts
@@ -176,15 +176,18 @@ describe('chat tool-card migration contract (#332 PR3b)', () => {
       );
     }
     // The open/collapsed divider — the one card surface that differs by state
-    // (the collapsed default has no bottom border). Keep the state on the
-    // Base UI root, but declare the border on the styled part itself: root is a
-    // named group, trigger/header reads `[data-open]` from that group. This is
-    // closer to the Base UI / ShadCN convention than a parent-child selector on
-    // the root.
+    // (the collapsed default has no bottom border). Base UI puts
+    // `[data-panel-open]` directly on the Collapsible Trigger, so keep the border
+    // on the styled trigger/header part without adding a root group or crossing
+    // elements to read root state.
     assert.ok(
       !rawSrc.includes('[open]>summary'),
       'tool card source must not keep the old native details `[open]>summary` selector, even in comments',
     );
+    assert.ok(
+      !rawSrc.includes('group-data-[open]/tool'),
+      'tool card source must not use a root group to read open state when Base UI Trigger exposes [data-panel-open]',
+    );
     const itemStart = block.indexOf('item:');
     const headerStart = block.indexOf('header:', itemStart);
     const dotStart = block.indexOf('dot:', headerStart);
@@ -192,16 +195,16 @@ describe('chat tool-card migration contract (#332 PR3b)', () => {
     const itemBlock = block.slice(itemStart, headerStart);
     const headerBlock = block.slice(headerStart, dotStart);
     assert.ok(
-      itemBlock.includes('group/tool'),
-      'tool card root must expose a named group so styled parts can read Base UI [data-open]',
+      !itemBlock.includes('group/tool'),
+      'tool card root must not add a named group for open state when Base UI Trigger exposes [data-panel-open]',
     );
     assert.ok(
       !itemBlock.includes('border-bottom'),
       'tool card root must not own the open-state divider; put the border on the trigger/header part',
     );
     assert.ok(
-      headerBlock.includes('group-data-[open]/tool:[border-bottom:1px_solid_var(--border)]'),
-      'tool card header must add the divider from the Base UI [data-open] group state',
+      headerBlock.includes('data-[panel-open]:[border-bottom:1px_solid_var(--border)]'),
+      'tool card header must add the divider from Base UI Trigger [data-panel-open]',
     );
     // Anti-drift: pin the distinctive literals and ban the semantic-scale
     // forms they would be swapped for. Radius uses the `--radius-surface`
diff --git a/packages/ui/src/primitives/chat.tsx b/packages/ui/src/primitives/chat.tsx
index 9cca8dca3e..9d6842125f 100644
--- a/packages/ui/src/primitives/chat.tsx
+++ b/packages/ui/src/primitives/chat.tsx
@@ -429,11 +429,9 @@ const toolVariants = cva("", {
       // `.maka-tool` (effective: the later `padding: 0` rule wins over `8px 12px`)
       // + `.toolItem` + the `[data-status]` border / background / opacity swaps.
       // `[border: …]` / `[border-color: …]` are arbitrary so the status overrides
-      // touch only the color, never width/style. `group/tool` exposes Base UI
-      // `[data-open]` to the trigger/header part without root-owned child
-      // selectors.
+      // touch only the color, never width/style.
       item:
-        "[border:1px_solid_var(--border)] rounded-[var(--radius-surface)] bg-[var(--foreground-2)] p-0 mt-2 [font-family:var(--font-mono)] text-[12.5px] text-[color:var(--foreground-secondary)] overflow-hidden [box-shadow:var(--shadow-minimal-flat)] group/tool"
+        "[border:1px_solid_var(--border)] rounded-[var(--radius-surface)] bg-[var(--foreground-2)] p-0 mt-2 [font-family:var(--font-mono)] text-[12.5px] text-[color:var(--foreground-secondary)] overflow-hidden [box-shadow:var(--shadow-minimal-flat)]"
         // `waiting_permission` border tint — see `WP_CARD_BORDER` above (String.raw).
         + " " + WP_CARD_BORDER
         + " data-[status=running]:[border-color:oklch(from_var(--status-running)_l_c_h_/_0.4)]"
@@ -441,10 +439,9 @@ const toolVariants = cva("", {
         + " data-[status=errored]:[border-color:oklch(from_var(--destructive)_l_c_h_/_0.4)] data-[status=errored]:bg-[oklch(from_var(--destructive)_l_c_h_/_0.04)]"
         + " data-[status=interrupted]:[border-color:var(--border)] data-[status=interrupted]:bg-[var(--foreground-3)] data-[status=interrupted]:opacity-[0.7]",
       // The Collapsible trigger/header: 8px · name · meta grid. The open-state
-      // divider is declared on the styled part itself, reading `[data-open]` from
-      // the named root group.
+      // divider reads Base UI's `[data-panel-open]` trigger attribute directly.
       header:
-        "list-none grid grid-cols-[8px_minmax(0,1fr)_auto] items-center gap-2.5 px-3 py-2 text-[color:var(--foreground-secondary)] group-data-[open]/tool:[border-bottom:1px_solid_var(--border)]",
+        "list-none grid grid-cols-[8px_minmax(0,1fr)_auto] items-center gap-2.5 px-3 py-2 text-[color:var(--foreground-secondary)] data-[panel-open]:[border-bottom:1px_solid_var(--border)]",
       // `.maka-tool-status-dot` (+ the `[data-status]` color swaps; running adds
       // the box-shadow ring + `maka-tool-pulse` breath — keyframe stays in CSS).
       dot:

From 92fa1e141787427540e9a56bf858141273f3f870 Mon Sep 17 00:00:00 2001
From: AstroHan <lei.yuhan@outlook.com>
Date: Sun, 5 Jul 2026 17:53:23 +0800
Subject: [PATCH 10/10] fix(ui): drop unused SelectList wrapper after rebase

After rebasing PR5 onto main, the old PR5 style-hook commit still introduced a
SelectList wrapper, but main now has the ui.tsx dead-export contract and there
is no consumer for SelectList. Keep the style-hook convention on used wrappers
only and remove the dead export instead of adding a pending allowlist entry.

Verification: style-hook/divider/disclosure contracts pass (13/13), desktop
tests pass (2019/2019), typecheck clean.
---
 packages/ui/src/ui.tsx | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/packages/ui/src/ui.tsx b/packages/ui/src/ui.tsx
index 3b849fa684..78ee88db97 100644
--- a/packages/ui/src/ui.tsx
+++ b/packages/ui/src/ui.tsx
@@ -331,12 +331,6 @@ export const SelectTrigger = forwardRef<HTMLButtonElement, React.ComponentPropsW
 export const SelectValue = BaseSelect.Value;
 export const SelectPortal = BaseSelect.Portal;
 export const SelectPositioner = BaseSelect.Positioner;
-export const SelectList = forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof BaseSelect.List>>(function SelectList(
-  { className, ...props },
-  ref,
-) {
-  return <BaseSelect.List ref={ref} className={cn('max-h-[var(--available-height)] overflow-y-auto py-1', className)} data-slot="select-list" {...props} />;
-});
 export const SelectPopup = forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof BaseSelect.Popup>>(function SelectPopup(
   { className, ...props },
   ref,