@nadicodeai/ui 8.1.0 → 8.2.0

package/docs/agent-orb.md

@@ -0,0 +1,82 @@
+# Agent orbs
+
+`AgentOrb` is the abstract Agent identity family requested on 2026-09-19:
+seven structures from `thinking-orbs` 0.3.1, each painted in one configurable
+colour. These are persistent appearance choices, not activity states. They
+apply equally to Nadia and other Agents; this family assigns no face or
+special character to Nadia. Existing Forma consumers are not migrated by
+this component slice.
+
+| Form | Structure | Upstream preset |
+| --- | --- | --- |
+| `ribbon` | Flowing dotted bands | `composing` |
+| `lattice` | Rotating particle bands | `solving` |
+| `orbit` | Particles on tilted orbits | `working` |
+| `globe` | Dotted globe and scanning meridian | `searching` |
+| `network` | Connected constellation | `connecting` |
+| `braid` | Interwoven strands | `weaving` |
+| `morph` | Changing geometric contour | `shaping` |
+
+The form does not select a job, tools or runtime status. Do not switch it when
+an Agent starts searching or solving. Applications own the persisted form,
+colour, name and status; names beside avatars provide exact identification.
+
+## Component
+
+```tsx
+import { AgentOrb } from "@nadicodeai/ui/components/agent-orb";
+
+<AgentOrb form="ribbon" color="var(--nc-identity-cobalto)" size={32} label="Nadia" />;
+```
+
+`form` is required. `color` accepts one CSS colour, including a customer-chosen
+colour or a canonical token. Omit it to inherit text colour. This configurable
+artwork is not a new palette for controls or status. Every particle and line
+uses the same pigment; opacity, not another colour, creates depth. Working
+releases occasional coloured flourishes; Done repeats the same arcs,
+arrowheads, rings and sparkles in a short celebration around
+that single-colour identity, using the existing chart and warning tokens. Choose a
+colour visible on the intended background. A deliberately black pigment on a
+black surface is not automatically recoloured.
+
+Sizes are 20, 24, 32, 40, 64, 96 and 160 CSS pixels. Menu sizes through 32 use
+the upstream compact density; larger sizes use its detailed profile. `paused`
+holds the current frame and resumes without resetting the appearance. An
+accessible image requires `label`; use `decorative` beside an existing name.
+The component is Canvas 2D, not WebGL. It reuses the vendor's portable geometry
+API because the stock React component only offers monochrome light/dark ink,
+not a configurable pigment.
+
+Motion is limited to 30 painted frames per second. Offscreen and hidden orbs
+stop scheduling animation. Reduced motion freezes the current frame and is
+observed live. Unmount removes the frame request and observers. DPR is capped
+at two. Without Canvas 2D, the accessible name remains available.
+
+`state` accepts idle, working, waiting, blocked, thinking and done. Geometry
+and state gestures have separate clocks: slowing a gesture must not make the
+idle form appear frozen. Each form has its own geometry pace, shared across
+avatar sizes; Morph holds a contour for about 1.6 seconds and changes it over
+one second at idle. Working and Thinking keep the form's base pace.
+Waiting holds its pose; Blocked makes one gentle interrupted effort and stops.
+V7 keeps the material free-standing and intact:
+no gear, thought bubble, pause, exclamation mark or check is cut into the form.
+Working and Thinking preserve the native geometry: do not stretch, flatten,
+fold or emit copies of the orb to convey either state. Working uses one open,
+tapered multicoloured ribbon passing behind and in front of the orb on a
+7.2-second loop. Thinking uses three persistent coloured dots above the orb,
+with sequential opacity and slight size pulses on a 3.6-second loop.
+The distinct symbols remain visible throughout both cycles. Done repeats
+the ribbon in three celebratory sweeps and then rests. Changing `motionKey`
+replays it. These exterior cues use the celebration palette; the body keeps
+its configured pigment. Reduced motion holds both cues still.
+No state has an enclosing circle. Keep a nearby status label where exact
+state identification matters, including reduced motion and compact sizes.
+Reduced motion holds the state pose and skips the celebration.
+
+The [Portal Agent workspace](../../../apps/portal/src/components/agent-workspace/agent-workspace.tsx)
+uses the shared component. Inspect its Agent list and detail views in the
+running local Portal for compact and full-size appearances. Development
+profiles provide example orb choices; their preview edits do not change
+stored Agent records.
+
+[Upstream library and presets](https://libraries.dev/orbs), MIT licensed.

package/docs/agent-visual.md

@@ -1,5 +1,10 @@
 # Agent Visual System
 
+Legacy API for existing consumers. New Agent workspace surfaces use
+[AgentOrb](agent-orb.md) and the shared
+[product language](../../design-system/PRODUCT_LANGUAGE.md#agent-section-contract).
+The multicolour recipes below do not govern new Portal agent representations.
+
 The Agent visual is the decorative identity for a persistent Agent in Nadia.
 It is a living, multicolour metaball form whose recipe is assigned by Agent
 type. It does not represent status, capability, runtime activity, or work

package/docs/contract.md

@@ -152,7 +152,7 @@ states to the orb.
 
 ## Admission Rules
 
-Assistant conversation and runtime APIs enter through `@nadicodeai/ui/agents`; Agent identity enters through `@nadicodeai/ui/components/agent-card`, `@nadicodeai/ui/components/agent-visual`, and the Forma avatars in `@nadicodeai/ui/components/forma-avatar` (owned by [`forma-avatar.md`](forma-avatar.md)). 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, 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.
+Assistant conversation and runtime APIs enter through `@nadicodeai/ui/agents`; Agent identity enters through `@nadicodeai/ui/components/agent-card`, `@nadicodeai/ui/components/agent-orb`, `@nadicodeai/ui/components/agent-visual`, and the Forma avatars in `@nadicodeai/ui/components/forma-avatar` (owned by [`forma-avatar.md`](forma-avatar.md)). 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, 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.
 
 ### Placement
 
@@ -166,6 +166,17 @@ where [`apps/nadia/docs/entry-screen.md`](../../../apps/nadia/docs/entry-screen.
 owns their contract. `packages/ui/tests/guards/product-placement.test.ts`
 refuses a product's name in either package.
 
+### Abstract Agent identities
+
+`AgentOrb` is the seven-form, single-colour abstract family in
+[`agent-orb.md`](agent-orb.md), exposed through
+`@nadicodeai/ui/components/agent-orb`. Its consuming validation surface is
+`examples/agent-orbs`: the built component at detail, menu and conversation
+sizes, with independently editable colours. The application stores appearance;
+upstream activity names select geometry only and never infer an Agent role or
+change its identity with runtime work. Customer-selected artwork colours are
+inputs, not component palette literals or interface colour roles.
+
 ### Agent identity presentation
 
 The visual system (the closed recipes, motion, fallbacks, and licensing) is
@@ -190,7 +201,6 @@ product-domain `agent` object prop in the shared package.
 - **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 [`packages/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.
 - **Third-party brand marks are generated, never hand-drawn and never hand-edited.** Other companies' marks live in `packages/ui/src/components/brand-icons/`, emitted from an explicit allow-list by `packages/ui/scripts/build-brand-icons.mjs` and exported through the `@nadicodeai/ui/components/brand-icons` subpath. They are identity images, not UI icons: a brand mark is exempt from the currentColor stroke system and from the raw-literal rule, it never stands in for a UI icon, and a UI icon never stands in for a brand. Marks drawn as one silhouette are stripped to `currentColor` by the generator; every other mark keeps its official colors verbatim. To add a brand, edit the generator's allow-list and run `npm run generate:brand-icons -w @nadicodeai/ui`; hand edits to the generated directory are lost and `packages/ui/tests/guards/brand-icons-codegen.test.ts` fails on them. Use is nominative only — naming a platform, an integration, or a provider — never adjacent to endorsement or partnership wording; that nominative posture is the licensing and trademark position, so a mark never appears where the copy implies endorsement.
-
   The one script reads two explicit allow-lists: platform marks out of the Iconify `logos` set (CC0-1.0), and model makers' marks out of the LobeHub icon set (MIT, `@lobehub/icons-static-svg`), both as `devDependencies`. The emitted components are plain SVG, so neither icon data package belongs in the runtime dependency set or reaches a consumer bundle. The artwork itself does ship, so every upstream whose licence asks for one travels with a notice in `LICENSES/` and `NOTICE`, and `tests/guards/brand-icons-codegen.test.ts` holds the allow-list to that: a new source cannot ship unattributed.
 - **No fake proof APIs.** Components may support future testimonials, logos, stats, and proof slots, but they must render nothing public when the proof is absent. Do not ship placeholder customer names, metrics, or logos.
 
@@ -230,7 +240,9 @@ comparison line and a note, both in the caller's language. There is no grouped o
 row of KPIs is a `CardRow` of `KpiCard`s, each its own card. Apps supply the
 figures and bind links through `render`. Charts expose `size` (`default` or
 `lg`), which selects a fixed plot height, so consumers never select internal
-chart elements.
+chart elements. `ChartSummary` owns a chart's measured value, trend badge,
+status and comparison line inside the chart card; consumers provide typed
+content instead of rebuilding that presentation beside the plot.
 
 `CollectionToolbar` owns the collection-control layout: compact filters at the
 leading edge, a flexible search field, and trailing actions. Its slot order is
@@ -284,9 +296,24 @@ and status retain their column headers. Missing values retain their place.
 `standard` retains full columns at 768px of container width, `wide` at 1024px,
 and `spacious` at 1152px for schemas with additional operational columns.
 The same owner switches column visibility, detail visibility, and row boundaries.
+`TableRecordGroup` wraps the primary row and its compact detail row in one
+native row group, so hovering, focusing, expanding, or selecting either half
+highlights one record. A consumer does not render the two rows as independent
+siblings. Portal `DataTable` chooses a layout from its column count by default;
+a comparison whose columns remain readable longer may select one of these
+shared layouts instead of adding route-owned width rules.
 Two supporting facts use two columns; additional facts can use three when they fit.
 The cell renderer supplies the value, leaving the label to the detail row.
 
+### Missing table values
+
+`TableValue` owns the [cross-product missing-value convention](../../design-system/PRODUCT_LANGUAGE.md#missing-values-in-collections).
+Pass the actual scalar or rendered value and a required localized `missingLabel`.
+Null, undefined and empty strings render a muted, visually fixed `—` plus
+screen-reader text; zero and present values pass through unchanged. No custom
+visible fallback is exposed. Do not prefill `value` with absence copy.
+Loading, failure, permission and actionable states remain outside this component.
+
 ## Consumer Boundary
 
 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.
@@ -342,3 +369,19 @@ The identity row names who is signed in and carries one `DropdownMenuItem
 iconOnly` gear at its trailing edge, linking to the account section; the menu
 does not repeat that section's pages as commands. Consumers bind preference
 persistence, routing, and localized labels.
+
+## Object workspace compositions
+
+`ObjectIdentity`, `ObjectOverview`, `ObjectSection` and `ObjectFacts` compose the
+[shared IA patterns](../../design-system/PRODUCT_LANGUAGE.md#reusable-information-architecture)
+from existing Card and typography foundations. They own identity/action alignment,
+primary/supporting responsive columns, summary boundaries and semantic definition
+pairs. They take slots and values, never domain stores, URLs, permissions or save
+functions. Portal's agent workspace binds them to its scoped routes; Nadia may
+reuse the same presentation within its own shell. Do not ship a second complete
+Agent application inside this package.
+
+`ObjectIdentity.support` adds a small set of stable, labelled context facts to
+the identity header. The facts sit beside the identity when space allows and
+collapse behind the caller's localized disclosure label on compact screens.
+Operational warnings and changing report readings remain in the page body.

package/docs/model-identity.md

@@ -0,0 +1,18 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadicodeai/ui",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -36,6 +36,10 @@
       "types": "./dist/lib/theme-mode.d.ts",
       "import": "./dist/lib/theme-mode.js"
     },
+    "./lib/format-token-count": {
+      "types": "./dist/lib/format-token-count.d.ts",
+      "import": "./dist/lib/format-token-count.js"
+    },
     "./components/*": {
       "types": "./dist/components/*.d.ts",
       "import": "./dist/components/*.js"
@@ -66,11 +70,12 @@
     "@assistant-ui/react": "0.15.20",
     "@assistant-ui/react-markdown": "0.14.15",
     "@base-ui/react": "^1.8.0",
-    "@nadicodeai/design-system": "8.1.0",
+    "@nadicodeai/design-system": "8.2.0",
     "@paper-design/shaders": "0.0.81",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "date-fns": "^4.4.0",
     "embla-carousel-react": "^8.6.0",
     "input-otp": "^1.5.0",
     "lucide-react": "1.47.0",