Skip to content

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

refactor: share the clip pose evaluator between the preview and the audit (#12264)

[._.]/ Adam Eivya961be03c1b8
diff --git a/client/src/lib/README.md b/client/src/lib/README.md
index 320255635e..d83fd39a0a 100644
--- a/client/src/lib/README.md
+++ b/client/src/lib/README.md
@@ -287,7 +287,7 @@ grep -i "what you want to do" client/src/lib/README.md
| `threeVendorImportMap.js` | Inlines the vendored three.js modules into a Code Animation page for the sandboxed preview (#10464). `importsThree(html)` detects a bare `three` / `three/addons/*` import (mirrors the server's `threeVendor.js`); `buildThreeImportMap(files)` turns the `GET /api/code-animation/vendor/three` bundle into an import map of `data:` URLs (the opaque-origin iframe cannot fetch `./vendor/*.js`), rewriting the vendored files' relative imports to `three-vendor/<path>` ids; `inlineThreeVendor(html, files)` replaces any import map in the page with it. |
| `brainThreads.js` | Re-export of `server/lib/brainThreads.js` — Brain THREAD statuses, `isTerminalThreadStatus` / `isThreadOverdue`, `threadNextLine` and the server's list comparator `compareThreads`, so the Threads tab and the Open Threads widget group, badge and order rows exactly as `GET /api/brain/threads` does (a *thread* is a tracked open loop, never a message thread). |
| `threadRefKinds.js` | Re-export of `server/lib/threadRefKinds.js` — the Brain THREAD ref vocabulary and `(kind, id)` → label/URL route table (a *thread* is a tracked topic or commitment, never a message thread). Named exports only — `threadRefLabel`/`threadRefUrl` (what the client renders with) and `THREAD_REF_KIND_IDS` / `EXTERNAL_THREAD_REF_KINDS` (what the Threads tab's ref picker enumerates and how `ThreadRefChip` picks `<a>` over `<Link>`). `pages/CatalogIngredient.jsx` renders its inbound-ref chips through `threadRefUrl`/`threadRefLabel` here instead of its own local switch, so the repo has exactly one kind→route table. |
-| `threejsAnimation.js` | Pure pose evaluator for the declarative clip contract in `server/lib/threejsModel.js`, used by the Three.js Models preview transport. `evaluateThreejsClipPose(clip, timeSeconds)` → `{ timeSeconds, pose, activeSequenceIds, activePartIds }` where `pose` is a null-prototype partId → `{ position?, rotationDegrees?, scale?, opacity?, visible? }` map: each part+channel resolves from the one sequence that owns the instant (the window containing it, else the most recent behind it, else the next ahead), `visible` steps at the window's end rather than interpolating, and a part no sequence drives is absent so the spec renders as authored. `collectThreejsCues(clip, from, to)` returns the data-only sound cues a play loop crossed in the half-open `[from, to)` interval — a scrub calls it never, which is what makes scrubbing silent. `listThreejsClips` / `listThreejsCues` / `resolveThreejsClip` / `getThreejsClipDuration` read a spec that may have no `animation` key at all. |
+| `threejsAnimation.js` | Pure pose evaluator for the declarative clip contract in `server/lib/threejsModel.js`, used by the Three.js Models preview transport; the pose comes from the shared `server/lib/threejsModelClipPose.js` leaf the physical audit also measures. `evaluateThreejsClipPose(clip, timeSeconds)` → `{ timeSeconds, pose, activeSequenceIds, activePartIds }` where `pose` is a null-prototype partId → `{ position?, rotationDegrees?, scale?, opacity?, visible? }` map: each part+channel resolves from the one sequence that owns the instant (the window containing it, else the most recent behind it, else the next ahead), `visible` steps at the window's end rather than interpolating, and a part no sequence drives is absent so the spec renders as authored. `collectThreejsCues(clip, from, to)` returns the data-only sound cues a play loop crossed in the half-open `[from, to)` interval — a scrub calls it never, which is what makes scrubbing silent. `listThreejsClips` / `listThreejsCues` / `resolveThreejsClip` / `getThreejsClipDuration` read a spec that may have no `animation` key at all. |
| `threejsEnvironment.js` | Image-based lighting for the procedural sculpt spec, used by the Three.js Models preview. `spec.lights` are punctual — they light a surface but give it nothing to REFLECT, so `metalness`, `transmission`, `clearcoat` and `iridescence` read off an environment or read off nothing, and a plausible conductor renders near-black without one. `createSculptEnvironmentTarget(renderer, preset)` builds a preset locally from three's own primitives and prefilters it through `PMREMGenerator` — `neutral` is three's bundled `RoomEnvironment`, `studio` a dark shell with three emissive softbox panels plus a floor bounce — returning null for `none`; the caller owns the render TARGET and disposes it (disposing only `.texture` leaks the framebuffer behind it). `THREEJS_RENDER_PROFILE` mirrors the server's colour-space/tone-map/exposure contract so the preview renders at what the export stamps on the model. Deliberately NOT drei's `<Environment preset=…>`, which fetches an HDR from a CDN: rendering a local model makes no outbound request. `resolveSculptEnvironment(spec)` is the client mirror of `resolveThreejsEnvironment` in `server/lib/threejsModel.js`, reading a spec with no `environment` key as the `none` it was actually authored against. |
| `threejsExplode.js` | Disassembly + part-picking maths for the procedural sculpt spec, shared by the Three.js Models preview so explode and the picker agree on what "a part" is. `computeExplodeLayout(parts, amount)` → `{ offsets, meshOffsets, unitIds, growth }`: separation is a layout **scale about the model centre** (≈2× at full explode) plus a base clearance for parts sitting at the centre — never a uniform outward push, which slides the arrangement without opening gaps — where `offsets` add to a unit's own `position` and `meshOffsets` apply to a group around a container's own geometry (moving its group instead would drag its child units along), and `growth` measures how much the layout actually grew so the camera re-fits on real change. `buildPartSelectionIndex(parts)` → `{ owners, ancestry, names }` for click resolution, subtree highlight, and the selection label. All maps are null-prototype — part ids are provider-authored and `idSchema` accepts `toString`. `isReliefPart` / `isContainerPart` expose the shared part definition: a part flagged `explodeWithParent` is surface relief that rides its parent and resolves selection up to it (unless it has no parent to ride), every other geometry-bearing part is both a movable unit and a selectable component, a part whose descendants carry geometry is additionally descended through, and a part with no geometry in its subtree moves nothing. |
| `threejsRig.js` | `summarizeThreejsArticulation(spec)` → `{ articulationReady, jointCount, socketCount, attachmentCount, anchoredAttachmentCount, unanchoredAttachmentCount, jointsByPartId }` — client mirror of the readiness rule in `server/lib/threejsModelRig.js`, used by the Three.js Models preview, which is handed a bare spec rather than the record's stored report (and gets none at all for a model generated before rig readiness shipped). A spec with no `articulation` key reads as a static assembly; a graph is ready only when it carries more than a lone root, every child joint names a pivot socket, and every declared attachment names what it hangs from (the anchored `attachments` list and the older anchor-less `attachmentPartIds` are merged into one count). `jointsByPartId` is null-prototype so a provider-authored part id cannot resolve to an inherited function. |
diff --git a/client/src/lib/threejsAnimation.js b/client/src/lib/threejsAnimation.js
index a58f760dd3..fff38bf7ae 100644
--- a/client/src/lib/threejsAnimation.js
+++ b/client/src/lib/threejsAnimation.js
@@ -4,7 +4,7 @@
*
* A clip is data, never code: named sequences carry one part between two
* authored endpoints inside a bounded window, and the easing is a NAME resolved
- * against `utils/easing`'s curve map. So the pose at time T is a pure function
+ * against a fixed curve map. So the pose at time T is a pure function
* of (clip, T) — the same input gives the same pose whether it arrived from a
* play loop, a scrub, or a test — and nothing here touches Three.js, the DOM, or
* a clock.
@@ -23,18 +23,18 @@
* no two sequences on one part+channel at once, every `partId` real), so there
* is no conflict resolution here to get wrong.
*
- * These semantics are MIRRORED by the player PortOS emits into an exported
- * factory (`server/lib/threejsModelPlayerSource.js`), so a clip poses identically
- * in the preview and in a consumer's own scene. Change one and change the other.
+ * The pose itself comes from `server/lib/threejsModelClipPose.js`, the same
+ * evaluator the server's physical audit measures, so the audit and the preview
+ * cannot disagree. Its semantics are MIRRORED by the player PortOS emits into an
+ * exported factory (`server/lib/threejsModelPlayerSource.js`), pinned by
+ * `threejsModelClipPose.test.js`. Change one and change the other.
*/
-import { EASING_CURVES, linear } from '../utils/easing.js';
+import { evaluateThreejsModelClipPose } from '../../../server/lib/threejsModelClipPose.js';
/** Channels a sequence may drive, in the order the schema declares them. */
export const THREEJS_CLIP_CHANNELS = ['position', 'rotationDegrees', 'scale', 'opacity', 'visible'];
-const clamp01 = (value) => (value < 0 ? 0 : value > 1 ? 1 : value);
-
/** Declared clips for a spec, or `[]` for a static assembly. */
export const listThreejsClips = (spec) => (Array.isArray(spec?.animation?.clips) ? spec.animation.clips : []);
@@ -55,51 +55,6 @@ export function resolveThreejsClip(spec, clipId) {
/** Authored duration of a clip — the window, not the last sequence's end. */
export const getThreejsClipDuration = (clip) => (Number.isFinite(clip?.durationSeconds) ? clip.durationSeconds : 0);
-const interpolate = (range, progress) => {
- const { from, to } = range;
- if (Array.isArray(from) && Array.isArray(to)) {
- return from.map((value, axis) => value + ((to[axis] - value) * progress));
- }
- return from + ((to - from) * progress);
-};
-
-// `from` until the window closes, `to` from that instant on. Used for the one
-// channel that cannot be interpolated.
-const step = (range, progress) => (progress >= 1 ? range.to : range.from);
-
-const channelValue = (sequence, range, channel, timeSeconds) => {
- const span = sequence.endSeconds - sequence.startSeconds;
- // A zero-length window is unreachable through the schema, which requires
- // `endSeconds > startSeconds`; a hand-repaired record that has one reads as
- // already finished rather than dividing by zero.
- const raw = span > 0 ? (timeSeconds - sequence.startSeconds) / span : 1;
- const progress = clamp01(raw);
- if (channel === 'visible') return step(range, progress);
- const curve = EASING_CURVES[sequence.easing] || linear;
- return interpolate(range, curve(progress));
-};
-
-// 2 = this window contains the instant, 1 = it is behind the playhead, 0 = it is
-// still ahead. The schema forbids two windows on one part+channel from
-// overlapping, so a tie can only happen at a shared endpoint or among windows
-// that all sit on the same side of the playhead.
-const rankAt = (sequence, time) => {
- if (time >= sequence.startSeconds && time <= sequence.endSeconds) return 2;
- return sequence.endSeconds < time ? 1 : 0;
-};
-
-const outranks = (candidate, current, time) => {
- const candidateRank = rankAt(candidate, time);
- const currentRank = rankAt(current, time);
- if (candidateRank !== currentRank) return candidateRank > currentRank;
- // Two windows meeting at a shared instant: the one that has just BEGUN wins,
- // so forward playback reads as the handover it is rather than replaying the
- // finished sequence's final frame.
- if (candidateRank === 2) return candidate.startSeconds > current.startSeconds;
- if (candidateRank === 1) return candidate.endSeconds > current.endSeconds;
- return candidate.startSeconds < current.startSeconds;
-};
-
/**
* Pose for every part a clip drives at an absolute time.
*
@@ -110,43 +65,15 @@ const outranks = (candidate, current, time) => {
* `activeSequenceIds` are the sequences whose window contains the time.
*/
export function evaluateThreejsClipPose(clip, timeSeconds) {
- // Null-prototype: part ids are provider-authored and the id schema accepts
- // `toString`, so a bare lookup on a plain object can hand back a function.
- const pose = Object.create(null);
const sequences = Array.isArray(clip?.sequences) ? clip.sequences : [];
const time = Number.isFinite(timeSeconds) ? timeSeconds : 0;
- const activeSequenceIds = [];
- const activeParts = new Set();
-
- // Each part+channel is resolved from the ONE sequence that owns the instant:
- // the window containing it, else the most recent window behind it (whose `to`
- // still holds), else the next window ahead (whose `from` has not moved yet).
- // Declaration order decides nothing, so a spec that lists its sequences out of
- // time order evaluates identically.
- const owners = new Map();
- for (const sequence of sequences) {
- for (const channel of THREEJS_CLIP_CHANNELS) {
- const range = sequence.channels?.[channel];
- if (!range) continue;
- const key = `${sequence.partId}|${channel}`;
- const current = owners.get(key);
- if (!current || outranks(sequence, current.sequence, time)) {
- owners.set(key, { sequence, range, channel });
- }
- }
- if (time >= sequence.startSeconds && time <= sequence.endSeconds) {
- activeSequenceIds.push(sequence.id);
- activeParts.add(sequence.partId);
- }
- }
- const activePartIds = [...activeParts];
-
- for (const { sequence, range, channel } of owners.values()) {
- const partPose = pose[sequence.partId] || (pose[sequence.partId] = {});
- partPose[channel] = channelValue(sequence, range, channel, time);
- }
-
- return { timeSeconds: time, pose, activeSequenceIds, activePartIds };
+ const active = sequences.filter((sequence) => time >= sequence.startSeconds && time <= sequence.endSeconds);
+ return {
+ timeSeconds: time,
+ pose: evaluateThreejsModelClipPose(clip, time),
+ activeSequenceIds: active.map((sequence) => sequence.id),
+ activePartIds: [...new Set(active.map((sequence) => sequence.partId))],
+ };
}
/**
diff --git a/server/lib/README.md b/server/lib/README.md
index d4ff710c5f..f9905aafa3 100644
--- a/server/lib/README.md
+++ b/server/lib/README.md
@@ -406,7 +406,7 @@ The barrel `server/lib/index.js` is a machine-checkable enumeration of every pub
| `pngMetadata.js` | `extractGenerationMetadataEntries` shares the bounded projection between PNG text chunks and video container tags. `extractPngGenerationMetadataFile` seeks past pixel data for bounded disk-file metadata extraction. Bounded PNG `tEXt`/`zTXt`/`iTXt` extraction for Stable Diffusion-compatible provenance plus normalization of prompt, negative prompt, sampler, steps, CFG, seed, size, model, and model hash fields; `GENERATION_METADATA_LIMITS` shares the projection bounds with catalog sync validation. Pure. |
| `threejsModel.js` | Validated declarative procedural-model schema plus deterministic standalone Three.js factory export for the Three.js Models workspace. Also the cross-section gate: `evaluateThreejsFlatness(spec)` counts distinct vertex planes per axis — relative to the mesh's own size, with a rotation-invariant zero-volume check behind it — and treats an `extrude` with no bevel thickness as the two-plane slab it is to report when the majority of identity-priority features are built only from flat parts — a model that reads right head-on and like cardboard when orbited. `buildThreejsFlatnessFeedback(flatness)` turns that into default refinement feedback; `listSpecNames(names)` is the shared capped name-list formatter both gates use in finding messages. Also the material-plausibility gate: `evaluateThreejsMaterialPlausibility(spec)` keys a bounded per-family prior table (metal, wood, plastic, glass, fabric, ceramic, rubber, stone, leather, paper) off tokens in each material's id and reports channels whose values the named substance does not support — metalness 0.9 oak, transmission 1.0 steel — skipping any id that names no family or two, and any channel the material's `type` never forwards to Three.js. Advisory only: it never clamps, because a stylized model may legitimately break every prior. `buildThreejsMaterialFeedback(plausibility)` turns that into default refinement feedback. The same pass emits a `reflective-material-without-environment` note when a spec authors reflective channels (metalness above 0.6, or any transmission/clearcoat/iridescence) while `environment.preset` is `none` — those channels read off an environment, so in that scene their values cannot be judged at all. Attachments are declared in two forms — the original anchor-less `attachmentPartIds` and the anchored `attachments: [{ partId, anchorPartId | anchorSocket, maxOffset }]` — and `resolveThreejsAttachments(articulation)` merges them into one canonical list (an anchored entry wins over a bare id) so every gate reads the same set; `isThreejsAttachmentAnchored(attachment)` is the shared anchored/unanchored predicate and `DEFAULT_ATTACHMENT_MAX_OFFSET` the default tolerance. The spec-level refinement rejects an anchor that does not resolve, one that is the attachment itself, an anchor chain that cycles, and the model root (the sole top-level part) — which carries no relationship to any body part. The spec carries an optional `environment` block (see `threejsModelEnvironment.js`), and `buildThreejsFactorySource()` stamps its render profile onto `root.userData.sculptRuntime.render` and exports it as `renderProfile`, so a consumer wiring their own `WebGLRenderer` reproduces the model instead of a differently tone-mapped approximation. |
| `threejsModelAnimation.js` | `summarizeThreejsAnimation(spec)` — clip inventory *and* playback gate over an already-validated Three.js spec: `{ animated, clipCount, cueCount, sequenceCount, movingPartCount, longestClipSeconds, findings, warningCount, clips }`. The schema proves a declared `animation` block is well *formed* (sequences on real parts, inside their clip, never two on one channel at once, never a cue without motion); this reports what the model *declared* — one entry per clip with its role, duration, sequence and distinct-cue counts — plus the ways a well-formed clip still plays badly: a clip authored against a pose the assembly does not build (`clip-start-pose-mismatch`), a handover between sequences that do not meet (`clip-sequence-jump`), a `loop: true` clip that does not return to where it began, a one-shot `idle`, an unfired cue, a long dead tail, and an articulation graph with no clip at all. Advisory warnings only — a static assembly is a complete answer. `buildThreejsAnimationFeedback(animation)` turns those findings into default refinement feedback. A spec with no `animation` key summarizes as not animated — never as evaluated-and-empty. |
-| `threejsModelClipPose.js` | `evaluateThreejsModelClipPose(clip, timeSeconds)` — server copy of the declarative clip pose evaluator (owner per part+channel, step `visible`, the four easing curves), mirroring `client/src/lib/threejsAnimation.js` and the emitted `THREEJS_PLAYER_SOURCE` so the gates measure the pose the preview and the export show; its test executes all three against one clip. |
+| `threejsModelClipPose.js` | `evaluateThreejsModelClipPose(clip, timeSeconds)` — the declarative clip pose evaluator (owner per part+channel, step `visible`, the four easing curves) shared by the preview (`client/src/lib/threejsAnimation.js` re-uses it) and the physical audit, so the gate measures the pose the user sees; its test pins it against the emitted `THREEJS_PLAYER_SOURCE`. |
| `threejsModelCoverage.js` | `evaluateThreejsPartCoverage(spec, { family })` — structural assembly gate over an already-validated Three.js spec: flags promised features fused onto the same part set, geometry claimed by no detail, and details nothing was built for (folded minor relief stays a `note`). With a subject family it also warns on a required component the spec never mentions at all — the one check that can fault a spec for what it failed to *promise*. `buildThreejsCoverageFeedback(coverage)` turns the error findings (plus any family gap) into default refinement feedback. |
| `threejsModelEnvironment.js` | The image-based-lighting and render-profile half of the procedural sculpt contract, kept **dependency-free** so the client suite can import it to assert parity with `client/src/lib/threejsEnvironment.js` (`threejsModel.js` pulls in zod, which the client CI job does not install). `THREEJS_ENVIRONMENT_PRESETS` (`none`/`neutral`/`studio`) is the bounded preset list the spec schema builds its enum from; `resolveThreejsEnvironment(spec)` normalizes a spec's `{ preset, intensity }` block, reading an absent, partial, or unrecognized one as `DEFAULT_THREEJS_ENVIRONMENT` per field — a record stored before the block shipped has no key and was rendered with no environment, so `none` is the honest reading of it. `THREEJS_RENDER_PROFILE` is the output-colour-space / tone-mapping / exposure contract `buildThreejsFactorySource()` stamps onto every export. |
| `threejsModelFamilies.js` | Curated subject-family checklists for Three.js generation. `THREEJS_MODEL_FAMILY_OPTIONS` / `THREEJS_MODEL_FAMILY_IDS` drive the picker and route validation; `buildThreejsFamilyChecklist(id)` returns the prompt block spliced into generation (`''` for the default `general`, so an un-narrowed subject keeps the unchanged general-purpose prompt); `findMissingFamilyComponents(spec, id)` reports which required components the spec never mentions. |
diff --git a/server/lib/threejsModelClipPose.js b/server/lib/threejsModelClipPose.js
index 0a6a5ed8c5..c6cacee311 100644
--- a/server/lib/threejsModelClipPose.js
+++ b/server/lib/threejsModelClipPose.js
@@ -1,20 +1,17 @@
/**
- * Server-side pose evaluator for the declarative clip contract in
- * `threejsModel.js`, used by the gates that measure a clip mid-motion
- * (`threejsModelPhysicalAudit.js`).
+ * Pure pose evaluator for the declarative clip contract in `threejsModel.js`,
+ * shared by the Three.js Models preview (`client/src/lib/threejsAnimation.js`
+ * re-uses it) and the gates that measure a clip mid-motion
+ * (`threejsModelPhysicalAudit.js`), so the audit measures the pose the user sees.
*
- * The semantics MIRROR the preview evaluator (`client/src/lib/threejsAnimation.js`)
- * and the player emitted into an exported factory (`threejsModelPlayerSource.js`):
+ * The semantics MIRROR the player emitted into an exported factory
+ * (`threejsModelPlayerSource.js`):
* per part+channel the owning sequence is the window containing the instant, else
* the most recent window behind it (its `to` holds), else the next window ahead
* (its `from` has not moved yet); `visible` is a step that takes `to` only once
- * the window completes; easing names resolve to the same four curves. A gate
- * that sampled any other pose would report defects the user can never see, or
- * pass ones they can. `threejsModelClipPose.test.js` executes all three against
- * the same clip so they cannot drift apart silently.
- *
- * Server code cannot import the client module, and the player is a fixed source
- * string, so this is the third copy rather than a shared one.
+ * the window completes; `easeInOut` is smoothstep. The player is a fixed source
+ * string that cannot import this module, so `threejsModelClipPose.test.js`
+ * executes both against the same clip to keep them from drifting apart.
*/
const CLIP_CHANNELS = ['position', 'rotationDegrees', 'scale', 'opacity', 'visible'];
diff --git a/server/lib/threejsModelClipPose.test.js b/server/lib/threejsModelClipPose.test.js
index a753558219..ada856b1f0 100644
--- a/server/lib/threejsModelClipPose.test.js
+++ b/server/lib/threejsModelClipPose.test.js
@@ -1,11 +1,9 @@
import { describe, expect, it } from 'vitest';
-import { evaluateThreejsClipPose as evaluatePreviewPose } from '../../client/src/lib/threejsAnimation.js';
import { evaluateThreejsModelClipPose } from './threejsModelClipPose.js';
import { THREEJS_PLAYER_SOURCE } from './threejsModelPlayerSource.js';
-// The audit only means something if it measures the pose the user sees, so the
-// server evaluator is pinned against BOTH other copies — the preview's and the
-// one shipped inside an exported factory — over every semantic they share:
+// The preview re-uses this evaluator, so the remaining copy to pin is the one
+// shipped inside an exported factory, over every semantic they share:
// each easing curve, the step `visible`, a gap between two windows on one
// channel (the earlier `to` holds), the time before a part's first window (its
// `from` holds), and sequences declared out of time order.
@@ -27,15 +25,14 @@ const clip = {
};
describe('evaluateThreejsModelClipPose', () => {
- it('poses a clip exactly as the preview and the exported player do', async () => {
+ it('poses a clip exactly as the exported player does', async () => {
const { evaluateSculptClipPose } = await importEmittedPlayer();
for (let step = 0; step <= 32; step += 1) {
const time = step * 0.125;
const server = { ...evaluateThreejsModelClipPose(clip, time) };
- expect(server).toEqual({ ...evaluatePreviewPose(clip, time).pose });
expect(server).toEqual({ ...evaluateSculptClipPose(clip, time) });
}
- // Spot-check the semantics the parity rests on, so three copies that drifted
+ // Spot-check the semantics the parity rests on, so two copies that drifted
// together cannot pass by agreeing with each other.
expect(evaluateThreejsModelClipPose(clip, 0).arm.rotationDegrees).toEqual([0, 0, 0]);
expect(evaluateThreejsModelClipPose(clip, 2).arm.rotationDegrees).toEqual([0, 90, 0]);