windows-rs Documentation

Technical Documentation: microsoft/windows-rs

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`docs/readme.md`) Copy Section

windows-rs provides Rust crates for Windows APIs, from COM support and system services to UI and
raw bindings.

Prefer the focused crates below when they cover the functionality you need. For additional APIs,
windows-bindgen can generate a minimal project-specific binding,
while windows and windows-sys provide broad API
coverage behind feature flags for binary applications.

Reusable libraries should avoid the windows and windows-sys umbrella crates. They add
dependency weight and version churn, and several libraries can bring incompatible versions of the
same large crate into one dependency tree. Prefer the focused crates for shared Windows types and
generate any remaining private bindings with windows-bindgen.

Each crate page covers usage and maintenance. Generated API documentation is available on
docs.rs.

Crates Copy Chapter

Core types and interop Copy Section

Values and collections Copy Section

Async and threading Copy Section

System services Copy Section

UI and graphics Copy Section

Code generation and metadata Copy Section

Macro implementation Copy Section

These crates implement macros exported by windows-core. Applications should use the
windows-core exports rather than depend on them directly.

Windows API bindings Copy Section

Use windows-bindgen when the focused crates above do not cover the APIs you need. Binary
applications may instead prefer the convenience of the pre-generated windows or windows-sys
umbrella crate.

Overview (`metadata/win32/readme.md`) Copy Section

Win32 metadata snapshot

This directory holds the canonical RDL snapshot of the Win32 API surface that
windows-clang scrapes from the Windows SDK headers. The whole
API lives in a single flat Windows.Win32 namespace, split one file per defining header -
e.g. wingdi.rdl holds exactly the declarations wingdi.h defines - written in the human-readable
RDL text format. The partitioning follows the source (the clang
cursor's defining header), not a hand-curated namespace layout.

The merged binary Windows.Win32.winmd that downstream tooling consumes is not checked in (winmd
is a binary format, and *.winmd is git-ignored). This text snapshot is committed instead so the
API surface can be browsed directly and so changes show up as readable diffs in pull requests - the
same reason the generated windows and windows-sys crates are committed.

Generated - do not edit by hand Copy Chapter

These files are produced by tool-win32:

cargo run -p tool-win32

Re-run the tool after changing the manifest (the const slices in
crates/tools/win32/src/main.rs), the hand-authored vocabulary seed (metadata/metadata.rdl), or
the scraper, and commit the resulting diff. Hand edits will be overwritten on the next run - the
tool clears the generated partitions in this directory and re-emits the whole closure. The seed
lives one level up (metadata/metadata.rdl) so it survives that clear.

See docs/crates/windows-clang.md for the scraper design -
how the metadata matches the SDK headers, header partitioning, and the documented deviations from
the reference - and docs/crates/windows-rdl.md for the winmd
artifact and layout of the in-house metadata pipeline that replaces the external win32metadata
project.

Overview (`crates/libs/animation/readme.md`) Copy Section

windows-animation Copy Chapter

Windows Animation wraps the Windows Animation Manager (IUIAnimationManager) for variable
interpolation, transitions, and storyboards. It does not depend on a UI or rendering framework.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-animation]
version = "0.100"

use windows_animation::*;

fn main() -> Result<()> {
    let manager = Manager::new()?;
    let opacity = manager.create_variable(0.0)?;

    // Animate from 0.0 to 1.0 over half a second.
    let library = TransitionLibrary::new()?;
    let fade_in = library.linear(0.5, 1.0)?;

    let storyboard = manager.create_storyboard()?;
    storyboard.add_transition(&opacity, &fade_in)?;
    storyboard.schedule(0.0)?;

    // Each frame, advance the clock and read the current value.
    manager.update(0.25)?;
    let value = opacity.value()?;
    assert!((0.0..=1.0).contains(&value));
    Ok(())
}

Overview (`crates/libs/bindgen/readme.md`) Copy Section

windows-bindgen Copy Chapter

The windows-bindgen crate generates Rust bindings from
Windows metadata.

• Guide

Add the generator as a build dependency and the generated code's runtime dependency:

[dependencies.windows-link]
version = "0.100"

[build-dependencies.windows-bindgen]
version = "0.100"

Generate a flat file in OUT_DIR from build.rs:

use std::path::Path;

fn main() {
    let out_dir = std::env::var("OUT_DIR").unwrap();
    windows_bindgen::builder()
        .output(Path::new(&out_dir).join("bindings.rs"))
        .filter("GetTickCount")
        .flat()
        .sys()
        .write();
}

Filters name the functions, constants, or types you need. Signature dependencies are included
automatically. See the guide for qualified names, member filters, and filter files.

Use the generated bindings from src/main.rs:

mod bindings {
    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
}

fn main() {
    unsafe {
        println!("{}", bindings::GetTickCount());
    }
}

For a published library, generate and commit src/bindings.rs from a separate tool instead of
running the generator in consumer builds. Formatting is best effort; install rustfmt when
generating checked-in source.

Overview (`crates/libs/canvas/readme.md`) Copy Section

windows-canvas Copy Chapter

Windows Canvas wraps Direct2D, Direct3D 11, DXGI, DirectWrite, and WIC for 2D drawing.

The core crate is host-neutral. Enable system for the typed windows-window swap-chain helper,
reactor for Canvas controls in Reactor, and composition to draw into Composition surfaces. The
system and reactor host adapters can coexist unless composition selects their incompatible
Composition backends.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-canvas]
version = "0.100"

use windows_canvas::*;

fn main() -> Result<()> {
    let device = GpuDevice::new_warp()?;
    let mut swap_chain = device.create_swap_chain(640, 480)?;

    let session = swap_chain.begin_draw()?;
    session.clear(ColorF::CORNFLOWER_BLUE);

    let brush = session.create_solid_brush(ColorF::rgb(1.0, 0.5, 0.0))?;
    session.fill_rect(&Rect::new(20.0, 20.0, 200.0, 120.0), &brush);
    drop(session);

    swap_chain.present()?;
    Ok(())
}

Overview (`crates/libs/clang/readme.md`) Copy Section

windows-clang Copy Chapter

The windows-clang crate extracts declarations from C and
C++ source with libclang and emits RDL. It is the
header-facing stage of the Windows metadata pipeline:

headers -> windows-clang -> RDL -> windows-rdl -> WinMD

Add the crate to your Cargo.toml:

[dependencies.windows-clang]
version = "0.100"

For ordinary header-to-RDL generation, configure and run the high-level builder:

windows_clang::clang()
    .input("Example.h")
    .args(["-x", "c++", "--target=x86_64-pc-windows-msvc"])
    .reference_default()
    .namespace("Example")
    .library("example.dll")
    .output("Example.rdl")
    .write()
    .unwrap();

The builder reads inputs and references, invokes the extractor, emits RDL, and writes the output.
Use Input, extract, and EmitOptions directly when a generator needs to inspect or
combine immutable snapshots before emission.

The caller owns libclang installation, compiler arguments, package versions, import-library
discovery, architecture merging, output promotion, and RDL-to-WinMD compilation. See the crate
documentation for both APIs and the extraction model.

Overview (`crates/libs/collections/readme.md`) Copy Section

windows-collections Copy Chapter

The windows-collections crate implements Windows
collection interfaces for Rust collections.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-collections]
version = "0.100"

use windows_collections::*;

let numbers = IIterable::<i32>::from(vec![1, 2, 3]);

for value in numbers {
    println!("{value}");
}

Overview (`crates/libs/composition/readme.md`) Copy Section

windows-composition Copy Chapter

Windows Composition wraps the retained-mode Windows composition engine for standalone windows and
WinUI 3 applications.

The default system feature hosts Composition in a windows-window window. Use the reactor
feature for a Composition host inside Reactor, with default features disabled. The stacks are
mutually exclusive. Both support Canvas drawing surfaces through windows-canvas[composition];
select Canvas's matching system or reactor feature.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-composition]
version = "0.100"

use windows_composition::*;

fn build(compositor: &Compositor) -> SpriteVisual {
    let visual = compositor.create_sprite_visual();
    visual.set_size(200.0, 120.0);

    let brush = compositor.create_color_brush(CompositionColor::rgb(0, 120, 215));
    visual.set_brush(&brush);
    visual
}

Overview (`crates/libs/core/readme.md`) Copy Section

windows-core Copy Chapter

The windows-core crate provides COM and WinRT types,
traits, and macros for the windows-* family of crates.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-core]
version = "0.100"

Use the core types as needed:

use windows_core::{h, Result, HRESULT, HSTRING};

// WinRT reference-counted strings.
let name: &HSTRING = h!("Windows.Foundation.Uri");
assert_eq!(name, &HSTRING::from("Windows.Foundation.Uri"));

// HRESULT-based results.
fn check(code: HRESULT) -> Result<()> {
    code.ok()
}

assert!(check(HRESULT(0)).is_ok());
assert!(check(HRESULT(-2147467259)).is_err());

create_instance activates an in-process COM class and returns a requested interface. The
application must initialize the calling thread for COM before using it.

Use init_mta for apartment-agnostic code. UI threads that require a single-threaded apartment can
hold the value returned by init_sta for the lifetime of their COM objects.

Overview (`crates/libs/cppwinrt/readme.md`) Copy Section

cppwinrt Copy Chapter

The cppwinrt crate bundles the C++/WinRT compiler for use in
Rust.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.cppwinrt]
version = "0.100"

Use cppwinrt function as needed:

println!("{}", cppwinrt::cppwinrt(["-help"]));

Overview (`crates/libs/default/readme.md`) Copy Section

windows-default Copy Chapter

The windows-default crate provides the default metadata
for Windows APIs as embedded byte slices. Build tools can use WINRT and WIN32 without
locating or distributing separate .winmd files.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-default]
version = "0.100"

use windows_default::{WIN32, WINRT};

assert!(!WINRT.is_empty());
assert!(!WIN32.is_empty());

Overview (`crates/libs/future/readme.md`) Copy Section

windows-future Copy Chapter

The windows-future crate adapts WinRT asynchronous
operations to Rust futures.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-future]
version = "0.100"

Use the Windows async types as needed:

use windows_future::*;

// This result will be available immediately.
let ready = IAsyncOperation::ready(Ok(123));
assert_eq!(ready.join().unwrap(), 123);

let ready = IAsyncOperation::spawn(|| {
    // Some lengthy operation goes here...
    Ok(456)
});

assert_eq!(ready.join().unwrap(), 456);

Overview (`crates/libs/implement/readme.md`) Copy Section

windows-implement Copy Chapter

The windows-implement crate provides the
#[implement] macro for implementing COM and WinRT interfaces in Rust.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies]
windows-core = "0.100"
windows-implement = "0.100"

use windows_core::{IUnknown, interface};
use windows_implement::implement;

#[interface("57f61c8b-b400-4035-a7c2-abbddf9e3559")]
unsafe trait IValue: IUnknown {
    fn get(&self) -> u32;
}

#[implement(IValue)]
struct Value(u32);

impl IValue_Impl for Value_Impl {
    unsafe fn get(&self) -> u32 {
        self.0
    }
}

let value: IValue = Value(42).into();
assert_eq!(unsafe { value.get() }, 42);

Overview (`crates/libs/interface/readme.md`) Copy Section

windows-interface Copy Chapter

The windows-interface crate provides the
#[interface] macro for declaring COM interfaces in Rust.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies]
windows-core = "0.100"
windows-interface = "0.100"

use windows_core::IUnknown;
use windows_interface::interface;

#[interface("57f61c8b-b400-4035-a7c2-abbddf9e3559")]
unsafe trait IValue: IUnknown {
    fn get(&self) -> u32;
}

Overview (`crates/libs/link/readme.md`) Copy Section

windows-link Copy Chapter

The windows-link crate provides the link macro that
simplifies linking. The link macro uses raw-dylib and thus does not require import lib files.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-link]
version = "0.100"

Use the link macro to import functions and their matching function-pointer types. Here the loader
functions are linked normally while MessageBoxA is resolved at runtime:

use std::ffi::c_void;
use windows_link::link;

link!("kernel32.dll" "system" fn LoadLibraryA(name: *const u8) -> *mut c_void);
link!("kernel32.dll" "system" fn GetProcAddress(
    library: *mut c_void,
    name: *const u8,
) -> *mut c_void);
link!("user32.dll" "system" fn MessageBoxA(
    hwnd: *mut c_void,
    text: *const u8,
    caption: *const u8,
    kind: u32,
) -> i32);

unsafe {
    let module = LoadLibraryA(b"user32.dll\0".as_ptr());
    let address = GetProcAddress(module, b"MessageBoxA\0".as_ptr());

    if !address.is_null() {
        let message_box: MessageBoxA = std::mem::transmute(address);

        message_box(
            std::ptr::null_mut(),
            b"text\0".as_ptr(),
            b"caption\0".as_ptr(),
            0,
        );
    }
}

Overview (`crates/libs/metadata/readme.md`) Copy Section

windows-metadata Copy Chapter

The windows-metadata crate reads and writes the
ECMA-335 metadata format used by .NET, WinRT, and Win32 metadata.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-metadata]
version = "0.100"

Query a type with the metadata reader:

use windows_metadata::*;

let index = reader::Index::read("Windows.winmd").unwrap();

let def = index.expect("Windows.Foundation", "Point");
assert_eq!(def.namespace(), "Windows.Foundation");
assert_eq!(def.name(), "Point");

let extends = def.extends().unwrap();
assert_eq!(extends.namespace(), "System");
assert_eq!(extends.name(), "ValueType");

let fields: Vec<_> = def.fields().collect();
assert_eq!(fields.len(), 2);
assert_eq!(fields[0].name(), "X");
assert_eq!(fields[1].name(), "Y");
assert_eq!(fields[0].ty(), Type::F32);
assert_eq!(fields[1].ty(), Type::F32);

Overview (`crates/libs/numerics/readme.md`) Copy Section

windows-numerics Copy Chapter

The windows-numerics crate provides Windows vector,
matrix, plane, and quaternion types.

• Getting
  started

These are the same graphics math types used by composition, Direct2D, and Direct3D
APIs, so values flow into those APIs without conversion.

Start by adding the following to your Cargo.toml file:

[dependencies.windows-numerics]
version = "0.100"

Use the vector and matrix types as needed:

use windows_numerics::*;

let a = Vector2::new(3.0, 4.0);
assert_eq!(a.length(), 5.0);

let b = Vector3::new(1.0, 0.0, 0.0);
let c = Vector3::new(0.0, 1.0, 0.0);
assert_eq!(b.cross(&c), Vector3::new(0.0, 0.0, 1.0));

let transform = Matrix3x2::translation(10.0, 20.0);
assert_eq!(transform.m31, 10.0);
assert_eq!(transform.m32, 20.0);

Overview (`crates/libs/pickers/readme.md`) Copy Section

windows-pickers Copy Chapter

Windows Pickers provides file and folder pickers backed by the Windows Common Item Dialog. It
supports standalone Windows applications and components built with windows-reactor.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies]
windows-pickers = "0.100"
windows-window = "0.100"

# #[cfg(feature = "system")]
# mod example {
use windows_pickers::{OpenFilePicker, Result};
use windows_window::Window;

fn pick_rust_file(window: &Window) -> Result<()> {
    let path = OpenFilePicker::new()
        .title("Open a Rust source file")
        .filter_extensions("Rust source", ["rs"])
        .filter_all()
        .show(window)?;

    if let Some(path) = path {
        println!("{}", path.display());
    }

    Ok(())
}
# }

The calling thread must be a COM single-threaded apartment (STA). Cancellation returns Ok(None);
other Windows failures are returned as errors.

Overview (`crates/libs/rdl/readme.md`) Copy Section

windows-rdl Copy Chapter

The windows-rdl crate compiles RDL (Rust Definition
Language) - a Rust-like text format for describing Windows APIs - into ECMA-335 .winmd metadata,
and back again.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-rdl]
version = "0.100"

Use the reader to compile .rdl source into a .winmd, and the writer to regenerate canonical
.rdl from a .winmd:

windows_rdl::reader()
    .input("example.rdl")
    .output("example.winmd")
    .write()
    .unwrap();

windows_rdl::writer()
    .input("example.winmd")
    .output("example.rdl")
    .write()
    .unwrap();

Overview (`crates/libs/reactor-setup/readme.md`) Copy Section

windows-reactor-setup Copy Chapter

Windows Reactor Setup stages the Windows App SDK runtime files needed by a
windows-reactor application that runs
fully self-contained.

• Getting
  started

Add it as a build dependency:

[build-dependencies]
windows-reactor-setup = "0.100"

Call the setup function from build.rs:

windows_reactor_setup::as_self_contained();

Runtime extraction caches are separate for each target architecture and are reused only after
successful extraction and required-file checks. Download, extraction, and copy errors fail the
build rather than leaving it to succeed with missing runtime files.

Overview (`crates/libs/reactor/readme.md`) Copy Section

windows-reactor Copy Chapter

Windows Reactor is a typed declarative UI library for building native WinUI 3 applications in
Rust. Components own Rust state, describe the current view, and receive typed messages from
controls.

Add Reactor to Cargo.toml:

[dependencies.windows-reactor]
version = "0.100"

use windows_reactor::*;

#[derive(Clone, Copy)]
enum Message {
    Increment,
    Reset,
}

struct Counter {
    count: i32,
}

impl Component for Counter {
    type Input = ();
    type Message = Message;

    fn create(_input: &(), _context: &ComponentContext<Self>) -> Self {
        Self { count: 0 }
    }

    fn update(&mut self, message: Message, _context: &ComponentContext<Self>) {
        match message {
            Message::Increment => self.count += 1,
            Message::Reset => self.count = 0,
        }
    }

    fn view(&self, _input: &(), context: &mut ViewContext<Self>) -> View {
        let content = StackPanel::new().spacing(8.0).children((
            format!("Count: {}", self.count),
            Button::new()
                .on_click(context.message(Message::Increment))
                .content("Increment"),
            Button::new()
                .on_click(context.message(Message::Reset))
                .content("Reset"),
        ));

        context.window_frame("Counter", content)
    }
}

fn main() {
    App::run_component::<Counter>(()).unwrap();
}

Run with cargo run. Applications use the default features and an installed Windows App SDK
runtime. See the setup guide for runtime prerequisites and self-contained deployment.

The getting-started guide covers editable state, child components, background work, images,
and application windows. Browse the samples for complete applications and focused examples.

Overview (`crates/libs/reference/readme.md`) Copy Section

windows-reference Copy Chapter

The windows-reference crate implements
IReference<T> for boxed Windows values.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-reference]
version = "0.100"

use windows_reference::*;

let value = IReference::<i32>::from(42);
assert_eq!(value.Value().unwrap(), 42);

Overview (`crates/libs/registry/readme.md`) Copy Section

windows-registry Copy Chapter

The windows-registry crate reads and writes the Windows
registry.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-registry]
version = "0.100"

use windows_registry::*;

fn main() -> Result<()> {
    let key = CURRENT_USER.create(r"software\windows-rs")?;

    key.set_u32("number", 123)?;
    key.set_string("name", "Rust")?;

    println!("{}", key.get_u32("number")?);
    println!("{}", key.get_string("name")?);

    Ok(())
}

Overview (`crates/libs/result/readme.md`) Copy Section

windows-result Copy Chapter

The windows-result crate provides Windows error types for
Win32, COM, and WinRT APIs.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-result]
version = "0.100"

Use the HRESULT, Error, and specialized Result types as needed:

use windows_result::*;

const S_OK: HRESULT = HRESULT(0);
const ERROR_CANCELLED: WIN32_ERROR = WIN32_ERROR(1223);
const E_CANCELLED: HRESULT = ERROR_CANCELLED.to_hresult();

fn main() -> Result<()> {
    S_OK.ok()?;
    let e = Error::new(E_CANCELLED, "test message");
    assert_eq!(e.code(), E_CANCELLED);
    assert_eq!(e.message(), "test message");
    Ok(())
}

Overview (`crates/libs/services/readme.md`) Copy Section

windows-services Copy Chapter

The windows-services crate implements Windows service
processes.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-services]
version = "0.100"

windows_services::Service::new()
    .can_pause()
    .can_stop()
    .run(|_service, _command| {})
    .unwrap();

Overview (`crates/libs/strings/readme.md`) Copy Section

windows-strings Copy Chapter

The windows-strings crate provides Windows string types
and literals.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-strings]
version = "0.100"

Use the Windows string types as needed:

use windows_strings::*;

const A: PCSTR = s!("ansi");
const W: PCWSTR = w!("wide");

fn main() {
    let b = BSTR::from("bstr");
    let h = HSTRING::from("hstring");

    assert_eq!(b, "bstr");
    assert_eq!(h, "hstring");

    assert_eq!(unsafe { A.to_string().unwrap() }, "ansi");
    assert_eq!(unsafe { W.to_string().unwrap() }, "wide");
}

Overview (`crates/libs/sys/readme.md`) Copy Section

windows-sys Copy Chapter

The windows-sys crate provides raw Windows API declarations, structs, and constants without
wrappers or helper traits.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-sys]
version = "0.100"
features = [
    "handleapi",
    "synchapi",
    "winuser",
]

Make use of any Windows APIs as needed:

use windows_sys::{core::*, Win32::*};

unsafe {
    let event = CreateEventW(std::ptr::null_mut(), 1, 0, std::ptr::null());
    SetEvent(event);
    WaitForSingleObject(event, 0);
    CloseHandle(event);

    MessageBoxA(0 as _, s!("Ansi"), s!("Caption"), MB_OK as u32);
    MessageBoxW(0 as _, w!("Wide"), w!("Caption"), MB_OK as u32);
}

Overview (`crates/libs/threading/readme.md`) Copy Section

windows-threading Copy Chapter

The windows-threading crate wraps the Windows thread
pool.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-threading]
version = "0.100"

Submit work to the default pool:

windows_threading::submit(|| {
    println!("thread: {}", windows_threading::thread_id());

    loop {
        println!(".");
        windows_threading::sleep(1000);
    }
});

Process an iterator in parallel:

let counter = std::sync::RwLock::<usize>::new(0);

windows_threading::for_each(0..10, |value| {
    println!("thread: {}, value: {value}", windows_threading::thread_id());
    let mut counter = counter.write().unwrap();
    *counter += value;
});

assert_eq!(*counter.read().unwrap(), 45);

Overview (`crates/libs/time/readme.md`) Copy Section

windows-time Copy Chapter

The windows-time crate provides Windows TimeSpan and
DateTime values with Rust constructors, arithmetic, and std::time conversions.

• Getting
  started

TimeSpan is a duration and DateTime is a point in time. Both use 100-nanosecond ticks.

Start by adding the following to your Cargo.toml file:

[dependencies.windows-time]
version = "0.100"

Use the time types as needed:

use windows_time::*;

let span = TimeSpan::from_minutes(90);
assert_eq!(span.whole_seconds(), 5400);

let start = DateTime::from_unix_secs(1_000_000_000);
let later = start.checked_add(span).unwrap();
assert_eq!(later.unix_secs(), 1_000_005_400);

Overview (`crates/libs/version/readme.md`) Copy Section

windows-version Copy Chapter

The windows-version crate reads the Windows version
without relying on the application manifest.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-version]
version = "0.100"

use windows_version::*;

println!("Current version: {:?}", OsVersion::current());

if is_server() {
    println!("Running on a Windows Server release.");
}

if OsVersion::current() >= OsVersion::new(10, 0, 0, 12345) {
    println!("Can use a feature available on this version or later.")
}

Overview (`crates/libs/webview/readme.md`) Copy Section

windows-webview Copy Chapter

Windows WebView wraps the WebView2 COM APIs to host Microsoft Edge
(Chromium) in a window.

The crate has no default UI framework. Enable system for a complete windows-window host or
reactor for a WebView2 control in a Reactor view. Enable both when an application uses both host
types.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies]
windows-webview = { version = "0.100", features = ["system"] }

WebViewWindowBuilder::run owns the COM apartment, parent window, WebView2 environment and
controller, resize handling, shutdown order, and the application's windows-window message loop:

use windows_webview::*;

fn main() -> Result<()> {
    WebViewWindow::new("WebView2")
        .size(1000, 700)
        .run(|host| {
            host.webview()
                .navigate("https://github.com/microsoft/windows-rs")?;
            Ok(())
        })
}

Use WebViewHost::builder when another framework owns the parent HWND and message loop. It chains
environment and controller creation into one callback and returns one host object for the
framework to retain. The raw-window sample shows the raw HWND
contract. The reactor sample embeds WebView2 in a Reactor view,
while reactor-window uses Reactor controls to drive a
WebView hosted in a separate windows-window.

Overview (`crates/libs/window/readme.md`) Copy Section

windows-window Copy Chapter

The windows-window crate provides basic window creation
and message-loop support for Canvas, WebView2, and custom rendering.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows-window]
version = "0.100"

use windows_window::*;

fn main() -> Result<()> {
    let window = Window::new("Hello")
        .client_size(800, 600)
        .on_resize(|width, height| {
            println!("resized to {width} x {height}");
        })
        .on_close(|| {
            println!("release HWND-hosted resources here");
        })
        .quit_on_close(true)
        .create()?;

    // `window.hwnd()` can be handed to windows-canvas, WebView2, Direct2D, etc.
    println!("created window {:?}", window.hwnd());

    run();
    Ok(())
}

Overview (`crates/libs/windows/readme.md`) Copy Section

windows Copy Chapter

The windows crate provides Rust bindings for Win32, COM, and
WinRT APIs generated from
Windows metadata.

• Getting
  started

Start by adding the following to your Cargo.toml file:

[dependencies.windows]
version = "0.100"
features = [
    "Data_Xml_Dom",
    "handleapi",
    "synchapi",
    "winuser",
]

Make use of any Windows APIs as needed:

use windows::{core::*, Data::Xml::Dom::*, Win32::*};

fn main() -> Result<()> {
    let doc = XmlDocument::new()?;
    doc.LoadXml(h!("<html>hello world</html>"))?;

    let root = doc.DocumentElement()?;
    assert!(root.NodeName()? == "html");
    assert!(root.InnerText()? == "hello world");

    unsafe {
        let event = CreateEventW(None, true, false, None);
        if event.is_null() {
            return Err(Error::from_thread());
        }
        SetEvent(event).ok()?;
        WaitForSingleObject(event, 0);
        CloseHandle(event).ok()?;

        MessageBoxA(None, s!("Ansi"), s!("Caption"), MB_OK as u32);
        MessageBoxW(None, w!("Wide"), w!("Caption"), MB_OK as u32);
    }

    Ok(())
}

Overview (`crates/tests/bench/readme.md`) Copy Section

test_bench

A side-by-side WinRT projection benchmark. Three consumers call the identical Rust WinRT
component, so every per-call delta is projection cost.

The cswinrt project is a focused CsWinRT 3.0 preview probe rather than a benchmark column. The
preview package builds on plain net10.0, but it does not contain the WinRT.Interop assembly
that its delegate marshaller loads. The probe fails at the first event subscription and its Cargo
test remains ignored until a complete preview ships.

The component (component -> bench_component.dll) is a real WinRT component: RDL -> winmd ->
windows-bindgen -> #[implement], activated registration-free via DllGetActivationFactory. It
exposes one activatable class, Bench.Widget, with scalar, string, metadata Object, nullable
reference, async, event, vector, map, and view operations. A non-default INonDefault interface
provides the QueryInterface fixture, and LiveCount reports native ownership balance.

Running Copy Chapter

# Full run (10,000,000 iterations, median of three runs by default)
crates/tests/bench/run.ps1

# Quick run
crates/tests/bench/run.ps1 -Iterations 100000 -Runs 1

run.ps1 builds the component first so its metadata writer does not race a consumer build, builds
the three consumers, stages bench_component.dll as Bench.dll, and prints median throughput,
memory, and leak values. The lower native result and the CsWinRT result are bold.

Each consumer also has a cargo test that runs the same path with a small iteration count, so CI
exercises the matrix wherever the .NET SDK and MSVC toolchain are present.

Results Copy Chapter

Measured on August 5, 2026 with .NET SDK 10.0.302 and CsWinRT 2.3.1. Times are milliseconds for
10,000,000 operations (median of three runs); Error uses 1,000,000 operations. Lower is better.

Metrics Copy Chapter

The timed bodies use the same loop bounds, inputs, result retention, collection sizes, and reduced
error count wherever the public projection surfaces permit. CsWinRT finalization is forced outside
affected timers so cleanup does not contaminate the following metric.

The GetMany row requests the same final result through each public projection. windows-rs and
C++/WinRT expose the WinRT GetMany method directly. CsWinRT maps IVector<T> to IList<T>, so
its public CopyTo adapter loops over GetAt.

The Error row highlights projection error models. Rust observes a failed HRESULT as a Result
branch. C++/WinRT and CsWinRT throw and catch exceptions, so this row uses a reduced loop count.

The leak row checks native AddRef/Release balance. Rust and C++/WinRT release deterministically
at scope exit. CsWinRT returns to baseline after GC.Collect() and
WaitForPendingFinalizers() because an RCW retains its native reference until finalization.

To add a metric, emit a matching Name: <ms> ms line from every consumer and add its name to the
$Metrics array in run.ps1.

Overview (`crates/samples/reactor/content-dialog/readme.md`) Copy Section

ContentDialog default button

Run cargo run -p reactor-content-dialog.

Choose a default button, then press Enter in the dialog. WinUI highlights the default button and
normally focuses it when the dialog opens. The result is shown after the dialog closes; Cancel
returns ContentDialogResult::None.

The editor case shows the focus exception: a multiline TextBox receives focus and consumes Enter
to insert a line instead of closing the dialog. Tab moves focus to the buttons.

ContentDialogButton::None removes the default-button designation, not the buttons' own keyboard
behavior. A focused button can still respond to Enter.

Overview (`crates/samples/reactor/font-icon/readme.md`) Copy Section

FontIcon size and foreground

Run cargo run -p reactor-font-icon.

FontIcon::new()
    .glyph("\u{E80F}")
    .font_size(48.0)
    .foreground(ThemeBrush::PrimaryText)

Compare small red and large blue glyphs, a theme-aware foreground, and the native defaults on the
same icon. "Toggle theme" switches the window between light and dark.

Without a foreground override, the preview inherits its color from the surrounding HyperlinkButton.
"Native defaults" removes both overrides, restoring the native font size and inherited foreground.
font_size accepts finite positive values. foreground accepts a Color or a ThemeBrush.

Overview (`crates/samples/reactor/gallery/readme.md`) Copy Section

Reactor gallery

This sample is the windows-reactor port of the WinUI control gallery. It contains 65
destinations across 11 categories:

• Basic Input
• Collections
• Date and Time
• Design Guidance
• Dialogs and Flyouts
• Layout
• Media
• Menus and Toolbars
• Navigation
• Status and Info
• Text

Run it with:

cargo run -p reactor-gallery

The shell uses a generated TitleBar and NavigationView. The pane lists categories by default.
Select a category to open its card grid, then select a card to open the control page. Search
replaces the category links with matching control destinations. Back navigation follows the
shell's page history.

Each control destination is a component under src/pages/. Pages use controlled state for live
examples such as text input, sliders, selection controls, dialogs, progress indicators, and layout
changes. Page-owned state is recreated when a destination is retired and later reopened. Window
state, including the selected theme and backdrop material, belongs to the shell and persists across
page replacement.

For implementation examples, read the compiled page components in src/pages/.
The gallery does not duplicate them as display-only source snippets, which can drift from the
working examples.

The gallery is organized as follows:

Bundled images in assets/ are loaded through Image::source_file. Sample cards use WinUI theme
brushes so their surfaces follow the selected light, dark, or system theme. The Materials page
changes the live window backdrop between Mica, Mica Alt, Acrylic, and a solid background.

The gallery uses generated GridView selection feedback, BreadcrumbBar item-click events, and
the Viewbox child slot. Flyout, SplitButton, TabView, and InfoBar examples use their native event
and ownership contracts rather than substituting pointer handlers.

Recording-runtime tests mount the full gallery, replace pages through shell navigation, mount every
registered destination, drive representative controlled input, reject events from retired pages,
and verify that shell-owned theme and backdrop state survives page replacement.

Overview (`crates/samples/reactor/navigation/readme.md`) Copy Section

Navigation and multi-window workspace

This sample qualifies navigation and window isolation by opening a secondary workspace from the
primary at runtime. A SplitView hosts the navigation pane and current page through generated
typed slots. Each window owns its page, editor text, focus reference, background work, and
component queue. The windows share a small application model that broadcasts theme changes and
window-lifecycle notifications.

Run it with:

cargo run -p reactor-navigation

Try this sequence:

1. Choose Open secondary window, then open the editor in each window and enter different text.
2. Move between Home and Editor and confirm each window retains its own text.
   The window title follows the current page.
3. Change the shared theme and confirm both windows update.
4. Start background work in the secondary window, then choose Close this window.
5. Confirm the primary window remains responsive and reports the secondary closure.

ComponentContext::open_window stages an independent root with the current component publication.
After publication, the host registers a pending open and mounts that root in a new Pump. The
opener's scope does not own the new Pump. Close requests use the same transactional boundary and
are applied only after publication. Each workspace declares its native title from component state.
Declarative size configuration remains deferred rather than being hidden in the sample with direct
WinUI calls.

Overview (`crates/samples/reactor/number-box/readme.md`) Copy Section

NumberBox options

Run cargo run -p reactor-number-box.

NumberBox::new()
    .small_change(0.25)
    .spin_button_placement_mode(NumberBoxSpinButtonPlacementMode::Inline)

Compare hidden, inline, and compact spinner buttons. The compact popup appears when the control
receives focus. Up/Down and the spinner buttons use small_change; values remain between 0 and 20.
small_change accepts finite f64 values.

The step button switches between 0.25 and 2. "Use native defaults" removes both properties from the
existing controls, restoring a step of 1 and hidden buttons. The headers identify the custom modes;
all three use hidden buttons while the overrides are removed.

Overview (`crates/samples/reactor/startup_perf/readme.md`) Copy Section

Windows Reactor startup tracing sample

This blank app demonstrates TraceLogging events across the Windows Reactor startup lifecycle. It
renders one static TextBlock in a 1000x1000 window.

The app uses the ETW team's tracelogging crate to emit TraceLogging events from the
BenchmarkSyntheticApps provider:

• Provider GUID: FD80D616-E92B-4B2B-9BED-131ADA36A8FD
• Keyword: 0x0000400000000000
• App name: blank_windows_reactor
• Process name: blank-windows-reactor.exe

Every event includes AppName, Seq, and Pid fields.

Run the framework-dependent app with:

cargo run -p reactor-startup-perf --release

MSIX package Copy Chapter

Run these commands from the repository root:

1. Install Windows App Development CLI 0.5.0 or later, or upgrade an existing installation:

   powershell Copy

   # First installation:
   winget install Microsoft.WinAppCli --source winget
   
   # Existing installation:
   winget upgrade Microsoft.WinAppCli --source winget
   
   winapp --version

2. Build the app and prepare the package layout:

   powershell Copy

   cargo build -p reactor-startup-perf --release --quiet
   $work = "target\reactor-startup-msix"
   $layout = "$work\layout"
   Remove-Item $layout -Recurse -Force -ErrorAction Ignore
   New-Item $layout -ItemType Directory | Out-Null
   Copy-Item `
       target\release\blank-windows-reactor.exe `
       $layout
   $output = "$work\blank-windows-reactor_x64.msix"
   $manifest = "crates\samples\reactor\startup_perf\package\Package.appxmanifest"

3. Create an unsigned package:

   powershell Copy

   winapp pack $layout --manifest $manifest --output $output --skip-pri

   To sign without a timestamp, use one winapp pack call:

   powershell Copy

   $certificate = "C:\certificates\package.pfx"
   $securePassword = Read-Host "Certificate password" -AsSecureString
   $certificatePassword = [Net.NetworkCredential]::new("", $securePassword).Password
   winapp pack $layout `
       --manifest $manifest `
       --output $output `
       --skip-pri `
       --cert $certificate `
       --cert-password $certificatePassword

   winapp pack cannot timestamp a signature. For timestamped signing, package first and then
   sign:

   powershell Copy

   $certificate = "C:\certificates\package.pfx"
   $timestampUrl = "https://timestamp.example.com"
   $securePassword = Read-Host "Certificate password" -AsSecureString
   $certificatePassword = [Net.NetworkCredential]::new("", $securePassword).Password
   winapp pack $layout --manifest $manifest --output $output --skip-pri
   winapp sign $output `
       $certificate `
       --password $certificatePassword `
       --timestamp $timestampUrl

The checked-in manifest uses version 1.0.0.0 and the Microsoft corporate publisher. Update its
Identity before packaging if either value needs to change. The publisher must exactly match the
signing certificate subject.

WinApp CLI accepts local and UNC certificate paths, but it passes the path directly to signtool;
copy the PFX locally first if the signing environment does not allow signtool to read the share.
Certificate passwords are command-line arguments because WinApp CLI does not provide a secure input
or environment-variable option.

The package remains framework-dependent. Install Microsoft.WindowsAppRuntime.2.msix on the target
machine before launching it.

Overview (`crates/samples/reactor/text-block-alignment/readme.md`) Copy Section

TextBlock alignment

Run cargo run -p reactor-text-block-alignment.

TextBlock::new()
    .text("Centered text")
    .text_alignment(TextAlignment::Center)

text_alignment positions text within the TextBlock's available width. horizontal_alignment
positions the TextBlock itself. The sample compares left, centered, and right text in stretched
controls with a centered, content-sized control. Resize the window to see the difference.

TextBlock and TextBox share Reactor's TextAlignment enum. Canvas has a separate TextAlignment
for DirectWrite; qualify the type or use an import alias when using both crates.

Updating or omitting text_alignment keeps the native TextBlock. Omitting a previously declared
alignment clears its local value and lets WinUI supply the alignment again.

Overview (`crates/samples/reactor/text-box-read-only/readme.md`) Copy Section

Read-only TextBox

Run cargo run -p reactor-text-box-read-only.

Both fields allow selection and copying without editing. The second uses text_alignment to center
its text inside the stretched control. Resize the window to see the difference.

Overview (`crates/samples/reactor/translation-transition/readme.md`) Copy Section

Translation transition

Run cargo run -p reactor-translation-transition.

Open and close the panel, or click again while it is moving to reverse direction. Translation is a
visual offset in DIPs; it does not change the space reserved by layout or remove the panel.

Overview (`crates/samples/reactor/virtual/readme.md`) Copy Section

Virtual task editor

This sample qualifies windows-reactor virtualization with application behavior rather than
static labels. It includes:

• keyed row components with controlled TextBox and ToggleSwitch values;
• front insertion, removal, move-to-end, reversal, and a 1,000-item reset;
• direct selection input for each keyed row;
• validation and queued typed focus;
• keyed row effects and cleanup on recycle;
• background loading with scope-owned cancellation;
• conditional row content;
• same-key payload updates and key-changing source resets.

Run it with:

cargo run -p reactor-virtual

The same component model has a feature-gated RecordingRuntime performance driver. Run it in
release mode:

cargo run -p reactor-virtual --bin reactor-virtual-perf `
    --features perf --release -- --samples 500

The driver measures local editing, broad and redundant parent messages, an unchanged root-component
memo hit, a forced value-equal root recomposition, 32-row recycle/realize batches, background
completion, and a mixed virtual cycle. It reports allocator traffic and median, p95, and p99
Rust-side turn time. It also measures value-equal declaration scaling at 1,000, 10,000, and 100,000
tasks. It does not include WinUI control work, layout, rendering, or presentation.

The live driver adds CompositionTarget::Rendering frame intervals and host/native phase timing:

cargo run -p reactor-virtual --bin reactor-virtual-live-perf `
    --features perf --release -- --samples 300
cargo run -p reactor-virtual --bin reactor-virtual-live-perf `
    --features perf --release -- --baseline --samples 300

The active run moves by 32 virtual indices per frame, alternates selection, edits a
controlled row every six frames, and delivers a background completion every 30 frames. The
baseline opens the same 1,000-item editor without scheduling those actions. Each command writes a
report next to the executable. After the measured frames, the driver also verifies that queued
recycle and source-reset work left no retired WinUI shell tokens. A machine that emits no
composition frames writes an explicit failure report and exits unsuccessfully after 20 seconds.

The durable task title belongs to TaskEditor, not the realized row component. A row component is
retained across key-stable payload updates, but native virtualization or a source reset may recycle
it. Non-empty controlled drafts update that model immediately; a blank validation draft remains
row-local and falls back to the last valid model value after recycling. The recording-runtime test
enters edit mode, checks queued focus, edits a task, explicitly recycles it, reverses the source,
and verifies that its title survives each re-realization with one cleanup per retired row effect.

The buttons provide a deterministic manual stress sequence:

1. Select a row, enter edit mode, and change its title.
2. Reverse or move the source and confirm the title remains in the task model.
3. Add and remove rows at the front.
4. Load another 100 rows in the background.
5. Reset to 1,000 rows and repeat edits while scrolling.

Overview (`crates/samples/windows/dcomp/readme.md`) Copy Section

This sample first appeared in Kenny's DirectComposition course on Pluralsight. Check it out to learn all about DirectComposition, Direct2D, and DirectWrite, image decoding, and animation.

Overview (`crates/samples/windows/direct3d12/readme.md`) Copy Section

Overview (`crates/samples/windows/spellchecker/readme.md`) Copy Section

Windows SpellChecker

A sample showing how to use the Windows spell-checking API (ISpellCheckerFactory, ISpellChecker)
from the windows crate. It checks a line of text from the command line and prints corrections to
standard out.

Running Copy Chapter

Make sure you have Rust installed, and then run the following:

cargo run -- "This is text with a word missspelled!"

Overview (`crates/samples/windows/uiautomation/readme.md`) Copy Section

UI Automation Copy Chapter

A simple example using the new UI Automation API. This sample requires Windows 11.

Overview (`crates/tests/libs/reactor/readme.md`) Copy Section

Reactor tests

test-reactor is the home for the new Cargo-based Reactor tests. It lives alongside the existing
selftest, integration, and performance crates without depending on their harnesses or Reactor's
test feature. Add new cases here and migrate existing coverage individually. Remove an old case
only after its replacement proves the same behavior; retire old helpers when their consumers are
gone.

The crate uses the public Reactor API, direct Windows UI Automation, and the Rust standard library.
build.rs generates only the required native bindings into OUT_DIR using windows-bindgen and
stages the host's private Windows App Runtime using windows-reactor-setup.
There are no generated test cases, external runners, or dependencies on the windows crate.

Running Copy Chapter

cargo test -p test-reactor

On x64 this runs the automated suite, including live WinUI cases and harness failure checks. It requires
an interactive desktop. Cargo deploys the runtime; no machine-wide runtime installation is needed.
The first build needs network access to download the pinned runtime packages. Five native drag/drop
cases are explicitly ignored; see Opt-in drag/drop coverage. Foreground
or focus failures do not silently skip tests. Do not interact with other applications while the
suite runs. Standard Cargo name filters can select individual cases during development.

The crate also runs in the ordinary workspace test command. Other workspace packages can enable
Reactor's legacy test feature through Cargo feature unification; this fixture still uses only the
public application API and real WinUI. The package-only command covers the default-feature build.

The ui integration target is x64-only. The existing x64 workspace job runs the live suite; x86 and
ARM64 build the fixture and run windows-reactor-setup's filesystem and multiprocess tests as part
of workspace testing. This is an explicit architecture boundary, not a runtime skip when focus
or foreground is unavailable.

Layout Copy Chapter

The library contains the application fixtures. Cargo's integration-test harness supplies the
host executable's path without filesystem searches or a child mode in the test runner. Keeping the
host separate gives WinUI its own main thread and application lifetime. The binary's test = false
disables its empty unit-test harness, not the behavioral tests.

Each UI case launches the Cargo-built test-reactor executable in a fresh process. The suite
serializes desktop cases even with Cargo's default thread count. UI Automation runs on an MTA
worker, while the test thread watches the child and enforces a 30-second deadline, including blocked
UIA calls. Success requires completed assertions and a successful exit after closing the fixture's
own window. Failure cancels further driver work and terminates the owned child.

The driver timeout regressions use the same supervisor as live UI cases, with short private
deadlines and synthetic workers rather than COM calls. Each case releases and joins its worker
before asserting the outcome. Live cases retain the 30-second deadline and five-second cleanup
allowance.

The driver uses exact automation IDs, or exact name and control type for menu items, scoped to the
child's windows. Repeated entries for the same native element count once; distinct matching elements
are an error. Waits inspect current UI state; they do not force layout or synthesize Reactor
callbacks. UIA invocation, Value edits, and keyboard input are separate operations. Keyboard injection
checks the foreground process, focused element, and modifier keys.

Button-menu cases use UIA Invoke to exercise WinUI's menu actions, not synthetic Reactor events.
They retain old invoke providers across content, attachment, and owner changes, check popup closure
including the submenu entry, and invoke retired providers before and after opening a replacement.
Retired invocations must leave both the callback count and the replacement popup unchanged. Current
items must deliver the expected key and callback generation exactly once; callback counts are
observed for 250 ms to detect extra deliveries. These tests cover button menus. Dropdown, menu-bar,
command-bar, and tray surfaces remain in the legacy integration fixture.

Pointer cases use SendInput with physical virtual-desktop coordinates derived from UIA anchor
bounds. The fixture's Border has no UIA peer; short text anchors locate its bare background without
clicking the text itself. Guards check foreground ownership, the window under button input, and
held buttons/modifiers. The supervisor owns button cleanup, so cancellation or a blocked UIA worker
cannot leave cleanup dependent on that worker returning. A case that finishes with an injected
button still pressed fails.

The policy fixtures install no press/release callbacks on the target. Capture and release are
observed through native movement routing, not a stored policy or capture flag. Focus is observed
through the target's direct native focus event; setting focus on the baseline button is a separate
driver action. Dynamic cases omit the policy entirely at mount, exercise that state, and then enable
it while preserving the UIA anchor's identity. They do not set the policy to false initially, since
that setter can itself activate a lazy native subscription.

Cargo captures driver steps and assertion failures. On a condition timeout the driver also prints
the fixture's UI tree. Child stdout and stderr are written to separate files to avoid blocked pipes;
failures report the log directory under the system temporary directory. Successful cases remove
their logs. The parent deadline still applies if reading the UI tree stalls.

Opt-in drag/drop coverage Copy Chapter

The native drag/drop cases are preserved from PR #5115, but are not part of the default automated
suite. WinUI does not support this drag/drop path in elevated processes
(microsoft/microsoft-ui-xaml#7690).
GitHub-hosted Windows runners run as administrator. The tests use #[ignore = "..."] so Cargo reports
them as ignored, not passed. Explicitly running them elevated fails before launching a fixture.
No runner-specific skip, token manipulation, or automatic elevation change is used.

Run the policy and failure-cleanup cases from a non-elevated terminal on an idle interactive desktop:

cargo test -p test-reactor --test ui drop_policy -- --ignored
cargo test -p test-reactor --test ui drag_source_is_stopped_after_driver_failure -- --ignored

The cancellation case also has an unresolved intermittent UIA timeout (0x80131505) after
cancellation. Keeping the source window and its STA alive across drags has not eliminated that
failure. It remains an opt-in regression case, not evidence that cancellation is reliable:

cargo test -p test-reactor --test ui cancelled_drag_can_be_restarted -- --ignored --nocapture

To run all five opt-in cases, including the unresolved cancellation regression:

cargo test -p test-reactor --test ui -- --ignored

The source is a native window on a dedicated OLE STA in the fixture process. It receives injected
input and runs DoDragDrop, leaving WinUI free to render policy changes and read dropped data.
It advertises only CF_UNICODETEXT. Assertions require source-reported hover operations, the final
OLE operation, and a text read, not just a Copy cursor. The target has no drag/drop callbacks that
could mask policy-only activation.

The source window and STA live for the fixture session. Each drag owns its data and feedback
objects. Normal shutdown joins the UIA driver before closing the fixture, which stops and joins the
source thread. The OLE callback checks cancellation and a 20-second deadline; the existing parent
supervisor still bounds blocked native calls. No UIA timeout is retried or treated as success.

App-process coverage Copy Chapter

The pilot uses compiler instrumentation and the llvm-tools Rust toolchain component, without a
Cargo coverage plugin. In a fresh PowerShell session at the repository root:

$ErrorActionPreference = "Stop"
$PSNativeCommandUseErrorActionPreference = $true
$target = Join-Path $PWD "target\reactor-ui-coverage"
$profiles = Join-Path $target ("profiles-" + [Guid]::NewGuid())
New-Item -ItemType Directory $profiles | Out-Null
$env:RUSTFLAGS = "-C instrument-coverage"
$env:LLVM_PROFILE_FILE = Join-Path $profiles "%p-%m.profraw"
cargo test -p test-reactor --target-dir $target
$sysroot = rustc --print sysroot
$hostTriple = (rustc -vV | Select-String "^host: ").ToString().Substring(6)
$llvm = Join-Path $sysroot "lib\rustlib\$hostTriple\bin"
$raw = @(Get-ChildItem $profiles -Filter "*.profraw")
& "$llvm\llvm-profdata.exe" merge -sparse $raw.FullName -o "$profiles\ui.profdata"
& "$llvm\llvm-cov.exe" show "$target\debug\test-reactor.exe" `
    "-instr-profile=$profiles\ui.profdata" `
    '--include-filename-regex=native[\\/]+winui[\\/]+(hosting|events)\.rs$'

The unique profile directory prevents earlier runs from contributing counts. Child processes
inherit the profile pattern, and %p-%m separates their output. Report against test-reactor.exe,
not just the integration-test driver: the native Reactor code runs in the fixture. The source filter
above shows the menu callback update and native text setter paths exercised by these cases. This
is a pilot path report, not an overall Reactor coverage percentage or a replacement for the core
coverage job. Close the PowerShell session afterwards to discard the instrumentation environment.

Overview (`crates/tests/libs/reactor_bench/readme.md`) Copy Section

Reactor benchmark

This benchmark measures Reactor retained updates, component scheduling, lifecycle work,
virtualization, and memory attribution without WinUI layout or rendering.

cargo run -p test-reactor-bench --release --quiet
cargo run -p test-reactor-bench --release --quiet -- --count 4096 --samples 40 --batch 4
cargo run -p test-reactor-bench --release --quiet -- --architecture-gate
cargo run -p test-reactor-bench --profile profiling --quiet -- --retained-memory --count 512

The output includes median and p95 update time, allocated bytes and allocation count per update,
retained bytes per object, isolated component updates, and retained component-scope memory.
Component rows also cover isolated and all-consumer typed-context invalidation, same-type updates,
and retained-root type replacement.

The recursive component rows build balanced trees, target the deepest leaf, and report retained
bytes per scope, update latency, allocations, allocated bytes, and mutation count. The timed
updates disable recording-adapter batch validation because that diagnostic intentionally clones
the complete adapter state.

The --architecture-gate mode uses six samples by default and reports:

• Keyed no-change and one-property-change updates across two 50,000-object graphs in one timed
  operation. Reactor enforces a 65,536-object limit per graph.
• Controlled 513-node memory fixtures that separate declaration construction, retained
  graph storage, string properties, events, TreeNode relation shape, and recording-adapter storage.
• Root-type replacement and middle-child removal in a 16,384-component graph.

Use --gate-samples or --component-count to override the gate defaults.

The --retained-memory mode releases benchmark scratch buffers after mounting and reports live
retained-graph allocations separately from declarations and adapter state. It prints release
layout sizes and additive slot, relation, child-vector, property/event, virtual, and retirement
storage for keyed and unkeyed flat trees, a deep chain, relation-heavy controls, TreeNode
structural objects, a virtual source, and an active retirement.

No-op allocation, changed-update allocation, retained memory, and large-tree scaling are separate
gates.

Overview (`crates/tests/libs/reactor_integration/readme.md`) Copy Section

Reactor public integration tests

These isolated executables exercise the public application API without Reactor's test feature.
Build this package separately from privileged selftests and benchmarks so Cargo does not unify
their diagnostic features into this build.

cargo check -p test-reactor-integration --all-targets
cargo run -p test-reactor-integration --bin application_lifecycle -- replacement
cargo run -p test-reactor-integration --bin application_lifecycle -- multiple
cargo run -p test-reactor-integration --bin application_lifecycle -- startup-error
cargo run -p test-reactor-integration --bin application_menu
cargo run -p test-reactor-integration --bin application_menus
cargo run -p test-reactor-integration --bin menu_lifetimes -- dropdown
cargo run -p test-reactor-integration --bin application_resources -- lifecycle
cargo run -p test-reactor-integration --bin application_dispatch -- application
cargo run -p test-reactor-integration --bin application_dispatch -- notification
cargo run -p test-reactor-integration --bin tray_flyout
cargo run -p test-reactor-integration --bin menu_position -- thread-unaware
cargo run -p test-reactor-integration --bin canvas_integration
cargo run -p test-reactor-integration --bin webview_integration
cargo run -p test-reactor-integration --bin window_state
cargo run -p test-reactor-integration --bin window_observers
cargo run -p test-reactor-integration --bin window_theme
cargo run -p test-reactor-integration --bin title_bar

Each executable owns its application lifetime and watchdog. The lifecycle fixture covers
last-window replacement, multiple-window shutdown, and startup errors. The menu fixture checks
application-lifetime work after its Reactor window closes. The application-resource fixtures cover
declarative window and icon lifetimes, nested dispatch, and menu replacement and selection.
The notification dispatch mode sends interactions and recovery requests to its own callback window
during nested component and application updates, and checks that queued events cannot outlive icon
removal.
The tray-flyout fixture uses an application-owned icon and checks that its menu overlaps the icon's
monitor, extends outside that monitor's work area, and closes during application shutdown.
It measures menu-item bounds through UI Automation rather than the popup window's shadow bounds,
and requires a running Windows shell with a notification area. Companion-crate fixtures exercise
Canvas drawing and WebView initialization. The window-state fixture observes size and icon changes
through the public window callback and Win32 APIs. The window-observer fixture covers callback
replacement without replay, real changes, removal, re-subscription, and independent subscriptions
for color scheme, size, and placement. It also covers removal and re-subscription within one drain,
handoff from a parent to a child, and replacement of the subscribing child. The title-bar fixture
opens a second window from a running application and checks through UI Automation that its
TitleBar right header keeps the same
caption-button inset as the first window.

Run window_theme on an interactive desktop. It temporarily makes its windows topmost without
activation to sample their rendered backgrounds.

Run menu_lifetimes with dropdown, menubar, command, or tray on an interactive desktop.
It uses process-scoped UI Automation and notification messages sent to its own icon. Button-menu
lifetimes are covered by the named Cargo tests in test-reactor.

The menu-position fixture covers pmv2, unaware, system, and thread-unaware DPI modes. It
checks exact physical host bounds and restoration of the caller's thread context, including when
a duplicate menu request is rejected. Run on a display scaled above 100% to exercise coordinate
virtualization.

Use --features self-contained to run with bundled Windows App SDK dependencies. Otherwise,
the Windows App Runtime must be installed. WebView tests also need the WebView2 runtime.

Overview (`crates/tests/libs/reactor_perf/readme.md`) Copy Section

Reactor stress benchmark

test_reactor_perf compares windows-reactor with the C# Reactor
StressPerf.ReactorOptimized workload:

• 70 columns x 70 rows = 4,900 TextBlock cells;
• deterministic .NET Random(42) data and update sequence;
• a 33 ms update timer;
• at least one randomly selected cell per tick, controlled by --percent;
• cached cell declarations rebuilt only for changed indices;
• snapshot-driven root component updates;
• phase, frame, allocation, and working-set reporting.

Run the live benchmark in release mode:

cargo run -p test_reactor_perf --release -- --headless --percent 10 --duration 10

The report is written next to the executable as StressPerf.Reactor.report.txt. Add --json to
also write StressPerf.Reactor.metrics.json.

The in-app frame counter uses CompositionTarget::Rendering, matching the C# workload. As with the
C# harness, render completion is a better no-admin throughput proxy, and ETW presents are required
for a final user-visible frame-rate comparison.

Overview (`crates/tests/libs/reactor_selftest/readme.md`) Copy Section

Reactor native self-test

This executable runs the Reactor WinUI adapter inside the Reactor application host. Generated
coverage constructs and clears every schema property and event contract. Handwritten phases cover
controlled input, ordered native events, attachments, images, references, pointer injection,
retirement, TreeView content, ListView data, and virtualization.

cargo run -p test-reactor-selftest --quiet
cargo run -p test-reactor-selftest --quiet -- --headless

A watchdog terminates the process with an error if WinUI hangs or the application fails to exit.
Application lifecycle, menu, Canvas, WebView, and window-state fixtures live in
test-reactor-integration. They use the public application
API without enabling Reactor's diagnostic test feature.

Asynchronous phases wait for native readiness rather than assuming a timer tick is sufficient.
The ContentDialog check requests opening before its owner window exists, waits for Opened, then
calls Hide and requires Closed.
Use assertions for failures in component callbacks. Calling process::exit there can run
application teardown while callback state is still borrowed.

CI also runs the self-test and native library tests in debug mode with
RUSTFLAGS="-D warnings --cfg windows_cast_diagnostics". check_casts.ps1 checks their captured
output for unexpected same-pointer QueryInterface calls. Its allowlist covers agility checks,
canonical COM identity, activation, and known conversions from IInspectable; these still require
queries even when the returned pointer is unchanged. Review new diagnostics before adding an
exception. A clean result covers only the paths exercised by those tests.

Run every default Reactor, Composition, and WebView sample long enough to catch startup failures:

powershell -File crates\tests\libs\reactor_selftest\run_samples.ps1

The script builds each package independently, captures runtime stdout and stderr, requires the
process to remain alive for three seconds, and then closes or terminates that process. Use
-RunSeconds, -Family, or -Package to narrow or lengthen a run, and -KeepLogs to retain all
captured output.

Use -Package with -ChangedSince <commit> to run the named packages plus samples changed between
that commit and HEAD. Added files and deleted files within surviving packages count as changes;
removed packages are not run. -List prints the selection without building or launching anything.
The comparison commit must be available locally.

CI Copy Chapter

PRs and master pushes run the native self-test once, with cast diagnostics, and retain the native
regressions, public integration fixtures, deployment checks, isolated feature checks, and public
API snapshot. Workspace unit tests and generation checks belong to test.yml and gen.yml.

The smoke gate runs Counter, Gallery, Workbench, the Reactor Composition host, standalone system
Composition, and Reactor WebView, plus changed or new samples. PRs compare against their base commit;
pushes compare against the previous branch tip, including every commit in the push. Each package
is built independently, and GUI processes run serially.

Scheduled and manually dispatched runs also enforce coverage floors, repeat the native self-test,
and launch every sample. The routine gate targets roughly ten minutes; the exhaustive runs can take
longer. CLI tools use pinned cargo install versions. The public API tool has a separate cache saved
immediately after installation, so a later test failure does not discard the compiled tool.

Run the sample selection checks without starting any windows:

pwsh -File crates\tests\libs\reactor_selftest\test_samples.ps1

Code Of Conduct (`docs/code_of_conduct.md`) Copy Section

Code of conduct Copy Chapter

This project has adopted the Microsoft Open Source Code of Conduct.

Resources:

• Microsoft Open Source Code of Conduct
• Microsoft Code of Conduct FAQ
• Contact [email protected] with questions or concerns

Contributing (`docs/contributing.md`) Copy Section

Contributing Copy Chapter

This project welcomes contributions and suggestions. Most contributions require you to agree to a
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will determine whether you need to provide a CLA and
decorate the PR appropriately (for example, with a status check or comment). Follow the bot's
instructions. You only need to do this once across all repositories using our CLA.

This project has adopted the
Microsoft Open Source Code of Conduct. For more
information, see the
Code of Conduct FAQ or contact
[email protected].

Before Contributing Copy Chapter

Start by
opening a new issue or commenting on
an existing issue to discuss a feature or bug
fix. This lets maintainers and contributors agree on an approach before you spend time on a pull
request. The pull request template therefore asks you to refer to an existing issue.

Dependencies (`docs/dependencies.md`) Copy Section

Dependencies

This page tracks every external SDK, header set, metadata file, and runtime the build and tooling
depend on: the version, where it is pinned, how it is obtained, and how the pin is validated. It
covers build/tooling and runtime dependencies (Windows SDK, WDK, WinRT contracts, libclang,
Windows App SDK, WebView2). It does not cover the crates.io Rust dependencies in Cargo.toml,
which are already centralized under [workspace.dependencies].

The model: one owner, validated by running Copy Chapter

There is no central version registry. Every external dependency has a single owning tool that
declares the pin as a const, downloads/consumes the artifact at that exact version, and runs in CI
(.github/workflows/gen.yml) - so running the tool proves the pin is current, in one of two ways:

• Generators (tool-win32, tool-winrt, tool-webview, tool-reactor-metadata,
  tool-reactor) regenerate
  committed artifacts; gen.yml runs each then git diff --exit-code, so a stale pin produces a
  diff and fails.
• Validators (tool-clang, and guards inside generators) assert invariants and write nothing; a
  violation panics loudly, failing the job with a clean tree.

When one crate must track a pin another crate owns, the owner reads the peer's constant straight
from source with helpers::read_str_const and asserts they
agree. Pins are never copied - they are read back and checked. windows-clang stays a clean
libclang library and is not a shared home for SDK/runtime versions.

At a glance Copy Chapter

Toolchain: libclang Copy Chapter

The header scrapers (tool-win32, tool-webview) parse C/C++ with libclang. The
version is pinned because clang's macro-capture behavior drifts across majors, which would silently
change the generated metadata.

• Owner: provision.rs declares LIBCLANG_VERSION = "22.1.8". libclang.dll comes from the
  libclang.runtime.win-<arch> NuGet packages (dotnet/clangsharp, .NET Foundation) fetched at
  that version. The paired clang builtin resource headers (needed only for the non-x64 arch
  passes, to reconcile the aarch64 __prefetch builtin) come from a blobless, shallow, sparse git
  checkout of clang/lib/Headers at the derived llvmorg-<ver> tag - so the DLL and headers are
  the same single-const pin and can never drift.
• Obtained: if LIBCLANG_PATH is unset, ensure_libclang fetches the pinned
  libclang.runtime.win-<arch> package via nuget_package (the shared NuGet global cache, same as
  the SDK/WDK/WebView2 pins) and points LIBCLANG_PATH at its runtimes/<rid>/native/; non-x64
  passes also fetch the pinned LLVM resource headers via git. LIBCLANG_PATH /
  CLANG_RESOURCE_DIR override for offline machines. All three scrapers call it, so their gen.yml
  jobs need no LLVM install - they always parse with the pinned 22.1.8, in CI and on a fresh
  checkout alike.
• CI: every workflow self-provisions the pinned libclang from NuGet - no CI job installs LLVM.
  The gen.yml scrapers call ensure_libclang; clippy.yml loads no libclang at all
  (cargo clippy never parses); and test.yml, whose windows-clang tests load libclang at
  runtime,
  exports LIBCLANG_PATH from the same pin via `echo "LIBCLANG_PATH=$(cargo run -q -p tool-clang --
  path)"

  "$GITHUB_ENV". tool-clang pathprintshelpers::libclang_dir(), keeping the unsafe set_var` off the multithreaded test runner. The Linux CI jobs build code that needs no libclang.

• Validated by tool-clang: fetches, loads, and version-asserts the pin (the same provisioning
  the scrapers run). Writes nothing.
• To update: bump LIBCLANG_VERSION - a single const that drives both the NuGet DLL and the
  llvmorg-<ver> git tag for the headers, so there is nothing else to touch. Run tool-clang (must
  pass) and regenerate all metadata. No prebuilt-asset ceiling: the DLL comes from NuGet and the
  headers from a git tag, both of which track current LLVM.

Windows SDK, WDK, and WinRT contracts Copy Chapter

Each feeds an in-house generator producing a committed .winmd in windows-default. The metadata
is embedded for Rust build tools and remains available as files for external tools. Provenance is
documented in crates/libs/default/readme.md.

windows-bindgen, windows-rdl, and windows-clang depend on windows-default so their builders
can select this metadata without filesystem paths. Binaries linking those crates include both
metadata files.

• Obtained: windows_clang::nuget_package(id, version) restores from the NuGet global cache or
  downloads from nuget.org (NUGET_PACKAGES overrides the cache).
• tool-win32 runs both scrapes, so the WDK km scrape reuses the same SDK_VERSION headers as
  the um scrape (they share the crate); WDK_VERSION is a separate pin in km.rs.
• The "marketing" include/lib folder nested in each package (e.g. 10.0.28000.0) is derived
  from the version via helpers::marketing_dir (first three components + .0), so the version is
  the single edit - never a second folder constant to keep in sync.
• To update: bump the owning constant, run cargo run -p tool-<win32|winrt>, and commit the
  regenerated .rdl snapshot(s) and .winmd.

CONTRACTS_VERSION happens to share the 10.0.28000 build number with SDK_VERSION, but it is a
distinct NuGet package with its own pin - the two are not coupled and can diverge.

WebView2 Copy Chapter

WebView2 ships only C/C++ SDK headers, so windows-webview is scraped from them. The WinRT Core
metadata and runtime projection DLL are separate artifacts.

• Headers are downloaded, not vendored: tool-webview fetches the pinned NuGet package via
  nuget_package and parses the headers from it. A bump is a one-line WEBVIEW2_VERSION edit.
• Pinned libclang: like tool-win32, tool-webview calls ensure_libclang +
  assert_libclang_version, so it parses with the exact pinned 22.1.8 (its gen.yml job needs no
  LLVM install - only the SDK include paths for the system headers WebView2.h pulls in).
• Runtime projection: bump WEBVIEW2_VER in reactor-setup; it must equal
  WEBVIEW2_VERSION - tool-reactor-metadata asserts this.
• Core.winmd is refreshed into the shared Reactor metadata by tool-reactor-metadata at
  WEBVIEW2_VERSION (see below).

For the full pipeline and COM<->WinRT bridge, see windows-webview.

WinUI / Windows App SDK Copy Chapter

windows-reactor is generated from WinUI / Windows App SDK .winmd; windows-reactor-setup stages
the matching runtime so reactor apps run. Metadata and runtime are two faces of one release, tied to
a single number.

Metadata is regenerated, not hand-copied. tool-reactor-metadata owns
WINDOWS_APP_SDK_VERSION = "2.5.1". On every run it downloads the umbrella
Microsoft.WindowsAppSDK metapackage at that version, reads the exact component versions
(Foundation / InteractiveExperiences / WinUI) pinned in its nuspec, downloads each component, and
copies their .winmd - plus Microsoft.Web.WebView2.Core.winmd at WEBVIEW2_VERSION - into the
committed metadata at crates/tools/reactor-metadata/winmd/. gen.yml re-runs the tool and fails
on any diff, so the metadata provably matches the pin. (extras.winmd in that directory is
generated by tool-reactor-metadata from Windows.Win32.winmd, not a package.) The metadata stays
committed because tool-reactor, tool-webview, and tool-composition read it.

windows-reactor-setup is a published runtime helper with no generated artifact, so its pins can't
be proven by regen. Instead tool-reactor-metadata guards them on every run, asserting (and
failing loudly on drift) that:

• WINDOWS_APP_SDK_VERSION (metadata) equals RUNTIME_VER (runtime) - one number drives both;

• WEBVIEW2_VER equals WEBVIEW2_VERSION, so the staged WebView2 runtime matches the ABI the
  bindings target; and

• reactor.yml's installer URL installs RUNTIME_VER (.../windowsappsdk/<major.minor>/<ver>/),
  so CI's self-tests exercise the runtime apps ship.

• To update metadata + runtime: bump WINDOWS_APP_SDK_VERSION (tool-reactor-metadata) and
  RUNTIME_VER (reactor-setup) together, update the reactor.yml installer URL, then run
  cargo run -p tool-reactor-metadata and commit the refreshed metadata. The guard enforces the
  version agreement; the regen enforces the metadata.

• assets/app.manifest is a generated activation asset with no committed generator -
  app.manifest transforms the App SDK package.appxfragment files into SxS fusion format (source
  versions in its header). It is forward-compatible, so refreshed only when the reactor control set
  needs newly-moved classes, not on every bump.

• resources.pri is staged from the App SDK runtime package only for self-contained deployment via
  as_self_contained; framework-dependent staging does not copy it.

See windows-reactor and
windows-reactor-setup.

Download mechanisms Copy Chapter

Two independent NuGet paths, both using https://www.nuget.org/api/v2/package/{id}/{version}:

• windows_clang::nuget_package - used by the scraping/codegen tools (tool-win32,
  tool-winrt, tool-webview, tool-reactor-metadata). Restores into the NuGet global cache
  (NUGET_PACKAGES overrides), else downloads via bundled curl/tar. Layout-agnostic - each
  caller indexes the subtree it needs.
• reactor-setup's staging - runs in the build.rs of every consuming app to stage the App SDK
  runtime and WebView2 projection. Dependency-free (std + the curl.exe/tar.exe shipped with
  Windows), which is why it does not reuse nuget_package.

The `tool-*` / pin pairing Copy Chapter

All cross-file reads go through helpers::read_str_const, so each pin is declared once by its owner
and read back everywhere else.

Security (`docs/security.md`) Copy Section

Security Copy Chapter

Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include Microsoft, Azure, DotNet, AspNet, Xamarin, and many more.

If you believe you have found a security vulnerability in any Microsoft-owned repository that meets Microsoft's definition of a security vulnerability, please report it to us as described below.

Reporting Security Issues Copy Chapter

Please do not report security vulnerabilities through public GitHub issues.

Instead, please report them to the Microsoft Security Response Center (MSRC) at https://msrc.microsoft.com/create-report.

If you prefer to submit without logging in, send email to [email protected]. If possible, encrypt your message with our PGP key; please download it from the the Microsoft Security Response Center PGP Key page.

You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at microsoft.com/msrc.

Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:

• Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
• Full paths of source file(s) related to the manifestation of the issue
• The location of the affected source code (tag/branch/commit or direct URL)
• Any special configuration required to reproduce the issue
• Step-by-step instructions to reproduce the issue
• Proof-of-concept or exploit code (if possible)
• Impact of the issue, including how an attacker might exploit the issue

This information will help us triage your report more quickly.

If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our Microsoft Bug Bounty Program page for more details about our active programs.

Preferred Languages Copy Chapter

We prefer all communications to be in English.

Policy Copy Chapter

Microsoft follows the principle of Coordinated Vulnerability Disclosure.

Crates Cppwinrt (`docs/crates/cppwinrt.md`) Copy Section

cppwinrt

The C++/WinRT compiler, bundled for use from Rust.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 📁 Source

cppwinrt packages the C++/WinRT compiler so it can be
invoked from a Rust build. It is a thin wrapper that runs the bundled cppwinrt.exe with the
arguments you provide, returning its output. This is primarily useful for interop scenarios that
also generate C++/WinRT projection headers.

Rust code should prefer a focused crate or windows-bindgen implementation support. Binary
applications can use the broad windows projection when convenient. Use cppwinrt
when a Rust build also compiles C++ that consumes or implements WinRT types.

Start with the crate README for setup and the help
invocation. The bundled executable runs only on Windows.

First workflow: generate headers for a C++ build Copy Chapter

1. Produce or obtain the component winmd.
2. Choose an output directory owned by the build, normally OUT_DIR.
3. Invoke cppwinrt::cppwinrt with -in for the component metadata and any reference metadata,
   then -out for the include directory.
4. Add that directory to the C++ compiler's include paths.
5. Link the libraries required by the generated C++ and the component.

crates/samples/robot/component_cpp/build.rs is the component example. It compiles
src/robot.rdl with windows-rdl, passes robot.winmd and the default metadata
directory to C++/WinRT, then compiles component.cpp as C++20. The matching
robot/client_cpp/build.rs consumes the component's winmd and compiles a C++ client.

Input and output model Copy Chapter

cppwinrt(args) accepts any iterator of values convertible to OsStr, so paths do not need UTF-8
conversion. The arguments are passed unchanged to the bundled compiler. On success the function
returns standard output as a String; on failure it panics with standard error.

The wrapper copies cppwinrt.exe to a unique temporary path for each call, runs it synchronously,
and removes the executable afterward. C++/WinRT itself writes the requested projection output.
Call cppwinrt(["-help"]) for the option set supported by the bundled compiler version.

Integration and pitfalls Copy Chapter

• windows-rdl can compile a component's reviewable RDL contract to the winmd consumed here.
• windows-default contains the standard winmd files, but C++/WinRT expects input paths. The robot
  samples pass the crate directory containing those files.
• windows-bindgen is the Rust projection counterpart when both Rust and C++ consume one contract.
• Gate build-script use to Windows with the MSVC environment when the build also invokes MSVC.
• Add rerun-if-changed directives for component metadata and C++ sources. Generated headers alone
  do not tell Cargo when to rerun the build script.
• The wrapper panics on compiler failure and does not return a structured status. Supply only
  validated arguments and let the build fail visibly.
• Do not assume options from a newer standalone C++/WinRT release. Check the bundled compiler's
  -help output.

Internal documentation Copy Chapter

The remainder of this page covers how the crate is built and maintained. It is for contributors and
is not needed to use cppwinrt.

How it's built Copy Section

Packages the prebuilt cppwinrt.exe. src/bindings.rs is generated by tool-bindings from
crates/tools/bindings/src/cppwinrt.txt and supplies the CoCreateGuid call used for temporary
directory names.

Testing Copy Section

Run cargo test -p cppwinrt; see also the workspace test crates.

Crates Windows Animation (`docs/crates/windows-animation.md`) Copy Section

windows-animation

A safe wrapper around the Windows Animation Manager (IUIAnimationManager).

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 🧩 Samples
• 📁 Source

When to use it Copy Chapter

Use windows-animation when a Windows application needs time-based interpolation for values that
it will draw or apply itself. It works well with immediate-mode rendering: advance the manager on
each frame, read each Variable, and use the values in a canvas, Direct2D, Direct3D, or
DirectComposition scene.

The crate does not create a timer, request frames, draw content, or update a UI property. For
retained WinUI visuals in windows-reactor, Reactor's Composition
transitions usually fit better because the compositor owns their frame updates.

Prerequisites Copy Chapter

Initialize COM on the thread that creates the animation objects. For a console or rendering thread,
windows_core::init_mta() is suitable, as shown by the samples. A UI thread may use its existing
apartment. Use one monotonic time origin for scheduling and updates.

The README contains dependency setup and a minimal storyboard. The workflow below focuses on
integrating animation into a real frame loop.

First workflow: drive a rendered property Copy Chapter

1. Create one Manager and one TransitionLibrary.
2. Create a Variable for each scalar property, using the current rendered value as its initial
   value.
3. Build a transition and schedule it at an absolute time from the application's animation clock.
4. On every requested frame, sample that clock and call Manager::update(time) once.
5. Read all variables, draw or apply the values, and request another frame while animation remains
   active.

For example, the per-frame portion of a renderer can be kept separate from transition setup:

use windows_animation::{Manager, Result, Variable};

fn draw_frame(manager: &Manager, x: &Variable, now: f64) -> Result<f64> {
    manager.update(now)?;
    let x = x.value()?;
    // Use `x` in the renderer for this frame.
    Ok(x)
}

now is an absolute timestamp in the same time domain used when scheduling, not elapsed time since
the previous frame. Supplying deltas makes the animation clock stall or move incorrectly.

Core API and lifecycle Copy Chapter

Manager coordinates variables, transitions, and storyboards. Reuse it for values updated from
the same frame clock. Variable holds the current interpolated f64. TransitionLibrary creates
transition descriptions. Transition and Storyboard are retained COM-backed values and can be
cloned.

There are two scheduling paths:

• Manager::schedule_transition applies one transition to one variable at an absolute start time.
• Manager::create_storyboard creates a group that can coordinate several variables or sequence
  transitions before scheduling the group.

Keep the Manager and every Variable needed by rendering alive for the animation lifetime.
Propagate the windows_core::Result from creation, scheduling, updates, and value reads; COM
initialization and invalid transition parameters are reported through those results.

Transition choices Copy Chapter

Acceleration and deceleration are ratios of total duration and must sum to <= 1.0. Durations and
final values use f64.

For direct scheduling:

use windows_animation::*;

fn retarget(manager: &Manager, library: &TransitionLibrary, x: &Variable, now: f64)
    -> Result<()>
{
    let transition = library.accelerate_decelerate(0.25, 320.0, 0.3, 0.3)?;
    manager.schedule_transition(x, &transition, now)
}

Sequencing with storyboards Copy Chapter

Storyboard::add_transition adds a transition and returns a Keyframe marking its end.
add_transition_at_keyframe starts another transition at that point. A keyframe can coordinate a
later transition on the same variable or another variable.

Build the entire storyboard before calling schedule(start_time). Its time is absolute in the
manager's clock domain. The storyboard sample sequences a rise and fall on one variable; the
same pattern can start a fade after a movement finishes.

Frame-loop and error pitfalls Copy Chapter

• Update a manager once per frame before reading its variables. Reading first returns the value
  from the previous update.
• Use a monotonic high-resolution clock. Wall-clock changes must not move animation time backward.
• Schedule and update with the same time origin. 0.0 is valid for a deterministic offline
  timeline, while a live app commonly uses seconds since renderer startup.
• The crate does not report whether more frames are required. The application owns invalidation
  and its stop condition.
• Do not block the UI thread between updates in an interactive application; missed updates appear
  as skipped visual frames even though interpolation remains time-correct.
• Treat a failed creation, transition, schedule, update, or value read as an application error.
  Do not continue rendering with a stale value unless that is an explicit fallback.

DirectComposition Copy Chapter

Variable::copy_curve copies the variable's curve to an object implementing
IDCompositionAnimation. DirectComposition can then evaluate it on its own composition thread,
without the application reading Variable::value each frame.

This API targets Win32 DirectComposition, not the Windows.UI.Composition engine used by WinUI and
Reactor. The two animation object models are not interchangeable.

Samples Copy Chapter

Run the headless sample with:

cargo run -p animation-storyboard

The sample schedules one transition directly and chains two more through a storyboard keyframe. It
initializes COM explicitly and prints deterministic values using the absolute-time update pattern.

The canvas/clock sample applies the same API in a live
per-frame rendering loop.

Internal documentation Copy Chapter

This section is for contributors to windows-animation.

src/bindings.rs is generated by tool-bindings from
crates/tools/bindings/src/animation.txt. The hand-written Manager, TransitionLibrary,
Storyboard, Transition, Keyframe, and Variable wrappers expose the selected Windows
Animation Manager 2 interfaces.

Manager::new and TransitionLibrary::new create their COM classes with
windows_core::create_instance.
Manager methods delegate scheduling and updates to IUIAnimationManager2. Storyboards add an
explicit keyframe after each transition so the returned opaque Keyframe can anchor another
transition. Variable::copy_curve casts the supplied interface to IDCompositionAnimation before
copying the curve.

Keep the generated filter and the hand-written surface aligned. The headless examples are also the
clearest end-to-end checks of COM creation, direct scheduling, keyframe sequencing, and updates.

Crates Windows Bindgen (`docs/crates/windows-bindgen.md`) Copy Section

windows-bindgen

Generate Rust bindings for the Windows APIs your project needs.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 🧩 Samples
• 📁 Source

Use windows-bindgen to generate a focused binding set from Windows metadata (.winmd).
It includes default Win32 and WinRT metadata and can also read custom metadata. For broad
pre-generated bindings, use windows or windows-sys.

The README shows dependency setup, generation from
build.rs, and inclusion of the generated file. This guide covers API selection and generation
options.

Generate bindings Copy Chapter

Configure the builder, then call write():

windows_bindgen::builder()
    .output("src/bindings.rs")
    .filters(["GetTickCount", "GetTickCount64"])
    .flat()
    .sys()
    .write();

The command-line-style adapter does the same thing:

windows_bindgen::bindgen([
    "--out", "src/bindings.rs",
    "--flat",
    "--sys",
    "--filter", "GetTickCount", "GetTickCount64",
]);

Both forms require an output path and at least one include filter. Paths are relative to the
generator's working directory.

For a published library, run generation from a separate tool and commit src/bindings.rs.
Consumers then need only the generated code's runtime dependencies. Applications can instead
generate into OUT_DIR from build.rs, as shown in the README.

Select APIs Copy Chapter

Start with the function, constant, or type name in the Windows API documentation. For example,
.filter("GetTickCount") selects GetTickCount. Include any A or W suffix
in the metadata name; filters do not expand C preprocessor aliases.

Signature dependencies are included automatically. You do not need to list every parameter and
return type. Select an interface or its members explicitly when you also need to call its methods.

The bundled Win32 metadata places APIs in Windows.Win32. Bare names such as GetTickCount and
qualified names such as Windows.Win32.GetTickCount both work. The subsystem paths used by
windows and windows-sys package features, such as Win32_System_Com, are not metadata
namespaces: do not turn them into filters such as Windows.Win32.System.Com.

Filters accept dots or :: between path segments and {...} for grouped names:

Bare names search all input namespaces; qualify a name when you need to distinguish matching
definitions. For custom metadata, use the namespaces declared in that metadata.

Interface shells do not expose iteration. Iteration helpers require First, or Current,
HasCurrent, and MoveNext for an iterator.

For runtime classes, select the instance, static, or factory methods you need. For example,
Windows.Foundation.Uri::CreateUri selects a factory method; a class name alone does not select
its factory methods.

Member filters select methods on a type, not free functions in a subsystem namespace.
Property and event names select their accessor pairs. For type and namespace selections, prefix a
filter with ! to exclude it. More specific rules take precedence; exclusions win ties regardless
of argument order. Prefer narrow filters to generating a namespace and removing items from it.

Keep longer filter lists in a file Copy Section

Create apis.txt with one filter per line:

// APIs used by this project.
GetTickCount
GetTickCount64

Use .filter_file("apis.txt") or --filter-file apis.txt. Blank lines and lines beginning with
// are ignored. A file containing the entire argument list can be read with --etc.

Choose the output Copy Chapter

Style controls the generated API. Layout controls where it is written.

sys and minimal are mutually exclusive, as are flat and package. Narrow filters are needed
in every style. Generated APIs may also use focused support crates such as windows-numerics;
add the dependencies referenced by the generated source.

Bit-field accessors Copy Section

For native bit fields, default and minimal bindings provide getters and setters over the backing
integer fields. Sys bindings keep the backing fields without accessors.

Common options Copy Chapter

The builder reference documents all methods, and bindgen lists the command-line-style
arguments.

For compose, also filter the class and its composable factory methods, and select its override
interfaces with implement.

With no explicit input, generation uses the bundled metadata. Adding a custom input replaces
that default; add input_default() if it also needs Windows definitions. Compile RDL with
windows-rdl, or scrape headers with windows-clang,
before passing the resulting .winmd to bindgen.

Formatting uses rustfmt from PATH and is best effort: unavailable or failed formatting leaves
the output unformatted without a warning. rustfmt("max_width=120") sets configuration, not an
executable path. Install rustfmt when generating checked-in source.

Samples Copy Chapter

Contributing Copy Chapter

The generator reads metadata through windows-metadata.
test_bindgen contains the fixtures; run cargo test -p test_bindgen and
cargo test -p windows-bindgen. After changing generation logic, run the affected tool-*
generators and inspect the output diffs. tool-bindings generates focused library bindings;
tool-package generates the published windows and windows-sys packages.

Crates Windows Canvas (`docs/crates/windows-canvas.md`) Copy Section

windows-canvas

Safe 2D drawing over Direct2D, Direct3D 11, DXGI, DirectWrite, and WIC.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 🧩 Samples
• 📁 Source
• Reactor guide
• Composition guide

When to use it Copy Chapter

Use Canvas for custom 2D graphics, charts, diagrams, image processing, text layout, geometry hit
testing, or animation. It is a drawing API rather than a control toolkit. Combine it with Reactor
when the app also needs WinUI controls.

Use Composition when the scene is primarily a retained tree of visuals that Windows animates and
composes. Use Canvas when the app draws pixels and paths for each requested frame. The two can be
combined by drawing Canvas content into a composition surface.

Canvas is host-neutral by default. Enable system for the typed windows-window swap-chain helper
and system Composition, or reactor for Reactor controls and lifted Composition. Enable
composition with the selected host to draw into Composition surfaces. The host adapters can
coexist when composition is not enabled; the Composition backends cannot.

The basic idea Copy Chapter

Canvas is an immediate-mode drawing API. The application receives a drawing session and describes
the current frame with commands such as clear, fill_rect, draw_text, and draw_bitmap.

begin a frame -> issue drawing commands -> finish the frame -> present it

There is no retained scene tree. If a shape should still be visible in the next frame, draw it
again. Keep application state - points, colors, text, images - in normal Rust data and turn that
state into drawing commands.

The simplest host is Reactor. It creates the graphics device and swap chain, tracks size and display
scale, and handles device recovery. Enable the feature in Cargo.toml:

windows-canvas = { version = "0.100.0", default-features = false, features = ["reactor"] }
windows-reactor = "0.100.0"

Your first canvas Copy Chapter

canvas draws once when the surface is ready and again when its size or display scale changes:

use windows_canvas::*;
use windows_reactor::App;

fn draw(ctx: &DrawContext) -> Result<()> {
    ctx.clear(ColorF::DARK_SLATE_BLUE);

    let brush = ctx.create_solid_brush(ColorF::CORNFLOWER_BLUE)?;
    let center = Vector2::new(ctx.width / 2.0, ctx.height / 2.0);
    let radius = ctx.width.min(ctx.height) * 0.3;
    ctx.fill_ellipse(&Ellipse::circle(center, radius), &brush);

    Ok(())
}

fn main() -> Result<()> {
    App::run(canvas(draw))
}

The callback receives a DrawContext. Its width and height are the available size in
device-independent pixels. It dereferences to DrawingSession, so drawing methods and resource
creation are available directly on ctx.

Clear the surface, or fully cover it, unless keeping pixels from the previous frame is intentional.

Draw shapes with brushes Copy Chapter

A brush supplies paint. Create it once within a frame and reuse it for as many operations as
needed:

let brush = ctx.create_solid_brush(ColorF::CORNFLOWER_BLUE)?;

ctx.fill_rect(&Rect::from_xywh(20.0, 20.0, 160.0, 100.0), &brush);
ctx.draw_ellipse(
    &Ellipse::circle(Vector2::new(260.0, 100.0), 60.0),
    &brush,
    4.0,
);

brush.set_color(ColorF::WHITE);
ctx.draw_line(
    Vector2::new(20.0, 160.0),
    Vector2::new(320.0, 160.0),
    &brush,
    2.0,
);

Rect, RoundedRect, and Ellipse are lightweight geometry values. Use fill_* for a solid
interior and draw_* for an outline. Gradient brushes use the same drawing methods.

Apply a temporary transform Copy Chapter

with_transform applies translation, rotation, or scale only while its closure runs, then restores
the previous transform:

let transform =
    Matrix3x2::rotation_around(15.0, Vector2::new(ctx.width / 2.0, ctx.height / 2.0));

ctx.with_transform(&transform, || {
    ctx.fill_rect(
        &Rect::from_xywh(ctx.width / 2.0 - 80.0, ctx.height / 2.0 - 40.0, 160.0, 80.0),
        &brush,
    );
});

Scoped transforms make helper functions easier to combine because one drawing operation cannot
leave a transform behind for the next one.

Build a custom path Copy Chapter

For a polygon, PathBuilder::polygon is the shortest route:

let points = [
    Vector2::new(160.0, 40.0),
    Vector2::new(280.0, 240.0),
    Vector2::new(40.0, 120.0),
    Vector2::new(280.0, 120.0),
    Vector2::new(40.0, 240.0),
];

let star = PathBuilder::new(ctx.device())?.polygon(points)?;
let brush = ctx.create_solid_brush(ColorF::new(1.0, 0.8, 0.0, 1.0))?;
ctx.fill_path(&star, &brush);

Use begin, line_to, and bezier_to when the path needs individual segments:

let curve = PathBuilder::new(ctx.device())?
    .begin_hollow(Vector2::new(40.0, 160.0))
    .bezier_to(
        Vector2::new(120.0, 20.0),
        Vector2::new(240.0, 300.0),
        Vector2::new(320.0, 160.0),
    )
    .end_open()
    .build()?;

ctx.draw_path(&curve, &brush, 3.0);

Paths also support bounds and fill or stroke hit testing, which is useful for diagrams and editors.

Draw text Copy Chapter

For ordinary text, create a TextFormat and draw into a rectangle:

let format = TextFormat::new("Segoe UI", 32.0)?
    .with_alignment(TextAlignment::Center)
    .with_paragraph_alignment(ParagraphAlignment::Center);
let brush = ctx.create_solid_brush(ColorF::WHITE)?;

ctx.draw_text(
    "Hello, Canvas!",
    &format,
    &Rect::new(0.0, 0.0, ctx.width, ctx.height),
    &brush,
);

Use TextLayout when text is drawn repeatedly or needs measurement, reflow, caret bounds, or hit
testing. Cache the layout and rebuild it when its text, format, size, or device changes. The
text_layout sample shows that pattern.

Load and draw an image Copy Chapter

load_bitmap decodes an image file:

let bitmap = ctx.load_bitmap("assets/photo.png")?;
let destination = Rect::from_xywh(20.0, 20.0, bitmap.width(), bitmap.height());
ctx.draw_bitmap(&bitmap, &destination, 1.0);

For generated image data, create_bitmap accepts tightly packed premultiplied BGRA pixels:

let bitmap = ctx.create_bitmap(&pixels, width, height)?;
ctx.draw_bitmap(
    &bitmap,
    &Rect::from_xywh(0.0, 0.0, width as f32, height as f32),
    1.0,
);

Bitmaps, brushes, paths, and text layouts depend on the graphics device. Creating them inside the
draw callback is the easiest starting point. Cache expensive resources only when profiling shows
the need, and rebuild cached resources when ctx.device_changed() is true.

Redraw when state changes Copy Chapter

Use canvas when content changes only because the surface was created or resized. Use
animated_canvas for motion that needs every display frame:

animated_canvas(|ctx| {
    draw_frame(ctx, elapsed_time())
})

For input-driven content, use canvas_invalidated. Store an Invalidator with the component,
change the drawing data in update, and request one new frame:

struct Sketch {
    points: Rc<RefCell<Vec<Vector2>>>,
    invalidator: Invalidator,
}

fn update(&mut self, point: Vector2, _context: &ComponentContext<Self>) {
    self.points.borrow_mut().push(point);
    self.invalidator.invalidate();
}

fn draw_points(ctx: &DrawContext, points: &[Vector2]) -> Result<()> {
    ctx.clear(ColorF::BLACK);
    let brush = ctx.create_solid_brush(ColorF::WHITE)?;
    for &point in points {
        ctx.fill_ellipse(&Ellipse::circle(point, 3.0), &brush);
    }
    Ok(())
}

fn view(&self, _input: &(), _context: &mut ViewContext<Self>) -> View {
    let points = Rc::clone(&self.points);
    canvas_invalidated(&self.invalidator, move |ctx| {
        draw_points(ctx, &points.borrow())
    })
}

Invalidation keeps the app idle between changes. Do not use continuous animation for a chart,
drawing, or diagram that changes only after input.

Drive a standalone swap chain Copy Chapter

Without Reactor, the application creates a GpuDevice and SwapChain and owns the frame loop. The
essential sequence is:

use windows_canvas::*;

fn draw_frame(chain: &mut SwapChain) -> Result<bool> {
    let session = chain.begin_draw()?;
    session.clear(ColorF::DARK_SLATE_BLUE);

    let brush = session.create_solid_brush(ColorF::CORNFLOWER_BLUE)?;
    session.fill_rect(&Rect::from_xywh(20.0, 20.0, 200.0, 120.0), &brush);

    drop(session);
    chain.present()
}

The drawing session borrows the swap chain, so finish and drop it before present. A standalone
host must also resize the swap chain, update display scale, schedule frames, and recreate the
device, swap chain, and dependent resources when present returns Ok(false). The
standalone sample connects those pieces to
windows-window. Its resize callback redraws the existing swap chain because the outer render loop
is suspended while Windows runs its modal interactive-sizing loop.

What to read next Copy Chapter

Browse crates/samples/canvas for focused drawing and hosting
examples.

Internal documentation Copy Chapter

The remainder of this page describes how the crate is built and maintained. Applications do not
need it to use Canvas.

Architecture Copy Section

The safe wrappers are hand-written and include GpuDevice, SwapChain, DrawingSession,
geometry, brushes, text, bitmaps, effects, and render targets.

GpuDevice owns the shared Direct3D, Direct2D, DXGI, DirectWrite, and WIC objects. A swap chain
owns one D2D device context and is rendered on its owning thread. WARP allows tests and callers to
render without a physical GPU.

device_lost.rs classifies D2D and DXGI loss codes. Standalone callers perform recovery. The
Reactor host rebuilds its device, swap chain, and cached state after loss.

The Reactor integration lives behind this crate's reactor feature. The dependency direction is
windows-canvas[reactor] -> windows-reactor. Canvas owns rendering resources and receives only
typed panel metrics, rendering notifications, deferred frame callbacks, and attachment completion
through ElementRef<SwapChainPanel>.

The system feature enables windows-window and GpuDevice::create_swap_chain_for_window.
Reactor-only builds do not compile windows-window; raw create_swap_chain_for_hwnd remains
available without either host.

Continuous mode uses WinUI's CompositionTarget::Rendering for its normal animation clock. Layout
and scale changes also request a coalesced dispatcher frame because composition rendering can be
delayed while WinUI processes interactive resize input. Demand mode stays idle until layout, scale,
or Invalidator requests a frame.

Panel binding, swap-chain, and attachment-request generations reject stale completion callbacks.
Resizing buffers preserves the existing panel attachment; only panel replacement or swap-chain
rebuilding requires SetSwapChain. Canvas::on_error reports initialization, attachment, resize,
drawing, presentation, and failed recovery through IntegrationError.

CanvasImageSource uses a borrowed drawing session over a WinUI SurfaceImageSource.
CanvasCompositionExt uses a borrowed drawing session over
ICompositionDrawingSurfaceInterop. Both pair every successful BeginDraw with EndDraw,
including panic cleanup.

If a composition-surface draw reports device loss, create a replacement GpuDevice, call
GpuDevice::replace_graphics_device to rebind the existing CompositionGraphicsDevice, and retry
the draw. The Composition surfaces and visuals remain in place during recovery.

Code generation Copy Section

src/bindings.rs is generated by tool-bindings from
crates/tools/bindings/src/canvas.txt. It contains minimal flat bindings for Direct2D,
Direct3D 11, DXGI, DirectWrite, and WIC, plus referenced WinRT numerics types.

src/reactor_bindings.rs is generated by tool-reactor for the WinUI bridge. Generated files are
committed and must not be edited by hand. After changing
crates/tools/reactor/src/canvas.txt or the generator, run the corresponding tool and verify
cargo check -p windows-canvas --quiet.

Testing Copy Section

Canvas tests use the WARP software rasterizer and do not require a physical GPU. The integration
suite is in test_canvas:

cargo test -p test_canvas

Use RenderTarget for off-screen drawing tests. Repeated presents on a composition swap chain
without a visual consumer can leave WARP waiting for queued work during device destruction.

Reactor integration behavior is also covered by Reactor's recording and live surface tests. The
Composition Canvas sample covers the system bridge, and the Stacker Reactor sample covers the
lifted bridge.

Crates Windows Clang (`docs/crates/windows-clang.md`) Copy Section

windows-clang

Generates RDL from C/C++ headers using libclang.

• crates.io
• docs.rs
• Getting started
• Source

windows-clang is the header-facing stage of the Windows metadata pipeline:

headers -> windows-clang -> RDL -> windows-rdl -> WinMD

It extracts declarations and source annotations from C and C++ headers. Compile the resulting
RDL with windows-rdl, then use windows-bindgen to
generate Rust bindings.

Setup Copy Chapter

The README shows the Cargo dependency. Install a compatible
libclang and set LIBCLANG_PATH to its directory if it is not discoverable on your system.
The crate loads libclang at runtime; it does not install it or the headers you want to process.

Supply compiler arguments for the language, target architecture, include directories, and
preprocessor definitions your headers require. Metadata references do not supply C/C++ headers
or compiler include paths.

Generate RDL Copy Chapter

Configure the builder, then call write():

windows_clang::clang()
    .input("Example.h")
    .args(["-x", "c++", "--target=x86_64-pc-windows-msvc"])
    .reference_default()
    .namespace("Example")
    .library("example.dll")
    .output("Example.rdl")
    .write()
    .unwrap();

At least one input, a namespace, and an output path are required. Paths are relative to the
generator's working directory.

Declarations from input headers are output roots. Included headers can supply dependencies without
having all their declarations emitted; use filter to include their declarations as roots too.
This is a header-path filter, not a function-name filter.

References let generated RDL use existing types without redefining them. Use reference_default
when your headers depend on Windows APIs and reference for your own metadata.

The builder reference
documents all methods.

Inspect extraction results Copy Chapter

Use Input, extract, and EmitOptions directly when a generator needs to inspect declarations,
assign different DLLs to functions, or emit separate header partitions.

let input = windows_clang::Input::new(
    "Example.h",
    std::fs::read_to_string("Example.h").unwrap(),
);
let snapshot = windows_clang::extract(
    [input],
    &["-x", "c++", "--target=x86_64-pc-windows-msvc"],
)
.unwrap();

The resulting Snapshot owns translation-unit-local facts and constants. facts, constants,
unsupported, and dump expose the extraction result for diagnostics and validation.

Input::new(name, source) treats name as a root. The following methods control which included
headers contribute output roots:

Configure emission Copy Chapter

Use Snapshot::emit(namespace) for one namespace, emit_with_library to attach one DLL to all
functions, or emit_with_options for generator policy. emit_by_header_with_options returns a
map of defining-header names to RDL partitions.

EmitOptions controls:

References are explicit TypeReference values classified as Type, Interface, or Enum.
Referenced enum member names let an overlay emit an enum only when it adds members to the base.
MetadataReferences builds that map from WinMD files and records existing type, function, and
constant names for exclusion. apply_reference_exclusions excludes only types with an
unambiguous external reference, while apply_exclusions is available for overlays that must omit
every item from a known base.

Exclusions filter root declarations; they do not establish that a dependency has an external
definition. Supply references for external types; required local dependencies are still emitted.

The caller owns DLL selection, architecture merging, and RDL-to-WinMD compilation. Extraction
does not discover import libraries or combine target architectures automatically.

Known limits Copy Chapter

• RDL cannot represent mixed raw pointer-chain mutability. If any level in a raw pointer run is
  const, every level in that run is emitted as const.
• Coverage is limited to declarations reachable from configured roots.
• Conflicting declarations can fail emission as ambiguous; extraction is not a general C++ binding
  generator.
• SAL projection supports only a subset of annotations and size relationships.
• Non-finite floating-point constants and interface-valued constants cannot be emitted.
• Header extraction cannot infer curated handle cleanup, last-error, or documentation policy.
• Stable Rust has no function-pointer ABI corresponding to every native calling convention.

Contributing Copy Chapter

Run cargo test -p windows-clang and cargo test -p test_clang. Header fixtures and expected RDL
live in crates/tests/libs/clang; tests regenerate the expected output, and CI rejects output
changes that are not committed. After changing extraction or emission, run the affected tool-*
generators and review the output diffs.

Repository tooling provisions its pinned libclang with cargo run -q -p tool-clang -- path.
Set LIBCLANG_PATH to the reported directory before running tests.

Crates Windows Collections (`docs/crates/windows-collections.md`) Copy Section

windows-collections

Stock WinRT collection types backed by Rust containers.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 📁 Source

When to use this crate Copy Chapter

Use windows-collections when a WinRT API expects a collection interface and your data starts as a
Rust Vec or BTreeMap. The crate supplies stock implementations of the standard WinRT
interfaces, so application and component code do not need to implement their vtables.

This is an ABI adapter, not a replacement for Rust collections. Keep data as Vec or BTreeMap
while it remains inside Rust, and convert at the boundary where a WinRT collection is required.

Getting started Copy Chapter

The crate README contains the dependency declaration and
minimal vector and map examples. The stock implementations require the default std feature. For
a first workflow:

1. Identify the exact interface in the receiving API's signature.
2. Build the values in a Vec or BTreeMap.
3. Convert the container with InterfaceType::from.
4. Pass or return the projected interface and handle its methods as fallible operations.

use windows_collections::IVector;

fn numbers() -> IVector<i32> {
    let values = IVector::<i32>::from(vec![1, 2, 3]);
    values.Append(4).unwrap();
    values
}

In application code, propagate the Result returned by collection methods instead of unwrapping
when the operation can fail.

Choosing a collection interface Copy Chapter

T::Default is the Rust storage form defined by the type's RuntimeType implementation. For
ordinary value types it is usually T. Projected nullable or interface types may use an
Option<T> storage form, so let the compiler guide the concrete container type.

The mutable interfaces own their Rust containers behind synchronization. View conversions own
read-only values, and GetView on a mutable collection returns a snapshot rather than a live view.

Common tasks Copy Chapter

Build and read a map Copy Section

use std::collections::BTreeMap;
use windows_collections::IMapView;
use windows_strings::{h, HSTRING};

fn main() {
    let values = BTreeMap::from([
        (HSTRING::from("one"), 1),
        (HSTRING::from("two"), 2),
    ]);
    let values = IMapView::<HSTRING, i32>::from(values);

    assert!(values.HasKey(h!("one")).unwrap());
    assert_eq!(values.Lookup(h!("two")).unwrap(), 2);
}

Missing keys and invalid vector indexes return the WinRT E_BOUNDS error. Check with HasKey or
Size when absence is expected rather than using an error as normal control flow.

Iterate projected values Copy Section

Generated IntoIterator implementations allow a borrowed or owned collection to be used in a
for loop. Each item is still a projected value, and map iteration yields
IKeyValuePair<K, V>:

# use windows_collections::IIterable;
let values = IIterable::<i32>::from(vec![1, 2, 3]);

for value in &values {
    println!("{value}");
}

Iteration uses GetMany in blocks instead of making one iterator ABI call for each item. Reading
each map pair's Key and Value remains a separate ABI operation.

Publish collection changes Copy Section

Convert a container to IObservableVector or IObservableMap when consumers need
VectorChanged or MapChanged. Register the projected event handler, retain its token, and pass
that token to the corresponding remove method when the subscription ends. Mutating through the
observable interface raises insertion, removal, replacement, or reset notifications.

Important choices and pitfalls Copy Chapter

• Convert to the interface the API asks for. A mutable IVector<T> is unnecessary when the API
  accepts IIterable<T> or IVectorView<T>.
• Conversion consumes the Rust container. Clone it first only when Rust must retain an independent
  copy.
• GetView snapshots the current contents. Later writes to the mutable source are not reflected in
  that view.
• Map iteration snapshots entries when First is called. It does not hold a live traversal of the
  backing BTreeMap.
• Calls cross a WinRT ABI and return Result; repeated fine-grained lookups can cost more than
  processing the original Rust container before conversion.

Samples and next steps Copy Chapter

The collections-collections sample converts a
Vec and a BTreeMap, mutates the projected interfaces, and iterates their values. Continue with
the
docs.rs API for the methods on the interface required by
your Windows API. windows-reference covers boxed WinRT values that can
also appear as collection elements.

Internal documentation Copy Chapter

The remainder of this page covers how the crate is built and maintained. It is for contributors and
is not needed to use windows-collections.

How it's built Copy Section

src/bindings.rs is generated by tool-bindings from crates/tools/bindings/src/collections.txt;
the collection adapters are hand-written. Used internally by the windows crate.

Iterating a collection (for x in &vector) yields through BufferedIterator
(src/buffered_iterator.rs), which fetches elements a block at a time via GetMany rather than one
IIterator::next ABI call per element. windows-bindgen generates the IntoIterator impls that
reference it. The block is sized to keep the buffer near 2 KB regardless of element size.

This batching applies to maps too: IMap/IMapView/IObservableMap implement
IIterable>, so for pair in &map drives the same BufferedIterator (yielding
IKeyValuePair items) - there is no separate, slower map path. A map iteration still costs more
than a vector of scalars, but not because of the iterator: GetMany over IVector
bulk-copies the values inline, whereas over a map it returns a block of IKeyValuePair COM objects
(one AddRef each) and reading every pair.Value()/Key() remains a per-pair ABI crossing - the
IMap ABI offers no bulk key/value read. Separately, the component-side stock map iterator
snapshots its entries once at First() so each step is O(1) rather than re-walking the tree,
keeping a full traversal linear.

Testing Copy Section

Run cargo test -p windows-collections; see also the workspace test crates.

Crates Windows Composition (`docs/crates/windows-composition.md`) Copy Section

windows-composition

Safe wrappers for the Windows retained-mode composition engine.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 🧩 Samples
• 📁 Source
• Reactor hosting samples
• Canvas guide
• Window guide

When to use it Copy Chapter

Use Composition for a retained tree of lightweight visuals, brushes, shapes, and animations. It is
a good fit for animated backgrounds, overlays, game boards, transitions, and scenes where Windows
should retain and compose objects between updates.

Composition does not provide controls, text input, accessibility behavior, or layout panels. Use
windows-reactor for WinUI controls. Use
windows-canvas when custom drawing is easier as immediate-mode 2D commands.
Composition can host Canvas-drawn surfaces.

The basic idea Copy Chapter

Composition is a retained graphics API. You create a tree of visual objects, change their
properties when application state changes, and let Windows draw and animate the result.

create visuals -> attach them to a tree -> update properties -> Windows composes the scene

This differs from Canvas, where the application issues drawing commands for each frame. A
Composition visual stays in the tree until it is removed. Changing its offset, size, brush, or
animation is enough to change what appears on screen.

A Compositor creates every object in a scene. The most common visual types are:

Start with sprite visuals. They are enough for backgrounds, cards, overlays, game pieces, and many
animations.

Choose how to host the scene Copy Chapter

The crate supports two Composition stacks:

The two stacks use different Windows APIs and their objects cannot be mixed. Cargo features are
mutually exclusive, so applications selecting Reactor must disable the default system feature:

windows-composition = { version = "0.100.0", default-features = false, features = ["reactor"] }

Both stacks can create a graphics device and drawing surface for windows-canvas. Enable Canvas's
composition feature and select its matching system or reactor feature.

The examples below begin with the default system stack because it shows the visual model with the
least framework code.

Your first visual tree Copy Chapter

This complete program creates a window and fills it with a dark sprite:

use windows_composition::*;
use windows_window::*;

fn main() -> Result<()> {
    let _queue = DispatcherQueueController::create_on_current_thread()?;
    let compositor = Compositor::new()?;

    let window = Window::new("Composition")
        .size(800, 600)
        .create()?;
    let target = compositor.create_desktop_window_target(&window, false)?;

    let root = compositor.create_sprite_visual();
    root.set_relative_size_adjustment(Vector2::new(1.0, 1.0));
    root.set_brush(&compositor.create_color_brush(CompositionColor::rgb(30, 30, 46)));
    target.set_root(&root);

    run();
    Ok(())
}

The dispatcher queue and target must stay alive while the scene is displayed. Declaring them in
main keeps their lifetimes clear.

The Compositor creates both the visual and its brush. Composition objects in one tree should come
from the same compositor.

Build a scene from nested visuals Copy Chapter

Visuals form an ordered tree. Insert a child at the top to draw it in front of existing children,
or at the bottom to draw it behind them:

let card = compositor.create_sprite_visual();
card.set_size(240.0, 160.0);
card.set_offset(40.0, 40.0, 0.0);
card.set_brush(&compositor.create_color_brush(CompositionColor::rgb(0, 120, 215)));

let badge = compositor.create_sprite_visual();
badge.set_size(32.0, 32.0);
badge.set_offset(192.0, 16.0, 0.0);
badge.set_brush(&compositor.create_color_brush(CompositionColor::rgb(255, 255, 255)));

card.children().insert_at_top(&badge);
root.children().insert_at_top(&card);

The badge's offset is relative to the card. Moving the card moves both visuals. Keep handles to
visuals that the application will change later; attached visuals remain in the scene even if a
local clone is dropped.

Use the child collection to change the tree:

root.children().remove(&card);
root.children().remove_all();

Size and position visuals Copy Chapter

set_size uses width and height. set_offset uses x, y, and z:

visual.set_size(200.0, 120.0);
visual.set_offset(24.0, 48.0, 0.0);

Composition does not lay out a scene like WinUI. Either update exact sizes when the host changes or
make a child track its parent:

background.set_relative_size_adjustment(Vector2::new(1.0, 1.0));

A relative size of (1.0, 1.0) fills the parent. Relative adjustments can be combined with an
exact size or offset, which is useful for margins:

panel.set_relative_size_adjustment(Vector2::new(1.0, 1.0));
panel.set_size(-32.0, -32.0);
panel.set_offset(16.0, 16.0, 0.0);

Coordinates are device-independent pixels. The host is still responsible for reporting its own
size changes when exact dimensions are used.

Animate a property Copy Chapter

Animations are retained objects too. Create an animation, add key frames, and start it on a visual:

use std::time::Duration;

let pulse = compositor.create_vector3_key_frame_animation();
pulse.insert_key_frame(0.0, Vector3::new(1.0, 1.0, 1.0));
pulse.insert_key_frame(0.5, Vector3::new(1.2, 1.2, 1.0));
pulse.insert_key_frame(1.0, Vector3::new(1.0, 1.0, 1.0));
pulse.set_duration(Duration::from_millis(800));
pulse.set_iterate_forever();

card.start_animation("Scale", &pulse);

Windows advances the animation without an application frame loop. Use
ScalarKeyFrameAnimation for one-number properties such as "Opacity" and
Vector3KeyFrameAnimation for properties such as "Scale" and "Offset".

Property names are exact, case-sensitive Composition strings. Rust cannot catch a misspelling in
"Scale".

Draw retained shapes Copy Chapter

Use a ShapeVisual when the scene needs an ellipse or another vector shape rather than a
rectangular sprite:

let visual = compositor.create_shape_visual();
visual.set_size(200.0, 200.0);

let geometry = compositor.create_ellipse_geometry();
geometry.set_radius(Vector2::new(80.0, 80.0));

let circle = compositor.create_sprite_shape(&geometry);
circle.set_offset(Vector2::new(100.0, 100.0));
circle.set_fill_brush(&compositor.create_color_brush(CompositionColor::rgb(0, 120, 215)));
visual.shapes().append(&circle);

root.children().insert_at_top(&visual);

Shapes remain editable after they are attached. Change the geometry, brush, or visual properties
instead of rebuilding the scene for every update.

Put Composition inside Reactor Copy Chapter

With the reactor feature, a Reactor Grid provides the host. The flow is:

1. Attach an ElementRef<Grid> to the grid.
2. Observe the composition host from use_effect.
3. On CompositionHostEvent::Ready, adopt the supplied compositor with
   Compositor::from_host.
4. Build a visual tree and attach it with request_set_child_visual.
5. Update its size on Ready and Metrics events.

The important bridge calls look like this:

let compositor = Compositor::from_host(compositor)?;
let root = compositor.create_sprite_visual();
root.set_relative_size_adjustment(Vector2::new(1.0, 1.0));
root.set_brush(&compositor.create_color_brush(CompositionColor::rgb(30, 30, 46)));

let _ = host.request_set_child_visual(Some(root.host_visual()), |result| {
    if let Err(error) = result {
        eprintln!("failed to attach composition visual: {error:?}");
    }
});

The observation must live until the effect is cleaned up. The
host sample contains the complete
component lifecycle; start there rather than copying only the bridge calls.

What to read next Copy Chapter

Browse crates/samples/composition for focused hosting and
animation examples.

CompositionScopedBatch::on_completed returns an event revoker that must remain alive until the
tracked work finishes. In a Reactor component, have the callback send a message and update the
retained scene from Component::update.

Internal documentation Copy Chapter

The remainder of this page describes how the crate is built and maintained. Applications do not
need it to use Composition.

Dependencies and feature model Copy Section

The crate depends on windows-core, windows-numerics, windows-collections, and windows-time,
not the umbrella windows crate. Visual offsets and sizes reuse Vector2 and Vector3. Shape
collections use IVector, implicit animation collections use IMap, and animation timing uses
TimeSpan.

The system feature also depends on windows-window and enables dispatcher queue, HWND target,
graphics-device, and drawing-surface support. The reactor feature selects lifted bindings and
exposes host conversions. Compile errors reject zero or two selected stacks.

Cargo unifies features across a build graph. Unified CI jobs that build Reactor exclude
system-stack consumers, then check those consumers in a separate step. Add new consumers to the
matching CI groups. tool-yml generates the stack-specific MSRV and feature checks.

Wrapper model Copy Section

Each safe type is a newtype over one owned COM interface. Concrete visual types dereference through
their base hierarchy. Brush, Shape, and Animation are sealed traits that keep private
generated binding types out of public signatures.

Constructors and immediate recoverable operations return windows_core::Result. Retained-object
property and factory conveniences fail fast on COM errors. CompositionColor wraps the flat
Windows.UI.Color ABI value.

Code generation Copy Section

Composition uses tool-composition because it needs system and non-default lifted metadata. The
tool first uses windows-rdl to generate the lifted native interop metadata from interop.rdl,
then runs windows_bindgen twice with --flat --minimal --dead-code.

• System bindings read the repository's Windows and Win32 metadata and include
  Windows.UI.Composition, dispatcher queue, desktop interop, and surface interop APIs.
• Lifted bindings read the pinned Microsoft UI and Graphics metadata used by Reactor, the
  repository's Windows and Win32 metadata, and the generated interop metadata. They include
  Microsoft.UI.Composition with shared foundation, color, DirectX, and native interop types.

crates/tools/composition/src/composition.txt is the shared filter. System-only regions are omitted
from lifted generation. Composition, DirectX, and native interop entries are rewritten for the
lifted stack. lib.rs selects bindings.rs or bindings_lifted.rs.

Generated binding files are committed and must not be edited by hand. After changing the filter,
metadata inputs, or tool, run:

cargo run -p tool-composition --quiet
cargo check -p windows-composition --quiet

Run cargo run -p tool-yml after changing feature-matrix generation.

Reactor bridge Copy Section

Reactor reports CompositionHostEvent through a typed ElementRef<Grid>. A ready event contains
an application-safe compositor capability and layout metrics. Compositor::from_host adopts that
capability. Visual::host_visual exports only an application-owned lifted visual for attachment.

Both crates generate lifted bindings from the same pinned Microsoft UI metadata. Host attachment
and observation commands exist in Reactor's native and recording runtimes. Window and node
identities reject late events and completions.

Reactor also consumes lifted key-frame, group, easing, and implicit-animation wrappers for element
lifecycle transitions.

Canvas bridge Copy Section

Each stack exposes matching compositor, graphics-device, and drawing-surface interop interfaces. A
Canvas device becomes a CompositionGraphicsDevice, which creates a premultiplied BGRA drawing
surface. A composition surface brush paints that surface onto a visual.

windows-canvas implements the drawing half behind its composition feature. It borrows the
Direct2D context returned by begin_draw, applies the backing-atlas offset, and pairs the operation
with end_draw.

Testing Copy Section

test_composition includes pure value tests and live headless tests. The live tests create a
dispatcher queue and real compositor, then exercise visual, brush, shape, collection, and animation
wrappers without a window. Getter checks also verify that wrapper methods route to the intended
versioned COM interface.

Run:

cargo test -p test_composition

Window hosting is covered by the standalone sample. Reactor host behavior is covered by Reactor's
recording tests and live self-test fixtures.

Crates Windows Core (`docs/crates/windows-core.md`) Copy Section

windows-core

Core COM and WinRT type support shared by the windows-* crates.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 📁 Source

When to use this crate Copy Chapter

Use windows-core directly when you need the common types behind generated Windows bindings,
author a COM or WinRT interface in Rust, or work with COM identity, apartments, factories, or
references. It provides IUnknown, IInspectable, Interface, GUID, RuntimeType, and the
support used by generated projections.

Most code should start with a focused windows-* crate instead. Those crates already depend on and
re-export the core types they need. Binary applications may use the broad
windows projection. Add a direct windows-core dependency when your own public API
names these types or when no higher-level crate
owns the operation.

Getting started Copy Chapter

The crate README has the dependency declaration and a minimal
example using strings and results. For a first COM or WinRT workflow:

1. Select or generate bindings for the Windows API you want to call.
2. Initialize the calling thread's COM apartment when the API requires it.
3. Keep projected interface values as owned Rust values and propagate windows_core::Result.
4. Use Interface::cast when you need another interface implemented by the same object.

For apartment-agnostic command-line code, init_mta initializes an uninitialized calling thread as
MTA and keeps the process MTA alive:

use windows_core::Result;

fn main() -> Result<()> {
    windows_core::init_mta()?;
    // Create and use projected COM or WinRT objects here.
    Ok(())
}

If a UI framework or host initializes COM for you, follow its apartment model instead. init_mta
does not change a thread that is already initialized in another apartment.

For a standalone UI thread, init_sta initializes COM as a single-threaded apartment. Keep the
returned value alive until after the apartment's COM interface values are dropped:

use windows_core::Result;

fn main() -> Result<()> {
    let _apartment = windows_core::init_sta()?;
    // Create and use apartment-bound COM objects here.
    Ok(())
}

Core API model Copy Chapter

Projected interface values are reference-counted owners. Cloning one performs the corresponding
COM reference-count operation, dropping it releases the reference, and cast performs
QueryInterface. Prefer these operations over manual AddRef, Release, or pointer casts.

create_instance::<T>(&class_id) wraps the common non-aggregated
CoCreateInstance(..., CLSCTX_INPROC_SERVER, ...) call. The caller remains responsible for COM
apartment initialization and for choosing a class that supports the calling apartment.

Common tasks Copy Chapter

Moving between interfaces Copy Section

Use cast to request another interface from the same COM identity:

use windows_core::{Interface, IInspectable, IUnknown, Result};

fn as_inspectable(value: &IUnknown) -> Result<IInspectable> {
    value.cast()
}

A failed query is returned as an Error. A Rust type conversion is not a replacement for
QueryInterface unless the generated API provides that conversion.

Sharing an apartment-bound object Copy Section

Do not assume that every interface can be sent to another apartment. Create an
AgileReference<T>, move or clone that reference, and call resolve in the apartment where the
object will be used:

use windows_core::{AgileReference, Interface, Result};

fn make_agile<T: Interface>(value: &T) -> Result<AgileReference<T>> {
    AgileReference::new(value)
}

Weak<T> serves a different purpose: it avoids keeping an object alive and returns None from
upgrade after the object has been destroyed.

Declaring and implementing an interface Copy Section

The default proc-macros feature re-exports #[interface] and #[implement]:

use windows_core::*;

#[interface("7e75ffe0-2f8c-4040-953e-b1f83a48f77b")]
unsafe trait IValue: IUnknown {
    unsafe fn value(&self) -> i32;
}

#[implement(IValue)]
struct Value {
    value: i32,
}

impl IValue_Impl for Value_Impl {
    unsafe fn value(&self) -> i32 {
        self.value
    }
}

fn main() -> Result<()> {
    let object: IValue = Value { value: 42 }.into();
    assert_eq!(unsafe { object.value() }, 42);

    let unknown: IUnknown = object.cast()?;
    let object: IValue = unknown.cast()?;
    assert_eq!(unsafe { object.value() }, 42);

    Ok(())
}

#[interface] generates the vtable, caller wrappers, and implementation trait. #[implement]
generates the wrapper that owns the vtables and reference count. The implementation methods remain
responsible for the interface contract and any safety requirements in the ABI.

Important choices and pitfalls Copy Chapter

• The default features are std and proc-macros. Disable proc-macros when avoiding the
  syn, quote, and proc-macro2 build dependencies matters; the narrower interface_decl! and
  implement_decl! macros remain available.
• Raw interface pointers do not carry an owning lifetime. Use from_raw, from_raw_borrowed,
  into_raw, and related Interface operations only when the ownership contract is known.
• COM apartment initialization is per thread. Initializing one thread does not initialize worker
  threads.
• EventRevoker unregisters on drop. Keep it alive for as long as the handler should run; use
  into_token only when another owner will remove the registration.
• The imp module supports generated code and crate internals. Application code should prefer the
  public projected types and traits.

Samples and next steps Copy Chapter

There is no standalone windows-core sample group. The
windows samples show Result, init_mta, strings, and projected
interfaces in complete API calls. The robot sample shows a Rust
component implementing generated COM and WinRT interfaces for multiple clients.

Continue with windows-result for error propagation and
windows-strings for ABI string choices.

Internal documentation Copy Chapter

The remainder of this page covers how the crate is built and maintained. It is for contributors and
is not needed to use windows-core.

How it's built Copy Section

src/bindings.rs is generated by tool-bindings from crates/tools/bindings/src/core.txt. The
hand-written modules (agile_reference, com_object, compose, event) provide the COM runtime
support. The #[implement]/#[interface] proc macros are re-exported from the
windows-implement/windows-interface crates
behind the proc-macros feature, and the implement_macro/interface_macro modules supply the
implement_decl!/interface_decl! declarative equivalents used when that feature is off.

Testing Copy Section

Run cargo test -p windows-core; see also the workspace test crates.

Crates Windows Default (`docs/crates/windows-default.md`) Copy Section

windows-default

The default Windows metadata used by the build-time crates.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 📁 Source

windows-default embeds the canonical Windows Runtime and Windows API metadata as byte slices.
Build tools use WINRT and WIN32 when they need the standard metadata without locating separate
.winmd files.

Applications should use a focused crate, windows-bindgen, or, for binaries that want a broad
pre-generated surface, windows or windows-sys. Most code
generators should use input_default or reference_default on the builder they already use. Use
windows-default directly only when implementing a metadata tool that accepts in-memory winmd
bytes.

The crate exposes two static byte slices:

Both files are included in the published crate and embedded with include_bytes!. The crate does
not extract files or perform I/O.

First workflow: add standard metadata to a custom index Copy Chapter

1. Construct windows_metadata::reader::File values from WINRT and WIN32.
2. Add component-specific winmd files.
3. Build one windows_metadata::reader::Index over the combined files.
4. Query or transform the index without locating an SDK installation.

tool-reactor-metadata uses this pattern when its metadata resolver combines WinUI winmds with the
standard definitions. If you are compiling RDL or generating Rust, use the neighboring builder
methods instead; they already perform the byte-to-file conversion.

Integration Copy Chapter

The build crates depend on windows-default and expose the metadata through their own builders.
Callers therefore do not need a separate dependency or a path into the Windows SDK.

The windows-bindgen textual adapter accepts --in default. The bindgen, RDL, and Clang builders
use explicit default methods instead; their path-style input methods treat "default" as an
ordinary path. Byte-input APIs remain available for custom metadata that is already in memory.

Programs that link one of these build crates include both metadata payloads in the binary. These
crates are intended for build tools rather than runtime dependencies.

Pitfalls Copy Chapter

• WIN32 is one flat Windows.Win32 metadata set. Published windows and windows-sys feature
  namespaces are created later by tool-package.
• Adding any explicit bindgen input disables the implicit default input. Call input_default when
  the custom metadata references standard types.
• reference_default and resolution_default are not synonyms in windows-clang. The former can
  suppress already-defined declarations; the latter only classifies WinRT ABI projections.
• Linking this crate embeds both payloads even if the tool reads only one static.
• The bytes are build inputs. They do not provide Windows DLLs or make an API available on the
  running operating system.

Internal documentation Copy Chapter

The remainder of this page covers how the crate is built and maintained. It is for contributors and
is not needed to use windows-default.

How it's built Copy Section

The crate has no dependencies. src/lib.rs exposes each committed .winmd through
include_bytes!.

tool-winrt merges the Windows SDK contract metadata, writes canonical RDL, and compiles that RDL
back to Windows.winmd. tool-win32 scrapes the Windows SDK and WDK headers for X64, Arm64, and
X86, merges the architecture-specific RDL, and writes Windows.Win32.winmd.

For missing SDK coverage, add the declaring header to tool-win32's header list and check that its
exports have an import library in the existing list. Regenerate the metadata with tool-win32,
then run tool-package and tool-features to update the published bindings and feature index.
Do not hand-edit the generated RDL or metadata.

See Dependencies for the package versions
and provenance.

Packaging Copy Section

The repository .gitignore normally excludes .winmd files, with an exception for this crate's
two committed payloads. Cargo packages tracked files by default, so Cargo.toml does not need a
separate include list. cargo package -p windows-default must contain both .winmd files.

Testing Copy Section

The metadata is exercised through its consumers:

• test_bindgen, test_rdl, and the windows-clang integration tests cover default and byte
  inputs.
• tool-winrt, tool-win32, and tool-roundtrip verify deterministic metadata generation.
• The tool-yml generated workflows build and document windows-default like the other library
  crates.

After changing the payloads or their generators, run the owning generator and confirm that the
other generators remain output-neutral.

Crates Windows Future (`docs/crates/windows-future.md`) Copy Section

windows-future

Stock async types for Windows APIs.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 🧩 Samples
• 📁 Source

windows-future provides IAsyncOperation and the related WinRT async interfaces, with
conveniences for producing and consuming them from Rust.

When to use Copy Chapter

Use this crate when an API returns one of the four WinRT async interfaces, or when your own WinRT
API must return one:

• IAsyncAction
• IAsyncOperation<T>
• IAsyncActionWithProgress
• IAsyncOperationWithProgress<T, P>

Use an async runtime's native task type for Rust-only work that does not cross a WinRT boundary.
windows-future adapts WinRT operations to Rust futures; it is not an async executor.

Getting started Copy Chapter

The crate README has the dependency declaration and a minimal
ready/spawn example. A typical first workflow is to receive an IAsyncOperation<T> from a
Windows API, choose how the surrounding code should wait for it, and propagate its
windows_core::Result<T>:

async fn consume(operation: windows_future::IAsyncOperation<i32>) -> windows_core::Result<i32> {
    let value = operation.await?;
    Ok(value + 1)
}

The operation begins according to the WinRT API's rules; converting it into a future does not
create or schedule the operation.

Consuming an operation Copy Chapter

Choose one completion style and let it own the operation's completion handler:

All three paths return or receive a Result, including failures reported by the WinRT operation.
Avoid join() on a UI thread or another thread that must continue pumping work.

Producing an operation Copy Chapter

ready wraps a result that is already available. spawn runs a Send + 'static closure on the
Windows thread pool and exposes its result as a WinRT async object. Pick IAsyncAction for ()
and IAsyncOperation<T> for a value. The progress variants provide the corresponding interface
shape, but closures passed to spawn do not report intermediate progress.

The std feature is enabled by default and supplies ready, spawn, and the IntoFuture
implementation used by .await. Without it, the interface types and the join/when consumption
helpers remain available.

Platform constraints and pitfalls Copy Chapter

• The crate targets Windows and WinRT async interfaces.
• A WinRT completion handler can be assigned only once. These helpers may assign that handler while
  an operation is running, so do not combine them or a direct SetCompleted call on one operation.
• spawn is for blocking or synchronous work that is safe on a pool thread. It does not make
  thread-affine UI or COM work safe to move off its owning thread.
• ready and spawn expose Cancel and Close through IAsyncInfo, but these constructors do
  not interrupt the supplied closure.

Sample and next steps Copy Chapter

The spawn sample contrasts an immediately ready operation
with work submitted to the Windows thread pool. Next, inspect the API that produces your operation
to determine its result type, error behavior, cancellation support, and any thread affinity.

Internal documentation Copy Chapter

The remainder of this page covers how the crate is built and maintained. It is for contributors and
is not needed to use windows-future.

How it's built Copy Section

src/bindings.rs is generated by tool-bindings from crates/tools/bindings/src/future.txt and
future_impl.txt; the Future bridge is hand-written.

Testing Copy Section

Run cargo test -p windows-future; see also the workspace test crates.

Crates Windows Implement (`docs/crates/windows-implement.md`) Copy Section

windows-implement

The procedural macro that exposes a Rust type through COM or WinRT interfaces.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 📁 Source

windows-implement provides #[implement]. The macro builds the vtables, identity object,
reference count, QueryInterface routing, and conversions needed to expose a Rust struct through
one or more generated interfaces.

Intended audience Copy Chapter

Use this macro when Rust is the implementation side of COM or WinRT: a component, callback,
activation factory, shell extension, test object, or another object passed to an API as an
interface. Calling an existing interface does not require #[implement].

Application and component code normally imports windows_core::implement. The separate
windows-implement dependency is an implementation detail of windows-core's default
proc-macros feature. Its generated code also depends on windows-core, so direct consumption
offers no standalone runtime.

Interfaces usually come from a focused crate or custom
windows-bindgen output. A binary application may instead use the broad
windows projection. Pair this macro with
#[interface] only for a manually owned or missing interface definition.
See windows-core for a compact end-to-end example.

Implementation model Copy Chapter

For #[implement(IValue)] struct Value, the interface declaration or generated bindings provide an
IValue_Impl trait. The macro creates a Value_Impl wrapper. Implement the generated trait for
that wrapper, then convert the original Value into an interface type.

For an inherited interface, implement the *_Impl traits required by the interface and its parent
chain. List each independently exposed interface in #[implement(...)]; do not list a base merely
to compensate for a missing parent relationship in the interface definition.

The resulting interface value owns a COM reference. Cloning an interface increments the reference
count, dropping it decrements the count, and cast uses QueryInterface. The original Rust value
is dropped when the final COM reference is released.

Implementation methods use the projected signatures generated for the interface. Return
windows_core::Result<T> when offered by that trait, and return a precise HRESULT when the trait
uses raw status values. The generated thunk translates Result errors at the ABI boundary.

Threading and agility Copy Chapter

Implementations are agile by default. The macro exposes IAgileObject and an agile marshaler
unless the attribute includes Agile = false. This is a COM promise, not a convenience flag.

Before accepting the default, verify that:

• method calls may arrive from the apartments and threads allowed by the interface contract;
• shared mutable state is synchronized correctly;
• borrowed thread-affine resources never escape their owning apartment;
• destruction is valid on the thread that releases the final reference.

Use Agile = false for an apartment-affine object. Add an interface such as IAgileObject
explicitly only when the object implements that contract itself. For WinRT implementations,
TrustLevel = Partial or TrustLevel = Full controls the value reported by
IInspectable::GetTrustLevel; omit it unless the component's contract requires a nondefault trust
level.

Errors, panics, and pointers Copy Chapter

Treat every generated implementation method as an FFI boundary:

• Validate raw pointers before dereferencing them when the ABI permits validation.
• Initialize required out parameters on every success path and on failure paths required by the
  interface contract.
• Convert expected failures into Error, Result, or the documented HRESULT.
• Do not let a panic cross the generated external function. Remove panic paths from boundary code
  or catch them at a layer that can map them to a defined failure.
• Keep interface references alive for as long as stored raw pointers derived from them are used.

Error::new or Error::from_hresult preserves an HRESULT for projected Result methods. Use the
error code specified by the interface contract; an arbitrary failure code makes native callers
hard to diagnose.

Reference-counted interface fields can form cycles. COM reference counting does not collect them.
Use weak references where the interface model supports them or define an explicit teardown path.

Practical component workflow Copy Chapter

1. Generate or declare the interfaces and inspect their *_Impl traits.
2. Design a Rust state type with explicit synchronization and apartment assumptions.
3. Add #[implement] with only the interfaces the object must expose.
4. Implement every required *_Impl trait on the generated wrapper.
5. Convert the value to the narrowest interface returned to the caller.
6. Test cast for each supported and unsupported interface, not just direct method calls.
7. Test failure HRESULTs, out-parameter initialization, final release, and any cross-thread use
   promised by agility.

For static factories and exported components, the repository's robot component sample shows
StaticComObject, activation factory output, OutRef, and generated implementation traits. The
implementation test crates contain smaller examples for identity, inheritance, generic WinRT
interfaces, agility, and error propagation.

Pitfalls Copy Section

• Implementing the Rust trait does not make an incorrect interface declaration ABI-safe.
• Interior mutability without synchronization can violate the default agile contract.
• Returning an interface to native code transfers a reference-counted ownership interest; avoid
  temporary raw pointers that outlive their owner.
• cast success is governed by the interface list and inheritance graph generated into
  QueryInterface.
• Generic constraints from the annotated struct are carried into the generated wrapper. Keep them
  compatible with every generated *_Impl trait.

When procedural macros are disabled, windows-core::implement_decl! covers the common always-agile
case with a more explicit and narrower declarative syntax. Use its module documentation as the
grammar reference.

Internal documentation Copy Chapter

windows-implement is a syn/quote procedural macro crate. src/lib.rs parses the annotated
struct, interface list, generics, Agile, and TrustLevel options. src/gen.rs emits the wrapper,
vtable chains, identity and reference-counting implementation, interface conversions, and
QueryInterface routing.

The crate depends on the *_Impl traits and vtable constructors emitted by
windows-interface or windows-bindgen. Generated paths target ::windows_core; the proc macro
crate is separated only to satisfy Rust's procedural macro packaging model.

Run cargo test -p windows-implement; the test_implement and test_implement_core crates cover
the runtime contract more broadly.

Crates Windows Interface (`docs/crates/windows-interface.md`) Copy Section

windows-interface

The procedural macro that turns a Rust trait declaration into a COM interface.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 📁 Source

windows-interface provides the #[interface] attribute used to declare a COM interface that can
be called or implemented from Rust.

Intended audience Copy Chapter

Prefer interfaces from a focused crate or generated with
windows-bindgen. Binary applications may also use interfaces from the broad
windows projection. Declare an interface manually only when the ABI is owned by the
project, the interface is missing from metadata, or a focused interoperability test needs an
independent declaration.

The macro is normally consumed as windows_core::interface, not by depending on this crate
directly. windows-core re-exports it through its default proc-macros feature and supplies every
runtime type referenced by the generated code. The separate crate exists because procedural macros
must be compiled as a proc-macro crate.

See windows-core for the paired declaration and implementation example. Use
the lower-level interface_decl! macro from windows-core only when the procedural macro feature
is disabled and its narrower grammar is sufficient.

Designing a declaration Copy Chapter

An interface declaration records an ABI, not an ordinary Rust trait design. Verify these items
before writing it:

1. Use the interface's exact IID. Reusing or mistyping an IID can make QueryInterface return an
   object with an incompatible vtable.
2. Name the direct base interface after :. Use IUnknown for a base COM interface.
3. Preserve method order, including every inherited method represented by the parent.
4. Match parameter types, pointer constness, return types, and Windows integer widths exactly.
5. Mark the trait unsafe; callers and implementors must uphold the ABI contract.

The accepted trait form is intentionally restricted. Methods take &self; async methods,
generics, explicit ABI declarations, variadics, default bodies, and non-documentation attributes
are rejected. One parent path describes the vtable inheritance chain.

For COM methods that return only an HRESULT status, Result<()> provides a projected caller and
implementor shape while the vtable entry returns HRESULT. An explicit HRESULT return preserves
the raw status. Do not replace an ABI out parameter with Result<T> by analogy: declare the
parameter shape expected by the macro and ABI. Ref<T> and OutRef<T> are supported for interface
input and output parameters and project to the corresponding Param and OutParam caller forms.

What the macro generates Copy Chapter

For an interface named IValue, #[interface] generates:

• the transparent IValue interface wrapper;
• an Interface implementation containing the IID and vtable type;
• Deref to the declared parent interface;
• caller methods that dispatch through the vtable;
• the IValue_Vtbl layout;
• the IValue_Impl trait used by #[implement];
• conversions and QueryInterface support needed by windows-core.

Caller methods remain unsafe because the declaration cannot prove pointer validity or
API-specific invariants. The wrapper handles COM identity and reference counting through
windows-core; it does not validate a hand-written ABI.

Practical workflow and pitfalls Copy Chapter

Keep a manual interface declaration next to a citation or checked-in definition of its ABI. Add a
test that exercises both a known implementation and QueryInterface through the expected IID when
possible.

Common failures are severe:

• A wrong method order or signature dispatches through the wrong machine-level contract.
• A wrong parent produces an invalid inherited vtable layout.
• A correct IID paired with an incorrect layout can corrupt memory.
• Rust references in an ABI are valid only when their representation and lifetime are part of the
  agreed Rust-to-Rust contract. Public COM ABIs normally use Windows ABI types and pointers.
• Result<()> translates an error into HRESULT at the boundary; panics are not COM errors and must
  not unwind across an external call.

Prefer generating the declaration from .winmd with windows-bindgen when metadata can describe
the interface. That keeps caller and implementation projections aligned and avoids maintaining a
vtable by hand.

Internal documentation Copy Chapter

windows-interface is a syn/quote procedural macro crate. src/lib.rs parses the restricted
trait and GUID. src/generation.rs emits the interface wrapper, vtable, implementation trait,
inheritance traversal, and Ref<T>/OutRef<T> parameter adapters. src/guid.rs parses the IID.

The generated paths are rooted at ::windows_core, which is why direct use still requires a
compatible windows-core dependency. The implementation macro consumes the generated *_Impl
traits and vtable constructors; changes to either macro must preserve that contract.

Run cargo test -p windows-interface; the test_interface and implementation test crates cover
cross-crate behavior.

Crates Windows Link (`docs/crates/windows-link.md`) Copy Section

windows-link

A macro for declaring Windows DLL imports without an import library.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 📁 Source

windows-link provides the link! macro. It emits a raw external function declaration using
Rust's raw-dylib linking mode and a function-pointer type alias with the same name.

Intended audience Copy Chapter

This crate is for binding generators and authors of narrow low-level bindings. The generated
windows and windows-sys crates already declare and link the Windows APIs they expose, so
application code should not redeclare those functions.

Use windows-link directly when:

• an exported Windows function is absent from the available metadata;
• a project owns a small reviewed raw binding;
• generated --sys bindings use link! as their runtime link mechanism;
• the function-pointer type emitted beside the declaration is useful to an abstraction.

Use windows-bindgen when several metadata-backed declarations are needed.
A binary application may use windows or windows-sys when the
published umbrella crates already contain the API. Reusable libraries should prefer focused crates
and narrow generated bindings.

Unlike #[interface] and #[implement], link! is not a procedural macro normally re-exported for
application use. Rich generated bindings invoke it through windows-core; raw generated bindings
depend on windows-link directly. Most users therefore encounter this crate as binding
infrastructure rather than as an application dependency.

Declaration contract Copy Chapter

The README shows the macro grammar and its function-pointer alias. Every token in a declaration is
part of the ABI contract:

• The library literal must name the DLL that exports the symbol on supported Windows versions.
• The ABI literal must match the export, commonly "system" for Windows APIs.
• The optional link-name literal maps the Rust identifier to a differently named export.
• Parameter and return types must match the export exactly, including pointer constness and integer
  width.
• The declaration is unsafe even when a particular function happens to accept only integers.

On x86 Windows, the macro requests undecorated import names. On other Windows architectures it
uses a verbatim raw-dylib import. Do not add architecture-specific spelling to compensate without
checking the actual exported symbol and Rust's ABI behavior.

The type alias has the same identifier as the function because Rust has separate value and type
namespaces. This permits code such as let callback: GetTickCount = GetTickCount;. The alias is an
unsafe extern function pointer and carries the same caller obligations as the direct declaration.

Practical workflow Copy Chapter

Before adding a declaration:

1. Search the windows and windows-sys API reference for the symbol.
2. Confirm the DLL, export name, calling convention, and exact signature from an authoritative
   Windows definition.
3. Decide which Windows versions and architectures the surrounding crate supports.
4. Put the declaration in a private FFI module.
5. Add a safe wrapper only if its preconditions, ownership, result convention, and cleanup can be
   expressed correctly.
6. Test on each supported architecture when decoration, variadics, or unusual ABI types are
   involved.

link! only arranges static import resolution. It is not delayed loading and does not make an
optional export safe to call on older systems. For optional APIs, resolve the symbol dynamically
and keep the module loaded for at least as long as the function pointer can be called.

Pitfalls Copy Section

• A successful link does not prove the Rust signature is ABI-compatible.
• DLL forwarding and API-set names are Windows implementation details; use the library contract
  documented for the API.
• The macro does not generate feature gates. Add the surrounding cfg and Cargo feature policy in
  the binding crate.
• A declaration produced on a non-Windows target does not make the Windows export available there.
• Variadic and uncommon calling conventions have Rust and architecture restrictions. Prefer
  metadata-backed windows-sys output when it supports the declaration.
• Do not duplicate a symbol declaration with a different signature in the same program.

Internal documentation Copy Chapter

The crate is hand-written and no_std. src/lib.rs contains the three link! expansions: x86
Windows, other Windows architectures, and non-Windows parsing support. The Windows expansions use
kind = "raw-dylib" and +verbatim; x86 also sets import_name_type = "undecorated".

windows-bindgen emits this macro for sys-style bindings unless --extern is selected.
windows-core re-exports the macro for rich and minimal generated bindings, while windows-sys
calls it through its direct dependency.

Run cargo test -p windows-link; generated binding tests exercise its wider use.

Crates Windows Metadata (`docs/crates/windows-metadata.md`) Copy Section

windows-metadata

A low-level reader and writer for the ECMA-335 metadata format.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 📁 Source

windows-metadata reads and writes the ECMA-335 metadata format used by .NET, WinRT, and the Win32
metadata. It is the foundation windows-bindgen builds on. The
reader::Index type loads one or more .winmd files and lets you query namespaces, type
definitions, and their members.

Applications should start with a focused crate or windows-bindgen; binary applications may use
windows or windows-sys when they want a broad pre-generated
surface. Use windows-metadata directly when writing a metadata inspector, generator, merger, or
namespace transformation. The API exposes metadata facts; it does not project them into a safe Rust
API.

Start with the crate README for dependency setup and a
focused type query.

First workflow: inspect an API definition Copy Chapter

1. Load a file with reader::Index::read, or construct reader::File values and pass them to
   Index::new.
2. Locate a type with get when duplicates are possible or expect when exactly one definition is
   an invariant.
3. Inspect category, extends, fields, methods, signatures, attributes, and nested types.
4. Keep rows borrowed from the index; use leak or read_static only when a tool requires
   process-lifetime rows.

For methods, match ECMA-335 parameter rows with
MethodDef::params_by_sequence(signature.types.len()). Sequence 0 belongs to the return value;
nonzero sequences are one-based signature positions. params() instead returns physical table
order and is appropriate for lossless copying, not semantic parameter association.

tool-reactor-metadata provides a larger example. Its metadata resolver loads WinUI winmd files,
adds windows-default byte inputs, indexes classes and interfaces, then uses method signatures and
attributes to drive generated UI code. tool-features uses Index::iter_items to enumerate
types, free functions, and constants.

Input and output model Copy Chapter

reader::File owns one winmd byte stream. reader::Index combines files into searchable
namespace, type, nested-type, and expanded Win32 Apis indexes. A zero architecture selector keeps
all rows; Index::new_for_architecture selects neutral rows plus one of X86 (1), X64 (2), or Arm64
(4).

The writer API is lower-level. writer::File builds ECMA-335 rows and into_stream returns the
finished bytes. Prefer windows-rdl when a reviewable source format is useful;
use the writer directly when a tool is copying or synthesizing table rows.

Common tool tasks Copy Chapter

The merger accepts files or directories. Architecture merge retains one neutral definition only
when the same shape is present on every merged architecture; divergent shapes are tagged and kept.
The remapper rewrites definitions and references together and splits Win32 Apis members across
their routed target namespaces.

Integration and pitfalls Copy Chapter

• windows-default supplies the standard WinRT and Win32 files as byte
  slices. Construct reader::File values from those bytes when a custom tool needs them.
• windows-rdl provides a higher-level text authoring and decompilation path.
• windows-bindgen applies Rust projection policy to these raw metadata
  facts.
• A metadata parameter marked neither In nor Out is ParamDirection::Unspecified. Do not infer
  input direction in the metadata layer.
• Optional, reserved, retval, and buffer-count annotations are independent facts. Consumers decide
  how those facts affect their public API.
• Duplicate type definitions can be valid in an unfiltered multi-architecture index. Do not call
  expect unless uniqueness is guaranteed.
• Preserve physical row order when copying malformed or sparse metadata; use semantic helpers when
  interpreting it.

The focused fixtures in crates/tests/libs/rdl and crates/tests/libs/bindgen show metadata
shapes. The main tool consumers are tool-winrt, tool-win32, tool-package, tool-features,
and tool-reactor-metadata.

Internal documentation Copy Chapter

The remainder of this page covers how the crate is built and maintained. It is for contributors and
is not needed to use windows-metadata.

How it's built Copy Section

Consumed by windows-bindgen. src/bindings.rs is generated by tool-bindings from
crates/tools/bindings/src/metadata.txt; the ECMA-335 tables and readers are hand-written.

Multi-arch merge Copy Section

windows-metadata's merge module coalesces the per-architecture winmds that tool-win32 scrapes
(x64, arm64, x86) into a single winmd. A type identical across every arch is emitted once as
arch-neutral; a type that diverges is split into per-arch copies, each tagged with a
SupportedArchitectureAttribute (spelled #[arch(X86|X64|Arm64)] in RDL).

reader::Index::new_for_architecture selects one of those copies while retaining neutral rows.
Its bit values match the metadata attribute: 1 for X86, 2 for X64, and 4 for Arm64. Plain
Index::new keeps every copy for tools that need to inspect or merge the complete metadata.

The collapse-or-split decision is structural, driven by type_sig() - a hash of everything that can
legitimately differ between architectures:

• fields - name, type, and constant value (so an enum whose members hold different per-arch
  values splits instead of silently dropping the divergent values);
• method signatures - Win32 callbacks and WinRT delegates have no fields and diverge only in
  their Invoke signature, so a fields-only signature would wrongly collapse arch-divergent
  callbacks into one untagged copy;
• layout - #pragma pack and ClassLayout;
• AlignmentAttribute - __declspec(align(N)) raised alignment is encoded only by that
  attribute (ClassLayout can only lower alignment), so a type that differs solely in forced
  over-alignment must fold the attribute into the signature or the divergent copy is lost;
• flags - the type's attribute flags.

Types present on only a subset of arches still go through the same structural split, so a type
that is present on x64+arm64 (but not x86) and diverges between those two is split per arch rather
than collapsing to whichever copy happened to be first. A group is emitted arch-neutral only when
its signature spans every arch in the run.

Unmanaged callbacks have one narrow semantic reconciliation before that split. If at least one
architecture explicitly uses isize or usize and every other copy uses the same native-sized
integer for its architecture (i32/u32 on x86, i64/u64 on x64 or arm64), the callback keeps
one native-sized signature. It becomes arch-neutral when present on every merged architecture;
otherwise it keeps its subset arch tag. This handles SDK declarations such as FARPROC, whose
return is spelled INT_PTR on 64-bit but legacy int on x86. A plain i32/i64 pair does not
qualify: the explicit native-sized spelling is required as semantic evidence.

The merge is deterministic: it stages through BTreeMaps and insertion-ordered Vecs, with no
HashMap reaching the output.

The merger and namespace remapper accept strings, Path, or PathBuf for input and output paths
and retain them as PathBuf. The remapper provides singular/plural input/inputs,
source/sources, and route/routes methods.

Nested type identity Copy Section

Decoded signature TypeName values retain the outermost namespace and a slash-separated name,
such as Test and Outer/Child. TypeDef::full_name, TypeRef::full_name, and
TypeDefOrRef::full_name expose that identity; their name and namespace accessors still return
the raw table columns. TypeDef names follow NestedClass, while TypeRef names follow enclosing
TypeRef scopes.

The writer turns the qualified name into an enclosing-TypeRef chain. Merge preserves that chain,
and namespace remapping routes its outermost type without changing the nested path. A
NestedClass row alone does not resolve an unqualified, module-scoped reference to a nested type
(ECMA-335 II.7.3 and II.22.38).

Nested generic instantiations are outside the writer's supported input. Both signature and
TypeSpec emission assert against them rather than derive a nested name's arity from the total
generic argument count. Top-level generics and non-generic nested records remain supported.

test_metadata::nested_references checks physical scope chains, signature decoding through both
TypeRef and TypeDef tokens, repeated leaf names under different parents, rejection of nested
generic instantiations, merge, and namespace remapping.

Method parameter association Copy Section

ECMA-335 Param rows are not positional. Param.Sequence == 0 describes the return value, and a
nonzero sequence identifies a one-based signature parameter. Rows may be absent, sparse, or stored
out of order.

reader::MethodDef::params_by_sequence(parameter_count) returns a separate optional return row and
one Option<MethodParam> per signature position. It reports duplicate sequences and nonzero
sequences outside the signature as MethodParamSequenceError; consumers do not choose a
first-wins or last-wins interpretation. If several rows are invalid, the first invalid physical row
is reported. MethodDef::params() still iterates physical table order. The merge and remap writers
use that physical iterator on purpose so lossless copying preserves row order, sparse rows, and
malformed input for a later validator.

MethodParam::direction() decodes only the In and Out bits into ParamDirection::{Input, Output, InputOutput, Unspecified}. is_optional, is_reserved, and is_retval_attribute expose
their independent metadata facts. These helpers do not inspect pointer mutability, infer a default
for an unspecified direction, combine ReservedAttribute with Optional, or decide whether a
parameter should become a language return value. Array and byte-count attributes remain available
through attributes() because each projection validates different public-surface shapes.

Determinism and the winmd writer Copy Section

The writer is the foundation of the pipeline's reproducible builds. It stages Constant /
Attribute / GenericParam (and the bindgen TypeTree) in BTreeMaps / BTreeSets, and the
module MVID is a fixed zero GUID, so regenerating a winmd is byte-for-byte identical across
platforms (CI validates the committed winmds on Linux).

Notable invariants in the ECMA-335 tables:

• The HasSemantics coded index and the Property/Event/MethodSemantics tables are emitted
  only when non-empty, and MethodSemantics rows are sorted by Association - strict readers
  reject an unsorted table.
• write_index asserts on the run-list one-past-end sentinel rather than silently wrapping to 0
  for a target table with exactly 65535 rows (the guard lives on the write side so the reader's
  width threshold stays ECMA-conformant for external winmds).
• Value::Bool constants round-trip symmetrically (the reader maps ELEMENT_TYPE_BOOLEAN); the CLR
  element-type vocabulary (ELEMENT_TYPE_*) is hand-authored in src/clr.rs because its defining
  header (corhdr.h) ships only in the .NET SDK and cannot be scraped.

Testing Copy Section

Run cargo test -p windows-metadata; see also the workspace test crates. The arch-merge
collapse/split rules are pinned by arch_roundtrip.rs (divergent fields, callbacks, forced
alignment, enum constant values, subset-present divergence) and merge.rs (native-sized callback
reconciliation). method_params.rs authors metadata directly with writer::File and covers dense,
absent, return, sparse, out-of-order, duplicate, and out-of-range parameter rows. It also covers all
four raw directions and verifies that optional, reserved, retval, and count attributes remain
independent facts. remap.rs covers explicit and fallback namespace routing, singular/plural
builder methods, missing outputs, and invalid inputs.

Crates Windows Numerics (`docs/crates/windows-numerics.md`) Copy Section

windows-numerics

Graphics-oriented vector and matrix math from Windows.Foundation.Numerics.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 📁 Source

windows-numerics provides the POD math value types used by Direct2D, composition, and other
graphics APIs: Vector2, Vector3, Vector4, Matrix3x2, and Matrix4x4. Each is a plain
#[repr(C)] struct with inherent methods and operator overloads layered on top.

When to use Copy Chapter

Use this crate when a Windows graphics or composition API accepts
Windows.Foundation.Numerics values. The structs have the expected Windows ABI layout, so vectors
and matrices can cross those API boundaries without conversion.

For a Rust-only math engine, consider a general-purpose math crate if you need quaternions, planes,
SIMD-specific operations, or a larger set of transforms. windows-numerics focuses on the five
value types projected by this crate.

Getting started Copy Chapter

The crate README contains the dependency declaration and
minimal vector and matrix examples. A useful first workflow is to calculate with the same types
that the target Windows API expects:

use windows_numerics::{Matrix3x2, Vector2};

let position = Vector2::new(20.0, 30.0);
let offset = Vector2::new(5.0, -10.0);
let translated = position + offset;
let transform = Matrix3x2::translation(translated.x, translated.y);

assert_eq!((transform.m31, transform.m32), (25.0, 20.0));

Keep values as f32; these Windows numeric types do not provide f64 variants.

Vectors Copy Chapter

Vector2, Vector3, and Vector4 provide constructors, zero/one and axis vectors, dot products,
length and distance operations, and normalization. Vector3 also provides a cross product.
Arithmetic operators work with owned or borrowed vectors; multiplication and division between
vectors are component-wise. Scalar multiplication and division use f32.

Use length_squared or distance_squared when only a comparison is needed, avoiding a square
root. Check for a zero-length vector before calling normalize, since normalization divides by
the length.

Matrices and transforms Copy Chapter

Matrix3x2 represents 2D affine transforms. It provides identity, translation, scale, rotation,
and skew constructors, including variants around a center point. Rotation and skew angles are in
degrees.

Matrix4x4 provides 3D translation, Y-axis rotation in degrees, and perspective projection.
Matrix multiplication composes transforms; preserve the order expected by the Windows API and test
the result with representative points rather than assuming another math library's convention.

Platform constraints and pitfalls Copy Chapter

• The types are plain #[repr(C)] structs with public fields. Initialize every field when using a
  struct literal, or prefer the constructors.
• Equality is exact floating-point equality. Use an application-appropriate tolerance for computed
  values.
• Normalizing a zero vector and constructing invalid projection inputs can produce non-finite
  values.
• The default std feature supplies square root and trigonometric methods used by length,
  distance, normalization, rotation, and skew. Basic value types and arithmetic remain available
  without it.

Samples and next steps Copy Chapter

The canvas, composition, Direct2D, and DirectComposition samples use these types in real graphics
workflows. Start with the
canvas transform sample for a 2D
matrix and the
composition animation sample
for vectors passed to composition APIs.

Internal documentation Copy Chapter

The remainder of this page covers how the crate is built and maintained. It is for contributors and
is not needed to use windows-numerics.

How it's built Copy Section

src/bindings.rs is generated by tool-bindings from crates/tools/bindings/src/numerics.txt; the
inherent methods and operator trait impls are hand-written.

Testing Copy Section

Run cargo test -p windows-numerics; see also the workspace test crates.

Crates Windows Pickers (`docs/crates/windows-pickers.md`) Copy Section

windows-pickers

File and folder pickers backed by the Windows Common Item Dialog.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 🧩 Samples
• 📁 Source
• Reactor guide
• Window guide

When to use it Copy Chapter

Use windows-pickers when a Windows desktop application needs the system file-open, folder, or
file-save dialog. The crate returns filesystem PathBuf values and uses the Windows Shell for
navigation, filtering, recent locations, and overwrite confirmation.

The crate wraps the common picker workflows rather than every IFileDialog extension point. Use
raw Windows bindings when an application needs custom dialog controls, dialog events,
non-filesystem Shell items, or other advanced Common Item Dialog APIs.

The basic idea Copy Chapter

Choose a picker, configure it with consuming builder methods, and show or request it:

Showing a picker is synchronous. IFileDialog::Show runs a nested modal message loop and returns
after the user confirms or cancels the dialog. The crate does not read, create, or modify the
selected file.

Choose how to host the picker Copy Chapter

The default system feature accepts a borrowed windows_window::Window:

[dependencies]
windows-core = "0.100"
windows-pickers = "0.100"
windows-window = "0.100"

Applications that own an HWND through another windowing library can disable default features and
use show_for_hwnd:

windows-pickers = { version = "0.100", default-features = false }

Enable reactor to request a picker from a Reactor component:

windows-pickers = { version = "0.100", default-features = false, features = ["reactor"] }
windows-reactor = "0.100"

The system and reactor features are additive. An application may enable both when it uses both
host types.

Pick your first file Copy Chapter

This complete program initializes COM, creates an owner window, and shows an open-file picker:

use windows_pickers::{OpenFilePicker, Result};
use windows_window::Window;

fn main() -> Result<()> {
    let _apartment = windows_core::init_sta()?;
    let window = Window::new("Open a file").create()?;

    let path = OpenFilePicker::new()
        .title("Open a Rust source file")
        .filter_extensions("Rust source", ["rs"])
        .filter_all()
        .show(&window)?;

    if let Some(path) = path {
        println!("{}", path.display());
    }

    Ok(())
}

The calling UI thread must be a COM single-threaded apartment (STA). An application with an
existing UI framework normally uses the apartment initialized by that framework rather than
initializing COM again. Keep the owner window alive until show returns.

Pick files and folders Copy Chapter

OpenFilePicker::show and FolderPicker::show return one selected path:

let file = OpenFilePicker::new().show(&window)?;
let folder = FolderPicker::new().show(&window)?;

Use show_multiple when the user may select more than one item:

let files = OpenFilePicker::new()
    .title("Attach files")
    .commit_label("Attach")
    .filter_all()
    .show_multiple(&window)?;

let folders = FolderPicker::new()
    .title("Add search folders")
    .show_multiple(&window)?;

commit_label changes the confirmation button for a task-specific action such as "Attach",
"Import", or "Choose".

Choose a save path Copy Chapter

SaveFilePicker configures the proposed file name, extension, filters, and overwrite behavior:

let path = SaveFilePicker::new()
    .title("Save report")
    .filter_extensions("Text", ["txt"])
    .suggested_name("report")
    .default_extension("txt")
    .overwrite_prompt(true)
    .show(&window)?;

suggested_name sets the initial name. default_extension supplies the extension when the user
enters a name without one; a leading period is optional. Configured filters restrict the accepted
file types. overwrite_prompt explicitly enables or disables replacement confirmation, while
leaving it unset preserves the native dialog default.

The returned path is only the user's choice. The application remains responsible for opening the
file and handling races, permissions, sharing violations, and any final overwrite policy.

Configure file filters Copy Chapter

Add extension filters directly to an open or save picker:

let picker = OpenFilePicker::new()
    .filter_extensions("Images", ["png", "jpg", "jpeg"])
    .filter_extensions("Portable Network Graphics", ["png"])
    .filter_all()
    .initial_filter(0);

Extensions may include a leading period. Use filter_patterns for native wildcard patterns:

let picker = OpenFilePicker::new()
    .filter_patterns("Reports", ["report-*.csv", "summary-*.csv"])
    .filter_all();

Each filter must have a nonempty name and at least one nonempty extension or pattern.

initial_filter uses a zero-based index into the configured filters. An out-of-range index is
reported as an error before the dialog opens.

Set the initial location Copy Chapter

Each picker provides two path-based and two known-folder methods:

PickerLocation supports Desktop, Documents, Downloads, Music, Pictures, Videos, Computer, and
3D Objects. When both a default and forced location are configured, the default is applied first
and the forced location determines the initial view.

Path-based locations must resolve to Shell items. An invalid or unavailable configured path is
reported before the dialog opens.

Preserve Shell state Copy Chapter

Pass a stable GUID to client_id when the Shell should remember state such as the last visited
folder:

let picker = OpenFilePicker::new()
    .client_id(GUID::from_u128(0x6d81d46c_77da_4874_8ca7_754546ba6803));

Use the same GUID for picker uses that should share history and different GUIDs for independent
histories. Without a client ID, the crate does not opt the dialog into this persistence mechanism.

Handle cancellation and errors Copy Chapter

Single-selection pickers return Result<Option>:

Multiple-selection methods return Result<Vec>. An empty vector means cancellation
because the dialog cannot successfully confirm an empty selection. Only the native
ERROR_CANCELLED result is translated into cancellation; other failures remain
windows_core::Error values.

Use a raw HWND Copy Chapter

The raw-handle methods work with another Win32 host:

let path = OpenFilePicker::new().show_for_hwnd(hwnd)?;

The pointer must be a valid, non-null owner HWND on the calling UI thread and remain live until the
method returns. The calling thread must be a COM single-threaded apartment (STA). The raw methods
are available without the system feature.

Request a picker from Reactor Copy Chapter

Picker methods cannot call IFileDialog::Show inline while Reactor is publishing component state.
The reactor feature adds request and request_multiple, which stage the modal operation and
map its result into a component message:

enum Message {
    Open,
    Picked(windows_pickers::Result<Option<PathBuf>>),
}

fn update(&mut self, message: Message, context: &ComponentContext<Self>) {
    match message {
        Message::Open => {
            if !OpenFilePicker::new()
                .filter_all()
                .request(context, Message::Picked)
            {
                self.status = "Another window operation is pending".to_string();
            }
        }
        Message::Picked(Ok(Some(path))) => {
            self.status = path.display().to_string();
        }
        Message::Picked(Ok(None)) => {
            self.status = "Selection cancelled".to_string();
        }
        Message::Picked(Err(error)) => {
            self.status = format!("Picker failed: {error}");
        }
    }
}

A true return means Reactor staged the request, not that the picker has already opened. Reactor
runs it on the owning window's UI thread after the current publication commits and queues the
mapped message for a later component update. It discards the operation if publication fails, the
component retires, or the window starts closing.

Each Reactor window accepts one pending native window operation at a time. Other Reactor windows
remain independent. No additional COM initialization is needed in a Reactor application. The
reactor/message-box sample uses the same
ComponentContext::run_window support with another native modal API.

Samples Copy Chapter

Run an individual standalone workflow with:

cargo run -p pickers-standalone -- open
cargo run -p pickers-standalone -- open-multiple
cargo run -p pickers-standalone -- folder
cargo run -p pickers-standalone -- folder-multiple
cargo run -p pickers-standalone -- save

Run the Reactor sample with:

cargo run -p pickers-reactor

Internal documentation Copy Chapter

This section is for contributors to windows-pickers.

src/bindings.rs is generated by tool-bindings from
crates/tools/bindings/src/pickers.txt. It contains the minimal Common Item Dialog, Shell item,
COM activation, and string-allocation APIs used by the hand-written wrapper.

Open and folder pickers create FileOpenDialog; the save picker creates FileSaveDialog. All
preserve the native option defaults while adding FOS_FORCEFILESYSTEM. Folder selection adds
FOS_PICKFOLDERS, multiple selection adds FOS_ALLOWMULTISELECT, and save dialogs with filters
add FOS_STRICTFILETYPES.

Shared configuration retains UTF-16 backing storage until Show returns. Filesystem locations are
converted with SHCreateItemFromParsingName, known locations with
SHCreateItemInKnownFolder, and selected IShellItem values with SIGDN_FILESYSPATH. Returned
strings are copied into PathBuf values before CoTaskMemFree.

Client identity is applied before folder configuration so a forced folder still determines the
initial view. Requested option bits are merged with GetOptions rather than replacing unrelated
native defaults.

After changing the binding filter, run:

cargo run -p tool-bindings --quiet
cargo check -p windows-pickers --quiet

Unit tests cover configuration and cancellation translation without opening modal Shell UI.

Crates Windows Rdl (`docs/crates/windows-rdl.md`) Copy Section

windows-rdl

A parser for RDL (Rust Definition Language) and an ECMA-335 metadata generator.

• 📦 crates.io
• 📖 docs.rs
• 🚀 Getting started
• 📁 Source

windows-rdl is the front of the metadata authoring pipeline. It parses RDL (Rust Definition
Language), a small Rust-like syntax for Windows APIs. It emits ECMA-335 .winmd metadata for
windows-bindgen. It also writes canonical RDL from .winmd files.

Most applications should use existing bindings rather than author metadata. Use windows-rdl when
you are defining a custom WinRT or Win32 surface, adapting header output from
windows-clang, or maintaining reviewable text for a winmd generator.

Start with the crate README for setup and the two basic builder
calls. The full language reference is in
crates/libs/rdl/rdl.md.

First workflow: define a custom component surface Copy Chapter

1. Create an .rdl file with one or more #[winrt] or #[win32] modules.
2. Add standard metadata as a reference if the declarations mention Windows types.
3. Compile the RDL to a winmd with reader.
4. Feed the winmd to windows-bindgen or C++/WinRT.
5. Treat the RDL as the reviewed source and regenerate the binary winmd.

crates/samples/robot/component follows this path. Its build script compiles src/robot.rdl,
references standard Windows metadata, then asks bindgen for the Robotics namespace and WinRT
implementation support. crates/samples/robot/component_cpp sends the same kind of output to
cppwinrt.

Input and output model Copy Chapter

Reader references resolve names but are not emitted as definitions. Use reference_default for
the bundled standard metadata, or the path and byte reference methods for custom dependencies.
Writer inputs are definitions to render; input_default renders the bundled metadata.

Writer filters accept namespace prefixes, qualified or unqualified names, and ! exclusions.
split writes one file per namespace. partition accepts an item-name -> file-stem map and writes
one file per defining header. item_names reads the names declared under one namespace without
compiling the file.

RDL syntax Copy Chapter

RDL uses Rust tokens and module syntax, but it describes metadata rather than executable Rust.
A top-level mod is a metadata namespace. Tag it #[winrt] or #[win32] to select the type
system. Items include classes, interfaces, delegates, callbacks, enums, structs, unions, typedefs,
constants, and imported functions.

#[win32]
mod Example {
    #[repr(i32)]
    enum Color {
        Red = 1,
        Green = 2,
        Blue = 3,
    }

    struct Point {
        x: i32,
        y: i32,
    }

    const MAX: u32 = 42;

    #[library("example.dll")]
    extern fn GetPoint() -> Point;

    #[guid(0x00000001_0002_0003_0004_000000000005)]
    interface ICustom : Windows::Win32::System::Com::IUnknown {
        fn Method(&self, value: i32) -> i32;
    }
}

Most attributes name a metadata attribute type directly. Some attributes use short pseudo-attribute
names. The reader expands those names to full metadata attributes. See PSEUDO_ATTRS in
windows-rdl.

Struct bit fields use their own syntax. A run of bit fields packed into one backing integer is
written as a C-like block on that field. Each member uses Name: width. Anonymous padding uses
_: width.

struct D3D11_VIDEO_PROCESSOR_COLOR_SPACE {
    _bitfield: u32 {
        Usage: 1,
        RGB_Range: 1,
        YCbCr_Matrix: 1,
        YCbCr_xvYCC: 1,
        Nominal_Range: 2,
        Reserved: 26,
    },
}

Member offsets are implicit. Each offset is the total width of earlier members, including padding.
The reader writes one Windows.Win32.Metadata.NativeBitfieldAttribute(name, offset, width) custom
attribute per named member. The writer renders it back to block form.

See windows-clang for how the scraper emits bit
fields. See windows-bindgen for the accessors they
drive.

WinRT types use the #[winrt] namespace flavor. They also add runtime-class and property syntax.

#[winrt]
mod Robotics {
    #[Activatable(1)]
    class Robot {
        IRobot,
    }

    #[ExclusiveTo(Robot)]
    interface IRobot {
        fn Speak(&self, message: String);
        Name: String;
    }
}

The crates/tests/libs/rdl/input directory has focused .rdl files for syntax examples. It covers
structs, flags, delegates, generic interfaces, unions, and more.