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
/**
* Declarative procedural-model contract used by the Three.js Models workspace.
*
* AI providers author this bounded JSON scene spec instead of executable
* JavaScript. The browser renders only allowlisted Three.js primitives (plus a
* bounded custom BufferGeometry), and this module deterministically exports the
* same spec as a standalone Three.js factory.
*/
import { z } from 'zod';
import { failValidation } from './errorHandler.js';
import {
resolveThreejsEnvironment,
THREEJS_ENVIRONMENT_PRESETS,
THREEJS_RENDER_PROFILE,
} from './threejsModelEnvironment.js';
import { THREEJS_PLAYER_SOURCE } from './threejsModelPlayerSource.js';
import {
applyLinear,
IDENTITY_LINEAR,
multiplyLinear,
rotationMatrix,
scaleLinear,
vectorLength,
} from './threejsTransform.js';
const idSchema = z.string().trim().min(1).max(80).regex(/^[A-Za-z][A-Za-z0-9_-]*$/);
const colorSchema = z.string().regex(/^#[0-9a-fA-F]{6}$/);
const finite = z.number().finite().min(-10_000).max(10_000);
const positive = z.number().finite().positive().max(10_000);
const vec3Schema = z.tuple([finite, finite, finite]);
// A part `scale` is a size multiplier, never a mirror or a visibility switch. A
// component at or near zero collapses the part to an invisible plane; a negative
// one reflects it, and three.js compensates for the negative world determinant by
// flipping the front face, so nothing throws and the preview looks plausible.
// That is what makes both expensive to chase: they are indistinguishable from a
// modeling choice, and a plain `finite` triple accepts either. This spec has no
// reflection concept — the prompt never asks for one, an LLM-authored negative
// component is an authoring slip, and the exported factory is consumed by tools
// that do not all compensate for a mirrored node — so the authoring contract
// rejects both. `storedThreejsSculptSpecSchema` keeps accepting them on read.
const MIN_PART_SCALE = 1e-4;
const scaleComponent = positive.min(MIN_PART_SCALE);
const scale3Schema = z.tuple([scaleComponent, scaleComponent, scaleComponent]);
const boxGeometrySchema = z.object({
type: z.literal('box'),
width: positive,
height: positive,
depth: positive,
});
const sphereGeometrySchema = z.object({
type: z.literal('sphere'),
radius: positive,
widthSegments: z.number().int().min(8).max(96).default(32),
heightSegments: z.number().int().min(4).max(64).default(16),
});
const cylinderGeometrySchema = z.object({
type: z.literal('cylinder'),
radiusTop: z.number().finite().min(0).max(10_000),
radiusBottom: z.number().finite().min(0).max(10_000),
height: positive,
radialSegments: z.number().int().min(3).max(96).default(32),
});
const coneGeometrySchema = z.object({
type: z.literal('cone'),
radius: positive,
height: positive,
radialSegments: z.number().int().min(3).max(96).default(32),
});
const torusGeometrySchema = z.object({
type: z.literal('torus'),
radius: positive,
tube: positive,
radialSegments: z.number().int().min(3).max(64).default(16),
tubularSegments: z.number().int().min(6).max(128).default(48),
arcDegrees: z.number().finite().min(1).max(360).default(360),
});
const capsuleGeometrySchema = z.object({
type: z.literal('capsule'),
radius: positive,
length: z.number().finite().min(0).max(10_000),
capSegments: z.number().int().min(2).max(32).default(8),
radialSegments: z.number().int().min(3).max(64).default(16),
});
const latheGeometrySchema = z.object({
type: z.literal('lathe'),
points: z.array(z.tuple([finite, finite])).min(2).max(96),
segments: z.number().int().min(3).max(96).default(32),
});
// Shoelace area — a closed outline whose points are coincident or collinear
// extrudes to nothing, so it is rejected rather than rendered as an empty mesh.
const MIN_RING_AREA = 1e-6;
const ringArea = (ring) => {
let doubled = 0;
for (let index = 0; index < ring.length; index += 1) {
const [x1, y1] = ring[index];
const [x2, y2] = ring[(index + 1) % ring.length];
doubled += (x1 * y2) - (x2 * y1);
}
return Math.abs(doubled) / 2;
};
// Even-odd ray cast. A point exactly on an edge reads as outside, which is what
// we want: a hole touching the outline is a malformed cutout, not a cutout.
const pointInRing = (ring, [px, py]) => {
let inside = false;
for (let index = 0, previous = ring.length - 1; index < ring.length; previous = index, index += 1) {
const [xi, yi] = ring[index];
const [xj, yj] = ring[previous];
const straddles = (yi > py) !== (yj > py);
if (straddles && px < (((xj - xi) * (py - yi)) / (yj - yi)) + xi) inside = !inside;
}
return inside;
};
const turn = (a, b, c) => Math.sign(((b[0] - a[0]) * (c[1] - a[1])) - ((b[1] - a[1]) * (c[0] - a[0])));
const onSegment = (a, b, p) => turn(a, b, p) === 0
&& p[0] >= Math.min(a[0], b[0]) && p[0] <= Math.max(a[0], b[0])
&& p[1] >= Math.min(a[1], b[1]) && p[1] <= Math.max(a[1], b[1]);
const segmentsCross = (a, b, c, d) => {
if (turn(a, b, c) !== turn(a, b, d) && turn(c, d, a) !== turn(c, d, b)) return true;
return onSegment(a, b, c) || onSegment(a, b, d) || onSegment(c, d, a) || onSegment(c, d, b);
};
const ringsCross = (outer, inner) => {
for (let i = 0; i < outer.length; i += 1) {
const a = outer[i];
const b = outer[(i + 1) % outer.length];
for (let j = 0; j < inner.length; j += 1) {
if (segmentsCross(a, b, inner[j], inner[(j + 1) % inner.length])) return true;
}
}
return false;
};
// A ring that crosses itself has no defined interior — the shoelace area stays
// non-zero (the lobes partly cancel) but the triangulator picks an arbitrary
// filling, so require a simple polygon: no two non-adjacent edges may meet.
const isSimpleRing = (ring) => {
for (let i = 0; i < ring.length; i += 1) {
for (let j = i + 1; j < ring.length; j += 1) {
const adjacent = j === i + 1 || (i === 0 && j === ring.length - 1);
if (!adjacent && segmentsCross(ring[i], ring[(i + 1) % ring.length], ring[j], ring[(j + 1) % ring.length])) {
return false;
}
}
}
return true;
};
// Vertex containment alone is not enough: a concave outline can hold every hole
// vertex while an edge between two of them leaves through the notch. Bounded by
// the ring caps (160 outline points × 12 holes × 160 hole points), so the O(n·m)
// edge sweep only runs against provider output that already passed the caps.
const ringContainsRing = (outer, inner) =>
inner.every((point) => pointInRing(outer, point)) && !ringsCross(outer, inner);
// Two holes that touch, cross, or nest are one cutout described twice; the
// triangulator resolves the doubled winding by leaving material inside them.
const ringsOverlap = (a, b) => ringsCross(a, b)
|| b.every((point) => pointInRing(a, point))
|| a.every((point) => pointInRing(b, point));
const outlineRingSchema = z.array(z.tuple([finite, finite])).min(3).max(160)
.refine((ring) => ringArea(ring) > MIN_RING_AREA, 'outline must enclose a non-zero area')
.refine(isSimpleRing, 'outline must not cross itself');
const extrudeGeometrySchema = z.object({
type: z.literal('extrude'),
outline: outlineRingSchema,
holes: z.array(outlineRingSchema).max(12).default([]),
depth: positive,
bevelEnabled: z.boolean().default(false),
bevelThickness: z.number().finite().min(0).max(1_000).default(0.1),
bevelSize: z.number().finite().min(0).max(1_000).default(0.1),
bevelSegments: z.number().int().min(0).max(8).default(2),
curveSegments: z.number().int().min(1).max(24).default(8),
steps: z.number().int().min(1).max(32).default(1),
}).superRefine((definition, ctx) => {
// A hole that is not strictly inside the outline is not a cutout — Three.js
// silently emits a disjoint or self-intersecting face instead of failing.
definition.holes.forEach((hole, index) => {
if (!ringContainsRing(definition.outline, hole)) {
ctx.addIssue({ code: 'custom', message: `extrude hole ${index} falls outside the outline`, path: ['holes', index] });
}
for (let other = 0; other < index; other += 1) {
if (ringsOverlap(definition.holes[other], hole)) {
ctx.addIssue({ code: 'custom', message: `extrude hole ${index} overlaps hole ${other}`, path: ['holes', index] });
}
}
});
});
// Exact collinearity only — the epsilon guards float noise, never near-straight
// paths, which sweep a perfectly good tube.
const isCollinearPath = (points) => {
const [origin] = points;
const spread = points.find((point) => point.some((value, axis) => value !== origin[axis]));
if (!spread) return true;
const direction = spread.map((value, axis) => value - origin[axis]);
return points.every((point) => {
const offset = point.map((value, axis) => value - origin[axis]);
const cross = [
(direction[1] * offset[2]) - (direction[2] * offset[1]),
(direction[2] * offset[0]) - (direction[0] * offset[2]),
(direction[0] * offset[1]) - (direction[1] * offset[0]),
];
return cross.every((component) => Math.abs(component) < 1e-9);
});
};
const tubeGeometrySchema = z.object({
type: z.literal('tube'),
path: z.array(vec3Schema).min(2).max(96)
.refine(
(points) => points.every((point, index) => index === 0 || point.some((value, axis) => value !== points[index - 1][axis])),
'tube path cannot repeat the same point consecutively',
),
radius: positive,
tubularSegments: z.number().int().min(2).max(256).default(64),
radialSegments: z.number().int().min(3).max(32).default(12),
closed: z.boolean().default(false),
curveType: z.enum(['centripetal', 'chordal', 'catmullrom']).default('centripetal'),
tension: z.number().finite().min(0).max(1).default(0.5),
}).superRefine((definition, ctx) => {
if (!definition.closed) return;
const first = definition.path[0];
const last = definition.path[definition.path.length - 1];
// A closed curve already joins the endpoints; repeating the seam point yields a
// zero-length segment and NaN frames in the centripetal/chordal parameterizations.
if (first.every((value, axis) => value === last[axis])) {
ctx.addIssue({ code: 'custom', message: 'a closed tube path must not repeat its first point at the end', path: ['path'] });
}
// Fewer than three points — or any number of collinear ones — closes into a
// curve that runs out and retraces itself, so the tube overlaps its own surface.
if (definition.path.length < 3 || isCollinearPath(definition.path)) {
ctx.addIssue({ code: 'custom', message: 'a closed tube path needs at least three non-collinear points', path: ['path'] });
}
});
const customGeometrySchema = z.object({
type: z.literal('custom'),
// 900 vertices / 2,700 coordinates is deliberately generous for a
// procedural reconstruction while bounding provider output and browser work.
vertices: z.array(finite).min(9).max(2_700)
.refine((values) => values.length % 3 === 0, 'vertices must contain xyz triples'),
indices: z.array(z.number().int().min(0).max(899)).min(3).max(5_400)
.refine((values) => values.length % 3 === 0, 'indices must contain triangle triples'),
});
export const threejsGeometrySchema = z.discriminatedUnion('type', [
boxGeometrySchema,
sphereGeometrySchema,
cylinderGeometrySchema,
coneGeometrySchema,
torusGeometrySchema,
capsuleGeometrySchema,
latheGeometrySchema,
extrudeGeometrySchema,
tubeGeometrySchema,
customGeometrySchema,
]);
export const threejsMaterialSchema = z.object({
type: z.enum(['standard', 'physical', 'basic']).default('standard'),
side: z.enum(['front', 'double']).default('front'),
color: colorSchema,
metalness: z.number().finite().min(0).max(1).default(0),
roughness: z.number().finite().min(0).max(1).default(0.65),
emissive: colorSchema.default('#000000'),
emissiveIntensity: z.number().finite().min(0).max(20).default(0),
opacity: z.number().finite().min(0).max(1).default(1),
transparent: z.boolean().default(false),
wireframe: z.boolean().default(false),
clearcoat: z.number().finite().min(0).max(1).default(0),
clearcoatRoughness: z.number().finite().min(0).max(1).default(0),
// Physical-only channels. They are parsed for every material type so a spec
// round-trips unchanged, but only `type: 'physical'` forwards them to Three.js.
// `ior` is bounded to the range MeshPhysicalMaterial itself clamps to.
ior: z.number().finite().min(1).max(2.333).default(1.5),
transmission: z.number().finite().min(0).max(1).default(0),
thickness: z.number().finite().min(0).max(1_000).default(0),
sheen: z.number().finite().min(0).max(1).default(0),
iridescence: z.number().finite().min(0).max(1).default(0),
anisotropy: z.number().finite().min(0).max(1).default(0),
});
// The scale bound is the ONE thing that differs between what a provider may
// author and what an install may already have stored, so the part hierarchy is
// built from it rather than written twice.
const makePartSchema = (scaleSchema) => {
let partSchema;
partSchema = z.lazy(() => z.object({
id: idSchema,
name: z.string().trim().min(1).max(120),
geometry: threejsGeometrySchema.optional(),
material: idSchema.optional(),
position: vec3Schema.default([0, 0, 0]),
rotationDegrees: vec3Schema.default([0, 0, 0]),
scale: scaleSchema.default([1, 1, 1]),
castShadow: z.boolean().default(true),
receiveShadow: z.boolean().default(true),
// Surface relief (serrations, stria, trim, port floors) belongs TO a part
// rather than being one: it rides its parent when the model is taken apart,
// and a click on it selects the parent. Without the flag a disassembly
// shatters into a comb of loose slivers nobody can read or pick.
explodeWithParent: z.boolean().default(false),
children: z.array(partSchema).max(40).default([]),
}));
return partSchema;
};
const lightSchema = z.object({
type: z.enum(['ambient', 'hemisphere', 'directional', 'point', 'spot']),
color: colorSchema.default('#ffffff'),
groundColor: colorSchema.default('#202030'),
intensity: z.number().finite().min(0).max(100),
position: vec3Schema.default([4, 6, 4]),
angleDegrees: z.number().finite().min(1).max(179).default(45),
penumbra: z.number().finite().min(0).max(1).default(0.25),
});
// The environment/render-profile half of the contract lives in its own
// dependency-free module so the client suite can import it to assert parity —
// this file imports zod, which the client CI job does not install.
const environmentSchema = z.object({
preset: z.enum(THREEJS_ENVIRONMENT_PRESETS).default('none'),
intensity: z.number().finite().min(0).max(4).default(1),
});
const socketSchema = z.object({
name: idSchema,
parentPartId: idSchema,
position: vec3Schema.default([0, 0, 0]),
rotationDegrees: vec3Schema.default([0, 0, 0]),
});
// Articulation is a DECLARATION of intent, not a skeleton: PortOS does not skin,
// bind, or deform anything, and nothing downstream of this schema pretends it
// does. A joint names a part that is meant to rotate and the socket it rotates
// about, so a later rig/export path has something stable to attach to and the UI
// can say "articulation-ready" only when the graph is actually well formed.
const jointSchema = z.object({
id: idSchema,
// The part this joint drives. One part backs at most one joint — two joints on
// the same part is a graph that cannot be built, not a redundancy.
partId: idSchema,
// `null` marks the single root. Every other joint names a joint declared
// EARLIER in the array, which is what makes a cycle unrepresentable.
parentJointId: idSchema.nullable().default(null),
// The named socket this joint pivots about. Optional on the root (whose pivot
// is the model origin); a child joint without one has no defined axis, which
// the rig-readiness report treats as not-ready rather than silently rigged.
pivotSocket: idSchema.nullable().default(null),
});
const MAX_JOINTS = 64;
// How far an attachment's bounds may sit from its anchor's surface before the
// physical audit calls the relationship broken. A correctly worn hat overlaps
// the head it sits on, so the AABB gap is zero; a charm on a short chain is a
// fraction of a unit away. The default is deliberately tight — a provider that
// needs slack says so per attachment rather than the gate guessing generously,
// because the defects this catches (a hat at hip height, a charm below the
// ground plane) are off by whole model-heights, not by fractions.
export const DEFAULT_ATTACHMENT_MAX_OFFSET = 0.25;
const MAX_ATTACHMENT_OFFSET = 10;
const MAX_ATTACHMENTS = 40;
// An attachment is only meaningful relative to the thing it hangs from, so this
// entry carries that relationship: the part being carried, and EXACTLY ONE of
// the part or the socket it is carried by. Declaring an attachment without an
// anchor is still accepted through the older `attachmentPartIds` list, which is
// what every spec authored before this field existed uses — those read forward
// as anchor-less entries and the gates report them as unanchored rather than
// rejecting a stored record.
const attachmentSchema = z.object({
partId: idSchema,
anchorPartId: idSchema.nullable().default(null),
anchorSocket: idSchema.nullable().default(null),
maxOffset: z.number().finite().min(0).max(MAX_ATTACHMENT_OFFSET).default(DEFAULT_ATTACHMENT_MAX_OFFSET),
}).superRefine((attachment, ctx) => {
const anchors = [attachment.anchorPartId, attachment.anchorSocket].filter((value) => value !== null);
if (anchors.length !== 1) {
ctx.addIssue({
code: 'custom',
message: `attachment ${attachment.partId} needs exactly one of anchorPartId or anchorSocket, found ${anchors.length}`,
path: ['anchorPartId'],
});
}
});
const articulationSchema = z.object({
joints: z.array(jointSchema).min(1).max(MAX_JOINTS),
// Parts explicitly declared as carried attachments — a pack, a weapon, a hat.
// They ride an articulated part rather than articulating, and saying so is the
// point: without the declaration "not a joint" and "nobody classified it" are
// the same silence.
//
// Kept unchanged and still accepted: this is the anchor-less form. `attachments`
// below is additive, not a replacement, so a stored spec stays valid.
attachmentPartIds: z.array(idSchema).max(MAX_ATTACHMENTS).default([]),
// The same declaration plus the one thing the list above cannot say: what each
// attachment is carried BY. Without it "declared as an attachment" and
// "parented at the model root and related to nothing" are indistinguishable,
// and every downstream gate credits the second as though it were the first.
attachments: z.array(attachmentSchema).max(MAX_ATTACHMENTS).default([]),
});
const detailSchema = z.object({
feature: z.string().trim().min(1).max(240),
evidence: z.string().trim().min(1).max(500),
implementationPartIds: z.array(idSchema).min(1).max(12),
priority: z.enum(['identity', 'major', 'minor']).default('major'),
});
// Animation clips. PortOS still builds STATIC assemblies — nothing here is
// skinned, bound, or deformed, and no provider-authored JavaScript ever runs.
// A clip is a DECLARATION of transforms over time: named sequences that carry
// one part from one authored pose to another inside a bounded window, so a
// deployable can demonstrate assembly, retraction, or destruction and a
// timeline can scrub it deterministically.
//
// Absent `animation` means "static assembly", exactly the way absent
// `articulation` means "no declared joints" — a spec written before clips
// shipped keeps parsing, rendering, and exporting unchanged.
export const THREEJS_CLIP_EASINGS = ['linear', 'easeIn', 'easeOut', 'easeInOut'];
export const THREEJS_CLIP_ROLES = ['deploy', 'retract', 'assemble', 'destroy', 'idle', 'custom'];
// Cue KINDS, not sounds: PortOS ships no audio and loads none. A cue is a data
// identifier a host may map to its own sample, and the kind is the only hint
// about what it should sound like.
export const THREEJS_CUE_KINDS = ['mechanical', 'servo', 'latch', 'hydraulic', 'impact', 'electronic', 'ambient'];
const MAX_CLIP_SECONDS = 120;
const MIN_CLIP_SECONDS = 0.05;
const clipSeconds = z.number().finite().min(0).max(MAX_CLIP_SECONDS);
const unitInterval = z.number().finite().min(0).max(1);
// Every channel is a bounded pair of authored endpoints. There are no keyframe
// arrays and no provider-authored curves: an easing NAME picks one of four
// interpolations PortOS implements, which is what keeps playback deterministic
// and the contract small enough to validate exhaustively.
const rangeSchema = (valueSchema) => z.object({ from: valueSchema, to: valueSchema });
const cueSchema = z.object({
id: idSchema,
label: z.string().trim().min(1).max(120),
kind: z.enum(THREEJS_CUE_KINDS).default('mechanical'),
});
// `visible` is a STEP, not an interpolation: the part holds `from` for the whole
// window and takes `to` the instant the sequence completes. A part that should
// appear part-way through a clip is authored as its own short sequence ending at
// that instant — which keeps the evaluator a pure function of time with no
// hidden fade semantics.
const CHANNEL_KEYS = ['position', 'rotationDegrees', 'scale', 'opacity', 'visible'];
// A sound cue synchronizes to MOVEMENT. A fade or a visibility flip has no
// mechanism behind it to hear, so it cannot be what a cue is attached to.
const MOTION_CHANNEL_KEYS = ['position', 'rotationDegrees', 'scale'];
const rangeChanges = (range) => {
if (!range) return false;
const { from, to } = range;
if (Array.isArray(from) && Array.isArray(to)) return from.some((value, axis) => value !== to[axis]);
return from !== to;
};
const makeSequenceSchema = (scaleSchema) => z.object({
id: idSchema,
name: z.string().trim().min(1).max(120),
partId: idSchema,
startSeconds: clipSeconds,
endSeconds: clipSeconds,
easing: z.enum(THREEJS_CLIP_EASINGS).default('easeInOut'),
channels: z.object({
position: rangeSchema(vec3Schema).optional(),
rotationDegrees: rangeSchema(vec3Schema).optional(),
scale: rangeSchema(scaleSchema).optional(),
opacity: rangeSchema(unitInterval).optional(),
visible: rangeSchema(z.boolean()).optional(),
}),
// The cue this sequence fires when the playhead crosses its start during
// PLAYBACK. Scrubbing never fires anything — that split is the whole reason
// the cue is data rather than an embedded sound.
cueId: idSchema.nullable().default(null),
}).superRefine((sequence, ctx) => {
if (!(sequence.endSeconds > sequence.startSeconds)) {
ctx.addIssue({ code: 'custom', message: 'a sequence must end after it starts', path: ['endSeconds'] });
}
const changed = CHANNEL_KEYS.filter((key) => rangeChanges(sequence.channels[key]));
if (changed.length === 0) {
// A sequence whose endpoints are equal occupies a window on the timeline and
// moves nothing — indistinguishable from a modeling slip, and it would make
// the overlap rule below reject a real sequence in the same window.
ctx.addIssue({ code: 'custom', message: 'a sequence must change at least one channel', path: ['channels'] });
}
if (sequence.cueId && !changed.some((key) => MOTION_CHANNEL_KEYS.includes(key))) {
ctx.addIssue({
code: 'custom',
message: `sequence ${sequence.id} fires cue ${sequence.cueId} without moving the part — attach a cue to a sequence that changes position, rotation, or scale`,
path: ['cueId'],
});
}
});
const makeClipSchema = (scaleSchema) => z.object({
id: idSchema,
name: z.string().trim().min(1).max(120),
role: z.enum(THREEJS_CLIP_ROLES).default('custom'),
durationSeconds: z.number().finite().min(MIN_CLIP_SECONDS).max(MAX_CLIP_SECONDS),
loop: z.boolean().default(false),
sequences: z.array(makeSequenceSchema(scaleSchema)).min(1).max(120),
}).superRefine((clip, ctx) => {
const sequenceIds = new Set();
// One window per part per channel. Two sequences driving the same channel of
// the same part at the same time have no defined result — whichever the
// evaluator happened to visit last would win, so the ambiguity is rejected at
// authoring time instead of resolved by declaration order.
const windows = new Map();
clip.sequences.forEach((sequence, index) => {
if (sequenceIds.has(sequence.id)) {
ctx.addIssue({ code: 'custom', message: `duplicate sequence id: ${sequence.id}`, path: ['sequences', index, 'id'] });
}
sequenceIds.add(sequence.id);
if (sequence.endSeconds > clip.durationSeconds) {
ctx.addIssue({
code: 'custom',
message: `sequence ${sequence.id} ends at ${sequence.endSeconds}s, past the clip's ${clip.durationSeconds}s duration`,
path: ['sequences', index, 'endSeconds'],
});
}
for (const channel of CHANNEL_KEYS) {
if (!sequence.channels[channel]) continue;
const key = `${sequence.partId}|${channel}`;
const claimed = windows.get(key) || [];
const clash = claimed.find((other) => sequence.startSeconds < other.endSeconds && other.startSeconds < sequence.endSeconds);
if (clash) {
ctx.addIssue({
code: 'custom',
message: `sequences ${clash.id} and ${sequence.id} both drive ${channel} of part ${sequence.partId} at the same time`,
path: ['sequences', index, 'channels', channel],
});
}
claimed.push(sequence);
windows.set(key, claimed);
}
});
});
const makeAnimationSchema = (scaleSchema) => z.object({
clips: z.array(makeClipSchema(scaleSchema)).min(1).max(12),
cues: z.array(cueSchema).max(24).default([]),
}).superRefine((animation, ctx) => {
const cueIds = new Set();
animation.cues.forEach((cue, index) => {
if (cueIds.has(cue.id)) {
ctx.addIssue({ code: 'custom', message: `duplicate cue id: ${cue.id}`, path: ['cues', index, 'id'] });
}
cueIds.add(cue.id);
});
const clipIds = new Set();
animation.clips.forEach((clip, clipIndex) => {
if (clipIds.has(clip.id)) {
ctx.addIssue({ code: 'custom', message: `duplicate clip id: ${clip.id}`, path: ['clips', clipIndex, 'id'] });
}
clipIds.add(clip.id);
clip.sequences.forEach((sequence, index) => {
if (sequence.cueId && !cueIds.has(sequence.cueId)) {
ctx.addIssue({
code: 'custom',
message: `unknown cue: ${sequence.cueId}`,
path: ['clips', clipIndex, 'sequences', index, 'cueId'],
});
}
});
});
});
const makeSpecSchema = (scaleSchema) => z.object({
schemaVersion: z.literal(1),
name: z.string().trim().min(1).max(120),
summary: z.string().trim().min(1).max(1_000),
subjectType: z.enum(['object', 'character', 'hybrid']),
limitations: z.array(z.string().trim().min(1).max(500)).max(12).default([]),
background: colorSchema.default('#111827'),
camera: z.object({
position: vec3Schema,
target: vec3Schema.default([0, 0, 0]),
fov: z.number().finite().min(15).max(90).default(42),
}),
materials: z.record(idSchema, threejsMaterialSchema)
.refine((materials) => Object.keys(materials).length > 0, 'at least one material is required')
.refine((materials) => Object.keys(materials).length <= 50, 'at most 50 materials are allowed'),
lights: z.array(lightSchema).min(1).max(8),
// Optional and additive, same contract as `articulation` and `animation`: a
// spec authored before image-based lighting shipped simply has no key, which
// `resolveThreejsEnvironment` reads as the `none` it was actually rendered
// with. A newly authored spec is asked for a real preset.
environment: environmentSchema.optional(),
parts: z.array(makePartSchema(scaleSchema)).min(1).max(40),
sockets: z.array(socketSchema).max(40).default([]),
// Optional and additive: a spec written before articulation shipped simply has
// no key, which every consumer reads as "static assembly", never as "rigged".
articulation: articulationSchema.optional(),
// Same contract: absent means the model is a static assembly with nothing to
// play, which is what every spec authored before clips shipped says.
animation: makeAnimationSchema(scaleSchema).optional(),
detailInventory: z.array(detailSchema).min(1).max(80),
}).superRefine((spec, ctx) => {
const materialIds = new Set(Object.keys(spec.materials));
const partIds = new Set();
let partCount = 0;
const visit = (part, depth, path) => {
partCount += 1;
if (depth > 8) {
ctx.addIssue({ code: 'custom', message: 'part hierarchy cannot exceed 8 levels', path });
}
if (partIds.has(part.id)) {
ctx.addIssue({ code: 'custom', message: `duplicate part id: ${part.id}`, path: [...path, 'id'] });
}
partIds.add(part.id);
if (part.geometry && !part.material) {
ctx.addIssue({ code: 'custom', message: 'a part with geometry requires a material', path: [...path, 'material'] });
}
if (part.material && !materialIds.has(part.material)) {
ctx.addIssue({ code: 'custom', message: `unknown material: ${part.material}`, path: [...path, 'material'] });
}
if (part.geometry?.type === 'custom') {
const vertexCount = part.geometry.vertices.length / 3;
const invalidIndex = part.geometry.indices.find((index) => index >= vertexCount);
if (invalidIndex !== undefined) {
ctx.addIssue({ code: 'custom', message: `custom geometry index ${invalidIndex} exceeds vertex count ${vertexCount}`, path: [...path, 'geometry', 'indices'] });
}
}
part.children.forEach((child, index) => visit(child, depth + 1, [...path, 'children', index]));
};
spec.parts.forEach((part, index) => visit(part, 1, ['parts', index]));
if (partCount > 160) {
ctx.addIssue({ code: 'custom', message: 'model cannot exceed 160 total parts', path: ['parts'] });
}
for (const [index, socket] of spec.sockets.entries()) {
if (!partIds.has(socket.parentPartId)) {
ctx.addIssue({ code: 'custom', message: `unknown socket parent: ${socket.parentPartId}`, path: ['sockets', index, 'parentPartId'] });
}
}
if (spec.articulation) {
const socketNames = new Set(spec.sockets.map((socket) => socket.name));
const jointIds = new Set();
const jointPartIds = new Set();
let rootCount = 0;
for (const [index, joint] of spec.articulation.joints.entries()) {
const at = (key) => ['articulation', 'joints', index, key];
if (jointIds.has(joint.id)) {
ctx.addIssue({ code: 'custom', message: `duplicate joint id: ${joint.id}`, path: at('id') });
}
if (!partIds.has(joint.partId)) {
ctx.addIssue({ code: 'custom', message: `unknown joint part: ${joint.partId}`, path: at('partId') });
} else if (jointPartIds.has(joint.partId)) {
ctx.addIssue({ code: 'custom', message: `part ${joint.partId} is already driven by another joint`, path: at('partId') });
}
if (joint.parentJointId === null) {
rootCount += 1;
} else if (!jointIds.has(joint.parentJointId)) {
// Earlier-only, so a dangling parent, a forward reference, and a cycle
// are all the same rejection — there is no graph walk to get wrong.
ctx.addIssue({
code: 'custom',
message: `joint ${joint.id} names parent ${joint.parentJointId}, which is not a joint declared before it`,
path: at('parentJointId'),
});
}
if (joint.pivotSocket !== null && !socketNames.has(joint.pivotSocket)) {
ctx.addIssue({ code: 'custom', message: `unknown pivot socket: ${joint.pivotSocket}`, path: at('pivotSocket') });
}
jointIds.add(joint.id);
jointPartIds.add(joint.partId);
}
if (rootCount !== 1) {
ctx.addIssue({
code: 'custom',
message: `articulation needs exactly one root joint (a joint with parentJointId null), found ${rootCount}`,
path: ['articulation', 'joints'],
});
}
for (const [index, partId] of spec.articulation.attachmentPartIds.entries()) {
const path = ['articulation', 'attachmentPartIds', index];
if (!partIds.has(partId)) {
ctx.addIssue({ code: 'custom', message: `unknown attachment part: ${partId}`, path });
} else if (jointPartIds.has(partId)) {
// A part cannot be both carried and articulated — that is the one
// ambiguity this declaration exists to remove.
ctx.addIssue({ code: 'custom', message: `part ${partId} is declared as an attachment and also driven by a joint`, path });
}
}
// The model root carries no relationship to any body part, so anchoring to
// it is the literal defect this field exists to catch. PortOS has no scene
// root PART — `parts` is an array — so the root is the sole top-level part
// when there is exactly one: that part IS the whole assembly. A spec with
// several top-level parts has no such container, and each of them is a real
// component worth anchoring to.
const rootPartId = spec.parts.length === 1 ? spec.parts[0].id : null;
const socketParentByName = new Map(spec.sockets.map((socket) => [socket.name, socket.parentPartId]));
const anchorPartByAttachment = new Map();
const seenAttachmentPartIds = new Set();
for (const [index, attachment] of spec.articulation.attachments.entries()) {
const at = (key) => ['articulation', 'attachments', index, key];
if (!partIds.has(attachment.partId)) {
ctx.addIssue({ code: 'custom', message: `unknown attachment part: ${attachment.partId}`, path: at('partId') });
} else if (jointPartIds.has(attachment.partId)) {
ctx.addIssue({ code: 'custom', message: `part ${attachment.partId} is declared as an attachment and also driven by a joint`, path: at('partId') });
}
if (seenAttachmentPartIds.has(attachment.partId)) {
ctx.addIssue({ code: 'custom', message: `duplicate attachment part: ${attachment.partId}`, path: at('partId') });
}
seenAttachmentPartIds.add(attachment.partId);
// Resolve whichever anchor form was given down to the part it names, so
// self-anchoring, root-anchoring, and cycles are one check apiece rather
// than one per form.
let anchorPartId = null;
if (attachment.anchorPartId !== null) {
if (!partIds.has(attachment.anchorPartId)) {
ctx.addIssue({ code: 'custom', message: `unknown attachment anchor part: ${attachment.anchorPartId}`, path: at('anchorPartId') });
} else {
anchorPartId = attachment.anchorPartId;
}
} else if (attachment.anchorSocket !== null) {
if (!socketNames.has(attachment.anchorSocket)) {
ctx.addIssue({ code: 'custom', message: `unknown attachment anchor socket: ${attachment.anchorSocket}`, path: at('anchorSocket') });
} else {
anchorPartId = socketParentByName.get(attachment.anchorSocket) ?? null;
}
}
if (anchorPartId !== null) {
const anchorPath = attachment.anchorPartId !== null ? at('anchorPartId') : at('anchorSocket');
if (anchorPartId === attachment.partId) {
ctx.addIssue({ code: 'custom', message: `attachment ${attachment.partId} is anchored to itself`, path: anchorPath });
} else if (anchorPartId === rootPartId) {
ctx.addIssue({
code: 'custom',
message: `attachment ${attachment.partId} is anchored to the model root ${anchorPartId}, which names no body part to hang from`,
path: anchorPath,
});
} else {
anchorPartByAttachment.set(attachment.partId, { anchorPartId, path: anchorPath });
}
}
}
// An anchor chain that closes on itself describes no position: a pack on a
// strap on the pack. Walk each chain to its end; every hop is an attachment
// that was itself anchored, so the walk is bounded by the entry count.
for (const [partId, entry] of anchorPartByAttachment) {
const visited = new Set([partId]);
let cursor = entry.anchorPartId;
while (cursor && anchorPartByAttachment.has(cursor) && !visited.has(cursor)) {
visited.add(cursor);
cursor = anchorPartByAttachment.get(cursor).anchorPartId;
}
if (cursor && visited.has(cursor)) {
ctx.addIssue({
code: 'custom',
message: `attachment ${partId} sits on an anchor chain that cycles back through ${cursor}`,
path: entry.path,
});
}
}
}
if (spec.animation) {
for (const [clipIndex, clip] of spec.animation.clips.entries()) {
for (const [index, sequence] of clip.sequences.entries()) {
if (!partIds.has(sequence.partId)) {
ctx.addIssue({
code: 'custom',
message: `unknown sequence part: ${sequence.partId}`,
path: ['animation', 'clips', clipIndex, 'sequences', index, 'partId'],
});
}
}
}
}
for (const [index, detail] of spec.detailInventory.entries()) {
for (const [partIndex, id] of detail.implementationPartIds.entries()) {
if (!partIds.has(id)) {
ctx.addIssue({ code: 'custom', message: `unknown detail part: ${id}`, path: ['detailInventory', index, 'implementationPartIds', partIndex] });
}
}
}
});
/**
* The AUTHORING contract: what a provider is allowed to hand back. Part scale is
* floored here, so a spec that would render a part reflected or collapsed is
* rejected at the one moment the model can still be asked for another pass.
*/
export const threejsSculptSpecSchema = makeSpecSchema(scale3Schema);
/**
* The READ contract for a spec an install has already stored. Identical except
* that part scale keeps the original unbounded `finite` triple.
*
* Tightening an authoring bound must not retroactively invalidate data that was
* accepted under the old one. A stored spec is rendered from the record verbatim
* (the preview never re-validates), so rejecting it on the way OUT would take
* Copy/Download away from a `ready` model whose only remedy is a paid
* regeneration — and machine-repairing it instead would silently un-mirror an
* asymmetric part or resize a collapsed one back into view. Neither is a repair
* this schema is entitled to make, so an existing record exports exactly as it
* renders, while the bound above keeps any NEW spec from acquiring the problem.
*/
export const storedThreejsSculptSpecSchema = makeSpecSchema(vec3Schema);
/**
* One canonical attachment list from the two forms a spec may declare.
*
* `attachmentPartIds` (the original, anchor-less form) and `attachments` (the
* anchored one) both mean "this part is carried", so every gate that reasons
* about attachments reads them through here rather than each picking a form and
* disagreeing with the next. An anchored entry wins over a bare id for the same
* part — the richer declaration is the one the author meant.
*
* @param {object|null} articulation a spec's `articulation` object, or null
* @returns {Array<{partId: string, anchorPartId: string|null, anchorSocket: string|null, maxOffset: number}>}
*/
export function resolveThreejsAttachments(articulation) {
const entries = new Map();
const bareIds = Array.isArray(articulation?.attachmentPartIds) ? articulation.attachmentPartIds : [];
for (const partId of bareIds) {
if (typeof partId !== 'string' || entries.has(partId)) continue;
entries.set(partId, { partId, anchorPartId: null, anchorSocket: null, maxOffset: DEFAULT_ATTACHMENT_MAX_OFFSET });
}
const anchored = Array.isArray(articulation?.attachments) ? articulation.attachments : [];
for (const attachment of anchored) {
if (typeof attachment?.partId !== 'string') continue;
entries.set(attachment.partId, {
partId: attachment.partId,
anchorPartId: attachment.anchorPartId ?? null,
anchorSocket: attachment.anchorSocket ?? null,
maxOffset: Number.isFinite(attachment.maxOffset) ? attachment.maxOffset : DEFAULT_ATTACHMENT_MAX_OFFSET,
});
}
return [...entries.values()];
}
/**
* Whether a resolved attachment names something to hang from at all.
* @param {{anchorPartId: string|null, anchorSocket: string|null}} attachment
* @returns {boolean}
*/
export const isThreejsAttachmentAnchored = (attachment) => (
Boolean(attachment?.anchorPartId) || Boolean(attachment?.anchorSocket)
);
const MAX_NAMES_IN_MESSAGE = 8;
/**
* Render a capped, comma-joined list of spec-level names (parts or features) for
* a finding message. Shared with `threejsModelCoverage.js` so both gates cap the
* same way — a finding that prints forty part names is one nobody reads.
*/
export const listSpecNames = (names) => (names.length > MAX_NAMES_IN_MESSAGE
? `${names.slice(0, MAX_NAMES_IN_MESSAGE).join(', ')} (+${names.length - MAX_NAMES_IN_MESSAGE} more)`
: names.join(', '));
// Cross-section gate. A spec can match its reference head-on — silhouette,
// colour zones, part count — and still be a diorama of cardboard cut-outs:
// every load-bearing part a planar extrusion on its own depth plane, correct
// from the generated camera and hollow the moment the user orbits. Neither the
// schema nor the assembly-coverage gate sees it, because a slab is well-formed
// geometry that implements exactly the detail it claims.
//
// Evidence of form is PLANE count, not triangle count: a fan of four hundred
// triangles sharing one Z value has no profile at all. So a `custom` mesh is
// slab-like when its thinnest axis carries fewer distinct coordinates than a
// curved surface needs to read as curved (or when the cloud has no volume in
// any orientation), and an `extrude` with no bevel thickness is one by
// construction — its sweep has exactly two depth planes no matter how many
// `steps` subdivide the side walls.
//
// Honest limit: a genuinely three-dimensional but very coarse custom mesh (an
// eight-vertex box) also lands under the plane threshold. That shape is already
// against the prompt's guidance — `box` exists — so the false positive only
// fires on geometry that should not have been custom triangles in the first
// place.
const SLAB_PLANE_THRESHOLD = 11;
// Planes are quantized relative to the mesh's own size rather than in absolute
// units: a fixed 1e-3 grid would report a 0.005-unit detail mesh as having five
// planes on every axis no matter how round it is, so the gate would punish
// small parts for being small. A thousandth of the largest extent asks the
// scale-free question the gate actually means — does this axis carry structure
// at the scale of the part itself.
const RELATIVE_PLANE_QUANTUM = 1e-3;
// Plane counting is axis-aligned, which a cut-out whose ROTATION was baked into
// its vertices (rather than carried by the part's `rotationDegrees`) slips past
// — turned 45°, a single flat fan samples a distinct value on all three axes. A
// point cloud with no volume is flat in every orientation, so the covariance
// determinant, normalized by the mean variance so it is scale-free, catches
// that case however the mesh is turned. The bound is deliberately strict: only
// an essentially zero-thickness cloud qualifies, leaving thin-but-real parts to
// the plane count above rather than double-jeopardy here.
const COPLANAR_DETERMINANT = 1e-6;
// An extrude can represent a membrane only when its sweep is negligible at the
// scale of its outline. Keep this relative so the declaration works for both a
// small fin and a large cape, while a positive-depth plate remains a solid slab.
const OPEN_SHELL_DEPTH_RATIO = 1e-3;
// Aggregate, never per-part: `extrude` is the RIGHT answer for a plate, a badge,
// or a sign, so a flat part is only evidence when the model's identity rides on
// it. The finding is "the load-bearing parts are predominantly flat", reported
// once the majority of buildable identity features are backed by nothing else.
const FLAT_IDENTITY_RATIO_THRESHOLD = 0.6;
const axisBounds = (vertices, axis) => {
let min = Infinity;
let max = -Infinity;
for (let index = axis; index < vertices.length; index += 3) {
if (vertices[index] < min) min = vertices[index];
if (vertices[index] > max) max = vertices[index];
}
return [min, max];
};
const countAxisPlanes = (vertices) => {
const bounds = [0, 1, 2].map((axis) => axisBounds(vertices, axis));
const quantum = Math.max(...bounds.map(([min, max]) => max - min)) * RELATIVE_PLANE_QUANTUM;
// Every vertex sits on one point, so there is exactly one plane per axis.
if (!(quantum > 0)) return [1, 1, 1];
const axes = [new Set(), new Set(), new Set()];
// Bucketed from each axis's own minimum rather than the absolute coordinate,
// so the count is a property of the shape and not of where it was authored:
// a mesh built far from the origin divides a large offset by a small quantum
// and loses distinct planes to float resolution.
vertices.forEach((value, index) => {
const axis = index % 3;
axes[axis].add(Math.round((value - bounds[axis][0]) / quantum));
});
return axes.map((axis) => axis.size);
};
const isCoplanarCloud = (vertices) => {
const count = vertices.length / 3;
const mean = [0, 0, 0];
vertices.forEach((value, index) => { mean[index % 3] += value / count; });
let xx = 0; let yy = 0; let zz = 0; let xy = 0; let xz = 0; let yz = 0;
for (let index = 0; index < count; index += 1) {
const x = vertices[index * 3] - mean[0];
const y = vertices[(index * 3) + 1] - mean[1];
const z = vertices[(index * 3) + 2] - mean[2];
xx += (x * x) / count; yy += (y * y) / count; zz += (z * z) / count;
xy += (x * y) / count; xz += (x * z) / count; yz += (y * z) / count;
}
const determinant = (xx * ((yy * zz) - (yz * yz)))
- (xy * ((xy * zz) - (yz * xz)))
+ (xz * ((xy * yz) - (yy * xz)));
const meanVariance = (xx + yy + zz) / 3;
if (!(meanVariance > 0)) return true;
return Math.abs(determinant) / (meanVariance ** 3) < COPLANAR_DETERMINANT;
};
// Three.js composes a part's local transform as rotation * scale, then applies
// each ancestor's transform from the outside. Keeping the linear part here is
// enough for the relative thickness check and avoids making the server-side gate
// depend on Three.js just to answer a geometry question.
const partLinear = (part) => multiplyLinear(
rotationMatrix(part.rotationDegrees),
scaleLinear(part.scale),
);
const transformVertices = (vertices, matrix) => {
const transformed = [];
for (let index = 0; index + 2 < vertices.length; index += 3) {
transformed.push(...applyLinear(matrix, vertices.slice(index, index + 3)));
}
return transformed;
};
const isZeroThicknessGeometry = (geometry, worldLinear = IDENTITY_LINEAR) => {
if (!geometry) return false;
if (geometry.type === 'custom') {
const vertices = Array.isArray(geometry.vertices) ? geometry.vertices : [];
return vertices.length >= 9 && isCoplanarCloud(transformVertices(vertices, worldLinear));
}
if (geometry.type !== 'extrude') return false;
const outline = Array.isArray(geometry.outline) ? geometry.outline : [];
if (outline.length < 3 || !(geometry.depth > 0)) return false;
const xs = outline.map(([x]) => x);
const ys = outline.map(([, y]) => y);
const spanX = Math.max(...xs) - Math.min(...xs);
const spanY = Math.max(...ys) - Math.min(...ys);
const xSpan = spanX * vectorLength(applyLinear(worldLinear, [1, 0, 0]));
const ySpan = spanY * vectorLength(applyLinear(worldLinear, [0, 1, 0]));
const span = Math.max(xSpan, ySpan);
const thickness = geometry.depth * vectorLength(applyLinear(worldLinear, [0, 0, 1]));
return span > 0 && thickness > 0 && thickness / span <= OPEN_SHELL_DEPTH_RATIO;
};
const isSlabGeometry = (geometry) => {
if (!geometry) return false;
if (geometry.type === 'extrude') {
// `bevelEnabled` defaults to false in the schema, so a parsed spec always
// carries it; `!== true` also reads a stored spec that predates it. The
// thickness matters as much as the flag: a bevel of zero thickness adds no
// depth plane, and flipping the boolean alone is the cheapest way for a
// model to answer this gate without changing the geometry at all.
return geometry.bevelEnabled !== true || !(geometry.bevelThickness > 0);
}
if (geometry.type !== 'custom') return false;
const vertices = Array.isArray(geometry.vertices) ? geometry.vertices : [];
if (vertices.length < 9) return false;
return Math.min(...countAxisPlanes(vertices)) < SLAB_PLANE_THRESHOLD || isCoplanarCloud(vertices);
};
const collectMeshes = (part, out = []) => {
if (part.geometry) out.push(part);
for (const child of part.children || []) collectMeshes(child, out);
return out;
};
/**
* @param {object} spec a spec that has already passed `threejsSculptSpecSchema`
* @returns {{findings: Array, errorCount: number, warningCount: number, noteCount: number,
* identityDetailCount: number, flatIdentityDetailCount: number, flatRatio: number|null,
* slabPartIds: string[]}}
*/
export function evaluateThreejsFlatness(spec) {
const byId = new Map();
const worldLinearById = new Map();
const indexPart = (part, parentLinear = IDENTITY_LINEAR) => {
byId.set(part.id, part);
const worldLinear = multiplyLinear(parentLinear, partLinear(part));
worldLinearById.set(part.id, worldLinear);
for (const child of part.children || []) indexPart(child, worldLinear);
};
for (const part of spec?.parts || []) indexPart(part);
const details = Array.isArray(spec?.detailInventory) ? spec.detailInventory : [];
const slabPartIds = new Set();
const flatDetails = [];
let evaluated = 0;
for (const detail of details) {
if (detail.priority !== 'identity') continue;
const meshes = new Map();
for (const id of new Set(detail.implementationPartIds || [])) {
const part = byId.get(id);
if (!part) continue;
// A detail may point at a group whose children carry the geometry, and two
// of its ids may nest, so meshes are collected by id rather than counted.
for (const mesh of collectMeshes(part)) meshes.set(mesh.id, mesh);
}
// Nothing was built for this feature anywhere — that is the assembly-coverage
// gate's `unbuilt-detail`, and counting it here would let a spec that built
// almost nothing read as a flat one.
if (meshes.size === 0) continue;
evaluated += 1;
const implementing = [...meshes.values()];
if (!implementing.every((mesh) => isSlabGeometry(mesh.geometry))) continue;
flatDetails.push({
feature: detail.feature,
partIds: implementing.map((mesh) => mesh.id),
isIntentionalMembrane: implementing.every((mesh) => (
spec?.materials?.[mesh.material]?.side === 'double'
&& isZeroThicknessGeometry(mesh.geometry, worldLinearById.get(mesh.id))
)),
});
for (const mesh of implementing) slabPartIds.add(mesh.id);
}
// `null`, not 0: a spec with no buildable identity feature was not measured
// flat, it was not measured at all, and a 0 would read as a clean result.
const flatFeatures = flatDetails.map(({ feature }) => feature);
const intentionalMembraneDetails = flatDetails.filter(({ isIntentionalMembrane }) => isIntentionalMembrane);
const intentionalMembraneFeatures = intentionalMembraneDetails.map(({ feature }) => feature);
const unintentionalDetails = flatDetails.filter(({ isIntentionalMembrane }) => !isIntentionalMembrane);
const unintentionalFeatures = unintentionalDetails.map(({ feature }) => feature);
const intentionalMembranePartIds = new Set(intentionalMembraneDetails.flatMap(({ partIds }) => partIds));
const flatRatio = evaluated === 0 ? null : flatFeatures.length / evaluated;
const findings = [];
if (flatRatio !== null && flatRatio > FLAT_IDENTITY_RATIO_THRESHOLD) {
const nonMembraneFeatureCount = evaluated - intentionalMembraneDetails.length;
const nonMembraneFlatRatio = nonMembraneFeatureCount === 0
? 0
: unintentionalFeatures.length / nonMembraneFeatureCount;
if (intentionalMembraneFeatures.length > 0) {
findings.push({
code: 'flat-identity-parts',
severity: 'note',
partIds: [...intentionalMembranePartIds],
features: intentionalMembraneFeatures,
message: `${intentionalMembraneFeatures.length} of ${evaluated} identity-defining features are intentional membrane surfaces (zero-thickness open shells: ${listSpecNames(intentionalMembraneFeatures)}). Their materials are double-sided (side "double"), so they remain visible from both sides.`,
});
}
if (nonMembraneFlatRatio > FLAT_IDENTITY_RATIO_THRESHOLD) {
const offenders = [...new Set(unintentionalDetails.flatMap(({ partIds }) => partIds))];
findings.push({
code: 'flat-identity-parts',
severity: 'warning',
partIds: offenders,
features: unintentionalFeatures,
message: `${unintentionalFeatures.length} of ${nonMembraneFeatureCount} identity-defining features are built only from flat parts (${listSpecNames(offenders.map((id) => byId.get(id)?.name || id))}). The model will read as a projection the moment it is orbited — give the parts the subject's identity rides on a real cross-section instead of stacking unbevelled extrusions and planar triangle fans. If a part is genuinely a zero-thickness membrane, make its material double-sided (side "double") instead; do not use that declaration to avoid giving a solid part real depth.`,
});
}
}
const warningCount = findings.filter((finding) => finding.severity === 'warning').length;
const noteCount = findings.filter((finding) => finding.severity === 'note').length;
return {
findings,
errorCount: 0,
warningCount,
noteCount,
identityDetailCount: evaluated,
flatIdentityDetailCount: flatFeatures.length,
flatRatio,
slabPartIds: [...slabPartIds],
};
}
/**
* Default refinement feedback derived from a stored flatness result. Returns ''
* when the model has a cross-section, so the caller falls through to whatever
* other feedback it has.
*/
export function buildThreejsFlatnessFeedback(flatness) {
const warnings = (flatness?.findings || []).filter((finding) => finding.severity === 'warning');
if (warnings.length === 0) return '';
return [
'The previous pass failed the cross-section check — it reads as a flat projection rather than a solid:',
...warnings.map((finding, index) => `${index + 1}. ${finding.message}`),
'Rebuild those parts with genuine depth: compose them from primitives, or give an extrude a bevel, so the model holds up from any orbit angle. If a part is genuinely a zero-thickness membrane — such as a cape, leaf, fin, or wing — make its material double-sided (side "double") instead, but never use that declaration to avoid giving a solid part real depth.',
].join('\n');
}
// Material-plausibility gate. `threejsMaterialSchema` bounds every PBR channel
// to what Three.js itself accepts, which says nothing about whether the values
// describe the substance the material is named for: metalness 0.9 oak and
// transmission 1.0 steel both parse, and both light completely wrong.
//
// The priors below are per-family plausible ranges, keyed off tokens in the
// material's own id — the only name a material carries in the spec. Matching is
// deliberately conservative: a material keys a prior only when exactly ONE
// family's keywords appear in it, so an unrecognized id (`mat_primary`) or a
// genuinely mixed one (`wood_metal_trim`) produces no feedback rather than a
// wrong one. That trade is affordable because this gate NEVER clamps — a
// stylized model is entitled to break every prior here, and the only cost of a
// missed match is a skipped hint.
//
// Bounds are stated only where a family really constrains the channel, and only
// in the direction it constrains: `undefined` is "this family says nothing",
// which is different from a bound of 0. Channels left out entirely (thickness,
// iridescence, anisotropy, emissive) are art direction, not substance.
const MATERIAL_FAMILY_PRIORS = [
{
family: 'metal',
keywords: ['metal', 'metallic', 'steel', 'iron', 'chrome', 'brass', 'bronze', 'copper', 'aluminum', 'aluminium', 'silver', 'gold', 'gilt', 'titanium', 'pewter', 'nickel', 'alloy', 'gunmetal'],
// The one family with a metalness FLOOR: a bare metal surface that is not
// metallic is the single most common way a generated spec reads as plastic.
channels: { metalness: [0.6, 1], roughness: [0.02, 0.6], transmission: [0, 0.05], sheen: [0, 0.1] },
},
{
family: 'wood',
keywords: ['wood', 'wooden', 'timber', 'oak', 'walnut', 'birch', 'maple', 'pine', 'mahogany', 'teak', 'bamboo', 'plank', 'lumber'],
channels: { metalness: [0, 0.15], roughness: [0.35, 1], transmission: [0, 0.05], sheen: [0, 0.3] },
},
{
family: 'plastic',
keywords: ['plastic', 'abs', 'pvc', 'nylon', 'resin', 'acrylic', 'vinyl', 'polymer', 'polycarbonate'],
channels: { metalness: [0, 0.1], roughness: [0.05, 0.95], ior: [1.3, 1.8] },
},
{
family: 'glass',
keywords: ['glass', 'crystal', 'lens', 'glazing', 'pane', 'windshield', 'quartz'],
// The transmission floor is the point of this entry: opaque "glass" is the
// mirror image of the metalness case above.
channels: { metalness: [0, 0.1], roughness: [0, 0.35], transmission: [0.4, 1], ior: [1.3, 1.9] },
},
{
family: 'fabric',
keywords: ['fabric', 'cloth', 'cotton', 'linen', 'wool', 'velvet', 'silk', 'canvas', 'denim', 'textile', 'felt', 'upholstery', 'curtain'],
channels: { metalness: [0, 0.1], roughness: [0.5, 1], clearcoat: [0, 0.2], transmission: [0, 0.15] },
},
{
family: 'ceramic',
keywords: ['ceramic', 'porcelain', 'clay', 'terracotta', 'tile', 'earthenware'],
channels: { metalness: [0, 0.1], roughness: [0.03, 0.7], transmission: [0, 0.2], ior: [1.3, 1.9] },
},
{
family: 'rubber',
keywords: ['rubber', 'tire', 'tyre', 'tread', 'silicone', 'neoprene', 'gasket'],
channels: { metalness: [0, 0.1], roughness: [0.5, 1], clearcoat: [0, 0.2], transmission: [0, 0.05] },
},
{
family: 'stone',
keywords: ['stone', 'rock', 'granite', 'marble', 'concrete', 'cement', 'slate', 'brick', 'asphalt', 'sandstone'],
channels: { metalness: [0, 0.15], roughness: [0.3, 1], transmission: [0, 0.1] },
},
{
family: 'leather',
keywords: ['leather', 'suede', 'hide'],
channels: { metalness: [0, 0.1], roughness: [0.3, 0.95], transmission: [0, 0.05] },
},
{
family: 'paper',
keywords: ['paper', 'cardboard', 'carton', 'paperboard', 'parchment'],
channels: { metalness: [0, 0.1], roughness: [0.5, 1], transmission: [0, 0.2] },
},
];
// A keyword claimed by two families would silently resolve to whichever entry
// is declared last, which is exactly the confident-nonsense the ambiguity rule
// above exists to prevent — so a collision fails at import rather than at
// review time.
const MATERIAL_KEYWORD_FAMILIES = MATERIAL_FAMILY_PRIORS.reduce((map, prior) => {
for (const keyword of prior.keywords) {
const owner = map.get(keyword);
if (owner) throw new Error(`material family keyword "${keyword}" is claimed by both ${owner.family} and ${prior.family}`);
map.set(keyword, prior);
}
return map;
}, new Map());
// `basic` is unlit, so none of these channels reach the renderer at all; the
// physical-only ones are parsed for every type but only forwarded by
// `type: 'physical'` (see `createMaterial`). Reporting a channel that cannot
// affect the render would be a finding the user can do nothing useful with.
const MATERIAL_CHANNELS_BY_TYPE = {
basic: [],
standard: ['metalness', 'roughness'],
physical: ['metalness', 'roughness', 'clearcoat', 'ior', 'transmission', 'sheen'],
};
// The channels that read off an ENVIRONMENT rather than off the punctual lights:
// with nothing to reflect, a conductor renders near-black and transmission,
// clearcoat and iridescence do essentially nothing. Same type filter as above —
// `basic` is unlit and the physical-only channels are forwarded only by
// `type: 'physical'` — so the note never names a channel that could not have
// rendered anyway. The metalness threshold is the metal family's own floor: a
// dielectric with a little metalness has almost nothing to lose here.
const REFLECTIVE_METALNESS_FLOOR = 0.6;
const REFLECTIVE_CHANNELS_BY_TYPE = {
basic: [],
standard: ['metalness'],
physical: ['metalness', 'transmission', 'clearcoat', 'iridescence'],
};
// A channel counts as authored when it is above the floor its own absence would
// sit at: metalness has a real threshold, the rest are opt-in from zero.
const reflectiveChannelFloor = (channel) => (channel === 'metalness' ? REFLECTIVE_METALNESS_FLOOR : 0);
/**
* Split a spec identifier — a material id, a part name, a feature phrase — into
* lowercase word tokens, breaking on separators AND on camelCase boundaries so
* `oakTrim` and `oak_trim` tokenize the same. A trailing
* plural is folded in as an extra candidate token rather than replacing the
* original, so `planks` matches `plank` without `abs` losing its own keyword.
*/
const tokenizeSpecIdentifier = (id) => {
const words = String(id || '')
.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
.toLowerCase()
.split(/[^a-z0-9]+/)
.filter(Boolean);
const tokens = new Set(words);
for (const word of words) {
if (word.length > 3 && word.endsWith('s')) tokens.add(word.slice(0, -1));
}
return [...tokens];
};
/**
* The single family a material id names, or `null` when it names none or more
* than one. Ambiguity is deliberately NOT resolved by precedence — picking one
* of two competing substances is how a prior table starts producing confident
* nonsense.
*/
const matchMaterialFamily = (id) => {
const matched = new Set();
for (const token of tokenizeSpecIdentifier(id)) {
const prior = MATERIAL_KEYWORD_FAMILIES.get(token);
if (prior) matched.add(prior);
}
return matched.size === 1 ? [...matched][0] : null;
};
/**
* Report PBR channels whose values are implausible for the substance a material
* id names. Advisory ONLY — nothing here rewrites a spec, because a stylized
* model may legitimately break every prior in the table.
*
* @param {object} spec a spec that has already passed `threejsSculptSpecSchema`
* @returns {{findings: Array, errorCount: number, warningCount: number, noteCount: number,
* materialCount: number, matchedMaterialCount: number}}
*/
export function evaluateThreejsMaterialPlausibility(spec) {
const materials = (spec?.materials && typeof spec.materials === 'object') ? spec.materials : {};
const findings = [];
const unlitReflective = [];
const environment = resolveThreejsEnvironment(spec);
let matched = 0;
for (const [id, material] of Object.entries(materials)) {
if (environment.preset === 'none') {
const reflective = (REFLECTIVE_CHANNELS_BY_TYPE[material?.type] || REFLECTIVE_CHANNELS_BY_TYPE.standard)
.filter((channel) => {
const value = material?.[channel];
return typeof value === 'number' && Number.isFinite(value) && value > reflectiveChannelFloor(channel);
});
if (reflective.length > 0) unlitReflective.push({ id, channels: reflective });
}
const prior = matchMaterialFamily(id);
if (!prior) continue;
matched += 1;
const channels = MATERIAL_CHANNELS_BY_TYPE[material?.type] || MATERIAL_CHANNELS_BY_TYPE.standard;
const offenders = [];
for (const channel of channels) {
const range = prior.channels[channel];
const value = material?.[channel];
// A stored spec predating a channel reads back undefined — unevaluated,
// not out of range.
if (!range || typeof value !== 'number' || !Number.isFinite(value)) continue;
const [min, max] = range;
if (value >= min && value <= max) continue;
offenders.push({ channel, value, min, max });
}
if (offenders.length === 0) continue;
findings.push({
code: 'implausible-material-values',
severity: 'warning',
materialIds: [id],
family: prior.family,
channels: offenders,
message: `Material "${id}" reads as ${prior.family}, but ${offenders
.map(({ channel, value, min, max }) => `${channel} ${value} is outside the ${min}–${max} a ${prior.family} surface normally sits in`)
.join(', and ')}. Re-derive those channels from the substance (or rename the material if it is not ${prior.family} at all) — unless the look is deliberately stylized, in which case leave it.`,
});
}
// One finding per implausible material, so the warning tally is also the count
// of materials that failed — no separate tally that could disagree with it.
const warningCount = findings.length;
// One note for the whole spec rather than one per material: the remedy is a
// single spec-level choice, and repeating it per material would bury the
// substance warnings above it.
if (unlitReflective.length > 0) {
findings.push({
code: 'reflective-material-without-environment',
severity: 'note',
materialIds: unlitReflective.map((entry) => entry.id),
channels: unlitReflective,
message: `${listSpecNames(unlitReflective.map((entry) => entry.id))} author reflective channels (${listSpecNames([...new Set(unlitReflective.flatMap((entry) => entry.channels))])}) while "environment.preset" is "none". Those channels read off an environment, so in this scene a conductor renders near-black and transmission, clearcoat and iridescence do essentially nothing — the values cannot be judged as authored. Give the spec an environment ("neutral" or "studio") to see them.`,
});
}
return {
findings,
errorCount: 0,
warningCount,
noteCount: findings.length - warningCount,
materialCount: Object.keys(materials).length,
matchedMaterialCount: matched,
};
}
/**
* Default refinement feedback derived from a stored material-plausibility
* result: the substance warnings, then the unlit-reflective note if the spec
* authored reflective channels with no environment. Returns '' when there is
* neither, so the caller falls through to whatever other feedback it has.
*/
export function buildThreejsMaterialFeedback(plausibility) {
const findings = plausibility?.findings || [];
const warnings = findings.filter((finding) => finding.severity === 'warning');
const substance = warnings.length === 0 ? [] : [
'The previous pass gave some materials values that do not match the substance they are named for:',
...warnings.map((finding, index) => `${index + 1}. ${finding.message}`),
'Set each channel from what the surface actually is — bare metal is metallic and fairly smooth, wood and stone are rough dielectrics, glass transmits — and keep any deliberate stylization you still want.',
];
// The unlit-reflective note is fed back as well as displayed: choosing an
// environment preset is a change the next pass can actually make, and leaving
// it out is what lets a refinement "fix" a black conductor by dropping its
// metalness instead.
const unlit = findings.filter((finding) => finding.code === 'reflective-material-without-environment');
return [...substance, ...unlit.map((finding) => finding.message)].join('\n');
}
// Swept-arc curvature gate. A generated spec routinely DECLARES a curved feature
// — a horn, a tail, a hook, a bent conduit — and then implements it with a
// straight run of control points. Every bounds-based check is blind to that: the
// bounding box of a straight tube is a perfectly reasonable box, nothing
// penetrates anything, the part touches its parent, and the silhouette from the
// generated camera can even be right. Only the SHAPE of the swept path says the
// horn does not curve.
//
// Two different measurements, because the two sweep geometries carry their
// curvature in different places:
//
// * `tube` sweeps a circle along an explicit list of control points, so the
// curvature lives in that polyline. The points are fitted to their best-fit
// plane and then to a circle within it, and the path counts as curved when it
// rides that circle — a fit its points really lie on, spanning a minimum
// angle, with the centre a bounded distance from the path — or, for a bend
// that rides no single circle at all, when its excursion from its own
// best-fit line is large enough to see. Each bound below rejects a different
// degenerate fit.
// * `extrude` sweeps a closed outline along a STRAIGHT axis, so there is no
// sweep path to fit an arc to — and a closed ring is useless as one, since it
// has no endpoints and always turns a full 360°. Its curvature is in the
// outline's silhouette instead: a curved form (crescent, hook, claw) has a
// concave side, while a straight tapered spike is convex however finely it is
// subdivided. So the outline is measured by how much of its turning is
// concave.
//
// Both gates fire only on a part the spec itself declares curved — by name, or
// through a `detailInventory` feature that names it. `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 something says it was meant to
// bend.
// How far a path has to turn to read as a curve rather than as authoring slack.
// The travel is accumulated as an ABSOLUTE sum per segment rather than as the
// signed range about the fitted centre: an S-curved tail sweeps one way and then
// back, and a signed range would cancel those halves and report a genuinely
// curved path as straight.
export const SWEPT_ARC_MIN_SPAN_DEGREES = 25;
// Absolute accumulation means authoring noise ADDS UP instead of cancelling, so
// a jittered straight run reaches the span threshold without ever bending. A
// span is therefore only credited when the points actually LIE on the circle
// that was fitted to them, measured as RMS radial error against its radius.
const SWEPT_ARC_MAX_RADIAL_ERROR_RATIO = 0.05;
// And the fitted circle has to sit alongside the path rather than out at
// infinity: an arc riding one circle puts its centre about a radius away, which
// at 25° of span is 2.25 times the path's own extent. For a clean fit this
// agrees with the span bound by construction — it is the bound that still holds
// when the fit is only approximate, and the span it produced cannot be trusted
// on its own.
const SWEPT_ARC_MAX_CENTER_DISTANCE_RATIO = 3;
// An arc fit answers "does this ride ONE circle", which an S-curved tail and a
// sharply kinked hook both fail while being obviously not straight. So bending
// is also measured directly, as the path's largest excursion from its own
// best-fit line relative to its extent — the one measure that survives a path
// with no single centre at all.
const SWEPT_PATH_MIN_SAGITTA_RATIO = 0.05;
// A crescent's concave (inner) boundary turns back through about the same angle
// its outer boundary sweeps, so the outline threshold is the arc threshold.
export const CURVED_OUTLINE_MIN_CONCAVE_TURN_DEGREES = 25;
// Concavity has to be SUSTAINED, not merely present. Summed over the whole ring,
// a single deep V-notch at the base of an otherwise straight spike buys hundreds
// of degrees, and serrated, stepped, and slotted silhouettes are common — so the
// gate would pass exactly the straight claw it exists to catch. A run of concave
// vertices only counts when the boundary it governs is a real stretch of the
// outline rather than a nick in it.
const CONCAVE_RUN_MIN_LENGTH_RATIO = 0.25;
// Tokens that declare a form which has to bend to read as itself. Deliberately
// narrow, because this text is fed back into the next refinement pass: a false
// positive does not merely add noise, it TELLS the provider to bend a part that
// was right to be straight.
//
// So a noun earns a bare place here only when a straight version of the part
// would be wrong. "pipe", "rod", "trunk", "tail", "whisker", "bow", and "barb"
// are all absent — a tail boom runs down a fuselage, a tail fin is a flat plate,
// and a whisker is a straight bristle — and they declare a curve only through a
// modifier that is itself on the list, which is why "curved tail" and "coiled
// tail" still match. Bare "arc" and "hoop" are absent for a different reason: an
// "arcReactor" is a disc, and a hoop authored as an extruded ring has a convex
// outline with the curve in its HOLE, so both would report a correct build as
// the defect.
const CURVED_FORM_TOKENS = new Set([
'horn', 'antler', 'tusk', 'fang', 'claw', 'talon', 'pincer', 'mandible',
'tentacle', 'hook', 'crook',
'curve', 'curved', 'curving', 'curl', 'curled', 'coil', 'coiled', 'spiral',
'bend', 'bent', 'arced', 'arch', 'arched', 'bowed',
'crescent', 'scythe', 'sickle', 'elbow',
]);
/**
* True when an identifier names a form that has to bend. Reuses the material
* tokenizer so `hornLeft`, `horn_left`, and `Horns` all match.
*/
const namesCurvedForm = (identifier) => tokenizeSpecIdentifier(identifier)
.some((token) => CURVED_FORM_TOKENS.has(token));
const crossProduct = (a, b) => [
(a[1] * b[2]) - (a[2] * b[1]),
(a[2] * b[0]) - (a[0] * b[2]),
(a[0] * b[1]) - (a[1] * b[0]),
];
/**
* The eigenvector of the smallest eigenvalue of a symmetric 3x3 covariance —
* the best-fit plane's normal. Closed-form rather than iterative: a path carries
* at most 96 points and the audit runs on every refinement pass.
*
* @param {number[]} covariance `[xx, yy, zz, xy, xz, yz]`
*/
const smallestEigenvector = ([xx, yy, zz, xy, xz, yz]) => {
const offDiagonal = (xy * xy) + (xz * xz) + (yz * yz);
const mean = (xx + yy + zz) / 3;
let smallest;
if (offDiagonal <= 0) {
smallest = Math.min(xx, yy, zz);
} else {
const spread = ((xx - mean) ** 2) + ((yy - mean) ** 2) + ((zz - mean) ** 2) + (2 * offDiagonal);
const scale = Math.sqrt(spread / 6);
const b = [
(xx - mean) / scale, xy / scale, xz / scale,
xy / scale, (yy - mean) / scale, yz / scale,
xz / scale, yz / scale, (zz - mean) / scale,
];
const determinant = (b[0] * ((b[4] * b[8]) - (b[5] * b[7])))
- (b[1] * ((b[3] * b[8]) - (b[5] * b[6])))
+ (b[2] * ((b[3] * b[7]) - (b[4] * b[6])));
const phi = Math.acos(Math.min(1, Math.max(-1, determinant / 2))) / 3;
const first = mean + (2 * scale * Math.cos(phi));
const third = mean + (2 * scale * Math.cos(phi + ((2 * Math.PI) / 3)));
smallest = Math.min(first, third, (3 * mean) - first - third);
}
// The null space of (covariance - smallest * I): every pair of its rows spans
// the plane, so their cross product is the normal. The longest one is taken
// because a near-degenerate pair produces numerical dust.
const rows = [
[xx - smallest, xy, xz],
[xy, yy - smallest, yz],
[xz, yz, zz - smallest],
];
let normal = null;
let longest = 0;
for (let i = 0; i < 3; i += 1) {
for (let j = i + 1; j < 3; j += 1) {
const candidate = crossProduct(rows[i], rows[j]);
const length = vectorLength(candidate);
if (length > longest) {
longest = length;
normal = candidate;
}
}
}
return longest > 0 ? normal.map((value) => value / longest) : [0, 0, 1];
};
/**
* Least-squares circle through 2D points (Kasa). Returns `null` when the points
* are collinear, where the normal equations are singular and any "circle"
* through them is an artifact of float noise.
*/
const fitCircle2D = (points) => {
const count = points.length;
const meanX = points.reduce((total, [x]) => total + x, 0) / count;
const meanY = points.reduce((total, [, y]) => total + y, 0) / count;
let suu = 0; let svv = 0; let suv = 0; let suuu = 0; let svvv = 0; let suvv = 0; let svuu = 0;
for (const [x, y] of points) {
const u = x - meanX;
const v = y - meanY;
suu += u * u; svv += v * v; suv += u * v;
suuu += u * u * u; svvv += v * v * v;
suvv += u * v * v; svuu += v * u * u;
}
const determinant = (suu * svv) - (suv * suv);
// Relative, not absolute: the same collinear path authored in millimetres and
// in metres must both read as collinear.
if (Math.abs(determinant) <= ((suu + svv) ** 2) * 1e-12) return null;
const rhsU = (suuu + suvv) / 2;
const rhsV = (svvv + svuu) / 2;
const centerU = ((rhsU * svv) - (rhsV * suv)) / determinant;
const centerV = ((rhsV * suu) - (rhsU * suv)) / determinant;
return {
center: [meanX + centerU, meanY + centerV],
radius: Math.sqrt((centerU * centerU) + (centerV * centerV) + ((suu + svv) / count)),
centroid: [meanX, meanY],
};
};
/**
* The largest perpendicular excursion of 2D points from their own best-fit
* line. Straightness measured directly, so a path that bends without riding any
* single circle still reads as bent.
*/
const maxDeviationFromBestFitLine = (points) => {
const meanX = points.reduce((total, [x]) => total + x, 0) / points.length;
const meanY = points.reduce((total, [, y]) => total + y, 0) / points.length;
let sxx = 0; let syy = 0; let sxy = 0;
for (const [x, y] of points) {
sxx += (x - meanX) ** 2;
syy += (y - meanY) ** 2;
sxy += (x - meanX) * (y - meanY);
}
// The principal direction of a symmetric 2x2 scatter, in closed form.
const angle = Math.atan2(2 * sxy, sxx - syy) / 2;
const normal = [-Math.sin(angle), Math.cos(angle)];
return points.reduce((widest, [x, y]) => Math.max(
widest,
Math.abs(((x - meanX) * normal[0]) + ((y - meanY) * normal[1])),
), 0);
};
/**
* Measure how far a swept path actually bends.
*
* The points are projected onto their own best-fit plane and fitted to a circle
* there. The path is credited as curved when it rides that circle — a fit its
* points really lie on, spanning a minimum angle, with the centre a bounded
* distance from the path — OR, for a bend that rides no single circle, when its
* excursion from its own best-fit line is large enough to see.
*
* @param {Array<number[]>} points ordered `[x, y, z]` control points
* @returns {{straight: boolean, collinear: boolean, arcSpanDegrees: number,
* radius: number|null, centerDistanceRatio: number|null,
* radialErrorRatio: number|null, sagittaRatio: number, extent: number}}
*/
export function evaluateSweptArcCurvature(points) {
const usable = (Array.isArray(points) ? points : [])
.filter((point) => Array.isArray(point) && point.length === 3 && point.every(Number.isFinite));
const straightResult = (extent) => ({
straight: true,
collinear: true,
arcSpanDegrees: 0,
radius: null,
centerDistanceRatio: null,
radialErrorRatio: null,
sagittaRatio: 0,
extent,
});
const separation = (a, b) => vectorLength(b.map((value, axis) => value - a[axis]));
// Two points ARE a straight segment, and an exactly collinear run of any
// length sweeps one too — no fit is needed, and none would be meaningful.
if (usable.length < 3) return straightResult(usable.length === 2 ? separation(usable[0], usable[1]) : 0);
if (isCollinearPath(usable)) return straightResult(separation(usable[0], usable[usable.length - 1]));
const centroid = [0, 1, 2].map((axis) => usable.reduce((total, point) => total + point[axis], 0) / usable.length);
const offsets = usable.map((point) => point.map((value, axis) => value - centroid[axis]));
const covariance = [0, 0, 0, 0, 0, 0];
for (const [x, y, z] of offsets) {
covariance[0] += (x * x) / offsets.length;
covariance[1] += (y * y) / offsets.length;
covariance[2] += (z * z) / offsets.length;
covariance[3] += (x * y) / offsets.length;
covariance[4] += (x * z) / offsets.length;
covariance[5] += (y * z) / offsets.length;
}
const normal = smallestEigenvector(covariance);
// Any seed not parallel to the normal spans the plane with it; the axis with
// the smallest component is the one guaranteed not to be.
const seed = Math.abs(normal[0]) < 0.9 ? [1, 0, 0] : [0, 1, 0];
const uAxis = crossProduct(normal, seed);
const uLength = vectorLength(uAxis);
const u = uLength > 0 ? uAxis.map((value) => value / uLength) : [1, 0, 0];
const v = crossProduct(normal, u);
const projected = offsets.map((offset) => [
(offset[0] * u[0]) + (offset[1] * u[1]) + (offset[2] * u[2]),
(offset[0] * v[0]) + (offset[1] * v[1]) + (offset[2] * v[2]),
]);
let extent = 0;
for (let i = 0; i < projected.length; i += 1) {
for (let j = i + 1; j < projected.length; j += 1) {
extent = Math.max(extent, Math.hypot(projected[i][0] - projected[j][0], projected[i][1] - projected[j][1]));
}
}
if (!(extent > 0)) return straightResult(extent);
const sagittaRatio = maxDeviationFromBestFitLine(projected) / extent;
const circle = fitCircle2D(projected);
if (!circle) {
return {
straight: sagittaRatio < SWEPT_PATH_MIN_SAGITTA_RATIO,
collinear: false,
arcSpanDegrees: 0,
radius: null,
centerDistanceRatio: null,
radialErrorRatio: null,
sagittaRatio,
extent,
};
}
// Per-segment and absolute, so an S-curve accumulates its two opposing bends
// instead of cancelling them. Safe to sum unsigned only because the radial
// error below refuses to credit a span the points did not trace.
let arcSpanRadians = 0;
for (let index = 1; index < projected.length; index += 1) {
const previous = Math.atan2(projected[index - 1][1] - circle.center[1], projected[index - 1][0] - circle.center[0]);
const current = Math.atan2(projected[index][1] - circle.center[1], projected[index][0] - circle.center[0]);
let step = current - previous;
while (step > Math.PI) step -= 2 * Math.PI;
while (step < -Math.PI) step += 2 * Math.PI;
arcSpanRadians += Math.abs(step);
}
const arcSpanDegrees = (arcSpanRadians * 180) / Math.PI;
const squaredRadialError = projected.reduce((total, [x, y]) => {
const deviation = Math.hypot(x - circle.center[0], y - circle.center[1]) - circle.radius;
return total + ((deviation * deviation) / projected.length);
}, 0);
const radialErrorRatio = Math.sqrt(squaredRadialError) / circle.radius;
const centerDistanceRatio = Math.hypot(
circle.center[0] - circle.centroid[0],
circle.center[1] - circle.centroid[1],
) / extent;
const ridesArc = radialErrorRatio <= SWEPT_ARC_MAX_RADIAL_ERROR_RATIO
&& arcSpanDegrees >= SWEPT_ARC_MIN_SPAN_DEGREES
&& centerDistanceRatio <= SWEPT_ARC_MAX_CENTER_DISTANCE_RATIO;
return {
straight: !ridesArc && sagittaRatio < SWEPT_PATH_MIN_SAGITTA_RATIO,
collinear: false,
arcSpanDegrees,
radius: circle.radius,
centerDistanceRatio,
radialErrorRatio,
sagittaRatio,
extent,
};
}
/**
* The largest SUSTAINED concave turn in a closed outline, in degrees: the
* longest unbroken run of concave vertices whose stretch of boundary is a real
* fraction of the outline's own size. A convex ring returns 0; a crescent
* returns roughly the arc its inner boundary sweeps; a notch or a serration in
* an otherwise straight silhouette returns 0 however deep it is cut.
*
* @param {Array<number[]>} ring ordered `[x, y]` outline points
*/
export function measureOutlineConcaveTurn(ring) {
const points = (Array.isArray(ring) ? ring : [])
.filter((point) => Array.isArray(point) && point.length === 2 && point.every(Number.isFinite));
if (points.length < 3) return 0;
const segmentLength = (index) => {
const current = points[index];
const next = points[(index + 1) % points.length];
return Math.hypot(next[0] - current[0], next[1] - current[1]);
};
const turns = points.map((current, index) => {
const previous = points[(index - 1 + points.length) % points.length];
const next = points[(index + 1) % points.length];
const incoming = [current[0] - previous[0], current[1] - previous[1]];
const outgoing = [next[0] - current[0], next[1] - current[1]];
return Math.atan2(
(incoming[0] * outgoing[1]) - (incoming[1] * outgoing[0]),
(incoming[0] * outgoing[0]) + (incoming[1] * outgoing[1]),
);
});
// A simple ring turns through a full circle exactly once, so the sign of the
// total is its winding — measured from the turns themselves rather than from a
// signed area, so the two can never disagree about which side is concave.
const winding = turns.reduce((total, turn) => total + turn, 0) >= 0 ? 1 : -1;
const xs = points.map(([x]) => x);
const ys = points.map(([, y]) => y);
const extent = Math.hypot(Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys));
if (!(extent > 0)) return 0;
// Walked over two laps so a run straddling the start of the array is measured
// whole rather than split into two short ones.
let runTurn = 0;
let runLength = 0;
let widest = 0;
for (let step = 0; step < points.length * 2; step += 1) {
const index = step % points.length;
const concave = -turns[index] * winding;
if (concave > 0) {
// The boundary a concave vertex governs runs from the segment arriving at
// it to the segment leaving it, so a run picks up its leading segment once.
if (runTurn === 0) runLength += segmentLength((index - 1 + points.length) % points.length);
runTurn += concave;
runLength += segmentLength(index);
if (runLength >= extent * CONCAVE_RUN_MIN_LENGTH_RATIO) {
widest = Math.max(widest, runTurn);
}
} else {
runTurn = 0;
runLength = 0;
}
}
return (widest * 180) / Math.PI;
}
/**
* Measure whichever sweep geometry this is, using the measure that geometry
* carries its curvature in. Returns `null` for anything this gate cannot speak
* about — a straight `box` rail named "elbowBracket", a closed tube, an extrude
* whose curve may live in a hole — so a caller can tell "measured and straight"
* from "not measurable".
*/
export function evaluateSweptGeometryCurvature(geometry) {
if (geometry?.type === 'tube') {
// A closed tube is a loop: the schema already refuses a collinear one, and a
// loop has no endpoints for an arc span to mean anything between.
if (geometry.closed === true) return null;
const curvature = evaluateSweptArcCurvature(geometry.path);
return { kind: 'tube', straight: curvature.straight, arcSpanDegrees: curvature.arcSpanDegrees };
}
if (geometry?.type === 'extrude') {
// A ring, an arch, and a slotted plate all put their curve in a HOLE, and a
// hole leaves the outline convex, so an outline measurement would report the
// canonical build as the defect. There is no measurement here that separates
// those from a straight spike with a cutout, so the gate declines to speak.
if ((geometry.holes || []).length > 0) return null;
const concaveTurnDegrees = measureOutlineConcaveTurn(geometry.outline);
return {
kind: 'extrude',
straight: concaveTurnDegrees < CURVED_OUTLINE_MIN_CONCAVE_TURN_DEGREES,
concaveTurnDegrees,
};
}
return null;
}
/**
* Parts the spec declares as curved forms, keyed by part id, with the name or
* feature phrase that declared it. A `detailInventory` feature counts as a
* declaration, which is how a part called `part_17` still gets measured when the
* feature it builds is "curved brass horn".
*
* Only declarations that name ONE sweep are returned. A curved form built from
* several parts — a tail of five tapered segments, a horn split into a base and
* a tip — curves by ARRANGEMENT, and every piece of it is legitimately straight,
* so measuring the pieces would report the correct build as the defect. That is
* why a segment nested under an already-declared part is skipped, why a part
* that owns sweep-carrying children is skipped even when it carries a sweep of
* its own (its geometry is the base of an assembly, not the whole curve), and
* why a feature implementing itself with more than one sweep is skipped too.
*/
export function collectDeclaredCurvedParts(spec) {
const declared = new Map();
const byId = new Map();
const declare = (partId, declaredBy) => {
if (!declared.has(partId)) declared.set(partId, declaredBy);
};
const hasSweepDescendant = (part) => (part.children || []).some((child) => (
evaluateSweptGeometryCurvature(child.geometry) || hasSweepDescendant(child)
));
const walk = (parts, ancestorDeclared) => {
for (const part of parts || []) {
byId.set(part.id, part);
const name = part.name || part.id;
const isDeclared = namesCurvedForm(name);
if (isDeclared && !ancestorDeclared && !hasSweepDescendant(part)) declare(part.id, name);
walk(part.children, ancestorDeclared || isDeclared);
}
};
walk(spec?.parts, false);
for (const detail of spec?.detailInventory || []) {
if (!namesCurvedForm(detail.feature)) continue;
const sweeps = (detail.implementationPartIds || [])
.filter((partId) => evaluateSweptGeometryCurvature(byId.get(partId)?.geometry));
if (sweeps.length !== 1) continue;
declare(sweeps[0], detail.feature);
}
return declared;
}
const toIdentifier = (name) => {
const words = String(name || 'Procedural').replace(/[^A-Za-z0-9]+/g, ' ').trim().split(/\s+/).filter(Boolean);
const joined = words.map((word) => word[0].toUpperCase() + word.slice(1)).join('') || 'Procedural';
return /^[A-Za-z]/.test(joined) ? joined : `Model${joined}`;
};
/**
* Deterministically package a validated scene spec as a standalone Three.js
* Group factory. No model-authored JavaScript is executed by PortOS.
*/
export function buildThreejsFactorySource(input) {
// Exporting reads a STORED spec, so it validates against the read contract —
// an install's existing model stays downloadable even if it predates a bound.
// The parse still has to happen (the emitted source must be well-formed), and
// a raw ZodError would normalize to an opaque 500 saying nothing a user can act
// on, so `failValidation` names the offending path in a 400 instead.
const parsed = storedThreejsSculptSpecSchema.safeParse(input);
if (!parsed.success) failValidation(parsed);
const spec = parsed.data;
const factoryName = `create${toIdentifier(spec.name)}Model`;
const serialized = JSON.stringify(spec, null, 2);
// The renderer contract the spec was composed against. Serialized rather than
// derived in the emitted source, because the colour-management half of it is
// PortOS's viewer contract and is not in the spec at all.
const renderProfile = JSON.stringify(
{ ...THREEJS_RENDER_PROFILE, environment: resolveThreejsEnvironment(spec) },
null,
2
);
return `// Generated by PortOS Three.js Models.
// Procedural image-to-Three.js workflow inspired by https://github.com/hoainho/img2threejs
import * as THREE from 'three';
const spec = ${serialized};
// The renderer settings this model was authored against. Configure your own
// WebGLRenderer and scene to match, or it will not reproduce: without the
// environment its metals have nothing to reflect, and a different tone map or
// exposure changes every value on screen. Data only — this module builds no
// renderer, and the environment preset is yours to construct.
const renderProfile = ${renderProfile};
const radians = (degrees) => THREE.MathUtils.degToRad(degrees);
const rotation = (value) => value.map(radians);
function createGeometry(definition) {
switch (definition.type) {
case 'box':
return new THREE.BoxGeometry(definition.width, definition.height, definition.depth);
case 'sphere':
return new THREE.SphereGeometry(definition.radius, definition.widthSegments, definition.heightSegments);
case 'cylinder':
return new THREE.CylinderGeometry(definition.radiusTop, definition.radiusBottom, definition.height, definition.radialSegments);
case 'cone':
return new THREE.ConeGeometry(definition.radius, definition.height, definition.radialSegments);
case 'torus':
return new THREE.TorusGeometry(definition.radius, definition.tube, definition.radialSegments, definition.tubularSegments, radians(definition.arcDegrees));
case 'capsule':
return new THREE.CapsuleGeometry(definition.radius, definition.length, definition.capSegments, definition.radialSegments);
case 'lathe':
return new THREE.LatheGeometry(definition.points.map(([x, y]) => new THREE.Vector2(x, y)), definition.segments);
case 'extrude': {
const shape = new THREE.Shape(definition.outline.map(([x, y]) => new THREE.Vector2(x, y)));
for (const hole of definition.holes) {
shape.holes.push(new THREE.Path(hole.map(([x, y]) => new THREE.Vector2(x, y))));
}
return new THREE.ExtrudeGeometry(shape, {
depth: definition.depth,
bevelEnabled: definition.bevelEnabled,
bevelThickness: definition.bevelThickness,
bevelSize: definition.bevelSize,
bevelSegments: definition.bevelSegments,
curveSegments: definition.curveSegments,
steps: definition.steps,
});
}
case 'tube': {
const curve = new THREE.CatmullRomCurve3(
definition.path.map(([x, y, z]) => new THREE.Vector3(x, y, z)),
definition.closed,
definition.curveType,
definition.tension
);
return new THREE.TubeGeometry(curve, definition.tubularSegments, definition.radius, definition.radialSegments, definition.closed);
}
case 'custom': {
const geometry = new THREE.BufferGeometry();
geometry.setAttribute('position', new THREE.Float32BufferAttribute(definition.vertices, 3));
geometry.setIndex(definition.indices);
geometry.computeVertexNormals();
geometry.computeBoundingSphere();
return geometry;
}
default:
throw new Error(\`Unsupported geometry type: \${definition.type}\`);
}
}
function createMaterial(definition) {
const doubleSided = definition.side === 'double' ? { side: THREE.DoubleSide } : {};
const unlit = {
color: definition.color,
opacity: definition.opacity,
transparent: definition.transparent,
wireframe: definition.wireframe,
...doubleSided,
};
if (definition.type === 'basic') {
return new THREE.MeshBasicMaterial(unlit);
}
const lit = {
...unlit,
metalness: definition.metalness,
roughness: definition.roughness,
emissive: definition.emissive,
emissiveIntensity: definition.emissiveIntensity,
// The spec's environment intensity, so the reflective channels below read at
// the strength they were authored at once you assign the environment.
envMapIntensity: renderProfile.environment.intensity,
};
if (definition.type === 'physical') {
return new THREE.MeshPhysicalMaterial({
...lit,
clearcoat: definition.clearcoat,
clearcoatRoughness: definition.clearcoatRoughness,
ior: definition.ior,
transmission: definition.transmission,
thickness: definition.thickness,
sheen: definition.sheen,
iridescence: definition.iridescence,
anisotropy: definition.anisotropy,
});
}
return new THREE.MeshStandardMaterial(lit);
}
function createPart(definition, materials, nodes) {
const node = definition.geometry
? new THREE.Mesh(createGeometry(definition.geometry), materials[definition.material])
: new THREE.Group();
node.name = definition.name;
node.position.set(...definition.position);
node.rotation.set(...rotation(definition.rotationDegrees));
node.scale.set(...definition.scale);
node.castShadow = definition.castShadow;
node.receiveShadow = definition.receiveShadow;
// Carried through so a standalone consumer of the exported factory can build
// the same disassembly the PortOS preview does: relief rides its parent.
node.userData.partId = definition.id;
node.userData.explodeWithParent = definition.explodeWithParent;
nodes[definition.id] = node;
for (const child of definition.children) node.add(createPart(child, materials, nodes));
return node;
}
export function ${factoryName}() {
const root = new THREE.Group();
root.name = spec.name;
const materials = Object.fromEntries(
Object.entries(spec.materials).map(([id, definition]) => [id, createMaterial(definition)])
);
const nodes = {};
for (const part of spec.parts) root.add(createPart(part, materials, nodes));
root.userData.sculptRuntime = {
schemaVersion: spec.schemaVersion,
subjectType: spec.subjectType,
nodes,
sockets: spec.sockets,
// Declared articulation intent, or null when the spec has none — the parse
// above is what makes this trustworthy, so a consumer reads a graph that is
// known single-rooted, acyclic, and pointed at real parts and sockets. It is
// NOT a skeleton: nothing here is skinned, bound, or deformed.
articulation: spec.articulation || null,
// Declared clips, or null for a static assembly. Data only: the parse above
// proves every sequence names a real part, stays inside its clip, and never
// fights another sequence for the same channel, so createSculptAnimationPlayer
// below can drive the nodes above from it — PortOS-authored playback over
// provider-authored DATA, never anything the provider wrote as code.
animation: spec.animation || null,
detailInventory: spec.detailInventory,
limitations: spec.limitations,
// The renderer contract above, carried on the model so a consumer that only
// ever sees the Group still knows what it has to match to reproduce it.
render: renderProfile,
};
return root;
}
${THREEJS_PLAYER_SOURCE}
export { spec, renderProfile };
`;
}