@atmos.build/ui 0.1.0 → 0.1.1

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

@@ -62,6 +62,8 @@ 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;
     constructor(opts?: NautAvatarOptions);
     attach(el: NautAvatarElements): void;
@@ -73,6 +75,8 @@ 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;
 }
 /** Stable pseudo-random pick so the same id always gets the same appearance. */

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,6 +643,8 @@ 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;
     constructor(opts = {}) {
         this.rand = rng(opts.seed ?? 1);
@@ -639,6 +654,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;
@@ -662,8 +678,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 +695,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 +721,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,6 +772,26 @@ 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)

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,7 +4,62 @@ 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;
+/** Where the mouse is, shared by every face so one listener serves the page. */
+const pointer = {
+    x: 0,
+    y: 0,
+    active: false,
+    /** 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.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(),
@@ -13,12 +68,17 @@ const ticker = {
     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.follow)
+                aimAtPointer(entry, now);
         for (const entry of ticker.entries)
             if (entry.visible)
                 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();
@@ -27,9 +87,12 @@ const ticker = {
     },
     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 +102,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 +112,15 @@ 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,
+    }));
     React.useImperativeHandle(forwardedRef, () => ({ play: (gesture) => engine.play(gesture) }), [
         engine,
     ]);
@@ -58,7 +130,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 ||
@@ -82,9 +155,11 @@ export const NautAvatar = React.forwardRef(function NautAvatar({ shape = 'circle
             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;
+        ticker.add(entry);
         const observer = svg && typeof IntersectionObserver !== 'undefined'
             ? new IntersectionObserver((records) => {
                 for (const record of records)
@@ -96,8 +171,9 @@ export const NautAvatar = React.forwardRef(function NautAvatar({ shape = 'circle
         return () => {
             observer?.disconnect();
             ticker.remove(entry);
+            entry.svg = null;
         };
-    }, [engine, reducedMotion]);
+    }, [engine, entry, reducedMotion]);
     React.useEffect(() => {
         if (!reducedMotion)
             return;

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,136 @@
+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;
+    /** 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, className }: NautSceneProps): React.ReactElement;

package/dist/components/naut-scene.js

@@ -0,0 +1,168 @@
+'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, className }) {
+    const reducedMotion = useReducedMotion();
+    const { faces, gesture, interval } = NAUT_SCENES[scene];
+    const handles = React.useRef([]);
+    React.useEffect(() => {
+        if (reducedMotion)
+            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);
+        };
+    }, [gesture, interval, reducedMotion]);
+    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: reducedMotion
+                        ? 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, seed: `${scene}-${index}` }) }) }, `${face.shape}-${face.color}-${index}`))) }) }));
+}

package/dist/index.d.ts

@@ -67,6 +67,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

@@ -67,6 +67,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.1",
   "description": "The complete atmOS React component system and MCP App authoring helpers.",
   "type": "module",
   "license": "UNLICENSED",
@@ -83,6 +83,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"