@usetheo/ui 0.13.0 → 0.13.2

package/CHANGELOG.md

@@ -1,12 +1,484 @@
 # Changelog
 
-All notable changes to `@usetheo/ui` are documented in this file.
+All notable changes to `@theokit/ui` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [0.17.0] - 2026-06-22
+
+### Added
+- `TokenUsageChart` gains `maxScale` (fix the y-axis maximum so multiple charts
+  share a scale — bars exceeding it clamp to 100% while the tooltip + a11y table
+  keep the true number) and `splitSeries` (render input vs output as adjacent
+  grouped bars instead of stacked). Plus pure `toUsageMetrics(points)` (totals +
+  peak per-period total) and `splitUsagePoints(points)` (transpose into parallel
+  `labels`/`input`/`output` series) helpers, exported from
+  `@theokit/ui/token-usage-chart` and the root barrel. (M5-7)
+- `toAgentStreamItems({ history, live }, { classifyTool? })` — a pure, order-aware
+  builder that merges completed conversation `UIMessage`s with live `AgentEvent`s
+  into the `AgentStreamItem[]` that `<AgentStream>` renders: history becomes
+  `message` items, live activity becomes `tool-call` items (status mapped from
+  `AgentEventStatus`), history-then-live. `classifyTool` customizes each
+  tool-call item per event (presentational fields only — `kind`/`id`/`status`
+  stay authoritative). Ships `mapAgentEventStatus` + the now-exported
+  `MessageStreamItem`/`ToolCallStreamItem` item types. (M5-6)
+- `useStickToBottom` — auto-scrolls a scroll container to the bottom as content
+  grows, but only while the user is pinned near the bottom (a `threshold` guard),
+  so it never yanks the view away while they read history. Streamed content is
+  detected with a `MutationObserver` (a scroll container's box does not resize as
+  content grows inside it), with a `ResizeObserver` on top for box-size changes
+  like images finishing load. Encapsulates the Radix
+  `[data-radix-scroll-area-viewport]` selector: attach `scrollRef` to a
+  `<ScrollArea>` and the hook resolves the real scrollable node internally.
+  Ships the pure `isNearBottom` helper too. Exported from `@theokit/ui/scroll-area`
+  and the root barrel. (M5-5)
+- `@theokit/ui/sdk-tools-adapters` — pure converters from `@theokit/sdk-tools`
+  tool results into theo-ui rich-primitive props: `adaptGitDiffResult`
+  (parses a unified diff into `DiffViewer` hunks), `adaptReadFileResult`
+  (`CodeBlock`), `adaptShellResult` (`TerminalPanel` lines), `adaptListDirResult`
+  (`DataTable` rows), `adaptApplyPatchResult` (`CreatedFilesCard` files), plus the
+  reusable `parseUnifiedDiff`. Each returns `null` on an error/unparseable result
+  so a tool card keeps its `ToolCallPart` fallback. The adapters are pure and
+  import nothing from `@theokit/sdk-tools` at runtime — consumers gain zero new
+  runtime dependency; a dev-only contract test imports the real factories and
+  runs their handlers to guard against result-shape drift. (M5-4)
+- `AgentToolRenderer` — an overridable tool-renderer registry for the chat
+  surface. A tool invocation is dispatched to a rich renderer (diff, terminal,
+  code, created-files, data-table) by a classification function, falling back to
+  `ToolCallPart` for anything unmapped. `<ChatMessage>` now accepts
+  `toolRenderers` (shallow-merged over the default) and `classifyTool` props
+  alongside the existing `partRenderers` / `dataRenderers`; `partRenderers.tool`
+  still takes priority. Exposed via `@theokit/ui/agent-tool-renderer` and the
+  root barrel: `AgentToolRenderer`, `defaultToolRegistry`, `defaultClassifyTool`,
+  `resolveToolRenderer`, and the `ToolRenderer` / `ToolRendererKind` /
+  `ToolRendererRegistry` / `ClassifyTool` types. `ToolCallPart` now lives in this
+  module (the fallback tool renderer) and is re-exported unchanged. Behavior
+  note: with the default registry, a tool whose name matches a known kind (e.g.
+  `git_diff`, `shell`, `read_file`) and whose state is `output-available` now
+  renders its rich surface instead of the generic `ToolCallPart`; unmapped tools
+  and every non-`output-available` state (streaming, awaiting-approval, error,
+  denied) are unchanged and keep using `ToolCallPart`. Pass `classifyTool` /
+  `toolRenderers` to override. (M5-3)
+
+### Changed
+- Public copy aligned to honest, ecosystem-fit framing across `README.md`,
+  `PITCH.md`, and `CLAUDE.md`: removed the unsubstantiated multi-framework
+  compatibility claims (Next.js / Vite / Remix / Astro / Tanstack "CI-verified")
+  and the false "peer-deps on React only" line. Reframed as a standard React +
+  Tailwind package that pairs with TheoKit or runs standalone, with the RSC
+  fix described as "Server-Component safe" rather than a marketed Next.js
+  target. Counts corrected to 153 components / 1,513 tests / 151 stories and the
+  stale `@theokit/ui@next` install snippets updated to `@theokit/ui` (now
+  published to `latest`).
+- README refreshed: component count corrected to 153, the v0.16.0 shadcn-v4
+  features documented (`data-slot`, `"use client"`/RSC, per-subpath types), and
+  the inaccurate "peer-deps on React only" line corrected (React is the only
+  required peer; Radix/CVA/cmdk/lucide ship as dependencies). (#13)
+
+### Deprecated
+
+### Removed
+- `PITCH.md` (landing-page marketing copy) removed from the repo. Public copy
+  now lives in `README.md` + the docs site; the Voice/Tone scope in `CLAUDE.md`
+  and `rules/public-copy.md` and the `public-copy-lint` hook were updated to
+  drop the `PITCH.md` reference.
+
+### Fixed
+- **Visual-regression gate tolerates cross-environment antialiasing.** The
+  Playwright `toHaveScreenshot` config used `threshold: 0.001` + `maxDiffPixels: 0`
+  (zero tolerance), so the 101 snapshots only ever matched the exact machine that
+  generated them — they failed in CI with 488-1882 antialiased pixels differing
+  (ratio ≤0.2%, no real regression). Raised to Playwright's antialiasing-robust
+  default `threshold: 0.2` with a `maxDiffPixels: 200` safety net that still
+  fails on a genuine visual regression (thousands+ of pixels). (Internal CI
+  hygiene.) (#15)
+- **Bundle-size gate scoped to deterministic artifacts.** `dist/components.css`
+  is a Tailwind v4 `@source`-scanned generated file whose exact byte size is
+  environment-sensitive (~470KB locally vs ~104KB on CI runners — both valid
+  output, differing by Tailwind's v3/v4 `@import` resolution across pnpm
+  layouts). It is removed from the byte-exact ±5% bundle gate (which now stays
+  focused on the deterministic shipped JS/dts bundles) and remains bounded by
+  the environment-robust `dogfood:precompiled-utilities` gate. (Internal CI
+  hygiene.) (#15)
+- **`shadcn add chat-message` no longer references a moved file.** M5-3 moved
+  `ToolCallPart` out of `chat-message/parts/` into the new `agent-tool-renderer`
+  component, but the `chat-message` registry descriptor still listed the old
+  `parts/tool-call-part.tsx` path — so the shadcn-compatible copy-paste path
+  was broken. `agent-tool-renderer` is now its own first-class registry item
+  (with story + test) and `chat-message` declares it as a `registryDependency`.
+  (#15)
+- **Agent-stream barrel-wiring test no longer flakes under suite load.** The
+  `await import("./index.js")` smoke test occasionally exceeded vitest's 5s
+  default (observed 5078ms) under worker-pool contention on cold runners. The
+  global `testTimeout` is raised to 20s — a hard ceiling that still fails a
+  genuinely hung test. (#15)
+- **`quality:gates` typecheck no longer blocks on dev-only playground demos.**
+  `playground/**` self-imports the package's own built subpaths
+  (`@theokit/ui/slide`, `/slide-deck`, `/slide/plugins/*`), which resolve to
+  `dist/*.d.ts` — absent when `pnpm typecheck` runs before `pnpm build`, so the
+  gate had failed (TS2307) on every release since 0.14.0. Playground is
+  non-shipped demo code exercised via Ladle, so it is excluded from the gate
+  typecheck instead of blocking releases. (Internal CI hygiene.) (#15)
+- **Release build no longer depends on a pnpm-specific `.bin` shim.**
+  `scripts/build-precompiled-css.ts` resolved the Tailwind v4 CLI at a nested
+  `@tailwindcss/cli/node_modules/.bin/tailwindcss` path that pnpm only
+  materializes in some hoist layouts — absent under CI's `--frozen-lockfile`
+  install, so `pnpm build` failed and the tagged release never published. Now
+  resolves the package's own declared `bin` entry from its `package.json` and
+  runs it via `node`, independent of any `.bin` shim. (#14)
+- **`@theokit/sdk-tools` file-link devDependency removed.** The M5-4 contract
+  test had pulled in `@theokit/sdk-tools: file:../theokit-sdk/...`, which does
+  not resolve under `pnpm install --frozen-lockfile` in CI (no sibling repo) and
+  blocked the publish. The 25 adapter unit tests validate against the documented
+  `{ ok: true, ... }` result shapes; the factory result contract is owned by the
+  SDK repo. (#14)
+- **Status indicators now render their colors under the v3 Tailwind preset.**
+  `StatusIndicator` uses `bg-status-online` / `-offline` / `-degraded` / `-info`,
+  but the `status` color palette was never added to `tailwind-preset.ts` (only
+  the v4 `@theme` declared `--color-status-*`), so those utilities resolved to
+  transparent in the v3 build path (e.g. the Ladle dev server) — the dots were
+  invisible. Added the `status` palette to the preset, mapped to the existing
+  `--status-*` tokens. The npm/v4 build was already correct. Registry
+  `tailwind-preset.json` regenerated.
+- **npm publish CI restored.** The `release.yml` (and `deploy-ladle.yml`) GitHub
+  Actions workflow failed on every tagged release since v0.14.1 because
+  `pnpm/action-setup@v4` pinned `version: 9.15.0`, conflicting with
+  `package.json`'s `packageManager: pnpm@10.32.1`
+  (`ERR_PNPM_BAD_PM_VERSION`). Removed the hardcoded version so the package
+  actually publishes to npm again. (#13)
+
+### Security
+
+## [0.17.0] - 2026-06-22
+
+### Added
+- `TokenUsageChart` gains `maxScale` (fix the y-axis maximum so multiple charts
+  share a scale — bars exceeding it clamp to 100% while the tooltip + a11y table
+  keep the true number) and `splitSeries` (render input vs output as adjacent
+  grouped bars instead of stacked). Plus pure `toUsageMetrics(points)` (totals +
+  peak per-period total) and `splitUsagePoints(points)` (transpose into parallel
+  `labels`/`input`/`output` series) helpers, exported from
+  `@theokit/ui/token-usage-chart` and the root barrel. (M5-7)
+- `toAgentStreamItems({ history, live }, { classifyTool? })` — a pure, order-aware
+  builder that merges completed conversation `UIMessage`s with live `AgentEvent`s
+  into the `AgentStreamItem[]` that `<AgentStream>` renders: history becomes
+  `message` items, live activity becomes `tool-call` items (status mapped from
+  `AgentEventStatus`), history-then-live. `classifyTool` customizes each
+  tool-call item per event (presentational fields only — `kind`/`id`/`status`
+  stay authoritative). Ships `mapAgentEventStatus` + the now-exported
+  `MessageStreamItem`/`ToolCallStreamItem` item types. (M5-6)
+- `useStickToBottom` — auto-scrolls a scroll container to the bottom as content
+  grows, but only while the user is pinned near the bottom (a `threshold` guard),
+  so it never yanks the view away while they read history. Streamed content is
+  detected with a `MutationObserver` (a scroll container's box does not resize as
+  content grows inside it), with a `ResizeObserver` on top for box-size changes
+  like images finishing load. Encapsulates the Radix
+  `[data-radix-scroll-area-viewport]` selector: attach `scrollRef` to a
+  `<ScrollArea>` and the hook resolves the real scrollable node internally.
+  Ships the pure `isNearBottom` helper too. Exported from `@theokit/ui/scroll-area`
+  and the root barrel. (M5-5)
+- `@theokit/ui/sdk-tools-adapters` — pure converters from `@theokit/sdk-tools`
+  tool results into theo-ui rich-primitive props: `adaptGitDiffResult`
+  (parses a unified diff into `DiffViewer` hunks), `adaptReadFileResult`
+  (`CodeBlock`), `adaptShellResult` (`TerminalPanel` lines), `adaptListDirResult`
+  (`DataTable` rows), `adaptApplyPatchResult` (`CreatedFilesCard` files), plus the
+  reusable `parseUnifiedDiff`. Each returns `null` on an error/unparseable result
+  so a tool card keeps its `ToolCallPart` fallback. The adapters are pure and
+  import nothing from `@theokit/sdk-tools` at runtime — consumers gain zero new
+  runtime dependency; a dev-only contract test imports the real factories and
+  runs their handlers to guard against result-shape drift. (M5-4)
+- `AgentToolRenderer` — an overridable tool-renderer registry for the chat
+  surface. A tool invocation is dispatched to a rich renderer (diff, terminal,
+  code, created-files, data-table) by a classification function, falling back to
+  `ToolCallPart` for anything unmapped. `<ChatMessage>` now accepts
+  `toolRenderers` (shallow-merged over the default) and `classifyTool` props
+  alongside the existing `partRenderers` / `dataRenderers`; `partRenderers.tool`
+  still takes priority. Exposed via `@theokit/ui/agent-tool-renderer` and the
+  root barrel: `AgentToolRenderer`, `defaultToolRegistry`, `defaultClassifyTool`,
+  `resolveToolRenderer`, and the `ToolRenderer` / `ToolRendererKind` /
+  `ToolRendererRegistry` / `ClassifyTool` types. `ToolCallPart` now lives in this
+  module (the fallback tool renderer) and is re-exported unchanged. Behavior
+  note: with the default registry, a tool whose name matches a known kind (e.g.
+  `git_diff`, `shell`, `read_file`) and whose state is `output-available` now
+  renders its rich surface instead of the generic `ToolCallPart`; unmapped tools
+  and every non-`output-available` state (streaming, awaiting-approval, error,
+  denied) are unchanged and keep using `ToolCallPart`. Pass `classifyTool` /
+  `toolRenderers` to override. (M5-3)
+
+### Changed
+- Public copy aligned to honest, ecosystem-fit framing across `README.md`,
+  `PITCH.md`, and `CLAUDE.md`: removed the unsubstantiated multi-framework
+  compatibility claims (Next.js / Vite / Remix / Astro / Tanstack "CI-verified")
+  and the false "peer-deps on React only" line. Reframed as a standard React +
+  Tailwind package that pairs with TheoKit or runs standalone, with the RSC
+  fix described as "Server-Component safe" rather than a marketed Next.js
+  target. Counts corrected to 153 components / 1,513 tests / 151 stories and the
+  stale `@theokit/ui@next` install snippets updated to `@theokit/ui` (now
+  published to `latest`).
+- README refreshed: component count corrected to 153, the v0.16.0 shadcn-v4
+  features documented (`data-slot`, `"use client"`/RSC, per-subpath types), and
+  the inaccurate "peer-deps on React only" line corrected (React is the only
+  required peer; Radix/CVA/cmdk/lucide ship as dependencies). (#13)
+
+### Deprecated
+
+### Removed
+- `PITCH.md` (landing-page marketing copy) removed from the repo. Public copy
+  now lives in `README.md` + the docs site; the Voice/Tone scope in `CLAUDE.md`
+  and `rules/public-copy.md` and the `public-copy-lint` hook were updated to
+  drop the `PITCH.md` reference.
+
+### Fixed
+- **Status indicators now render their colors under the v3 Tailwind preset.**
+  `StatusIndicator` uses `bg-status-online` / `-offline` / `-degraded` / `-info`,
+  but the `status` color palette was never added to `tailwind-preset.ts` (only
+  the v4 `@theme` declared `--color-status-*`), so those utilities resolved to
+  transparent in the v3 build path (e.g. the Ladle dev server) — the dots were
+  invisible. Added the `status` palette to the preset, mapped to the existing
+  `--status-*` tokens. The npm/v4 build was already correct. Registry
+  `tailwind-preset.json` regenerated.
+- **npm publish CI restored.** The `release.yml` (and `deploy-ladle.yml`) GitHub
+  Actions workflow failed on every tagged release since v0.14.1 because
+  `pnpm/action-setup@v4` pinned `version: 9.15.0`, conflicting with
+  `package.json`'s `packageManager: pnpm@10.32.1`
+  (`ERR_PNPM_BAD_PM_VERSION`). Removed the hardcoded version so the package
+  actually publishes to npm again. (#13)
+
+### Security
+
+## [0.16.0] - 2026-06-18
+
+### Added
+- **`data-slot` attribute on every component (shadcn v4 convention).** All 135
+  components now emit `data-slot="<name>"` on their root element (compound
+  sub-parts carry `data-slot="<name>-<part>"`), so consumers can target and
+  override styles via stable attribute selectors instead of relying on Tailwind
+  class order. New quality gate `validateDataSlot` enforces presence on every
+  component. (community-standard-componentization, T2.1)
+- **Per-subpath TypeScript declarations.** Importing `@theokit/ui/button` now
+  resolves an isolated `Button`-only `.d.ts` instead of the entire barrel's
+  type surface, so type-checking a single subpath no longer loads all 135
+  components' types. Declarations are emitted by `tsc -p tsconfig.dts.json`
+  (tsup's bundler OOMs at 130+ entries). (community-standard-componentization, T3.1)
+- **`data-variant` / `data-size` on cva components (shadcn v4).** The 9
+  variant-driven components (Button, Badge, Avatar, Select, Switch, Input,
+  Textarea, Checkbox, Toast) now emit `data-variant`/`data-size` alongside
+  `data-slot`, so consumers can style by attribute (e.g.
+  `[data-slot=button][data-variant=secondary]`). The `*Variants` helpers remain
+  exported for class reuse. (community-standard-componentization, T5.1)
+
+- `"use client"` directive added to the 45 client component source files
+  (anything using React hooks/context), matching shadcn/ui conventions.
+- Post-build step `scripts/inject-use-client.ts` re-injects the directive into
+  the output entry shims + component chunks (esbuild strips it during
+  `splitting`). Wired into the `build` script.
+- New quality gate `validateUseClientDirective` — fails the build if a client
+  component ships without the directive in `dist/`. (T1.2)
+
+
+### Changed
+- Tailwind v4 devDep alignment + v3-legacy removal (Phase 4) is deferred to a
+  dedicated `tailwind-v4-migration` cycle — see ADR 0001. The shipped
+  `dist/components.css` is already built with Tailwind v4; the deferred work is
+  the dev/test version label + the v3-legacy compat artifacts.
+- Bundle baseline updated for the new per-subpath declaration strategy: the
+  barrel `dist/index.d.ts` is now a thin re-export (15 KB vs the old 206 KB
+  inlined monolith) because per-component types live in their own files under
+  `dist/components/`. Engine `.d.ts` moved from `dist/<engine>/` to
+  `dist/components/.../`. (community-standard-componentization, T3.1)
+- Bundle baseline for `dist/components.css` corrected to the full `@source`
+  scan size (the prior baseline was set in an environment where Tailwind v4's
+  `@source` glob under-scanned the library tree — a known pnpm-symlink
+  fragility documented in `scripts/build-precompiled-css.ts`). The
+  `data-slot` / `"use client"` work is bundle-neutral — verified empirically
+  (removing `data-slot` leaves `components.css` byte-identical). `dist/slide`
+  and `dist/slide-deck` grew by a few bytes from the directive + data-slot.
+  NOTE: `components.css` size is `@source`-environment-sensitive; CI should
+  confirm the full-scan value reproduces in its environment.
+
+
+### Fixed
+- **`@theokit/ui` now works in Next.js App Router (React Server Components).**
+  The `"use client"` directive is preserved in the published build so importing
+  a client component (anything using hooks) no longer throws *"useState only
+  works in a Client Component"*. Previously esbuild stripped the directive under
+  code-splitting, so every npm-installed client component was broken in RSC
+  projects. Both consumption paths are fixed — subpath (`@theokit/ui/agent-event`)
+  and barrel (`@theokit/ui`). (community-standard-componentization, T1.1)
+
+## [0.15.0] - 2026-06-16
+
+### Added
+- **Prompt composites — "ask the user" cards for agent surfaces, modeled on
+  Claude Code's question UX.** Four self-contained composites, each rendering
+  one question at a time (sequencing across questions is the consumer's
+  responsibility — there is no built-in flow orchestrator):
+  - **`ChoicePrompt`** — single-select (radio). Header chip, options with
+    label + description, `1`..`9` number-key shortcuts (terminal-style
+    selection), injectable free-text "Other" option, and a side-by-side preview
+    pane when options carry preview content. Emits `onConfirm` with the chosen
+    value (plus the typed Other text when relevant).
+  - **`MultiSelectPrompt`** — multi-select (checkbox). Same surface as
+    `ChoicePrompt` with number-key toggles, an Other row, a `minSelected` gate,
+    and a stacked preview pane for every selected option. Emits `onConfirm`
+    with the value array.
+  - **`TextPrompt`** — free-text. Single-line `Input` or multi-line `Textarea`
+    with an optional `required` gate. Emits `onConfirm` with the typed text.
+  - **`ConfirmPrompt`** — binary yes/no. Optional `destructive` variant that
+    tones the confirm action red and exposes the card as an `alertdialog`.
+  Controlled or uncontrolled. Ships a `prompt` registry lib item carrying the
+  shared `PromptOption` type + helpers consumed by the choice composites.
+
+## [0.14.4] - 2026-06-13
+
+### Added
+
+- `pnpm dev:pack` script for local cross-repo consumption — generates tarball at `dist/theokit-ui-{version}.tgz` that installs without dual-React symlink issues. Documented in CONTRIBUTING.md.
+
+## [0.14.3] - 2026-06-09
+
+**Patch — PageShell content spacing standardization.**
+
+### Fixed
+- **`PageShell` content slot now renders direct children with `flex flex-col gap-6`.**
+  Previously the content `<div>` had no internal spacing, so pages with 2+
+  top-level children (e.g. dashboard `/memory` landing with 5 sibling
+  sections: KPI strip + trend grid + getting-started card + Explore
+  heading + Explore grid) rendered them flush against each other. The new
+  wrapper matches the outer `<main className="flex flex-col gap-6">` gap,
+  so spacing is uniform across the page. Pages that already wrap content
+  in a single grid or div are unaffected — `gap-6` only applies between
+  sibling elements. Equivalent to manually wrapping every page's content
+  in `<div className="flex flex-col gap-6">`, but enforced at the
+  composite level so every consumer benefits without per-page churn.
+
+## [0.14.2] - 2026-06-09
+
+**Patch — build-pipeline correctness. Bundles the 0.14.1 color migration
+plus two FAANG-grade fixes that were required to ship a clean build to
+npm. 0.14.1 was tagged in git but never published to the npm registry;
+0.14.2 is the first published artifact carrying the violet unification.**
+
+### Added
+- **`src/lib/env.ts` — typed environment helpers (`isDev()`, `isProd()`).**
+  Centralizes `process.env.NODE_ENV` reads through a single typed accessor
+  that uses `globalThis.process?.env?.NODE_ENV`. Works in browser via
+  bundler `define` injection (Vite/Webpack/esbuild), in Node (SSR/tests),
+  and defensively in browser-without-bundler-injection (returns
+  `isDev() === true` to err on the side of more diagnostics). This is the
+  same pattern React, Radix, and Stripe Elements use — funnel every
+  `NODE_ENV` read through a typed helper so consumers' bundlers can
+  dead-code-eliminate dev-only branches in their production build.
+
+### Changed
+- **Six components migrated from raw `process.env.NODE_ENV` to `isDev()`.**
+  `theme-provider`, `status-dot`, `timestamp`, `env-var-editor`,
+  `thinking-level-selector`, `build-log-stream`. No behavior change in
+  consumer production builds — only a typecheck-cleanliness and
+  build-stability improvement. The previous direct `process.env` reads
+  triggered TypeScript `TS2591` failures unless `@types/node` was listed
+  in `tsconfig.json#compilerOptions.types`. Adding `"node"` there is the
+  workaround we explicitly rejected: it pollutes the ambient global
+  namespace of a UI library with Node-only APIs (`Buffer`, `fs`, `path`,
+  `Stream`) and surfaces them in author autocomplete inside React
+  components. The typed helper is the right pattern.
+
+### Fixed
+- **`src/vite-plugin.test.ts:76` — implicit `any` on `.map` callback parameter.**
+  Annotated as `(c: unknown[])`. Pre-existing TypeScript strictness
+  violation unrelated to the violet migration, but the typecheck job in
+  `prepublishOnly`'s `quality:gates` must be clean for publish to proceed.
+
+## [0.14.1] - 2026-06-09 — NOT PUBLISHED
+
+Tagged in git as `v0.14.1` but never published to the npm registry. The
+build pipeline surfaced two pre-existing TypeScript errors (six raw
+`process.env.NODE_ENV` reads + one implicit-`any` test assertion) that
+needed to be fixed before publish. The color migration carried out by
+this commit is bundled into `0.14.2` (see above) along with those fixes.
+
+**Patch (token value change only — full backward-compat preserved).**
+
+### Changed
+- **Theo violet primary unified to `#A855F7` electric violet**. The Violet Forge theme's `--primary` (and matching `--ring`) moved from `#7C3AED` (`oklch(0.542 0.245 293)`) to `#A855F7` (`oklch(0.628 0.225 296)`) — same family, higher chroma at higher lightness, calmer execution without cyberpunk halos. Decision based on cross-surface unification (marketing + cloud/dashboard share one cor): the new value reads as production-grade premium and works consistently across light + dark surfaces. Burnt sienna accent `#C96442` is preserved (warmth complement unchanged). `--primary-deep` and `--primary-glow` continue to derive algorithmically via OKLCH relative-color syntax — no manual override needed. Files touched: `src/styles/tokens.css` (light + dark `--primary` and `--ring`), `src/themes/violet-forge.ts` (light + dark `primary` and `ring`), `src/components/primitives/slide/themes/violet-forge.css` (`--theo-slide-accent`), `src/components/primitives/whiteboard/whiteboard.stories.tsx` (stroke demo), `src/themes/color.ts` (JSDoc examples refreshed). Tests in `src/themes/color.test.ts` intentionally left unchanged — they test the `hex()` function with `#7C3AED` as a static example, decoupled from brand color choice. Consumers (theo-website, theo-cloud/dashboard, theokit framework) pick up the new color automatically on next install/rebuild via `@theokit/ui/preset.css`.
+
+## [0.14.0] - 2026-06-03
+
+**Minor (additive — full backward-compat preserved via legacy helpers).**
+
+Community best practices alignment cohort. Migrates `@theokit/ui` from HSL split to OKLCH as the canonical color format, introduces status semantic tokens, two new composites (StatusIndicator + MetricCard), a lint rule banning literal Tailwind color classes in components, `prefers-color-scheme` auto-detect, forced-colors (Windows High Contrast Mode) support, and a Playwright visual regression baseline. All 6 ADRs (0004-0009), full migration guide, and 5 new test files shipped. WCAG AA preserved across 10 themes × 2 modes. `classic-paper` rebalanced to visibly warm cream (per Vintage Paper + Anthropic Claude UI references) for reduced vision fatigue on long agent sessions.
+
+See [docs/migration/hsl-to-oklch.md](docs/migration/hsl-to-oklch.md) for the full upgrade guide.
+
+### Added — Community Best Practices Alignment (2026-06-03)
+
+- **Status semantic token group** (ADR-0007). New `ColorScale` keys
+  `--status-online`, `--status-offline`, `--status-degraded`, `--status-info`
+  plus foreground companions — 8 keys × 11 themes. Separates operational state
+  (gateway alive/dead/slow/info) from action-result (success/destructive/warning/info).
+- **`StatusIndicator` composite** consuming the status group. API:
+  `<StatusIndicator status="online" label="Connected" pulse?>`.
+- **`MetricCard` composite** for dashboard tiles. API:
+  `<MetricCard title value delta={{value,trend}} hint? icon? invertTrend? />`.
+  `invertTrend` flips trend semantics for cost/churn/latency metrics (EC-17).
+- **`respectSystemMode` prop** on `<ThemeProvider>` (default `true`, ADR-0009).
+  Reads `(prefers-color-scheme: dark)` on hydration and subscribes to OS changes.
+  User-driven `setMode()` overrides the system signal. `matchMedia` listener
+  cleanup on unmount (EC-12).
+- **`forced-colors` media query** in `tokens.css` (ADR-0008). Maps semantic
+  tokens to system colors (Canvas, CanvasText, Highlight, ...) for Windows
+  High Contrast Mode. WCAG 2.2 SC 1.4.1/1.4.3.
+- **Container query sizes** (`--container-3xs` through `--container-7xl`)
+  declared in `tokens-v4.css` for Tailwind v4 `@container` variants.
+- **Algorithmic tonal derivations** for `--primary-deep`, `--primary-glow`,
+  `--accent-deep` via OKLCH relative-color syntax with `max()`/`min()`
+  anti-overflow clamps (ADR-0006, EC-7).
+- **Lint rule scanner** `scripts/lib/literal-color-scanner.ts` blocks literal
+  Tailwind color classes in `src/components/**/*.tsx`. Wired into
+  `pnpm quality:structure` (ADR-0004). 14 unit tests.
+- **Valibot theme schema** `src/themes/schema.ts` (D5 revised — Valibot
+  ~1.5KB gzipped vs Zod ~12KB).
+- **OKLCH `color-value-pattern.ts`** extracted from `theme-provider.tsx`.
+  Accepts plain OKLCH, relative-color syntax (EC-5), HSL split, hex, var().
+
+### Changed — Community Best Practices Alignment (2026-06-03)
+
+- **All 11 built-in themes migrated from HSL split to OKLCH** (ADR-0005).
+  638 values converted via `scripts/migrate-themes-to-oklch.ts`. Round-trip
+  delta ~0.001 L per value (visually equivalent, < 0.5% pixel diff).
+  Legacy HSL split format still accepted by the runtime validator.
+- **`tokens-v4.css` aliases** drop `hsl()` wrapper —
+  `--color-primary: var(--primary)` direct.
+- **`tokens.css` shadows + texture utilities** use
+  `color-mix(in oklch, var(--x) N%, transparent)` for alpha composition.
+- **`hex()` and `rgb()` helpers** now return `oklch(L C H)` strings (T2.6).
+- **`gateway-status-indicator`, `run-status-pill`, `update-banner`,
+  `stability-bundle-viewer`** swept of 12 literal Tailwind color classes
+  → semantic tokens. Closes hidden theme-switching bug.
+- **`primary-deep` / `primary-glow` / `accent-deep`** are now `optional`
+  in `ColorScale`. CSS auto-derives via `oklch(from ...)` when omitted.
+- **`validateThemeContrast`** accepts both HSL split and OKLCH input.
+
+### Deprecated — Community Best Practices Alignment
+
+- **`hexToHsl(input)`** and **`rgbToHslLegacy(r, g, b)`** — use `hex()` /
+  `rgb()` (OKLCH output) instead. Removal scheduled for next major.
+
 ## [0.13.0] - 2026-05-29
 
 **Minor (additive only — zero breaking changes).**
@@ -14,7 +486,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Seven new components shipped as Phase 1 of the `theokit-ui-parity` plan
 (`.claude/knowledge-base/plans/theokit-ui-parity-plan.md` v1.1). All seven
 mirror OpenClaw Control UI patterns the framework lacked, designed to be
-composable into any theokit app via `@usetheo/ui` barrel.
+composable into any theokit app via `@theokit/ui` barrel.
 
 ### Added — Phase 2 component
 
@@ -105,7 +577,7 @@ composable into any theokit app via `@usetheo/ui` barrel.
 
 **Stable release — promoted from `0.12.0-next.0` after dogfood validation + cross-repo contract gates landed.**
 
-First `@usetheo/ui` release on the npm `latest` tag without a `-next.*` pre-release suffix. Content is the union of everything shipped in `0.12.0-next.0` (2026-05-25) plus the additions below from `[Unreleased]` consolidation. **Zero breaking changes vs `0.12.0-next.0`** — consumers on `^0.12.0-next.0` upgrade transparently.
+First `@theokit/ui` release on the npm `latest` tag without a `-next.*` pre-release suffix. Content is the union of everything shipped in `0.12.0-next.0` (2026-05-25) plus the additions below from `[Unreleased]` consolidation. **Zero breaking changes vs `0.12.0-next.0`** — consumers on `^0.12.0-next.0` upgrade transparently.
 
 ### Added (dogfood-fixes-and-coverage-expansion T4.1, 2026-05-28)
 
@@ -127,14 +599,14 @@ that complement the existing `llms.txt`: a structured visual spec
 ### Added
 
 - **`DESIGN.md` at repo root (NEW)** — plain-text design system spec
-  for LLM assistants generating UI against `@usetheo/ui`. Follows the
+  for LLM assistants generating UI against `@theokit/ui`. Follows the
   awesome-design-md 9-section canonical structure (Visual Theme &
   Atmosphere · Color Palette & Roles · Typography Rules · Layout
   Principles · Depth & Elevation · Component Stylings · Responsive
   Behavior · Do's and Don'ts · Agent Prompt Guide). Tokens mirror
   `src/styles/tokens.css` and `src/themes/violet-forge.ts`. Shipped
   via `package.json > files` alongside `llms.txt` and `CHANGELOG.md`
-  so consumers see the visual spec at `node_modules/@usetheo/ui/DESIGN.md`.
+  so consumers see the visual spec at `node_modules/@theokit/ui/DESIGN.md`.
   Reference research lives at
   `.claude/knowledge-base/reference/design-md-convention.md`.
 - **`skills/theo-ui/` companion agent skill (NEW)** — library-aware
@@ -176,7 +648,7 @@ Brief: `theo/docs/handoff/2026-05-25-theo-ui-cloud-dashboard-brief-5.md`
   `Object.assign`: `Trigger`, `Portal`, `Content`, `Item`,
   `CheckboxItem`, `RadioItem`, `Label`, `Separator`, `Shortcut`,
   `Group`, `Sub`, `SubTrigger`, `SubContent`, `RadioGroup`. Styled
-  with `@usetheo/ui` design tokens. Consolidates 5 prior direct-
+  with `@theokit/ui` design tokens. Consolidates 5 prior direct-
   Radix usages (`model-selector`, `intent-selector`, `agent-profile`,
   `theme-switcher`, `theo-code-shell`) under a single styled
   wrapper. 6 unit tests + 5 Ladle stories. SSR-safe.
@@ -250,7 +722,7 @@ new primitives yet — pure version bump):
 
 | Metric | 0.10.0-next.0 | 0.11.0-next.0 | Δ |
 |---|---|---|---|
-| `@usetheo/ui` chunk | 10.96 KB brotli | 10.98 KB brotli | **+0.02 KB (+0.2%)** |
+| `@theokit/ui` chunk | 10.96 KB brotli | 10.98 KB brotli | **+0.02 KB (+0.2%)** |
 | TOTAL initial JS | 134.68 KB brotli | 135.56 KB brotli | +0.88 KB (+0.6%) |
 
 Per-chunk cap (18 KB): passes with 7.02 KB headroom.
@@ -273,8 +745,8 @@ defect surfaced by the TheoCloud dashboard bundle audit
 exports declared in `package.json#exports` (`./alert`, `./button`,
 `./table`, …) were **cosmetic** — each pointed at the same
 `./dist/index.js` (the 417 KB barrel). `import { Alert } from
-"@usetheo/ui/alert"` resolved byte-identical to
-`import { Alert } from "@usetheo/ui"`, and barrel tree-shaking
+"@theokit/ui/alert"` resolved byte-identical to
+`import { Alert } from "@theokit/ui"`, and barrel tree-shaking
 failed in consumers because of `forwardRef` side-effect bailouts,
 `Object.assign` compound components, and `sideEffects: ["**/*.css"]`
 conservatism. TheoCloud measured **0 KB dropped** from the 240 KB
@@ -282,7 +754,7 @@ minified barrel regardless of how few exports were used.
 
 This release extends the per-component dist pattern that already
 worked for `whiteboard` / `slide` / `slide-deck` to every primitive
-and composite. The barrel `import { X } from "@usetheo/ui"` is
+and composite. The barrel `import { X } from "@theokit/ui"` is
 preserved unchanged (additive migration shape, same as `@mui/material`).
 
 Plan: `.claude/knowledge-base/plans/subpath-tree-shaking-plan.md`
@@ -308,7 +780,7 @@ Brief: `theo/docs/handoff/2026-05-24-theo-ui-subpath-tree-shaking-brief-4.md`
   `NODE_OPTIONS=--max-old-space-size=8192` (the flag does not
   propagate to workers). Per-component subpaths resolve their `types`
   field at the barrel `dist/index.d.ts` — TypeScript still finds
-  `Alert`/`AlertProps` from `import { Alert } from "@usetheo/ui/alert"`.
+  `Alert`/`AlertProps` from `import { Alert } from "@theokit/ui/alert"`.
   Trade-off: consumers' typecheck pulls the full type graph regardless
   of subpath, but the JS dist (where tree-shaking matters) is
   per-component and small.
@@ -350,7 +822,7 @@ chunks. **Consumer-side bundle delta against TheoCloud dashboard
 
 | Metric | 0.9.0-next.0 | 0.10.0-next.0 | Δ |
 |---|---|---|---|
-| `@usetheo/ui` chunk | 36.96 KB brotli | 10.96 KB brotli | **−26.00 KB (−70.3%)** |
+| `@theokit/ui` chunk | 36.96 KB brotli | 10.96 KB brotli | **−26.00 KB (−70.3%)** |
 | TOTAL initial JS | 176.27 KB brotli | 134.68 KB brotli | −41.59 KB (−23.6%) |
 
 Per-chunk cap (50 KB): passes with 39 KB headroom (was 13 KB).
@@ -369,16 +841,16 @@ Evidence file:
 ### Migration (consumer-side, opt-in)
 
 ```diff
-- import { Card, Button, Alert } from "@usetheo/ui";
-+ import { Card } from "@usetheo/ui/card";
-+ import { Button } from "@usetheo/ui/button";
-+ import { Alert } from "@usetheo/ui/alert";
+- import { Card, Button, Alert } from "@theokit/ui";
++ import { Card } from "@theokit/ui/card";
++ import { Button } from "@theokit/ui/button";
++ import { Alert } from "@theokit/ui/alert";
 ```
 
 The barrel import keeps working — migration is gradual, file by
 file. CSS, themes, and isolated engines stay barrel-imported:
-`import { ThemeProvider, violetForge } from "@usetheo/ui"`,
-`import "@usetheo/ui/styles.css"`.
+`import { ThemeProvider, violetForge } from "@theokit/ui"`,
+`import "@theokit/ui/styles.css"`.
 
 ## [0.9.0-next.0] - 2026-05-23
 
@@ -530,7 +1002,7 @@ Consumer brief: `theo/docs/handoff/2026-05-23-theo-ui-cloud-dashboard-gaps-brief
 - **Taxonomy gate** classified ConfirmDialog + CodeBlock as composites
   (D2 in the plan). Brief #2 listed all 8 as primitives, but the
   validate-quality-gates.ts script is hard-fail for any
-  `primitives/` file that imports another `@usetheo/ui` component.
+  `primitives/` file that imports another `@theokit/ui` component.
 - **Timestamp uses native `title` HTML attribute** (D3) instead of
   the `<Tooltip>` component, to keep the file a true primitive
   without sibling-primitive imports.
@@ -610,7 +1082,7 @@ Consumer brief: `theo/docs/handoff/2026-05-23-theo-ui-cloud-dashboard-gaps-brief
 - **Taxonomy invariant preserved.** `UsageMeter → Progress` and
   `AccountMenu → Avatar + PlanBadge` use relative-path imports
   (`../{slug}/index.js`), not barrel imports, so primitives still have
-  zero `@usetheo/ui` cross-dependencies per the structural gate.
+  zero `@theokit/ui` cross-dependencies per the structural gate.
 - **Bundle delta.** `dist/index.js` grows by ~6 KB (4 primitives + types
   + small imports). Within the ±5% baseline tolerance (rebaselined).
 - **Subpath exports.** `package.json#exports` gains `./usage-meter`,
@@ -688,7 +1160,7 @@ every `<button>` rendered by `Sidebar.Item`, `QuickActionChips`,
 `ChatComposer`, `ContextWindowBar`, `ToolCallCard`, `AgentProfile`,
 `CommandPalette`, etc. was showing the default arrow cursor instead of
 the pointing hand. Visual regression observed in TheoKit
-`examples/full-stack-agent` against `@usetheo/ui@0.6.1-next.0`.
+`examples/full-stack-agent` against `@theokit/ui@0.6.1-next.0`.
 
 ### Fixed
 
@@ -713,7 +1185,7 @@ the pointing hand. Visual regression observed in TheoKit
      accessibility convention. (#TBD)
 
 The fix is opt-in by consumer choice — they imported
-`@usetheo/ui/styles.css`. Tailwind v4's global preflight remains
+`@theokit/ui/styles.css`. Tailwind v4's global preflight remains
 untouched; only this stylesheet's `@layer base` adds the rule. (#TBD)
 
 ### Notes
@@ -726,7 +1198,7 @@ untouched; only this stylesheet's `@layer base` adds the rule. (#TBD)
   #    pointing-hand icon (not the default arrow).
   #
   # CSS grep test:
-  grep -c "button:not(:disabled)" node_modules/@usetheo/ui/dist/styles.css
+  grep -c "button:not(:disabled)" node_modules/@theokit/ui/dist/styles.css
   # MUST return >= 1 (pre-fix: 0)
   ```
 
@@ -741,12 +1213,12 @@ the entire library rendered flat under pnpm.
 
 - **pnpm symlink + Tailwind v4 `@source` bug** — Tailwind v4's
   `tinyglobby`-based scanner does **not** follow symbolic links. Under a
-  pnpm install, `node_modules/@usetheo/ui` is a symlink to a deep
-  `node_modules/.pnpm/@usetheo+ui@…/node_modules/@usetheo/ui` directory,
+  pnpm install, `node_modules/@theokit/ui` is a symlink to a deep
+  `node_modules/.pnpm/@theokit+ui@…/node_modules/@theokit/ui` directory,
   and the consumer-side pattern
-  `@source "node_modules/@usetheo/ui/dist/**/*.{js,mjs,cjs}"` (the one
+  `@source "node_modules/@theokit/ui/dist/**/*.{js,mjs,cjs}"` (the one
   the `vite-plugin` previously emitted via the
-  `virtual:@usetheo/ui/library-sources.css` virtual module) expanded to
+  `virtual:@theokit/ui/library-sources.css` virtual module) expanded to
   **zero** matches. Every `hover:bg-muted`, `hover:text-foreground`,
   `data-[state=active]:…` variant the library's 79 primitives + 41
   composites use was therefore never emitted into the consumer's CSS,
@@ -768,7 +1240,7 @@ the entire library rendered flat under pnpm.
   gzipped. This is the canonical Tailwind v4 library pattern used by
   Radix UI Themes, shadcn/ui pre-compiled, and Mantine v7. (#TBD)
 - **`dist/styles.css` chains `@import "./components.css"`** at the end,
-  so a single `@import "@usetheo/ui/styles.css"` in the consumer's CSS
+  so a single `@import "@theokit/ui/styles.css"` in the consumer's CSS
   now transitively pulls in every utility the library uses — zero
   filesystem scanning required. Consumer-side `@theme` overrides still
   win via the runtime CSS-var cascade (every utility resolves
@@ -785,9 +1257,9 @@ the entire library rendered flat under pnpm.
 
 ### Changed
 
-- **`@usetheo/ui/vite-plugin` virtual module** — the
-  `virtual:@usetheo/ui/library-sources.css` module no longer emits the
-  broken `@source "node_modules/@usetheo/ui/..."` default globs. It is
+- **`@theokit/ui/vite-plugin` virtual module** — the
+  `virtual:@theokit/ui/library-sources.css` module no longer emits the
+  broken `@source "node_modules/@theokit/ui/..."` default globs. It is
   retained for backwards compatibility (TheoKit's earlier integration
   code may still resolve it) but now emits only an explanatory comment
   block when no `contentExtra` option is passed. The plugin's primary
@@ -803,7 +1275,7 @@ the entire library rendered flat under pnpm.
   starter, Mantine v7.
 - Verification recipe matching TheoKit's reproduction script:
   ```bash
-  grep -c "\.hover\\:bg-muted" node_modules/.pnpm/@usetheo+ui@*/node_modules/@usetheo/ui/dist/components.css
+  grep -c "\.hover\\:bg-muted" node_modules/.pnpm/@theokit+ui@*/node_modules/@theokit/ui/dist/components.css
   # MUST return >= 1 (pre-fix: 0)
   ```
 
@@ -872,7 +1344,7 @@ branching navigation, and a streaming-safe markdown preprocess.
 
 ### Breaking changes
 
-- **`Message` type removed.** `import type { Message } from "@usetheo/ui"`
+- **`Message` type removed.** `import type { Message } from "@theokit/ui"`
   now fails — use `UIMessage` instead. TypeScript will hint
   `Did you mean 'UIMessage'?`.
 - **`message.content` removed.** Replace every callsite:
@@ -899,7 +1371,7 @@ branching navigation, and a streaming-safe markdown preprocess.
   `<ChatMessage>` — fold them into custom UI under the message body, or
   attach via `metadata?: unknown` (consumer-typed) and read from there.
 - **`./components/primitives/chat-message/`** deleted. Imports must move
-  to `./components/composites/chat-message/` (the public `@usetheo/ui`
+  to `./components/composites/chat-message/` (the public `@theokit/ui`
   barrel handles this; only relative imports inside the repo need
   updating).
 
@@ -939,12 +1411,12 @@ ships a fixture-backed real-build dogfood so the regression cannot recur.
 - **`./preset` subpath is now a CSS file.** Tailwind v4 dropped the v3 JS
   preset format — `theme.extend.colors.{name}` declarations are a no-op for
   v4. The new `dist/preset.css` simply chains `@import "./tokens.css"` and
-  `@import "./tokens-v4.css"` so consumers can `@import "@usetheo/ui/preset.css"`
+  `@import "./tokens-v4.css"` so consumers can `@import "@theokit/ui/preset.css"`
   from their own Tailwind v4 entry CSS. (#TBD)
 
 ### Added
 
-- **`@usetheo/ui/tokens-v4.css` (NEW)** — `@theme {}` block declaring 28
+- **`@theokit/ui/tokens-v4.css` (NEW)** — `@theme {}` block declaring 28
   `--color-*` aliases (full color set), 14 `--text-*` typescale tiers
   (Violet Forge — `--text-display-2xl` through `--text-code-sm` with companion
   `--*--line-height`, `--*--letter-spacing`, `--*--font-weight`), 3 `--font-*`
@@ -953,14 +1425,14 @@ ships a fixture-backed real-build dogfood so the regression cannot recur.
   uses `hsl(var(--*))` indirection so `<ThemeProvider>`'s runtime
   `[data-theme]` cascade keeps working — switching themes still recolors
   every utility. (#TBD)
-- **`@usetheo/ui/styles-v3-legacy.css` (NEW)** — the previous v3-shaped
+- **`@theokit/ui/styles-v3-legacy.css` (NEW)** — the previous v3-shaped
   `@tailwind base/components/utilities` entry. Pinned consumers on
   `tailwindcss@^3` who still want a prebuilt stylesheet can import this
-  subpath. New code SHOULD use `@usetheo/ui/styles.css` (v4) instead.
-- **`@usetheo/ui/preset-v3-legacy` (NEW)** — the v3 JS `Partial<Config>`
+  subpath. New code SHOULD use `@theokit/ui/styles.css` (v4) instead.
+- **`@theokit/ui/preset-v3-legacy` (NEW)** — the v3 JS `Partial<Config>`
   preset that previously lived at `./preset`. Renamed so the canonical
   `./preset` subpath can host the v4 CSS preset. v3 consumers update
-  imports from `@usetheo/ui/preset` to `@usetheo/ui/preset-v3-legacy`.
+  imports from `@theokit/ui/preset` to `@theokit/ui/preset-v3-legacy`.
 - **Dogfood scripts** — `pnpm dogfood:v4-zero-config` (shape check, runs in
   `quality:gates`) and `pnpm dogfood:v4-real-build` (end-to-end: packs the
   tarball, installs in a tmp project alongside `@tailwindcss/cli@^4`, runs
@@ -974,8 +1446,8 @@ ships a fixture-backed real-build dogfood so the regression cannot recur.
 
 - **Breaking for any 0.5.0-next.0 consumer.** The `./preset` subpath changed
   from JS (`Partial<Config>` default-export) to CSS file. Code importing
-  `import preset from "@usetheo/ui/preset"` will break and must migrate to
-  `@import "@usetheo/ui/preset.css"` in an entry CSS. Blast radius: TheoKit
+  `import preset from "@theokit/ui/preset"` will break and must migrate to
+  `@import "@theokit/ui/preset.css"` in an entry CSS. Blast radius: TheoKit
   (already reverted away from 0.5.x by the time this fix shipped) plus any
   community consumer that adopted 0.5.0-next.0 in the same day — likely zero.
 - The runtime indirection via `hsl(var(--*))` aliases keeps `<ThemeProvider>`
@@ -992,31 +1464,31 @@ Zero visual break and no runtime behavior change for existing consumers.
 
 ### Added
 
-- **`@usetheo/ui/vite-plugin` (NEW, RFC 0008)** — Default-export factory
+- **`@theokit/ui/vite-plugin` (NEW, RFC 0008)** — Default-export factory
   returning one Vite `Plugin`. The plugin's `config()` hook
   dynamic-imports `@tailwindcss/vite` v4 and chains it into the
   consumer's plugin array when resolvable, and degrades to `console.warn`
-  + CSS-only mode (via the pre-built `@usetheo/ui/styles.css` subpath)
+  + CSS-only mode (via the pre-built `@theokit/ui/styles.css` subpath)
   when the peer is not installed. A virtual module
-  `virtual:@usetheo/ui/library-sources.css` provides the `@source`
-  directive covering `node_modules/@usetheo/ui/dist/**/*.{js,mjs,cjs}`
+  `virtual:@theokit/ui/library-sources.css` provides the `@source`
+  directive covering `node_modules/@theokit/ui/dist/**/*.{js,mjs,cjs}`
   so Tailwind scans the library's published JS for utilities. Plugin
-  name slug: `@usetheo/ui/vite-plugin`. Options: `tailwind?: boolean`
+  name slug: `@theokit/ui/vite-plugin`. Options: `tailwind?: boolean`
   (default `true`), `contentExtra?: string[]` (extra `@source` globs).
   (#TBD)
-- **`@usetheo/ui/preset` (NEW, RFC 0008)** — Default-export Tailwind v4
+- **`@theokit/ui/preset` (NEW, RFC 0008)** — Default-export Tailwind v4
   `Partial<Config>` mirroring the design tokens in `tokens.css`
   (colors via `hsl(var(--x) / <alpha-value>)`, font families, the
   Violet Forge typescale, radii, shadows, animations, motion timing)
-  with `content` paths covering `./node_modules/@usetheo/ui/dist/**` and
+  with `content` paths covering `./node_modules/@theokit/ui/dist/**` and
   the `tailwindcss-animate` plugin. Consumer usage:
-  `import preset from "@usetheo/ui/preset"; export default { presets: [preset] }`.
+  `import preset from "@theokit/ui/preset"; export default { presets: [preset] }`.
   Internally delegates to the existing `src/styles/tailwind-preset.ts` —
   the v3 shadcn-registry preset and the v4 import preset stay
   byte-for-byte aligned and impossible to drift. (#TBD)
 - **`@tailwindcss/vite ^4`, `tailwindcss ^4`, `vite ^6 || ^7` peer-deps
   (all optional)** — added to `peerDependenciesMeta` so consumers
-  importing `@usetheo/ui` standalone (no framework) are not forced into
+  importing `@theokit/ui` standalone (no framework) are not forced into
   Tailwind v4. Required only when consuming via TheoKit's auto-wire path
   or the new `./vite-plugin` subpath. (#TBD)
 
@@ -1024,7 +1496,7 @@ Zero visual break and no runtime behavior change for existing consumers.
 
 - Existing `tailwindcss@^3` consumers continue to work via the shadcn
   registry preset (`registry/r/tailwind-preset.json`) and the prebuilt
-  `@usetheo/ui/styles.css`. The new subpaths are additive — they do not
+  `@theokit/ui/styles.css`. The new subpaths are additive — they do not
   break v3-based setups.
 - The `vite-plugin` returns ONE `Plugin` object (not `Plugin[]`) per the
   cross-repo contract with TheoKit's `integrateUseTheoUI()`. The chain
@@ -1094,10 +1566,10 @@ preserves rendered markup for callers that don't pass `size`.
 ## [0.1.0-next.1] - 2026-05-19
 
 ### Added
-- **Slide rich content — Tier 1 baked-in + Tier 2 plugin system (2026-05-19, RFC 0004)** — Estende `<Slide>` (RFC 0002) e `<SlideDeck>` (RFC 0003) com conteúdo rico nível PowerPoint sem reinventar parsers. **Tier 1 (zero peer-deps novas):** (a) GFM alerts `> [!NOTE/TIP/IMPORTANT/WARNING/CAUTION]` detectados em mdast post-process (alerts.ts) → `<aside class="theo-slide-alert" data-theo-slide-alert-type>` temado em ambos os themes (default + violet-forge); (b) 7 layouts via frontmatter `layout` (`default`, `title`, `two-column`, `image-right`, `image-left`, `code-output`, `section`) em CSS grid templates (themes/layouts.css importado pelos dois themes); (c) backgroundImage + backgroundGradient com `sanitizeBgUrl` rejeitando `javascript:`/`vbscript:`/TODO data: URLs (EC-7), cap 500_000 chars; (d) Marpit `![bg](url)` syntax extraído em mdast walker → `ParsedSlide.extractedBackground = { url, modifier }` (D18/EC-5), sanitizado antes de armazenar com fallback `MARPIT_BG_UNSAFE_URL`, modifier-aware (`cover`/`fit`/`left`/`right`); (e) header/footer/paginate overlays via frontmatter (plain text ≤200 chars cada), CSS absolute positioned. **Tier 2 (opt-in plugin system):** plugin architecture com `<Slide plugins={SlidePlugin[]}>` e relay `<SlideDeck plugins>` para cada slide interno. `SlidePlugin` shape: `{ name, mdastTransform?, hastTransform?, components?, sanitizeSchemaExtension? }` com error isolation D16 (cada chamada em try/catch, throws agregadas em `errors[]` com `code: "PLUGIN_ERROR"`; pipeline **nunca** propaga exception) e sanitize-schema merge D17 (extensions unionadas com defaultSchema + Tier 1 baseline). Quatro plugins shipados em sub-subpaths `@usetheo/ui/slide/plugins/{shiki,math,mermaid,emoji}`: **shikiPlugin** (peer-dep `shiki`; lazy + singleton highlighter; pre-renderiza `<pre><code class="language-XXX">` em HTML temado dual-theme com sanitize ext `<span> style/className`); **mathPlugin** (peer-deps `katex` + `hast-util-from-html`; substitui `$inline$` + `$$block$$` por KaTeX displayMode/inline; skip em `<code>`/`<pre>`; sanitize ext com lista completa de ≥30 tags MathML — `math`, `mfrac`, `msqrt`, `msup`, `msub`, `msubsup`, `munder`, `mover`, `mtable`, `mtr`, `mtd`, `mphantom`, `mstyle`, `annotation`, etc. — EC-4); **mermaidPlugin** (peer-dep `mermaid`; converte `<pre><code class="language-mermaid">` em `<theo-mermaid source>` com React `<MermaidDiagram>` que lazy-importa mermaid e injeta SVG via innerHTML; SSR placeholder distinguível de erro com `role="img"` + source code preservado, EC-10; sanitize ext com ≥30 tags SVG — `svg`, `g`, `path`, `rect`, `circle`, `text`, `marker`, `foreignObject`, etc. — EC-4); **emojiPlugin** (zero peer-deps de runtime, usa `unist-util-visit-parents` já no stack; 100 shortcodes Unicode embedded; **EC-6: ancestor check** via `isInsideCodeOrPre` skipa replace dentro de `<code>`/`<pre>` para preservar type hints Python / YAML keys / Ruby symbols). Pipeline order: `validateSlide → parseBody → detectAlerts (Tier 1) → extractMarpitBackgrounds (Tier 1) → plugin.mdastTransform[] → mdastToHast → plugin.hastTransform[] → sanitize(defaultSchema + extensions) → hastToReact (consumer + plugin components)`. Bundle isolation invariant preservada: barrel `dist/index.js` **inalterado**; cada plugin é entry tsup próprio com peer-deps externalizados. `scripts/sync-exports.ts` ganha 4 entries em `ISOLATED_SUBPATHS`. `package.json` ganha 9 peer-deps opcionais (`shiki`, `katex`, `mermaid`, `micromark-extension-math`, `mdast-util-math`, `hast-util-from-html`, `unist-util-visit`, `unist-util-visit-parents`). RFC `docs/rfcs/0004-slide-rich-content.md` status `Implemented`. **128 testes novos** distribuídos em 13 phases (T0.1 plugin contract: 13 testes; T0.2 parseSlide integration: 11 testes; T1.1 alerts: 8 testes; T2/T3/T5 schema: 25 testes; T4.1 Marpit bg: 9 testes; T6.1 Shiki: 6 testes; T7.1 Math: 7 testes; T8.1 Mermaid: 7 testes; T9.1 Emoji: 10 testes; Slide component: 32 testes). Suite total: 1174 testes verdes. Codes de erro novos: `PLUGIN_ERROR`, `PLUGIN_PEER_DEP_MISSING`, `MARPIT_BG_UNSAFE_URL`. (#TBD)
-- **SlideDeck composite engine — multi-slide deck w/ navigation, presenter, fullscreen, PDF (2026-05-19)** — `@usetheo/ui/slide-deck` agora orquestra N `<Slide>` primitives com navegação completa: keyboard (←/→/Space/Home/End/Esc/F/N/Ctrl+P, com guard contra inputs/contentEditable), touch swipe (Pointer Events nativos, multi-touch filtrado, pointercancel limpo — EC-6/EC-7), hash routing bidirectional (`#/N` 1-based, via `history.replaceState` para evitar loop — EC-10), lazy initializer SSR-safe (D17/EC-5). Sub-componentes em namespace dot: `<SlideDeck.Slides>` `<SlideDeck.Controls>` `<SlideDeck.ProgressBar>` `<SlideDeck.SlideNumber>` `<SlideDeck.Thumbnails>` (IntersectionObserver lazy + EC-13 fallback) `<SlideDeck.PresenterView>` (inline panel com timer + speaker notes) `<SlideDeck.FullscreenButton>` (cross-browser API + EC-8 iOS guard) `<SlideDeck.PrintButton>` (window.print + `@page` CSS, afterprint cleanup). Transitions CSS-only (`none`/`fade`/`slide`) com timeout fallback 300ms (D16/EC-3) e respeito a `prefers-reduced-motion`. Progressive fragments via Marpit-style `*` lists (D12, contagem por regex anti-falsos-positivos em `**bold**` ou fenced code). Speaker notes via `<!-- notes: ... -->` HTML comments (D11). Aceita `slides: string | SlideDeckSlide[]` (D4); split string via mdast `thematicBreak` reusando algoritmo do Slide D12 + strip global frontmatter primeiro (D15/EC-1 — evita phantom empty slide). `useReducer` state machine com `UPDATE_TOTAL_SLIDES` que clampa `currentIndex` (EC-4). Zero peer-deps novas — reusa as 7 do Slide. Bundle isolado em `dist/slide-deck/index.js` (~48 KB com Slide vendored); barrel principal `dist/index.js` **inalterado**. RFC `docs/rfcs/0003-slide-deck.md` status `Implemented`. 160 testes específicos do SlideDeck verdes. Stories Ladle: `DefaultDeck`, `WithGfmTable`, `WithSpeakerNotes`, `WithFragments`, `WithFadeTransition`, `WithSlideTransition`, `HashRouting`, `HeadlessLayout`, `WithThumbnails`, `PresenterModeOn`, `LargeDeck` (50 slides), `EmptyDeck`, `SingleSlideDeck`, `ControlledNavigation`. (#TBD)
-- **Slide engine — view-only primitive funcional (2026-05-19)** — `@usetheo/ui/slide` agora renderiza markdown + frontmatter YAML como surface temada com canvas lógico fixo (default 16:9 → 1280×720), espelhando o padrão de bundle isolado entregue pelo Whiteboard. Pipeline: `validateSlide` (async — D11) → `parseBody` (micromark + GFM) → `mdastToHast` (`allowDangerousHtml: false`) → `sanitizeHast` (`defaultSchema` sem extensões — D8, com diff de tag-count que emite `BANNED_TAG` — D13) → `hastToReact` (real React VDOM via `hast-util-to-jsx-runtime` — D9, **sem `dangerouslySetInnerHTML`**). Frontmatter YAML único (sem HTML comment syntax do Marpit — D4), validado com Zod `.strict()` (4 keys aceitos: `theme`, `lang`, `color`, `backgroundColor`). Multi-slide input (top-level `---` detectado via mdast `thematicBreak` — D12, sem false-positive em fenced code blocks) emite `MULTIPLE_SLIDES` e renderiza somente o primeiro slide. Input guards (D14): BOM strip, `aspectRatio` inválido → fallback 16:9 + `INVALID_ASPECT_RATIO`, raw frontmatter > 10 KB → `FRONTMATTER_TOO_LARGE`. Container fit (D7) via `useSlideFit` hook (algoritmo Reveal.js: `scale = clamp(min(W/cw, H/ch), minScale, maxScale)` em `ResizeObserver` callback). Dois temas built-in (`default`, `violet-forge`) via CSS variables `--theo-slide-*` layered sobre Violet Forge tokens, com `light-dark()` para dark mode automático. A11y: `<section role="region" aria-roledescription="slide" aria-label>`. Race-resistant re-parse via `versionRef` counter (EC-7). 7 markdown peer-deps são **opcionais**: `mdast-util-from-markdown`, `mdast-util-gfm`, `micromark-extension-gfm`, `mdast-util-to-hast`, `hast-util-sanitize`, `hast-util-to-jsx-runtime`, `yaml`. Bundle isolado em `dist/slide/index.js`; barrel principal `dist/index.js` **inalterado**. RFC `docs/rfcs/0002-slide.md` status `Implemented`. 12 Ladle stories: `HappyPath`, `GfmTable`, `WithFrontmatter`, `VioletForgeTheme`, `AspectFourByThree`, `MultiSlideTruncated`, `MalformedFrontmatter`, `BannedScript`, `LongContent`, `CustomComponents`, `SmallContainer`, `LargeContainer`. (#TBD)
-- **Whiteboard engine — view-only primitive funcional (2026-05-18)** — `@usetheo/ui/whiteboard` agora renderiza JSON declarativo (`WhiteboardData`) como SVG com estética hand-drawn estilo Excalidraw. **Sete tipos** de elemento suportados: `rect`, `ellipse`, `diamond`, `line`, `arrow`, `text`, `freedraw`. **Pan + zoom built-in** via `viewBox` (wheel = zoom-to-cursor, mouse drag = pan, Space = hand mode, pinch touch supported). **Prop `fitOnLoad`** centra automaticamente os elementos na viewport. Schema Zod com clamps de sanidade (EC-3 `.finite()` rejeita NaN/Infinity; EC-4 `.max(20000)` em dimensões; `.max(500)` em labels; `.max(5000)` em text e points/elements). `<Whiteboard>` valida JSON em `useMemo`, dispara `onValidationError` em `useEffect` (EC-6 — nunca durante render), e cai em SVG vazio com `data-whiteboard-state="invalid"` quando o JSON falha. SSR-safe (`renderToString` produz markup estático correto). `roughjs` + `perfect-freehand` são peer-deps **opcionais**; `zod` entra em `dependencies` regulares (EC-5 opção A). Bundle isolado em `dist/whiteboard/index.js` (21.53KB ESM); barrel principal `dist/index.js` **inalterado** (320.41KB). RFC `docs/rfcs/0001-whiteboard.md` status `Implemented`. 86 testes específicos do Whiteboard verdes + 776 testes totais do projeto. Stories Ladle: `Empty`, `Flowchart`, `Architecture`, `FreedrawSketch`, `MixedAll`, `InvalidJSON`. (#TBD)
+- **Slide rich content — Tier 1 baked-in + Tier 2 plugin system (2026-05-19, RFC 0004)** — Estende `<Slide>` (RFC 0002) e `<SlideDeck>` (RFC 0003) com conteúdo rico nível PowerPoint sem reinventar parsers. **Tier 1 (zero peer-deps novas):** (a) GFM alerts `> [!NOTE/TIP/IMPORTANT/WARNING/CAUTION]` detectados em mdast post-process (alerts.ts) → `<aside class="theo-slide-alert" data-theo-slide-alert-type>` temado em ambos os themes (default + violet-forge); (b) 7 layouts via frontmatter `layout` (`default`, `title`, `two-column`, `image-right`, `image-left`, `code-output`, `section`) em CSS grid templates (themes/layouts.css importado pelos dois themes); (c) backgroundImage + backgroundGradient com `sanitizeBgUrl` rejeitando `javascript:`/`vbscript:`/TODO data: URLs (EC-7), cap 500_000 chars; (d) Marpit `![bg](url)` syntax extraído em mdast walker → `ParsedSlide.extractedBackground = { url, modifier }` (D18/EC-5), sanitizado antes de armazenar com fallback `MARPIT_BG_UNSAFE_URL`, modifier-aware (`cover`/`fit`/`left`/`right`); (e) header/footer/paginate overlays via frontmatter (plain text ≤200 chars cada), CSS absolute positioned. **Tier 2 (opt-in plugin system):** plugin architecture com `<Slide plugins={SlidePlugin[]}>` e relay `<SlideDeck plugins>` para cada slide interno. `SlidePlugin` shape: `{ name, mdastTransform?, hastTransform?, components?, sanitizeSchemaExtension? }` com error isolation D16 (cada chamada em try/catch, throws agregadas em `errors[]` com `code: "PLUGIN_ERROR"`; pipeline **nunca** propaga exception) e sanitize-schema merge D17 (extensions unionadas com defaultSchema + Tier 1 baseline). Quatro plugins shipados em sub-subpaths `@theokit/ui/slide/plugins/{shiki,math,mermaid,emoji}`: **shikiPlugin** (peer-dep `shiki`; lazy + singleton highlighter; pre-renderiza `<pre><code class="language-XXX">` em HTML temado dual-theme com sanitize ext `<span> style/className`); **mathPlugin** (peer-deps `katex` + `hast-util-from-html`; substitui `$inline$` + `$$block$$` por KaTeX displayMode/inline; skip em `<code>`/`<pre>`; sanitize ext com lista completa de ≥30 tags MathML — `math`, `mfrac`, `msqrt`, `msup`, `msub`, `msubsup`, `munder`, `mover`, `mtable`, `mtr`, `mtd`, `mphantom`, `mstyle`, `annotation`, etc. — EC-4); **mermaidPlugin** (peer-dep `mermaid`; converte `<pre><code class="language-mermaid">` em `<theo-mermaid source>` com React `<MermaidDiagram>` que lazy-importa mermaid e injeta SVG via innerHTML; SSR placeholder distinguível de erro com `role="img"` + source code preservado, EC-10; sanitize ext com ≥30 tags SVG — `svg`, `g`, `path`, `rect`, `circle`, `text`, `marker`, `foreignObject`, etc. — EC-4); **emojiPlugin** (zero peer-deps de runtime, usa `unist-util-visit-parents` já no stack; 100 shortcodes Unicode embedded; **EC-6: ancestor check** via `isInsideCodeOrPre` skipa replace dentro de `<code>`/`<pre>` para preservar type hints Python / YAML keys / Ruby symbols). Pipeline order: `validateSlide → parseBody → detectAlerts (Tier 1) → extractMarpitBackgrounds (Tier 1) → plugin.mdastTransform[] → mdastToHast → plugin.hastTransform[] → sanitize(defaultSchema + extensions) → hastToReact (consumer + plugin components)`. Bundle isolation invariant preservada: barrel `dist/index.js` **inalterado**; cada plugin é entry tsup próprio com peer-deps externalizados. `scripts/sync-exports.ts` ganha 4 entries em `ISOLATED_SUBPATHS`. `package.json` ganha 9 peer-deps opcionais (`shiki`, `katex`, `mermaid`, `micromark-extension-math`, `mdast-util-math`, `hast-util-from-html`, `unist-util-visit`, `unist-util-visit-parents`). RFC `docs/rfcs/0004-slide-rich-content.md` status `Implemented`. **128 testes novos** distribuídos em 13 phases (T0.1 plugin contract: 13 testes; T0.2 parseSlide integration: 11 testes; T1.1 alerts: 8 testes; T2/T3/T5 schema: 25 testes; T4.1 Marpit bg: 9 testes; T6.1 Shiki: 6 testes; T7.1 Math: 7 testes; T8.1 Mermaid: 7 testes; T9.1 Emoji: 10 testes; Slide component: 32 testes). Suite total: 1174 testes verdes. Codes de erro novos: `PLUGIN_ERROR`, `PLUGIN_PEER_DEP_MISSING`, `MARPIT_BG_UNSAFE_URL`. (#TBD)
+- **SlideDeck composite engine — multi-slide deck w/ navigation, presenter, fullscreen, PDF (2026-05-19)** — `@theokit/ui/slide-deck` agora orquestra N `<Slide>` primitives com navegação completa: keyboard (←/→/Space/Home/End/Esc/F/N/Ctrl+P, com guard contra inputs/contentEditable), touch swipe (Pointer Events nativos, multi-touch filtrado, pointercancel limpo — EC-6/EC-7), hash routing bidirectional (`#/N` 1-based, via `history.replaceState` para evitar loop — EC-10), lazy initializer SSR-safe (D17/EC-5). Sub-componentes em namespace dot: `<SlideDeck.Slides>` `<SlideDeck.Controls>` `<SlideDeck.ProgressBar>` `<SlideDeck.SlideNumber>` `<SlideDeck.Thumbnails>` (IntersectionObserver lazy + EC-13 fallback) `<SlideDeck.PresenterView>` (inline panel com timer + speaker notes) `<SlideDeck.FullscreenButton>` (cross-browser API + EC-8 iOS guard) `<SlideDeck.PrintButton>` (window.print + `@page` CSS, afterprint cleanup). Transitions CSS-only (`none`/`fade`/`slide`) com timeout fallback 300ms (D16/EC-3) e respeito a `prefers-reduced-motion`. Progressive fragments via Marpit-style `*` lists (D12, contagem por regex anti-falsos-positivos em `**bold**` ou fenced code). Speaker notes via `<!-- notes: ... -->` HTML comments (D11). Aceita `slides: string | SlideDeckSlide[]` (D4); split string via mdast `thematicBreak` reusando algoritmo do Slide D12 + strip global frontmatter primeiro (D15/EC-1 — evita phantom empty slide). `useReducer` state machine com `UPDATE_TOTAL_SLIDES` que clampa `currentIndex` (EC-4). Zero peer-deps novas — reusa as 7 do Slide. Bundle isolado em `dist/slide-deck/index.js` (~48 KB com Slide vendored); barrel principal `dist/index.js` **inalterado**. RFC `docs/rfcs/0003-slide-deck.md` status `Implemented`. 160 testes específicos do SlideDeck verdes. Stories Ladle: `DefaultDeck`, `WithGfmTable`, `WithSpeakerNotes`, `WithFragments`, `WithFadeTransition`, `WithSlideTransition`, `HashRouting`, `HeadlessLayout`, `WithThumbnails`, `PresenterModeOn`, `LargeDeck` (50 slides), `EmptyDeck`, `SingleSlideDeck`, `ControlledNavigation`. (#TBD)
+- **Slide engine — view-only primitive funcional (2026-05-19)** — `@theokit/ui/slide` agora renderiza markdown + frontmatter YAML como surface temada com canvas lógico fixo (default 16:9 → 1280×720), espelhando o padrão de bundle isolado entregue pelo Whiteboard. Pipeline: `validateSlide` (async — D11) → `parseBody` (micromark + GFM) → `mdastToHast` (`allowDangerousHtml: false`) → `sanitizeHast` (`defaultSchema` sem extensões — D8, com diff de tag-count que emite `BANNED_TAG` — D13) → `hastToReact` (real React VDOM via `hast-util-to-jsx-runtime` — D9, **sem `dangerouslySetInnerHTML`**). Frontmatter YAML único (sem HTML comment syntax do Marpit — D4), validado com Zod `.strict()` (4 keys aceitos: `theme`, `lang`, `color`, `backgroundColor`). Multi-slide input (top-level `---` detectado via mdast `thematicBreak` — D12, sem false-positive em fenced code blocks) emite `MULTIPLE_SLIDES` e renderiza somente o primeiro slide. Input guards (D14): BOM strip, `aspectRatio` inválido → fallback 16:9 + `INVALID_ASPECT_RATIO`, raw frontmatter > 10 KB → `FRONTMATTER_TOO_LARGE`. Container fit (D7) via `useSlideFit` hook (algoritmo Reveal.js: `scale = clamp(min(W/cw, H/ch), minScale, maxScale)` em `ResizeObserver` callback). Dois temas built-in (`default`, `violet-forge`) via CSS variables `--theo-slide-*` layered sobre Violet Forge tokens, com `light-dark()` para dark mode automático. A11y: `<section role="region" aria-roledescription="slide" aria-label>`. Race-resistant re-parse via `versionRef` counter (EC-7). 7 markdown peer-deps são **opcionais**: `mdast-util-from-markdown`, `mdast-util-gfm`, `micromark-extension-gfm`, `mdast-util-to-hast`, `hast-util-sanitize`, `hast-util-to-jsx-runtime`, `yaml`. Bundle isolado em `dist/slide/index.js`; barrel principal `dist/index.js` **inalterado**. RFC `docs/rfcs/0002-slide.md` status `Implemented`. 12 Ladle stories: `HappyPath`, `GfmTable`, `WithFrontmatter`, `VioletForgeTheme`, `AspectFourByThree`, `MultiSlideTruncated`, `MalformedFrontmatter`, `BannedScript`, `LongContent`, `CustomComponents`, `SmallContainer`, `LargeContainer`. (#TBD)
+- **Whiteboard engine — view-only primitive funcional (2026-05-18)** — `@theokit/ui/whiteboard` agora renderiza JSON declarativo (`WhiteboardData`) como SVG com estética hand-drawn estilo Excalidraw. **Sete tipos** de elemento suportados: `rect`, `ellipse`, `diamond`, `line`, `arrow`, `text`, `freedraw`. **Pan + zoom built-in** via `viewBox` (wheel = zoom-to-cursor, mouse drag = pan, Space = hand mode, pinch touch supported). **Prop `fitOnLoad`** centra automaticamente os elementos na viewport. Schema Zod com clamps de sanidade (EC-3 `.finite()` rejeita NaN/Infinity; EC-4 `.max(20000)` em dimensões; `.max(500)` em labels; `.max(5000)` em text e points/elements). `<Whiteboard>` valida JSON em `useMemo`, dispara `onValidationError` em `useEffect` (EC-6 — nunca durante render), e cai em SVG vazio com `data-whiteboard-state="invalid"` quando o JSON falha. SSR-safe (`renderToString` produz markup estático correto). `roughjs` + `perfect-freehand` são peer-deps **opcionais**; `zod` entra em `dependencies` regulares (EC-5 opção A). Bundle isolado em `dist/whiteboard/index.js` (21.53KB ESM); barrel principal `dist/index.js` **inalterado** (320.41KB). RFC `docs/rfcs/0001-whiteboard.md` status `Implemented`. 86 testes específicos do Whiteboard verdes + 776 testes totais do projeto. Stories Ladle: `Empty`, `Flowchart`, `Architecture`, `FreedrawSketch`, `MixedAll`, `InvalidJSON`. (#TBD)
 - **`scripts/validate-bundle-size.ts` ganha gate EC-1 anti-leak** — Após o check de tamanho, faz `grep` em `dist/index.js` por strings `roughjs` e `perfect-freehand`; falha o build se qualquer engine peer-dep aparecer no barrel. Previne regressões silenciosas onde uma engine vaze para o barrel principal e arraste KBs extras para todos os consumers, mesmo os que só usam shadcn primitives. Runtime-metric proof: `grep -c "roughjs\\|perfect-freehand" dist/index.js → 0` confirmado em 2026-05-18. (#TBD)
 - **`scripts/sync-exports.ts` ganha `ISOLATED_SUBPATHS`** — novo array de overrides para subpaths que devem apontar para `dist/<engine>/index.js` próprio, não re-export do barrel. Detecta colisão com auto-scanned subpaths e lança Error explícito. Suporta a regra de bundle isolation por engine declarada em `CLAUDE.md > Roadmap`. Cobertura via novo `scripts/sync-exports.test.ts` (6 testes). (#TBD)
 - **`tsup.config.ts` ganha multi-entry** — `entry` agora é objeto com `index` (barrel) + `whiteboard/index` (engine). External list inclui `roughjs`, `/^roughjs\//` e `perfect-freehand` para garantir que o engine bundle não vendoriza essas libs e o barrel não vaza. Build produz `dist/whiteboard/index.{js,d.ts}` ao lado de `dist/index.{js,d.ts}` sem afetar tamanho do barrel. (#TBD)
@@ -1108,7 +1580,7 @@ preserves rendered markup for callers that don't pass `size`.
 ## [0.1.0-next.0] - 2026-05-16
 
 First public pre-release on npm under the `next` dist-tag. Install with
-`pnpm add @usetheo/ui@next` (the default `latest` tag is intentionally
+`pnpm add @theokit/ui@next` (the default `latest` tag is intentionally
 unset until 1.0). Highlights from the agent-team-audit-fixes-2026-05-16
 remediation sprint:
 
@@ -1130,15 +1602,15 @@ remediation sprint:
 - **Migration**:
   ```tsx
   // Before
-  import { ThemeProvider } from "@usetheo/ui";
+  import { ThemeProvider } from "@theokit/ui";
   <ThemeProvider>...</ThemeProvider>
 
   // After — option A (recommended for parity with old behavior)
-  import { ThemeProvider, builtinThemes } from "@usetheo/ui";
+  import { ThemeProvider, builtinThemes } from "@theokit/ui";
   <ThemeProvider themes={builtinThemes}>...</ThemeProvider>
 
   // After — option B (new in v0.1.0-next.0)
-  import { TheoUIProvider } from "@usetheo/ui";
+  import { TheoUIProvider } from "@theokit/ui";
   <TheoUIProvider>...</TheoUIProvider>
   ```
 - **Why this is acceptable pre-1.0**: package is `0.0.0` and never published; first public release will be `0.1.0-next.0`. No external consumers exist yet (validated via `npm view`).
@@ -1153,22 +1625,22 @@ remediation sprint:
 - **`scripts/validate-registry.ts`** — `targetToItemName` reverse map resolves `@/components/ui/<target>` imports to the registry item that ships that file (fix for multi-file items like `toast` which ships `toaster.tsx`).
 
 ### Documentation (Agent-team audit fixes, 2026-05-16)
-- **`PITCH.md`** — removed false claim that `npx create-theokit my-app` already imports `@usetheo/ui` when picking the dashboard template (verified via `grep -r "@usetheo/ui" /home/paulo/Projetos/usetheo/theokit/` returning zero matches). Replaced with honest "TheoKit integration is on the roadmap." Aligned tertiary CTAs with reality (substituted dead `docs.usetheo.dev/ui` with GitHub anchor).
+- **`PITCH.md`** — removed false claim that `npx create-theokit my-app` already imports `@theokit/ui` when picking the dashboard template (verified via `grep -r "@theokit/ui" /home/paulo/Projetos/usetheo/theokit/` returning zero matches). Replaced with honest "TheoKit integration is on the roadmap." Aligned tertiary CTAs with reality (substituted dead `docs.usetheo.dev/ui` with GitHub anchor).
 - **`README.md`** — updated `pnpm quality:gates` pipeline listing to match `package.json#scripts['quality:gates']` exactly: now lists 11 gates (`format:check` → `lint:ci` → `typecheck` → `test` → `build` → `registry:build` → `registry:validate` → `quality:structure` → `quality:bundle` → `quality:a11y` → `ladle:build`). Previous text omitted `quality:bundle` and `quality:a11y`.
 - **CHANGELOG correction** — earlier entry under "Phase 3 — Build correctness + exports surface" stated `validateExportsMap` "locks `package.json#exports` to the canonical 5-entry set". Since commit `77b2f7a` (`feat(exports): subpath import for every component`) the strategy expanded to 107+ subpath entries generated by `scripts/sync-exports.ts`. Authoritative source is `package.json` itself. Prior entries in versioned releases stay immutable per Keep a Changelog; this correction lives in `[Unreleased]`.
 
 ### Added (Pitch + Voice and Tone formalization, 2026-05-15)
-- **`PITCH.md`** at project root — landing-page copy for `@usetheo/ui` (Violet Forge) using the TheoKit aspirational voice. Three layers: HERO (no jargon), BODY (benefit-first with one technical anchor per item), DEEP DIVE (full technical vocabulary, after the `## How it works` delimiter). Companion to `README.md` for marketing surfaces; verified component counts and quality metrics against `README.md` and `src/`.
-- **`CLAUDE.md`** at project root — contract between Claude and this project. Defines what TheoUI is, the locked names (npm package, theme names, registry endpoint, module format, component taxonomy), the Voice and Tone section that formalizes adoption of the TheoKit aspirational voice for public copy (strategic review dated 2026-05-15), the relationship to the other usetheo pillars (Harness, Skills, Runtime), and the quality-gate non-bypass rule.
+- **`PITCH.md`** at project root — landing-page copy for `@theokit/ui` (Violet Forge) using the TheoKit aspirational voice. Three layers: HERO (no jargon), BODY (benefit-first with one technical anchor per item), DEEP DIVE (full technical vocabulary, after the `## How it works` delimiter). Companion to `README.md` for marketing surfaces; verified component counts and quality metrics against `README.md` and `src/`.
+- **`CLAUDE.md`** at project root — contract between Claude and this project. Defines what TheoUI is, the locked names (npm package, theme names, registry endpoint, module format, component taxonomy), the Voice and Tone section that formalizes adoption of the TheoKit aspirational voice for public copy (strategic review dated 2026-05-15), the relationship to the other Theo pillars (Harness, Skills, Runtime), and the quality-gate non-bypass rule.
 
 ### Changed (Cross-project, 2026-05-15)
 - Root monorepo `CLAUDE.md` (`../CLAUDE.md`) `## Voice and Tone — sub-project scoped` section: TheoUI moved from the "technical-direct only" list to the aspirational-voice list, alongside TheoKit and TheoKit-SDK. Rationale captured inline (TheoUI is the visual surface every other product inherits from; benefits from outcome-shaped framing on landing copy).
 - Root monorepo sub-project index: `theo-ui` "Read first" pointer updated from `theo-ui/README.md` to `theo-ui/CLAUDE.md` (was a fallback because no `CLAUDE.md` existed in this project until today).
 
 ### Changed (README alignment with PITCH, 2026-05-15)
-- `README.md` HERO + BODY layers rewritten in the TheoKit aspirational voice to match `PITCH.md`. New h1: *"The UI your agent already needs."* Tagline calls out the 102 agent-shaped components. `@usetheo/ui` demoted from h1 to a small tag above it (discoverability preserved without dominating the HERO).
-- Added `## The shift` storytelling block between the HERO and `## Why @usetheo/ui`.
-- `## Why @usetheo/ui` now closes with the comparison table from `PITCH.md` (`@usetheo/ui` vs shadcn/Radix, Tremor, build-yourself) and the punch line *"Same Radix UI underneath as shadcn — no philosophy fight. We just shipped the next 102 components you were about to write."*
+- `README.md` HERO + BODY layers rewritten in the TheoKit aspirational voice to match `PITCH.md`. New h1: *"The UI your agent already needs."* Tagline calls out the 102 agent-shaped components. `@theokit/ui` demoted from h1 to a small tag above it (discoverability preserved without dominating the HERO).
+- Added `## The shift` storytelling block between the HERO and `## Why @theokit/ui`.
+- `## Why @theokit/ui` now closes with the comparison table from `PITCH.md` (`@theokit/ui` vs shadcn/Radix, Tremor, build-yourself) and the punch line *"Same Radix UI underneath as shadcn — no philosophy fight. We just shipped the next 102 components you were about to write."*
 - Added `## What you'd build` (5 concrete surfaces) before `## Quickstart`.
 - Added `## How it works` DEEP DIVE delimiter before `## Quickstart`; everything from there downward stays technical-direct.
 - Quickstart code sample swapped from a generic `<Button>` example to `<AgentEvent>` + `<ToolCall>` + `<DeploymentRow>` — agent-shaped primitives nobody else ships.
@@ -1223,8 +1695,8 @@ remediation sprint:
 
 ### Changed (HIGH-002 / T4.1 — self-hosted fonts as default)
 - **`src/styles/fonts.css` no longer `@import`s from `fonts.googleapis.com`.** Now declares six `@font-face` rules pointing at `./fonts/geist-{400,500,600}.woff2` and `./fonts/geist-mono-{400,500,600}.woff2`. Total asset budget: ~290 KB of woff2 next to the CSS. Eliminates the render-blocking third-party fetch that previously hit `fonts.googleapis.com` on every cold page load — fixes GDPR / CSP friction for the enterprise audience.
-- `src/styles/fonts-cdn.css` (NEW) — opt-in entrypoint that preserves the legacy Google Fonts CDN behavior. Consumers who prefer not to host static assets can `@import "@usetheo/ui/fonts-cdn.css"` instead of `@usetheo/ui/fonts.css` / `@usetheo/ui/styles.css`.
-- `tsup.config.ts` `onSuccess` now also copies `src/styles/fonts/*.woff2` → `dist/fonts/` and `src/styles/fonts-cdn.css` → `dist/fonts-cdn.css`. The relative URLs in `fonts.css` (`./fonts/geist-400.woff2`) resolve correctly inside `node_modules/@usetheo/ui/dist/`.
+- `src/styles/fonts-cdn.css` (NEW) — opt-in entrypoint that preserves the legacy Google Fonts CDN behavior. Consumers who prefer not to host static assets can `@import "@theokit/ui/fonts-cdn.css"` instead of `@theokit/ui/fonts.css` / `@theokit/ui/styles.css`.
+- `tsup.config.ts` `onSuccess` now also copies `src/styles/fonts/*.woff2` → `dist/fonts/` and `src/styles/fonts-cdn.css` → `dist/fonts-cdn.css`. The relative URLs in `fonts.css` (`./fonts/geist-400.woff2`) resolve correctly inside `node_modules/@theokit/ui/dist/`.
 - Geist OFL license shipped at `src/styles/fonts/LICENSE-GEIST.txt` → `dist/fonts/LICENSE-GEIST.txt`. Apache-2.0 + OFL is a clean dual-license combination.
 - New `geist` devDependency: used only as the source of woff2 artifacts at install time; not bundled into `dist/index.js`.
 - `validateDocsTypography` now asserts that `src/styles/fonts.css` contains `@font-face` and does NOT `@import` from `fonts.googleapis.com`, and that `src/styles/fonts-cdn.css` exists.
@@ -1239,7 +1711,7 @@ remediation sprint:
 - `.ladle/generated/welcome.stats.ts` — `welcome.stats.ts` moved out of `src/` (HIGH-003 / T3.3). `sync-readme.ts` writes to the new path; `validateCountConsistency` reads from it. The file no longer ships in the npm tarball.
 
 ### Breaking
-- **Reclassification of 7 components from `primitives/` to `composites/`** (BLOCKER-001 remediation, D2): `AgentEditor`, `RuleEditor`, `SkillEditor`, `ApprovalCard`, `CronJobsList`, `SkillsList`, `MCPServerList`. Each value-imported one or more sibling primitives, which violated the mechanical taxonomy rule in `docs/architecture.md`. They are composites by every reasonable definition (FormField+Input+Button = composite; list-of-card = composite). Public barrel (`@usetheo/ui`) is unchanged — named exports preserved. Registry consumers via `npx shadcn add`: `type` changed from `registry:ui` to `registry:block` and `target` from `components/ui/<name>` to `components/blocks/<name>`. Migration: re-run `npx shadcn add <name>` to relocate the file, or rename the import path manually.
+- **Reclassification of 7 components from `primitives/` to `composites/`** (BLOCKER-001 remediation, D2): `AgentEditor`, `RuleEditor`, `SkillEditor`, `ApprovalCard`, `CronJobsList`, `SkillsList`, `MCPServerList`. Each value-imported one or more sibling primitives, which violated the mechanical taxonomy rule in `docs/architecture.md`. They are composites by every reasonable definition (FormField+Input+Button = composite; list-of-card = composite). Public barrel (`@theokit/ui`) is unchanged — named exports preserved. Registry consumers via `npx shadcn add`: `type` changed from `registry:ui` to `registry:block` and `target` from `components/ui/<name>` to `components/blocks/<name>`. Migration: re-run `npx shadcn add <name>` to relocate the file, or rename the import path manually.
 - **`form-field` now imports `@radix-ui/react-label` directly** (BLOCKER-001 / D2 exception). Previously imported the sibling `Label` primitive. `form-field.tsx` now inlines the same Radix LabelPrimitive + identical Tailwind tokens. Visual parity preserved. `registry/form-field.json` adds `@radix-ui/react-label` to `dependencies` and removes `label` from `registryDependencies`.
 
 ### Fixed