Turn one illustration into an animated 2D mesh avatar with a coding agent and a local editor
Add native Rust workspace with avatar loading and grid building
shinshin86abcd8dba1ffe
diff --git a/.gitignore b/.gitignoreindex 39509ca..d37478a 100644--- a/.gitignore+++ b/.gitignore@@ -9,4 +9,5 @@ playwright-report/__pycache__/projects/work/+native/target/samples/**/review/diff --git a/native/Cargo.lock b/native/Cargo.locknew file mode 100644index 0000000..671c1ee--- /dev/null+++ b/native/Cargo.lock@@ -0,0 +1,280 @@+# This file is automatically @generated by Cargo.+# It is not intended for manual editing.+version = 4++[[package]]+name = "adler2"+version = "2.0.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"++[[package]]+name = "anyhow"+version = "1.0.104"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"++[[package]]+name = "arbitrary"+version = "1.5.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3bc62ac97cc33321f50863d514c3bc38a453947a8f9e781137e47c7401020aed"+dependencies = [+ "derive_arbitrary",+]++[[package]]+name = "bitflags"+version = "1.3.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"++[[package]]+name = "cfg-if"+version = "1.0.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"++[[package]]+name = "crc32fast"+version = "1.5.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0ba106e844045ddc02c20768ac4b0b7cb45f2cc2ecbd833ac9f5dacb183c2055"+dependencies = [+ "cfg-if",+]++[[package]]+name = "crossbeam-utils"+version = "0.8.23"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"++[[package]]+name = "derive_arbitrary"+version = "1.5.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1b034bd7d5f032402a2479444dcc6f74e36a03f31854d41680fb240ef682a1ac"+dependencies = [+ "proc-macro2",+ "quote",+ "syn",+]++[[package]]+name = "equivalent"+version = "1.0.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826"++[[package]]+name = "fdeflate"+version = "0.3.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"+dependencies = [+ "simd-adler32",+]++[[package]]+name = "flate2"+version = "1.1.10"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6e634e2e0ebac1ee034020da1ca582e17ffe4e0f5e985823721e168928136dcb"+dependencies = [+ "crc32fast",+ "miniz_oxide 0.9.1",+ "zlib-rs",+]++[[package]]+name = "hashbrown"+version = "0.17.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"++[[package]]+name = "indexmap"+version = "2.14.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"+dependencies = [+ "equivalent",+ "hashbrown",+]++[[package]]+name = "itoa"+version = "1.0.18"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"++[[package]]+name = "memchr"+version = "2.8.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"++[[package]]+name = "mesh-avatar-core"+version = "0.1.0"+dependencies = [+ "anyhow",+ "png",+ "serde",+ "serde_json",+ "zip",+]++[[package]]+name = "mesh-avatar-desktop"+version = "0.1.0"++[[package]]+name = "mesh-avatar-wgpu"+version = "0.1.0"+dependencies = [+ "mesh-avatar-core",+]++[[package]]+name = "miniz_oxide"+version = "0.8.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"+dependencies = [+ "adler2",+ "simd-adler32",+]++[[package]]+name = "miniz_oxide"+version = "0.9.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b63fbc4a50860e98e7b2aa7804ded1db5cbc3aff9193adaff57a6931bf7c4b4c"+dependencies = [+ "adler2",+ "simd-adler32",+]++[[package]]+name = "png"+version = "0.17.16"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "82151a2fc869e011c153adc57cf2789ccb8d9906ce52c0b39a6b5697749d7526"+dependencies = [+ "bitflags",+ "crc32fast",+ "fdeflate",+ "flate2",+ "miniz_oxide 0.8.9",+]++[[package]]+name = "proc-macro2"+version = "1.0.107"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"+dependencies = [+ "unicode-ident",+]++[[package]]+name = "quote"+version = "1.0.47"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"+dependencies = [+ "proc-macro2",+]++[[package]]+name = "serde"+version = "1.0.229"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"+dependencies = [+ "serde_core",+ "serde_derive",+]++[[package]]+name = "serde_core"+version = "1.0.229"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"+dependencies = [+ "serde_derive",+]++[[package]]+name = "serde_derive"+version = "1.0.229"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"+dependencies = [+ "proc-macro2",+ "quote",+ "syn",+]++[[package]]+name = "serde_json"+version = "1.0.154"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"+dependencies = [+ "itoa",+ "memchr",+ "serde",+ "serde_core",+ "zmij",+]++[[package]]+name = "simd-adler32"+version = "0.3.10"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"++[[package]]+name = "syn"+version = "3.0.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"+dependencies = [+ "proc-macro2",+ "quote",+ "unicode-ident",+]++[[package]]+name = "unicode-ident"+version = "1.0.27"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"++[[package]]+name = "zip"+version = "2.6.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1dcb24d0152526ae49b9b96c1dcf71850ca1e0b882e4e28ed898a93c41334744"+dependencies = [+ "arbitrary",+ "crc32fast",+ "crossbeam-utils",+ "indexmap",+ "memchr",+]++[[package]]+name = "zlib-rs"+version = "0.6.8"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112"++[[package]]+name = "zmij"+version = "1.0.23"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"diff --git a/native/Cargo.toml b/native/Cargo.tomlnew file mode 100644index 0000000..e4db84c--- /dev/null+++ b/native/Cargo.toml@@ -0,0 +1,17 @@+[workspace]+members = ["crates/mesh-avatar-core", "crates/mesh-avatar-wgpu", "apps/mesh-avatar-desktop"]+resolver = "2"++[workspace.package]+version = "0.1.0"+edition = "2021"+rust-version = "1.88"+publish = false++[workspace.dependencies]+mesh-avatar-core = { path = "crates/mesh-avatar-core" }+anyhow = "1"+serde = { version = "1", features = ["derive"] }+serde_json = "1"+png = "0.17"+zip = { version = "2", default-features = false }diff --git a/native/apps/mesh-avatar-desktop/Cargo.toml b/native/apps/mesh-avatar-desktop/Cargo.tomlnew file mode 100644index 0000000..cdc6d3e--- /dev/null+++ b/native/apps/mesh-avatar-desktop/Cargo.toml@@ -0,0 +1,6 @@+[package]+name = "mesh-avatar-desktop"+version.workspace = true+edition.workspace = true+rust-version.workspace = true+publish.workspace = truediff --git a/native/apps/mesh-avatar-desktop/src/main.rs b/native/apps/mesh-avatar-desktop/src/main.rsnew file mode 100644index 0000000..e6ef620--- /dev/null+++ b/native/apps/mesh-avatar-desktop/src/main.rs@@ -0,0 +1,3 @@+fn main() {+ eprintln!("The desktop avatar app is not implemented yet.");+}diff --git a/native/conformance/dump.mjs b/native/conformance/dump.mjsnew file mode 100644index 0000000..884899f--- /dev/null+++ b/native/conformance/dump.mjs@@ -0,0 +1,60 @@+// Run with Node.js 22.17+ from any directory: node native/conformance/dump.mjs+import { existsSync } from 'node:fs';+import { readFile, mkdir, writeFile } from 'node:fs/promises';+import { registerHooks } from 'node:module';+import { fileURLToPath } from 'node:url';+import { PNG } from 'pngjs';++// Match the runtime's bundler-style extensionless lighting imports in plain Node.+const hooks = registerHooks({ resolve(specifier, context, next) {+ if (specifier.startsWith('.') && !/\.[a-z]+$/i.test(specifier)) {+ for (const extension of ['.ts', '.js']) {+ const url = new URL(specifier + extension, context.parentURL);+ if (existsSync(url)) return next(url.href, context);+ }+ }+ return next(specifier, context);+} });+const { createRig } = await import('../../packages/runtime/src/engine/rig.js');+const { createRenderer } = await import('../../packages/runtime/src/engine/renderer.js');+const { parseRig } = await import('../../packages/runtime/src/rig/validate.ts');+hooks.deregister();++const sample = new URL('../../samples/miko-qipao/', import.meta.url);+const json = async path => JSON.parse(await readFile(new URL(path, sample), 'utf8'));+const rig = parseRig(await json('rig.json'));+const metadata = await json('built/layers.json');+const sprites = await json('built/sprites/sprites.json');+const { buildGrid } = createRenderer(createRig(rig), rig);+const plain = mesh => Object.fromEntries(Object.entries(mesh).map(([key, value]) =>+ [key, ArrayBuffer.isView(value) ? Array.from(value) : value]));+const grids = [];+for (const [sprite, rectangles] of [[false, { base: [0, 0, rig.image.width, rig.image.height], ...metadata.layers }], [true, sprites.layers]]) {+ for (const [name, rect] of Object.entries(rectangles)) {+ const texture = `${sprite ? 'sprites/' : ''}${name}.png`;+ const image = PNG.sync.read(await readFile(new URL(`built/${texture}`, sample)));+ if (image.width !== rect[2] || image.height !== rect[3]) throw new Error(`PNG dimensions do not match ${texture}`);+ const cell = sprite ? rig.mesh.spriteCell : name === 'base' ? rig.mesh.baseCell+ : name === 'hand' ? rig.mesh.handCell : name.startsWith('tassel') ? rig.mesh.tasselCell+ : name.endsWith('_ball') ? rig.mesh.eyeBallCell : rig.mesh.eyeCell;+ const fine = name === 'base' ? rig.mesh.fine : null;+ const alpha = Uint8Array.from({ length: image.width * image.height }, (_, i) => image.data[i * 4 + 3]);+ grids.push({ name, texture, cell, fine, mesh: plain(buildGrid(rect, cell, alpha, image.width, fine)) });+ }+}++// Exercise numerical edges independently of the installed sample's geometry/alpha.+const cases = [+ { name: 'opaque-standin', rect: [10, 20, 5, 7], cell: 2, alpha: [255], width: 1 },+ { name: 'transparent', rect: [0, 0, 5, 4], cell: 2, alpha: Array(20).fill(3), width: 5 },+ { name: 'alpha-border', rect: [2.25, -3.5, 5, 4], cell: 2, alpha: [4, ...Array(19).fill(0)], width: 5 },+ { name: 'fine-boundary', rect: [1, 2, 12, 10], cell: 4, alpha: [255], width: 1,+ fine: { x0: 4, x1: 10, y0: 3, y1: 9, cell: 2 } },+ { name: 'fractional-tail', rect: [0, 0, 4.25, 2.5], cell: 2, alpha: [255], width: 1 },+].map(input => ({ ...input, fine: input.fine ?? null,+ mesh: plain(buildGrid(input.rect, input.cell, Uint8Array.from(input.alpha), input.width, input.fine ?? null)) }));++const destination = new URL('../target/conformance/', import.meta.url);+await mkdir(destination, { recursive: true });+await writeFile(new URL('grids.json', destination), JSON.stringify({ version: 1, grids, cases }) + '\n');+console.log(`Wrote ${grids.length} layer/sprite grids and ${cases.length} edge cases to ${fileURLToPath(new URL('grids.json', destination))}`);diff --git a/native/crates/mesh-avatar-core/Cargo.toml b/native/crates/mesh-avatar-core/Cargo.tomlnew file mode 100644index 0000000..028fa55--- /dev/null+++ b/native/crates/mesh-avatar-core/Cargo.toml@@ -0,0 +1,13 @@+[package]+name = "mesh-avatar-core"+version.workspace = true+edition.workspace = true+rust-version.workspace = true+publish.workspace = true++[dependencies]+anyhow.workspace = true+serde.workspace = true+serde_json.workspace = true+png.workspace = true+zip.workspace = truediff --git a/native/crates/mesh-avatar-core/src/engine/grid.rs b/native/crates/mesh-avatar-core/src/engine/grid.rsnew file mode 100644index 0000000..0e3b2b9--- /dev/null+++ b/native/crates/mesh-avatar-core/src/engine/grid.rs@@ -0,0 +1,163 @@+//! Layer grids matching the JavaScript renderer's buildGrid.++use crate::rig::FineGrid;+use anyhow::{ensure, Result};+use serde::{Deserialize, Serialize};++#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]+pub struct Grid {+ pub rect: [f64; 4],+ pub cols: usize,+ pub rows: usize,+ pub rest: Vec<f32>,+ pub uv: Vec<f32>,+ pub pos: Vec<f32>,+ pub tris: Vec<u32>,+ pub lines: Vec<u32>,+}++fn axis(start: f64, len: f64, cell: f64, fine: Option<(f64, f64, f64)>) -> Result<Vec<f64>> {+ let mut out = vec![start];+ let mut v = start;+ while v < start + len - 0.5 {+ let c = fine+ .filter(|&(from, to, _)| v >= from && v < to)+ .map_or(cell, |(_, _, cell)| cell);+ let next = (start + len).min(v + c);+ ensure!(next > v, "grid step is below coordinate precision");+ v = next;+ out.push(v);+ }+ Ok(out)+}++pub fn build_grid(+ rect: [f64; 4],+ cell: f64,+ alpha: &[u8],+ alpha_width: usize,+ fine: Option<&FineGrid>,+) -> Result<Grid> {+ let [rx, ry, rw, rh] = rect;+ ensure!(+ rect.iter().all(|v| v.is_finite()) && rw > 0.0 && rh > 0.0,+ "invalid grid rectangle"+ );+ ensure!(+ cell.is_finite() && cell >= 1.0,+ "grid cell must be at least one pixel"+ );+ ensure!(+ alpha_width > 0 && !alpha.is_empty() && alpha.len().is_multiple_of(alpha_width),+ "invalid alpha dimensions"+ );+ if let Some(fine) = fine {+ ensure!(fine.cell > 0, "fine cell must be positive");+ }+ // Bound allocation and ensure every index fits the JS Uint32Array representation.+ ensure!(+ rw <= 65535.0 && rh <= 65535.0,+ "grid dimensions exceed limits"+ );+ let xs = axis(+ rx,+ rw,+ cell,+ fine.map(|f| (f.x0 as f64, f.x1 as f64, f.cell as f64)),+ )?;+ let ys = axis(+ ry,+ rh,+ cell,+ fine.map(|f| (f.y0 as f64, f.y1 as f64, f.cell as f64)),+ )?;+ let cols = xs.len() - 1;+ let rows = ys.len() - 1;+ let count = xs+ .len()+ .checked_mul(ys.len())+ .filter(|&n| n <= 4_000_000)+ .ok_or_else(|| anyhow::anyhow!("grid has too many vertices"))?;+ let mut rest = Vec::with_capacity(count * 2);+ let mut uv = Vec::with_capacity(count * 2);+ for &y in &ys {+ for &x in &xs {+ rest.extend([x as f32, y as f32]);+ uv.extend([((x - rx) / rw) as f32, ((y - ry) / rh) as f32]);+ }+ }+ let mut tris = Vec::new();+ let mut lines = Vec::new();+ let alpha_height = alpha.len() / alpha_width;+ let ax = if alpha_width == 1 { 0.0 } else { 1.0 };+ for j in 0..rows {+ for i in 0..cols {+ let x0 = (((xs[i] - rx).floor() * ax - 2.0).max(0.0) as usize).min(alpha_width);+ let x1 = (((xs[i + 1] - rx).ceil() * ax + 2.0).max(0.0) as usize).min(alpha_width);+ let y0 = (((ys[j] - ry).floor() * ax - 2.0).max(0.0) as usize).min(alpha_height);+ let y1 = (((ys[j + 1] - ry).ceil() * ax + 2.0).max(0.0) as usize).min(alpha_height);+ let any = (y0..y1).any(|y| {+ alpha[y * alpha_width + x0..y * alpha_width + x1]+ .iter()+ .any(|&a| a > 3)+ });+ if !any {+ continue;+ }+ let a = (j * (cols + 1) + i) as u32;+ let b = a + 1;+ let c = a + cols as u32 + 1;+ let d = c + 1;+ tris.extend([a, b, c, b, d, c]);+ lines.extend([a, b, a, c, b, c]);+ if i == cols - 1 {+ lines.extend([b, d]);+ }+ if j == rows - 1 {+ lines.extend([c, d]);+ }+ }+ }+ Ok(Grid {+ rect,+ cols,+ rows,+ pos: rest.clone(),+ rest,+ uv,+ tris,+ lines,+ })+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn opaque_standin_and_alpha_threshold() {+ let grid = build_grid([10.0, 20.0, 4.0, 4.0], 2.0, &[255], 1, None).unwrap();+ assert_eq!((grid.cols, grid.rows), (2, 2));+ assert_eq!(grid.tris.len(), 24);+ assert_eq!(&grid.tris[..6], &[0, 1, 3, 1, 4, 3]);+ assert_eq!(grid.pos, grid.rest);+ assert!(build_grid([0.0, 0.0, 4.0, 4.0], 2.0, &[3], 1, None)+ .unwrap()+ .tris+ .is_empty());+ assert_eq!(+ build_grid([0.0, 0.0, 4.0, 4.0], 2.0, &[4], 1, None)+ .unwrap()+ .tris+ .len(),+ 24+ );+ }++ #[test]+ fn rejects_invalid_input() {+ assert!(build_grid([0.0, 0.0, 4.0, 4.0], 0.0, &[255], 1, None).is_err());+ assert!(build_grid([0.0, 0.0, 4.0, 4.0], 2.0, &[255], 0, None).is_err());+ assert!(build_grid([1e16, 0.0, 4.0, 4.0], 1.0, &[255], 1, None).is_err());+ }+}diff --git a/native/crates/mesh-avatar-core/src/engine/mod.rs b/native/crates/mesh-avatar-core/src/engine/mod.rsnew file mode 100644index 0000000..f7a1b46--- /dev/null+++ b/native/crates/mesh-avatar-core/src/engine/mod.rs@@ -0,0 +1 @@+pub mod grid;diff --git a/native/crates/mesh-avatar-core/src/format.rs b/native/crates/mesh-avatar-core/src/format.rsnew file mode 100644index 0000000..b4b15dc--- /dev/null+++ b/native/crates/mesh-avatar-core/src/format.rs@@ -0,0 +1,826 @@+//! Load a built project directory or a stored ZIP .mavatar archive.++use crate::rig::{Eye, Rig};+use anyhow::{bail, ensure, Context, Result};+use serde::{Deserialize, Serialize};+use serde_json::Value;+use std::{+ collections::{BTreeMap, BTreeSet},+ fs,+ io::{Cursor, Read, Seek, SeekFrom},+ path::Path,+};++const MAX_ENTRIES: usize = 200;+const MAX_SIZE: u64 = 64 * 1024 * 1024;+pub type Rect = [u32; 4];++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct Manifest {+ pub format: String,+ pub version: u32,+ pub name: String,+ pub author: Option<String>,+ pub license: Option<String>,+ pub thumbnail: Option<String>,+ pub source: Option<String>,+ pub studio: Option<Studio>,+ #[serde(rename = "lipSync")]+ pub lip_sync: Option<Value>,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct Studio {+ pub version: String,+}++impl Manifest {+ fn parse(bytes: &[u8]) -> Result<Self> {+ let m: Self =+ serde_json::from_slice(bytes).context("avatar.json: invalid manifest JSON")?;+ ensure!(+ m.format == "mesh-avatar" && m.version == 1,+ "avatar.json: unsupported format or version"+ );+ ensure!(+ !m.name.trim().is_empty(),+ "avatar.json.name must not be empty"+ );+ if let Some(studio) = &m.studio {+ ensure!(+ !studio.version.trim().is_empty(),+ "avatar.json.studio.version must not be empty"+ );+ }+ Ok(m)+ }++ fn default_named(name: String) -> Self {+ Self {+ format: "mesh-avatar".into(),+ version: 1,+ name,+ author: None,+ license: None,+ thumbnail: None,+ source: None,+ studio: None,+ lip_sync: None,+ }+ }+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct EyeCurves {+ pub x0: f64,+ pub x1: f64,+ pub top: [f64; 24],+ pub bot: [f64; 24],+}++impl EyeCurves {+ fn matches(&self, eye: &Eye) -> bool {+ self.x0 == eye.x0 && self.x1 == eye.x1 && self.top == eye.top && self.bot == eye.bot+ }+}++fn legacy_version() -> u32 {+ 1+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct LayerMetadata {+ #[serde(default = "legacy_version")]+ pub version: u32,+ pub build: String,+ pub size: [u32; 2],+ pub layers: BTreeMap<String, Rect>,+ pub eyes: [EyeCurves; 2],+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct SpriteMetadata {+ #[serde(default = "legacy_version")]+ pub version: u32,+ pub build: String,+ pub layers: BTreeMap<String, Rect>,+}++#[derive(Debug, Clone)]+pub struct Texture {+ pub width: u32,+ pub height: u32,+ /// Straight RGBA, retaining original red/alpha channels for CPU masks.+ pub rgba: Vec<u8>,+}++impl Texture {+ pub fn alpha(&self) -> Vec<u8> {+ self.rgba.as_chunks::<4>().0.iter().map(|p| p[3]).collect()+ }++ /// RGBA upload data matching WebGL's premultiplied-alpha texture convention.+ pub fn premultiplied_rgba(&self) -> Vec<u8> {+ let mut pixels = self.rgba.clone();+ for p in pixels.as_chunks_mut::<4>().0 {+ let alpha = u32::from(p[3]);+ for c in &mut p[..3] {+ *c = ((u32::from(*c) * alpha + 127) / 255) as u8;+ }+ }+ pixels+ }++ pub fn decode(bytes: &[u8]) -> Result<Self> {+ let mut decoder = png::Decoder::new(Cursor::new(bytes));+ decoder.set_transformations(png::Transformations::EXPAND | png::Transformations::STRIP_16);+ decoder.set_limits(png::Limits {+ bytes: MAX_SIZE as usize,+ });+ let mut reader = decoder.read_info().context("invalid PNG header")?;+ let info = reader.info();+ let rgba_size = u64::from(info.width)+ .checked_mul(u64::from(info.height))+ .and_then(|n| n.checked_mul(4))+ .context("PNG dimensions overflow")?;+ ensure!(rgba_size <= MAX_SIZE, "decoded PNG exceeds 64 MB");+ let mut bytes = vec![0; reader.output_buffer_size()];+ let output = reader+ .next_frame(&mut bytes)+ .context("invalid PNG pixels")?;+ let bytes = &bytes[..output.buffer_size()];+ let mut rgba = Vec::with_capacity(rgba_size as usize);+ match output.color_type {+ png::ColorType::Rgba => rgba.extend_from_slice(bytes),+ png::ColorType::Rgb => {+ for p in bytes.as_chunks::<3>().0 {+ rgba.extend([p[0], p[1], p[2], 255]);+ }+ }+ png::ColorType::Grayscale => {+ for &v in bytes {+ rgba.extend([v, v, v, 255]);+ }+ }+ png::ColorType::GrayscaleAlpha => {+ for p in bytes.as_chunks::<2>().0 {+ rgba.extend([p[0], p[0], p[0], p[1]]);+ }+ }+ png::ColorType::Indexed => bail!("PNG palette was not expanded"),+ }+ Ok(Self {+ width: output.width,+ height: output.height,+ rgba,+ })+ }+}++#[derive(Debug)]+pub struct AvatarPackage {+ pub manifest: Manifest,+ pub rig: Rig,+ pub layers: LayerMetadata,+ pub sprites: Option<SpriteMetadata>,+ /// Keys relative to built/, for example base.png or sprites/mouth_a.png.+ pub textures: BTreeMap<String, Texture>,+}++fn check_entry_name(name: &str) -> Result<()> {+ let b = name.as_bytes();+ ensure!(+ !name.is_empty()+ && !name.starts_with('/')+ && !name.contains(['\\', '\0'])+ && !(b.len() >= 2 && b[0].is_ascii_alphabetic() && b[1] == b':')+ && !name.split('/').any(|s| s == ".."),+ "unsafe asset path: {name}"+ );+ Ok(())+}++fn bounded_read(reader: impl Read) -> Result<Vec<u8>> {+ let mut bytes = Vec::new();+ reader.take(MAX_SIZE + 1).read_to_end(&mut bytes)?;+ ensure!(bytes.len() as u64 <= MAX_SIZE, "file exceeds 64 MB");+ Ok(bytes)+}++// zip's filename map deduplicates names. Check the raw directory first so duplicate+// entries and inconsistent local headers cannot silently change the loaded avatar.+fn check_zip_directory(reader: &mut (impl Read + Seek)) -> Result<()> {+ fn read_at(reader: &mut (impl Read + Seek), offset: u64, size: usize) -> Result<Vec<u8>> {+ reader.seek(SeekFrom::Start(offset))?;+ let mut bytes = vec![0; size];+ reader.read_exact(&mut bytes).context("truncated ZIP")?;+ Ok(bytes)+ }+ let u16_at = |b: &[u8], i| u16::from_le_bytes([b[i], b[i + 1]]);+ let u32_at = |b: &[u8], i| u32::from_le_bytes([b[i], b[i + 1], b[i + 2], b[i + 3]]);+ let size = reader.seek(SeekFrom::End(0))?;+ let tail_size = size.min(65557) as usize;+ ensure!(tail_size >= 22, "truncated ZIP end record");+ let tail = read_at(reader, size - tail_size as u64, tail_size)?;+ let end = (0..=tail_size - 22)+ .rev()+ .find(|&i| {+ u32_at(&tail, i) == 0x06054b50 && i + 22 + u16_at(&tail, i + 20) as usize == tail_size+ })+ .context("invalid ZIP end record")?;+ ensure!(+ u16_at(&tail, end + 4) == 0+ && u16_at(&tail, end + 6) == 0+ && u16_at(&tail, end + 8) == u16_at(&tail, end + 10),+ "multi-disk ZIP is unsupported"+ );+ let count = u16_at(&tail, end + 10) as usize;+ ensure!(+ count <= MAX_ENTRIES,+ "archive exceeds {MAX_ENTRIES} entries"+ );+ let directory = u64::from(u32_at(&tail, end + 16));+ let directory_end = directory + u64::from(u32_at(&tail, end + 12));+ ensure!(+ directory_end == size - tail_size as u64 + end as u64,+ "invalid ZIP directory size"+ );+ let mut position = directory;+ let mut seen = BTreeSet::new();+ for _ in 0..count {+ ensure!(position + 46 <= directory_end, "truncated ZIP directory");+ let header = read_at(reader, position, 46)?;+ ensure!(+ u32_at(&header, 0) == 0x02014b50,+ "invalid ZIP directory header"+ );+ let name_len = u16_at(&header, 28) as usize;+ let next = position+ + 46+ + name_len as u64+ + u64::from(u16_at(&header, 30))+ + u64::from(u16_at(&header, 32));+ ensure!(next <= directory_end, "truncated ZIP directory entry");+ let name_bytes = read_at(reader, position + 46, name_len)?;+ let name = std::str::from_utf8(&name_bytes).context("ZIP filename must be UTF-8")?;+ check_entry_name(name)?;+ ensure!(seen.insert(name.to_owned()), "duplicate ZIP entry: {name}");+ let compressed = u64::from(u32_at(&header, 20));+ let uncompressed = u64::from(u32_at(&header, 24));+ let flags = u16_at(&header, 8);+ ensure!(+ compressed <= MAX_SIZE && uncompressed <= MAX_SIZE,+ "ZIP entry {name}: exceeds 64 MB"+ );+ ensure!(+ u16_at(&header, 10) == 0 && compressed == uncompressed,+ "ZIP entry {name}: expected stored compression"+ );+ ensure!(+ flags & 1 == 0,+ "ZIP entry {name}: encryption is unsupported"+ );+ let offset = u64::from(u32_at(&header, 42));+ ensure!(offset + 30 <= directory, "invalid local ZIP offset");+ let local = read_at(reader, offset, 30)?;+ ensure!(+ u32_at(&local, 0) == 0x04034b50 && u16_at(&local, 8) == 0 && u16_at(&local, 6) == flags,+ "inconsistent local ZIP header"+ );+ let local_name_len = u16_at(&local, 26) as usize;+ let start = offset + 30 + local_name_len as u64 + u64::from(u16_at(&local, 28));+ ensure!(start + uncompressed <= directory, "truncated ZIP payload");+ ensure!(+ read_at(reader, offset + 30, local_name_len)? == name_bytes,+ "inconsistent local ZIP filename"+ );+ position = next;+ }+ ensure!(position == directory_end, "invalid ZIP entry count");+ reader.rewind()?;+ Ok(())+}++fn unpack(mut reader: impl Read + Seek) -> Result<BTreeMap<String, Vec<u8>>> {+ check_zip_directory(&mut reader)?;+ let mut zip = zip::ZipArchive::new(reader).context("invalid .mavatar ZIP")?;+ ensure!(+ zip.len() <= MAX_ENTRIES,+ "archive exceeds {MAX_ENTRIES} entries"+ );+ let mut files = BTreeMap::new();+ for i in 0..zip.len() {+ let file = zip.by_index(i).context("unreadable ZIP entry")?;+ let name = std::str::from_utf8(file.name_raw())+ .context("ZIP filename must be UTF-8")?+ .to_owned();+ check_entry_name(&name)?;+ ensure!(!files.contains_key(&name), "duplicate ZIP entry: {name}");+ ensure!(+ file.compression() == zip::CompressionMethod::Stored,+ "ZIP entry {name}: expected stored compression"+ );+ ensure!(+ file.size() <= MAX_SIZE && file.compressed_size() <= MAX_SIZE,+ "ZIP entry {name}: exceeds 64 MB"+ );+ files.insert(+ name.clone(),+ bounded_read(file).with_context(|| format!("ZIP entry {name}"))?,+ );+ }+ ensure!(+ files.contains_key("avatar.json"),+ "avatar.json: missing file in .mavatar archive"+ );+ Ok(files)+}++fn validate_rectangles(layers: &BTreeMap<String, Rect>, size: [u32; 2]) -> Result<()> {+ for (name, &[x, y, w, h]) in layers {+ ensure!(+ !name.is_empty()+ && name+ .bytes()+ .all(|c| c.is_ascii_alphanumeric() || c == b'_' || c == b'-'),+ "unsafe layer name: {name}"+ );+ ensure!(+ w > 0+ && h > 0+ && u64::from(x) + u64::from(w) <= u64::from(size[0])+ && u64::from(y) + u64::from(h) <= u64::from(size[1]),+ "layer {name}: rectangle must stay inside image"+ );+ }+ Ok(())+}++impl AvatarPackage {+ pub fn open(path: impl AsRef<Path>) -> Result<Self> {+ let path = path.as_ref();+ if !path.is_dir() {+ return Self::from_archive(+ fs::File::open(path).context("could not open avatar archive")?,+ );+ }+ let root = path+ .canonicalize()+ .context("could not open avatar folder")?;+ let read = |name: &str| -> Result<Option<Vec<u8>>> {+ check_entry_name(name)?;+ let resolved = match root.join(name).canonicalize() {+ Ok(path) => path,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(None),+ Err(e) => return Err(e).with_context(|| format!("could not resolve {name}")),+ };+ ensure!(+ resolved.starts_with(&root),+ "asset escapes project folder: {name}"+ );+ Ok(Some(+ bounded_read(fs::File::open(resolved)?)+ .with_context(|| format!("could not read {name}"))?,+ ))+ };+ let name = root+ .file_name()+ .and_then(|v| v.to_str())+ .unwrap_or("Avatar")+ .to_owned();+ Self::load(read, Some(name))+ }++ pub fn from_archive(reader: impl Read + Seek) -> Result<Self> {+ let files = unpack(reader)?;+ Self::load(|name| Ok(files.get(name).cloned()), None)+ }++ fn load(+ read: impl Fn(&str) -> Result<Option<Vec<u8>>>,+ folder_name: Option<String>,+ ) -> Result<Self> {+ let required = |name: &str| read(name)?.with_context(|| format!("{name}: missing file"));+ let layers: LayerMetadata = serde_json::from_slice(&required("built/layers.json")?)+ .context("built/layers.json: invalid metadata")?;+ ensure!(+ layers.version == 1 && !layers.build.trim().is_empty(),+ "built/layers.json: unsupported version or empty build"+ );+ let mut raw: Value =+ serde_json::from_slice(&required("rig.json")?).context("rig.json: invalid JSON")?;+ // Legacy folder rigs can get baked eye curves from layer metadata; archives must contain them.+ if folder_name.is_some() {+ if let Some(eyes) = raw.get_mut("eyes").and_then(Value::as_array_mut) {+ for (eye, curves) in eyes.iter_mut().zip(&layers.eyes) {+ if let Some(eye) = eye.as_object_mut() {+ for (key, value) in serde_json::to_value(curves)?.as_object().unwrap() {+ eye.entry(key.clone()).or_insert_with(|| value.clone());+ }+ }+ }+ }+ }+ let rig = Rig::parse(&serde_json::to_vec(&raw)?)?;+ ensure!(+ layers.size == [rig.image.width, rig.image.height],+ "built/layers.json.size must match rig image dimensions"+ );+ validate_rectangles(&layers.layers, layers.size)?;+ for (curves, eye) in layers.eyes.iter().zip(&rig.eyes) {+ ensure!(+ curves.matches(eye),+ "built/layers.json eyes must match rig eye curves"+ );+ }+ for i in 0..2 {+ for part in ["ball", "low", "crease", "lash"] {+ let name = format!("eye{i}_{part}");+ ensure!(+ layers.layers.contains_key(&name),+ "missing required layer: {name}"+ );+ }+ }+ if rig.hand.is_some() {+ ensure!(+ layers.layers.contains_key("hand"),+ "missing required hand layer"+ );+ }+ for accessory in &rig.accessories {+ ensure!(+ layers.layers.contains_key(&accessory.name),+ "missing accessory layer: {}",+ accessory.name+ );+ }+ let manifest = match read("avatar.json")? {+ Some(bytes) => Manifest::parse(&bytes)?,+ None => Manifest::default_named(folder_name.context("avatar.json: missing manifest")?),+ };+ let sprites: Option<SpriteMetadata> = read("built/sprites/sprites.json")?+ .map(|bytes| {+ serde_json::from_slice(&bytes)+ .context("built/sprites/sprites.json: invalid metadata")+ })+ .transpose()?;+ if let Some(sprites) = &sprites {+ ensure!(+ sprites.version == 1 && !sprites.build.trim().is_empty(),+ "sprites metadata: unsupported version or empty build"+ );+ validate_rectangles(&sprites.layers, layers.size)?;+ }+ let mut image_rects = BTreeMap::from([+ (+ "base.png".to_owned(),+ [0, 0, rig.image.width, rig.image.height],+ ),+ (+ "hairmask.png".to_owned(),+ [0, 0, rig.image.width, rig.image.height],+ ),+ ]);+ for (name, rect) in &layers.layers {+ image_rects.insert(format!("{name}.png"), *rect);+ }+ if let Some(sprites) = &sprites {+ for (name, rect) in &sprites.layers {+ image_rects.insert(format!("sprites/{name}.png"), *rect);+ }+ }+ let mut textures = BTreeMap::new();+ for (name, rect) in image_rects {+ let texture = Texture::decode(&required(&format!("built/{name}"))?)+ .with_context(|| format!("built/{name}"))?;+ ensure!(+ [texture.width, texture.height] == [rect[2], rect[3]],+ "built/{name}: PNG dimensions must match rectangle"+ );+ textures.insert(name, texture);+ }+ Ok(Self {+ manifest,+ rig,+ layers,+ sprites,+ textures,+ })+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use std::{+ io::Write,+ sync::{+ atomic::{AtomicUsize, Ordering},+ OnceLock,+ },+ };++ fn png_bytes(width: u32, height: u32, color: png::ColorType, pixels: &[u8]) -> Vec<u8> {+ let mut bytes = Vec::new();+ {+ let mut encoder = png::Encoder::new(&mut bytes, width, height);+ encoder.set_color(color);+ encoder.set_depth(png::BitDepth::Eight);+ encoder+ .write_header()+ .unwrap()+ .write_image_data(pixels)+ .unwrap();+ }+ bytes+ }++ fn fixture() -> BTreeMap<String, Vec<u8>> {+ static FILES: OnceLock<BTreeMap<String, Vec<u8>>> = OnceLock::new();+ FILES+ .get_or_init(|| {+ let mut files = BTreeMap::from([+ (+ "avatar.json".into(),+ include_bytes!("../../../../samples/miko-qipao/avatar.json").to_vec(),+ ),+ (+ "rig.json".into(),+ include_bytes!("../../../../samples/miko-qipao/rig.json").to_vec(),+ ),+ (+ "built/layers.json".into(),+ include_bytes!("../../../../samples/miko-qipao/built/layers.json").to_vec(),+ ),+ (+ "built/sprites/sprites.json".into(),+ include_bytes!("../../../../samples/miko-qipao/built/sprites/sprites.json")+ .to_vec(),+ ),+ ]);+ let layers: LayerMetadata =+ serde_json::from_slice(&files["built/layers.json"]).unwrap();+ let sprites: SpriteMetadata =+ serde_json::from_slice(&files["built/sprites/sprites.json"]).unwrap();+ let mut rects = BTreeMap::from([+ ("base".to_owned(), [0, 0, layers.size[0], layers.size[1]]),+ (+ "hairmask".to_owned(),+ [0, 0, layers.size[0], layers.size[1]],+ ),+ ]);+ rects.extend(layers.layers);+ rects.extend(+ sprites+ .layers+ .into_iter()+ .map(|(n, r)| (format!("sprites/{n}"), r)),+ );+ for (name, [_, _, w, h]) in rects {+ // Synthetic opaque images; the loader tests do not depend on sample PNGs.+ files.insert(+ format!("built/{name}.png"),+ png_bytes(+ w,+ h,+ png::ColorType::Grayscale,+ &vec![255; (w * h) as usize],+ ),+ );+ }+ files+ })+ .clone()+ }++ fn archive(files: &BTreeMap<String, Vec<u8>>) -> Vec<u8> {+ let mut writer = zip::ZipWriter::new(Cursor::new(Vec::new()));+ for (name, bytes) in files {+ writer+ .start_file(+ name,+ zip::write::SimpleFileOptions::default()+ .compression_method(zip::CompressionMethod::Stored),+ )+ .unwrap();+ writer.write_all(bytes).unwrap();+ }+ writer.finish().unwrap().into_inner()+ }++ fn load(files: &BTreeMap<String, Vec<u8>>, folder: bool) -> Result<AvatarPackage> {+ AvatarPackage::load(+ |name| Ok(files.get(name).cloned()),+ folder.then(|| "Test Avatar".to_owned()),+ )+ }++ fn edit_json(files: &mut BTreeMap<String, Vec<u8>>, name: &str, edit: impl FnOnce(&mut Value)) {+ let mut value = serde_json::from_slice(&files[name]).unwrap();+ edit(&mut value);+ files.insert(name.into(), serde_json::to_vec(&value).unwrap());+ }++ struct TestFolder(std::path::PathBuf);+ impl TestFolder {+ fn new(files: &BTreeMap<String, Vec<u8>>) -> Self {+ static NEXT: AtomicUsize = AtomicUsize::new(0);+ let path = Path::new(env!("CARGO_MANIFEST_DIR"))+ .join("../../target/test-fixtures")+ .join(format!(+ "{}-{}",+ std::process::id(),+ NEXT.fetch_add(1, Ordering::Relaxed)+ ));+ fs::create_dir_all(&path).unwrap();+ for (name, bytes) in files {+ let file = path.join(name);+ fs::create_dir_all(file.parent().unwrap()).unwrap();+ fs::write(file, bytes).unwrap();+ }+ Self(path)+ }+ }+ impl Drop for TestFolder {+ fn drop(&mut self) {+ let _ = fs::remove_dir_all(&self.0);+ }+ }++ #[test]+ fn opens_archive_and_folder_with_all_assets() {+ let files = fixture();+ let folder = TestFolder::new(&files);+ let folder_avatar = AvatarPackage::open(&folder.0).unwrap();+ let archive_path = folder.0.join("avatar.mavatar");+ fs::write(&archive_path, archive(&files)).unwrap();+ let packed = AvatarPackage::open(archive_path).unwrap();+ assert_eq!(packed.manifest.name, folder_avatar.manifest.name);+ assert_eq!(packed.textures.len(), 29);+ assert_eq!(packed.textures.len(), folder_avatar.textures.len());+ for (name, texture) in &packed.textures {+ assert_eq!(texture.rgba, folder_avatar.textures[name].rgba);+ }+ }++ #[test]+ fn folder_defaults_and_legacy_curves_are_not_archive_defaults() {+ let mut files = fixture();+ files.remove("avatar.json");+ edit_json(&mut files, "rig.json", |v| {+ for eye in v["eyes"].as_array_mut().unwrap() {+ for field in ["x0", "x1", "top", "bot"] {+ eye.as_object_mut().unwrap().remove(field);+ }+ }+ });+ let avatar = load(&files, true).unwrap();+ assert_eq!(avatar.manifest.name, "Test Avatar");+ assert!(avatar.layers.eyes[0].matches(&avatar.rig.eyes[0]));+ assert!(AvatarPackage::from_archive(Cursor::new(archive(&files))).is_err());+ files.insert("avatar.json".into(), fixture()["avatar.json"].clone());+ assert!(load(&files, false).is_err());+ }++ #[test]+ fn optional_features_and_unknown_fields_remain_compatible() {+ let mut files = fixture();+ files.remove("built/sprites/sprites.json");+ edit_json(&mut files, "rig.json", |v| {+ let object = v.as_object_mut().unwrap();+ for field in ["buns", "strands", "accessories", "hand"] {+ object.remove(field);+ }+ object.insert("futureFeature".into(), serde_json::json!({"enabled": true}));+ });+ let avatar = load(&files, false).unwrap();+ assert!(avatar.sprites.is_none());+ assert!(avatar.rig.strands.is_empty());+ assert!(avatar.rig.hand.is_none());+ }++ #[test]+ fn rejects_bad_rigs_metadata_and_images() {+ type Mutation = (&'static str, fn(&mut Value));+ let mutations: &[Mutation] = &[+ ("rig.json", |v| v["version"] = 2.into()),+ ("rig.json", |v| v["head"]["rx"] = 0.into()),+ ("rig.json", |v| v["mesh"]["baseCell"] = 0.into()),+ ("rig.json", |v| v["mesh"]["eyeCell"] = 1.5.into()),+ ("rig.json", |v| v["eyes"][0]["top"] = serde_json::json!([1])),+ ("rig.json", |v| v["view"]["padSide"] = (-0.5).into()),+ ("built/layers.json", |v| v["version"] = 2.into()),+ ("built/layers.json", |v| v["size"][0] = 1.into()),+ ("built/layers.json", |v| v["eyes"][0]["top"][0] = 0.into()),+ ("built/layers.json", |v| {+ v["layers"].as_object_mut().unwrap().remove("eye0_ball");+ }),+ ("built/sprites/sprites.json", |v| {+ v["layers"]["../escape"] = serde_json::json!([0, 0, 1, 1])+ }),+ ];+ for &(name, edit) in mutations {+ let mut files = fixture();+ edit_json(&mut files, name, edit);+ assert!(load(&files, true).is_err(), "accepted invalid {name}");+ }+ for name in [+ "built/base.png",+ "built/hairmask.png",+ "built/sprites/mouth_a.png",+ ] {+ let mut files = fixture();+ files.remove(name);+ assert!(load(&files, true).is_err(), "accepted missing {name}");+ files.insert(name.into(), vec![1, 2, 3]);+ assert!(load(&files, true).is_err(), "accepted corrupt {name}");+ files.insert(+ name.into(),+ png_bytes(1, 1, png::ColorType::Grayscale, &[255]),+ );+ assert!(+ load(&files, true).is_err(),+ "accepted wrong dimensions for {name}"+ );+ }+ }++ #[test]+ fn rejects_unsafe_archive_entries_and_inconsistent_headers() {+ for name in ["../evil", "/evil", "C:evil", "built\\evil"] {+ let files = BTreeMap::from([(name.to_owned(), vec![1])]);+ assert!(unpack(Cursor::new(archive(&files))).is_err());+ }+ let mut data = archive(&BTreeMap::from([+ ("one".into(), vec![1]),+ ("two".into(), vec![2]),+ ]));+ // Rewrite both occurrences of a same-length filename to create a duplicate.+ for i in 0..data.len() - 2 {+ if &data[i..i + 3] == b"two" {+ data[i..i + 3].copy_from_slice(b"one");+ }+ }+ assert!(unpack(Cursor::new(data))+ .unwrap_err()+ .to_string()+ .contains("duplicate"));+ let good = archive(&BTreeMap::from([("one".into(), vec![1])]));+ let mut bad = good.clone();+ bad[30] = b'x';+ assert!(unpack(Cursor::new(bad)).is_err());+ assert!(unpack(Cursor::new(&good[..good.len() - 1])).is_err());+ let mut too_many = good;+ let end = too_many.len() - 22;+ too_many[end + 8..end + 12].copy_from_slice(&[201, 0, 201, 0]);+ assert!(unpack(Cursor::new(too_many))+ .unwrap_err()+ .to_string()+ .contains("entries"));+ }++ #[test]+ fn decodes_png_channels_and_premultiplies_for_upload() {+ for (color, pixels, expected) in [+ (+ png::ColorType::Grayscale,+ vec![100],+ vec![100, 100, 100, 255],+ ),+ (+ png::ColorType::GrayscaleAlpha,+ vec![100, 128],+ vec![100, 100, 100, 128],+ ),+ (png::ColorType::Rgb, vec![20, 40, 60], vec![20, 40, 60, 255]),+ (+ png::ColorType::Rgba,+ vec![20, 40, 60, 128],+ vec![20, 40, 60, 128],+ ),+ ] {+ let texture = Texture::decode(&png_bytes(1, 1, color, &pixels)).unwrap();+ assert_eq!(texture.rgba, expected);+ assert_eq!(texture.alpha(), [expected[3]]);+ }+ let texture =+ Texture::decode(&png_bytes(1, 1, png::ColorType::Rgba, &[20, 40, 60, 128])).unwrap();+ assert_eq!(texture.premultiplied_rgba(), [10, 20, 30, 128]);+ }++ #[cfg(unix)]+ #[test]+ fn rejects_folder_symlinks_outside_project() {+ let folder = TestFolder::new(&fixture());+ let outside = TestFolder::new(&BTreeMap::from([("base.png".into(), vec![1])]));+ fs::remove_file(folder.0.join("built/base.png")).unwrap();+ std::os::unix::fs::symlink(+ outside.0.canonicalize().unwrap().join("base.png"),+ folder.0.join("built/base.png"),+ )+ .unwrap();+ let error = AvatarPackage::open(&folder.0).unwrap_err();+ assert!(error.to_string().contains("escapes project"));+ }+}diff --git a/native/crates/mesh-avatar-core/src/lib.rs b/native/crates/mesh-avatar-core/src/lib.rsnew file mode 100644index 0000000..6ba75e5--- /dev/null+++ b/native/crates/mesh-avatar-core/src/lib.rs@@ -0,0 +1,5 @@+//! Data loading and CPU geometry for mesh avatars.++pub mod engine;+pub mod format;+pub mod rig;diff --git a/native/crates/mesh-avatar-core/src/rig.rs b/native/crates/mesh-avatar-core/src/rig.rsnew file mode 100644index 0000000..e7c84c0--- /dev/null+++ b/native/crates/mesh-avatar-core/src/rig.rs@@ -0,0 +1,346 @@+//! Typed rig data. Unknown JSON fields are ignored for forward compatibility.++use anyhow::{ensure, Context, Result};+use serde::{Deserialize, Serialize};++pub type Point = [f64; 2];+pub type Band = [f64; 2];++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct Ellipse {+ pub cx: f64,+ pub cy: f64,+ pub rx: f64,+ pub ry: f64,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct Eye {+ pub opening: Vec<Point>,+ pub roi: Vec<Point>,+ pub x0: f64,+ pub x1: f64,+ pub top: [f64; 24],+ pub bot: [f64; 24],+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct Strand {+ pub name: String,+ pub nodes: Vec<Point>,+ pub sigma: f64,+ pub k: f64,+ pub max: f64,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct Accessory {+ pub name: String,+ pub pivot: Point,+ pub tip: Point,+ pub split: f64,+ pub r#box: [i64; 4],+ pub color: AccessoryColor,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct AccessoryColor {+ pub redness: f64,+ pub min_red: f64,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct Hand {+ pub outline: Vec<Point>,+ pub jaw: Vec<Point>,+ pub jaw_range: Band,+ pub background: Vec<Point>,+ pub elbow: Point,+ pub wrist: Point,+ pub knuckle: Point,+ pub contact: Point,+ pub forearm_share: f64,+ pub arm_band: Band,+ pub wrist_band: Band,+ pub hand_band: Band,+ pub finger_x_band: Band,+ pub finger_y_band: Band,+ pub pin_band: Band,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct ImageSize {+ pub width: u32,+ pub height: u32,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct Head {+ #[serde(flatten)]+ pub ellipse: Ellipse,+ pub shift_x: f64,+ pub shift_y: f64,+ pub pivot_x: f64,+ pub pivot_y: f64,+ pub max_roll: f64,+ pub weight_band: Band,+ pub turn_band: Band,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct Body {+ pub pivot_x: f64,+ pub pivot_y: f64,+ pub max_roll: f64,+ pub breath_band: Band,+ pub roll_band: Band,+ pub chest: Ellipse,+ pub shoulders: Vec<Ellipse>,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct BandedEllipse {+ #[serde(flatten)]+ pub ellipse: Ellipse,+ pub band: Band,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct Face {+ pub nose: Ellipse,+ pub mouth: Ellipse,+ pub eye_a: Ellipse,+ pub eye_b: Ellipse,+ pub ear_l: Ellipse,+ pub ear_r: Ellipse,+ pub brow: BandedEllipse,+ pub jaw: BandedEllipse,+}++#[derive(Debug, Clone, Default, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct Buns {+ pub bun_l: Option<Ellipse>,+ pub bun_r: Option<Ellipse>,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct MouthArea {+ #[serde(flatten)]+ pub ellipse: Ellipse,+ pub angle: f64,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct Mouth {+ pub cx: f64,+ pub cy: f64,+ pub angle: f64,+ pub half_len: f64,+ pub bow: f64,+ pub area: MouthArea,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct FineGrid {+ pub x0: i64,+ pub x1: i64,+ pub y0: i64,+ pub y1: i64,+ pub cell: u32,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct Mesh {+ pub base_cell: u32,+ pub fine: FineGrid,+ pub hand_cell: u32,+ pub tassel_cell: u32,+ pub eye_ball_cell: u32,+ pub eye_cell: u32,+ pub sprite_cell: u32,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+#[serde(rename_all = "camelCase")]+pub struct View {+ pub pad_top: f64,+ pub pad_side: f64,+ pub gaze_center: Option<Point>,+}++#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct Rig {+ pub version: u32,+ pub image: ImageSize,+ pub head: Head,+ pub body: Body,+ pub face: Face,+ pub buns: Option<Buns>,+ pub eyes: [Eye; 2],+ pub mouth: Mouth,+ pub cheeks: [Point; 2],+ #[serde(default)]+ pub strands: Vec<Strand>,+ #[serde(default)]+ pub accessories: Vec<Accessory>,+ pub hand: Option<Hand>,+ pub mesh: Mesh,+ pub view: View,+}++fn ellipse(e: &Ellipse) -> Result<()> {+ ensure!(e.rx > 0.0 && e.ry > 0.0, "ellipse radii must be positive");+ Ok(())+}++fn band(b: Band) -> Result<()> {+ ensure!(b[0] < b[1], "band start must be less than end");+ Ok(())+}++impl Rig {+ pub fn parse(bytes: &[u8]) -> Result<Self> {+ let rig: Self = serde_json::from_slice(bytes).context("rig.json: invalid rig JSON")?;+ rig.validate().context("rig.json: invalid rig")?;+ Ok(rig)+ }++ pub fn validate(&self) -> Result<()> {+ ensure!(self.version == 1, "only rig version 1 is supported");+ ensure!(+ self.image.width > 0 && self.image.height > 0,+ "image dimensions must be positive"+ );+ ellipse(&self.head.ellipse)?;+ band(self.head.weight_band)?;+ band(self.head.turn_band)?;+ band(self.body.breath_band)?;+ band(self.body.roll_band)?;+ let f = &self.face;+ for e in [+ &self.body.chest,+ &f.nose,+ &f.mouth,+ &f.eye_a,+ &f.eye_b,+ &f.ear_l,+ &f.ear_r,+ &f.brow.ellipse,+ &f.jaw.ellipse,+ &self.mouth.area.ellipse,+ ]+ .into_iter()+ .chain(self.body.shoulders.iter())+ {+ ellipse(e)?;+ }+ band(f.brow.band)?;+ band(f.jaw.band)?;+ if let Some(buns) = &self.buns {+ for e in [&buns.bun_l, &buns.bun_r].into_iter().flatten() {+ ellipse(e)?;+ }+ }+ for (i, eye) in self.eyes.iter().enumerate() {+ ensure!(+ eye.opening.len() >= 3 && eye.roi.len() >= 3,+ "eyes[{i}]: polygons need at least three points"+ );+ ensure!(eye.x0 < eye.x1, "eyes[{i}]: x1 must exceed x0");+ ensure!(+ eye.top.iter().zip(eye.bot).all(|(&a, b)| a <= b),+ "eyes[{i}]: top must not exceed bottom curve"+ );+ }+ ensure!(self.mouth.half_len > 0.0, "mouth.halfLen must be positive");+ for s in &self.strands {+ ensure!(!s.name.trim().is_empty(), "strand name must not be empty");+ ensure!(+ s.nodes.len() >= 2 && s.nodes.windows(2).all(|p| p[0] != p[1]),+ "strand needs distinct consecutive nodes"+ );+ ensure!(+ s.sigma > 0.0 && s.k > 0.0 && s.max > 0.0,+ "strand sigma/k/max must be positive"+ );+ }+ for a in &self.accessories {+ ensure!(+ !a.name.trim().is_empty(),+ "accessory name must not be empty"+ );+ ensure!(+ a.split > 0.0 && a.split < 1.0,+ "accessory split must be between zero and one"+ );+ ensure!(a.pivot != a.tip, "accessory tip must differ from pivot");+ let [x0, y0, x1, y1] = a.r#box;+ ensure!(+ x0 >= 0+ && y0 >= 0+ && x0 < x1+ && y0 < y1+ && x1 <= self.image.width as i64+ && y1 <= self.image.height as i64,+ "accessory rectangle must stay inside image"+ );+ ensure!(+ (0.0..=1.0).contains(&a.color.redness),+ "accessory redness must be between zero and one"+ );+ }+ if let Some(h) = &self.hand {+ ensure!(+ h.outline.len() >= 3 && h.background.len() >= 3 && h.jaw.len() >= 2,+ "invalid hand polygons or jaw"+ );+ ensure!(+ (0.0..=1.0).contains(&h.forearm_share),+ "hand forearmShare must be between zero and one"+ );+ for b in [+ h.jaw_range,+ h.arm_band,+ h.wrist_band,+ h.hand_band,+ h.finger_x_band,+ h.finger_y_band,+ h.pin_band,+ ] {+ band(b)?;+ }+ }+ let m = &self.mesh;+ ensure!(+ [+ m.base_cell,+ m.fine.cell,+ m.hand_cell,+ m.tassel_cell,+ m.eye_ball_cell,+ m.eye_cell,+ m.sprite_cell+ ]+ .iter()+ .all(|&n| n > 0),+ "mesh cells must be positive"+ );+ ensure!(+ m.fine.x0 < m.fine.x1 && m.fine.y0 < m.fine.y1,+ "fine rectangle must have positive area"+ );+ ensure!(+ self.view.pad_top > -1.0 && self.view.pad_top < 1.0 && self.view.pad_side > -0.5,+ "view margins must leave a positive viewport"+ );+ Ok(())+ }+}diff --git a/native/crates/mesh-avatar-core/tests/conformance.rs b/native/crates/mesh-avatar-core/tests/conformance.rsnew file mode 100644index 0000000..7c2c310--- /dev/null+++ b/native/crates/mesh-avatar-core/tests/conformance.rs@@ -0,0 +1,78 @@+use mesh_avatar_core::{+ engine::grid::{build_grid, Grid},+ format::AvatarPackage,+ rig::FineGrid,+};+use serde::Deserialize;+use std::{fs, path::Path};++#[derive(Deserialize)]+struct Golden {+ version: u32,+ grids: Vec<Layer>,+ cases: Vec<Case>,+}++#[derive(Deserialize)]+struct Layer {+ name: String,+ texture: String,+ cell: f64,+ fine: Option<FineGrid>,+ mesh: Grid,+}++#[derive(Deserialize)]+struct Case {+ name: String,+ rect: [f64; 4],+ cell: f64,+ alpha: Vec<u8>,+ width: usize,+ fine: Option<FineGrid>,+ mesh: Grid,+}++#[test]+fn every_sample_grid_matches_javascript_exactly() {+ let native = Path::new(env!("CARGO_MANIFEST_DIR")).join("../..");+ let golden_path = native.join("target/conformance/grids.json");+ let bytes = match fs::read(&golden_path) {+ Ok(bytes) => bytes,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => {+ eprintln!("Grid goldens absent; skipping. Run node native/conformance/dump.mjs first.");+ return;+ }+ Err(e) => panic!("could not read grid goldens: {e}"),+ };+ let golden: Golden = serde_json::from_slice(&bytes).unwrap();+ assert_eq!(golden.version, 1);+ let avatar = AvatarPackage::open(native.join("../samples/miko-qipao")).unwrap();+ assert_eq!(+ golden.grids.len(),+ 1 + avatar.layers.layers.len() + avatar.sprites.as_ref().unwrap().layers.len()+ );+ for layer in golden.grids {+ let texture = &avatar.textures[&layer.texture];+ let actual = build_grid(+ layer.mesh.rect,+ layer.cell,+ &texture.alpha(),+ texture.width as usize,+ layer.fine.as_ref(),+ )+ .unwrap();+ assert_eq!(actual, layer.mesh, "grid mismatch for {}", layer.name);+ }+ for case in golden.cases {+ let actual = build_grid(+ case.rect,+ case.cell,+ &case.alpha,+ case.width,+ case.fine.as_ref(),+ )+ .unwrap();+ assert_eq!(actual, case.mesh, "grid mismatch for {}", case.name);+ }+}diff --git a/native/crates/mesh-avatar-wgpu/Cargo.toml b/native/crates/mesh-avatar-wgpu/Cargo.tomlnew file mode 100644index 0000000..fab5168--- /dev/null+++ b/native/crates/mesh-avatar-wgpu/Cargo.toml@@ -0,0 +1,9 @@+[package]+name = "mesh-avatar-wgpu"+version.workspace = true+edition.workspace = true+rust-version.workspace = true+publish.workspace = true++[dependencies]+mesh-avatar-core.workspace = truediff --git a/native/crates/mesh-avatar-wgpu/src/lib.rs b/native/crates/mesh-avatar-wgpu/src/lib.rsnew file mode 100644index 0000000..bf7c711--- /dev/null+++ b/native/crates/mesh-avatar-wgpu/src/lib.rs@@ -0,0 +1,3 @@+//! GPU rendering support for mesh avatars.+//!+//! The renderer is not implemented yet.