[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69B8WNYS31M4P012P2QTX6R":3,"skill-same:01M69B8WNYS31M4P012P2QTX6R":66},{"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":43,"commitSha":44,"skillDirectory":45,"forksCount":46,"repositoryHtmlUrl":47,"repositoryHomepageUrl":6,"ownerHtmlUrl":48,"ownerBlogUrl":49,"ownerDescription":50,"updatedAt":51,"install":52,"resources":65},"01M69B8WNYS31M4P012P2QTX6R","reactor-navigation",null,"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.","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-navigation\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37],"navigation","reactor navigation","transitions","when","multi-page","wiring","linking","renderer","hook","multi","apps","deep","caching","route","use","operations","page","stack","lifecycle","2026-11-10 10:12:30",false,"---\nname: reactor-navigation\ndescription: \"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.\"\n---\n\n# Navigation in Reactor\n\nReactor uses a **stack-based navigation model** with type-safe routes. You\ndefine routes as an enum, create a navigation handle with `UseNavigation`,\nand render the current page with `NavigationHost`. The system manages\nback\u002Fforward stacks, transitions, caching, and deep linking.\n\n## Quick reference\n\n| API | Purpose |\n|-----|---------|\n| `UseNavigation(Route.Home)` | Create a `NavigationHandle\u003CRoute>` (call once at root) |\n| `UseNavigation\u003CRoute>()` | Retrieve the nearest ancestor's handle (child components) |\n| `NavigationHost(nav, route => ...)` | Render the current page |\n| `NavigationView([items], content)` | Sidebar navigation with icons |\n| `TabView(Tab(...), Tab(...))` | Tab-based parallel navigation |\n| `UseNavigationLifecycle(...)` | Page appear\u002Fdisappear callbacks |\n| `UseSystemBackButton(nav, window)` | Wire system back button to nav stack |\n| `DeepLinkMap\u003CRoute>` | Map URI patterns to routes |\n\n## 1. Defining routes\n\nUse an enum. Each value is a distinct page:\n\n```csharp\nenum Route { Home, Settings, Profile, Details }\n```\n\nFor routes that carry data, use a discriminated-union pattern with records:\n\n```csharp\nabstract record Route\n{\n    public record Home : Route;\n    public record Settings : Route;\n    public record Details(int ItemId) : Route;\n}\n```\n\n## 2. Basic navigation\n\n```csharp\nclass App : Component\n{\n    public override Element Render()\n    {\n        var nav = UseNavigation(Route.Home);\n\n        return VStack(12,\n            HStack(8,\n                Button(\"Home\", () => nav.Navigate(Route.Home)),\n                Button(\"Settings\", () => nav.Navigate(Route.Settings)),\n                Button(\"Back\", () => nav.GoBack()).IsEnabled(nav.CanGoBack)\n            ),\n            NavigationHost(nav, route => route switch\n            {\n                Route.Home     => Component\u003CHomePage>(),\n                Route.Settings => Component\u003CSettingsPage>(),\n                _ => TextBlock(\"Not found\")\n            })\n        );\n    }\n}\n```\n\n**Key points:**\n- `UseNavigation(Route.Home)` — call once at the root with the initial route.\n- `nav.Navigate(route)` — pushes onto the back stack.\n- `nav.GoBack()` \u002F `nav.GoForward()` — stack navigation.\n- `NavigationHost(nav, route => ...)` — renders the matched element.\n\n## 3. Stack operations\n\n| Method | Effect |\n|--------|--------|\n| `Navigate(route)` | Push route onto back stack |\n| `GoBack()` | Pop current, return to previous |\n| `GoForward()` | Move forward (after going back) |\n| `Replace(route)` | Swap current route without touching the stack |\n| `Reset(route)` | Clear all stacks, start fresh |\n| `PopTo(predicate)` | Pop until a matching route is found |\n\nProperties: `CurrentRoute`, `CanGoBack`, `CanGoForward`, `BackStack`,\n`ForwardStack`, `Depth`.\n\nUse `Reset` for sign-out flows to prevent navigating back to authenticated\npages.\n\n## 4. NavigationView (sidebar)\n\n```csharp\nvar nav = UseNavigation(Route.Home);\n\nreturn NavigationView(\n    [\n        NavItem(\"Home\", icon: \"Home\", tag: \"Home\"),\n        NavItem(\"Settings\", icon: \"Setting\", tag: \"Settings\"),\n        NavItem(\"Profile\", icon: \"Contact\", tag: \"Profile\")\n    ],\n    content: NavigationHost(nav, route => route switch\n    {\n        Route.Home     => VStack(Heading(\"Home\"), TextBlock(\"Welcome.\")).Padding(24),\n        Route.Settings => VStack(Heading(\"Settings\"), TextBlock(\"Configure.\")).Padding(24),\n        Route.Profile  => VStack(Heading(\"Profile\"), TextBlock(\"Your info.\")).Padding(24),\n        _ => TextBlock(\"Not found\").Padding(24)\n    })\n);\n```\n\n`NavItem(label, icon?, tag?)` creates sidebar items. Icons are Segoe Fluent\nIcons names. The `NavigationView` handles selection state.\n\n**Manual wiring (without `UseNavigation`):**\n`SelectedTag` and `OnSelectionChanged` are record properties — use `with { }`.\nFor the settings item: set `IsSettingsVisible = true` and check `args.IsSettingsSelected` (not via tag).\nUse `.Set(nv => nv.PaneDisplayMode = ...)` for non-record properties.\n\n## 5. TabView (parallel tabs)\n\nUnlike stack navigation, tabs keep all content alive simultaneously:\n\n```csharp\nreturn TabView(\n    Tab(\"Documents\", VStack(12,\n        TextBlock(\"Your documents.\"),\n        Button(\"New\", () => { })).Padding(24)),\n    Tab(\"Recent\", TextBlock(\"Recently opened.\").Padding(24)),\n    Tab(\"Shared\", TextBlock(\"Shared files.\").Padding(24))\n);\n```\n\nUse tabs when users switch freely between parallel workspaces.\n\n## 6. Page lifecycle\n\n`UseNavigationLifecycle` fires callbacks when a page appears or disappears:\n\nCallbacks are scoped to the nearest enclosing `NavigationHost`. Each nested host\ndispatches lifecycle events and guards for its own navigation stack.\n\n```csharp\nUseNavigationLifecycle(\n    onNavigatedTo: ctx => LoadData(ctx.PreviousRoute),\n    onNavigatingFrom: ctx =>\n    {\n        if (hasUnsavedChanges) ctx.Cancel(); \u002F\u002F prevent navigation\n    },\n    onNavigatedFrom: ctx => SaveDraft()\n);\n```\n\n| Callback | When |\n|----------|------|\n| `onNavigatedTo` | After this page becomes active — fetch data, start timers |\n| `onNavigatingFrom` | Before leaving — call `ctx.Cancel()` to block navigation |\n| `onNavigatedFrom` | After leaving — save drafts, stop timers |\n\n## 7. Page transitions\n\nSet `Transition` on `NavigationHost`:\n\n```csharp\nNavigationHost(nav, route => ...) with\n{\n    Transition = NavigationTransition.DrillIn()\n}\n```\n\n| Transition | Effect |\n|-----------|--------|\n| `NavigationTransition.Entrance()` | Slide up + fade in — the default, and what WinUI's `Frame` plays with no transition info |\n| `NavigationTransition.Slide()` | Slide + fade — vertical unless you pass a direction |\n| `NavigationTransition.Fade()` | Crossfade |\n| `NavigationTransition.DrillIn()` | Scale + fade — use for list→detail |\n| `NavigationTransition.Spring()` | Spring-physics slide |\n| `NavigationTransition.None` | Instant swap |\n| `NavigationTransition.Connected(key)` | Native shared-element motion |\n\n`NavigationTransition.Default` is an alias for `Entrance()`. Use `Entrance()` when you\nmean the motion; use `Default` only when you mean \"whatever the framework default is\".\n\nGoBack automatically reverses direction. Transitions run on the compositor\nthread.\n\n### Shared elements with independent page motion\n\nMark the source and destination with the same `.ConnectedAnimation(key)` and\nselect that key for the navigation:\n\n```csharp\nnav.Navigate(Route.Details, new NavigateOptions\n{\n    ConnectedAnimationKey = \"device-card\",\n    Transition = NavigationTransition.DrillIn(),\n});\n```\n\nThe shared element and page transition run together. `Transition = null` uses\nthe host's default; `NavigationTransition.None` selects shared-element-only\nmotion. `NavigationTransition.Connected(key)` is a shorthand for that latter case.\nThe key and page transition travel together on back\u002Fforward navigation.\n\nUse a unique key within each active page subtree, including nested hosts. The\ndestination can appear after its first render or effect: navigation waits for\nits measured bounds before starting native motion. Missing, duplicate, or\nzero-sized destinations fall back to the selected page transition. Reduced\nmotion completes the navigation immediately. Both motions finish before the\nold page is cached or unmounted and lifecycle completion callbacks run.\nInterrupted navigation still delivers the outgoing page's `onNavigatedFrom`;\nthe current destination receives `onNavigatedTo` when its transition completes.\n\n## 8. Deep linking\n\n`DeepLinkMap` maps URI patterns to route constructors:\n\n```csharp\nvar map = UseMemo(() => new DeepLinkMap\u003CRoute>()\n    .Map(\"\u002F\", _ => Route.Home)\n    .Map(\"\u002Fsettings\", _ => Route.Settings)\n    .Map(\"\u002Fusers\u002F{id:int}\u002Fposts\u002F{postId:int}\", args =>\n    {\n        var userId = args.Get\u003Cint>(\"id\");\n        var postId = args.Get\u003Cint>(\"postId\");\n        return Route.Details;\n    }, backStackFactory: () => new[] { Route.Home }));\n\n\u002F\u002F Resolve from activation URI:\nmap.Resolve(uri);\n```\n\n**Pattern segments:**\n\n| Segment | Matches |\n|---------|---------|\n| `\u002Fliteral` | Exact match |\n| `\u002F{param}` | String capture |\n| `\u002F{param:int}` | Typed capture (int, long, bool, Guid) |\n| `\u002F{param?}` | Optional parameter |\n| `\u002F{**}` | Wildcard — remaining path |\n| `?key=value` | Query string parameters |\n\n`backStackFactory` builds a synthetic back stack so GoBack works after\ndeep-linked entry.\n\n## 9. Page caching\n\n```csharp\nNavigationHost(nav, route => ...) with\n{\n    CacheMode = NavigationCacheMode.Enabled,\n    CacheSize = 5\n}\n```\n\n| Cache mode | Behavior |\n|-----------|----------|\n| `Disabled` | Always unmount\u002Fremount (default) |\n| `Enabled` | LRU cache up to `CacheSize` entries |\n| `Required` | Always cached, never evicted |\n\nCaching preserves scroll position, text input, and component state.\n\n## 10. State serialization\n\n```csharp\nvar state = nav.GetState();         \u002F\u002F NavigationState\u003CTRoute> snapshot\nnav.SetState(state);                \u002F\u002F restore stacks + fire Navigated(Reset)\n```\n\nReactor returns a plain `NavigationState\u003CTRoute>` POCO and lets you pick the\nstorage format. For JSON persistence pair the snapshot with a\n`JsonSerializerContext` (AOT-safe):\n\n```csharp\n[JsonSerializable(typeof(NavigationState\u003CAppRoute>))]\npartial class AppJsonContext : JsonSerializerContext { }\n\nvar json = JsonSerializer.Serialize(nav.GetState(), AppJsonContext.Default.NavigationStateAppRoute);\n\u002F\u002F later…\nnav.SetState(JsonSerializer.Deserialize(json, AppJsonContext.Default.NavigationStateAppRoute)!);\n```\n\nUse for persisting navigation across app restarts.\n\n## 11. System back button\n\n```csharp\nUseSystemBackButton(nav, window);\n```\n\nWires the Windows title-bar back button and hardware back button to your\nnavigation stack automatically.\n\n## Critical gotchas\n\n1. **Call `UseNavigation(initial)` once at the root.** Children retrieve the\n   same handle via `UseNavigation\u003CRoute>()` (no initial value) through\n   context.\n2. **Use enums for routes.** Compile-time safety — can't navigate to a\n   non-existent route.\n3. **Use `Reset` for sign-out.** Clears the stack so users can't go back.\n4. **DrillIn for list→detail.** Signals hierarchy; pairs with connected\n   animation.\n5. **`ctx.Cancel()` in `onNavigatingFrom`** — the only way to guard\n   against unsaved-changes navigation.\n6. **Don't forget `backStackFactory` in deep links.** Without it, GoBack\n   does nothing after a deep-linked entry.\n\n## Threading\n\n`UseNavigation` mutators are **thread-safe by default** (issue #234). The\nhandle captures the UI thread when it is created, so calling `Navigate`,\n`GoBack`, `GoForward`, `Replace`, `Reset`, `PopTo`, or `SetState` from a\n`Task.Run`, a timer, or after `await … ConfigureAwait(false)` auto-marshals\nthe operation back onto the captured dispatcher — no `threadSafe:` flag and\nno manual `DispatcherQueue.TryEnqueue` needed:\n\n```csharp\nawait Task.Run(async () => {\n    var itemId = await LoadItemIdAsync();\n    nav.Navigate(new Route.Details(itemId)); \u002F\u002F marshals onto the UI thread automatically\n});\n```\n\nThis mirrors the `UseState` \u002F `UseReducer` contract. Two caveats:\n\n- **No live dispatcher → loud throw.** Off-thread calls in a headless or\n  unit-test context (no `ReactorApp.UIDispatcher`), or after the dispatcher\n  has shut down, throw `InvalidOperationException` instead of silently\n  corrupting the back\u002Fforward stacks. On the UI thread the call runs inline.\n- **Off-thread `bool` means \"scheduled\", not \"navigated\".** When a mutator\n  marshals, its return value reports that the operation was *enqueued*, not\n  that the navigation ultimately succeeded. Don't branch on it from a\n  background thread.\n","# Navigation in Reactor\n\nReactor uses a **stack-based navigation model** with type-safe routes. You\ndefine routes as an enum, create a navigation handle with `UseNavigation`,\nand render the current page with `NavigationHost`. The system manages\nback\u002Fforward stacks, transitions, caching, and deep linking.\n\n## Quick reference\n\n| API | Purpose |\n|-----|---------|\n| `UseNavigation(Route.Home)` | Create a `NavigationHandle\u003CRoute>` (call once at root) |\n| `UseNavigation\u003CRoute>()` | Retrieve the nearest ancestor's handle (child components) |\n| `NavigationHost(nav, route => ...)` | Render the current page |\n| `NavigationView([items], content)` | Sidebar navigation with icons |\n| `TabView(Tab(...), Tab(...))` | Tab-based parallel navigation |\n| `UseNavigationLifecycle(...)` | Page appear\u002Fdisappear callbacks |\n| `UseSystemBackButton(nav, window)` | Wire system back button to nav stack |\n| `DeepLinkMap\u003CRoute>` | Map URI patterns to routes |\n\n## 1. Defining routes\n\nUse an enum. Each value is a distinct page:\n\n```csharp\nenum Route { Home, Settings, Profile, Details }\n```\n\nFor routes that carry data, use a discriminated-union pattern with records:\n\n```csharp\nabstract record Route\n{\n    public record Home : Route;\n    public record Settings : Route;\n    public record Details(int ItemId) : Route;\n}\n```\n\n## 2. Basic navigation\n\n```csharp\nclass App : Component\n{\n    public override Element Render()\n    {\n        var nav = UseNavigation(Route.Home);\n\n        return VStack(12,\n            HStack(8,\n                Button(\"Home\", () => nav.Navigate(Route.Home)),\n                Button(\"Settings\", () => nav.Navigate(Route.Settings)),\n                Button(\"Back\", () => nav.GoBack()).IsEnabled(nav.CanGoBack)\n            ),\n            NavigationHost(nav, route => route switch\n            {\n                Route.Home     => Component\u003CHomePage>(),\n                Route.Settings => Component\u003CSettingsPage>(),\n                _ => TextBlock(\"Not found\")\n            })\n        );\n    }\n}\n```\n\n**Key points:**\n- `UseNavigation(Route.Home)` — call once at the root with the initial route.\n- `nav.Navigate(route)` — pushes onto the back stack.\n- `nav.GoBack()` \u002F `nav.GoForward()` — stack navigation.\n- `NavigationHost(nav, route => ...)` — renders the matched element.\n\n## 3. Stack operations\n\n| Method | Effect |\n|--------|--------|\n| `Navigate(route)` | Push route onto back stack |\n| `GoBack()` | Pop current, return to previous |\n| `GoForward()` | Move forward (after going back) |\n| `Replace(route)` | Swap current route without touching the stack |\n| `Reset(route)` | Clear all stacks, start fresh |\n| `PopTo(predicate)` | Pop until a matching route is found |\n\nProperties: `CurrentRoute`, `CanGoBack`, `CanGoForward`, `BackStack`,\n`ForwardStack`, `Depth`.\n\nUse `Reset` for sign-out flows to prevent navigating back to authenticated\npages.\n\n## 4. NavigationView (sidebar)\n\n```csharp\nvar nav = UseNavigation(Route.Home);\n\nreturn NavigationView(\n    [\n        NavItem(\"Home\", icon: \"Home\", tag: \"Home\"),\n        NavItem(\"Settings\", icon: \"Setting\", tag: \"Settings\"),\n        NavItem(\"Profile\", icon: \"Contact\", tag: \"Profile\")\n    ],\n    content: NavigationHost(nav, route => route switch\n    {\n        Route.Home     => VStack(Heading(\"Home\"), TextBlock(\"Welcome.\")).Padding(24),\n        Route.Settings => VStack(Heading(\"Settings\"), TextBlock(\"Configure.\")).Padding(24),\n        Route.Profile  => VStack(Heading(\"Profile\"), TextBlock(\"Your info.\")).Padding(24),\n        _ => TextBlock(\"Not found\").Padding(24)\n    })\n);\n```\n\n`NavItem(label, icon?, tag?)` creates sidebar items. Icons are Segoe Fluent\nIcons names. The `NavigationView` handles selection state.\n\n**Manual wiring (without `UseNavigation`):**\n`SelectedTag` and `OnSelectionChanged` are record properties — use `with { }`.\nFor the settings item: set `IsSettingsVisible = true` and check `args.IsSettingsSelected` (not via tag).\nUse `.Set(nv => nv.PaneDisplayMode = ...)` for non-record properties.\n\n## 5. TabView (parallel tabs)\n\nUnlike stack navigation, tabs keep all content alive simultaneously:\n\n```csharp\nreturn TabView(\n    Tab(\"Documents\", VStack(12,\n        TextBlock(\"Your documents.\"),\n        Button(\"New\", () => { })).Padding(24)),\n    Tab(\"Recent\", TextBlock(\"Recently opened.\").Padding(24)),\n    Tab(\"Shared\", TextBlock(\"Shared files.\").Padding(24))\n);\n```\n\nUse tabs when users switch freely between parallel workspaces.\n\n## 6. Page lifecycle\n\n`UseNavigationLifecycle` fires callbacks when a page appears or disappears:\n\nCallbacks are scoped to the nearest enclosing `NavigationHost`. Each nested host\ndispatches lifecycle events and guards for its own navigation stack.\n\n```csharp\nUseNavigationLifecycle(\n    onNavigatedTo: ctx => LoadData(ctx.PreviousRoute),\n    onNavigatingFrom: ctx =>\n    {\n        if (hasUnsavedChanges) ctx.Cancel(); \u002F\u002F prevent navigation\n    },\n    onNavigatedFrom: ctx => SaveDraft()\n);\n```\n\n| Callback | When |\n|----------|------|\n| `onNavigatedTo` | After this page becomes active — fetch data, start timers |\n| `onNavigatingFrom` | Before leaving — call `ctx.Cancel()` to block navigation |\n| `onNavigatedFrom` | After leaving — save drafts, stop timers |\n\n## 7. Page transitions\n\nSet `Transition` on `NavigationHost`:\n\n```csharp\nNavigationHost(nav, route => ...) with\n{\n    Transition = NavigationTransition.DrillIn()\n}\n```\n\n| Transition | Effect |\n|-----------|--------|\n| `NavigationTransition.Entrance()` | Slide up + fade in — the default, and what WinUI's `Frame` plays with no transition info |\n| `NavigationTransition.Slide()` | Slide + fade — vertical unless you pass a direction |\n| `NavigationTransition.Fade()` | Crossfade |\n| `NavigationTransition.DrillIn()` | Scale + fade — use for list→detail |\n| `NavigationTransition.Spring()` | Spring-physics slide |\n| `NavigationTransition.None` | Instant swap |\n| `NavigationTransition.Connected(key)` | Native shared-element motion |\n\n`NavigationTransition.Default` is an alias for `Entrance()`. Use `Entrance()` when you\nmean the motion; use `Default` only when you mean \"whatever the framework default is\".\n\nGoBack automatically reverses direction. Transitions run on the compositor\nthread.\n\n### Shared elements with independent page motion\n\nMark the source and destination with the same `.ConnectedAnimation(key)` and\nselect that key for the navigation:\n\n```csharp\nnav.Navigate(Route.Details, new NavigateOptions\n{\n    ConnectedAnimationKey = \"device-card\",\n    Transition = NavigationTransition.DrillIn(),\n});\n```\n\nThe shared element and page transition run together. `Transition = null` uses\nthe host's default; `NavigationTransition.None` selects shared-element-only\nmotion. `NavigationTransition.Connected(key)` is a shorthand for that latter case.\nThe key and page transition travel together on back\u002Fforward navigation.\n\nUse a unique key within each active page subtree, including nested hosts. The\ndestination can appear after its first render or effect: navigation waits for\nits measured bounds before starting native motion. Missing, duplicate, or\nzero-sized destinations fall back to the selected page transition. Reduced\nmotion completes the navigation immediately. Both motions finish before the\nold page is cached or unmounted and lifecycle completion callbacks run.\nInterrupted navigation still delivers the outgoing page's `onNavigatedFrom`;\nthe current destination receives `onNavigatedTo` when its transition completes.\n\n## 8. Deep linking\n\n`DeepLinkMap` maps URI patterns to route constructors:\n\n```csharp\nvar map = UseMemo(() => new DeepLinkMap\u003CRoute>()\n    .Map(\"\u002F\", _ => Route.Home)\n    .Map(\"\u002Fsettings\", _ => Route.Settings)\n    .Map(\"\u002Fusers\u002F{id:int}\u002Fposts\u002F{postId:int}\", args =>\n    {\n        var userId = args.Get\u003Cint>(\"id\");\n        var postId = args.Get\u003Cint>(\"postId\");\n        return Route.Details;\n    }, backStackFactory: () => new[] { Route.Home }));\n\n\u002F\u002F Resolve from activation URI:\nmap.Resolve(uri);\n```\n\n**Pattern segments:**\n\n| Segment | Matches |\n|---------|---------|\n| `\u002Fliteral` | Exact match |\n| `\u002F{param}` | String capture |\n| `\u002F{param:int}` | Typed capture (int, long, bool, Guid) |\n| `\u002F{param?}` | Optional parameter |\n| `\u002F{**}` | Wildcard — remaining path |\n| `?key=value` | Query string parameters |\n\n`backStackFactory` builds a synthetic back stack so GoBack works after\ndeep-linked entry.\n\n## 9. Page caching\n\n```csharp\nNavigationHost(nav, route => ...) with\n{\n    CacheMode = NavigationCacheMode.Enabled,\n    CacheSize = 5\n}\n```\n\n| Cache mode | Behavior |\n|-----------|----------|\n| `Disabled` | Always unmount\u002Fremount (default) |\n| `Enabled` | LRU cache up to `CacheSize` entries |\n| `Required` | Always cached, never evicted |\n\nCaching preserves scroll position, text input, and component state.\n\n## 10. State serialization\n\n```csharp\nvar state = nav.GetState();         \u002F\u002F NavigationState\u003CTRoute> snapshot\nnav.SetState(state);                \u002F\u002F restore stacks + fire Navigated(Reset)\n```\n\nReactor returns a plain `NavigationState\u003CTRoute>` POCO and lets you pick the\nstorage format. For JSON persistence pair the snapshot with a\n`JsonSerializerContext` (AOT-safe):\n\n```csharp\n[JsonSerializable(typeof(NavigationState\u003CAppRoute>))]\npartial class AppJsonContext : JsonSerializerContext { }\n\nvar json = JsonSerializer.Serialize(nav.GetState(), AppJsonContext.Default.NavigationStateAppRoute);\n\u002F\u002F later…\nnav.SetState(JsonSerializer.Deserialize(json, AppJsonContext.Default.NavigationStateAppRoute)!);\n```\n\nUse for persisting navigation across app restarts.\n\n## 11. System back button\n\n```csharp\nUseSystemBackButton(nav, window);\n```\n\nWires the Windows title-bar back button and hardware back button to your\nnavigation stack automatically.\n\n## Critical gotchas\n\n1. **Call `UseNavigation(initial)` once at the root.** Children retrieve the\n   same handle via `UseNavigation\u003CRoute>()` (no initial value) through\n   context.\n2. **Use enums for routes.** Compile-time safety — can't navigate to a\n   non-existent route.\n3. **Use `Reset` for sign-out.** Clears the stack so users can't go back.\n4. **DrillIn for list→detail.** Signals hierarchy; pairs with connected\n   animation.\n5. **`ctx.Cancel()` in `onNavigatingFrom`** — the only way to guard\n   against unsaved-changes navigation.\n6. **Don't forget `backStackFactory` in deep links.** Without it, GoBack\n   does nothing after a deep-linked entry.\n\n## Threading\n\n`UseNavigation` mutators are **thread-safe by default** (issue #234). The\nhandle captures the UI thread when it is created, so calling `Navigate`,\n`GoBack`, `GoForward`, `Replace`, `Reset`, `PopTo`, or `SetState` from a\n`Task.Run`, a timer, or after `await … ConfigureAwait(false)` auto-marshals\nthe operation back onto the captured dispatcher — no `threadSafe:` flag and\nno manual `DispatcherQueue.TryEnqueue` needed:\n\n```csharp\nawait Task.Run(async () => {\n    var itemId = await LoadItemIdAsync();\n    nav.Navigate(new Route.Details(itemId)); \u002F\u002F marshals onto the UI thread automatically\n});\n```\n\nThis mirrors the `UseState` \u002F `UseReducer` contract. Two caveats:\n\n- **No live dispatcher → loud throw.** Off-thread calls in a headless or\n  unit-test context (no `ReactorApp.UIDispatcher`), or after the dispatcher\n  has shut down, throw `InvalidOperationException` instead of silently\n  corrupting the back\u002Fforward stacks. On the UI thread the call runs inline.\n- **Off-thread `bool` means \"scheduled\", not \"navigated\".** When a mutator\n  marshals, its return value reports that the operation was *enqueued*, not\n  that the navigation ultimately succeeded. Don't branch on it from a\n  background thread.\n",{"name":5,"description":7},"main","74791562c11792f7c0e2dd875f1e82b94d70b397","plugins\u002Freactor\u002Fskills\u002Freactor-navigation",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":53,"prompt":63,"zipAvailable":64},[54,57,60],{"tool":55,"command":56},"npx","npx skills add microsoft\u002Fmicrosoft-ui-reactor --skill reactor-navigation",{"tool":58,"command":59},"bunx","bunx skills add microsoft\u002Fmicrosoft-ui-reactor --skill reactor-navigation",{"tool":61,"command":62},"pnpm","pnpm dlx skills add microsoft\u002Fmicrosoft-ui-reactor --skill reactor-navigation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fplugins\u002Freactor\u002Fskills\u002Freactor-navigation\u002FSKILL.md",true,[],[67,73,100,125,149,167],{"skillNo":68,"name":69,"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":70,"categories":71,"keywords":72,"publishedAt":38},"01M69B94E15PYYWXAGFV832MRK","Charting","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fsrc\u002FReactor.Advanced\u002FCharting\u002Fskill.md",[],[69],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"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",[],[80,81,82,83,84,85,86,22,87,88,89,90,37,91,92,93,94,95,96,97,98,99],"reactor wrapping","declarative","with","hand","code","cheat","generator","auto","controls","custom","element","winui","ZeRO","panel","community","back","inference","diagnostics","toolkit","windows",{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":38},"01M69B90PW92BQ4YNZYTP4SERB","reactor-windowing","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.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmicrosoft-ui-reactor\u002Fblob\u002Fmain\u002Fplugins\u002Freactor\u002Fskills\u002Freactor-windowing\u002FSKILL.md",[],[107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,99,122,123,124],"reactor windowing","persistence","cookbook","integration","folder","command","command palette","top","progress","window","palette","file","restore","open","tool","remember","position","make",{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":131,"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",[],[132,133,118,82,134,135,33,136,137,138,139,140,141,142,143,144,145,146,147,148],"reactor recipes","recipes","recipe","form","adjust","single","pages","async","card","submit","loading","states","fetch","gating","single-file","ready","error",{"skillNo":150,"name":151,"nameZh":6,"description":152,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":153,"categories":154,"keywords":155,"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",[],[156,157,89,158,159,160,33,161,162,163,164,165,166,22],"input","reactor input","implementing","drag","gestures","events","direct","management","behavior","focus","drop",{"skillNo":168,"name":169,"nameZh":6,"description":170,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":171,"categories":172,"keywords":181,"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",[173,178],{"categoryNo":174,"categoryName":175,"taxonomyType":176,"taxonomyTypeDesc":177},"01JBSEEDCAT000000000000009","前端开发","SCENARIO","使用场景",{"categoryNo":179,"categoryName":180,"taxonomyType":176,"taxonomyTypeDesc":177},"01JBSEEDCAT000000000000015","视觉设计",[182,183,184,185,186,187,188,139,189,190,191,22,192,193,194,195,196,197,198,199],"getting started","reactor getting started","work","task","load","minimal","calls","mental model","for","you","critical","only","hooks","project","model","app","react","design"]