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
// /sign-mirror: learn a handshape by making it, not by watching one.
//
// The avatar forms the target letter. Your camera watches your hand. The two
// are compared against the SAME handshape spec (src/sign-handshapes.js), so the
// thing being taught and the thing being graded can never drift apart. Hold the
// shape and the letter passes; hold it wrong and the page names the finger.
//
// Everything on the camera side stays on the device. MediaPipe's hand
// landmarker runs in this tab, the grading is arithmetic in src/sign-grader.js,
// and no frame, landmark, or score is ever uploaded. There is no network call
// in the practice loop at all.
import { PoseStage } from './avatar-pose.js';
import { buildFingerspellingClip } from './fingerspelling.js';
import { LETTERS, LETTER_NOTES } from './asl-alphabet-data.js';
import { GradeSmoother, gradeHandshape, rankHandshapes } from './sign-grader.js';
import { HAND_CONNECTIONS, handshapeLandmarks, projectHand } from './sign-hand-model.js';
import { loadSignPrefs, resolveRig, saveSignPrefs } from './sign-avatars.js';
import { log } from './shared/log.js';
const PROGRESS_KEY = 'threews:sign-mirror-progress';
// Letters whose handshape is identical to another letter's: in ASL they differ
// by which way the hand points, which a handshape score cannot see. They are
// still taught, with the difference spelled out, but never marked wrong for it.
const SHARED_SHAPE = { G: 'Q', Q: 'G', K: 'P', P: 'K' };
// The manual alphabet in the order it is easiest to learn: closed shapes first,
// then the open hands, then the pairs people confuse, then the moving letters.
const COURSE = [
{ id: 'closed', title: 'Closed hands', blurb: 'Four letters made with the fingers folded in. The thumb does all the work.', letters: ['A', 'S', 'E', 'O'] },
{ id: 'open', title: 'Open hands', blurb: 'The flat and spread shapes. Easy to hold, easy to read.', letters: ['B', 'C', 'F', 'L'] },
{ id: 'points', title: 'Pointing fingers', blurb: 'One or two fingers up. Watch the gap between them.', letters: ['D', 'U', 'V', 'W'] },
{ id: 'tricky', title: 'The confusable ones', blurb: 'The pairs that trip up every beginner. Take these slowly.', letters: ['M', 'N', 'T', 'R'] },
{ id: 'rest', title: 'The rest', blurb: 'Everything left, including the two letters that move.', letters: ['G', 'H', 'I', 'K', 'P', 'Q', 'X', 'Y', 'J', 'Z'] },
];
const MOVING = new Set(['J', 'Z']);
const ALL_COURSE_LETTERS = COURSE.flatMap((s) => s.letters);
const $ = (sel, root = document) => root.querySelector(sel);
function readJSON(key, fallback) {
try {
return JSON.parse(localStorage.getItem(key)) || fallback;
} catch {
return fallback;
}
}
function writeJSON(key, value) {
try {
localStorage.setItem(key, JSON.stringify(value));
} catch {
/* private mode: progress just does not persist */
}
}
const SVG_NS = 'http://www.w3.org/2000/svg';
/**
* Draw a hand skeleton into an SVG element from 21 projected points.
*
* The overlay redraws on every camera frame, so the nodes are built once and
* then only their coordinates change: rebuilding 21 circles and 21 lines sixty
* times a second is enough layout churn to be felt on a laptop.
*/
function drawSkeleton(svg, points, { className = '' } = {}) {
let g = svg.firstElementChild;
if (!g || g.childElementCount !== HAND_CONNECTIONS.length + points.length) {
svg.textContent = '';
g = document.createElementNS(SVG_NS, 'g');
for (let i = 0; i < HAND_CONNECTIONS.length; i++) g.append(document.createElementNS(SVG_NS, 'line'));
points.forEach((_, i) => {
const dot = document.createElementNS(SVG_NS, 'circle');
dot.setAttribute('r', i === 0 || i % 4 === 0 ? '3.6' : '2.4');
g.append(dot);
});
svg.append(g);
}
if (g.getAttribute('class') !== className) g.setAttribute('class', className);
const nodes = g.children;
HAND_CONNECTIONS.forEach(([a, b], i) => {
const line = nodes[i];
line.setAttribute('x1', points[a].x.toFixed(1));
line.setAttribute('y1', points[a].y.toFixed(1));
line.setAttribute('x2', points[b].x.toFixed(1));
line.setAttribute('y2', points[b].y.toFixed(1));
});
points.forEach((p, i) => {
const dot = nodes[HAND_CONNECTIONS.length + i];
dot.setAttribute('cx', p.x.toFixed(1));
dot.setAttribute('cy', p.y.toFixed(1));
});
}
async function boot() {
const stageHost = $('#sm-stage');
if (!stageHost) return;
const prefs = loadSignPrefs();
const progress = readJSON(PROGRESS_KEY, { passed: {}, best: {} });
// The rig, the signing hand and any custom avatar come from the same stored
// block /sign-language and /asl-alphabet write.
let avatar = resolveRig(prefs);
let dominant = prefs.dominant === 'Left' ? 'Left' : 'Right';
let stage = null;
let canSign = false;
let current = ALL_COURSE_LETTERS[0];
let playToken = 0;
const statusEl = $('#sm-status');
const setStatus = (msg, tone = '') => {
if (!statusEl) return;
statusEl.textContent = msg || '';
statusEl.dataset.tone = tone;
};
// ── The avatar half ──────────────────────────────────────────────────────
const replayBtn = $('#sm-replay');
const setReplayable = (on) => {
if (!replayBtn) return;
replayBtn.disabled = !on;
replayBtn.title = on ? '' : 'This avatar cannot fingerspell, so there is nothing to replay. The target diagram still shows the shape.';
};
const mountStage = async () => {
stage?.dispose();
stage = new PoseStage(stageHost, { glbUrl: avatar.url, framing: 'portrait' });
try {
const { supported } = await stage.mount();
stage.start();
canSign = !!supported;
if (!supported) setStatus('This avatar has no finger bones. Practice still works: the target diagram and the scoring do not need it.', 'warn');
setReplayable(canSign);
return canSign;
} catch (err) {
log.warn('[sign-mirror] stage mount failed', err?.message);
canSign = false;
setReplayable(false);
setStatus('The 3D preview could not start. The target diagram and scoring still work.', 'warn');
return false;
}
};
const showOnAvatar = (letter) => {
if (!stage?.anim || !canSign) return;
const token = ++playToken;
let clip;
try {
clip = buildFingerspellingClip(letter, { holdSeconds: 1.6, transitionSeconds: 0.3, dominant, settle: false });
} catch (err) {
log.warn('[sign-mirror] clip failed', err?.message);
return;
}
const name = `sm-${token}`;
stage.anim.injectClip(name, clip, { loop: false });
stage.anim.playOnce(name, { settleTo: null });
};
// ── The target diagram ───────────────────────────────────────────────────
const targetSvg = $('#sm-target');
const drawTarget = (letter) => {
if (!targetSvg) return;
const box = targetSvg.viewBox.baseVal;
const pts = projectHand(handshapeLandmarks(letter, dominant), {
width: box.width,
height: box.height,
padding: 20,
flip: dominant === 'Left',
});
drawSkeleton(targetSvg, pts, { className: 'sm-skel sm-skel-target' });
};
// ── The camera half ──────────────────────────────────────────────────────
const video = $('#sm-video');
const overlay = $('#sm-overlay');
const scoreEl = $('#sm-score');
const scoreBar = $('#sm-score-bar');
const hintEl = $('#sm-hint');
const fingersEl = $('#sm-fingers');
const cameraBtn = $('#sm-camera');
const cameraNote = $('#sm-camera-note');
let landmarker = null;
let stream = null;
let raf = 0;
let running = false;
let lastVideoTime = -1;
const smoother = new GradeSmoother({ passScore: 78, holdMs: 800 });
const IDLE_HINT = 'Turn the camera on to be graded, or just copy the diagram.';
// The still letters: J and Z are excluded because they are defined by a path
// the hand traces, which a single-frame ranking cannot recognise.
const RANKABLE = LETTERS.filter((l) => !MOVING.has(l));
const RANK_INTERVAL_MS = 350;
let lastRankAt = 0;
let lookedLike = '';
// The hint is a live region, and it is written on every graded frame. Writing
// the same sentence again would make a screen reader read it again, so only a
// genuine change reaches the DOM. The tone is carried separately because a
// camera failure has to LOOK different from a coaching tip, and the sentence
// alone does not say so.
const setHint = (text, tone = '') => {
if (!hintEl) return;
if (hintEl.textContent !== text) hintEl.textContent = text;
if (hintEl.dataset.tone !== tone) hintEl.dataset.tone = tone;
};
/**
* Report a camera or tracker failure where the learner is actually looking.
*
* The avatar's status strip is the wrong home for this: it sits in the OTHER
* panel, over the 3D stage, hundreds of pixels from the button that was just
* pressed, so pressing "Turn the camera on" and being refused looked like the
* button did nothing. The hint box is directly above that button in both the
* two-column and the stacked layout, and is already a polite live region, so
* the recovery sentence goes there and the stage strip is cleared rather than
* left repeating it into a second live region.
*
* @param {string} message what went wrong and what to do about it
*/
const reportCameraProblem = (message) => {
stopCamera();
setStatus('');
setHint(message, 'warn');
};
const setScore = (value, holding, heldMs) => {
const pct = Math.max(0, Math.min(100, value));
if (scoreEl) scoreEl.textContent = `${Math.round(pct)}`;
if (scoreBar) {
scoreBar.style.setProperty('--sm-fill', `${pct}%`);
scoreBar.dataset.state = pct >= 78 ? 'good' : pct >= 55 ? 'close' : 'far';
scoreBar.setAttribute('aria-valuenow', String(Math.round(pct)));
}
if (holding && heldMs > 0) {
const held = Math.min(1, heldMs / smoother.holdMs);
scoreBar?.style.setProperty('--sm-hold', `${(held * 100).toFixed(0)}%`);
} else {
scoreBar?.style.setProperty('--sm-hold', '0%');
}
};
// One row per finger, built on the first graded frame and then updated in
// place. Same reason as the skeleton: this runs at camera frame rate.
const fingerRows = new Map();
const renderFingers = (grade) => {
if (!fingersEl) return;
for (const f of grade.fingers) {
let row = fingerRows.get(f.finger);
if (!row) {
const el = document.createElement('div');
el.className = 'sm-finger';
const name = document.createElement('span');
name.className = 'sm-finger-name';
name.textContent = f.finger;
const bar = document.createElement('span');
bar.className = 'sm-finger-bar';
// A real progressbar rather than a bare div: a screen reader can
// read the number on demand, without every frame announcing itself.
bar.setAttribute('role', 'progressbar');
bar.setAttribute('aria-label', `${f.finger} finger`);
bar.setAttribute('aria-valuemin', '0');
bar.setAttribute('aria-valuemax', '100');
el.append(name, bar);
fingersEl.append(el);
row = { el, bar, pct: -1 };
fingerRows.set(f.finger, row);
}
const state = f.score >= 0.8 ? 'good' : f.score >= 0.5 ? 'close' : 'far';
if (row.el.dataset.state !== state) row.el.dataset.state = state;
const pct = Math.round(f.score * 100);
if (pct !== row.pct) {
row.pct = pct;
row.bar.style.setProperty('--sm-fill', `${pct}%`);
row.bar.setAttribute('aria-valuenow', String(pct));
}
}
};
const clearFingers = () => {
fingerRows.clear();
if (fingersEl) fingersEl.textContent = '';
};
// The best score per letter survives the session, but the grader beats it
// many times a second: batch the write instead of touching storage per frame.
let bestTimer = 0;
const flushProgress = () => {
if (!bestTimer) return;
window.clearTimeout(bestTimer);
bestTimer = 0;
writeJSON(PROGRESS_KEY, progress);
renderLetterBest();
};
const saveBestSoon = () => {
if (bestTimer) return;
bestTimer = window.setTimeout(() => {
bestTimer = 0;
writeJSON(PROGRESS_KEY, progress);
renderLetterBest();
}, 2000);
};
const markPassed = (letter) => {
progress.passed[letter] = true;
writeJSON(PROGRESS_KEY, progress);
document.querySelector(`.sm-letter[data-char="${letter}"]`)?.setAttribute('data-passed', 'true');
renderProgress();
};
const onPassed = (letter) => {
markPassed(letter);
setStatus(`${letter} is right. Well held.`, 'good');
const idx = ALL_COURSE_LETTERS.indexOf(letter);
const next = ALL_COURSE_LETTERS.slice(idx + 1).find((l) => !progress.passed[l]) || ALL_COURSE_LETTERS.find((l) => !progress.passed[l]);
setHint(next ? `${letter} passed. ${next} is next.` : `${letter} passed. That is every letter in the alphabet.`);
if (next) window.setTimeout(() => selectLetter(next), 900);
else setStatus('Every letter passed. You can read and make the whole manual alphabet.', 'good');
};
const gradeFrame = (landmarks, now) => {
let grade;
try {
// J and Z move, and only their handshape can be scored; the letter card
// says so outright, so every letter grades against its own shape.
grade = gradeHandshape(landmarks, current);
} catch (err) {
log.warn('[sign-mirror] grade failed', err?.message);
return;
}
const state = smoother.push(grade, now);
setScore(state.score, state.holding, state.heldMs);
renderFingers(grade);
if (progress.best[current] == null || Math.round(state.score) > progress.best[current]) {
progress.best[current] = Math.round(state.score);
saveBestSoon();
}
if (state.passed) {
smoother.reset();
flushProgress();
onPassed(current);
return;
}
// When the hand is a long way off, say what it DOES look like: a learner
// making a clean B while aiming for D is helped far more by "that is a B"
// than by "straighten your ring finger". Ranking every letter costs a full
// grade per candidate, so it runs a few times a second, not per frame.
if (state.score < 45 && now - lastRankAt > RANK_INTERVAL_MS) {
lastRankAt = now;
const [best] = rankHandshapes(landmarks, RANKABLE);
lookedLike = best && best.name !== current && best.score > 70 ? best.name : '';
} else if (state.score >= 45) {
lookedLike = '';
}
setHint(lookedLike ? `That is a clean ${lookedLike}. For ${current}: ${grade.hint}` : grade.hint);
};
const stopCamera = () => {
running = false;
cancelAnimationFrame(raf);
stream?.getTracks().forEach((t) => t.stop());
stream = null;
lastVideoTime = -1;
smoother.reset();
if (video) video.srcObject = null;
document.body.dataset.smCamera = 'off';
if (cameraBtn) {
cameraBtn.textContent = 'Turn the camera on';
cameraBtn.setAttribute('aria-pressed', 'false');
}
overlay?.replaceChildren();
setScore(0, false, 0);
clearFingers();
lookedLike = '';
lastRankAt = 0;
if (cameraNote) cameraNote.hidden = true;
// Back to the state the page opened in: the box says what to do next
// rather than sitting there empty.
setHint(IDLE_HINT);
flushProgress();
};
/**
* What to tell the learner when the camera does not come up. The raw error is
* a bundler URL or a DOM exception name, neither of which anyone can act on,
* so each cause gets the sentence that says what to actually do next.
*
* @param {unknown} err whatever was thrown
* @param {'tracker'|'camera'} where which half of the start failed
* @returns {string}
*/
const cameraFailureMessage = (err, where) => {
const name = err?.name || '';
const text = err?.message || '';
if (where === 'tracker') {
return 'The hand tracker could not be downloaded. Check the connection and try again; the target diagram and the letter notes work without it.';
}
if (name === 'NotAllowedError' || /denied|not allowed|permission/i.test(text)) {
return 'Camera permission was refused. Allow it in your browser address bar, then try again.';
}
if (name === 'NotFoundError' || name === 'DevicesNotFoundError' || /not found|no device/i.test(text)) {
return 'No camera was found on this device. Copy the target diagram by eye instead: the letter notes still teach the shape.';
}
if (name === 'NotReadableError' || name === 'TrackStartError' || /in use|could not start video/i.test(text)) {
return 'The camera is busy in another app or tab. Close the other one and try again.';
}
if (name === 'SecurityError' || !window.isSecureContext) {
return 'Browsers only hand out the camera over HTTPS. Open this page on https://three.ws and try again.';
}
if (name === 'OverconstrainedError') {
return 'This camera cannot deliver the format the tracker needs. Try another camera, or copy the target diagram by eye.';
}
return 'The camera could not start. Try again, or copy the target diagram by eye: the letter notes still teach the shape.';
};
const startCamera = async () => {
if (running) return;
if (!navigator.mediaDevices?.getUserMedia) {
setHint(
window.isSecureContext
? 'This browser has no camera API. Practice with the target diagram instead.'
: 'Browsers only hand out the camera over HTTPS. Open this page on https://three.ws to be graded live.',
'warn',
);
return;
}
let failedAt = 'camera';
cameraBtn.disabled = true;
cameraBtn.setAttribute('aria-busy', 'true');
cameraBtn.textContent = 'Starting the camera...';
document.body.dataset.smCamera = landmarker ? 'starting' : 'loading';
try {
if (!landmarker) {
failedAt = 'tracker';
setStatus('Loading the hand tracker (about 8 MB, once per browser).');
const { FilesetResolver, HandLandmarker } = await import('@mediapipe/tasks-vision');
const { modelUrl, visionWasmBase } = await import('./shared/mediapipe-assets.js');
const fileset = await FilesetResolver.forVisionTasks(await visionWasmBase());
landmarker = await HandLandmarker.createFromOptions(fileset, {
baseOptions: {
modelAssetPath: modelUrl('hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task'),
delegate: 'GPU',
},
runningMode: 'VIDEO',
numHands: 1,
});
}
failedAt = 'camera';
document.body.dataset.smCamera = 'starting';
stream = await navigator.mediaDevices.getUserMedia({ video: { width: 640, height: 480, facingMode: 'user' }, audio: false });
video.srcObject = stream;
await video.play();
running = true;
document.body.dataset.smCamera = 'on';
cameraBtn.textContent = 'Turn the camera off';
cameraBtn.setAttribute('aria-pressed', 'true');
setStatus('Camera on. Nothing leaves this tab.', 'good');
if (cameraNote) cameraNote.hidden = false;
loop();
} catch (err) {
log.warn(`[sign-mirror] ${failedAt} failed`, err?.message);
// A tracker that half-loaded is not reusable: drop it so the next
// attempt downloads it again rather than throwing on a dead handle.
if (failedAt === 'tracker') landmarker = null;
reportCameraProblem(cameraFailureMessage(err, failedAt));
} finally {
cameraBtn.disabled = false;
cameraBtn.removeAttribute('aria-busy');
}
};
const loop = () => {
if (!running) return;
raf = requestAnimationFrame(loop);
if (!video.videoWidth || video.currentTime === lastVideoTime) return;
lastVideoTime = video.currentTime;
let result;
try {
result = landmarker.detectForVideo(video, performance.now());
} catch (err) {
// A tracker that throws mid-stream (a lost GPU context, a released
// WASM heap) would otherwise kill the frame loop silently and leave
// the page claiming the camera is on. Stop, and say why.
log.warn('[sign-mirror] tracker failed', err?.message);
landmarker = null;
reportCameraProblem('The hand tracker stopped. Turn the camera on again to restart it.');
return;
}
const hand = result?.landmarks?.[0];
if (!hand?.length) {
setHint('No hand in frame. Hold one hand up, palm toward the camera.');
if (overlay?.firstElementChild) overlay.replaceChildren();
setScore(0, false, 0);
return;
}
// The preview is mirrored so it reads like a mirror; the overlay has to
// be mirrored with it or the skeleton lands on the wrong side.
const box = overlay.viewBox.baseVal;
drawSkeleton(
overlay,
hand.map((p) => ({ x: (1 - p.x) * box.width, y: p.y * box.height })),
{ className: 'sm-skel sm-skel-live' },
);
gradeFrame(hand, performance.now());
};
// ── Letter selection ─────────────────────────────────────────────────────
const bigEl = $('#sm-big');
const noteEl = $('#sm-note');
const lookEl = $('#sm-look');
const sharedEl = $('#sm-shared');
const movingEl = $('#sm-moving');
function selectLetter(letter) {
if (!LETTER_NOTES[letter]) return;
current = letter;
smoother.reset();
setScore(0, false, 0);
if (bigEl) bigEl.textContent = letter;
if (noteEl) noteEl.textContent = LETTER_NOTES[letter].hand;
if (lookEl) {
lookEl.textContent = LETTER_NOTES[letter].look || '';
lookEl.hidden = !LETTER_NOTES[letter].look;
}
if (sharedEl) {
const twin = SHARED_SHAPE[letter];
sharedEl.hidden = !twin;
if (twin) sharedEl.textContent = `${letter} and ${twin} are the same handshape. What separates them is which way the hand points, so the score below cannot tell them apart: check the direction against the avatar.`;
}
if (movingEl) {
movingEl.hidden = !MOVING.has(letter);
if (MOVING.has(letter)) movingEl.textContent = `${letter} moves. The score checks the handshape only; watch the avatar for the path it traces.`;
}
document.querySelectorAll('.sm-letter').forEach((el) => {
el.setAttribute('aria-pressed', String(el.dataset.char === letter));
});
drawTarget(letter);
showOnAvatar(letter);
lookedLike = '';
lastRankAt = 0;
if (!running) {
setHint(IDLE_HINT);
clearFingers();
}
const url = new URL(location.href);
url.searchParams.set('letter', letter);
history.replaceState(null, '', url);
}
// ── Course rail ──────────────────────────────────────────────────────────
const railEl = $('#sm-rail');
const buildRail = () => {
if (!railEl) return;
railEl.textContent = '';
for (const section of COURSE) {
const wrap = document.createElement('section');
wrap.className = 'sm-group';
const h = document.createElement('h3');
h.textContent = section.title;
const p = document.createElement('p');
p.textContent = section.blurb;
const row = document.createElement('div');
row.className = 'sm-letters';
for (const letter of section.letters) {
const btn = document.createElement('button');
btn.type = 'button';
btn.className = 'sm-letter';
btn.dataset.char = letter;
btn.textContent = letter;
btn.setAttribute('aria-pressed', String(letter === current));
if (progress.passed[letter]) btn.dataset.passed = 'true';
btn.addEventListener('click', () => selectLetter(letter));
row.append(btn);
}
wrap.append(h, p, row);
railEl.append(wrap);
}
renderLetterBest();
};
// The best score a letter has reached is worth seeing: it turns 26 identical
// squares into a map of where the practice actually is. The sliver under the
// letter is the score, and the label says it out loud for a screen reader.
function renderLetterBest() {
for (const btn of document.querySelectorAll('.sm-letter')) {
const letter = btn.dataset.char;
const best = progress.best[letter];
const held = progress.passed[letter];
btn.style.setProperty('--sm-best', `${Math.max(0, Math.min(100, best ?? 0))}%`);
btn.dataset.tried = best == null ? 'false' : 'true';
const label = held
? `Practise the letter ${letter}, already held correctly`
: best == null
? `Practise the letter ${letter}, not attempted yet`
: `Practise the letter ${letter}, best score ${best} of 100`;
btn.setAttribute('aria-label', label);
btn.title = label;
}
}
const progressEl = $('#sm-progress');
const progressBar = $('#sm-progress-bar');
function renderProgress() {
const done = ALL_COURSE_LETTERS.filter((l) => progress.passed[l]).length;
const pct = Math.round((done / ALL_COURSE_LETTERS.length) * 100);
if (progressEl) progressEl.textContent = `${done} of ${ALL_COURSE_LETTERS.length} letters held correctly`;
if (progressBar) {
progressBar.style.setProperty('--sm-fill', `${pct}%`);
progressBar.setAttribute('aria-valuenow', String(done));
}
}
// ── Controls ─────────────────────────────────────────────────────────────
cameraBtn?.addEventListener('click', () => (running ? stopCamera() : startCamera()));
replayBtn?.addEventListener('click', () => showOnAvatar(current));
$('#sm-reset')?.addEventListener('click', () => {
progress.passed = {};
progress.best = {};
writeJSON(PROGRESS_KEY, progress);
document.querySelectorAll('.sm-letter[data-passed]').forEach((el) => el.removeAttribute('data-passed'));
renderLetterBest();
renderProgress();
setStatus('Progress cleared. Every letter is back to unpractised.');
});
const handBtns = document.querySelectorAll('[data-hand]');
handBtns.forEach((btn) => {
btn.setAttribute('aria-pressed', String(btn.dataset.hand === dominant));
btn.addEventListener('click', () => {
dominant = btn.dataset.hand === 'Left' ? 'Left' : 'Right';
handBtns.forEach((b) => b.setAttribute('aria-pressed', String(b.dataset.hand === dominant)));
saveSignPrefs({ dominant });
drawTarget(current);
showOnAvatar(current);
});
});
document.addEventListener('keydown', (e) => {
if (e.metaKey || e.ctrlKey || e.altKey) return;
const tag = e.target?.tagName;
if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || e.target?.isContentEditable) return;
const key = e.key.toUpperCase();
if (LETTER_NOTES[key]) {
selectLetter(key);
e.preventDefault();
}
});
// ── Boot ─────────────────────────────────────────────────────────────────
setReplayable(false);
buildRail();
renderProgress();
await mountStage();
const wanted = new URLSearchParams(location.search).get('letter')?.toUpperCase();
const first = LETTER_NOTES[wanted] ? wanted : ALL_COURSE_LETTERS.find((l) => !progress.passed[l]) || ALL_COURSE_LETTERS[0];
// The stage crossfades into its idle after mounting; a letter played before
// that lands is overwritten by it, so wait for the idle to take hold.
for (let i = 0; i < 60 && stage?.anim && !stage.anim.currentName; i++) {
await new Promise((resolve) => setTimeout(resolve, 50));
}
selectLetter(first);
setStatus('');
window.addEventListener('pagehide', stopCamera);
document.addEventListener('visibilitychange', () => {
if (document.hidden && running) stopCamera();
});
}
if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot, { once: true });
else boot();