Skip to content

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.

fix(sign-mirror): report a refused camera next to the button that asked for it

nirholas4d88d6c70014
diff --git a/docs/sign-language.md b/docs/sign-language.md
index 9879aa2cd..18da8a1d1 100644
--- a/docs/sign-language.md
+++ b/docs/sign-language.md
@@ -35,6 +35,8 @@ Nothing here needs an account, a plugin, or a download. It is 3D in the browser.
The status line under the avatar tells you what it just did, for example `signed happy, meet, you · spelled to`, so you always know which words were real signs and which were spelled.
+The avatar is a multi-megabyte model, so it arrives a beat after the page. You do not have to wait for it: type and press **🤟 Sign it** while the silhouette is still breathing, and the phrase is queued and performed the moment the avatar lands. If the model fails to download, the stage says so and offers **Retry the avatar**; the [sign API](#the-sign-api) further down runs on the server and keeps working either way.
+
Three settings sit under the input, and all three are remembered on your next visit:
| Setting | Options | Why it exists |
@@ -456,6 +458,8 @@ npm run sign:sheet -- --dominant Left # left-handed signer
| What you see | Why | Fix |
|---|---|---|
+| A breathing silhouette where the avatar should be | The avatar GLB is still downloading | Nothing to do. Anything you type or click meanwhile is queued and signed the moment it lands |
+| "The 3D preview did not load" on the stage | The avatar GLB request failed, usually the network | Click **Retry the avatar**. The [sign API](#the-sign-api) runs server-side and works without the preview |
| "Load a rigged avatar to fingerspell" in the Studio | You are on the built-in mannequin, which has no skinned skeleton | Click **Load avatar**, or open `/pose?avatar=<id>` |
| The avatar refuses to sign, saying the rig cannot | The skeleton has no finger bones, so handshapes are impossible | Use a rig with fingers. Most generated and Mixamo-style avatars have them |
| It signs, but the face never changes | The rig carries no ARKit blendshapes | Switch the **Avatar** setting to Expressive face on /sign-language, or use an avatar exported with ARKit shapes |
diff --git a/pages/sign-mirror.html b/pages/sign-mirror.html
index 913b81cee..2e34fc85b 100644
--- a/pages/sign-mirror.html
+++ b/pages/sign-mirror.html
@@ -194,7 +194,17 @@
content: ''; position: absolute; inset: 0; width: var(--sm-hold, 0%);
background: rgba(255,255,255,.35); border-radius: inherit; transition: width var(--duration-instant) linear;
}
- #sm-hint { min-height: 42px; border: 1px dashed var(--stroke); border-radius: 12px; padding: 10px 13px; font-size: 14px; color: var(--ink-dim); line-height: 1.5; }
+ #sm-hint {
+ min-height: 42px; border: 1px dashed var(--stroke); border-radius: 12px;
+ padding: 10px 13px; font-size: 14px; color: var(--ink-dim); line-height: 1.5;
+ transition: border-color var(--duration-base) var(--ease-standard), color var(--duration-base) var(--ease-standard), background var(--duration-base) var(--ease-standard);
+ }
+ /* A camera that refused to start is not a coaching tip, and the sentence
+ alone does not say so: the box it lands in has to read as a problem. */
+ #sm-hint[data-tone='warn'] {
+ border-style: solid; border-color: var(--warn);
+ background: rgba(252, 211, 77, .09); color: var(--ink);
+ }
#sm-fingers { display: flex; flex-direction: column; gap: 6px; }
.sm-finger { display: grid; grid-template-columns: 64px 1fr; align-items: center; gap: 10px; }
.sm-finger-name { font-size: 12px; color: var(--ink-dim); font-family: var(--font-mono); text-transform: capitalize; }
diff --git a/src/sign-mirror-page.js b/src/sign-mirror-page.js
index 7ecf4a7b9..34a14e667 100644
--- a/src/sign-mirror-page.js
+++ b/src/sign-mirror-page.js
@@ -199,9 +199,32 @@ async function boot() {
// 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.
- const setHint = (text) => {
- if (hintEl && hintEl.textContent !== text) hintEl.textContent = text;
+ // 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) => {
@@ -396,7 +419,7 @@ async function boot() {
const startCamera = async () => {
if (running) return;
if (!navigator.mediaDevices?.getUserMedia) {
- setStatus(
+ 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.',
@@ -442,8 +465,7 @@ async function boot() {
// 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;
- stopCamera();
- setStatus(cameraFailureMessage(err, failedAt), 'warn');
+ reportCameraProblem(cameraFailureMessage(err, failedAt));
} finally {
cameraBtn.disabled = false;
cameraBtn.removeAttribute('aria-busy');
@@ -464,8 +486,7 @@ async function boot() {
// the page claiming the camera is on. Stop, and say why.
log.warn('[sign-mirror] tracker failed', err?.message);
landmarker = null;
- stopCamera();
- setStatus('The hand tracker stopped. Turn the camera on again to restart it.', 'warn');
+ reportCameraProblem('The hand tracker stopped. Turn the camera on again to restart it.');
return;
}
const hand = result?.landmarks?.[0];