fix(desktop): stop Skills Hub picker overlaying the installed list and cut Capabilities lag

Layout (overlap bug): the EmbeddedHubPicker section had no flex
containment — its fixed-height iframe viewport made the section's
min-content height rigid, so at a tall persisted drag height or a short
window the flex column starved the installed-skills area to 0px and the
hub header row painted straight over the list's sort strip and "changes
apply to new sessions" footer. The picker section now clips its own
content (overflow-hidden, shrinkable, min-h for the header row), the hub
viewport uses flex-basis instead of a hard height so it gives pixels
back first, the list region keeps a min-h-40 floor, and the sash drag is
clamped against the actual column height (list reserve) rather than just
the window.

Perf (Capabilities lag):
- The hub iframe (a full Docusaurus site) mounted eagerly with the view
  and re-mounted on every scope change (key={`picker-${scopeKey}`}).
  It now lazy-mounts the first time the Skills tab is shown, then stays
  mounted but display:none across Tools/MCP so a tab bounce never
  reloads the site. The scope key is gone — the picker fetches nothing;
  the profile rides into each install call as a prop.
- EmbeddedHubPicker is memo()ed and subscribes to the single
  UPDATE_ALL_KEY running flag via useStoreSelector instead of the whole
  $hubActions map, which churns on every tailed log line during installs.
- Collapse state now persists through the pane store (0 = collapsed),
  matching DetailPane, instead of resetting open on every mount.
- CapRow gets content-visibility:auto so 80+ row lists skip offscreen
  layout/paint (fixed row heights keep scroll geometry stable).

Validation: npm run check:lint (tsc x3 + eslint) clean; vitest
src/app/skills 9/9 passing, including a new test asserting the iframe
is absent on non-Skills tabs, mounts with the Skills tab, and survives
a tab switch hidden.
This commit is contained in:
Teknium
2026-08-17 16:01:49 -07:00
parent 76ff060748
commit d16413ef43
4 changed files with 252 additions and 147 deletions
+5 -1
View File
@@ -449,7 +449,11 @@ export function CapRow({
return (
<div
className={cn(
'group/row row-hover flex w-full shrink-0 items-center rounded-md hover:text-foreground',
// content-visibility:auto lets the browser skip layout/paint for
// offscreen rows — the Capabilities lists routinely hold 80+ entries.
// Row height is already fixed (h-8/h-11), so skipped rows keep their
// exact size and scrollbar geometry never jumps.
'group/row row-hover flex w-full shrink-0 items-center rounded-md [content-visibility:auto] hover:text-foreground',
subtitle ? 'h-11' : 'h-8',
active ? 'bg-(--ui-row-active-background) text-foreground' : 'text-(--ui-text-secondary)'
)}
@@ -1,9 +1,10 @@
import { useStore } from '@nanostores/react'
import { type PointerEvent as ReactPointerEvent, useEffect, useState } from 'react'
import { memo, type PointerEvent as ReactPointerEvent, useEffect, useRef, useState } from 'react'
import { Button } from '@/components/ui/button'
import { useI18n } from '@/i18n'
import { Loader2 } from '@/lib/icons'
import { useStoreSelector } from '@/lib/use-session-slice'
import { cn } from '@/lib/utils'
import { $hubActions, installHubSkill, UPDATE_ALL_KEY, updateHubSkills } from '@/store/hub-actions'
import { notify, notifyError } from '@/store/notifications'
@@ -26,6 +27,13 @@ const HUB_PANE_ID = 'capabilities-hub'
const HUB_DEFAULT_PX = 380
const HUB_MIN_PX = 120
const HUB_MAX_VH = 0.75
// Collapse threshold, mirroring DetailPane: a persisted height at/below this
// reads as "collapsed to the header" (the toggle stores 0).
const HUB_COLLAPSED_PX = 4
// Room the sash must always leave for the content ABOVE the picker (the
// installed-skills list plus its strip) so dragging the hub up can never
// crush the list to zero and shove its chrome under the hub header.
const HUB_LIST_RESERVED_PX = 176
interface SkillPickMessage {
identifier?: string
@@ -36,6 +44,10 @@ interface SkillPickMessage {
}
interface EmbeddedHubPickerProps {
/** Kept mounted but fully hidden (display:none). The Capabilities view uses
* this to preserve the loaded hub iframe across tab switches — a plain
* unmount would reload the whole docs site on every return to Skills. */
hidden?: boolean
/** Names of skills already installed in the scoped profile — a pick that
* matches is refused with a toast instead of re-running the install. */
installedNames: ReadonlySet<string>
@@ -46,15 +58,28 @@ interface EmbeddedHubPickerProps {
/** The Skills Hub browser for the Skills tab: a resizable iframe of the live
* hub where every card installs with one click. Expanded by default —
* discovery IS the point — with a collapse toggle and an update-all action. */
export function EmbeddedHubPicker({ installedNames, profile }: EmbeddedHubPickerProps) {
* discovery IS the point — with a collapse toggle (persisted, like every
* other pane) and an update-all action. Memoized: the iframe must not sit in
* the parent's keystroke/re-render path. */
export const EmbeddedHubPicker = memo(function EmbeddedHubPicker({
hidden = false,
installedNames,
profile
}: EmbeddedHubPickerProps) {
const { t } = useI18n()
const h = t.skills.hub
const [open, setOpen] = useState(true)
const updating = useStore($hubActions)[UPDATE_ALL_KEY]?.running ?? false
// Subscribe to the ONE flag this header renders, not the whole action map —
// $hubActions churns on every tailed log line during an install.
const updating = useStoreSelector($hubActions, actions => actions[UPDATE_ALL_KEY]?.running ?? false)
// Collapse state rides the same persisted height override the sash writes
// (0 = collapsed to the header), so "Hide the hub browser" survives tab
// switches and restarts instead of re-expanding — and re-loading the docs
// site — on every visit. Same contract as DetailPane.
const heightOverride = useStore($paneHeightOverride(HUB_PANE_ID))
const height = heightOverride ?? HUB_DEFAULT_PX
const open = height > HUB_COLLAPSED_PX
const [dragging, setDragging] = useState(false)
const sectionRef = useRef<HTMLElement>(null)
// Top-edge sash: dragging UP grows the hub (shrinking the skills list above,
// which is the flex-1 sibling). Same gesture as DetailPane / the shell's
@@ -68,7 +93,13 @@ export function EmbeddedHubPicker({ installedNames, profile }: EmbeddedHubPicker
event.preventDefault()
const startY = event.clientY
const startHeight = height
const max = Math.round(window.innerHeight * HUB_MAX_VH)
// Clamp against the actual Capabilities column, not just the window: the
// hub may never grow past "column minus the list's reserved strip", so
// the installed list always keeps real height and its header/footer can't
// end up sharing pixels with the hub header.
const column = sectionRef.current?.parentElement
const columnMax = column ? column.clientHeight - HUB_LIST_RESERVED_PX : Number.POSITIVE_INFINITY
const max = Math.max(HUB_MIN_PX, Math.round(Math.min(window.innerHeight * HUB_MAX_VH, columnMax)))
setDragging(true)
const onMove = (move: globalThis.PointerEvent) => {
@@ -131,7 +162,20 @@ export function EmbeddedHubPicker({ installedNames, profile }: EmbeddedHubPicker
}
return (
<div className="relative border-t border-(--ui-stroke-secondary)">
<section
className={cn(
// Shrinkable (no shrink-0) + overflow-hidden: the picker is a flex
// child of the Capabilities column. Before, its fixed-height viewport
// made the section's min-content height rigid, so a short window (or a
// tall persisted drag height) starved the installed list to 0px and
// the list's strip/footer painted straight over this header. Now the
// section clips its own content and gives height back to the list;
// min-h keeps the header row itself always visible.
'relative flex min-h-9 flex-col overflow-hidden border-t border-(--ui-stroke-secondary)',
hidden && 'hidden'
)}
ref={sectionRef}
>
{/* Top-edge drag sash — pull the whole hub section up/down. */}
<div
className="group/hubsash absolute inset-x-0 top-0 z-10 h-1 -translate-y-1/2 cursor-row-resize"
@@ -145,22 +189,28 @@ export function EmbeddedHubPicker({ installedNames, profile }: EmbeddedHubPicker
)}
/>
</div>
<div className="flex items-center justify-between px-3 py-1.5">
<div className="flex shrink-0 items-center justify-between px-3 py-1.5">
<span className="text-[0.7rem] font-medium text-(--ui-text-tertiary)">{h.pickerTitle}</span>
<div className="flex items-center gap-1">
<Button disabled={updating} onClick={updateAll} size="xs" variant="text">
{updating && <Loader2 className="size-3 animate-spin" />}
{updating ? h.updating : h.updateAll}
</Button>
<Button onClick={() => setOpen(v => !v)} size="xs" variant="text">
<Button
onClick={() => setPaneHeightOverride(HUB_PANE_ID, open ? 0 : undefined)}
size="xs"
variant="text"
>
{open ? h.pickerHide : h.pickerBrowse}
</Button>
</div>
</div>
{open && (
<div className="grid gap-1 px-3 pb-2">
<div className="flex min-h-0 flex-col gap-1 px-3 pb-2">
{/* Resizable viewport: height comes from the top-edge drag sash
above (persisted; double-click resets). The iframe is rendered
above (persisted; double-click resets). flex-basis instead of a
hard height so a short window shrinks the hub viewport rather
than letting it spill over the list. The iframe is rendered
oversized and scaled DOWN (133% × 0.75) so the hub page starts
zoomed out — the cross-origin page itself can't be styled, but
scaling the frame is ours. */}
@@ -168,9 +218,9 @@ export function EmbeddedHubPicker({ installedNames, profile }: EmbeddedHubPicker
style={{
border: '1px solid var(--ui-stroke-secondary)',
borderRadius: 8,
height,
flex: `0 1 ${height}px`,
maxWidth: '100%',
minHeight: HUB_MIN_PX,
minHeight: 0,
minWidth: 320,
overflow: 'hidden',
position: 'relative',
@@ -194,9 +244,9 @@ export function EmbeddedHubPicker({ installedNames, profile }: EmbeddedHubPicker
title={h.pickerTitle}
/>
</div>
<p className="px-1 text-[0.65rem] leading-4 text-(--ui-text-quaternary)">{h.pickerHint}</p>
<p className="shrink-0 px-1 text-[0.65rem] leading-4 text-(--ui-text-quaternary)">{h.pickerHint}</p>
</div>
)}
</div>
</section>
)
}
})
@@ -292,6 +292,42 @@ describe('SkillsView toolset management', () => {
)
})
it('mounts the hub iframe lazily and keeps it (hidden) across tab switches', async () => {
// On a non-Skills tab the docs-site iframe must not exist at all — an
// eagerly mounted hub is exactly the Capabilities lag bug.
await renderSkills() // ?tab=toolsets
await screen.findByRole('switch', { name: 'Turn Web Search toolset off' })
expect(document.querySelector('iframe')).toBeNull()
cleanup()
// Embedded mode drives tabs through local state (the route hooks are
// mocked here), starting on Skills: the picker mounts with the tab.
const { SkillsView } = await import('./index')
await act(async () => {
render(
<QueryClientProvider client={queryClient}>
<MemoryRouter initialEntries={['/skills']}>
<SkillsView embedded />
</MemoryRouter>
</QueryClientProvider>
)
})
const iframe = document.querySelector('iframe')
expect(iframe).toBeTruthy()
expect(iframe!.closest('section')!.classList.contains('hidden')).toBe(false)
// Switch to Tools → the iframe STAYS mounted (no docs-site reload on the
// next visit) but its section is fully hidden, so nothing from the hub
// can paint over the toolsets UI.
await act(async () => {
fireEvent.click(screen.getByRole('button', { name: /Tools/ }))
})
const kept = document.querySelector('iframe')
expect(kept).toBeTruthy()
expect(kept!.closest('section')!.classList.contains('hidden')).toBe(true)
})
it('shows a vision explainer that deep-links to Settings → Models', async () => {
// Vision has no TOOL_CATEGORIES provider matrix — its model lives in the
// auxiliary model config, so the detail pane must point there instead of
+145 -130
View File
@@ -211,6 +211,17 @@ export function SkillsView({
const [query, setQuery] = useState('')
// The hub picker hosts a full docs-site iframe — the single most expensive
// thing on this page. It mounts lazily (first time the Skills tab is shown)
// and then STAYS mounted but hidden across tab switches, so bouncing to
// Tools/MCP and back never reloads the site. Derived-state pattern: flips
// once, during render, never back.
const [hubMounted, setHubMounted] = useState(mode === 'skills')
if (mode === 'skills' && !hubMounted) {
setHubMounted(true)
}
// Capabilities profile-scope selector: which profile's Tools/MCP config we're
// editing. Defaults to the app-wide active profile; overriding it here lets
// the user configure ANY profile's toolsets/MCP without switching the whole
@@ -670,138 +681,142 @@ export function SkillsView({
profile. */}
<div className="flex h-full flex-col">
{profileScopeSelector}
<div className="min-h-0 flex-1">
{mode === 'mcp' ? (
<McpTab gateway={gateway} key={`mcp-${scopeKey}`} profile={scopeProfile} />
) : (skillsFailed || toolsetsFailed) && (!skills || !toolsets) ? (
<PanelEmpty
action={
<Button onClick={() => void refreshCapabilities()} size="sm">
{t.skills.refresh}
</Button>
}
description={skillsError instanceof Error ? skillsError.message : undefined}
icon="error"
title={t.skills.skillsLoadFailed}
/>
) : !skills || !toolsets ? (
<PageLoader label={t.skills.loading} />
) : mode === 'skills' ? (
// Installed skills on top, the Skills Hub browser underneath —
// discovery sits with management, expanded by default. The picker
// renders even when the (filtered) list is empty: a fresh install
// with zero skills is exactly when browsing the hub matters most.
<div className="flex h-full min-h-0 flex-col">
<div className="min-h-0 flex-1">
{visibleSkills.length === 0 ? (
capabilityEmpty('skills')
) : (
<MasterDetail pane={skillEditorPane} resizeId="capabilities-split" split="wide">
<ListColumn
header={
<ListStrip
left={sortButton(skillsSortDesc, () => $skillsSortDesc.set(!$skillsSortDesc.get()))}
right={
<ListStripMenu
items={[
{
disabled: bulkBusy,
label: t.skills.disableUnused,
onSelect: () => void disableUnused()
}
]}
label={t.skills.tabSkills}
toggle={bulkSwitch(allSkillsEnabled)}
/>
}
/>
}
>
{visibleSkills.map(skill => (
<CapRow
active={activeSkill?.name === skill.name}
busy={bulkBusy}
enabled={skill.enabled}
key={skill.name}
meta={usageOf(skill) > 0 ? `×${compactNumber(usageOf(skill))}` : undefined}
onSelect={() => setSelectedSkill(skill.name)}
onToggle={enabled => void handleToggleSkill(skill, enabled)}
subtitle={skillSubtitle(skill)}
title={skill.name}
toggleLabel={skill.name}
/>
))}
</ListColumn>
<DetailColumn footer={t.skills.changesApplyNewSessions}>
{activeSkill && (
<SkillDetail
onArchive={() => setArchiveTarget(activeSkill.name)}
onEdit={() => void openSkillEditor(activeSkill.name)}
profile={scopeProfile}
skill={activeSkill}
/>
)}
</DetailColumn>
</MasterDetail>
)}
</div>
<EmbeddedHubPicker
installedNames={installedSkillNames}
key={`picker-${scopeKey}`}
profile={scopeProfile}
/>
</div>
) : visibleToolsets.length === 0 ? (
capabilityEmpty('tools')
) : (
<MasterDetail resizeId="capabilities-split" split="wide">
<ListColumn
header={
<ListStrip
left={sortButton(toolsetsSortDesc, () => $toolsetsSortDesc.set(!$toolsetsSortDesc.get()))}
right={<ListStripMenu label={t.skills.tabToolsets} toggle={bulkSwitch(allToolsetsEnabled)} />}
/>
<div className="flex min-h-0 flex-1 flex-col">
<div className={mode === 'skills' ? 'min-h-40 flex-1 overflow-hidden' : 'min-h-0 flex-1'}>
{mode === 'mcp' ? (
<McpTab gateway={gateway} key={`mcp-${scopeKey}`} profile={scopeProfile} />
) : (skillsFailed || toolsetsFailed) && (!skills || !toolsets) ? (
<PanelEmpty
action={
<Button onClick={() => void refreshCapabilities()} size="sm">
{t.skills.refresh}
</Button>
}
>
{visibleToolsets.map(toolset => {
const label = toolsetDisplayLabel(toolset)
const calls = toolCalls ? toolsetCalls(toolset, toolCalls) : null
return (
<CapRow
active={activeToolset?.name === toolset.name}
busy={bulkBusy}
enabled={toolset.enabled}
key={toolset.name}
meta={
calls === null ? (
<CountSkeleton />
) : calls > 0 ? (
`×${compactNumber(calls)}`
) : (
`${toolNames(toolset).length} tools`
)
}
onSelect={() => setSelectedToolset(toolset.name)}
onToggle={checked => void handleToggleToolset(toolset, checked)}
subtitle={asText(toolset.description)}
title={label}
toggleLabel={t.skills.toggleToolset(label, !toolset.enabled)}
description={skillsError instanceof Error ? skillsError.message : undefined}
icon="error"
title={t.skills.skillsLoadFailed}
/>
) : !skills || !toolsets ? (
<PageLoader label={t.skills.loading} />
) : mode === 'skills' ? (
// Installed skills on top, the Skills Hub browser underneath —
// discovery sits with management. The list region keeps a floor
// (min-h-40, on the wrapper above) so a tall hub viewport or a
// short window shrinks the HUB, never the list: the sort strip
// and "changes apply" footer can no longer be starved to 0px
// and painted over by the hub header.
visibleSkills.length === 0 ? (
capabilityEmpty('skills')
) : (
<MasterDetail pane={skillEditorPane} resizeId="capabilities-split" split="wide">
<ListColumn
header={
<ListStrip
left={sortButton(skillsSortDesc, () => $skillsSortDesc.set(!$skillsSortDesc.get()))}
right={
<ListStripMenu
items={[
{
disabled: bulkBusy,
label: t.skills.disableUnused,
onSelect: () => void disableUnused()
}
]}
label={t.skills.tabSkills}
toggle={bulkSwitch(allSkillsEnabled)}
/>
}
/>
}
>
{visibleSkills.map(skill => (
<CapRow
active={activeSkill?.name === skill.name}
busy={bulkBusy}
enabled={skill.enabled}
key={skill.name}
meta={usageOf(skill) > 0 ? `×${compactNumber(usageOf(skill))}` : undefined}
onSelect={() => setSelectedSkill(skill.name)}
onToggle={enabled => void handleToggleSkill(skill, enabled)}
subtitle={skillSubtitle(skill)}
title={skill.name}
toggleLabel={skill.name}
/>
))}
</ListColumn>
<DetailColumn footer={t.skills.changesApplyNewSessions}>
{activeSkill && (
<SkillDetail
onArchive={() => setArchiveTarget(activeSkill.name)}
onEdit={() => void openSkillEditor(activeSkill.name)}
profile={scopeProfile}
skill={activeSkill}
/>
)}
</DetailColumn>
</MasterDetail>
)
) : visibleToolsets.length === 0 ? (
capabilityEmpty('tools')
) : (
<MasterDetail resizeId="capabilities-split" split="wide">
<ListColumn
header={
<ListStrip
left={sortButton(toolsetsSortDesc, () => $toolsetsSortDesc.set(!$toolsetsSortDesc.get()))}
right={<ListStripMenu label={t.skills.tabToolsets} toggle={bulkSwitch(allToolsetsEnabled)} />}
/>
)
})}
</ListColumn>
<DetailColumn footer={t.skills.changesApplyNewSessions}>
{activeToolset && (
<ToolsetDetail
onConfiguredChange={refreshToolsets}
profile={scopeProfile}
toolCalls={toolCalls ?? {}}
toolset={activeToolset}
/>
)}
</DetailColumn>
</MasterDetail>
}
>
{visibleToolsets.map(toolset => {
const label = toolsetDisplayLabel(toolset)
const calls = toolCalls ? toolsetCalls(toolset, toolCalls) : null
return (
<CapRow
active={activeToolset?.name === toolset.name}
busy={bulkBusy}
enabled={toolset.enabled}
key={toolset.name}
meta={
calls === null ? (
<CountSkeleton />
) : calls > 0 ? (
`×${compactNumber(calls)}`
) : (
`${toolNames(toolset).length} tools`
)
}
onSelect={() => setSelectedToolset(toolset.name)}
onToggle={checked => void handleToggleToolset(toolset, checked)}
subtitle={asText(toolset.description)}
title={label}
toggleLabel={t.skills.toggleToolset(label, !toolset.enabled)}
/>
)
})}
</ListColumn>
<DetailColumn footer={t.skills.changesApplyNewSessions}>
{activeToolset && (
<ToolsetDetail
onConfiguredChange={refreshToolsets}
profile={scopeProfile}
toolCalls={toolCalls ?? {}}
toolset={activeToolset}
/>
)}
</DetailColumn>
</MasterDetail>
)}
</div>
{/* Hub picker OUTSIDE the tab ternary: it lazy-mounts the first time
Skills is shown, then stays mounted (hidden) across Tools/MCP so
the docs-site iframe never reloads on a tab bounce. No scope key
on purpose — the picker fetches nothing; scope rides the
`profile` prop into each install call, and remounting on scope
change would reload the whole site for no data benefit. */}
{hubMounted && (
<EmbeddedHubPicker hidden={mode !== 'skills'} installedNames={installedSkillNames} profile={scopeProfile} />
)}
</div>
</div>