microsoft · Jason Morse (JasonVMo) · Aug 17, 2026 · Aug 17, 2026 · Aug 18, 2026 · Aug 18, 2026
diff --git a/.changeset/calm-zones-focus.md b/.changeset/calm-zones-focus.md
@@ -0,0 +1,5 @@
+---
+'@fluentui-react-native/focus-zone': patch
+---
+
+Convert FocusZone to an unstyled phased primitive and add package-owned macOS and Windows Fabric implementations alongside Paper.
diff --git a/.github/skills/agentic-storybook-development/SKILL.md b/.github/skills/agentic-storybook-development/SKILL.md
@@ -10,15 +10,20 @@ Work on the native Storybook application in `packages/agentic-components/storybo
 
 ## Workflow
 
-1. Read the repository `AGENTS.md`, then the
+1. Read the repository `AGENTS.md`, then the compact
+   [agent map](../../../packages/agentic-components/storybook/agent-map.yaml). Read the
    [Storybook instructions](../../../packages/agentic-components/storybook/AGENTS.md) and
-   [README](../../../packages/agentic-components/storybook/README.md).
+   [README](../../../packages/agentic-components/storybook/README.md) only as needed for the task.
 2. Inspect the Storybook `package.json` and run its declared workspace scripts; do not invent direct runner commands.
-3. Reproduce the first failure from the Storybook workspace so pnpm-linked React Native tooling resolves from the app.
+3. Use `storybook-agent` to query runtime story IDs, select stories, and sweep renderability. Reproduce the first
+   failure from the Storybook workspace so pnpm-linked React Native tooling resolves from the app.
 4. Treat native workspaces, Pods, lockfiles, generated solutions, build directories, and DerivedData as disposable
    outputs. Fix the owning manifest, Podfile, configuration, or script instead.
 5. After dependency or workaround changes, regenerate the affected native dependency source and use a clean build so
    stale output cannot produce a false success.
+   When adding a codegen-enabled workspace dependency to existing macOS Pods, the first pod install can generate its
+   spec without refreshing ReactCodegen's source list. If the clean build then reports a missing generated spec header,
+   run `pods:macos` once more before changing native configuration.
 6. Validate the JavaScript bundle and the affected native build. Run Storybook format/lint and the root build when
    manifests or shared package references changed.
 

diff --git a/packages/agentic-components/storybook/AGENTS.md b/packages/agentic-components/storybook/AGENTS.md
@@ -2,7 +2,19 @@
 
 These instructions apply to `packages/agentic-components/storybook` and its descendants.
 
-Read this file, `README.md`, and `package.json` before changing the Storybook application or its native projects.
+Read [`agent-map.yaml`](agent-map.yaml) first for the compact architecture, lookup, and interaction map. Read this file,
+`README.md`, and `package.json` before changing the Storybook application or its native projects.
+
+## Agent-efficient discovery and interaction
+
+- Query the live story index with `yarn storybook-agent stories <query>` instead of guessing IDs or searching the
+  sidebar.
+- Select stories with `yarn storybook-agent select <runtime-story-id>` and sweep renderability with
+  `yarn storybook-agent sweep [query]`.
+- Use screenshots only for visual evidence. Use WebSocket events and accessibility bounds for lookup and interaction.
+- Treat `src/storybook.requires.ts` as generated output; use `src/main.ts` for source configuration.
+- Keep `agent-map.yaml` synchronized when stable paths, scripts, services, or interaction contracts change. Do not list
+  individual stories there; the runtime index is authoritative.
 
 ## Command and dependency discipline
 

diff --git a/packages/agentic-components/storybook/README.md b/packages/agentic-components/storybook/README.md
@@ -3,7 +3,7 @@
 On-device [Storybook](https://storybook.js.org/) app (Storybook for React Native v10) for
 `@fluentui-react-native/components` and linked standalone native packages. It loads every
 `*.stories.(ts|tsx)` file from the agentic library source (`../src`) plus the standalone
-Callout package so its native stories run in the Fabric host.
+Callout and FocusZone packages so their native stories run in the Fabric host.
 
 It runs in Storybook **liteMode**, which mocks out the heavy default on-device UI
 (`@storybook/react-native-ui`). This avoids the `react-native-reanimated` /
@@ -16,6 +16,17 @@ unwrapped (`No theme`, the default) or apply the default light, dark, or high-co
 The selected Theme wraps the preview decorator, so it applies to every rendered story and remains
 selected while navigating between stories.
 
+For agent-driven work, [`agent-map.yaml`](agent-map.yaml) is the compact map of stable files,
+services, runtime events, lookup order, and native interaction rules. The checked-in
+`yarn storybook-agent` helper queries the live index rather than duplicating story IDs:
+
+```sh
+yarn storybook-agent status
+yarn storybook-agent stories FocusZone
+yarn storybook-agent select primitives-focuszone--circular-navigation
+yarn storybook-agent sweep FocusZone
+```
+
 ## Layout
 
 ```
@@ -92,6 +103,10 @@ Requires Visual Studio 2022 with the React Native Windows build prerequisites. T
 solution, `ExperimentalFeatures.props`, and build outputs are git-ignored and can be regenerated
 with `yarn windows:generate`.
 
+FocusZone is autolinked as a package-owned Windows Fabric native library. Its
+Windows component view handles directional navigation, single-stop Tab
+navigation, and focus restoration while the existing Win32 implementation
+remains platform-provided.
 The raw React Native Windows CLI path remains available as `yarn windows:cli`, but the declared
 `windows` workflow avoids two failure modes in this app: CLI deployment can stall while enabling
 Developer Mode, and starting Metro before the native build can make its watcher observe generated

diff --git a/packages/agentic-components/storybook/agent-map.yaml b/packages/agentic-components/storybook/agent-map.yaml
@@ -0,0 +1,87 @@
+version: 1
+purpose: Agent-optimized map of stable Storybook structure and runtime discovery paths.
+
+sources:
+  config: src/main.ts
+  app_entry: index.js
+  app_shell: src/StorybookApp.tsx
+  theme_host: src/StorybookTheme.tsx
+  channel_server: storybook-server.cjs
+  generated_requires:
+    path: src/storybook.requires.ts
+    policy: generated-do-not-edit
+  story_globs:
+    - ../../src/**/*.stories.?(ts|tsx)
+    - ../../../components/Callout/src/**/*.stories.?(ts|tsx)
+    - ../../../components/FocusZone/src/**/*.stories.?(ts|tsx)
+
+services:
+  metro:
+    script: start
+    health_url: http://127.0.0.1:8081/status
+  channel:
+    script: storybook-server
+    websocket_url: ws://127.0.0.1:7007/
+    mcp_url: http://127.0.0.1:7007/mcp
+
+runtime_protocol:
+  index:
+    request:
+      type: RN_GET_INDEX
+      args: []
+    response: RN_GET_INDEX_RESPONSE
+  select:
+    request:
+      type: setCurrentStory
+      args:
+        - storyId: <runtime-story-id>
+    success: storyFinished
+    failures:
+      - storyErrored
+      - storyMissing
+      - storyThrewException
+
+agent_commands:
+  status: yarn storybook-agent status
+  find_stories: yarn storybook-agent stories <query>
+  select_story: yarn storybook-agent select <runtime-story-id>
+  sweep_stories: yarn storybook-agent sweep [query]
+
+lookup_order:
+  - Use "storybook-agent stories <query>" for runtime IDs; never guess ID slugging.
+  - Read this map for stable paths, services, and commands.
+  - Read src/main.ts for story-source changes.
+  - Read a matched story file for component-specific behavior.
+  - Read generated requires only to diagnose generation output.
+
+interaction_order:
+  - Use the WebSocket helper for listing, selecting, and sweeping stories.
+  - Use accessibility elements for native focus and control state.
+  - Use HID mouse or keyboard events when accessibility actions do not invoke React Native handlers.
+  - Use screenshots for visual evidence, not element lookup.
+
+native:
+  macos:
+    process: ReactTestApp
+    app_bundle: macos/DerivedData/Build/Products/Debug/ReactTestApp.app
+    coordinate_notes:
+      accessibility: logical-points
+      screenshots: backing-pixels
+      rule: Query element bounds and display scale; do not copy screenshot coordinates.
+  windows:
+    project_policy: generated
+    generation_script: windows:generate
+
+validation:
+  javascript:
+    - format
+    - lint
+    - bundle:macos
+  native:
+    normal: macos:build
+    after_native_or_pod_change: macos:build:clean
+
+output_hygiene:
+  - Use the helper's filtered and summary output instead of logging raw channel events.
+  - Search large native build logs for errors and final status instead of reading them in full.
+  - Keep warning suppression exact; console diagnostics remain available even when LogBox hides a warning.
diff --git a/packages/agentic-components/storybook/index.js b/packages/agentic-components/storybook/index.js
@@ -1,5 +1,12 @@
-import { AppRegistry } from 'react-native';
+import { AppRegistry, LogBox } from 'react-native';
 import StorybookApp from './src/StorybookApp';
 import { name as appName } from './app.json';
 
+LogBox.ignoreLogs([
+  // The supported React Native peer floor predates the public root codegen exports.
+  /^Deep imports from the 'react-native' package are deprecated \('react-native\/Libraries\/Utilities\/codegenNative(?:Commands|Component)'\)\./,
+  // Storybook's sidebar expands its LegendList pool on demand without affecting rendering.
+  '[legend-list] No unused container available, so creating one on demand.',
+]);
+
 AppRegistry.registerComponent(appName, () => StorybookApp);
diff --git a/packages/agentic-components/storybook/package.json b/packages/agentic-components/storybook/package.json
@@ -17,7 +17,8 @@
     "macos:build": "xcodebuild -workspace macos/AgenticStorybook.xcworkspace -scheme AgenticStorybook -configuration Debug -destination 'platform=macOS' -derivedDataPath macos/DerivedData CODE_SIGNING_ALLOWED=NO build",
     "macos:build:clean": "xcodebuild -workspace macos/AgenticStorybook.xcworkspace -scheme AgenticStorybook -configuration Debug -destination 'platform=macOS' -derivedDataPath macos/DerivedData CODE_SIGNING_ALLOWED=NO clean build",
     "macos": "rnx-cli run --platform macos",
-    "windows": "pwsh -NoProfile -File scripts/start-windows-agent-session.ps1",
+    "storybook-agent": "node scripts/storybook-agent.cjs",
+    "windows": "react-native run-windows --arch x64 --sln windows/AgenticStorybook.sln",
     "windows:cli": "react-native run-windows --arch x64 --sln windows/AgenticStorybook.sln",
     "windows:info": "react-native run-windows --info --no-telemetry",
     "windows:build": "react-native run-windows --arch x64 --sln windows/AgenticStorybook.sln --no-packager --no-deploy --no-launch --logging --no-telemetry --buildLogDirectory artifacts/windows/build-logs",

diff --git a/packages/agentic-components/storybook/scripts/smoke-stories.json b/packages/agentic-components/storybook/scripts/smoke-stories.json
@@ -14,5 +14,10 @@
     "testId": "agentic-storybook-callout-trigger",
     "statusTestId": "agentic-storybook-callout-status",
     "artifactName": "callout-default"
+  },
+  {
+    "storyId": "primitives-focuszone--two-dimensional-navigation",
+    "testId": "focus-zone-item-1",
+    "artifactName": "focus-zone-two-dimensional-navigation"
   }
 ]