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
// @vitest-environment jsdom
//
// async-state boundary contract — the unit-level proof of the A04 audit goal:
// "a forced network failure never yields a blank page or an unhandled
// rejection." Every data-driven surface routes its loading → fetch →
// empty / error / retry lifecycle through src/shared/async-state.js, so the
// guarantees that keep a void off the screen live here. These tests lock that
// behaviour in: a rejected load resolves into a *designed, retryable* error
// state (not a throw), empty data renders the empty shell, and Retry re-runs
// the original load.
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { loadInto, renderError } from '../src/shared/async-state.js';
// Note: resolveError logs technical detail via log.js, which binds
// console.error at import time — a later spy cannot intercept it. These tests
// therefore assert the user-facing contract (a designed shell, never a raw
// message), not the console channel; the stderr line on a failing load is the
// by-design "errors always log" behaviour.
describe('async-state — loadInto boundary', () => {
let container;
beforeEach(() => {
container = document.createElement('div');
document.body.appendChild(container);
});
afterEach(() => {
container.remove();
});
it('renders the populated state on a successful load', async () => {
const data = await loadInto(container, {
load: () => Promise.resolve(['a', 'b', 'c']),
render: (items, el) => {
el.innerHTML = items.map((i) => `<div class="card">${i}</div>`).join('');
},
skeleton: { count: 3, variant: 'card' },
});
expect(data).toEqual(['a', 'b', 'c']);
expect(container.querySelectorAll('.card')).toHaveLength(3);
// No leftover skeleton / error shells.
expect(container.querySelector('.tws-sk')).toBeNull();
expect(container.querySelector('.tws-es--error')).toBeNull();
});
it('renders a designed empty state (not the populated render) when data is empty', async () => {
const render = vi.fn();
const data = await loadInto(container, {
load: () => Promise.resolve([]),
render,
empty: { title: 'No agents yet', body: 'Deploy your first agent to see it here.' },
});
expect(data).toBeNull();
expect(render).not.toHaveBeenCalled();
const empty = container.querySelector('.tws-es');
expect(empty).not.toBeNull();
expect(empty.textContent).toContain('No agents yet');
});
it('a rejected load fails into a retryable error state instead of throwing', async () => {
// The promise must RESOLVE (to null) — an unhandled rejection here would be
// exactly the blank-screen failure A04 exists to prevent.
const data = await loadInto(container, {
load: () => Promise.reject(new Error('boom: network down')),
render: () => {
throw new Error('render must not run on a failed load');
},
context: 'test:boundary',
});
expect(data).toBeNull();
const errShell = container.querySelector('.tws-es--error');
expect(errShell).not.toBeNull();
expect(errShell.getAttribute('role')).toBe('alert');
// An actionable recovery affordance is present.
expect(container.querySelector('[data-sk-retry]')).not.toBeNull();
// The raw error message is never surfaced verbatim in the user-facing copy.
expect(errShell.textContent).not.toContain('boom: network down');
});
it('Retry re-runs the original load and recovers into the populated state', async () => {
let attempt = 0;
const load = vi.fn(() => {
attempt += 1;
return attempt === 1
? Promise.reject(new Error('transient'))
: Promise.resolve(['recovered']);
});
await loadInto(container, {
load,
render: (items, el) => {
el.innerHTML = items.map((i) => `<div class="card">${i}</div>`).join('');
},
});
// First attempt failed → error shell with a retry button.
const retry = container.querySelector('[data-sk-retry]');
expect(retry).not.toBeNull();
// Clicking Retry re-runs loadInto; await a microtask flush for the re-render.
retry.click();
await vi.waitFor(() => {
expect(container.querySelector('.card')).not.toBeNull();
});
expect(load).toHaveBeenCalledTimes(2);
expect(container.querySelector('.card').textContent).toBe('recovered');
expect(container.querySelector('.tws-es--error')).toBeNull();
});
it('loadInto on a null container is a no-op (defensive, never throws)', async () => {
await expect(loadInto(null, { load: () => Promise.resolve([]), render: () => {} }))
.resolves.toBeNull();
});
});
describe('async-state — renderError direct shell', () => {
let container;
beforeEach(() => {
container = document.createElement('div');
document.body.appendChild(container);
});
afterEach(() => {
container.remove();
});
it('renders the shared error shell and wires the retry callback', () => {
const onRetry = vi.fn();
renderError(container, new Error('offline'), { context: 'test:direct' }, onRetry);
const errShell = container.querySelector('.tws-es--error');
expect(errShell).not.toBeNull();
const retry = container.querySelector('[data-sk-retry]');
expect(retry).not.toBeNull();
retry.click();
expect(onRetry).toHaveBeenCalledTimes(1);
});
it('honours a caller-supplied error title/body override', () => {
renderError(
container,
new Error('raw detail'),
{ error: { title: 'Couldn’t load your agents', body: 'Check your connection.' } },
);
const errShell = container.querySelector('.tws-es--error');
expect(errShell.textContent).toContain('Couldn’t load your agents');
expect(errShell.textContent).toContain('Check your connection.');
expect(errShell.textContent).not.toContain('raw detail');
});
});