From 6ac9046bd457f09cdb5eb7b229e50584877b8f68 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 12:10:04 +0000 Subject: [PATCH 1/4] Share streaming TextureCraft tile payloads --- Cargo.lock | 8 + Cargo.toml | 1 + crates/tcraft/Cargo.toml | 15 ++ crates/tcraft/README.md | 14 ++ crates/tcraft/src/lib.rs | 342 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 380 insertions(+) create mode 100644 crates/tcraft/Cargo.toml create mode 100644 crates/tcraft/README.md create mode 100644 crates/tcraft/src/lib.rs diff --git a/Cargo.lock b/Cargo.lock index d984ac115..b0f05a3b0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2686,6 +2686,14 @@ dependencies = [ "kurbo 0.13.1", ] +[[package]] +name = "craft-tcraft" +version = "0.1.0" +dependencies = [ + "craft-zip", + "thiserror 2.0.21", +] + [[package]] name = "craft-text" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 77b20da79..d60c3469b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -142,6 +142,7 @@ craft-stencilcraft-document = { path = "crates/stencilcraft-document" } craft-svg-paths = { path = "crates/svg-paths" } craft-stream-codecs = { path = "crates/stream-codecs" } craft-text = { path = "crates/text" } +craft-tcraft = { path = "crates/tcraft" } craft-texture = { path = "crates/texture" } craft-tga = { path = "crates/tga" } craft-timeline = { path = "crates/timeline" } diff --git a/crates/tcraft/Cargo.toml b/crates/tcraft/Cargo.toml new file mode 100644 index 000000000..76eeeafb0 --- /dev/null +++ b/crates/tcraft/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "craft-tcraft" +description = "Streaming binary payloads of TextureCraft project archives" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +craft-zip = { workspace = true } +thiserror = { workspace = true } diff --git a/crates/tcraft/README.md b/crates/tcraft/README.md new file mode 100644 index 000000000..e5831ef98 --- /dev/null +++ b/crates/tcraft/README.md @@ -0,0 +1,14 @@ +# craft-tcraft + +Streaming neutral `TCTX` binary payloads used inside TextureCraft `.tcraft` projects. Sparse +paint data stores 64×64 tiles of little-endian `u16` components; baked maps store dense +little-endian `f32` values. This crate does not yet define the project JSON schema or ZIP +envelope and does not depend on TextureCraft's app types. + +`read_tiles` validates the expected dimensions and components, bounds tile count, rejects +out-of-range and repeated tile positions, and delivers one owned tile at a time. `read_baked` +validates dimensions and declared length and decodes in bounded chunks. Both consume the same +caller-owned `craft_zip::Budget` used for the surrounding project and reject trailing data. +`write_tiles` and `write_baked` stream their bodies rather than copying an entire image; a caller +must discard an incomplete output if a write fails. Limits and ownership rules beyond this +binary format remain with the project reader. diff --git a/crates/tcraft/src/lib.rs b/crates/tcraft/src/lib.rs new file mode 100644 index 000000000..50022bb1e --- /dev/null +++ b/crates/tcraft/src/lib.rs @@ -0,0 +1,342 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] +//! Streaming `TCTX` tile and baked-map payloads in TextureCraft `.tcraft` archives. +//! +//! This codec handles the neutral binary payload, not the application's project model or ZIP +//! envelope. Reads use a caller-owned budget shared with other archive entries. No reader opens +//! a file or reserves memory based on a claimed payload before checking it. + +use std::collections::HashSet; +use std::io::{self, Read, Write}; + +use craft_zip::Budget; + +pub const TILE_SIDE: u32 = 64; +pub const TILE_AREA: usize = 64 * 64; +pub const HEADER_BYTES: u64 = 24; +pub const VERSION: u32 = 1; +const MAGIC: &[u8; 4] = b"TCTX"; +const CHUNK: usize = 1 << 16; + +#[derive(Debug, thiserror::Error)] +pub enum Error { + #[error("invalid TCTX payload: {0}")] + Invalid(String), + #[error("TCTX version {0} is newer than supported")] + NewerVersion(u32), + #[error("TCTX limit: {0}")] + Limit(String), + #[error("TCTX I/O: {0}")] + Io(#[from] io::Error), +} + +/// Width, height and number of components expected by the enclosing project schema. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Layout { + pub width: u32, + pub height: u32, + pub components: usize, +} + +#[derive(Clone, Copy, Debug)] +struct Header { + layout: Layout, + count: u32, +} + +fn charge(budget: &mut Budget, n: u64) -> Result<(), Error> { + budget.charge(n).map_err(|e| Error::Limit(e.to_string())) +} + +fn read_header(reader: &mut impl Read, budget: &mut Budget) -> Result { + charge(budget, HEADER_BYTES)?; + let mut bytes = [0u8; HEADER_BYTES as usize]; + reader.read_exact(&mut bytes)?; + if bytes.get(..4) != Some(MAGIC.as_slice()) { + return Err(Error::Invalid("bad magic".into())); + } + let word = |i: usize| bytes.get(i * 4..i * 4 + 4).map(|b| u32::from_le_bytes([b[0], b[1], b[2], b[3]])).unwrap_or(0); + let version = word(1); + if version > VERSION { + return Err(Error::NewerVersion(version)); + } + Ok(Header { layout: Layout { width: word(2), height: word(3), components: word(4) as usize }, count: word(5) }) +} + +fn write_header(writer: &mut impl Write, layout: Layout, count: u32) -> Result<(), Error> { + let components = u32::try_from(layout.components).map_err(|_| Error::Limit("too many components".into()))?; + writer.write_all(MAGIC)?; + for value in [VERSION, layout.width, layout.height, components, count] { + writer.write_all(&value.to_le_bytes())?; + } + Ok(()) +} + +fn expect_end(reader: &mut impl Read) -> Result<(), Error> { + let mut byte = [0u8; 1]; + if reader.read(&mut byte)? != 0 { + return Err(Error::Invalid("trailing data".into())); + } + Ok(()) +} + +fn tile_dimensions(layout: Layout) -> Result<(u32, u32, usize), Error> { + if layout.width == 0 || layout.height == 0 || layout.components == 0 { + return Err(Error::Invalid("empty tile layout".into())); + } + let x = layout.width.div_ceil(TILE_SIDE); + let y = layout.height.div_ceil(TILE_SIDE); + let bytes = TILE_AREA.checked_mul(layout.components).and_then(|n| n.checked_mul(2)).ok_or_else(|| Error::Limit("tile is too large".into()))?; + Ok((x, y, bytes)) +} + +/// Decode tiles one at a time, transferring each tile to the callback. +/// Positions and duplicate tiles are checked before delivery; the entry must end exactly. +pub fn read_tiles( + reader: &mut impl Read, + expected: Layout, + budget: &mut Budget, + mut tile: impl FnMut(u32, u32, Vec) -> Result<(), Error>, +) -> Result<(), Error> { + let header = read_header(reader, budget)?; + if header.layout != expected { + return Err(Error::Invalid("tile layout differs from the project".into())); + } + let (tiles_x, tiles_y, bytes_per_tile) = tile_dimensions(expected)?; + if u64::from(header.count) > u64::from(tiles_x) * u64::from(tiles_y) { + return Err(Error::Invalid("more tiles than the image holds".into())); + } + let mut bytes = Vec::new(); + let mut seen = HashSet::new(); + for _ in 0..header.count { + let payload = u64::try_from(bytes_per_tile).map_err(|_| Error::Limit("tile is too large".into()))?.saturating_add(8); + charge(budget, payload)?; + if bytes.is_empty() { + bytes.try_reserve_exact(bytes_per_tile).map_err(|_| Error::Limit("tile allocation failed".into()))?; + bytes.resize(bytes_per_tile, 0); + } + let mut pos = [0u8; 8]; + reader.read_exact(&mut pos)?; + let x = u32::from_le_bytes([pos[0], pos[1], pos[2], pos[3]]); + let y = u32::from_le_bytes([pos[4], pos[5], pos[6], pos[7]]); + if x >= tiles_x || y >= tiles_y || seen.contains(&(x, y)) { + return Err(Error::Invalid(format!("bad or repeated tile ({x}, {y})"))); + } + seen.try_reserve(1).map_err(|_| Error::Limit("tile index allocation failed".into()))?; + seen.insert((x, y)); + reader.read_exact(&mut bytes)?; + let mut values = Vec::new(); + values.try_reserve_exact(bytes_per_tile / 2).map_err(|_| Error::Limit("tile allocation failed".into()))?; + values.extend(bytes.as_chunks::<2>().0.iter().map(|b| u16::from_le_bytes(*b))); + tile(x, y, values)?; + } + expect_end(reader) +} + +/// Write tiles in caller order, without buffering the image. A failure may leave a partial +/// entry; callers writing a project should discard the incomplete output. +pub fn write_tiles<'a>( + writer: &mut impl Write, + layout: Layout, + count: u32, + tiles: impl IntoIterator, +) -> Result<(), Error> { + let (tiles_x, tiles_y, bytes_per_tile) = tile_dimensions(layout)?; + if u64::from(count) > u64::from(tiles_x) * u64::from(tiles_y) { + return Err(Error::Invalid("more tiles than the image holds".into())); + } + write_header(writer, layout, count)?; + let mut seen = HashSet::new(); + let mut bytes = Vec::new(); + let mut written = 0u32; + for (x, y, values) in tiles { + if written >= count || x >= tiles_x || y >= tiles_y || seen.contains(&(x, y)) || values.len() != bytes_per_tile / 2 { + return Err(Error::Invalid("bad, repeated or incorrectly sized tile".into())); + } + seen.try_reserve(1).map_err(|_| Error::Limit("tile index allocation failed".into()))?; + seen.insert((x, y)); + if bytes.is_empty() { + bytes.try_reserve_exact(bytes_per_tile).map_err(|_| Error::Limit("tile allocation failed".into()))?; + } + bytes.clear(); + bytes.extend(values.iter().flat_map(|v| v.to_le_bytes())); + writer.write_all(&x.to_le_bytes())?; + writer.write_all(&y.to_le_bytes())?; + writer.write_all(&bytes)?; + written += 1; + } + if written != count { + return Err(Error::Invalid("tile count differs from its data".into())); + } + Ok(()) +} + +/// Read a dense f32 map, validating declared size and charging its shared budget first. +pub fn read_baked( + reader: &mut impl Read, + declared_bytes: u64, + components: usize, + max_texels: u64, + budget: &mut Budget, +) -> Result<(Layout, Vec), Error> { + let header = read_header(reader, budget)?; + let layout = header.layout; + let texels = u64::from(layout.width) * u64::from(layout.height); + if texels == 0 || texels > max_texels || layout.components != components || components == 0 { + return Err(Error::Invalid("bad baked-map dimensions or components".into())); + } + let count = texels.checked_mul(components as u64).ok_or_else(|| Error::Limit("too many map values".into()))?; + let payload = count.checked_mul(4).ok_or_else(|| Error::Limit("map is too large".into()))?; + if declared_bytes != HEADER_BYTES.checked_add(payload).ok_or_else(|| Error::Limit("map is too large".into()))? { + return Err(Error::Invalid("declared map size differs from its dimensions".into())); + } + charge(budget, payload)?; + let count = usize::try_from(count).map_err(|_| Error::Limit("too many map values".into()))?; + let mut values = Vec::new(); + let chunk_bytes = CHUNK.min(count) * 4; + let mut bytes = Vec::new(); + bytes.try_reserve_exact(chunk_bytes).map_err(|_| Error::Limit("map chunk allocation failed".into()))?; + bytes.resize(chunk_bytes, 0); + while values.len() < count { + let n = CHUNK.min(count - values.len()); + let chunk = bytes.get_mut(..n * 4).ok_or_else(|| Error::Invalid("bad map chunk".into()))?; + reader.read_exact(chunk)?; + values.try_reserve(n).map_err(|_| Error::Limit("map allocation failed".into()))?; + values.extend(chunk.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b))); + } + expect_end(reader)?; + Ok((layout, values)) +} + +/// Write a dense f32 map in bounded chunks without constructing a second copy of its payload. +pub fn write_baked(writer: &mut impl Write, layout: Layout, values: &[f32]) -> Result<(), Error> { + let count = u64::from(layout.width).checked_mul(u64::from(layout.height)).and_then(|n| n.checked_mul(layout.components as u64)); + if layout.width == 0 || layout.height == 0 || layout.components == 0 || count != Some(values.len() as u64) { + return Err(Error::Invalid("map dimensions differ from its data".into())); + } + write_header(writer, layout, 0)?; + let mut bytes = Vec::new(); + bytes.try_reserve_exact(CHUNK * 4).map_err(|_| Error::Limit("map chunk allocation failed".into()))?; + for chunk in values.chunks(CHUNK) { + bytes.clear(); + bytes.extend(chunk.iter().flat_map(|v| v.to_le_bytes())); + writer.write_all(&bytes)?; + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use std::io::Cursor; + + fn header(layout: Layout, count: u32) -> Vec { + let mut bytes = Vec::new(); + write_header(&mut bytes, layout, count).unwrap(); + bytes + } + + #[test] + fn baked_map_matches_the_native_little_endian_wire_layout() { + let layout = Layout { width: 2, height: 1, components: 1 }; + let mut expected = b"TCTX".to_vec(); + for value in [1u32, 2, 1, 1, 0] { + expected.extend_from_slice(&value.to_le_bytes()); + } + expected.extend_from_slice(&1.0f32.to_le_bytes()); + expected.extend_from_slice(&(-0.5f32).to_le_bytes()); + let mut actual = Vec::new(); + write_baked(&mut actual, layout, &[1.0, -0.5]).unwrap(); + assert_eq!(actual, expected); + let (decoded, values) = read_baked(&mut Cursor::new(&expected), expected.len() as u64, 1, 2, &mut Budget::new("project", 32)).unwrap(); + assert_eq!(decoded, layout); + assert_eq!(values, [1.0, -0.5]); + expected[4..8].copy_from_slice(&2u32.to_le_bytes()); + assert!(matches!(read_baked(&mut Cursor::new(&expected), 32, 1, 2, &mut Budget::new("project", 32)), Err(Error::NewerVersion(2)))); + } + + #[test] + fn dense_maps_round_trip_bit_exactly_in_bounded_chunks() { + let layout = Layout { width: 300, height: 300, components: 1 }; + let mut values = vec![0.25; 90_000]; + values[123] = f32::from_bits(0x7fc0_1234); + let mut bytes = Vec::new(); + write_baked(&mut bytes, layout, &values).unwrap(); + let mut budget = Budget::new("project", bytes.len() as u64); + let (decoded_layout, decoded) = read_baked(&mut Cursor::new(&bytes), bytes.len() as u64, 1, 100_000, &mut budget).unwrap(); + assert_eq!(decoded_layout, layout); + assert!(decoded.iter().zip(values.iter()).all(|(a, b)| a.to_bits() == b.to_bits())); + assert_eq!(budget.remaining(), 0); + } + + #[test] + fn dense_maps_refuse_false_lengths_limits_and_trailing_data() { + let layout = Layout { width: 2, height: 2, components: 1 }; + let mut bytes = Vec::new(); + write_baked(&mut bytes, layout, &[1.0; 4]).unwrap(); + let mut budget = Budget::new("project", 100); + assert!(read_baked(&mut Cursor::new(&bytes), 999, 1, 4, &mut budget).is_err()); + let mut budget = Budget::new("project", 39); + assert!(matches!(read_baked(&mut Cursor::new(&bytes), 40, 1, 4, &mut budget), Err(Error::Limit(_)))); + let mut extra = bytes.clone(); + extra.push(0); + let mut budget = Budget::new("project", 100); + assert!(read_baked(&mut Cursor::new(extra), 40, 1, 4, &mut budget).is_err()); + } + + #[test] + fn hostile_headers_and_tiles_are_rejected_without_trusting_counts() { + let layout = Layout { width: 64, height: 64, components: 1 }; + let mut bad_magic = header(layout, 0); + bad_magic[0] = b'X'; + assert!(read_tiles(&mut Cursor::new(bad_magic), layout, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); + assert!(read_tiles(&mut Cursor::new(header(layout, 2)), layout, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); + let other = Layout { width: 65, ..layout }; + assert!(read_tiles(&mut Cursor::new(header(layout, 0)), other, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); + let mut outside = header(layout, 1); + outside.extend_from_slice(&1u32.to_le_bytes()); + outside.extend_from_slice(&0u32.to_le_bytes()); + assert!(read_tiles(&mut Cursor::new(outside), layout, &mut Budget::new("project", 10_000), |_, _, _| Ok(())).is_err()); + let mut truncated = header(layout, 1); + truncated.extend_from_slice(&[0; 8]); + assert!(read_tiles(&mut Cursor::new(truncated), layout, &mut Budget::new("project", 10_000), |_, _, _| Ok(())).is_err()); + let mut extra = header(layout, 0); + extra.push(1); + assert!(read_tiles(&mut Cursor::new(extra), layout, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); + } + + #[test] + fn sparse_tiles_stream_and_reject_duplicates_and_short_budget() { + let layout = Layout { width: 128, height: 64, components: 1 }; + let mut bytes = header(layout, 2); + for x in [0u32, 1] { + bytes.extend_from_slice(&x.to_le_bytes()); + bytes.extend_from_slice(&0u32.to_le_bytes()); + for _ in 0..TILE_AREA { + bytes.extend_from_slice(&(x as u16 + 1).to_le_bytes()); + } + } + let first = vec![1u16; TILE_AREA]; + let second = vec![2u16; TILE_AREA]; + let mut written = Vec::new(); + write_tiles(&mut written, layout, 2, [(0, 0, first.as_slice()), (1, 0, second.as_slice())]).unwrap(); + assert_eq!(written, bytes, "the streamed writer keeps the native wire layout"); + assert!(write_tiles(&mut Vec::new(), layout, 2, [(0, 0, first.as_slice())]).is_err()); + let mut seen = Vec::new(); + let mut budget = Budget::new("project", bytes.len() as u64); + read_tiles(&mut Cursor::new(&bytes), layout, &mut budget, |x, y, tile| { + seen.push((x, y, tile.first().copied())); + Ok(()) + }) + .unwrap(); + assert_eq!(seen, [(0, 0, Some(1)), (1, 0, Some(2))]); + let mut duplicate = bytes.clone(); + let second = HEADER_BYTES as usize + 8 + TILE_AREA * 2; + duplicate[second..second + 4].copy_from_slice(&0u32.to_le_bytes()); + assert!(read_tiles(&mut Cursor::new(duplicate), layout, &mut Budget::new("project", u64::MAX), |_, _, _| Ok(())).is_err()); + assert!(matches!( + read_tiles(&mut Cursor::new(bytes), layout, &mut Budget::new("project", HEADER_BYTES), |_, _, _| Ok(())), + Err(Error::Limit(_)) + )); + } +} From 5f46c0ab25f067f6fdb863c7e1f9ff567712f394 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 12:23:23 +0000 Subject: [PATCH 2/4] Preserve project budget and streaming IO errors --- crates/tcraft/src/lib.rs | 51 ++++++++++++++++++++++++---------------- 1 file changed, 31 insertions(+), 20 deletions(-) diff --git a/crates/tcraft/src/lib.rs b/crates/tcraft/src/lib.rs index 50022bb1e..4646d8717 100644 --- a/crates/tcraft/src/lib.rs +++ b/crates/tcraft/src/lib.rs @@ -24,6 +24,8 @@ pub enum Error { Invalid(String), #[error("TCTX version {0} is newer than supported")] NewerVersion(u32), + #[error("TCTX budget: {0}")] + Budget(#[from] craft_zip::Exceeded), #[error("TCTX limit: {0}")] Limit(String), #[error("TCTX I/O: {0}")] @@ -45,10 +47,10 @@ struct Header { } fn charge(budget: &mut Budget, n: u64) -> Result<(), Error> { - budget.charge(n).map_err(|e| Error::Limit(e.to_string())) + budget.charge(n).map_err(Error::from) } -fn read_header(reader: &mut impl Read, budget: &mut Budget) -> Result { +fn read_header(reader: &mut (impl Read + ?Sized), budget: &mut Budget) -> Result { charge(budget, HEADER_BYTES)?; let mut bytes = [0u8; HEADER_BYTES as usize]; reader.read_exact(&mut bytes)?; @@ -63,7 +65,7 @@ fn read_header(reader: &mut impl Read, budget: &mut Budget) -> Result Result<(), Error> { +fn write_header(writer: &mut (impl Write + ?Sized), layout: Layout, count: u32) -> Result<(), Error> { let components = u32::try_from(layout.components).map_err(|_| Error::Limit("too many components".into()))?; writer.write_all(MAGIC)?; for value in [VERSION, layout.width, layout.height, components, count] { @@ -72,7 +74,7 @@ fn write_header(writer: &mut impl Write, layout: Layout, count: u32) -> Result<( Ok(()) } -fn expect_end(reader: &mut impl Read) -> Result<(), Error> { +fn expect_end(reader: &mut (impl Read + ?Sized)) -> Result<(), Error> { let mut byte = [0u8; 1]; if reader.read(&mut byte)? != 0 { return Err(Error::Invalid("trailing data".into())); @@ -93,12 +95,17 @@ fn tile_dimensions(layout: Layout) -> Result<(u32, u32, usize), Error> { /// Decode tiles one at a time, transferring each tile to the callback. /// Positions and duplicate tiles are checked before delivery; the entry must end exactly. pub fn read_tiles( - reader: &mut impl Read, + reader: &mut (impl Read + ?Sized), expected: Layout, + max_texels: u64, budget: &mut Budget, mut tile: impl FnMut(u32, u32, Vec) -> Result<(), Error>, ) -> Result<(), Error> { let header = read_header(reader, budget)?; + let texels = u64::from(expected.width) * u64::from(expected.height); + if texels == 0 || texels > max_texels { + return Err(Error::Limit("tile image exceeds its texel limit".into())); + } if header.layout != expected { return Err(Error::Invalid("tile layout differs from the project".into())); } @@ -136,7 +143,7 @@ pub fn read_tiles( /// Write tiles in caller order, without buffering the image. A failure may leave a partial /// entry; callers writing a project should discard the incomplete output. pub fn write_tiles<'a>( - writer: &mut impl Write, + writer: &mut (impl Write + ?Sized), layout: Layout, count: u32, tiles: impl IntoIterator, @@ -173,7 +180,7 @@ pub fn write_tiles<'a>( /// Read a dense f32 map, validating declared size and charging its shared budget first. pub fn read_baked( - reader: &mut impl Read, + reader: &mut (impl Read + ?Sized), declared_bytes: u64, components: usize, max_texels: u64, @@ -188,7 +195,7 @@ pub fn read_baked( let count = texels.checked_mul(components as u64).ok_or_else(|| Error::Limit("too many map values".into()))?; let payload = count.checked_mul(4).ok_or_else(|| Error::Limit("map is too large".into()))?; if declared_bytes != HEADER_BYTES.checked_add(payload).ok_or_else(|| Error::Limit("map is too large".into()))? { - return Err(Error::Invalid("declared map size differs from its dimensions".into())); + return Err(Error::Invalid(format!("{declared_bytes} bytes for a {}×{}×{} map", layout.width, layout.height, layout.components))); } charge(budget, payload)?; let count = usize::try_from(count).map_err(|_| Error::Limit("too many map values".into()))?; @@ -209,7 +216,7 @@ pub fn read_baked( } /// Write a dense f32 map in bounded chunks without constructing a second copy of its payload. -pub fn write_baked(writer: &mut impl Write, layout: Layout, values: &[f32]) -> Result<(), Error> { +pub fn write_baked(writer: &mut (impl Write + ?Sized), layout: Layout, values: &[f32]) -> Result<(), Error> { let count = u64::from(layout.width).checked_mul(u64::from(layout.height)).and_then(|n| n.checked_mul(layout.components as u64)); if layout.width == 0 || layout.height == 0 || layout.components == 0 || count != Some(values.len() as u64) { return Err(Error::Invalid("map dimensions differ from its data".into())); @@ -277,7 +284,7 @@ mod tests { let mut budget = Budget::new("project", 100); assert!(read_baked(&mut Cursor::new(&bytes), 999, 1, 4, &mut budget).is_err()); let mut budget = Budget::new("project", 39); - assert!(matches!(read_baked(&mut Cursor::new(&bytes), 40, 1, 4, &mut budget), Err(Error::Limit(_)))); + assert!(matches!(read_baked(&mut Cursor::new(&bytes), 40, 1, 4, &mut budget), Err(Error::Budget(_)))); let mut extra = bytes.clone(); extra.push(0); let mut budget = Budget::new("project", 100); @@ -287,22 +294,26 @@ mod tests { #[test] fn hostile_headers_and_tiles_are_rejected_without_trusting_counts() { let layout = Layout { width: 64, height: 64, components: 1 }; + assert!(matches!( + read_tiles(&mut Cursor::new(header(layout, 0)), layout, 4095, &mut Budget::new("project", 100), |_, _, _| Ok(())), + Err(Error::Limit(_)) + )); let mut bad_magic = header(layout, 0); bad_magic[0] = b'X'; - assert!(read_tiles(&mut Cursor::new(bad_magic), layout, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); - assert!(read_tiles(&mut Cursor::new(header(layout, 2)), layout, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); + assert!(read_tiles(&mut Cursor::new(bad_magic), layout, u64::MAX, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); + assert!(read_tiles(&mut Cursor::new(header(layout, 2)), layout, u64::MAX, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); let other = Layout { width: 65, ..layout }; - assert!(read_tiles(&mut Cursor::new(header(layout, 0)), other, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); + assert!(read_tiles(&mut Cursor::new(header(layout, 0)), other, u64::MAX, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); let mut outside = header(layout, 1); outside.extend_from_slice(&1u32.to_le_bytes()); outside.extend_from_slice(&0u32.to_le_bytes()); - assert!(read_tiles(&mut Cursor::new(outside), layout, &mut Budget::new("project", 10_000), |_, _, _| Ok(())).is_err()); + assert!(read_tiles(&mut Cursor::new(outside), layout, u64::MAX, &mut Budget::new("project", 10_000), |_, _, _| Ok(())).is_err()); let mut truncated = header(layout, 1); truncated.extend_from_slice(&[0; 8]); - assert!(read_tiles(&mut Cursor::new(truncated), layout, &mut Budget::new("project", 10_000), |_, _, _| Ok(())).is_err()); + assert!(read_tiles(&mut Cursor::new(truncated), layout, u64::MAX, &mut Budget::new("project", 10_000), |_, _, _| Ok(())).is_err()); let mut extra = header(layout, 0); extra.push(1); - assert!(read_tiles(&mut Cursor::new(extra), layout, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); + assert!(read_tiles(&mut Cursor::new(extra), layout, u64::MAX, &mut Budget::new("project", 100), |_, _, _| Ok(())).is_err()); } #[test] @@ -324,7 +335,7 @@ mod tests { assert!(write_tiles(&mut Vec::new(), layout, 2, [(0, 0, first.as_slice())]).is_err()); let mut seen = Vec::new(); let mut budget = Budget::new("project", bytes.len() as u64); - read_tiles(&mut Cursor::new(&bytes), layout, &mut budget, |x, y, tile| { + read_tiles(&mut Cursor::new(&bytes), layout, u64::MAX, &mut budget, |x, y, tile| { seen.push((x, y, tile.first().copied())); Ok(()) }) @@ -333,10 +344,10 @@ mod tests { let mut duplicate = bytes.clone(); let second = HEADER_BYTES as usize + 8 + TILE_AREA * 2; duplicate[second..second + 4].copy_from_slice(&0u32.to_le_bytes()); - assert!(read_tiles(&mut Cursor::new(duplicate), layout, &mut Budget::new("project", u64::MAX), |_, _, _| Ok(())).is_err()); + assert!(read_tiles(&mut Cursor::new(duplicate), layout, u64::MAX, &mut Budget::new("project", u64::MAX), |_, _, _| Ok(())).is_err()); assert!(matches!( - read_tiles(&mut Cursor::new(bytes), layout, &mut Budget::new("project", HEADER_BYTES), |_, _, _| Ok(())), - Err(Error::Limit(_)) + read_tiles(&mut Cursor::new(bytes), layout, u64::MAX, &mut Budget::new("project", HEADER_BYTES), |_, _, _| Ok(())), + Err(Error::Budget(_)) )); } } From b85e4b150b7e427b1fd3c88b4ed9e6aba055053c Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 12:34:47 +0000 Subject: [PATCH 3/4] Add neutral project document schema --- Cargo.lock | 2 ++ crates/tcraft/Cargo.toml | 2 ++ crates/tcraft/src/lib.rs | 50 +++++++++++++++++++++++++++++++++++++++- 3 files changed, 53 insertions(+), 1 deletion(-) diff --git a/Cargo.lock b/Cargo.lock index b0f05a3b0..761575903 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2691,6 +2691,8 @@ name = "craft-tcraft" version = "0.1.0" dependencies = [ "craft-zip", + "serde", + "serde_json", "thiserror 2.0.21", ] diff --git a/crates/tcraft/Cargo.toml b/crates/tcraft/Cargo.toml index 76eeeafb0..3ce35abfb 100644 --- a/crates/tcraft/Cargo.toml +++ b/crates/tcraft/Cargo.toml @@ -12,4 +12,6 @@ workspace = true [dependencies] craft-zip = { workspace = true } +serde = { workspace = true } +serde_json = { workspace = true } thiserror = { workspace = true } diff --git a/crates/tcraft/src/lib.rs b/crates/tcraft/src/lib.rs index 4646d8717..730ef3b0c 100644 --- a/crates/tcraft/src/lib.rs +++ b/crates/tcraft/src/lib.rs @@ -6,10 +6,12 @@ //! envelope. Reads use a caller-owned budget shared with other archive entries. No reader opens //! a file or reserves memory based on a claimed payload before checking it. -use std::collections::HashSet; +use std::collections::{BTreeMap, HashSet}; use std::io::{self, Read, Write}; use craft_zip::Budget; +use serde::{Deserialize, Serialize}; +use serde_json::Value; pub const TILE_SIDE: u32 = 64; pub const TILE_AREA: usize = 64 * 64; @@ -32,6 +34,34 @@ pub enum Error { Io(#[from] io::Error), } +/// Neutral top-level project schema. Nested app-domain values and unknown fields remain JSON +/// so they round-trip without requiring TextureCraft's in-memory model. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +pub struct ProjectDocument { + pub format_version: u32, + pub name: String, + pub mesh: String, + pub normal_format: Value, + pub texture_sets: Vec, + pub layers: BTreeMap, + pub next_id: u64, + pub display: Value, + #[serde(default)] + pub cameras: Vec, + #[serde(flatten)] + pub extra: BTreeMap, +} + +/// Read only the version before an application applies its own recovery policy. Serde's +/// structured parse rejects a duplicate or invalid version field, like the project reader. +pub fn project_version(bytes: &[u8]) -> Result { + #[derive(Deserialize)] + struct Version { + format_version: u32, + } + Ok(serde_json::from_slice::(bytes)?.format_version) +} + /// Width, height and number of components expected by the enclosing project schema. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct Layout { @@ -243,6 +273,24 @@ mod tests { bytes } + #[test] + fn project_schema_keeps_nested_and_future_fields() { + let json = serde_json::json!({ + "format_version": 2, "name": "Stone", "mesh": "mesh.obj", "normal_format": "openGl", + "texture_sets": [{"name": "main", "futureSet": {"keep": true}}], + "layers": {"1": {"kind": "paint", "futureLayer": [1, 2]}}, "next_id": 2, + "display": {"futureDisplay": 4}, "mesh_file": "source.obj", "futureProject": [3] + }); + let bytes = serde_json::to_vec(&json).unwrap(); + assert_eq!(project_version(&bytes).unwrap(), 2); + let document: ProjectDocument = serde_json::from_slice(&bytes).unwrap(); + let mut expected = json; + expected["cameras"] = serde_json::json!([]); + assert_eq!(serde_json::to_value(document).unwrap(), expected); + assert!(project_version(br#"{"format_version":1,"format_version":2}"#).is_err()); + assert!(project_version(br#"{"format_version":-1}"#).is_err()); + } + #[test] fn baked_map_matches_the_native_little_endian_wire_layout() { let layout = Layout { width: 2, height: 1, components: 1 }; From d2c1cac0324491bd67f6e3b583a5dffb18bf78eb Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 13:38:46 +0000 Subject: [PATCH 4/4] Reject colliding project extension fields --- crates/tcraft/src/lib.rs | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/crates/tcraft/src/lib.rs b/crates/tcraft/src/lib.rs index 730ef3b0c..d7af3e8a6 100644 --- a/crates/tcraft/src/lib.rs +++ b/crates/tcraft/src/lib.rs @@ -36,7 +36,7 @@ pub enum Error { /// Neutral top-level project schema. Nested app-domain values and unknown fields remain JSON /// so they round-trip without requiring TextureCraft's in-memory model. -#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[derive(Clone, Debug, PartialEq, Deserialize)] pub struct ProjectDocument { pub format_version: u32, pub name: String, @@ -52,6 +52,30 @@ pub struct ProjectDocument { pub extra: BTreeMap, } +impl Serialize for ProjectDocument { + fn serialize(&self, serializer: S) -> Result { + use serde::ser::{Error as _, SerializeMap as _}; + const RESERVED: &[&str] = &["format_version", "name", "mesh", "normal_format", "texture_sets", "layers", "next_id", "display", "cameras"]; + if self.extra.keys().any(|key| RESERVED.contains(&key.as_str())) { + return Err(S::Error::custom("an extra project field duplicates a known field")); + } + let mut map = serializer.serialize_map(Some(9 + self.extra.len()))?; + map.serialize_entry("format_version", &self.format_version)?; + map.serialize_entry("name", &self.name)?; + map.serialize_entry("mesh", &self.mesh)?; + map.serialize_entry("normal_format", &self.normal_format)?; + map.serialize_entry("texture_sets", &self.texture_sets)?; + map.serialize_entry("layers", &self.layers)?; + map.serialize_entry("next_id", &self.next_id)?; + map.serialize_entry("display", &self.display)?; + map.serialize_entry("cameras", &self.cameras)?; + for (key, value) in &self.extra { + map.serialize_entry(key, value)?; + } + map.end() + } +} + /// Read only the version before an application applies its own recovery policy. Serde's /// structured parse rejects a duplicate or invalid version field, like the project reader. pub fn project_version(bytes: &[u8]) -> Result { @@ -286,7 +310,10 @@ mod tests { let document: ProjectDocument = serde_json::from_slice(&bytes).unwrap(); let mut expected = json; expected["cameras"] = serde_json::json!([]); - assert_eq!(serde_json::to_value(document).unwrap(), expected); + assert_eq!(serde_json::to_value(&document).unwrap(), expected); + let mut duplicate = document; + duplicate.extra.insert("mesh".into(), serde_json::json!("other.obj")); + assert!(serde_json::to_vec(&duplicate).is_err()); assert!(project_version(br#"{"format_version":1,"format_version":2}"#).is_err()); assert!(project_version(br#"{"format_version":-1}"#).is_err()); }