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
#!/usr/bin/env node
/**
* Interactive-state ratchet (QB-07): every clickable thing must answer the pointer.
*
* B14 gave the platform a focus floor and a disabled floor in public/tokens.css,
* so a keyboard user now sees a ring on every control and a disabled control
* always reads as disabled. Hover is the state those floors cannot cover: what
* "hovered" looks like is component-specific (a card lifts, a button tints, a
* tab brightens its underline), and a blanket rule would stack on top of every
* component that already styles its own hover instead of filling the gap.
*
* So it is audited instead. A selector that declares `cursor: pointer` is
* telling the user "this is clickable"; if the same stylesheet never defines a
* :hover rule for it, that promise has no feedback behind it. The pointer
* changes shape and nothing else happens, which reads as a dead control.
*
* What counts as covered: any rule in the same file whose selector is this
* selector followed by :hover, or that contains it with a :hover on an ancestor
* (`.card:hover .thumb`). Selectors already carrying a state pseudo-class are
* not themselves audited, and neither is anything inside @media (hover: none),
* where a hover state is meaningless.
*
* The count may only go DOWN, same contract as the token-drift ratchet: the
* baseline lives in audit-interactive-states.baseline.json and a run that
* exceeds it fails and names the file plus the exact selectors that regressed.
*
* Usage:
* node scripts/audit-interactive-states.mjs # exit 1 if it increased
* node scripts/audit-interactive-states.mjs --list # print every gap
* node scripts/audit-interactive-states.mjs --update # rewrite the baseline
*/
import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
import { join, relative, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const BASELINE_PATH = join(ROOT, 'scripts', 'audit-interactive-states.baseline.json');
/** Every stylesheet we author, minus build output and vendored third-party CSS
* (public/scene-studio/libs holds CodeMirror; its hover model is not ours to
* change and editing it would be overwritten by the next version bump). */
const SKIP_DIRS = new Set(['node_modules', 'vendor', 'assets', 'libs', 'dist']);
function collectStylesheets(dir) {
const out = [];
for (const entry of readdirSync(dir)) {
const p = join(dir, entry);
if (statSync(p).isDirectory()) {
if (SKIP_DIRS.has(entry)) continue;
out.push(...collectStylesheets(p));
} else if (entry.endsWith('.css')) {
out.push(p);
}
}
return out;
}
/** Drop comments, and drop @media blocks where hover cannot happen. */
function normalize(css) {
const noComments = css.replace(/\/\*[\s\S]*?\*\//g, '');
// Remove `@media (hover: none) …{ … }` including its nested rules. Brace
// counting, because the block contains rules with their own braces.
let out = '';
let i = 0;
while (i < noComments.length) {
const at = noComments.indexOf('@media', i);
if (at === -1) {
out += noComments.slice(i);
break;
}
const open = noComments.indexOf('{', at);
if (open === -1) {
out += noComments.slice(i);
break;
}
const query = noComments.slice(at, open);
if (!/hover\s*:\s*none/.test(query)) {
out += noComments.slice(i, open + 1);
i = open + 1;
continue;
}
out += noComments.slice(i, at);
let depth = 1;
let j = open + 1;
while (j < noComments.length && depth > 0) {
if (noComments[j] === '{') depth++;
else if (noComments[j] === '}') depth--;
j++;
}
i = j;
}
return out;
}
const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
/** A rule that paints nothing: only the cursor plus inherited typography or
* appearance resets. Matched against the whole declaration block. */
const RESET_ONLY =
/^(?:\s*(?:cursor|font|font-family|font-size|appearance|-webkit-appearance|-moz-appearance|user-select|-webkit-user-select|touch-action)\s*:[^;]*;?\s*|\s*(?:color|background|background-color|border|outline|padding|margin)\s*:\s*(?:inherit|none|transparent|0|unset|initial)\s*;?\s*)+$/;
/** `position: absolute` pinned to all four edges: a stretched link overlay. */
const STRETCHED_LINK = /position:\s*absolute/;
/** Any declaration that actually paints something the pointer could see change. */
const PAINTS =
/(?:^|;)\s*(?:background(?:-color|-image)?|border(?:-color|-width|-style)?|color|box-shadow|opacity|filter|transform)\s*:/;
function gapsIn(css) {
const sheet = normalize(css);
const rules = [...sheet.matchAll(/([^{}]+)\{([^{}]*)\}/g)];
const gaps = new Set();
for (const [, selectorList, body] of rules) {
if (!/cursor:\s*pointer/.test(body)) continue;
// An invisible hit target (the transparent <input type=file> stretched
// over a drop zone, a bare click-catcher) has nothing to restyle; the
// visible element under it owns the feedback.
if (/opacity:\s*0\s*(;|$)/.test(body)) continue;
// A base reset (`button { font-family: inherit; cursor: pointer; }`)
// declares the cursor for every button on the page. It is not a
// component, and a hover rule at that selector would stack on top of
// every real component instead of filling a gap.
if (RESET_ONLY.test(body)) continue;
// A stretched link: `position: absolute; inset: 0` with nothing painted.
// It is a transparent hit layer over a card, and the card owns the
// feedback, exactly like the opacity:0 case above.
if (STRETCHED_LINK.test(body) && !PAINTS.test(body)) continue;
for (const selector of selectorList.split(',').map((s) => s.trim()).filter(Boolean)) {
if (!selector || selector.startsWith('@')) continue;
// A selector that already names a state is not the thing being audited.
if (/:hover|:focus|:active|:checked/.test(selector)) continue;
const escaped = escapeRe(selector);
// Three ways a hover rule can cover this selector:
// .x:hover is the direct rule
// .x .y:hover / .x:hover .y is a :hover elsewhere in the compound
// button.tag-pill:hover for .pills .tag-pill is the same element
// reached through a differently-spelled selector, so the LAST
// compound carrying a hover counts. Without this the audit files
// a finding against a control that visibly does respond.
const lastCompound = selector.split(/[\s>+~]+/).filter(Boolean).pop() || selector;
// `:hover` can sit on either side of the selector in a covering rule:
// `.x:hover .y` (ancestor) and `.x .y:hover` (self) both style it.
const inSameSelector = new RegExp(
`(?:${escaped}[^{},]*:hover|:hover[^{},]*${escaped})`,
);
// A pseudo-element is styled on hover as `base:hover::thumb`, so the
// :hover lands BETWEEN the base and the pseudo and neither pattern
// above sees it. Both vendor spellings of a range thumb hit this.
const pseudoAt = selector.indexOf('::');
const hoverBeforePseudo =
pseudoAt > 0 &&
new RegExp(
`${escapeRe(selector.slice(0, pseudoAt))}:hover${escapeRe(selector.slice(pseudoAt))}`,
).test(sheet);
// `.a b` is also covered by `.a:hover b`, where the :hover is spliced
// into the middle of the selector rather than at either end. Try
// every compound boundary.
const compounds = selector.split(/(\s+|\s*[>+~]\s*)/);
let hoverMidSelector = false;
for (let i = 0; i < compounds.length; i += 2) {
const spliced = compounds
.map((part, j) => (j === i ? `${part}:hover` : part))
.join('');
if (new RegExp(escapeRe(spliced)).test(sheet)) {
hoverMidSelector = true;
break;
}
}
const covered =
new RegExp(`${escaped}:hover`).test(sheet) ||
inSameSelector.test(sheet) ||
hoverBeforePseudo ||
hoverMidSelector ||
(lastCompound !== selector &&
// Only when the compound is specific enough to name one
// component. A bare `button` or `summary` tail would match
// any `button:hover` in the file and hide every real gap.
/[.#[]/.test(lastCompound) &&
new RegExp(`${escapeRe(lastCompound)}(?=[^{},]*:hover)`).test(sheet));
if (covered) continue;
gaps.add(selector);
}
}
return [...gaps];
}
function audit() {
const perFile = {};
let total = 0;
for (const sheet of [
...collectStylesheets(join(ROOT, 'src')),
...collectStylesheets(join(ROOT, 'public')),
]) {
const gaps = gapsIn(readFileSync(sheet, 'utf8'));
if (gaps.length) {
perFile[relative(ROOT, sheet)] = gaps.sort();
total += gaps.length;
}
}
return { total, perFile };
}
const { total, perFile } = audit();
if (process.argv.includes('--list')) {
for (const [file, gaps] of Object.entries(perFile).sort((a, b) => b[1].length - a[1].length)) {
console.log(`${file} (${gaps.length})`);
for (const g of gaps) console.log(` ${g}`);
}
console.log(`\n${total} clickable selector(s) with no hover rule.`);
process.exit(0);
}
if (process.argv.includes('--update')) {
const counts = Object.fromEntries(
Object.entries(perFile).map(([file, gaps]) => [file, gaps.length]),
);
writeFileSync(BASELINE_PATH, JSON.stringify({ total, perFile: counts }, null, '\t') + '\n');
console.log(`✓ interactive-state baseline updated: ${total} clickable selector(s) with no hover rule.`);
process.exit(0);
}
let baseline;
try {
baseline = JSON.parse(readFileSync(BASELINE_PATH, 'utf8'));
} catch {
console.error('✗ missing baseline (run: node scripts/audit-interactive-states.mjs --update)');
process.exit(1);
}
if (total > baseline.total) {
console.error(
`\n✗ interactive-state gaps increased: ${total} clickable selector(s) with no hover rule (baseline ${baseline.total}).\n`,
);
for (const [file, gaps] of Object.entries(perFile)) {
const was = baseline.perFile[file] || 0;
if (gaps.length > was) {
console.error(` ${file}: ${gaps.length} (was ${was})`);
for (const g of gaps) console.error(` ${g}`);
}
}
console.error(
'\nA selector that sets cursor: pointer promises the element is clickable.\n' +
'Give it a :hover rule built from tokens, e.g.\n' +
' .thing:hover { background: var(--surface-3); border-color: var(--stroke-strong); }\n' +
'Focus and disabled are already covered platform-wide by the floors in\n' +
'public/tokens.css (see DESIGN-TOKENS.md); hover is the one you must author.\n',
);
process.exit(1);
}
if (total < baseline.total) {
console.log(
`✓ interactive-state gaps: ${total} (baseline ${baseline.total}), improved. Lock it in with:\n` +
' node scripts/audit-interactive-states.mjs --update',
);
} else {
console.log(`✓ interactive-state gaps unchanged: ${total} clickable selector(s) with no hover rule.`);
}