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
/**
* Frame governor — unit tests.
*
* The governor is the heat fix for /play and /club: it caps how often a
* rAF-driven loop actually does sim + render work, independent of the
* display's refresh rate. These tests drive it with synthetic timestamps
* (no rAF, no DOM) and assert the properties the pages rely on:
*
* - a 60fps cap on a 144Hz timestamp stream runs ~60 frames/sec, not 48
* (the remainder-carry) and never more than the cap (+jitter slack)
* - a true 60Hz stream under a 60fps cap never skips (the 0.5ms slack)
* - cap changes take effect immediately (blur → 30fps)
* - degenerate caps (0, NaN) refuse to run rather than running hot
* - power-saver persistence round-trips and survives broken storage
*/
import { describe, it, expect, beforeEach } from 'vitest';
import {
createFrameGovernor,
getPowerSaver,
setPowerSaver,
FPS_ACTIVE,
FPS_IDLE,
FPS_SAVER,
} from '../src/shared/frame-governor.js';
// Count how many frames the governor lets through over `seconds` of a
// synthetic display running at `hz`, with a per-frame cap of `fps`.
function runStream({ hz, fps, seconds = 2, start = 1000 }) {
const gov = createFrameGovernor();
const period = 1000 / hz;
const frames = Math.round(seconds * hz);
let ran = 0;
for (let i = 0; i < frames; i++) {
if (gov.shouldRun(start + i * period, fps)) ran++;
}
return ran / seconds; // frames per second actually run
}
describe('createFrameGovernor', () => {
it('caps a 144Hz stream to ~60fps (remainder-carry, no 48fps quantization)', () => {
const rate = runStream({ hz: 144, fps: 60 });
expect(rate).toBeGreaterThanOrEqual(55);
expect(rate).toBeLessThanOrEqual(65);
});
it('caps a 240Hz stream to ~60fps', () => {
const rate = runStream({ hz: 240, fps: 60 });
expect(rate).toBeGreaterThanOrEqual(55);
expect(rate).toBeLessThanOrEqual(65);
});
it('never skips frames on a true 60Hz panel at a 60fps cap', () => {
const rate = runStream({ hz: 60, fps: 60 });
expect(rate).toBe(60);
});
it('caps a 60Hz stream to ~30fps under the idle cap', () => {
const rate = runStream({ hz: 60, fps: 30 });
expect(rate).toBeGreaterThanOrEqual(28);
expect(rate).toBeLessThanOrEqual(32);
});
it('applies a cap change on the very next frame', () => {
const gov = createFrameGovernor();
// 60Hz stream, active cap: every frame runs.
expect(gov.shouldRun(0, 60)).toBe(true);
expect(gov.shouldRun(16.67, 60)).toBe(true);
// Blur → 30fps cap: the frame ~16ms later must now be skipped.
expect(gov.shouldRun(33.33, 30)).toBe(false);
expect(gov.shouldRun(50, 30)).toBe(true);
});
it('runs immediately after a long stall without a catch-up burst', () => {
const gov = createFrameGovernor();
expect(gov.shouldRun(0, 60)).toBe(true);
// 5s hidden-tab gap: first frame back runs...
expect(gov.shouldRun(5000, 60)).toBe(true);
// ...and the next display frame does NOT get a queued burst.
expect(gov.shouldRun(5006.9, 60)).toBe(false);
});
it('refuses to run on degenerate caps instead of running uncapped', () => {
const gov = createFrameGovernor();
expect(gov.shouldRun(0, 0)).toBe(false);
expect(gov.shouldRun(16, -30)).toBe(false);
expect(gov.shouldRun(32, NaN)).toBe(false);
});
it('fails open on a non-finite timestamp (never wedges the loop shut)', () => {
const gov = createFrameGovernor();
expect(gov.shouldRun(NaN, 60)).toBe(true);
expect(gov.shouldRun(undefined, 60)).toBe(true);
});
it('reset() lets the next frame run regardless of recency', () => {
const gov = createFrameGovernor();
expect(gov.shouldRun(1000, 60)).toBe(true);
expect(gov.shouldRun(1001, 60)).toBe(false);
gov.reset();
expect(gov.shouldRun(1002, 60)).toBe(true);
});
});
describe('fps constants', () => {
it('keeps the shared vocabulary sane (active > idle/saver > 0)', () => {
expect(FPS_ACTIVE).toBeGreaterThan(FPS_IDLE);
expect(FPS_IDLE).toBeGreaterThan(0);
expect(FPS_SAVER).toBeGreaterThan(0);
expect(FPS_SAVER).toBeLessThanOrEqual(FPS_IDLE);
});
});
describe('power-saver persistence', () => {
beforeEach(() => {
// vitest environment may or may not provide localStorage; give the
// module a working in-memory one for the round-trip test.
const store = new Map();
globalThis.localStorage = {
getItem: (k) => (store.has(k) ? store.get(k) : null),
setItem: (k, v) => store.set(k, String(v)),
removeItem: (k) => store.delete(k),
};
});
it('defaults off and round-trips on/off', () => {
expect(getPowerSaver()).toBe(false);
setPowerSaver(true);
expect(getPowerSaver()).toBe(true);
setPowerSaver(false);
expect(getPowerSaver()).toBe(false);
});
it('reads as off when storage throws (private mode, sandboxed iframe)', () => {
globalThis.localStorage = {
getItem() { throw new Error('denied'); },
setItem() { throw new Error('denied'); },
};
expect(getPowerSaver()).toBe(false);
expect(() => setPowerSaver(true)).not.toThrow();
});
});