perf(design-systems): speed up preview loading

[kuigoo]

Fixes #7079

Why

I hit this while browsing bundled design-system presets locally: on a slower daemon or filesystem, moving through the picker repeatedly replaced the preview pane with a loading state.

The picker promoted every transient hover/focus target immediately. Overlapping preview consumers could then repeat the same detail read, while bundled detail resolution still paid for a catalog scan. Besides making the picker feel slow, the existing read path also allowed a write-after-read race to surface stale editable content.

This PR keeps quick browsing cheap without weakening freshness after design-system mutations.

What users will see

• The picker waits for 120 ms of stable hover or keyboard focus before loading a preview.
• Crossing rows quickly no longer flashes a loader for every transient preset.
• Concurrent detail, preview, and showcase consumers share their reads.
• Bundled presets are reused during a browsing burst; editable systems are invalidated and fenced after writes.
• The visual layout and available controls are unchanged.

Under the same local production build and 300 ms simulated detail latency, rapidly scanning eight official presets reduced measured detail HTTP attempts from 8 to 2.

Surface area

• UI — new page / dialog / panel / menu item / setting / empty state in apps/web or apps/desktop (including Electron menu bar)
• Keyboard shortcut — new or changed
• CLI / env var — new od subcommand or flag, new tools-dev / tools-pack flag, or new OD_* env var
• API / contract — new /api/* endpoint, new SSE event, or changed shape in packages/contracts
• Extension point — new entry under skills/, design-systems/, design-templates/, or craft/, or change to the skills protocol
• i18n keys — added new translation keys (see TRANSLATIONS.md for the locale workflow)
• New top-level dependency — adding any new entry to the root package.json (dependencies or devDependencies); workspace-package package.json files are out of scope. Include a paragraph on what we get vs. what bytes we ship (see CONTRIBUTING.md → Code style)
• Default behavior change — changes what existing users experience without opting in (default model, default setting, file/SQLite schema, auto-network on startup, auto-install)
• None — internal refactor, docs, tests, or translation update only

Screenshots

The comparison visualizes the measured scan on the same captured UI with 300 ms simulated latency on GET /api/design-systems/:id. The request counters come from the proxy measurement; the row traversal is slowed so the behavior is readable.

Bug fix verification

• Test path: apps/web/tests/components/DesignSystemPicker.test.tsx
• Red on main: yes — both the hover and keyboard-focus intent specs fail because fetchDesignSystem is called before 119 ms elapses.
• Green on this branch: yes — the same focused run passes both specs.
• Additional regression coverage: apps/web/tests/design-system-preview-performance.test.ts covers coalescing, abort behavior, cache lifetime, fresh reads, write invalidation, and stale in-flight fencing; apps/daemon/tests/design-systems/detail-summary-fast-path.test.ts covers the single-ID bundled fast path.

Validation

• pnpm guard
• pnpm typecheck
• pnpm --filter @open-design/web build
• pnpm --filter @open-design/daemon build
• Targeted web Vitest suites: 168 passed
• Targeted daemon Vitest suites: 76 passed
• Focused red/green run: DesignSystemPicker.test.tsx -t 'waits for hover intent|applies preview intent' — 2 failed on main, 2 passed on this branch
• Local production smoke: web and daemon returned HTTP 200; canonical airbnb returned 200 while non-canonical Airbnb / AIRBNB returned 404
• Local performance comparison: eight rapidly traversed official presets, 300 ms simulated detail latency, 8 → 2 detail HTTP attempts

[lefarcen]

Thanks @kuigoo — the hover-intent + shared-read direction is clearly scoped from the PR body, especially the red/green verification around preview churn.

Since this PR is currently marked as a draft, we'll hold off on detailed review until it's ready for review.

💡 To drive this PR to merge hands-free, paste this to your AI coding agent (Claude Code / Codex / opencode / Cursor …):
Take over nexu-io/open-design#7080 until it merges — read https://raw.githubusercontent.com/nexu-io/looper/main/skills/pr-takeover/SKILL.md and follow it.

[lefarcen]

Thanks for marking this ready, @kuigoo. Since this changes user-facing preview behavior, I’m flagging it for a manual QA pass before merge — please hold off self-merging for now; we’ll loop QA in once it’s merge-ready.

[github-actions]

Visual regression review

Head: 374ec94 · Base: 56c634b

0 changed · 49 unchanged · 0 new without baseline · 0 failed

Unchanged cases

Case	Main	PR	Diff
visual-avatar-local-agent-list 0 px (0.00%)
visual-avatar-local-agent-list-panel 0 px (0.00%)
visual-avatar-menu 0 px (0.00%)
visual-avatar-menu-panel 0 px (0.00%)
visual-avatar-open-design-model-picker 0 px (0.00%)
visual-critical-settings 0 px (0.00%)
visual-critical-workspace 0 px (0.00%)
visual-critical-workspace-preview 0 px (0.00%)
visual-design-system-detail 0 px (0.00%)
visual-design-systems 0 px (0.00%)
visual-home 0 px (0.00%)
visual-home-catalog 0 px (0.00%)
visual-home-context-picker 0 px (0.00%)
visual-home-context-picker-popover 0 px (0.00%)
visual-home-plugin-filter 0 px (0.00%)
visual-home-plugin-use-staged 0 px (0.00%)
visual-home-plugin-use-with-query 0 px (0.00%)
visual-home-staged-attachment 0 px (0.00%)
visual-integrations 0 px (0.00%)
visual-integrations-mcp 0 px (0.00%)

Visual diff is advisory only and does not block merging.

[mrcfps]

@kuigoo thanks for the careful perf work here — this is a solid fix for the design-system picker thrash.

I reviewed the changed ranges across web + daemon: hover/focus intent debouncing in DesignSystemPicker, shared cancellable detail/preview/showcase reads with generation fencing and write invalidation in registry.ts, controlled detail handoff in the kit preview/modal, and the bundled single-ID summary fast path on the daemon detail route. The red/green picker intent specs and the coalescing/abort/stale-fence coverage match the behavior I traced, and I did not find correctness, safety, or maintainability issues that should block merge.

Nice measurement-backed win (8 → 2 detail attempts under the simulated scan) without changing the visible controls.

_{🔁 Powered by Looper · runner=reviewer · agent=opencode · An autonomous AI dev team for your GitHub repos.}