Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Physical-conformance audit gate for an already-validated Three.js scene spec.
*
* Checks static assemblies and animated clips across key poses for:
* 1. `floating-part`: Parts touching no parent, sibling, joint, attachment, or ground surface.
* 2. `buried-geometry`: Parts swallowed completely or heavily inside another part without hierarchy/attachment exemption.
* 3. `coplanar-surface`: Sibling or unrelated part pairs sharing a near-coplanar surface (z-fighting).
* 4. `unprovenanced-transition`: Animated parts that pop into existence in open space without emerging from a parent or ground level.
* 5. `nonuniform-parent-scale`: A non-relief child inherits a parent's anisotropic scale and may be distorted.
* 6. `unanchored-attachment`: A part declared as carried that names nothing it is carried by.
* 7. `attachment-far-from-anchor`: A declared attachment measured away from the anchor the spec says it hangs from.
* 8. `bilateral-mirror-scale`: One half of a named left/right pair mirrored by negating a scale component.
* 9. `bilateral-pair-same-side`: A named left/right pair that never crosses the lateral plane.
* 10. `bilateral-chirality`: A named left/right pair mirrored by a 180-degree yaw instead of a lateral reflection.
* 11. `straight-swept-path`: A part declared as a curved form built from a sweep that never bends.
*
* Checks 6 and 7 exist because `floating-part` and `buried-geometry` both miss
* the same defect: a hat that belongs behind the shoulders but is authored at
* hip height touches its neighbours, so nothing calls it floating, and it is not
* contained by anything, so nothing calls it buried. Only the declared
* relationship to its anchor makes the position wrong — which is why an
* attachment whose anchor geometry cannot be measured is reported as unmeasured
* rather than allowed to read as clean.
* Checks 8-10 exist because every bounds-based check above is blind to
* handedness: a hand spun around the vertical axis, or scaled by -1 in X,
* occupies exactly the same box as a correctly reflected one. Only the
* transform that placed it says which way round the limb is built.
* Check 11 covers the same blind spot in one more dimension: a horn swept along
* a straight run of control points has a perfectly reasonable bounding box,
* penetrates nothing, and touches its parent, so every check above passes it.
* Only the shape of the swept path itself says it never curves.
*/
import {
CURVED_OUTLINE_MIN_CONCAVE_TURN_DEGREES,
SWEPT_ARC_MIN_SPAN_DEGREES,
collectDeclaredCurvedParts,
evaluateSweptGeometryCurvature,
isThreejsAttachmentAnchored,
listSpecNames,
resolveThreejsAttachments,
} from './threejsModel.js';
import { evaluateThreejsModelClipPose } from './threejsModelClipPose.js';
import {
applyTransform,
composeTransform,
IDENTITY_TRANSFORM,
multiplyLinear,
} from './threejsTransform.js';
const EPSILON = 1e-4;
const COPLANAR_TOLERANCE = 1e-3;
const TOUCH_TOLERANCE = 0.02;
// Clip poses measured per audit, shared by every clip. Boundaries alone miss
// motion that leaves and comes back inside one window — an arm turned through
// 360° is back at rest at both ends — so each sequence also contributes interior
// samples. The budget is dealt round-robin across clips, so a sequence-heavy
// first clip cannot starve a later one, and every sample that does not fit is
// reported rather than dropped. 48 keeps the walk bounded (12 clips is the
// schema maximum, four poses each) while covering a typical model completely.
const MAX_CLIP_AUDIT_POSES = 48;
// A rotating sequence gets one interior sample per this many degrees of turn,
// up to MAX_INTERIOR_SEGMENTS segments; every sequence gets at least its midpoint.
const MAX_ROTATION_STEP_DEGREES = 90;
const MAX_INTERIOR_SEGMENTS = 8;
// Omitted times are listed for the reader up to this many per clip; the count
// is always exact.
const MAX_LISTED_OMITTED_TIMES = 24;
// One percent anisotropy is small enough to ignore authoring noise while still
// catching the intentional shape-squashing that distorts a child hierarchy.
const NONUNIFORM_SCALE_TOLERANCE = 0.01;
const ANISOTROPY_COMPARISON_TOLERANCE = 0.01;
// A mirrored limb is REFLECTED across the lateral plane (x = 0). Two other
// transforms land the part in roughly the right place while inverting its
// handedness: a 180-degree yaw about the vertical axis, and a negated scale
// component. Both are what turn a right hand into a left hand with the thumb
// pointing backward, so both are named explicitly rather than measured as a
// generic bounds defect — the bounding boxes are identical either way.
const LATERAL_REFLECTION = [-1, 0, 0, 0, 1, 0, 0, 0, 1];
const VERTICAL_YAW_180 = [-1, 0, 0, 0, 1, 0, 0, 0, -1];
const CHIRALITY_LINEAR_TOLERANCE = 1e-3;
const CHIRALITY_POSITION_TOLERANCE = 1e-3;
// A reflected pair is compared with a tolerance that grows with how far the
// pair sits from the lateral plane, so a limb two units out is not reported for
// authoring noise that a limb near the centreline would never produce.
const CHIRALITY_POSITION_RELATIVE_TOLERANCE = 0.02;
function getLocalBounds(geometry) {
if (!geometry) return null;
switch (geometry.type) {
case 'box': {
const [x, y, z] = [geometry.width / 2, geometry.height / 2, geometry.depth / 2];
return [[-x, -y, -z], [x, y, z]];
}
case 'sphere': {
const r = geometry.radius;
return [[-r, -r, -r], [r, r, r]];
}
case 'cylinder':
case 'cone': {
const top = geometry.type === 'cone' ? 0 : (geometry.radiusTop ?? geometry.radius);
const bottom = geometry.type === 'cone' ? geometry.radius : (geometry.radiusBottom ?? geometry.radius);
const half = geometry.height / 2;
const widest = Math.max(top, bottom);
return [[-widest, -half, -widest], [widest, half, widest]];
}
case 'capsule': {
const r = geometry.radius;
const half = geometry.length / 2;
return [[-r, -(half + r), -r], [r, half + r, r]];
}
case 'torus': {
const outer = geometry.radius + geometry.tube;
return [[-outer, -outer, -geometry.tube], [outer, outer, geometry.tube]];
}
case 'lathe': {
const points = geometry.points || [];
let maxR = 0;
let minY = Infinity;
let maxY = -Infinity;
for (const [x, y] of points) {
maxR = Math.max(maxR, Math.abs(x));
minY = Math.min(minY, y);
maxY = Math.max(maxY, y);
}
if (!Number.isFinite(minY)) { minY = -1; maxY = 1; maxR = 1; }
return [[-maxR, minY, -maxR], [maxR, maxY, maxR]];
}
case 'extrude': {
const outline = geometry.outline || [];
let minX = Infinity;
let maxX = -Infinity;
let minY = Infinity;
let maxY = -Infinity;
for (const [x, y] of outline) {
minX = Math.min(minX, x);
maxX = Math.max(maxX, x);
minY = Math.min(minY, y);
maxY = Math.max(maxY, y);
}
if (!Number.isFinite(minX)) { minX = 0; maxX = 1; minY = 0; maxY = 1; }
return [[minX, minY, 0], [maxX, maxY, geometry.depth || 1]];
}
case 'tube': {
const path = geometry.path || [];
const r = geometry.radius || 0.1;
let minX = Infinity; let maxX = -Infinity;
let minY = Infinity; let maxY = -Infinity;
let minZ = Infinity; let maxZ = -Infinity;
for (const [x, y, z] of path) {
minX = Math.min(minX, x); maxX = Math.max(maxX, x);
minY = Math.min(minY, y); maxY = Math.max(maxY, y);
minZ = Math.min(minZ, z); maxZ = Math.max(maxZ, z);
}
if (!Number.isFinite(minX)) { minX = 0; maxX = 1; minY = 0; maxY = 1; minZ = 0; maxZ = 1; }
return [[minX - r, minY - r, minZ - r], [maxX + r, maxY + r, maxZ + r]];
}
case 'custom': {
const vertices = geometry.vertices || [];
let minX = Infinity; let maxX = -Infinity;
let minY = Infinity; let maxY = -Infinity;
let minZ = Infinity; let maxZ = -Infinity;
for (let i = 0; i < vertices.length; i += 3) {
const x = vertices[i]; const y = vertices[i + 1]; const z = vertices[i + 2];
minX = Math.min(minX, x); maxX = Math.max(maxX, x);
minY = Math.min(minY, y); maxY = Math.max(maxY, y);
minZ = Math.min(minZ, z); maxZ = Math.max(maxZ, z);
}
if (!Number.isFinite(minX)) { minX = -1; maxX = 1; minY = -1; maxY = 1; minZ = -1; maxZ = 1; }
return [[minX, minY, minZ], [maxX, maxY, maxZ]];
}
default:
return null;
}
}
function getWorldAABB(localBounds, transform) {
const [[minX, minY, minZ], [maxX, maxY, maxZ]] = localBounds;
const corners = [
[minX, minY, minZ], [minX, minY, maxZ], [minX, maxY, minZ], [minX, maxY, maxZ],
[maxX, minY, minZ], [maxX, minY, maxZ], [maxX, maxY, minZ], [maxX, maxY, maxZ],
].map((p) => applyTransform(transform, p));
return [0, 1, 2].map((axis) => [
Math.min(...corners.map((c) => c[axis])),
Math.max(...corners.map((c) => c[axis])),
]);
}
function aabbDistance(a, b) {
const dx = Math.max(0, a[0][0] - b[0][1], b[0][0] - a[0][1]);
const dy = Math.max(0, a[1][0] - b[1][1], b[1][0] - a[1][1]);
const dz = Math.max(0, a[2][0] - b[2][1], b[2][0] - a[2][1]);
return Math.hypot(dx, dy, dz);
}
function aabbContains(container, subject, tolerance = EPSILON) {
return [0, 1, 2].every((axis) => (
subject[axis][0] >= container[axis][0] - tolerance
&& subject[axis][1] <= container[axis][1] + tolerance
));
}
function faceAreaOverlap2D(minA1, maxA1, minA2, maxA2, minB1, maxB1, minB2, maxB2) {
const overlap1 = Math.max(0, Math.min(maxA1, maxB1) - Math.max(minA1, minB1));
const overlap2 = Math.max(0, Math.min(maxA2, maxB2) - Math.max(minA2, minB2));
return overlap1 * overlap2;
}
const isTransparent = (material) => Boolean(material)
&& ((material.transparent === true && (material.opacity ?? 1) < 1) || (material.transmission ?? 0) > 0);
// The clip pose is the one the preview and the exported player show
// (`threejsModelClipPose.js`); a part no sequence drives keeps its authored pose.
function getPoseStateResolver(clip, timeSeconds) {
const pose = evaluateThreejsModelClipPose(clip, timeSeconds);
return (part) => {
const driven = pose[part.id] || {};
return {
position: driven.position ?? part.position ?? [0, 0, 0],
rotationDegrees: driven.rotationDegrees ?? part.rotationDegrees ?? [0, 0, 0],
scale: driven.scale ?? part.scale ?? [1, 1, 1],
visible: driven.visible ?? (part.visible !== false),
opacity: driven.opacity ?? part.opacity ?? 1,
};
};
}
const roundTime = (value) => Number(value.toFixed(4));
const formatTimes = (times) => times.map((time) => `${time}s`).join(', ');
const sequenceSegments = (sequence) => {
const range = sequence.channels?.rotationDegrees;
const turn = range && Array.isArray(range.from) && Array.isArray(range.to)
? Math.max(...range.from.map((value, axis) => Math.abs((range.to[axis] ?? value) - value)))
: 0;
return Math.min(MAX_INTERIOR_SEGMENTS, Math.max(2, Math.ceil(turn / MAX_ROTATION_STEP_DEGREES)));
};
/**
* Every pose time worth measuring in one clip, highest priority first: the clip
* boundaries, then each sequence's midpoint, then sequence boundaries, then the
* extra subdivisions of large rotations. Priority only matters when the budget
* runs out, and then it decides which poses are reported as omitted.
*/
const planClipSampleTimes = (clip) => {
const sequences = (Array.isArray(clip.sequences) ? clip.sequences : [])
.filter((sequence) => Number.isFinite(sequence.startSeconds) && Number.isFinite(sequence.endSeconds))
.sort((a, b) => (a.startSeconds - b.startSeconds) || (a.endSeconds - b.endSeconds));
const tiers = [
[0, Number.isFinite(clip.durationSeconds) ? clip.durationSeconds : 0],
sequences.map((sequence) => (sequence.startSeconds + sequence.endSeconds) / 2),
sequences.flatMap((sequence) => [sequence.startSeconds, sequence.endSeconds]),
sequences.flatMap((sequence) => {
const segments = sequenceSegments(sequence);
const span = sequence.endSeconds - sequence.startSeconds;
return Array.from({ length: segments - 1 }, (_, index) => sequence.startSeconds + ((span * (index + 1)) / segments));
}),
];
const ordered = [];
const seen = new Set();
for (const time of tiers.flat()) {
const rounded = roundTime(time);
if (seen.has(rounded)) continue;
seen.add(rounded);
ordered.push(rounded);
}
return ordered;
};
// Round-robin, in clip declaration order: deterministic, and no clip gets a
// second pose until every clip with candidates left has had another one.
const allocateClipPoseBudget = (candidateLists, budget) => {
const quotas = candidateLists.map(() => 0);
let remaining = budget;
let progressed = true;
while (remaining > 0 && progressed) {
progressed = false;
candidateLists.forEach((candidates, index) => {
if (remaining <= 0 || quotas[index] >= candidates.length) return;
quotas[index] += 1;
remaining -= 1;
progressed = true;
});
}
return quotas;
};
function collectPoseVolumes(spec, getPartState) {
const volumes = [];
// Every part, not only the ones that carry geometry: a socket hangs off its
// parent part's world transform, and that parent is routinely a bare group.
const transformsByPartId = new Map();
// A hidden parent hides its whole subtree in Three.js, so visibility is
// inherited down the walk; opacity lives on each part's own material and is not.
const walk = (part, parentTransform, ancestorIds, parentVisible) => {
const state = getPartState ? getPartState(part) : {
position: part.position,
rotationDegrees: part.rotationDegrees,
scale: part.scale,
visible: part.visible !== false,
opacity: part.opacity ?? 1,
};
const transform = composeTransform(parentTransform, state);
transformsByPartId.set(part.id, transform);
const visible = parentVisible && state.visible !== false;
const localBounds = getLocalBounds(part.geometry);
if (localBounds) {
const worldBounds = getWorldAABB(localBounds, transform);
volumes.push({
id: part.id,
name: part.name || part.id,
geometry: part.geometry,
materialId: part.material || null,
explodeWithParent: part.explodeWithParent === true,
ancestorIds,
visible,
opacity: state.opacity,
worldBounds,
});
}
for (const child of part.children || []) {
walk(child, transform, [...ancestorIds, part.id], visible);
}
};
for (const part of spec?.parts || []) {
walk(part, IDENTITY_TRANSFORM, [], true);
}
return { volumes, transformsByPartId };
}
const flattenParts = (parts) => {
const flattened = [];
const walk = (list) => {
for (const part of list || []) {
flattened.push(part);
walk(part.children);
}
};
walk(parts);
return flattened;
};
const normalizeScale = (scale) => (
Array.isArray(scale) && scale.length === 3 && scale.every((value) => Number.isFinite(value))
? scale
: [1, 1, 1]
);
const getScaleAnisotropy = (scale) => {
const normalized = normalizeScale(scale);
const absolute = normalized.map((value) => Math.abs(value));
const minimum = Math.min(...absolute);
const maximum = Math.max(...absolute);
const ratio = maximum / Math.max(minimum, EPSILON);
if (ratio <= 1 + NONUNIFORM_SCALE_TOLERANCE) return null;
return { scale: normalized, ratio };
};
const formatScale = (scale) => `[${scale.map((value) => Number(value.toFixed(4))).join(', ')}]`;
const formatNames = (names) => listSpecNames(names.map((name) => `"${name}"`));
const collectNonReliefDescendants = (part) => {
const descendants = [];
const walk = (children) => {
for (const child of children || []) {
if (child.explodeWithParent === true) continue;
if (child.geometry) {
descendants.push({ id: child.id, name: child.name || child.id });
}
walk(child.children);
}
};
walk(part.children);
return descendants;
};
const buildNonuniformParentScaleFinding = (part, scaleSamples, context = {}) => {
const descendants = collectNonReliefDescendants(part);
if (descendants.length === 0) return null;
const normalizedSamples = scaleSamples.map((sample) => ({
...sample,
anisotropy: getScaleAnisotropy(sample.scale),
}));
const analyzedSamples = normalizedSamples
.filter((sample) => sample.anisotropy);
if (analyzedSamples.length === 0) return null;
const mostAnisotropic = analyzedSamples.reduce((best, sample) => (
sample.anisotropy.ratio > best.anisotropy.ratio ? sample : best
));
const sequenceIds = [...new Set(analyzedSamples.map((sample) => sample.sequenceId).filter(Boolean))];
const { clipName, ...metadata } = context;
const descendantNames = descendants.map((descendant) => descendant.name);
const scope = clipName
? `In clip "${clipName}", part "${part.name || part.id}" reaches authored non-uniform scale ${formatScale(mostAnisotropic.anisotropy.scale)}`
: `Part "${part.name || part.id}" is authored with non-uniform scale ${formatScale(mostAnisotropic.anisotropy.scale)}`;
const sequenceSuffix = sequenceIds.length > 0 ? ` in scale sequence${sequenceIds.length === 1 ? '' : 's'} ${formatNames(sequenceIds)}` : '';
return {
code: 'nonuniform-parent-scale',
severity: 'warning',
...metadata,
sequenceId: mostAnisotropic.sequenceId ?? metadata.sequenceId,
sequenceIds,
partIds: [part.id, ...descendants.map((descendant) => descendant.id)],
affectedDescendantNames: descendantNames,
anisotropyRatio: mostAnisotropic.anisotropy.ratio,
message: `${scope} (maximum anisotropy ratio ${mostAnisotropic.anisotropy.ratio.toFixed(2)})${sequenceSuffix}, which cascades onto non-relief descendants ${formatNames(descendantNames)} and can distort them.`,
};
};
const unionBounds = (a, b) => {
if (!a) return b;
if (!b) return a;
return [0, 1, 2].map((axis) => [Math.min(a[axis][0], b[axis][0]), Math.max(a[axis][1], b[axis][1])]);
};
const isInSubtree = (volume, partId) => volume.id === partId || volume.ancestorIds.includes(partId);
/**
* World bounds for one part INCLUDING its descendants, optionally minus one
* nested subtree.
*
* An anchor is routinely a bare group whose surface is entirely in its children
* — "head" holding a skull and a jaw — so measuring only the part's own geometry
* would report a hat as unmeasurable against the head it plainly sits on. But an
* attachment is usually parented UNDER its anchor, and folding the attachment's
* own geometry into the anchor's bounds would make every nested attachment
* measure zero units away from itself: the check would pass a hat at hip height
* precisely because it is a child of the head. Hence the exclusion.
*/
const subtreeBounds = (volumes, partId, excludePartId = null) => {
let bounds = null;
for (const volume of volumes) {
if (!isInSubtree(volume, partId)) continue;
if (excludePartId && isInSubtree(volume, excludePartId)) continue;
bounds = unionBounds(bounds, volume.worldBounds);
}
return bounds;
};
// A socket is a point, and `aabbDistance` already measures box-to-box, so the
// point rides in as a degenerate box rather than earning a second routine.
const pointBounds = ([x, y, z]) => [[x, x], [y, y], [z, z]];
const formatOffset = (value) => Number(value.toFixed(3));
/**
* Measure every anchored attachment against the thing it says it hangs from, in
* one pose.
*
* @returns {{findings: Array, unmeasured: Array<{partId: string, anchorPartId: string|null,
* anchorSocket: string|null, reason: string}>, measured: Set<string>}}
*/
function measureAttachmentAnchors({
attachments,
volumes,
transformsByPartId,
socketsByName,
namesByPartId,
context = {},
}) {
const findings = [];
const unmeasured = [];
// Which attachments this pose could actually put a number on, so a pose that
// could not see an anchor never overrides a pose that could.
const measured = new Set();
if (attachments.length === 0) return { findings, unmeasured, measured };
const measurable = volumes.filter((volume) => volume.visible && volume.opacity > 0);
const label = (partId) => `"${namesByPartId.get(partId) || partId}"`;
const { clipName, ...metadata } = context;
for (const attachment of attachments) {
const attachmentBounds = subtreeBounds(measurable, attachment.partId);
if (!attachmentBounds) {
unmeasured.push({
partId: attachment.partId,
anchorPartId: attachment.anchorPartId,
anchorSocket: attachment.anchorSocket,
reason: 'the attachment has no visible geometry to measure',
});
continue;
}
let anchorBounds = null;
let anchorDescription = '';
if (attachment.anchorSocket) {
const socket = socketsByName.get(attachment.anchorSocket);
const transform = socket ? transformsByPartId.get(socket.parentPartId) : null;
if (transform) {
anchorBounds = pointBounds(applyTransform(transform, socket.position || [0, 0, 0]));
anchorDescription = `socket "${attachment.anchorSocket}" on ${label(socket.parentPartId)}`;
}
} else if (attachment.anchorPartId) {
anchorBounds = subtreeBounds(measurable, attachment.anchorPartId, attachment.partId);
anchorDescription = label(attachment.anchorPartId);
}
if (!anchorBounds) {
unmeasured.push({
partId: attachment.partId,
anchorPartId: attachment.anchorPartId,
anchorSocket: attachment.anchorSocket,
reason: attachment.anchorSocket
? 'the anchor socket could not be located in this pose'
: 'the anchor part has no visible geometry to measure',
});
continue;
}
measured.add(attachment.partId);
const distance = aabbDistance(attachmentBounds, anchorBounds);
if (distance <= attachment.maxOffset) continue;
const scope = clipName
? `In clip "${clipName}" at ${formatOffset(metadata.timeSeconds ?? 0)}s, part ${label(attachment.partId)}`
: `Part ${label(attachment.partId)}`;
findings.push({
code: 'attachment-far-from-anchor',
// The spec asserted this relationship itself, so a part measured away from
// its own declared anchor is a stated fact the model does not build.
severity: 'error',
...metadata,
partIds: attachment.anchorPartId
? [attachment.partId, attachment.anchorPartId]
: [attachment.partId],
anchorPartId: attachment.anchorPartId,
anchorSocket: attachment.anchorSocket,
distance: formatOffset(distance),
maxOffset: attachment.maxOffset,
message: `${scope} is declared as an attachment carried by ${anchorDescription}, but it sits ${formatOffset(distance)} units away from it (allowed ${attachment.maxOffset}). Move it onto ${anchorDescription} or re-anchor it to the part it is actually carried by.`,
});
}
return { findings, unmeasured, measured };
}
const collectAnimatedScaleSamples = (part, sequences) => sequences
.filter((sequence) => sequence.partId === part.id && sequence.channels?.scale)
.flatMap((sequence) => [
{ scale: sequence.channels.scale.from, sequenceId: sequence.id },
{ scale: sequence.channels.scale.to, sequenceId: sequence.id },
]);
// Side tokens are matched as whole identifier tokens, never as substrings: a
// substring match pairs "relay" with "lay" and reads the "l" out of "lamp".
const BILATERAL_SIDE_TOKENS = new Map([
['left', 'left'],
['l', 'left'],
['right', 'right'],
['r', 'right'],
]);
// Both camel boundaries, not just the common one: "handL" needs lower-upper,
// and "LHand" needs upper-upper-lower or the whole name reads as one token and
// the pair is never found.
const tokenizeIdentifier = (value) => String(value ?? '')
.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
.split(/[^A-Za-z0-9]+/)
.filter(Boolean)
.map((token) => token.toLowerCase());
/**
* The pairing key for one identifier: its remaining tokens, sorted, so
* "leftHand", "hand_L", "LHand" and "Hand Left" all key to the same pair.
*
* Order is discarded deliberately. A generated spec routinely mixes conventions
* between the two halves of one pair — "leftFoot" beside "foot_R" — and an
* ordered key would leave exactly those pairs unchecked. Every other token still
* has to match as a multiset, so the pairing stays as tight as the names.
*
* Returns null when there is no side token, when there are several (a name that
* says both sides names neither), or when the side token is the whole
* identifier — a part simply called "left" has no counterpart to be paired with.
*/
const describeBilateralSide = (identifier) => {
const tokens = tokenizeIdentifier(identifier);
if (tokens.length < 2) return null;
const sideIndexes = tokens.reduce((found, token, index) => (
BILATERAL_SIDE_TOKENS.has(token) ? [...found, index] : found
), []);
if (sideIndexes.length !== 1) return null;
const [sideIndex] = sideIndexes;
return {
key: tokens.filter((_, index) => index !== sideIndex).sort().join('|'),
side: BILATERAL_SIDE_TOKENS.get(tokens[sideIndex]),
};
};
/**
* Group parts into left/right pairs by name (falling back to id).
*
* Only an unambiguous one-to-one grouping is returned. Three parts sharing a
* key — a spec with two "wing-l" variants — cannot say which counterpart each
* one is meant to mirror, and guessing would report chirality against the wrong
* limb.
*/
const collectBilateralPairs = (parts) => {
const groups = new Map();
for (const part of parts) {
const descriptor = describeBilateralSide(part.name || part.id)
|| (part.name ? describeBilateralSide(part.id) : null);
if (!descriptor) continue;
const group = groups.get(descriptor.key) || { left: [], right: [] };
group[descriptor.side].push(part);
groups.set(descriptor.key, group);
}
return [...groups.values()]
.filter((group) => group.left.length === 1 && group.right.length === 1)
.map((group) => ({ left: group.left[0], right: group.right[0] }));
};
const collectPartChains = (parts) => {
const chains = new Map();
const walk = (list, ancestors) => {
for (const part of list || []) {
const chain = [...ancestors, part];
chains.set(part.id, chain);
walk(part.children, chain);
}
};
walk(parts, []);
return chains;
};
/**
* Both halves of a pair placed in the frame of their nearest common ancestor.
*
* The lateral plane a pair is mirrored across is the one their shared parent
* defines, NOT world x = 0. A subject modelled off the origin, or a body yawed
* to face somewhere other than down +Z, is mirror-symmetric about its own axis
* and about no world plane at all — comparing it against x = 0 reports every
* correctly built pair on it. Composing down from the common ancestor cancels
* that shared placement, and leaves exactly the authored local transforms the
* refinement feedback asks the next pass to change.
*/
const transformsRelativeToCommonAncestor = (leftChain, rightChain) => {
let shared = 0;
while (shared < leftChain.length - 1
&& shared < rightChain.length - 1
&& leftChain[shared] === rightChain[shared]) {
shared += 1;
}
const compose = (chain) => chain.slice(shared).reduce(
(transform, part) => composeTransform(transform, part),
IDENTITY_TRANSFORM,
);
return [compose(leftChain), compose(rightChain)];
};
const determinant3 = (m) => (
(m[0] * ((m[4] * m[8]) - (m[5] * m[7])))
- (m[1] * ((m[3] * m[8]) - (m[5] * m[6])))
+ (m[2] * ((m[3] * m[7]) - (m[4] * m[6])))
);
const linearClose = (a, b) => a.every((value, index) => Math.abs(value - b[index]) <= CHIRALITY_LINEAR_TOLERANCE);
const vectorClose = (a, b, tolerance) => a.every((value, index) => Math.abs(value - b[index]) <= tolerance);
const formatVector = (vector) => `[${vector.map(formatOffset).join(', ')}]`;
// Every primitive in this set maps onto itself under a 180-degree yaw, so a lone
// one of them is built identically whether it was reflected or turned around.
// Reporting those would bury the real defects under every blocky limb in the
// catalogue. `extrude`, `tube` and `custom` carry an authored profile that a yaw
// visibly turns around, and any assembly of more than one volume shows the flip
// in where its pieces land.
const YAW_SYMMETRIC_GEOMETRY_TYPES = new Set(['box', 'sphere', 'cylinder', 'cone', 'capsule', 'torus', 'lathe']);
const isYawDistinguishable = (volumes, partId) => {
const subtree = volumes.filter((volume) => isInSubtree(volume, partId));
if (subtree.length !== 1) return subtree.length > 1;
return !YAW_SYMMETRIC_GEOMETRY_TYPES.has(subtree[0].geometry?.type);
};
/**
* Chirality and symmetry findings for the resting pose.
*
* Only the resting pose is audited: which way round a limb is built is authored
* into the assembly, and a clip that rotates an arm is not a chirality defect.
*
* A flipped ORIENTATION is what every finding here turns on. A counterpart
* merely placed at a different depth is a staggered pose — a figure mid-stride
* has one hand forward and one back — and reporting that as chirality would ask
* the next pass to flatten every pose it was asked for. The depth is reported
* only as corroboration, once the orientation already says the limb is turned
* around.
*
* @returns {Array} findings, at most one per pair
*/
function buildBilateralChiralityFindings({ pairs, chains, volumes }) {
const findings = [];
for (const { left, right } of pairs) {
const leftChain = chains.get(left.id);
const rightChain = chains.get(right.id);
if (!leftChain || !rightChain) continue;
const [leftTransform, rightTransform] = transformsRelativeToCommonAncestor(leftChain, rightChain);
const leftName = left.name || left.id;
const rightName = right.name || right.id;
const partIds = [left.id, right.id];
const leftPosition = leftTransform.translation;
const rightPosition = rightTransform.translation;
// A negated scale component is the one mirror that leaves the bounds
// untouched and every normal inside out, so it is reported before the
// orientation comparison — which has no meaning across a handedness flip.
const leftDeterminant = determinant3(leftTransform.linear);
const rightDeterminant = determinant3(rightTransform.linear);
if ((leftDeterminant < 0) !== (rightDeterminant < 0)) {
const flipped = leftDeterminant < 0 ? leftName : rightName;
const intact = leftDeterminant < 0 ? rightName : leftName;
findings.push({
code: 'bilateral-mirror-scale',
severity: 'warning',
partIds,
message: `Bilateral pair "${leftName}" / "${rightName}" is mirrored by negating a scale component on "${flipped}", which inverts its handedness and face winding relative to "${intact}". Build the pair with positive scale on both sides and reflect the counterpart across the lateral plane instead: position [-x, y, z] with rotation [rx, -ry, -rz].`,
});
continue;
}
// A pair that never crosses its parent's lateral plane was not mirrored at
// all — one limb was copied to the other side's name and left where it was.
const sameSide = Math.sign(leftPosition[0]) === Math.sign(rightPosition[0])
&& Math.min(Math.abs(leftPosition[0]), Math.abs(rightPosition[0])) > TOUCH_TOLERANCE;
if (sameSide) {
findings.push({
code: 'bilateral-pair-same-side',
severity: 'warning',
partIds,
message: `Bilateral pair "${leftName}" / "${rightName}" sits entirely on one side of the lateral plane (both offset from their common parent at x = ${formatOffset(leftPosition[0])} and x = ${formatOffset(rightPosition[0])}), so the pair never straddles the body. Negate the x offset of one of them so each limb sits on its own side.`,
});
continue;
}
const reflectedLinear = multiplyLinear(multiplyLinear(LATERAL_REFLECTION, leftTransform.linear), LATERAL_REFLECTION);
if (linearClose(rightTransform.linear, reflectedLinear)) continue;
// Nothing is reported for a pair that is merely posed differently: an arm
// raised on one side is legitimate, and only a positively identified yaw is
// a chirality defect. Both compositions are tested because the yaw is
// authored either way — as a 180-degree turn of the placed limb (world side)
// or as a [0, 180, 0] local rotation on the part itself (local side).
const orientationYawed = isYawDistinguishable(volumes, right.id) && (
linearClose(rightTransform.linear, multiplyLinear(VERTICAL_YAW_180, leftTransform.linear))
|| linearClose(rightTransform.linear, multiplyLinear(leftTransform.linear, VERTICAL_YAW_180))
);
if (!orientationYawed) continue;
const positionTolerance = Math.max(
CHIRALITY_POSITION_TOLERANCE,
CHIRALITY_POSITION_RELATIVE_TOLERANCE * Math.hypot(...leftPosition),
);
const reflectedPosition = [-leftPosition[0], leftPosition[1], leftPosition[2]];
const yawedPosition = [-leftPosition[0], leftPosition[1], -leftPosition[2]];
const placementYawed = !vectorClose(rightPosition, reflectedPosition, positionTolerance)
&& Math.abs(leftPosition[2]) > positionTolerance
&& vectorClose(rightPosition, yawedPosition, positionTolerance);
findings.push({
code: 'bilateral-chirality',
severity: 'warning',
partIds,
message: `Bilateral pair "${leftName}" / "${rightName}" is mirrored by a 180° yaw about the vertical axis rather than a reflection across the lateral plane: "${rightName}" carries the orientation of "${leftName}" turned around rather than reflected${placementYawed ? `, and sits at ${formatVector(rightPosition)} where a reflection would place it at ${formatVector(reflectedPosition)}` : ''}. A yaw preserves handedness instead of inverting it, which is what produces backward-facing hands and feet with the big toe on the outer edge. Reflect the counterpart instead: position [-x, y, z] with rotation [rx, -ry, -rz] and positive scale.`,
});
}
return findings;
}
const formatDegrees = (value) => `${Math.round(value)}°`;
/**
* Report a part the spec declares as a curved form whose sweep never bends.
*
* Named or feature-declared curvature is the whole trigger: `tube` and `extrude`
* are the right answer for plenty of straight parts — a rail, a plate, a strut —
* so a straight sweep is evidence of nothing until the spec says it was meant to
* turn.
*/
const buildSweptPathCurvatureFindings = (spec, parts) => {
const partsById = new Map(parts.map((part) => [part.id, part]));
const findings = [];
for (const [partId, declaredBy] of collectDeclaredCurvedParts(spec)) {
const part = partsById.get(partId);
const curvature = evaluateSweptGeometryCurvature(part?.geometry);
if (!curvature || !curvature.straight) continue;
const name = part.name || part.id;
// Only when the declaration came from somewhere else — repeating the part's
// own name back at it reads as a stutter.
const declaration = declaredBy === name ? '' : ` (declared by the feature "${declaredBy}")`;
const message = curvature.kind === 'tube'
? `Part "${name}"${declaration} is a curved form built from a tube whose path ${curvature.arcSpanDegrees > 0 ? `only turns through ${formatDegrees(curvature.arcSpanDegrees)}` : 'runs through collinear control points'}, so it sweeps straight. Sample the intended curve into "path" so consecutive points step around a centre — a horn, tail, hook, or bent conduit needs at least ${formatDegrees(SWEPT_ARC_MIN_SPAN_DEGREES)} of turn — instead of listing points along one line.`
: `Part "${name}"${declaration} is a curved form built from an extrude whose outline never turns back on itself (${formatDegrees(curvature.concaveTurnDegrees)} of sustained concave turning). An extrude sweeps its outline along a STRAIGHT axis, so the curve has to be in the outline's own silhouette: give it a concave side of at least ${formatDegrees(CURVED_OUTLINE_MIN_CONCAVE_TURN_DEGREES)}, or build the part as a "tube" whose path follows the curve.`;
findings.push({
code: 'straight-swept-path',
severity: 'warning',
partIds: [partId],
message,
});
}
return findings;
};
/**
* @param {object|null} spec a validated Three.js scene spec
* @returns {{findings: Array, errorCount: number, warningCount: number, noteCount: number,
* evaluatedPartCount: number, evaluatedPoseCount: number}}
*/
export function evaluateThreejsPhysicalAudit(spec) {
if (!spec || !Array.isArray(spec.parts)) {
return {
findings: [],
errorCount: 0,
warningCount: 0,
noteCount: 0,
evaluatedPartCount: 0,
evaluatedPoseCount: 0,
unmeasuredAttachments: [],
};
}
const materials = spec.materials && typeof spec.materials === 'object' ? spec.materials : {};
const declaredAttachments = resolveThreejsAttachments(spec.articulation);
const anchoredAttachments = declaredAttachments.filter(isThreejsAttachmentAnchored);
const attachments = new Set(declaredAttachments.map((attachment) => attachment.partId));
const jointPartIds = new Set((spec.articulation?.joints || []).map((j) => j.partId).filter(Boolean));
const socketsByName = new Map((spec.sockets || []).map((socket) => [socket.name, socket]));
const findings = [];
const seenKeys = new Set();
const parts = flattenParts(spec.parts);
const namesByPartId = new Map(parts.map((part) => [part.id, part.name || part.id]));
const staticScaleFindings = new Map();
const strongestAnimatedScaleFindings = new Map();
const addFinding = (finding) => {
const key = `${finding.code}|${[...finding.partIds].sort().join(',')}|${finding.clipId || ''}|${finding.sequenceId || ''}`;
if (seenKeys.has(key)) return;
seenKeys.add(key);
findings.push(finding);
};
// 1. Static Resting Pose Evaluation
const { volumes: staticVolumes, transformsByPartId } = collectPoseVolumes(spec, null);
const evaluatedPartCount = staticVolumes.length;
let evaluatedPoseCount = 1;
// A declaration with no anchor in it cannot be measured at all, so it is
// reported before any geometry is looked at.
for (const attachment of declaredAttachments) {
if (isThreejsAttachmentAnchored(attachment)) continue;
addFinding({
code: 'unanchored-attachment',
severity: 'warning',
partIds: [attachment.partId],
message: `Part "${namesByPartId.get(attachment.partId) || attachment.partId}" is declared as a carried attachment but names nothing it is carried by, so nothing ties it to the part it hangs from. Declare it in "attachments" with an "anchorPartId" or "anchorSocket".`,
});
}
const staticAnchorReport = measureAttachmentAnchors({
attachments: anchoredAttachments,
volumes: staticVolumes,
transformsByPartId,
socketsByName,
namesByPartId,
});
// Accumulated across every pose, and resolved at the end: an attachment
// measured in ANY pose was checked, so a clip pose that happens to hide the
// anchor must not retroactively report it as unverified — and an attachment no
// pose could measure must never read as clean.
const measuredAnywhere = new Set(staticAnchorReport.measured);
const unmeasuredByPartId = new Map(staticAnchorReport.unmeasured.map((entry) => [entry.partId, entry]));
const staticAnchorFailures = new Set();
for (const finding of staticAnchorReport.findings) {
staticAnchorFailures.add(finding.partIds[0]);
addFinding(finding);
}
for (const part of parts) {
const finding = buildNonuniformParentScaleFinding(part, [{ scale: part.scale }]);
if (finding) {
staticScaleFindings.set(part.id, finding);
addFinding(finding);
}
}
const visibleStaticVolumes = staticVolumes.filter((v) => v.visible && v.opacity > 0);
for (const finding of buildBilateralChiralityFindings({
pairs: collectBilateralPairs(parts),
chains: collectPartChains(spec.parts),
volumes: visibleStaticVolumes,
})) {
addFinding(finding);
}
for (const finding of buildSweptPathCurvatureFindings(spec, parts)) {
addFinding(finding);
}
// Floating check & Buried & Coplanar on resting pose
for (let i = 0; i < visibleStaticVolumes.length; i += 1) {
const subject = visibleStaticVolumes[i];
// Ground contact check: min Y <= TOUCH_TOLERANCE
const touchesGround = subject.worldBounds[1][0] <= TOUCH_TOLERANCE;
const isAttachment = attachments.has(subject.id) || jointPartIds.has(subject.id);
const hasParent = subject.ancestorIds.length > 0;
let touchesAnyOther = touchesGround || isAttachment || hasParent;
for (let j = 0; j < visibleStaticVolumes.length; j += 1) {
if (i === j) continue;
const other = visibleStaticVolumes[j];
// Check distance
const dist = aabbDistance(subject.worldBounds, other.worldBounds);
if (dist <= TOUCH_TOLERANCE) {
touchesAnyOther = true;
}
if (i < j) {
// Buried check (subject inside container or other inside subject)
const isAncestorChild = subject.ancestorIds.includes(other.id) || other.ancestorIds.includes(subject.id);
const seeThrough = isTransparent(materials[other.materialId]) || isTransparent(materials[subject.materialId]);
if (!seeThrough && !isAncestorChild && !attachments.has(subject.id) && !attachments.has(other.id)) {
if (aabbContains(other.worldBounds, subject.worldBounds)) {
addFinding({
code: 'buried-geometry',
severity: 'error',
partIds: [subject.id, other.id],
message: `Part "${subject.name}" is completely buried inside "${other.name}". Move it out to an exposed surface or parent it properly.`,
});
} else if (aabbContains(subject.worldBounds, other.worldBounds)) {
addFinding({
code: 'buried-geometry',
severity: 'error',
partIds: [other.id, subject.id],
message: `Part "${other.name}" is completely buried inside "${subject.name}". Move it out to an exposed surface or parent it properly.`,
});
}
}
// Coplanar surface check
if (!isAncestorChild) {
for (let axis = 0; axis < 3; axis += 1) {
const axis1 = (axis + 1) % 3;
const axis2 = (axis + 2) % 3;
const planeMatches = Math.abs(subject.worldBounds[axis][0] - other.worldBounds[axis][0]) < COPLANAR_TOLERANCE
|| Math.abs(subject.worldBounds[axis][1] - other.worldBounds[axis][1]) < COPLANAR_TOLERANCE
|| Math.abs(subject.worldBounds[axis][1] - other.worldBounds[axis][0]) < COPLANAR_TOLERANCE
|| Math.abs(subject.worldBounds[axis][0] - other.worldBounds[axis][1]) < COPLANAR_TOLERANCE;
if (planeMatches) {
const area = faceAreaOverlap2D(
subject.worldBounds[axis1][0], subject.worldBounds[axis1][1],
subject.worldBounds[axis2][0], subject.worldBounds[axis2][1],
other.worldBounds[axis1][0], other.worldBounds[axis1][1],
other.worldBounds[axis2][0], other.worldBounds[axis2][1],
);
const minArea = Math.min(
(subject.worldBounds[axis1][1] - subject.worldBounds[axis1][0])
* (subject.worldBounds[axis2][1] - subject.worldBounds[axis2][0]),
(other.worldBounds[axis1][1] - other.worldBounds[axis1][0])
* (other.worldBounds[axis2][1] - other.worldBounds[axis2][0]),
);
if (minArea > EPSILON && area / minArea >= 0.25) {
const axisName = axis === 0 ? 'X' : axis === 1 ? 'Y' : 'Z';
addFinding({
code: 'coplanar-surface',
severity: 'warning',
partIds: [subject.id, other.id],
message: `Parts "${subject.name}" and "${other.name}" share a coplanar surface along the ${axisName} axis, causing z-fighting flickering. Shift one slightly or offset their bounds.`,
});
}
}
}
}
}
}
if (!touchesAnyOther) {
addFinding({
code: 'floating-part',
severity: 'warning',
partIds: [subject.id],
message: `Part "${subject.name}" floats unattached in space without touching any parent, sibling, joint, or ground surface.`,
});
}
}
// 2. Animated Clips & Pose Evaluation
const clips = Array.isArray(spec.animation?.clips) ? spec.animation.clips : [];
const candidateTimes = clips.map(planClipSampleTimes);
const quotas = allocateClipPoseBudget(candidateTimes, MAX_CLIP_AUDIT_POSES);
const clipCoverage = [];
clips.forEach((clip, clipIndex) => {
const sequences = Array.isArray(clip.sequences) ? clip.sequences : [];
for (const part of parts) {
const scaleSamples = collectAnimatedScaleSamples(part, sequences);
if (scaleSamples.length > 0) {
const finding = buildNonuniformParentScaleFinding(part, scaleSamples, {
clipId: clip.id,
clipName: clip.name || clip.id,
});
if (finding) {
const current = strongestAnimatedScaleFindings.get(part.id);
if (!current || finding.anisotropyRatio > current.anisotropyRatio) {
strongestAnimatedScaleFindings.set(part.id, finding);
}
}
}
}
const candidates = candidateTimes[clipIndex];
const timesToTest = candidates.slice(0, quotas[clipIndex]).sort((a, b) => a - b);
const omittedTimes = candidates.slice(quotas[clipIndex]).sort((a, b) => a - b);
evaluatedPoseCount += timesToTest.length;
clipCoverage.push({
clipId: clip.id,
clipName: clip.name || clip.id,
sampledTimes: timesToTest,
omittedCount: omittedTimes.length,
omittedTimes: omittedTimes.slice(0, MAX_LISTED_OMITTED_TIMES),
});
// Only the attachment measurement walks the sampled poses, so a pose left
// out of the budget is a gap in that check alone — and it is said so,
// rather than letting the clean count imply every moment was measured.
if (omittedTimes.length > 0 && anchoredAttachments.length > 0) {
const listed = omittedTimes.slice(0, MAX_LISTED_OMITTED_TIMES);
addFinding({
code: 'clip-poses-unsampled',
severity: 'note',
partIds: [],
clipId: clip.id,
omittedTimes: listed,
omittedCount: omittedTimes.length,
message: `In clip "${clip.name || clip.id}", attachments were checked at ${timesToTest.length} of ${candidates.length} sampled pose(s); the audit's ${MAX_CLIP_AUDIT_POSES}-pose budget across ${clips.length} clip(s) left ${formatTimes(listed)}${omittedTimes.length > listed.length ? ` and ${omittedTimes.length - listed.length} more` : ''} unmeasured, so an attachment could leave its anchor there unreported.`,
});
}
// A clip can carry an attachment away from its anchor without ever breaking
// the resting pose, so the same measurement runs over the sampled poses —
// reporting the WORST one per attachment rather than the first, so the
// refinement feedback names the moment the relationship is most broken.
if (anchoredAttachments.length > 0) {
const worstByPartId = new Map();
for (const timeSeconds of timesToTest) {
const pose = collectPoseVolumes(spec, getPoseStateResolver(clip, timeSeconds));
const report = measureAttachmentAnchors({
attachments: anchoredAttachments,
volumes: pose.volumes,
transformsByPartId: pose.transformsByPartId,
socketsByName,
namesByPartId,
context: { clipId: clip.id, clipName: clip.name || clip.id, timeSeconds },
});
for (const partId of report.measured) measuredAnywhere.add(partId);
for (const entry of report.unmeasured) {
if (!unmeasuredByPartId.has(entry.partId)) unmeasuredByPartId.set(entry.partId, entry);
}
for (const finding of report.findings) {
const partId = finding.partIds[0];
// The resting pose already reported this attachment; repeating it per
// clip would bury the clip-only breaks the pose walk exists to find.
if (staticAnchorFailures.has(partId)) continue;
const current = worstByPartId.get(partId);
if (!current || finding.distance > current.distance) worstByPartId.set(partId, finding);
}
}
for (const finding of worstByPartId.values()) addFinding(finding);
}
// Check unprovenanced transitions for sequences that toggle visibility/opacity
for (const seq of sequences) {
const visCh = seq.channels?.visible;
const opacCh = seq.channels?.opacity;
const appears = (visCh && visCh.from === false && visCh.to === true)
|| (opacCh && opacCh.from === 0 && opacCh.to > 0);
if (appears && seq.startSeconds > 0) {
const getPoseState = getPoseStateResolver(clip, seq.startSeconds);
const { volumes: poseVolumes } = collectPoseVolumes(spec, getPoseState);
const partVolume = poseVolumes.find((v) => v.id === seq.partId);
if (partVolume) {
const parentVolume = poseVolumes.find((v) => partVolume.ancestorIds.includes(v.id));
const touchesGround = partVolume.worldBounds[1][0] <= TOUCH_TOLERANCE;
const insideParent = parentVolume && aabbDistance(partVolume.worldBounds, parentVolume.worldBounds) <= TOUCH_TOLERANCE;
if (!touchesGround && !insideParent) {
addFinding({
code: 'unprovenanced-transition',
severity: 'warning',
partIds: [seq.partId],
clipId: clip.id,
sequenceId: seq.id,
timeSeconds: seq.startSeconds,
message: `In clip "${clip.name || clip.id}", sequence "${seq.name || seq.id}" makes part "${partVolume.name}" appear at ${seq.startSeconds}s in open air without emerging from a parent part or ground level.`,
});
}
}
}
}
});
for (const [partId, finding] of strongestAnimatedScaleFindings) {
const staticFinding = staticScaleFindings.get(partId);
const staticRatio = staticFinding?.anisotropyRatio || 0;
if (!staticFinding || finding.anisotropyRatio > staticRatio * (1 + ANISOTROPY_COMPARISON_TOLERANCE)) {
addFinding(finding);
}
}
const unmeasuredAttachments = [...unmeasuredByPartId.values()]
.filter((entry) => !measuredAnywhere.has(entry.partId));
const countBy = (severity) => findings.filter((f) => f.severity === severity).length;
return {
findings,
errorCount: countBy('error'),
warningCount: countBy('warning'),
noteCount: countBy('note'),
evaluatedPartCount,
evaluatedPoseCount,
// Never folded into the clean count: an attachment whose anchor could not be
// measured was not checked, and reporting it as passing is the failure this
// gate exists to avoid.
unmeasuredAttachments,
// Which clip times the pose walk measured and which the budget left out.
// `complete`/`partial` describe the attachment check over clip motion;
// a record written before this field existed carries none, which readers
// treat as "interior clip poses never measured", not as complete.
poseCoverage: {
status: clips.length === 0
? 'static'
: clipCoverage.some((entry) => entry.omittedCount > 0) ? 'partial' : 'complete',
measuresAttachments: anchoredAttachments.length > 0,
budget: MAX_CLIP_AUDIT_POSES,
clips: clipCoverage,
},
};
}
/**
* Default refinement feedback for a physical audit report.
* Returns '' when there are no actionable errors or warnings.
*
* @param {object|null} physicalAudit a stored `evaluateThreejsPhysicalAudit` result
* @returns {string}
*/
export function buildThreejsPhysicalAuditFeedback(physicalAudit) {
const actionable = (physicalAudit?.findings || []).filter((f) => f.severity === 'error' || f.severity === 'warning');
const unmeasured = Array.isArray(physicalAudit?.unmeasuredAttachments) ? physicalAudit.unmeasuredAttachments : [];
// A clip pose the budget left out is, like an unmeasured anchor, an
// attachment relationship nothing verified — so it is fed back too.
const unsampled = (physicalAudit?.findings || []).filter((f) => f.code === 'clip-poses-unsampled');
if (actionable.length === 0 && unmeasured.length === 0 && unsampled.length === 0) return '';
const hasNonuniformParentScale = actionable.some((finding) => finding.code === 'nonuniform-parent-scale');
const hasBilateralChirality = actionable.some((finding) => (
finding.code === 'bilateral-chirality'
|| finding.code === 'bilateral-mirror-scale'
|| finding.code === 'bilateral-pair-same-side'
));
const hasStraightSweptPath = actionable.some((finding) => finding.code === 'straight-swept-path');
const attachmentFindings = actionable.filter((finding) => (
finding.code === 'unanchored-attachment' || finding.code === 'attachment-far-from-anchor'
));
// Name the anchor rather than the defect: the next pass needs somewhere to put
// the part, and "this is floating" without a destination is what produced the
// hat at hip height in the first place.
const anchorNames = [...new Set(attachmentFindings
.map((finding) => finding.anchorSocket || finding.anchorPartId)
.filter(Boolean))];
return [
'The previous pass failed physical conformance audits:',
...actionable.map((finding, index) => `${index + 1}. ${finding.message}`),
...unmeasured.map((entry) => `Attachment "${entry.partId}" could not be checked against ${entry.anchorSocket ? `socket "${entry.anchorSocket}"` : `"${entry.anchorPartId}"`} because ${entry.reason} — give both the attachment and its anchor real geometry so the relationship can be verified.`),
...unsampled.map((finding) => `${finding.message} Keep every carried part on its anchor throughout each motion, not only where a sequence starts and ends.`),
...(hasNonuniformParentScale ? [
'For non-uniform parent scale findings, size each part through its own geometry dimensions (for example, box width/height/depth or sphere radius) and keep containers near-uniform instead of squashing a parent that owns other components.',
] : []),
...(hasStraightSweptPath ? [
'For straight swept-path findings, put the curve in the geometry rather than in the part name: a "tube" needs enough control points, stepped around a centre, that its path visibly turns, and an "extrude" only curves when its outline itself has a concave side. Rotating or repositioning a straight sweep does not make it a curved one.',
] : []),
...(hasBilateralChirality ? [
'For bilateral pair findings, mirror a paired limb across the lateral plane rather than turning it around: give the counterpart position [-x, y, z] and rotation [rx, -ry, -rz] with every scale component positive. A 180° yaw about the vertical axis or a negative scale factor leaves the bounding box correct while pointing thumbs backward and putting big toes on the outer edge.',
] : []),
...(attachmentFindings.length > 0 ? [
`For attachment findings, every entry in "articulation.attachments" must name the part or socket it hangs from and be positioned against it${anchorNames.length > 0 ? ` (the anchors named above: ${listSpecNames(anchorNames.map((name) => `"${name}"`))})` : ''}. Anchoring to the model root is not acceptable — name the body part that actually carries the piece.`,
] : []),
'Ensure every part is physically attached to a parent, sibling, or ground plane, keep geometry exposed rather than buried inside unrelated parts, avoid exact coplanar surfaces that cause flickering, and make animated parts emerge cleanly from parents or hidden containers.',
].join('\n');
}