[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69B90PW92BQ4YNZYTP4SERB":3,"skill-same:01M69B90PW92BQ4YNZYTP4SERB":78},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":38,"linkOnly":39,"markdownContent":40,"markdownBody":41,"frontMatter":42,"refName":55,"commitSha":56,"skillDirectory":57,"forksCount":58,"repositoryHtmlUrl":59,"repositoryHomepageUrl":6,"ownerHtmlUrl":60,"ownerBlogUrl":61,"ownerDescription":62,"updatedAt":63,"install":64,"resources":77},"01M69B90PW92BQ4YNZYTP4SERB","reactor-windowing",null,"Reactor top-level windowing cookbook: WindowSpec, OpenWindow, draggable windows, borderless\u002Ftool windows, placement persistence, taskbar visibility, z-order, aspect ratio, SizeToContent, displays, taskbar integration, and owner-window file\u002Ffolder pickers.","microsoft\u002Fmicrosoft-ui-reactor","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69B6EF21X2GHARCXN2BH1K1",896,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fplugins\u002Freactor\u002Fskills\u002Freactor-windowing\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"reactor windowing","progress","make","position","persistence","cookbook","integration","folder","command","command palette","top","window","palette","file","restore","open","tool","windows","remember","2026-11-10 10:12:30",false,"---\nname: reactor-windowing\ndescription: \"Reactor top-level windowing cookbook: WindowSpec, OpenWindow, draggable windows, borderless\u002Ftool windows, placement persistence, taskbar visibility, z-order, aspect ratio, SizeToContent, displays, taskbar integration, and owner-window file\u002Ffolder pickers.\"\nwhen_to_invoke:\n  - \"open a window\"\n  - \"secondary window\"\n  - \"make a window draggable\"\n  - \"remember window position\"\n  - \"restore window placement\"\n  - \"tool palette\"\n  - \"command palette\"\n  - \"window aspect ratio\"\n  - \"borderless window\"\n  - \"always on top\"\n  - \"taskbar progress\"\n  - \"file picker\"\n---\n\n# Reactor Windowing\n\nUse this skill when a task involves top-level windows, placement, shell chrome,\ntaskbar features, displays, or native pickers.\n\n## Core APIs\n\n```csharp\nvar win = ReactorApp.OpenWindow(\n    new WindowSpec { Title = \"Settings\", Width = 520, Height = 420 },\n    () => new SettingsWindow());\n\nwin.Activate();\nwin.Close();\n```\n\n`WindowSpec` is immutable startup intent. `ReactorWindow` is the live handle for\nruntime mutators (`SetSize`, `SetPosition`, `SetAspectRatio`, `BeginDragMove`,\n`SavePlacement`, `Update`).\n\n## Size and resize\n\n```csharp\nnew WindowSpec\n{\n    ResizeMode = WindowResizeMode.CanMinimize,       \u002F\u002F CanResize | NoResize | CanMinimize\n    AspectRatio = 16.0 \u002F 9.0,\n    MinWidth = 480,\n    SizeToContent = WindowSizeToContent.Manual,      \u002F\u002F Manual | Width | Height | WidthAndHeight\n};\n\nUseWindow()?.SetAspectRatio(4.0 \u002F 3.0);\nUseWindowAspectRatio(1.0); \u002F\u002F scoped; unmount clears\n```\n\nRules:\n\n- `AspectRatio` cannot combine with `ResizeMode.NoResize`.\n- `AspectRatio` cannot combine with `SizeToContent`.\n- `SizeToContent` ignores maximized windows and may settle one frame after mount.\n\n## Movement, drag, and persistence\n\n```csharp\nnew WindowSpec\n{\n    StartPosition = WindowStartPosition.CenterOnCurrent,\n    IsMovableByBackground = true,\n};\n\nvar (x, y) = UseWindowPosition();\nvar drag = UseWindowDragMove();\nButton(\"Drag\", drag);\nBorder(customEditor).Drag(false); \u002F\u002F opt out of background drag\n```\n\nWindow hooks (`UseWindow`, `UseWindowPosition`, `UseWindowDragMove`, `UseDpi`, `UseWindowState`,\n`UseIsActive`, `UseClosingGuard`, `UseWindowAspectRatio`, …) bind the window whose host renders the\ncomponent, including nested components and virtualized rows, never \"the most recently active window\".\nIn tray flyouts and `ReactorHostControl` embeds they return `null` \u002F their outside-a-window values.\n\n```csharp\nvar spec = new WindowSpec { Title = \"Shell\" }\n    .WithPersistence(\"shell-main\", WindowStartPosition.CenterOnCurrent);\n\nUseWindow()?.SavePlacement();\n```\n\nPersistence requires `PersistPlacement`; use `.WithPersistence(...)` for the\ncommon case. `PersistenceId` alone is only identity for persistence systems.\n\nPlacement goes to an auto-picked store: `ApplicationData.Current.LocalSettings`\nwhen packaged, else a JSON file under `%LOCALAPPDATA%\u002F\u003CProcessName>\u002F`. That\ndefault is keyed on the **process name**, so renaming the exe strands saved\nlayouts. Unpackaged apps can opt into a stable publisher\u002Fproduct identity\nbefore the first `OpenWindow`:\n\n```csharp\nusing Microsoft.UI.Reactor.Hosting.Persistence;\n\nReactorApp.WindowPersistenceStore =\n    new UnpackagedAppDataStore(publisher: \"Contoso\", product: \"TimeTracker\");\n```\n\nOpt-in rather than default: the two stores key data differently, so switching\ndoes not migrate existing layouts. Multiple instances sharing one\npublisher\u002Fproduct are safe — writes are serialized across processes, so one\nwindow's save cannot drop another's entry. Two windows sharing a\n`PersistenceId` still overwrite each other, by design.\n\n## Z-order, taskbar, and chrome\n\n```csharp\nnew WindowSpec\n{\n    ShowInTaskbar = false,\n    ShowInSwitcher = true,\n    Level = WindowLevel.Floating,          \u002F\u002F Normal | Floating | AlwaysOnTop\n    Style = WindowStyle.ToolWindow,        \u002F\u002F Default | None | ToolWindow\n    CornerStyle = WindowCornerStyle.RoundedSmall,\n};\n```\n\nNotes:\n\n- `Floating` stays above owners and sibling Reactor app windows.\n- `ToolWindow` hides from the taskbar by default unless `ShowInTaskbar` is explicit.\n- `WindowStyle.None` should normally set `IsMovableByBackground = true`.\n- `UseIsCovered()` is a z-order hint, not pixel-accurate occlusion.\n\n## Title bar and backdrop\n\n```csharp\nVStack(\n    TitleBar(\"My App\"),\n    Body());\n```\n\nA `TitleBar(...)` element infers `ExtendsContentIntoTitleBar = true` when the\nspec value is `null`. Explicit `true` or `false` wins.\n\n> **Close-safety caveat (#537):** `ExtendsContentIntoTitleBar = false` with a\n> mounted `TitleBar(...)` is allowed and previously crashed on close\n> (`STATUS_HEAP_CORRUPTION`); Reactor now flips the window back into\n> content-extended mode just before the native close (every close\u002Fexit\u002Fdispose\n> path) so it is safe. Prefer omitting `TitleBar(...)` when you want the system\n> title bar.\n\n### Title bar icon\n\n```csharp\nReactorApp.Run\u003CApp>(\"My App\", icon: WindowIcon.FromPath(\"Assets\u002FAppIcon.ico\"));\n\nTitleBar(\"My App\");            \u002F\u002F inherits the window icon -- nothing to declare\nTitleBar(\"My App\").NoIcon();   \u002F\u002F opt out, for a deliberately bare title bar\n```\n\nA `TitleBar(...)` with no `.Icon(...)` inherits the **window's** icon:\n`WindowSpec.Icon` if declared, otherwise the `Assets\\AppIcon.ico` convention\nbeside the app. Do not restate the app icon on the title bar — that is the\ndefault. Use `.Icon(...)` only to show a *different* mark there.\n\nNot inherited: an icon that exists only as an executable PE resource\n(`\u003CApplicationIcon>`), because that stage yields a raw `HICON` with no path and a\nXAML `IconSource` needs an image source; and an embedded window\n(`WindowSpec.Embed`), which never receives a window icon at all.\n\n### Icon sources\n\n```csharp\nWindowIcon.FromPath(\"Assets\u002FAppIcon.ico\");          \u002F\u002F file beside the app\nWindowIcon.FromResource(\"ms-appx:\u002F\u002F\u002FAssets\u002FA.ico\"); \u002F\u002F packaged resource\nWindowIcon.FromBytes(icoOrPngBytes);                \u002F\u002F encoded data in memory\nWindowIcon.FromRgba(pixels, 16, 16);                \u002F\u002F raw RGBA8, top-down\n```\n\nNot every surface takes every kind, because they need different primitives:\n\n| Surface | `FromPath` | `FromResource` | `FromBytes` \u002F `FromRgba` |\n| --- | --- | --- | --- |\n| Window caption \u002F Alt-Tab | yes | yes | no |\n| Tray icon, taskbar overlay, thumbnail toolbar | yes | no | yes |\n| Jump-list entry | unpackaged only | packaged only | no |\n\nThe three shell surfaces need a raw `HICON` (`LoadImageW` on a file, or\n`CreateIconFromResourceEx` on in-memory data), neither of which reads an\n`ms-appx:` URI. Jump lists need a `Uri`. `AppWindow.SetIcon` needs a filesystem\npath. An unusable source is skipped with a diagnostic, never thrown — on the\nwindow that means falling through to `Assets\\AppIcon.ico` or the PE icon, so a\nbinary `icon:` leaves the window no barer than declaring none.\n\nReach for the binary factories when the icon is an embedded resource, a\ndownload, or drawn at runtime: they avoid writing a temporary file. The bytes\nare copied at construction and held for the `WindowIcon`'s lifetime.\n\n### Tall title bar\n\n```csharp\nTitleBar(\"My App\").WithNavigation(nav).PaneToggleButtonVisible(true).Tall();\nnew WindowSpec { ExtendsContentIntoTitleBar = true, TitleBarHeight = WindowTitleBarHeight.Tall };\n```\n\n`.Tall()` \u002F `.HeightOption(WindowTitleBarHeight)` (`Standard` \u002F `Tall` \u002F\n`Collapsed`) is the layout for a title bar hosting a back button or pane toggle.\nIt sets both the system caption (`AppWindow.TitleBar.PreferredHeightOption`) and\nthe WinUI title-bar control's own height — the control does not follow the\ncaption, so setting one alone leaves them disagreeing. An explicit `.Height(...)`\nwins over the implied 48; `WindowSpec.TitleBarHeight` wins over the element.\n\n> Requires a content-extended window — the native setter throws\n> `ERROR_INVALID_STATE` otherwise. Reactor applies it after its own\n> content-extension flip and warns instead of throwing, so prefer this over\n> setting `PreferredHeightOption` from a `UseEffect`.\n\n### Caption button theme\n\n```csharp\nTitleBar(\"My App\").PreferredTheme(isDark ? WindowTitleBarTheme.Dark : WindowTitleBarTheme.Light);\nnew WindowSpec { TitleBarTheme = WindowTitleBarTheme.Dark };\n```\n\nWinUI does not carry an element's `RequestedTheme` to the system caption buttons\n(min\u002Fmax\u002Fclose), so a root themed opposite to the system keeps system-themed buttons.\n`.PreferredTheme(WindowTitleBarTheme)` (`Legacy` \u002F `UseDefaultAppMode` \u002F `Light` \u002F\n`Dark`) writes `AppWindow.TitleBar.PreferredTheme` on mount and on change — no\n`UseEffect`. Opt-in: with nothing declared Reactor never writes the property, and\nremoving a declaration restores the value the caption had before Reactor first applied one.\n`WindowSpec.TitleBarTheme` wins over the element. Unlike the height, it does not\nneed a content-extended window.\n\n### Custom title-bar content and drag regions\n\n`TitleBar(...)` accepts a leading `.LeftHeader(...)`, central `.Content(...)`,\nand trailing `.RightHeader(...)`, each hosting a Reactor element. Removing a slot\nwith `with { LeftHeader = null }` also cleans up its subtree. Interactive controls are excluded from\nthe drag region automatically (WinApp SDK ≥ 2.1.3). Override per element with\n`.IsDragRegion(false)` (force clickable) or `.IsDragRegion(true)` (force draggable),\nand add `.AutoRefreshDragRegions()` when the content changes across renders:\n\n```csharp\n(TitleBar(\"Gallery\") with\n{\n    Content = HStack(8,\n        AutoSuggestBox(\"\", _ => {}).Width(200),\n        Button(Icon(FontIcon(\"\\uE713\", fontSize: 16)), OnSettings)\n            .AutomationName(\"Settings\").IsDragRegion(false)),\n}).AutoRefreshDragRegions();\n```\n\n```csharp\nVStack(...).Backdrop(BackdropKind.Mica);\nnew WindowSpec { Backdrop = BackdropChoice.Of(BackdropKind.DesktopAcrylic) };\n```\n\n`BackdropKind.Transparent` falls back to no backdrop when unsupported by the\nreferenced Windows App SDK.\n\n## Taskbar, displays, and pickers\n\n```csharp\nvar taskbar = UseWindow()!.TaskbarItem;\ntaskbar.Description = \"Exporting\";\ntaskbar.Progress.State = TaskbarProgressState.Normal;\ntaskbar.Progress.Value = 0.25;\n\nvar displays = UseDisplays();\nvar nearest = ReactorDisplay.NearestTo(window.Position.X, window.Position.Y);\n\n\u002F\u002F Pickers are not hooks: call them directly from UI-thread event handlers, never during Render.\n\u002F\u002F using Microsoft.Windows.Storage.Pickers;  (not Windows.Storage.Pickers: both define PickerLocationId)\nreturn VStack(\n    Button(\"Open\", async () => { var file = await PickFileAsync(new(FileTypeFilter: [\".txt\"])); if (file is null) return; var text = await File.ReadAllTextAsync(file.Path); }),\n    Button(\"Open multiple\", async () => { var files = await PickMultipleFilesAsync(new() { FileTypeChoices = [new(\"Notes\", [\".txt\", \".md\"])] }); }),\n    Button(\"Folder\", async () => { var folder = await PickFolderAsync(new()); }),\n    Button(\"Folders\", async () => { var folders = await PickMultipleFoldersAsync(new()); }),\n    Button(\"Save\", async () => { var target = await PickSaveFileAsync(new(\n        [new(\"Text\", [\".txt\"]), new(\"Markdown\", [\".md\"])], SuggestedFileName: \"report\"));\n        if (target is not null) await File.WriteAllTextAsync(target.Path, \"body\"); }));\n```\n\n`PickFileAsync` \u002F `PickMultipleFilesAsync` \u002F `PickFolderAsync` \u002F `PickMultipleFoldersAsync` \u002F `PickSaveFileAsync`\nreturn `PickFileResult` \u002F `PickFolderResult` (`Microsoft.Windows.Storage.Pickers`, exposing `.Path`); cancellation\nreturns `null` or an empty list. The owner is the window whose host renders the component (not whichever window is\nactive), the dialog works in elevated apps, and the call throws `InvalidOperationException` once the component has\nunmounted or its window has closed. Inside `ReactorHostControl` the owner is the window the control is loaded in\nwhen the method is called; an unloaded control throws. `FileTypeChoices` is an ordered\n`IReadOnlyList\u003CFileTypeChoice>` whose order sets the default entry; labels\nmust be unique. Options also take `Title`, `SuggestedFolder`, `SuggestedStartFolder`, `InitialFileTypeIndex`, and\n(save) `DefaultFileExtension` \u002F `ShowOverwritePrompt`. There is no arbitrary HWND parameter.\n\n## Render errors\n\nOutside an `ErrorBoundary`, a render failure shows a built-in fallback with the\nfull exception text. Replace it app-wide, per window, or per host; a host's own\nhandler wins, and `null` on the window\u002Fhost falls through to the app default:\n\n```csharp\nReactorApp.DefaultRenderErrorHandler = e => TextBlock(\"Something went wrong.\");\nReactorApp.OpenWindow(spec with { RenderErrorHandler = e => SettingsErrorView(e) }, render);\nwindow.Host.RenderErrorHandler = e => { e.Propagate(); return null; }; \u002F\u002F → OnUnhandledException\n```\n\nReturn `null` to keep the built-in fallback. If the handler (or the element it\nreturns) throws, Reactor shows a neutral message without exception details. The\nhandler runs again each time a failing component re-renders, so de-duplicate\ntelemetry. If `OnUnhandledException` declines a propagated error, a re-render\nends the process (WinUI does not raise `Application.UnhandledException` for it).\n\n## Recipe: Command Palette\n\nPowerToys Run-style launcher. See `samples\u002Fapps\u002Fcommand-palette-window\u002F`.\n\n```csharp\nnew WindowSpec\n{\n    Style = WindowStyle.None,\n    IsMovableByBackground = true,\n    Level = WindowLevel.AlwaysOnTop,\n    CornerStyle = WindowCornerStyle.Rounded,\n    StartPosition = WindowStartPosition.CenterOnCurrent,\n    ShowInTaskbar = false,\n    ShowInSwitcher = false,\n};\n```\n\n## Recipe: Tool Palette\n\nPhotoshop-style owned floating palette. See `samples\u002Fapps\u002Ftool-palette\u002F`.\n\n```csharp\nvar main = ReactorApp.OpenWindow(new WindowSpec { Title = \"Editor\" }, () => new Editor());\n\nReactorApp.OpenWindow(new WindowSpec\n{\n    Title = \"Tools\",\n    Owner = main,\n    Style = WindowStyle.ToolWindow,\n    Level = WindowLevel.Floating,\n    CornerStyle = WindowCornerStyle.RoundedSmall,\n}, () => new ToolPalette());\n```\n\n## Recipe: Media Player (aspect-locked)\n\n```csharp\nnew WindowSpec\n{\n    Title = \"Player\",\n    Width = 960,\n    Height = 540,\n    AspectRatio = 16.0 \u002F 9.0,\n};\n\nUseWindow()?.SetAspectRatio(videoWidth \u002F (double)videoHeight);\nUseWindowAspectRatio(16.0 \u002F 9.0);\n```\n","# Reactor Windowing\n\nUse this skill when a task involves top-level windows, placement, shell chrome,\ntaskbar features, displays, or native pickers.\n\n## Core APIs\n\n```csharp\nvar win = ReactorApp.OpenWindow(\n    new WindowSpec { Title = \"Settings\", Width = 520, Height = 420 },\n    () => new SettingsWindow());\n\nwin.Activate();\nwin.Close();\n```\n\n`WindowSpec` is immutable startup intent. `ReactorWindow` is the live handle for\nruntime mutators (`SetSize`, `SetPosition`, `SetAspectRatio`, `BeginDragMove`,\n`SavePlacement`, `Update`).\n\n## Size and resize\n\n```csharp\nnew WindowSpec\n{\n    ResizeMode = WindowResizeMode.CanMinimize,       \u002F\u002F CanResize | NoResize | CanMinimize\n    AspectRatio = 16.0 \u002F 9.0,\n    MinWidth = 480,\n    SizeToContent = WindowSizeToContent.Manual,      \u002F\u002F Manual | Width | Height | WidthAndHeight\n};\n\nUseWindow()?.SetAspectRatio(4.0 \u002F 3.0);\nUseWindowAspectRatio(1.0); \u002F\u002F scoped; unmount clears\n```\n\nRules:\n\n- `AspectRatio` cannot combine with `ResizeMode.NoResize`.\n- `AspectRatio` cannot combine with `SizeToContent`.\n- `SizeToContent` ignores maximized windows and may settle one frame after mount.\n\n## Movement, drag, and persistence\n\n```csharp\nnew WindowSpec\n{\n    StartPosition = WindowStartPosition.CenterOnCurrent,\n    IsMovableByBackground = true,\n};\n\nvar (x, y) = UseWindowPosition();\nvar drag = UseWindowDragMove();\nButton(\"Drag\", drag);\nBorder(customEditor).Drag(false); \u002F\u002F opt out of background drag\n```\n\nWindow hooks (`UseWindow`, `UseWindowPosition`, `UseWindowDragMove`, `UseDpi`, `UseWindowState`,\n`UseIsActive`, `UseClosingGuard`, `UseWindowAspectRatio`, …) bind the window whose host renders the\ncomponent, including nested components and virtualized rows, never \"the most recently active window\".\nIn tray flyouts and `ReactorHostControl` embeds they return `null` \u002F their outside-a-window values.\n\n```csharp\nvar spec = new WindowSpec { Title = \"Shell\" }\n    .WithPersistence(\"shell-main\", WindowStartPosition.CenterOnCurrent);\n\nUseWindow()?.SavePlacement();\n```\n\nPersistence requires `PersistPlacement`; use `.WithPersistence(...)` for the\ncommon case. `PersistenceId` alone is only identity for persistence systems.\n\nPlacement goes to an auto-picked store: `ApplicationData.Current.LocalSettings`\nwhen packaged, else a JSON file under `%LOCALAPPDATA%\u002F\u003CProcessName>\u002F`. That\ndefault is keyed on the **process name**, so renaming the exe strands saved\nlayouts. Unpackaged apps can opt into a stable publisher\u002Fproduct identity\nbefore the first `OpenWindow`:\n\n```csharp\nusing Microsoft.UI.Reactor.Hosting.Persistence;\n\nReactorApp.WindowPersistenceStore =\n    new UnpackagedAppDataStore(publisher: \"Contoso\", product: \"TimeTracker\");\n```\n\nOpt-in rather than default: the two stores key data differently, so switching\ndoes not migrate existing layouts. Multiple instances sharing one\npublisher\u002Fproduct are safe — writes are serialized across processes, so one\nwindow's save cannot drop another's entry. Two windows sharing a\n`PersistenceId` still overwrite each other, by design.\n\n## Z-order, taskbar, and chrome\n\n```csharp\nnew WindowSpec\n{\n    ShowInTaskbar = false,\n    ShowInSwitcher = true,\n    Level = WindowLevel.Floating,          \u002F\u002F Normal | Floating | AlwaysOnTop\n    Style = WindowStyle.ToolWindow,        \u002F\u002F Default | None | ToolWindow\n    CornerStyle = WindowCornerStyle.RoundedSmall,\n};\n```\n\nNotes:\n\n- `Floating` stays above owners and sibling Reactor app windows.\n- `ToolWindow` hides from the taskbar by default unless `ShowInTaskbar` is explicit.\n- `WindowStyle.None` should normally set `IsMovableByBackground = true`.\n- `UseIsCovered()` is a z-order hint, not pixel-accurate occlusion.\n\n## Title bar and backdrop\n\n```csharp\nVStack(\n    TitleBar(\"My App\"),\n    Body());\n```\n\nA `TitleBar(...)` element infers `ExtendsContentIntoTitleBar = true` when the\nspec value is `null`. Explicit `true` or `false` wins.\n\n> **Close-safety caveat (#537):** `ExtendsContentIntoTitleBar = false` with a\n> mounted `TitleBar(...)` is allowed and previously crashed on close\n> (`STATUS_HEAP_CORRUPTION`); Reactor now flips the window back into\n> content-extended mode just before the native close (every close\u002Fexit\u002Fdispose\n> path) so it is safe. Prefer omitting `TitleBar(...)` when you want the system\n> title bar.\n\n### Title bar icon\n\n```csharp\nReactorApp.Run\u003CApp>(\"My App\", icon: WindowIcon.FromPath(\"Assets\u002FAppIcon.ico\"));\n\nTitleBar(\"My App\");            \u002F\u002F inherits the window icon -- nothing to declare\nTitleBar(\"My App\").NoIcon();   \u002F\u002F opt out, for a deliberately bare title bar\n```\n\nA `TitleBar(...)` with no `.Icon(...)` inherits the **window's** icon:\n`WindowSpec.Icon` if declared, otherwise the `Assets\\AppIcon.ico` convention\nbeside the app. Do not restate the app icon on the title bar — that is the\ndefault. Use `.Icon(...)` only to show a *different* mark there.\n\nNot inherited: an icon that exists only as an executable PE resource\n(`\u003CApplicationIcon>`), because that stage yields a raw `HICON` with no path and a\nXAML `IconSource` needs an image source; and an embedded window\n(`WindowSpec.Embed`), which never receives a window icon at all.\n\n### Icon sources\n\n```csharp\nWindowIcon.FromPath(\"Assets\u002FAppIcon.ico\");          \u002F\u002F file beside the app\nWindowIcon.FromResource(\"ms-appx:\u002F\u002F\u002FAssets\u002FA.ico\"); \u002F\u002F packaged resource\nWindowIcon.FromBytes(icoOrPngBytes);                \u002F\u002F encoded data in memory\nWindowIcon.FromRgba(pixels, 16, 16);                \u002F\u002F raw RGBA8, top-down\n```\n\nNot every surface takes every kind, because they need different primitives:\n\n| Surface | `FromPath` | `FromResource` | `FromBytes` \u002F `FromRgba` |\n| --- | --- | --- | --- |\n| Window caption \u002F Alt-Tab | yes | yes | no |\n| Tray icon, taskbar overlay, thumbnail toolbar | yes | no | yes |\n| Jump-list entry | unpackaged only | packaged only | no |\n\nThe three shell surfaces need a raw `HICON` (`LoadImageW` on a file, or\n`CreateIconFromResourceEx` on in-memory data), neither of which reads an\n`ms-appx:` URI. Jump lists need a `Uri`. `AppWindow.SetIcon` needs a filesystem\npath. An unusable source is skipped with a diagnostic, never thrown — on the\nwindow that means falling through to `Assets\\AppIcon.ico` or the PE icon, so a\nbinary `icon:` leaves the window no barer than declaring none.\n\nReach for the binary factories when the icon is an embedded resource, a\ndownload, or drawn at runtime: they avoid writing a temporary file. The bytes\nare copied at construction and held for the `WindowIcon`'s lifetime.\n\n### Tall title bar\n\n```csharp\nTitleBar(\"My App\").WithNavigation(nav).PaneToggleButtonVisible(true).Tall();\nnew WindowSpec { ExtendsContentIntoTitleBar = true, TitleBarHeight = WindowTitleBarHeight.Tall };\n```\n\n`.Tall()` \u002F `.HeightOption(WindowTitleBarHeight)` (`Standard` \u002F `Tall` \u002F\n`Collapsed`) is the layout for a title bar hosting a back button or pane toggle.\nIt sets both the system caption (`AppWindow.TitleBar.PreferredHeightOption`) and\nthe WinUI title-bar control's own height — the control does not follow the\ncaption, so setting one alone leaves them disagreeing. An explicit `.Height(...)`\nwins over the implied 48; `WindowSpec.TitleBarHeight` wins over the element.\n\n> Requires a content-extended window — the native setter throws\n> `ERROR_INVALID_STATE` otherwise. Reactor applies it after its own\n> content-extension flip and warns instead of throwing, so prefer this over\n> setting `PreferredHeightOption` from a `UseEffect`.\n\n### Caption button theme\n\n```csharp\nTitleBar(\"My App\").PreferredTheme(isDark ? WindowTitleBarTheme.Dark : WindowTitleBarTheme.Light);\nnew WindowSpec { TitleBarTheme = WindowTitleBarTheme.Dark };\n```\n\nWinUI does not carry an element's `RequestedTheme` to the system caption buttons\n(min\u002Fmax\u002Fclose), so a root themed opposite to the system keeps system-themed buttons.\n`.PreferredTheme(WindowTitleBarTheme)` (`Legacy` \u002F `UseDefaultAppMode` \u002F `Light` \u002F\n`Dark`) writes `AppWindow.TitleBar.PreferredTheme` on mount and on change — no\n`UseEffect`. Opt-in: with nothing declared Reactor never writes the property, and\nremoving a declaration restores the value the caption had before Reactor first applied one.\n`WindowSpec.TitleBarTheme` wins over the element. Unlike the height, it does not\nneed a content-extended window.\n\n### Custom title-bar content and drag regions\n\n`TitleBar(...)` accepts a leading `.LeftHeader(...)`, central `.Content(...)`,\nand trailing `.RightHeader(...)`, each hosting a Reactor element. Removing a slot\nwith `with { LeftHeader = null }` also cleans up its subtree. Interactive controls are excluded from\nthe drag region automatically (WinApp SDK ≥ 2.1.3). Override per element with\n`.IsDragRegion(false)` (force clickable) or `.IsDragRegion(true)` (force draggable),\nand add `.AutoRefreshDragRegions()` when the content changes across renders:\n\n```csharp\n(TitleBar(\"Gallery\") with\n{\n    Content = HStack(8,\n        AutoSuggestBox(\"\", _ => {}).Width(200),\n        Button(Icon(FontIcon(\"\\uE713\", fontSize: 16)), OnSettings)\n            .AutomationName(\"Settings\").IsDragRegion(false)),\n}).AutoRefreshDragRegions();\n```\n\n```csharp\nVStack(...).Backdrop(BackdropKind.Mica);\nnew WindowSpec { Backdrop = BackdropChoice.Of(BackdropKind.DesktopAcrylic) };\n```\n\n`BackdropKind.Transparent` falls back to no backdrop when unsupported by the\nreferenced Windows App SDK.\n\n## Taskbar, displays, and pickers\n\n```csharp\nvar taskbar = UseWindow()!.TaskbarItem;\ntaskbar.Description = \"Exporting\";\ntaskbar.Progress.State = TaskbarProgressState.Normal;\ntaskbar.Progress.Value = 0.25;\n\nvar displays = UseDisplays();\nvar nearest = ReactorDisplay.NearestTo(window.Position.X, window.Position.Y);\n\n\u002F\u002F Pickers are not hooks: call them directly from UI-thread event handlers, never during Render.\n\u002F\u002F using Microsoft.Windows.Storage.Pickers;  (not Windows.Storage.Pickers: both define PickerLocationId)\nreturn VStack(\n    Button(\"Open\", async () => { var file = await PickFileAsync(new(FileTypeFilter: [\".txt\"])); if (file is null) return; var text = await File.ReadAllTextAsync(file.Path); }),\n    Button(\"Open multiple\", async () => { var files = await PickMultipleFilesAsync(new() { FileTypeChoices = [new(\"Notes\", [\".txt\", \".md\"])] }); }),\n    Button(\"Folder\", async () => { var folder = await PickFolderAsync(new()); }),\n    Button(\"Folders\", async () => { var folders = await PickMultipleFoldersAsync(new()); }),\n    Button(\"Save\", async () => { var target = await PickSaveFileAsync(new(\n        [new(\"Text\", [\".txt\"]), new(\"Markdown\", [\".md\"])], SuggestedFileName: \"report\"));\n        if (target is not null) await File.WriteAllTextAsync(target.Path, \"body\"); }));\n```\n\n`PickFileAsync` \u002F `PickMultipleFilesAsync` \u002F `PickFolderAsync` \u002F `PickMultipleFoldersAsync` \u002F `PickSaveFileAsync`\nreturn `PickFileResult` \u002F `PickFolderResult` (`Microsoft.Windows.Storage.Pickers`, exposing `.Path`); cancellation\nreturns `null` or an empty list. The owner is the window whose host renders the component (not whichever window is\nactive), the dialog works in elevated apps, and the call throws `InvalidOperationException` once the component has\nunmounted or its window has closed. Inside `ReactorHostControl` the owner is the window the control is loaded in\nwhen the method is called; an unloaded control throws. `FileTypeChoices` is an ordered\n`IReadOnlyList\u003CFileTypeChoice>` whose order sets the default entry; labels\nmust be unique. Options also take `Title`, `SuggestedFolder`, `SuggestedStartFolder`, `InitialFileTypeIndex`, and\n(save) `DefaultFileExtension` \u002F `ShowOverwritePrompt`. There is no arbitrary HWND parameter.\n\n## Render errors\n\nOutside an `ErrorBoundary`, a render failure shows a built-in fallback with the\nfull exception text. Replace it app-wide, per window, or per host; a host's own\nhandler wins, and `null` on the window\u002Fhost falls through to the app default:\n\n```csharp\nReactorApp.DefaultRenderErrorHandler = e => TextBlock(\"Something went wrong.\");\nReactorApp.OpenWindow(spec with { RenderErrorHandler = e => SettingsErrorView(e) }, render);\nwindow.Host.RenderErrorHandler = e => { e.Propagate(); return null; }; \u002F\u002F → OnUnhandledException\n```\n\nReturn `null` to keep the built-in fallback. If the handler (or the element it\nreturns) throws, Reactor shows a neutral message without exception details. The\nhandler runs again each time a failing component re-renders, so de-duplicate\ntelemetry. If `OnUnhandledException` declines a propagated error, a re-render\nends the process (WinUI does not raise `Application.UnhandledException` for it).\n\n## Recipe: Command Palette\n\nPowerToys Run-style launcher. See `samples\u002Fapps\u002Fcommand-palette-window\u002F`.\n\n```csharp\nnew WindowSpec\n{\n    Style = WindowStyle.None,\n    IsMovableByBackground = true,\n    Level = WindowLevel.AlwaysOnTop,\n    CornerStyle = WindowCornerStyle.Rounded,\n    StartPosition = WindowStartPosition.CenterOnCurrent,\n    ShowInTaskbar = false,\n    ShowInSwitcher = false,\n};\n```\n\n## Recipe: Tool Palette\n\nPhotoshop-style owned floating palette. See `samples\u002Fapps\u002Ftool-palette\u002F`.\n\n```csharp\nvar main = ReactorApp.OpenWindow(new WindowSpec { Title = \"Editor\" }, () => new Editor());\n\nReactorApp.OpenWindow(new WindowSpec\n{\n    Title = \"Tools\",\n    Owner = main,\n    Style = WindowStyle.ToolWindow,\n    Level = WindowLevel.Floating,\n    CornerStyle = WindowCornerStyle.RoundedSmall,\n}, () => new ToolPalette());\n```\n\n## Recipe: Media Player (aspect-locked)\n\n```csharp\nnew WindowSpec\n{\n    Title = \"Player\",\n    Width = 960,\n    Height = 540,\n    AspectRatio = 16.0 \u002F 9.0,\n};\n\nUseWindow()?.SetAspectRatio(videoWidth \u002F (double)videoHeight);\nUseWindowAspectRatio(16.0 \u002F 9.0);\n```\n",{"name":5,"description":7,"when_to_invoke":43},[44,45,46,47,48,49,28,50,51,52,53,54],"open a window","secondary window","make a window draggable","remember window position","restore window placement","tool palette","window aspect ratio","borderless window","always on top","taskbar progress","file picker","main","0cdc78ad040d2b6b8c50c2899f6c10ce1d2849d1","plugins\u002Freactor\u002Fskills\u002Freactor-windowing",67,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-15 01:08:04",{"source":8,"skillName":5,"commands":65,"prompt":75,"zipAvailable":76},[66,69,72],{"tool":67,"command":68},"npx","npx skills add microsoft\u002Fmicrosoft-ui-reactor --skill reactor-windowing",{"tool":70,"command":71},"bunx","bunx skills add microsoft\u002Fmicrosoft-ui-reactor --skill reactor-windowing",{"tool":73,"command":74},"pnpm","pnpm dlx skills add microsoft\u002Fmicrosoft-ui-reactor --skill reactor-windowing","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fplugins\u002Freactor\u002Fskills\u002Freactor-windowing\u002FSKILL.md",true,[],[79,85,113,138,161,179],{"skillNo":80,"name":81,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":38},"01M69B94E15PYYWXAGFV832MRK","Charting","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fsrc\u002FReactor.Advanced\u002FCharting\u002Fskill.md",[],[81],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":38},"01M69B92C846XMSNJ4PZGVYY3C","reactor-wrapping","Turn ANY WinUI control — a vendor\u002Fthird-party control, your own custom Control, or a Windows Community Toolkit one — into a first-class declarative Reactor element with the [GenerateReactorWrapper] source generator, zero hand-written wrapper code. Covers auto-inference (props, content, two-way pairs, panel\u002Fitems children, events), the [Wrap*] annotation cheat-sheet, imperative-lifecycle controls, diagnostics, and when to fall back to a hand-written ControlDescriptor.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fplugins\u002Freactor\u002Fskills\u002Freactor-wrapping\u002FSKILL.md",[],[92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,36],"reactor wrapping","declarative","with","hand","code","cheat","generator","when","auto","controls","custom","element","lifecycle","winui","ZeRO","panel","community","back","inference","diagnostics","toolkit",{"skillNo":114,"name":115,"nameZh":6,"description":116,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":117,"categories":118,"keywords":119,"publishedAt":38},"01M69B8Y5Y0VKXADXCN3W1NK89","reactor-recipes","Paste-ready single-file Reactor recipes indexed by intent — list with add\u002Fdelete\u002Ftoggle, sidebar navigation between pages, form with validation + submit gating, async fetch with loading\u002Ferror\u002Fdata states, themed Win11 card surface. Use a recipe instead of synthesizing from prose: copy, adjust, ship.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fplugins\u002Freactor\u002Fskills\u002Freactor-recipes\u002FSKILL.md",[],[120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,32,94],"reactor recipes","recipes","pages","gating","single","recipe","adjust","use","async","card","submit","loading","states","fetch","form","single-file","ready","error",{"skillNo":139,"name":140,"nameZh":6,"description":141,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":142,"categories":143,"keywords":144,"publishedAt":38},"01M69B8WNYS31M4P012P2QTX6R","reactor-navigation","Reactor navigation — `UseNavigation` hook, `NavigationHost` renderer, `NavigationView` sidebar, `TabView` tabs, route params, stack operations, page lifecycle, deep linking, transitions, caching. Use when building multi-page apps or wiring sidebar\u002Ftab navigation.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fplugins\u002Freactor\u002Fskills\u002Freactor-navigation\u002FSKILL.md",[],[145,146,147,148,149,150,151,152,153,154,155,99,156,127,104,157,158,159,160],"navigation","reactor navigation","hook","stack","renderer","transitions","linking","route","multi","wiring","caching","apps","operations","multi-page","page","deep",{"skillNo":162,"name":163,"nameZh":6,"description":164,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":165,"categories":166,"keywords":167,"publishedAt":38},"01M69B8TGJA43N8X6BFVWTXC1H","reactor-input","Reactor input — gestures (`OnPan`, `OnPinch`, `OnRotate`), pointer events, drag-and-drop (`OnDragStarting`), focus management (`UseElementFocus`, `UseFocus`, `UseFocusTrap`). Use when implementing direct manipulation or custom focus behavior.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fplugins\u002Freactor\u002Fskills\u002Freactor-input\u002FSKILL.md",[],[168,169,102,170,171,172,127,173,174,175,176,177,178,99],"reactor input","input","implementing","drag","gestures","events","direct","management","behavior","focus","drop",{"skillNo":180,"name":181,"nameZh":6,"description":182,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":183,"categories":184,"keywords":193,"publishedAt":38},"01M69B8R3MR39KBJ6V4NXGEB2N","reactor-getting-started","Reactor essentials in one place — React-to-Reactor mental model, minimal app shape, hooks, the most-used factories, the critical gotchas, and project setup. This is the only skill you need loaded for typical Reactor work; load topical skills (`reactor-async`, `reactor-design`, etc.) only when the task explicitly calls for them.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fplugins\u002Freactor\u002Fskills\u002Freactor-getting-started\u002FSKILL.md",[185,190],{"categoryNo":186,"categoryName":187,"taxonomyType":188,"taxonomyTypeDesc":189},"01JBSEEDCAT000000000000009","前端开发","SCENARIO","使用场景",{"categoryNo":191,"categoryName":192,"taxonomyType":188,"taxonomyTypeDesc":189},"01JBSEEDCAT000000000000015","视觉设计",[194,195,196,197,198,199,200,128,201,202,203,99,204,205,206,207,208,209,210,211],"getting started","reactor getting started","work","task","load","minimal","calls","mental model","for","you","critical","only","hooks","project","model","app","react","design"]