@nadicodeai/ui 0.21.0 → 1.0.0

package/dist/styles/globals.css

@@ -14,10 +14,12 @@
 @layer tokens, theme, reset, base, foundation, motion, layout, primitives, components, utilities;
 
 @import "tailwindcss";
+@import "shadow-plugin";
 @import "tw-animate-css";
+@import "tw-shimmer";
+@import "@assistant-ui/react-markdown/styles/dot.css";
 @import "./shadcn.tailwind.css";
 @import "@nadicodeai/design-system/css";
-@import "@xyflow/react/dist/style.css" layer(components);
 
 /*
  * Tailwind v4's dark: variant defaults to an OS media query. Match shadcn's
@@ -52,218 +54,30 @@
   }
 }
 
-/*
- * The canonical design-system module owns raw --nc-* mode aliases, semantic
- * roles, and their Tailwind utility bridge for both root and scoped `.dark`
- * surfaces. This adapter owns only narrow technology integration such as ANSI
- * class translation below.
- */
-
-/*
- * The design-system CSS components (.nc-chat-thread, .nc-chat-bubble-*,
- * .nc-artifact-preview, .nc-approval-gate, .nc-tool-call-trace,
- * .nc-usage-meter, .nc-run-timeline, .nc-memory-item, .nc-handoff-banner, …)
- * paint from the raw --nc-canvas/ink/body/line/canvas-soft/muted/warning
- * palette. The generated mode layer remaps that surface palette alongside every
- * other authored dark pair, so nc-* CSS components need no local mode selectors.
- */
-
-/*
- * ansi-to-react emits stable classes when Terminal enables `useClasses`.
- * Terminal is an intentionally fixed-dark technology surface, so this adapter
- * maps those protocol classes directly to canonical dark design tokens. It does
- * not declare a parallel product-token hierarchy.
- */
-[data-slot="terminal"] .ansi-black-fg {
-  color: var(--nc-dark-muted);
-}
-
-[data-slot="terminal"] .ansi-red-fg {
-  color: var(--nc-dark-error);
-}
-
-[data-slot="terminal"] .ansi-green-fg {
-  color: var(--nc-dark-success);
-}
-
-[data-slot="terminal"] .ansi-yellow-fg {
-  color: var(--nc-dark-warning);
-}
-
-[data-slot="terminal"] .ansi-blue-fg {
-  color: var(--nc-dark-info);
-}
-
-[data-slot="terminal"] .ansi-magenta-fg {
-  color: var(--nc-dark-chart-6);
-}
-
-[data-slot="terminal"] .ansi-cyan-fg {
-  color: var(--nc-dark-cyan);
-}
-
-[data-slot="terminal"] .ansi-white-fg {
-  color: var(--nc-dark-body);
-}
-
-[data-slot="terminal"] .ansi-bright-black-fg {
-  color: var(--nc-dark-body);
-}
-
-[data-slot="terminal"] .ansi-bright-red-fg {
-  color: var(--nc-dark-error-deep);
-}
-
-[data-slot="terminal"] .ansi-bright-green-fg {
-  color: var(--nc-dark-link-deep);
-}
-
-[data-slot="terminal"] .ansi-bright-yellow-fg {
-  color: var(--nc-dark-warning-deep);
-}
-
-[data-slot="terminal"] .ansi-bright-blue-fg {
-  color: var(--nc-dark-info-deep);
-}
-
-[data-slot="terminal"] .ansi-bright-magenta-fg {
-  color: var(--nc-dark-chart-seq-3);
-}
-
-[data-slot="terminal"] .ansi-bright-cyan-fg {
-  color: var(--nc-dark-cyan-soft);
-}
-
-[data-slot="terminal"] .ansi-bright-white-fg {
-  color: var(--nc-dark-ink);
-}
-
-[data-slot="terminal"] .ansi-black-bg {
-  background-color: var(--nc-dark-canvas);
-}
-
-[data-slot="terminal"] .ansi-red-bg {
-  background-color: var(--nc-dark-error);
-}
-
-[data-slot="terminal"] .ansi-green-bg {
-  background-color: var(--nc-dark-success);
-}
-
-[data-slot="terminal"] .ansi-yellow-bg {
-  background-color: var(--nc-dark-warning);
-}
-
-[data-slot="terminal"] .ansi-blue-bg {
-  background-color: var(--nc-dark-info);
-}
-
-[data-slot="terminal"] .ansi-magenta-bg {
-  background-color: var(--nc-dark-chart-6);
-}
-
-[data-slot="terminal"] .ansi-cyan-bg {
-  background-color: var(--nc-dark-cyan);
-}
-
-[data-slot="terminal"] .ansi-white-bg {
-  background-color: var(--nc-dark-body);
-}
-
-[data-slot="terminal"] .ansi-bright-black-bg {
-  background-color: var(--nc-dark-body);
-}
-
-[data-slot="terminal"] .ansi-bright-red-bg {
-  background-color: var(--nc-dark-error-deep);
-}
-
-[data-slot="terminal"] .ansi-bright-green-bg {
-  background-color: var(--nc-dark-link-deep);
-}
-
-[data-slot="terminal"] .ansi-bright-yellow-bg {
-  background-color: var(--nc-dark-warning-deep);
-}
-
-[data-slot="terminal"] .ansi-bright-blue-bg {
-  background-color: var(--nc-dark-info-deep);
-}
-
-[data-slot="terminal"] .ansi-bright-magenta-bg {
-  background-color: var(--nc-dark-chart-seq-3);
-}
-
-[data-slot="terminal"] .ansi-bright-cyan-bg {
-  background-color: var(--nc-dark-cyan-soft);
-}
-
-[data-slot="terminal"] .ansi-bright-white-bg {
-  background-color: var(--nc-dark-ink);
-}
-
-[data-slot="terminal"] .ansi-black-bg:not([class*="-fg"]) {
-  color: var(--nc-dark-ink);
-}
-
-[data-slot="terminal"]
-  :is(
-    .ansi-red-bg,
-    .ansi-green-bg,
-    .ansi-yellow-bg,
-    .ansi-blue-bg,
-    .ansi-magenta-bg,
-    .ansi-cyan-bg,
-    .ansi-white-bg,
-    .ansi-bright-black-bg,
-    .ansi-bright-red-bg,
-    .ansi-bright-green-bg,
-    .ansi-bright-yellow-bg,
-    .ansi-bright-blue-bg,
-    .ansi-bright-magenta-bg,
-    .ansi-bright-cyan-bg,
-    .ansi-bright-white-bg
-  ):not([class*="-fg"]) {
-  color: var(--nc-dark-canvas);
-}
-
-[data-nc-code-block-body] {
-  background-color: var(--shiki-code-block-light-bg, var(--background));
-  color: var(--shiki-code-block-light-fg, var(--foreground));
-}
+@layer components {
+  .nc-glass-control {
+    background: color-mix(in srgb, var(--popover) var(--nc-material-glass-opacity), transparent);
+    backdrop-filter: blur(var(--nc-material-glass-blur))
+      saturate(var(--nc-material-glass-saturation));
+  }
 
-.dark [data-nc-code-block-body] {
-  background-color: var(
-    --shiki-code-block-dark-bg,
-    var(--shiki-code-block-light-bg, var(--background))
-  );
-  color: var(--shiki-code-block-dark-fg, var(--shiki-code-block-light-fg, var(--foreground)));
-}
+  .nc-toast {
+    border: 0 !important;
+  }
 
-[data-nc-code-token] {
-  background-color: var(--shiki-code-token-light-bg, transparent);
-  color: var(--shiki-code-token-light-color, var(--foreground));
-  font-style: var(--shiki-code-token-light-font-style, normal);
-  font-weight: var(--shiki-code-token-light-font-weight, normal);
-  text-decoration: var(--shiki-code-token-light-text-decoration, none);
+  @media (prefers-reduced-transparency: reduce) {
+    .nc-glass-control {
+      background: var(--popover);
+      backdrop-filter: none;
+    }
+  }
 }
 
-.dark [data-nc-code-token] {
-  background-color: var(--shiki-code-token-dark-bg, var(--shiki-code-token-light-bg, transparent));
-  color: var(--shiki-code-token-dark-color, var(--shiki-code-token-light-color, var(--foreground)));
-  font-style: var(
-    --shiki-code-token-dark-font-style,
-    var(--shiki-code-token-light-font-style, normal)
-  );
-  font-weight: var(
-    --shiki-code-token-dark-font-weight,
-    var(--shiki-code-token-light-font-weight, normal)
-  );
-  text-decoration: var(
-    --shiki-code-token-dark-text-decoration,
-    var(--shiki-code-token-light-text-decoration, none)
-  );
-}
+/*
+ * The canonical design-system module owns raw --nc-* mode aliases, semantic
+ * roles, and their Tailwind utility bridge for both root and scoped `.dark`
+ * surfaces.
+ */
 
 .toaster [data-sonner-toast][data-styled="true"] [data-description] {
   color: var(--muted-foreground);
@@ -292,4 +106,5 @@
 }
 
 @source "../components";
+@source "../internal";
 @source "../lib";

package/docs/agents/nadicodeai-ui.md

@@ -10,22 +10,20 @@ authoritative interfaces without carrying a second copy of them.
 - Package/consumer boundary, styling invariants, admission rules, and
   accessibility: [`../contract.md`](../contract.md).
 - Current component modules and named exports: `src/components/`,
-  `src/index.ts`, `src/ai-elements.ts`, and `package.json` in a source checkout;
+  `src/index.ts` and `package.json` in a source checkout;
   package exports and declarations in an installed package.
-- Import examples, form-stack guidance, `SeamGrid` usage, and live shadcn/AI
-  Elements discovery commands: [`../../README.md`](../../README.md).
+- Import examples, form-stack guidance, `SeamGrid` usage, and live shadcn and
+  assistant-ui discovery commands: [`../../README.md`](../../README.md).
 
 Do not maintain component, chart, form, section, export, or registry inventories
 in agent prose. Follow the owning source or document above.
 
 ## Product work
 
-- Agent work surfaces: [`../agent-work-surfaces.md`](../agent-work-surfaces.md).
+- Agent UI ownership: [`../contract.md`](../contract.md).
 - Product compositions and sections:
   [`../product-compositions.md`](../product-compositions.md) and
   [`../product-sections.md`](../product-sections.md).
-- Terminal and TUI semantics:
-  [`../terminal-tui-semantics.md`](../terminal-tui-semantics.md).
 
 Routes, persistence, authentication, server state, runtime adapters,
 permissions, analytics, and product-specific copy stay in the consuming app.
@@ -38,5 +36,7 @@ Use shadcn MCP or the CLI live; never commit an upstream registry inventory.
 the committed package surface. Preview upstream changes before applying them;
 do not overwrite maintained source without explicit maintainer direction.
 
-The package [`AGENTS.md`](../../AGENTS.md) maps scoped commands. Repository
-completion is the root `npm run quality` gate.
+The package [`AGENTS.md`](../../AGENTS.md) maps scoped commands. Proof escalates
+by the ladder in the repository's root `AGENTS.md` "Commands": this workspace's
+`check` and `test`, then the root `npm run check` and `npm run test` when the
+diff reaches other workspaces.

package/docs/component-classification.md

@@ -2,7 +2,7 @@
 
 This file records the ownership class for U4 product compositions. The package may render standard product UI, but consuming apps own app behavior, data, persistence, and product-specific promises.
 
-If first-party shadcn or AI Elements registry source already covers the same
+If first-party shadcn or assistant-ui registry source already covers the same
 generic product UI, do not add a parallel NadicodeAI package API. Use the
 registry item in the consuming app and adapt it there with app-owned data,
 copy, and behavior.

package/docs/consuming-cross-repo.md

@@ -17,10 +17,16 @@ npm install @nadicodeai/ui@<exact-version> react@^19 react-dom@^19 tailwindcss@^
 dependency exactly. A React consumer does not declare that dependency directly
 just to use UI components or the UI stylesheet.
 
+The package installs its Agent UI implementation exactly. Consumers import
+presentation, runtime primitives, providers, hooks, and types through
+`@nadicodeai/ui/agents`; they do not install or import assistant-ui packages
+directly. A protocol-specific runtime adapter remains a direct consumer
+dependency because the application owns transport and message state.
+
 Declare `@nadicodeai/design-system` directly only when the app intentionally
-uses a separate public design-system API, such as a font/logo asset, the static
-CSS interface for a separate non-React surface, or the optional agent-chat
-enhancer. Pin that direct dependency to the version required by the installed
+uses a separate public design-system API, such as a font/logo asset or the
+static CSS interface for a separate non-React surface. Pin that direct
+dependency to the version required by the installed
 UI release:
 
 ```bash
@@ -36,7 +42,9 @@ import "@nadicodeai/ui/globals.css";
 ```
 
 `@nadicodeai/ui/globals.css` is the complete React style interface. It composes
-Tailwind v4, shadcn, and the complete design-system CSS module.
+Tailwind v4, shadcn, the exact smooth-shadow plugin, and the complete
+design-system CSS module. Consumers do not import `shadow-plugin`, restyle its
+optical ring, or add a second border/ring to package-owned elevated roots.
 Do not import `@nadicodeai/design-system/css`, generated theme files, or CSS
 partials beside it. The package declares its own built component sources; Tailwind's
 normal automatic detection covers the consumer application. The app still owns

package/docs/contract.md

@@ -9,20 +9,96 @@ The normative invariants for the `@nadicodeai/ui` package: what may live here, h
 - **Components inherit one complete React style interface.** `@nadicodeai/ui/globals.css` composes every style dependency owned by this package, including the complete design-system CSS module. Components carry no theme of their own, and React callers do not compose design-system stylesheets or partials beside it. Installation and source-scanning setup live in the [consumer setup guide](consuming-cross-repo.md).
 - **Design-system geometry remains the foundation.** React components compose the kept `nc-*` page grammar and display CSS components; they do not redefine frame math, marker placement, token values, or raw CSS geometry. Use parent-paints-plus-gap for bordered cell grids and keep every visible seam single-owner (doctrine home: `design-system/DESIGN.md` "## Layout").
 
+### Material surfaces
+
+`shadow-plugin@1.2.7` enters once through `@nadicodeai/ui/globals.css`. Its
+integrated optical ring is part of every elevated shadow and remains at the
+vendor default, including the 18% white dark-mode ring. Never pair a
+`smooth-shadow-ring-*` root with `border-*`, a separate `ring-*`,
+`smooth-ring-*`, or a local `--smooth-ring-color` override.
+
+Physical role, not content importance, chooses depth:
+
+- `Card surface="resting"` (the default) uses `smooth-shadow-ring-md`.
+- `Card surface="raised"` uses `smooth-shadow-ring-lg`; active or selected
+  work chooses it explicitly.
+- `Card surface="plain"` is the explicit structural/auth/website escape and
+  carries no elevation.
+- Tooltip, menu, popover, select, combobox, navigation popup, hover card,
+  chart tooltip, and toast roots own `smooth-shadow-ring-xl` internally.
+- Dialog, alert dialog, drawer, and sheet roots own
+  `smooth-shadow-ring-2xl` internally.
+
+All solid surfaces use the one semantic fill. Dark mode therefore stays true
+black; depth never comes from progressively greyer cards. Because the plugin
+owns `box-shadow` with `!important`, focus on an elevated root uses the
+canonical outline rather than another box-shadow ring.
+
+`GlassControl` is the only shared glass material. It is control chrome,
+using `shape="control"` for compact floating controls and `shape="bar"` for
+full-width header chrome. Cards and modal primitives continue to own page
+content, KPIs, tables, inspectors, and dialog bodies. Reduced transparency
+falls back to the same solid floating surface.
+
+`Empty` makes containment explicit with `scope="page" | "region" | "card"`.
+Page and region states own one opaque dashed boundary. A Card-scoped Empty is
+transparent and unframed because the Card already owns containment.
+
+## Status Vocabulary
+
+`Badge` is the product's only status carrier. It ships five semantic tone
+variants — `gray`, `green`, `red`, `amber`, `blue` — each one soft/deep pair
+from the generated tokens (`--nc-canvas-soft-2`/`--nc-body`,
+`--nc-link-bg-soft`/`--nc-link-deep`, `--nc-error-soft`/`--nc-error-deep`,
+`--nc-warning-soft`/`--nc-warning-deep`, `--nc-info-soft`/`--nc-info-deep`), so
+a status clears AA in both modes without a call site painting anything. A status
+badge carries a mark in the existing icon slot beside its word, because colour
+must never be the only thing that says what the status is; the mark is
+`aria-hidden`, and the word is the accessible status. The tones are variants,
+not utilities, precisely so `nadicodeai/no-shadcn-appearance-override` and
+`nadicodeai/no-raw-color-utility` can keep them here.
+
+What this package does not own: which statuses exist, which tone and which mark
+each value takes, and the words. Those are the consuming app's domain — the
+Portal maps them in one kit module and nothing else picks a status colour. The
+design-system side of the decision, and why the retired CSS status grammars are
+gone, is [`design-system/DESIGN.md`, "## Status Vocabulary"](../../../design-system/DESIGN.md#status-vocabulary).
+
 ## Package Shape Invariants
 
 - **Source-authored, built package.** Components are authored as shadcn-style source in `src/`, then emitted to `dist/` for consumption by other apps. Package exports must point at built JS, declarations, and CSS, never raw `src/*.tsx`, and `npm pack --dry-run` must include only intentional consumer artifacts.
-- **Package surface is source-backed.** `src/components/` is intentionally flat shadcn-style source. Do not document folders or package namespaces that do not exist, and do not add top-level exports for recipes, blocks, agent, or terminal groupings unless a later package API decision adds concrete source, built files, docs, and tests in the same change.
-- **shadcn and AI Elements are package surface.** Installed shadcn and AI Elements modules under `src/components/` are intentional ready-to-use exports. The source tree owns the component inventory; `src/index.ts` and `src/ai-elements.ts` own the barrels, and `package.json` owns the public export shape. Guards derive the consumer surface from those owners. Prose routes to them instead of maintaining another component list.
+- **Package surface is source-backed.** Public components stay flat under `src/components/`. Reviewed registry source under `src/internal/` is implementation, not a package namespace. Do not add top-level exports for recipes, blocks, agent, terminal, or vendor groupings unless a later package API decision adds concrete public source, built files, docs, and tests in the same change.
+- **Agents is the client-only conversation interface.** `@nadicodeai/ui/agents` re-exports the complete `@assistant-ui/react` runtime and primitive API plus the reviewed, branded registry composition held under `src/internal/assistant-ui/`. Its built entry retains `"use client"`. Consumers receive Thread, attachments, Markdown, reasoning, tools, suggestions, providers, runtimes, hooks, and types from that one domain namespace. Agent identity components use their direct component subpaths so server compositions do not import the conversation runtime. The vendor name is not a public NadicodeAI subpath, and the package does not rename, wrap, or rebuild assistant-ui behavior.
 - **Base UI is the active primitive base.** `components.json` must resolve through a Base style, currently `base-nova`, and `npx shadcn@latest info --json` must report `base: "base"`. Do not reintroduce `radix-ui`, `@radix-ui/*`, or `vaul` to package source, dependencies, or app optimizer configuration. Registry-owned shadcn primitives stay aligned with current `shadcn@latest` Base UI output; use Base UI `render` composition instead of Radix `asChild`. `cmdk` is allowed only for the stock shadcn Command component while the current `base-nova` registry declares that dependency; do not use it elsewhere or replace it without a shadcn/compatibility decision and tests.
 - **Named shadcn blocks stay named.** When a user, plan, or issue selects a shadcn block/example such as `login-02`, `signup-02`, `dashboard-01`, or `sidebar-*`, use that registry item as the source of truth through shadcn CLI/MCP. Do not replace it with a package-authored abstraction unless the plan explicitly records the substitution, the reason, and the true consumer route that proves it.
-- **Public surface changes require a release decision.** Any change to exported components, `src/index.ts`, `src/ai-elements.ts`, package `exports`, `globals.css`, theme behavior, package docs, package skills, or design-system token/CSS/theme output consumed by this package must end with an explicit npm release decision before handoff: bump the relevant version(s) and run `npm pack --dry-run -w @nadicodeai/ui` per `../../../docs/internal/npm-publishing.md`, or include a `[no-publish]` commit marker with the reason in the commit body. The pre-push gate requires one of the two. When the UI change depends on modified `@nadicodeai/design-system` output, bump and publish `@nadicodeai/design-system` first, then update this package's dependency and publish UI. Never claim a UI package change is shipped until `npm view @nadicodeai/ui version` reports the intended version.
+- **Public surface changes require a release decision.** Any change to exported components, `src/index.ts`, package `exports`, `globals.css`, theme behavior, package docs, package skills, or design-system token/CSS/theme output consumed by this package must end with an explicit npm release decision before handoff: bump the relevant version(s) and run `npm pack --dry-run -w @nadicodeai/ui` per `../../../docs/internal/npm-publishing.md`, or include a `[no-publish]` commit marker with the reason in the commit body. The pre-push gate requires one of the two. When the UI change depends on modified `@nadicodeai/design-system` output, bump and publish `@nadicodeai/design-system` first, then update this package's dependency and publish UI. Never claim a UI package change is shipped until `npm view @nadicodeai/ui version` reports the intended version.
 
 ## Admission Rules
 
-Agent work surfaces (chat, composer, tool approval, artifacts, threads, diffs, terminal/file preview, and the underlying agent state models) are NadicodeAI core domain. They belong in this package outright, not behind a named consumer. Any other new product composition (a shell, a settings surface, a generic section) is admitted only with a named consuming surface landing in the same change. Genuinely app-bespoke UI (window chrome, boot/install overlays, mascots, PTY/xterm embeds) stays in the consuming app; it never becomes a package abstraction. A component left unconsumed after its target migration ships gets removed.
-
-- **Standard components, not app-owned product features.** This package ships primitives, standard UI components, AI Elements, brand adapters, React adapters, reusable sections, and presentational product components. It must not ship app-specific feature/use-case screens or names such as operator-login, portal activation, customer credential control, or customer management. Generic data tables, command palettes, and chart cards are app-owned shadcn registry adaptations. The source-backed `chart-*` package surface is the plan-approved exception per issue #166 and ADR 0010; chart cards remain app-owned. Every data-shaped chart exposes an equivalent non-visual data alternative. A component whose complete value is already available in visible text or `aria-valuetext` does not add a redundant table.
+Assistant conversation and runtime APIs enter through `@nadicodeai/ui/agents`; Agent identity enters through `@nadicodeai/ui/components/agent-card` and `@nadicodeai/ui/components/agent-visual`. The consuming application still constructs the runtime and owns transport, persistence, permissions, tools, approvals, and failure policy. Shared non-Agent product components (a shell, a settings surface, a generic section, a diff, or a file preview) are admitted only with a named consuming surface landing in the same change. App-bespoke UI and behavior (window chrome, boot/install overlays, mascots, PTY/xterm embeds, queues, approvals, and persistence) stay in the consuming app; they never become package abstractions. A component left unconsumed after its target migration ships gets removed.
+
+### Agent identity presentation
+
+`AgentVisual` is the shared branded identity renderer. Its public degrees of
+freedom are deliberately closed: one of `general`, `reasoning`,
+`coordination`, `communication`, or `execution`, plus the structural
+presentation `registry`, `card`, or `detail`. Consumers cannot supply colours,
+shader code, speed, count, density, frame, or material. Registry and Card
+presentations are deterministic posters. Detail may mount the Paper Metaballs
+renderer only after WebGL2 and reduced-motion checks; SSR, reduced motion,
+missing WebGL, initialization failure, and context loss retain the same poster.
+The visual is decorative by default. A meaningful selectable image opts into
+`decorative={false}` and supplies `label`.
+
+`AgentCard` composes the fundamental `Card` with explicit `visual`, `name`,
+`job`, `status`, `meta`, and `action` slots. It owns presentation only. The app
+still owns Agent data, recipe assignment, status grammar, routing, actions, and
+heading hierarchy; when the Card is the page identity, the `name` slot carries
+that page's `h1`.
+There is no `AgentGlyph`, `AgentRow`, `KpiCard`, or product-domain `agent`
+object prop in the shared package.
+
+- **Standard components, not app-owned product features.** This package ships primitives, standard UI components, assistant-ui compositions, brand adapters, React adapters, reusable sections, and presentational product components. It must not ship app-specific feature/use-case screens or names such as operator-login, portal activation, customer credential control, or customer management. Generic data tables, command palettes, and chart cards are app-owned shadcn registry adaptations. The source-backed `chart-*` package surface is the plan-approved exception per issue #166 and ADR 0010; chart cards remain app-owned. Every data-shaped chart exposes an equivalent non-visual data alternative. A component whose complete value is already available in visible text or `aria-valuetext` does not add a redundant table.
 - **Auth routes are consumer-owned shadcn block work.** Login, signup, OTP, two-factor, magic-link, and provider-button flows start from the selected shadcn block/example in the consuming app, with app-owned Better Auth behavior. Do not ship generic auth, signup, OTP, federated-login, or provider abstractions from this package unless a later explicit boundary decision replaces the selected shadcn block.
 - **Reusable sections and compositions live here after proof.** Bento grids, media mounts, demo surfaces, page frames, section intros, CTA bands, proof slots, benefits grids, generic shells, and homepage/use-case sections belong in `@nadicodeai/ui` when a second concrete consumer, a plan-approved shared component, or a named validation slice proves the package boundary. Website, portal, and sibling Nadia routes pass data and media children into existing compositions instead of rebuilding layout locally.
 - **Brand renderers live here for React consumers.** Logo geometry, asset generation, and usage semantics are owned by [`design-system/DESIGN.md`, "Brand media authority"](../../../design-system/DESIGN.md#brand-media-authority). `BrandLockup` supplies the approved horizontal lockup. `BrandMark` serves tight spaces and `BrandWordmark` serves placements where the name must read by itself. All three render the package's public neutral geometry seam with React-scoped SVG ids, dynamic theme paint, and accessible names. Consuming routes use these adapters; they never import raw logo assets, draw brand SVG inline, mask or recolor assets, or create another lockup rule.
@@ -39,7 +115,7 @@ The source tree, barrels, and package exports own the current reusable section v
 
 ## Consumer Boundary
 
-Consumers own routing, auth, app data, server actions, runtime adapters, permission decisions, analytics, and app-specific copy. The package owns the presentational structure and state vocabulary only. [`terminal-tui-semantics.md`](terminal-tui-semantics.md) owns TUI semantics.
+Consumers own routing, auth, app data, server actions, runtime construction and adapters, permission decisions, analytics, and app-specific copy. The package owns reusable React presentation and the public Agent UI dependency boundary. Agent state and behavior come through the Agents interface; non-React and TUI contracts belong to their consuming products.
 
 App source composes layout, data, behavior, and semantic content around package components. It does not restyle an imported component root: appearance changes enter through the component's typed variant or are added to the owning package component. App `className` values on package components are limited to structural layout and sizing. App source uses semantic roles such as `bg-background` and `text-foreground`; raw Tailwind palette colors and canonical `nc-*` color utilities stay behind package-owned primitives such as `BrandField`. Visible controls come from `@nadicodeai/ui`, while hidden inputs remain valid form transport. The root ESLint rules `nadicodeai/no-shadcn-appearance-override`, `nadicodeai/no-raw-color-utility`, and `nadicodeai/no-native-visible-control` enforce this boundary.
 

package/docs/migration/1.0.0.md

@@ -0,0 +1,75 @@
+# Migrating to `@nadicodeai/ui` 1.0.0
+
+This release makes material hierarchy and Agent identity package-owned. It
+also publishes the previously held status-vocabulary break.
+
+## Status
+
+`StatusTag` and `StateTag` are removed. Use `Badge` with one of its five
+semantic tones. The consuming app owns the status word, icon, and tone mapping.
+
+```tsx
+import { Badge } from "@nadicodeai/ui/components/badge";
+
+<Badge variant="green">Ready</Badge>;
+```
+
+The retired `.nc-status-tag`, `.nc-state-tag`, and `.nc-state-row` CSS classes
+have no replacement CSS API.
+
+## Material and Card
+
+Import `@nadicodeai/ui/globals.css` once. It now composes
+`shadow-plugin@1.2.7`; consumers do not install its classes or override its
+ring.
+
+`Card` defaults to `surface="resting"`. Use `surface="raised"` only for work
+that is physically raised or selected, and `surface="plain"` for the explicit
+structural/auth/website escape. `variant` continues to describe interaction.
+Replace the removed `variant="borderless"` with `surface="plain"`.
+
+```tsx
+<Card>Resting content</Card>
+<Card surface="raised">Selected work</Card>
+<Card surface="plain">Structural content</Card>
+```
+
+Overlay primitives now own floating or modal elevation internally. Remove
+caller `border-*`, `ring-*`, `shadow-*`, and `smooth-shadow-*` appearance
+classes from their content roots.
+
+## Empty and glass control
+
+Set Empty containment explicitly when nesting matters:
+
+```tsx
+<Empty scope="region">No agents</Empty>
+<Card><Empty scope="card">No runs</Empty></Card>
+```
+
+Use `GlassControl shape="control"` for compact controls and `shape="bar"` for
+full-width header chrome. Both float over legible content. Cards and modal
+primitives continue to contain page content and dialog bodies.
+
+## Agent identity
+
+Agent identity is available from direct component subpaths. The
+`@nadicodeai/ui/agents` entry remains the client-only assistant conversation
+and runtime interface.
+
+```tsx
+import { AgentCard } from "@nadicodeai/ui/components/agent-card";
+import { AgentVisual } from "@nadicodeai/ui/components/agent-visual";
+
+<AgentCard
+  name={agent.name}
+  job={agent.job}
+  status={<Badge variant="blue">Running</Badge>}
+  visual={<AgentVisual recipe={agent.recipe} presentation="card" />}
+/>;
+```
+
+Recipe assignment is app-owned and explicit. Do not infer it from a free-form
+role, hash an identifier, or randomize it. `AgentVisual` accepts only the five
+closed recipes and three presentations; raw shader controls are intentionally
+not public. `AgentGlyph` and `AgentRow` do not exist in the 1.0.0 API.

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

@@ -10,7 +10,6 @@ Current invariants:
 - `@nadicodeai/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.
-- AI Elements use the package-local `useControllableState` helper instead of Radix's hook.
 
 ## Migration Catalog
 
@@ -26,16 +25,6 @@ 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.
-- AI Elements replace `@radix-ui/react-use-controllable-state` with `src/hooks/use-controllable-state.ts`.
-
-AI Elements using the local controlled/uncontrolled helper:
-
-- `chain-of-thought`
-- `mic-selector`
-- `reasoning`
-- `stack-trace`
-- `transcription`
-- `voice-selector`
 
 ## Breaking in 0.5.0
 

package/docs/product-compositions.md

@@ -2,7 +2,7 @@
 
 U4 adds the first shared product compositions for NadicodeAI admin, settings, and agent-work surfaces. These components are presentational only: consumers own routing, persistence, server actions, mutations, analytics, auth providers, permissions, and product-specific page copy.
 
-When first-party shadcn or AI Elements registry source already covers the same
+When first-party shadcn or assistant-ui registry source already covers the same
 generic product UI, use that registry item in the consuming app instead of
 adding a parallel NadicodeAI package API. Data tables, command palettes, and
 chart cards follow this rule: use `@shadcn/data-table-demo`,

package/llms.txt

@@ -12,11 +12,13 @@ Use this file as a map; read the owning document before changing behavior.
 - Current component modules: `src/components/**/*.tsx` in the repository.
 - Current published subpaths: `package.json` `exports` plus the generated
   `dist/components/**/*.d.ts` declarations in an installed package.
-- Agent work surfaces: `docs/agent-work-surfaces.md`.
+- Public Agent UI interface: `src/agents.ts`, exported as `@nadicodeai/ui/agents`.
+- Material, Card, Empty, glass-control, AgentVisual, and AgentCard semantics:
+  `docs/contract.md`; 1.0 adoption steps: `docs/migration/1.0.0.md`.
+- Maintained conversation implementation: `src/internal/assistant-ui/`.
 - Product compositions and sections: `docs/product-compositions.md` and
   `docs/product-sections.md`.
-- Terminal and TUI semantics: `docs/terminal-tui-semantics.md`.
-- Maintenance workflow and live shadcn or AI Elements discovery:
+- Maintenance workflow and live shadcn or assistant-ui discovery:
   `docs/agents/nadicodeai-ui.md`.
 
 The component inventory is source-backed and is not repeated in prose. Use the
@@ -29,14 +31,13 @@ Prefer explicit component subpaths:
 
 ```tsx
 import { Button } from "@nadicodeai/ui/components/button";
-import { Message } from "@nadicodeai/ui/components/ai-elements/message";
+import { AssistantRuntimeProvider, Thread } from "@nadicodeai/ui/agents";
 ```
 
-Use the root or AI Elements barrel when a barrel is more useful:
+Use the root barrel when it is more useful:
 
 ```tsx
 import { Button } from "@nadicodeai/ui";
-import { Message, PromptInput } from "@nadicodeai/ui/ai-elements";
 ```
 
 Read the generated declaration for the current export names and props. Do not