From 0591db34387c7ee7e79845637cc0ca64d59a88b7 Mon Sep 17 00:00:00 2001 From: Vigneswaran Rajkumar <118706051+IAmVigneswaran@users.noreply.github.com> Date: Thu, 6 Aug 2026 20:36:10 +0800 Subject: [PATCH] Notion JSON column order + ShotExtractionTest (3.3.4) Emit Notion Shot Extraction JSON keys in CSV column order and add optional ShotExtractionTest integration (suite 1173). Sync docs and agent guides. --- .cursorrules | 10 +- .gitignore | 9 + AGENT.md | 14 +- ARCHITECTURE.md | 24 +- CHANGELOG.md | 18 ++ Documentation/Coverage.md | 8 +- Documentation/Manual.md | 4 +- Documentation/Manual/00-Index.md | 4 +- Documentation/Manual/01-Overview.md | 3 +- Documentation/Manual/17-Cross-Platform-iOS.md | 4 +- Documentation/Manual/19-CLI.md | 2 +- Documentation/Manual/20-Reporting.md | 2 +- Documentation/Manual/21-Shot-Extraction.md | 5 +- Documentation/Manual/22-Examples.md | 4 +- Documentation/README.md | 6 +- GUARDRAILS.md | 10 +- Package.swift | 12 +- README.md | 21 +- .../FCPXMLShotManifestExporter.swift | 50 +++- .../FCPXMLShotManifestSchema.swift | 5 +- Sources/OpenFCPXMLKitCLI/README.md | 2 +- Tests/ExcelReportTest/Output/README.md | 2 +- Tests/ExcelReportTest/README.md | 2 +- .../FCPXMLShotExtractionTests.swift | 25 +- Tests/README.md | 35 ++- Tests/ShotExtractionTest/Output/.gitkeep | 0 Tests/ShotExtractionTest/Output/README.md | 35 +++ Tests/ShotExtractionTest/README.md | 135 +++++++++++ .../ShotExtractionExportTests.swift | 199 ++++++++++++++++ .../ShotExtractionFixture.swift | 216 ++++++++++++++++++ Tests/Submitted FCPXML/README.md | 2 +- 31 files changed, 797 insertions(+), 71 deletions(-) create mode 100644 Tests/ShotExtractionTest/Output/.gitkeep create mode 100644 Tests/ShotExtractionTest/Output/README.md create mode 100644 Tests/ShotExtractionTest/README.md create mode 100644 Tests/ShotExtractionTest/ShotExtractionExportTests.swift create mode 100644 Tests/ShotExtractionTest/ShotExtractionFixture.swift diff --git a/.cursorrules b/.cursorrules index 53a459b..b2c611e 100644 --- a/.cursorrules +++ b/.cursorrules @@ -42,7 +42,7 @@ OpenFCPXMLKit targets macOS 26+, iOS 26+, Xcode 26+, and Swift 6.3 with full con **Backward compatibility:** The entire codebase must remain backward compatible with FCPXML 1.5. Optional attributes and elements introduced in later versions (e.g. 1.11, 1.13) must be omitted or ignored when reading/writing or converting to 1.5; mark such features in code comments with the minimum FCPXML version (e.g. `FCPXML 1.13+`). -Current status: **1169** tests listed in `swift test list` (**1161** in `OpenFCPXMLKitTests` + **8** optional `ExcelReportTest`; all Swift Testing `@Test`); FCPXML versions 1.5–1.14 supported (DTDs included, full parsing, typed element-type coverage for all DTD elements via FCPXMLElementType); Final Cut Pro frame rates (23.976, 24, 25, 29.97, 30, 50, 59.94, 60); thread-safe and concurrency-compliant with comprehensive async/await support; no known security vulnerabilities. Version conversion automatically drops elements not in the target version’s DTD (e.g. adjust-colorConform, adjust-stereo-3D); DTD validation runs per version (validateDocumentAgainstDTD, validateDocumentAgainstDeclaredVersion) and after CLI convert. FCPXMLVersion.supportsBundleFormat is true for 1.10+ (.fcpxmld bundle); 1.5–1.9 support only single-file .fcpxml. FCPXML creation: create FCPXML documents from scratch with events, projects, resources, and clips via XMLDocumentManager, XMLDocument initializers, or FCPXMLService. Timeline manipulation: ripple insert (shifts subsequent clips), auto lane assignment, clip queries (by lane, time range, asset ID), lane range computation, secondary storylines. Timeline metadata: markers, chapter markers, keywords, ratings, custom metadata, timestamps (createdAt, modifiedAt). FCPXMLTimecode: custom timecode type (arithmetic, frame alignment, CMTime conversion, FCPXML string parsing). MIME type detection, asset validation, silence detection, asset duration measurement, parallel file I/O, still image asset support. TimelineFormat enhancements: presets (hd720p, dci4K, hd1080i, hd720i), computed properties (aspectRatio, isHD, isUHD, interlaced). Typed adjustment models: Crop, Corners, Transform, Blend, Stabilization, Volume, Panner, Loudness, NoiseReduction, HumReduction, Equalization, MatchEqualization, Transform360, ColorConform, Stereo3D, VoiceIsolation with full clip integration. Typed effect/filter models: VideoFilter, AudioFilter, VideoFilterMask with FilterParameter support and keyframe animation (auxValue support FCPXML 1.11+). Typed caption/title models: Caption and Title with TextStyle and TextStyleDefinition for full text formatting. SmartCollection models: SmartCollection with match-clip, match-media, match-ratings, match-text, match-usage (1.9+), match-representation (1.10+), match-markers (1.10+), match-analysis-type (1.14). Keyframe animation: KeyframeAnimation, Keyframe with interpolation types, FadeIn/FadeOut with fade types, integrated with FilterParameter. CMTime Codable extension: Direct CMTime encoding/decoding as FCPXML time strings. Collection organization: CollectionFolder and KeywordCollection models for organizing clips and media. Live Drawing (FCPXML 1.11+): LiveDrawing model for live-drawing story elements. HiddenClipMarker (FCPXML 1.13+): HiddenClipMarker model for hidden clip markers. Format/Asset 1.13+: Format heroEye, Asset heroEyeOverride, Asset mediaReps (multiple media-rep). Cross-platform XML abstraction: protocol layer (OFKXMLNode, OFKXMLElement, OFKXMLDocument, OFKXMLFactory); Foundation backend on macOS; AEXML backend on iOS; OFKXMLDefaultFactory() for platform dispatch; FCPXMLStructuralValidator for cross-platform structural validation; FCPXMLDTDValidator platform-conditional (full DTD on macOS, structural fallback on iOS). Comprehensive test coverage: **1161** tests across 60 FCPXML sample files including 360 video, auditions, conform-rate, still images, multicam, secondary storylines, audio keyframes (FCPXMLAudioKeyframeTests: adjust-volume param keyframeAnimation parsing, decibel/time validation, fadeIn/fadeOut integration, secondary storyline detection), keyword collections/folders, Photoshop integration, smart collections, and reporting column layout/exclusion/disabled-clip/workbook/PDF formatting tests. Shot Extraction: primary-timeline still-image shots → PNG + CSV or [csv2notion-neo](https://github.com/TheAcharya/csv2notion-neo)-compatible Notion JSON (`ShotExtractor` / `extractShots(options:)` / `planShots(options:)` dry-run; CLI `--extract-shots` with `--dry-run`, `--scene-number`, `--extract-format`, `--folder-format`, optional `--icon` / **Icon Image**); rejects primary video, titles/generators, and audio; independent of Reporting. Excel and PDF reporting: multi-sheet `.xlsx` workbooks via `FinalCutPro.FCPXML.buildReport(options:)` (ReportBuilder, ReportOptions presets, ReportExcelExport on XLKit) and optional `.pdf` via `ReportPDFExport` (CoreGraphics; cover page with black “About This PDF Export” + `info.circle`, TOC with accent colour chips + content-tint washes, per-sheet tints, column-width expansion after exclusions, section pagination; same Report configuration as Excel); sheets for Role Inventory (**Selected Roles Inventory** + per-role sheets with **26** fixed columns including Duplicate Frames / Frame Size / Audio Config / Codecs / Ingest Date + dynamic metadata keys; per-role **Total:** footers), Markers, Keywords, Titles & Generators, Transitions, **Non-Std Effects & Templates**, Video & Audio Effects, Speed Change Effects, **Summary** (project title in **B1**, narrow Row column A, black role-duration data), and **Media Summary** (Row + red missing-media paths); enabled empty sheets keep headers + `ReportEmptySectionStatus` / **No Missing Media**; 1-based **Row** on tabular Excel/PDF sheets by default (`ensuringRowColumn` / `allowsInjectedRowColumn`); inventory and section-sheet cell formatting, role exclusions, global column exclusion (`ReportColumn` / `excludedColumns`, including `ReportColumn.row`), disabled-clip filtering (`excludeDisabledClips`), project-name / compound-clip-name filtering (`allReportTimelineSources()`; standalone compound-clip exports without ``), `ReportTimecodeFormat` / `--timecode-format`, inventory-first `ReportBuildPhase` progress callbacks; optional `copyrightLabel` / CLI `--label-copyright` (Excel cover **A2**; PDF cover + footer centre); `includeChapterMarkersInMarkersReport` defaults **true** (Type = Chapter; no CLI chapter flag); `includeMarkersOutsideClipBoundaries` / Markers **Hidden** column. Extraction presets: Captions, Effects, FrameData, Markers, Roles, Titles. Experimental CLI (OpenFCPXMLKit-CLI): single binary with embedded DTDs; --check-version, --convert-version (stripping + DTD validation), --extension-type (fcpxmld | fcpxml; default fcpxmld; 1.5–1.9 always .fcpxml), --validate, --media-copy, --extract-shots (--dry-run), --create-project (new empty FCPXML project: --width, --height, --rate, --project-version, output-dir; DTD validation before write; FCP-style output with DOCTYPE, colorSpace, default smart collections), --report (Excel report: role inventory by default; --report-full, per-section flags including --report-markers, --report-keywords, --report-titles-generators, --report-transitions, --report-non-standard-effects, --report-effects, --report-speed-change-effects, --report-summary, --report-media-summary, --media-resolution, --media-summary-distinguish-proxy, --exclude-role, --exclude-column, --exclude-disabled-clips, --include-markers-outside-clip-boundaries, --protect-sheets, --timecode-format, --report-project, --label-copyright, --create-pdf); --log writes user-visible output for all commands to the log file; see Sources/OpenFCPXMLKitCLI/README.md. +Current status: **1173** tests listed in `swift test list` (**1161** in `OpenFCPXMLKitTests` + **8** optional `ExcelReportTest` + **4** optional `ShotExtractionTest`; all Swift Testing `@Test`); FCPXML versions 1.5–1.14 supported (DTDs included, full parsing, typed element-type coverage for all DTD elements via FCPXMLElementType); Final Cut Pro frame rates (23.976, 24, 25, 29.97, 30, 50, 59.94, 60); thread-safe and concurrency-compliant with comprehensive async/await support; no known security vulnerabilities. Version conversion automatically drops elements not in the target version’s DTD (e.g. adjust-colorConform, adjust-stereo-3D); DTD validation runs per version (validateDocumentAgainstDTD, validateDocumentAgainstDeclaredVersion) and after CLI convert. FCPXMLVersion.supportsBundleFormat is true for 1.10+ (.fcpxmld bundle); 1.5–1.9 support only single-file .fcpxml. FCPXML creation: create FCPXML documents from scratch with events, projects, resources, and clips via XMLDocumentManager, XMLDocument initializers, or FCPXMLService. Timeline manipulation: ripple insert (shifts subsequent clips), auto lane assignment, clip queries (by lane, time range, asset ID), lane range computation, secondary storylines. Timeline metadata: markers, chapter markers, keywords, ratings, custom metadata, timestamps (createdAt, modifiedAt). FCPXMLTimecode: custom timecode type (arithmetic, frame alignment, CMTime conversion, FCPXML string parsing). MIME type detection, asset validation, silence detection, asset duration measurement, parallel file I/O, still image asset support. TimelineFormat enhancements: presets (hd720p, dci4K, hd1080i, hd720i), computed properties (aspectRatio, isHD, isUHD, interlaced). Typed adjustment models: Crop, Corners, Transform, Blend, Stabilization, Volume, Panner, Loudness, NoiseReduction, HumReduction, Equalization, MatchEqualization, Transform360, ColorConform, Stereo3D, VoiceIsolation with full clip integration. Typed effect/filter models: VideoFilter, AudioFilter, VideoFilterMask with FilterParameter support and keyframe animation (auxValue support FCPXML 1.11+). Typed caption/title models: Caption and Title with TextStyle and TextStyleDefinition for full text formatting. SmartCollection models: SmartCollection with match-clip, match-media, match-ratings, match-text, match-usage (1.9+), match-representation (1.10+), match-markers (1.10+), match-analysis-type (1.14). Keyframe animation: KeyframeAnimation, Keyframe with interpolation types, FadeIn/FadeOut with fade types, integrated with FilterParameter. CMTime Codable extension: Direct CMTime encoding/decoding as FCPXML time strings. Collection organization: CollectionFolder and KeywordCollection models for organizing clips and media. Live Drawing (FCPXML 1.11+): LiveDrawing model for live-drawing story elements. HiddenClipMarker (FCPXML 1.13+): HiddenClipMarker model for hidden clip markers. Format/Asset 1.13+: Format heroEye, Asset heroEyeOverride, Asset mediaReps (multiple media-rep). Cross-platform XML abstraction: protocol layer (OFKXMLNode, OFKXMLElement, OFKXMLDocument, OFKXMLFactory); Foundation backend on macOS; AEXML backend on iOS; OFKXMLDefaultFactory() for platform dispatch; FCPXMLStructuralValidator for cross-platform structural validation; FCPXMLDTDValidator platform-conditional (full DTD on macOS, structural fallback on iOS). Comprehensive test coverage: **1161** tests across 60 FCPXML sample files including 360 video, auditions, conform-rate, still images, multicam, secondary storylines, audio keyframes (FCPXMLAudioKeyframeTests: adjust-volume param keyframeAnimation parsing, decibel/time validation, fadeIn/fadeOut integration, secondary storyline detection), keyword collections/folders, Photoshop integration, smart collections, and reporting column layout/exclusion/disabled-clip/workbook/PDF formatting tests. Shot Extraction: primary-timeline still-image shots → PNG + CSV or [csv2notion-neo](https://github.com/TheAcharya/csv2notion-neo)-compatible Notion JSON (`ShotExtractor` / `extractShots(options:)` / `planShots(options:)` dry-run; CLI `--extract-shots` with `--dry-run`, `--scene-number`, `--extract-format`, `--folder-format`, optional `--icon` / **Icon Image**); rejects primary video, titles/generators, and audio; independent of Reporting. Excel and PDF reporting: multi-sheet `.xlsx` workbooks via `FinalCutPro.FCPXML.buildReport(options:)` (ReportBuilder, ReportOptions presets, ReportExcelExport on XLKit) and optional `.pdf` via `ReportPDFExport` (CoreGraphics; cover page with black “About This PDF Export” + `info.circle`, TOC with accent colour chips + content-tint washes, per-sheet tints, column-width expansion after exclusions, section pagination; same Report configuration as Excel); sheets for Role Inventory (**Selected Roles Inventory** + per-role sheets with **26** fixed columns including Duplicate Frames / Frame Size / Audio Config / Codecs / Ingest Date + dynamic metadata keys; per-role **Total:** footers), Markers, Keywords, Titles & Generators, Transitions, **Non-Std Effects & Templates**, Video & Audio Effects, Speed Change Effects, **Summary** (project title in **B1**, narrow Row column A, black role-duration data), and **Media Summary** (Row + red missing-media paths); enabled empty sheets keep headers + `ReportEmptySectionStatus` / **No Missing Media**; 1-based **Row** on tabular Excel/PDF sheets by default (`ensuringRowColumn` / `allowsInjectedRowColumn`); inventory and section-sheet cell formatting, role exclusions, global column exclusion (`ReportColumn` / `excludedColumns`, including `ReportColumn.row`), disabled-clip filtering (`excludeDisabledClips`), project-name / compound-clip-name filtering (`allReportTimelineSources()`; standalone compound-clip exports without ``), `ReportTimecodeFormat` / `--timecode-format`, inventory-first `ReportBuildPhase` progress callbacks; optional `copyrightLabel` / CLI `--label-copyright` (Excel cover **A2**; PDF cover + footer centre); `includeChapterMarkersInMarkersReport` defaults **true** (Type = Chapter; no CLI chapter flag); `includeMarkersOutsideClipBoundaries` / Markers **Hidden** column. Extraction presets: Captions, Effects, FrameData, Markers, Roles, Titles. Experimental CLI (OpenFCPXMLKit-CLI): single binary with embedded DTDs; --check-version, --convert-version (stripping + DTD validation), --extension-type (fcpxmld | fcpxml; default fcpxmld; 1.5–1.9 always .fcpxml), --validate, --media-copy, --extract-shots (--dry-run), --create-project (new empty FCPXML project: --width, --height, --rate, --project-version, output-dir; DTD validation before write; FCP-style output with DOCTYPE, colorSpace, default smart collections), --report (Excel report: role inventory by default; --report-full, per-section flags including --report-markers, --report-keywords, --report-titles-generators, --report-transitions, --report-non-standard-effects, --report-effects, --report-speed-change-effects, --report-summary, --report-media-summary, --media-resolution, --media-summary-distinguish-proxy, --exclude-role, --exclude-column, --exclude-disabled-clips, --include-markers-outside-clip-boundaries, --protect-sheets, --timecode-format, --report-project, --label-copyright, --create-pdf); --log writes user-visible output for all commands to the log file; see Sources/OpenFCPXMLKitCLI/README.md. Xcode 26 dynamic linking compatibility: `swift-log` (`Logging`) is an explicit direct dependency in `Package.swift` to satisfy stricter transitive dylib linking rules when building OpenFCPXMLKit as a dynamic framework. @@ -143,13 +143,15 @@ Tests live under Tests/. Full description is in Tests/README.md. Summary: - Tests/ExcelReportTest/: optional Swift Testing integration target (**8** `@Test` methods; writes `Output/OFK-Default.xlsx`, `Output/OFK-Full.xlsx`, `Output/OFK-Default.pdf`, `Output/OFK-Full.pdf`, `Output/OFK-ExcludedColumns.pdf`, `Output/OFK-Copyright.xlsx`, `Output/OFK-Copyright.pdf`, `Output/OFK-OutsideClipBoundaries.xlsx` / `.pdf`, `, `Output/OFK-ProtectedSheets.xlsx`, and `Output/OFK-ExcludeRoleSubrole.xlsx` / `.pdf` from a local fixture; `Test.cancel` when fixture missing). See Tests/ExcelReportTest/README.md. +- Tests/ShotExtractionTest/: optional Swift Testing integration target (**4** `@Test` methods; writes PNG + CSV / Notion JSON under `Output/` including `OFK-Shots.csv` / `.json` / `OFK-Shots-result.json`; `OFK_SHOT_EXTRACTION_FCPXML`; `Test.cancel` when fixture or media missing). See Tests/ShotExtractionTest/README.md. + - Tests/Submitted FCPXML/: private local inbox for user-supplied FCPXML (`Inbox/`, `Notes/`). Contents are **gitignored** (never commit or push to GitHub); only `README.md` and `.gitkeep` are tracked. Workflow: anonymise → reproduce → fix → promote minimal public fixture. Smoke: `FCPXMLSubmittedFCPXMLSmokeTests` (`Test.cancel` when empty). See Tests/Submitted FCPXML/README.md. - Tests/FCPXML Samples/FCPXML/: sample .fcpxml files (60 samples). File tests and logic tests load these via `FCPXMLTestSampleLoading` / `FCPXMLTestingSampleSupport`; missing **bundled** samples **fail**; optional fixtures use `Test.cancel`. - Tests/OpenFCPXMLKitTests/: FCPXMLTestResources.swift (packageRoot, fcpxmlSamplesDirectory, urlForFCPXMLSample, FCPXMLSampleName); FCPXMLTestSampleLoading.swift / FCPXMLTestingSampleSupport.swift (tryLoad* / require*; fcpxmlFrameRateSampleNames, allFCPXMLSampleNames; Test.cancel for optional fixtures); FCPXMLReportingReportFixture.swift and FCPXMLReportingReportTestSupport.swift (optional reporting integration fixtures/assertions). OpenFCPXMLKitTests.swift: main @Suite with dependencies created in init(); MARK comments group tests. FileTests/: one test class per sample or category (e.g. FCPXMLFileTest_24, FCPXMLFileTest_AllSamples, FCPXMLFileTest_FrameRates, FCPXMLFileTest_GeneralDemo, FCPXMLFileTest_HiddenMarkers, FCPXMLFileTest_360Video, FCPXMLFileTest_AuditionSample, FCPXMLFileTest_ImageSample, FCPXMLFileTest_Multicam, FCPXMLFileTest_Photoshop, FCPXMLFileTest_SmartCollection). LogicAndParsing/: FCPXMLRootVersionTests, FCPXMLStructureTests, FCPXMLFormatAssetTests. Every test-case class is FCPXML-prefixed except the module-named umbrella OpenFCPXMLKitTests. FCPXMLAuthoringTests / FCPXMLVersionFeatureGateTests / FCPXMLProjectionEdgeCaseCorpusTests: detached Authoring, feature gate, Projection edge corpus. FCPXMLShotExtractionTests: still-image Shot Extraction (**10** `@Test`; PNG + CSV/Notion; reject video/titles/audio; dry-run). FCPXMLSubmittedFCPXMLSmokeTests: optional Inbox parse smoke. FCPXMLTimelineManipulationTests: ripple insert, auto lane assignment, clip queries, lane range, timestamps, metadata, secondary storylines, audio keyframes; injectable "now" for timestamp tests via lock-based NowBox (no DispatchSemaphore); do-catch for insertClipAutoLane/insertingClipAutoLane to verify success. FCPXMLTimecodeTests: initialization, arithmetic, comparison, CMTime conversion, frame alignment, hashing, codable. FCPXMLMIMETypeDetectionTests: sync and async detection for various file types. FCPXMLAssetValidationTests: asset existence, lane compatibility, TimelineClip integration. FCPXMLSilenceDetectionTests: silence detection at start/end of audio files. FCPXMLAssetDurationMeasurementTests: duration measurement for audio/video/images. FCPXMLParallelFileIOTests: concurrent read/write operations. FCPXMLAudioEnhancementTests: NoiseReduction, HumReduction, Equalization, MatchEqualization, Clip integration. FCPXMLTransform360Tests: coordinate types, spherical/cartesian, clip integration. FCPXMLCaptionTitleTests: TextStyle, TextStyleDefinition, Caption/Title integration, CaptionSample file test. FCPXMLKeyframeAnimationTests: FadeIn, FadeOut, Keyframe, KeyframeAnimation, FilterParameter integration. FCPXMLAudioKeyframeTests: audio keyframes in adjust-volume (param name="amount" with keyframeAnimation); parsing from FCPXML samples; decibel values (-3dB, -37dB); time values (FCPXML fractional format); fadeIn/fadeOut integration; multiple keyframes in sequence; secondary storyline and nested clip detection; TimelineWithSecondaryStorylineWithAudioKeyframes, TimelineSample file tests. FCPXMLCMTimeCodableTests: CMTime encoding/decoding as FCPXML time strings. FCPXMLCollectionTests: CollectionFolder, KeywordCollection, nested structures. FCPXMLSmartCollectionTests: SmartCollection models, match rules (MatchUsage, MatchRepresentation, MatchMarkers, MatchAnalysisType), round-trip, version stripping. FCPXMLAdjustmentTests: typed adjustment models and clip integration. FCPXMLFilterTests: VideoFilter, AudioFilter, VideoFilterMask, FilterParameter. FCPXMLImportOptionsTests: import options and library location parsing. FCPXMLCodableTests: Codable round-trip for model types. FCPXMLMediaExtractionTests: media reference extraction and copy (CLI --media-copy flow). FCPXMLDTDValidatorTests: per-version DTD validation. FCPXMLStructuralValidatorTests: cross-platform structural validation. FCPXMLAEXMLSerializationParityTests: AEXML vs Foundation serialization parity. FCPXMLTimelineExportValidationTests: timeline, exporters (empty timeline creation and project-creation export at different sizes and frame rates; includeDefaultSmartCollections and DTD validation), validators, file loader. FCPXMLAPIAndEdgeCaseTests: async load API, ServiceLogger injection, edge cases, Live Drawing (1.11+), HiddenClipMarker (1.13+). FCPXMLCutDetectionTests: edit points, transitions, gaps, CutSample file test. FCPXMLPerformanceTests: parameterised and basic performance tests. Reporting/extraction tests are all FCPXML-prefixed (FCPXMLCompoundClipReportTests, FCPXMLRoleInventoryReportTests, FCPXMLRoleInventoryColumnLayoutTests, FCPXMLRoleInventorySheetTotalTests, FCPXMLRoleInventoryDuplicateFramesTests, FCPXMLNonStandardEffectsTemplatesReportTests, FCPXMLMarkersReportTests, FCPXMLKeywordsReportTests, FCPXMLTitlesReportTests, FCPXMLTransitionsReportTests, FCPXMLEffectsReportTests, FCPXMLSpeedChangeEffectsReportTests, FCPXMLSummaryReportTests, FCPXMLReportExcelExportTests, FCPXMLReportPDFExportTests, FCPXMLReportPDFSheetPlanTests, FCPXMLReportPDFTableLayoutTests, FCPXMLReportFormattingTests, FCPXMLReportRoleExclusionTests, FCPXMLReportTimecodeFormatTests, FCPXMLReportBuildPhaseTests, FCPXMLReportColumnExclusionTests, FCPXMLReportExcludeDisabledClipsTests, FCPXMLRoleDisplayPreferenceTests, FCPXMLRoleInventoryClipCollectorTests, FCPXMLRoleInventoryRoleSheetOrderingTests, FCPXMLSummaryRoleDurationAggregatorTests, FCPXMLEffectsReportPolicyTests, FCPXMLSpeedChangeFormattingTests, FCPXMLDisplayClipNameTests, FCPXMLTitleDisplayTests, FCPXMLExtractionScopeTests, FCPXMLExtractedElementTests, FCPXMLEffectsCollectorTests, FCPXMLRolesExtractionPresetTests, FCPXMLEffectAppleSuppliedTests, FCPXMLClipParsingCarriesAudioTests, FCPXMLTransformAdjustmentParsingTests, FCPXMLTransitionSpinePlacementTests). -Use descriptive `@Test` / `@Suite` names; group related tests logically; use meaningful `#expect` / `#require` assertions. The suite is **Swift Testing only** (no XCTest). Current total: **1169** tests listed in `swift test list` (**1161** in `OpenFCPXMLKitTests` + **8** optional `ExcelReportTest`) covering all functionality including async/await, timeline manipulation, metadata, timestamps, FCPXMLTimecode, MIME type detection, asset validation, silence detection, asset duration measurement, parallel file I/O, version conversion stripping, per-version DTD validation, extract-then-copy (CLI --media-copy flow), synchronized clip matching, secondary storyline traversal, clip identification, URL resolution, version conversion edge cases, typed adjustment models (including Transform360, ColorConform, Stereo3D, VoiceIsolation), typed effect/filter models, typed caption/title models, smart collections (match-clip, match-media, match-ratings, match-text, match-usage, match-representation, match-markers, match-analysis-type), keyframe animation, audio keyframes (FCPXMLAudioKeyframeTests: adjust-volume param keyframeAnimation parsing, decibel/time validation, fadeIn/fadeOut integration), CMTime Codable extension, collection organization, Live Drawing (1.11+), HiddenClipMarker (1.13+), Format/Asset 1.13+ (heroEye, heroEyeOverride, mediaReps), FCPXMLExporter clip-level metadata export and XML declaration standalone="no", FCPXMLTimelineManipulationTests refactor (lock-based NowBox, do-catch for throwing APIs), Excel reporting (Selected Roles Inventory column layout, Summary/Media Summary split, ReportTimecodeFormat / format-aware headers, inventory-first ReportBuildPhase progress, global column exclusion, disabled-clip filtering, workbook cell formatting via FCPXMLReportWorkbookExporter), 360 video features, auditions, conform-rate, still images, multicam, secondary storylines, audio keyframes, keyword collections/folders, and Photoshop integration. +Use descriptive `@Test` / `@Suite` names; group related tests logically; use meaningful `#expect` / `#require` assertions. The suite is **Swift Testing only** (no XCTest). Current total: **1173** tests listed in `swift test list` (**1161** in `OpenFCPXMLKitTests` + **8** optional `ExcelReportTest` + **4** optional `ShotExtractionTest`) covering all functionality including async/await, timeline manipulation, metadata, timestamps, FCPXMLTimecode, MIME type detection, asset validation, silence detection, asset duration measurement, parallel file I/O, version conversion stripping, per-version DTD validation, extract-then-copy (CLI --media-copy flow), synchronized clip matching, secondary storyline traversal, clip identification, URL resolution, version conversion edge cases, typed adjustment models (including Transform360, ColorConform, Stereo3D, VoiceIsolation), typed effect/filter models, typed caption/title models, smart collections (match-clip, match-media, match-ratings, match-text, match-usage, match-representation, match-markers, match-analysis-type), keyframe animation, audio keyframes (FCPXMLAudioKeyframeTests: adjust-volume param keyframeAnimation parsing, decibel/time validation, fadeIn/fadeOut integration), CMTime Codable extension, collection organization, Live Drawing (1.11+), HiddenClipMarker (1.13+), Format/Asset 1.13+ (heroEye, heroEyeOverride, mediaReps), FCPXMLExporter clip-level metadata export and XML declaration standalone="no", FCPXMLTimelineManipulationTests refactor (lock-based NowBox, do-catch for throwing APIs), Excel reporting (Selected Roles Inventory column layout, Summary/Media Summary split, ReportTimecodeFormat / format-aware headers, inventory-first ReportBuildPhase progress, global column exclusion, disabled-clip filtering, workbook cell formatting via FCPXMLReportWorkbookExporter), 360 video features, auditions, conform-rate, still images, multicam, secondary storylines, audio keyframes, keyword collections/folders, and Photoshop integration. --- @@ -165,7 +167,7 @@ SwiftTimecode integration: use SwiftTimecode for all timecode operations; suppor ## Testing Requirements -Test coverage: unit tests for all public APIs; integration tests for complex workflows; performance tests for time-critical operations; concurrency tests for async operations; test all supported frame rates (Final Cut Pro compatible). Current: **1169** tests listed in `swift test list` (including AEXML parity, FCPXMLDTDValidatorTests, FCPXMLStructuralValidatorTests, FCPXMLReportTimecodeFormatTests, FCPXMLReportBuildPhaseTests, FCPXMLReportColumnExclusionTests, FCPXMLReportExcludeDisabledClipsTests, FCPXMLRoleInventoryColumnLayoutTests, FCPXMLRoleInventorySheetTotalTests, FCPXMLRoleInventoryDuplicateFramesTests, FCPXMLNonStandardEffectsTemplatesReportTests, FCPXMLReportExcelExportTests workbook cell formatting, FCPXMLReportPDFExportTests PDF export, FCPXMLReportPDFSheetPlanTests TOC colour-index parity, FCPXMLReportPDFTableLayoutTests column-width expansion, optional ExcelReportTest integration) covering all functionality including async/await, timeline manipulation, metadata, timestamps, FCPXMLTimecode, MIME type detection, asset validation, silence detection, asset duration measurement, parallel file I/O, version conversion, DTD validation, extract-then-copy flow, synchronized clip matching, secondary storyline traversal, clip identification, URL resolution, version conversion edge cases, typed adjustment models (including Transform360, ColorConform, Stereo3D, VoiceIsolation), typed effect/filter models, typed caption/title models, smart collections (match-clip, match-media, match-ratings, match-text, match-usage, match-representation, match-markers, match-analysis-type), keyframe animation, audio keyframes (FCPXMLAudioKeyframeTests: adjust-volume param keyframeAnimation parsing, decibel/time validation, fadeIn/fadeOut integration), CMTime Codable extension, collection organization, Live Drawing (1.11+), HiddenClipMarker (1.13+), Format/Asset 1.13+ (heroEye, heroEyeOverride, mediaReps), FCPXMLExporter clip-level metadata export and XML declaration standalone="no", FCPXMLTimelineManipulationTests (lock-based NowBox, do-catch), Excel reporting enhancements, PDF report export (TOC colour chips, column expansion after exclusions), 360 video features, auditions, conform-rate, still images, multicam, secondary storylines, audio keyframes, keyword collections/folders, and Photoshop integration. +Test coverage: unit tests for all public APIs; integration tests for complex workflows; performance tests for time-critical operations; concurrency tests for async operations; test all supported frame rates (Final Cut Pro compatible). Current: **1173** tests listed in `swift test list` (including AEXML parity, FCPXMLDTDValidatorTests, FCPXMLStructuralValidatorTests, FCPXMLReportTimecodeFormatTests, FCPXMLReportBuildPhaseTests, FCPXMLReportColumnExclusionTests, FCPXMLReportExcludeDisabledClipsTests, FCPXMLRoleInventoryColumnLayoutTests, FCPXMLRoleInventorySheetTotalTests, FCPXMLRoleInventoryDuplicateFramesTests, FCPXMLNonStandardEffectsTemplatesReportTests, FCPXMLReportExcelExportTests workbook cell formatting, FCPXMLReportPDFExportTests PDF export, FCPXMLReportPDFSheetPlanTests TOC colour-index parity, FCPXMLReportPDFTableLayoutTests column-width expansion, optional ExcelReportTest + ShotExtractionTest integration) covering all functionality including async/await, timeline manipulation, metadata, timestamps, FCPXMLTimecode, MIME type detection, asset validation, silence detection, asset duration measurement, parallel file I/O, version conversion, DTD validation, extract-then-copy flow, synchronized clip matching, secondary storyline traversal, clip identification, URL resolution, version conversion edge cases, typed adjustment models (including Transform360, ColorConform, Stereo3D, VoiceIsolation), typed effect/filter models, typed caption/title models, smart collections (match-clip, match-media, match-ratings, match-text, match-usage, match-representation, match-markers, match-analysis-type), keyframe animation, audio keyframes (FCPXMLAudioKeyframeTests: adjust-volume param keyframeAnimation parsing, decibel/time validation, fadeIn/fadeOut integration), CMTime Codable extension, collection organization, Live Drawing (1.11+), HiddenClipMarker (1.13+), Format/Asset 1.13+ (heroEye, heroEyeOverride, mediaReps), FCPXMLExporter clip-level metadata export and XML declaration standalone="no", FCPXMLTimelineManipulationTests (lock-based NowBox, do-catch), Excel reporting enhancements, PDF report export (TOC colour chips, column expansion after exclusions), 360 video features, auditions, conform-rate, still images, multicam, secondary storylines, audio keyframes, keyword collections/folders, and Photoshop integration. Test data: use realistic FCPXML samples; include edge cases and error conditions; test all supported frame rates; validate against actual Final Cut Pro output where applicable. @@ -258,7 +260,7 @@ Code review process: review for Swift 6.3 compliance; check concurrency implemen ## Documentation Sync -Keep this file in sync with AGENT.md. Hard must / must-not constraints live in **GUARDRAILS.md** (update Signs when a design lock or regression is learned — Signs: `swift-testing-only`, `chapter-markers-on-markers-sheet`, `markers-keywords-survive-host-occlusion`, `effects-role-type-filter`, `summary-percent-is-fraction`, `connected-role-inventory-survives-nesting`, `title-roles-honor-attribute`, `empty-enabled-report-sheets-keep-status`, `shot-extraction-primary-stills-only`, `row-colour-survives-column-exclusion`; keep ARCHITECTURE.md for structure and mermaid). Both AGENT.md and this file must reflect: changelog styling (CHANGELOG.md: Keep a Changelog format, version links to release tags, ✨ New Features / 🔧 Improvements / 🐛 Bug Fixes); project overview and codebase rewrite/refactor; architecture and single injection point (FCPXMLUtility.defaultForExtensions); source layout (Analysis, Classes, Delegates, Errors, Extensions including +Modular and +Codable, Implementations, Protocols, Services, Utilities, Annotations, Export, Timeline, Timing, Validation, FileIO, Logging, Format, Model including Adjustments, Animations, Filters, Clips with +Adjustments and +Typed, CommonElements with TextStyle/TextStyleDefinition, Structure with CollectionFolder/KeywordCollection/SmartCollection, Parsing, Extraction, Projection (TimelineProjector / MulticamProjection / RefClipProjection / ChannelKindFilter), Reporting including Excel/ and PDF/, ShotExtraction (`ShotExtractor` / PNG + CSV / csv2notion-neo Notion JSON), XML with Protocols/Foundation/AEXML/OFKXMLDefaultFactory, FCPXML DTDs; reporting vs core layers in ARCHITECTURE.md §2.7); test structure (Tests/ layout — **Swift Testing only**, no XCTest; harness `FCPXMLTestResources` / `FCPXMLTestSampleLoading` / `FCPXMLTestingSampleSupport`; FileTests/ including FCPXMLFileTest_GeneralDemo, FCPXMLFileTest_HiddenMarkers, FCPXMLFileTest_360Video, FCPXMLFileTest_AuditionSample, FCPXMLFileTest_ImageSample, FCPXMLFileTest_Multicam, FCPXMLFileTest_Photoshop, FCPXMLFileTest_SmartCollection, LogicAndParsing/ including FCPXMLFormatAssetTests, FCPXMLCutDetectionTests, FCPXMLTimelineProjectionTests, FCPXMLVersionConversionTests, FCPXMLMediaExtractionTests, FCPXMLTimelineManipulationTests, FCPXMLTimecodeTests, FCPXMLMIMETypeDetectionTests, FCPXMLAssetValidationTests, FCPXMLSilenceDetectionTests, FCPXMLAssetDurationMeasurementTests, FCPXMLParallelFileIOTests, FCPXMLAudioEnhancementTests, FCPXMLTransform360Tests, FCPXMLCaptionTitleTests, FCPXMLKeyframeAnimationTests, FCPXMLAudioKeyframeTests, FCPXMLCMTimeCodableTests, FCPXMLCollectionTests, FCPXMLSmartCollectionTests, FCPXMLAdjustmentTests, FCPXMLFilterTests, FCPXMLImportOptionsTests, FCPXMLCodableTests, FCPXMLAEXMLSerializationParityTests, FCPXMLDTDValidatorTests, FCPXMLStructuralValidatorTests, OpenFCPXMLKitTests.swift, FCPXMLTimelineExportValidationTests, FCPXMLAPIAndEdgeCaseTests, FCPXMLPerformanceTests (`ContinuousClock` budgets), FCPXMLTimelineProjectionTests, FCPXMLProjectionCoverageTests, FCPXMLParsingCoverageTests, FCPXMLEngineHygieneTests, FCPXMLReportObligationCorpusTests, FCPXMLExtractionNestFidelityTests, FCPXMLRoleInheritanceMatrixTests, FCPXMLExtractionProjectionPolicyTests, FCPXMLMarkersKeywordsProjectionTests, FCPXMLTitlesProjectionTests, FCPXMLTransitionsProjectionTests, FCPXMLEffectsProjectionTests, FCPXMLShotExtractionTests, FCPXMLSubmittedFCPXMLSmokeTests, and FCPXML-prefixed reporting/extraction tests (FCPXMLRoleInventoryReportTests, FCPXMLRoleInventoryColumnLayoutTests, FCPXMLRoleInventorySheetTotalTests, FCPXMLRoleInventoryDuplicateFramesTests, FCPXMLNonStandardEffectsTemplatesReportTests, FCPXMLCompoundClipReportTests, FCPXMLMarkersReportTests, FCPXMLKeywordsReportTests, FCPXMLTitlesReportTests, FCPXMLTransitionsReportTests, FCPXMLEffectsReportTests, FCPXMLSpeedChangeEffectsReportTests, FCPXMLSummaryReportTests, FCPXMLReportExcelExportTests, FCPXMLReportPDFExportTests, FCPXMLReportPDFSheetPlanTests, FCPXMLReportPDFTableLayoutTests, FCPXMLReportFormattingTests, FCPXMLReportRoleExclusionTests, FCPXMLReportTimecodeFormatTests, FCPXMLReportBuildPhaseTests, FCPXMLRoleDisplayPreferenceTests, FCPXMLRoleInventoryClipCollectorTests, FCPXMLRoleInventoryRoleSheetOrderingTests, FCPXMLSummaryRoleDurationAggregatorTests, FCPXMLEffectsReportPolicyTests, FCPXMLSpeedChangeFormattingTests, FCPXMLDisplayClipNameTests, FCPXMLTitleDisplayTests, FCPXMLExtractionScopeTests, FCPXMLExtractedElementTests, FCPXMLEffectsCollectorTests, FCPXMLRolesExtractionPresetTests, FCPXMLEffectAppleSuppliedTests, FCPXMLClipParsingCarriesAudioTests, FCPXMLTransformAdjustmentParsingTests, FCPXMLTransitionSpinePlacementTests); every test-case class is FCPXML-prefixed except the module-named umbrella OpenFCPXMLKitTests; empty timeline creation and project-creation export at different sizes and frame rates in FCPXMLTimelineExportValidationTests (clip-level metadata export, XML declaration standalone="no")). Cross-platform XML (OFKXML*, FCPXMLStructuralValidator, iOS). Private `Tests/Submitted FCPXML/` inbox (gitignored contents; never commit private FCPXML to GitHub). FCPXML 1.5–1.14 and FCPXMLElementType; FCPXMLVersion.supportsBundleFormat (1.10+); version conversion with element stripping and per-version DTD validation; FCPXML creation from scratch; timeline manipulation (ripple insert, auto lane assignment, clip queries, lane range, secondary storylines); timeline metadata (markers, chapter markers, keywords, ratings, timestamps); FCPXMLTimecode custom type; MIME type detection; asset validation (including still images); silence detection; asset duration measurement; parallel file I/O; TimelineFormat enhancements; typed adjustment models (Crop, Corners, Transform, Blend, Stabilization, Volume, Panner, Loudness, NoiseReduction, HumReduction, Equalization, MatchEqualization, Transform360, ColorConform, Stereo3D, VoiceIsolation); typed effect/filter models (VideoFilter, AudioFilter, VideoFilterMask, FilterParameter with keyframe animation and auxValue 1.11+); typed caption/title models (Caption, Title with TextStyle, TextStyleDefinition); smart collections (SmartCollection with match-clip, match-media, match-ratings, match-text, match-usage, match-representation, match-markers, match-analysis-type); keyframe animation (KeyframeAnimation, Keyframe, FadeIn, FadeOut); audio keyframes (FCPXMLAudioKeyframeTests: adjust-volume param keyframeAnimation parsing, decibel/time validation, fadeIn/fadeOut integration); CMTime Codable extension; collection organization (CollectionFolder, KeywordCollection); Live Drawing (1.11+); HiddenClipMarker (1.13+); Format/Asset 1.13+ (heroEye, heroEyeOverride, mediaReps); experimental CLI (OpenFCPXMLKit-CLI, single binary, embedded DTDs, --check-version, --convert-version, --extension-type fcpxml|fcpxmld, --validate, --media-copy, --extract-shots (--dry-run), --create-project with DTD validation and FCP-style output, --report Excel/PDF report with --report-full/per-section flags/--report-non-standard-effects/--report-summary/--report-media-summary/--media-resolution/--media-summary-distinguish-proxy/--exclude-role/--exclude-column/--exclude-disabled-clips/--include-markers-outside-clip-boundaries/--protect-sheets/--timecode-format/--report-project/--label-copyright/--create-pdf, --log/--log-level/--quiet with log file capturing all command output); Excel and PDF reporting subsystem (`allReportTimelineSources` / compound-clip timelines) (Reporting/ builders, Sections/Rows, Support including RoleInventoryColumnLayout, RoleInventoryDuplicateFrames, RoleInventorySheetTotal, ReportColumnExclusion, ReportFormatting, ReportTimecodeFormat, ReportBuildProgress; Excel/ via XLKit; buildReport/ReportExcelExport/ReportPDFExport; Non-Std Effects & Templates; Summary and Media Summary sheets; inventory Duplicate Frames / per-role Total footers; excludeDisabledClips/excludedColumns/timecodeFormat/copyrightLabel/includeChapterMarkersInMarkersReport (default true)/includeMarkersOutsideClipBoundaries/protectSheets; `--label-copyright`; inventory-first enabledPhases; PDF cover notes + TOC colour chips / SheetPlan colorIndex; TableLayout column expansion to contentWidth and Row inject); Shot Extraction (`ShotExtractor` / `planShots` / `--extract-shots` / `--dry-run`; Notion JSON via csv2notion-neo); extraction presets (Captions, Effects, FrameData, Markers, Roles, Titles); Manual chapters including 08 Detached Authoring / 12 Timeline Projection / 17 Cross-Platform / 19 CLI / 20 Reporting / 21 Shot Extraction / 22 Examples; Tests/ExcelReportTest optional integration (**8** Swift Testing; `Test.cancel` without fixture); Tests/Submitted FCPXML private inbox; Final Cut Pro frame rates; Swift 6 concurrency (Sendable, async/await, CI strict-concurrency job); Xcode 26 dynamic framework linking compatibility via explicit `swift-log` (`Logging`) dependency in `Package.swift`; SwiftExtensions 3.0.0+ and SwiftSemanticVersion 1.0.0+ (`SemanticVersion` for `FinalCutPro.FCPXML.Version`); current test count **1169** listed in `swift test list` (**1161** + **8**; all Swift Testing). When updating either file, update both and keep terminology and examples consistent. +Keep this file in sync with AGENT.md. Hard must / must-not constraints live in **GUARDRAILS.md** (update Signs when a design lock or regression is learned — Signs: `swift-testing-only`, `chapter-markers-on-markers-sheet`, `markers-keywords-survive-host-occlusion`, `effects-role-type-filter`, `summary-percent-is-fraction`, `connected-role-inventory-survives-nesting`, `title-roles-honor-attribute`, `empty-enabled-report-sheets-keep-status`, `shot-extraction-primary-stills-only`, `row-colour-survives-column-exclusion`; keep ARCHITECTURE.md for structure and mermaid). Both AGENT.md and this file must reflect: changelog styling (CHANGELOG.md: Keep a Changelog format, version links to release tags, ✨ New Features / 🔧 Improvements / 🐛 Bug Fixes); project overview and codebase rewrite/refactor; architecture and single injection point (FCPXMLUtility.defaultForExtensions); source layout (Analysis, Classes, Delegates, Errors, Extensions including +Modular and +Codable, Implementations, Protocols, Services, Utilities, Annotations, Export, Timeline, Timing, Validation, FileIO, Logging, Format, Model including Adjustments, Animations, Filters, Clips with +Adjustments and +Typed, CommonElements with TextStyle/TextStyleDefinition, Structure with CollectionFolder/KeywordCollection/SmartCollection, Parsing, Extraction, Projection (TimelineProjector / MulticamProjection / RefClipProjection / ChannelKindFilter), Reporting including Excel/ and PDF/, ShotExtraction (`ShotExtractor` / PNG + CSV / csv2notion-neo Notion JSON), XML with Protocols/Foundation/AEXML/OFKXMLDefaultFactory, FCPXML DTDs; reporting vs core layers in ARCHITECTURE.md §2.7); test structure (Tests/ layout — **Swift Testing only**, no XCTest; harness `FCPXMLTestResources` / `FCPXMLTestSampleLoading` / `FCPXMLTestingSampleSupport`; FileTests/ including FCPXMLFileTest_GeneralDemo, FCPXMLFileTest_HiddenMarkers, FCPXMLFileTest_360Video, FCPXMLFileTest_AuditionSample, FCPXMLFileTest_ImageSample, FCPXMLFileTest_Multicam, FCPXMLFileTest_Photoshop, FCPXMLFileTest_SmartCollection, LogicAndParsing/ including FCPXMLFormatAssetTests, FCPXMLCutDetectionTests, FCPXMLTimelineProjectionTests, FCPXMLVersionConversionTests, FCPXMLMediaExtractionTests, FCPXMLTimelineManipulationTests, FCPXMLTimecodeTests, FCPXMLMIMETypeDetectionTests, FCPXMLAssetValidationTests, FCPXMLSilenceDetectionTests, FCPXMLAssetDurationMeasurementTests, FCPXMLParallelFileIOTests, FCPXMLAudioEnhancementTests, FCPXMLTransform360Tests, FCPXMLCaptionTitleTests, FCPXMLKeyframeAnimationTests, FCPXMLAudioKeyframeTests, FCPXMLCMTimeCodableTests, FCPXMLCollectionTests, FCPXMLSmartCollectionTests, FCPXMLAdjustmentTests, FCPXMLFilterTests, FCPXMLImportOptionsTests, FCPXMLCodableTests, FCPXMLAEXMLSerializationParityTests, FCPXMLDTDValidatorTests, FCPXMLStructuralValidatorTests, OpenFCPXMLKitTests.swift, FCPXMLTimelineExportValidationTests, FCPXMLAPIAndEdgeCaseTests, FCPXMLPerformanceTests (`ContinuousClock` budgets), FCPXMLTimelineProjectionTests, FCPXMLProjectionCoverageTests, FCPXMLParsingCoverageTests, FCPXMLEngineHygieneTests, FCPXMLReportObligationCorpusTests, FCPXMLExtractionNestFidelityTests, FCPXMLRoleInheritanceMatrixTests, FCPXMLExtractionProjectionPolicyTests, FCPXMLMarkersKeywordsProjectionTests, FCPXMLTitlesProjectionTests, FCPXMLTransitionsProjectionTests, FCPXMLEffectsProjectionTests, FCPXMLShotExtractionTests, FCPXMLSubmittedFCPXMLSmokeTests, and FCPXML-prefixed reporting/extraction tests (FCPXMLRoleInventoryReportTests, FCPXMLRoleInventoryColumnLayoutTests, FCPXMLRoleInventorySheetTotalTests, FCPXMLRoleInventoryDuplicateFramesTests, FCPXMLNonStandardEffectsTemplatesReportTests, FCPXMLCompoundClipReportTests, FCPXMLMarkersReportTests, FCPXMLKeywordsReportTests, FCPXMLTitlesReportTests, FCPXMLTransitionsReportTests, FCPXMLEffectsReportTests, FCPXMLSpeedChangeEffectsReportTests, FCPXMLSummaryReportTests, FCPXMLReportExcelExportTests, FCPXMLReportPDFExportTests, FCPXMLReportPDFSheetPlanTests, FCPXMLReportPDFTableLayoutTests, FCPXMLReportFormattingTests, FCPXMLReportRoleExclusionTests, FCPXMLReportTimecodeFormatTests, FCPXMLReportBuildPhaseTests, FCPXMLRoleDisplayPreferenceTests, FCPXMLRoleInventoryClipCollectorTests, FCPXMLRoleInventoryRoleSheetOrderingTests, FCPXMLSummaryRoleDurationAggregatorTests, FCPXMLEffectsReportPolicyTests, FCPXMLSpeedChangeFormattingTests, FCPXMLDisplayClipNameTests, FCPXMLTitleDisplayTests, FCPXMLExtractionScopeTests, FCPXMLExtractedElementTests, FCPXMLEffectsCollectorTests, FCPXMLRolesExtractionPresetTests, FCPXMLEffectAppleSuppliedTests, FCPXMLClipParsingCarriesAudioTests, FCPXMLTransformAdjustmentParsingTests, FCPXMLTransitionSpinePlacementTests); every test-case class is FCPXML-prefixed except the module-named umbrella OpenFCPXMLKitTests; empty timeline creation and project-creation export at different sizes and frame rates in FCPXMLTimelineExportValidationTests (clip-level metadata export, XML declaration standalone="no")). Cross-platform XML (OFKXML*, FCPXMLStructuralValidator, iOS). Private `Tests/Submitted FCPXML/` inbox (gitignored contents; never commit private FCPXML to GitHub). FCPXML 1.5–1.14 and FCPXMLElementType; FCPXMLVersion.supportsBundleFormat (1.10+); version conversion with element stripping and per-version DTD validation; FCPXML creation from scratch; timeline manipulation (ripple insert, auto lane assignment, clip queries, lane range, secondary storylines); timeline metadata (markers, chapter markers, keywords, ratings, timestamps); FCPXMLTimecode custom type; MIME type detection; asset validation (including still images); silence detection; asset duration measurement; parallel file I/O; TimelineFormat enhancements; typed adjustment models (Crop, Corners, Transform, Blend, Stabilization, Volume, Panner, Loudness, NoiseReduction, HumReduction, Equalization, MatchEqualization, Transform360, ColorConform, Stereo3D, VoiceIsolation); typed effect/filter models (VideoFilter, AudioFilter, VideoFilterMask, FilterParameter with keyframe animation and auxValue 1.11+); typed caption/title models (Caption, Title with TextStyle, TextStyleDefinition); smart collections (SmartCollection with match-clip, match-media, match-ratings, match-text, match-usage, match-representation, match-markers, match-analysis-type); keyframe animation (KeyframeAnimation, Keyframe, FadeIn, FadeOut); audio keyframes (FCPXMLAudioKeyframeTests: adjust-volume param keyframeAnimation parsing, decibel/time validation, fadeIn/fadeOut integration); CMTime Codable extension; collection organization (CollectionFolder, KeywordCollection); Live Drawing (1.11+); HiddenClipMarker (1.13+); Format/Asset 1.13+ (heroEye, heroEyeOverride, mediaReps); experimental CLI (OpenFCPXMLKit-CLI, single binary, embedded DTDs, --check-version, --convert-version, --extension-type fcpxml|fcpxmld, --validate, --media-copy, --extract-shots (--dry-run), --create-project with DTD validation and FCP-style output, --report Excel/PDF report with --report-full/per-section flags/--report-non-standard-effects/--report-summary/--report-media-summary/--media-resolution/--media-summary-distinguish-proxy/--exclude-role/--exclude-column/--exclude-disabled-clips/--include-markers-outside-clip-boundaries/--protect-sheets/--timecode-format/--report-project/--label-copyright/--create-pdf, --log/--log-level/--quiet with log file capturing all command output); Excel and PDF reporting subsystem (`allReportTimelineSources` / compound-clip timelines) (Reporting/ builders, Sections/Rows, Support including RoleInventoryColumnLayout, RoleInventoryDuplicateFrames, RoleInventorySheetTotal, ReportColumnExclusion, ReportFormatting, ReportTimecodeFormat, ReportBuildProgress; Excel/ via XLKit; buildReport/ReportExcelExport/ReportPDFExport; Non-Std Effects & Templates; Summary and Media Summary sheets; inventory Duplicate Frames / per-role Total footers; excludeDisabledClips/excludedColumns/timecodeFormat/copyrightLabel/includeChapterMarkersInMarkersReport (default true)/includeMarkersOutsideClipBoundaries/protectSheets; `--label-copyright`; inventory-first enabledPhases; PDF cover notes + TOC colour chips / SheetPlan colorIndex; TableLayout column expansion to contentWidth and Row inject); Shot Extraction (`ShotExtractor` / `planShots` / `--extract-shots` / `--dry-run`; Notion JSON via csv2notion-neo with CSV column key order); extraction presets (Captions, Effects, FrameData, Markers, Roles, Titles); Manual chapters including 08 Detached Authoring / 12 Timeline Projection / 17 Cross-Platform / 19 CLI / 20 Reporting / 21 Shot Extraction / 22 Examples; Tests/ExcelReportTest optional integration (**8** Swift Testing; `Test.cancel` without fixture); Tests/ShotExtractionTest optional integration (**4** Swift Testing; Notion CSV key order; `Test.cancel` without fixture); Tests/Submitted FCPXML private inbox; Final Cut Pro frame rates; Swift 6 concurrency (Sendable, async/await, CI strict-concurrency job); Xcode 26 dynamic framework linking compatibility via explicit `swift-log` (`Logging`) dependency in `Package.swift`; SwiftExtensions 3.0.0+ and SwiftSemanticVersion 1.0.0+ (`SemanticVersion` for `FinalCutPro.FCPXML.Version`); current test count **1173** listed in `swift test list` (**1161** + **8** + **4**; all Swift Testing). When updating either file, update both and keep terminology and examples consistent. --- diff --git a/.gitignore b/.gitignore index 0c3581e..8d7df51 100644 --- a/.gitignore +++ b/.gitignore @@ -31,6 +31,15 @@ Tests/ExcelReportTest/Output/*.xlsx Tests/ExcelReportTest/Output/*.pdf Tests/ExcelReportTest/Output/~$* +# Local Shot Extraction integration fixtures and generated exports (not committed). +Tests/ShotExtractionTest/*.fcpxmld/ +Tests/ShotExtractionTest/*.fcpxml +Tests/ShotExtractionTest/Output/*.fcpxmld/ +Tests/ShotExtractionTest/Output/*.fcpxml +Tests/ShotExtractionTest/Output/* +!Tests/ShotExtractionTest/Output/README.md +!Tests/ShotExtractionTest/Output/.gitkeep + # Private user-submitted FCPXML inbox (never commit contents — only README / .gitkeep). Tests/Submitted FCPXML/Inbox/** !Tests/Submitted FCPXML/Inbox/.gitkeep diff --git a/AGENT.md b/AGENT.md index 070320f..0849cca 100644 --- a/AGENT.md +++ b/AGENT.md @@ -43,7 +43,7 @@ OpenFCPXMLKit targets macOS 26+, iOS 26+, Xcode 26+, and Swift 6.3 with full con **Backward compatibility:** The entire codebase must remain backward compatible with FCPXML 1.5. Optional attributes and elements introduced in later versions (e.g. 1.11, 1.13) must be omitted or ignored when reading/writing or converting to 1.5; mark such features in code comments with the minimum FCPXML version (e.g. `FCPXML 1.13+`). -Current status: **1169** tests listed in `swift test list` (**1161** in `OpenFCPXMLKitTests` + **8** optional `ExcelReportTest`; all Swift Testing `@Test`); FCPXML versions 1.5–1.14 supported (DTDs included, full parsing, typed element-type coverage for all DTD elements via FCPXMLElementType); Final Cut Pro frame rates (23.976, 24, 25, 29.97, 30, 50, 59.94, 60); thread-safe and concurrency-compliant with comprehensive async/await support; no known security vulnerabilities. Version conversion automatically drops elements not in the target version’s DTD (e.g. adjust-colorConform, adjust-stereo-3D); DTD validation runs per version (validateDocumentAgainstDTD, validateDocumentAgainstDeclaredVersion) and after CLI convert. FCPXMLVersion.supportsBundleFormat is true for 1.10+ (.fcpxmld bundle); 1.5–1.9 support only single-file .fcpxml. FCPXML creation: create FCPXML documents from scratch with events, projects, resources, and clips via XMLDocumentManager, XMLDocument initializers, or FCPXMLService. Timeline manipulation: ripple insert (shifts subsequent clips), auto lane assignment, clip queries (by lane, time range, asset ID), lane range computation, secondary storylines. Timeline metadata: markers, chapter markers, keywords, ratings, custom metadata, timestamps (createdAt, modifiedAt). FCPXMLTimecode: custom timecode type (arithmetic, frame alignment, CMTime conversion, FCPXML string parsing). MIME type detection, asset validation, silence detection, asset duration measurement, parallel file I/O, still image asset support. TimelineFormat enhancements: presets (hd720p, dci4K, hd1080i, hd720i), computed properties (aspectRatio, isHD, isUHD, interlaced). Typed adjustment models: Crop, Corners, Transform, Blend, Stabilization, Volume, Panner, Loudness, NoiseReduction, HumReduction, Equalization, MatchEqualization, Transform360, ColorConform, Stereo3D, VoiceIsolation with full clip integration. Typed effect/filter models: VideoFilter, AudioFilter, VideoFilterMask with FilterParameter support and keyframe animation (auxValue support FCPXML 1.11+). Typed caption/title models: Caption and Title with TextStyle and TextStyleDefinition for full text formatting. SmartCollection models: SmartCollection with match-clip, match-media, match-ratings, match-text, match-usage (1.9+), match-representation (1.10+), match-markers (1.10+), match-analysis-type (1.14). Keyframe animation: KeyframeAnimation, Keyframe with interpolation types, FadeIn/FadeOut with fade types, integrated with FilterParameter. CMTime Codable extension: Direct CMTime encoding/decoding as FCPXML time strings. Collection organization: CollectionFolder and KeywordCollection models for organizing clips and media. Live Drawing (FCPXML 1.11+): LiveDrawing model for live-drawing story elements. HiddenClipMarker (FCPXML 1.13+): HiddenClipMarker model for hidden clip markers. Format/Asset 1.13+: Format heroEye, Asset heroEyeOverride, Asset mediaReps (multiple media-rep). Cross-platform XML abstraction: protocol layer (OFKXMLNode, OFKXMLElement, OFKXMLDocument, OFKXMLFactory); Foundation backend on macOS (unchanged behaviour); AEXML backend on iOS; OFKXMLDefaultFactory() for platform dispatch; FCPXMLStructuralValidator for cross-platform structural validation; FCPXMLDTDValidator is platform-conditional (full DTD on macOS, structural fallback on iOS). Comprehensive test coverage: **1161** tests across 60 FCPXML sample files including 360 video, auditions, conform-rate, still images, multicam, secondary storylines, audio keyframes (FCPXMLAudioKeyframeTests: adjust-volume param keyframeAnimation parsing, decibel/time validation, fadeIn/fadeOut integration, secondary storyline detection), keyword collections/folders, Photoshop integration, smart collections, and reporting column layout/exclusion/disabled-clip/workbook/PDF formatting tests. Shot Extraction: primary-timeline still-image shots → PNG + CSV or [csv2notion-neo](https://github.com/TheAcharya/csv2notion-neo)-compatible Notion JSON (`ShotExtractor` / `extractShots(options:)` / `planShots(options:)` dry-run; CLI `--extract-shots` with `--dry-run`, `--scene-number`, `--extract-format`, `--folder-format`, optional `--icon` / **Icon Image**); rejects primary video, titles/generators, and audio; independent of Reporting. Excel and PDF reporting: multi-sheet `.xlsx` workbooks via `FinalCutPro.FCPXML.buildReport(options:)` (ReportBuilder, ReportOptions presets, ReportExcelExport on XLKit) and optional `.pdf` via `ReportPDFExport` (CoreGraphics; cover page with black “About This PDF Export” + `info.circle`, TOC with accent colour chips + content-tint washes, per-sheet tints, column-width expansion after exclusions, section pagination; same Report configuration as Excel); sheets for Role Inventory (**Selected Roles Inventory** + per-role sheets with **26** fixed columns including Duplicate Frames / Frame Size / Audio Config / Codecs / Ingest Date + dynamic metadata keys; per-role **Total:** footers), Markers, Keywords, Titles & Generators, Transitions, **Non-Std Effects & Templates**, Video & Audio Effects, Speed Change Effects, **Summary** (project title in **B1**, narrow Row column A, black role-duration data), and **Media Summary** (Row + red missing-media paths); enabled empty sheets keep headers + `ReportEmptySectionStatus` / **No Missing Media**; 1-based **Row** on tabular Excel/PDF sheets by default (`ensuringRowColumn` / `allowsInjectedRowColumn`); inventory and section-sheet cell formatting, role exclusions, global column exclusion (`ReportColumn` / `excludedColumns`, including `ReportColumn.row`), disabled-clip filtering (`excludeDisabledClips`), project-name / compound-clip-name filtering (`allReportTimelineSources()`; standalone compound-clip exports without ``), `ReportTimecodeFormat` / `--timecode-format`, inventory-first `ReportBuildPhase` progress callbacks; optional `copyrightLabel` / CLI `--label-copyright` (Excel cover **A2**; PDF cover + footer centre); `includeChapterMarkersInMarkersReport` defaults **true** (Type = Chapter; no CLI chapter flag); `includeMarkersOutsideClipBoundaries` / Markers **Hidden** column. Extraction presets: Captions, Effects, FrameData, Markers, Roles, Titles. Experimental CLI (OpenFCPXMLKit-CLI): single binary with embedded DTDs; --check-version, --convert-version (stripping + DTD validation), --extension-type (fcpxmld | fcpxml; default fcpxmld; 1.5–1.9 always .fcpxml), --validate, --media-copy, --extract-shots (--dry-run), --create-project (new empty FCPXML project: --width, --height, --rate, --project-version, output-dir; DTD validation before write; FCP-style output with DOCTYPE, colorSpace, default smart collections), --report (Excel report: role inventory by default; --report-full, per-section flags including --report-markers, --report-keywords, --report-titles-generators, --report-transitions, --report-non-standard-effects, --report-effects, --report-speed-change-effects, --report-summary, --report-media-summary, --media-resolution, --media-summary-distinguish-proxy, --exclude-role, --exclude-column, --exclude-disabled-clips, --include-markers-outside-clip-boundaries, --protect-sheets, --timecode-format, --report-project, --label-copyright, --create-pdf); --log writes user-visible output for all commands to the log file; see Sources/OpenFCPXMLKitCLI/README.md. +Current status: **1173** tests listed in `swift test list` (**1161** in `OpenFCPXMLKitTests` + **8** optional `ExcelReportTest` + **4** optional `ShotExtractionTest`; all Swift Testing `@Test`); FCPXML versions 1.5–1.14 supported (DTDs included, full parsing, typed element-type coverage for all DTD elements via FCPXMLElementType); Final Cut Pro frame rates (23.976, 24, 25, 29.97, 30, 50, 59.94, 60); thread-safe and concurrency-compliant with comprehensive async/await support; no known security vulnerabilities. Version conversion automatically drops elements not in the target version’s DTD (e.g. adjust-colorConform, adjust-stereo-3D); DTD validation runs per version (validateDocumentAgainstDTD, validateDocumentAgainstDeclaredVersion) and after CLI convert. FCPXMLVersion.supportsBundleFormat is true for 1.10+ (.fcpxmld bundle); 1.5–1.9 support only single-file .fcpxml. FCPXML creation: create FCPXML documents from scratch with events, projects, resources, and clips via XMLDocumentManager, XMLDocument initializers, or FCPXMLService. Timeline manipulation: ripple insert (shifts subsequent clips), auto lane assignment, clip queries (by lane, time range, asset ID), lane range computation, secondary storylines. Timeline metadata: markers, chapter markers, keywords, ratings, custom metadata, timestamps (createdAt, modifiedAt). FCPXMLTimecode: custom timecode type (arithmetic, frame alignment, CMTime conversion, FCPXML string parsing). MIME type detection, asset validation, silence detection, asset duration measurement, parallel file I/O, still image asset support. TimelineFormat enhancements: presets (hd720p, dci4K, hd1080i, hd720i), computed properties (aspectRatio, isHD, isUHD, interlaced). Typed adjustment models: Crop, Corners, Transform, Blend, Stabilization, Volume, Panner, Loudness, NoiseReduction, HumReduction, Equalization, MatchEqualization, Transform360, ColorConform, Stereo3D, VoiceIsolation with full clip integration. Typed effect/filter models: VideoFilter, AudioFilter, VideoFilterMask with FilterParameter support and keyframe animation (auxValue support FCPXML 1.11+). Typed caption/title models: Caption and Title with TextStyle and TextStyleDefinition for full text formatting. SmartCollection models: SmartCollection with match-clip, match-media, match-ratings, match-text, match-usage (1.9+), match-representation (1.10+), match-markers (1.10+), match-analysis-type (1.14). Keyframe animation: KeyframeAnimation, Keyframe with interpolation types, FadeIn/FadeOut with fade types, integrated with FilterParameter. CMTime Codable extension: Direct CMTime encoding/decoding as FCPXML time strings. Collection organization: CollectionFolder and KeywordCollection models for organizing clips and media. Live Drawing (FCPXML 1.11+): LiveDrawing model for live-drawing story elements. HiddenClipMarker (FCPXML 1.13+): HiddenClipMarker model for hidden clip markers. Format/Asset 1.13+: Format heroEye, Asset heroEyeOverride, Asset mediaReps (multiple media-rep). Cross-platform XML abstraction: protocol layer (OFKXMLNode, OFKXMLElement, OFKXMLDocument, OFKXMLFactory); Foundation backend on macOS (unchanged behaviour); AEXML backend on iOS; OFKXMLDefaultFactory() for platform dispatch; FCPXMLStructuralValidator for cross-platform structural validation; FCPXMLDTDValidator is platform-conditional (full DTD on macOS, structural fallback on iOS). Comprehensive test coverage: **1161** tests across 60 FCPXML sample files including 360 video, auditions, conform-rate, still images, multicam, secondary storylines, audio keyframes (FCPXMLAudioKeyframeTests: adjust-volume param keyframeAnimation parsing, decibel/time validation, fadeIn/fadeOut integration, secondary storyline detection), keyword collections/folders, Photoshop integration, smart collections, and reporting column layout/exclusion/disabled-clip/workbook/PDF formatting tests. Shot Extraction: primary-timeline still-image shots → PNG + CSV or [csv2notion-neo](https://github.com/TheAcharya/csv2notion-neo)-compatible Notion JSON (`ShotExtractor` / `extractShots(options:)` / `planShots(options:)` dry-run; CLI `--extract-shots` with `--dry-run`, `--scene-number`, `--extract-format`, `--folder-format`, optional `--icon` / **Icon Image**); rejects primary video, titles/generators, and audio; independent of Reporting. Excel and PDF reporting: multi-sheet `.xlsx` workbooks via `FinalCutPro.FCPXML.buildReport(options:)` (ReportBuilder, ReportOptions presets, ReportExcelExport on XLKit) and optional `.pdf` via `ReportPDFExport` (CoreGraphics; cover page with black “About This PDF Export” + `info.circle`, TOC with accent colour chips + content-tint washes, per-sheet tints, column-width expansion after exclusions, section pagination; same Report configuration as Excel); sheets for Role Inventory (**Selected Roles Inventory** + per-role sheets with **26** fixed columns including Duplicate Frames / Frame Size / Audio Config / Codecs / Ingest Date + dynamic metadata keys; per-role **Total:** footers), Markers, Keywords, Titles & Generators, Transitions, **Non-Std Effects & Templates**, Video & Audio Effects, Speed Change Effects, **Summary** (project title in **B1**, narrow Row column A, black role-duration data), and **Media Summary** (Row + red missing-media paths); enabled empty sheets keep headers + `ReportEmptySectionStatus` / **No Missing Media**; 1-based **Row** on tabular Excel/PDF sheets by default (`ensuringRowColumn` / `allowsInjectedRowColumn`); inventory and section-sheet cell formatting, role exclusions, global column exclusion (`ReportColumn` / `excludedColumns`, including `ReportColumn.row`), disabled-clip filtering (`excludeDisabledClips`), project-name / compound-clip-name filtering (`allReportTimelineSources()`; standalone compound-clip exports without ``), `ReportTimecodeFormat` / `--timecode-format`, inventory-first `ReportBuildPhase` progress callbacks; optional `copyrightLabel` / CLI `--label-copyright` (Excel cover **A2**; PDF cover + footer centre); `includeChapterMarkersInMarkersReport` defaults **true** (Type = Chapter; no CLI chapter flag); `includeMarkersOutsideClipBoundaries` / Markers **Hidden** column. Extraction presets: Captions, Effects, FrameData, Markers, Roles, Titles. Experimental CLI (OpenFCPXMLKit-CLI): single binary with embedded DTDs; --check-version, --convert-version (stripping + DTD validation), --extension-type (fcpxmld | fcpxml; default fcpxmld; 1.5–1.9 always .fcpxml), --validate, --media-copy, --extract-shots (--dry-run), --create-project (new empty FCPXML project: --width, --height, --rate, --project-version, output-dir; DTD validation before write; FCP-style output with DOCTYPE, colorSpace, default smart collections), --report (Excel report: role inventory by default; --report-full, per-section flags including --report-markers, --report-keywords, --report-titles-generators, --report-transitions, --report-non-standard-effects, --report-effects, --report-speed-change-effects, --report-summary, --report-media-summary, --media-resolution, --media-summary-distinguish-proxy, --exclude-role, --exclude-column, --exclude-disabled-clips, --include-markers-outside-clip-boundaries, --protect-sheets, --timecode-format, --report-project, --label-copyright, --create-pdf); --log writes user-visible output for all commands to the log file; see Sources/OpenFCPXMLKitCLI/README.md. Xcode 26 dynamic linking compatibility: `swift-log` (`Logging`) is an explicit direct dependency in `Package.swift` to satisfy stricter transitive dylib linking rules when building OpenFCPXMLKit as a dynamic framework. @@ -82,7 +82,7 @@ Foundation XML types (XMLDocument, XMLElement) and the protocol types that wrap ## Modularity and Safety -- **Shot Extraction:** Mid-layer under `Sources/OpenFCPXMLKit/ShotExtraction/` — primary-timeline still-image shots → PNG + CSV or [csv2notion-neo](https://github.com/TheAcharya/csv2notion-neo)-compatible Notion JSON (`ShotExtractor` / `extractShots` / `planShots` dry-run; CLI `--extract-shots` / `--dry-run`; optional `--icon` / **Icon Image**). Rejects primary video, titles/generators, and audio. Consumes Projection only; independent of Reporting. See Manual 21. +- **Shot Extraction:** Mid-layer under `Sources/OpenFCPXMLKit/ShotExtraction/` — primary-timeline still-image shots → PNG + CSV or [csv2notion-neo](https://github.com/TheAcharya/csv2notion-neo)-compatible Notion JSON with CSV column key order (`ShotExtractor` / `extractShots` / `planShots` dry-run; CLI `--extract-shots` / `--dry-run`; optional `--icon` / **Icon Image**). Rejects primary video, titles/generators, and audio. Consumes Projection only; independent of Reporting. See Manual 21. - All major functionality is protocol-based and dependency-injected, with both sync and async/await APIs. - Code is Sendable where appropriate; `@unchecked Sendable` removed from delegates (AttributeParserDelegate, FCPXMLParserDelegate) since they are internal-only and used synchronously. The project builds and tests with Swift 6 strict concurrency (`-strict-concurrency=complete`). CI runs a job that enforces this. - No known vulnerabilities in dependencies (including SwiftTimecode 3.1.2) as of July 2025. No unsafe pointers, dynamic code execution, or C APIs; concurrency is structured and type-safe. @@ -156,7 +156,7 @@ Source layout under Sources/OpenFCPXMLKit/: - Projection: Timeline analysis mid-layer. `TimelineProjecting`, `TimelineProjector`, `TimelineProjectionOptions` (incl. `.trackAnalysis`), `MediaChannel`, `MediaUsageWindow`, `LanePath`, `RetimingSegment` (`clipped`, `composing`), `TimelineOccupancyIndex` (start-sorted overlap); Retiming/`TimeMap+RetimingSegments`, `ConformRate+Retiming`, `ClipRetiming`, `AudioSplitRetiming`; Walk/`AssetChannelExpansion`, `SpineProjection`, `ProjectionTiming`, `MulticamProjection`, `RefClipProjection`, `ChannelKindFilter`. Nested/multicam/ref/audition unfold + channel filtering. Reporting: `ReportProjectionContext` / `ReportBuilder` project-once for inventory, markers, keywords, titles, transitions, effects, speed-change, media summary, and summary. See ARCHITECTURE.md §2.7 and Manual 12. - Authoring: Detached document value graph (`FinalCutPro.FCPXML.Authoring`) — `Document`, resources/story structs, `Element` encode protocol, `VersionAvailability` omit-on-write; parallel to live Model wrappers; not for Reporting. - Reporting: Excel and PDF report export. Top-level: Report, ReportOptions (including `copyrightLabel`), ReportBuilder (resolves timelines via `allReportTimelineSources()` / `ReportTimelineSource`), ReportTimecodeFormat, ReportBuildProgress (`ReportBuildPhase.enabledPhases(for:)` — inventory-first; Non-Std before Effects). Subfolders: Builders (RoleInventory, Markers, Keywords, Titles, Transitions, NonStandardEffectsTemplates, Effects, SpeedChangeEffects, Summary, MediaSummary), Sections and Rows (typed section/row models with `columnHeaders(timecodeFormat:)`), Support (RoleInventoryClipCollector — nested connected own-assignment via `fcpHasStandaloneConnectedInventoryAssignment`, under-spine title/`Title.role` and leaf `