@symbiote-native/engine 0.1.2 → 0.1.3

package/build/accessibility-info/index.android.js

@@ -14,9 +14,8 @@ import { dlog } from '../debug.js';
 import { isBoolean, } from './shared.js';
 // The Android native module name. This is the module the Android JS wrapper
 // (INativeAccessibilityInfoAndroid) resolves: the stock RN `AccessibilityInfo` Turbo/legacy
-// module. Per the symbiote invariant, a module name is only provable on a real host (a
-// headless fake answers to any name); this Android name is DEVICE-VERIFY-PENDING. See
-// .docs/native-module-platform-routing.md.
+// module. A module name is only provable on a real host (a headless fake answers to any
+// name); this Android name is DEVICE-VERIFY-PENDING.
 const ACCESSIBILITY_MODULE = 'AccessibilityInfo';
 // Public event name -> the Android device event the native side emits. Android renames
 // most of them; events with no Android source (iOS-only) are absent and yield an inert

package/build/accessibility-info/index.ios.js

@@ -15,9 +15,8 @@ import { isBoolean, } from './shared.js';
 // The iOS native module name RN registers this under. NOTE: this is the name the iOS JS
 // wrapper (INativeAccessibilityManagerIOS) resolves via
 // `TurboModuleRegistry.get('AccessibilityManager')`, NOT the spec filename
-// `NativeAccessibilityManager`. Per the symbiote invariant, a module name is only provable
-// on a real host (a headless fake answers to any name); this iOS name is device-verified
-// (the pre-split file shipped it). See .docs/native-module-platform-routing.md.
+// `NativeAccessibilityManager`. A module name is only provable on a real host (a headless
+// fake answers to any name); this iOS name is device-verified (the pre-split file shipped it).
 const ACCESSIBILITY_MODULE = 'AccessibilityManager';
 // Public event name -> the iOS device event the native side emits. iOS keeps the names
 // 1:1; the indirection exists only so the mapping stays explicit (Android renames them).

package/build/accessibility-info/shared.js

@@ -6,7 +6,8 @@
 // event maps to (iOS `screenReaderChanged` vs Android `touchExplorationDidChange`).
 // So the .ios/.android files own the native calls and per-platform event-name map;
 // the public types + the shared method surface live here. Filename selects, no
-// Platform.OS read (see ADR 0012 + native_module_name_is_platform_specific). Mirrors
+// Platform.OS read: the native module name is resolved per platform inside those
+// files, not derived from this file's name. Mirrors
 // RN's Libraries/Components/AccessibilityInfo/AccessibilityInfo.js.
 export function isBoolean(value) {
     return typeof value === 'boolean';

package/build/action-sheet-ios/index.js

@@ -3,8 +3,8 @@
 // passes options straight through and the native `callback(buttonIndex)` reports
 // the tapped row. We mirror RN faithfully.
 //
-// The native contract is confirmed from RN's TurboModule spec at
-// .vendors/react-native/.../src/private/specs_DEPRECATED/modules/INativeActionSheetManager.js:
+// The native contract is confirmed from RN's TurboModule spec for
+// `INativeActionSheetManager`:
 //   showActionSheetWithOptions(options, callback: (buttonIndex: number) => void)
 //   showShareActionSheetWithOptions(options, failureCallback, successCallback)
 //   dismissActionSheet?()

package/build/alert/index.android.js

@@ -5,15 +5,15 @@
 // neutral, last-to-first as RN does. Everything platform-agnostic is the shared core.
 // Metro picks this file on an Android host.
 //
-// The native contract is confirmed from RN's TurboModule spec:
-//   .vendors/.../specs_DEPRECATED/modules/INativeDialogManagerAndroid.js
-//     getConstants(): { buttonClicked, dismissed, buttonPositive, buttonNegative,
-//                       buttonNeutral }
-//     showAlert(config, onError: (msg) => void, onAction: (action, buttonKey?) => void)
+// The native contract is confirmed from RN's TurboModule spec for
+// `INativeDialogManagerAndroid`:
+//   getConstants(): { buttonClicked, dismissed, buttonPositive, buttonNegative,
+//                     buttonNeutral }
+//   showAlert(config, onError: (msg) => void, onAction: (action, buttonKey?) => void)
 //
 // device-verify-pending: the `DialogManagerAndroid` name and routing are confirmed from RN
 // source but not yet exercised on a real Android host; only a bridgeless resolution log
-// there can prove the name. See .docs/native-module-platform-routing.md.
+// there can prove the name.
 //
 // Non-throwing, like StatusBar: a missing native module is a no-op, never a crash.
 import { dlog } from '../debug.js';

package/build/alert/index.ios.js

@@ -5,9 +5,9 @@
 // AlertManager path RN uses. Metro picks this file on an iOS host; the base alert.ts
 // re-exports it for web/headless.
 //
-// The native contract is confirmed from RN's TurboModule spec:
-//   .vendors/.../specs_DEPRECATED/modules/INativeAlertManager.js
-//     alertWithArgs(args: Args, callback: (id: number, value: string) => void)
+// The native contract is confirmed from RN's TurboModule spec for
+// `INativeAlertManager`:
+//   alertWithArgs(args: Args, callback: (id: number, value: string) => void)
 //
 // Non-throwing, like StatusBar: a missing native module is a no-op, never a crash (on a
 // device the module may be absent).

package/build/alert/index.js

@@ -4,5 +4,5 @@
 // → graceful no-op). The barrel imports './alert', which resolves here under tsc/tsx and to
 // the platform file under Metro. The `export *` re-exports the public type names
 // (AlertType, AlertButtonStyle, AlertButton, AlertButtons, AlertOptions) so the barrel's
-// `export type { ... } from '../alert/index.js'` still resolves. See ADR 0019.
+// `export type { ... } from '../alert/index.js'` still resolves.
 export * from './index.ios.js';

package/build/alert/shared.js

@@ -3,7 +3,7 @@
 // constant defaults, and the button-normalization helper. The per-platform files
 // (alert.ios.ts / alert.android.ts) implement `alert()` fully against their own native
 // module (iOS keeps `prompt` too); the two native call shapes are too divergent to share
-// a factory. No native, no `Platform.OS` read here. See ADR 0019.
+// a factory. No native, no `Platform.OS` read here.
 // The default positive label RN uses when a button carries no text.
 export const DEFAULT_POSITIVE_TEXT = 'OK';
 // Normalize the `buttons` arg into a consistent list: undefined/empty becomes a single

package/build/animated/animated-component-shared.js

@@ -3,8 +3,7 @@
 // mechanism (capture the host node, build an AnimatedProps leaf, reduce animated
 // props to their current values, override with the passthrough style) is pure JS,
 // identical across frameworks. Only `assignRef` is framework-ref-specific and stays
-// per-adapter; everything here is shared. Extracted from the React wrapper (ADR
-// 0016/0017) so a new adapter reuses it verbatim.
+// per-adapter; everything here is shared so a new adapter reuses it verbatim.
 import { AnimatedNode } from './graph.js';
 import { AnimatedStyle } from './style.js';
 export function isAnimatedNode(value) {

package/build/animated/animations/base.js

@@ -1,5 +1,5 @@
 // Minimal driver base, ported from RN's animations/Animation.js with every
-// native path removed (ADR 0016): no NativeAnimatedHelper, no
+// native path removed: no NativeAnimatedHelper, no
 // __startAnimationIfNative, no shouldUseNativeDriver, no FeatureFlags. What
 // remains is the JS-only contract: hold the end callback, track whether the
 // animation is still active, and fire onEnd at most once.
@@ -48,7 +48,7 @@ export class BaseAnimation {
     // If useNativeDriver was requested and the module is present, mirror the value
     // graph into native and hand the curve to native. The JS rAF loop is then
     // skipped entirely. Returns true when native took over. Falls back to JS (false)
-    // when the module is missing (ADR 0016 path), so an app without RCTAnimation
+    // when the module is missing, so an app without RCTAnimation
     // still animates.
     startNativeIfNeeded(animatedValue) {
         if (!this.nativeDriverRequested)

package/build/animated/animations/composition.js

@@ -1,5 +1,5 @@
 // The driver factory + composition API, ported from RN's
-// AnimatedImplementation.js, JS orchestration only (ADR 0016). `timing` /
+// AnimatedImplementation.js, JS orchestration only. `timing` /
 // `spring` / `decay` wrap a value with a fresh driver and return a
 // CompositeAnimation; `parallel` / `sequence` / `stagger` / `loop` / `delay`
 // orchestrate those. Vector (XY/Color) handling, tracking, AnimatedEvent and

package/build/animated/animations/decay.js

@@ -1,5 +1,5 @@
-// DecayAnimation: ported from RN's animations/DecayAnimation.js, JS path only
-// (ADR 0016). Models momentum bleeding off under friction: an initial velocity
+// DecayAnimation: ported from RN's animations/DecayAnimation.js, JS path only.
+// Models momentum bleeding off under friction: an initial velocity
 // decays exponentially toward a resting value. Ends when consecutive frames
 // move less than 0.1.
 import { dlog } from '../../debug.js';

package/build/animated/animations/spring.js

@@ -1,5 +1,5 @@
 // SpringAnimation: ported from RN's animations/SpringAnimation.js, JS path
-// only (ADR 0016). Integrates the closed form of a damped harmonic oscillator
+// only. Integrates the closed form of a damped harmonic oscillator
 // each frame and rests once both velocity and displacement fall below their
 // thresholds. A spring chained after a previous spring inherits its
 // position/velocity/time (getInternalState) so retargeting mid-flight stays

package/build/animated/animations/timing.js

@@ -1,5 +1,5 @@
 // TimingAnimation: ported from RN's animations/TimingAnimation.js, JS path
-// only (ADR 0016). Walks a value from `fromValue` to `toValue` over `duration`
+// only. Walks a value from `fromValue` to `toValue` over `duration`
 // ms, shaping progress through an easing function. The native-frame export and
 // __startAnimationIfNative branch are dropped.
 import { Easing } from '../easing.js';

package/build/animated/graph.js

@@ -2,8 +2,7 @@
 // sits ABOVE symbiote's shadow tree. Ported from React Native's AnimatedNode.js
 // + AnimatedWithChildren.js, with every native-driver path
 // (NativeAnimatedHelper / __isNative / __makeNative / __getNativeConfig) removed:
-// this is the JS-driven engine (ADR 0016). The native driver re-introduces those
-// hooks separately (ADR 0017).
+// this is a JS-driven engine. A native driver re-introduces those hooks separately.
 //
 // Two phases drive an update:
 //   A) top-down: when a Value changes, walk children to the leaf nodes (the
@@ -28,7 +27,7 @@ export class AnimatedNode {
     // _withSuspendedCallbacks, then fires once with the final value. Ported from RN's
     // AnimatedColor._suspendCallbacks.
     suspendCallbacks = 0;
-    // Native-driver state (ADR 0017). Off until a useNativeDriver animation marks
+    // Native-driver state. Off until a useNativeDriver animation marks
     // the graph native; `nativeTag` is the node's identity in the native module,
     // allocated lazily on first reference (which also creates the native node).
     isNative = false;

package/build/animated/index.js

@@ -1,6 +1,6 @@
-// @symbiote-native/engine/animated: the framework-agnostic, JS-driven Animated engine
-// (ADR 0016). The value graph, easing, interpolation and (Phase 2) drivers are
-// pure JS with no React and no native dependency; every adapter re-exports them.
+// @symbiote-native/engine/animated: the framework-agnostic, JS-driven Animated engine.
+// The value graph, easing, interpolation and drivers are pure JS with no React
+// and no native dependency; every adapter re-exports them.
 export { AnimatedNode, AnimatedWithChildren, flushValue } from './graph.js';
 export { AnimatedValue } from './value.js';
 export { AnimatedValueXY } from './value-xy.js';
@@ -15,12 +15,12 @@ export { SpringAnimation } from './animations/spring.js';
 export { DecayAnimation } from './animations/decay.js';
 export { AnimatedTracking } from './animations/tracking.js';
 export { timing, spring, decay, parallel, sequence, stagger, loop, delay, } from './animations/composition.js';
-// The native-driver bridge (ADR 0017). Adapters need it to connect a props leaf to
+// The native-driver bridge. Adapters need it to connect a props leaf to
 // a host view tag and to restore default values on disconnect.
 export { nativeAnimated, isNativeAnimatedAvailable, } from './native/native-animated.js';
 // The pure graph leaves and the mock, framework-agnostic (extend AnimatedWithChildren,
 // no React/Vue). They live here with the rest of the graph; every adapter's
-// createAnimatedComponent + Animated namespace re-exports them (ADR 0016/0017).
+// createAnimatedComponent + Animated namespace re-exports them.
 export { AnimatedProps } from './props.js';
 export { AnimatedStyle, AnimatedTransform } from './style.js';
 export { AnimatedMock } from './mock.js';

package/build/animated/native/native-animated.js

@@ -1,4 +1,4 @@
-// The native-driver bridge (ADR 0017). When an animation runs with
+// The native-driver bridge. When an animation runs with
 // useNativeDriver:true, the whole value graph is mirrored into native "animated
 // nodes" and the curve is handed to the stock NativeAnimated TurboModule, which
 // then mutates the bound shadow node every frame with ZERO JS per frame.
@@ -6,7 +6,7 @@
 // We consume the module that ships in stock react-native, no native fork. On
 // iOS bridgeless it registers as `NativeAnimatedTurboModule`; we fall back to the
 // legacy `NativeAnimatedModule` name. Resolution goes through the same JSI seam as
-// every other native module (getNativeModule), consistent with ADR 0012. The
+// every other native module (getNativeModule). The
 // module is resolved lazily on first use, so importing this file headless (no
 // native host) is inert until a native-driven animation actually starts.
 import { dlog } from '../../debug.js';
@@ -29,7 +29,7 @@ function module() {
 }
 // True when the stock native module is present in the binary: the gate the
 // drivers consult before honouring useNativeDriver:true (else they fall back to
-// the JS-driven path of ADR 0016).
+// the JS-driven path).
 export function isNativeAnimatedAvailable() {
     return module() !== null;
 }

package/build/animated/props.js

@@ -5,8 +5,8 @@
 // flushes to this leaf via its `update()` method, which re-pulls the current values
 // into a flat partial and pushes it through shared's scoped setNativeProps: one
 // targeted clone-on-write commit. Ported from RN's AnimatedProps.js, JS-driven path
-// only: native config (__makeNative / __getNativeConfig / connectAnimatedNodeToView,
-// ADR 0017) is stripped.
+// only: native config (__makeNative / __getNativeConfig / connectAnimatedNodeToView)
+// is stripped.
 //
 // `update` MUST be a method, not a class field: flushValue detects a leaf by reading
 // a `update` function off the node, and under useDefineForClassFields a field
@@ -73,7 +73,7 @@ export class AnimatedProps extends AnimatedWithChildren {
     // base component's public instance via setNativeView.
     target = null;
     // The Fabric view tag this leaf is bound to natively (null until connected).
-    // Kept so __detach can disconnect exactly what it connected (ADR 0017).
+    // Kept so __detach can disconnect exactly what it connected.
     connectedViewTag = null;
     constructor(inputProps) {
         super();
@@ -139,7 +139,7 @@ export class AnimatedProps extends AnimatedWithChildren {
         this.target = null;
         super.__detach();
     }
-    // ---- native driver (ADR 0017) -------------------------------------------
+    // ---- native driver -------------------------------------------------------
     // Marking the leaf native binds it to the host view. The value->...->props edges
     // are wired by the upstream walk (AnimatedWithChildren.__makeNative); the one
     // thing only the leaf can do is attach the props node to a real view tag.

package/build/animated/style.js

@@ -2,7 +2,7 @@
 // `transform` whose entries may themselves be AnimatedNodes. Ported from RN's
 // AnimatedStyle.js + AnimatedTransform.js, NUMERIC path only: the native-driver
 // config (__makeNative / __getNativeConfig / allowlist) and the web/string/color
-// branches are stripped (ADR 0016). On __getValue() each node re-pulls its
+// branches are stripped. On __getValue() each node re-pulls its
 // animated entries into a plain flat object the props leaf hoists onto the view.
 import { AnimatedNode, AnimatedWithChildren } from './graph.js';
 import { flattenStyle } from '../style/index.js';
@@ -88,7 +88,7 @@ export class AnimatedTransform extends AnimatedWithChildren {
         super.__detach();
     }
     // Native: one entry per transform, animated entries pointing at their value's
-    // native tag, static ones carrying the (angle-normalized) literal (ADR 0017).
+    // native tag, static ones carrying the (angle-normalized) literal.
     __getNativeConfig() {
         const transforms = [];
         for (const entry of this.transforms) {
@@ -171,7 +171,7 @@ export class AnimatedStyle extends AnimatedWithChildren {
             node.__removeChild(this);
         super.__detach();
     }
-    // Native: map each animated style key to its value's native tag (ADR 0017).
+    // Native: map each animated style key to its value's native tag.
     // Static keys are not in the native style node. The view already carries them.
     __getNativeConfig() {
         const style = {};

package/build/animated/value-xy.js

@@ -2,7 +2,7 @@
 // driving node itself: it multiplexes two ordinary AnimatedValues (x, y), so the
 // same clone-on-write and listener machinery that powers AnimatedValue applies
 // per-axis. Ported from RN's AnimatedValueXY.js with the native-driver and
-// platform-config branches removed (ADR 0016). The two child values carry their
+// platform-config branches removed. The two child values carry their
 // own native state if they are ever made native.
 import { AnimatedValue } from './value.js';
 let nextListenerId = 1;

package/build/animated/value.js

@@ -1,7 +1,7 @@
 // AnimatedValue: the standard driving value. One value can drive many props in
 // sync but is driven by one mechanism at a time: a new mechanism (a fresh
 // animation, or setValue) stops the previous one. Ported from RN's
-// AnimatedValue.js with the native-driver branches removed (ADR 0016); tracking
+// AnimatedValue.js with the native-driver branches removed; tracking
 // (animating toward another animated node) is deferred.
 import { AnimatedWithChildren, flushValue } from './graph.js';
 import { AnimatedInterpolation } from './interpolation-node.js';

package/build/back-handler/index.js

@@ -12,9 +12,8 @@ import { dlog } from '../debug.js';
 // The native module name RN registers this under. NOTE: this is the name the
 // INativeDeviceEventManager spec resolves via
 // `TurboModuleRegistry.get('DeviceEventManager')`, NOT the spec filename
-// `INativeDeviceEventManager`. Per the symbiote invariant, a module name is only
-// provable on a real host (a headless fake answers to any name); this name is
-// device-verify-pending (Android). See .docs/native-module-platform-routing.md.
+// `INativeDeviceEventManager`. A module name is only provable on a real host (a
+// headless fake answers to any name); this name is device-verify-pending (Android).
 const DEVICE_EVENT_MANAGER_MODULE = 'DeviceEventManager';
 // The device event native emits when the hardware back button is pressed.
 const DEVICE_BACK_EVENT = 'hardwareBackPress';

package/build/commit.js

@@ -553,13 +553,13 @@ function commitContainer(rootTag) {
             `cloneChildren=${stats.cloneChildren} reused=${stats.reused}`);
     }
 }
-// Targeted per-frame prop write for the JS-driven Animated path (ADR 0016). RN
-// flushes an animation frame with an in-place `instance.setNativeProps(...)`; we have
-// no in-place mutation (Fabric is persistent), so a frame is one scoped commit: mutate
+// Targeted per-frame prop write for the JS-driven Animated path. RN flushes an
+// animation frame with an in-place `instance.setNativeProps(...)`; we have no
+// in-place mutation (Fabric is persistent), so a frame is one scoped commit: mutate
 // the node's desired props, then re-reconcile its surface. The engine clones only this
 // node (props differ), bubbles the re-clone to the root, reuses every sibling subtree
 // by reference, and emits a single completeRoot. This is the "slow tier", viable for a
-// single shallow animation; the native driver (ADR 0017) is the answer for scale.
+// single shallow animation; driving the animation natively is the answer for scale.
 export function setNativeProps(node, partial) {
     const record = mirror.get(node);
     if (record === undefined) {
@@ -581,8 +581,8 @@ export function setNativeProps(node, partial) {
     commitContainer(record.rootTag);
 }
 // The committed reactTag of a node (stable across clone-on-write), for binding the
-// Animated native driver via connectAnimatedNodeToView (ADR 0017). Undefined until the
-// node has been committed at least once.
+// native Animated driver via connectAnimatedNodeToView. Undefined until the node
+// has been committed at least once.
 export function getNativeTag(node) {
     return mirror.get(node)?.tag;
 }

package/build/dimensions/index.js

@@ -5,8 +5,7 @@
 // event whose payload IS a fresh IDimensionsPayload. We cache the metrics and notify
 // 'change' listeners on each update, exactly as RN does.
 //
-// The native contract is confirmed from RN's TurboModule spec at
-// .vendors/.../specs_DEPRECATED/modules/INativeDeviceInfo.js:
+// The native contract mirrors React Native's TurboModule spec for DeviceInfo:
 //   getConstants(): { Dimensions: { window?, screen?, windowPhysicalPixels?,
 //                     screenPhysicalPixels? } }
 // We resolve it through the same generic native-module bridge as Platform

package/build/i18n-manager/index.js

@@ -15,9 +15,8 @@
 import { dlog } from '../debug.js';
 import { getNativeModule } from '../native-modules.js';
 // The iOS native module name RN registers this under (the same name on both
-// platforms). NOTE: per the symbiote invariant, a module name is only provable on
-// a real host (a headless fake answers to any name); this name is
-// device-verify-pending. See .docs/native-module-platform-routing.md.
+// platforms). A module name is only provable on a real host — a headless fake
+// answers to any name — so this name is still pending verification on device.
 const I18N_MANAGER_MODULE = 'I18nManager';
 // RN's fallback constants when no native module is linked (headless / not yet on
 // device): not RTL, and the iOS default of swapping in RTL.

package/build/index.js

@@ -39,8 +39,8 @@ export { AnimatedNode, AnimatedWithChildren, AnimatedValue, AnimatedValueXY, Ani
 export { getSlot } from './fabric.js';
 // Imperative runtime modules: framework-agnostic native-bridge consumers (no visual, no
 // lifecycle), moved here from @symbiote-native/react so every adapter re-exports the SAME module.
-// Native module names are platform-selected and device-verified, not headless (CLAUDE.md
-// <native_module_name_is_platform_specific>).
+// The native module a JS API talks to is chosen per platform and can only be confirmed on a
+// real device or simulator, not headless (a headless fake resolves any module name).
 export { Alert } from './alert/index.js';
 export { Share } from './share/index.js';
 export { ActionSheetIOS } from './action-sheet-ios/index.js';

package/build/layout-animation/index.js

@@ -13,8 +13,7 @@ import { dlog } from '../debug.js';
 // DEVICE-VERIFY-PENDING: on bridgeless Fabric the layout-animation configure call
 // is exposed by RN through the UIManager surface (RN's non-Fabric path calls
 // `UIManager.configureNextLayoutAnimation`; the Fabric path routes the same args
-// onto `global.nativeFabricUIManager.configureNextLayoutAnimation`). Per
-// .docs/decisions/0012 and .docs/native-module-platform-routing.md the native
+// onto `global.nativeFabricUIManager.configureNextLayoutAnimation`). The native
 // MODULE NAME is platform-specific and a headless fake answers to ANY name, so
 // the name below is the most plausible bridgeless candidate, NOT proven. Only the
 // simulator/device resolution log can confirm it; the fallback list is tried in

package/build/linking/index.android.js

@@ -5,7 +5,7 @@
 //
 // device-verify-pending: the `IntentAndroid` name and routing are confirmed from RN
 // source but not yet exercised on a real Android host; only a bridgeless resolution
-// log there can prove the name. See .docs/native-module-platform-routing.md.
+// log there can prove the name.
 import { createLinking } from './shared.js';
 export const Linking = createLinking({
     moduleName: 'IntentAndroid',

package/build/linking/index.js

@@ -2,5 +2,5 @@
 // platform file). Metro overrides this with linking.ios.ts / linking.android.ts on a
 // real iOS/Android host; off those, the iOS build is the fallback (its LinkingManager
 // resolves null elsewhere → graceful no-op). The barrel imports './linking', which
-// resolves here under tsc/tsx and to the platform file under Metro. See ADR 0019.
+// resolves here under tsc/tsx and to the platform file under Metro.
 export * from './index.ios.js';

package/build/linking/shared.js

@@ -6,7 +6,7 @@
 //
 // Metro selects the platform file on a real host (linking.android.ts > linking.ts);
 // the base linking.ts re-exports the iOS build for web/headless. There is no runtime
-// `Platform.OS` read; the filename is the selector. See ADR 0019.
+// `Platform.OS` read; the filename is the selector.
 import { installDeviceEventHub, NativeEventEmitter, } from '../native-events.js';
 import { getNativeModule } from '../native-modules.js';
 import { dlog } from '../debug.js';

package/build/native-events.js

@@ -6,7 +6,7 @@
 // second registration is a silent no-op. So we do NOT register our own hub on a
 // real host: the app injects RN's DeviceEventEmitter (the bus native actually
 // calls) via `setDeviceEventSource`, exactly like setColorProcessor. The built-in
-// hub below stays as the fallback bus for headless/non-RN runs. See .docs/decisions/0012.
+// hub below stays as the fallback bus for headless/non-RN runs.
 import { dlog } from './debug.js';
 import { runWrapped } from './dispatch.js';
 // The single device-event bus. Native pushes into `emit`; subscribers (wrapped by

package/build/native-modules.js

@@ -7,7 +7,7 @@
 // This is first-party access, for symbiote's own modules (StatusBarManager,
 // KeyboardObserver, …). Third-party RN packages import `TurboModuleRegistry` from
 // `'react-native'` and read the same global themselves; they do not go through
-// here. See .docs/decisions/0012.
+// here.
 import { dlog } from './debug.js';
 // The native module value crosses from an untyped HostObject into our types here;
 // the caller vouches for its shape via T (the single trust-boundary narrowing, no

package/build/node.js

@@ -1,8 +1,9 @@
 // The retained shadow-tree. Adapters mutate this cheap in-memory tree through a
 // tiny API; the commit engine (commit.ts) later walks it and translates the
 // whole thing into Fabric's clone-on-write child sets. Keeping the retained
-// tree mutable while the Fabric mirror stays persistent is the core R2 trick,
-// and it lives here in shared so no adapter re-implements it.
+// tree mutable while the Fabric mirror stays persistent lets every adapter mutate
+// freely without touching Fabric's clone-on-write protocol directly, and it
+// lives here in shared so no adapter re-implements it.
 import { isEventFor } from './view-config.js';
 import { isClassNameValue, resolveClassName } from './style-registry/index.js';
 const BRAND = Symbol('symbiote.node');

package/build/permissions-android/index.js

@@ -20,10 +20,9 @@
 import { getNativeModule } from '../native-modules.js';
 import { dlog } from '../debug.js';
 // The native module name RN registers this TurboModule under
-// (`TurboModuleRegistry.get<Spec>('PermissionsAndroid')`). NOTE: per the
-// symbiote invariant, a module name is only provable on a real host (a headless
-// fake answers to any name); this name is device-verify-pending. See
-// .docs/native-module-platform-routing.md.
+// (`TurboModuleRegistry.get<Spec>('PermissionsAndroid')`). NOTE: a module name is
+// only provable on a real host (a headless fake answers to any name); this name
+// is device-verify-pending.
 const PERMISSIONS_ANDROID_MODULE = 'PermissionsAndroid';
 // The runtime-permission result strings Android can return. Modeled as a frozen
 // `as const` map: the generated-style constant-map exception to "no magic

package/build/platform/index.android.js

@@ -2,7 +2,7 @@
 // `OS` is the static 'android'; `Version` is the numeric API level and the rest come
 // from the PlatformConstants native module (RN spec NativePlatformConstantsAndroid.js,
 // a different payload from iOS). Metro picks this on an Android host. The module name is
-// the same 'PlatformConstants'; only the shape differs. See .docs/decisions/0022.
+// the same 'PlatformConstants'; only the shape differs.
 import { createConstantsResolver } from './shared.js';
 // The filename already selected this host: 'android' is a literal, not a probe.
 const OS_ANDROID = 'android';

package/build/platform/index.ios.js

@@ -2,7 +2,7 @@
 // is the static 'ios'; everything else derives from the PlatformConstants native module
 // (RN spec NativePlatformConstantsIOS.js), read lazily and cached via the shared
 // resolver. Metro picks this on an iOS host; it is also the base re-export target
-// (platform.ts) so tsc / tsx / web (no Metro) land here too. See .docs/decisions/0022.
+// (platform.ts) so tsc / tsx / web (no Metro) land here too.
 import { createConstantsResolver, UNKNOWN_VERSION, } from './shared.js';
 // interfaceIdiom values RN compares against for the device-class getters.
 const IDIOM_PAD = 'pad';

package/build/platform/index.js

@@ -1,5 +1,4 @@
 // Base / default Platform: re-exports the iOS implementation. Metro overrides this
 // with platform.ios.ts / platform.android.ts on a real host; under tsc / tsx / web
 // (no Metro) resolution lands here. The filename is the selector, no Platform.OS read.
-// See .docs/decisions/0022 (and 0020 for the same split on component names).
 export * from './index.ios.js';

package/build/platform/shared.js

@@ -4,7 +4,6 @@
 // owns only what genuinely differs: the OS literal, the constants shape + guard, the
 // select precedence, and the device-class getters. The filename is the selector (Metro
 // picks platform.ios / platform.android by host); no Platform.OS read lives here.
-// See .docs/decisions/0022 (and 0020 for the same split on component names).
 import { dlog } from '../debug.js';
 import { getNativeModule } from '../native-modules.js';
 // The native module name RN registers PlatformConstants under, identical on both

package/build/settings/index.js

@@ -10,10 +10,8 @@ import { getNativeModule } from '../native-modules.js';
 import { dlog } from '../debug.js';
 // The iOS native module name RN registers this under. NOTE: this is the name the
 // iOS JS wrapper resolves via `TurboModuleRegistry.getEnforcing('SettingsManager')`.
-// The spec filename is `INativeSettingsManager`. Per the symbiote invariant, a
-// module name is only provable on a real host (a headless fake answers to any
-// name); this iOS name is device-verify-pending.
-// See .docs/native-module-platform-routing.md.
+// The spec filename is `INativeSettingsManager`. A module name is only provable on a
+// real host (a headless fake answers to any name); this iOS name is device-verify-pending.
 const SETTINGS_MODULE = 'SettingsManager';
 // The device event native emits when the app's defaults change out from under JS
 // (e.g. a Settings.bundle edit). Its payload is a record of changed key->value.

package/build/share/index.android.js

@@ -2,12 +2,11 @@
 // `share(content, dialogTitle?) -> Promise<{ action }>`. We validate content, build the
 // content dict (title/message), forward the dialog title, and map the resolved action
 // onto the shared IShareAction shape; Android has no dismiss path, so RN fills the
-// missing activityType with null. Metro picks this file on an Android host. See ADR 0019.
+// missing activityType with null. Metro picks this file on an Android host.
 //
 // device-verify-pending: the `ShareModule` name matches NativeShareModule's
 // TurboModuleRegistry.get('ShareModule') from RN source, but headless fakes resolve any
 // name, so it is only proven on a real Android host (a bridgeless resolution log there).
-// See .docs/native-module-platform-routing.md, ADR 0012.
 import { dlog } from '../debug.js';
 import { getNativeModule } from '../native-modules.js';
 import { validateContent, shareActions, SHARED_ACTION, DISMISSED_ACTION } from './shared.js';

package/build/share/index.ios.js

@@ -3,7 +3,7 @@
 // `showShareActionSheetWithOptions(options, failure, success)`. We validate content, map
 // options onto the native share options, and resolve the IShareAction from the success
 // callback. Metro picks this file on an iOS host; the base share.ts re-exports it for
-// web/headless. See ADR 0019.
+// web/headless.
 import { dlog } from '../debug.js';
 import { getNativeModule } from '../native-modules.js';
 import { validateContent, shareActions, SHARED_ACTION, DISMISSED_ACTION } from './shared.js';

package/build/share/index.js

@@ -2,5 +2,5 @@
 // platform file). Metro overrides this with share.ios.ts / share.android.ts on a real
 // iOS/Android host; off those, the iOS build is the fallback (its ActionSheetManager
 // resolves null elsewhere → graceful reject). The barrel imports './share', which
-// resolves here under tsc/tsx and to the platform file under Metro. See ADR 0019.
+// resolves here under tsc/tsx and to the platform file under Metro.
 export * from './index.ios.js';

package/build/share/shared.js

@@ -6,7 +6,7 @@
 //
 // Metro selects the platform file on a real host (share.android.ts > share.ts); the base
 // share.ts re-exports the iOS build for web/headless. There is no runtime `Platform.OS`
-// read: the filename is the selector. See ADR 0019.
+// read: the filename is the selector.
 // RN's Share action constants (RN Share.js ~173/179). These back the documented
 // `result.action === Share.dismissedAction` pattern. True statically-known literals,
 // so CONSTANT_CASE; the public fields (Share.sharedAction / Share.dismissedAction) are

package/build/status-bar/index.android.js

@@ -9,7 +9,7 @@
 // not installed" because RN installs global.RN$stopSurface from its own renderer, which we
 // replace. Now that render.ts installs RN$stopSurface and tears surfaces down cleanly, the
 // relayout survives and the bar updates without blanking (verified on device: show/hide +
-// light/dark text). See render.ts installStopSurfaceGlobal + native-module-platform-routing.
+// light/dark text). See render.ts's installStopSurfaceGlobal.
 import { getNativeModule } from '../native-modules.js';
 import { processColor } from '../commit.js';
 import { dlog } from '../debug.js';

package/build/status-bar/index.ios.js

@@ -1,7 +1,6 @@
 // StatusBar on iOS drives the iOS `StatusBarManager` TurboModule from props (via
 // applyStatusBarProps) and from the static methods (statusBarImperative). The native
-// contract is RN's spec at
-// .vendors/react-native/.../src/private/specs_DEPRECATED/modules/NativeStatusBarManagerIOS.js:
+// contract mirrors RN's own NativeStatusBarManagerIOS spec:
 //   setStyle(statusBarStyle?: string, animated: boolean)
 //   setHidden(hidden: boolean, withAnimation: 'none' | 'fade' | 'slide')
 //   setNetworkActivityIndicatorVisible(visible: boolean)

package/build/status-bar/shared.js

@@ -6,7 +6,7 @@
 // flags from our bridgeless surface blanks it (a window-insets relayout detaches the Fabric
 // surface). So the .ios/.android files own the native calls (applyStatusBarProps +
 // statusBarImperative); the types + the framework-agnostic imperative surface live here.
-// Filename selects, no Platform.OS read (see ADR 0012 + native_module_name_is_platform_specific).
+// Filename selects, no Platform.OS read.
 //
 // This is the engine half: pure types + the imperative API. Each adapter wraps it with a
 // per-framework declarative component (React FC + useEffect, Vue defineComponent + watchEffect)

package/build/style-registry/index.js

@@ -1,20 +1,17 @@
-// Runtime style registry, ported from wolf-tui's internal/shared/src/styles/registry.ts.
-// Side-effect CSS imports (compiled by the sibling CSS-to-style build package, not
-// this module) call registerStyles() with camelCase keys; components look them up
-// by resolveClassName(). No CSS parsing happens here — this is a Map<string, ...>
-// lookup, nothing more.
+// Runtime style registry. Side-effect CSS imports (compiled by the sibling CSS-to-style
+// build package, not this module) call registerStyles() with camelCase keys; components
+// look them up by resolveClassName(). No CSS parsing happens here — this is a
+// Map<string, ...> lookup, nothing more.
 //
-// Dropped vs the wolf-tui original: all Tailwind-utility detection (registerTailwind-
-// Metadata / isTailwindUtility / custom prefix-static sets) — this repo's style
-// surface has no Tailwind layer, so compound lookup below always runs for 2-4-part
-// class strings instead of being gated behind "no part looks like a utility class".
+// This registry has no Tailwind-utility detection layer — this repo's style surface has
+// no Tailwind layer, so the compound lookup below always runs for 2-4-part class strings
+// instead of being gated behind "no part looks like a utility class".
 //
 // kebab-case authoring: a CSS selector `.section-label` always registers under the
 // camelCase key `sectionLabel` (@symbiote-native/css-parser's extractClassName), so a template
 // can write EITHER `class="sectionLabel"` OR `class="section-label"` — resolveOne below
-// falls back to the kebab->camel form on a miss. Reinstated (wolf-tui had this, an
-// earlier port here dropped it on the assumption authors would always match the
-// camelCase key exactly) once that assumption proved wrong in practice.
+// falls back to the kebab->camel form on a miss. The fallback matters because assuming
+// authors would always match the camelCase key exactly proved wrong in practice.
 // Compound lookup tries every ordering of 2-4 space-separated class parts joined by
 // '.' (e.g. "btn primary" -> "btn.primary" / "primary.btn") before falling back to a
 // per-class merge, mirroring CSS compound-selector registration (`.btn.primary { }`).
@@ -93,10 +90,9 @@ function generateKPermutations(parts, size) {
     helper([], parts, 0);
     return result;
 }
-// wolf-tui joins a compound permutation with '.' ("btn.primary") because its CSS
-// pipeline registers dot-joined selector strings. This repo's CSS-to-style compiler
-// emits plain camelCase keys for every class, single or compound, so "btn primary"
-// must resolve against a registered "btnPrimary" instead.
+// Compound permutations join as camelCase ("btn primary" -> "btnPrimary") because this
+// repo's CSS-to-style compiler emits plain camelCase keys for every class, single or
+// compound, so "btn primary" must resolve against a registered "btnPrimary".
 function toCompoundKey(parts) {
     return parts.reduce((key, part, index) => (index === 0 ? part : key + capitalize(part)), '');
 }

package/build/toast-android/index.js

@@ -17,9 +17,9 @@ import { dlog } from '../debug.js';
 import { getNativeModule } from '../native-modules.js';
 // The native module name RN registers this under. NOTE: this is the name the spec
 // resolves via `TurboModuleRegistry.getEnforcing<Spec>('ToastAndroid')`, NOT the
-// spec filename `INativeToastAndroid`. Per the symbiote invariant, a module name is
-// only provable on a real host (a headless fake answers to any name); this Android
-// name is device-verify-pending. See .docs/native-module-platform-routing.md.
+// spec filename `INativeToastAndroid`. A module name is only provable on a real
+// host (a headless fake answers to any name); this Android name is confirmed from
+// RN source but not yet exercised on a device.
 const TOAST_MODULE = 'ToastAndroid';
 // Conventional RN values for SHORT/LONG/TOP/BOTTOM/CENTER. On a real device the
 // numbers come from native getConstants() (resolved below); these are the fallbacks

package/build/vibration/index.android.js

@@ -5,8 +5,7 @@
 //
 // device-verify-pending: the `Vibration` name and the `vibrateByPattern` routing are
 // confirmed from RN source but not yet exercised on a real Android host: only a
-// bridgeless resolution log there can prove the name. See
-// .docs/native-module-platform-routing.md.
+// bridgeless resolution log there can prove the name.
 import { createVibration } from './shared.js';
 // RN encodes "do not repeat" as -1 and "repeat from start" as 0 in vibrateByPattern.
 const REPEAT_NONE = -1;

package/build/vibration/index.js

@@ -2,5 +2,5 @@
 // platform file). Metro overrides this with vibration.ios.ts / vibration.android.ts on a
 // real iOS/Android host; off those, the iOS build is the fallback (its Vibration module
 // resolves null elsewhere → graceful no-op). The barrel imports './vibration', which
-// resolves here under tsc/tsx and to the platform file under Metro. See ADR 0019.
+// resolves here under tsc/tsx and to the platform file under Metro.
 export * from './index.ios.js';

package/build/vibration/shared.js

@@ -5,17 +5,16 @@
 // `createVibration`. Mirrors RN's Libraries/Vibration/Vibration.js: a number is a single
 // buzz, an array is a pattern.
 //
-// Native module name is `Vibration` on BOTH iOS and Android (see
-// .docs/native-module-platform-routing.md), so unlike Linking the module name is shared,
-// not divergent. The TurboModule spec lives at specs_DEPRECATED/modules/INativeVibration.js:
+// Native module name is `Vibration` on BOTH iOS and Android, so unlike Linking the
+// module name is shared, not divergent. The TurboModule spec lives at
+// specs_DEPRECATED/modules/INativeVibration.js:
 //   vibrate(pattern: number)
 //   vibrateByPattern(pattern: number[], repeat: number)
 //   cancel()
 //
 // Metro selects the platform file on a real host (vibration.android.ts > vibration.ts);
 // the base vibration.ts re-exports the iOS build for web/headless. There is no runtime
-// `Platform.OS` read; the filename is the selector. See ADR 0019. No Fabric view,
-// pure JS->native.
+// `Platform.OS` read; the filename is the selector. No Fabric view, pure JS->native.
 import { dlog } from '../debug.js';
 import { getNativeModule } from '../native-modules.js';
 const VIBRATION_MODULE = 'Vibration';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/engine",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "SymbioteNative's retained shadow-tree engine — clone-on-write commit path + event normalization over React Native Fabric, shared by every framework adapter.",
   "repository": {
     "type": "git",
@@ -32,7 +32,7 @@
     "react-native": ">=0.86"
   },
   "devDependencies": {
-    "@symbiote-native/test-utils": "0.1.1"
+    "@symbiote-native/test-utils": "0.1.3"
   },
   "scripts": {
     "typecheck": "tsc --build",