Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* ui-juice — the shared game-feel library for three.ws.
* ════════════════════════════════════════════════════════════════════════════
* One vocabulary of interaction primitives, proven on /swarms, extracted so every
* front-end surface adopts the same motion instead of reinventing it.
*
* Every primitive is:
* · token-driven — durations/easings come from public/tokens.css, never raw ms.
* · reduced-motion-safe — the global `prefers-reduced-motion` block zeroes the
* `--duration-*` tokens, so `reducedMotion()` reads the computed token and each
* primitive jumps straight to its correct final state with no animation.
* · real-value only — these are transition helpers over real numbers/series; they
* never fabricate inputs.
*
* See docs/ui-juice.md for the full reference and a runnable example of each export.
*/
// ── motion environment ───────────────────────────────────────────────────────
let _rootStyle = null;
function rootStyle() {
if (typeof window === 'undefined' || typeof getComputedStyle !== 'function') return null;
// Re-read each call is cheap and survives theme/token swaps; cache the element ref only.
_rootStyle = getComputedStyle(document.documentElement);
return _rootStyle;
}
/**
* Resolve a `--duration-*` token to milliseconds from the live computed styles.
* Returns the numeric ms (e.g. 220) or the fallback when the token is absent.
* Under prefers-reduced-motion the global token override makes every duration 0.
* @param {string} token e.g. '--duration-base'
* @param {number} [fallback=220]
* @returns {number} milliseconds
*/
export function durationMs(token = '--duration-base', fallback = 220) {
const style = rootStyle();
if (!style) return fallback;
const raw = style.getPropertyValue(token).trim();
if (!raw) return fallback;
if (raw.endsWith('ms')) return parseFloat(raw) || 0;
if (raw.endsWith('s')) return (parseFloat(raw) || 0) * 1000;
const n = parseFloat(raw);
return Number.isFinite(n) ? n : fallback;
}
/**
* True when motion should be suppressed. Reads the computed `--duration-base`
* token (zeroed by the global prefers-reduced-motion block) and also honours a
* direct matchMedia check, so it's correct even before tokens.css loads.
* @returns {boolean}
*/
export function reducedMotion() {
if (durationMs('--duration-base', 220) === 0) return true;
return typeof window !== 'undefined' && typeof window.matchMedia === 'function'
&& window.matchMedia('(prefers-reduced-motion: reduce)').matches;
}
const easeOutCubic = (x) => 1 - Math.pow(1 - x, 3);
const now = () => (typeof performance !== 'undefined' && performance.now ? performance.now() : 0);
// ── 1. countUp ────────────────────────────────────────────────────────────────
const countTimers = typeof WeakMap === 'function' ? new WeakMap() : null;
/**
* Animate a number on an element between two REAL values, preserving the caller's
* formatting (sign, units, %). Cancels any in-flight count-up on the same element.
* Reduced motion → sets the final formatted value instantly.
*
* @param {HTMLElement} el target element (textContent is written)
* @param {number} from start value
* @param {number} to end value
* @param {{format?:(n:number)=>string, duration?:number, ease?:(x:number)=>number, token?:string}} [opts]
* @example countUp(el, 0, 1280, { format: (n) => `$${Math.round(n)}` })
*/
export function countUp(el, from, to, opts = {}) {
if (!el) return;
const format = opts.format || ((n) => String(Math.round(n)));
const ease = opts.ease || easeOutCubic;
if (countTimers) {
const prev = countTimers.get(el);
if (prev) { cancelAnimationFrame(prev); countTimers.delete(el); }
}
el.dataset.juiceVal = to == null ? '' : String(to);
if (from == null || to == null || from === to || reducedMotion() || typeof requestAnimationFrame !== 'function') {
el.textContent = format(to);
return;
}
const dur = opts.duration || durationMs(opts.token || '--duration-slow', 420);
if (dur <= 0) { el.textContent = format(to); return; }
// Seed the start from the FIRST frame's own timestamp rather than performance.now().
// requestAnimationFrame is not contractually on the same time origin as
// performance.now() (polyfills and some embedders pass a Date-based clock), and a
// `t` behind `start` drives p negative — easeOutCubic then overshoots wildly and the
// element renders garbage like "-42797%" before settling. Clamping p as well keeps a
// single frame from ever painting a value outside [from, to].
let start = null;
const delta = to - from;
const step = (t) => {
if (start === null) start = t;
const p = Math.max(0, Math.min(1, (t - start) / dur));
el.textContent = format(from + delta * ease(p));
if (p < 1) { if (countTimers) countTimers.set(el, requestAnimationFrame(step)); }
else { el.textContent = format(to); if (countTimers) countTimers.delete(el); }
};
if (countTimers) countTimers.set(el, requestAnimationFrame(step));
else requestAnimationFrame(step);
}
/**
* Count an element from its last `countUp`/`flashValue`-tracked value to a new one
* and flash in the direction of change — the swarms `updateTile` pattern, generalized.
* @param {HTMLElement} el
* @param {number} to new real value
* @param {(n:number)=>string} format
* @param {{flash?:boolean}} [opts]
*/
export function updateValue(el, to, format, opts = {}) {
if (!el) return;
const prevRaw = el.dataset.juiceVal;
const prev = prevRaw == null || prevRaw === '' ? null : Number(prevRaw);
if (opts.flash !== false && prev != null && to != null && to !== prev) {
flashValue(el, to > prev ? 'up' : 'down');
}
countUp(el, prev, to, { format });
}
// ── 2. flashValue ───────────────────────────────────────────────────────────────
/**
* Directional tint pulse on an element, then settle. Generalizes the swarms `flash()`.
* Adds a class the CSS animates; reduced motion → no-op (final state already correct).
* @param {HTMLElement} el
* @param {'up'|'down'|'neutral'} [direction='neutral']
*/
export function flashValue(el, direction = 'neutral') {
if (!el || reducedMotion()) return;
const cls = direction === 'up' ? 'juice-flash--up' : direction === 'down' ? 'juice-flash--down' : 'juice-flash--neutral';
el.classList.remove('juice-flash--up', 'juice-flash--down', 'juice-flash--neutral');
void el.offsetWidth; // restart the animation on back-to-back flashes
el.classList.add(cls);
el.addEventListener('animationend', () => el.classList.remove(cls), { once: true });
}
// ── 3. enterRow ─────────────────────────────────────────────────────────────────
/**
* Slide+fade a freshly-inserted row/item in from the top (live logs/feeds).
* Reduced motion → no class added, element is already in its final state.
* @param {HTMLElement} el the just-inserted element
*/
export function enterRow(el) {
if (!el || reducedMotion()) return;
el.classList.add('juice-enter');
el.addEventListener('animationend', () => el.classList.remove('juice-enter'), { once: true });
}
/**
* Stagger-enter a list of freshly-inserted elements (grid/feed population).
* Each item's delay is index × step, capped so long lists don't crawl in.
* Reduced motion → no-op.
* @param {Iterable<HTMLElement>} els
* @param {{step?:number, max?:number}} [opts] step ms between items, max total delay
*/
export function enterStagger(els, opts = {}) {
if (reducedMotion()) return;
const step = opts.step || 28;
const max = opts.max || 320;
let i = 0;
for (const el of els) {
if (!el) { i++; continue; }
const delay = Math.min(i * step, max);
el.style.setProperty('--juice-enter-delay', `${delay}ms`);
enterRow(el);
i++;
}
}
// ── 4. sparkline ────────────────────────────────────────────────────────────────
/**
* Build the polyline path + bounds for a real numeric series. Pure; unit-tested.
* @param {number[]} values
* @param {number} width
* @param {number} height
* @param {number} [pad=2]
* @returns {{points:string, last:{x:number,y:number}, min:number, max:number, net:number}}
*/
export function sparklinePath(values, width, height, pad = 2) {
const v = (values || []).filter((n) => Number.isFinite(n));
const w = width, h = height;
if (v.length === 0) return { points: '', last: { x: 0, y: h / 2 }, min: 0, max: 0, net: 0 };
const min = Math.min(...v);
const max = Math.max(...v);
const span = max - min || 1;
const innerW = Math.max(1, w - pad * 2);
const innerH = Math.max(1, h - pad * 2);
const stepX = v.length > 1 ? innerW / (v.length - 1) : 0;
const pts = v.map((n, i) => {
const x = pad + i * stepX;
const y = pad + innerH - ((n - min) / span) * innerH;
return { x, y };
});
return {
points: pts.map((p) => `${p.x.toFixed(2)},${p.y.toFixed(2)}`).join(' '),
last: pts[pts.length - 1],
min, max,
net: v[v.length - 1] - v[0],
};
}
/**
* Inline SVG string for a real numeric series. Net-positive vs net-negative coloring
* via tokens; optional animated draw (stroke-dashoffset) and a final-point dot.
* @param {number[]} values
* @param {{width?:number, height?:number, fill?:boolean, dot?:boolean, animate?:boolean, stroke?:string}} [opts]
* @returns {string} SVG markup
*/
export function sparkline(values, opts = {}) {
const width = opts.width || 96;
const height = opts.height || 28;
const { points, last, net } = sparklinePath(values, width, height);
if (!points) return `<svg class="juice-spark" width="${width}" height="${height}" aria-hidden="true"></svg>`;
const color = opts.stroke || (net >= 0 ? 'var(--success)' : 'var(--danger)');
const animate = opts.animate && !reducedMotion();
const fillEl = opts.fill
? `<polygon class="juice-spark-fill" points="${points} ${last.x.toFixed(2)},${height} 0,${height}" fill="${color}" opacity="0.12" />`
: '';
const dotEl = opts.dot !== false
? `<circle class="juice-spark-dot" cx="${last.x.toFixed(2)}" cy="${last.y.toFixed(2)}" r="2" fill="${color}" />`
: '';
return `<svg class="juice-spark${animate ? ' juice-spark--draw' : ''}" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" fill="none" aria-hidden="true">`
+ fillEl
+ `<polyline points="${points}" stroke="${color}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" />`
+ dotEl
+ `</svg>`;
}
// ── 5. ring ─────────────────────────────────────────────────────────────────────
/**
* Arc-length geometry for a ring gauge filling to a real percentage. Pure; unit-tested.
* @param {number} pct 0..100 (clamped)
* @param {number} size px
* @param {number} stroke ring thickness px
* @returns {{r:number, circumference:number, offset:number, pct:number, center:number}}
*/
export function ringGeometry(pct, size, stroke) {
const clamped = Math.max(0, Math.min(100, Number.isFinite(pct) ? pct : 0));
const center = size / 2;
const r = center - stroke / 2;
const circumference = 2 * Math.PI * r;
const offset = circumference * (1 - clamped / 100);
return { r, circumference, offset, pct: clamped, center };
}
/**
* SVG arc gauge filling to a real percentage with a centered label.
* @param {number} pct 0..100
* @param {{size?:number, stroke?:number, label?:string, color?:string, track?:string, animate?:boolean}} [opts]
* @returns {string} SVG markup
*/
export function ring(pct, opts = {}) {
const size = opts.size || 64;
const stroke = opts.stroke || 5;
const { r, circumference, offset, pct: p, center } = ringGeometry(pct, size, stroke);
const color = opts.color || (p >= 66 ? 'var(--success)' : p >= 33 ? 'var(--warn)' : 'var(--danger)');
const track = opts.track || 'var(--surface-3)';
const label = opts.label != null ? opts.label : `${Math.round(p)}%`;
const animate = opts.animate !== false && !reducedMotion();
// dashoffset starts full (empty) then transitions to the real offset for a fill sweep
const startOffset = animate ? circumference : offset;
return `<svg class="juice-ring" width="${size}" height="${size}" viewBox="0 0 ${size} ${size}" role="img" aria-label="${escapeAttr(String(label))}">`
+ `<circle cx="${center}" cy="${center}" r="${r.toFixed(2)}" fill="none" stroke="${track}" stroke-width="${stroke}" />`
+ `<circle class="juice-ring-fill" cx="${center}" cy="${center}" r="${r.toFixed(2)}" fill="none" stroke="${color}" stroke-width="${stroke}" stroke-linecap="round"`
+ ` stroke-dasharray="${circumference.toFixed(2)}" stroke-dashoffset="${startOffset.toFixed(2)}"`
+ ` data-offset="${offset.toFixed(2)}" transform="rotate(-90 ${center} ${center})" />`
+ (label !== '' ? `<text class="juice-ring-label" x="${center}" y="${center}" text-anchor="middle" dominant-baseline="central">${escapeHtml(String(label))}</text>` : '')
+ `</svg>`;
}
/**
* After inserting `ring(..., {animate:true})` markup, call this on the container to
* sweep the fill from empty to its real offset. Safe to call when reduced motion.
* @param {HTMLElement} scope element containing one or more `.juice-ring-fill`
*/
export function playRings(scope) {
if (!scope) return;
const fills = scope.querySelectorAll('.juice-ring-fill[data-offset]');
fills.forEach((fill) => {
const target = fill.getAttribute('data-offset');
if (reducedMotion()) { fill.style.strokeDashoffset = target; return; }
requestAnimationFrame(() => requestAnimationFrame(() => { fill.style.strokeDashoffset = target; }));
});
}
// ── 6. flipReorder ──────────────────────────────────────────────────────────────
/**
* FLIP-animate a container's children to their new positions after a re-sort or
* re-render, so lists reorder smoothly instead of snapping. Call `capture()` BEFORE
* the DOM mutation and `play()` AFTER. Reduced motion → play() is a no-op.
*
* @param {HTMLElement} container
* @param {(el:HTMLElement)=>string} keyFn stable identity per child (e.g. el => el.dataset.id)
* @returns {{capture:()=>void, play:()=>void}}
* @example
* const flip = flipReorder(list, el => el.dataset.id);
* flip.capture(); list.append(...resorted); flip.play();
*/
export function flipReorder(container, keyFn) {
let firstRects = null;
const measure = () => {
const map = new Map();
if (!container) return map;
Array.from(container.children).forEach((child) => {
const key = keyFn(child);
if (key != null) map.set(String(key), child.getBoundingClientRect());
});
return map;
};
return {
capture() { firstRects = measure(); },
play() {
if (!container || !firstRects || reducedMotion()) { firstRects = null; return; }
Array.from(container.children).forEach((child) => {
const key = keyFn(child);
const first = key != null && firstRects.get(String(key));
if (!first) return;
const last = child.getBoundingClientRect();
const dx = first.left - last.left;
const dy = first.top - last.top;
if (!dx && !dy) return;
child.style.transform = `translate(${dx}px, ${dy}px)`;
child.style.transition = 'none';
requestAnimationFrame(() => {
child.style.transition = 'transform var(--duration-base) var(--ease-emphasized)';
child.style.transform = '';
});
child.addEventListener('transitionend', () => { child.style.transition = ''; child.style.transform = ''; }, { once: true });
});
firstRects = null;
},
};
}
/**
* Diff two ordered key lists into the set of keys whose index changed — the pure
* core of a FLIP reorder decision. Unit-tested.
* @param {string[]} before
* @param {string[]} after
* @returns {string[]} keys that moved
*/
export function reorderedKeys(before, after) {
const beforeIdx = new Map(before.map((k, i) => [String(k), i]));
const moved = [];
after.forEach((k, i) => {
const key = String(k);
if (beforeIdx.has(key) && beforeIdx.get(key) !== i) moved.push(key);
});
return moved;
}
// ── 7. liveDot ──────────────────────────────────────────────────────────────────
/**
* Markup for a small live-state indicator mirroring the swarms `.sw-live` vocabulary
* for SSE-backed surfaces. States: 'live' | 'connecting' | 'idle' | 'error'.
* @param {'live'|'connecting'|'idle'|'error'} [state='idle']
* @param {{label?:string}} [opts]
* @returns {string} markup
*/
export function liveDot(state = 'idle', opts = {}) {
const label = opts.label != null ? opts.label : state;
return `<span class="juice-live" data-state="${escapeAttr(state)}">`
+ `<span class="juice-live-dot" aria-hidden="true"></span>`
+ `<span class="juice-live-txt">${escapeHtml(String(label))}</span>`
+ `</span>`;
}
function stampLiveDot(live, state, label) {
live.dataset.state = state;
const txt = live.querySelector('.juice-live-txt');
if (txt && label != null) txt.textContent = label;
}
// A live badge is usually authored inside a line of copy, and on four surfaces
// (/clash, /leaderboard, /labor-market, /signals) that line carries
// `data-i18n-html`. The catalog value for such a key is a frozen snapshot of the
// original markup, badge included, so the i18n pass reinstates the authored
// state ("connecting") over whatever the page has since learned. The pass is
// async, so it always lands after the first setLiveDot call, and a surface that
// then stops polling (an unconfigured upstream, a settled stream) is left
// showing an amber "connecting" that contradicts the page beneath it.
//
// Re-stamp the last requested state whenever the badge's container swaps its
// children out. Watching the container rather than listening for an i18n event
// keeps this correct for every writer: the boot-time document pass, a locale
// switch, and the injected-content observer all rewrite children the same way.
const liveDotWanted = new WeakMap(); // container -> { state, label }
const liveDotWatched = new WeakSet(); // containers already observed
function watchLiveDot(live, state, label) {
const host = live.closest?.('[data-i18n-html]') || live.parentElement;
if (!host) return;
liveDotWanted.set(host, { state, label });
if (liveDotWatched.has(host) || typeof MutationObserver !== 'function') return;
liveDotWatched.add(host);
// childList only, no subtree: the re-stamp writes an attribute and a text
// node deeper down, so it can never retrigger this observer.
const observer = new MutationObserver(() => {
const want = liveDotWanted.get(host);
const next = host.querySelector('.juice-live');
if (!want || !next || next.dataset.state === want.state) return;
stampLiveDot(next, want.state, want.label);
});
observer.observe(host, { childList: true });
}
/**
* Update an existing `.juice-live` element's state + label in place, and keep it
* updated if something later rewrites the markup around it (see above).
* @param {HTMLElement} el a `.juice-live` element (or container of one)
* @param {'live'|'connecting'|'idle'|'error'} state
* @param {string} [label]
*/
export function setLiveDot(el, state, label) {
if (!el) return;
const live = el.classList && el.classList.contains('juice-live') ? el : el.querySelector && el.querySelector('.juice-live');
if (!live) return;
stampLiveDot(live, state, label);
watchLiveDot(live, state, label);
}
// ── 8. rippleOnce ───────────────────────────────────────────────────────────────
/**
* A single restrained accent ripple along an element's edge for "something happened"
* beats (a real success, a fired event). No confetti. Reduced motion → no-op.
* @param {HTMLElement} el
*/
export function rippleOnce(el) {
if (!el || reducedMotion()) return;
el.classList.remove('juice-ripple');
void el.offsetWidth; // restart on back-to-back beats
el.classList.add('juice-ripple');
el.addEventListener('animationend', () => el.classList.remove('juice-ripple'), { once: true });
}
// ── internals ───────────────────────────────────────────────────────────────────
function escapeHtml(s) {
return s.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>');
}
function escapeAttr(s) {
return s.replace(/&/g, '&').replace(/"/g, '"').replace(/</g, '<').replace(/>/g, '>');
}