@atmos.build/ui 0.1.0 → 0.1.2

package/dist/components/diff-stat-format.d.ts

@@ -0,0 +1,9 @@
+/**
+ * How a diff's line counts are written down.
+ *
+ * Exact below a thousand and abbreviated above it: a reviewer wants to know a hunk touched
+ * seven lines, and only that a rewrite touched roughly sixteen hundred. Abbreviation goes
+ * through `Intl.NumberFormat` rather than a hardcoded `k`, so a five-figure refactor stays the
+ * same width as a one-line fix in every locale.
+ */
+export declare function compactFormatter(locale?: string): (value: number) => string;

package/dist/components/diff-stat-format.js

@@ -0,0 +1,13 @@
+/**
+ * How a diff's line counts are written down.
+ *
+ * Exact below a thousand and abbreviated above it: a reviewer wants to know a hunk touched
+ * seven lines, and only that a rewrite touched roughly sixteen hundred. Abbreviation goes
+ * through `Intl.NumberFormat` rather than a hardcoded `k`, so a five-figure refactor stays the
+ * same width as a one-line fix in every locale.
+ */
+export function compactFormatter(locale) {
+    const exact = new Intl.NumberFormat(locale);
+    const compact = new Intl.NumberFormat(locale, { notation: 'compact', maximumFractionDigits: 1 });
+    return (value) => (value < 1000 ? exact.format(value) : compact.format(value));
+}

package/dist/components/diff-stat-label.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+export interface DiffStatLabelProps extends Omit<React.ComponentProps<'span'>, 'children'> {
+    additions: number;
+    deletions: number;
+    /**
+     * The whole label as one string, for readers who get it announced rather than scanned.
+     * Required because the visible form is punctuation and digits, which is not a sentence in
+     * any language — the caller is the only place that can translate it.
+     */
+    label: string;
+    /** Formatting locale. Left to the runtime's own when the caller has no opinion. */
+    locale?: string;
+    size?: 'sm' | 'md';
+}
+/**
+ * How much a diff changed, in the two numbers a reviewer actually scans for.
+ *
+ * The colours are the diff surface's own `--diff-added` / `--diff-removed` rather than the
+ * status palette's success and danger: this label sits next to the lines it counts, and a
+ * green borrowed from "operation succeeded" reads as a different kind of statement.
+ *
+ * Counts go through `Intl.NumberFormat` rather than a hand-rolled `k`, which means the width
+ * is the locale's decision and not ours — German short notation does not abbreviate thousands
+ * at all, so a German reader sees `24.019` where an English one sees `24K`. Showing them an
+ * English abbreviation instead would be narrower and wrong.
+ */
+export declare function DiffStatLabel({ additions, deletions, label, locale, size, className, ...props }: DiffStatLabelProps): React.JSX.Element;

package/dist/components/diff-stat-label.js

@@ -0,0 +1,24 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from 'react';
+import { cn } from '../lib/cn.js';
+import { compactFormatter } from './diff-stat-format.js';
+const SIZES = { sm: 'gap-1 text-[11px]', md: 'gap-1.5 text-xs' };
+/**
+ * How much a diff changed, in the two numbers a reviewer actually scans for.
+ *
+ * The colours are the diff surface's own `--diff-added` / `--diff-removed` rather than the
+ * status palette's success and danger: this label sits next to the lines it counts, and a
+ * green borrowed from "operation succeeded" reads as a different kind of statement.
+ *
+ * Counts go through `Intl.NumberFormat` rather than a hand-rolled `k`, which means the width
+ * is the locale's decision and not ours — German short notation does not abbreviate thousands
+ * at all, so a German reader sees `24.019` where an English one sees `24K`. Showing them an
+ * English abbreviation instead would be narrower and wrong.
+ */
+export function DiffStatLabel({ additions, deletions, label, locale, size = 'sm', className, ...props }) {
+    const format = React.useMemo(() => compactFormatter(locale), [locale]);
+    const added = Math.max(0, Math.trunc(additions));
+    const removed = Math.max(0, Math.trunc(deletions));
+    return (_jsx("span", { "data-slot": "diff-stat-label", className: cn('inline-flex shrink-0 items-center font-mono tabular-nums', SIZES[size], className), "aria-label": label, ...props, children: added === 0 && removed === 0 ? (_jsx("span", { className: "text-muted-foreground", "aria-hidden": true, children: "\u2014" })) : (_jsxs(_Fragment, { children: [added > 0 ? (_jsxs("span", { className: "text-diff-added", "aria-hidden": true, children: ["+", format(added)] })) : null, removed > 0 ? (_jsxs("span", { className: "text-diff-removed", "aria-hidden": true, children: ["\u2212", format(removed)] })) : null] })) }));
+}

package/dist/components/naut-avatar-engine.d.ts

@@ -31,12 +31,20 @@ export interface NautAvatarOptions {
     seed?: number;
     idle?: boolean;
 }
+export interface NautAvatarAttributeElement {
+    setAttribute(name: string, value: string): void;
+}
+export interface NautAvatarEyeElement extends NautAvatarAttributeElement {
+    style: {
+        opacity: string;
+    };
+}
 export interface NautAvatarElements {
-    root: SVGGElement;
-    body: SVGPathElement;
-    eyes: SVGGElement;
-    eyeL: SVGPathElement;
-    eyeR: SVGPathElement;
+    root: NautAvatarAttributeElement;
+    body: NautAvatarAttributeElement;
+    eyes: NautAvatarAttributeElement;
+    eyeL: NautAvatarEyeElement;
+    eyeR: NautAvatarEyeElement;
 }
 /**
  * Framework-agnostic renderer: owns the animation state and writes attributes onto the
@@ -62,9 +70,13 @@ export declare class NautAvatarEngine {
     private readonly face;
     private targetFace;
     private readonly idleState;
+    /** An expression holds one eye shape forever; idle opens the eyes between beats. */
+    private readonly eyeRest;
     private el;
+    private readonly rendered;
     constructor(opts?: NautAvatarOptions);
     attach(el: NautAvatarElements): void;
+    get needsResponsiveFrameRate(): boolean;
     setShape(shape: NautShape): void;
     setColor(color: NautColor): void;
     setExpression(key: NautExpression, instant?: boolean): void;
@@ -73,7 +85,11 @@ export declare class NautAvatarEngine {
     settle(): void;
     update(dt: number): void;
     private updateIdle;
+    /** Eases the eyes back to their neutral open shape and back into the expression. */
+    private restEyes;
     private render;
+    private writeAttribute;
+    private writeStyle;
 }
 /** Stable pseudo-random pick so the same id always gets the same appearance. */
 export declare function hashSeed(input: string): number;

package/dist/components/naut-avatar-engine.js

@@ -148,6 +148,7 @@ const NEUTRAL_HEAD = {
     sy: 1,
 };
 const eyeKey = (param, side) => `${param}${side}`;
+const EYE_KEYS = EYE_PARAMS.flatMap((param) => [eyeKey(param, 'L'), eyeKey(param, 'R')]);
 function expandFace(spec) {
     const out = {};
     for (const [k, v] of Object.entries(spec)) {
@@ -223,6 +224,7 @@ const EXPRESSIONS = {
         },
     },
     sleepy: {
+        fixedEyes: true,
         face: { topCut: 0.55, botCut: 0, round: 0.6, gazeY: 0.25, headY: 3 },
         loop: (t, o) => {
             const s = Math.max(0, Math.sin(t * 1.2));
@@ -240,6 +242,7 @@ const EXPRESSIONS = {
         },
     },
     error: {
+        fixedEyes: true,
         face: { cross: 1, w: 15, h: 15, pill: 0, round: 0.2 },
         loop: (t, o) => {
             o.headX += Math.sin(t * 90) * Math.exp(-(t % 2.4) * 3) * 3;
@@ -252,7 +255,10 @@ const EXPRESSIONS = {
             o.roll += Math.sin(t * 0.7) * 3;
         },
     },
-    wink: { face: { topCutR: 0.5, botCutR: 0.44, smileL: 0.35, round: 0.6, roll: -3 } },
+    wink: {
+        fixedEyes: true,
+        face: { topCutR: 0.5, botCutR: 0.44, smileL: 0.35, round: 0.6, roll: -3 },
+    },
     focused: {
         face: { topCut: 0.28, botCut: 0.22, round: 0.25, w: 8.5, h: 17 },
         loop: (t, o) => {
@@ -276,6 +282,7 @@ const EXPRESSIONS = {
     },
     smug: { face: { topCut: 0.42, topSlant: -8, round: 0.3, gazeX: 0.45, roll: -4, smile: 0.25 } },
     talking: {
+        fixedEyes: true,
         face: {},
         loop: (t, o) => {
             const s = Math.abs(Math.sin(t * 9)) * 0.55 + Math.abs(Math.sin(t * 5.3)) * 0.45;
@@ -286,6 +293,7 @@ const EXPRESSIONS = {
         },
     },
     loading: {
+        fixedEyes: true,
         face: { w: 7, h: 7, round: 1 },
         loop: (t, o) => {
             o.gazeX += Math.cos(t * 3) * 0.75;
@@ -599,6 +607,11 @@ function nodePath(nodes) {
 }
 const cloneNodes = (nodes) => nodes.map((n) => [n[0], n[1], n[2], n[3], n[4], n[5]]);
 export const NAUT_VIEWBOX = '-126 -126 252 252';
+/** How long a mood wears its own eye shape before the face rests, and how long it rests. */
+const HOLD_EXPRESSION_S = 3.4;
+const HOLD_EXPRESSION_JITTER_S = 2.6;
+const OPEN_EYES_S = 1.8;
+const OPEN_EYES_JITTER_S = 1.4;
 /**
  * Framework-agnostic renderer: owns the animation state and writes attributes onto the
  * SVG elements it is given. Call `update(dt)` once per frame.
@@ -630,7 +643,10 @@ export class NautAvatarEngine {
         curGazeY: 0,
         curRoll: 0,
     };
+    /** An expression holds one eye shape forever; idle opens the eyes between beats. */
+    eyeRest = { open: 0, cur: 0, next: HOLD_EXPRESSION_S };
     el = null;
+    rendered = new Map();
     constructor(opts = {}) {
         this.rand = rng(opts.seed ?? 1);
         this.shape = opts.shape ?? 'circle';
@@ -639,6 +655,7 @@ export class NautAvatarEngine {
         this.idle = opts.idle ?? true;
         this.time = this.rand() * 100;
         this.idleState.nextBlink = 2 + this.rand() * 3;
+        this.eyeRest.next = HOLD_EXPRESSION_S + this.rand() * HOLD_EXPRESSION_JITTER_S;
         this.nodes = cloneNodes(SHAPES[this.shape].nodes);
         this.sphere = SHAPES[this.shape].sphere;
         this.eyeYOff = SHAPES[this.shape].eyeY;
@@ -648,6 +665,17 @@ export class NautAvatarEngine {
     }
     attach(el) {
         this.el = el;
+        this.rendered.clear();
+    }
+    get needsResponsiveFrameRate() {
+        const targetGazeX = this.gazeTarget?.x ?? this.idleState.gazeX;
+        const targetGazeY = this.gazeTarget?.y ?? this.idleState.gazeY;
+        return (this.gestures.length > 0 ||
+            Math.abs(this.idleState.curGazeX - targetGazeX) > 0.01 ||
+            Math.abs(this.idleState.curGazeY - targetGazeY) > 0.01 ||
+            Math.abs(this.idleState.curRoll - this.idleState.roll) > 0.02 ||
+            Math.abs(this.eyeRest.cur - this.eyeRest.open) > 0.01 ||
+            FACE_KEYS.some((key) => Math.abs(this.face[key] - this.targetFace[key]) > 0.002));
     }
     setShape(shape) {
         this.shape = shape;
@@ -662,8 +690,14 @@ export class NautAvatarEngine {
         if (changed || instant)
             this.emotionTime = 0;
         this.targetFace = { ...NEUTRAL, ...expandFace(def.face) };
-        if (instant)
+        if (changed || instant) {
+            this.eyeRest.open = 0;
+            this.eyeRest.next = HOLD_EXPRESSION_S + this.rand() * HOLD_EXPRESSION_JITTER_S;
+        }
+        if (instant) {
             Object.assign(this.face, this.targetFace);
+            this.eyeRest.cur = 0;
+        }
         if (def.enter && !instant && changed)
             this.play(def.enter);
     }
@@ -673,6 +707,8 @@ export class NautAvatarEngine {
     /** Snap every tween to its target (used for static renders / reduced motion). */
     settle() {
         Object.assign(this.face, this.targetFace);
+        this.eyeRest.open = 0;
+        this.eyeRest.cur = 0;
         this.nodes = cloneNodes(SHAPES[this.shape].nodes);
         this.sphere = SHAPES[this.shape].sphere;
         this.eyeYOff = SHAPES[this.shape].eyeY;
@@ -697,6 +733,7 @@ export class NautAvatarEngine {
         if (def.loop)
             def.loop(this.emotionTime, o);
         this.updateIdle(dt, o);
+        this.restEyes(dt, o, def);
         for (const g of this.gestures) {
             g.t += dt / GESTURES[g.key].dur;
             GESTURES[g.key].fn(clamp(g.t, 0, 1), o);
@@ -747,14 +784,34 @@ export class NautAvatarEngine {
         o.gazeY += s.curGazeY;
         o.roll += s.curRoll;
     }
+    /** Eases the eyes back to their neutral open shape and back into the expression. */
+    restEyes(dt, o, def) {
+        const rest = this.eyeRest;
+        if (this.idle && !def.fixedEyes) {
+            rest.next -= dt;
+            if (rest.next <= 0) {
+                rest.open = rest.open > 0.5 ? 0 : 1;
+                rest.next = rest.open
+                    ? OPEN_EYES_S + this.rand() * OPEN_EYES_JITTER_S
+                    : HOLD_EXPRESSION_S + this.rand() * HOLD_EXPRESSION_JITTER_S;
+            }
+        }
+        else
+            rest.open = 0;
+        rest.cur = approach(rest.cur, rest.open, 3, dt);
+        if (rest.cur < 0.002)
+            return;
+        for (const k of EYE_KEYS)
+            o[k] = lerp(o[k], NEUTRAL[k], rest.cur);
+    }
     render(o) {
         const el = this.el;
         if (!el)
             return;
-        el.root.setAttribute('transform', `translate(${o.headX.toFixed(2)} ${o.headY.toFixed(2)}) scale(${o.sx.toFixed(3)} ${o.sy.toFixed(3)})`);
-        el.body.setAttribute('d', nodePath(this.nodes));
-        el.body.setAttribute('fill', NAUT_COLORS[this.color]);
-        el.eyes.setAttribute('transform', `rotate(${o.roll.toFixed(2)})`);
+        this.writeAttribute('root.transform', el.root, 'transform', `translate(${o.headX.toFixed(1)} ${o.headY.toFixed(1)}) scale(${o.sx.toFixed(3)} ${o.sy.toFixed(3)})`);
+        this.writeAttribute('body.d', el.body, 'd', nodePath(this.nodes));
+        this.writeAttribute('body.fill', el.body, 'fill', NAUT_COLORS[this.color]);
+        this.writeAttribute('eyes.transform', el.eyes, 'transform', `rotate(${o.roll.toFixed(1)})`);
         const yaw = clamp(o.gazeX, -1.3, 1.3) * 0.85 + o.spin;
         const pitch = -clamp(o.gazeY, -1.3, 1.3) * 0.7;
         const R = this.sphere;
@@ -766,7 +823,7 @@ export class NautAvatarEngine {
             const poly = eyePolygon(p, sgn);
             const eye = side === 'L' ? el.eyeL : el.eyeR;
             if (!poly.length) {
-                eye.setAttribute('d', '');
+                this.writeAttribute(`eye${side}.d`, eye, 'd', '');
                 continue;
             }
             const fr = eyeFrame(sgn * o.eyeSep, o.eyeLat, yaw, pitch);
@@ -778,12 +835,24 @@ export class NautAvatarEngine {
             const vx = lerp(0, fr.V[0], curve);
             const vy = lerp(1, fr.V[1], curve);
             const d = poly
-                .map(([lx, ly], i) => `${i ? 'L' : 'M'} ${(cx + ux * lx + vx * ly).toFixed(2)} ${(cy + uy * lx + vy * ly).toFixed(2)}`)
+                .map(([lx, ly], i) => `${i ? 'L' : 'M'} ${(cx + ux * lx + vx * ly).toFixed(1)} ${(cy + uy * lx + vy * ly).toFixed(1)}`)
                 .join(' ');
-            eye.setAttribute('d', d + ' Z');
-            eye.style.opacity = fr.P[2] > 0 ? '1' : '0';
+            this.writeAttribute(`eye${side}.d`, eye, 'd', d + ' Z');
+            this.writeStyle(`eye${side}.opacity`, eye.style, 'opacity', fr.P[2] > 0 ? '1' : '0');
         }
     }
+    writeAttribute(key, element, name, value) {
+        if (this.rendered.get(key) === value)
+            return;
+        this.rendered.set(key, value);
+        element.setAttribute(name, value);
+    }
+    writeStyle(key, style, name, value) {
+        if (this.rendered.get(key) === value)
+            return;
+        this.rendered.set(key, value);
+        style[name] = value;
+    }
 }
 /** Stable pseudo-random pick so the same id always gets the same appearance. */
 export function hashSeed(input) {

package/dist/components/naut-avatar.d.ts

@@ -17,6 +17,8 @@ export interface NautAvatarProps extends Omit<React.SVGProps<SVGSVGElement>, 're
         x: number;
         y: number;
     } | null;
+    /** Glance at a mouse that comes near the face. Ignored once `gaze` is given. */
+    followPointer?: boolean;
     /** Any stable id — keeps a list of Nauts from blinking in unison. */
     seed?: string | number;
 }

package/dist/components/naut-avatar.js

@@ -4,32 +4,104 @@ import * as React from 'react';
 import { useReducedMotion } from 'motion/react';
 import { cn } from '../lib/cn.js';
 import { NAUT_VIEWBOX, NautAvatarEngine, hashSeed, } from './naut-avatar-engine.js';
+import { pointerGaze } from './naut-pointer-gaze.js';
 export { NAUT_COLORS, NAUT_COLOR_KEYS, NAUT_EXPRESSIONS, NAUT_GESTURES, NAUT_SHAPES, isNautColor, isNautShape, nautAppearanceForSeed, } from './naut-avatar-engine.js';
+/** A face can be carried across the page by something other than a mouse or a scroll. */
+const RECT_MAX_AGE_MS = 500;
+const IDLE_FRAME_MS = 1000 / 3;
+const RESPONSIVE_FRAME_MS = 1000 / 20;
+const POINTER_SETTLE_MS = 350;
+/** Where the mouse is, shared by every face so one listener serves the page. */
+const pointer = {
+    x: 0,
+    y: 0,
+    active: false,
+    lastMovedAt: 0,
+    /** Bumps whenever cached face rects could have gone stale. */
+    moved: 0,
+    onPointer(event) {
+        if (event.pointerType === 'touch') {
+            pointer.active = false;
+            return;
+        }
+        pointer.x = event.clientX;
+        pointer.y = event.clientY;
+        pointer.active = true;
+        pointer.lastMovedAt = performance.now();
+        pointer.moved++;
+    },
+    onLeave() {
+        pointer.active = false;
+    },
+    onLayout() {
+        pointer.moved++;
+    },
+    listen() {
+        window.addEventListener('pointermove', pointer.onPointer, { passive: true });
+        window.addEventListener('pointerdown', pointer.onPointer, { passive: true });
+        document.addEventListener('mouseleave', pointer.onLeave);
+        window.addEventListener('scroll', pointer.onLayout, { passive: true, capture: true });
+        window.addEventListener('resize', pointer.onLayout, { passive: true });
+    },
+    stop() {
+        window.removeEventListener('pointermove', pointer.onPointer);
+        window.removeEventListener('pointerdown', pointer.onPointer);
+        document.removeEventListener('mouseleave', pointer.onLeave);
+        window.removeEventListener('scroll', pointer.onLayout, { capture: true });
+        window.removeEventListener('resize', pointer.onLayout);
+        pointer.active = false;
+    },
+};
+function aimAtPointer(entry, now) {
+    const svg = entry.svg;
+    if (!pointer.active || !svg) {
+        entry.engine.gazeTarget = null;
+        return;
+    }
+    if (entry.rectAt !== pointer.moved || now - entry.rectTime > RECT_MAX_AGE_MS) {
+        entry.rect = svg.getBoundingClientRect();
+        entry.rectAt = pointer.moved;
+        entry.rectTime = now;
+    }
+    entry.engine.gazeTarget = entry.rect ? pointerGaze(entry.rect, pointer.x, pointer.y) : null;
+}
 /** One animation frame loop drives every mounted avatar; offscreen ones sit out. */
 const ticker = {
     entries: new Set(),
     frame: 0,
-    last: 0,
     tick(now) {
-        const dt = Math.min((now - ticker.last) / 1000, 0.05);
-        ticker.last = now;
-        for (const entry of ticker.entries)
-            if (entry.visible)
-                entry.engine.update(dt);
+        const pointerResponsive = pointer.active && now - pointer.lastMovedAt < POINTER_SETTLE_MS;
+        for (const entry of ticker.entries) {
+            if (!entry.visible)
+                continue;
+            const responsive = (entry.follow && pointerResponsive) || entry.engine.needsResponsiveFrameRate;
+            const frameMs = responsive ? RESPONSIVE_FRAME_MS : IDLE_FRAME_MS;
+            if (now - entry.lastUpdate < frameMs)
+                continue;
+            const dt = Math.min((now - entry.lastUpdate) / 1000, 0.1);
+            entry.lastUpdate = now;
+            if (entry.follow)
+                aimAtPointer(entry, now);
+            entry.engine.update(dt);
+        }
         ticker.frame = ticker.entries.size ? requestAnimationFrame(ticker.tick) : 0;
     },
     add(entry) {
+        if (!ticker.entries.size)
+            pointer.listen();
         ticker.entries.add(entry);
         if (!ticker.frame) {
-            ticker.last = performance.now();
             ticker.frame = requestAnimationFrame(ticker.tick);
         }
     },
     remove(entry) {
         ticker.entries.delete(entry);
-        if (!ticker.entries.size && ticker.frame) {
-            cancelAnimationFrame(ticker.frame);
-            ticker.frame = 0;
+        if (!ticker.entries.size) {
+            pointer.stop();
+            if (ticker.frame) {
+                cancelAnimationFrame(ticker.frame);
+                ticker.frame = 0;
+            }
         }
     },
 };
@@ -39,7 +111,7 @@ const seedNumber = (seed) => typeof seed === 'number' ? seed : hashSeed(seed ??
  * look around. The eyes are holes, so set `--naut-avatar-eye` to the surface the
  * avatar sits on (defaults to `--background`).
  */
-export const NautAvatar = React.forwardRef(function NautAvatar({ shape = 'circle', color = 'ink', expression = 'neutral', idle = true, gaze = null, seed, className, style, ...props }, forwardedRef) {
+export const NautAvatar = React.forwardRef(function NautAvatar({ shape = 'circle', color = 'ink', expression = 'neutral', idle = true, gaze = null, followPointer = true, seed, className, style, ...props }, forwardedRef) {
     const reducedMotion = useReducedMotion();
     const animated = idle && !reducedMotion;
     const svgRef = React.useRef(null);
@@ -49,6 +121,16 @@ export const NautAvatar = React.forwardRef(function NautAvatar({ shape = 'circle
     const eyeLRef = React.useRef(null);
     const eyeRRef = React.useRef(null);
     const [engine] = React.useState(() => new NautAvatarEngine({ shape, color, expression, seed: seedNumber(seed), idle: animated }));
+    const [entry] = React.useState(() => ({
+        engine,
+        svg: null,
+        visible: true,
+        follow: false,
+        rect: null,
+        rectAt: -1,
+        rectTime: 0,
+        lastUpdate: performance.now(),
+    }));
     React.useImperativeHandle(forwardedRef, () => ({ play: (gesture) => engine.play(gesture) }), [
         engine,
     ]);
@@ -58,7 +140,8 @@ export const NautAvatar = React.forwardRef(function NautAvatar({ shape = 'circle
         engine.setExpression(expression);
         engine.idle = animated;
         engine.gazeTarget = gaze;
-    }, [engine, shape, color, expression, animated, gaze]);
+        entry.follow = followPointer && !gaze && animated;
+    }, [engine, entry, shape, color, expression, animated, gaze, followPointer]);
     React.useLayoutEffect(() => {
         if (!rootRef.current ||
             !bodyRef.current ||
@@ -77,14 +160,17 @@ export const NautAvatar = React.forwardRef(function NautAvatar({ shape = 'circle
         engine.update(0);
     }, [engine]);
     React.useEffect(() => {
-        if (reducedMotion) {
+        if (!animated) {
             engine.settle();
             engine.update(0);
             return;
         }
-        const entry = { engine, visible: true };
-        ticker.add(entry);
         const svg = svgRef.current;
+        entry.svg = svg;
+        entry.rect = null;
+        entry.rectAt = -1;
+        entry.lastUpdate = performance.now();
+        ticker.add(entry);
         const observer = svg && typeof IntersectionObserver !== 'undefined'
             ? new IntersectionObserver((records) => {
                 for (const record of records)
@@ -96,13 +182,14 @@ export const NautAvatar = React.forwardRef(function NautAvatar({ shape = 'circle
         return () => {
             observer?.disconnect();
             ticker.remove(entry);
+            entry.svg = null;
         };
-    }, [engine, reducedMotion]);
+    }, [animated, engine, entry]);
     React.useEffect(() => {
-        if (!reducedMotion)
+        if (animated)
             return;
         engine.settle();
         engine.update(0);
-    }, [engine, reducedMotion, shape, color, expression]);
-    return (_jsx("svg", { ref: svgRef, viewBox: NAUT_VIEWBOX, "data-slot": "naut-avatar", "data-shape": shape, "data-color": color, "data-expression": expression, className: cn('block size-full overflow-visible select-none', className), style: style, "aria-hidden": props['aria-label'] ? undefined : true, ...props, children: _jsxs("g", { ref: rootRef, children: [_jsx("path", { ref: bodyRef }), _jsxs("g", { ref: eyesRef, children: [_jsx("path", { ref: eyeLRef, fill: "var(--naut-avatar-eye, var(--background))" }), _jsx("path", { ref: eyeRRef, fill: "var(--naut-avatar-eye, var(--background))" })] })] }) }));
+    }, [animated, engine, shape, color, expression]);
+    return (_jsx("svg", { ref: svgRef, viewBox: NAUT_VIEWBOX, "data-slot": "naut-avatar", "data-shape": shape, "data-color": color, "data-expression": expression, "data-atmos-motion": animated ? 'running' : undefined, "data-atmos-motion-property": animated ? 'svg-attributes' : undefined, className: cn('block size-full overflow-visible select-none', className), style: style, "aria-hidden": props['aria-label'] ? undefined : true, ...props, children: _jsxs("g", { ref: rootRef, children: [_jsx("path", { ref: bodyRef }), _jsxs("g", { ref: eyesRef, children: [_jsx("path", { ref: eyeLRef, fill: "var(--naut-avatar-eye, var(--background))" }), _jsx("path", { ref: eyeRRef, fill: "var(--naut-avatar-eye, var(--background))" })] })] }) }));
 });

package/dist/components/naut-pointer-gaze.d.ts

@@ -0,0 +1,16 @@
+export interface FaceBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Where a face should look to notice a mouse at (x, y), in the same [-1, 1] gaze the
+ * avatar takes elsewhere. Null once the pointer is out of reach, which hands the eyes
+ * back to their idle wander. Reach scales with the face, so a 16px Naut in a list only
+ * looks up for a cursor beside it while a hero-sized one watches across a column.
+ */
+export declare function pointerGaze(box: FaceBox, x: number, y: number): {
+    x: number;
+    y: number;
+} | null;

package/dist/components/naut-pointer-gaze.js

@@ -0,0 +1,31 @@
+/** How far from a face a mouse still counts as near, in face radii. */
+const REACH = 6;
+/** Inside this share of the reach the face gives the pointer its full attention. */
+const FULL = 0.45;
+/** Pointer offset, in face radii, that deflects the eyes all the way. */
+const SPAN = 3;
+/** A glance, not a lock: the eyes stop short of their extreme. */
+const WEIGHT = 0.85;
+const clamp01 = (v) => (v < 0 ? 0 : v > 1 ? 1 : v);
+const smoothstep = (v) => v * v * (3 - 2 * v);
+const deflect = (offset, span) => Math.max(-1, Math.min(1, offset / span));
+/**
+ * Where a face should look to notice a mouse at (x, y), in the same [-1, 1] gaze the
+ * avatar takes elsewhere. Null once the pointer is out of reach, which hands the eyes
+ * back to their idle wander. Reach scales with the face, so a 16px Naut in a list only
+ * looks up for a cursor beside it while a hero-sized one watches across a column.
+ */
+export function pointerGaze(box, x, y) {
+    if (!box.width || !box.height)
+        return null;
+    const radius = Math.max(box.width, box.height) / 2;
+    const dx = x - (box.left + box.width / 2);
+    const dy = y - (box.top + box.height / 2);
+    const reach = radius * REACH;
+    const distance = Math.hypot(dx, dy);
+    if (distance > reach)
+        return null;
+    const attention = WEIGHT * smoothstep(clamp01((reach - distance) / (reach * (1 - FULL))));
+    const span = radius * SPAN;
+    return { x: deflect(dx, span) * attention, y: deflect(dy, span) * attention };
+}

package/dist/components/naut-scene.d.ts

@@ -0,0 +1,138 @@
+import * as React from 'react';
+import type { NautColor, NautExpression, NautGesture, NautShape } from './naut-avatar-engine.js';
+export interface NautSceneFace {
+    shape: NautShape;
+    color: NautColor;
+    expression: NautExpression;
+    /** Share of the scene's height the face stands as; smaller reads as further off. */
+    size: number;
+    /** Where the face floats, as a share of the scene box from its top left. */
+    x: number;
+    y: number;
+    /** Seconds one drift takes; slower reads as further off. */
+    drift: number;
+}
+export interface NautSceneDef {
+    faces: readonly NautSceneFace[];
+    /** Run across the whole scene on a loop, one face after the next. */
+    gesture: NautGesture;
+    /** Seconds between one run of the gesture and the next. */
+    interval: number;
+}
+/**
+ * The illustrations a page reaches for, drawn from the same faces the product
+ * uses everywhere else — so an empty state, a 404 and a chat header are all
+ * recognisably the same Nauts rather than a separate cast of stock art.
+ */
+export declare const NAUT_SCENES: {
+    readonly adrift: {
+        readonly faces: readonly [{
+            readonly shape: "circle";
+            readonly color: "sun";
+            readonly expression: "confused";
+            readonly size: 0.62;
+            readonly x: 0.4;
+            readonly y: 0.4;
+            readonly drift: 7;
+        }, {
+            readonly shape: "triangle";
+            readonly color: "mint";
+            readonly expression: "surprised";
+            readonly size: 0.3;
+            readonly x: 0.76;
+            readonly y: 0.68;
+            readonly drift: 9;
+        }, {
+            readonly shape: "diamond";
+            readonly color: "lavender";
+            readonly expression: "sleepy";
+            readonly size: 0.2;
+            readonly x: 0.105;
+            readonly y: 0.72;
+            readonly drift: 11;
+        }];
+        readonly gesture: "lookAround";
+        readonly interval: 6;
+    };
+    readonly greeting: {
+        readonly faces: readonly [{
+            readonly shape: "circle";
+            readonly color: "sun";
+            readonly expression: "happy";
+            readonly size: 0.56;
+            readonly x: 0.4;
+            readonly y: 0.42;
+            readonly drift: 6;
+        }, {
+            readonly shape: "hexagon";
+            readonly color: "sky";
+            readonly expression: "excited";
+            readonly size: 0.34;
+            readonly x: 0.735;
+            readonly y: 0.56;
+            readonly drift: 7.5;
+        }, {
+            readonly shape: "squircle";
+            readonly color: "coral";
+            readonly expression: "happy";
+            readonly size: 0.22;
+            readonly x: 0.1;
+            readonly y: 0.62;
+            readonly drift: 9;
+        }];
+        readonly gesture: "bounce";
+        readonly interval: 5;
+    };
+    readonly crew: {
+        readonly faces: readonly [{
+            readonly shape: "squircle";
+            readonly color: "coral";
+            readonly expression: "happy";
+            readonly size: 0.38;
+            readonly x: 0.17;
+            readonly y: 0.56;
+            readonly drift: 8;
+        }, {
+            readonly shape: "circle";
+            readonly color: "sun";
+            readonly expression: "focused";
+            readonly size: 0.52;
+            readonly x: 0.5;
+            readonly y: 0.46;
+            readonly drift: 6.5;
+        }, {
+            readonly shape: "hexagon";
+            readonly color: "sky";
+            readonly expression: "thinking";
+            readonly size: 0.38;
+            readonly x: 0.83;
+            readonly y: 0.56;
+            readonly drift: 9.5;
+        }];
+        readonly gesture: "nod";
+        readonly interval: 6;
+    };
+    readonly alone: {
+        readonly faces: readonly [{
+            readonly shape: "circle";
+            readonly color: "sun";
+            readonly expression: "neutral";
+            readonly size: 0.86;
+            readonly x: 0.5;
+            readonly y: 0.5;
+            readonly drift: 7;
+        }];
+        readonly gesture: "blink";
+        readonly interval: 7;
+    };
+};
+export type NautSceneName = keyof typeof NAUT_SCENES;
+export interface NautSceneProps {
+    scene: NautSceneName;
+    /** Enables ambient drift and gestures. */
+    animated?: boolean;
+    /** Sizes the scene; the faces lay themselves out inside whatever box this gives. */
+    className?: string;
+}
+/** A small animated illustration built from Naut faces. Decorative — it carries no label. */
+export declare function NautScene({ scene, animated, className, }: NautSceneProps): React.ReactElement;

package/dist/components/naut-scene.js

@@ -0,0 +1,169 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+import { motion, useReducedMotion } from 'motion/react';
+import { cn } from '../lib/cn.js';
+import { NautAvatar } from './naut-avatar.js';
+/**
+ * The illustrations a page reaches for, drawn from the same faces the product
+ * uses everywhere else — so an empty state, a 404 and a chat header are all
+ * recognisably the same Nauts rather than a separate cast of stock art.
+ */
+export const NAUT_SCENES = {
+    adrift: {
+        faces: [
+            {
+                shape: 'circle',
+                color: 'sun',
+                expression: 'confused',
+                size: 0.62,
+                x: 0.4,
+                y: 0.4,
+                drift: 7,
+            },
+            {
+                shape: 'triangle',
+                color: 'mint',
+                expression: 'surprised',
+                size: 0.3,
+                x: 0.76,
+                y: 0.68,
+                drift: 9,
+            },
+            {
+                shape: 'diamond',
+                color: 'lavender',
+                expression: 'sleepy',
+                size: 0.2,
+                x: 0.105,
+                y: 0.72,
+                drift: 11,
+            },
+        ],
+        gesture: 'lookAround',
+        interval: 6,
+    },
+    greeting: {
+        faces: [
+            { shape: 'circle', color: 'sun', expression: 'happy', size: 0.56, x: 0.4, y: 0.42, drift: 6 },
+            {
+                shape: 'hexagon',
+                color: 'sky',
+                expression: 'excited',
+                size: 0.34,
+                x: 0.735,
+                y: 0.56,
+                drift: 7.5,
+            },
+            {
+                shape: 'squircle',
+                color: 'coral',
+                expression: 'happy',
+                size: 0.22,
+                x: 0.1,
+                y: 0.62,
+                drift: 9,
+            },
+        ],
+        gesture: 'bounce',
+        interval: 5,
+    },
+    crew: {
+        faces: [
+            {
+                shape: 'squircle',
+                color: 'coral',
+                expression: 'happy',
+                size: 0.38,
+                x: 0.17,
+                y: 0.56,
+                drift: 8,
+            },
+            {
+                shape: 'circle',
+                color: 'sun',
+                expression: 'focused',
+                size: 0.52,
+                x: 0.5,
+                y: 0.46,
+                drift: 6.5,
+            },
+            {
+                shape: 'hexagon',
+                color: 'sky',
+                expression: 'thinking',
+                size: 0.38,
+                x: 0.83,
+                y: 0.56,
+                drift: 9.5,
+            },
+        ],
+        gesture: 'nod',
+        interval: 6,
+    },
+    alone: {
+        faces: [
+            {
+                shape: 'circle',
+                color: 'sun',
+                expression: 'neutral',
+                size: 0.86,
+                x: 0.5,
+                y: 0.5,
+                drift: 7,
+            },
+        ],
+        gesture: 'blink',
+        interval: 7,
+    },
+};
+/** Milliseconds between one face taking up the gesture and the next. */
+const GESTURE_STAGGER_MS = 180;
+/** Share of its own height a face wanders up and down. */
+const DRIFT_TRAVEL = 9;
+/** Degrees a face tips as it drifts. */
+const DRIFT_TILT = 4;
+/** Seconds between the starts of neighbouring drifts, so nothing moves in unison. */
+const DRIFT_OFFSET = 0.7;
+/** A small animated illustration built from Naut faces. Decorative — it carries no label. */
+export function NautScene({ scene, animated = true, className, }) {
+    const reducedMotion = useReducedMotion();
+    const active = animated && !reducedMotion;
+    const { faces, gesture, interval } = NAUT_SCENES[scene];
+    const handles = React.useRef([]);
+    React.useEffect(() => {
+        if (!active)
+            return;
+        const pending = [];
+        const run = () => {
+            handles.current.forEach((handle, index) => {
+                pending.push(window.setTimeout(() => handle?.play(gesture), index * GESTURE_STAGGER_MS));
+            });
+        };
+        const id = window.setInterval(run, interval * 1000);
+        return () => {
+            window.clearInterval(id);
+            for (const timeout of pending)
+                window.clearTimeout(timeout);
+        };
+    }, [active, gesture, interval]);
+    return (_jsx("div", { "aria-hidden": true, className: cn('flex items-center justify-center', className), children: _jsx("div", { className: "relative aspect-3/2 h-full", children: faces.map((face, index) => (_jsx("span", { className: "absolute block aspect-square", style: {
+                    left: `${face.x * 100}%`,
+                    top: `${face.y * 100}%`,
+                    height: `${face.size * 100}%`,
+                    transform: 'translate(-50%, -50%)',
+                }, children: _jsx(motion.span, { className: "block size-full", animate: !active
+                        ? undefined
+                        : {
+                            y: [`-${DRIFT_TRAVEL}%`, `${DRIFT_TRAVEL}%`],
+                            rotate: [-DRIFT_TILT, DRIFT_TILT],
+                        }, transition: {
+                        duration: face.drift,
+                        delay: index * DRIFT_OFFSET,
+                        repeat: Infinity,
+                        repeatType: 'mirror',
+                        ease: 'easeInOut',
+                    }, children: _jsx(NautAvatar, { ref: (handle) => {
+                            handles.current[index] = handle;
+                        }, shape: face.shape, color: face.color, expression: face.expression, idle: active, seed: `${scene}-${index}` }) }) }, `${face.shape}-${face.color}-${index}`))) }) }));
+}

package/dist/components/shimmer-text.d.ts

@@ -1,8 +1,8 @@
 import * as React from 'react';
-import { type HTMLMotionProps } from 'motion/react';
-export interface ShimmerTextProps extends Omit<HTMLMotionProps<'span'>, 'children'> {
+export interface ShimmerTextProps extends Omit<React.ComponentPropsWithoutRef<'span'>, 'children'> {
     children: string | number;
+    animate?: boolean;
     duration?: number;
     spread?: number;
 }
-export declare const ShimmerText: React.NamedExoticComponent<Omit<ShimmerTextProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
+export declare const ShimmerText: React.NamedExoticComponent<ShimmerTextProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/shimmer-text.js

@@ -1,23 +1,59 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import * as React from 'react';
-import { motion, useReducedMotion } from 'motion/react';
+import { useMediaQuery } from '../hooks/use-media-query.js';
 import { cn } from '../lib/cn.js';
-const ShimmerTextComponent = React.forwardRef(function ShimmerText({ children, className, duration = 2, spread = 2, style, ...props }, forwardedRef) {
-    const reducedMotion = useReducedMotion();
+const SHIMMER_FRAME_MS = 1000 / 8;
+const shimmerEntries = new Set();
+let shimmerTimer = 0;
+function paintShimmers() {
+    const now = performance.now();
+    for (const entry of shimmerEntries) {
+        const progress = ((now - entry.startedAt) % entry.durationMs) / entry.durationMs;
+        entry.element.style.backgroundPosition = `${100 - progress * 100}% center, 0 center`;
+    }
+}
+function startShimmer(entry) {
+    shimmerEntries.add(entry);
+    paintShimmers();
+    if (!shimmerTimer)
+        shimmerTimer = window.setInterval(paintShimmers, SHIMMER_FRAME_MS);
+}
+function stopShimmer(entry) {
+    shimmerEntries.delete(entry);
+    if (shimmerEntries.size || !shimmerTimer)
+        return;
+    window.clearInterval(shimmerTimer);
+    shimmerTimer = 0;
+}
+const ShimmerTextComponent = React.forwardRef(function ShimmerText({ children, className, duration = 2, spread = 2, style, animate = true, ...props }, forwardedRef) {
+    const reducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
+    const active = animate !== false && !reducedMotion;
+    const localRef = React.useRef(null);
+    const setRef = React.useCallback((node) => {
+        localRef.current = node;
+        if (typeof forwardedRef === 'function')
+            forwardedRef(node);
+        else if (forwardedRef)
+            forwardedRef.current = node;
+    }, [forwardedRef]);
     const dynamicSpread = React.useMemo(() => `${String(children).length * spread}px`, [children, spread]);
-    const backgroundImage = reducedMotion
-        ? 'linear-gradient(var(--base-color), var(--base-color))'
-        : 'var(--bg), linear-gradient(var(--base-color), var(--base-color))';
-    return (_jsx(motion.span, { ref: forwardedRef, "data-slot": "shimmer-text", className: cn('relative inline-block bg-[length:250%_100%,auto] bg-clip-text text-transparent', '[--base-color:color-mix(in_oklch,var(--foreground)_30%,transparent)] [--base-gradient-color:var(--foreground)]', '[background-repeat:no-repeat,padding-box]', '[--bg:linear-gradient(90deg,transparent_calc(50%-var(--spread)),var(--base-gradient-color),transparent_calc(50%+var(--spread)))]', className), 
-        // Keyframes, not an initial→animate delta: nested under an AnimatePresence
-        // the presence context suppresses `initial`, which would freeze the sweep
-        // at its end position and leave the text flat.
-        animate: reducedMotion ? undefined : { backgroundPosition: ['100% center', '0% center'] }, transition: {
-            repeat: Number.POSITIVE_INFINITY,
-            duration,
-            ease: 'linear',
-        }, style: {
+    const backgroundImage = active
+        ? 'var(--bg), linear-gradient(var(--base-color), var(--base-color))'
+        : 'linear-gradient(var(--base-color), var(--base-color))';
+    React.useEffect(() => {
+        const element = localRef.current;
+        if (!active || !element)
+            return;
+        const entry = {
+            element,
+            durationMs: Math.max(duration * 1000, SHIMMER_FRAME_MS),
+            startedAt: performance.now(),
+        };
+        startShimmer(entry);
+        return () => stopShimmer(entry);
+    }, [active, duration, children]);
+    return (_jsx("span", { ref: setRef, "data-slot": "shimmer-text", "data-atmos-motion": active ? 'running' : undefined, "data-atmos-motion-property": active ? 'background-position' : undefined, className: cn('relative inline-block bg-[length:250%_100%,auto] bg-clip-text text-transparent contain-paint', '[--base-color:color-mix(in_oklch,var(--foreground)_30%,transparent)] [--base-gradient-color:var(--foreground)]', '[background-repeat:no-repeat,padding-box]', '[--bg:linear-gradient(90deg,transparent_calc(50%-var(--spread)),var(--base-gradient-color),transparent_calc(50%+var(--spread)))]', className), style: {
             '--spread': dynamicSpread,
             backgroundImage,
             ...style,

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export { TemplateChipInput, type TemplateChipInputProps, type TemplateChipInputH
 export { RunStatusBadge, type RunStatus, type RunStatusBadgeProps, } from './components/run-status-badge.js';
 export { ConfidenceMeter, confidenceLevel, type ConfidenceLevel, type ConfidenceMeterProps, } from './components/confidence-meter.js';
 export { DateTile, type DateTileProps } from './components/date-tile.js';
+export { DiffStatLabel, type DiffStatLabelProps } from './components/diff-stat-label.js';
+export { compactFormatter } from './components/diff-stat-format.js';
 export { MetricBreakdown, MetricGrid, MetricPanel, MetricSectionHeading, MetricTile, type MetricBreakdownItem, type MetricBreakdownProps, type MetricGridProps, type MetricPanelProps, type MetricSectionHeadingProps, type MetricTileProps, type MetricTone, } from './components/metric-grid.js';
 export { resolveDateTimeFormat, type FormatDateTime } from './lib/date-time-format.js';
 export { ProvenanceChip, type ProvenanceChipProps, type ProvenanceMethod, } from './components/provenance-chip.js';
@@ -67,6 +69,7 @@ export { SortableList, SortableItem, SortableRow, DragHandle, DragPreview, useSo
 export { VoiceLine, type VoiceLineProps, type VoiceLineState } from './components/voice-line.js';
 export { ShimmerText, type ShimmerTextProps } from './components/shimmer-text.js';
 export { NautAvatar, NAUT_COLORS, NAUT_COLOR_KEYS, NAUT_EXPRESSIONS, NAUT_GESTURES, NAUT_SHAPES, isNautColor, isNautShape, nautAppearanceForSeed, type NautAppearance, type NautAvatarHandle, type NautAvatarProps, type NautColor, type NautExpression, type NautGesture, type NautShape, } from './components/naut-avatar.js';
+export { NautScene, NAUT_SCENES, type NautSceneDef, type NautSceneFace, type NautSceneName, type NautSceneProps, } from './components/naut-scene.js';
 export { TranscriptionOverlay, type TranscriptionOverlayLabels, type TranscriptionOverlayProps, type TranscriptionOverlaySelector, type TranscriptionOverlayState, } from './components/transcription-overlay.js';
 export { TimestampedTranscript, type TimestampedTranscriptLabels, type TimestampedTranscriptProps, type TimestampedTranscriptUtterance, type TimestampedTranscriptWord, } from './components/timestamped-transcript.js';
 export { MicrophonePriority, type MicrophonePriorityItem, type MicrophonePriorityLabels, type MicrophonePriorityProps, } from './components/microphone-priority.js';

package/dist/index.js

@@ -24,6 +24,8 @@ export { TemplateChipInput, } from './components/template-chip-input.js';
 export { RunStatusBadge, } from './components/run-status-badge.js';
 export { ConfidenceMeter, confidenceLevel, } from './components/confidence-meter.js';
 export { DateTile } from './components/date-tile.js';
+export { DiffStatLabel } from './components/diff-stat-label.js';
+export { compactFormatter } from './components/diff-stat-format.js';
 export { MetricBreakdown, MetricGrid, MetricPanel, MetricSectionHeading, MetricTile, } from './components/metric-grid.js';
 export { resolveDateTimeFormat } from './lib/date-time-format.js';
 export { ProvenanceChip, } from './components/provenance-chip.js';
@@ -67,6 +69,7 @@ export { SortableList, SortableItem, SortableRow, DragHandle, DragPreview, useSo
 export { VoiceLine } from './components/voice-line.js';
 export { ShimmerText } from './components/shimmer-text.js';
 export { NautAvatar, NAUT_COLORS, NAUT_COLOR_KEYS, NAUT_EXPRESSIONS, NAUT_GESTURES, NAUT_SHAPES, isNautColor, isNautShape, nautAppearanceForSeed, } from './components/naut-avatar.js';
+export { NautScene, NAUT_SCENES, } from './components/naut-scene.js';
 export { TranscriptionOverlay, } from './components/transcription-overlay.js';
 export { TimestampedTranscript, } from './components/timestamped-transcript.js';
 export { MicrophonePriority, } from './components/microphone-priority.js';

package/dist/mcp-app/vite.d.ts

@@ -1,7 +1,9 @@
-import { type UserConfig } from 'vite';
+import { type Plugin, type UserConfig } from 'vite';
 export interface AtmosMcpAppViteOptions {
     root: string;
     entry?: string;
     outDir?: string;
 }
 export declare function atmosMcpAppViteConfig({ root, entry, outDir, }: AtmosMcpAppViteOptions): UserConfig;
+export declare function atmosMcpAppSourceMetadata(root: string): Plugin;
+export declare function annotateMcpAppReactComponents(code: string, filename: string, sourcePath: string): string;

package/dist/mcp-app/vite.js

@@ -1,12 +1,16 @@
 import tailwindcss from '@tailwindcss/postcss';
 import react from '@vitejs/plugin-react';
 import path from 'node:path';
+import ts from 'typescript';
 import { defineConfig } from 'vite';
+const MCP_APP_SOURCE_METADATA_PROPERTY = '__atmosMcpSource';
+const REACT_COMPONENT_FILE = /\.[jt]sx$/i;
+const NON_PRODUCTION_COMPONENT_FILE = /\.(?:stories|test|spec)\.[cm]?[jt]sx?$/i;
 export function atmosMcpAppViteConfig({ root, entry = 'src/main.tsx', outDir = '../dist', }) {
     return defineConfig({
         root,
         publicDir: false,
-        plugins: [react()],
+        plugins: [atmosMcpAppSourceMetadata(root), react()],
         define: { 'process.env.NODE_ENV': JSON.stringify('production') },
         css: { postcss: { plugins: [tailwindcss()] } },
         resolve: { dedupe: ['react', 'react-dom', 'react/jsx-runtime'] },
@@ -28,3 +32,104 @@ export function atmosMcpAppViteConfig({ root, entry = 'src/main.tsx', outDir = '
         },
     });
 }
+export function atmosMcpAppSourceMetadata(root) {
+    const appRoot = normalizePath(path.resolve(root));
+    return {
+        name: 'atmos-mcp-app-source-metadata',
+        enforce: 'pre',
+        transform(code, id) {
+            const file = normalizePath(id.split('?')[0] ?? id);
+            if (!shouldAnnotateComponentFile(file, appRoot))
+                return null;
+            const sourcePath = normalizePath(path.relative(appRoot, file));
+            if (!isSafeSourcePath(sourcePath))
+                return null;
+            const transformed = annotateMcpAppReactComponents(code, file, sourcePath);
+            return transformed === code ? null : { code: transformed, map: null };
+        },
+    };
+}
+export function annotateMcpAppReactComponents(code, filename, sourcePath) {
+    const sourceFile = ts.createSourceFile(filename, code, ts.ScriptTarget.Latest, true, filename.toLowerCase().endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.JSX);
+    const componentNames = topLevelComponentNames(sourceFile);
+    if (componentNames.length === 0)
+        return code;
+    const assignments = componentNames.map((componentName) => sourceMetadataAssignment(componentName, sourcePath));
+    return `${code.trimEnd()}\n\n${assignments.join('\n')}\n`;
+}
+function topLevelComponentNames(sourceFile) {
+    const names = [];
+    const seen = new Set();
+    for (const statement of sourceFile.statements) {
+        if (ts.isFunctionDeclaration(statement) && statement.name) {
+            addComponentName(names, seen, statement.name.text);
+            continue;
+        }
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) &&
+                declaration.initializer &&
+                isReactComponentInitializer(declaration.initializer)) {
+                addComponentName(names, seen, declaration.name.text);
+            }
+        }
+    }
+    return names;
+}
+function addComponentName(names, seen, name) {
+    if (!/^[A-Z][A-Za-z0-9_]*$/.test(name) || seen.has(name))
+        return;
+    seen.add(name);
+    names.push(name);
+}
+function isReactComponentInitializer(expression) {
+    const value = unwrapExpression(expression);
+    if (ts.isArrowFunction(value) || ts.isFunctionExpression(value))
+        return true;
+    if (!ts.isCallExpression(value))
+        return false;
+    const callee = dottedName(value.expression);
+    return (callee === 'memo' ||
+        callee === 'React.memo' ||
+        callee === 'forwardRef' ||
+        callee === 'React.forwardRef');
+}
+function unwrapExpression(expression) {
+    let value = expression;
+    while (ts.isParenthesizedExpression(value) ||
+        ts.isAsExpression(value) ||
+        ts.isTypeAssertionExpression(value) ||
+        ts.isSatisfiesExpression(value) ||
+        ts.isNonNullExpression(value)) {
+        value = value.expression;
+    }
+    return value;
+}
+function dottedName(expression) {
+    if (ts.isIdentifier(expression))
+        return expression.text;
+    if (!ts.isPropertyAccessExpression(expression))
+        return undefined;
+    const parent = dottedName(expression.expression);
+    return parent ? `${parent}.${expression.name.text}` : expression.name.text;
+}
+function sourceMetadataAssignment(componentName, sourcePath) {
+    const metadata = JSON.stringify({ sourcePath, componentName });
+    return `Object.defineProperty(${componentName}, ${JSON.stringify(MCP_APP_SOURCE_METADATA_PROPERTY)}, { value: ${metadata} });`;
+}
+function shouldAnnotateComponentFile(file, appRoot) {
+    return (file.startsWith(`${appRoot}/`) &&
+        REACT_COMPONENT_FILE.test(file) &&
+        !NON_PRODUCTION_COMPONENT_FILE.test(file) &&
+        !file.includes('/node_modules/'));
+}
+function isSafeSourcePath(value) {
+    return (Boolean(value) &&
+        value.length <= 512 &&
+        !value.startsWith('/') &&
+        !value.split('/').includes('..'));
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, '/');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atmos.build/ui",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The complete atmOS React component system and MCP App authoring helpers.",
   "type": "module",
   "license": "UNLICENSED",
@@ -32,6 +32,10 @@
       "types": "./dist/lib/cn.d.ts",
       "import": "./dist/lib/cn.js"
     },
+    "./naut-avatar-engine": {
+      "types": "./dist/components/naut-avatar-engine.d.ts",
+      "import": "./dist/components/naut-avatar-engine.js"
+    },
     "./view-query": {
       "types": "./dist/lib/view-query/index.d.ts",
       "import": "./dist/lib/view-query/index.js"
@@ -83,6 +87,7 @@
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.2",
     "tw-animate-css": "^1.4.0",
+    "typescript": "^5.7.0",
     "use-intl": "^4.13.2",
     "vite": "8.1.4",
     "yjs": "^13.6.31"