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
/**
* Rig-readiness report for an already-validated Three.js scene spec.
*
* PortOS generates static assemblies. It does not skin a mesh, bind a bind pose,
* or export a skeleton, and the honest thing to publish is therefore not "this
* model is animation-ready" but "this model declares an articulation graph a
* later rig/export path could attach to — or it does not, and here is why".
*
* `threejsSculptSpecSchema` already proves the graph is well FORMED: one root,
* no cycles or forward references, joints pointed at real parts, pivots pointed
* at real sockets. What it cannot say is whether the graph is USEFUL — a single
* root joint, or child joints with no pivot axis, validate cleanly and rig into
* nothing. That judgement lives here, and it reports rather than rejects: a spec
* that falls short is still a good model, it is just a static one.
*/
import { isThreejsAttachmentAnchored, listSpecNames, resolveThreejsAttachments } from './threejsModel.js';
// One joint is a root and nothing else — a graph with nothing to rotate against
// it describes a static assembly with extra words.
const MIN_USEFUL_JOINTS = 2;
const jointLabel = (joint) => joint.id;
/**
* @param {object|null} spec a spec that has already passed a sculpt-spec schema
* @returns {{articulationReady: boolean, reasons: string[], jointCount: number,
* socketCount: number, attachmentCount: number, anchoredAttachmentCount: number,
* unanchoredAttachmentCount: number, rootJointId: string|null,
* subjectType: string|null}}
*/
export function evaluateThreejsRigReadiness(spec) {
const subjectType = spec?.subjectType || null;
const articulation = spec?.articulation || null;
const joints = Array.isArray(articulation?.joints) ? articulation.joints : [];
// An attachment that names nothing to hang from is a declaration with no
// relationship in it, so it is counted separately rather than credited toward
// a rig a later export path could actually attach to.
const attachments = resolveThreejsAttachments(articulation);
const anchored = attachments.filter(isThreejsAttachmentAnchored);
const unanchored = attachments.filter((attachment) => !isThreejsAttachmentAnchored(attachment));
const attachmentCount = attachments.length;
const rootJoint = joints.find((joint) => !joint.parentJointId) || null;
// Distinct sockets, not joint count: two joints naming the same pivot is one
// usable axis, and reporting two would overstate what the model can be rigged
// against.
const socketCount = new Set(joints.map((joint) => joint.pivotSocket).filter(Boolean)).size;
const reasons = [];
if (!articulation) {
reasons.push(subjectType === 'character' || subjectType === 'hybrid'
? 'The spec declares no articulation graph, so this character is a static assembly — its parts have a hierarchy but no joints, pivots, or bind pose.'
: 'This subject was generated as a static assembly and declares no articulation graph.');
} else {
if (joints.length < MIN_USEFUL_JOINTS) {
reasons.push(`Only ${joints.length} joint is declared, which is a root and nothing to move against it.`);
}
// A root's pivot is the model origin; a child joint without one has no axis
// to rotate about, so the graph names moving parts it cannot actually move.
const unpivoted = joints.filter((joint) => joint.parentJointId && !joint.pivotSocket);
if (unpivoted.length > 0) {
reasons.push(`${unpivoted.length} of ${joints.length} joints name no pivot socket, so they have no axis to rotate about (${listSpecNames(unpivoted.map(jointLabel))}).`);
}
if (unanchored.length > 0) {
reasons.push(`${unanchored.length} of ${attachmentCount} declared attachments name nothing to hang from, so nothing ties them to the part they are carried by (${listSpecNames(unanchored.map((attachment) => attachment.partId))}).`);
}
}
return {
articulationReady: reasons.length === 0,
reasons,
jointCount: joints.length,
socketCount,
attachmentCount,
anchoredAttachmentCount: anchored.length,
unanchoredAttachmentCount: unanchored.length,
rootJointId: rootJoint?.id || null,
subjectType,
};
}