@nadicodeai/ui 0.22.0 → 1.0.1

package/dist/internal/agent-visual/recipes.js

@@ -0,0 +1,72 @@
+export const AGENT_VISUAL_RECIPE_SPECS = {
+    general: {
+        colors: ["cobalto", "verde", "arancio", "giallo", "rosso"],
+        count: 10,
+        frame: 0,
+        material: "solid",
+        posterForm: [
+            [45, 64, 29],
+            [68, 42, 32],
+            [99, 45, 34],
+            [116, 71, 27],
+            [79, 80, 35],
+        ],
+        size: 0.83,
+    },
+    reasoning: {
+        colors: ["cobalto", "verde", "giallo"],
+        count: 10,
+        frame: 0,
+        material: "points",
+        posterForm: [
+            [44, 61, 28],
+            [69, 39, 31],
+            [98, 44, 34],
+            [113, 71, 29],
+            [76, 80, 34],
+        ],
+        size: 0.83,
+    },
+    coordination: {
+        colors: ["verde", "cobalto", "arancio"],
+        count: 8,
+        frame: 2_700,
+        material: "wire",
+        posterForm: [
+            [48, 61, 31],
+            [77, 40, 33],
+            [111, 58, 29],
+            [90, 82, 27],
+        ],
+        size: 0.76,
+    },
+    communication: {
+        colors: ["giallo", "arancio", "rosso"],
+        count: 12,
+        frame: 5_400,
+        material: "solid",
+        posterForm: [
+            [51, 55, 29],
+            [79, 43, 35],
+            [107, 63, 30],
+            [77, 80, 28],
+        ],
+        size: 0.69,
+    },
+    execution: {
+        colors: ["rosso", "arancio", "cobalto"],
+        count: 6,
+        frame: 8_100,
+        material: "particles",
+        posterForm: [
+            [48, 65, 28],
+            [78, 52, 39],
+            [109, 64, 32],
+            [82, 86, 24],
+        ],
+        size: 0.92,
+    },
+};
+export function campoVariable(campo) {
+    return `--nc-campo-${campo}`;
+}

package/dist/internal/agent-visual/renderer.d.ts

@@ -0,0 +1,10 @@
+import { type AgentVisualRecipe } from "./recipes";
+type AgentVisualRendererProps = {
+    host: HTMLElement;
+    onReady: () => void;
+    onUnavailable: () => void;
+    recipe: AgentVisualRecipe;
+};
+export default function AgentVisualRenderer({ host, onReady, onUnavailable, recipe, }: AgentVisualRendererProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=renderer.d.ts.map

package/dist/internal/agent-visual/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../src/internal/agent-visual/renderer.tsx"],"names":[],"mappings":"AAYA,OAAO,EAA4C,KAAK,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAU7F,KAAK,wBAAwB,GAAG;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,MAAM,EAAE,iBAAiB,CAAC;CAC3B,CAAC;AAEF,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,EAC1C,IAAI,EACJ,OAAO,EACP,aAAa,EACb,MAAM,GACP,EAAE,wBAAwB,+BA8G1B"}

package/dist/internal/agent-visual/renderer.js

@@ -0,0 +1,112 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { defaultObjectSizing, getShaderNoiseTexture, metaballsFragmentShader, ShaderFitOptions, ShaderMount as PaperShaderMount, } from "@paper-design/shaders";
+import { useEffect, useRef } from "react";
+import { resolveCampoColor } from "./color.js";
+import { AGENT_VISUAL_RECIPE_SPECS, campoVariable } from "./recipes.js";
+import { AGENT_VISUAL_SHADER } from "./shader.js";
+const MATERIAL_INDEX = {
+    particles: 3,
+    points: 1,
+    solid: 0,
+    wire: 2,
+};
+export default function AgentVisualRenderer({ host, onReady, onUnavailable, recipe, }) {
+    const mountRef = useRef(null);
+    useEffect(() => {
+        const mount = mountRef.current;
+        if (!mount)
+            return;
+        const spec = AGENT_VISUAL_RECIPE_SPECS[recipe];
+        const isSolid = spec.material === "solid";
+        const colors = spec.colors.map((color) => resolveCampoColor(host, campoVariable(color)));
+        const colorBack = resolveCampoColor(host, campoVariable("inchiostro"));
+        const hasPalette = colors.every((color) => color !== null) && colorBack !== null;
+        if (!hasPalette) {
+            onUnavailable();
+            return;
+        }
+        let cancelled = false;
+        let canvas = null;
+        let readyFrame = 0;
+        let shaderMount = null;
+        const clearMount = () => {
+            mount.replaceChildren();
+            mount.removeAttribute("data-paper-shader");
+        };
+        const disposeMount = () => {
+            try {
+                shaderMount?.dispose();
+            }
+            catch {
+                // The deterministic poster remains visible even if vendor cleanup fails.
+            }
+            shaderMount = null;
+            clearMount();
+        };
+        const handleContextLost = (event) => {
+            event.preventDefault();
+            cancelled = true;
+            cancelAnimationFrame(readyFrame);
+            readyFrame = 0;
+            canvas?.removeEventListener("webglcontextlost", handleContextLost);
+            canvas = null;
+            disposeMount();
+            onUnavailable();
+        };
+        const initialize = async () => {
+            try {
+                const noiseTexture = getShaderNoiseTexture();
+                if (noiseTexture && !noiseTexture.complete)
+                    await noiseTexture.decode();
+                if (cancelled)
+                    return;
+                shaderMount = new PaperShaderMount(mount, isSolid ? metaballsFragmentShader : AGENT_VISUAL_SHADER, {
+                    u_colorBack: colorBack,
+                    u_colors: colors,
+                    u_colorsCount: colors.length,
+                    u_count: spec.count,
+                    u_fit: ShaderFitOptions[defaultObjectSizing.fit],
+                    u_noiseTexture: noiseTexture,
+                    u_offsetX: defaultObjectSizing.offsetX,
+                    u_offsetY: defaultObjectSizing.offsetY,
+                    u_originX: defaultObjectSizing.originX,
+                    u_originY: defaultObjectSizing.originY,
+                    u_rotation: defaultObjectSizing.rotation,
+                    u_scale: 1.15,
+                    u_size: spec.size,
+                    u_worldHeight: defaultObjectSizing.worldHeight,
+                    u_worldWidth: defaultObjectSizing.worldWidth,
+                    ...(isSolid
+                        ? {}
+                        : {
+                            u_detail: 0.55,
+                            u_material: MATERIAL_INDEX[spec.material],
+                        }),
+                }, undefined, 0.24, spec.frame, undefined, 720_000);
+                canvas = shaderMount.canvasElement;
+                canvas.addEventListener("webglcontextlost", handleContextLost);
+                readyFrame = requestAnimationFrame(() => {
+                    readyFrame = 0;
+                    if (!cancelled)
+                        onReady();
+                });
+            }
+            catch {
+                canvas?.removeEventListener("webglcontextlost", handleContextLost);
+                canvas = null;
+                disposeMount();
+                if (!cancelled)
+                    onUnavailable();
+            }
+        };
+        void initialize();
+        return () => {
+            cancelled = true;
+            cancelAnimationFrame(readyFrame);
+            canvas?.removeEventListener("webglcontextlost", handleContextLost);
+            disposeMount();
+        };
+    }, [host, onReady, onUnavailable, recipe]);
+    return _jsx("div", { className: "size-full", ref: mountRef });
+}

package/dist/internal/agent-visual/shader.d.ts

@@ -0,0 +1,2 @@
+export declare const AGENT_VISUAL_SHADER = "#version 300 es\nprecision mediump float;\n\nuniform float u_time;\nuniform sampler2D u_noiseTexture;\nuniform vec4 u_colorBack;\nuniform vec4 u_colors[8];\nuniform float u_colorsCount;\nuniform float u_size;\nuniform float u_count;\nuniform float u_material;\nuniform float u_detail;\nuniform vec2 u_resolution;\n\nin vec2 v_objectUV;\nout vec4 fragColor;\n\n#define TWO_PI 6.28318530718\n\nfloat randomR(vec2 p) {\n  vec2 uv = floor(p) / 100. + .5;\n  return texture(u_noiseTexture, fract(uv)).r;\n}\n\nfloat noise(float x) {\n  float i = floor(x);\n  float f = fract(x);\n  float u = f * f * (3.0 - 2.0 * f);\n  return mix(randomR(vec2(i, 0.0)), randomR(vec2(i + 1.0, 0.0)), u);\n}\n\nfloat getBallShape(vec2 uv, vec2 c, float p) {\n  float s = .5 * length(uv - c);\n  s = 1. - clamp(s, 0., 1.);\n  return pow(s, p);\n}\n\nfloat hash21(vec2 p) {\n  p = fract(p * vec2(123.34, 456.21));\n  p += dot(p, p + 45.32);\n  return fract(p.x * p.y);\n}\n\nfloat orderedPoints(vec2 surfaceUV, float depth) {\n  float density = clamp(min(u_resolution.x, u_resolution.y) / 12.0 * u_detail, 6.0, 34.0);\n  vec2 pointUV = fract(surfaceUV * density) - 0.5;\n  float radius = mix(0.14, 0.23, depth);\n  return 1.0 - smoothstep(radius * 0.7, radius, length(pointUV));\n}\n\nfloat triangularWire(vec2 surfaceUV, float depth) {\n  float density = clamp(min(u_resolution.x, u_resolution.y) / 16.0 * u_detail, 5.0, 26.0);\n  vec2 grid = surfaceUV * density;\n  float horizontal = abs(fract(grid.y) - 0.5);\n  float diagonalA = abs(fract(grid.x + grid.y * 0.5) - 0.5);\n  float diagonalB = abs(fract(grid.x - grid.y * 0.5) - 0.5);\n  float nearestLine = min(horizontal, min(diagonalA, diagonalB));\n  float width = mix(0.032, 0.072, depth);\n  return 1.0 - smoothstep(width * 0.55, width, nearestLine);\n}\n\nfloat particleLayer(vec2 surfaceUV, float density, float depth, float time, float layerSeed, float threshold) {\n  vec2 gridUV = surfaceUV * density + layerSeed;\n  vec2 cell = floor(gridUV);\n  vec2 local = fract(gridUV) - 0.5;\n  float seed = hash21(cell + layerSeed);\n  vec2 jitter = vec2(hash21(cell + layerSeed + 3.17), hash21(cell + layerSeed + 8.41)) - 0.5;\n  jitter *= 0.72;\n  jitter += 0.08 * vec2(sin(time * 0.42 + seed * 18.0 + layerSeed), cos(time * 0.31 + seed * 14.0 - layerSeed));\n  float radius = mix(0.055, 0.175, hash21(cell + layerSeed + 14.3)) * mix(0.78, 1.35, depth);\n  float particle = 1.0 - smoothstep(radius * 0.68, radius, length(local - jitter));\n  float brightness = mix(0.45, 1.0, hash21(cell + layerSeed + 24.7));\n  return particle * step(threshold, seed) * brightness;\n}\n\nfloat livingParticles(vec2 surfaceUV, float depth, float time) {\n  float density = clamp(min(u_resolution.x, u_resolution.y) / 6.5 * u_detail, 13.0, 68.0);\n  float dust = particleLayer(surfaceUV, density, depth, time, 0.0, 0.16);\n  float motes = particleLayer(surfaceUV, density * 0.46, depth, time * 0.72, 19.7, 0.62);\n  return max(dust * 0.78, motes);\n}\n\nfloat surfacePattern(vec2 surfaceUV, float depth, float material, float time) {\n  if (material < 0.5) return 1.0;\n  if (material < 1.5) return orderedPoints(surfaceUV, depth);\n  if (material < 2.5) return triangularWire(surfaceUV, depth);\n  return livingParticles(surfaceUV, depth, time);\n}\n\nvoid main() {\n  vec2 shape_uv = v_objectUV + .5;\n  const float firstFrameOffset = 2503.4;\n  float t = .2 * (u_time + firstFrameOffset);\n  vec3 totalColor = vec3(0.);\n  float totalShape = 0.;\n  float totalOpacity = 0.;\n  vec2 weightedCenter = vec2(0.);\n  vec2 weightedOrientation = vec2(0.);\n  float centerWeight = 0.;\n\n  for (int i = 0; i < 20; i++) {\n    if (i >= int(ceil(u_count))) break;\n    float idxFract = float(i) / 20.0;\n    float angle = TWO_PI * idxFract;\n    float speed = 1. - .2 * idxFract;\n    vec2 pos = vec2(.5) + 1e-4 + .9 * (vec2(noise(angle * 10. + float(i) + t * speed), noise(angle * 20. + float(i) - t * speed)) - .5);\n    int safeIndex = i % int(u_colorsCount + 0.5);\n    vec4 ballColor = u_colors[safeIndex];\n    ballColor.rgb *= ballColor.a;\n    float sizeFrac = 1.;\n    if (float(i) > floor(u_count - 1.)) sizeFrac *= fract(u_count);\n    float shape = getBallShape(shape_uv, pos, 45. - 30. * u_size * sizeFrac);\n    shape *= pow(u_size, .2);\n    shape = smoothstep(0., 1., shape);\n    totalColor += ballColor.rgb * shape;\n    totalShape += shape;\n    totalOpacity += ballColor.a * shape;\n    float centerContribution = shape * shape;\n    weightedCenter += pos * centerContribution;\n    weightedOrientation += vec2(cos(angle), sin(angle)) * centerContribution;\n    centerWeight += centerContribution;\n  }\n\n  totalColor /= max(totalShape, 1e-4);\n  totalOpacity /= max(totalShape, 1e-4);\n  float edgeWidth = fwidth(totalShape);\n  float finalShape = smoothstep(.4, .4 + edgeWidth, totalShape);\n  vec2 fieldCenter = weightedCenter / max(centerWeight, 1e-4);\n  vec2 fieldVector = shape_uv - fieldCenter;\n  float depth = smoothstep(0.4, 1.45, totalShape);\n  float fieldRotation = 0.18 * atan(weightedOrientation.y, weightedOrientation.x);\n  float rotationCos = cos(fieldRotation);\n  float rotationSin = sin(fieldRotation);\n  vec2 surfaceUV = fieldCenter + mat2(rotationCos, rotationSin, -rotationSin, rotationCos) * fieldVector * (1.0 + 0.1 * depth);\n  vec2 gradient = vec2(dFdx(totalShape), dFdy(totalShape));\n  vec2 gradientDirection = gradient / max(length(gradient), 1e-4);\n  surfaceUV += gradientDirection * 0.008 * sin(totalShape * 4.0);\n  float feature = surfacePattern(surfaceUV, depth, u_material, t);\n  vec3 normal = normalize(vec3(-gradient * 36.0, 1.0));\n  vec3 lightDirection = normalize(vec3(-0.45, 0.65, 0.8));\n  float surfaceLight = 0.62 + 0.38 * max(dot(normal, lightDirection), 0.0);\n  float baseSurface = mix(0.012, 0.06, depth);\n  float surface = u_material < 0.5 ? 1.0 : mix(baseSurface, surfaceLight, feature);\n  vec3 color = totalColor * finalShape * surface;\n  float opacity = totalOpacity * finalShape * surface;\n  vec3 bgColor = u_colorBack.rgb * u_colorBack.a;\n  color = color + bgColor * (1. - opacity);\n  opacity = opacity + u_colorBack.a * (1. - opacity);\n  color += 1. / 256. * (fract(sin(dot(.014 * gl_FragCoord.xy, vec2(12.9898, 78.233))) * 43758.5453123) - .5);\n  fragColor = vec4(color, opacity);\n}\n";
+//# sourceMappingURL=shader.d.ts.map

package/dist/internal/agent-visual/shader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader.d.ts","sourceRoot":"","sources":["../../../src/internal/agent-visual/shader.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,mBAAmB,+oMAuJ/B,CAAC"}

package/dist/internal/agent-visual/shader.js

@@ -0,0 +1,158 @@
+/*
+ * Modified from Paper Shaders 0.0.78 Metaballs (Apache-2.0).
+ * The metaball field, motion, colour blending, and edge calculation remain
+ * Paper's construction. `surfacePattern` clips the four approved NadicodeAI
+ * identity materials inside that generated form. Attribution ships in NOTICE.
+ */
+export const AGENT_VISUAL_SHADER = `#version 300 es
+precision mediump float;
+
+uniform float u_time;
+uniform sampler2D u_noiseTexture;
+uniform vec4 u_colorBack;
+uniform vec4 u_colors[8];
+uniform float u_colorsCount;
+uniform float u_size;
+uniform float u_count;
+uniform float u_material;
+uniform float u_detail;
+uniform vec2 u_resolution;
+
+in vec2 v_objectUV;
+out vec4 fragColor;
+
+#define TWO_PI 6.28318530718
+
+float randomR(vec2 p) {
+  vec2 uv = floor(p) / 100. + .5;
+  return texture(u_noiseTexture, fract(uv)).r;
+}
+
+float noise(float x) {
+  float i = floor(x);
+  float f = fract(x);
+  float u = f * f * (3.0 - 2.0 * f);
+  return mix(randomR(vec2(i, 0.0)), randomR(vec2(i + 1.0, 0.0)), u);
+}
+
+float getBallShape(vec2 uv, vec2 c, float p) {
+  float s = .5 * length(uv - c);
+  s = 1. - clamp(s, 0., 1.);
+  return pow(s, p);
+}
+
+float hash21(vec2 p) {
+  p = fract(p * vec2(123.34, 456.21));
+  p += dot(p, p + 45.32);
+  return fract(p.x * p.y);
+}
+
+float orderedPoints(vec2 surfaceUV, float depth) {
+  float density = clamp(min(u_resolution.x, u_resolution.y) / 12.0 * u_detail, 6.0, 34.0);
+  vec2 pointUV = fract(surfaceUV * density) - 0.5;
+  float radius = mix(0.14, 0.23, depth);
+  return 1.0 - smoothstep(radius * 0.7, radius, length(pointUV));
+}
+
+float triangularWire(vec2 surfaceUV, float depth) {
+  float density = clamp(min(u_resolution.x, u_resolution.y) / 16.0 * u_detail, 5.0, 26.0);
+  vec2 grid = surfaceUV * density;
+  float horizontal = abs(fract(grid.y) - 0.5);
+  float diagonalA = abs(fract(grid.x + grid.y * 0.5) - 0.5);
+  float diagonalB = abs(fract(grid.x - grid.y * 0.5) - 0.5);
+  float nearestLine = min(horizontal, min(diagonalA, diagonalB));
+  float width = mix(0.032, 0.072, depth);
+  return 1.0 - smoothstep(width * 0.55, width, nearestLine);
+}
+
+float particleLayer(vec2 surfaceUV, float density, float depth, float time, float layerSeed, float threshold) {
+  vec2 gridUV = surfaceUV * density + layerSeed;
+  vec2 cell = floor(gridUV);
+  vec2 local = fract(gridUV) - 0.5;
+  float seed = hash21(cell + layerSeed);
+  vec2 jitter = vec2(hash21(cell + layerSeed + 3.17), hash21(cell + layerSeed + 8.41)) - 0.5;
+  jitter *= 0.72;
+  jitter += 0.08 * vec2(sin(time * 0.42 + seed * 18.0 + layerSeed), cos(time * 0.31 + seed * 14.0 - layerSeed));
+  float radius = mix(0.055, 0.175, hash21(cell + layerSeed + 14.3)) * mix(0.78, 1.35, depth);
+  float particle = 1.0 - smoothstep(radius * 0.68, radius, length(local - jitter));
+  float brightness = mix(0.45, 1.0, hash21(cell + layerSeed + 24.7));
+  return particle * step(threshold, seed) * brightness;
+}
+
+float livingParticles(vec2 surfaceUV, float depth, float time) {
+  float density = clamp(min(u_resolution.x, u_resolution.y) / 6.5 * u_detail, 13.0, 68.0);
+  float dust = particleLayer(surfaceUV, density, depth, time, 0.0, 0.16);
+  float motes = particleLayer(surfaceUV, density * 0.46, depth, time * 0.72, 19.7, 0.62);
+  return max(dust * 0.78, motes);
+}
+
+float surfacePattern(vec2 surfaceUV, float depth, float material, float time) {
+  if (material < 0.5) return 1.0;
+  if (material < 1.5) return orderedPoints(surfaceUV, depth);
+  if (material < 2.5) return triangularWire(surfaceUV, depth);
+  return livingParticles(surfaceUV, depth, time);
+}
+
+void main() {
+  vec2 shape_uv = v_objectUV + .5;
+  const float firstFrameOffset = 2503.4;
+  float t = .2 * (u_time + firstFrameOffset);
+  vec3 totalColor = vec3(0.);
+  float totalShape = 0.;
+  float totalOpacity = 0.;
+  vec2 weightedCenter = vec2(0.);
+  vec2 weightedOrientation = vec2(0.);
+  float centerWeight = 0.;
+
+  for (int i = 0; i < 20; i++) {
+    if (i >= int(ceil(u_count))) break;
+    float idxFract = float(i) / 20.0;
+    float angle = TWO_PI * idxFract;
+    float speed = 1. - .2 * idxFract;
+    vec2 pos = vec2(.5) + 1e-4 + .9 * (vec2(noise(angle * 10. + float(i) + t * speed), noise(angle * 20. + float(i) - t * speed)) - .5);
+    int safeIndex = i % int(u_colorsCount + 0.5);
+    vec4 ballColor = u_colors[safeIndex];
+    ballColor.rgb *= ballColor.a;
+    float sizeFrac = 1.;
+    if (float(i) > floor(u_count - 1.)) sizeFrac *= fract(u_count);
+    float shape = getBallShape(shape_uv, pos, 45. - 30. * u_size * sizeFrac);
+    shape *= pow(u_size, .2);
+    shape = smoothstep(0., 1., shape);
+    totalColor += ballColor.rgb * shape;
+    totalShape += shape;
+    totalOpacity += ballColor.a * shape;
+    float centerContribution = shape * shape;
+    weightedCenter += pos * centerContribution;
+    weightedOrientation += vec2(cos(angle), sin(angle)) * centerContribution;
+    centerWeight += centerContribution;
+  }
+
+  totalColor /= max(totalShape, 1e-4);
+  totalOpacity /= max(totalShape, 1e-4);
+  float edgeWidth = fwidth(totalShape);
+  float finalShape = smoothstep(.4, .4 + edgeWidth, totalShape);
+  vec2 fieldCenter = weightedCenter / max(centerWeight, 1e-4);
+  vec2 fieldVector = shape_uv - fieldCenter;
+  float depth = smoothstep(0.4, 1.45, totalShape);
+  float fieldRotation = 0.18 * atan(weightedOrientation.y, weightedOrientation.x);
+  float rotationCos = cos(fieldRotation);
+  float rotationSin = sin(fieldRotation);
+  vec2 surfaceUV = fieldCenter + mat2(rotationCos, rotationSin, -rotationSin, rotationCos) * fieldVector * (1.0 + 0.1 * depth);
+  vec2 gradient = vec2(dFdx(totalShape), dFdy(totalShape));
+  vec2 gradientDirection = gradient / max(length(gradient), 1e-4);
+  surfaceUV += gradientDirection * 0.008 * sin(totalShape * 4.0);
+  float feature = surfacePattern(surfaceUV, depth, u_material, t);
+  vec3 normal = normalize(vec3(-gradient * 36.0, 1.0));
+  vec3 lightDirection = normalize(vec3(-0.45, 0.65, 0.8));
+  float surfaceLight = 0.62 + 0.38 * max(dot(normal, lightDirection), 0.0);
+  float baseSurface = mix(0.012, 0.06, depth);
+  float surface = u_material < 0.5 ? 1.0 : mix(baseSurface, surfaceLight, feature);
+  vec3 color = totalColor * finalShape * surface;
+  float opacity = totalOpacity * finalShape * surface;
+  vec3 bgColor = u_colorBack.rgb * u_colorBack.a;
+  color = color + bgColor * (1. - opacity);
+  opacity = opacity + u_colorBack.a * (1. - opacity);
+  color += 1. / 256. * (fract(sin(dot(.014 * gl_FragCoord.xy, vec2(12.9898, 78.233))) * 43758.5453123) - .5);
+  fragColor = vec4(color, opacity);
+}
+`;

package/dist/internal/assistant-ui/thread.js

@@ -53,7 +53,7 @@ const ThreadSuggestionItem = () => {
     return (_jsx("div", { className: "aui-thread-welcome-suggestion-display", children: _jsxs(SuggestionPrimitive.Trigger, { send: true, render: _jsx(Button, { variant: "ghost", className: "aui-thread-welcome-suggestion text-foreground hover:bg-muted border-border/60 h-auto gap-1.5 rounded-full border px-3.5 py-1.5 text-sm font-normal whitespace-nowrap transition-colors" }), children: [_jsx(SuggestionPrimitive.Title, { className: "aui-thread-welcome-suggestion-text-1" }), _jsx(SuggestionPrimitive.Description, { className: "aui-thread-welcome-suggestion-text-2 empty:hidden" })] }) }));
 };
 const Composer = () => {
-    return (_jsx(ComposerPrimitive.Root, { className: "aui-composer-root relative flex w-full flex-col", children: _jsxs(ComposerPrimitive.AttachmentDropzone, { render: _jsx("div", { "data-slot": "aui_composer-shell", className: "nc-transition-paint flex w-full flex-col gap-2 rounded-(--composer-radius) border border-border bg-(--composer-bg) p-(--composer-padding) shadow-raised focus-within:border-ring data-[dragging=true]:border-dashed data-[dragging=true]:border-ring data-[dragging=true]:bg-accent" }), children: [_jsx(ComposerAttachments, {}), _jsx(ComposerPrimitive.Input, { placeholder: "Send a message...", className: "aui-composer-input caret-primary placeholder:text-muted-foreground/80 max-h-32 min-h-10 w-full resize-none bg-transparent px-2.5 py-1 text-base outline-none", rows: 1, autoFocus: true, enterKeyHint: "send", "aria-label": "Message input" }), _jsx(ComposerAction, {})] }) }));
+    return (_jsx(ComposerPrimitive.Root, { className: "aui-composer-root relative flex w-full flex-col", children: _jsxs(ComposerPrimitive.AttachmentDropzone, { render: _jsx("div", { "data-slot": "aui_composer-shell", className: "nc-transition-paint flex w-full flex-col gap-2 rounded-(--composer-radius) border border-border bg-(--composer-bg) p-(--composer-padding) focus-within:border-ring data-[dragging=true]:border-dashed data-[dragging=true]:border-ring data-[dragging=true]:bg-accent" }), children: [_jsx(ComposerAttachments, {}), _jsx(ComposerPrimitive.Input, { placeholder: "Send a message...", className: "aui-composer-input caret-primary placeholder:text-muted-foreground/80 max-h-32 min-h-10 w-full resize-none bg-transparent px-2.5 py-1 text-base outline-none", rows: 1, autoFocus: true, enterKeyHint: "send", "aria-label": "Message input" }), _jsx(ComposerAction, {})] }) }));
 };
 const ComposerAction = () => {
     return (_jsxs("div", { className: "aui-composer-action-wrapper relative flex items-center justify-between", children: [_jsx(ComposerAddAttachment, {}), _jsxs("div", { className: "flex items-center gap-1.5", children: [_jsxs(AuiIf, { condition: (s) => s.thread.capabilities.dictation, children: [_jsx(AuiIf, { condition: (s) => s.composer.dictation == null, children: _jsx(ComposerPrimitive.Dictate, { render: _jsx(TooltipIconButton, { tooltip: "Voice input", side: "bottom", type: "button", variant: "ghost", size: "icon", className: "aui-composer-dictate size-7 rounded-full", "aria-label": "Start voice input" }), children: _jsx(MicIcon, { className: "aui-composer-dictate-icon size-4" }) }) }), _jsx(AuiIf, { condition: (s) => s.composer.dictation != null, children: _jsx(ComposerPrimitive.StopDictation, { render: _jsx(TooltipIconButton, { tooltip: "Stop dictation", side: "bottom", type: "button", variant: "ghost", size: "icon", className: "aui-composer-stop-dictation text-destructive size-7 rounded-full", "aria-label": "Stop voice input" }), children: _jsx(SquareIcon, { className: "aui-composer-stop-dictation-icon size-3.5 fill-current motion-safe:animate-pulse" }) }) })] }), _jsx(AuiIf, { condition: (s) => !s.thread.isRunning, children: _jsx(ComposerPrimitive.Send, { render: _jsx(TooltipIconButton, { tooltip: "Send message", side: "bottom", type: "button", variant: "default", size: "icon", className: "aui-composer-send size-7 rounded-full", "aria-label": "Send message" }), children: _jsx(ArrowUpIcon, { className: "aui-composer-send-icon size-4.5" }) }) }), _jsx(AuiIf, { condition: (s) => s.thread.isRunning, children: _jsx(ComposerPrimitive.Cancel, { render: _jsx(Button, { type: "button", variant: "default", size: "icon", className: "aui-composer-cancel size-7 rounded-full", "aria-label": "Stop generating" }), children: _jsx(SquareIcon, { className: "aui-composer-cancel-icon size-3.5 fill-current" }) }) })] })] }));
@@ -102,7 +102,7 @@ const AssistantMessage = () => {
                         } }), _jsx(MessageError, {})] }), _jsxs("div", { "data-slot": "aui_assistant-message-footer", className: cn("ms-2 flex items-center", ACTION_BAR_HEIGHT), children: [_jsx(BranchPicker, {}), _jsx(AssistantActionBar, {})] })] }));
 };
 const AssistantActionBar = () => {
-    return (_jsxs(ActionBarPrimitive.Root, { hideWhenRunning: true, autohide: "not-last", className: "aui-assistant-action-bar-root nc-transition-opacity col-start-3 row-start-2 -ms-1 flex gap-1 text-muted-foreground", children: [_jsxs(ActionBarPrimitive.Copy, { render: _jsx(TooltipIconButton, { tooltip: "Copy" }), children: [_jsx(AuiIf, { condition: (s) => s.message.isCopied, children: _jsx(CheckIcon, {}) }), _jsx(AuiIf, { condition: (s) => !s.message.isCopied, children: _jsx(CopyIcon, {}) })] }), _jsx(ActionBarPrimitive.Reload, { render: _jsx(TooltipIconButton, { tooltip: "Refresh" }), children: _jsx(RefreshCwIcon, {}) }), _jsxs(ActionBarMorePrimitive.Root, { children: [_jsx(ActionBarMorePrimitive.Trigger, { render: _jsx(TooltipIconButton, { tooltip: "More", className: "data-[state=open]:bg-accent" }), children: _jsx(MoreHorizontalIcon, {}) }), _jsx(ActionBarMorePrimitive.Content, { side: "bottom", align: "start", sideOffset: 6, className: "aui-action-bar-more-content nc-transition-opacity bg-popover/95 text-popover-foreground data-[state=closed]:opacity-0 data-[state=open]:opacity-100 z-50 min-w-[8rem] overflow-hidden rounded-xl border p-1.5 shadow-lg backdrop-blur-sm", children: _jsxs(ActionBarPrimitive.ExportMarkdown, { render: _jsx(ActionBarMorePrimitive.Item, { className: "aui-action-bar-more-item hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground flex cursor-pointer items-center gap-2 rounded-lg px-2.5 py-1.5 text-sm outline-none select-none" }), children: [_jsx(DownloadIcon, { className: "size-4" }), "Export as Markdown"] }) })] })] }));
+    return (_jsxs(ActionBarPrimitive.Root, { hideWhenRunning: true, autohide: "not-last", className: "aui-assistant-action-bar-root nc-transition-opacity col-start-3 row-start-2 -ms-1 flex gap-1 text-muted-foreground", children: [_jsxs(ActionBarPrimitive.Copy, { render: _jsx(TooltipIconButton, { tooltip: "Copy" }), children: [_jsx(AuiIf, { condition: (s) => s.message.isCopied, children: _jsx(CheckIcon, {}) }), _jsx(AuiIf, { condition: (s) => !s.message.isCopied, children: _jsx(CopyIcon, {}) })] }), _jsx(ActionBarPrimitive.Reload, { render: _jsx(TooltipIconButton, { tooltip: "Refresh" }), children: _jsx(RefreshCwIcon, {}) }), _jsxs(ActionBarMorePrimitive.Root, { children: [_jsx(ActionBarMorePrimitive.Trigger, { render: _jsx(TooltipIconButton, { tooltip: "More", className: "data-[state=open]:bg-accent" }), children: _jsx(MoreHorizontalIcon, {}) }), _jsx(ActionBarMorePrimitive.Content, { side: "bottom", align: "start", sideOffset: 6, className: "aui-action-bar-more-content nc-transition-opacity z-50 min-w-[8rem] overflow-hidden rounded-xl border-0 bg-popover p-1.5 text-popover-foreground smooth-shadow-ring-xl data-[state=closed]:opacity-0 data-[state=open]:opacity-100", children: _jsxs(ActionBarPrimitive.ExportMarkdown, { render: _jsx(ActionBarMorePrimitive.Item, { className: "aui-action-bar-more-item hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground flex cursor-pointer items-center gap-2 rounded-lg px-2.5 py-1.5 text-sm outline-none select-none" }), children: [_jsx(DownloadIcon, { className: "size-4" }), "Export as Markdown"] }) })] })] }));
 };
 const UserMessage = () => {
     return (_jsxs(MessagePrimitive.Root, { "data-slot": "aui_user-message-root", className: "grid auto-rows-auto grid-cols-[minmax(72px,1fr)_auto] content-start gap-y-2 px-2 [contain-intrinsic-size:auto_200px] [content-visibility:auto] [&:where(>*)]:col-start-2", "data-role": "user", children: [_jsx(UserMessageAttachments, {}), _jsxs("div", { className: "aui-user-message-content-wrapper relative col-start-2 min-w-0", children: [_jsx("div", { className: "aui-user-message-content peer bg-muted text-foreground rounded-xl px-4 py-2 wrap-break-word empty:hidden", children: _jsx(MessagePrimitive.Parts, {}) }), _jsx("div", { className: "aui-user-action-bar-wrapper absolute start-0 top-1/2 -translate-x-full -translate-y-1/2 pe-2 peer-empty:hidden rtl:translate-x-full", children: _jsx(UserActionBar, {}) })] }), _jsx(BranchPicker, { "data-slot": "aui_user-branch-picker", className: "col-span-full col-start-1 row-start-3 -me-1 justify-end" })] }));
@@ -111,7 +111,7 @@ const UserActionBar = () => {
     return (_jsx(ActionBarPrimitive.Root, { hideWhenRunning: true, autohide: "not-last", className: "aui-user-action-bar-root flex flex-col items-end", children: _jsx(ActionBarPrimitive.Edit, { render: _jsx(TooltipIconButton, { tooltip: "Edit", className: "aui-user-action-edit" }), children: _jsx(PencilIcon, {}) }) }));
 };
 const EditComposer = () => {
-    return (_jsx(MessagePrimitive.Root, { "data-slot": "aui_edit-composer-wrapper", className: "flex flex-col px-2 [contain-intrinsic-size:auto_200px] [content-visibility:auto]", children: _jsxs(ComposerPrimitive.Root, { className: "aui-edit-composer-root ms-auto flex w-full max-w-[85%] flex-col rounded-(--composer-radius) border border-border bg-(--composer-bg) shadow-raised", children: [_jsx(ComposerPrimitive.Input, { className: "aui-edit-composer-input text-foreground min-h-14 w-full resize-none bg-transparent px-4 pt-3 pb-1 text-base outline-none", autoFocus: true }), _jsxs("div", { className: "aui-edit-composer-footer mx-2.5 mb-2.5 flex items-center gap-1.5 self-end", children: [_jsx(ComposerPrimitive.Cancel, { render: _jsx(Button, { variant: "ghost", size: "sm", className: "h-8 rounded-full px-3.5" }), children: "Cancel" }), _jsx(ComposerPrimitive.Send, { render: _jsx(Button, { size: "sm", className: "h-8 rounded-full px-3.5" }), children: "Update" })] })] }) }));
+    return (_jsx(MessagePrimitive.Root, { "data-slot": "aui_edit-composer-wrapper", className: "flex flex-col px-2 [contain-intrinsic-size:auto_200px] [content-visibility:auto]", children: _jsxs(ComposerPrimitive.Root, { className: "aui-edit-composer-root ms-auto flex w-full max-w-[85%] flex-col rounded-(--composer-radius) border border-border bg-(--composer-bg)", children: [_jsx(ComposerPrimitive.Input, { className: "aui-edit-composer-input text-foreground min-h-14 w-full resize-none bg-transparent px-4 pt-3 pb-1 text-base outline-none", autoFocus: true }), _jsxs("div", { className: "aui-edit-composer-footer mx-2.5 mb-2.5 flex items-center gap-1.5 self-end", children: [_jsx(ComposerPrimitive.Cancel, { render: _jsx(Button, { variant: "ghost", size: "sm", className: "h-8 rounded-full px-3.5" }), children: "Cancel" }), _jsx(ComposerPrimitive.Send, { render: _jsx(Button, { size: "sm", className: "h-8 rounded-full px-3.5" }), children: "Update" })] })] }) }));
 };
 const BranchPicker = ({ className, ...rest }) => {
     return (_jsxs(BranchPickerPrimitive.Root, { hideWhenSingleBranch: true, className: cn("aui-branch-picker-root text-muted-foreground -ms-2 me-2 inline-flex items-center text-xs", className), ...rest, children: [_jsx(BranchPickerPrimitive.Previous, { render: _jsx(TooltipIconButton, { tooltip: "Previous" }), children: _jsx(ChevronLeftIcon, {}) }), _jsxs("span", { className: "aui-branch-picker-state font-medium", children: [_jsx(BranchPickerPrimitive.Number, {}), " / ", _jsx(BranchPickerPrimitive.Count, {})] }), _jsx(BranchPickerPrimitive.Next, { render: _jsx(TooltipIconButton, { tooltip: "Next" }), children: _jsx(ChevronRightIcon, {}) })] }));

package/dist/styles/globals.css

@@ -14,6 +14,7 @@
 @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";
@@ -53,6 +54,25 @@
   }
 }
 
+@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));
+  }
+
+  .nc-toast {
+    border: 0 !important;
+  }
+
+  @media (prefers-reduced-transparency: reduce) {
+    .nc-glass-control {
+      background: var(--popover);
+      backdrop-filter: none;
+    }
+  }
+}
+
 /*
  * The canonical design-system module owns raw --nc-* mode aliases, semantic
  * roles, and their Tailwind utility bridge for both root and scoped `.dark`
@@ -86,4 +106,5 @@
 }
 
 @source "../components";
+@source "../internal";
 @source "../lib";

package/docs/agents/nadicodeai-ui.md

@@ -36,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/consuming-cross-repo.md

@@ -42,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,18 +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.** 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 public Agent UI 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/`. Consumers receive Thread, attachments, Markdown, reasoning, tools, suggestions, providers, runtimes, hooks, and types from that one domain namespace. The vendor name is not a public NadicodeAI subpath, and the package does not rename, wrap, or rebuild assistant-ui behavior.
+- **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`, 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 presentation and runtime APIs enter through `@nadicodeai/ui/agents`; 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, 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. Every presentation
+mounts the same ambient Paper Metaballs renderer after the reduced-motion
+check. The shared component mounts it only while the visual intersects the
+viewport, releasing its WebGL context offscreen; the vendor pauses it when the
+document is hidden. SSR, first paint, reduced motion,
+missing WebGL, initialization failure, and context loss retain the same
+deterministic 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.