feat(ui): add @reui/onboarding-3 block and wire up the @reui registry

[forrestchang]

Tests the ReUI install flow end-to-end and lands the block it produced. Ref MUL-5628.

The flow works, but not out of the box — three repo-config gaps blocked it and the vendored output needed conformance fixes before it would compile here.

What the install did

pnpm dlx shadcn@latest add @reui/onboarding-3 from packages/ui, answering n to every overwrite prompt so local component customizations survive. It created 7 block files plus @reui/stepper, @reui/icon-stack, and use-file-upload, and skipped the 15 base components (avatar, button, field, combobox, select, …) that already exist here — none were modified.

Import rewriting worked cleanly: @/components/ui/button → @multica/ui/components/ui/button. The registry's internal @/app/(create)/components/icon-placeholder placeholder resolved into real lucide-react imports from our iconLibrary setting. @hugeicons/* is a genuine new dependency — it supplies the brand icons (Google, LinkedIn, Reddit, YouTube) for the discovery-source step that lucide doesn't ship.

Registry setup

• Registered the authenticated @reui registry in packages/ui/components.json.
• tsconfig paths for the bare components / lib aliases. The first install failed outright: Could not resolve the following aliases: components, lib. shadcn resolves components.json aliases through workspace package exports and tsconfig paths, and @multica/ui/components / @multica/ui/lib matched neither (we export ./components/ui/* and ./lib/utils, but nothing at those roots). This blocks any registry item targeting those roots, not just this block.
• Flipped rsc to true. With it false, shadcn strips "use client" on the way in. The first run silently landed onboarding.tsx and dot-sphere.tsx — both useState/useRef/canvas components — without the directive, which breaks them under the App Router. 44 of the 60 existing components in this package already carry it, so rsc: false was stale config.
• Exported ./components/reui/* and ./components/blocks/* so the installed files resolve for consumers.

Conformance fixes on the vendored output

The block does not compile against this repo's settings as shipped:

• noUncheckedIndexedAccess — 20 errors. Fixed with non-empty tuple types for the cycled sphere/step constants (readonly [T, ...T[]], so index 0 is a sound fallback), a guarded drop-file path, and a clamped unit index in formatBytes, which previously returned "1.5undefined" for sizes past YB.
• Select requires items — our local select.tsx deliberately makes it required ("Base UI renders the raw value unless Root receives an items label map"). The block passed a SelectValue function child instead.
• Type scale — apps/web/app/type-scale.test.ts flagged 15 off-scale sizes (text-xs, text-sm, text-2xl, text-[0.8125rem], …). Moved onto the role-named steps, dropping leading-* utilities that became redundant once the token supplied the same line-height.

Verification

• pnpm typecheck — 6/6 pass
• pnpm lint — 0 errors. 4 react-hooks/exhaustive-deps warnings remain inside the vendored stepper.tsx / use-file-upload.ts; left as upstream ships them so future re-installs stay a clean diff.
• pnpm test — web 22/22 (including the type-scale, text-contrast, and brand-variant guards), desktop 47/47, docs 4/4. The 8 @multica/core failures and the views sidebar-resize failure reproduce on a clean tree without this branch — pre-existing, unrelated.
• Rendered the block in jsdom to confirm the first step mounts. That was a throwaway check, not committed: the block is reference UI, and a test pinning vendored demo code would cost more than it protects.

Notes for review

• The block is not routed or imported by the product — it lands as reference UI under packages/ui/components/blocks/.
• That placement is the CLI default and keeps the install reproducible, but it sits against the packages/ui = "atomic UI components only" rule in CLAUDE.md. If you'd rather this live in packages/views/, say so and I'll move it — it would mean hand-relocating on every re-install.
• REUI_LICENSE_KEY is a Pro credential. It stays in packages/ui/.env.local (already covered by the .env* gitignore) or your shell; nothing secret is committed. Documented in the CLAUDE.md UI Rules section.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
multica-docs	Ready	Preview	Aug 2, 2026 5:53pm