{"owner":"microsoft","repo":"windows-rs","hasSkills":true,"totalSkillsCount":1,"totalTokensCount":3595,"categories":["copilot-instructions"],"hasMcp":false,"mcpConfig":null,"found":[".github/copilot-instructions.md"],"skills":{".github/copilot-instructions.md":"# Copilot Instructions for windows-rs\n\nRead this file at the start of every session. It contains the essential commands, conventions, and\narchitecture knowledge needed to work on this repository.\n\n## Workflow\n\nDo not create git commits automatically. The maintainer reviews all changes first and handles\ncommits manually. Make changes locally, run fmt/clippy/tests to verify, and report back.\n\n## Repository Layout\n\nCargo workspace (`resolver = \"3\"`). Members are globbed from:\n\n- `crates/libs/*` - the published/library crates (`windows`, `windows-sys`, `windows-core`, plus\n  `windows-bindgen`, `metadata`, `rdl`, and the newer `reactor`/`canvas`/`webview`/`window` crates).\n  See `docs/readme.md` for the full categorized crate index, and `docs/crates/<crate>.md` per crate.\n- `crates/tools/*` - code generators and CI helpers, run via `cargo run -p tool-*`.\n- `crates/tests/*/*` - test crates; `crates/tests/libs/<crate>` mirrors each library crate (e.g.\n  `test_reactor`, `test-webview`). Crate names are `test_<dir>`.\n- `crates/samples/*/*` - runnable examples.\n\nThe crates fall into rough groups (see `docs/readme.md` for the authoritative list): core & errors\n(`windows-core`, `windows-result`, `windows-strings`); values & collections (`numerics`,\n`collections`, `reference`, `time`); async & threading (`future`, `threading`); system services\n(`registry`, `services`, `version`); COM macros & linking (`implement`, `interface`, `link`); UI &\ngraphics (`reactor`, `canvas`, `webview`, `window`, `animation`, `reactor-setup`); codegen &\nmetadata tooling (`bindgen`, `metadata`, `rdl`, `cppwinrt`); and the full API projection (`windows`,\n`windows-sys`).\n\n## Before Finalizing Changes\n\n```sh\ncargo fmt --all\n```\n\nCI enforces rustfmt. Always format before finalizing changes. On Windows, the workspace-wide\ncommand may exceed the process command-line limit; use `cargo fmt -p <crate>` for each affected\ncrate instead.\n\n## Build & Test Commands\n\n### Core crates\n\n```sh\ncargo check -p windows-core --quiet\ncargo check -p windows --quiet\ncargo clippy -p <crate> --all-targets\ncargo test -p <crate>\n\n# Run a single test by name filter\ncargo test -p <crate> <test_name_substring>\n```\n\nCI sets `RUSTFLAGS: -D warnings`, so any warning fails the build. Workspace-wide lints are\nconfigured in the root `Cargo.toml` (`[workspace.lints]`) - clippy lints like\n`uninlined_format_args`, `redundant_clone`, and `semicolon_if_nothing_returned` are promoted to\nwarnings and therefore enforced.\n\n### Reactor\n\n```sh\n# Refresh WinUI metadata after changing Windows App SDK or WebView2 pins\ncargo run -p tool-reactor-metadata --quiet\n\n# Regenerate Reactor code after editing schema.toml or tool-reactor source\ncargo run -p tool-reactor --quiet\n\n# Regenerate bindings (after editing filter .txt files)\ncargo run -p tool-bindings --quiet\n\n# Verify reactor compiles\ncargo check -p windows-reactor --quiet\n\n# Unit tests (headless, fast)\ncargo test -p windows-reactor --all-features --quiet\n\n# Public API tests (x64 interactive desktop; Cargo deploys the runtime)\ncargo test -p test-reactor\ncargo test -p test-reactor --test ui window::\n\n# Clippy\ncargo clippy -p windows-reactor --all-targets\n```\n\n### Canvas\n\n```sh\ncargo check -p windows-canvas --quiet\ncargo test -p windows-canvas --quiet\ncargo clippy -p windows-canvas --all-targets\n```\n\n### Full workspace\n\n```sh\ncargo run -p tool-clippy-all    # runs clippy across all crates\n```\n\n## Code Generation Pipeline\n\n**Never hand-edit generated files.** Generated outputs are committed, and CI fails if regenerating\nproduces a diff (the `gen` workflow runs each `cargo run -p tool-*` and rejects any change; the\n`test` workflow likewise fails if tests modify tracked files). After editing generators or filters,\nre-run the tool and commit the result.\n\nThe core `windows` / `windows-sys` crates are generated from Windows metadata (`.winmd`) via\n`windows-bindgen` (driven by `tool-package`). `windows-metadata` and `windows-rdl` support\nreading/authoring that metadata. The reactor / canvas / webview pipelines layer on top:\n\n1. **`tool-reactor-metadata`** - refreshes committed WinUI / Windows App SDK / WebView2 `.winmd`\n   metadata and generates `extras.winmd`.\n\n2. **`tool-reactor`** - reads `crates/tools/reactor/src/schema.toml` plus the shared WinUI\n   metadata -> generates Reactor declarations, native projection code, the Reactor native\n   bindings, and the canvas Reactor bridge bindings.\n\n3. **`tool-bindings`** - reads filter `.txt` files from `crates/tools/bindings/src/` -> runs\n   `windows-bindgen` -> generates `bindings.rs` in each crate:\n   - `crates/libs/canvas/src/bindings.rs` (from `canvas.txt`)\n   - `crates/libs/time/src/bindings.rs`, `numerics`, `reference`, etc.\n\n4. **`tool-package`** - generates the published `windows` and `windows-sys` package crates using\n   `--package` mode (per-namespace files + Cargo.toml features).\n\n4. After regenerating, always verify: `cargo check -p <affected-crate> --quiet`\n\n## Key Architecture Facts\n\n### Crate relationships\n\n- `windows-core` is the foundation - almost everything depends on it.\n- `windows` is the umbrella crate that re-exports from `windows-core`, `windows-numerics`,\n  `windows-time`, `windows-collections`, `windows-reference`, etc.\n- `windows-reactor` depends on `windows-core` (not `windows`) and uses minimal bindings generated\n  with `--minimal --flat` mode.\n- `windows-canvas` similarly uses minimal bindings for D2D/DXGI/DWrite/WIC.\n- `windows-animation` wraps Win32 UIAnimation Manager COM APIs.\n\n### Reactor architecture\n\n- WinUI backend ownership is split across `crates/libs/reactor/src/native/winui/mod.rs` and\n  `crates/libs/reactor/src/native/winui/`.\n- The TOML config (`crates/tools/reactor/src/schema.toml`) declares 79 WinUI controls. Keys are\n  WinUI metadata names; the tool infers types, setter patterns, and event handlers from `.winmd`\n  files.\n- COM casts: classes Deref to their default interface (zero-cost). Only cast to non-default parent\n  interfaces. The `Param` trait handles parent-class conversions automatically.\n\n### Canvas architecture\n\n- Canvas wraps D2D/DXGI behind safe Rust types (`GpuDevice`, `SwapChain`, `DrawingSession`,\n  `PathBuilder`).\n- `animated_canvas()` (reactor feature) renders on UI thread via `CompositionTarget::Rendering`.\n- Device-lost recovery is automatic.\n\n## Conventions\n\n- **Module layout**: When a module has a directory, put its entry point in `name/mod.rs`, not\n  `name.rs` beside the `name/` directory. The workspace enables Clippy's `self_named_module_files`\n  lint to enforce this for modules with external submodules.\n- **Fail fast**: Contract violations, internal bugs, and unexpected native failures panic (`.unwrap()`\n  or `panic!`); Reactor does not roll back or poison state. Return `Result` only where the caller\n  can act: startup and public `App` APIs, errors returned from app closures (surfaced through\n  `App::run`), and imperative completions such as `FocusError`. A dispatcher that rejects work is\n  shutting down; drop the work rather than failing.\n- **`.unwrap()` over `.expect(\"...\")`** - the panic hook provides full context.\n- **No `thread_local!` in app code** - keep state in components and pass shared values through typed\n  contexts. `thread_local!` is reserved for framework plumbing.\n- **Test naming**: Reactor unit tests live in `windows-reactor`. Public behavioral coverage belongs\n  in `test-reactor`. Prefer a small set of high-value contracts over exhaustive UIA matrices or\n  preserving every legacy assertion. Do not add separate runners or test scripts. Keep library tests\n  headless rather than adding ignored native fixtures. The functional crate participates in workspace\n  tests and uses `windows-reactor-setup` in its build script. Live UI cases run on x64; setup's\n  filesystem and multiprocess tests run on all Windows architectures.\n  Run the crate alone when checking default features rather than the workspace's unified\n  features.\n  Canvas tests use WARP rendering.\n- **Reactor test documentation**: Keep testing instructions in `crates/tests/libs/reactor/readme.md`,\n  not `docs/crates/windows-reactor.md`. `cargo test -p test-reactor` must run the automated suite\n  without ignored-test flags. Generate its native bindings with `windows-bindgen` in `build.rs`\n  rather than depending on the `windows` crate.\n\n## Documentation\n\nThe `docs/` folder has one page per crate:\n\n- **`docs/crates/<crate>.md`** - a single page per crate covering both usage and internals (how the\n  crate is built and maintained: codegen pipeline, generated files, conventions). It links to the\n  crate's own `readme.md` for the user-facing intro and quick example.\n- **`crates/libs/<crate>/readme.md`** - the user-facing introduction with a quick example (also the\n  crates.io / docs.rs landing).\n- **`docs/readme.md`** - the documentation hub and crate index.\n\n`docs/` also holds `contributing.md`, `code_of_conduct.md`, and `security.md`.\n\nWhen making changes to a crate, update its `docs/crates/<crate>.md` page and its `readme.md` as\nneeded. For example, `windows-reactor` changes touch `docs/crates/windows-reactor.md` (codegen,\nTOML, threading, COM pitfalls, plus the conceptual overview) and `crates/libs/reactor/readme.md`\n(getting started and the quick example).\n\n## Writing Style for Docs and Comments\n\nThese rules were established while cleaning up the docs and code comments and apply to all Markdown\n(`.md`) and Rust comments/doc-comments across the repo. Keep new writing consistent with them.\n\n- **ASCII punctuation only.** Use `-` for dashes (never em/en-dashes), `...` for ellipsis, `->` for\n  arrows, `<=`/`>=`/`!=` for comparisons, and straight quotes. Drop the section sign from standard\n  references (write `ECMA-335 II.22`, `C11 6.4.4.1`, not `\\u00a7...`). The only non-ASCII that stays\n  is genuine test data (e.g. a Greek-letter string literal exercising UTF-8 handling).\n- **100-column wrap.** Hard-wrap Markdown prose and long comment blocks at 100 columns. Keep the\n  wrap consistent within a file - do not mix wrapped and unwrapped paragraphs.\n- **No LLM tells.** Avoid the vocabulary and tics that mark agent-written text: `faithful`,\n  `corpus`, `ledger`, `crucially`, `notably`, `essentially`, `robust`, `seamless`, `comprehensive`,\n  `deliberately`, `simply`, `under the hood`, `that said`, `importantly`, `conceptually`,\n  `effectively`, `single source of truth`, `industry-standard`, `first-class`, `leverage`,\n  `utilize`, `Note that ...`. Say the concrete thing instead. `ergonomic` and rustdoc `**bold**` are\n  fine.\n- **No decorative formatting.** No box-drawing banner comments (`// -- Title ------`), no duplicated\n  doc paragraphs (a real copy-paste tell), no filler that restates the code.\n- **Prefer tables over wordy paragraphs** where the content is a set of parallel cases (rules,\n  mappings, options).\n- **Describe the code as it is,** not its history. Avoid churn narration (`used to`, `previously`,\n  `an earlier version`, `no longer`) unless it describes real runtime behavior, not codebase edits.\n- **Do not edit generated files** to satisfy these rules; only hand-written sources.\n\n## Open Investigations / TODO\n\nEnduring record of known issues so they are not lost between sessions. Add findings here; remove or\nmark done as they are addressed. Cite code by file + symbol name, not line number - line numbers go\nstale fast.\n\n### Native menu theme propagation\n\nInvestigate `crates/libs/reactor/src/native/transient_menu.rs` `MenuThemeState::refresh` and\n`show_pending`. A CI run observed a flyout item remaining Light while its anchor reported Dark.\nThe cause is unconfirmed. The headless preference and callback tests do not establish native theme\npropagation; investigate the behavior before adding a focused public-API regression case.\n\n### Reactor live coverage gaps (test-reactor fixtures)\n\nAbout 48 of the 81 schema objects have no live `test-reactor` coverage. Add contract-style fixtures\nin priority order. Verify indirect coverage (for example `CommandBar` via the menu fixture) before\nadding a case. The `controlled` fixture covers toggles, grouped `RadioButton`s, `Expander`, and\nranged values.\n\n| Priority | Area | Contracts to check |\n| --- | --- | --- |\n| 1 | Panes: `SplitView`, `NavigationView` `is_pane_open` | `SplitView` observes only `PaneClosed`; WinUI has no user-driven open, so likely fine |\n| 1 | Text and pickers: `PasswordBox`, `ColorPicker`, `CalendarDatePicker`, `RichEditBox` | Echo and normalization |\n| 2 | `TreeView` / `TreeNode` | Insert, remove, reorder, expand state, item invoke; no live tests exist |\n| 3 | Item-flag selectors: `ListBox`, `SelectorBar`, `NavigationView`, `BreadcrumbBar` | Selection shape differs from index selectors |\n| 3 | Selector edge cases | Index reassert during retire / exit animation, async intermediate events, `GridView` vs `ListView` parity |\n| 4 | Open/close surfaces: `InfoBar`, `TeachingTip`, `ToolTip` | Open state and close callbacks |\n| 5 | Display-only: shapes, icons, `ProgressBar`, `ProgressRing`, `Viewbox`, panels | Low risk; smoke only |\n\n### Repo-wide dead-code / quality audit (2026-07)\n\nOpen items across the hand-written crates (reactor, bindgen, rdl, clang, canvas, metadata, webview,\ncore) that need a design decision or a larger change. Any bindgen source change must be proven\noutput-neutral by running the `tool-*` generators and confirming `git diff` shows no generated-file\nchanges (the `gen` workflow enforces this).\n\n#### Duplication / refactor candidates\n\n| Location | Issue |\n| --- | --- |\n| `metadata` `merge/mod.rs` `write_type` vs `merge/remap.rs` `write_type` | Two ~60-line structurally identical functions; the remap copy's comment says it mirrors `merge::write_type`. Any new ECMA table must be added to both, with no compiler guard. |\n| `canvas` `session.rs` gradient-stop + bitmap-properties builders | Duplicated ABI-stop and bitmap-properties construction across the brush paths. |\n| `bindgen` `types/interface.rs` + `cpp_interface.rs` local `fn combine` | Duplicate local helper. |\n| `canvas` `color.rs` `DARK_SLATE_BLUE` | `rgb(0.05, 0.05, 0.1)` does not match the CSS color of that name (public API used by samples). |\n\n#### Coverage gaps\n\n| Area | Gap |\n| --- | --- |\n| `metadata` `Remapper` (`merge/remap.rs`) | No tests anywhere; routing/`split_apis` logic is exercised only in the live build, so a regression yields a malformed namespaced winmd with no failing test. |\n| webview | `process-failed`, download, and deferral paths untested. |\n"},"files":{".github/copilot-instructions.md":"# Copilot Instructions for windows-rs\n\nRead this file at the start of every session. It contains the essential commands, conventions, and\narchitecture knowledge needed to work on this repository.\n\n## Workflow\n\nDo not create git commits automatically. The maintainer reviews all changes first and handles\ncommits manually. Make changes locally, run fmt/clippy/tests to verify, and report back.\n\n## Repository Layout\n\nCargo workspace (`resolver = \"3\"`). Members are globbed from:\n\n- `crates/libs/*` - the published/library crates (`windows`, `windows-sys`, `windows-core`, plus\n  `windows-bindgen`, `metadata`, `rdl`, and the newer `reactor`/`canvas`/`webview`/`window` crates).\n  See `docs/readme.md` for the full categorized crate index, and `docs/crates/<crate>.md` per crate.\n- `crates/tools/*` - code generators and CI helpers, run via `cargo run -p tool-*`.\n- `crates/tests/*/*` - test crates; `crates/tests/libs/<crate>` mirrors each library crate (e.g.\n  `test_reactor`, `test-webview`). Crate names are `test_<dir>`.\n- `crates/samples/*/*` - runnable examples.\n\nThe crates fall into rough groups (see `docs/readme.md` for the authoritative list): core & errors\n(`windows-core`, `windows-result`, `windows-strings`); values & collections (`numerics`,\n`collections`, `reference`, `time`); async & threading (`future`, `threading`); system services\n(`registry`, `services`, `version`); COM macros & linking (`implement`, `interface`, `link`); UI &\ngraphics (`reactor`, `canvas`, `webview`, `window`, `animation`, `reactor-setup`); codegen &\nmetadata tooling (`bindgen`, `metadata`, `rdl`, `cppwinrt`); and the full API projection (`windows`,\n`windows-sys`).\n\n## Before Finalizing Changes\n\n```sh\ncargo fmt --all\n```\n\nCI enforces rustfmt. Always format before finalizing changes. On Windows, the workspace-wide\ncommand may exceed the process command-line limit; use `cargo fmt -p <crate>` for each affected\ncrate instead.\n\n## Build & Test Commands\n\n### Core crates\n\n```sh\ncargo check -p windows-core --quiet\ncargo check -p windows --quiet\ncargo clippy -p <crate> --all-targets\ncargo test -p <crate>\n\n# Run a single test by name filter\ncargo test -p <crate> <test_name_substring>\n```\n\nCI sets `RUSTFLAGS: -D warnings`, so any warning fails the build. Workspace-wide lints are\nconfigured in the root `Cargo.toml` (`[workspace.lints]`) - clippy lints like\n`uninlined_format_args`, `redundant_clone`, and `semicolon_if_nothing_returned` are promoted to\nwarnings and therefore enforced.\n\n### Reactor\n\n```sh\n# Refresh WinUI metadata after changing Windows App SDK or WebView2 pins\ncargo run -p tool-reactor-metadata --quiet\n\n# Regenerate Reactor code after editing schema.toml or tool-reactor source\ncargo run -p tool-reactor --quiet\n\n# Regenerate bindings (after editing filter .txt files)\ncargo run -p tool-bindings --quiet\n\n# Verify reactor compiles\ncargo check -p windows-reactor --quiet\n\n# Unit tests (headless, fast)\ncargo test -p windows-reactor --all-features --quiet\n\n# Public API tests (x64 interactive desktop; Cargo deploys the runtime)\ncargo test -p test-reactor\ncargo test -p test-reactor --test ui window::\n\n# Clippy\ncargo clippy -p windows-reactor --all-targets\n```\n\n### Canvas\n\n```sh\ncargo check -p windows-canvas --quiet\ncargo test -p windows-canvas --quiet\ncargo clippy -p windows-canvas --all-targets\n```\n\n### Full workspace\n\n```sh\ncargo run -p tool-clippy-all    # runs clippy across all crates\n```\n\n## Code Generation Pipeline\n\n**Never hand-edit generated files.** Generated outputs are committed, and CI fails if regenerating\nproduces a diff (the `gen` workflow runs each `cargo run -p tool-*` and rejects any change; the\n`test` workflow likewise fails if tests modify tracked files). After editing generators or filters,\nre-run the tool and commit the result.\n\nThe core `windows` / `windows-sys` crates are generated from Windows metadata (`.winmd`) via\n`windows-bindgen` (driven by `tool-package`). `windows-metadata` and `windows-rdl` support\nreading/authoring that metadata. The reactor / canvas / webview pipelines layer on top:\n\n1. **`tool-reactor-metadata`** - refreshes committed WinUI / Windows App SDK / WebView2 `.winmd`\n   metadata and generates `extras.winmd`.\n\n2. **`tool-reactor`** - reads `crates/tools/reactor/src/schema.toml` plus the shared WinUI\n   metadata -> generates Reactor declarations, native projection code, the Reactor native\n   bindings, and the canvas Reactor bridge bindings.\n\n3. **`tool-bindings`** - reads filter `.txt` files from `crates/tools/bindings/src/` -> runs\n   `windows-bindgen` -> generates `bindings.rs` in each crate:\n   - `crates/libs/canvas/src/bindings.rs` (from `canvas.txt`)\n   - `crates/libs/time/src/bindings.rs`, `numerics`, `reference`, etc.\n\n4. **`tool-package`** - generates the published `windows` and `windows-sys` package crates using\n   `--package` mode (per-namespace files + Cargo.toml features).\n\n4. After regenerating, always verify: `cargo check -p <affected-crate> --quiet`\n\n## Key Architecture Facts\n\n### Crate relationships\n\n- `windows-core` is the foundation - almost everything depends on it.\n- `windows` is the umbrella crate that re-exports from `windows-core`, `windows-numerics`,\n  `windows-time`, `windows-collections`, `windows-reference`, etc.\n- `windows-reactor` depends on `windows-core` (not `windows`) and uses minimal bindings generated\n  with `--minimal --flat` mode.\n- `windows-canvas` similarly uses minimal bindings for D2D/DXGI/DWrite/WIC.\n- `windows-animation` wraps Win32 UIAnimation Manager COM APIs.\n\n### Reactor architecture\n\n- WinUI backend ownership is split across `crates/libs/reactor/src/native/winui/mod.rs` and\n  `crates/libs/reactor/src/native/winui/`.\n- The TOML config (`crates/tools/reactor/src/schema.toml`) declares 79 WinUI controls. Keys are\n  WinUI metadata names; the tool infers types, setter patterns, and event handlers from `.winmd`\n  files.\n- COM casts: classes Deref to their default interface (zero-cost). Only cast to non-default parent\n  interfaces. The `Param` trait handles parent-class conversions automatically.\n\n### Canvas architecture\n\n- Canvas wraps D2D/DXGI behind safe Rust types (`GpuDevice`, `SwapChain`, `DrawingSession`,\n  `PathBuilder`).\n- `animated_canvas()` (reactor feature) renders on UI thread via `CompositionTarget::Rendering`.\n- Device-lost recovery is automatic.\n\n## Conventions\n\n- **Module layout**: When a module has a directory, put its entry point in `name/mod.rs`, not\n  `name.rs` beside the `name/` directory. The workspace enables Clippy's `self_named_module_files`\n  lint to enforce this for modules with external submodules.\n- **Fail fast**: Contract violations, internal bugs, and unexpected native failures panic (`.unwrap()`\n  or `panic!`); Reactor does not roll back or poison state. Return `Result` only where the caller\n  can act: startup and public `App` APIs, errors returned from app closures (surfaced through\n  `App::run`), and imperative completions such as `FocusError`. A dispatcher that rejects work is\n  shutting down; drop the work rather than failing.\n- **`.unwrap()` over `.expect(\"...\")`** - the panic hook provides full context.\n- **No `thread_local!` in app code** - keep state in components and pass shared values through typed\n  contexts. `thread_local!` is reserved for framework plumbing.\n- **Test naming**: Reactor unit tests live in `windows-reactor`. Public behavioral coverage belongs\n  in `test-reactor`. Prefer a small set of high-value contracts over exhaustive UIA matrices or\n  preserving every legacy assertion. Do not add separate runners or test scripts. Keep library tests\n  headless rather than adding ignored native fixtures. The functional crate participates in workspace\n  tests and uses `windows-reactor-setup` in its build script. Live UI cases run on x64; setup's\n  filesystem and multiprocess tests run on all Windows architectures.\n  Run the crate alone when checking default features rather than the workspace's unified\n  features.\n  Canvas tests use WARP rendering.\n- **Reactor test documentation**: Keep testing instructions in `crates/tests/libs/reactor/readme.md`,\n  not `docs/crates/windows-reactor.md`. `cargo test -p test-reactor` must run the automated suite\n  without ignored-test flags. Generate its native bindings with `windows-bindgen` in `build.rs`\n  rather than depending on the `windows` crate.\n\n## Documentation\n\nThe `docs/` folder has one page per crate:\n\n- **`docs/crates/<crate>.md`** - a single page per crate covering both usage and internals (how the\n  crate is built and maintained: codegen pipeline, generated files, conventions). It links to the\n  crate's own `readme.md` for the user-facing intro and quick example.\n- **`crates/libs/<crate>/readme.md`** - the user-facing introduction with a quick example (also the\n  crates.io / docs.rs landing).\n- **`docs/readme.md`** - the documentation hub and crate index.\n\n`docs/` also holds `contributing.md`, `code_of_conduct.md`, and `security.md`.\n\nWhen making changes to a crate, update its `docs/crates/<crate>.md` page and its `readme.md` as\nneeded. For example, `windows-reactor` changes touch `docs/crates/windows-reactor.md` (codegen,\nTOML, threading, COM pitfalls, plus the conceptual overview) and `crates/libs/reactor/readme.md`\n(getting started and the quick example).\n\n## Writing Style for Docs and Comments\n\nThese rules were established while cleaning up the docs and code comments and apply to all Markdown\n(`.md`) and Rust comments/doc-comments across the repo. Keep new writing consistent with them.\n\n- **ASCII punctuation only.** Use `-` for dashes (never em/en-dashes), `...` for ellipsis, `->` for\n  arrows, `<=`/`>=`/`!=` for comparisons, and straight quotes. Drop the section sign from standard\n  references (write `ECMA-335 II.22`, `C11 6.4.4.1`, not `\\u00a7...`). The only non-ASCII that stays\n  is genuine test data (e.g. a Greek-letter string literal exercising UTF-8 handling).\n- **100-column wrap.** Hard-wrap Markdown prose and long comment blocks at 100 columns. Keep the\n  wrap consistent within a file - do not mix wrapped and unwrapped paragraphs.\n- **No LLM tells.** Avoid the vocabulary and tics that mark agent-written text: `faithful`,\n  `corpus`, `ledger`, `crucially`, `notably`, `essentially`, `robust`, `seamless`, `comprehensive`,\n  `deliberately`, `simply`, `under the hood`, `that said`, `importantly`, `conceptually`,\n  `effectively`, `single source of truth`, `industry-standard`, `first-class`, `leverage`,\n  `utilize`, `Note that ...`. Say the concrete thing instead. `ergonomic` and rustdoc `**bold**` are\n  fine.\n- **No decorative formatting.** No box-drawing banner comments (`// -- Title ------`), no duplicated\n  doc paragraphs (a real copy-paste tell), no filler that restates the code.\n- **Prefer tables over wordy paragraphs** where the content is a set of parallel cases (rules,\n  mappings, options).\n- **Describe the code as it is,** not its history. Avoid churn narration (`used to`, `previously`,\n  `an earlier version`, `no longer`) unless it describes real runtime behavior, not codebase edits.\n- **Do not edit generated files** to satisfy these rules; only hand-written sources.\n\n## Open Investigations / TODO\n\nEnduring record of known issues so they are not lost between sessions. Add findings here; remove or\nmark done as they are addressed. Cite code by file + symbol name, not line number - line numbers go\nstale fast.\n\n### Native menu theme propagation\n\nInvestigate `crates/libs/reactor/src/native/transient_menu.rs` `MenuThemeState::refresh` and\n`show_pending`. A CI run observed a flyout item remaining Light while its anchor reported Dark.\nThe cause is unconfirmed. The headless preference and callback tests do not establish native theme\npropagation; investigate the behavior before adding a focused public-API regression case.\n\n### Reactor live coverage gaps (test-reactor fixtures)\n\nAbout 48 of the 81 schema objects have no live `test-reactor` coverage. Add contract-style fixtures\nin priority order. Verify indirect coverage (for example `CommandBar` via the menu fixture) before\nadding a case. The `controlled` fixture covers toggles, grouped `RadioButton`s, `Expander`, and\nranged values.\n\n| Priority | Area | Contracts to check |\n| --- | --- | --- |\n| 1 | Panes: `SplitView`, `NavigationView` `is_pane_open` | `SplitView` observes only `PaneClosed`; WinUI has no user-driven open, so likely fine |\n| 1 | Text and pickers: `PasswordBox`, `ColorPicker`, `CalendarDatePicker`, `RichEditBox` | Echo and normalization |\n| 2 | `TreeView` / `TreeNode` | Insert, remove, reorder, expand state, item invoke; no live tests exist |\n| 3 | Item-flag selectors: `ListBox`, `SelectorBar`, `NavigationView`, `BreadcrumbBar` | Selection shape differs from index selectors |\n| 3 | Selector edge cases | Index reassert during retire / exit animation, async intermediate events, `GridView` vs `ListView` parity |\n| 4 | Open/close surfaces: `InfoBar`, `TeachingTip`, `ToolTip` | Open state and close callbacks |\n| 5 | Display-only: shapes, icons, `ProgressBar`, `ProgressRing`, `Viewbox`, panels | Low risk; smoke only |\n\n### Repo-wide dead-code / quality audit (2026-07)\n\nOpen items across the hand-written crates (reactor, bindgen, rdl, clang, canvas, metadata, webview,\ncore) that need a design decision or a larger change. Any bindgen source change must be proven\noutput-neutral by running the `tool-*` generators and confirming `git diff` shows no generated-file\nchanges (the `gen` workflow enforces this).\n\n#### Duplication / refactor candidates\n\n| Location | Issue |\n| --- | --- |\n| `metadata` `merge/mod.rs` `write_type` vs `merge/remap.rs` `write_type` | Two ~60-line structurally identical functions; the remap copy's comment says it mirrors `merge::write_type`. Any new ECMA table must be added to both, with no compiler guard. |\n| `canvas` `session.rs` gradient-stop + bitmap-properties builders | Duplicated ABI-stop and bitmap-properties construction across the brush paths. |\n| `bindgen` `types/interface.rs` + `cpp_interface.rs` local `fn combine` | Duplicate local helper. |\n| `canvas` `color.rs` `DARK_SLATE_BLUE` | `rgb(0.05, 0.05, 0.1)` does not match the CSS color of that name (public API used by samples). |\n\n#### Coverage gaps\n\n| Area | Gap |\n| --- | --- |\n| `metadata` `Remapper` (`merge/remap.rs`) | No tests anywhere; routing/`split_apis` logic is exercised only in the live build, so a regression yields a malformed namespaced winmd with no failing test. |\n| webview | `process-failed`, download, and deferral paths untested. |\n"},"items":[{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/microsoft/windows-rs/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# Copilot Instructions for windows-rs\n\nRead this file at the start of every session. It contains the essential commands, conventions, and\narchitecture knowledge needed to work on this repository.\n\n## Workflow\n\nDo not create git commits automatically. The maintainer reviews all changes first and handles\ncommits manually. Make changes locally, run fmt/clippy/tests to verify, and report back.\n\n## Repository Layout\n\nCargo workspace (`resolver = \"3\"`). Members are globbed from:\n\n- `crates/libs/*` - the published/library crates (`windows`, `windows-sys`, `windows-core`, plus\n  `windows-bindgen`, `metadata`, `rdl`, and the newer `reactor`/`canvas`/`webview`/`window` crates).\n  See `docs/readme.md` for the full categorized crate index, and `docs/crates/<crate>.md` per crate.\n- `crates/tools/*` - code generators and CI helpers, run via `cargo run -p tool-*`.\n- `crates/tests/*/*` - test crates; `crates/tests/libs/<crate>` mirrors each library crate (e.g.\n  `test_reactor`, `test-webview`). Crate names are `test_<dir>`.\n- `crates/samples/*/*` - runnable examples.\n\nThe crates fall into rough groups (see `docs/readme.md` for the authoritative list): core & errors\n(`windows-core`, `windows-result`, `windows-strings`); values & collections (`numerics`,\n`collections`, `reference`, `time`); async & threading (`future`, `threading`); system services\n(`registry`, `services`, `version`); COM macros & linking (`implement`, `interface`, `link`); UI &\ngraphics (`reactor`, `canvas`, `webview`, `window`, `animation`, `reactor-setup`); codegen &\nmetadata tooling (`bindgen`, `metadata`, `rdl`, `cppwinrt`); and the full API projection (`windows`,\n`windows-sys`).\n\n## Before Finalizing Changes\n\n```sh\ncargo fmt --all\n```\n\nCI enforces rustfmt. Always format before finalizing changes. On Windows, the workspace-wide\ncommand may exceed the process command-line limit; use `cargo fmt -p <crate>` for each affected\ncrate instead.\n\n## Build & Test Commands\n\n### Core crates\n\n```sh\ncargo check -p windows-core --quiet\ncargo check -p windows --quiet\ncargo clippy -p <crate> --all-targets\ncargo test -p <crate>\n\n# Run a single test by name filter\ncargo test -p <crate> <test_name_substring>\n```\n\nCI sets `RUSTFLAGS: -D warnings`, so any warning fails the build. Workspace-wide lints are\nconfigured in the root `Cargo.toml` (`[workspace.lints]`) - clippy lints like\n`uninlined_format_args`, `redundant_clone`, and `semicolon_if_nothing_returned` are promoted to\nwarnings and therefore enforced.\n\n### Reactor\n\n```sh\n# Refresh WinUI metadata after changing Windows App SDK or WebView2 pins\ncargo run -p tool-reactor-metadata --quiet\n\n# Regenerate Reactor code after editing schema.toml or tool-reactor source\ncargo run -p tool-reactor --quiet\n\n# Regenerate bindings (after editing filter .txt files)\ncargo run -p tool-bindings --quiet\n\n# Verify reactor compiles\ncargo check -p windows-reactor --quiet\n\n# Unit tests (headless, fast)\ncargo test -p windows-reactor --all-features --quiet\n\n# Public API tests (x64 interactive desktop; Cargo deploys the runtime)\ncargo test -p test-reactor\ncargo test -p test-reactor --test ui window::\n\n# Clippy\ncargo clippy -p windows-reactor --all-targets\n```\n\n### Canvas\n\n```sh\ncargo check -p windows-canvas --quiet\ncargo test -p windows-canvas --quiet\ncargo clippy -p windows-canvas --all-targets\n```\n\n### Full workspace\n\n```sh\ncargo run -p tool-clippy-all    # runs clippy across all crates\n```\n\n## Code Generation Pipeline\n\n**Never hand-edit generated files.** Generated outputs are committed, and CI fails if regenerating\nproduces a diff (the `gen` workflow runs each `cargo run -p tool-*` and rejects any change; the\n`test` workflow likewise fails if tests modify tracked files). After editing generators or filters,\nre-run the tool and commit the result.\n\nThe core `windows` / `windows-sys` crates are generated from Windows metadata (`.winmd`) via\n`windows-bindgen` (driven by `tool-package`). `windows-metadata` and `windows-rdl` support\nreading/authoring that metadata. The reactor / canvas / webview pipelines layer on top:\n\n1. **`tool-reactor-metadata`** - refreshes committed WinUI / Windows App SDK / WebView2 `.winmd`\n   metadata and generates `extras.winmd`.\n\n2. **`tool-reactor`** - reads `crates/tools/reactor/src/schema.toml` plus the shared WinUI\n   metadata -> generates Reactor declarations, native projection code, the Reactor native\n   bindings, and the canvas Reactor bridge bindings.\n\n3. **`tool-bindings`** - reads filter `.txt` files from `crates/tools/bindings/src/` -> runs\n   `windows-bindgen` -> generates `bindings.rs` in each crate:\n   - `crates/libs/canvas/src/bindings.rs` (from `canvas.txt`)\n   - `crates/libs/time/src/bindings.rs`, `numerics`, `reference`, etc.\n\n4. **`tool-package`** - generates the published `windows` and `windows-sys` package crates using\n   `--package` mode (per-namespace files + Cargo.toml features).\n\n4. After regenerating, always verify: `cargo check -p <affected-crate> --quiet`\n\n## Key Architecture Facts\n\n### Crate relationships\n\n- `windows-core` is the foundation - almost everything depends on it.\n- `windows` is the umbrella crate that re-exports from `windows-core`, `windows-numerics`,\n  `windows-time`, `windows-collections`, `windows-reference`, etc.\n- `windows-reactor` depends on `windows-core` (not `windows`) and uses minimal bindings generated\n  with `--minimal --flat` mode.\n- `windows-canvas` similarly uses minimal bindings for D2D/DXGI/DWrite/WIC.\n- `windows-animation` wraps Win32 UIAnimation Manager COM APIs.\n\n### Reactor architecture\n\n- WinUI backend ownership is split across `crates/libs/reactor/src/native/winui/mod.rs` and\n  `crates/libs/reactor/src/native/winui/`.\n- The TOML config (`crates/tools/reactor/src/schema.toml`) declares 79 WinUI controls. Keys are\n  WinUI metadata names; the tool infers types, setter patterns, and event handlers from `.winmd`\n  files.\n- COM casts: classes Deref to their default interface (zero-cost). Only cast to non-default parent\n  interfaces. The `Param` trait handles parent-class conversions automatically.\n\n### Canvas architecture\n\n- Canvas wraps D2D/DXGI behind safe Rust types (`GpuDevice`, `SwapChain`, `DrawingSession`,\n  `PathBuilder`).\n- `animated_canvas()` (reactor feature) renders on UI thread via `CompositionTarget::Rendering`.\n- Device-lost recovery is automatic.\n\n## Conventions\n\n- **Module layout**: When a module has a directory, put its entry point in `name/mod.rs`, not\n  `name.rs` beside the `name/` directory. The workspace enables Clippy's `self_named_module_files`\n  lint to enforce this for modules with external submodules.\n- **Fail fast**: Contract violations, internal bugs, and unexpected native failures panic (`.unwrap()`\n  or `panic!`); Reactor does not roll back or poison state. Return `Result` only where the caller\n  can act: startup and public `App` APIs, errors returned from app closures (surfaced through\n  `App::run`), and imperative completions such as `FocusError`. A dispatcher that rejects work is\n  shutting down; drop the work rather than failing.\n- **`.unwrap()` over `.expect(\"...\")`** - the panic hook provides full context.\n- **No `thread_local!` in app code** - keep state in components and pass shared values through typed\n  contexts. `thread_local!` is reserved for framework plumbing.\n- **Test naming**: Reactor unit tests live in `windows-reactor`. Public behavioral coverage belongs\n  in `test-reactor`. Prefer a small set of high-value contracts over exhaustive UIA matrices or\n  preserving every legacy assertion. Do not add separate runners or test scripts. Keep library tests\n  headless rather than adding ignored native fixtures. The functional crate participates in workspace\n  tests and uses `windows-reactor-setup` in its build script. Live UI cases run on x64; setup's\n  filesystem and multiprocess tests run on all Windows architectures.\n  Run the crate alone when checking default features rather than the workspace's unified\n  features.\n  Canvas tests use WARP rendering.\n- **Reactor test documentation**: Keep testing instructions in `crates/tests/libs/reactor/readme.md`,\n  not `docs/crates/windows-reactor.md`. `cargo test -p test-reactor` must run the automated suite\n  without ignored-test flags. Generate its native bindings with `windows-bindgen` in `build.rs`\n  rather than depending on the `windows` crate.\n\n## Documentation\n\nThe `docs/` folder has one page per crate:\n\n- **`docs/crates/<crate>.md`** - a single page per crate covering both usage and internals (how the\n  crate is built and maintained: codegen pipeline, generated files, conventions). It links to the\n  crate's own `readme.md` for the user-facing intro and quick example.\n- **`crates/libs/<crate>/readme.md`** - the user-facing introduction with a quick example (also the\n  crates.io / docs.rs landing).\n- **`docs/readme.md`** - the documentation hub and crate index.\n\n`docs/` also holds `contributing.md`, `code_of_conduct.md`, and `security.md`.\n\nWhen making changes to a crate, update its `docs/crates/<crate>.md` page and its `readme.md` as\nneeded. For example, `windows-reactor` changes touch `docs/crates/windows-reactor.md` (codegen,\nTOML, threading, COM pitfalls, plus the conceptual overview) and `crates/libs/reactor/readme.md`\n(getting started and the quick example).\n\n## Writing Style for Docs and Comments\n\nThese rules were established while cleaning up the docs and code comments and apply to all Markdown\n(`.md`) and Rust comments/doc-comments across the repo. Keep new writing consistent with them.\n\n- **ASCII punctuation only.** Use `-` for dashes (never em/en-dashes), `...` for ellipsis, `->` for\n  arrows, `<=`/`>=`/`!=` for comparisons, and straight quotes. Drop the section sign from standard\n  references (write `ECMA-335 II.22`, `C11 6.4.4.1`, not `\\u00a7...`). The only non-ASCII that stays\n  is genuine test data (e.g. a Greek-letter string literal exercising UTF-8 handling).\n- **100-column wrap.** Hard-wrap Markdown prose and long comment blocks at 100 columns. Keep the\n  wrap consistent within a file - do not mix wrapped and unwrapped paragraphs.\n- **No LLM tells.** Avoid the vocabulary and tics that mark agent-written text: `faithful`,\n  `corpus`, `ledger`, `crucially`, `notably`, `essentially`, `robust`, `seamless`, `comprehensive`,\n  `deliberately`, `simply`, `under the hood`, `that said`, `importantly`, `conceptually`,\n  `effectively`, `single source of truth`, `industry-standard`, `first-class`, `leverage`,\n  `utilize`, `Note that ...`. Say the concrete thing instead. `ergonomic` and rustdoc `**bold**` are\n  fine.\n- **No decorative formatting.** No box-drawing banner comments (`// -- Title ------`), no duplicated\n  doc paragraphs (a real copy-paste tell), no filler that restates the code.\n- **Prefer tables over wordy paragraphs** where the content is a set of parallel cases (rules,\n  mappings, options).\n- **Describe the code as it is,** not its history. Avoid churn narration (`used to`, `previously`,\n  `an earlier version`, `no longer`) unless it describes real runtime behavior, not codebase edits.\n- **Do not edit generated files** to satisfy these rules; only hand-written sources.\n\n## Open Investigations / TODO\n\nEnduring record of known issues so they are not lost between sessions. Add findings here; remove or\nmark done as they are addressed. Cite code by file + symbol name, not line number - line numbers go\nstale fast.\n\n### Native menu theme propagation\n\nInvestigate `crates/libs/reactor/src/native/transient_menu.rs` `MenuThemeState::refresh` and\n`show_pending`. A CI run observed a flyout item remaining Light while its anchor reported Dark.\nThe cause is unconfirmed. The headless preference and callback tests do not establish native theme\npropagation; investigate the behavior before adding a focused public-API regression case.\n\n### Reactor live coverage gaps (test-reactor fixtures)\n\nAbout 48 of the 81 schema objects have no live `test-reactor` coverage. Add contract-style fixtures\nin priority order. Verify indirect coverage (for example `CommandBar` via the menu fixture) before\nadding a case. The `controlled` fixture covers toggles, grouped `RadioButton`s, `Expander`, and\nranged values.\n\n| Priority | Area | Contracts to check |\n| --- | --- | --- |\n| 1 | Panes: `SplitView`, `NavigationView` `is_pane_open` | `SplitView` observes only `PaneClosed`; WinUI has no user-driven open, so likely fine |\n| 1 | Text and pickers: `PasswordBox`, `ColorPicker`, `CalendarDatePicker`, `RichEditBox` | Echo and normalization |\n| 2 | `TreeView` / `TreeNode` | Insert, remove, reorder, expand state, item invoke; no live tests exist |\n| 3 | Item-flag selectors: `ListBox`, `SelectorBar`, `NavigationView`, `BreadcrumbBar` | Selection shape differs from index selectors |\n| 3 | Selector edge cases | Index reassert during retire / exit animation, async intermediate events, `GridView` vs `ListView` parity |\n| 4 | Open/close surfaces: `InfoBar`, `TeachingTip`, `ToolTip` | Open state and close callbacks |\n| 5 | Display-only: shapes, icons, `ProgressBar`, `ProgressRing`, `Viewbox`, panels | Low risk; smoke only |\n\n### Repo-wide dead-code / quality audit (2026-07)\n\nOpen items across the hand-written crates (reactor, bindgen, rdl, clang, canvas, metadata, webview,\ncore) that need a design decision or a larger change. Any bindgen source change must be proven\noutput-neutral by running the `tool-*` generators and confirming `git diff` shows no generated-file\nchanges (the `gen` workflow enforces this).\n\n#### Duplication / refactor candidates\n\n| Location | Issue |\n| --- | --- |\n| `metadata` `merge/mod.rs` `write_type` vs `merge/remap.rs` `write_type` | Two ~60-line structurally identical functions; the remap copy's comment says it mirrors `merge::write_type`. Any new ECMA table must be added to both, with no compiler guard. |\n| `canvas` `session.rs` gradient-stop + bitmap-properties builders | Duplicated ABI-stop and bitmap-properties construction across the brush paths. |\n| `bindgen` `types/interface.rs` + `cpp_interface.rs` local `fn combine` | Duplicate local helper. |\n| `canvas` `color.rs` `DARK_SLATE_BLUE` | `rgb(0.05, 0.05, 0.1)` does not match the CSS color of that name (public API used by samples). |\n\n#### Coverage gaps\n\n| Area | Gap |\n| --- | --- |\n| `metadata` `Remapper` (`merge/remap.rs`) | No tests anywhere; routing/`split_apis` logic is exercised only in the live build, so a regression yields a malformed namespaced winmd with no failing test. |\n| webview | `process-failed`, download, and deferral paths untested. |\n","isInternal":false,"tokens":3595,"sizeBytes":14504}],"systemPromptSnippet":"<yakaai_skills repo=\"microsoft/windows-rs\">\n<!-- File: .github/copilot-instructions.md (Tokens: ~3595 | Category: copilot-instructions) -->\n# Copilot Instructions for windows-rs\n\nRead this file at the start of every session. It contains the essential commands, conventions, and\narchitecture knowledge needed to work on this repository.\n\n## Workflow\n\nDo not create git commits automatically. The maintainer reviews all changes first and handles\ncommits manually. Make changes locally, run fmt/clippy/tests to verify, and report back.\n\n## Repository Layout\n\nCargo workspace (`resolver = \"3\"`). Members are globbed from:\n\n- `crates/libs/*` - the published/library crates (`windows`, `windows-sys`, `windows-core`, plus\n  `windows-bindgen`, `metadata`, `rdl`, and the newer `reactor`/`canvas`/`webview`/`window` crates).\n  See `docs/readme.md` for the full categorized crate index, and `docs/crates/<crate>.md` per crate.\n- `crates/tools/*` - code generators and CI helpers, run via `cargo run -p tool-*`.\n- `crates/tests/*/*` - test crates; `crates/tests/libs/<crate>` mirrors each library crate (e.g.\n  `test_reactor`, `test-webview`). Crate names are `test_<dir>`.\n- `crates/samples/*/*` - runnable examples.\n\nThe crates fall into rough groups (see `docs/readme.md` for the authoritative list): core & errors\n(`windows-core`, `windows-result`, `windows-strings`); values & collections (`numerics`,\n`collections`, `reference`, `time`); async & threading (`future`, `threading`); system services\n(`registry`, `services`, `version`); COM macros & linking (`implement`, `interface`, `link`); UI &\ngraphics (`reactor`, `canvas`, `webview`, `window`, `animation`, `reactor-setup`); codegen &\nmetadata tooling (`bindgen`, `metadata`, `rdl`, `cppwinrt`); and the full API projection (`windows`,\n`windows-sys`).\n\n## Before Finalizing Changes\n\n```sh\ncargo fmt --all\n```\n\nCI enforces rustfmt. Always format before finalizing changes. On Windows, the workspace-wide\ncommand may exceed the process command-line limit; use `cargo fmt -p <crate>` for each affected\ncrate instead.\n\n## Build & Test Commands\n\n### Core crates\n\n```sh\ncargo check -p windows-core --quiet\ncargo check -p windows --quiet\ncargo clippy -p <crate> --all-targets\ncargo test -p <crate>\n\n# Run a single test by name filter\ncargo test -p <crate> <test_name_substring>\n```\n\nCI sets `RUSTFLAGS: -D warnings`, so any warning fails the build. Workspace-wide lints are\nconfigured in the root `Cargo.toml` (`[workspace.lints]`) - clippy lints like\n`uninlined_format_args`, `redundant_clone`, and `semicolon_if_nothing_returned` are promoted to\nwarnings and therefore enforced.\n\n### Reactor\n\n```sh\n# Refresh WinUI metadata after changing Windows App SDK or WebView2 pins\ncargo run -p tool-reactor-metadata --quiet\n\n# Regenerate Reactor code after editing schema.toml or tool-reactor source\ncargo run -p tool-reactor --quiet\n\n# Regenerate bindings (after editing filter .txt files)\ncargo run -p tool-bindings --quiet\n\n# Verify reactor compiles\ncargo check -p windows-reactor --quiet\n\n# Unit tests (headless, fast)\ncargo test -p windows-reactor --all-features --quiet\n\n# Public API tests (x64 interactive desktop; Cargo deploys the runtime)\ncargo test -p test-reactor\ncargo test -p test-reactor --test ui window::\n\n# Clippy\ncargo clippy -p windows-reactor --all-targets\n```\n\n### Canvas\n\n```sh\ncargo check -p windows-canvas --quiet\ncargo test -p windows-canvas --quiet\ncargo clippy -p windows-canvas --all-targets\n```\n\n### Full workspace\n\n```sh\ncargo run -p tool-clippy-all    # runs clippy across all crates\n```\n\n## Code Generation Pipeline\n\n**Never hand-edit generated files.** Generated outputs are committed, and CI fails if regenerating\nproduces a diff (the `gen` workflow runs each `cargo run -p tool-*` and rejects any change; the\n`test` workflow likewise fails if tests modify tracked files). After editing generators or filters,\nre-run the tool and commit the result.\n\nThe core `windows` / `windows-sys` crates are generated from Windows metadata (`.winmd`) via\n`windows-bindgen` (driven by `tool-package`). `windows-metadata` and `windows-rdl` support\nreading/authoring that metadata. The reactor / canvas / webview pipelines layer on top:\n\n1. **`tool-reactor-metadata`** - refreshes committed WinUI / Windows App SDK / WebView2 `.winmd`\n   metadata and generates `extras.winmd`.\n\n2. **`tool-reactor`** - reads `crates/tools/reactor/src/schema.toml` plus the shared WinUI\n   metadata -> generates Reactor declarations, native projection code, the Reactor native\n   bindings, and the canvas Reactor bridge bindings.\n\n3. **`tool-bindings`** - reads filter `.txt` files from `crates/tools/bindings/src/` -> runs\n   `windows-bindgen` -> generates `bindings.rs` in each crate:\n   - `crates/libs/canvas/src/bindings.rs` (from `canvas.txt`)\n   - `crates/libs/time/src/bindings.rs`, `numerics`, `reference`, etc.\n\n4. **`tool-package`** - generates the published `windows` and `windows-sys` package crates using\n   `--package` mode (per-namespace files + Cargo.toml features).\n\n4. After regenerating, always verify: `cargo check -p <affected-crate> --quiet`\n\n## Key Architecture Facts\n\n### Crate relationships\n\n- `windows-core` is the foundation - almost everything depends on it.\n- `windows` is the umbrella crate that re-exports from `windows-core`, `windows-numerics`,\n  `windows-time`, `windows-collections`, `windows-reference`, etc.\n- `windows-reactor` depends on `windows-core` (not `windows`) and uses minimal bindings generated\n  with `--minimal --flat` mode.\n- `windows-canvas` similarly uses minimal bindings for D2D/DXGI/DWrite/WIC.\n- `windows-animation` wraps Win32 UIAnimation Manager COM APIs.\n\n### Reactor architecture\n\n- WinUI backend ownership is split across `crates/libs/reactor/src/native/winui/mod.rs` and\n  `crates/libs/reactor/src/native/winui/`.\n- The TOML config (`crates/tools/reactor/src/schema.toml`) declares 79 WinUI controls. Keys are\n  WinUI metadata names; the tool infers types, setter patterns, and event handlers from `.winmd`\n  files.\n- COM casts: classes Deref to their default interface (zero-cost). Only cast to non-default parent\n  interfaces. The `Param` trait handles parent-class conversions automatically.\n\n### Canvas architecture\n\n- Canvas wraps D2D/DXGI behind safe Rust types (`GpuDevice`, `SwapChain`, `DrawingSession`,\n  `PathBuilder`).\n- `animated_canvas()` (reactor feature) renders on UI thread via `CompositionTarget::Rendering`.\n- Device-lost recovery is automatic.\n\n## Conventions\n\n- **Module layout**: When a module has a directory, put its entry point in `name/mod.rs`, not\n  `name.rs` beside the `name/` directory. The workspace enables Clippy's `self_named_module_files`\n  lint to enforce this for modules with external submodules.\n- **Fail fast**: Contract violations, internal bugs, and unexpected native failures panic (`.unwrap()`\n  or `panic!`); Reactor does not roll back or poison state. Return `Result` only where the caller\n  can act: startup and public `App` APIs, errors returned from app closures (surfaced through\n  `App::run`), and imperative completions such as `FocusError`. A dispatcher that rejects work is\n  shutting down; drop the work rather than failing.\n- **`.unwrap()` over `.expect(\"...\")`** - the panic hook provides full context.\n- **No `thread_local!` in app code** - keep state in components and pass shared values through typed\n  contexts. `thread_local!` is reserved for framework plumbing.\n- **Test naming**: Reactor unit tests live in `windows-reactor`. Public behavioral coverage belongs\n  in `test-reactor`. Prefer a small set of high-value contracts over exhaustive UIA matrices or\n  preserving every legacy assertion. Do not add separate runners or test scripts. Keep library tests\n  headless rather than adding ignored native fixtures. The functional crate participates in workspace\n  tests and uses `windows-reactor-setup` in its build script. Live UI cases run on x64; setup's\n  filesystem and multiprocess tests run on all Windows architectures.\n  Run the crate alone when checking default features rather than the workspace's unified\n  features.\n  Canvas tests use WARP rendering.\n- **Reactor test documentation**: Keep testing instructions in `crates/tests/libs/reactor/readme.md`,\n  not `docs/crates/windows-reactor.md`. `cargo test -p test-reactor` must run the automated suite\n  without ignored-test flags. Generate its native bindings with `windows-bindgen` in `build.rs`\n  rather than depending on the `windows` crate.\n\n## Documentation\n\nThe `docs/` folder has one page per crate:\n\n- **`docs/crates/<crate>.md`** - a single page per crate covering both usage and internals (how the\n  crate is built and maintained: codegen pipeline, generated files, conventions). It links to the\n  crate's own `readme.md` for the user-facing intro and quick example.\n- **`crates/libs/<crate>/readme.md`** - the user-facing introduction with a quick example (also the\n  crates.io / docs.rs landing).\n- **`docs/readme.md`** - the documentation hub and crate index.\n\n`docs/` also holds `contributing.md`, `code_of_conduct.md`, and `security.md`.\n\nWhen making changes to a crate, update its `docs/crates/<crate>.md` page and its `readme.md` as\nneeded. For example, `windows-reactor` changes touch `docs/crates/windows-reactor.md` (codegen,\nTOML, threading, COM pitfalls, plus the conceptual overview) and `crates/libs/reactor/readme.md`\n(getting started and the quick example).\n\n## Writing Style for Docs and Comments\n\nThese rules were established while cleaning up the docs and code comments and apply to all Markdown\n(`.md`) and Rust comments/doc-comments across the repo. Keep new writing consistent with them.\n\n- **ASCII punctuation only.** Use `-` for dashes (never em/en-dashes), `...` for ellipsis, `->` for\n  arrows, `<=`/`>=`/`!=` for comparisons, and straight quotes. Drop the section sign from standard\n  references (write `ECMA-335 II.22`, `C11 6.4.4.1`, not `\\u00a7...`). The only non-ASCII that stays\n  is genuine test data (e.g. a Greek-letter string literal exercising UTF-8 handling).\n- **100-column wrap.** Hard-wrap Markdown prose and long comment blocks at 100 columns. Keep the\n  wrap consistent within a file - do not mix wrapped and unwrapped paragraphs.\n- **No LLM tells.** Avoid the vocabulary and tics that mark agent-written text: `faithful`,\n  `corpus`, `ledger`, `crucially`, `notably`, `essentially`, `robust`, `seamless`, `comprehensive`,\n  `deliberately`, `simply`, `under the hood`, `that said`, `importantly`, `conceptually`,\n  `effectively`, `single source of truth`, `industry-standard`, `first-class`, `leverage`,\n  `utilize`, `Note that ...`. Say the concrete thing instead. `ergonomic` and rustdoc `**bold**` are\n  fine.\n- **No decorative formatting.** No box-drawing banner comments (`// -- Title ------`), no duplicated\n  doc paragraphs (a real copy-paste tell), no filler that restates the code.\n- **Prefer tables over wordy paragraphs** where the content is a set of parallel cases (rules,\n  mappings, options).\n- **Describe the code as it is,** not its history. Avoid churn narration (`used to`, `previously`,\n  `an earlier version`, `no longer`) unless it describes real runtime behavior, not codebase edits.\n- **Do not edit generated files** to satisfy these rules; only hand-written sources.\n\n## Open Investigations / TODO\n\nEnduring record of known issues so they are not lost between sessions. Add findings here; remove or\nmark done as they are addressed. Cite code by file + symbol name, not line number - line numbers go\nstale fast.\n\n### Native menu theme propagation\n\nInvestigate `crates/libs/reactor/src/native/transient_menu.rs` `MenuThemeState::refresh` and\n`show_pending`. A CI run observed a flyout item remaining Light while its anchor reported Dark.\nThe cause is unconfirmed. The headless preference and callback tests do not establish native theme\npropagation; investigate the behavior before adding a focused public-API regression case.\n\n### Reactor live coverage gaps (test-reactor fixtures)\n\nAbout 48 of the 81 schema objects have no live `test-reactor` coverage. Add contract-style fixtures\nin priority order. Verify indirect coverage (for example `CommandBar` via the menu fixture) before\nadding a case. The `controlled` fixture covers toggles, grouped `RadioButton`s, `Expander`, and\nranged values.\n\n| Priority | Area | Contracts to check |\n| --- | --- | --- |\n| 1 | Panes: `SplitView`, `NavigationView` `is_pane_open` | `SplitView` observes only `PaneClosed`; WinUI has no user-driven open, so likely fine |\n| 1 | Text and pickers: `PasswordBox`, `ColorPicker`, `CalendarDatePicker`, `RichEditBox` | Echo and normalization |\n| 2 | `TreeView` / `TreeNode` | Insert, remove, reorder, expand state, item invoke; no live tests exist |\n| 3 | Item-flag selectors: `ListBox`, `SelectorBar`, `NavigationView`, `BreadcrumbBar` | Selection shape differs from index selectors |\n| 3 | Selector edge cases | Index reassert during retire / exit animation, async intermediate events, `GridView` vs `ListView` parity |\n| 4 | Open/close surfaces: `InfoBar`, `TeachingTip`, `ToolTip` | Open state and close callbacks |\n| 5 | Display-only: shapes, icons, `ProgressBar`, `ProgressRing`, `Viewbox`, panels | Low risk; smoke only |\n\n### Repo-wide dead-code / quality audit (2026-07)\n\nOpen items across the hand-written crates (reactor, bindgen, rdl, clang, canvas, metadata, webview,\ncore) that need a design decision or a larger change. Any bindgen source change must be proven\noutput-neutral by running the `tool-*` generators and confirming `git diff` shows no generated-file\nchanges (the `gen` workflow enforces this).\n\n#### Duplication / refactor candidates\n\n| Location | Issue |\n| --- | --- |\n| `metadata` `merge/mod.rs` `write_type` vs `merge/remap.rs` `write_type` | Two ~60-line structurally identical functions; the remap copy's comment says it mirrors `merge::write_type`. Any new ECMA table must be added to both, with no compiler guard. |\n| `canvas` `session.rs` gradient-stop + bitmap-properties builders | Duplicated ABI-stop and bitmap-properties construction across the brush paths. |\n| `bindgen` `types/interface.rs` + `cpp_interface.rs` local `fn combine` | Duplicate local helper. |\n| `canvas` `color.rs` `DARK_SLATE_BLUE` | `rgb(0.05, 0.05, 0.1)` does not match the CSS color of that name (public API used by samples). |\n\n#### Coverage gaps\n\n| Area | Gap |\n| --- | --- |\n| `metadata` `Remapper` (`merge/remap.rs`) | No tests anywhere; routing/`split_apis` logic is exercised only in the live build, so a regression yields a malformed namespaced winmd with no failing test. |\n| webview | `process-failed`, download, and deferral paths untested. |\n</yakaai_skills>"}