@nadicodeai/ui 8.6.0 → 9.0.1

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

@@ -1,10 +0,0 @@
-import type { ResolvedFormaOptions } from "./model.js";
-export interface FormaHandle {
-    update(options: ResolvedFormaOptions): void;
-    dispose(): void;
-}
-export interface FormaMountCallbacks {
-    onModeChange?: (mode: "live" | "still") => void;
-}
-export declare function mountForma(svg: SVGSVGElement, options: ResolvedFormaOptions, callbacks?: FormaMountCallbacks): FormaHandle;
-//# sourceMappingURL=rig.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"rig.d.ts","sourceRoot":"","sources":["../../../src/internal/forma/rig.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAUpD,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC5C,OAAO,IAAI,IAAI,CAAC;CACjB;AACD,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,KAAK,IAAI,CAAC;CACjD;AAyLD,wBAAgB,UAAU,CACxB,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,oBAAoB,EAC7B,SAAS,GAAE,mBAAwB,GAClC,WAAW,CAwCb"}

package/dist/internal/forma/rig.js

@@ -1,211 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,8 +0,0 @@
-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/dist/internal/forma/stored-appearance.d.ts

@@ -1,29 +0,0 @@
-import { type FormaChoice, type FormaColor } from "./model.js";
-/** What Hermes stores for an Agent's look. Both may be absent or unknown. */
-export interface StoredAppearance {
-    shape?: string | null;
-    color?: string | null;
-}
-/** The `shape` value a chosen form is stored as. */
-export declare const shapeFor: (form: FormaChoice) => string;
-/** The stored shape of the form an Agent wears until a customer chooses one. */
-export declare const defaultShape: string;
-/**
- * The hex each palette colour is stored as. Hermes keeps an Agent's colour as
- * a CSS colour for its own surfaces, so the stored spelling is a value rather
- * than a token reference; `stored-appearance.test.ts` holds this table to the
- * shipped design-system tokens, and the ESLint colour-literal exemption in the
- * root config names this file.
- */
-export declare const formaColorValues: Record<FormaColor, string>;
-/**
- * Resolve the stored strings to what `FormaAvatar` draws. An unknown shape is
- * the default form and an unknown colour is undefined, which leaves the form
- * its own pigment. The root Agent is the caller's business: a caller that owns
- * one passes `form="nadia"` instead of asking here.
- */
-export declare function resolveAppearance(stored: StoredAppearance): {
-    form: FormaChoice;
-    color: FormaColor | undefined;
-};
-//# sourceMappingURL=stored-appearance.d.ts.map

package/dist/internal/forma/stored-appearance.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"stored-appearance.d.ts","sourceRoot":"","sources":["../../../src/internal/forma/stored-appearance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAA0C,MAAM,SAAS,CAAC;AAEpG,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,oDAAoD;AACpD,eAAO,MAAM,QAAQ,GAAI,MAAM,WAAW,KAAG,MAAyB,CAAC;AAEvE,gFAAgF;AAChF,eAAO,MAAM,YAAY,EAAE,MAA8B,CAAC;AAc1D;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAOvD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG;IAC3D,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;CAC/B,CAEA"}

package/dist/internal/forma/stored-appearance.js

@@ -1,53 +0,0 @@
-import { defaultForm, formaChoices, formaColors } from "./model.js";
-/** The `shape` value a chosen form is stored as. */
-export const shapeFor = (form) => `forma:${form}`;
-/** The stored shape of the form an Agent wears until a customer chooses one. */
-export const defaultShape = shapeFor(defaultForm);
-/**
- * The five role names the launch Agents were stored under, each kept at the
- * form it wore. Forms are shapes, never roles: nothing new is stored this way.
- */
-const legacyShapes = new Map([
-    ["forma:research", "uovo"],
-    ["forma:build", "goccia"],
-    ["forma:design", "nuvola"],
-    ["forma:operate", "quadrato"],
-    ["forma:review", "esagono"],
-]);
-/**
- * The hex each palette colour is stored as. Hermes keeps an Agent's colour as
- * a CSS colour for its own surfaces, so the stored spelling is a value rather
- * than a token reference; `stored-appearance.test.ts` holds this table to the
- * shipped design-system tokens, and the ESLint colour-literal exemption in the
- * root config names this file.
- */
-export const formaColorValues = {
-    verde: "#00a85a",
-    cobalto: "#1e3cff",
-    rosso: "#d3302f",
-    arancio: "#ff5a1f",
-    giallo: "#ffc220",
-    avorio: "#e9e7db",
-};
-/**
- * Resolve the stored strings to what `FormaAvatar` draws. An unknown shape is
- * the default form and an unknown colour is undefined, which leaves the form
- * its own pigment. The root Agent is the caller's business: a caller that owns
- * one passes `form="nadia"` instead of asking here.
- */
-export function resolveAppearance(stored) {
-    return { form: formFor(stored.shape), color: colorFor(stored.color) };
-}
-function formFor(shape) {
-    if (!shape)
-        return defaultForm;
-    // A Map, not an object: the shape is a stored string from a machine, and an
-    // object lookup would hand back `toString` or `constructor` for those spellings.
-    return (formaChoices.find((form) => shape === shapeFor(form)) ?? legacyShapes.get(shape) ?? defaultForm);
-}
-function colorFor(color) {
-    if (!color)
-        return undefined;
-    const stored = color.toLowerCase();
-    return formaColors.find((name) => stored === formaColorValues[name] || color === name);
-}

package/docs/agent-visual.md

@@ -1,114 +0,0 @@
-# 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
-output. Those facts stay in text, status components, assistant-ui, and the
-product surfaces that own them.
-
-This system is distinct from Nadia's portrait. Nadia keeps the one canonical
-identity in `brand/AGENTS.md` "Nadia's identity"; Agent visuals identify the other named,
-role-specific Agents that a company operates inside Nadia.
-
-## Approved form
-
-- One connected metaball entity sits on a true-black field.
-- The entity is always multicolour and draws its five hues from the Agent
-  identity palette: Cobalto, Verde, Arancio, Giallo, and Rosso. That palette
-  is owned by `packages/design-system/DESIGN.md`, which holds the token names
-  and values; this document holds the recipes that arrange them.
-- The entity itself carries the surface. Texture never paints the background.
-- The four approved surfaces are solid, ordered points, borderless triangular
-  wire, and irregular living particles.
-- Ordered points form a regular, readable field. Living particles vary in
-  position, size, and brightness so the two surfaces remain visibly distinct.
-- Triangular wire has no outer stroke. The clipped triangular network alone
-  defines the body.
-- The visual has no initials, letters, face, avatar frame, status tint, or
-  caller-selected colour.
-
-## Closed recipes
-
-The five recipes below are the complete public set. Their names, palettes,
-surface assignments, ball counts, sizes, and deterministic frames are fixed.
-Applications assign one recipe explicitly. They never hash an id, inspect a
-free-form role label, randomize a recipe, or expose these parameters to a
-caller.
-
-| Recipe        | Surface          | Palette order                          | Count | Size | Still frame |
-| ------------- | ---------------- | -------------------------------------- | ----: | ---: | ----------: |
-| General       | Solid            | Cobalto, Verde, Arancio, Giallo, Rosso |    10 | 0.83 |           0 |
-| Reasoning     | Ordered points   | Cobalto, Verde, Giallo                 |    10 | 0.83 |           0 |
-| Coordination  | Triangular wire  | Verde, Cobalto, Arancio                |     8 | 0.76 |        2700 |
-| Communication | Solid            | Giallo, Arancio, Rosso                 |    12 | 0.69 |        5400 |
-| Execution     | Living particles | Rosso, Arancio, Cobalto                |     6 | 0.92 |        8100 |
-
-`general` is the deliberate fallback when a product has not stored an Agent's
-recipe yet. It is not an inference from the Agent's name, id, role, status, or
-position in a list.
-
-## Placement and motion
-
-The same recipe keeps the same identity wherever it appears. Each recipe owns
-both its approved deterministic SVG poster form and its ambient shader
-parameters in one internal record. The two presentations are intentionally
-recognizable realizations of one recipe, not pixel-identical renderers.
-
-- Registry cells, `AgentCard`, focal Agent detail, and the design-system
-  showcase use the ambient reference motion at speed 0.24. The text name
-  remains the primary identity, and motion never reports status or activity.
-- The shared component mounts the renderer only while the visual intersects
-  the viewport and releases its WebGL context offscreen; the vendor pauses it
-  when the document is hidden. Compact registry placement therefore keeps the
-  same identity without retaining offscreen shader canvases.
-- Reduced-motion, missing WebGL2, shader initialization failure, and context
-  loss all keep the same deterministic still. They do not substitute a new
-  shape, colour, icon, or blank box.
-- The still renders before the client shader is eligible so server rendering
-  and hydration never present an empty visual slot.
-
-The visual is normally hidden from assistive technology because the adjacent
-Agent name carries the identity. A picker in which the visual is itself the
-choice may give it an accessible name. Status and job information never enter
-that name.
-
-## Implementation ownership
-
-`@nadicodeai/ui` owns the typed `AgentVisual` implementation and the
-presentational `AgentCard` composition. The API exposes the closed recipe and
-approved presentation roles, not raw colours, shader source, speed, count,
-frame, density, material, or arbitrary tuning.
-
-Consuming products own the stored recipe assignment, Agent data, routing,
-actions, permissions, and placement. An Agent registry remains a table when
-the job is comparison; the visual may appear inside its identity cell without
-turning the row into a new `AgentRow` component.
-
-## Source and modification record
-
-The solid form mounts the published `metaballsFragmentShader` from
-`@paper-design/shaders` version `0.0.78` verbatim. The other three surfaces use
-a NadicodeAI modification of that release's published Metaballs shader. The
-modification preserves metaball generation, motion, colour blending, edge
-calculation, and background composition, then changes only the fill clipped
-inside the final entity shape.
-
-The package is Apache-2.0 and includes a `NOTICE` file. Any distributed
-modified source must keep the Apache-2.0 license, retain the upstream notices,
-carry a prominent modification notice, and include the upstream NOTICE text:
-
-```text
-Paper Shaders
-Copyright 2026 Paper
-
-Powered by Paper Shaders:
-https://shaders.paper.design
-```
-
-The identity system is one closed, package-owned system; additions go through
-this document, never through a new ad-hoc visual.

package/docs/forma-avatar.md

@@ -1,110 +0,0 @@
-# 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.
-
-The stored appearance resolves in this package too, so every product draws one
-Agent the same way. `StoredAppearance` is the pair of strings a product stores, `shape`
-and `color`, either of which may be absent or unknown. `resolveAppearance`
-answers the `form` and `color` the avatar takes: an unknown shape is
-`defaultForm`, the five retired role shapes keep the form each one wore, and an
-unknown colour is `undefined`, which leaves the form its own pigment. A stored
-colour matches a palette hex in any case or the bare colour name.
-The resolver lives in `@nadicodeai/ui/components/forma-appearance`, which
-carries no `"use client"`: `FormaAvatar` is a client component, and a pure
-function re-exported from a client module becomes a client reference a server
-cannot call, so the two entry points do not re-export each other and every
-consumer imports the look from one and the avatar from the other.
-`shapeFor(form)` writes the stored spelling of a chosen form, `defaultShape` is
-`shapeFor(defaultForm)`, and `formaColorValues` is the hex each palette colour
-is stored as, held to the shipped design-system tokens by a test beside the
-resolver. The root Agent is the product's decision, not the resolver's: a
-product that owns one passes `form="nadia"` itself.
-
-Additions to the family go through this document and the design-system
-token contract, never through an ad-hoc visual.