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

37.4 KB
Raw Blame
import { act, fireEvent, render, screen } from '@testing-library/react';
import { MemoryRouter, useLocation } from 'react-router';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';

// The preview reads the live renderer and scene off the r3f context to install a
// PMREM environment. There is no GL context under jsdom, so the stand-ins below
// are what the environment effect writes to — and `scene.environment` is the one
// observable that says whether a spec's preset reached the scene at all.
const threeState = vi.hoisted(() => ({ gl: { isWebGLRenderer: true }, scene: { environment: null } }));
const environmentBuilds = vi.hoisted(() => []);
vi.mock('../../lib/threejsEnvironment', async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    // PMREM needs a real renderer; what matters here is WHICH preset the preview
    // asked for, that its texture reached the scene, and that the whole render
    // TARGET is released again — disposing the texture alone leaks the
    // framebuffer behind it.
    createSculptEnvironmentTarget: (_renderer, preset) => {
      const target = { preset, texture: { preset }, dispose: vi.fn() };
      environmentBuilds.push(target);
      return target;
    },
  };
});

// Fails the CANVAS ITSELF, which is how r3f surfaces a throw from inside the
// scene: it catches whatever the tree threw and re-throws it from its own
// render. Nothing under jsdom can build real geometry, so this is the only way
// to reach the boundary the preview now wraps the canvas in.
const canvasFailure = vi.hoisted(() => ({ error: null }));
vi.mock('@react-three/fiber', () => ({
  useThree: (selector) => selector(threeState),
  Canvas: ({ children, ...props }) => {
    if (canvasFailure.error) throw canvasFailure.error;
    return (
    <div
      data-testid="threejs-canvas"
      data-alpha={String(props.gl?.alpha)}
      data-tone-exposure={String(props.gl?.toneMappingExposure)}
      data-linear={String(props.linear)}
      data-flat={String(props.flat)}
      data-dpr={Array.isArray(props.dpr) ? props.dpr.join(',') : String(props.dpr)}
      data-shadows={String(props.shadows)}
      data-camera-position={props.camera?.position?.join(',')}
    >
      {children}
    </div>
    );
  },
  useFrame: vi.fn(),
}));
// A chainable stand-in for drei's Bounds api, so the explode re-fit is
// observable without a real renderer.
const boundsApi = vi.hoisted(() => {
  const api = {};
  api.refresh = vi.fn(() => api);
  api.clip = vi.fn(() => api);
  api.fit = vi.fn(() => api);
  return api;
});
vi.mock('@react-three/drei', () => ({
  Bounds: ({ children }) => children,
  useBounds: () => boundsApi,
  OrbitControls: () => null,
}));

// r3f object props stringify to "[object Object]" under the DOM renderer, so the
// only way to see WHICH geometry the preview attached is to record it as the real
// builder hands it back.
const built = vi.hoisted(() => []);
vi.mock('../../lib/threejsSculpt', async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    createSculptBufferGeometry: (definition) => {
      const geometry = actual.createSculptBufferGeometry(definition);
      built.push(geometry);
      return geometry;
    },
  };
});

import { THREEJS_RENDER_PROFILE } from '../../lib/threejsEnvironment';
import ThreejsModelPreview from './ThreejsModelPreview';

const SPEC = {
  name: 'Example model',
  schemaVersion: 1,
  background: '#111827',
  camera: { position: [0, 0, 3], fov: 45, target: [0, 0, 0] },
  lights: [],
  materials: {},
  parts: [],
};

const material = (overrides) => ({
  type: 'standard',
  color: '#8b5a2b',
  metalness: 0,
  roughness: 0.6,
  emissive: '#000000',
  emissiveIntensity: 0,
  opacity: 1,
  transparent: false,
  wireframe: false,
  clearcoat: 0,
  clearcoatRoughness: 0,
  ior: 1.5,
  transmission: 0,
  thickness: 0,
  sheen: 0,
  iridescence: 0,
  anisotropy: 0,
  ...overrides,
});

const part = (id, geometry, materialId, overrides = {}) => ({
  id,
  name: id,
  geometry,
  material: materialId,
  position: [0, 0, 0],
  rotationDegrees: [0, 0, 0],
  scale: [1, 1, 1],
  castShadow: true,
  receiveShadow: true,
  children: [],
  ...overrides,
});

// The preview keeps the picked part in the URL, so every render needs a router.
const renderPreview = (ui, entry = '/') =>
  render(ui, { wrapper: ({ children }) => <MemoryRouter initialEntries={[entry]}>{children}</MemoryRouter> });

const LocationProbe = () => <output data-testid="location-probe">{useLocation().search}</output>;

const box = { type: 'box', width: 1, height: 1, depth: 1 };
const positionOf = (container, name) =>
  container.querySelector(`group[name="${name}"]`).getAttribute('position').split(',').map(Number);
const setExplode = (value) => fireEvent.change(screen.getByLabelText('Explode'), { target: { value: String(value) } });

describe('ThreejsModelPreview', () => {
  it('offers preset and custom preview backgrounds without changing the scene spec', () => {
    renderPreview(<ThreejsModelPreview spec={SPEC} />);

    expect(screen.getByRole('button', { name: 'Black' })).toHaveAttribute('aria-pressed', 'false');
    expect(screen.getByRole('button', { name: 'Green screen' })).toHaveAttribute('aria-pressed', 'false');
    expect(screen.getByLabelText('Custom preview background color')).toHaveValue('#111827');

    fireEvent.click(screen.getByRole('button', { name: 'White' }));
    expect(screen.getByRole('button', { name: 'White' })).toHaveAttribute('aria-pressed', 'true');
    expect(SPEC.background).toBe('#111827');

    fireEvent.click(screen.getByRole('button', { name: 'Transparent' }));
    expect(screen.getByTestId('threejs-canvas')).toHaveAttribute('data-alpha', 'true');
    expect(screen.getByLabelText('Custom preview background color')).toHaveValue('#000000');
  });

  it('adapts presentation quality locally without changing the generated spec', () => {
    const originalSpec = structuredClone(SPEC);
    renderPreview(<ThreejsModelPreview spec={SPEC} />);

    expect(screen.getByLabelText('Quality')).toHaveValue('auto');
    expect(screen.getByText('Auto · high')).toBeInTheDocument();
    expect(screen.getByTestId('threejs-canvas')).toHaveAttribute('data-dpr', '1,1.5');
    expect(screen.getByTestId('threejs-canvas')).toHaveAttribute('data-shadows', 'soft');

    fireEvent.change(screen.getByLabelText('Quality'), { target: { value: 'low' } });

    expect(screen.getByText('Fixed · low')).toBeInTheDocument();
    expect(screen.getByTestId('threejs-canvas')).toHaveAttribute('data-dpr', '0.75,1');
    expect(screen.getByTestId('threejs-canvas')).toHaveAttribute('data-shadows', 'basic');
    expect(SPEC).toEqual(originalSpec);
  });

  it('keeps deterministic camera and material inspections in validated URL state without changing the spec', () => {
    const spec = { ...SPEC, materials: { body: material() }, parts: [part('body', box, 'body')] };
    renderPreview(<><ThreejsModelPreview spec={spec} family={{ orbitViews: ['side profile'], reviewAxes: ['panel gap continuity'] }} /><LocationProbe /></>, '/?auditCamera=near&auditMode=wireframe');

    expect(screen.getByRole('button', { name: 'Near' })).toHaveAttribute('aria-pressed', 'true');
    expect(screen.getByRole('button', { name: 'Wireframe' })).toHaveAttribute('aria-pressed', 'true');
    expect(screen.getByTestId('threejs-canvas')).toHaveAttribute('data-camera-position', '0,0,1.7999999999999998');
    expect(screen.getByText(/Family review: side profile/)).toBeInTheDocument();
    expect(screen.getByText(/panel gap continuity/)).toBeInTheDocument();
    expect(screen.getByText(/never change the saved model/)).toBeInTheDocument();

    fireEvent.click(screen.getByRole('button', { name: 'Family review' }));
    fireEvent.click(screen.getByRole('button', { name: 'Part boundaries' }));
    expect(screen.getByTestId('location-probe')).toHaveTextContent('auditCamera=family');
    expect(screen.getByTestId('location-probe')).toHaveTextContent('auditMode=boundaries');
    expect(spec).toEqual({ ...SPEC, materials: { body: material() }, parts: [part('body', box, 'body')] });
  });

  it('falls back to the authored final view when an audit URL is stale', () => {
    renderPreview(<ThreejsModelPreview spec={SPEC} />, '/?auditCamera=unknown&auditMode=unknown');

    expect(screen.getByRole('button', { name: 'Authored' })).toHaveAttribute('aria-pressed', 'true');
    expect(screen.getByRole('button', { name: 'Final' })).toHaveAttribute('aria-pressed', 'true');
  });

  it('preserves an authored overhead direction in near and far bookmarks', () => {
    renderPreview(<ThreejsModelPreview spec={{ ...SPEC, camera: { ...SPEC.camera, position: [0, 3, 0] } }} />, '/?auditCamera=near');

    expect(screen.getByTestId('threejs-canvas')).toHaveAttribute('data-camera-position', '0,1.7999999999999998,0');
  });

  it('renders extrude and tube parts as built buffer geometries', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={{
      ...SPEC,
      materials: { body: material() },
      parts: [
        part('plate', {
          type: 'extrude',
          outline: [[-1, -1], [1, -1], [1, 1], [-1, 1]],
          holes: [[[-0.3, -0.3], [0.3, -0.3], [0.3, 0.3], [-0.3, 0.3]]],
          depth: 0.4,
          bevelEnabled: false,
          bevelThickness: 0.1,
          bevelSize: 0.1,
          bevelSegments: 2,
          curveSegments: 8,
          steps: 1,
        }, 'body'),
        part('cable', {
          type: 'tube',
          path: [[0, 0, 0], [0, 1, 0.5], [0.6, 1.6, 0]],
          radius: 0.08,
          tubularSegments: 24,
          radialSegments: 8,
          closed: false,
          curveType: 'centripetal',
          tension: 0.5,
        }, 'body'),
      ],
    }} />);

    expect(container.querySelectorAll('primitive[attach="geometry"]')).toHaveLength(2);
    expect(built.map((geometry) => geometry.type)).toEqual(['ExtrudeGeometry', 'TubeGeometry']);
    expect(built.every((geometry) => geometry.getAttribute('position').count > 0)).toBe(true);
  });

  it('forwards physical material channels only to physical materials', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={{
      ...SPEC,
      materials: {
        glass: material({ type: 'physical', ior: 1.45, transmission: 0.8, thickness: 0.6, sheen: 0.3, iridescence: 0.7, anisotropy: 0.9 }),
        paint: material(),
      },
      parts: [
        part('pane', { type: 'box', width: 1, height: 1, depth: 1 }, 'glass'),
        part('frame', { type: 'box', width: 1, height: 1, depth: 1 }, 'paint'),
      ],
    }} />);

    const physical = container.querySelector('meshPhysicalMaterial');
    expect(physical.getAttribute('ior')).toBe('1.45');
    expect(physical.getAttribute('transmission')).toBe('0.8');
    expect(physical.getAttribute('thickness')).toBe('0.6');
    expect(physical.getAttribute('sheen')).toBe('0.3');
    expect(physical.getAttribute('iridescence')).toBe('0.7');
    expect(physical.getAttribute('anisotropy')).toBe('0.9');

    const standard = container.querySelector('meshStandardMaterial');
    expect(standard.getAttribute('ior')).toBeNull();
    expect(standard.getAttribute('transmission')).toBeNull();
  });
});

// Punctual lights light a surface; only an environment gives it something to
// REFLECT. Without one, a physically plausible conductor renders near-black and
// the next refinement pass "fixes" that by authoring implausible values back in.
describe('ThreejsModelPreview environment', () => {
  const metalSpec = (environment) => ({
    ...SPEC,
    ...(environment ? { environment } : {}),
    materials: { chrome: material({ metalness: 1, roughness: 0.1 }) },
    parts: [part('shell', box, 'chrome')],
  });
  const intensityOf = (container) =>
    container.querySelector('meshStandardMaterial').getAttribute('envMapIntensity');

  beforeEach(() => {
    environmentBuilds.length = 0;
    threeState.scene.environment = null;
  });

  // Every export stamps THREEJS_RENDER_PROFILE onto the model as the settings it
  // was authored against. r3f installs sRGB + ACESFilmic for `linear={false}
  // flat={false}`, so passing either flag here would quietly make that claim
  // false; exposure is the one r3f leaves alone, so the preview states it.
  it('renders at the render profile the export promises', () => {
    renderPreview(<ThreejsModelPreview spec={SPEC} />);
    const canvas = screen.getByTestId('threejs-canvas');
    expect(canvas).toHaveAttribute('data-tone-exposure', String(THREEJS_RENDER_PROFILE.toneMappingExposure));
    expect(canvas).toHaveAttribute('data-linear', 'undefined');
    expect(canvas).toHaveAttribute('data-flat', 'undefined');
  });

  it('assigns the authored preset to the scene and forwards its intensity to the material', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={metalSpec({ preset: 'studio', intensity: 2 })} />);

    expect(environmentBuilds.map((target) => target.preset)).toEqual(['studio']);
    expect(threeState.scene.environment).toBe(environmentBuilds[0].texture);
    expect(intensityOf(container)).toBe('2');
  });

  // A record stored before the environment block shipped has no key and was
  // rendered with none, so it must keep rendering exactly that way.
  it('builds nothing for a spec that predates the environment block', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={metalSpec(null)} />);

    expect(environmentBuilds).toHaveLength(0);
    expect(threeState.scene.environment).toBeNull();
    expect(intensityOf(container)).toBe('1');
  });

  it('swaps presets without leaking the previous PMREM target', () => {
    const { rerender } = renderPreview(<ThreejsModelPreview spec={metalSpec({ preset: 'neutral', intensity: 1 })} />);
    const [first] = environmentBuilds;

    rerender(<ThreejsModelPreview spec={metalSpec({ preset: 'studio', intensity: 1 })} />);
    expect(first.dispose).toHaveBeenCalled();
    expect(threeState.scene.environment).toBe(environmentBuilds[1].texture);
    expect(environmentBuilds[1].preset).toBe('studio');
  });

  it('releases the render target and clears the scene on unmount', () => {
    const { unmount } = renderPreview(<ThreejsModelPreview spec={metalSpec({ preset: 'studio', intensity: 1 })} />);
    const [target] = environmentBuilds;

    unmount();
    expect(target.dispose).toHaveBeenCalled();
    expect(threeState.scene.environment).toBeNull();
  });
});

// A knife: one blade carrying surface relief that must not fly off on its own,
// plus a separate handle so there is something to separate FROM.
const knifeSpec = () => ({
  ...SPEC,
  materials: { steel: material() },
  parts: [
    part('blade', box, 'steel', {
      name: 'Blade',
      position: [-1, 0, 0],
      children: [part('serrations', box, 'steel', { name: 'Serrations', position: [0, 0.5, 0], explodeWithParent: true })],
    }),
    part('handle', box, 'steel', { name: 'Handle', position: [1, 0, 0] }),
  ],
});

describe('ThreejsModelPreview disassembly', () => {
  beforeEach(() => {
    boundsApi.fit.mockClear();
  });

  it('separates the parts by scaling the layout about the centre, keeping relief on its part', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={knifeSpec()} />);

    expect(positionOf(container, 'Blade')).toEqual([-1, 0, 0]);
    expect(positionOf(container, 'Handle')).toEqual([1, 0, 0]);

    setExplode(1);

    // Assembled spread is ±1, so a full explode puts each part at ±(2 + clearance) —
    // a real gap opens between them rather than the pair sliding together.
    const [bladeX] = positionOf(container, 'Blade');
    const [handleX] = positionOf(container, 'Handle');
    expect(bladeX).toBeCloseTo(-2.18, 6);
    expect(handleX).toBeCloseTo(2.18, 6);

    // Relief rides the blade — its own transform never changes.
    expect(positionOf(container, 'Serrations')).toEqual([0, 0.5, 0]);
  });

  it('re-fits the camera when the layout actually grows', () => {
    renderPreview(<ThreejsModelPreview spec={knifeSpec()} />);
    boundsApi.fit.mockClear();

    setExplode(0.5);
    expect(boundsApi.refresh).toHaveBeenCalled();
    expect(boundsApi.fit).toHaveBeenCalledTimes(1);

    // Same layout, no wasted re-fit.
    setExplode(0.5);
    expect(boundsApi.fit).toHaveBeenCalledTimes(1);
  });

  it('disables the explode control when there is only one part to move', () => {
    renderPreview(<ThreejsModelPreview spec={{ ...SPEC, materials: { steel: material() }, parts: [part('solo', box, 'steel')] }} />);
    expect(screen.getByLabelText('Explode')).toBeDisabled();
  });

  it('resolves a click on surface relief up to the part it belongs to and highlights that subtree', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={knifeSpec()} />);

    expect(screen.queryByRole('button', { name: 'Clear part selection' })).not.toBeInTheDocument();

    fireEvent.click(container.querySelector('group[name="Serrations"] mesh'));

    // The sliver is not the answer — the blade it rides is.
    expect(screen.getByText('Blade')).toBeInTheDocument();
    expect(screen.getByText('blade')).toBeInTheDocument();

    const highlighted = container.querySelectorAll('meshStandardMaterial[emissive="#38bdf8"]');
    // Blade + its relief light up together; the handle stays as authored.
    expect(highlighted).toHaveLength(2);
    expect(container.querySelector('group[name="Handle"] meshStandardMaterial').getAttribute('emissive')).toBe('#000000');
  });

  it('moves a container-with-geometry\'s own shell without dragging its child part', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={{
      ...SPEC,
      materials: { steel: material() },
      parts: [part('body', box, 'steel', {
        name: 'Body',
        children: [
          part('trim', box, 'steel', { name: 'Trim', position: [0, 0, 1] }),
          part('engraving', box, 'steel', { name: 'Engraving', position: [0, 0.5, 0], explodeWithParent: true }),
        ],
      })],
    }} />);

    // Assembled: the body's group sits at the origin and its shell is not offset.
    expect(container.querySelector('group[name="Body"] > group:not([name])')).toBeNull();

    setExplode(1);

    // The body's GROUP must not move — that would carry the trim with it and
    // separate nothing. Its shell moves inside an offset group instead.
    expect(positionOf(container, 'Body')).toEqual([0, 0, 0]);
    const shell = container.querySelector('group[name="Body"] > group:not([name])');
    expect(shell.getAttribute('position').split(',').map(Number).some((value) => value !== 0)).toBe(true);
    expect(shell.querySelector('mesh')).not.toBeNull();
    // The shell's own engraving rides INSIDE that offset group — its authored
    // transform is untouched; it moves only because its wrapper does. Hoist it
    // out and the body separates from its own surface detail.
    expect(container.querySelector('group[name="Body"] > group:not([name]) > group[name="Engraving"]')).not.toBeNull();
    expect(positionOf(container, 'Engraving')).toEqual([0, 0.5, 0]);
    // And the trim moves on its own.
    expect(positionOf(container, 'Trim')).not.toEqual([0, 0, 1]);
  });

  it('keeps the picked part in the URL so it survives a reload and a stale id degrades', () => {
    const { container, unmount } = renderPreview(<ThreejsModelPreview spec={knifeSpec()} />, '/?part=handle');
    expect(screen.getByText('Handle')).toBeInTheDocument();
    expect(container.querySelectorAll('meshStandardMaterial[emissive="#38bdf8"]')).toHaveLength(1);
    unmount();

    // A link to a part this model no longer has must not render an empty label.
    renderPreview(<ThreejsModelPreview spec={knifeSpec()} />, '/?part=noSuchPart');
    expect(screen.queryByRole('button', { name: 'Clear part selection' })).not.toBeInTheDocument();
  });

  it('selects a plain part on its own and clears the selection', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={knifeSpec()} />);

    fireEvent.click(container.querySelector('group[name="Handle"] mesh'));
    expect(screen.getByText('Handle')).toBeInTheDocument();
    expect(container.querySelectorAll('meshStandardMaterial[emissive="#38bdf8"]')).toHaveLength(1);

    fireEvent.click(screen.getByRole('button', { name: 'Clear part selection' }));
    expect(container.querySelectorAll('meshStandardMaterial[emissive="#38bdf8"]')).toHaveLength(0);
  });
});

// The knife again, this time with a declared articulation graph: the handle is
// the root and the blade pivots about a named socket.
const articulatedKnifeSpec = () => ({
  ...knifeSpec(),
  sockets: [{ name: 'bladePivot', parentPartId: 'handle', position: [0, 0, 0], rotationDegrees: [0, 0, 0] }],
  articulation: {
    joints: [
      { id: 'rootJoint', partId: 'handle', parentJointId: null, pivotSocket: null },
      { id: 'bladeJoint', partId: 'blade', parentJointId: 'rootJoint', pivotSocket: 'bladePivot' },
    ],
    attachmentPartIds: [],
  },
});

describe('ThreejsModelPreview articulation status', () => {
  it('calls a spec with no articulation a static assembly, never animation-ready', () => {
    renderPreview(<ThreejsModelPreview spec={knifeSpec()} />);
    expect(screen.getByText('Static assembly')).toBeInTheDocument();
    expect(screen.queryByText(/Articulation-ready/)).not.toBeInTheDocument();
  });

  it('reports a usable graph with its joint and pivot counts', () => {
    renderPreview(<ThreejsModelPreview spec={articulatedKnifeSpec()} />);
    expect(screen.getByText('Articulation-ready · 2 joints · 1 pivot')).toBeInTheDocument();
  });

  // Schema-valid but rig-useless: the child joint has no axis, so the badge must
  // agree with the server's report instead of claiming a rig off mere presence.
  it('stays static when a child joint names no pivot socket, and says how many joints it saw', () => {
    const spec = articulatedKnifeSpec();
    spec.articulation.joints[1].pivotSocket = null;
    renderPreview(<ThreejsModelPreview spec={spec} />);
    expect(screen.getByText('Static assembly · 2 joints declared')).toBeInTheDocument();
  });

  it('names the joint driving a picked part, and the fact when it has no pivot', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={articulatedKnifeSpec()} />);

    fireEvent.click(container.querySelector('group[name="Blade"] mesh'));
    expect(screen.getByText('joint bladeJoint · pivot bladePivot')).toBeInTheDocument();

    fireEvent.click(container.querySelector('group[name="Handle"] mesh'));
    expect(screen.getByText('joint rootJoint · no pivot')).toBeInTheDocument();
  });

  it('renders a legacy spec with no articulation key without crashing the picker', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={knifeSpec()} />);
    fireEvent.click(container.querySelector('group[name="Handle"] mesh'));
    expect(screen.getByText('Handle')).toBeInTheDocument();
    expect(screen.queryByText(/^joint /)).not.toBeInTheDocument();
  });
});

const clipSpec = () => ({
  ...knifeSpec(),
  animation: {
    cues: [{ id: 'latchRelease', label: 'Latch lets go', kind: 'latch' }],
    clips: [
      {
        id: 'deploy',
        name: 'Deploy',
        role: 'deploy',
        durationSeconds: 2,
        loop: false,
        sequences: [
          {
            id: 'swingBlade',
            name: 'Swing blade',
            partId: 'blade',
            startSeconds: 0,
            endSeconds: 1,
            easing: 'linear',
            channels: { position: { from: [-1, 0, 0], to: [-1, 4, 0] } },
            cueId: 'latchRelease',
          },
          {
            id: 'dropHandle',
            name: 'Drop handle',
            partId: 'handle',
            startSeconds: 1,
            endSeconds: 2,
            easing: 'linear',
            channels: { visible: { from: true, to: false }, opacity: { from: 1, to: 0 } },
            cueId: null,
          },
        ],
      },
      {
        id: 'retract',
        name: 'Retract',
        role: 'retract',
        durationSeconds: 1,
        loop: false,
        sequences: [{
          id: 'foldBlade',
          name: 'Fold blade',
          partId: 'blade',
          startSeconds: 0,
          endSeconds: 1,
          easing: 'linear',
          channels: { position: { from: [-1, 4, 0], to: [-1, 0, 0] } },
          cueId: null,
        }],
      },
    ],
  },
});

const scrub = (value) => fireEvent.change(screen.getByLabelText('Time'), { target: { value: String(value) } });
const opacityOf = (container, name) =>
  container.querySelector(`group[name="${name}"] meshStandardMaterial`).getAttribute('opacity');

describe('ThreejsModelPreview clips', () => {
  let frames = [];
  let nowMs = 0;

  beforeEach(() => {
    frames = [];
    nowMs = 0;
    // A hand-driven frame queue, so playback is stepped deterministically
    // instead of waiting on the browser's own rAF cadence.
    vi.spyOn(globalThis, 'requestAnimationFrame').mockImplementation((callback) => frames.push(callback));
    vi.spyOn(globalThis, 'cancelAnimationFrame').mockImplementation(() => {});
    vi.spyOn(performance, 'now').mockImplementation(() => nowMs);
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  const advance = (ms) => {
    nowMs += ms;
    const pending = frames.splice(0);
    act(() => {
      for (const callback of pending) callback(nowMs);
    });
  };

  it('shows no transport for a model that declares no clips', () => {
    renderPreview(<ThreejsModelPreview spec={knifeSpec()} />);
    expect(screen.queryByLabelText('Clip')).not.toBeInTheDocument();
    expect(screen.queryByLabelText('Play clip')).not.toBeInTheDocument();
  });

  it('renders a declared clip at its start pose and keeps undriven parts as authored', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={clipSpec()} />);

    expect(screen.getByLabelText('Clip')).toHaveValue('deploy');
    expect(positionOf(container, 'Blade')).toEqual([-1, 0, 0]);
    // Undriven at t=0: the handle keeps the authored material, with no opacity
    // override in sight.
    expect(opacityOf(container, 'Handle')).toBe('1');
  });

  it('scrubs to any time deterministically, including the visibility step at a window end', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={clipSpec()} />);

    scrub(0.5);
    expect(positionOf(container, 'Blade')).toEqual([-1, 2, 0]);
    expect(screen.getByText('Swing blade')).toBeInTheDocument();

    scrub(1.5);
    // Past its window the blade holds where its sequence left it, while the
    // handle is half faded through the window that is still running. (The
    // `visible` step riding the same sequence is asserted in the evaluator's own
    // suite — React drops a boolean prop on an unrecognized element, so the DOM
    // stand-in for a three.js group cannot show it.)
    expect(positionOf(container, 'Blade')).toEqual([-1, 4, 0]);
    expect(opacityOf(container, 'Handle')).toBe('0.5');

    scrub(2);
    expect(opacityOf(container, 'Handle')).toBe('0');
  });

  it('never fires a cue while scrubbing', () => {
    const onCue = vi.fn();
    renderPreview(<ThreejsModelPreview spec={clipSpec()} onCue={onCue} />);

    scrub(0.5);
    scrub(0);
    scrub(1.2);
    expect(onCue).not.toHaveBeenCalled();
  });

  it('plays the clip forward, fires each crossed cue once, and stops at the end', () => {
    const onCue = vi.fn();
    const { container } = renderPreview(<ThreejsModelPreview spec={clipSpec()} onCue={onCue} />);

    fireEvent.click(screen.getByLabelText('Play clip'));
    advance(500);
    expect(positionOf(container, 'Blade')).toEqual([-1, 2, 0]);
    expect(onCue).toHaveBeenCalledTimes(1);
    expect(onCue).toHaveBeenCalledWith(expect.objectContaining({
      cueId: 'latchRelease',
      sequenceId: 'swingBlade',
      partId: 'blade',
      clipId: 'deploy',
      cue: expect.objectContaining({ label: 'Latch lets go', kind: 'latch' }),
    }));

    advance(500);
    expect(onCue).toHaveBeenCalledTimes(1);

    // Past the authored duration the clip stops on its final pose instead of
    // running on, and the transport flips back to offering Play.
    advance(2_000);
    expect(screen.getByLabelText('Play clip')).toBeInTheDocument();
    expect(screen.getByText('2.00/2.00s')).toBeInTheDocument();
    expect(frames).toHaveLength(0);
  });

  it('applies the speed multiplier to the playhead', () => {
    renderPreview(<ThreejsModelPreview spec={clipSpec()} />);

    fireEvent.change(screen.getByLabelText('Speed'), { target: { value: '2' } });
    fireEvent.click(screen.getByLabelText('Play clip'));
    advance(500);
    expect(screen.getByText('1.00/2.00s')).toBeInTheDocument();
  });

  it('stops back to the clip start and releases the frame loop on unmount', () => {
    const { unmount } = renderPreview(<ThreejsModelPreview spec={clipSpec()} />);

    fireEvent.click(screen.getByLabelText('Play clip'));
    advance(500);
    fireEvent.click(screen.getByLabelText('Stop clip'));
    expect(screen.getByText('0.00/2.00s')).toBeInTheDocument();
    expect(globalThis.cancelAnimationFrame).toHaveBeenCalled();

    fireEvent.click(screen.getByLabelText('Play clip'));
    globalThis.cancelAnimationFrame.mockClear();
    unmount();
    expect(globalThis.cancelAnimationFrame).toHaveBeenCalled();
  });

  it('keeps the open clip in the URL and rewinds when it changes', () => {
    const { container } = renderPreview(
      <><ThreejsModelPreview spec={clipSpec()} /><LocationProbe /></>,
      '/?clip=retract',
    );

    expect(screen.getByLabelText('Clip')).toHaveValue('retract');
    expect(positionOf(container, 'Blade')).toEqual([-1, 4, 0]);

    scrub(0.5);
    fireEvent.change(screen.getByLabelText('Clip'), { target: { value: 'deploy' } });
    expect(screen.getByTestId('location-probe')).toHaveTextContent('clip=deploy');
    expect(screen.getByText('0.00/2.00s')).toBeInTheDocument();
  });

  it('falls back to the first clip when the URL names one this model does not have', () => {
    renderPreview(<ThreejsModelPreview spec={clipSpec()} />, '/?clip=noSuchClip');
    expect(screen.getByLabelText('Clip')).toHaveValue('deploy');
  });

  it('leaves explode and part picking working while a clip is posed', () => {
    const { container } = renderPreview(<ThreejsModelPreview spec={clipSpec()} />);

    scrub(1);
    setExplode(1);
    // The clip's pose and the disassembly offset compose rather than replacing
    // each other: the blade sits at its posed Y with the explode offset on top.
    const [bladeX, bladeY] = positionOf(container, 'Blade');
    expect(bladeY).toBe(4);
    expect(bladeX).toBeCloseTo(-2.18, 6);

    fireEvent.click(container.querySelector('group[name="Blade"] mesh'));
    expect(screen.getByText('Blade')).toBeInTheDocument();
  });
});

describe('ThreejsModelPreview clip framing and looping', () => {
  let frames = [];
  let nowMs = 0;

  beforeEach(() => {
    frames = [];
    nowMs = 0;
    boundsApi.fit.mockClear();
    vi.spyOn(globalThis, 'requestAnimationFrame').mockImplementation((callback) => frames.push(callback));
    vi.spyOn(globalThis, 'cancelAnimationFrame').mockImplementation(() => {});
    vi.spyOn(performance, 'now').mockImplementation(() => nowMs);
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });

  const advance = (ms) => {
    nowMs += ms;
    const pending = frames.splice(0);
    act(() => {
      for (const callback of pending) callback(nowMs);
    });
  };

  it('re-frames when a different clip opens, but never chases a playing one', () => {
    renderPreview(<ThreejsModelPreview spec={clipSpec()} />);
    boundsApi.fit.mockClear();

    // Scrubbing and playing move parts every frame — a camera that re-fit on
    // each of them would chase the mechanism instead of watching it.
    scrub(0.5);
    fireEvent.click(screen.getByLabelText('Play clip'));
    advance(300);
    expect(boundsApi.fit).not.toHaveBeenCalled();

    // Opening another clip is a discrete jump to a pose that can sit well
    // outside the assembled one, so that one does re-frame.
    fireEvent.change(screen.getByLabelText('Clip'), { target: { value: 'retract' } });
    expect(boundsApi.fit).toHaveBeenCalled();
  });

  it('fires every cue once across a frame gap longer than a looping clip', () => {
    const spec = clipSpec();
    spec.animation.clips[0].loop = true;
    const onCue = vi.fn();
    renderPreview(<ThreejsModelPreview spec={spec} onCue={onCue} />);

    fireEvent.click(screen.getByLabelText('Play clip'));
    // 7s on a 2s loop: three and a half cycles skipped in one frame. Every cue
    // fires once for the gap — not once per skipped cycle, and not zero times.
    advance(7_000);
    expect(onCue).toHaveBeenCalledTimes(1);
    expect(onCue).toHaveBeenCalledWith(expect.objectContaining({ cueId: 'latchRelease' }));
    // ...and the clip keeps running from where it wrapped to.
    expect(screen.getByText('1.00/2.00s')).toBeInTheDocument();

    advance(1_500);
    expect(onCue).toHaveBeenCalledTimes(2);
  });
});

describe('ThreejsModelPreview clip refresh', () => {
  it('rewinds and stops when a refinement rewrites the open clip under the same id', () => {
    const { rerender } = renderPreview(<ThreejsModelPreview spec={clipSpec()} />);
    scrub(1.2);
    expect(screen.getByText('1.20/2.00s')).toBeInTheDocument();

    // The detail page re-fetches every 2s while a generation runs: an equivalent
    // snapshot must not throw away where the user scrubbed to.
    rerender(<ThreejsModelPreview spec={clipSpec()} />);
    expect(screen.getByText('1.20/2.00s')).toBeInTheDocument();

    // A refinement that hands back a rewritten `deploy` is a different clip
    // wearing the same id — evaluating it at the old playhead would pose the
    // model somewhere the new clip never authored.
    const refined = clipSpec();
    refined.animation.clips[0].durationSeconds = 5;
    refined.animation.clips[0].sequences[0].endSeconds = 3;
    rerender(<ThreejsModelPreview spec={refined} />);
    expect(screen.getByText('0.00/5.00s')).toBeInTheDocument();
  });
});

describe('ThreejsModelPreview spec-render failures', () => {
  // React and the shared ErrorBoundary both log every caught error.
  let logged;
  beforeEach(() => {
    logged = vi.spyOn(console, 'error').mockImplementation(() => {});
  });
  afterEach(() => {
    canvasFailure.error = null;
    vi.restoreAllMocks();
  });

  // The spec is LLM-generated, so a malformed one throws inside geometry
  // construction. Without a boundary the throw escapes to the router and blanks
  // the page — the same class of failure the GLB viewer had for meshes.
  it('shows an inline panel instead of letting a bad spec take the page down', () => {
    canvasFailure.error = new Error('THREE.BufferGeometry.computeBoundingSphere(): NaN position values');
    // Nothing catches this above the preview: without its own boundary the throw
    // escapes `render` here, exactly as it escapes to the router in the app.
    renderPreview(<ThreejsModelPreview spec={SPEC} />);

    expect(screen.getByTestId('threejs-spec-error')).toBeInTheDocument();
    expect(screen.getByText('This model spec could not be rendered')).toBeInTheDocument();
    expect(screen.getByText(/NaN position values/)).toBeInTheDocument();
    expect(screen.queryByTestId('threejs-canvas')).not.toBeInTheDocument();
    expect(logged).toHaveBeenCalledWith(expect.stringContaining('💥 React Error'), expect.anything());
    // The overlay chrome is a DOM peer that comes AFTER the panel, so leaving it
    // mounted paints it over the message — and every control on it drives a
    // canvas that no longer exists.
    expect(screen.queryByRole('radiogroup', { name: 'Preview background' })).not.toBeInTheDocument();
    expect(screen.queryByLabelText('Explode')).not.toBeInTheDocument();
    expect(screen.queryByText(/Drag to orbit/)).not.toBeInTheDocument();
  });

  // The selected-part badge is the third piece of chrome gated on the failure,
  // and it only mounts with a part in the URL — so the case above never reaches
  // it. Same defect either way: it is a DOM peer that follows the panel, so it
  // paints over the message and its Clear button drives an unmounted canvas.
  it('hides the selected-part badge behind the failure too', () => {
    canvasFailure.error = new Error('bad geometry');
    renderPreview(<ThreejsModelPreview spec={knifeSpec()} />, '/?part=handle');

    expect(screen.getByTestId('threejs-spec-error')).toBeInTheDocument();
    expect(screen.queryByText('Handle')).not.toBeInTheDocument();
    expect(screen.queryByRole('button', { name: 'Clear part selection' })).not.toBeInTheDocument();
  });

  // A lost WebGL context throws the same way a bad spec does, but it can come
  // back — and the spec signature never changes, so nothing else would clear it.
  it('recovers from a failure the spec signature can never clear', () => {
    canvasFailure.error = new Error('THREE.WebGLRenderer: Error creating WebGL context.');
    renderPreview(<ThreejsModelPreview spec={SPEC} />);
    expect(screen.getByTestId('threejs-spec-error')).toBeInTheDocument();

    canvasFailure.error = null;
    fireEvent.click(screen.getByRole('button', { name: /Retry/i }));

    expect(screen.queryByTestId('threejs-spec-error')).not.toBeInTheDocument();
    expect(screen.getByTestId('threejs-canvas')).toBeInTheDocument();
  });

  // The failure is remembered against the spec that produced it, so a
  // regeneration is not stuck behind the previous spec's bad geometry.
  it('clears the panel when a different spec arrives', () => {
    canvasFailure.error = new Error('bad geometry');
    const { rerender } = renderPreview(<ThreejsModelPreview spec={SPEC} />);
    expect(screen.getByTestId('threejs-spec-error')).toBeInTheDocument();

    canvasFailure.error = null;
    rerender(<ThreejsModelPreview spec={{ ...SPEC, name: 'Regenerated model' }} />);

    expect(screen.queryByTestId('threejs-spec-error')).not.toBeInTheDocument();
    expect(screen.getByTestId('threejs-canvas')).toBeInTheDocument();
  });
});