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
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.mdindex 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.jsindex 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.mdindex 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.jsindex 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.jsindex 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]);