[jonwis]

Summary

Adds a data-driven alternative to per-animation generated native code:

1. LottieGen -Language flatbuffer serializes the translated WinCompData graph into .lcomp files.
2. A native C++/WinRT reader realizes that graph using the caller's compositor.
3. Applications compile the reader into their existing binaries and embed or otherwise supply the data.

There is no separate runtime DLL, COM activation layer, or exported loader ABI. The earlier
registration-free COM design has been removed. Each consuming binary owns its reader implementation.
The existing C#, C++/CX, and C++/WinRT generation paths remain available.

Format and integration

The format stores the translated Composition graph, not the original Lottie JSON. Translation stays
in the generator; the application needs only the native reader and compiled data.

• Indexed graph references and interned strings preserve object sharing.
• The schema, generated C#/C++ bindings, serializer, and managed round-trip reader are included.
• The native reader verifies the FlatBuffer, schema version, required API contract, and graph references.
• Contract-specific fallback translations produce separate .lcomp variants; the host selects one.
• Direct2D supplies native path geometry without a Win2D dependency.

The same serialized format serves two separately compiled C++/WinRT projections:

Composition API	Reader definition
Windows.UI.Composition	LOTTIE_RUNTIME_WINUI2
Microsoft.UI.Composition	LOTTIE_RUNTIME_WINUI3

Consumers build as C++20 with exactly one definition per reader compilation. The projection-specific
namespaces keep the two native implementations distinct; this is source integration, not an ABI bridge.

LottieGen.nupkg includes the reader source/header, generated schema binding, pinned FlatBuffers
headers, licenses, and integration instructions. It does not distribute a reader DLL or COM manifest.

Native loading APIs

• LoadComposition retains the Visual-only loading contract.
• LoadCompositionWithMetadata returns the root visual, duration, dimensions, frame rate, markers,
  live theme properties, and realized image-surface descriptors.
• Theme properties are the actual property set referenced by the graph's expressions. Updating them
  changes the existing visual tree.
• Hosts can observe image completion and reuse loaded image surfaces across new trees from the same
  buffer and XAML host compositor.
• Metadata validation rejects malformed values and indices. Marker order, duplicate names, and finite
  out-of-range progress values are preserved; projection and playback policy belong to the host.

The host owns XAML integration, animated-visual adapters, progress animation, image-completion policy,
and object lifetime. Image-bearing animations use the XAML host's compositor.

Anonymized native-client size example

Representative migrations from generated native animation code to embedded .lcomp resources:

DLL	Animations migrated	Final DLL size change
foo.dll	33	-42.26%
bar.dll	9	-25.56%
baz.dll	2	-9.33%
qux.dll	2	-1.45%
quux.dll	1	+1.54%
Combined	47	-23.50%

Counts are distinct animations, not generated API-contract variants. Negative percentages mean a
smaller DLL. The combined percentage is weighted by the original DLL sizes, not averaged across rows.

These are matched standalone Release/x64 measurements of complete DLLs, including each DLL's reader,
host adapters, and embedded payloads. They exclude PDBs and unchanged dependencies, and do not measure
whole-package size or working set. One pair used identical analysis-disabled settings on both sides.
The two-animation result in baz.dll includes removing fallback variants outside that host's supported
OS range.

The single-animation DLL grows because reader/adapter overhead outweighs the generated code removed.
The reader cost is amortized within each binary, not shared through a new runtime DLL.

Validation and remaining work

• Managed tests cover graph round trips, corpus coverage, and malformed-buffer rejection.
• The focused native regression executable builds with /W4 /WX and passes on WinUI 2/x64. It covers
  metadata validation, the legacy no-metadata API, live theme/cache identity, owned-property
  initialization ordering, image reuse, and invalid image descriptors.
• The standalone inspection-tool source provides load, --dump, and --show paths. Its build still
  needs removal of a stale loader cleanup reference left by the deleted COM implementation; the
  native regression result above does not claim that the inspection tool or the full matrix is green.

(via Copilot)

[jonwis]

@dotnet-policy-service agree company="Microsoft"

[aborziak-ms]

@jonwis I left a few inline comments, but wanted to share some higher-level thoughts as well:

• I'd suggest scoping this PR to the .lcomp format + LottieGen output + a small native C++ runtime. For native, a simple .h/.cpp drop-in that takes the app's Compositor and works with AnimatedVisualPlayer should be enough. I don't think we necessarily need the COM DLL here, since C++ apps can just compile the drop-in. The C# interpreter would mostly duplicate Instantiator, which the managed side (Lottie-Windows package) can reuse.
• I can pick up the managed side separately and integrate lcomp into Lottie-Windows UWP and WinUI packages. The .lcomp graph is basically what Loader already builds from JSON, so we can load it through the existing LottieVisualSource path and get AnimatedVisualPlayer, images, WinUI 3 etc. for free.
• Since the format would be shared by both, it'd be good to settle a few things now: include all UAP versions (like codegen does), have a versioning for schema changes, and keep the generated types internal.
• For FlatBuffers, maybe just check in include/flatbuffers + LICENSE inside the native runtime folder instead of a full submodule? It's the only thing that needs the headers, it keeps the drop-in self-contained.

[aborziak-ms]

I think the managed side should just live in Lottie-Windows. Then there's one C# library that handles both JSON and .lcomp, and .lcomp can reuse the existing pipeline (CompositionDeserializer → Instantiator → AnimatedVisualPlayer) instead of a separate C# interpreter. I'd keep LottieRuntime as the small native runtime for C++ only. Otherwise, I'm worried we end up with too many pieces doing the same thing but a little differently.

[jonwis]

OK. I'll extend the existing C# library with this support instead and remove this one.

[jonwis]

• I don't think we necessarily need the COM DLL here, since C++ apps can just compile the drop-in. The C# interpreter would mostly duplicate Instantiator, which the managed side (Lottie-Windows package) can reuse.

OK, will narrow to just the producer and C++ consumer code, and update the C# instantiator. In Windows, we'll want to have a shared copy of the instantiator. What do you think about "a pretty OK sample" that shows using this in a common way? Or do we just assume the bots will figure out how to have one copy per process?

• pick up the managed side separately and integrate lcomp into Lottie-Windows UWP and WinUI packages.

That'd be great! Is there anything needed to get this ready for a C++/WinRT consumer of WASDK XAML/Composition? Does Lottie-Windows have a C++/WinRT package?

• it'd be good to settle a few things now: include all UAP versions (like codegen does), have a versioning for schema changes, and keep the generated types internal.

See note on supported UAP versions. At some point we should include "supported WASDK versions" and migrate people to using the Microsoft.UI types. I'll make the changes you suggest.

include/flatbuffers + LICENSE inside the native runtime

I'll have to see what that looks like; IIRC I had to tinker a bit to get flatc.exe working correctly.

Thanks for the comments!

[jonwis]

Addressed the FlatBuffers vendoring suggestion from your review: the submodule is removed, and the pinned C++ headers plus upstream LICENSE are now checked into external/flatbuffers. UPSTREAM.md records the exact commit/version, and build/RegenerateFlatbuffers.ps1 now documents where to get the matching flatc.exe and source archive, validates both compiler/header versions, and can refresh the vendored copy. The checked-in files were verified byte-for-byte against the formerly pinned submodule revision.