diff --git a/Cargo.lock b/Cargo.lock index 3d8cf4a7b..651fdf49b 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2799,6 +2799,7 @@ dependencies = [ name = "craft-xfl" version = "0.1.0" dependencies = [ + "craft-xml", "miniz_oxide 0.8.9", "thiserror 2.0.21", ] diff --git a/crates/xfl/Cargo.toml b/crates/xfl/Cargo.toml index ddf2b3a36..9c8a40e3c 100644 --- a/crates/xfl/Cargo.toml +++ b/crates/xfl/Cargo.toml @@ -11,5 +11,6 @@ repository.workspace = true workspace = true [dependencies] +craft-xml = { workspace = true } miniz_oxide = "0.8" thiserror = { workspace = true } diff --git a/crates/xfl/src/document.rs b/crates/xfl/src/document.rs new file mode 100644 index 000000000..f3f3194d8 --- /dev/null +++ b/crates/xfl/src/document.rs @@ -0,0 +1,414 @@ +//! Neutral views of the native XFL document schema. +//! +//! This layer recognizes the document, stage, scene, layer and keyframe fields defined by XFL. +//! It does not construct a consumer's animation model. More detailed payloads remain available +//! through [`Document::root`] for the application adapter. +use craft_xml::{Doctype, El, Error as XmlError, Limits, Options, UnknownEntity}; + +/// Maximum bytes of XML in one XFL document or library item. +pub const MAX_XML_BYTES: usize = 256 * 1024 * 1024; +/// Maximum depth accepted by AniCraft's existing XFL XML adapter (root depth is one). +pub const MAX_XML_DEPTH: usize = 257; +/// Maximum XFL document elements accepted by the existing adapter. +pub const MAX_XML_ELEMENTS: usize = 4_000_000; + +/// An XFL `DOMDocument.xml` tree plus typed, zero-copy views over its native structure. +#[derive(Clone, Debug)] +pub struct Document { + root: El, +} + +/// Stage metadata stored on the root `DOMDocument` element. +#[derive(Clone, Copy, Debug)] +pub struct Stage<'a> { + pub width: Option, + pub height: Option, + pub frame_rate: Option, + pub background_color: Option<&'a str>, +} + +/// Bounds used when projecting native schema fields into a compact model. +#[derive(Clone, Copy, Debug)] +pub struct ModelLimits { + pub max_timelines: usize, + pub max_layers_per_timeline: usize, +} + +/// Compact XFL metadata that does not retain or duplicate the parsed XML tree. +#[derive(Clone, Debug, PartialEq)] +pub struct DocumentModel { + pub stage: StageModel, + pub timelines: Vec, + /// Present for a library `DOMSymbolItem`; absent for normal `DOMDocument` files. + pub symbol_timeline: Option, +} + +#[derive(Clone, Copy, Debug, Default, PartialEq)] +pub struct StageModel { + pub width: Option, + pub height: Option, + pub frame_rate: Option, + pub has_background_color: bool, +} + +#[derive(Clone, Debug, Default, PartialEq)] +pub struct TimelineModel { + pub layers: Vec, +} + +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum LayerType { + #[default] + Normal, + Folder, + Guide, + Mask, + Other, +} + +#[derive(Clone, Debug, Default, PartialEq)] +pub struct LayerModel { + pub layer_type: LayerType, + pub parent_layer_index: Option, + pub visible: Option, + pub locked: Option, + pub outline: Option, + pub height_multiplier: Option, + pub frames: Vec, +} + +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum TweenType { + Motion, + Shape, + MotionObject, + #[default] + Other, +} + +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct FrameModel { + pub index: Option, + pub duration: Option, + pub is_comment: bool, + pub tween_type: TweenType, +} + +/// A timeline (`DOMTimeline`) listed under `DOMDocument/timelines`. +#[derive(Clone, Copy, Debug)] +pub struct Timeline<'a> { + element: &'a El, +} + +/// A native `DOMLayer` element. +#[derive(Clone, Copy, Debug)] +pub struct Layer<'a> { + element: &'a El, +} + +/// A native `DOMFrame` element. +#[derive(Clone, Copy, Debug)] +pub struct Frame<'a> { + element: &'a El, +} + +fn attr_last<'a>(element: &'a El, name: &str) -> Option<&'a str> { + element.attrs.iter().rev().find(|(key, _)| key == name).map(|(_, value)| value.as_str()) +} + +fn number_f32(element: &El, name: &str) -> Option { + attr_last(element, name).and_then(|value| value.trim().parse::().ok()).filter(|value| value.is_finite()) +} + +fn number_u32(element: &El, name: &str) -> Option { + attr_last(element, name).and_then(|value| value.trim().parse::().ok()) +} + +fn boolean(element: &El, name: &str) -> Option { + attr_last(element, name).map(|value| value.trim() == "true") +} + +impl Document { + /// Parse XFL XML with AniCraft's existing size, depth, element, attribute, entity, doctype + /// and malformed-end-tag behavior. The shared XML parser owns byte parsing; this crate owns + /// the XFL-specific limits and schema views. + pub fn parse(bytes: &[u8]) -> Result { + let defaults = Limits::DEFAULT; + let limits = Limits { + max_input: MAX_XML_BYTES, + max_depth: MAX_XML_DEPTH, + max_nodes: MAX_XML_ELEMENTS.saturating_mul(2).saturating_add(1), + max_elements: MAX_XML_ELEMENTS, + max_attrs: defaults.max_attrs, + max_attrs_total: defaults.max_attrs_total, + }; + let options = + Options { limits, strict_end_tags: true, unknown_entity: UnknownEntity::Literal, doctype: Doctype::Ignore, ..Options::default() }; + Ok(Self { root: options.parse(bytes)? }) + } + + /// The lossless XML tree used by consumer adapters for schema details this view does not + /// interpret. Text and child order come directly from `craft-xml`. + pub fn root(&self) -> &El { + &self.root + } + + /// The root's local element name (normally `DOMDocument`). + pub fn root_name(&self) -> &str { + &self.root.name + } + + /// The XFL stage metadata, applying finite-number checks but leaving product defaults and + /// clamping to the consumer. + pub fn stage(&self) -> Stage<'_> { + Stage { + width: number_f32(&self.root, "width"), + height: number_f32(&self.root, "height"), + frame_rate: number_f32(&self.root, "frameRate"), + background_color: attr_last(&self.root, "backgroundColor"), + } + } + + /// Timelines in document order. Non-`DOMTimeline` extension nodes are skipped. + pub fn timelines(&self) -> impl Iterator> { + self.root + .child("timelines") + .into_iter() + .flat_map(El::elements) + .filter(|element| element.name == "DOMTimeline") + .map(|element| Timeline { element }) + } + + /// The timeline nested under `DOMSymbolItem/timeline`, if this is library symbol XML. + pub fn symbol_timeline(&self) -> Option> { + self.root.child("timeline")?.child("DOMTimeline").map(|element| Timeline { element }) + } + + /// Projects bounded schema metadata and returns the XML tree by ownership. Consumers can + /// convert that tree into their compatibility representation without keeping two full trees + /// alive during import. + pub fn into_parts(self, limits: ModelLimits) -> (DocumentModel, El) { + let stage = StageModel { + width: number_f32(&self.root, "width"), + height: number_f32(&self.root, "height"), + frame_rate: number_f32(&self.root, "frameRate"), + has_background_color: attr_last(&self.root, "backgroundColor").is_some(), + }; + let timelines = self.timelines().take(limits.max_timelines).map(|timeline| timeline.into_model(limits.max_layers_per_timeline)).collect(); + let symbol_timeline = self.symbol_timeline().map(|timeline| timeline.into_model(limits.max_layers_per_timeline)); + (DocumentModel { stage, timelines, symbol_timeline }, self.root) + } +} + +impl<'a> Timeline<'a> { + pub fn name(self) -> Option<&'a str> { + attr_last(self.element, "name") + } + + /// Raw timeline XML for application-specific payload conversion. + pub fn element(self) -> &'a El { + self.element + } + + /// Layers in native order. Non-`DOMLayer` extension nodes are skipped. + pub fn layers(self) -> impl Iterator> { + self.element.child("layers").into_iter().flat_map(El::elements).filter(|element| element.name == "DOMLayer").map(|element| Layer { element }) + } + + fn into_model(self, max_layers: usize) -> TimelineModel { + TimelineModel { layers: self.layers().take(max_layers).map(Layer::into_model).collect() } + } +} + +impl<'a> Layer<'a> { + pub fn name(self) -> Option<&'a str> { + attr_last(self.element, "name") + } + + pub fn layer_type(self) -> Option<&'a str> { + attr_last(self.element, "layerType") + } + + pub fn parent_layer_index(self) -> Option { + number_u32(self.element, "parentLayerIndex") + } + + pub fn visible(self) -> Option { + boolean(self.element, "visible") + } + + pub fn locked(self) -> Option { + boolean(self.element, "locked") + } + + pub fn outline(self) -> Option { + boolean(self.element, "outline") + } + + pub fn color(self) -> Option<&'a str> { + attr_last(self.element, "color") + } + + pub fn height_multiplier(self) -> Option { + number_u32(self.element, "heightMultiplier") + } + + /// Frames in native order. Non-`DOMFrame` extension nodes are skipped. + pub fn frames(self) -> impl Iterator> { + self.element.child("frames").into_iter().flat_map(El::elements).filter(|element| element.name == "DOMFrame").map(|element| Frame { element }) + } + + fn into_model(self) -> LayerModel { + let layer_type = match attr_last(self.element, "layerType") { + Some("folder") => LayerType::Folder, + Some("guide") => LayerType::Guide, + Some("mask") => LayerType::Mask, + Some("normal") | None => LayerType::Normal, + Some(_) => LayerType::Other, + }; + LayerModel { + layer_type, + parent_layer_index: number_u32(self.element, "parentLayerIndex"), + visible: boolean(self.element, "visible"), + locked: boolean(self.element, "locked"), + outline: boolean(self.element, "outline"), + height_multiplier: number_u32(self.element, "heightMultiplier"), + frames: self.frames().map(Frame::into_model).collect(), + } + } +} + +impl<'a> Frame<'a> { + pub fn index(self) -> Option { + number_u32(self.element, "index") + } + + pub fn duration(self) -> Option { + number_u32(self.element, "duration") + } + + pub fn label_type(self) -> Option<&'a str> { + attr_last(self.element, "labelType") + } + + pub fn name(self) -> Option<&'a str> { + attr_last(self.element, "name") + } + + pub fn tween_type(self) -> Option<&'a str> { + attr_last(self.element, "tweenType") + } + + /// Raw frame XML for application-specific shape, action, sound and tween conversion. + pub fn element(self) -> &'a El { + self.element + } + + fn into_model(self) -> FrameModel { + let tween_type = match attr_last(self.element, "tweenType") { + Some("motion") => TweenType::Motion, + Some("shape") => TweenType::Shape, + Some("motion object") => TweenType::MotionObject, + _ => TweenType::Other, + }; + FrameModel { + index: number_u32(self.element, "index"), + duration: number_u32(self.element, "duration"), + is_comment: attr_last(self.element, "labelType").is_some_and(|value| value.trim() == "comment"), + tween_type, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reads_stage_scene_layer_and_frame_schema_without_building_an_app_model() { + let bytes = br##"]> + + + + + + + + + + +"##; + let document = Document::parse(bytes).unwrap(); + assert_eq!(document.root_name(), "DOMDocument"); + let stage = document.stage(); + assert_eq!((stage.width, stage.height, stage.frame_rate), (Some(640.0), Some(480.0), Some(29.97))); + assert_eq!(stage.background_color, Some("#123456")); + let mut timelines = document.timelines(); + let timeline = timelines.next().unwrap(); + assert_eq!(timeline.name(), Some("Scene &custom;"), "declared entities stay literal"); + assert!(timelines.next().is_none()); + let mut layers = timeline.layers(); + let layer = layers.next().unwrap(); + assert_eq!(layer.name(), Some("Background")); + assert_eq!(layer.layer_type(), Some("normal")); + assert_eq!(layer.parent_layer_index(), Some(0)); + assert_eq!((layer.visible(), layer.locked(), layer.outline()), (Some(false), Some(true), Some(true))); + assert_eq!(layer.color(), Some("#abcdef")); + assert_eq!(layer.height_multiplier(), Some(2)); + let frame = layer.frames().next().unwrap(); + assert_eq!((frame.index(), frame.duration()), (Some(4), Some(3))); + assert_eq!((frame.name(), frame.label_type(), frame.tween_type()), (Some("Intro"), Some("name"), Some("motion"))); + assert_eq!(frame.element().child("elements").unwrap().child("Shape").unwrap().name, "Shape"); + } + + #[test] + fn uses_last_duplicate_attribute_like_the_legacy_xfl_adapter() { + let document = Document::parse(br##""##).unwrap(); + assert_eq!(document.stage().width, Some(2.0)); + } + + #[test] + fn preserves_lenient_doctype_entities_and_strict_end_tag_behavior() { + let document = Document::parse(br##"tail"##).unwrap(); + assert_eq!(document.stage().width, None); + assert!(Document::parse(b"").is_err()); + } + + #[test] + fn applies_the_existing_xfl_depth_and_attribute_budgets() { + let too_deep = format!("{}{}", "".repeat(MAX_XML_DEPTH + 1), "".repeat(MAX_XML_DEPTH + 1)); + assert!(matches!(Document::parse(too_deep.as_bytes()), Err(XmlError::TooDeep(_)))); + + let mut too_many_attrs = String::from(""); + assert!(matches!(Document::parse(too_many_attrs.as_bytes()), Err(XmlError::TooManyAttrs(_)))); + } + + #[test] + fn projects_neutral_schema_fields_and_returns_the_xml_tree_by_move() { + let document = Document::parse( + br##""##, + ) + .unwrap(); + let (model, root) = document.into_parts(ModelLimits { max_timelines: 1, max_layers_per_timeline: 1 }); + assert_eq!(model.stage, StageModel { width: Some(640.0), height: None, frame_rate: None, has_background_color: true }); + assert_eq!(model.timelines.len(), 1); + let layer = &model.timelines[0].layers[0]; + assert_eq!(layer.layer_type, LayerType::Mask); + assert_eq!(layer.visible, Some(false)); + assert_eq!(layer.frames[0], FrameModel { index: Some(7), duration: Some(2), is_comment: true, tween_type: TweenType::Shape }); + assert_eq!(root.attr("width"), Some("640")); + assert_eq!(root.child("timelines").unwrap().child("DOMTimeline").unwrap().attr("name"), Some("Scene")); + } + + #[test] + fn projects_symbol_timeline_under_the_native_symbol_wrapper() { + let document = Document::parse(b"").unwrap(); + let (model, _) = document.into_parts(ModelLimits { max_timelines: 10, max_layers_per_timeline: 10 }); + assert!(model.timelines.is_empty()); + assert_eq!(model.symbol_timeline.unwrap().layers[0].frames[0].index, Some(1)); + } +} diff --git a/crates/xfl/src/lib.rs b/crates/xfl/src/lib.rs index 83fdad40b..9fce43eac 100644 --- a/crates/xfl/src/lib.rs +++ b/crates/xfl/src/lib.rs @@ -23,6 +23,8 @@ use std::cell::Cell; use std::collections::HashMap; +/// Neutral views of the XFL document, timeline, layer and frame schema. +pub mod document; /// XFL's edge-attribute grammar, independent of any consuming application's geometry types. pub mod edges;