feat(ui): style-hook convention + small Base UI migrations (Collapsible/Tooltip/NumberField) (#520 PR5)

[Astro-Han]

Summary

PR5 of #520 — the style-hook convention foundation + the smaller Base UI migrations that follow it. Four items, one commit each (each independently revertible), TDD red → green → refactor.

#22 (input canonical) was scoped into PR5 but moved to PR8 during this work — primitives/input.tsx carries a different structure (data-slot="input-control" span + inner Base UI input, ring-[3px]) than the native ui.tsxInput (single <input> + inputClasses, ring-2), and bare-field-chrome-contract.test.ts pins the native's data-maka-field-chrome + border-input + ring-2, so retiring the native is not a clean look-preserving swap. The issue plan was re-arranged (#22 → PR8); this PR opens with 1-4 only.

New primitives (packages/ui/src/primitives/)

Primitive	Wraps	data-slot
collapsible.tsx	@base-ui/react/collapsible Root/Trigger/Panel	collapsible / collapsible-trigger / collapsible-panel
tooltip.tsx	@base-ui/react/tooltip Root/Trigger/Content (Portal+Positioner+Popup)	tooltip / tooltip-trigger / tooltip-content
number-field.tsx	@base-ui/react/number-field Root/Input	number-field / number-field-input

All follow the style-hook convention (item 23): data-slot on each part, Base UI's native boolean state attributes (data-panel-open, data-open, etc.) adopted as-is. The Collapsible Trigger carries a button-chrome reset (the native <summary> had no bg/border/padding, but <button> does). The Tooltip Trigger uses Base UI v1's render prop (not Radix asChild). The NumberField Input reuses maka's inputClasses (now exported from ui.tsx) so the port inputs keep their look.

Convergence

• item 23 — style-hook convention: data-slot added to all 20 Base UI wrappers in ui.tsx (Button/Separator/Checkbox/Dialog backdrop+popup/Select Trigger+List+Popup+Group+GroupLabel+Separator+Item/FieldDescription/Label/Switch/Toggle/ToggleGroup/RadioGroup/Radio/Progress). A doc comment at the top of ui.tsx records the state-attribute decision (adopt Base UI native attribute-presence form — maka's renderer CSS has zero state-attribute selectors today, so nothing breaks), the per-component hook map, the whitelisted CSS var hooks, and the className(state) deferral.
• item 17 — disclosure → Collapsible: the four <details>/<summary> sites (chat-view turn-thinking + reasoning-panel, permission-dialog permission-raw, tool-activity) migrate to Base UI Collapsible (all independent single sections, so Collapsible not Accordion). CSS retargeted: summary → [data-slot="collapsible-trigger"], [open] → [data-panel-open], ::-webkit-details-marker/::marker resets dropped (button trigger has no native marker). The reasoning-panel's controlled-open moves from e.currentTarget.open off the toggle event to Collapsible's open + onOpenChange.
• item 20 — tooltip → Base UI Tooltip: the 13 clearest icon-only-action button title= usages (app-shell-chrome-actions 7, browser-panel 4, artifact-pane collapse) migrate to Base UI Tooltip; aria-label stays on the button, TooltipContent is the visual hover hint. The artifact-pane delete button's redundant title= is dropped (it shows a visible 删除 label). The longer tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) are tooltip-eligible but need per-site label-vs-tooltip judgment — deferred to a follow-up.
• item 21 — number-field: the two gateway/proxy port inputs migrate to Base UI NumberField (value: number | null, onValueChange), dropping the Number(event.currentTarget.value) hand-conversion. Proxy: 0 ↔ empty; gateway: empty → 3939 default, both preserved.

New contracts

Contract	Bans	Pins
style-hook-convention-contract.test.ts	a ui.tsx wrapper forwarding to <Base*> without data-slot	the convention doc comment present
disclosure-collapsible-contract.test.ts	<details>/<summary> (incl. in comments) in the 3 migrated files; missing Collapsible import	primitives/collapsible.tsx data-slot on Root/Trigger/Panel
tooltip-converge-contract.test.ts	a title= JSX attribute in the 3 migrated files; missing Tooltip import	primitives/tooltip.tsx data-slot on Root/Trigger/Content
number-field-converge-contract.test.ts	Number(event.currentTarget.value) hand-conversion in the 2 port files; missing NumberField import	primitives/number-field.tsx data-slot on Root/Input

Existing tests updated

• border-width-converge-contract: the triangle-caret allowlist selectors moved from summary::before to [data-slot="collapsible-trigger"]::before (the chevron border-width: 4px 0 4px 5px moved with the disclosure migration).
• chat-marker-cascade-contract / chat-tool-card-cascade-contract: the turn-thinking / tool-card residue selectors + the dropped marker-reset residue.
• app-region-hygiene-contract / search-modal-lifecycle-contract: the topbar-button className extraction + the shell-search-button regex now match the <TooltipTrigger render={<UiButton/>}> shape (the className moved from the UiButton element to the TooltipTrigger that renders it).
• settings-network-gateway-contract: the two port-input assertions now pin the NumberField form (value={...|| null} / value={...} + onValueChange={(v) => update…({ port: v ?? default })).

Commits

1. feat(ui): establish Base UI style-hook convention (data-slot + native state attrs) — item 23 (foundation).
2. feat(ui): migrate disclosure sites to Base UI Collapsible — item 17.
3. feat(ui): migrate icon-action tooltips to Base UI Tooltip — item 20.
4. feat(ui): migrate port inputs to Base UI NumberField — item 21.

Verification

• Tests: npm run -w @maka/desktop test — 2008/2008 pass (rebased onto main with PR2; +26 from PR2, +10 new contract assertions across 4 files). typecheck clean.
• Screenshots vs main (turn-narrative, settings-appearance, first-run × light): tooltips are hover-only so rest state is unchanged; turn-narrative 0.09% (the disclosure commit's summary→button pixel difference), settings-appearance 0.0136 (PR4's settings-nav snap residual, untouched here), first-run 0. The port inputs (general/open-gateway settings) have no capture scenario; they keep their look via the shared inputClasses.

Out of scope / deferred

• Add DeepSeek context budget diagnostics #22 input canonical → PR8 (see Summary).
• tooltip tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) — deferred to a follow-up; each needs a label-vs-tooltip check.
• feat(browser): embedded browser automation (opencli CDP observe→act) #18 toast + Add DeepSeek cost-runtime policy for Runtime v2/AiSdkFlow #19 alert-dialog → PR6. Add archive-backed stale tool result pruning #24-27 large migrations → PR7.

[Astro-Han]

Thanks for the review. Verified every claim against the code before acting; results + fixes below.

P2 — tool-activity defaultOpen (fixed, c06d50a9)

Verified. The disclosure migration set defaultOpen={isOpenByDefault(item.status)} (uncontrolled — open decided once on first render). The pre-Collapsible <details open={isOpenByDefault(status)}> re-evaluated open every render, so a card that defaulted open while pending/running no longer auto-collapsed when it settled. Real regression.

Fix: extracted a ToolActivityCard component (hooks can't live in the .map callback) with a controlled state machine: useState(isOpenByDefault(item.status)) seeds open, useEffect re-syncs it on [item.status] so a pending/running card collapses when it settles, onOpenChange={setOpen} lets the user toggle in between (the next status change re-syncs). This restores the status-following behavior and makes the user-toggle intentional rather than a React-not-rerendering side effect.

Test:disclosure-collapsible-contract now asserts tool-activity must NOT use defaultOpen, must use onOpenChange, and must re-sync via useEffect on [item.status]. (maka has no React testing-library / react-test-renderer, so the behavior is locked structurally + verified by hand; a rerender-act test is out of scope.) Will hand-test pending/running → completed/interrupted before merge.

P3 — Collapsible barrel / contract mismatch (fixed, f4dba2c2)

Verified. Barrel exported Collapsible as PrimitiveCollapsible (the old Tabs/Accordion convention), while Tooltip/NumberField export directly. The contract regex allowed @maka/ui as an import path, but the barrel didn't export Collapsible under that name — a phantom-pass path. The 3 internal sites import via ./primitives/collapsible.js (the in-package convention — alert/chat all use relative primitive paths), so the test passed for the right reason, but the @maka/ui allowance was misleading.

Fix: barrel now exports Collapsible / CollapsibleTrigger / CollapsiblePanel directly (dropped the Primitive* aliases and the CollapsiblePrimitive re-export — nothing consumes them; Tooltip/NumberField don't export their Primitive either). Internal sites keep their relative-path imports (convention); @maka/ui is now genuinely available rather than phantom.

P3 — tooltip.tsx doc showed asChild (fixed, f4dba2c2)

Verified. Line 14 usage doc showed <TooltipTrigger asChild> (Radix), but this PR uses Base UI v1's render prop. Fixed the example to render={<Button />} and noted the Trigger merges its props + children into the rendered element, so the next person doesn't copy the comment and hit the typecheck failure the migration hit.

待验证 — artifact delete title= (fixed, 28f6ed7a)

Partially verified — pushing back on the a11y part. The .maka-artifact-toolbar-destructive-label span is visually hidden but still announced (position:absolute; width:1px; clip-path:inset(50%); CSS comment: "only exists for assistive tech"). So the screen-reader path was preserved when title="删除" was dropped — no SR regression. But mouse users did lose the hover hint (native title= gone, no Base UI Tooltip added).

Fix: wrapped the delete button in a Base UI Tooltip (same shape as the artifact-pane collapse button). TooltipContent mirrors 删除/删除中… for hover; the visually-hidden span still carries the SR label. The two are complementary, not redundant.

P3 — tooltip three-layer JSX repetition (deferred)

Verified. 13 sites are highly isomorphic (<Tooltip><TooltipTrigger render={<Button variant="quiet" size="icon-sm"/>} ...props><Icon/></TooltipTrigger><TooltipContent>label</TooltipContent></Tooltip>).

Defering this one. A TooltipButton helper would save ~15-27 lines net, but the 13 sites' trigger props are heterogeneous (disabled / aria-expanded / conditional icon / conditional label / UiButton vs Button), so the helper becomes a pass-through wrapper (tooltip + render + {...triggerProps} + children) that mostly removes the <Tooltip>/<TooltipContent> wrapping — a modest win for a new abstraction layer + an app-region-hygiene regex adjustment (it extracts classNames from <TooltipTrigger render={<UiButton …/>}> blocks today). Happy to do it as a follow-up if the tooltip site count grows; for 13 sites the direct form is clearer and more flexible. Pushing back rather than adding abstraction for line-count.

待验证 — CI checks / hand-test

Local verification done:npm run -w @maka/desktop test → 2009/2009 pass. npm run typecheck clean across workspaces. Screenshots vs main: turn-narrative 0.09% (the disclosure commit's summary→button residual), settings-appearance 0.0136 (PR4's settings-nav snap, untouched here), first-run 0% — all hover-only tooltip / controlled-open changes add 0 at rest.

CI checks show 0 — will confirm CI triggers on the updated push. Will hand-test before merge: Collapsible keyboard toggle + status-following collapse, Tooltip hover/focus, NumberField empty/invalid input (proxy 0↔empty, gateway empty→3939).

---

Summary: 3 fix commits pushed (c06d50a9, f4dba2c2, 28f6ed7a). 1 item deferred with rationale (tooltip helper). Issue #520 re-arranged: #22 input-canonical moved to PR8 (not a clean look-preserving swap — primitives/input.tsx carries a different structure than the native ui.tsxInput, and bare-field-chrome-contract pins the native's data-maka-field-chrome + border-input + ring-2).

[Astro-Han]

Summary

PR5 of #520 — the style-hook convention foundation + the smaller Base UI migrations that follow it. Four items, one commit each (each independently revertible), TDD red → green → refactor.

#22 (input canonical) was scoped into PR5 but moved to PR8 during this work — primitives/input.tsx carries a different structure (data-slot="input-control" span + inner Base UI input, ring-[3px]) than the native ui.tsxInput (single <input> + inputClasses, ring-2), and bare-field-chrome-contract.test.ts pins the native's data-maka-field-chrome + border-input + ring-2, so retiring the native is not a clean look-preserving swap. The issue plan was re-arranged (#22 → PR8); this PR opens with 1-4 only.

New primitives (packages/ui/src/primitives/)

Primitive	Wraps	data-slot
collapsible.tsx	@base-ui/react/collapsible Root/Trigger/Panel	collapsible / collapsible-trigger / collapsible-panel
tooltip.tsx	@base-ui/react/tooltip Root/Trigger/Content (Portal+Positioner+Popup)	tooltip / tooltip-trigger / tooltip-content
number-field.tsx	@base-ui/react/number-field Root/Input	number-field / number-field-input

All follow the style-hook convention (item 23): data-slot on each part, Base UI's native boolean state attributes (data-panel-open, data-open, etc.) adopted as-is. The Collapsible Trigger carries a button-chrome reset (the native <summary> had no bg/border/padding, but <button> does). The Tooltip Trigger uses Base UI v1's render prop (not Radix asChild). The NumberField Input reuses maka's inputClasses (now exported from ui.tsx) so the port inputs keep their look.

Convergence

• item 23 — style-hook convention: data-slot added to all 20 Base UI wrappers in ui.tsx (Button/Separator/Checkbox/Dialog backdrop+popup/Select Trigger+List+Popup+Group+GroupLabel+Separator+Item/FieldDescription/Label/Switch/Toggle/ToggleGroup/RadioGroup/Radio/Progress). A doc comment at the top of ui.tsx records the state-attribute decision (adopt Base UI native attribute-presence form — maka's renderer CSS has zero state-attribute selectors today, so nothing breaks), the per-component hook map, the whitelisted CSS var hooks, and the className(state) deferral.
• item 17 — disclosure → Collapsible: the four <details>/<summary> sites (chat-view turn-thinking + reasoning-panel, permission-dialog permission-raw, tool-activity) migrate to Base UI Collapsible (all independent single sections, so Collapsible not Accordion). CSS retargeted: summary → [data-slot="collapsible-trigger"], [open] → [data-panel-open], ::-webkit-details-marker/::marker resets dropped (button trigger has no native marker). The reasoning-panel's controlled-open moves from e.currentTarget.open off the toggle event to Collapsible's open + onOpenChange.
• item 20 — tooltip → Base UI Tooltip: the 13 clearest icon-only-action button title= usages (app-shell-chrome-actions 7, browser-panel 4, artifact-pane collapse) migrate to Base UI Tooltip; aria-label stays on the button, TooltipContent is the visual hover hint. The artifact-pane delete button's redundant title= is dropped (it shows a visible 删除 label). The longer tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) are tooltip-eligible but need per-site label-vs-tooltip judgment — deferred to a follow-up.
• item 21 — number-field: the two gateway/proxy port inputs migrate to Base UI NumberField (value: number | null, onValueChange), dropping the Number(event.currentTarget.value) hand-conversion. Proxy: 0 ↔ empty; gateway: empty → 3939 default, both preserved.

New contracts

Contract	Bans	Pins
style-hook-convention-contract.test.ts	a ui.tsx wrapper forwarding to <Base*> without data-slot	the convention doc comment present
disclosure-collapsible-contract.test.ts	<details>/<summary> (incl. in comments) in the 3 migrated files; missing Collapsible import	primitives/collapsible.tsx data-slot on Root/Trigger/Panel
tooltip-converge-contract.test.ts	a title= JSX attribute in the 3 migrated files; missing Tooltip import	primitives/tooltip.tsx data-slot on Root/Trigger/Content
number-field-converge-contract.test.ts	Number(event.currentTarget.value) hand-conversion in the 2 port files; missing NumberField import	primitives/number-field.tsx data-slot on Root/Input

Existing tests updated

• border-width-converge-contract: the triangle-caret allowlist selectors moved from summary::before to [data-slot="collapsible-trigger"]::before (the chevron border-width: 4px 0 4px 5px moved with the disclosure migration).
• chat-marker-cascade-contract / chat-tool-card-cascade-contract: the turn-thinking / tool-card residue selectors + the dropped marker-reset residue.
• app-region-hygiene-contract / search-modal-lifecycle-contract: the topbar-button className extraction + the shell-search-button regex now match the <TooltipTrigger render={<UiButton/>}> shape (the className moved from the UiButton element to the TooltipTrigger that renders it).
• settings-network-gateway-contract: the two port-input assertions now pin the NumberField form (value={...|| null} / value={...} + onValueChange={(v) => update…({ port: v ?? default })).

Commits

1. feat(ui): establish Base UI style-hook convention (data-slot + native state attrs) — item 23 (foundation).
2. feat(ui): migrate disclosure sites to Base UI Collapsible — item 17.
3. feat(ui): migrate icon-action tooltips to Base UI Tooltip — item 20.
4. feat(ui): migrate port inputs to Base UI NumberField — item 21.

Verification

• Tests: npm run -w @maka/desktop test — 2008/2008 pass (rebased onto main with PR2; +26 from PR2, +10 new contract assertions across 4 files). typecheck clean.
• Screenshots vs main (turn-narrative, settings-appearance, first-run × light): tooltips are hover-only so rest state is unchanged; turn-narrative 0.09% (the disclosure commit's summary→button pixel difference), settings-appearance 0.0136 (PR4's settings-nav snap residual, untouched here), first-run 0. The port inputs (general/open-gateway settings) have no capture scenario; they keep their look via the shared inputClasses.

Out of scope / deferred

• Add DeepSeek context budget diagnostics #22 input canonical → PR8 (see Summary).
• tooltip tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) — deferred to a follow-up; each needs a label-vs-tooltip check.
• feat(browser): embedded browser automation (opencli CDP observe→act) #18 toast + Add DeepSeek cost-runtime policy for Runtime v2/AiSdkFlow #19 alert-dialog → PR6. Add archive-backed stale tool result pruning #24-27 large migrations → PR7.

[Astro-Han]

Thanks for the review. Verified every claim against the code before acting; results + fixes below.

P2 — tool-activity defaultOpen (fixed, c06d50a9)

Verified. The disclosure migration set defaultOpen={isOpenByDefault(item.status)} (uncontrolled — open decided once on first render). The pre-Collapsible <details open={isOpenByDefault(status)}> re-evaluated open every render, so a card that defaulted open while pending/running no longer auto-collapsed when it settled. Real regression.

Fix: extracted a ToolActivityCard component (hooks can't live in the .map callback) with a controlled state machine: useState(isOpenByDefault(item.status)) seeds open, useEffect re-syncs it on [item.status] so a pending/running card collapses when it settles, onOpenChange={setOpen} lets the user toggle in between (the next status change re-syncs). This restores the status-following behavior and makes the user-toggle intentional rather than a React-not-rerendering side effect.

Test:disclosure-collapsible-contract now asserts tool-activity must NOT use defaultOpen, must use onOpenChange, and must re-sync via useEffect on [item.status]. (maka has no React testing-library / react-test-renderer, so the behavior is locked structurally + verified by hand; a rerender-act test is out of scope.) Will hand-test pending/running → completed/interrupted before merge.

P3 — Collapsible barrel / contract mismatch (fixed, f4dba2c2)

Verified. Barrel exported Collapsible as PrimitiveCollapsible (the old Tabs/Accordion convention), while Tooltip/NumberField export directly. The contract regex allowed @maka/ui as an import path, but the barrel didn't export Collapsible under that name — a phantom-pass path. The 3 internal sites import via ./primitives/collapsible.js (the in-package convention — alert/chat all use relative primitive paths), so the test passed for the right reason, but the @maka/ui allowance was misleading.

Fix: barrel now exports Collapsible / CollapsibleTrigger / CollapsiblePanel directly (dropped the Primitive* aliases and the CollapsiblePrimitive re-export — nothing consumes them; Tooltip/NumberField don't export their Primitive either). Internal sites keep their relative-path imports (convention); @maka/ui is now genuinely available rather than phantom.

P3 — tooltip.tsx doc showed asChild (fixed, f4dba2c2)

Verified. Line 14 usage doc showed <TooltipTrigger asChild> (Radix), but this PR uses Base UI v1's render prop. Fixed the example to render={<Button />} and noted the Trigger merges its props + children into the rendered element, so the next person doesn't copy the comment and hit the typecheck failure the migration hit.

待验证 — artifact delete title= (fixed, 28f6ed7a)

Partially verified — pushing back on the a11y part. The .maka-artifact-toolbar-destructive-label span is visually hidden but still announced (position:absolute; width:1px; clip-path:inset(50%); CSS comment: "only exists for assistive tech"). So the screen-reader path was preserved when title="删除" was dropped — no SR regression. But mouse users did lose the hover hint (native title= gone, no Base UI Tooltip added).

Fix: wrapped the delete button in a Base UI Tooltip (same shape as the artifact-pane collapse button). TooltipContent mirrors 删除/删除中… for hover; the visually-hidden span still carries the SR label. The two are complementary, not redundant.

P3 — tooltip three-layer JSX repetition (deferred)

Verified. 13 sites are highly isomorphic (<Tooltip><TooltipTrigger render={<Button variant="quiet" size="icon-sm"/>} ...props><Icon/></TooltipTrigger><TooltipContent>label</TooltipContent></Tooltip>).

Defering this one. A TooltipButton helper would save ~15-27 lines net, but the 13 sites' trigger props are heterogeneous (disabled / aria-expanded / conditional icon / conditional label / UiButton vs Button), so the helper becomes a pass-through wrapper (tooltip + render + {...triggerProps} + children) that mostly removes the <Tooltip>/<TooltipContent> wrapping — a modest win for a new abstraction layer + an app-region-hygiene regex adjustment (it extracts classNames from <TooltipTrigger render={<UiButton …/>}> blocks today). Happy to do it as a follow-up if the tooltip site count grows; for 13 sites the direct form is clearer and more flexible. Pushing back rather than adding abstraction for line-count.

待验证 — CI checks / hand-test

Local verification done:npm run -w @maka/desktop test → 2009/2009 pass. npm run typecheck clean across workspaces. Screenshots vs main: turn-narrative 0.09% (the disclosure commit's summary→button residual), settings-appearance 0.0136 (PR4's settings-nav snap, untouched here), first-run 0% — all hover-only tooltip / controlled-open changes add 0 at rest.

CI checks show 0 — will confirm CI triggers on the updated push. Will hand-test before merge: Collapsible keyboard toggle + status-following collapse, Tooltip hover/focus, NumberField empty/invalid input (proxy 0↔empty, gateway empty→3939).

---

Summary: 3 fix commits pushed (c06d50a9, f4dba2c2, 28f6ed7a). 1 item deferred with rationale (tooltip helper). Issue #520 re-arranged: #22 input-canonical moved to PR8 (not a clean look-preserving swap — primitives/input.tsx carries a different structure than the native ui.tsxInput, and bare-field-chrome-contract pins the native's data-maka-field-chrome + border-input + ring-2).

[Astro-Han]

Summary

PR5 of #520 — the style-hook convention foundation + the smaller Base UI migrations that follow it. Four items, one commit each (each independently revertible), TDD red → green → refactor.

#22 (input canonical) was scoped into PR5 but moved to PR8 during this work — primitives/input.tsx carries a different structure (data-slot="input-control" span + inner Base UI input, ring-[3px]) than the native ui.tsxInput (single <input> + inputClasses, ring-2), and bare-field-chrome-contract.test.ts pins the native's data-maka-field-chrome + border-input + ring-2, so retiring the native is not a clean look-preserving swap. The issue plan was re-arranged (#22 → PR8); this PR opens with 1-4 only.

New primitives (packages/ui/src/primitives/)

Primitive	Wraps	data-slot
collapsible.tsx	@base-ui/react/collapsible Root/Trigger/Panel	collapsible / collapsible-trigger / collapsible-panel
tooltip.tsx	@base-ui/react/tooltip Root/Trigger/Content (Portal+Positioner+Popup)	tooltip / tooltip-trigger / tooltip-content
number-field.tsx	@base-ui/react/number-field Root/Input	number-field / number-field-input

All follow the style-hook convention (item 23): data-slot on each part, Base UI's native boolean state attributes (data-panel-open, data-open, etc.) adopted as-is. The Collapsible Trigger carries a button-chrome reset (the native <summary> had no bg/border/padding, but <button> does). The Tooltip Trigger uses Base UI v1's render prop (not Radix asChild). The NumberField Input reuses maka's inputClasses (now exported from ui.tsx) so the port inputs keep their look.

Convergence

• item 23 — style-hook convention: data-slot added to all 20 Base UI wrappers in ui.tsx (Button/Separator/Checkbox/Dialog backdrop+popup/Select Trigger+List+Popup+Group+GroupLabel+Separator+Item/FieldDescription/Label/Switch/Toggle/ToggleGroup/RadioGroup/Radio/Progress). A doc comment at the top of ui.tsx records the state-attribute decision (adopt Base UI native attribute-presence form — maka's renderer CSS has zero state-attribute selectors today, so nothing breaks), the per-component hook map, the whitelisted CSS var hooks, and the className(state) deferral.
• item 17 — disclosure → Collapsible: the four <details>/<summary> sites (chat-view turn-thinking + reasoning-panel, permission-dialog permission-raw, tool-activity) migrate to Base UI Collapsible (all independent single sections, so Collapsible not Accordion). CSS retargeted: summary → [data-slot="collapsible-trigger"], [open] → [data-panel-open], ::-webkit-details-marker/::marker resets dropped (button trigger has no native marker). The reasoning-panel's controlled-open moves from e.currentTarget.open off the toggle event to Collapsible's open + onOpenChange.
• item 20 — tooltip → Base UI Tooltip: the 13 clearest icon-only-action button title= usages (app-shell-chrome-actions 7, browser-panel 4, artifact-pane collapse) migrate to Base UI Tooltip; aria-label stays on the button, TooltipContent is the visual hover hint. The artifact-pane delete button's redundant title= is dropped (it shows a visible 删除 label). The longer tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) are tooltip-eligible but need per-site label-vs-tooltip judgment — deferred to a follow-up.
• item 21 — number-field: the two gateway/proxy port inputs migrate to Base UI NumberField (value: number | null, onValueChange), dropping the Number(event.currentTarget.value) hand-conversion. Proxy: 0 ↔ empty; gateway: empty → 3939 default, both preserved.

New contracts

Contract	Bans	Pins
style-hook-convention-contract.test.ts	a ui.tsx wrapper forwarding to <Base*> without data-slot	the convention doc comment present
disclosure-collapsible-contract.test.ts	<details>/<summary> (incl. in comments) in the 3 migrated files; missing Collapsible import	primitives/collapsible.tsx data-slot on Root/Trigger/Panel
tooltip-converge-contract.test.ts	a title= JSX attribute in the 3 migrated files; missing Tooltip import	primitives/tooltip.tsx data-slot on Root/Trigger/Content
number-field-converge-contract.test.ts	Number(event.currentTarget.value) hand-conversion in the 2 port files; missing NumberField import	primitives/number-field.tsx data-slot on Root/Input

Existing tests updated

• border-width-converge-contract: the triangle-caret allowlist selectors moved from summary::before to [data-slot="collapsible-trigger"]::before (the chevron border-width: 4px 0 4px 5px moved with the disclosure migration).
• chat-marker-cascade-contract / chat-tool-card-cascade-contract: the turn-thinking / tool-card residue selectors + the dropped marker-reset residue.
• app-region-hygiene-contract / search-modal-lifecycle-contract: the topbar-button className extraction + the shell-search-button regex now match the <TooltipTrigger render={<UiButton/>}> shape (the className moved from the UiButton element to the TooltipTrigger that renders it).
• settings-network-gateway-contract: the two port-input assertions now pin the NumberField form (value={...|| null} / value={...} + onValueChange={(v) => update…({ port: v ?? default })).

Commits

1. feat(ui): establish Base UI style-hook convention (data-slot + native state attrs) — item 23 (foundation).
2. feat(ui): migrate disclosure sites to Base UI Collapsible — item 17.
3. feat(ui): migrate icon-action tooltips to Base UI Tooltip — item 20.
4. feat(ui): migrate port inputs to Base UI NumberField — item 21.

Verification

• Tests: npm run -w @maka/desktop test — 2008/2008 pass (rebased onto main with PR2; +26 from PR2, +10 new contract assertions across 4 files). typecheck clean.
• Screenshots vs main (turn-narrative, settings-appearance, first-run × light): tooltips are hover-only so rest state is unchanged; turn-narrative 0.09% (the disclosure commit's summary→button pixel difference), settings-appearance 0.0136 (PR4's settings-nav snap residual, untouched here), first-run 0. The port inputs (general/open-gateway settings) have no capture scenario; they keep their look via the shared inputClasses.

Out of scope / deferred

• Add DeepSeek context budget diagnostics #22 input canonical → PR8 (see Summary).
• tooltip tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) — deferred to a follow-up; each needs a label-vs-tooltip check.
• feat(browser): embedded browser automation (opencli CDP observe→act) #18 toast + Add DeepSeek cost-runtime policy for Runtime v2/AiSdkFlow #19 alert-dialog → PR6. Add archive-backed stale tool result pruning #24-27 large migrations → PR7.

[Astro-Han]

Thanks for the review. Verified every claim against the code before acting; results + fixes below.

P2 — tool-activity defaultOpen (fixed, c06d50a9)

Verified. The disclosure migration set defaultOpen={isOpenByDefault(item.status)} (uncontrolled — open decided once on first render). The pre-Collapsible <details open={isOpenByDefault(status)}> re-evaluated open every render, so a card that defaulted open while pending/running no longer auto-collapsed when it settled. Real regression.

Fix: extracted a ToolActivityCard component (hooks can't live in the .map callback) with a controlled state machine: useState(isOpenByDefault(item.status)) seeds open, useEffect re-syncs it on [item.status] so a pending/running card collapses when it settles, onOpenChange={setOpen} lets the user toggle in between (the next status change re-syncs). This restores the status-following behavior and makes the user-toggle intentional rather than a React-not-rerendering side effect.

Test:disclosure-collapsible-contract now asserts tool-activity must NOT use defaultOpen, must use onOpenChange, and must re-sync via useEffect on [item.status]. (maka has no React testing-library / react-test-renderer, so the behavior is locked structurally + verified by hand; a rerender-act test is out of scope.) Will hand-test pending/running → completed/interrupted before merge.

P3 — Collapsible barrel / contract mismatch (fixed, f4dba2c2)

Verified. Barrel exported Collapsible as PrimitiveCollapsible (the old Tabs/Accordion convention), while Tooltip/NumberField export directly. The contract regex allowed @maka/ui as an import path, but the barrel didn't export Collapsible under that name — a phantom-pass path. The 3 internal sites import via ./primitives/collapsible.js (the in-package convention — alert/chat all use relative primitive paths), so the test passed for the right reason, but the @maka/ui allowance was misleading.

Fix: barrel now exports Collapsible / CollapsibleTrigger / CollapsiblePanel directly (dropped the Primitive* aliases and the CollapsiblePrimitive re-export — nothing consumes them; Tooltip/NumberField don't export their Primitive either). Internal sites keep their relative-path imports (convention); @maka/ui is now genuinely available rather than phantom.

P3 — tooltip.tsx doc showed asChild (fixed, f4dba2c2)

Verified. Line 14 usage doc showed <TooltipTrigger asChild> (Radix), but this PR uses Base UI v1's render prop. Fixed the example to render={<Button />} and noted the Trigger merges its props + children into the rendered element, so the next person doesn't copy the comment and hit the typecheck failure the migration hit.

待验证 — artifact delete title= (fixed, 28f6ed7a)

Partially verified — pushing back on the a11y part. The .maka-artifact-toolbar-destructive-label span is visually hidden but still announced (position:absolute; width:1px; clip-path:inset(50%); CSS comment: "only exists for assistive tech"). So the screen-reader path was preserved when title="删除" was dropped — no SR regression. But mouse users did lose the hover hint (native title= gone, no Base UI Tooltip added).

Fix: wrapped the delete button in a Base UI Tooltip (same shape as the artifact-pane collapse button). TooltipContent mirrors 删除/删除中… for hover; the visually-hidden span still carries the SR label. The two are complementary, not redundant.

P3 — tooltip three-layer JSX repetition (deferred)

Verified. 13 sites are highly isomorphic (<Tooltip><TooltipTrigger render={<Button variant="quiet" size="icon-sm"/>} ...props><Icon/></TooltipTrigger><TooltipContent>label</TooltipContent></Tooltip>).

Defering this one. A TooltipButton helper would save ~15-27 lines net, but the 13 sites' trigger props are heterogeneous (disabled / aria-expanded / conditional icon / conditional label / UiButton vs Button), so the helper becomes a pass-through wrapper (tooltip + render + {...triggerProps} + children) that mostly removes the <Tooltip>/<TooltipContent> wrapping — a modest win for a new abstraction layer + an app-region-hygiene regex adjustment (it extracts classNames from <TooltipTrigger render={<UiButton …/>}> blocks today). Happy to do it as a follow-up if the tooltip site count grows; for 13 sites the direct form is clearer and more flexible. Pushing back rather than adding abstraction for line-count.

待验证 — CI checks / hand-test

Local verification done:npm run -w @maka/desktop test → 2009/2009 pass. npm run typecheck clean across workspaces. Screenshots vs main: turn-narrative 0.09% (the disclosure commit's summary→button residual), settings-appearance 0.0136 (PR4's settings-nav snap, untouched here), first-run 0% — all hover-only tooltip / controlled-open changes add 0 at rest.

CI checks show 0 — will confirm CI triggers on the updated push. Will hand-test before merge: Collapsible keyboard toggle + status-following collapse, Tooltip hover/focus, NumberField empty/invalid input (proxy 0↔empty, gateway empty→3939).

---

Summary: 3 fix commits pushed (c06d50a9, f4dba2c2, 28f6ed7a). 1 item deferred with rationale (tooltip helper). Issue #520 re-arranged: #22 input-canonical moved to PR8 (not a clean look-preserving swap — primitives/input.tsx carries a different structure than the native ui.tsxInput, and bare-field-chrome-contract pins the native's data-maka-field-chrome + border-input + ring-2).

[Astro-Han]

Summary

PR5 of #520 — the style-hook convention foundation + the smaller Base UI migrations that follow it. Four items, one commit each (each independently revertible), TDD red → green → refactor.

#22 (input canonical) was scoped into PR5 but moved to PR8 during this work — primitives/input.tsx carries a different structure (data-slot="input-control" span + inner Base UI input, ring-[3px]) than the native ui.tsxInput (single <input> + inputClasses, ring-2), and bare-field-chrome-contract.test.ts pins the native's data-maka-field-chrome + border-input + ring-2, so retiring the native is not a clean look-preserving swap. The issue plan was re-arranged (#22 → PR8); this PR opens with 1-4 only.

New primitives (packages/ui/src/primitives/)

Primitive	Wraps	data-slot
collapsible.tsx	@base-ui/react/collapsible Root/Trigger/Panel	collapsible / collapsible-trigger / collapsible-panel
tooltip.tsx	@base-ui/react/tooltip Root/Trigger/Content (Portal+Positioner+Popup)	tooltip / tooltip-trigger / tooltip-content
number-field.tsx	@base-ui/react/number-field Root/Input	number-field / number-field-input

All follow the style-hook convention (item 23): data-slot on each part, Base UI's native boolean state attributes (data-panel-open, data-open, etc.) adopted as-is. The Collapsible Trigger carries a button-chrome reset (the native <summary> had no bg/border/padding, but <button> does). The Tooltip Trigger uses Base UI v1's render prop (not Radix asChild). The NumberField Input reuses maka's inputClasses (now exported from ui.tsx) so the port inputs keep their look.

Convergence

• item 23 — style-hook convention: data-slot added to all 20 Base UI wrappers in ui.tsx (Button/Separator/Checkbox/Dialog backdrop+popup/Select Trigger+List+Popup+Group+GroupLabel+Separator+Item/FieldDescription/Label/Switch/Toggle/ToggleGroup/RadioGroup/Radio/Progress). A doc comment at the top of ui.tsx records the state-attribute decision (adopt Base UI native attribute-presence form — maka's renderer CSS has zero state-attribute selectors today, so nothing breaks), the per-component hook map, the whitelisted CSS var hooks, and the className(state) deferral.
• item 17 — disclosure → Collapsible: the four <details>/<summary> sites (chat-view turn-thinking + reasoning-panel, permission-dialog permission-raw, tool-activity) migrate to Base UI Collapsible (all independent single sections, so Collapsible not Accordion). CSS retargeted: summary → [data-slot="collapsible-trigger"], [open] → [data-panel-open], ::-webkit-details-marker/::marker resets dropped (button trigger has no native marker). The reasoning-panel's controlled-open moves from e.currentTarget.open off the toggle event to Collapsible's open + onOpenChange.
• item 20 — tooltip → Base UI Tooltip: the 13 clearest icon-only-action button title= usages (app-shell-chrome-actions 7, browser-panel 4, artifact-pane collapse) migrate to Base UI Tooltip; aria-label stays on the button, TooltipContent is the visual hover hint. The artifact-pane delete button's redundant title= is dropped (it shows a visible 删除 label). The longer tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) are tooltip-eligible but need per-site label-vs-tooltip judgment — deferred to a follow-up.
• item 21 — number-field: the two gateway/proxy port inputs migrate to Base UI NumberField (value: number | null, onValueChange), dropping the Number(event.currentTarget.value) hand-conversion. Proxy: 0 ↔ empty; gateway: empty → 3939 default, both preserved.

New contracts

Contract	Bans	Pins
style-hook-convention-contract.test.ts	a ui.tsx wrapper forwarding to <Base*> without data-slot	the convention doc comment present
disclosure-collapsible-contract.test.ts	<details>/<summary> (incl. in comments) in the 3 migrated files; missing Collapsible import	primitives/collapsible.tsx data-slot on Root/Trigger/Panel
tooltip-converge-contract.test.ts	a title= JSX attribute in the 3 migrated files; missing Tooltip import	primitives/tooltip.tsx data-slot on Root/Trigger/Content
number-field-converge-contract.test.ts	Number(event.currentTarget.value) hand-conversion in the 2 port files; missing NumberField import	primitives/number-field.tsx data-slot on Root/Input

Existing tests updated

• border-width-converge-contract: the triangle-caret allowlist selectors moved from summary::before to [data-slot="collapsible-trigger"]::before (the chevron border-width: 4px 0 4px 5px moved with the disclosure migration).
• chat-marker-cascade-contract / chat-tool-card-cascade-contract: the turn-thinking / tool-card residue selectors + the dropped marker-reset residue.
• app-region-hygiene-contract / search-modal-lifecycle-contract: the topbar-button className extraction + the shell-search-button regex now match the <TooltipTrigger render={<UiButton/>}> shape (the className moved from the UiButton element to the TooltipTrigger that renders it).
• settings-network-gateway-contract: the two port-input assertions now pin the NumberField form (value={...|| null} / value={...} + onValueChange={(v) => update…({ port: v ?? default })).

Commits

1. feat(ui): establish Base UI style-hook convention (data-slot + native state attrs) — item 23 (foundation).
2. feat(ui): migrate disclosure sites to Base UI Collapsible — item 17.
3. feat(ui): migrate icon-action tooltips to Base UI Tooltip — item 20.
4. feat(ui): migrate port inputs to Base UI NumberField — item 21.

Verification

• Tests: npm run -w @maka/desktop test — 2008/2008 pass (rebased onto main with PR2; +26 from PR2, +10 new contract assertions across 4 files). typecheck clean.
• Screenshots vs main (turn-narrative, settings-appearance, first-run × light): tooltips are hover-only so rest state is unchanged; turn-narrative 0.09% (the disclosure commit's summary→button pixel difference), settings-appearance 0.0136 (PR4's settings-nav snap residual, untouched here), first-run 0. The port inputs (general/open-gateway settings) have no capture scenario; they keep their look via the shared inputClasses.

Out of scope / deferred

• Add DeepSeek context budget diagnostics #22 input canonical → PR8 (see Summary).
• tooltip tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) — deferred to a follow-up; each needs a label-vs-tooltip check.
• feat(browser): embedded browser automation (opencli CDP observe→act) #18 toast + Add DeepSeek cost-runtime policy for Runtime v2/AiSdkFlow #19 alert-dialog → PR6. Add archive-backed stale tool result pruning #24-27 large migrations → PR7.

[Astro-Han]

Thanks for the review. Verified every claim against the code before acting; results + fixes below.

P2 — tool-activity defaultOpen (fixed, c06d50a9)

Verified. The disclosure migration set defaultOpen={isOpenByDefault(item.status)} (uncontrolled — open decided once on first render). The pre-Collapsible <details open={isOpenByDefault(status)}> re-evaluated open every render, so a card that defaulted open while pending/running no longer auto-collapsed when it settled. Real regression.

Fix: extracted a ToolActivityCard component (hooks can't live in the .map callback) with a controlled state machine: useState(isOpenByDefault(item.status)) seeds open, useEffect re-syncs it on [item.status] so a pending/running card collapses when it settles, onOpenChange={setOpen} lets the user toggle in between (the next status change re-syncs). This restores the status-following behavior and makes the user-toggle intentional rather than a React-not-rerendering side effect.

Test:disclosure-collapsible-contract now asserts tool-activity must NOT use defaultOpen, must use onOpenChange, and must re-sync via useEffect on [item.status]. (maka has no React testing-library / react-test-renderer, so the behavior is locked structurally + verified by hand; a rerender-act test is out of scope.) Will hand-test pending/running → completed/interrupted before merge.

P3 — Collapsible barrel / contract mismatch (fixed, f4dba2c2)

Verified. Barrel exported Collapsible as PrimitiveCollapsible (the old Tabs/Accordion convention), while Tooltip/NumberField export directly. The contract regex allowed @maka/ui as an import path, but the barrel didn't export Collapsible under that name — a phantom-pass path. The 3 internal sites import via ./primitives/collapsible.js (the in-package convention — alert/chat all use relative primitive paths), so the test passed for the right reason, but the @maka/ui allowance was misleading.

Fix: barrel now exports Collapsible / CollapsibleTrigger / CollapsiblePanel directly (dropped the Primitive* aliases and the CollapsiblePrimitive re-export — nothing consumes them; Tooltip/NumberField don't export their Primitive either). Internal sites keep their relative-path imports (convention); @maka/ui is now genuinely available rather than phantom.

P3 — tooltip.tsx doc showed asChild (fixed, f4dba2c2)

Verified. Line 14 usage doc showed <TooltipTrigger asChild> (Radix), but this PR uses Base UI v1's render prop. Fixed the example to render={<Button />} and noted the Trigger merges its props + children into the rendered element, so the next person doesn't copy the comment and hit the typecheck failure the migration hit.

待验证 — artifact delete title= (fixed, 28f6ed7a)

Partially verified — pushing back on the a11y part. The .maka-artifact-toolbar-destructive-label span is visually hidden but still announced (position:absolute; width:1px; clip-path:inset(50%); CSS comment: "only exists for assistive tech"). So the screen-reader path was preserved when title="删除" was dropped — no SR regression. But mouse users did lose the hover hint (native title= gone, no Base UI Tooltip added).

Fix: wrapped the delete button in a Base UI Tooltip (same shape as the artifact-pane collapse button). TooltipContent mirrors 删除/删除中… for hover; the visually-hidden span still carries the SR label. The two are complementary, not redundant.

P3 — tooltip three-layer JSX repetition (deferred)

Verified. 13 sites are highly isomorphic (<Tooltip><TooltipTrigger render={<Button variant="quiet" size="icon-sm"/>} ...props><Icon/></TooltipTrigger><TooltipContent>label</TooltipContent></Tooltip>).

Defering this one. A TooltipButton helper would save ~15-27 lines net, but the 13 sites' trigger props are heterogeneous (disabled / aria-expanded / conditional icon / conditional label / UiButton vs Button), so the helper becomes a pass-through wrapper (tooltip + render + {...triggerProps} + children) that mostly removes the <Tooltip>/<TooltipContent> wrapping — a modest win for a new abstraction layer + an app-region-hygiene regex adjustment (it extracts classNames from <TooltipTrigger render={<UiButton …/>}> blocks today). Happy to do it as a follow-up if the tooltip site count grows; for 13 sites the direct form is clearer and more flexible. Pushing back rather than adding abstraction for line-count.

待验证 — CI checks / hand-test

Local verification done:npm run -w @maka/desktop test → 2009/2009 pass. npm run typecheck clean across workspaces. Screenshots vs main: turn-narrative 0.09% (the disclosure commit's summary→button residual), settings-appearance 0.0136 (PR4's settings-nav snap, untouched here), first-run 0% — all hover-only tooltip / controlled-open changes add 0 at rest.

CI checks show 0 — will confirm CI triggers on the updated push. Will hand-test before merge: Collapsible keyboard toggle + status-following collapse, Tooltip hover/focus, NumberField empty/invalid input (proxy 0↔empty, gateway empty→3939).

---

Summary: 3 fix commits pushed (c06d50a9, f4dba2c2, 28f6ed7a). 1 item deferred with rationale (tooltip helper). Issue #520 re-arranged: #22 input-canonical moved to PR8 (not a clean look-preserving swap — primitives/input.tsx carries a different structure than the native ui.tsxInput, and bare-field-chrome-contract pins the native's data-maka-field-chrome + border-input + ring-2).

[Astro-Han]

Summary

PR5 of #520 — the style-hook convention foundation + the smaller Base UI migrations that follow it. Four items, one commit each (each independently revertible), TDD red → green → refactor.

#22 (input canonical) was scoped into PR5 but moved to PR8 during this work — primitives/input.tsx carries a different structure (data-slot="input-control" span + inner Base UI input, ring-[3px]) than the native ui.tsxInput (single <input> + inputClasses, ring-2), and bare-field-chrome-contract.test.ts pins the native's data-maka-field-chrome + border-input + ring-2, so retiring the native is not a clean look-preserving swap. The issue plan was re-arranged (#22 → PR8); this PR opens with 1-4 only.

New primitives (packages/ui/src/primitives/)

Primitive	Wraps	data-slot
collapsible.tsx	@base-ui/react/collapsible Root/Trigger/Panel	collapsible / collapsible-trigger / collapsible-panel
tooltip.tsx	@base-ui/react/tooltip Root/Trigger/Content (Portal+Positioner+Popup)	tooltip / tooltip-trigger / tooltip-content
number-field.tsx	@base-ui/react/number-field Root/Input	number-field / number-field-input

All follow the style-hook convention (item 23): data-slot on each part, Base UI's native boolean state attributes (data-panel-open, data-open, etc.) adopted as-is. The Collapsible Trigger carries a button-chrome reset (the native <summary> had no bg/border/padding, but <button> does). The Tooltip Trigger uses Base UI v1's render prop (not Radix asChild). The NumberField Input reuses maka's inputClasses (now exported from ui.tsx) so the port inputs keep their look.

Convergence

• item 23 — style-hook convention: data-slot added to all 20 Base UI wrappers in ui.tsx (Button/Separator/Checkbox/Dialog backdrop+popup/Select Trigger+List+Popup+Group+GroupLabel+Separator+Item/FieldDescription/Label/Switch/Toggle/ToggleGroup/RadioGroup/Radio/Progress). A doc comment at the top of ui.tsx records the state-attribute decision (adopt Base UI native attribute-presence form — maka's renderer CSS has zero state-attribute selectors today, so nothing breaks), the per-component hook map, the whitelisted CSS var hooks, and the className(state) deferral.
• item 17 — disclosure → Collapsible: the four <details>/<summary> sites (chat-view turn-thinking + reasoning-panel, permission-dialog permission-raw, tool-activity) migrate to Base UI Collapsible (all independent single sections, so Collapsible not Accordion). CSS retargeted: summary → [data-slot="collapsible-trigger"], [open] → [data-panel-open], ::-webkit-details-marker/::marker resets dropped (button trigger has no native marker). The reasoning-panel's controlled-open moves from e.currentTarget.open off the toggle event to Collapsible's open + onOpenChange.
• item 20 — tooltip → Base UI Tooltip: the 13 clearest icon-only-action button title= usages (app-shell-chrome-actions 7, browser-panel 4, artifact-pane collapse) migrate to Base UI Tooltip; aria-label stays on the button, TooltipContent is the visual hover hint. The artifact-pane delete button's redundant title= is dropped (it shows a visible 删除 label). The longer tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) are tooltip-eligible but need per-site label-vs-tooltip judgment — deferred to a follow-up.
• item 21 — number-field: the two gateway/proxy port inputs migrate to Base UI NumberField (value: number | null, onValueChange), dropping the Number(event.currentTarget.value) hand-conversion. Proxy: 0 ↔ empty; gateway: empty → 3939 default, both preserved.

New contracts

Contract	Bans	Pins
style-hook-convention-contract.test.ts	a ui.tsx wrapper forwarding to <Base*> without data-slot	the convention doc comment present
disclosure-collapsible-contract.test.ts	<details>/<summary> (incl. in comments) in the 3 migrated files; missing Collapsible import	primitives/collapsible.tsx data-slot on Root/Trigger/Panel
tooltip-converge-contract.test.ts	a title= JSX attribute in the 3 migrated files; missing Tooltip import	primitives/tooltip.tsx data-slot on Root/Trigger/Content
number-field-converge-contract.test.ts	Number(event.currentTarget.value) hand-conversion in the 2 port files; missing NumberField import	primitives/number-field.tsx data-slot on Root/Input

Existing tests updated

• border-width-converge-contract: the triangle-caret allowlist selectors moved from summary::before to [data-slot="collapsible-trigger"]::before (the chevron border-width: 4px 0 4px 5px moved with the disclosure migration).
• chat-marker-cascade-contract / chat-tool-card-cascade-contract: the turn-thinking / tool-card residue selectors + the dropped marker-reset residue.
• app-region-hygiene-contract / search-modal-lifecycle-contract: the topbar-button className extraction + the shell-search-button regex now match the <TooltipTrigger render={<UiButton/>}> shape (the className moved from the UiButton element to the TooltipTrigger that renders it).
• settings-network-gateway-contract: the two port-input assertions now pin the NumberField form (value={...|| null} / value={...} + onValueChange={(v) => update…({ port: v ?? default })).

Commits

1. feat(ui): establish Base UI style-hook convention (data-slot + native state attrs) — item 23 (foundation).
2. feat(ui): migrate disclosure sites to Base UI Collapsible — item 17.
3. feat(ui): migrate icon-action tooltips to Base UI Tooltip — item 20.
4. feat(ui): migrate port inputs to Base UI NumberField — item 21.

Verification

• Tests: npm run -w @maka/desktop test — 2008/2008 pass (rebased onto main with PR2; +26 from PR2, +10 new contract assertions across 4 files). typecheck clean.
• Screenshots vs main (turn-narrative, settings-appearance, first-run × light): tooltips are hover-only so rest state is unchanged; turn-narrative 0.09% (the disclosure commit's summary→button pixel difference), settings-appearance 0.0136 (PR4's settings-nav snap residual, untouched here), first-run 0. The port inputs (general/open-gateway settings) have no capture scenario; they keep their look via the shared inputClasses.

Out of scope / deferred

• Add DeepSeek context budget diagnostics #22 input canonical → PR8 (see Summary).
• tooltip tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) — deferred to a follow-up; each needs a label-vs-tooltip check.
• feat(browser): embedded browser automation (opencli CDP observe→act) #18 toast + Add DeepSeek cost-runtime policy for Runtime v2/AiSdkFlow #19 alert-dialog → PR6. Add archive-backed stale tool result pruning #24-27 large migrations → PR7.

[Astro-Han]

Thanks for the review. Verified every claim against the code before acting; results + fixes below.

P2 — tool-activity defaultOpen (fixed, c06d50a9)

Verified. The disclosure migration set defaultOpen={isOpenByDefault(item.status)} (uncontrolled — open decided once on first render). The pre-Collapsible <details open={isOpenByDefault(status)}> re-evaluated open every render, so a card that defaulted open while pending/running no longer auto-collapsed when it settled. Real regression.

Fix: extracted a ToolActivityCard component (hooks can't live in the .map callback) with a controlled state machine: useState(isOpenByDefault(item.status)) seeds open, useEffect re-syncs it on [item.status] so a pending/running card collapses when it settles, onOpenChange={setOpen} lets the user toggle in between (the next status change re-syncs). This restores the status-following behavior and makes the user-toggle intentional rather than a React-not-rerendering side effect.

Test:disclosure-collapsible-contract now asserts tool-activity must NOT use defaultOpen, must use onOpenChange, and must re-sync via useEffect on [item.status]. (maka has no React testing-library / react-test-renderer, so the behavior is locked structurally + verified by hand; a rerender-act test is out of scope.) Will hand-test pending/running → completed/interrupted before merge.

P3 — Collapsible barrel / contract mismatch (fixed, f4dba2c2)

Verified. Barrel exported Collapsible as PrimitiveCollapsible (the old Tabs/Accordion convention), while Tooltip/NumberField export directly. The contract regex allowed @maka/ui as an import path, but the barrel didn't export Collapsible under that name — a phantom-pass path. The 3 internal sites import via ./primitives/collapsible.js (the in-package convention — alert/chat all use relative primitive paths), so the test passed for the right reason, but the @maka/ui allowance was misleading.

Fix: barrel now exports Collapsible / CollapsibleTrigger / CollapsiblePanel directly (dropped the Primitive* aliases and the CollapsiblePrimitive re-export — nothing consumes them; Tooltip/NumberField don't export their Primitive either). Internal sites keep their relative-path imports (convention); @maka/ui is now genuinely available rather than phantom.

P3 — tooltip.tsx doc showed asChild (fixed, f4dba2c2)

Verified. Line 14 usage doc showed <TooltipTrigger asChild> (Radix), but this PR uses Base UI v1's render prop. Fixed the example to render={<Button />} and noted the Trigger merges its props + children into the rendered element, so the next person doesn't copy the comment and hit the typecheck failure the migration hit.

待验证 — artifact delete title= (fixed, 28f6ed7a)

Partially verified — pushing back on the a11y part. The .maka-artifact-toolbar-destructive-label span is visually hidden but still announced (position:absolute; width:1px; clip-path:inset(50%); CSS comment: "only exists for assistive tech"). So the screen-reader path was preserved when title="删除" was dropped — no SR regression. But mouse users did lose the hover hint (native title= gone, no Base UI Tooltip added).

Fix: wrapped the delete button in a Base UI Tooltip (same shape as the artifact-pane collapse button). TooltipContent mirrors 删除/删除中… for hover; the visually-hidden span still carries the SR label. The two are complementary, not redundant.

P3 — tooltip three-layer JSX repetition (deferred)

Verified. 13 sites are highly isomorphic (<Tooltip><TooltipTrigger render={<Button variant="quiet" size="icon-sm"/>} ...props><Icon/></TooltipTrigger><TooltipContent>label</TooltipContent></Tooltip>).

Defering this one. A TooltipButton helper would save ~15-27 lines net, but the 13 sites' trigger props are heterogeneous (disabled / aria-expanded / conditional icon / conditional label / UiButton vs Button), so the helper becomes a pass-through wrapper (tooltip + render + {...triggerProps} + children) that mostly removes the <Tooltip>/<TooltipContent> wrapping — a modest win for a new abstraction layer + an app-region-hygiene regex adjustment (it extracts classNames from <TooltipTrigger render={<UiButton …/>}> blocks today). Happy to do it as a follow-up if the tooltip site count grows; for 13 sites the direct form is clearer and more flexible. Pushing back rather than adding abstraction for line-count.

待验证 — CI checks / hand-test

Local verification done:npm run -w @maka/desktop test → 2009/2009 pass. npm run typecheck clean across workspaces. Screenshots vs main: turn-narrative 0.09% (the disclosure commit's summary→button residual), settings-appearance 0.0136 (PR4's settings-nav snap, untouched here), first-run 0% — all hover-only tooltip / controlled-open changes add 0 at rest.

CI checks show 0 — will confirm CI triggers on the updated push. Will hand-test before merge: Collapsible keyboard toggle + status-following collapse, Tooltip hover/focus, NumberField empty/invalid input (proxy 0↔empty, gateway empty→3939).

---

Summary: 3 fix commits pushed (c06d50a9, f4dba2c2, 28f6ed7a). 1 item deferred with rationale (tooltip helper). Issue #520 re-arranged: #22 input-canonical moved to PR8 (not a clean look-preserving swap — primitives/input.tsx carries a different structure than the native ui.tsxInput, and bare-field-chrome-contract pins the native's data-maka-field-chrome + border-input + ring-2).

[Astro-Han]

Summary

PR5 of #520 — the style-hook convention foundation + the smaller Base UI migrations that follow it. Four items, one commit each (each independently revertible), TDD red → green → refactor.

#22 (input canonical) was scoped into PR5 but moved to PR8 during this work — primitives/input.tsx carries a different structure (data-slot="input-control" span + inner Base UI input, ring-[3px]) than the native ui.tsxInput (single <input> + inputClasses, ring-2), and bare-field-chrome-contract.test.ts pins the native's data-maka-field-chrome + border-input + ring-2, so retiring the native is not a clean look-preserving swap. The issue plan was re-arranged (#22 → PR8); this PR opens with 1-4 only.

New primitives (packages/ui/src/primitives/)

Primitive	Wraps	data-slot
collapsible.tsx	@base-ui/react/collapsible Root/Trigger/Panel	collapsible / collapsible-trigger / collapsible-panel
tooltip.tsx	@base-ui/react/tooltip Root/Trigger/Content (Portal+Positioner+Popup)	tooltip / tooltip-trigger / tooltip-content
number-field.tsx	@base-ui/react/number-field Root/Input	number-field / number-field-input

All follow the style-hook convention (item 23): data-slot on each part, Base UI's native boolean state attributes (data-panel-open, data-open, etc.) adopted as-is. The Collapsible Trigger carries a button-chrome reset (the native <summary> had no bg/border/padding, but <button> does). The Tooltip Trigger uses Base UI v1's render prop (not Radix asChild). The NumberField Input reuses maka's inputClasses (now exported from ui.tsx) so the port inputs keep their look.

Convergence

• item 23 — style-hook convention: data-slot added to all 20 Base UI wrappers in ui.tsx (Button/Separator/Checkbox/Dialog backdrop+popup/Select Trigger+List+Popup+Group+GroupLabel+Separator+Item/FieldDescription/Label/Switch/Toggle/ToggleGroup/RadioGroup/Radio/Progress). A doc comment at the top of ui.tsx records the state-attribute decision (adopt Base UI native attribute-presence form — maka's renderer CSS has zero state-attribute selectors today, so nothing breaks), the per-component hook map, the whitelisted CSS var hooks, and the className(state) deferral.
• item 17 — disclosure → Collapsible: the four <details>/<summary> sites (chat-view turn-thinking + reasoning-panel, permission-dialog permission-raw, tool-activity) migrate to Base UI Collapsible (all independent single sections, so Collapsible not Accordion). CSS retargeted: summary → [data-slot="collapsible-trigger"], [open] → [data-panel-open], ::-webkit-details-marker/::marker resets dropped (button trigger has no native marker). The reasoning-panel's controlled-open moves from e.currentTarget.open off the toggle event to Collapsible's open + onOpenChange.
• item 20 — tooltip → Base UI Tooltip: the 13 clearest icon-only-action button title= usages (app-shell-chrome-actions 7, browser-panel 4, artifact-pane collapse) migrate to Base UI Tooltip; aria-label stays on the button, TooltipContent is the visual hover hint. The artifact-pane delete button's redundant title= is dropped (it shows a visible 删除 label). The longer tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) are tooltip-eligible but need per-site label-vs-tooltip judgment — deferred to a follow-up.
• item 21 — number-field: the two gateway/proxy port inputs migrate to Base UI NumberField (value: number | null, onValueChange), dropping the Number(event.currentTarget.value) hand-conversion. Proxy: 0 ↔ empty; gateway: empty → 3939 default, both preserved.

New contracts

Contract	Bans	Pins
style-hook-convention-contract.test.ts	a ui.tsx wrapper forwarding to <Base*> without data-slot	the convention doc comment present
disclosure-collapsible-contract.test.ts	<details>/<summary> (incl. in comments) in the 3 migrated files; missing Collapsible import	primitives/collapsible.tsx data-slot on Root/Trigger/Panel
tooltip-converge-contract.test.ts	a title= JSX attribute in the 3 migrated files; missing Tooltip import	primitives/tooltip.tsx data-slot on Root/Trigger/Content
number-field-converge-contract.test.ts	Number(event.currentTarget.value) hand-conversion in the 2 port files; missing NumberField import	primitives/number-field.tsx data-slot on Root/Input

Existing tests updated

• border-width-converge-contract: the triangle-caret allowlist selectors moved from summary::before to [data-slot="collapsible-trigger"]::before (the chevron border-width: 4px 0 4px 5px moved with the disclosure migration).
• chat-marker-cascade-contract / chat-tool-card-cascade-contract: the turn-thinking / tool-card residue selectors + the dropped marker-reset residue.
• app-region-hygiene-contract / search-modal-lifecycle-contract: the topbar-button className extraction + the shell-search-button regex now match the <TooltipTrigger render={<UiButton/>}> shape (the className moved from the UiButton element to the TooltipTrigger that renders it).
• settings-network-gateway-contract: the two port-input assertions now pin the NumberField form (value={...|| null} / value={...} + onValueChange={(v) => update…({ port: v ?? default })).

Commits

1. feat(ui): establish Base UI style-hook convention (data-slot + native state attrs) — item 23 (foundation).
2. feat(ui): migrate disclosure sites to Base UI Collapsible — item 17.
3. feat(ui): migrate icon-action tooltips to Base UI Tooltip — item 20.
4. feat(ui): migrate port inputs to Base UI NumberField — item 21.

Verification

• Tests: npm run -w @maka/desktop test — 2008/2008 pass (rebased onto main with PR2; +26 from PR2, +10 new contract assertions across 4 files). typecheck clean.
• Screenshots vs main (turn-narrative, settings-appearance, first-run × light): tooltips are hover-only so rest state is unchanged; turn-narrative 0.09% (the disclosure commit's summary→button pixel difference), settings-appearance 0.0136 (PR4's settings-nav snap residual, untouched here), first-run 0. The port inputs (general/open-gateway settings) have no capture scenario; they keep their look via the shared inputClasses.

Out of scope / deferred

• Add DeepSeek context budget diagnostics #22 input canonical → PR8 (see Summary).
• tooltip tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) — deferred to a follow-up; each needs a label-vs-tooltip check.
• feat(browser): embedded browser automation (opencli CDP observe→act) #18 toast + Add DeepSeek cost-runtime policy for Runtime v2/AiSdkFlow #19 alert-dialog → PR6. Add archive-backed stale tool result pruning #24-27 large migrations → PR7.

[Astro-Han]

Thanks for the review. Verified every claim against the code before acting; results + fixes below.

P2 — tool-activity defaultOpen (fixed, c06d50a9)

Verified. The disclosure migration set defaultOpen={isOpenByDefault(item.status)} (uncontrolled — open decided once on first render). The pre-Collapsible <details open={isOpenByDefault(status)}> re-evaluated open every render, so a card that defaulted open while pending/running no longer auto-collapsed when it settled. Real regression.

Fix: extracted a ToolActivityCard component (hooks can't live in the .map callback) with a controlled state machine: useState(isOpenByDefault(item.status)) seeds open, useEffect re-syncs it on [item.status] so a pending/running card collapses when it settles, onOpenChange={setOpen} lets the user toggle in between (the next status change re-syncs). This restores the status-following behavior and makes the user-toggle intentional rather than a React-not-rerendering side effect.

Test:disclosure-collapsible-contract now asserts tool-activity must NOT use defaultOpen, must use onOpenChange, and must re-sync via useEffect on [item.status]. (maka has no React testing-library / react-test-renderer, so the behavior is locked structurally + verified by hand; a rerender-act test is out of scope.) Will hand-test pending/running → completed/interrupted before merge.

P3 — Collapsible barrel / contract mismatch (fixed, f4dba2c2)

Verified. Barrel exported Collapsible as PrimitiveCollapsible (the old Tabs/Accordion convention), while Tooltip/NumberField export directly. The contract regex allowed @maka/ui as an import path, but the barrel didn't export Collapsible under that name — a phantom-pass path. The 3 internal sites import via ./primitives/collapsible.js (the in-package convention — alert/chat all use relative primitive paths), so the test passed for the right reason, but the @maka/ui allowance was misleading.

Fix: barrel now exports Collapsible / CollapsibleTrigger / CollapsiblePanel directly (dropped the Primitive* aliases and the CollapsiblePrimitive re-export — nothing consumes them; Tooltip/NumberField don't export their Primitive either). Internal sites keep their relative-path imports (convention); @maka/ui is now genuinely available rather than phantom.

P3 — tooltip.tsx doc showed asChild (fixed, f4dba2c2)

Verified. Line 14 usage doc showed <TooltipTrigger asChild> (Radix), but this PR uses Base UI v1's render prop. Fixed the example to render={<Button />} and noted the Trigger merges its props + children into the rendered element, so the next person doesn't copy the comment and hit the typecheck failure the migration hit.

待验证 — artifact delete title= (fixed, 28f6ed7a)

Partially verified — pushing back on the a11y part. The .maka-artifact-toolbar-destructive-label span is visually hidden but still announced (position:absolute; width:1px; clip-path:inset(50%); CSS comment: "only exists for assistive tech"). So the screen-reader path was preserved when title="删除" was dropped — no SR regression. But mouse users did lose the hover hint (native title= gone, no Base UI Tooltip added).

Fix: wrapped the delete button in a Base UI Tooltip (same shape as the artifact-pane collapse button). TooltipContent mirrors 删除/删除中… for hover; the visually-hidden span still carries the SR label. The two are complementary, not redundant.

P3 — tooltip three-layer JSX repetition (deferred)

Verified. 13 sites are highly isomorphic (<Tooltip><TooltipTrigger render={<Button variant="quiet" size="icon-sm"/>} ...props><Icon/></TooltipTrigger><TooltipContent>label</TooltipContent></Tooltip>).

Defering this one. A TooltipButton helper would save ~15-27 lines net, but the 13 sites' trigger props are heterogeneous (disabled / aria-expanded / conditional icon / conditional label / UiButton vs Button), so the helper becomes a pass-through wrapper (tooltip + render + {...triggerProps} + children) that mostly removes the <Tooltip>/<TooltipContent> wrapping — a modest win for a new abstraction layer + an app-region-hygiene regex adjustment (it extracts classNames from <TooltipTrigger render={<UiButton …/>}> blocks today). Happy to do it as a follow-up if the tooltip site count grows; for 13 sites the direct form is clearer and more flexible. Pushing back rather than adding abstraction for line-count.

待验证 — CI checks / hand-test

Local verification done:npm run -w @maka/desktop test → 2009/2009 pass. npm run typecheck clean across workspaces. Screenshots vs main: turn-narrative 0.09% (the disclosure commit's summary→button residual), settings-appearance 0.0136 (PR4's settings-nav snap, untouched here), first-run 0% — all hover-only tooltip / controlled-open changes add 0 at rest.

CI checks show 0 — will confirm CI triggers on the updated push. Will hand-test before merge: Collapsible keyboard toggle + status-following collapse, Tooltip hover/focus, NumberField empty/invalid input (proxy 0↔empty, gateway empty→3939).

---

Summary: 3 fix commits pushed (c06d50a9, f4dba2c2, 28f6ed7a). 1 item deferred with rationale (tooltip helper). Issue #520 re-arranged: #22 input-canonical moved to PR8 (not a clean look-preserving swap — primitives/input.tsx carries a different structure than the native ui.tsxInput, and bare-field-chrome-contract pins the native's data-maka-field-chrome + border-input + ring-2).

[Astro-Han]

Summary

PR5 of #520 — the style-hook convention foundation + the smaller Base UI migrations that follow it. Four items, one commit each (each independently revertible), TDD red → green → refactor.

#22 (input canonical) was scoped into PR5 but moved to PR8 during this work — primitives/input.tsx carries a different structure (data-slot="input-control" span + inner Base UI input, ring-[3px]) than the native ui.tsxInput (single <input> + inputClasses, ring-2), and bare-field-chrome-contract.test.ts pins the native's data-maka-field-chrome + border-input + ring-2, so retiring the native is not a clean look-preserving swap. The issue plan was re-arranged (#22 → PR8); this PR opens with 1-4 only.

New primitives (packages/ui/src/primitives/)

Primitive	Wraps	data-slot
collapsible.tsx	@base-ui/react/collapsible Root/Trigger/Panel	collapsible / collapsible-trigger / collapsible-panel
tooltip.tsx	@base-ui/react/tooltip Root/Trigger/Content (Portal+Positioner+Popup)	tooltip / tooltip-trigger / tooltip-content
number-field.tsx	@base-ui/react/number-field Root/Input	number-field / number-field-input

All follow the style-hook convention (item 23): data-slot on each part, Base UI's native boolean state attributes (data-panel-open, data-open, etc.) adopted as-is. The Collapsible Trigger carries a button-chrome reset (the native <summary> had no bg/border/padding, but <button> does). The Tooltip Trigger uses Base UI v1's render prop (not Radix asChild). The NumberField Input reuses maka's inputClasses (now exported from ui.tsx) so the port inputs keep their look.

Convergence

• item 23 — style-hook convention: data-slot added to all 20 Base UI wrappers in ui.tsx (Button/Separator/Checkbox/Dialog backdrop+popup/Select Trigger+List+Popup+Group+GroupLabel+Separator+Item/FieldDescription/Label/Switch/Toggle/ToggleGroup/RadioGroup/Radio/Progress). A doc comment at the top of ui.tsx records the state-attribute decision (adopt Base UI native attribute-presence form — maka's renderer CSS has zero state-attribute selectors today, so nothing breaks), the per-component hook map, the whitelisted CSS var hooks, and the className(state) deferral.
• item 17 — disclosure → Collapsible: the four <details>/<summary> sites (chat-view turn-thinking + reasoning-panel, permission-dialog permission-raw, tool-activity) migrate to Base UI Collapsible (all independent single sections, so Collapsible not Accordion). CSS retargeted: summary → [data-slot="collapsible-trigger"], [open] → [data-panel-open], ::-webkit-details-marker/::marker resets dropped (button trigger has no native marker). The reasoning-panel's controlled-open moves from e.currentTarget.open off the toggle event to Collapsible's open + onOpenChange.
• item 20 — tooltip → Base UI Tooltip: the 13 clearest icon-only-action button title= usages (app-shell-chrome-actions 7, browser-panel 4, artifact-pane collapse) migrate to Base UI Tooltip; aria-label stays on the button, TooltipContent is the visual hover hint. The artifact-pane delete button's redundant title= is dropped (it shows a visible 删除 label). The longer tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) are tooltip-eligible but need per-site label-vs-tooltip judgment — deferred to a follow-up.
• item 21 — number-field: the two gateway/proxy port inputs migrate to Base UI NumberField (value: number | null, onValueChange), dropping the Number(event.currentTarget.value) hand-conversion. Proxy: 0 ↔ empty; gateway: empty → 3939 default, both preserved.

New contracts

Contract	Bans	Pins
style-hook-convention-contract.test.ts	a ui.tsx wrapper forwarding to <Base*> without data-slot	the convention doc comment present
disclosure-collapsible-contract.test.ts	<details>/<summary> (incl. in comments) in the 3 migrated files; missing Collapsible import	primitives/collapsible.tsx data-slot on Root/Trigger/Panel
tooltip-converge-contract.test.ts	a title= JSX attribute in the 3 migrated files; missing Tooltip import	primitives/tooltip.tsx data-slot on Root/Trigger/Content
number-field-converge-contract.test.ts	Number(event.currentTarget.value) hand-conversion in the 2 port files; missing NumberField import	primitives/number-field.tsx data-slot on Root/Input

Existing tests updated

• border-width-converge-contract: the triangle-caret allowlist selectors moved from summary::before to [data-slot="collapsible-trigger"]::before (the chevron border-width: 4px 0 4px 5px moved with the disclosure migration).
• chat-marker-cascade-contract / chat-tool-card-cascade-contract: the turn-thinking / tool-card residue selectors + the dropped marker-reset residue.
• app-region-hygiene-contract / search-modal-lifecycle-contract: the topbar-button className extraction + the shell-search-button regex now match the <TooltipTrigger render={<UiButton/>}> shape (the className moved from the UiButton element to the TooltipTrigger that renders it).
• settings-network-gateway-contract: the two port-input assertions now pin the NumberField form (value={...|| null} / value={...} + onValueChange={(v) => update…({ port: v ?? default })).

Commits

1. feat(ui): establish Base UI style-hook convention (data-slot + native state attrs) — item 23 (foundation).
2. feat(ui): migrate disclosure sites to Base UI Collapsible — item 17.
3. feat(ui): migrate icon-action tooltips to Base UI Tooltip — item 20.
4. feat(ui): migrate port inputs to Base UI NumberField — item 21.

Verification

• Tests: npm run -w @maka/desktop test — 2008/2008 pass (rebased onto main with PR2; +26 from PR2, +10 new contract assertions across 4 files). typecheck clean.
• Screenshots vs main (turn-narrative, settings-appearance, first-run × light): tooltips are hover-only so rest state is unchanged; turn-narrative 0.09% (the disclosure commit's summary→button pixel difference), settings-appearance 0.0136 (PR4's settings-nav snap residual, untouched here), first-run 0. The port inputs (general/open-gateway settings) have no capture scenario; they keep their look via the shared inputClasses.

Out of scope / deferred

• Add DeepSeek context budget diagnostics #22 input canonical → PR8 (see Summary).
• tooltip tail (truncation spans, SelectTrigger titles, status badges, OnboardingHero submit) — deferred to a follow-up; each needs a label-vs-tooltip check.
• feat(browser): embedded browser automation (opencli CDP observe→act) #18 toast + Add DeepSeek cost-runtime policy for Runtime v2/AiSdkFlow #19 alert-dialog → PR6. Add archive-backed stale tool result pruning #24-27 large migrations → PR7.

[Astro-Han]

Thanks for the review. Verified every claim against the code before acting; results + fixes below.

P2 — tool-activity defaultOpen (fixed, c06d50a9)

Verified. The disclosure migration set defaultOpen={isOpenByDefault(item.status)} (uncontrolled — open decided once on first render). The pre-Collapsible <details open={isOpenByDefault(status)}> re-evaluated open every render, so a card that defaulted open while pending/running no longer auto-collapsed when it settled. Real regression.

Fix: extracted a ToolActivityCard component (hooks can't live in the .map callback) with a controlled state machine: useState(isOpenByDefault(item.status)) seeds open, useEffect re-syncs it on [item.status] so a pending/running card collapses when it settles, onOpenChange={setOpen} lets the user toggle in between (the next status change re-syncs). This restores the status-following behavior and makes the user-toggle intentional rather than a React-not-rerendering side effect.

Test:disclosure-collapsible-contract now asserts tool-activity must NOT use defaultOpen, must use onOpenChange, and must re-sync via useEffect on [item.status]. (maka has no React testing-library / react-test-renderer, so the behavior is locked structurally + verified by hand; a rerender-act test is out of scope.) Will hand-test pending/running → completed/interrupted before merge.

P3 — Collapsible barrel / contract mismatch (fixed, f4dba2c2)

Verified. Barrel exported Collapsible as PrimitiveCollapsible (the old Tabs/Accordion convention), while Tooltip/NumberField export directly. The contract regex allowed @maka/ui as an import path, but the barrel didn't export Collapsible under that name — a phantom-pass path. The 3 internal sites import via ./primitives/collapsible.js (the in-package convention — alert/chat all use relative primitive paths), so the test passed for the right reason, but the @maka/ui allowance was misleading.

Fix: barrel now exports Collapsible / CollapsibleTrigger / CollapsiblePanel directly (dropped the Primitive* aliases and the CollapsiblePrimitive re-export — nothing consumes them; Tooltip/NumberField don't export their Primitive either). Internal sites keep their relative-path imports (convention); @maka/ui is now genuinely available rather than phantom.

P3 — tooltip.tsx doc showed asChild (fixed, f4dba2c2)

Verified. Line 14 usage doc showed <TooltipTrigger asChild> (Radix), but this PR uses Base UI v1's render prop. Fixed the example to render={<Button />} and noted the Trigger merges its props + children into the rendered element, so the next person doesn't copy the comment and hit the typecheck failure the migration hit.

待验证 — artifact delete title= (fixed, 28f6ed7a)

Partially verified — pushing back on the a11y part. The .maka-artifact-toolbar-destructive-label span is visually hidden but still announced (position:absolute; width:1px; clip-path:inset(50%); CSS comment: "only exists for assistive tech"). So the screen-reader path was preserved when title="删除" was dropped — no SR regression. But mouse users did lose the hover hint (native title= gone, no Base UI Tooltip added).

Fix: wrapped the delete button in a Base UI Tooltip (same shape as the artifact-pane collapse button). TooltipContent mirrors 删除/删除中… for hover; the visually-hidden span still carries the SR label. The two are complementary, not redundant.

P3 — tooltip three-layer JSX repetition (deferred)

Verified. 13 sites are highly isomorphic (<Tooltip><TooltipTrigger render={<Button variant="quiet" size="icon-sm"/>} ...props><Icon/></TooltipTrigger><TooltipContent>label</TooltipContent></Tooltip>).

Defering this one. A TooltipButton helper would save ~15-27 lines net, but the 13 sites' trigger props are heterogeneous (disabled / aria-expanded / conditional icon / conditional label / UiButton vs Button), so the helper becomes a pass-through wrapper (tooltip + render + {...triggerProps} + children) that mostly removes the <Tooltip>/<TooltipContent> wrapping — a modest win for a new abstraction layer + an app-region-hygiene regex adjustment (it extracts classNames from <TooltipTrigger render={<UiButton …/>}> blocks today). Happy to do it as a follow-up if the tooltip site count grows; for 13 sites the direct form is clearer and more flexible. Pushing back rather than adding abstraction for line-count.

待验证 — CI checks / hand-test

Local verification done:npm run -w @maka/desktop test → 2009/2009 pass. npm run typecheck clean across workspaces. Screenshots vs main: turn-narrative 0.09% (the disclosure commit's summary→button residual), settings-appearance 0.0136 (PR4's settings-nav snap, untouched here), first-run 0% — all hover-only tooltip / controlled-open changes add 0 at rest.

CI checks show 0 — will confirm CI triggers on the updated push. Will hand-test before merge: Collapsible keyboard toggle + status-following collapse, Tooltip hover/focus, NumberField empty/invalid input (proxy 0↔empty, gateway empty→3939).

---

Summary: 3 fix commits pushed (c06d50a9, f4dba2c2, 28f6ed7a). 1 item deferred with rationale (tooltip helper). Issue #520 re-arranged: #22 input-canonical moved to PR8 (not a clean look-preserving swap — primitives/input.tsx carries a different structure than the native ui.tsxInput, and bare-field-chrome-contract pins the native's data-maka-field-chrome + border-input + ring-2).