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

9.8 KB
Raw Blame
import { describe, expect, it } from 'vitest';
import { buildThreejsGenerationPrompt } from './prompt.js';

const build = (overrides = {}) => buildThreejsGenerationPrompt({
  sourcePath: '/tmp/reference.png',
  name: 'Example Model',
  ...overrides,
});

describe('buildThreejsGenerationPrompt', () => {
  it('documents the surface-relief flag in the parts shape and tells the model when to set it', () => {
    const prompt = build();
    // Undocumented, the flag is never emitted and every model disassembles into
    // a comb of slivers.
    expect(prompt).toContain('"explodeWithParent":false');
    expect(prompt).toContain('"explodeWithParent":true on surface relief');
    for (const relief of ['serrations', 'stria', 'trim', 'port floors']) {
      expect(prompt).toContain(relief);
    }
  });

  it('warns that non-uniform parent scale cascades to nested parts', () => {
    const prompt = build();
    expect(prompt).toContain("A part's scale applies to its whole group and cascades to everything nested under it");
    expect(prompt).toMatch(/Keep a\s+container part that owns other components near-uniformly scaled/);
    expect(prompt).toContain('box width/height/depth, sphere radius');
  });

  it('gates on the model coming apart into readable components', () => {
    expect(build()).toContain('The model must come apart into readable components');
  });

  // Without this the model authors a physically correct conductor into a scene
  // with nothing to reflect, sees it render near-black, and "fixes" it next pass
  // by authoring implausible values back in.
  it('offers the environment block and gates reflective channels on having one', () => {
    const prompt = build();
    expect(prompt).toContain('"environment": {"preset":"none" | "neutral" | "studio","intensity":0..4}');
    expect(prompt).toContain('reflect an environment or they reflect nothing');
    expect(prompt).toContain('sets an "environment" preset other than "none"');
  });

  it('says when extrude is the WRONG answer and gates on cross-section', () => {
    const prompt = build();
    // Selling extrude for silhouettes without naming its failure mode is how a
    // whole model ends up as a stack of unbevelled slabs.
    expect(prompt).toContain('When extrude is the WRONG answer');
    expect(prompt).toContain('"bevelEnabled":true');
    expect(prompt).toContain('must not have every identity part flat along one axis');
  });

  it('teaches the intentional open-shell declaration without weakening the depth gate', () => {
    const prompt = build();
    expect(prompt).toContain('"side":"front" | "double"');
    expect(prompt).toContain('needs a material with "side":"double" or it disappears from behind');
    expect(prompt).toContain('must not be used to dodge giving a solid part a real cross-section');
  });

  it('carries the reference path, name, and direction into the prompt', () => {
    const prompt = build({ prompt: 'Match the brass finish.' });
    expect(prompt).toContain('/tmp/reference.png');
    expect(prompt).toContain('Example Model');
    expect(prompt).toContain('Match the brass finish.');
  });

  it('switches to a refinement pass when a current spec is supplied', () => {
    const prompt = build({ currentSpec: { schemaVersion: 1, name: 'Example Model' }, feedback: 'Thin the handle.' });
    expect(prompt).toContain('This is a refinement pass');
    expect(prompt).toContain('Thin the handle.');
    expect(build()).not.toContain('This is a refinement pass');
  });

  describe('subject family', () => {
    it('leaves the prompt byte-identical when no family is chosen', () => {
      // The taxonomy is a narrowing the user opts into. If the default path
      // drifted even slightly, every existing install's generations would change
      // behavior without anyone asking for it.
      const baseline = build();
      expect(build({ family: null })).toBe(baseline);
      expect(build({ family: 'general' })).toBe(baseline);
      expect(build({ family: 'not-a-family' })).toBe(baseline);
      expect(baseline).not.toContain('SUBJECT FAMILY');
    });

    it('splices the checklist and its extra quality gates when a family is chosen', () => {
      const prompt = build({ family: 'vehicle' });
      expect(prompt).toContain('SUBJECT FAMILY — Vehicle');
      expect(prompt).toContain('Cockpit or cabin');
      expect(prompt).toContain('subject-family checklist is either built and inventoried');
      expect(prompt).toContain('The checklist is the floor');
    });

    it('keeps the family checklist alongside refinement feedback rather than replacing it', () => {
      // A refinement is where an under-observed component is most likely to get
      // fixed, so dropping the checklist on the second pass would defeat it.
      const prompt = build({
        family: 'architecture',
        currentSpec: { schemaVersion: 1, name: 'Example Model' },
        feedback: 'Deepen the window reveals.',
      });
      expect(prompt).toContain('This is a refinement pass');
      expect(prompt).toContain('Deepen the window reveals.');
      expect(prompt).toContain('SUBJECT FAMILY — Building / structure');
    });
  });
});

describe('buildThreejsGenerationPrompt articulation', () => {
  it('never calls the result animation-ready, because nothing PortOS generates is skinned', () => {
    const prompt = build();
    expect(prompt).not.toContain('animation-ready');
    expect(prompt).toContain('cleanly decomposed Three.js model');
  });

  it('requests the articulation contract when the subject could be a character', () => {
    for (const family of [undefined, null, 'general', 'character', 'not-a-family']) {
      const prompt = build({ family });
      expect(prompt).toContain('ARTICULATION (character and hybrid subjects only)');
      expect(prompt).toContain('"parentJointId":null');
      expect(prompt).toContain('"attachments"');
      // An attachment with no anchor is the defect the field exists to remove,
      // so the contract has to ask for one — and rule out the root by name.
      expect(prompt).toContain('"anchorPartId"');
      expect(prompt).toContain('"anchorSocket"');
      expect(prompt).toContain('MODEL ROOT is not an');
      // The contract has to say what it is NOT, or the model invents weights.
      expect(prompt).toContain('not a skeleton');
    }
  });

  it('leaves a prop, vehicle, or structure prompt without an articulation section', () => {
    for (const family of ['vehicle', 'weapon', 'architecture', 'device']) {
      expect(build({ family })).not.toContain('ARTICULATION');
    }
  });

  it('drops the section on a refinement of a spec already classified as an object', () => {
    const object = build({ currentSpec: { schemaVersion: 1, name: 'Example Model', subjectType: 'object' } });
    expect(object).not.toContain('ARTICULATION');
    // …and keeps it for a character refinement even under a non-character family,
    // because the spec's own classification is the stronger signal.
    const character = build({
      family: 'vehicle',
      currentSpec: { schemaVersion: 1, name: 'Example Model', subjectType: 'hybrid' },
    });
    expect(character).toContain('ARTICULATION (character and hybrid subjects only)');
  });
});

describe('buildThreejsGenerationPrompt articulation gating fallbacks', () => {
  it('falls back to the family signal for a subjectType this build does not know', () => {
    // A newer peer or a hand-repaired record could carry a classification this
    // build has no rule for; it must not qualify as a character by default.
    const unknownUnderVehicle = build({
      family: 'vehicle',
      currentSpec: { schemaVersion: 1, name: 'Example Model', subjectType: 'creature-thing' },
    });
    expect(unknownUnderVehicle).not.toContain('ARTICULATION');
    // The spec's own classification wins over the family: an unrecognized one
    // never qualifies, whatever the picker says.
    const unknownUnderCharacter = build({
      family: 'character',
      currentSpec: { schemaVersion: 1, name: 'Example Model', subjectType: 'creature-thing' },
    });
    expect(unknownUnderCharacter).not.toContain('ARTICULATION');
  });
});

describe('buildThreejsGenerationPrompt animation clips', () => {
  // Offered for every subject: a deployable can be an object, a character, or a
  // hybrid, so the clip contract is not gated the way articulation is.
  it('offers the clip contract whatever the subject is, and tells the model to omit it by default', () => {
    for (const overrides of [
      {},
      { family: 'vehicle' },
      { family: 'character', currentSpec: { schemaVersion: 1, name: 'Example Model', subjectType: 'character' } },
    ]) {
      const prompt = build(overrides);
      expect(prompt).toContain('ANIMATION CLIPS (optional, any subject)');
      expect(prompt).toContain('Omit the key entirely for a static subject');
    }
  });

  it('states the rules the schema actually enforces, so a rejection is never a surprise', () => {
    const prompt = build();
    expect(prompt).toContain('Every sequence changes at least one channel');
    expect(prompt).toContain('may not drive the same channel of the same part at overlapping times');
    expect(prompt).toContain('"visible" is a step, not a fade');
    expect(prompt).toContain('a cue may only ride a sequence that changes');
    expect(prompt).toContain('do not return JavaScript, keyframe arrays, or curve definitions');
  });

  it('names every easing and clip role the schema accepts', () => {
    const prompt = build();
    for (const easing of ['linear', 'easeIn', 'easeOut', 'easeInOut']) {
      expect(prompt).toContain(`"${easing}"`);
    }
    for (const role of ['deploy', 'retract', 'assemble', 'destroy', 'idle']) {
      expect(prompt).toContain(`"${role}"`);
    }
  });

  it('says a cue is an identifier, never audio PortOS would load', () => {
    expect(build()).toContain('never a filename, a URL, or audio data');
  });
});