@nadicodeai/ui 10.1.0 → 12.1.0

package/docs/migration/10.0.0.md

@@ -1,144 +0,0 @@
-# Migrating to `@nadicodeai/ui` 10.0.0
-
-This release carries the nadicode design system settled in
-[the ADR](https://github.com/nadicodeai/nadicodeai/blob/main/docs/adr/2026-09-23-the-nadicode-design-system.md):
-the new logo and name, twelve type tokens named by role, two greens, one motion
-law, activity without spinners, the stepped dark ring, three Agent colours, and
-the website's page grammar retired. `@nadicodeai/ui` 10.0.0 requires
-`@nadicodeai/design-system` 10.0.0; the two packages are released in lockstep.
-The type renames are the largest break for consumers; start there.
-
-## Type tokens
-
-Twelve sizes named by the role they play, Geist and Geist Mono only. Strong is
-a weight, not a token: a 500 run of body copy is `body-md` with
-`font-weight: 500`. Rename the `.nc-type-*` class and the `--nc-type-*` tokens
-at every call site.
-
-| Removed | Use instead |
-| --- | --- |
-| `title-lg` | `display-md` |
-| `title-md` | `heading-lg` |
-| `title-sm` | `heading-md` |
-| `display-md` | `heading-md` |
-| `display-sm` | `heading-sm` |
-| `body-md-strong` | `body-md` plus `font-weight: 500` |
-| `body-sm-strong` | `body-sm` plus `font-weight: 500` |
-| `caption-strong` | `caption` plus `font-weight: 500` |
-| `button-lg` | `body-md` plus `font-weight: 500` |
-| `button-md` | `body-sm` plus `font-weight: 500` |
-| `caption-mono` | `label-mono` |
-
-`display-xl`, `display-lg`, `body-lg`, `body-md`, `body-sm`, `caption` and
-`code` keep their names. `display-md` is now 40/42 rather than 24/32, so a call
-site that used the old small display tier moves to `heading-md`. Tracking is a
-display-tier exception and nothing else: the three display sizes run from
--0.035em at 72px to -0.025em at 40px, and every other tier is `0px`.
-
-## Colour tokens
-
-Two greens, and only two: `link` carries text, identity verde carries marks.
-
-| Removed | Use instead |
-| --- | --- |
-| `--nc-primary` | `--nc-identity-cobalto` for a brand mark, `--nc-link` for text, or the shadcn `--primary` role for the neutral action |
-| `--nc-dark-primary` | as above; the mode layer maps `--nc-identity-cobalto` in both themes |
-| `--nc-verde-vivo` | `--nc-identity-verde` |
-| `--nc-dark-verde-vivo` | `--nc-identity-verde` |
-
-The shadcn `primary` role is unchanged and still resolves to the neutral action
-family. `success` and `state-complete` are unchanged.
-
-## Motion tokens
-
-| Removed | Use instead |
-| --- | --- |
-| `--nc-duration-spin` | nothing; a busy spinner is not an Agent |
-| `--nc-duration-typing` | nothing; the typewriter line is retired |
-| `--nc-duration-shimmer` | nothing; the shimmer systems are retired |
-| `--nc-duration-pulse` | `--nc-duration-wait`, for the one waiting line |
-| `.nc-anim-typing`, `.nc-anim-pulse`, `.nc-anim-shimmer` | nothing; only Agents move on their own |
-
-One default transition in every product, `confirm` on `out-strong`, is declared
-once in the shipped `motion.css`. One reduced-motion policy replaces the
-per-component switches: movement stops and paint continues, so an overlay keeps
-its fade and only the transform or scale it would have travelled is dropped. A
-component that answered reduced motion with `motion-reduce:transition-none` on a
-paint-only transition should drop that class; one on a mixed transition should
-narrow to `motion-reduce:transition-opacity` instead.
-
-## Elevation
-
-In dark mode the four rungs step their ring: resting 12%, raised 16%, floating
-22%, modal 28% white, in place of one 18% ring on every rung. Light mode and the
-shadow falloff are unchanged, and the `nc-elevation-*` utilities are unchanged,
-so a consumer that uses the rung by name needs no edit.
-
-## Agent colours
-
-`agentOrbColors` is `cobalto`, `verde` and `arancio`, beside the inherited
-default. Rosso left the picker because it is exactly the error red, and a red
-Agent beside a red status badge read as a broken Agent. `agentOrbColorValues`
-and `agentOrbColorTokens` lose their `rosso` entry with it, so a caller that
-indexed either by a stored string must go through `resolveAgentOrb`, which maps
-a stored rosso, by name or by the `#d3302f` hex, to arancio. The retired
-spelling is exported as `retiredAgentOrbColorValues` for fixtures and tests.
-Nadia's ribbon keeps its rosso stripe.
-
-## Removed components
-
-| Removed | Use instead |
-| --- | --- |
-| `components/brand` (`BrandLockup`) | `BrandWordmark` |
-
-There is no lockup any more. The wordmark names the company in full and the n
-is already inside it, so a placement carrying `BrandMark` and `BrandWordmark`
-together draws the letter twice; pick the one form the space allows.
-`BrandMark` and `BrandWordmark` keep their props, and their default accessible
-name is now `nadicode`.
-
-## Removed assets
-
-The design system publishes seven files, as SVG and as transparent PNG, under
-the names the ADR gives them. Append `.png` to any route for the raster.
-
-| Removed | Use instead |
-| --- | --- |
-| `assets/logo-lockup`, `assets/logo-wordmark` | `assets/logo` |
-| `assets/logo-lockup-inverse`, `assets/logo-wordmark-inverse` | `assets/logo-white` |
-| `assets/logo-lockup-mono`, `assets/logo-wordmark-mono` | `assets/logo-one-ink` |
-| `assets/logo-mark` | `assets/mark` |
-| `assets/logo-mark-inverse` | `assets/mark-white` |
-| `assets/logo-mark-mono` | `assets/mark`; the n is one ink already |
-| `assets/logo-lockup-on-verde`, `assets/logo-mark-on-verde`, `assets/logo-wordmark-on-verde` | No replacement. The logo is never mounted on a verde field. |
-
-Added: `assets/logo-one-ink-white`, the one-ink wordmark on a dark ground, and
-`assets/app-icon`, the white n on the cobalto tile at 1024 for an application
-icon slot. The one-ink files exist for embossing, stamps and one-colour print,
-where a second colour cannot be laid down.
-
-`assets/logo-geometry` keeps its route and changes shape. `LogoPaints` is now a
-record of paint roles, `ink` for every stroked letter, `dot` for the dot over
-the i and `tile` for the icon's field, and a geometry that names a role the
-caller did not supply throws instead of rendering an unpainted shape.
-`resolveLogoGeometry` no longer takes `idPrefix`: the geometry emits no DOM id,
-so two logos on a page cannot collide. `logoLockupGeometry` is removed;
-`logoWordmarkGeometry` and `logoMarkGeometry` remain and `logoIconGeometry`
-is added.
-
-## Tokens
-
-| Added | Why |
-| --- | --- |
-| `--nc-logo-dot` | The dot's colour, #1e3cff, and the only token a consumer paints it with. |
-| `--nc-logo-dot` under `.dark` | #4d6bff, so the dot does not sink into black. |
-
-A consumer that painted the logo with `--nc-primary` moves to `--nc-logo-dot`.
-The generated mode layer flips it under any dark ancestor, so one rendered form
-serves both grounds.
-
-## The name
-
-The company is nadicode, lowercase. Package names and domains are unchanged;
-the accessible name of every shipped logo file and both React adapters is now
-`nadicode`.

package/docs/migration/2.0.0.md

@@ -1,69 +0,0 @@
-# Migrating to `@nadicodeai/ui` 2.0.0
-
-This release makes elevation package-owned. `shadow-plugin` is gone from the
-dependency tree, and `@nadicodeai/ui/globals.css` declares the four elevation
-utilities itself over the `--nc-elevation-*` tokens that
-`@nadicodeai/design-system` 2.0.0 generates. The recipes are the plugin's own
-values, copied byte for byte, so nothing renders differently in either mode.
-
-`@nadicodeai/ui` 2.0.0 requires `@nadicodeai/design-system` 2.0.0; the two
-packages are released in lockstep.
-
-## Elevation utilities
-
-Rename every call site by the rung's role. Each utility paints the same
-`box-shadow` its predecessor did, with two differences in mechanics: the vendor
-utilities carried `!important` and tinted the falloff through
-`--tw-shadow-color`; `nc-elevation-*` are plain `box-shadow`, so a `shadow-*`
-or `hover:shadow-*` on the same element now wins where it used to lose, and no
-colour tints the falloff.
-
-| 1.x | 2.0.0 | Role |
-| --- | --- | --- |
-| `smooth-shadow-ring-md` | `nc-elevation-resting` | The card that sits on the page |
-| `smooth-shadow-ring-lg` | `nc-elevation-raised` | Active or selected work |
-| `smooth-shadow-ring-xl` | `nc-elevation-floating` | Menu, popover, tooltip, toast |
-| `smooth-shadow-ring-2xl` | `nc-elevation-modal` | Dialog, drawer, sheet |
-
-The plugin's other utilities have no replacement. `smooth-ring-*` and the
-`--smooth-ring-color` override are gone: each rung's optical ring is the last
-layer of its own recipe, black at 5% in light and white at 18% in dark, and a
-call site never repaints it. `nadicodeai/no-elevated-edge` still rejects a
-`border-*` or a second `ring-*` on the same target as an elevation.
-
-Consumers stop installing `shadow-plugin`. It was never a documented direct
-dependency; drop it if it was added anyway.
-
-## DTCG token paths
-
-The generated token file nests every group under a `core` or a `register`
-parent. A consumer reading
-`@nadicodeai/design-system/tokens/dtcg` by path changes
-`nadicode.<group>` to `nadicode.core.<group>`:
-
-| 1.x path | 2.0.0 path |
-| --- | --- |
-| `nadicode.color` | `nadicode.core.color` |
-| `nadicode.spacing` | `nadicode.core.spacing` |
-| `nadicode.rounded` | `nadicode.core.rounded` |
-| `nadicode.typography` | `nadicode.core.typography` |
-
-`nadicode.core` also gains `material`, `elevation`, and `motion`, and
-`nadicode.register` holds the per-surface data. The emitted CSS custom property
-and Tailwind `@theme` names are unchanged: only the authoring path moved. The
-`./tailwind` JSON export's `spacing` map now holds core only; the website's
-page-grammar geometry and the Portal's chip density are read from
-`nadicode.register.website.layout` and `nadicode.register.portal.density`.
-
-## Removed easing aliases
-
-`--nc-ease-bounce` and `--nc-ease-out` are removed. They were aliases of two
-curves that ship under their own names:
-
-| Removed | Use |
-| --- | --- |
-| `--nc-ease-bounce` | `--nc-ease-in-out-strong` |
-| `--nc-ease-out` | `--nc-ease-out-strong` |
-
-React call sites can also write the Tailwind form, `ease-nc-in-out-strong` and
-`ease-nc-out-strong`.

package/docs/migration/6.0.0.md

@@ -1,30 +0,0 @@
-# Migrating to `@nadicodeai/ui` 6.0.0
-
-This release removes contract entries that nothing rendered. `@nadicodeai/ui`
-6.0.0 requires `@nadicodeai/design-system` 6.0.0; the two packages are
-released in lockstep.
-
-## Removed colour tokens
-
-| Removed | Use instead |
-| --- | --- |
-| `--nc-flag-red` | `--nc-identity-rosso` for the identity red, `--nc-error` for validation feedback. Same hex as both. |
-| `--nc-background-100`, `--nc-background-200` | `--nc-canvas`, `--nc-canvas-soft`. Same hex. |
-| `--nc-dark-cyan`, `--nc-dark-cyan-soft`, `--nc-dark-cyan-deep` | No replacement; the family had no light counterpart, no prose, and no consumer. |
-| `register.nadia.color.*.medallion` | No replacement; the first-run medallion no longer exists. |
-
-`register.nadia.color.dark.destructive` now aliases `dark-error` with
-`dark-on-primary` text, the same pair the foundation's `.dark` shadcn map
-already resolves `destructive` to. It aliased the removed `flag-red` with
-white text.
-
-## Removed Nadia asset routes
-
-`./assets/nadia-ordered-points`, `./assets/nadia-triangulated-wire` and
-`./assets/nadia-irregular-particles` are gone. `./assets/nadia-solid-surface`
-is the one approved master and the one route. The authored files stay in
-`brand/visual-design/images/nadia/material-states/transparent/`.
-
-## Removed layout entry
-
-`article-frame` is no longer documented; it never had CSS.

package/docs/migration/9.0.0.md

@@ -1,35 +0,0 @@
-# Migrating to `@nadicodeai/ui` 9.0.0
-
-Every Agent is now an `AgentOrb`, Nadia included. This release removes the
-other Agent identities. `@nadicodeai/ui` 9.0.0 requires
-`@nadicodeai/design-system` 9.0.0; the two packages are released in lockstep.
-
-## Removed components
-
-| Removed | Use instead |
-| --- | --- |
-| `components/forma-avatar` (`FormaAvatar`) | `components/agent-orb` (`AgentOrb`). Nadia is `form="nadia"`. |
-| `components/forma-appearance` (`resolveAppearance`, `shapeFor`, `defaultShape`, `formaColorValues`) | `components/agent-orb-appearance` (`resolveAgentOrb`, `shapeForOrb`, `defaultAgentOrbShape`, `agentOrbColorValues`, `agentOrbColorTokens`) |
-| `components/agent-visual` (`AgentVisual`) | `AgentOrb` |
-
-`resolveAgentOrb` reads every stored `forma:` spelling, the five launch role
-names included, as a distinct orb, so a stored look keeps drawing until
-someone changes it. Stored colours map to cobalto, verde, rosso and arancio;
-giallo, avorio and unknown values draw the inherited text colour. Store new
-choices as `orb:<form>` and the colour's hex, as
-[`agent-orb.md`](../agent-orb.md#stored-appearance) specifies.
-
-## Added
-
-`AgentOrb` takes `form="nadia"`: her ribbon, striped azzurro, verde, the orb's
-pigment and rosso. `--nc-identity-azzurro` is the design-system token for her
-azzurro stripe.
-
-## Removed tokens and assets
-
-| Removed | Use instead |
-| --- | --- |
-| `--nc-forma-visor`, `--nc-forma-bezel`, `--nc-forma-eye`, `--nc-forma-avorio`, `--nc-forma-sabbia` | No replacement; only Forma painted them. |
-| `@nadicodeai/design-system/assets/nadia-solid-surface` | `<AgentOrb form="nadia" />`. The portrait is retired as Nadia's look; the file stays in the brand archive. |
-
-The package no longer depends on `@paper-design/shaders`.

package/docs/migration/base-ui-migration.md

@@ -1,62 +0,0 @@
-# Base UI Migration
-
-`@nadicodeai/ui` now uses Base UI as its active shadcn primitive base.
-
-Current invariants:
-
-- `components.json` uses `base-nova`, and `npx shadcn@latest info --json` should report `base: "base"`.
-- Package source must not import `radix-ui`, `@radix-ui/*`, or `vaul`.
-- `cmdk` is allowed only for the stock shadcn Command component while the current `base-nova` registry declares it.
-- `packages/ui/package.json` must not depend on `radix-ui`, `@radix-ui/react-use-controllable-state`, or `vaul`.
-- Website and portal Next config must optimize `@base-ui/react`, not `radix-ui`.
-- Public shadcn primitive usage follows the current Base UI registry API. Base UI composition uses `render`; do not add package-local `asChild` adapters for registry-owned primitives.
-
-## Migration Catalog
-
-Direct Base-backed shadcn replacements:
-
-- `accordion`, `alert-dialog`, `aspect-ratio`, `avatar`, `checkbox`, `collapsible`, `context-menu`, `dialog`, `drawer`, `dropdown-menu`, `hover-card`, `label`, `menubar`, `navigation-menu`, `popover`, `progress`, `radio-group`, `scroll-area`, `select`, `separator`, `sheet`, `slider`, `switch`, `tabs`, `toggle`, `toggle-group`, and `tooltip`.
-
-Package-owned helpers:
-
-- Wrapper-only components (`badge`, `breadcrumb`, `button-group`, `item`, `sidebar`, `form`) compose through Base UI's `useRender`/`mergeProps` directly; the transitional `src/lib/slot.tsx` and `src/lib/base-render.tsx` shims are removed.
-
-Removed non-shadcn Radix carriers:
-
-- `command` stays backed by shadcn's stock `cmdk` implementation while the `base-nova` registry declares that dependency.
-- `drawer` replaces `vaul` with Base UI Drawer.
-
-## Breaking in 0.5.0
-
-`@nadicodeai/ui@0.5.0` removes the Radix-era compatibility layer that 0.4.x
-carried. Consumers upgrading from 0.4.x must migrate:
-
-- `asChild` is removed on every primitive (Button, triggers, closes, menu
-  items). Use Base UI's `render` prop instead; when the rendered element is
-  not a native `<button>`, also pass `nativeButton={false}` (for example
-  `<Button nativeButton={false} render={<a href="…" />}>`).
-- `DropdownMenuItem` / `ContextMenuItem` / `MenubarItem` no longer accept
-  `onSelect`. Use `onClick`, and `closeOnClick={false}` to keep the menu open
-  (replaces the `onSelect` + `event.preventDefault()` pattern).
-- `PromptInputActionAddScreenshot`'s `onSelect` prop is renamed `onClick`.
-- `Accordion` and `ToggleGroup` drop `type="single" | "multiple"` and string
-  values. Values are always arrays; pass `multiple` for multi-select.
-- `TooltipProvider` drops the `delayDuration` alias — use `delay`. HoverCard
-  open/close delays live on `HoverCardTrigger` (`delay` / `closeDelay`), not
-  the root.
-- `Drawer` drops the vaul-era `direction` / `activeSnapPoint` /
-  `setActiveSnapPoint` aliases — use Base UI's `swipeDirection` /
-  `snapPoint` / `onSnapPointChange`.
-- `DirectionProvider` drops the `dir` alias — use `direction`.
-- `NavigationMenuViewport` and `PopoverAnchor` are no longer exported; they
-  have no stock base-nova equivalent.
-- `CollapsibleContent` / disclosure panels drop the `forceMount` alias — use
-  Base UI's `keepMounted`.
-
-Verification:
-
-```bash
-npm run build -w @nadicodeai/ui
-npm run test -w @nadicodeai/ui
-rg 'radix-ui|@radix-ui|vaul' packages/ui/src packages/ui/package.json apps/website/next.config.ts apps/portal/next.config.ts
-```

package/docs/model-identity.md

@@ -1,18 +0,0 @@
-# Model identity compatibility adapter
-
-`ModelIdentity` is a compatibility adapter for consumers that still pass one
-`provider/model` string. It derives the author prefix and delegates all visual
-rendering to the canonical `ModelMark`; it has no provider registry, generated
-artwork, or presentation of its own. Unknown authors therefore receive the
-same neutral tile as every other `ModelMark` consumer.
-
-```tsx
-import { ModelIdentity } from "@nadicodeai/ui/components/model-identity";
-
-<ModelIdentity model="anthropic/claude-sonnet-5" />;
-```
-
-New consumers should import `ModelMark` and pass its `author` and `name`
-properties directly. The adapter keeps the older `model`, `label`, and
-`markSize` call shape while consumers migrate; a string `label` becomes the
-canonical model name, otherwise the model segment after the slash is shown.

package/docs/product-compositions.md

@@ -1,96 +0,0 @@
-# Product Compositions
-
-Shared product compositions own repeatable presentation and interaction. Consumers bind routing, persistence, permissions, and product copy. See the [component contract](contract.md) for each family's ownership.
-
-Check first-party shadcn or assistant-ui registry patterns before adding a
-composition. Once adapted, reuse its maintained owner; do not assemble the same
-registry example again for each page.
-
-Import components through the wildcard component subpath after build:
-
-```tsx
-import { SettingsSection } from "@nadicodeai/ui/components/settings-section"
-```
-
-Fixtures live in:
-
-- [`../tests/guards/product-compositions.test.ts`](../tests/guards/product-compositions.test.ts)
-- [`../tests/guards/product-compositions-ssr.test.ts`](../tests/guards/product-compositions-ssr.test.ts)
-- [`../src/components/settings-section.test.tsx`](../src/components/settings-section.test.tsx)
-
-## Boundaries
-
-| Component | Package owns | Consumer owns |
-| --- | --- | --- |
-| `SettingsSection` / `SettingsField` | Header, divided save footer, field layout, labels, descriptions, errors, and control associations. | Form state, validation, submission, persistence, settings taxonomy, and save/cancel behavior. |
-| `FeedbackState` | Shared empty, loading, saving, error, permission, offline, no-results, and fatal state presentation. | Recovery actions, retry behavior, permission escalation, app-specific state language. |
-
-## Collection and command recipes
-
-Portal's [`DataTable`](../../../apps/portal/src/components/kit/data-table.tsx) is
-the existing app owner for collection interaction, URL state, and registry
-behavior. It composes the shared `Table` and `TableDetailRow` with TanStack
-Table, following the [shadcn Data Table guide](https://ui.shadcn.com/docs/components/base/data-table)
-and the `@shadcn/dashboard-01` table block. The shared row owns compact fact
-geometry; a caller supplies its labels and values. Keep Portal's adapter for
-its existing consumers instead of introducing a second package table API.
-
-The shared [`command`](../src/components/command.tsx) component includes
-`CommandDialog`, as the [shadcn Command guide](https://ui.shadcn.com/docs/components/base/command)
-documents. A product composes its commands there and owns search data,
-selection effects, shortcuts, routing, and permission checks. The Portal
-command dialog is the current app owner for Portal navigation commands.
-
-## SettingsSection
-
-Use `SettingsSection` and `SettingsField` for horizontal settings rows that need consistent label, description, error, and control alignment.
-
-```tsx
-<SettingsSection
-  title="Workspace defaults"
-  description="Shared defaults for agent work."
-  footer={<Button type="submit">Save</Button>}
->
-  <SettingsField
-    id="review-window"
-    label="Review window"
-    description="How long approvals stay visible."
-    error={reviewWindowError}
-    invalid={Boolean(reviewWindowError)}
-  >
-    {({ controlProps }) => (
-      <Input {...controlProps} value={reviewWindow} onChange={onReviewWindowChange} />
-    )}
-  </SettingsField>
-</SettingsSection>
-```
-
-| Prop | Purpose |
-| --- | --- |
-| `title` / `description` / `actions` | Section header content and right-side action slot. |
-| `footer` | Local Save/Cancel controls and completion feedback. The owning form wraps the section. |
-| `id` / `label` | Required field identity and accessible label. |
-| `description` / `error` / `invalid` | Field helper text, error text, and invalid state. |
-| `children` | A render function receives `controlProps` for the real control in server and client components. |
-
-Spread `controlProps` onto the real control. SettingsField invokes the callback
-before rendered children cross any client boundary; it does not forward the
-callback to a client component. The [contract](contract.md) owns the field's
-accessibility and state guarantees.
-
-## FeedbackState
-
-Use `FeedbackState` when a surface needs a standard state panel outside an app-owned shadcn table adaptation.
-
-```tsx
-<FeedbackState
-  status="offline"
-  title="Connection paused"
-  description="Reconnect before continuing with this agent session."
-  actions={<ReconnectButton />}
-/>
-```
-
-Supported statuses: `empty`, `loading`, `saving`, `error`, `permission`, `offline`, `no-results`, and `fatal`.
-
-Accessibility: loading and saving states render with polite status semantics. Error, permission, offline, and fatal states render as alerts.

package/docs/product-sections.md

@@ -1,200 +0,0 @@
-# Product Sections
-
-U5 adds shared shell skeletons, plugin containment, installer states, and automation/settings sections. These components are presentational only. Consumers own routing, persistence, server actions, runtime adapters, permission decisions, retries, plugin trust, installer side effects, analytics, and product-specific page copy.
-
-Import components through the existing component subpath after build:
-
-```tsx
-import { DashboardShell } from "@nadicodeai/ui/components/dashboard-shell"
-import { PluginSlotBoundary } from "@nadicodeai/ui/components/plugin-slot-boundary"
-```
-
-Fixtures live in:
-
-- [`../tests/guards/product-sections.test.ts`](../tests/guards/product-sections.test.ts)
-- [`../tests/guards/product-sections-ssr.test.ts`](../tests/guards/product-sections-ssr.test.ts)
-
-## Boundaries
-
-| Component | Package owns | Consumer owns |
-| --- | --- | --- |
-| `DashboardShell` | Responsive slot layout, sidebar/header/content/inspector regions, mobile sidebar trigger, focusable shell structure, overflow containment. | Route state, nav definitions, page data, permission filtering, tenant/workspace context, page-specific copy. |
-| `DesktopAppShell` | Titlebar/statusbar framing, activity rail, primary/secondary/inspector panes, resizable panel composition, overflow containment. | Desktop runtime, window controls, route selection, IPC, command execution, local persistence. |
-| `InstallerShell` | Welcome/progress/success/failure presentation, progress display, step list, feedback-state composition. | Installer state machine, platform checks, downloads, retries, recovery behavior, logs. |
-| `PluginSlotBoundary` | Visible plugin content boundary, permission badges, warning/error alerts, contained overflow, redaction guidance. | Plugin runtime, trust decisions, install/remove actions, grants, sandbox policy, secrets. |
-| `AutomationSection` | Automation row layout, status badges, enable switch placement, empty state. | Automation definitions, scheduling, execution, persistence, permission rules. |
-| `ProviderSettings` | Provider setting rows built on `SettingsSection` and `SettingsField`. | Provider list, validation, saving, rate limits, billing or policy behavior. |
-| `McpServerSettings` | MCP server rows, status badges, enable switch placement, field semantics. | Server discovery, connection checks, grants, persistence, tool execution. |
-| `EnvironmentVariablesSettings` | Variable name rows and redacted state display. | Secret storage, reveal controls, value validation, rotation, syncing. |
-
-## DashboardShell
-
-Use `DashboardShell` when a web/admin surface needs shared app chrome without the package owning navigation.
-
-```tsx
-<DashboardShell
-  sidebar={<WorkspaceNav />}
-  sidebarHeader={<WorkspaceSwitcher />}
-  sidebarFooter={<AccountMenu />}
-  header={<PageHeading />}
-  headerActions={<RunAction />}
-  inspector={<PermissionSummary />}
->
-  <AgentQueue />
-</DashboardShell>
-```
-
-| Prop | Purpose |
-| --- | --- |
-| `sidebar` | Sidebar content slot. Consumers pass nav items or any compatible sidebar content. |
-| `header` / `headerActions` | Top chrome slots. The package adds the mobile navigation trigger. |
-| `children` | Main content region. |
-| `inspector` | Optional right-side inspector that stacks below content on smaller screens. |
-| `sidebarHeader` / `sidebarFooter` | Optional sidebar framing slots. |
-| `sidebarSide` / `sidebarVariant` / `sidebarCollapsible` | Pass-through shell options over the existing sidebar primitive. |
-
-Accessibility: the shell exposes labeled content and inspector regions. The mobile trigger has an accessible label and the underlying sidebar primitive preserves keyboard access and collapsed labels.
-
-## DesktopAppShell
-
-Use `DesktopAppShell` for desktop-shaped layouts where the consumer owns runtime behavior.
-
-```tsx
-<DesktopAppShell
-  title="Nadia desktop"
-  activityRail={<ActivityButtons />}
-  secondaryPane={<RunContext />}
-  inspectorRail={<Inspector />}
-  statusbar={<StatusLine />}
->
-  <Workspace />
-</DesktopAppShell>
-```
-
-| Prop | Purpose |
-| --- | --- |
-| `title` / `titlebar` / `titlebarActions` | Titlebar slots. `titlebar` can replace the default title row. |
-| `activityRail` | Left rail slot for mode buttons or app tools. |
-| `children` | Primary pane. |
-| `secondaryPane` | Optional resizable middle pane. |
-| `inspectorRail` | Optional resizable inspector pane. |
-| `statusbar` | Bottom status slot. |
-| `primaryPaneSize` / `secondaryPaneSize` / `inspectorPaneSize` | Initial resizable panel sizes. |
-
-The component does not assume browser routing, desktop IPC, or command execution.
-
-## InstallerShell
-
-Use `InstallerShell` for installer or setup flows with an app-owned state machine.
-
-```tsx
-<InstallerShell
-  state="progress"
-  title="Installing"
-  description="Preparing the local workspace."
-  progressValue={62}
-  steps={[
-    { id: "package", label: "Prepare package", status: "complete" },
-    { id: "settings", label: "Apply settings", status: "running" },
-  ]}
-  actions={<CancelButton />}
-/>
-```
-
-Supported states: `welcome`, `progress`, `success`, and `failure`.
-
-Step statuses: `pending`, `running`, `complete`, and `error`.
-
-The shell uses `FeedbackState` for the primary state message. Consumers provide the installer state, recovery actions, and side effects.
-
-## PluginSlotBoundary
-
-Use `PluginSlotBoundary` around extension or plugin-rendered content. It makes the plugin boundary visible and keeps overflow contained.
-
-```tsx
-<PluginSlotBoundary
-  title="Planner plugin"
-  status="warning"
-  permissions={[
-    { id: "files", label: "Read files", level: "review" },
-    { id: "network", label: "Network blocked", level: "denied" },
-  ]}
-  warning="Review plugin scope before granting access."
->
-  <PluginPreview />
-</PluginSlotBoundary>
-```
-
-Supported statuses: `ready`, `warning`, `error`, and `disabled`.
-
-Permission levels: `safe`, `review`, `risk`, and `denied`.
-
-Redaction rule: package fixtures and examples may show synthetic names, variable names, and redacted placeholders only. They must not include secret values, environment variable values, raw terminal output, user memory, or hidden reasoning.
-
-## AutomationSection
-
-Use `AutomationSection` for a list of app-owned automations.
-
-```tsx
-<AutomationSection
-  title="Automation runs"
-  automations={[
-    {
-      id: "briefing",
-      title: "Briefing preparation",
-      description: "Drafts a review packet.",
-      status: "running",
-      enabled: true,
-      toggleLabel: "Toggle briefing preparation",
-    },
-  ]}
-  onAutomationEnabledChange={setAutomationEnabled}
-/>
-```
-
-Supported statuses: `ready`, `running`, `paused`, `error`, and `disabled`.
-
-The callback reports a requested toggle. It does not save, schedule, retry, or execute anything.
-
-## Settings Patterns
-
-`ProviderSettings`, `McpServerSettings`, and `EnvironmentVariablesSettings` compose `SettingsSection` and `SettingsField` so settings rows share label, description, error, invalid, disabled, and control alignment behavior.
-
-```tsx
-<ProviderSettings
-  fields={[
-    {
-      id: "provider",
-      label: "Provider",
-      description: "Displayed provider label.",
-      value: "Nadia synthetic provider",
-    },
-  ]}
-/>
-
-<McpServerSettings
-  servers={[
-    {
-      id: "docs",
-      label: "Docs server",
-      description: "Read-only documentation context.",
-      status: "connected",
-      enabled: true,
-    },
-  ]}
-/>
-
-<EnvironmentVariablesSettings
-  variables={[
-    {
-      id: "model-key",
-      name: "NADIA_MODEL_KEY",
-      description: "Configured by the consuming app.",
-      state: "configured",
-      required: true,
-    },
-  ]}
-/>
-```
-
-Environment variable rows intentionally render names and redacted state only. They do not accept or display actual values.