@nadicodeai/ui 6.0.0 → 6.0.1

package/dist/internal/forma/rig.js

@@ -0,0 +1,211 @@
+import { computeFrame } from "./frame.js";
+import { createMotion, needsMotion, settled, stepPose, updateMotion, } from "./motion.js";
+const attributeName = (prop) => prop.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+function write(element, attributes) {
+    for (const prop in attributes) {
+        const value = attributes[prop] ?? "";
+        if (prop === "display") {
+            element.style.display = value;
+            continue;
+        }
+        const name = attributeName(prop);
+        if (element.getAttribute(name) !== value)
+            element.setAttribute(name, value);
+    }
+}
+const pools = new WeakMap();
+class Pool {
+    document;
+    entries = new Map();
+    observer;
+    reduced = typeof matchMedia === "function"
+        ? matchMedia("(prefers-reduced-motion: reduce)")
+        : { matches: false, addEventListener() { }, removeEventListener() { } };
+    pointer = { x: NaN, y: NaN };
+    frame;
+    lastFrame = -Infinity;
+    constructor(document) {
+        this.document = document;
+        this.observer =
+            typeof IntersectionObserver === "undefined"
+                ? undefined
+                : new IntersectionObserver((records) => {
+                    for (const record of records) {
+                        const entry = this.entries.get(record.target);
+                        if (!entry)
+                            continue;
+                        if (record.isIntersecting && !entry.visible)
+                            entry.motion.snap = true;
+                        entry.visible = record.isIntersecting;
+                        entry.dirty = true;
+                    }
+                    this.request();
+                }, { rootMargin: "80px" });
+        document.addEventListener("visibilitychange", this.onWake);
+        document.addEventListener("pointermove", this.onPointer, { passive: true });
+        document.addEventListener("pointerleave", this.onPointerLeave);
+        this.reduced.addEventListener("change", this.onWake);
+        window.addEventListener("resize", this.onWake);
+    }
+    onWake = () => {
+        for (const entry of this.entries.values()) {
+            entry.dirty = true;
+            entry.motion.snap = true;
+            entry.rect = null;
+        }
+        if (this.document.hidden && this.frame !== undefined) {
+            cancelAnimationFrame(this.frame);
+            this.frame = undefined;
+        }
+        this.request();
+    };
+    onPointer = (event) => {
+        if (event.pointerType === "touch")
+            return;
+        this.pointer.x = event.clientX;
+        this.pointer.y = event.clientY;
+        this.request();
+    };
+    onPointerLeave = () => {
+        this.pointer.x = NaN;
+        this.pointer.y = NaN;
+        this.request();
+    };
+    request() {
+        if (this.frame === undefined &&
+            !this.document.hidden &&
+            this.entries.size > 0 &&
+            typeof requestAnimationFrame === "function")
+            this.frame = requestAnimationFrame(this.tick);
+    }
+    aim(entry, now) {
+        const { motion } = entry;
+        if (motion.still || motion.view !== "front" || Number.isNaN(this.pointer.x)) {
+            motion.pointer.x = 0;
+            motion.pointer.y = 0;
+            return;
+        }
+        if (!entry.rect || now - entry.rectAt > 500) {
+            entry.rect = entry.svg.getBoundingClientRect();
+            entry.rectAt = now;
+        }
+        const rect = entry.rect;
+        if (!rect.width)
+            return;
+        const cx = rect.left + rect.width / 2;
+        const cy = rect.top + rect.height / 2;
+        const reach = Math.max(rect.width, 32) * 2.5;
+        const dx = this.pointer.x - cx;
+        const dy = this.pointer.y - cy;
+        const distance = Math.hypot(dx, dy);
+        const k = Math.min(1, distance / reach) / (distance || 1);
+        motion.pointer.x = Math.max(-1, Math.min(1, dx * k));
+        motion.pointer.y = Math.max(-1, Math.min(1, dy * k));
+    }
+    tick = (now) => {
+        this.frame = undefined;
+        if (this.document.hidden)
+            return;
+        if (now - this.lastFrame < 1000 / 30) {
+            this.request();
+            return;
+        }
+        const dt = Math.min(0.05, Math.max(0, (now - this.lastFrame) / 1000));
+        this.lastFrame = now;
+        let again = false;
+        for (const entry of this.entries.values()) {
+            if (!entry.visible)
+                continue;
+            const { motion } = entry;
+            motion.still = motion.paused || this.reduced.matches;
+            this.aim(entry, now);
+            const moving = needsMotion(motion, now);
+            if (entry.dirty || moving || entry.terminalFrameDue) {
+                const pose = stepPose(motion, now, entry.dirty ? 0 : dt);
+                this.paint(entry, pose, now);
+                this.setMode(entry, motion.still ? "still" : "live");
+                entry.dirty = false;
+                entry.terminalFrameDue = moving;
+            }
+            again ||= needsMotion(motion, now) && !settled(motion, now);
+            if (Number.isFinite(this.pointer.x) && motion.state === "idle" && !motion.still)
+                again = true;
+        }
+        if (again)
+            this.request();
+    };
+    paint(entry, pose, now) {
+        const frame = computeFrame(entry.motion, pose, now);
+        for (const part in frame) {
+            const element = entry.parts.get(part);
+            if (element)
+                write(element, frame[part]);
+        }
+        entry.svg.dataset.state = entry.motion.state;
+    }
+    setMode(entry, mode) {
+        if (entry.svg.dataset.renderMode === mode)
+            return;
+        entry.svg.dataset.renderMode = mode;
+        entry.callbacks.onModeChange?.(mode);
+    }
+    release(svg) {
+        this.observer?.unobserve(svg);
+        this.entries.delete(svg);
+        if (this.entries.size !== 0)
+            return;
+        if (this.frame !== undefined)
+            cancelAnimationFrame(this.frame);
+        this.observer?.disconnect();
+        this.document.removeEventListener("visibilitychange", this.onWake);
+        this.document.removeEventListener("pointermove", this.onPointer);
+        this.document.removeEventListener("pointerleave", this.onPointerLeave);
+        this.reduced.removeEventListener("change", this.onWake);
+        window.removeEventListener("resize", this.onWake);
+        pools.delete(this.document);
+    }
+}
+export function mountForma(svg, options, callbacks = {}) {
+    const doc = svg.ownerDocument;
+    let pool = pools.get(doc);
+    if (!pool) {
+        pool = new Pool(doc);
+        pools.set(doc, pool);
+    }
+    if (pool.entries.has(svg))
+        throw new Error("This element already has a Forma avatar");
+    const parts = new Map();
+    for (const element of svg.querySelectorAll("[data-part]"))
+        parts.set(element.getAttribute("data-part"), element);
+    const entry = {
+        svg,
+        parts,
+        motion: createMotion(options, performance.now()),
+        visible: !pool.observer,
+        dirty: true,
+        terminalFrameDue: false,
+        callbacks,
+        rect: null,
+        rectAt: -Infinity,
+    };
+    const activePool = pool;
+    pool.entries.set(svg, entry);
+    pool.observer?.observe(svg);
+    pool.request();
+    let disposed = false;
+    return {
+        update(next) {
+            if (disposed)
+                return;
+            updateMotion(entry.motion, next, performance.now());
+            entry.dirty = true;
+            activePool.request();
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            activePool.release(svg);
+        },
+    };
+}

package/dist/internal/forma/still.d.ts

@@ -0,0 +1,4 @@
+import { type Frame } from "./frame.js";
+import type { ResolvedFormaOptions } from "./model.js";
+export declare function stillFrame(options: ResolvedFormaOptions): Frame;
+//# sourceMappingURL=still.d.ts.map

package/dist/internal/forma/still.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"still.d.ts","sourceRoot":"","sources":["../../../src/internal/forma/still.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAgB,MAAM,SAAS,CAAC;AACnD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAGpD,wBAAgB,UAAU,CAAC,OAAO,EAAE,oBAAoB,GAAG,KAAK,CAK/D"}

package/dist/internal/forma/still.js

@@ -0,0 +1,8 @@
+import { computeFrame } from "./frame.js";
+import { createMotion, stepPose } from "./motion.js";
+export function stillFrame(options) {
+    const motion = createMotion({ ...options, paused: true }, 0);
+    motion.still = true;
+    const pose = stepPose(motion, 0, 0);
+    return computeFrame(motion, pose, 0);
+}

package/docs/contract.md

@@ -107,7 +107,7 @@ this same renderer.
 
 ## 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, 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.
+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. `@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/forma-avatar.md

@@ -0,0 +1,92 @@
+# Forma Avatars
+
+Forma is the avatar family for the Agents a company operates inside Nadia,
+and for Nadia herself. It is a character: a coloured shell with a visor and
+two eyes, alive through the approved lifecycle gestures. `@nadicodeai/ui`
+owns its rendering as one SVG per avatar; consuming products own the stored
+appearance, the Agent data, and every fact about status or work.
+
+This system is distinct from Nadia's portrait, which stays the one canonical
+identity in `brand/AGENTS.md` "Nadia's identity". Nadia's avatar here is her
+approved Forma shell: the tricolour, the signature eyes and lash flicks, and
+the Italy hallmark on her right flank (Natural Earth 110m Italy from
+AshKyd/geojson-regions, projected once with d3-geo 3.1.1 into a 512-unit box).
+
+## Forms and colours
+
+A customer picks a form and a colour. Forms are shapes, never roles: choosing
+Goccia grants no tools and changes no instructions, and the product names the
+job. The closed set is Nadia plus seven forms:
+
+| Form | Silhouette | Default shell | Visor | Eyes |
+| --- | --- | --- | --- | --- |
+| `nadia` | The approved shell, tricolour, fixed | verde | black | signature mint |
+| `goccia` | Drop | rosso | black | white |
+| `nuvola` | Cloud | cobalto | ivory | ink |
+| `triangolo` | Rounded triangle | verde | ivory | ink |
+| `esagono` | Hexagon | giallo | black | white |
+| `quadrato` | Squircle | arancio | ivory | ink |
+| `pillola` | Stadium | verde | black | white |
+| `uovo` | Egg | cobalto | black | white |
+
+Shell colours are the Agent identity palette (`identity-verde`, `-cobalto`,
+`-rosso`, `-arancio`, `-giallo`) plus `forma-avorio`; the visor, bezel,
+Nadia's eye light and the blocked sand are the `forma-*` tokens. All of them are owned by
+`packages/design-system/DESIGN.md` and read through their CSS custom
+properties, so an avatar carries no colour of its own. `uovo` is the form an
+Agent wears until a customer chooses; it is never inferred from a name, an
+id, a role label, or a position in a list.
+
+## Construction
+
+Every form carries a core sphere inside its silhouette. The one approved
+visor and the form's eyes ride on that sphere, seen through the engine's
+camera (perspective from 5.2 radii), and the silhouette clips them: the face
+is the same size and curvature on every form, and turning the head moves it
+across the shell the same way, foreshortening at the rim.
+
+The lighting reproduces the engine's studio, number for number where a
+gradient can: the shell is enamel deepened by its own pigment toward the
+rim (a multiply layer), shaded by the hemisphere light toward the floor,
+lit by the wide top-left key card, a hot spot, and the right rim card; the
+visor is black glass with one crisp reflection at its top-left corner, a
+soft haze across the top, the right-edge reflection, and a thin bezel lit
+only where the key reaches it; the eyes carry their halo and a glint, and
+Nadia's Italy hallmark is the engine's ivory engraving at longitude 1.24 on
+her right flank, visible from the side. Blocked morphs every form into the same torus and drains
+its pigment 28% toward `forma-sabbia`, as the approved renders do.
+
+## States and motion
+
+Six states: `idle`, `working`, `thinking`, `waiting`, `blocked`, `done`. The
+choreography is the approved engine's, number for number: the idle sway and
+pointer-following gaze; working's acknowledging nod, scan, beat, three pulsing
+ticks and two orbiting bead trails; thinking's tilt and three thought beads;
+waiting's pause bars; blocked's morph into the ring and bar; done's wind-up,
+full turn, hop, happy eyes and the three-ribbon celebration. A completion
+celebrates once per real transition or `motionKey` change; an initially
+completed avatar holds its finished pose. Waiting and blocked always face
+forward; `view="side"` shows the flank otherwise.
+
+One loop per document drives every mounted avatar at up to 30 frames a
+second. Offscreen and hidden avatars do not render, settled states stop the
+loop, and the pointer turns the heads nearest to it. `paused` and reduced
+motion hold the state's deterministic resting frame, which is also what the
+server renders, effects included (a working still carries its orbit beads, a
+thinking still its thought beads), so no surface ever shows an empty slot and
+no still image is shipped.
+
+## Package shape
+
+`FormaAvatar` (`@nadicodeai/ui/components/forma-avatar`) takes `form`,
+`color`, `state`, `size` (12–512 CSS pixels), `paused`, `view`, and
+`motionKey`. It is decorative by default; a visual that is itself the
+choice, as in a picker, opts into `decorative={false}` with a `label`. It
+exposes `data-forma-avatar`, `data-state`, `data-color` on its host and
+`data-render-mode` (`still` or `live`) on the SVG. The model's closed lists
+(`formaForms`, `formaChoices`, `formaColors`, `formaStates`, `formDetails`,
+`defaultForm`) are exported beside it for pickers and stored-appearance
+mapping; the geometry, rig and frame computation are internal.
+
+Additions to the family go through this document and the design-system
+token contract, never through an ad-hoc visual.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadicodeai/ui",
-  "version": "6.0.0",
+  "version": "6.0.1",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -70,7 +70,7 @@
     "@assistant-ui/react": "0.15.18",
     "@assistant-ui/react-markdown": "0.14.14",
     "@base-ui/react": "^1.8.0",
-    "@nadicodeai/design-system": "6.0.0",
+    "@nadicodeai/design-system": "6.0.1",
     "@paper-design/shaders": "0.0.80",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",