Add macOS Paper Storybook mode and PR coverage (#4355)

* initial package framing for native-core

* move callout and focus-zone into native-core package

* move existing implementations to legacy submodule

* Fix native-core macOS interoperability and validate migration

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix tsconfig configuration

* add the ability to run the macos storybook app in paper mode and add a pipeline run for it

* Constrain LayoutStableText labels to their reserved width

Fix the macOS Paper CI geometry failure without relaxing its native alignment assertions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Measure the native reserved Text instead of its wrapper View

Compare Text line boxes with the same Paper pixel-rounding policy, preserve the native assertions, and remove the ineffective max-width production change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Deduplicate compatible Storybook runtime dependencies

Align locked React, theming, and UI-common packages after the main-branch UI upgrades while preserving strict Metro duplicate checks and existing dependency ranges.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix moved rnx-kit dependency-management documentation links

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: JasonVMo

.changeset/macos-paper-storybook.md

@@ -0,0 +1,12 @@
+---
+'@fluentui-react-native/storybook-desktop': minor
+'@fluentui-react-native/components': patch
+---
+
+Add a macOS-only `--paper` option to prepare, build, launch, and smoke test Storybook with Paper while preserving Fabric as the default renderer.
+
+Use centered alignment in macOS Paper CompoundItemLayout stories to avoid the native Yoga baseline crash without changing the primitive or Fabric demonstrations.
+
+Measure LayoutStableText's hidden reserve Text directly in native alignment stories, avoiding Paper Text-versus-View pixel-rounding mismatches without relaxing the geometry assertions.
+
+Deduplicate compatible Storybook React, theming, and shared UI dependencies in the lockfile after desktop UI updates, keeping strict Metro duplicate checks enabled.

.github/workflows/pr.yml

@@ -244,6 +244,57 @@ jobs:
             apps/storybook/artifacts/storybook-commands
             ${{ steps.desktop-driver.outputs.doctor-path }}
 
+  macos-paper-storybook:
+    name: macOS Paper Storybook PR
+    runs-on: macos-26
+    timeout-minutes: 40
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up toolchain
+        uses: microsoft/react-native-test-app/.github/actions/setup-toolchain@c75754b0fedce160a4dcf7193fae1a6ece76efe2 # 5.4.11
+        with:
+          platform: macos
+          node-version: 22
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Build packages
+        run: yarn build
+
+      - name: Set up macOS Desktop Driver
+        id: desktop-driver
+        uses: ./.github/actions/setup-desktop-driver
+        with:
+          platform: macos
+          disabled-input-features: physicalClick
+
+      - name: Bundle macOS Paper
+        run: yarn storybook bundle --macos --paper
+        working-directory: apps/storybook
+
+      - name: Pod install (Paper)
+        run: yarn storybook prep --macos --paper
+        working-directory: apps/storybook
+
+      - name: Run through Paper storybook smoke tests
+        run: yarn storybook smoke --macos --paper --mode stories-and-tests
+        working-directory: apps/storybook
+        env:
+          CCACHE_DISABLE: 1
+
+      - name: Upload macOS Paper Storybook artifacts
+        if: ${{ always() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: Storybook_macos_Paper_Dump
+          path: |
+            apps/storybook/artifacts/macos
+            apps/storybook/artifacts/storybook-commands
+            ${{ steps.desktop-driver.outputs.doctor-path }}
+
   ios:
     name: iOS PR
     runs-on: macos-26

apps/fluent-tester/docs/android.md

@@ -44,7 +44,7 @@ yarn rnx-align-deps --set-version
 This command will ensure that all relevant packages are bumped correctly.
 
 You can read more about this tool here:
-[`@rnx-kit/align-deps` design document](https://github.com/microsoft/rnx-kit/blob/main/docsite/docs/architecture/dependency-management.md)
+[`@rnx-kit/align-deps` design document](https://github.com/microsoft/rnx-kit/blob/main/docsite/src/content/docs/docs/architecture/dependency-management.md)
 
 ## Debugging
 

apps/fluent-tester/docs/ios.md

@@ -42,7 +42,7 @@ yarn rnx-align-deps --set-version
 This command will ensure that all relevant packages are bumped correctly.
 
 You can read more about this tool here:
-[`@rnx-kit/align-deps` design document](https://github.com/microsoft/rnx-kit/blob/main/docsite/docs/architecture/dependency-management.md)
+[`@rnx-kit/align-deps` design document](https://github.com/microsoft/rnx-kit/blob/main/docsite/src/content/docs/docs/architecture/dependency-management.md)
 
 ## Debugging
 

apps/fluent-tester/docs/macos.md

@@ -51,7 +51,7 @@ yarn rnx-align-deps --set-version
 This command will ensure that all relevant packages are bumped correctly.
 
 You can read more about this tool here:
-[`@rnx-kit/align-deps` design document](https://github.com/microsoft/rnx-kit/blob/main/docsite/docs/architecture/dependency-management.md)
+[`@rnx-kit/align-deps` design document](https://github.com/microsoft/rnx-kit/blob/main/docsite/src/content/docs/docs/architecture/dependency-management.md)
 
 ## Troubleshooting
 

apps/fluent-tester/docs/windows.md

@@ -41,7 +41,7 @@ yarn rnx-align-deps --set-version
 This command will ensure that all relevant packages are bumped correctly.
 
 You can read more about this tool here:
-[`@rnx-kit/align-deps` design document](https://github.com/microsoft/rnx-kit/blob/main/docsite/docs/architecture/dependency-management.md)
+[`@rnx-kit/align-deps` design document](https://github.com/microsoft/rnx-kit/blob/main/docsite/src/content/docs/docs/architecture/dependency-management.md)
 
 ## Troubleshooting
 

apps/storybook/AGENTS.md

@@ -82,6 +82,8 @@ Read [`agent-map.yaml`](agent-map.yaml) first for the compact architecture, look
   repository root because subprocess dependency resolution must start in this workspace.
 - Run `yarn storybook bundle --macos` for the JavaScript bundle, `yarn storybook build --macos` for a non-launching
   native build, and `yarn storybook smoke --macos` for the complete owned lifecycle.
+- macOS defaults to Fabric. Add `--paper` to `prep`, `build`, `run`, or `smoke` for Paper; regenerate with `prep`
+  whenever switching renderers because both modes share the generated project and Pods. Keep the endpoint `macos`.
 - Preserve the shared smoke instance context: its canonical-root hash coordinates the macOS bundle identifier,
   Storybook port, Metro port, generated runtime polyfill, and exact app shutdown. Do not replace those values with
   process-name matching or fixed smoke ports.

apps/storybook/README.md

@@ -95,6 +95,29 @@ yarn storybook run --macos
 
 Requires Xcode + CocoaPods.
 
+Fabric is the default macOS renderer. Add `--paper` to use Paper with the same
+macOS story catalog and native Desktop Driver:
+
+```sh
+yarn storybook prep --macos --paper
+yarn storybook build --macos --paper
+yarn storybook smoke --macos --paper --mode stories-and-tests
+```
+
+For interactive development, use `yarn storybook driver --macos --paper` and
+`yarn storybook run --macos --paper` in separate terminals. `--paper` is supported
+only on macOS; it sets `RCT_NEW_ARCH_ENABLED=0` for child commands. Omitting it
+selects Fabric explicitly, even if the parent environment disables the New Architecture.
+Run `prep` again whenever switching renderers: the generated Xcode project and
+Pods are shared, so Paper and Fabric cannot run concurrently from one enlistment.
+To return to Fabric, run `yarn storybook prep --macos` before building or launching.
+The **macOS Paper Storybook PR** job runs the full catalog traversal and authored
+tests separately from the existing Fabric job.
+CompoundItemLayout's demos use centered alignment in macOS Paper because the
+current native text-baseline callback can return NaN and terminate Yoga
+([upstream issue](https://github.com/microsoft/react-native-macos/issues/3121)).
+Fabric and other platforms retain the baseline demonstration. The primitive itself is unchanged.
+
 Run `yarn storybook smoke --macos` for the complete server, Metro, build/launch, all-story traversal, and
 ownership-safe shutdown lifecycle. The shared CLI hashes this enlistment's canonical project root,
 uses that suffix in the native bundle identifier, and selects dedicated Storybook and Metro ports.
@@ -165,6 +188,11 @@ them. Win32 continues to exercise Callout through its Paper endpoint.
 Storybook's development bundle intentionally contains separate `pretty-format` and `react-is`
 versions used by its internal tooling. They are excluded from the duplicate-module enforcement;
 React, React Native, and application dependencies remain checked.
+After upgrading Storybook UI or addon packages, run
+`yarn dedupe '@storybook/*' storybook --strategy highest` from the repository
+root to align compatible locked React, theming, and shared UI dependencies.
+Keep these runtime packages covered by Metro's duplicate checks rather than
+adding exclusions for mismatched versions.
 
 ## Running on Win32
 

apps/storybook/agent-map.yaml

@@ -65,6 +65,11 @@ native:
     disabled_input_env: FURN_DESKTOP_DRIVER_DISABLED_INPUT_FEATURES
     ci_policy: explicit-build-then-prebuilt-only
   macos:
+    renderer:
+      default: fabric
+      paper_flag: --paper
+      switching: rerun-prep-before-build-or-launch
+      concurrency: one-renderer-per-enlistment
     process: ReactTestApp
     app_bundle: macos/DerivedData/Build/Products/Debug/ReactTestApp.app
     coordinate_notes:

apps/storybook/macos/Podfile

@@ -32,7 +32,7 @@ end
 # react-native-test-app runs codegen before autolinking, so seed its clean-install input first.
 write_storybook_autolinking_config!(File.expand_path('..', __dir__))
 
-use_test_app!(:fabric_enabled => true, :bridgeless_enabled => false) do |target|
+use_test_app!(:fabric_enabled => ENV.fetch('RCT_NEW_ARCH_ENABLED', '1') != '0', :bridgeless_enabled => false) do |target|
   target.app do
     platform :osx, '14'
   end