@nadicodeai/ui 4.0.4 → 5.1.0

package/docs/activity.md

@@ -0,0 +1,120 @@
+# System activity
+
+The system activity family has three motions. They describe ongoing system
+operations across the website, Portal and Nadia. They do not represent an
+Agent's identity, attention or personality.
+
+| Activity | Use when | Library motion |
+| --- | --- | --- |
+| `loading` | Retrieving or revealing content: opening a workspace, fetching records, refreshing a view, retrieving search results. | `composing`: flowing dotted bands wrap around a globe, shown as “Thinking…” in the library's large demo. |
+| `connecting` | Actively establishing or restoring communication with an account, service or device. | `connecting`: links form between nodes and carry signals. |
+| `processing` | Carrying out an operation: saving, submitting, applying changes, validating, importing, preparing an export, reconciling a sync, or other unmeasured work. | `working`: particles travel on tilted orbits. |
+
+These are three NadicodeAI activity treatments, not a claim that every design
+system defines these categories. The label names the specific operation;
+people are never expected to decode particle movement alone.
+
+## Choose the feedback
+
+An operation's purpose selects the orb; the endpoint, worker or request type
+does not. Retrieving search results is `loading`. Establishing the connection
+before that request is `connecting`. A working connection remains a settled
+status while data loads. Synchronizing records after connection is
+`processing`; reconnecting during sync temporarily uses `connecting`.
+
+Saving is `processing`, not a fourth activity. Uploading, downloading,
+installing and converting use the existing `Progress` component when the
+completed amount can be measured. For an unmeasured preparation phase, use
+`processing`. When progress will become measurable, reserve a progress
+treatment from the start so the transition does not move the layout. Never
+invent a percentage or surround an indeterminate orb with a simulated fill.
+
+Queued, paused, offline, blocked, successful and failed conditions use the
+existing status or action-feedback treatment. A request waiting for a person
+does not keep an orb moving. A retry uses `connecting` only while an actual
+connection attempt is in progress; its failure or recovery replaces activity
+with the appropriate feedback. An account being active is not an activity.
+
+Use the indicator beside the operation it describes. Keep the rest of the
+interface available. One operation gets one indicator; separately progressing
+operations can each have one. For content with a predictable layout, prefer
+`Skeleton` or retained content over replacing the region with an orb. Do not
+show both a skeleton and a central orb for the same wait.
+
+## Brand treatment
+
+All three reuse `thinking-orbs` 0.3.1 (MIT). Their geometry, depth ordering and
+size-specific density remain the library's. NadicodeAI adapts the palette and
+clock, not the rendering engine.
+
+The structure inherits the surrounding text's neutral ink. Foreground and
+signal particles carry the existing cobalto `--nc-info` role, mixed with that
+ink to preserve contrast in either appearance. Depth fades into the actual
+surface through transparency. There are no activity-specific colours: cobalto
+means work underway throughout the family. Green, amber and red retain their
+settled feedback meanings. Controls and panel backgrounds remain neutral.
+
+The selected clock multipliers are 0.92 for loading, 0.86 for connecting and
+0.92 for processing, applied to each original size-specific preset. The
+connection animation is slightly quieter because its forming links add
+movement as well as its travelling particles. The implementation owns these
+values together; consumers cannot tune speed, density or particle colours.
+
+Use 20 CSS pixels inline, including buttons and rows with room for that size;
+64 for a contained region; 88 for an application threshold. The 20 preset is
+separately tuned, and must not be obtained by shrinking the 64 preset. The 88
+extent uses the 64 preset. A 12–16 pixel badge slot keeps its existing compact
+spinner until its surrounding component explicitly accommodates this family.
+
+## React
+
+```tsx
+import { ActivityOrb } from "@nadicodeai/ui/components/activity-orb";
+
+<ActivityOrb activity="loading" label="Caricamento progetti" size={64} />;
+
+<div role="status">
+  <ActivityOrb activity="connecting" decorative />
+  <span>Connessione all’account…</span>
+</div>;
+
+<Button disabled={saving} aria-busy={saving}>
+  {saving ? <ActivityOrb activity="processing" decorative /> : null}
+  Salva modifiche
+</Button>;
+```
+
+`activity` is required. `size` defaults to 20. A meaningful standalone orb
+requires `label`; `decorative` removes its accessible name when the adjacent
+text or control already supplies the meaning. `paused` freezes the current
+frame for a user-controlled motion pause or a design specimen. It does not
+mean the underlying operation is paused. Product code unmounts the orb when
+the operation ends or cannot proceed.
+
+Import `@nadicodeai/ui/globals.css` as described in the
+[consumer guide](consuming-cross-repo.md). The renderer inherits actual CSS
+ink and reads canonical colour tokens. The existing `Orb` threshold adapter
+keeps its public API: `working` maps to `processing`, `connecting` maps to
+`connecting`, and `absent` mounts nothing. Its fixed dark appearance stays at
+the threshold seam, outside the shared renderer.
+
+## Accessibility and runtime
+
+Reduced motion holds one representative frame and makes no animation requests.
+A preference change takes effect while the component is mounted. The
+operation's readable label remains. Pausing and resuming preserves the phase.
+Offscreen or hidden activity stops rendering. Removing a component removes
+its animation request and observers. DPR is capped at two. The renderer uses
+Canvas 2D and requires no WebGL; without a 2D context, the accessible meaning
+remains and the surrounding operation stays usable.
+
+## Ownership and source
+
+The component owns rendering and the closed activity choices. Applications
+own requests, retries, progress measurements, copy, completion and recovery.
+Product-design guidance links here for selection and usage. The foundation's
+colour meanings remain in the design-system contract.
+
+The source selection follows the [library's public engine and presets](https://libraries.dev/orbs).
+The distinction between measured and unmeasured progress follows
+[Apple's progress guidance](https://developer.apple.com/design/human-interface-guidelines/progress-indicators).

package/docs/contract.md

@@ -6,7 +6,7 @@ The normative invariants for the `@nadicodeai/ui` package: what may live here, h
 
 - **Token-only, no raw literals or shadow aliases.** Components style through semantic shadcn utilities (`bg-background`, `text-foreground`, `border-input`, and the rest), or a canonical generated design-system token when no standard role is precise enough. The UI package does not mint screen-, component-, or product-specific color aliases. No raw `#hex` / `rgb()` / `hsl()` may appear in `.tsx`; a new source value goes to `packages/design-system/DESIGN.md` first and flows through generated output. A narrow protocol adapter may translate third-party classes directly to canonical tokens in `globals.css`, but it must not create another token vocabulary. Enforced by the raw-colour `no-restricted-syntax` selectors in the library ESLint config, `packages/ui/tests/guards/dark-semantic-roles.test.ts`, and `packages/ui/tests/guards/token-reference-integrity.test.ts`.
 - **Dark-ready semantics, no component dark implementation.** Components use the same semantic role or canonical mode-aware token in every mode. They must not ship Tailwind `dark:` color utilities, component-local `.dark` blocks, OS dark-mode branching, or raw dark palette utilities such as `dark:bg-slate-950` and `dark:text-white`. An intentionally fixed-presentation technology surface, such as the dark terminal console, selects canonical fixed-mode tokens as one coherent component treatment rather than branching by app theme. Enforced by `packages/ui/tests/guards/no-dark.test.ts`, `packages/ui/tests/guards/dark-semantic-roles.test.ts`, and `packages/ui/tests/guards/token-reference-integrity.test.ts`. The generated mode and theme architecture lives only in [`packages/design-system/DESIGN.md`](../../design-system/DESIGN.md#css-architecture--token-pipeline).
-- **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).
+- **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). `@nadicodeai/ui/threshold.css` is the one stylesheet outside it, because the surface that needs it most loads no Tailwind layer at all: the Nadia desktop shell takes that file and the design system's token artifact and nothing else. A React caller imports it beside globals.css, never instead of it.
 - **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: `packages/design-system/DESIGN.md` "## Layout").
 
 ### Material surfaces
@@ -92,6 +92,12 @@ gone, is [`packages/design-system/DESIGN.md`, "## Status Vocabulary"](../../desi
 
 ## Package Shape Invariants
 
+System activity uses `ActivityOrb` for loading, connecting and processing;
+[activity.md](activity.md) owns selection, rendering and accessibility. It
+composes with status feedback and measured progress without adding outcome
+states to the orb. The existing threshold `Orb` adapts its public states to
+this same renderer.
+
 - **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.** 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.
@@ -101,7 +107,7 @@ gone, is [`packages/design-system/DESIGN.md`, "## Status Vocabulary"](../../desi
 
 ## Admission Rules
 
-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.
+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, PTY/xterm embeds, queues, approvals, and persistence) stay in the consuming app; they never become package abstractions. `@nadicodeai/ui/threshold` is the plan-approved package surface for the room, Nadia's presence, the status orb and the typed line used by the Nadia desktop app. The screen, its copy and its state machine stay in the consuming app, and the entry ships no screen. Its contract is [`threshold.md`](threshold.md). A component left unconsumed after its target migration ships gets removed.
 
 ### Agent identity presentation
 

package/docs/threshold.md

@@ -0,0 +1,221 @@
+# The threshold primitives
+
+`@nadicodeai/ui/threshold` holds the four primitives a threshold is drawn from. A
+threshold is the moment before the product is usable: a first run, a sign-in, a
+repair. The Nadia desktop app draws its room, presence, status orb and typed line
+from here, so the brand logic has one home.
+
+The entry ships no screen and no state machine. Which view is on, what the
+words are, and when a threshold ends belong to the consuming app.
+
+```tsx
+import { NadiaPresence, Orb, ThresholdRoom, TypedLine } from "@nadicodeai/ui/threshold";
+import "@nadicodeai/ui/threshold.css";
+```
+
+## What each part is for
+
+| Part | Its one job | Never |
+| --- | --- | --- |
+| `ThresholdRoom` | the place: a verde field on true black | inside the working app |
+| `NadiaPresence` | the host: her arrival is the progress | a loader, a ring, a bar |
+| `Orb` | status: we are working, or we wait on the Customer | on an error, or beside an actionable button |
+| `TypedLine` | what Nadia is saying while you wait | a control or state machine |
+
+The logo is not on this list. It belongs to window chrome, the tray and the
+About row, never to a threshold.
+
+## The stylesheet
+
+`@nadicodeai/ui/threshold.css` is a separate import rather than a part of
+`globals.css`, because the surface that needs it most does not load Tailwind:
+the Nadia desktop shell takes this file and the design-system token layer and
+nothing else from this package. A Tailwind consumer imports it beside
+`@nadicodeai/ui/globals.css`.
+
+Both the stylesheet and the room need the design-system tokens above them, from
+`@nadicodeai/ui/globals.css` or `@nadicodeai/design-system/css`. Without that
+cascade there is no palette, and the room paints its still field rather than
+guessing a colour.
+
+## `ThresholdRoom`
+
+```tsx
+<div className="relative isolate overflow-hidden">
+  <ThresholdRoom energy={arriving ? 1 : 0} dimmed={repairing} ready={connected} />
+  {/* the presence and the words, above it */}
+</div>
+```
+
+| Prop | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `dimmed` | `boolean` | `false` | a repair or an error quiets the room to 22 percent |
+| `energy` | `number` | `0` | how much of the room's pace runs, 0 to 1 |
+| `ready` | `boolean` | `false` | success: the field takes verde vivo |
+| `className` | `string` | — | added to the root |
+
+The room paints absolutely inside its own relative, isolated parent and never
+against the viewport, so a bounded surface can hold one without covering the
+page. It is `aria-hidden`, takes no pointer events, and carries no words.
+
+**The recipe.** Paper Shaders 0.0.78 `meshGradientFragmentShader`, its published
+Ink preset adapted to two colours and slowed: `u_colors` are
+`--nc-identity-verde` and `--nc-identity-ink`, `u_colorsCount` 2, `u_distortion`
+1, `u_swirl` 0.2, `u_rotation` 90, `u_grainMixer` and `u_grainOverlay` 0, fit
+contain, scale 1. Mount speed is 0.22 at energy 1, starting frame 12000, minimum
+pixel ratio 1, maximum pixel count 1,024,000, canvas opacity 0.65. The room is
+masked with `radial-gradient(ellipse 65% 58% at 50% 35%, black 10%, transparent
+95%)`. The two colours are shader uniforms, never CSS.
+
+`energy` is a scalar so a screen can decide. The captured recipe is energy 1;
+Nadia's first run holds it there while she is still arriving and drops it to 0
+when she has, which stills the field. Sign-in, success and every repair state
+pass 0.
+
+**One canvas per window.** While `NadiaPresence` is painting her arrival with
+water, the room mounts nothing and shows this same still field; the moment the
+water leaves, at reveal 1 or when it cannot paint, the room's canvas mounts.
+The budget lives in the package, so a surface that composes both, as first run
+does, keeps the register's one shader canvas without doing anything.
+
+**No GPU, no tokens, or a lost context.** The room keeps its still field: a
+token-built radial gradient that needs no WebGL. It carries `data-surface`,
+`"shader"` while the canvas paints and `"still"` otherwise, and a mount that
+fails leaves no dead canvas covering the fallback. A `webglcontextlost` event
+returns it to the still field rather than to a black rectangle.
+
+**Reduced motion.** Speed 0: the shader paints frame 12000 once and stops. The
+room still has its colour and its shape; it just holds one frame.
+
+## `NadiaPresence`
+
+```tsx
+<NadiaPresence label={t("install.progress")} reveal={fraction} src={portrait} state="arriving" />
+```
+
+| Prop | Type | Meaning |
+| --- | --- | --- |
+| `label` | `string` | the accessible name of the arrival |
+| `reveal` | `number` | 0 behind the field, 1 standing clear |
+| `src` | `string` | the portrait master's URL |
+| `state` | `"arriving" \| "present" \| "ready" \| "error"` | which threshold she is in |
+
+`src` is a prop rather than an import because this package imports no binary
+asset of its own; the consuming surface resolves
+`@nadicodeai/design-system/assets/nadia-solid-surface` with its own bundler and
+passes the URL. Keeping it out of the library is what lets a Node or a
+bundler-free consumer load the module at all.
+
+**The arrival.** Opacity is `0.025 + 0.975 × reveal^1.25`, exported as
+`arrivalOpacity` so a screen can read the same curve. At the start she is a
+trace, which gives the arrival somewhere to go. Her lower edge dissolves into
+the room with `linear-gradient(black 55%, transparent 98%)` instead of ending on
+a rectangle. The `error` state multiplies her by 0.62.
+
+**The water.** While `state` is `arriving`, `reveal` is below 1 and motion is
+allowed, the portrait is painted by Paper's `waterFragmentShader` at a
+restrained intensity: `caustic`, `edges` and `waves` are `0.35`, `0.4` and `0.3`
+scaled by how much of the arrival is left, with `layering` 0.4 and `highlights`
+0.12, `colorBack` fully transparent and `colorHighlight` on
+`--nc-identity-verde`. Every amplitude reaches zero as she arrives, so her
+geometry holds and the water is gone by the time she stands clear. At reveal 1,
+and in every other state, this is the plain portrait.
+
+While the water is wanted it is the window's one shader canvas: the presence
+holds the canvas budget from the moment it asks for the water until the water
+is torn down, and the room keeps its still field for exactly that long.
+
+The water canvas is masked to her own silhouette. Water adds its highlight term
+to the whole frame rather than only to the sampled image, so an unmasked canvas
+paints a faintly lit rectangle over the room; the mask matches the shader's own
+contain fit and centred origin.
+
+**Reduced motion, no GPU, or an image that will not decode.** The plain
+portrait, at the same reveal. The figure carries `data-surface`, `"water"` or
+`"portrait"`.
+
+**Success.** `state="ready"` runs one 360 ms verde vivo beat over her silhouette
+on `--nc-ease-out-strong`, opacity 0 to 0.22 at 35 percent and back to 0, once.
+Verde vivo is Nadia's presence accent and this is the only place a threshold
+spends it, which is why the buttons beside it stay neutral. Reduced motion
+suppresses the beat.
+
+**Assistive technology.** A hidden `progressbar` carries `label` and the floored
+percentage, so it reaches 100 only when the arrival is actually finished. The
+portrait itself is decorative; the words are the typed line's.
+
+## `Orb`
+
+```tsx
+<Orb label={t("install.working")} state="working" />
+```
+
+| Prop | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `label` | `string` | — | what the orb means, in the Customer's language |
+| `size` | `88 \| 64 \| 20` | `88` | CSS pixels: 88 at a threshold, 20 inside a running turn, per the living-elements register |
+| `state` | `"working" \| "connecting" \| "absent"` | — | see below |
+
+The threshold adapter preserves its public states: `working` selects the
+shared `processing` activity, `connecting` selects `connecting`, and `absent`
+renders nothing. The threshold defaults to fixed dark ink; `theme="auto"`
+inherits the surrounding product's ink and `theme="light"` fixes light-surface
+ink. There is one renderer, `ActivityOrb`, rather than a second threshold orb.
+
+[System activity](activity.md) owns the motion recipes, colour treatment,
+optical sizes, reduced-motion behaviour and connection-versus-person-waiting
+rule. Applications retain their operation state machines and copy.
+
+## `TypedLine`
+
+```tsx
+<TypedLine text={t("install.step.1")} />
+```
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `cadenceMs` | `number` | `44` |
+| `text` | `string` | — |
+| `className` | `string` | — |
+
+The line types itself at 44 ms per character, the cadence the rendered
+comparisons selected for a first-run pause. Three things it does that a naive
+typewriter does not:
+
+- the count comes from elapsed time, not from how many callbacks arrived, so a
+  software renderer or a busy main thread cannot stretch a one second sentence
+  into five;
+- a hidden copy of the whole sentence reserves its width, so the orb beside it
+  does not travel sideways with each character;
+- the live region receives the complete sentence at once, so a screen reader is
+  never read one letter at a time.
+
+A new `text` retypes from a cleared line. The caret is steady while typing and
+hidden afterwards.
+
+**Reduced motion.** The whole line at once, and no caret.
+
+## Tokens, and the one fixed presentation
+
+Everything visual comes from design-system tokens. A threshold is a fixed dark
+surface: it is true black in every theme, so the text ladder reads
+`--nc-dark-ink`, `--nc-dark-body` and `--nc-dark-muted` directly instead of
+branching on the app's mode. That is the fixed-presentation escape
+[`contract.md`](contract.md) names, taken once and coherently for the whole
+surface.
+
+The room's two colours are the exception that proves it: they are shader
+uniforms read off `--nc-identity-verde` and `--nc-identity-ink` at mount, not
+CSS values.
+
+## Motion budget
+
+The foundation's: `--nc-duration-open` for a room fading in or out,
+`--nc-duration-confirm` for the presence, `--nc-ease-emphasized` and
+`--nc-ease-out-strong`. The success beat is the one
+duration written here rather than taken from a token, 360 ms, because it is an
+envelope rather than a state change.
+
+Under `prefers-reduced-motion: reduce` the room holds one frame, the water is
+not mounted, the presence jumps to its value, the beat does not run, the orb
+draws once and the line appears whole.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadicodeai/ui",
-  "version": "4.0.4",
+  "version": "5.1.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -19,6 +19,11 @@
       "types": "./dist/agents.d.ts",
       "import": "./dist/agents.js"
     },
+    "./threshold": {
+      "types": "./dist/threshold.d.ts",
+      "import": "./dist/threshold.js"
+    },
+    "./threshold.css": "./dist/components/threshold/threshold.css",
     "./hooks": {
       "types": "./dist/hooks/index.d.ts",
       "import": "./dist/hooks/index.js"
@@ -61,7 +66,7 @@
     "@assistant-ui/react": "0.15.1",
     "@assistant-ui/react-markdown": "0.14.8",
     "@base-ui/react": "^1.6.0",
-    "@nadicodeai/design-system": "4.0.4",
+    "@nadicodeai/design-system": "5.1.0",
     "@paper-design/shaders": "0.0.78",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -78,6 +83,7 @@
     "remark-gfm": "^4.0.1",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.0.0",
+    "thinking-orbs": "0.3.1",
     "tw-animate-css": "^1.4.0",
     "tw-shimmer": "0.4.12",
     "zustand": "^5.0.14"