@symbiote-native/vue 0.3.7 → 0.4.0

package/build/components/scroll-view/sticky-header.js

@@ -1,19 +1,17 @@
 // Sticky headers: the Vue twin of adapters/react/src/scroll-view-sticky-header.tsx, the JS layer
 // RN implements in ScrollView.js / ScrollViewStickyHeader.js.
 //
-// Source-based: RN does stickiness PURELY IN JS. ScrollView.js (render, ~line 1690)
-// wraps each child whose index is in `stickyHeaderIndices` in a ScrollViewStickyHeader, fed by a
-// single `_scrollAnimatedValue` an Animated.event drives from `onScroll` (ScrollView.js ~line
-// 1095). The native Fabric scroll view does NOT honor the index array on its own, so forwarding
-// `stickyHeaderIndices` to native is a silent no-op. So we replicate the JS layer: subscribe each
-// flagged child to the scroll offset and translate it to stay pinned. The interpolation mirrors
-// ScrollViewStickyHeader.js (non-inverted + inverted branches) and lives, framework-agnostic, in
+// RN does stickiness PURELY IN JS: ScrollView.js wraps each flagged child in a
+// ScrollViewStickyHeader fed by a single _scrollAnimatedValue that Animated.event drives from
+// onScroll. The native scroll view does NOT honor the index array itself, so forwarding
+// stickyHeaderIndices to native is a silent no-op - we replicate the JS layer instead. The
+// interpolation math (non-inverted + inverted) lives framework-agnostic in
 // @symbiote-native/components (computeStickyInterpolation); this file holds the Vue component
-// shell, the layout state, and the child-wrapping. Render shared verbatim with React via the math.
-// Vue supplies only the reactive lifecycle (refs/watch instead of useState/useEffect).
-import { defineComponent, h, isVNode, ref, shallowRef, watch, watchEffect, markRaw, } from '@vue/runtime-core';
+// shell, layout state, and child-wrapping. Vue supplies only the reactive lifecycle
+// (refs/watch instead of useState/useEffect).
+import { defineComponent, h, isVNode, onBeforeUnmount, ref, shallowRef, watchEffect, markRaw, } from '@vue/runtime-core';
 import { AnimatedValue, AnimatedInterpolation, Platform, dlog, } from '@symbiote-native/engine';
-import { computeStickyInterpolation, nextStickyHeaderY, readLayoutNumber, stickyDebounceMs, STICKY_HEADER_Z_INDEX, } from '@symbiote-native/components';
+import { createInitialStickyState, nextStickyHeaderY, readLayoutNumber, reduceSticky, STICKY_HEADER_Z_INDEX, } from '@symbiote-native/components';
 import { Animated } from '../../modules/animated/index.js';
 function isHandler(value) {
     return typeof value === 'function';
@@ -24,104 +22,109 @@ function isRecord(value) {
 function isAnimatedValue(value) {
     return value instanceof AnimatedValue;
 }
-// Read this header's wrapped child's own onLayout off its VNode props, so the sticky wrapper can
-// forward layout to it (RN ScrollViewStickyHeader.js calls the child's onLayout after its own).
+// So the sticky wrapper can forward layout to the child (RN calls the child's onLayout after its own).
 function readChildOnLayout(child) {
     if (!isRecord(child.props))
         return undefined;
     const handler = child.props.onLayout;
     return isHandler(handler) ? handler : undefined;
 }
-// One sticky header. Measures its own y/height via onLayout, interpolates the shared scroll offset
-// into a translateY that keeps it pinned to the top (or bottom, inverted) until the next header
-// collides with it, and drives that translate through the native driver when available so the pin
-// tracks scroll on the UI thread (no JS jitter). Ported from ScrollViewStickyHeader.js,
-// including the Fabric ShadowTree debounce path. inheritAttrs:false so the IStickyHeaderProps
-// inputs (scrollAnimatedValue/nextHeaderLayoutY/…) never fall through onto Animated.View and reach
-// Fabric as props (scrollAnimatedValue on a host node would crash Android's folly::dynamic).
+// One sticky header. Measures its own y/height via onLayout, interpolates the shared scroll
+// offset into a translateY pinning it to the top (or bottom, inverted) until the next header
+// collides with it, driven through the native driver when available (no JS jitter). Ported from
+// ScrollViewStickyHeader.js, including the Fabric ShadowTree debounce path. inheritAttrs:false
+// so the IStickyHeaderProps inputs never fall through onto Animated.View and reach Fabric as
+// props (scrollAnimatedValue on a host node would crash Android's folly::dynamic).
 export const ScrollViewStickyHeader = defineComponent({
     name: 'ScrollViewStickyHeader',
     inheritAttrs: false,
     setup(_props, { attrs, slots }) {
-        // The scroll-offset value the parent shares, read once (it is stable across renders, the same
-        // markRaw'd AnimatedValue), held by IDENTITY in a const (never run through toReactive). A fresh
-        // fallback keeps working if the invariant (wrapStickyHeaders always supplies it) ever breaks.
+        // Read once - stable across renders (the same markRaw'd AnimatedValue). Held by IDENTITY, never
+        // run through toReactive. A fresh fallback keeps working if wrapStickyHeaders ever fails to supply it.
         const scrollAnimatedValue = isAnimatedValue(attrs.scrollAnimatedValue)
             ? attrs.scrollAnimatedValue
             : markRaw(new AnimatedValue(0));
-        const measured = ref(false);
-        const layoutY = ref(0);
-        const layoutHeight = ref(0);
-        // The animated node that drives the transform (RN's animatedTranslateY). When the scroll value
-        // is native (attachStickyScroll), this interpolation runs on the UI thread: the smooth pin.
-        // Engine node → shallowRef (held by identity, the reactivity rule); the un-measured identity
-        // stub until the effect below rebuilds it.
+        // Mutated in place by reduceSticky. A plain object, not a ref: render reads it gated by the
+        // reactive `version` bump + `animatedTranslateY` below. DECISIONS (zero-swallow gate,
+        // debounce delay, rebuild ranges) all live in reduceSticky.
+        const state = createInitialStickyState();
+        // Bumped when the reducer commits a new translateY, forcing render to re-read state.translateY.
+        const version = ref(0);
+        // Engine node -> shallowRef (identity rule); the un-measured identity stub until the
+        // rebuild-interpolation effect below replaces it.
         const animatedTranslateY = shallowRef(scrollAnimatedValue.interpolate({ inputRange: [-1, 0], outputRange: [0, 0] }));
-        // The debounced EXPLICIT translateY pushed to the committed transform via
-        // passthroughAnimatedPropExplicitValues, so the Fabric ShadowTree (hit-testing) knows the pinned
-        // position while the native driver animates. null until the listener first fires.
-        const translateY = ref(null);
-        let haveReceivedInitialZeroTranslateY = true;
         let debounceTimer;
-        watch(translateY, value => {
-            if (value !== 0 && value !== null)
-                haveReceivedInitialZeroTranslateY = false;
+        // Held so the next rebuild detaches the old listener and onBeforeUnmount cleans up.
+        let interpolation;
+        let listenerId;
+        const inputs = () => ({
+            os: Platform.OS,
+            inverted: typeof attrs.inverted === 'boolean' ? attrs.inverted : undefined,
+            scrollViewHeight: typeof attrs.scrollViewHeight === 'number' ? attrs.scrollViewHeight : undefined,
+            nextHeaderLayoutY: typeof attrs.nextHeaderLayoutY === 'number' ? attrs.nextHeaderLayoutY : undefined,
         });
-        // The animated value updates several times per frame during scroll; debounce it and push the
-        // settled value into the committed transform so hit detection stays current (RN: a Fabric-only
-        // issue; symbiote is always Fabric, and worse on Android).
-        const animatedValueListener = ({ value }) => {
-            if (typeof value !== 'number')
-                return;
-            const timeout = stickyDebounceMs(Platform.OS);
-            // A freshly-rebuilt interpolation re-emits 0 to its listeners; swallow that first zero (RN).
-            if (value === 0 && !haveReceivedInitialZeroTranslateY) {
-                haveReceivedInitialZeroTranslateY = true;
-                return;
+        const runEffects = (effects) => {
+            for (const effect of effects) {
+                switch (effect.kind) {
+                    case 'rebuild-interpolation': {
+                        // Detach the old listener, build a fresh interpolation, and wire the settled-value listener.
+                        if (interpolation !== undefined && listenerId !== undefined) {
+                            interpolation.removeListener(listenerId);
+                            listenerId = undefined;
+                        }
+                        const next = scrollAnimatedValue.interpolate({
+                            inputRange: effect.inputRange,
+                            outputRange: effect.outputRange,
+                        });
+                        listenerId = next.addListener(({ value }) => {
+                            if (typeof value === 'number')
+                                dispatch({ kind: 'animated-tick', value });
+                        });
+                        interpolation = next;
+                        animatedTranslateY.value = next;
+                        break;
+                    }
+                    case 'schedule-debounce':
+                        // The animated value updates several times per frame; debounce the settled value so
+                        // hit detection stays current (a Fabric issue, worse on Android).
+                        if (debounceTimer !== undefined)
+                            clearTimeout(debounceTimer);
+                        debounceTimer = setTimeout(() => {
+                            debounceTimer = undefined;
+                            dispatch({ kind: 'debounce-fired', value: effect.value });
+                        }, effect.delay);
+                        break;
+                    case 'apply-passthrough':
+                        version.value += 1;
+                        break;
+                    case 'record-header-y':
+                        // Vue records through attrs.onLayout (the wrapper closure); the reducer emits no index for it.
+                        break;
+                }
             }
-            if (debounceTimer !== undefined)
-                clearTimeout(debounceTimer);
-            debounceTimer = setTimeout(() => {
-                translateY.value = value;
-            }, timeout);
         };
-        // Rebuild the interpolation whenever the layout / collision inputs change (the Vue twin of RN's
-        // effect, deps [measured, layoutY, layoutHeight, scrollViewHeight, nextHeaderLayoutY, inverted]).
-        // symbiote is always Fabric: listen to the settled value to keep the ShadowTree transform current
-        // for hit-testing (RN attaches this listener only under Fabric). scrollAnimatedValue is the stable
-        // const (RN lists it in deps; it never changes for one ScrollView, so the const is faithful).
-        watchEffect(onCleanup => {
-            const inverted = typeof attrs.inverted === 'boolean' ? attrs.inverted : undefined;
-            const scrollViewHeight = typeof attrs.scrollViewHeight === 'number' ? attrs.scrollViewHeight : undefined;
-            const nextHeaderLayoutY = typeof attrs.nextHeaderLayoutY === 'number' ? attrs.nextHeaderLayoutY : undefined;
-            const { inputRange, outputRange } = computeStickyInterpolation({
-                measured: measured.value,
-                inverted,
-                scrollViewHeight,
-                layoutY: layoutY.value,
-                layoutHeight: layoutHeight.value,
-                nextHeaderLayoutY,
-            });
-            const interpolation = scrollAnimatedValue.interpolate({ inputRange, outputRange });
-            const listenerId = interpolation.addListener(animatedValueListener);
-            animatedTranslateY.value = interpolation;
-            onCleanup(() => {
+        const dispatch = (action) => {
+            runEffects(reduceSticky(state, action, inputs()).effects);
+        };
+        // Rebuild whenever the collision/viewport inputs change ([inverted, scrollViewHeight,
+        // nextHeaderLayoutY]); also runs once on mount.
+        watchEffect(() => {
+            dispatch({ kind: 'inputs-changed' });
+        });
+        onBeforeUnmount(() => {
+            if (interpolation !== undefined && listenerId !== undefined) {
                 interpolation.removeListener(listenerId);
-                if (debounceTimer !== undefined)
-                    clearTimeout(debounceTimer);
-            });
+            }
+            if (debounceTimer !== undefined)
+                clearTimeout(debounceTimer);
         });
-        // Stable function ref (defined once, not re-created per render): record own y/height, mark
-        // measured, fire the wrapper's recorder (onHeaderLayoutY, in attrs.onLayout), then the child's
-        // own onLayout. Matches RN ScrollViewStickyHeader.js._onLayout order.
+        // Dispatch the layout, fire the wrapper's recorder (onHeaderLayoutY via attrs.onLayout), then
+        // the child's own onLayout. Matches RN ScrollViewStickyHeader.js._onLayout.
         const onLayout = (event) => {
             const y = readLayoutNumber(event, 'y');
             const height = readLayoutNumber(event, 'height');
-            if (y !== undefined)
-                layoutY.value = y;
-            if (height !== undefined)
-                layoutHeight.value = height;
-            measured.value = true;
+            // Keep the previous value when a field is absent (RN sets state only on a defined read).
+            dispatch({ kind: 'layout', y: y ?? state.layoutY, height: height ?? state.layoutHeight });
             const recorder = attrs.onLayout;
             if (isHandler(recorder))
                 recorder(event);
@@ -132,14 +135,15 @@ export const ScrollViewStickyHeader = defineComponent({
                 childOnLayout(event);
         };
         return () => {
+            // Read the version bump so a committed translateY re-runs render.
+            void version.value;
             // The EXPLICIT debounced translateY overrides the committed transform for hit-testing, while
-            // `animatedTranslateY` does the smooth (native-driven) pin. See RN ScrollViewStickyHeader.js.
-            const passthroughAnimatedPropExplicitValues = translateY.value !== null
-                ? { style: { transform: [{ translateY: translateY.value }] } }
+            // animatedTranslateY does the smooth (native-driven) pin.
+            const passthroughAnimatedPropExplicitValues = state.translateY !== null
+                ? { style: { transform: [{ translateY: state.translateY }] } }
                 : null;
             // collapsable:false keeps the wrapper a real Yoga node; zIndex makes the pinned header paint
-            // OVER the rows scrolling under it. The interpolation node passes inside the transform; the
-            // Animated wrapper's reduceProps rasterizes it into a numeric translateY for the committed tree.
+            // OVER the rows scrolling under it.
             return h(Animated.View, {
                 style: {
                     transform: [{ translateY: animatedTranslateY.value }],
@@ -153,15 +157,13 @@ export const ScrollViewStickyHeader = defineComponent({
     },
 });
 // Wrap each child flagged by `stickyHeaderIndices` in the sticky header component, fed by the
-// shared scroll AnimatedValue. Mirrors ScrollView.js's render-time children.map (~line 1690) and
-// the React adapter's wrapStickyHeaders. Returns the children unchanged when no indices are flagged.
+// shared scroll AnimatedValue. Returns the children unchanged when no indices are flagged.
 //
-// Cross-talk plumbing (RN's _headerLayoutYs + _onStickyHeaderLayout, ScrollView.js:1115-1143):
-// `headerLayoutYs` is a child-index→measured-y map the parent keeps; each header reports its own y
-// through `onHeaderLayoutY` as it measures, and we feed every header the y of the NEXT flagged
-// header (the collision point past which it scrolls off) by looking up its successor's index in
-// `stickyHeaderIndices`. The LAST flagged header has no successor, so its `nextHeaderLayoutY` stays
-// undefined and it sticks indefinitely (correct).
+// Cross-talk plumbing (RN's _headerLayoutYs + _onStickyHeaderLayout): headerLayoutYs is a
+// child-index -> measured-y map; each header reports its own y through onHeaderLayoutY, and we
+// feed every header the y of the NEXT flagged header (the collision point past which it scrolls
+// off). The LAST flagged header has no successor, so its nextHeaderLayoutY stays undefined and
+// it sticks indefinitely (correct).
 export function wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedValue, invertStickyHeaders, scrollViewHeight, StickyHeaderComponent, headerLayoutYs, onHeaderLayoutY) {
     if (stickyHeaderIndices === undefined || stickyHeaderIndices.length === 0)
         return children;
@@ -170,17 +172,15 @@ export function wrapStickyHeaders(children, stickyHeaderIndices, scrollAnimatedV
         const indexOfIndex = stickyHeaderIndices.indexOf(index);
         if (indexOfIndex === -1 || !isVNode(child))
             return child;
-        // The next flagged header's measured y, by index order in stickyHeaderIndices (RN
-        // ScrollView.js:1695 nextIndex). undefined until that header has measured (or for the last).
+        // The next flagged header's measured y. undefined until that header has measured (or for the last).
         const nextIndex = stickyHeaderIndices[indexOfIndex + 1];
         const nextHeaderLayoutY = nextStickyHeaderY(stickyHeaderIndices, indexOfIndex, headerLayoutYs);
         dlog(`Vue ScrollView sticky-header wrap index=${index} next=${nextIndex} nextY=${nextHeaderLayoutY}`);
         const props = {
             key: child.key ?? `sticky-${index}`,
             nextHeaderLayoutY,
-            // RN _onStickyHeaderLayout: record this header's own y, then push it to the previous header as
-            // its nextHeaderLayoutY. We record into the parent map; the lookup above feeds it forward on
-            // the resulting re-render (the headerLayoutYs bump in scroll-view-shared).
+            // Record this header's own y into the parent map; the lookup above feeds it forward to the
+            // previous header on the resulting re-render (the headerLayoutYs bump in scroll-view-shared).
             onLayout: (event) => {
                 const y = readLayoutNumber(event, 'y');
                 if (y !== undefined)

package/build/components/section-list/index.js

@@ -1,21 +1,18 @@
 // SectionList, the Vue public list-of-sections component. A thin wrapper over
 // VirtualizedSectionList, mirroring RN's layering (SectionList -> VirtualizedSectionList ->
-// VirtualizedList). All section-flattening / windowing / imperative-scroll logic lives below;
-// this layer re-exposes the same surface under the SectionList name and re-exposes the handle
-// (Vue resolves a parent ref to the exposed object, so the wrapper delegates). The Vue twin of
-// the React adapter's SectionList.
+// VirtualizedList). All section-flattening/windowing/imperative-scroll logic lives below; this
+// layer re-exposes the same surface and re-exposes the handle (Vue resolves a parent ref to the
+// exposed object, so the wrapper delegates).
 //
-// Typed-emits generic component (mirrors FlatList / VirtualizedList): a GENERIC setup function
-// `<ItemT,>(props: ISectionListProps<ItemT>, ctx: ICtx<ISectionListEmits>)` so the section inputs
-// (sections/renderItem/…) infer ItemT at the call site. As a pure forwarder it consumes nothing
-// itself — every input rides through $attrs straight onto VirtualizedSectionList; only the three
-// synthesized events (endReached/startReached/refresh) are bridged, gated on listener presence so
-// the inner list keeps its RefreshControl / edge-reached gating.
+// Typed-emits generic component: a GENERIC setup function so section inputs infer ItemT at the
+// call site. As a pure forwarder it consumes nothing itself - every input rides through $attrs
+// straight onto VirtualizedSectionList; only the three synthesized events are bridged, gated on
+// listener presence so the inner list keeps its RefreshControl/edge-reached gating.
 import { defineComponent, getCurrentInstance, h, shallowRef, } from '@vue/runtime-core';
 import { VirtualizedSectionList, } from '../virtualized-section-list/index.js';
 import { normalizeVueAttrs } from '../../utils/normalize-attrs.js';
-// VirtualizedSectionList is a generic component (generic construct signature), which h()'s overloads
-// can't resolve. Drive it through a loose functional-component handle (generic-component h() limit).
+// VirtualizedSectionList's generic construct signature can't be resolved by h()'s overloads, so
+// drive it through a loose functional-component handle.
 const VirtualizedSectionListHost = VirtualizedSectionList;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -36,17 +33,15 @@ function buildDelegate(getInner) {
     };
 }
 export const SectionList = defineComponent(
-// _props is read only by the type system: ISectionListProps<ItemT> is what lets ItemT infer at
-// the call site. As a pure forwarder, SectionList consumes nothing at runtime — it spreads $attrs.
+// _props is read only by the type system, to let ItemT infer at the call site.
 (_props, { attrs, expose, emit, slots }) => {
     const inner = shallowRef(null);
     const setInner = (instance) => {
         inner.value = isSectionHandle(instance) ? instance : null;
     };
     expose(buildDelegate(() => inner.value));
-    // The three section-list events are emits, so Vue strips their onX listeners from $attrs. Detect
-    // listener presence off the instance's own vnode props and bridge each ONLY when listened, so
-    // the inner VirtualizedSectionList (and its inner VirtualizedList) keeps its on-demand gating.
+    // Emits are stripped from $attrs by Vue; detect listener presence off the instance's own
+    // vnode props and bridge each ONLY when listened.
     const instance = getCurrentInstance();
     const listens = (onName) => {
         const vnodeProps = instance?.vnode.props;
@@ -60,8 +55,6 @@ export const SectionList = defineComponent(
             ? (info) => emit('startReached', info)
             : undefined;
         const refresh = listens('onRefresh') ? () => emit('refresh') : undefined;
-        // Pure forwarder: spread $attrs as props and pass the consumer's scoped slots (#item /
-        // #sectionHeader / … ) straight down to VirtualizedSectionList untouched.
         return h(VirtualizedSectionListHost, {
             ...normalizeVueAttrs(attrs),
             ref: setInner,

package/build/components/switch/shared.js

@@ -1,14 +1,12 @@
-// Switch, the Vue lifecycle half. The logic (the lastNativeReport reducer, valueFromChange,
-// the snap-back decision) lives in @symbiote-native/components/state and the render in
-// @symbiote-native/components/view, both shared verbatim with the React adapter. Here Vue supplies
-// the reactivity: a ref holds what native last reported, a function ref grabs the host node,
-// and a post-flush watch snaps native back when the parent rejects a toggle. This is the Vue
-// twin of the React adapter's useReducer + useLayoutEffect + dispatchViewCommand.
+// Switch, the Vue lifecycle half. The logic (lastNativeReport reducer, valueFromChange, the
+// snap-back decision) lives in @symbiote-native/components/state and the render in
+// @symbiote-native/components/view, both shared verbatim with React. Vue supplies the
+// reactivity: a ref holds what native last reported, a function ref grabs the host node, and a
+// post-flush watch snaps native back when the parent rejects a toggle.
 //
-// Inputs arrive as attrs (untyped), so each is narrowed with a runtime guard rather than a
-// cast. onValueChange MUST be stripped from the forwarded attrs: it is not a ViewConfig event
-// (it's derived from the native onChange), so leaking it would reach Fabric as a function prop
-// and crash Android's folly::dynamic.
+// Inputs arrive as attrs (untyped), so each is narrowed with a runtime guard, never a cast.
+// onValueChange MUST be stripped from the forwarded attrs: it is not a ViewConfig event, so
+// leaking it would reach Fabric as a function prop and crash Android's folly::dynamic.
 import { defineComponent, ref, shallowRef, watch } from '@vue/runtime-core';
 import { renderSwitch, switchReducer, createInitialSwitchState, shouldSnapBack, valueFromChange, } from '@symbiote-native/components';
 import { dispatchViewCommand, isSymbioteNode, dlog, } from '@symbiote-native/engine';
@@ -24,7 +22,6 @@ function asString(value) {
 function isBoolean(value) {
     return typeof value === 'boolean';
 }
-// trackColor arrives untyped; keep only the string false/true entries the render fn reads.
 function normalizeTrackColor(value) {
     if (!isRecord(value))
         return undefined;
@@ -36,12 +33,11 @@ function normalizeTrackColor(value) {
     return trackColor;
 }
 // The render fn's style param is a plain object; array/registered styles degrade to undefined
-// (the engine flattens those on its own). Same narrowing the Vue ActivityIndicator uses.
+// (the engine flattens those on its own).
 function isViewStyleObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-// The prop/handler keys the lifecycle consumes itself; everything else (accessibility,
-// testID, …) forwards onto the host node. onValueChange is pure JS and must never reach Fabric.
+// Everything else forwards onto the host node. onValueChange is pure JS and must never reach Fabric.
 const HANDLED_ATTRS = [
     'value',
     'modelValue',
@@ -62,22 +58,15 @@ function forwardAttrs(attrs) {
 }
 export function createSwitch(platform) {
     return defineComponent((_props, { attrs: rawAttrs, emit }) => {
-        // shallowRef, NOT ref: the engine node must be held by IDENTITY. A plain ref() runs the
-        // assigned object through Vue's toReactive(), so reading nodeRef.value back yields a
-        // reactive Proxy, a different object than the raw node. The engine's mirror is a WeakMap
-        // keyed on the raw node, so every imperative command (dispatchViewCommand / measure /
-        // setNativeProps) would miss on the Proxy and silently no-op. shallowRef stores the raw
-        // node untouched. General rule for this adapter: host nodes live in shallowRef / markRaw.
+        // shallowRef, NOT ref: a plain ref() would hand back a reactive Proxy the engine's WeakMap
+        // mirror doesn't recognize, so every imperative command would silently no-op. General rule
+        // for this adapter: host nodes live in shallowRef / markRaw.
         const nodeRef = shallowRef(null);
         const state = ref(createInitialSwitchState());
-        // The host node our Vue renderer creates IS an engine SymbioteNode; Vue hands it to this
-        // function ref on mount. A stable function ref (defined once) isn't re-invoked per patch.
         const setNodeRef = (el) => {
             nodeRef.value = isSymbioteNode(el) ? el : null;
         };
         const handleChange = (event) => {
-            // Vue-facing event is emitted here; the host still receives this internal onChange
-            // handler so the controlled snap-back state stays synchronized with native.
             const next = valueFromChange(event);
             dlog(`Switch onChange value=${String(next)} eventCount=${String(event.nativeEvent.eventCount)}`);
             if (next === undefined)
@@ -86,11 +75,10 @@ export function createSwitch(platform) {
             emitModelUpdate(emit, next);
             state.value = switchReducer(state.value, { type: 'native-reported', value: next });
         };
-        // Snap-back: when native reported a value the parent rejected (the value prop did not
-        // change), command the JS value back down: the controlled-Switch correction RN does via
-        // SwitchCommands.setValue. The decision is shared with React (shouldSnapBack); only the
-        // command name is platform-imperative. flush:'post' so the engine has committed the node
-        // before the command reads its Fabric handle.
+        // Snap-back: when native reported a value the parent rejected, command the JS value back
+        // down (the controlled-Switch correction RN does via SwitchCommands.setValue). The
+        // decision is shared with React (shouldSnapBack); only the command name is platform-
+        // imperative. flush:'post' so the node is committed before the command reads its Fabric handle.
         watch(() => ({
             fabricValue: resolveModelValue(rawAttrs, isBoolean) === true,
             switchState: state.value,

package/build/components/text-input/index.js

@@ -1,17 +1,13 @@
-// TextInput, the Vue lifecycle half. The folds/maps (value->text, the W3C/alias resolution)
-// and the controlled-write predicate live in @symbiote-native/components/state, the render (intrinsic
-// + native-prop mapping) in @symbiote-native/components/view, both shared verbatim with the React
-// adapter. Here Vue supplies only the reactivity: a shallowRef holds the host node, a ref holds
-// the acknowledged event count (so the exposed handle echoes the latest), setup-scope `let`s
-// hold the last native text + focus flag, a post-flush watch runs the controlled-write command,
-// and expose() wires the imperative handle. The Vue twin of the React useState/useRef +
-// useLayoutEffect + useImperativeHandle.
+// TextInput, the Vue lifecycle half. The folds/maps (value->text, W3C/alias resolution) and the
+// controlled-write predicate live in @symbiote-native/components/state, the render in
+// @symbiote-native/components/view, both shared verbatim with React. Vue supplies only the
+// reactivity: a shallowRef holds the host node, a ref holds the acknowledged event count, setup-
+// scope `let`s hold the last native text + focus flag, a post-flush watch runs the
+// controlled-write command, and expose() wires the imperative handle.
 //
-// Inputs arrive as attrs (untyped), so each is narrowed with a runtime guard rather than a cast.
-// onValueChange MUST be stripped from the forwarded attrs: it is not a ViewConfig event (it's
-// derived from the native onChange), so leaking it would reach Fabric as a function prop and
-// crash Android's folly::dynamic. The imperative module (blurTextInput / setInput*) is imported
-// from @symbiote-native/engine, the same framework-agnostic singleton both adapters share.
+// Inputs arrive as attrs (untyped), so each is narrowed with a runtime guard, never a cast.
+// onValueChange MUST be stripped from the forwarded attrs: it is not a ViewConfig event, so
+// leaking it would reach Fabric as a function prop and crash Android's folly::dynamic.
 import { defineComponent, onBeforeUnmount, ref, shallowRef, watch } from '@vue/runtime-core';
 import { resolveAccessibilityProps, resolveTextInputProps, renderTextInput, foldText, textFromChange, eventCountFromChange, shouldCommandText, INITIAL_EVENT_COUNT, SELECTION_NONE, } from '@symbiote-native/components';
 import { dispatchViewCommand, isSymbioteNode, dlog, blurTextInput, setInputFocused, setInputBlurred, whenCommitted, } from '@symbiote-native/engine';
@@ -30,7 +26,6 @@ function isString(value) {
 function asBoolean(value) {
     return typeof value === 'boolean' ? value : undefined;
 }
-// selection arrives untyped; keep only the numeric start/end the render fn + controlled write read.
 function normalizeSelection(value) {
     if (!isRecord(value))
         return undefined;
@@ -41,9 +36,7 @@ function normalizeSelection(value) {
         selection.end = value.end;
     return selection;
 }
-// The prop/handler keys the lifecycle consumes itself (mirrors the React adapter's destructure);
-// everything else (placeholder, secureTextEntry, the remaining native events, accessibility,
-// testID, style…) forwards onto the host node. onFocus/onBlur are re-supplied as our wrapped
+// Everything else forwards onto the host node. onFocus/onBlur are re-supplied as our wrapped
 // handlers; onValueChange is pure JS and must never reach Fabric.
 const HANDLED_ATTRS = [
     'value',
@@ -80,38 +73,30 @@ function forwardAttrs(attrs) {
     return result;
 }
 export const TextInput = defineComponent((_props, { attrs: rawAttrs, emit, expose }) => {
-    // shallowRef, NOT ref: the engine node must be held by IDENTITY. A plain ref() runs the node
-    // through Vue's toReactive(), handing back a reactive Proxy, a different object than the raw
-    // node the engine's WeakMap mirror is keyed on, so every imperative command
-    // (dispatchViewCommand / focus / blur / setTextAndSelection) would miss and silently no-op.
-    // Same rule applies to the Switch / ScrollView host node.
+    // shallowRef, NOT ref: a plain ref() would hand back a reactive Proxy the engine's WeakMap
+    // mirror doesn't recognize, so every imperative command would silently no-op. Same rule as
+    // the Switch / ScrollView host node.
     const nodeRef = shallowRef(null);
     const setNodeRef = (el) => {
         nodeRef.value = isSymbioteNode(el) ? el : null;
     };
-    // The count native last acknowledged. A ref so the render echoes it back as
-    // mostRecentEventCount and the exposed handle reads the latest; the controlled write commands
-    // it so native's eventLag lands on 0.
+    // The count native last acknowledged. A ref so render echoes it as mostRecentEventCount; the
+    // controlled write commands it so native's eventLag lands on 0.
     const mostRecentEventCount = ref(INITIAL_EVENT_COUNT);
-    // The last text native holds, as far as JS knows. Seeded from the mount-time value (the `text`
-    // prop already carries it down via createNode, so the FIRST controlled value is not a
-    // divergence and must NOT re-command). A setup-scope `let`: no render needed when it changes.
+    // Seeded from the mount-time value (the `text` prop already carries it down via createNode,
+    // so the FIRST controlled value is not a divergence and must NOT re-command).
     let lastNativeText = foldText(resolveModelValue(rawAttrs, isString), asString(rawAttrs.defaultValue));
-    // JS-side focus state, mirrored from the focus/blur events for isFocused(): native exposes no
-    // synchronous focus getter (RN's TextInputState holds the same).
+    // Mirrored from focus/blur events for isFocused(): native exposes no synchronous focus getter.
     let focused = false;
-    // autoFocus fires once when the node first commits; guard so a later node identity change does
-    // not re-focus.
+    // Guard so a later node identity change does not re-focus.
     let autoFocused = false;
     const handleChange = (event) => {
-        // Event seam: the controlled handshake hinges on the change payload carrying `text`
-        // (+ `eventCount`). iOS and Android Fabric can key these differently, so log the actual shape.
+        // iOS and Android Fabric can key the change payload differently, so log the actual shape.
         dlog(`TextInput change keys=[${Object.keys(event.nativeEvent).join(',')}] ` +
             `text=${JSON.stringify(event.nativeEvent.text)} count=${JSON.stringify(event.nativeEvent.eventCount)}`);
         const text = textFromChange(event);
         if (text !== undefined) {
-            // Record the text first, then the count, so the count never runs ahead of the text it
-            // stands for.
+            // Record the text first, so the count never runs ahead of the text it stands for.
             lastNativeText = text;
             emit('valueChange', text, event);
             emitModelUpdate(emit, text);
@@ -136,10 +121,8 @@ export const TextInput = defineComponent((_props, { attrs: rawAttrs, emit, expos
         emit('blur', event);
     };
     // Controlled write: when JS-side `value` diverges from what native reported, command the new
-    // text down with the acknowledged count; a plain prop re-push would race the user's
-    // keystrokes. Watching `value` covers every divergence (the parent only rewrites `value` after
-    // a change). flush:'post' so the engine has committed the node before the command reads its
-    // Fabric handle; the predicate makes it a no-op on mount (value === the seed).
+    // text down with the acknowledged count - a plain prop re-push would race the user's
+    // keystrokes. flush:'post' so the node is committed before the command reads its Fabric handle.
     watch(() => resolveModelValue(rawAttrs, isString), value => {
         const node = nodeRef.value;
         if (node === null)
@@ -158,11 +141,10 @@ export const TextInput = defineComponent((_props, { attrs: rawAttrs, emit, expos
         ]);
         lastNativeText = value;
     }, { flush: 'post' });
-    // autoFocus is driven in JS, not as a native prop: once the node first commits, command `focus`
-    // down once (RN does the same via TextInputState.focusInput). The watch fires when nodeRef is
-    // set (mount), but under Vue's async-batched commit the node has no Fabric tag yet at post-flush,
-    // so the focus command would be skipped with no retry. whenCommitted defers it to the commit that
-    // assigns the tag. Cancelled on unmount so an un-committed pending focus can't leak.
+    // autoFocus is driven in JS: once the node first commits, command `focus` down once. Under
+    // Vue's async-batched commit the node has no Fabric tag yet at post-flush, so
+    // whenCommitted defers it to the commit that assigns the tag. Cancelled on unmount so an
+    // un-committed pending focus can't leak.
     let cancelAutoFocus;
     watch(nodeRef, node => {
         if (autoFocused || node === null || rawAttrs.autoFocus !== true)
@@ -172,10 +154,8 @@ export const TextInput = defineComponent((_props, { attrs: rawAttrs, emit, expos
         cancelAutoFocus = whenCommitted(node, () => dispatchViewCommand(node, 'focus', []));
     }, { flush: 'post' });
     onBeforeUnmount(() => cancelAutoFocus?.());
-    // The imperative API RN exposes on the ref. The methods read nodeRef.value / the count LIVE,
-    // so no stale capture: the Vue twin of React's useImperativeHandle. focus/blur drive native
-    // view commands; clear and setSelection reuse setTextAndSelection (the same stale-safe path as
-    // a controlled write) echoing the acknowledged event count.
+    // Methods read nodeRef.value / the count LIVE, so no stale capture. clear/setSelection reuse
+    // setTextAndSelection, the same path as a controlled write.
     expose({
         focus: () => {
             const node = nodeRef.value;