@nadicodeai/ui 4.0.5 → 5.2.2

package/AGENTS.md

@@ -8,6 +8,10 @@ exports.
 - Consumer setup: `docs/consuming-cross-repo.md`.
 - Tokens, CSS, motion, and assets: `../design-system/DESIGN.md`.
 - Agent visuals: `docs/agent-visual.md`.
+- System activity indicators: `docs/activity.md`.
+- First run, sign-in, and repair surfaces: `docs/threshold.md`; the
+  primitives are `@nadicodeai/ui/threshold`, with
+  `@nadicodeai/ui/threshold.css` beside them.
 - Package releases: `../../docs/agents/publish.md`.
 
 `npm run dev -w @nadicodeai/ui` watches source and refreshes `dist/`;

package/README.md

@@ -89,6 +89,10 @@ from source and package exports, not from prose. assistant-ui runtime ownership
 and migration readiness live in the linked package docs; this README does not
 summarize them.
 
+System activity uses the shared `ActivityOrb` component. See
+[`docs/activity.md`](docs/activity.md) for the activity vocabulary, selected
+motions, brand treatment, sizes, accessibility and usage examples.
+
 ## Layout primitives
 
 `SeamGrid` is a supported low-level layout primitive: the single owner of the

package/dist/activity.d.ts

@@ -0,0 +1,2 @@
+export { mountActivityOrb, type ActivityKind, type ActivityOrbSize } from "./internal/activity-orb.js";
+//# sourceMappingURL=activity.d.ts.map

package/dist/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/activity.js

@@ -0,0 +1,2 @@
+// The same activity renderer for native startup HTML, before React is loaded.
+export { mountActivityOrb } from "./internal/activity-orb.js";

package/dist/components/activity-orb.d.ts

@@ -0,0 +1,21 @@
+import { type CSSProperties } from "react";
+import { type ActivityKind, type ActivityOrbSize } from "../internal/activity-orb.js";
+export type { ActivityKind, ActivityOrbSize } from "../internal/activity-orb.js";
+export type ActivityOrbProps = {
+    activity: ActivityKind;
+    className?: string;
+    style?: CSSProperties;
+    /** Freeze the animation for a preview or a user-controlled motion pause. */
+    paused?: boolean;
+    /** 20 inline, 64 within a region, 88 at an application threshold. */
+    size?: ActivityOrbSize;
+} & ({
+    decorative: true;
+    label?: never;
+} | {
+    decorative?: false;
+    label: string;
+});
+/** The shared system-activity family. The consumer owns the actual operation. */
+export declare function ActivityOrb({ activity, className, decorative, label, paused, size, style, ...props }: ActivityOrbProps): import("react").JSX.Element;
+//# sourceMappingURL=activity-orb.d.ts.map

package/dist/components/activity-orb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-orb.d.ts","sourceRoot":"","sources":["../../src/components/activity-orb.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,aAAa,EAAqB,MAAM,OAAO,CAAC;AAE9D,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAoB,MAAM,yBAAyB,CAAC;AAGpG,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE7E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,IAAI,CAAC,EAAE,eAAe,CAAC;CACxB,GAAG,CAAC;IAAE,UAAU,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,UAAU,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAElF,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,SAAS,EACT,UAAkB,EAClB,KAAK,EACL,MAAc,EACd,IAAS,EACT,KAAK,EACL,GAAG,KAAK,EACT,EAAE,gBAAgB,+BAmClB"}

package/dist/components/activity-orb.js

@@ -0,0 +1,26 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+import { mountActivityOrb } from "../internal/activity-orb.js";
+import { cn } from "../lib/utils.js";
+/** The shared system-activity family. The consumer owns the actual operation. */
+export function ActivityOrb({ activity, className, decorative = false, label, paused = false, size = 20, style, ...props }) {
+    const canvas = useRef(null);
+    const renderer = useRef(null);
+    const initiallyPaused = useRef(paused);
+    useEffect(() => {
+        if (!canvas.current)
+            return;
+        const mounted = mountActivityOrb(canvas.current, activity, size, initiallyPaused.current);
+        renderer.current = mounted;
+        return () => {
+            mounted.destroy();
+            renderer.current = null;
+        };
+    }, [activity, size]);
+    useEffect(() => {
+        initiallyPaused.current = paused;
+        renderer.current?.setPaused(paused);
+    }, [activity, paused, size]);
+    return (_jsx("canvas", { ...props, "aria-hidden": decorative || undefined, "aria-label": decorative ? undefined : label, className: cn("inline-block shrink-0 align-middle", className), "data-activity": activity, "data-slot": "activity-orb", height: size, ref: canvas, role: decorative ? undefined : "img", style: { ...style, height: size, width: size }, width: size, children: decorative ? null : label }));
+}

package/dist/components/threshold/canvas-budget.d.ts

@@ -0,0 +1,10 @@
+/** True while a primitive that outranks the room owns the window's canvas. */
+export declare function canvasHeld(): boolean;
+/**
+ * Take the window's canvas. Returns the release, which is idempotent: a
+ * teardown that runs twice releases once.
+ */
+export declare function holdCanvas(): () => void;
+/** Whether the room must yield its canvas right now. Live. */
+export declare function useCanvasHeld(): boolean;
+//# sourceMappingURL=canvas-budget.d.ts.map

package/dist/components/threshold/canvas-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-budget.d.ts","sourceRoot":"","sources":["../../../src/components/threshold/canvas-budget.ts"],"names":[],"mappings":"AA0BA,8EAA8E;AAC9E,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,IAAI,CAWvC;AAWD,8DAA8D;AAC9D,wBAAgB,aAAa,IAAI,OAAO,CAEvC"}

package/dist/components/threshold/canvas-budget.js

@@ -0,0 +1,54 @@
+"use client";
+import { useSyncExternalStore } from "react";
+/*
+ * One shader canvas per window: the living-elements register's rule, held
+ * here so no screen can break it by composition.
+ *
+ * Two threshold primitives can paint with a shader, the room and the arriving
+ * presence, and a threshold mounts both. The presence's water outranks the
+ * room: while Nadia is arriving her water is the window's one live canvas and
+ * the room shows its still field; when she stands clear the water leaves and
+ * the room's canvas is the one that paints. The presence takes a hold for as
+ * long as its water is wanted, and the room yields while any hold is out.
+ *
+ * The budget is per window, so it is module state rather than a context: a
+ * provider would let a surface forget to wrap both primitives, and the rule
+ * would then hold only where someone remembered it.
+ */
+let holds = 0;
+const listeners = new Set();
+const notify = () => {
+    for (const listener of listeners)
+        listener();
+};
+/** True while a primitive that outranks the room owns the window's canvas. */
+export function canvasHeld() {
+    return holds > 0;
+}
+/**
+ * Take the window's canvas. Returns the release, which is idempotent: a
+ * teardown that runs twice releases once.
+ */
+export function holdCanvas() {
+    holds += 1;
+    notify();
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        holds -= 1;
+        notify();
+    };
+}
+function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+const serverSnapshot = () => false;
+/** Whether the room must yield its canvas right now. Live. */
+export function useCanvasHeld() {
+    return useSyncExternalStore(subscribe, canvasHeld, serverSnapshot);
+}

package/dist/components/threshold/index.d.ts

@@ -0,0 +1,6 @@
+export { Orb, type OrbProps, type OrbSize, type OrbState, type OrbTheme } from "./orb.js";
+export { arrivalOpacity, NadiaPresence, type NadiaPresenceProps, type PresenceState, } from "./presence.js";
+export { ThresholdRoom, type ThresholdRoomProps } from "./room.js";
+export { TypedLine, type TypedLineProps } from "./typed-line.js";
+export { useReducedMotion } from "./use-reduced-motion.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/threshold/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/threshold/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,KAAK,QAAQ,EAAE,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,OAAO,CAAC;AACvF,OAAO,EACL,cAAc,EACd,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/components/threshold/index.js

@@ -0,0 +1,5 @@
+export { Orb } from "./orb.js";
+export { arrivalOpacity, NadiaPresence, } from "./presence.js";
+export { ThresholdRoom } from "./room.js";
+export { TypedLine } from "./typed-line.js";
+export { useReducedMotion } from "./use-reduced-motion.js";

package/dist/components/threshold/orb.d.ts

@@ -0,0 +1,14 @@
+import { type ActivityOrbSize } from "../activity-orb.js";
+export type OrbState = "working" | "connecting" | "absent";
+export type OrbTheme = "auto" | "dark" | "light";
+export type OrbSize = ActivityOrbSize;
+export type OrbProps = {
+    className?: string;
+    label: string;
+    size?: OrbSize;
+    state: OrbState;
+    theme?: OrbTheme;
+};
+/** Preserve the threshold API while using the one shared activity renderer. */
+export declare function Orb({ className, label, size, state, theme }: OrbProps): import("react").JSX.Element | null;
+//# sourceMappingURL=orb.d.ts.map

package/dist/components/threshold/orb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orb.d.ts","sourceRoot":"","sources":["../../../src/components/threshold/orb.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAG9E,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;AAC3D,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AACjD,MAAM,MAAM,OAAO,GAAG,eAAe,CAAC;AAEtC,MAAM,MAAM,QAAQ,GAAG;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB,CAAC;AAUF,+EAA+E;AAC/E,wBAAgB,GAAG,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,IAAS,EAAE,KAAK,EAAE,KAAc,EAAE,EAAE,QAAQ,sCAYnF"}

package/dist/components/threshold/orb.js

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ActivityOrb } from "../activity-orb.js";
+import { cn } from "../../lib/utils.js";
+// A threshold deliberately fixes its appearance. Normal product surfaces
+// inherit their ink; the shared renderer needs no knowledge of app themes.
+const THEME_INK = {
+    auto: "inherit",
+    dark: "var(--nc-dark-ink)",
+    light: "var(--nc-ink)",
+};
+/** Preserve the threshold API while using the one shared activity renderer. */
+export function Orb({ className, label, size = 88, state, theme = "dark" }) {
+    if (state === "absent")
+        return null;
+    return (_jsx(ActivityOrb, { activity: state === "working" ? "processing" : "connecting", className: cn("nc-threshold-orb", className), "data-state": state, label: label, size: size, style: { color: THEME_INK[theme] } }));
+}

package/dist/components/threshold/presence.d.ts

@@ -0,0 +1,27 @@
+export type PresenceState = "arriving" | "present" | "ready" | "error";
+export type NadiaPresenceProps = {
+    className?: string;
+    /** The accessible name of the arrival, read by the hidden progress bar. */
+    label: string;
+    /** 0 while she is behind the field, 1 when she stands clear. */
+    reveal: number;
+    /**
+     * The portrait master. The package imports no binary asset of its own, so
+     * the consuming surface resolves `@nadicodeai/design-system/assets/nadia-solid-surface`
+     * with its own bundler and passes the URL here.
+     */
+    src: string;
+    state: PresenceState;
+};
+/** The arrival curve: a trace at the start, not a face already half-built. */
+export declare function arrivalOpacity(reveal: number): number;
+/**
+ * Nadia at a threshold.
+ *
+ * `reveal` drives one opacity, so nothing re-renders per frame and the value
+ * a Customer sees is the value assistive technology is told. The lower edge
+ * dissolves into the room instead of ending on a rectangle. At `state="ready"`
+ * she takes one short verde vivo beat, her presence accent, and settles.
+ */
+export declare function NadiaPresence({ className, label, reveal, src, state }: NadiaPresenceProps): import("react").JSX.Element;
+//# sourceMappingURL=presence.d.ts.map

package/dist/components/threshold/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../../src/components/threshold/presence.tsx"],"names":[],"mappings":"AA+CA,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AAEvE,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,aAAa,CAAC;CACtB,CAAC;AAIF,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAgBD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,kBAAkB,+BAsIzF"}

package/dist/components/threshold/presence.js

@@ -0,0 +1,159 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { defaultObjectSizing, ShaderFitOptions, ShaderMount, waterFragmentShader, } from "@paper-design/shaders";
+import { useEffect, useRef, useState } from "react";
+import { resolveIdentityColor } from "../../internal/agent-visual/color.js";
+import { cn } from "../../lib/utils.js";
+import { holdCanvas } from "./canvas-budget.js";
+import { useReducedMotion } from "./use-reduced-motion.js";
+/*
+ * Nadia's presence: the portrait master itself, arriving through the room. No
+ * medallion, no ring, no bar. How much of her you can see is the progress.
+ *
+ * While she is arriving the portrait carries Paper Shaders' Water at a
+ * restrained intensity, so the field she is coming through moves across her
+ * without taking her geometry apart. Every amplitude is scaled by how much of
+ * the arrival is left, so the water is gone by the time she stands clear. At
+ * reveal 1, and in every other state, this is the plain portrait.
+ *
+ * The water is the window's one shader canvas while it is wanted. The presence
+ * holds the canvas budget from the moment the water is asked for until it is
+ * torn down, and the room keeps its still field for exactly that long
+ * (`canvas-budget.ts`).
+ */
+const ARRIVAL_FLOOR = 0.025;
+const ARRIVAL_CURVE = 1.25;
+const WATER_CAUSTIC = 0.35;
+const WATER_EDGES = 0.4;
+const WATER_WAVES = 0.3;
+const WATER_LAYERING = 0.4;
+const WATER_HIGHLIGHTS = 0.12;
+const WATER_SIZE = 1;
+const WATER_SPEED = 1;
+const WATER_FRAME = 0;
+const WATER_MIN_PIXEL_RATIO = 1;
+const WATER_MAX_PIXEL_COUNT = 1_024_000;
+const PRESENCE_FIELD_TOKEN = "--nc-identity-verde";
+const TRANSPARENT = [0, 0, 0, 0];
+const clampUnit = (value) => Math.min(Math.max(value, 0), 1);
+/** The arrival curve: a trace at the start, not a face already half-built. */
+export function arrivalOpacity(reveal) {
+    return ARRIVAL_FLOOR + (1 - ARRIVAL_FLOOR) * clampUnit(reveal) ** ARRIVAL_CURVE;
+}
+function waterUniforms(reveal, field) {
+    const remaining = 1 - clampUnit(reveal);
+    return {
+        u_caustic: WATER_CAUSTIC * remaining,
+        u_colorBack: TRANSPARENT,
+        u_colorHighlight: field,
+        u_edges: WATER_EDGES * remaining,
+        u_highlights: WATER_HIGHLIGHTS,
+        u_layering: WATER_LAYERING,
+        u_size: WATER_SIZE,
+        u_waves: WATER_WAVES * remaining,
+    };
+}
+/**
+ * Nadia at a threshold.
+ *
+ * `reveal` drives one opacity, so nothing re-renders per frame and the value
+ * a Customer sees is the value assistive technology is told. The lower edge
+ * dissolves into the room instead of ending on a rectangle. At `state="ready"`
+ * she takes one short verde vivo beat, her presence accent, and settles.
+ */
+export function NadiaPresence({ className, label, reveal, src, state }) {
+    const still = useReducedMotion();
+    const hostRef = useRef(null);
+    const mountRef = useRef(null);
+    const [surface, setSurface] = useState("portrait");
+    const value = clampUnit(reveal);
+    const arriving = state === "arriving";
+    const wet = arriving && value < 1 && !still;
+    useEffect(() => {
+        const host = hostRef.current;
+        if (!host || !wet)
+            return;
+        const field = resolveIdentityColor(host, PRESENCE_FIELD_TOKEN);
+        if (!field)
+            return;
+        let cancelled = false;
+        let canvas = null;
+        // Taken before the image decodes: the room stays still while her water is
+        // on its way, not only once it paints.
+        const releaseCanvas = holdCanvas();
+        const clearCanvases = () => {
+            for (const element of host.querySelectorAll("canvas"))
+                element.remove();
+            host.removeAttribute("data-paper-shader");
+        };
+        const teardown = () => {
+            canvas?.removeEventListener("webglcontextlost", handleContextLost);
+            canvas = null;
+            try {
+                mountRef.current?.dispose();
+            }
+            catch {
+                // The plain portrait is what stays; vendor cleanup failing is not
+                // allowed to remove Nadia from the screen.
+            }
+            mountRef.current = null;
+            clearCanvases();
+            // After disposal, so the room's canvas is never alive beside this one.
+            releaseCanvas();
+        };
+        function handleContextLost(event) {
+            event.preventDefault();
+            teardown();
+            setSurface("portrait");
+        }
+        const image = new Image();
+        image.decoding = "async";
+        image.src = src;
+        const mount = async () => {
+            try {
+                await image.decode();
+                if (cancelled)
+                    return;
+                mountRef.current = new ShaderMount(host, waterFragmentShader, {
+                    ...waterUniforms(value, field),
+                    u_fit: ShaderFitOptions.contain,
+                    u_image: image,
+                    u_offsetX: defaultObjectSizing.offsetX,
+                    u_offsetY: defaultObjectSizing.offsetY,
+                    u_originX: defaultObjectSizing.originX,
+                    u_originY: defaultObjectSizing.originY,
+                    u_rotation: defaultObjectSizing.rotation,
+                    u_scale: defaultObjectSizing.scale,
+                    u_worldHeight: defaultObjectSizing.worldHeight,
+                    u_worldWidth: defaultObjectSizing.worldWidth,
+                }, undefined, WATER_SPEED, WATER_FRAME, WATER_MIN_PIXEL_RATIO, WATER_MAX_PIXEL_COUNT, ["u_image"]);
+                canvas = mountRef.current.canvasElement;
+                canvas.addEventListener("webglcontextlost", handleContextLost);
+                setSurface("water");
+            }
+            catch {
+                // No WebGL, no palette, or an image that will not decode: she arrives
+                // as the plain portrait, which is the whole design at reveal 1 anyway.
+                teardown();
+                setSurface("portrait");
+            }
+        };
+        void mount();
+        return () => {
+            cancelled = true;
+            teardown();
+            setSurface("portrait");
+        };
+    }, [src, wet]);
+    useEffect(() => {
+        const host = hostRef.current;
+        const mount = mountRef.current;
+        if (!host || !mount)
+            return;
+        const field = resolveIdentityColor(host, PRESENCE_FIELD_TOKEN);
+        if (!field)
+            return;
+        mount.setUniforms(waterUniforms(value, field));
+    }, [value]);
+    return (_jsxs("div", { className: cn("nc-threshold-presence", className), "data-state": state, "data-still": still || undefined, style: { "--threshold-portrait": `url("${src}")` }, children: [_jsx("div", { "aria-hidden": "true", className: "nc-threshold-presence-figure", "data-surface": surface, ref: hostRef, style: { opacity: arriving ? arrivalOpacity(value) : 1 }, children: _jsx("img", { alt: "", className: "nc-threshold-presence-portrait", draggable: false, src: src }) }), _jsx("div", { "aria-label": label, "aria-valuemax": 100, "aria-valuemin": 0, "aria-valuenow": Math.floor(value * 100), className: "nc-threshold-sr", role: "progressbar" })] }));
+}

package/dist/components/threshold/room.d.ts

@@ -0,0 +1,33 @@
+export type ThresholdRoomProps = {
+    className?: string;
+    /** Repair and error states quiet the room instead of hiding it. */
+    dimmed?: boolean;
+    /**
+     * How much of the room's pace is running, 0 to 1. The captured recipe is
+     * energy 1; the first-run screen holds it there while Nadia is still
+     * arriving and drops it to 0 when she has, which stills the field. Sign-in,
+     * success and every repair state pass 0.
+     */
+    energy?: number;
+    /** Success: the field's colour becomes verde vivo, Nadia's presence accent. */
+    ready?: boolean;
+};
+/**
+ * The threshold's background field.
+ *
+ * It paints absolutely inside its own relative, isolated parent and never
+ * against the viewport, so a Portal panel can hold one without covering the
+ * page. It takes no pointer events and carries no words.
+ *
+ * When WebGL is unavailable, when the design-system tokens are not in the
+ * cascade above it, or when the context is lost after mounting, the element
+ * keeps its still field: a token-built radial gradient that needs no GPU. The
+ * room is never blank.
+ *
+ * The window carries one shader canvas. While Nadia's water is painting her
+ * arrival, the room holds this same still field and mounts nothing; the
+ * moment she stands clear the water leaves and the room's canvas is the one
+ * that paints (`canvas-budget.ts`).
+ */
+export declare function ThresholdRoom({ className, dimmed, energy, ready, }: ThresholdRoomProps): import("react").JSX.Element;
+//# sourceMappingURL=room.d.ts.map

package/dist/components/threshold/room.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room.d.ts","sourceRoot":"","sources":["../../../src/components/threshold/room.tsx"],"names":[],"mappings":"AAwCA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAIF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,EAC5B,SAAS,EACT,MAAc,EACd,MAAU,EACV,KAAa,GACd,EAAE,kBAAkB,+BA+IpB"}

package/dist/components/threshold/room.js

@@ -0,0 +1,168 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { defaultObjectSizing, meshGradientFragmentShader, ShaderFitOptions, ShaderMount, } from "@paper-design/shaders";
+import { useEffect, useRef, useState } from "react";
+import { resolveIdentityColor } from "../../internal/agent-visual/color.js";
+import { cn } from "../../lib/utils.js";
+import { useCanvasHeld } from "./canvas-budget.js";
+import { useReducedMotion } from "./use-reduced-motion.js";
+/*
+ * The room is the place a threshold happens in: one field of verde ink on true
+ * black, behind Nadia and behind the words. It is Paper Shaders' published
+ * Mesh Gradient "Ink" preset, adapted to two colours and slowed, mounted
+ * through the core `ShaderMount` the package already depends on. There is no
+ * React wrapper and no second shader engine.
+ *
+ * Every number below was selected from rendered captures (the study is
+ * `apps/nadia/build/design/threshold/`), so this module is the one place they
+ * are written.
+ */
+const ROOM_SPEED = 0.22;
+const ROOM_FRAME = 12_000;
+const ROOM_MIN_PIXEL_RATIO = 1;
+const ROOM_MAX_PIXEL_COUNT = 1_024_000;
+const ROOM_DISTORTION = 1;
+const ROOM_SWIRL = 0.2;
+const ROOM_ROTATION = 90;
+/** The field's ink, and the two colours it carries. Uniforms, never CSS. */
+const ROOM_INK_TOKEN = "--nc-identity-ink";
+const ROOM_FIELD_TOKEN = "--nc-identity-verde";
+const ROOM_READY_TOKEN = "--nc-dark-verde-vivo";
+const clampUnit = (value) => Math.min(Math.max(value, 0), 1);
+/**
+ * The threshold's background field.
+ *
+ * It paints absolutely inside its own relative, isolated parent and never
+ * against the viewport, so a Portal panel can hold one without covering the
+ * page. It takes no pointer events and carries no words.
+ *
+ * When WebGL is unavailable, when the design-system tokens are not in the
+ * cascade above it, or when the context is lost after mounting, the element
+ * keeps its still field: a token-built radial gradient that needs no GPU. The
+ * room is never blank.
+ *
+ * The window carries one shader canvas. While Nadia's water is painting her
+ * arrival, the room holds this same still field and mounts nothing; the
+ * moment she stands clear the water leaves and the room's canvas is the one
+ * that paints (`canvas-budget.ts`).
+ */
+export function ThresholdRoom({ className, dimmed = false, energy = 0, ready = false, }) {
+    const still = useReducedMotion();
+    const hostRef = useRef(null);
+    const mountRef = useRef(null);
+    const [surface, setSurface] = useState("still");
+    const held = useCanvasHeld();
+    const speed = still ? 0 : ROOM_SPEED * clampUnit(energy);
+    // The deferred mount reads the values current when it runs, not the ones of
+    // the render that scheduled it.
+    const speedRef = useRef(speed);
+    const readyRef = useRef(ready);
+    useEffect(() => {
+        speedRef.current = speed;
+        readyRef.current = ready;
+    });
+    // The window's one canvas. While Nadia's water holds it the room keeps its
+    // still field; when the hold is released the room mounts. Every other prop
+    // change is carried into the live mount by the two effects below, so a prop
+    // change never rebuilds a WebGL context.
+    //
+    // The mount is deferred by one microtask. Effects run in tree order, so a
+    // presence mounted after the room takes its hold after this effect has run;
+    // deferring lets that hold cancel a mount that has not happened yet, and
+    // the window never carries two live contexts, not even for one tick.
+    useEffect(() => {
+        const host = hostRef.current;
+        if (!host || held)
+            return;
+        let cancelled = false;
+        let canvas = null;
+        const clearCanvases = () => {
+            for (const element of host.querySelectorAll("canvas"))
+                element.remove();
+            host.removeAttribute("data-paper-shader");
+        };
+        const handleContextLost = (event) => {
+            event.preventDefault();
+            canvas?.removeEventListener("webglcontextlost", handleContextLost);
+            canvas = null;
+            try {
+                mountRef.current?.dispose();
+            }
+            catch {
+                // The still field is already behind the canvas; vendor cleanup failing
+                // must not take the room down with it.
+            }
+            mountRef.current = null;
+            clearCanvases();
+            setSurface("still");
+        };
+        const mount = () => {
+            if (cancelled)
+                return;
+            const ink = resolveIdentityColor(host, ROOM_INK_TOKEN);
+            const field = resolveIdentityColor(host, readyRef.current ? ROOM_READY_TOKEN : ROOM_FIELD_TOKEN);
+            // Without the design-system cascade there is no palette to paint with, and
+            // a guessed colour would be a second source for a token value.
+            if (!ink || !field)
+                return;
+            try {
+                mountRef.current = new ShaderMount(host, meshGradientFragmentShader, {
+                    u_colors: [field, ink],
+                    u_colorsCount: 2,
+                    u_distortion: ROOM_DISTORTION,
+                    u_fit: ShaderFitOptions.contain,
+                    u_grainMixer: 0,
+                    u_grainOverlay: 0,
+                    u_offsetX: defaultObjectSizing.offsetX,
+                    u_offsetY: defaultObjectSizing.offsetY,
+                    u_originX: defaultObjectSizing.originX,
+                    u_originY: defaultObjectSizing.originY,
+                    u_rotation: ROOM_ROTATION,
+                    u_scale: defaultObjectSizing.scale,
+                    u_swirl: ROOM_SWIRL,
+                    u_worldHeight: defaultObjectSizing.worldHeight,
+                    u_worldWidth: defaultObjectSizing.worldWidth,
+                }, undefined, speedRef.current, ROOM_FRAME, ROOM_MIN_PIXEL_RATIO, ROOM_MAX_PIXEL_COUNT);
+                canvas = mountRef.current.canvasElement;
+                canvas.addEventListener("webglcontextlost", handleContextLost);
+                setSurface("shader");
+            }
+            catch {
+                // The constructor prepends its canvas before it reaches the context, so
+                // a failed mount leaves one behind that would cover the still field.
+                mountRef.current = null;
+                clearCanvases();
+                setSurface("still");
+            }
+        };
+        queueMicrotask(mount);
+        return () => {
+            cancelled = true;
+            canvas?.removeEventListener("webglcontextlost", handleContextLost);
+            try {
+                mountRef.current?.dispose();
+            }
+            catch {
+                // Same reason as above: disposal is best effort.
+            }
+            mountRef.current = null;
+            clearCanvases();
+            setSurface("still");
+        };
+    }, [held]);
+    useEffect(() => {
+        mountRef.current?.setSpeed(speed);
+    }, [speed]);
+    useEffect(() => {
+        const host = hostRef.current;
+        const mount = mountRef.current;
+        if (!host || !mount)
+            return;
+        const ink = resolveIdentityColor(host, ROOM_INK_TOKEN);
+        const field = resolveIdentityColor(host, ready ? ROOM_READY_TOKEN : ROOM_FIELD_TOKEN);
+        if (!ink || !field)
+            return;
+        mount.setUniforms({ u_colors: [field, ink] });
+    }, [ready]);
+    return (_jsx("div", { "aria-hidden": "true", className: cn("nc-threshold-room", className), "data-dimmed": dimmed || undefined, "data-ready": ready || undefined, "data-surface": surface, ref: hostRef }));
+}