@linhey/rhine-design 0.6.0 → 0.8.0

package/tests/OrbitBackdrop.test.tsx

@@ -1,14 +1,20 @@
 import { StrictMode } from 'react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { act, cleanup, fireEvent, render, screen, within } from '@testing-library/react';
 import { OrbitBackdrop } from '../components';
 import { mountOrbit } from '../components/orbitRenderer';
+import { projectOrbitPoint, rotateOrbitPoint } from '../components/orbitProjection';
 import { OrbitGallery } from '../preview/OrbitGallery';
 
 class Media extends EventTarget {
   matches = false;
   set(value: boolean) { this.matches = value; this.dispatchEvent(new Event('change')); }
 }
+type PathCommand = [kind: 'move' | 'line' | 'arc' | 'rect' | 'close', ...coordinates: number[]];
+type Paint = {
+  kind: 'stroke' | 'fill'; path: PathCommand[]; color: string | CanvasGradient | CanvasPattern;
+  width: number; dash: number[]; dashOffset: number; cap: CanvasLineCap; join: CanvasLineJoin;
+};
 
 describe('OrbitBackdrop artwork and lifecycle', () => {
   let reduced: Media, compact: Media, hidden: boolean, bounds: { width: number; height: number };
@@ -18,11 +24,28 @@ describe('OrbitBackdrop artwork and lifecycle', () => {
   let draws: number, lines: number, trails: number, glows: number, firstPoint: number[], firstRadius: number, zoom: number;
   let hasPoint: boolean;
   let context: CanvasRenderingContext2D;
+  let paletteStyles: HTMLStyleElement;
+  let gradientColors: Set<string>;
+  let recordPaint: boolean, painted: Paint[], dashes: number[];
 
   beforeEach(() => {
     reduced = new Media(); compact = new Media(); hidden = false;
     bounds = { width: 600, height: 680 }; frameId = 0; frames = new Map();
     draws = lines = trails = glows = firstRadius = 0; firstPoint = []; hasPoint = false; zoom = 1;
+    gradientColors = new Set();
+    recordPaint = false; painted = []; dashes = [];
+    paletteStyles = document.createElement('style');
+    paletteStyles.textContent = `
+      .orbit-palette-fixture { --rhine-orbit-highlight: #165f49; }
+      .orbit-palette-fixture[data-rhine-theme="arknights"] { --rhine-orbit-highlight: #d9b477; }
+      .orbit-palette-fixture.alternate-palette { --rhine-orbit-highlight: #ed7020; }
+      .orbit-palette-fixture [data-rhine-orbit-appearance="original"] { --rhine-orbit-highlight: #ff658c; }
+      .orbit-linework-fixture { --rhine-orbit-linework: paper; }
+      .orbit-linework-fixture[data-rhine-theme="arknights"] { --rhine-orbit-linework: technical; }
+      .orbit-linework-fixture[data-rhine-theme="neo-brutalism"] { --rhine-orbit-linework: donut; }
+      .orbit-linework-fixture [data-rhine-orbit-appearance="original"] { --rhine-orbit-linework: original; }
+    `;
+    document.head.append(paletteStyles);
     resizeDisconnect = vi.fn(); intersectionDisconnect = vi.fn();
     vi.spyOn(document, 'hidden', 'get').mockImplementation(() => hidden);
     vi.spyOn(HTMLCanvasElement.prototype, 'clientWidth', 'get').mockImplementation(() => bounds.width);
@@ -37,29 +60,67 @@ describe('OrbitBackdrop artwork and lifecycle', () => {
       observe(target: Element) { intersect = value => this.callback([{ target, isIntersecting: value }]); }
       disconnect() { intersectionDisconnect(); }
     });
-    const gradient = { addColorStop() {} };
+    const gradient = { addColorStop(_offset: number, color: string) { gradientColors.add(color); } };
+    const states: Partial<CanvasRenderingContext2D>[] = [], savedDashes: number[][] = [];
+    let path: PathCommand[] = [];
+    const record = (command: PathCommand) => { if (recordPaint) path.push(command); };
+    const paint = (kind: Paint['kind'], commands = path) => {
+      if (recordPaint) painted.push({ kind, path: [...commands], color: kind === 'stroke' ? context.strokeStyle : context.fillStyle,
+        width: context.lineWidth, dash: [...dashes], dashOffset: context.lineDashOffset, cap: context.lineCap, join: context.lineJoin });
+    };
     context = {
-      setTransform() {}, clearRect() { draws++; lines = trails = glows = firstRadius = 0; hasPoint = false; },
-      beginPath() {}, closePath() {}, stroke() {}, fill() {}, arc(_x: number, _y: number, radius: number) { if (!firstRadius) firstRadius = radius; },
-      moveTo(x: number, y: number) { if (!hasPoint) { hasPoint = true; firstPoint = [x, y]; } },
-      lineTo() { lines++; },
+      lineWidth: 1, globalAlpha: 1, shadowOffsetX: 0, shadowOffsetY: 0, shadowBlur: 0, lineDashOffset: 0, lineCap: 'butt', lineJoin: 'miter',
+      save() {
+        states.push({ lineWidth: context.lineWidth, globalAlpha: context.globalAlpha, strokeStyle: context.strokeStyle, fillStyle: context.fillStyle,
+          lineCap: context.lineCap, lineJoin: context.lineJoin, lineDashOffset: context.lineDashOffset, shadowBlur: context.shadowBlur, shadowColor: context.shadowColor, shadowOffsetX: context.shadowOffsetX, shadowOffsetY: context.shadowOffsetY });
+        savedDashes.push([...dashes]);
+      },
+      restore() { Object.assign(context, states.pop()); dashes = savedDashes.pop() ?? []; },
+      setTransform() {},
+      clearRect() {
+        draws++; lines = trails = glows = firstRadius = 0; hasPoint = false;
+        painted = []; path = [];
+      },
+      beginPath() { path = []; }, closePath() { record(['close']); },
+      stroke() { paint('stroke'); }, fill() { paint('fill'); },
+      arc(x: number, y: number, radius: number, start: number, end: number) { if (!firstRadius) firstRadius = radius; record(['arc', x, y, radius, start, end]); },
+      rect(x: number, y: number, width: number, height: number) { record(['rect', x, y, width, height]); },
+      fillRect(x: number, y: number, width: number, height: number) { paint('fill', [['rect', x, y, width, height]]); },
+      strokeRect(x: number, y: number, width: number, height: number) { paint('stroke', [['rect', x, y, width, height]]); },
+      moveTo(x: number, y: number) { if (!hasPoint) { hasPoint = true; firstPoint = [x, y]; } record(['move', x, y]); },
+      lineTo(x: number, y: number) { lines++; record(['line', x, y]); },
+      setLineDash(segments: number[]) { dashes = [...segments]; }, getLineDash() { return [...dashes]; },
       createLinearGradient() { trails++; return gradient; },
       createRadialGradient() { glows++; return gradient; },
     } as unknown as CanvasRenderingContext2D;
     vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue(context);
   });
-  afterEach(() => { cleanup(); document.documentElement.removeAttribute('data-rhine-motion'); vi.restoreAllMocks(); vi.unstubAllGlobals(); });
+  afterEach(() => { cleanup(); paletteStyles.remove(); document.documentElement.removeAttribute('data-rhine-motion'); vi.restoreAllMocks(); vi.unstubAllGlobals(); });
 
   function advance(now: number) {
     act(() => { const pending = [...frames.values()]; frames.clear(); pending.forEach(callback => callback(now)); });
   }
 
+  it('keeps the shared camera aligned with the original orbit reference axes', () => {
+    const references = [
+      { point: { x: 1, y: 0, z: 0 }, x: 86.76980178489757, y: 33.1491730947802, depth: .6593846719714731 },
+      { point: { x: 0, y: 1, z: 0 }, x: -48.312703948795914, y: 98.67789420213471, depth: .16406628090045566 },
+      { point: { x: 0, y: 0, z: 1 }, x: -67.05339595630653, y: -57.01591387412629, depth: .7336852934607355 },
+    ];
+    for (const reference of references) {
+      const actual = projectOrbitPoint(rotateOrbitPoint(reference.point), 100, 0, 0);
+      expect(actual.x).toBeCloseTo(reference.x, 10); expect(actual.y).toBeCloseTo(reference.y, 10);
+      expect(actual.depth).toBeCloseTo(reference.depth, 10);
+    }
+  });
+
   it('retains the complete seeded artwork, caps pixel density and pauses without catching up', () => {
     vi.stubGlobal('devicePixelRatio', 3);
     const canvas = document.createElement('canvas'); document.body.append(canvas);
     const scene = mountOrbit(canvas, () => {});
     expect(canvas.width).toBe(1200); expect(canvas.height).toBe(1360);
     expect(trails).toBe(420); expect(glows).toBe(140); expect(lines).toBeGreaterThan(185 * 80);
+    expect(gradientColors).toEqual(new Set(['#addaff', '#addaff00', '#e1a147', '#e1a14700']));
     advance(100); const initial = [...firstPoint]; advance(200); const moving = [...firstPoint];
     expect(moving).not.toEqual(initial);
     scene.setPaused(true); const stoppedDraws = draws;
@@ -97,6 +158,105 @@ describe('OrbitBackdrop artwork and lifecycle', () => {
     advance(100); expect(snapshot()).toEqual(before); expect(frames.size).toBe(1);
   });
 
+  it('recolors a paused frame when its theme or appearance changes without remounting or losing content', async () => {
+    const view = (theme: string, appearance: 'theme' | 'original' = 'theme') => <div className="orbit-palette-fixture" data-rhine-theme={theme}>
+      <OrbitBackdrop appearance={appearance}><input aria-label="轨道草稿" defaultValue="起点" /></OrbitBackdrop>
+    </div>;
+    const { container, rerender } = render(view('default'));
+    const canvas = container.querySelector('canvas');
+    expect(context.fillStyle).toBe('#165f49');
+    expect(container.querySelector('.rhine-orbit')).toHaveAttribute('data-rhine-orbit-appearance', 'theme');
+    advance(100); advance(200);
+    fireEvent.change(screen.getByLabelText('轨道草稿'), { target: { value: '保留草稿' } });
+    fireEvent.click(screen.getByRole('button', { name: '暂停动效' }));
+    const frozen = [...firstPoint], before = draws;
+    await act(async () => { rerender(view('arknights')); });
+    expect(draws).toBeGreaterThan(before); expect(context.fillStyle).toBe('#d9b477');
+    expect(firstPoint).toEqual(frozen); expect(frames.size).toBe(0);
+    await act(async () => { rerender(view('arknights', 'original')); });
+    expect(context.fillStyle).toBe('#ff658c'); expect(firstPoint).toEqual(frozen); expect(frames.size).toBe(0);
+    await act(async () => { rerender(view('default', 'original')); });
+    expect(context.fillStyle).toBe('#ff658c');
+    await act(async () => { rerender(view('default')); });
+    expect(context.fillStyle).toBe('#165f49'); expect(firstPoint).toEqual(frozen);
+    expect(container.querySelector('canvas')).toBe(canvas);
+    expect(HTMLCanvasElement.prototype.getContext).toHaveBeenCalledTimes(1);
+    expect(screen.getByLabelText('轨道草稿')).toHaveValue('保留草稿');
+    expect(screen.getByRole('button', { name: '继续动效' })).toBeEnabled();
+    fireEvent.click(screen.getByRole('button', { name: '继续动效' }));
+    advance(10000); expect(firstPoint).toEqual(frozen);
+    advance(10100); expect(firstPoint).not.toEqual(frozen); expect(frames.size).toBe(1);
+  });
+
+  it('responds to CSS-only root classes and token overrides, without reading styles on every frame', async () => {
+    const styleReads = vi.spyOn(window, 'getComputedStyle');
+    const { container, unmount } = render(<div className="orbit-palette-fixture"><OrbitBackdrop /></div>);
+    const root = container.firstElementChild as HTMLElement;
+    expect(context.fillStyle).toBe('#165f49');
+    const readCount = styleReads.mock.calls.length;
+    advance(100); advance(200);
+    expect(styleReads.mock.calls.length).toBe(readCount);
+    const frozen = [...firstPoint];
+    await act(async () => { root.classList.add('alternate-palette'); });
+    expect(context.fillStyle).toBe('#ed7020'); expect(firstPoint).toEqual(frozen); expect(frames.size).toBe(1);
+    advance(10000); expect(firstPoint).toEqual(frozen);
+    advance(10100); expect(firstPoint).not.toEqual(frozen);
+    fireEvent.click(screen.getByRole('button', { name: '暂停动效' }));
+    const pausedPoint = [...firstPoint];
+    await act(async () => { root.style.setProperty('--rhine-orbit-highlight', 'rgb(32, 114, 153)'); });
+    expect(context.fillStyle).toBe('rgb(32, 114, 153)'); expect(firstPoint).toEqual(pausedPoint); expect(frames.size).toBe(0);
+    unmount(); const finalDraws = draws;
+    await act(async () => { root.style.setProperty('--rhine-orbit-highlight', '#abcdef'); });
+    expect(draws).toBe(finalDraws); expect(frames.size).toBe(0);
+  });
+
+  it('preserves color channels in transparent gradient stops for normalized RGB and wide-gamut colors', async () => {
+    const { container } = render(<OrbitBackdrop reducedMotion />);
+    const root = container.firstElementChild as HTMLElement;
+    gradientColors.clear();
+    await act(async () => {
+      root.style.setProperty('--rhine-orbit-trail-near', 'rgb(32, 114, 153)');
+      root.style.setProperty('--rhine-orbit-trail-far', 'color(display-p3 0.7 0.3 0.1 / 0.8)');
+    });
+    expect(gradientColors).toEqual(new Set(['rgb(32, 114, 153)', 'rgba(32,114,153,0)', 'color(display-p3 0.7 0.3 0.1 / 0.8)', 'color(display-p3 0.7 0.3 0.1 / 0)']));
+    expect(frames.size).toBe(0);
+  });
+
+  it('preserves the original geometry across host themes while object themes keep the same frozen clock and content', async () => {
+    recordPaint = true;
+    const view = (theme: string, appearance: 'theme' | 'original' = 'theme') => <div className="orbit-linework-fixture" data-rhine-theme={theme}>
+      <OrbitBackdrop appearance={appearance}><input aria-label="主题草稿" defaultValue="保留内容" /></OrbitBackdrop>
+    </div>;
+    const { container, rerender } = render(view('default', 'original'));
+    const canvas = container.querySelector('canvas');
+    advance(100); advance(200);
+    fireEvent.change(screen.getByLabelText('主题草稿'), { target: { value: '保留我的输入' } });
+    fireEvent.click(screen.getByRole('button', { name: '暂停动效' }));
+    const original = painted;
+    expect(trails).toBe(420); expect(glows).toBe(140);
+    for (const theme of ['arknights', 'neo-brutalism', 'default']) {
+      await act(async () => { rerender(view(theme, 'original')); });
+      expect(painted).toEqual(original); expect(frames.size).toBe(0);
+    }
+    const paintings: Paint[][] = [];
+    for (const theme of ['default', 'arknights']) {
+      await act(async () => { rerender(view(theme)); });
+      const frozen = painted; paintings.push(frozen);
+      expect(trails).toBe(0); expect(glows).toBe(0); expect(frozen.length).toBeGreaterThan(100);
+      advance(5000); expect(painted).toEqual(frozen);
+      await act(async () => { rerender(view(theme, 'original')); });
+      expect(painted).toEqual(original);
+      await act(async () => { rerender(view(theme)); });
+      expect(painted).toEqual(frozen); expect(frames.size).toBe(0);
+    }
+    expect(paintings[0]).not.toEqual(paintings[1]);
+    fireEvent.click(screen.getByRole('button', { name: '继续动效' }));
+    advance(10000); expect(painted).toEqual(paintings[1]);
+    advance(10100); expect(painted).not.toEqual(paintings[1]);
+    expect(container.querySelector('canvas')).toBe(canvas);
+    expect(screen.getByLabelText('主题草稿')).toHaveValue('保留我的输入');
+  });
+
   it('honors system and explicit reduction, and never lets false bypass the system', () => {
     reduced.matches = true;
     const { rerender } = render(<OrbitBackdrop reducedMotion={false} />);
@@ -132,6 +292,70 @@ describe('OrbitBackdrop artwork and lifecycle', () => {
     expect(frames.size).toBe(1);
   });
 
+  it('rotates a strawberry donut on compact Neo screens and preserves its frozen frame across appearance changes', async () => {
+    recordPaint = true; compact.matches = true;
+    const view = (appearance: 'theme' | 'original' = 'theme', theme = 'neo-brutalism') => <div className="orbit-linework-fixture" data-rhine-theme={theme}>
+      <OrbitBackdrop appearance={appearance}><input aria-label="甜甜圈草稿" defaultValue="保留" /></OrbitBackdrop>
+    </div>;
+    const { container, rerender } = render(view());
+    const canvas = container.querySelector('canvas');
+    expect(screen.getByRole('button', { name: '暂停动效' })).toBeEnabled();
+    const pinkFaces = painted.filter(paint => {
+      if (paint.kind !== 'fill') return false;
+      const rgb = String(paint.color).match(/^rgb\((\d+),(\d+),(\d+)\)$/);
+      return rgb && Number(rgb[1]) > Number(rgb[3]) && Number(rgb[3]) > Number(rgb[2]);
+    });
+    expect(pinkFaces.length).toBeGreaterThan(100);
+    expect(trails).toBe(0); expect(glows).toBe(0);
+    advance(100); const firstFrame = painted;
+    advance(200); expect(painted).not.toEqual(firstFrame);
+    fireEvent.change(screen.getByLabelText('甜甜圈草稿'), { target: { value: '保留我的输入' } });
+    fireEvent.click(screen.getByRole('button', { name: '暂停动效' }));
+    const frozen = painted;
+    expect(frames.size).toBe(0);
+    advance(5000); expect(painted).toEqual(frozen);
+    await act(async () => { rerender(view('original')); });
+    expect(screen.getByRole('button', { name: '窄屏静态画面' })).toBeDisabled();
+    expect(trails).toBe(420); expect(glows).toBe(140);
+    await act(async () => { rerender(view('theme', 'arknights')); });
+    expect(screen.getByRole('button', { name: '继续动效' })).toBeEnabled();
+    await act(async () => { rerender(view()); });
+    expect(screen.getByRole('button', { name: '继续动效' })).toBeEnabled();
+    expect(painted).toEqual(frozen); expect(frames.size).toBe(0);
+    expect(container.querySelector('canvas')).toBe(canvas);
+    expect(screen.getByLabelText('甜甜圈草稿')).toHaveValue('保留我的输入');
+    fireEvent.click(screen.getByRole('button', { name: '继续动效' }));
+    advance(10000); expect(painted).toEqual(frozen);
+    advance(10100); expect(painted).not.toEqual(frozen);
+  });
+
+  it.each(['default', 'arknights', 'neo-brutalism'])('stops the %s object for every motion preference, visibility change and disposal', async theme => {
+    const view = (explicit = false) => <div className="orbit-linework-fixture" data-rhine-theme={theme}>
+      <OrbitBackdrop reducedMotion={explicit} />
+    </div>;
+    compact.matches = true;
+    const { rerender, unmount } = render(view());
+    expect(frames.size).toBe(1);
+    act(() => reduced.set(true)); expect(frames.size).toBe(0);
+    rerender(view(false)); expect(frames.size).toBe(0);
+    expect(screen.getByRole('button', { name: '已减少动态' })).toBeDisabled();
+    act(() => reduced.set(false)); expect(frames.size).toBe(1);
+    rerender(view(true)); expect(frames.size).toBe(0);
+    rerender(view(false)); expect(frames.size).toBe(1);
+    await act(async () => { document.documentElement.setAttribute('data-rhine-motion', 'reduced'); });
+    expect(frames.size).toBe(0);
+    await act(async () => { document.documentElement.removeAttribute('data-rhine-motion'); });
+    expect(frames.size).toBe(1);
+    act(() => { hidden = true; document.dispatchEvent(new Event('visibilitychange')); }); expect(frames.size).toBe(0);
+    act(() => { hidden = false; document.dispatchEvent(new Event('visibilitychange')); }); expect(frames.size).toBe(1);
+    act(() => intersect(false)); expect(frames.size).toBe(0);
+    act(() => intersect(true)); expect(frames.size).toBe(1);
+    unmount(); const finalDraws = draws;
+    expect(frames.size).toBe(0);
+    await act(async () => { resize(); intersect(true); reduced.set(true); });
+    expect(draws).toBe(finalDraws);
+  });
+
   it('stops while hidden, offscreen, compact or empty and redraws a paused resize', () => {
     const { container } = render(<OrbitBackdrop />);
     act(() => { hidden = true; document.dispatchEvent(new Event('visibilitychange')); }); expect(frames.size).toBe(0);
@@ -170,12 +394,25 @@ describe('OrbitBackdrop artwork and lifecycle', () => {
     expect(screen.getByRole('button', { name: '静态画面' })).toBeDisabled(); expect(frames.size).toBe(0);
   });
 
-  it('replays the gallery artwork while preserving entered content and external replay focus', () => {
+  it('keeps the gallery artwork clear and preserves paused state and drafts across appearance changes and replay', async () => {
     const { container } = render(<OrbitGallery />); const canvas = container.querySelector('canvas');
+    const main = screen.getByRole('region', { name: '轨道背景预览' });
+    expect(within(main).queryByRole('textbox')).not.toBeInTheDocument();
+    expect(within(main).getAllByRole('button')).toHaveLength(1);
+    const disclosure = screen.getByText('查看组合控件示例');
+    expect(disclosure.closest('details')).not.toHaveAttribute('open');
+    fireEvent.click(disclosure);
     fireEvent.change(screen.getByRole('textbox', { name: '直接叠加的输入框' }), { target: { value: '新的轨道名称' } });
     fireEvent.change(screen.getByRole('textbox', { name: '工作空间名称' }), { target: { value: '新的工作空间' } });
+    fireEvent.click(within(main).getByRole('button', { name: '暂停动效' }));
+    await act(async () => { fireEvent.click(screen.getByRole('radio', { name: '原始深色' })); });
+    expect(container.querySelector('canvas')).toBe(canvas);
+    expect(main).toHaveAttribute('data-rhine-orbit-appearance', 'original');
+    expect(within(main).getByRole('button', { name: '继续动效' })).toBeEnabled();
+    await act(async () => { fireEvent.click(screen.getByRole('radio', { name: '跟随主题' })); });
+    expect(within(main).getByRole('button', { name: '继续动效' })).toBeEnabled();
     const replay = screen.getByRole('button', { name: '重播轨道' }); replay.focus(); fireEvent.click(replay);
-    expect(container.querySelector('canvas')).not.toBe(canvas); expect(replay).toHaveFocus(); expect(frames.size).toBe(1);
+    expect(container.querySelector('canvas')).not.toBe(canvas); expect(replay).toHaveFocus(); expect(frames.size).toBe(2);
     expect(screen.getByRole('textbox', { name: '直接叠加的输入框' })).toHaveValue('新的轨道名称');
     expect(screen.getByRole('textbox', { name: '工作空间名称' })).toHaveValue('新的工作空间');
     fireEvent.click(screen.getByRole('switch', { name: '减少轨道动态' })); expect(frames.size).toBe(0);

package/tests/OrbitDonutThree.test.tsx

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { BufferGeometry, InstancedMesh, Material, Texture, Vector3, type Mesh, type PerspectiveCamera, type Scene } from 'three';
+import { createDonutArtwork } from '../components/orbitDonutThree';
+import { projectOrbitPoint, rotateOrbitPoint } from '../components/orbitProjection';
+
+const gpu = vi.hoisted(() => ({ renderers: [] as Array<{
+  scene?: Scene; camera?: PerspectiveCamera; draws: number; dispose: ReturnType<typeof vi.fn>; forceContextLoss: ReturnType<typeof vi.fn>;
+}> }));
+vi.mock('three', async importOriginal => {
+  const actual = await importOriginal<typeof import('three')>();
+  return { ...actual, WebGLRenderer: class {
+    ratio = 1; draws = 0; scene?: Scene; camera?: PerspectiveCamera;
+    dispose = vi.fn(); forceContextLoss = vi.fn();
+    constructor(private options: { canvas: HTMLCanvasElement }) { gpu.renderers.push(this); }
+    setClearColor() {} setPixelRatio(value: number) { this.ratio = value; }
+    setSize(width: number, height: number) { this.options.canvas.width = Math.round(width * this.ratio); this.options.canvas.height = Math.round(height * this.ratio); }
+    render(scene: Scene, camera: PerspectiveCamera) { this.scene = scene; this.camera = camera; this.draws++; scene.updateMatrixWorld(); camera.updateMatrixWorld(); }
+  } };
+});
+
+describe('Three.js strawberry artwork', () => {
+  beforeEach(() => {
+    gpu.renderers = [];
+    vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue({
+      createLinearGradient: () => ({ addColorStop() {} }), fillRect() {}, beginPath() {}, ellipse() {}, fill() {},
+    } as unknown as CanvasRenderingContext2D);
+    vi.stubGlobal('requestAnimationFrame', vi.fn());
+  });
+  afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); });
+
+  it('renders detailed geometry and deterministic particles using only the supplied clock', () => {
+    vi.stubGlobal('devicePixelRatio', 3);
+    const art = createDonutArtwork(vi.fn()); art.draw(400, 620, 1);
+    const renderer = gpu.renderers[0], scene = renderer.scene!;
+    expect(art.canvas.width).toBe(600); expect(art.canvas.height).toBe(930);
+    expect((scene.getObjectByName('icing-sprinkles') as InstancedMesh).count).toBe(280);
+    expect((scene.getObjectByName('sugar-pearls') as InstancedMesh).count).toBe(110);
+    const icing = (scene.getObjectByName('strawberry-icing') as Mesh).geometry.getAttribute('position');
+    const radii = Array.from({ length: icing.count }, (_, i) => Math.hypot(icing.getX(i), icing.getY(i)));
+    // The ring should occupy the original artwork's envelope, even with real tube thickness.
+    expect(Math.max(...radii)).toBeGreaterThan(1.19); expect(Math.max(...radii)).toBeLessThan(1.22);
+    expect(Math.min(...radii)).toBeGreaterThan(.46); expect(Math.min(...radii)).toBeLessThan(.49);
+    const confetti = scene.getObjectByName('floating-confetti') as InstancedMesh;
+    expect(confetti.count).toBe(100);
+    const capture = () => ({ ring: scene.getObjectByName('strawberry-donut')!.matrixWorld.toArray(), particles: [...confetti.instanceMatrix.array] });
+    const frozen = capture(); art.draw(400, 620, 1); expect(capture()).toEqual(frozen);
+    art.draw(400, 620, 2); expect(capture().ring).not.toEqual(frozen.ring); expect(capture().particles).not.toEqual(frozen.particles);
+    expect(requestAnimationFrame).not.toHaveBeenCalled(); art.dispose();
+  });
+
+  it.each([[400, 620], [520, 360], [880, 526]])('matches the original scale, center and tilt at %s × %s over time', (width, height) => {
+    const art = createDonutArtwork(vi.fn());
+    for (const time of [0, 1, 4, 10]) {
+      art.draw(width, height, time);
+      const renderer = gpu.renderers[0], donut = renderer.scene!.getObjectByName('strawberry-donut')!;
+      for (const p of [new Vector3(0, 0, 0), new Vector3(1.2, 0, .2), new Vector3(0, 1.1, -.1), new Vector3(-.8, -.3, .4)]) {
+        const spin = time * .28 - .35;
+        const rotated = rotateOrbitPoint({ x: p.x * Math.cos(spin) - p.y * Math.sin(spin), y: p.x * Math.sin(spin) + p.y * Math.cos(spin), z: p.z });
+        const expected = projectOrbitPoint(rotated, Math.min(width * .66, height * .39), width * .62, height * .57);
+        const projected = p.clone().applyMatrix4(donut.matrixWorld).project(renderer.camera!);
+        expect((projected.x + 1) * width / 2).toBeCloseTo(expected.x, 6);
+        expect((1 - projected.y) * height / 2).toBeCloseTo(expected.y, 6);
+      }
+    }
+    art.dispose();
+  });
+
+  it('falls back during context loss and releases geometry, textures and instance resources once', () => {
+    const disposeGeometry = vi.spyOn(BufferGeometry.prototype, 'dispose'), disposeMaterial = vi.spyOn(Material.prototype, 'dispose');
+    const disposeTexture = vi.spyOn(Texture.prototype, 'dispose'), disposeInstance = vi.spyOn(InstancedMesh.prototype, 'dispose');
+    const invalidate = vi.fn(), art = createDonutArtwork(invalidate); art.draw(880, 526, 3);
+    const renderer = gpu.renderers[0], lost = new Event('webglcontextlost', { cancelable: true }); art.canvas.dispatchEvent(lost);
+    expect(lost.defaultPrevented).toBe(true); expect(art.draw(880, 526, 8)).toBe(false);
+    art.canvas.dispatchEvent(new Event('webglcontextrestored')); expect(invalidate).toHaveBeenCalledTimes(2);
+    expect(art.draw(880, 526, 3)).toBe(true);
+    art.dispose(); art.dispose();
+    expect(disposeGeometry).toHaveBeenCalledTimes(8); expect(disposeMaterial).toHaveBeenCalledTimes(9);
+    expect(disposeTexture).toHaveBeenCalledOnce(); expect(disposeInstance).toHaveBeenCalledTimes(4);
+    expect(renderer.dispose).toHaveBeenCalledOnce(); expect(renderer.forceContextLoss).toHaveBeenCalledOnce();
+    art.canvas.dispatchEvent(new Event('webglcontextrestored')); expect(invalidate).toHaveBeenCalledTimes(2);
+    expect(art.draw(880, 526, 9)).toBe(false);
+  });
+
+  it('cleans allocations if initialization fails before the first frame', () => {
+    const disposeGeometry = vi.spyOn(BufferGeometry.prototype, 'dispose'), disposeTexture = vi.spyOn(Texture.prototype, 'dispose');
+    vi.spyOn(InstancedMesh.prototype, 'setMatrixAt').mockImplementationOnce(() => { throw new Error('Synthetic GPU setup failure'); });
+    expect(() => createDonutArtwork(vi.fn())).toThrow('Synthetic GPU setup failure');
+    expect(disposeGeometry).toHaveBeenCalled(); expect(disposeTexture).toHaveBeenCalledOnce();
+    expect(gpu.renderers[0].dispose).toHaveBeenCalledOnce(); expect(gpu.renderers[0].forceContextLoss).toHaveBeenCalledOnce();
+  });
+});

package/tests/OrbitObjectsThree.test.tsx

@@ -0,0 +1,164 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { BufferGeometry, InstancedMesh, Material, Texture, Vector3, type Mesh, type PerspectiveCamera, type Points, type Scene, type ShaderMaterial } from 'three';
+import { createOrbitObject, type OrbitObjectKind } from '../components/orbitObjectsThree';
+
+const gpu = vi.hoisted(() => ({ renderers: [] as Array<{
+  scene?: Scene; camera?: PerspectiveCamera; dispose: ReturnType<typeof vi.fn>; forceContextLoss: ReturnType<typeof vi.fn>;
+}> }));
+vi.mock('three', async importOriginal => {
+  const actual = await importOriginal<typeof import('three')>();
+  return { ...actual, WebGLRenderer: class {
+    ratio = 1; scene?: Scene; camera?: PerspectiveCamera;
+    dispose = vi.fn(); forceContextLoss = vi.fn();
+    constructor(private options: { canvas: HTMLCanvasElement }) { gpu.renderers.push(this); }
+    setClearColor() {} setPixelRatio(value: number) { this.ratio = value; }
+    setSize(width: number, height: number) { this.options.canvas.width = Math.round(width * this.ratio); this.options.canvas.height = Math.round(height * this.ratio); }
+    render(scene: Scene, camera: PerspectiveCamera) { this.scene = scene; this.camera = camera; scene.updateMatrixWorld(); camera.updateMatrixWorld(); }
+  } };
+});
+
+describe.each<OrbitObjectKind>(['paper', 'technical'])('Three.js %s object', kind => {
+  beforeEach(() => {
+    gpu.renderers = []; vi.stubGlobal('requestAnimationFrame', vi.fn()); vi.stubGlobal('devicePixelRatio', 3);
+    vi.spyOn(HTMLCanvasElement.prototype, 'getContext').mockReturnValue({ createLinearGradient: () => ({ addColorStop() {} }), fillRect() {}, fillText() {} } as unknown as CanvasRenderingContext2D);
+  });
+  afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); });
+
+  it('animates the object and particles deterministically from the host clock, including after resize', () => {
+    const art = createOrbitObject(kind, vi.fn());
+    expect(art.draw(0, 620, 1)).toBe(false);
+    art.draw(400, 620, 1);
+    expect(art.canvas.width).toBe(600); expect(art.canvas.height).toBe(930);
+    const scene = gpu.renderers[0].scene!, bird = kind === 'paper';
+    expect(scene.name).toBe(bird ? 'origami-paper-bird' : 'originium-cluster');
+    const particles = scene.getObjectByName(bird ? 'floating-paper-flecks' : 'floating-fragments') as InstancedMesh;
+    const dust = scene.getObjectByName(bird ? 'paper-motes' : 'crystal-embers') as Points<BufferGeometry, ShaderMaterial>;
+    const capture = () => ({ wings: bird ? ['paper-wing-left', 'paper-wing-right'].map(name => scene.getObjectByName(name)!.rotation.z) : [], object: scene.getObjectByName('theme-object')!.matrixWorld.toArray(), particles: [...particles.instanceMatrix.array], time: dust.material.uniforms.time.value });
+    const frozen = capture(); art.draw(400, 620, 1); expect(capture()).toEqual(frozen);
+    art.draw(880, 526, 1); expect(capture()).toEqual(frozen);
+    art.draw(880, 526, 2); expect(capture().object).not.toEqual(frozen.object); expect(capture().particles).not.toEqual(frozen.particles);
+    expect(capture().time).toBe(2);
+    if (bird) {
+      expect(capture().wings).not.toEqual(frozen.wings);
+      const body = scene.getObjectByName('folded-body') as Mesh;
+      expect(body.geometry.getAttribute('position').count).toBeGreaterThan(20);
+      expect(scene.getObjectByName('paper-wing-left')).toBeDefined();
+      expect(scene.getObjectByName('paper-wing-right')).toBeDefined();
+      expect(scene.getObjectByName('folded-neck-and-beak')).toBeDefined();
+    } else {
+      for (let i = 0; i < 5; i++) expect(scene.getObjectByName(`originium-facet-${i}`)).toBeDefined();
+      expect(scene.getObjectByName('containment-ring')).toBeDefined();
+    }
+    expect(requestAnimationFrame).not.toHaveBeenCalled(); art.dispose();
+  });
+
+  if (kind === 'paper') it('continuously reshapes the existing paper buffers and creases, freezes mid-fold and reverses', () => {
+    const art = createOrbitObject(kind, vi.fn());
+    art.draw(880, 526, 0);
+    const object = gpu.renderers[0].scene!.getObjectByName('theme-object')!;
+    const meshes: Mesh[] = [];
+    object.traverse(node => { if ((node as Mesh).geometry) meshes.push(node as Mesh); });
+    const identities = meshes.map(mesh => [mesh.uuid, mesh.geometry.uuid, mesh.geometry.getAttribute('position')]);
+    const capture = () => meshes.map(mesh => [...mesh.geometry.getAttribute('position').array]);
+    const bird = capture();
+    art.draw(880, 526, 11); const halfway = capture();
+    expect(halfway).not.toEqual(bird);
+    art.draw(520, 460, 11); expect(capture()).toEqual(halfway);
+    art.draw(880, 526, 11.0001);
+    const adjacent = capture();
+    expect(Math.max(...adjacent.flatMap((points, i) => points.map((v, j) => Math.abs(v - halfway[i][j]))))).toBeLessThan(.001);
+    art.draw(880, 526, 21); const butterfly = capture();
+    expect(butterfly).not.toEqual(bird); expect(butterfly).not.toEqual(halfway);
+    expect(butterfly.every(points => points.every(Number.isFinite))).toBe(true);
+    art.draw(880, 526, 31); expect(capture()).toEqual(halfway);
+    art.draw(880, 526, 42); expect(capture()).toEqual(bird);
+    expect(meshes.map(mesh => [mesh.uuid, mesh.geometry.uuid, mesh.geometry.getAttribute('position')])).toEqual(identities);
+    expect(object.children.every(child => child.visible)).toBe(true);
+    art.dispose();
+  });
+
+  if (kind === 'paper') it('opens a nearly flat sheet between two folding gestures and suspends flapping', () => {
+    const art = createOrbitObject(kind, vi.fn());
+    const heightAt = (time: number) => {
+      art.draw(880, 526, time);
+      const wing = gpu.renderers[0].scene!.getObjectByName('paper-wing-left')!;
+      expect(Math.abs(wing.rotation.z)).toBe(0);
+      let height = 0;
+      wing.traverse(node => {
+        const positions = (node as Mesh).geometry?.getAttribute('position');
+        if (positions) for (let i = 0; i < positions.count; i++) height = Math.max(height, Math.abs(positions.getY(i)));
+      });
+      return height;
+    };
+    const gathered = heightAt(6.2), opened = heightAt(11), refolded = heightAt(14.4);
+    expect(opened).toBeLessThan(.08);
+    expect(gathered).toBeGreaterThan(opened * 4);
+    expect(refolded).toBeGreaterThan(opened * 4);
+    art.dispose();
+  });
+
+  if (kind === 'paper') it('flies, banks and beats its wings without leaving desktop or narrow frames', () => {
+    const art = createOrbitObject(kind, vi.fn()), vertex = new Vector3();
+    const motion: number[][] = [];
+    let maxX = 0, maxY = 0, extreme = '';
+    for (const [width, height] of [[400,360],[520,460],[880,526]]) for (let time = 0; time <= 84; time += .5) {
+      art.draw(width, height, time);
+      const { scene, camera } = gpu.renderers[0];
+      const bird = scene!.getObjectByName('theme-object')!;
+      motion.push([bird.position.x, bird.position.y, bird.position.z, bird.rotation.z, scene!.getObjectByName('paper-wing-left')!.rotation.z]);
+      scene!.getObjectByName('theme-object')!.traverse(node => {
+        const positions = (node as Mesh).geometry?.getAttribute('position');
+        if (!positions) return;
+        for (let i = 0; i < positions.count; i++) {
+          vertex.fromBufferAttribute(positions, i).applyMatrix4(node.matrixWorld).project(camera!);
+          maxX = Math.max(maxX, Math.abs(vertex.x));
+          if (Math.abs(vertex.y) > maxY) { maxY = Math.abs(vertex.y); extreme = `${width}x${height} t=${time} ${node.name}`; }
+        }
+      });
+    }
+    expect(maxX).toBeLessThan(.96);
+    expect(maxY, extreme).toBeLessThan(.94);
+    for (const [axis, minimumSpan] of [ .7, .3, .38, .22, .5 ].entries()) {
+      const values = motion.map(pose => pose[axis]);
+      expect(Math.max(...values) - Math.min(...values)).toBeGreaterThan(minimumSpan);
+    }
+    art.dispose();
+  });
+
+  it('recovers a frozen context and releases every owned resource exactly once', () => {
+    const geometrySpy = vi.spyOn(BufferGeometry.prototype, 'dispose'), materialSpy = vi.spyOn(Material.prototype, 'dispose');
+    const instanceSpy = vi.spyOn(InstancedMesh.prototype, 'dispose'), textureSpy = vi.spyOn(Texture.prototype, 'dispose'), invalidate = vi.fn();
+    const art = createOrbitObject(kind, invalidate); document.body.append(art.canvas); art.draw(880, 526, 3);
+    const renderer = gpu.renderers[0], geometries = new Set(), materials = new Set(), instances = new Set();
+    renderer.scene!.traverse(node => {
+      const mesh = node as Mesh;
+      if (mesh.geometry) geometries.add(mesh.geometry);
+      if (mesh.material) for (const m of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) materials.add(m);
+      if (node instanceof InstancedMesh) instances.add(node);
+    });
+    const lost = new Event('webglcontextlost', { cancelable: true }); art.canvas.dispatchEvent(lost);
+    expect(lost.defaultPrevented).toBe(true); expect(art.draw(880, 526, 8)).toBe(false);
+    art.canvas.dispatchEvent(new Event('webglcontextrestored')); expect(invalidate).toHaveBeenCalledTimes(2);
+    expect(art.draw(880, 526, 3)).toBe(true);
+    art.dispose(); art.dispose();
+    // Allocated but unused shared materials must also be released.
+    expect(new Set(geometrySpy.mock.contexts)).toEqual(geometries);
+    expect(geometrySpy).toHaveBeenCalledTimes(geometries.size);
+    expect(materialSpy.mock.contexts).toEqual(expect.arrayContaining([...materials]));
+    expect(new Set(materialSpy.mock.contexts).size).toBe(materialSpy.mock.calls.length);
+    expect(new Set(instanceSpy.mock.contexts)).toEqual(instances); expect(instanceSpy).toHaveBeenCalledTimes(instances.size);
+    expect(textureSpy).toHaveBeenCalledTimes(kind === 'paper' ? 2 : 1);
+    expect(new Set(textureSpy.mock.contexts).size).toBe(textureSpy.mock.calls.length);
+    expect(renderer.dispose).toHaveBeenCalledOnce(); expect(renderer.forceContextLoss).toHaveBeenCalledOnce();
+    expect(art.canvas.isConnected).toBe(false); expect(art.draw(400, 620, 4)).toBe(false);
+    art.canvas.dispatchEvent(new Event('webglcontextrestored')); expect(invalidate).toHaveBeenCalledTimes(2);
+  });
+
+  it('releases partial allocations if object construction fails', () => {
+    const disposeGeometry = vi.spyOn(BufferGeometry.prototype, 'dispose');
+    vi.spyOn(BufferGeometry.prototype, 'setAttribute').mockImplementationOnce(() => { throw new Error('Synthetic setup failure'); });
+    expect(() => createOrbitObject(kind, vi.fn())).toThrow('Synthetic setup failure');
+    expect(disposeGeometry).toHaveBeenCalled();
+    expect(gpu.renderers[0].dispose).toHaveBeenCalledOnce(); expect(gpu.renderers[0].forceContextLoss).toHaveBeenCalledOnce();
+  });
+});