Skip to content

Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor

9.1 KB
Raw Blame
import { afterEach, expect, test, vi } from 'vitest';
import { zipSync } from 'fflate';
import { createMeshAvatar, openAvatar, loadMeshAvatar, packAvatar } from 'mesh-avatar';
import { sampleFiles } from './avatar-fixture';

vi.mock('../src/engine', async importOriginal => ({
  ...await importOriginal<typeof import('../src/engine')>(),
  createMeshAvatar: vi.fn(async () => ({ destroy: vi.fn() })),
}));
afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); vi.mocked(createMeshAvatar).mockClear(); });
const files = sampleFiles(), archive = packAvatar(files);
const decode = (path: string) => JSON.parse(new TextDecoder().decode(files[path]));
function folderFetch(overrides: Record<string, Uint8Array | null> = {}) {
  return vi.fn(async (input: RequestInfo | URL) => {
    const path = new URL(String(input)).pathname.slice('/avatar/'.length);
    const data = Object.hasOwn(overrides, path) ? overrides[path] : files[path];
    return data ? new Response(new Uint8Array(data), { headers: { 'Content-Type': 'application/json' } }) : new Response('', { status: 404 });
  });
}

test('archive input forms expose the same rig and asset keys as folder loading', async () => {
  const fetch = folderFetch(); vi.stubGlobal('fetch', fetch);
  const folder = await openAvatar(new URL('https://example.test/avatar'));
  for (const source of [archive, new Uint8Array(archive).buffer, new Blob([new Uint8Array(archive)])]) {
    const loaded = await openAvatar(source);
    try {
      expect(loaded.manifest).toEqual(folder.manifest);
      expect(loaded.rig).toEqual(folder.rig);
      expect(Object.keys(loaded.assets).sort()).toEqual(Object.keys(folder.assets).sort());
      expect(Object.values(loaded.assets).every(url => url.startsWith('blob:'))).toBe(true);
      expect(await openAvatar(loaded)).toBe(loaded);
    } finally { loaded.release(); }
  }
  expect(fetch).toHaveBeenCalledTimes(5); // includes the optional overlays.json request
});

test('cloth folder and archive expose the bare base and garment cutout for the renderer', async () => {
  const rig = decode('rig.json'), meta = decode('built/layers.json');
  rig.cloth = [{ name: 'skirt', outline: [[0, 0], [100, 0], [100, 100]], waist: [[0, 0], [100, 0]], hem: [[0, 100], [100, 100]] }];
  meta.layers.cloth_skirt = [0, 0, 100, 100];
  const extra = { 'rig.json': new TextEncoder().encode(JSON.stringify(rig)), 'built/layers.json': new TextEncoder().encode(JSON.stringify(meta)),
    'built/base_cloth.png': new Uint8Array([1]), 'built/cloth_skirt.png': new Uint8Array([2]) };
  vi.stubGlobal('fetch', folderFetch(extra));
  const folder = await openAvatar('https://example.test/avatar/');
  const packed = await openAvatar(packAvatar({ ...files, ...extra }));
  try {
    expect(folder.assets['base_cloth.png']).toContain('/built/base_cloth.png');
    expect(folder.assets['cloth_skirt.png']).toContain('/built/cloth_skirt.png');
    expect(packed.assets['base_cloth.png']).toMatch(/^blob:/);
    expect(Object.keys(packed.assets).sort()).toEqual(Object.keys(folder.assets).sort());
  } finally { packed.release(); folder.release(); }
});

test('fetches archive URLs with query strings and creates usable, revocable image and JSON URLs', async () => {
  const fetch = vi.fn(async (_input: RequestInfo | URL) => new Response(new Uint8Array(archive))); vi.stubGlobal('fetch', fetch);
  const loaded = await openAvatar('https://example.test/avatar.mavatar?download=1');
  expect(String(fetch.mock.calls[0][0])).toBe('https://example.test/avatar.mavatar?download=1');
  vi.unstubAllGlobals();
  const image = await globalThis.fetch(loaded.assets['base.png']);
  expect(image.headers.get('content-type')).toBe('image/png');
  expect(Buffer.from(await image.arrayBuffer()).equals(Buffer.from(files['built/base.png']))).toBe(true);
  expect(await (await globalThis.fetch(loaded.assets['layers.json'])).json()).toEqual(decode('built/layers.json'));
  const revoke = vi.spyOn(URL, 'revokeObjectURL');
  loaded.release(); loaded.release();
  expect(revoke).toHaveBeenCalledTimes(Object.keys(loaded.assets).length);
});

test('folder URLs preserve query parameters, cache versions and optional older metadata', async () => {
  const fetch = folderFetch({ 'avatar.json': null, 'built/sprites/sprites.json': null }); vi.stubGlobal('fetch', fetch);
  vi.stubGlobal('location', { href: 'https://example.test/editor/index.html' });
  const loaded = await openAvatar('/avatar?token=test', { version: 123 });
  expect(loaded.manifest).toEqual({ format: 'mesh-avatar', version: 1, name: 'avatar' });
  expect(loaded.assets['sprites/sprites.json']).toBeUndefined();
  for (const [url] of fetch.mock.calls) {
    expect(new URL(String(url)).searchParams.get('v')).toBe('123');
    expect(new URL(String(url)).searchParams.get('token')).toBe('test');
  }
  expect(loaded.assets['base.png']).toBe('https://example.test/avatar/built/base.png?token=test&v=123');
});

test('fills only missing eye curve fields for any chosen rig filename and keeps mismatches visible', async () => {
  const raw = decode('rig.json'); delete raw.eyes[0].top; delete raw.eyes[1].x0;
  const fetch = folderFetch({ 'custom-rig.json': new TextEncoder().encode(JSON.stringify(raw)) }); vi.stubGlobal('fetch', fetch);
  expect((await openAvatar('https://example.test/avatar/', { rigFile: 'custom-rig.json' })).rig).toEqual(decode('rig.json'));
  raw.eyes[0].x0 += 1;
  vi.stubGlobal('fetch', folderFetch({ 'rig.json': new TextEncoder().encode(JSON.stringify(raw)) }));
  await expect(openAvatar('https://example.test/avatar/')).rejects.toThrow('built/layers.json.eyes[0].x0: must match rig.json.eyes[0].x0');
});

test('only missing optional metadata is tolerated, while invalid versions and HTTP failures are errors', async () => {
  const fetch = folderFetch();
  vi.stubGlobal('fetch', async (input: RequestInfo | URL) => String(input).endsWith('avatar.json') ? new Response('', { status: 403 }) : fetch(input));
  await expect(openAvatar('https://example.test/avatar/')).rejects.toThrow('avatar.json: could not load (403)');
  const rig = { ...decode('rig.json'), version: 2 };
  vi.stubGlobal('fetch', folderFetch({ 'rig.json': new TextEncoder().encode(JSON.stringify(rig)) }));
  await expect(openAvatar('https://example.test/avatar/')).rejects.toThrow('rig.json.version: unsupported version 2');
  vi.stubGlobal('fetch', folderFetch({ 'built/layers.json': null }));
  await expect(openAvatar('https://example.test/avatar/')).rejects.toThrow('built/layers.json: could not load (404)');
});

test('archives need a manifest and reject invalid content before making object URLs', async () => {
  const create = vi.spyOn(URL, 'createObjectURL');
  const missingManifest = { ...files }; delete missingManifest['avatar.json'];
  await expect(openAvatar(zipSync(missingManifest, { level: 0 }))).rejects.toThrow('avatar.json: missing file in .mavatar archive');
  const missingImage = { ...files }; delete missingImage['built/base.png'];
  await expect(openAvatar(zipSync(missingImage, { level: 0 }))).rejects.toThrow('built/base.png: missing file');
  expect(create).not.toHaveBeenCalled();
});

test('object URL creation failure releases all URLs already allocated', async () => {
  const create = vi.spyOn(URL, 'createObjectURL');
  create.mockReturnValueOnce('blob:first').mockImplementationOnce(() => { throw new Error('Allocation failed'); });
  const revoke = vi.spyOn(URL, 'revokeObjectURL');
  await expect(openAvatar(archive)).rejects.toThrow('Allocation failed');
  expect(revoke).toHaveBeenCalledExactlyOnceWith('blob:first');
});

test('loadMeshAvatar releases owned resources on destroy or failure but preserves caller-owned packages', async () => {
  const revoke = vi.spyOn(URL, 'revokeObjectURL');
  const avatar = await loadMeshAvatar({} as HTMLCanvasElement, archive, { manual: true });
  expect(createMeshAvatar).toHaveBeenCalledWith({}, { rig: avatar.package.rig, assets: avatar.package.assets, manual: true });
  avatar.destroy(); avatar.destroy();
  expect(revoke).toHaveBeenCalledTimes(Object.keys(avatar.package.assets).length);
  revoke.mockClear();
  vi.mocked(createMeshAvatar).mockRejectedValueOnce(new Error('Canvas unavailable'));
  await expect(loadMeshAvatar({} as HTMLCanvasElement, archive)).rejects.toThrow('Canvas unavailable');
  expect(revoke).toHaveBeenCalledTimes(Object.keys(avatar.package.assets).length);
  const shared = await openAvatar(archive), release = vi.spyOn(shared, 'release');
  const second = await loadMeshAvatar({} as HTMLCanvasElement, shared);
  second.destroy(); expect(release).not.toHaveBeenCalled();
  shared.release();
});

test('loadMeshAvatar applies saved mouth settings and lets explicit runtime options override them', async () => {
  const lipSync = { granularity: 0.2, openness: 0.75, closeSpeed: 0.1 };
  const archive = packAvatar(files, { manifest: { lipSync } });
  const avatar = await loadMeshAvatar({} as HTMLCanvasElement, archive);
  expect(avatar.package.manifest.lipSync).toEqual(lipSync);
  expect(vi.mocked(createMeshAvatar).mock.calls.at(-1)?.[1].lipSync).toEqual(lipSync);
  avatar.destroy();
  const override = { openness: 0.3 };
  const other = await loadMeshAvatar({} as HTMLCanvasElement, archive, { lipSync: override });
  expect(vi.mocked(createMeshAvatar).mock.calls.at(-1)?.[1].lipSync).toEqual({ ...lipSync, ...override });
  other.destroy();
});