diff --git a/Cargo.lock b/Cargo.lock index c11a134ae..b35796c04 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2803,6 +2803,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..8cde65513 --- /dev/null +++ b/crates/xfl/src/document.rs @@ -0,0 +1,524 @@ +//! 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, Local, Options, Pat, UnknownEntity}; +use std::borrow::Cow; + +/// 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>, +} + +/// The script-language version and document class selected by an XFL `PublishSettings.xml`. +/// Values stay in their native string form so each consumer can apply its own domain rules. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct PublishSettings<'a> { + pub action_script_version: Option>, + pub document_class: Option>, +} + +/// 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") +} + +fn trimmed_text<'a>(element: &'a El) -> Option> { + match element.text() { + Cow::Borrowed(text) => { + let trimmed = text.trim(); + (!trimmed.is_empty()).then_some(Cow::Borrowed(trimmed)) + } + Cow::Owned(text) => { + let trimmed = text.trim(); + (!trimmed.is_empty()).then(|| Cow::Owned(trimmed.to_string())) + } + } +} + +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 + } + + /// Reads the current publish profile, falling back to the first profile and then the root. + /// This is also used for `PublishSettings.xml` files, whose schema is separate from the main + /// `DOMDocument` tree. + pub fn publish_settings(&self) -> PublishSettings<'_> { + let profile = self + .root + .elements() + .find(|element| Local("flash_profile").matches(&element.name) && boolean(element, "current") == Some(true)) + .or_else(|| self.root.elements().find(|element| Local("flash_profile").matches(&element.name))) + .unwrap_or(&self.root); + let properties = profile.child(Local("PublishFlashProperties")).unwrap_or(profile); + let value = |name: &str| properties.child(Local(name)).and_then(trimmed_text); + PublishSettings { action_script_version: value("ActionScriptVersion"), document_class: value("DocumentClass") } + } + + /// 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(Local("timelines")) + .into_iter() + .flat_map(El::elements) + .filter(|element| Local("DOMTimeline").matches(&element.name)) + .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(Local("timeline"))?.child(Local("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(Local("layers")) + .into_iter() + .flat_map(El::elements) + .filter(|element| Local("DOMLayer").matches(&element.name)) + .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(Local("frames")) + .into_iter() + .flat_map(El::elements) + .filter(|element| Local("DOMFrame").matches(&element.name)) + .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)); + } + + #[test] + fn recognizes_prefixed_xfl_timeline_elements_by_local_name() { + let document = Document::parse( + b"", + ) + .unwrap(); + { + let mut timelines = document.timelines(); + let timeline = timelines.next().unwrap(); + assert!(timelines.next().is_none()); + let mut layers = timeline.layers(); + let layer = layers.next().unwrap(); + assert!(layers.next().is_none()); + let frame = layer.frames().next().unwrap(); + assert_eq!((frame.index(), frame.duration()), (Some(4), Some(2))); + } + let (model, _) = document.into_parts(ModelLimits { max_timelines: 1, max_layers_per_timeline: 1 }); + assert_eq!(model.timelines[0].layers[0].frames[0].index, Some(4)); + + let symbol = + Document::parse(b"").unwrap(); + assert!(symbol.symbol_timeline().is_some()); + } + + #[test] + fn reads_prefixed_publish_settings_children_by_local_name() { + let document = Document::parse( + b"3com.example.Main", + ) + .unwrap(); + let settings = document.publish_settings(); + assert_eq!(settings.action_script_version.as_deref(), Some("3")); + assert_eq!(settings.document_class.as_deref(), Some("com.example.Main")); + } + + #[test] + fn selects_current_publish_profile_and_uses_native_value_strings() { + let document = Document::parse( + br#"2OldClass 3 com.example.Main "#, + ) + .unwrap(); + let settings = document.publish_settings(); + assert_eq!(settings.action_script_version.as_deref(), Some("3")); + assert_eq!(settings.document_class.as_deref(), Some("com.example.Main")); + } + + #[test] + fn publish_settings_fall_back_to_first_profile_then_root() { + let first = Document::parse( + br#"23"#, + ) + .unwrap(); + assert_eq!(first.publish_settings().action_script_version.as_deref(), Some("2")); + + let root = Document::parse( + br#" 3 RootClass"#, + ) + .unwrap(); + let settings = root.publish_settings(); + assert_eq!(settings.action_script_version.as_deref(), Some("3")); + assert_eq!(settings.document_class.as_deref(), Some("RootClass")); + } +} diff --git a/crates/xfl/src/lib.rs b/crates/xfl/src/lib.rs index 83fdad40b..4a957111f 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; @@ -87,6 +89,19 @@ pub struct Archive<'a> { budget: Cell, } +/// The package root selected from an XFL archive's `DOMDocument.xml` paths. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum XflPackageRoot<'a> { + /// A document XML file is directly at the archive root. + Document, + /// The sole eligible top-level folder containing a document. + Folder(&'a str), + /// No document path was found. + Missing, + /// More than one eligible top-level folder contains a document, sorted by name. + Multiple(Vec<&'a str>), +} + const END: u32 = 0x0605_4b50; const END64: u32 = 0x0606_4b50; const LOCATOR64: u32 = 0x0706_4b50; @@ -527,6 +542,25 @@ impl<'a> Archive<'a> { self.entries.keys().map(String::as_str) } + /// Selects the package root from XFL document paths. A root-level document takes precedence; + /// otherwise only a single-level folder is eligible, with macOS metadata excluded. + pub fn xfl_package_root(&self) -> XflPackageRoot<'_> { + if self.entries.contains_key("DOMDocument.xml") { + return XflPackageRoot::Document; + } + let mut folders: Vec<&str> = self + .names() + .filter_map(|name| name.strip_suffix("/DOMDocument.xml")) + .filter(|folder| !folder.contains('/') && *folder != "__MACOSX") + .collect(); + folders.sort_unstable(); + match folders.as_slice() { + [] => XflPackageRoot::Missing, + [folder] => XflPackageRoot::Folder(folder), + _ => XflPackageRoot::Multiple(folders), + } + } + /// How many files and folder entries the archive lists. pub fn counts(&self) -> (usize, usize) { (self.entries.len(), self.folders) diff --git a/crates/xfl/src/tests.rs b/crates/xfl/src/tests.rs index ee4b2cf33..5ae0713ba 100644 --- a/crates/xfl/src/tests.rs +++ b/crates/xfl/src/tests.rs @@ -28,6 +28,32 @@ fn reads_stored_and_deflated_entries() { assert_eq!(a.read("missing").unwrap(), None); } +#[test] +fn xfl_package_root_prefers_root_then_selects_one_top_level_folder() { + let root = zip(&[("DOMDocument.xml", b"", true), ("Walk/DOMDocument.xml", b"", true)]); + let archive = Archive::open(&root).unwrap(); + assert_eq!(archive.xfl_package_root(), XflPackageRoot::Document); + + let folder = zip(&[("Walk/DOMDocument.xml", b"", true), ("Walk/LIBRARY/Clip.xml", b"", true)]); + let archive = Archive::open(&folder).unwrap(); + assert_eq!(archive.xfl_package_root(), XflPackageRoot::Folder("Walk")); +} + +#[test] +fn xfl_package_root_reports_sorted_candidates_and_ignores_metadata_and_nested_paths() { + let multiple = zip(&[ + ("Zebra/DOMDocument.xml", b"", true), + ("Apple/DOMDocument.xml", b"", true), + ("__MACOSX/DOMDocument.xml", b"not a project", true), + ]); + let archive = Archive::open(&multiple).unwrap(); + assert_eq!(archive.xfl_package_root(), XflPackageRoot::Multiple(vec!["Apple", "Zebra"])); + + let nested = zip(&[("One/Two/DOMDocument.xml", b"", true), ("__MACOSX/One/DOMDocument.xml", b"metadata", true)]); + let archive = Archive::open(&nested).unwrap(); + assert_eq!(archive.xfl_package_root(), XflPackageRoot::Missing); +} + #[test] fn the_checksum_matches_the_published_check_value() { assert_eq!(crc32(b"123456789"), 0xCBF4_3926);