react-native-impeller-platform 0.0.0-stage → 0.3.1

package/src/metro-shims/index.js

@@ -0,0 +1,382 @@
+'use strict';
+// Metro integration for the `impeller` platform.
+//
+// PLAN D5/D6: `withImpeller()` WRAPS the consumer's metro config -- it chains an
+// existing `resolveRequest` instead of replacing it, and it appends to
+// `resolver.platforms` instead of overwriting. A metro plugin that clobbers those
+// silently breaks every other RN plugin the app uses.
+//
+// Shims are resolved from `__dirname`, so linked / installed / tarball layouts all
+// work identically. Never CWD-relative.
+//
+// WHY REDIRECT BY RESOLVED PATH, NOT BY MODULE NAME
+// -------------------------------------------------
+// React Native imports its own internals RELATIVELY: `Libraries/Utilities/Platform`
+// is reached as `require('./Platform')` from inside react-native, so a resolver
+// keyed on the string 'react-native/Libraries/Utilities/Platform' NEVER fires. The
+// P1 consumer gate caught exactly that: the bundle built fine and contained no shim.
+// So: let the upstream resolver do its job, then inspect the file it landed on and
+// swap it. The `SHIM_TARGETS` suffixes below are matched against that resolved path.
+
+const fs = require('fs');
+const path = require('path');
+
+const SHIM_DIR = path.join(__dirname, 'shims');
+
+// resolved-path suffix (posix) -> shim file in SHIM_DIR
+const SHIM_TARGETS = {
+  'react-native/Libraries/Utilities/Platform.js': 'Platform.impeller.js',
+  // P4. Alert.js is NOT a stub and resolves perfectly — it simply branches
+  // itself out of existence: `if (ios) {...} else if (android) {...}` with no
+  // else. On `impeller` the call never leaves JavaScript, so a flawless native
+  // AlertManager is unreachable and nothing anywhere reports a problem. See
+  // shims/Alert.impeller.js for the full note; this is a distinct failure from
+  // the self-resolving RCTAlertManager.js stub below, and BOTH had to be fixed.
+  'react-native/Libraries/Alert/Alert.js': 'Alert.impeller.js',
+  // desktop-input-gap P0 item 1. Bare BaseViewConfig.js is ALSO covered by
+  // the PLATFORM_FORKED ios-stub redirect below (it is a genuine ios-stub-
+  // disease file, unrelated to this entry), but SHIM_TARGETS is consulted
+  // FIRST in shimForResolvedPath -- see below -- so this entry wins and the
+  // PLATFORM_FORKED one is inert for this specifier. Kept that way
+  // deliberately (not removed from PLATFORM_FORKED) so it stays the ios-stub-
+  // disease REFERENCE case the P2 gate's mutation suite targets, and this
+  // shim is additive on top of it (see shims/BaseViewConfig.impeller.js for
+  // why): the ios-stub-disease fix is still exactly what runs underneath.
+  'react-native/Libraries/NativeComponent/BaseViewConfig.js':
+    'BaseViewConfig.impeller.js',
+  // desktop-input-gap item 6. RN core's ConditionallyIgnoredEventHandlers
+  // strips onClick/onPointerDown/onPointerUp/... from validAttributes unless
+  // Platform.OS === 'ios' -- see shims/ViewConfigIgnore.impeller.js for the
+  // full "native fires, JS never hears" story.
+  'react-native/Libraries/NativeComponent/ViewConfigIgnore.js':
+    'ViewConfigIgnore.impeller.js',
+  // parity item 7. TextInputState.js sends focus/blur commands only on ios/
+  // android, behind a Platform.OS check Metro inlines to 'impeller' at build
+  // time, so ref.focus()/ref.blur() never reached native. See the shim.
+  'react-native/Libraries/Components/TextInput/TextInputState.js':
+    'TextInputState.impeller.js',
+  // parity item 12. Image.js self re-exports to undefined on impeller; in a
+  // __DEV__ bundle that crashed LogBox on its first warning. SC-30: the shim
+  // now mounts the real RCTImageView host component. See the shim.
+  'react-native/Libraries/Image/Image.js': 'Image.impeller.js',
+  // SC-18. Adds a fontFamily processor (array -> CSS stack); see the shim.
+  'react-native/Libraries/Components/View/ReactNativeStyleAttributes.js':
+    'ReactNativeStyleAttributes.impeller.js',
+  // SC-24. Button branches on Platform.OS ios/android, both false here.
+  'react-native/Libraries/Components/Button.js': 'Button.impeller.js',
+};
+
+// ---------------------------------------------------------------------------
+// PLATFORM-FORKED RN FILES ("ios-stub disease")
+//
+// Some react-native modules exist ONLY as `.ios.js` / `.android.js`, with a
+// bare `Foo.js` whose entire body is `import Foo from './Foo'; export default
+// Foo;` — a re-export that relies on the platform extension resolving to a
+// sibling. On a custom platform there is no sibling, so `./Foo` resolves to the
+// file ITSELF, the circular import yields `undefined`, and the export is
+// silently undefined.
+//
+// The failure surfaces far away and blames the renderer. Measured here:
+// BaseViewConfig.js self-resolved, so `PlatformBaseViewConfig` was undefined and
+// ViewConfig.js died with `Cannot read property 'bubblingEventTypes' of
+// undefined` while mounting the first <View> — which reads like a broken Fabric
+// component registration and is nothing of the sort.
+//
+// Fix: redirect the bare file to the iOS flavour, which is the desktop-shaped
+// one (the Android variants reach for JNI-backed view managers). This REDIRECTS
+// TO RN'S OWN FILE rather than vendoring a copy, so an RN bump carries its own
+// content and cannot go stale.
+const PLATFORM_FORKED = {
+  'react-native/Libraries/NativeComponent/BaseViewConfig.js': 'BaseViewConfig.ios.js',
+  // P4. `Libraries/Alert/RCTAlertManager.js` is a textbook instance: its entire
+  // body is `export * from './RCTAlertManager'`, which on a platform with no
+  // sibling extension resolves to ITSELF. `alertWithArgs` is then undefined and
+  // `Alert.alert()` dies with "alertWithArgs is not a function" — pointing at
+  // our AlertManager TurboModule, which is fine.
+  //
+  // Note the shape of the trap: the NATIVE module can be perfect and the
+  // feature still 100% broken, because the JS never reaches it. That is why
+  // the P4 gate asserts a native-side side-effect counter (alerts_shown) and
+  // not just "the module is in the manifest".
+  'react-native/Libraries/Alert/RCTAlertManager.js': 'RCTAlertManager.ios.js',
+  // Same disease, same fix. Reached by fetch/XMLHttpRequest.
+  'react-native/Libraries/Network/RCTNetworking.js': 'RCTNetworking.ios.js',
+};
+
+// ---------------------------------------------------------------------------
+// ENG-01a. FILES THAT BRANCH THEMSELVES OUT OF EXISTENCE ON A CUSTOM PLATFORM
+//
+// A third failure shape, distinct from both lists above. The file resolves
+// perfectly, imports perfectly, and RUNS -- and then does nothing, because its
+// entire body is `if (ios) {...} else if (android) {...}` with no else. Nothing
+// throws and nothing logs. Alert.js was the first (fixed by vendoring a shim);
+// TextInput.js is the second and CANNOT be vendored, because it is ~1000 lines
+// of stateful RN internals we would then own forever across RN bumps.
+//
+// So instead of replacing the file, we change the ANSWER IT GETS. When
+// TextInput.js asks `Platform.OS`, and only when TextInput.js asks, it is told
+// 'ios' -- the desktop-shaped arm, same rule as PLATFORM_FORKED above. Every
+// other importer of Platform still gets 'impeller'.
+//
+// ⚠️ MATCHED ON THE *IMPORTER*, NOT ON THE RESOLVED FILE.
+// The other two tables inspect what a request resolved TO. This one inspects
+// who ASKED. Metro gives us that as `context.originModulePath`. Keying this on
+// the resolved path instead would swap Platform for the entire bundle, which
+// is the global lie this design exists to avoid.
+const IOS_BRANCHED_IMPORTERS = {
+  'react-native/Libraries/Components/TextInput/TextInput.js':
+    'Platform.impeller-as-ios.js',
+};
+
+// ---------------------------------------------------------------------------
+// ENG-01c. MATCH ON THE ORIGIN *FOLDER*, NOT JUST THE FILE.
+//
+// The file table above is a lie in the presence of Metro's resolution cache.
+// metro/src/node-haste/DependencyGraph.js resolveDependency() keys the cache on
+// `(resolverOptions, originKey, targetKey, platform)` where, for a specifier
+// that contains "/" (ours is `../../Utilities/Platform`), originKey is
+// `path.dirname(originModulePath)` -- the origin FOLDER, not the file. It also
+// splits targetKey by import kind (`\0esm` vs `\0cjs`). resolveRequest runs
+// ONLY on a cache miss.
+//
+// Components/TextInput/ has three siblings importing ../../Utilities/Platform:
+//   TextInput.js          (ESM import) -- must get as-ios or it mounts null
+//   InputAccessoryView.js (ESM import) -- shares TextInput.js's exact cache key
+//   TextInputState.js     (CJS require) -- its own cache bucket
+// Because TextInput.js and InputAccessoryView.js share one ESM cache entry for
+// the whole folder, whichever resolves first fills it for both. When
+// InputAccessoryView wins, TextInput.js is handed the cached plain-impeller
+// Platform without resolveRequest ever running for it, branches itself out of
+// existence, and mounts no native field. Build order decides the winner, which
+// is why it flaked ~15% here and 6/6 in the HostApp app.
+//
+// FIX: key the origin rule on the FOLDER. Every importer in
+// Components/TextInput/ gets as-ios. This is forced, not chosen -- the shared
+// ESM cache key means TextInput.js and InputAccessoryView.js CANNOT be given
+// different answers. It is also correct:
+//   - TextInputState.js only reads OS to pick focus/blur commands, and the
+//     iOS commands are exactly what the native field TextInput.js now mounts
+//     expects (previously, with plain impeller, focus/blur silently no-op'd).
+//   - InputAccessoryView.js is iOS-only API. as-ios makes it try to mount
+//     RCTInputAccessoryViewNativeComponent, which is NOT registered in
+//     FabricHost -- but that path only runs if an app actually mounts
+//     <InputAccessoryView>, the pre-fix code already leaked as-ios to it ~50%
+//     of the time with no reported breakage, and registering that component is
+//     a separate future ticket, not a regression introduced here.
+const IOS_BRANCHED_ORIGIN_DIRS = {
+  'react-native/Libraries/Components/TextInput': 'Platform.impeller-as-ios.js',
+};
+
+// The module specifier TextInput.js actually writes is RELATIVE
+// (`import Platform from '../../Utilities/Platform'`), so this is checked
+// against the RESOLVED Platform path, gated by the origin file.
+const PLATFORM_MODULE_SUFFIX =
+  'react-native/Libraries/Utilities/Platform.js';
+
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+function shimForOrigin(originModulePath, resolvedFilePath) {
+  if (!originModulePath || !resolvedFilePath) return null;
+  if (!toPosix(resolvedFilePath).endsWith(PLATFORM_MODULE_SUFFIX)) return null;
+  const origin = toPosix(originModulePath);
+  for (const [suffix, shim] of Object.entries(IOS_BRANCHED_IMPORTERS)) {
+    if (origin.endsWith(suffix)) return path.join(SHIM_DIR, shim);
+  }
+  // ENG-01c: folder-scoped fallback. Metro's resolution cache is keyed on the
+  // origin FOLDER, so a file-only rule loses the race for siblings that share
+  // the cache entry. Match the containing directory of the importer.
+  const originDir = toPosix(path.dirname(originModulePath));
+  for (const [dirSuffix, shim] of Object.entries(IOS_BRANCHED_ORIGIN_DIRS)) {
+    if (originDir.endsWith(dirSuffix)) return path.join(SHIM_DIR, shim);
+  }
+  return null;
+}
+
+function shimForResolvedPath(filePath) {
+  if (!filePath) return null;
+  const posix = toPosix(filePath);
+  for (const [suffix, shim] of Object.entries(SHIM_TARGETS)) {
+    if (posix.endsWith(suffix)) return path.join(SHIM_DIR, shim);
+  }
+  for (const [suffix, sibling] of Object.entries(PLATFORM_FORKED)) {
+    if (posix.endsWith(suffix)) {
+      return path.join(path.dirname(filePath), sibling);
+    }
+  }
+  return null;
+}
+
+// parity item 20. Self re-export files redirected to their .ios.js sibling
+// (see resolveRequest). Only files measured to break are listed; the others
+// under Libraries/ are either already shimmed or render fine.
+const SELF_REEXPORTS = [
+  'react-native/Libraries/StyleSheet/PlatformColorValueTypes.js',
+  'react-native/Libraries/Utilities/BackHandler.js',
+  'react-native/Libraries/Components/AccessibilityInfo/legacySendAccessibilityEvent.js',
+];
+
+function selfReexportSibling(filePath) {
+  const posix = toPosix(filePath);
+  if (!SELF_REEXPORTS.some((rel) => posix.endsWith(rel))) return null;
+  const ios = filePath.replace(/\.js$/, '.ios.js');
+  return fs.existsSync(ios) ? ios : null;
+}
+
+// parity item 20. See shims/ReactNativeFeatureFlags.impeller.js.
+const FEATURE_FLAGS_SUFFIX =
+  'react-native/src/private/featureflags/ReactNativeFeatureFlags.js';
+const FEATURE_FLAGS_SHIM = 'ReactNativeFeatureFlags.impeller.js';
+
+// ENG-19. See resolveRequest and shims/reanimated.impeller.js.
+const REANIMATED = 'react-native-reanimated';
+const REANIMATED_SHIM = 'reanimated.impeller.js';
+
+// EXPO. `expo start` (@expo/cli withMetroMultiPlatform) asks
+// expo-modules-autolinking which package hosts react-native for the requested
+// platform, on EVERY resolve, and that is a closed switch (ios/android ->
+// react-native, tvos, macos, windows). For 'impeller' it THROWS "No support
+// package is known for platform". The retry-as-ios below then caught that
+// throw for every module, so `expo start` silently served an iOS bundle
+// (Settings.ios.js, Platform.ios.js, Image.ios.js...) and the first ios-only
+// TurboModule (SettingsManager) killed the dev boot. `react-native bundle`
+// never calls it, which is why the same config bundled fine there.
+//
+// The impeller platform's host package IS react-native (this package renders
+// stock react-native), so answer that, in the module @expo/cli reads, before
+// it reads it. A project without expo is left alone.
+function teachExpoImpellerPlatform(projectRoot) {
+  let platforms;
+  try {
+    const expoDir = path.dirname(require.resolve('expo/package.json', {paths: [projectRoot]}));
+    const exportsFile = require.resolve('expo-modules-autolinking/exports', {
+      paths: [path.join(expoDir, 'internal'), expoDir],
+    });
+    // The package's exports map points "./exports" at build/exports.js; older
+    // layouts had a root exports.js re-exporting ./build/exports.
+    const dir = path.dirname(exportsFile);
+    const candidates = [
+      path.join(dir, 'platforms', 'index.js'),
+      path.join(dir, 'build', 'platforms', 'index.js'),
+    ];
+    const found = candidates.find((c) => fs.existsSync(c));
+    if (!found) return 'unknown-shape';
+    platforms = require(found);
+  } catch (error) {
+    return 'no-expo';
+  }
+  if (typeof platforms.getSupportPackageForPlatform !== 'function') return 'unknown-shape';
+  if (platforms.getSupportPackageForPlatform.__rniImpeller) return 'patched';
+  const original = platforms.getSupportPackageForPlatform;
+  const patched = function getSupportPackageForPlatform(platform) {
+    return platform === 'impeller' ? 'react-native' : original.apply(this, arguments);
+  };
+  patched.__rniImpeller = true;
+  platforms.getSupportPackageForPlatform = patched;
+  return 'patched';
+}
+
+function withImpeller(config = {}) {
+  teachExpoImpellerPlatform(config.projectRoot || process.cwd());
+  const resolver = config.resolver || {};
+  const existingPlatforms = resolver.platforms || ['ios', 'android', 'native'];
+  const platforms = existingPlatforms.includes('impeller')
+    ? existingPlatforms
+    : [...existingPlatforms, 'impeller'];
+
+  const priorResolveRequest = resolver.resolveRequest;
+
+  function baseResolve(context, moduleName, platform) {
+    return priorResolveRequest
+      ? priorResolveRequest(context, moduleName, platform)
+      : context.resolveRequest(context, moduleName, platform);
+  }
+
+  function resolveRequest(context, moduleName, platform) {
+    // ENG-19. react-native-reanimated: the engine vends no Reanimated/Worklets
+    // native module, and an app that does not install the package cannot even
+    // bundle (react-native-css requires it from native/reanimated.js). When
+    // the app has NOT installed it, resolve to the package's inert stub
+    // (shims/reanimated.impeller.js). An app that installs the real package
+    // keeps it: that is a deliberate choice, and hiding it would be a lie.
+    if (platform === 'impeller' && moduleName === REANIMATED) {
+      try {
+        return baseResolve(context, moduleName, platform);
+      } catch (error) {
+        return {type: 'sourceFile', filePath: path.join(SHIM_DIR, REANIMATED_SHIM)};
+      }
+    }
+    let resolution;
+    try {
+      resolution = baseResolve(context, moduleName, platform);
+    } catch (error) {
+      // parity item 20. RN ships some modules ONLY as .ios.js + .android.js
+      // with no platform-neutral file, so resolving them for 'impeller'
+      // THROWS. ReactDevToolsSettingsManager (reached from setUpReactDevTools
+      // in every __DEV__ bundle) is one: no dev bundle could even be built.
+      // Retry as ios, and ONLY on a throw: a module that resolves to an ios
+      // stub exporting undefined is a different defect, and a blanket
+      // redirect would hide it. (Moved here from HostApp's metro.config.js.)
+      if (platform !== 'impeller') throw error;
+      // ⛔ NEVER retry a resolver that rejected the PLATFORM itself: that
+      // turns every module of the bundle into its iOS variant without a
+      // word (see teachExpoImpellerPlatform). Fail loudly instead.
+      if (/platform "impeller"/.test(String(error && error.message))) {
+        throw new Error(
+          'react-native-impeller-platform: the bundler rejected platform "impeller" (' +
+            String(error.message).split('\n')[0] +
+            '). Refusing to fall back to ios for every module.',
+        );
+      }
+      resolution = baseResolve(context, moduleName, 'ios');
+    }
+
+    if (platform !== 'impeller' || !resolution || resolution.type !== 'sourceFile') {
+      return resolution;
+    }
+    // parity item 20. Self re-export files: RN ships a few `Foo.js` whose body
+    // is `import Foo from './Foo'; export default Foo;`, meant to resolve
+    // through a .ios.js/.android.js sibling. On impeller there is no sibling,
+    // the import resolves back to ITSELF, and the default export is
+    // undefined. Measured in HostApp (Gluestack Popover): BackHandler ("Cannot
+    // read property 'addEventListener' of undefined") and
+    // legacySendAccessibilityEvent ("0,s.default is not a function").
+    const selfReexport = selfReexportSibling(resolution.filePath);
+    if (selfReexport) return {type: 'sourceFile', filePath: selfReexport};
+    // parity item 20. Feature-flags redirect (see the shim), except for the
+    // shim's own require of the real module.
+    const origin = toPosix(context.originModulePath || '');
+    if (
+      toPosix(resolution.filePath).endsWith(FEATURE_FLAGS_SUFFIX) &&
+      !origin.endsWith('/' + FEATURE_FLAGS_SHIM)
+    ) {
+      return {type: 'sourceFile', filePath: path.join(SHIM_DIR, FEATURE_FLAGS_SHIM)};
+    }
+    // Origin-scoped first: it is the narrower rule, and the only one that can
+    // return a DIFFERENT Platform than the global shim.
+    const originShim = shimForOrigin(context.originModulePath, resolution.filePath);
+    if (originShim) return {type: 'sourceFile', filePath: originShim};
+    const shim = shimForResolvedPath(resolution.filePath);
+    // A shim that wraps the real module requires it by path; do not loop it back.
+    if (shim && origin === toPosix(shim)) return resolution;
+    return shim ? {type: 'sourceFile', filePath: shim} : resolution;
+  }
+
+  return {
+    ...config,
+    resolver: {...resolver, platforms, resolveRequest},
+  };
+}
+
+module.exports = {
+  withImpeller,
+  teachExpoImpellerPlatform,
+  shimForResolvedPath,
+  shimForOrigin,
+  SHIM_TARGETS,
+  PLATFORM_FORKED,
+  IOS_BRANCHED_IMPORTERS,
+  IOS_BRANCHED_ORIGIN_DIRS,
+  SHIM_DIR,
+};

package/src/metro-shims/shims/Alert.impeller.js

@@ -0,0 +1,89 @@
+'use strict';
+// Alert shim for the `impeller` platform.
+//
+// ⛔ WHY THIS FILE EXISTS: RN's `Libraries/Alert/Alert.js` BRANCHES ITSELF OUT
+// OF EXISTENCE on any platform that is not ios or android.
+//
+//     static alert(...) {
+//       if (Platform.OS === 'ios') { ...prompt... }
+//       else if (Platform.OS === 'android') { ...DialogManager... }
+//     }                                   // <-- no else. Silent no-op.
+//
+// There is no error, no warning, and no dead import to grep for. The
+// AlertManager TurboModule can be perfect, registered, cached, and reachable
+// from JS — and `Alert.alert()` still does absolutely nothing, because the
+// call never leaves JavaScript.
+//
+// This is a DIFFERENT disease from the self-resolving `RCTAlertManager.js`
+// re-export stub (handled by the PLATFORM_FORKED redirect in ../index.js).
+// Both had to be fixed for Alert to work, and each one alone leaves the
+// feature 100% broken with a completely healthy-looking app. It is also why
+// the P4 gate asserts a NATIVE-side counter (`alerts_shown`) as well as a
+// pixel: the pixel proves JS got its callback, the counter proves the call
+// actually crossed the seam. A JS-side stub could satisfy either alone.
+//
+// We do NOT vendor a copy of Alert.js. This delegates to RN's own
+// `RCTAlertManager` (which our resolver points at the .ios flavour), so RN
+// keeps ownership of the payload shape and an RN bump carries its own changes.
+
+const {alertWithArgs} = require('react-native/Libraries/Alert/RCTAlertManager');
+
+class Alert {
+  static alert(title, message, buttons, options) {
+    Alert.prompt(title, message, buttons, 'default', undefined, undefined, options);
+  }
+
+  static prompt(title, message, callbackOrButtons, type, defaultValue, keyboardType, options) {
+    // Same normalisation RN's ios branch does. Kept here rather than
+    // reimplemented differently, so button indices line up with the callback
+    // ids the native side sends back.
+    let callbacks = [];
+    const buttonSpecs = [];
+    let cancelButtonKey;
+    let destructiveButtonKey;
+    let preferredButtonKey;
+
+    if (typeof callbackOrButtons === 'function') {
+      callbacks = [callbackOrButtons];
+    } else if (Array.isArray(callbackOrButtons)) {
+      callbackOrButtons.forEach((btn, index) => {
+        callbacks[index] = btn.onPress;
+        if (btn.style === 'cancel') {
+          cancelButtonKey = String(index);
+        } else if (btn.style === 'destructive') {
+          destructiveButtonKey = String(index);
+        }
+        if (btn.isPreferred) {
+          preferredButtonKey = String(index);
+        }
+        if (btn.text || index < (callbackOrButtons || []).length - 1) {
+          const btnDef = {};
+          btnDef[index] = btn.text || '';
+          buttonSpecs.push(btnDef);
+        }
+      });
+    }
+
+    alertWithArgs(
+      {
+        title: title || '',
+        message: message || undefined,
+        buttons: buttonSpecs,
+        type: type || undefined,
+        defaultValue,
+        cancelButtonKey,
+        destructiveButtonKey,
+        preferredButtonKey,
+        keyboardType,
+        userInterfaceStyle: (options && options.userInterfaceStyle) || undefined,
+      },
+      (id, value) => {
+        const cb = callbacks[id];
+        cb && cb(value);
+      },
+    );
+  }
+}
+
+module.exports = Alert;
+module.exports.default = Alert;

package/src/metro-shims/shims/BaseViewConfig.impeller.js

@@ -0,0 +1,81 @@
+'use strict';
+// desktop-input-gap P0 item 1. onKeyDown/onKeyUp view-config extension for
+// the `impeller` platform.
+//
+// WHY THIS EXISTS: BaseViewConfig.ios.js (what the PLATFORM_FORKED redirect
+// in ../index.js used to point bare BaseViewConfig.js at, before this file
+// existed) declares NEITHER bubblingEventTypes.topKeyDown/topKeyUp NOR
+// validAttributes.onKeyDown/onKeyUp -- RN 0.86's C++ BaseViewEventEmitter has
+// no onKeyDown/onKeyUp method at all (see docs/eng/desktop-input-gap.md), and
+// the JS-side view config for a plain <View> never declared the matching
+// bubbling registration either. So even though FabricHost.cpp's
+// dispatchKeyEvent dispatches a generic 'keyDown'/'keyUp' RawEvent (which
+// EventEmitter::normalizeEventType turns into exactly 'topKeyDown'/
+// 'topKeyUp'), nothing in the view config told Fabric's event system that
+// name maps to an onKeyDown/onKeyUp prop -- the native side would be fully
+// wired and JS would never hear it. Same "native perfect, JS never told"
+// shape Alert.js's self-branching produced (see Alert.impeller.js), one
+// layer further down the stack.
+//
+// We do NOT vendor a copy of BaseViewConfig.ios.js: this delegates to RN's
+// own file (requested with its EXPLICIT .ios.js extension so metro resolves
+// it directly, bypassing the platform-redirect machinery this same module
+// implements -- requesting the bare 'BaseViewConfig.js' specifier here would
+// recurse into this exact shim) and ADDS the two event names, so an RN bump
+// carries the bulk of the content and only the keys named here are ours to
+// maintain.
+const BaseViewConfigIosModule = require('react-native/Libraries/NativeComponent/BaseViewConfig.ios.js');
+const BaseViewConfigIos = BaseViewConfigIosModule.default || BaseViewConfigIosModule;
+
+const BaseViewConfigImpeller = {
+  ...BaseViewConfigIos,
+  bubblingEventTypes: {
+    ...BaseViewConfigIos.bubblingEventTypes,
+    // Matches the shape every other bubbling entry in BaseViewConfig.ios.js
+    // uses (topPress -> onPress/onPressCapture, etc.) and the react-native-
+    // windows/react-native-macos onKeyDown/onKeyUp payload fields (key, code,
+    // altKey, ctrlKey, metaKey, shiftKey) FabricHost::dispatchKeyEvent sends.
+    topKeyDown: {
+      phasedRegistrationNames: {
+        bubbled: 'onKeyDown',
+        captured: 'onKeyDownCapture',
+      },
+    },
+    topKeyUp: {
+      phasedRegistrationNames: {
+        bubbled: 'onKeyUp',
+        captured: 'onKeyUpCapture',
+      },
+    },
+    // desktop-input-gap item 6. Release of a non-left button over the view
+    // it was pressed on (react-native-macos/-windows `onAuxClick`; payload is
+    // a PointerEvent with button 1 middle, 2 right, 3 back, 4 forward).
+    topAuxClick: {
+      phasedRegistrationNames: {
+        bubbled: 'onAuxClick',
+        captured: 'onAuxClickCapture',
+      },
+    },
+  },
+  validAttributes: {
+    ...BaseViewConfigIos.validAttributes,
+    onKeyDown: true,
+    onKeyDownCapture: true,
+    onKeyUp: true,
+    onKeyUpCapture: true,
+    onAuxClick: true,
+    onAuxClickCapture: true,
+    // desktop-input-gap item 11. A Tab-focused <View focusable> receives
+    // onFocus/onBlur (FabricHost dispatches 'focus'/'blur', normalized to the
+    // topFocus/topBlur bubbling types BaseViewConfig.ios.js already declares).
+    // iOS declares the event types but not these props for View, so without
+    // them React would never keep a View's handler.
+    onFocus: true,
+    onFocusCapture: true,
+    onBlur: true,
+    onBlurCapture: true,
+  },
+};
+
+module.exports = BaseViewConfigImpeller;
+module.exports.default = BaseViewConfigImpeller;

package/src/metro-shims/shims/Button.impeller.js

@@ -0,0 +1,100 @@
+'use strict';
+// Button shim for the `impeller` platform (SC-24).
+//
+// RN's Button.js picks its look with Platform.OS / Platform.select, which Metro
+// inlines to 'impeller' at build time: the android branch is not taken (no
+// TouchableNativeFeedback) but neither is the ios one, so `styles.button` is
+// undefined and a `color` prop becomes a filled backgroundColor block with the
+// default black title. This copy hard-wires the iOS look: blue (or `color`)
+// title, no filled block, TouchableOpacity.
+
+const React = require('react');
+const interop = (m) => (m && m.default) || m;
+const StyleSheet = interop(require('react-native/Libraries/StyleSheet/StyleSheet'));
+const Text = interop(require('react-native/Libraries/Text/Text'));
+const TouchableOpacity = interop(require('react-native/Libraries/Components/Touchable/TouchableOpacity'));
+const View = interop(require('react-native/Libraries/Components/View/View'));
+
+const Button = ({ref, ...props}) => {
+  const {
+    accessibilityLabel,
+    accessibilityState,
+    'aria-busy': ariaBusy,
+    'aria-checked': ariaChecked,
+    'aria-disabled': ariaDisabled,
+    'aria-expanded': ariaExpanded,
+    'aria-label': ariaLabel,
+    'aria-selected': ariaSelected,
+    accessible,
+    accessibilityActions,
+    accessibilityHint,
+    accessibilityLanguage,
+    onAccessibilityAction,
+    importantForAccessibility,
+    color,
+    disabled: disabledProp,
+    onPress,
+    testID,
+    title,
+    touchSoundDisabled,
+  } = props;
+  const textStyles = [styles.text];
+  if (color) {
+    textStyles.push({color});
+  }
+
+  let state = {
+    busy: ariaBusy ?? accessibilityState?.busy,
+    checked: ariaChecked ?? accessibilityState?.checked,
+    disabled: ariaDisabled ?? accessibilityState?.disabled,
+    expanded: ariaExpanded ?? accessibilityState?.expanded,
+    selected: ariaSelected ?? accessibilityState?.selected,
+  };
+  const disabled = disabledProp != null ? disabledProp : state.disabled;
+  if (disabled !== state.disabled) {
+    state = {...state, disabled};
+  }
+  if (disabled) {
+    textStyles.push(styles.textDisabled);
+  }
+
+  if (typeof title !== 'string') {
+    throw new Error('The title prop of a Button must be a string');
+  }
+
+  return React.createElement(
+    TouchableOpacity,
+    {
+      accessible,
+      accessibilityActions,
+      onAccessibilityAction,
+      accessibilityLabel: ariaLabel || accessibilityLabel,
+      accessibilityHint,
+      accessibilityLanguage,
+      accessibilityRole: 'button',
+      accessibilityState: state,
+      importantForAccessibility:
+        importantForAccessibility === 'no' ? 'no-hide-descendants' : importantForAccessibility,
+      testID,
+      disabled,
+      onPress,
+      touchSoundDisabled,
+      ref,
+    },
+    React.createElement(
+      View,
+      null,
+      React.createElement(Text, {style: textStyles, disabled}, title),
+    ),
+  );
+};
+
+Button.displayName = 'Button';
+
+const styles = StyleSheet.create({
+  text: {textAlign: 'center', margin: 8, color: '#007AFF', fontSize: 18},
+  textDisabled: {color: '#cdcdcd'},
+});
+
+module.exports = Button;
+module.exports.default = Button;