@symbiote-native/vue 0.4.0 → 0.5.0

package/build/components/touchable.js

@@ -1,26 +1,35 @@
-// The Touchable* family for Vue, all built on Pressable, the Vue twin of the React adapter. The
-// press-timing constants and the deactivation-floor math are shared with React
-// (@symbiote-native/components/state/touchable); here Vue owns only the Animated wiring + the press
-// scheduling state:
-//   TouchableOpacity: animate an Animated.Value opacity toward activeOpacity on press-in, back
-//     to 1 on press-out, driven from Pressable's onPressIn/onPressOut.
-//   TouchableHighlight: paint underlayColor + lower child opacity while pressed, via Pressable's
-//     style-as-function (the pressed state RN drives with setState).
-//   TouchableWithoutFeedback: no visual change, just the press wiring.
+// The Touchable* family for Vue, all built on Pressable. Ported against RN's own sources
+// (.vendors/react-native/.../Components/Touchable/*.js) after the 2026-08-19 audit found ten
+// divergences shared by the React/Vue/Svelte/Angular ports; Solid migrated first, this is Vue.
+//
+// Shared (framework-agnostic) half: the press-scheduling machine, the underlay machine, the
+// resting-opacity math, the press-handler gate, the extra-style split. Vue owns only the
+// lifecycle — refs, the real timers, the Animated wiring, and the emit bridge:
+//   TouchableOpacity: an Animated.Value fading toward activeOpacity on press-in and back to the
+//     style's own opacity on press-out.
+//   TouchableHighlight: the underlay machine flipping a `shown` ref; underlayColor lands on the
+//     container, the lowered opacity on the cloned child.
+//   TouchableWithoutFeedback: the same press-scheduling machine with the visual half empty.
 //
 // Inputs arrive as attrs (untyped), narrowed with runtime guards. The handlers read attrs LIVE
 // (they fire on events, not render) so a re-supplied callback / timing is always honored.
-import { defineComponent, h } from '@vue/runtime-core';
-import { createTouchableFeedbackHandlers, createTouchableFeedbackRuntime, highlightPressedStyle, DEFAULT_ACTIVE_OPACITY, DEFAULT_HIGHLIGHT_CHILD_OPACITY, DEFAULT_MIN_PRESS_DURATION_MS, DEFAULT_UNDERLAY_COLOR, OPACITY_ACTIVE_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, RESTING_OPACITY, } from '@symbiote-native/components';
-import {} from '@symbiote-native/engine';
+import { cloneVNode, defineComponent, getCurrentInstance, h, onUnmounted, ref, watch, } from '@vue/runtime-core';
+import { createHighlightUnderlayHandlers, createHighlightUnderlayRuntime, createTouchableFeedbackHandlers, createTouchableFeedbackRuntime, hasTouchablePressHandler, resolveHighlightExtraStyles, restingOpacityFromStyle, DEFAULT_ACTIVE_OPACITY, OPACITY_ACTIVE_GRANT_DURATION_MS, OPACITY_INACTIVE_DURATION_MS, TOUCHABLE_MIN_PRESS_DURATION_MS, } from '@symbiote-native/components';
+import { dlog, } from '@symbiote-native/engine';
 import { Pressable, emitPressableEvents, PRESSABLE_EMITS, } from './pressable.js';
 import { Animated } from '../modules/animated/index.js';
 import { normalizeVueAttrs } from '../utils/normalize-attrs.js';
+const TOUCHABLE_HIGHLIGHT_EMITS = {
+    ...PRESSABLE_EMITS,
+    showUnderlay: () => true,
+    hideUnderlay: () => true,
+};
 function numberOr(value, fallback) {
     return typeof value === 'number' ? value : fallback;
 }
-// The real setTimeout the shared feedback machine schedules its deferred activation/deactivation on
-// (core/components has no timer globals). Returns a canceller so an early release flushes the timer.
+// The real setTimeout the shared machines schedule their deferred activation/deactivation/underlay
+// hide on (core/components has no timer globals). Returns a canceller so an early release flushes
+// the timer.
 function scheduleTimeout(callback, ms) {
     const id = setTimeout(callback, ms);
     return () => clearTimeout(id);
@@ -44,20 +53,41 @@ const TOUCHABLE_OPACITY_HANDLED = [
     'minPressDuration',
 ];
 export const TouchableOpacity = defineComponent((_props, { slots, attrs: rawAttrs, emit }) => {
-    // One Animated.Value per mount, resting at full opacity. Held by identity in setup scope (an
-    // engine object, never a reactive ref). The Animated.View leaf commits it every frame.
-    const opacity = new Animated.Value(RESTING_OPACITY);
+    // RN's _getChildStyleOpacityWithDefault: the fade settles at the opacity the CALLER's style
+    // asks for, not at a hard 1 — and the Animated.Value is SEEDED there, or the first paint jumps
+    // to fully opaque on a Touchable styled `opacity: 0.6`.
+    const restingOpacity = () => restingOpacityFromStyle(normalizeVueAttrs(rawAttrs).style);
+    // One Animated.Value per mount. Held by identity in setup scope (an engine object, never a
+    // reactive ref — a Proxy would miss the graph's bookkeeping). The Animated.View leaf commits
+    // it every frame.
+    const opacity = new Animated.Value(restingOpacity());
     // The shared press-scheduling cell (delayPressIn timer + activation clock), persisted across
     // renders in setup scope; the handlers are rebuilt each render over live attrs.
     const runtime = createTouchableFeedbackRuntime();
     function setOpacityTo(toValue, duration) {
+        dlog(`TouchableOpacity opacity -> ${toValue} over ${duration}ms`);
+        // useNativeDriver: true is RN's own (TouchableOpacity.js:242). opacity is natively drivable,
+        // so the fade survives a busy JS thread — the whole point of press feedback.
         Animated.timing(opacity, {
             toValue,
             duration,
             easing: Animated.Easing.inOut(Animated.Easing.quad),
-            useNativeDriver: false,
+            useNativeDriver: true,
         }).start();
     }
+    // RN's componentDidUpdate: a changed `disabled` or a changed style opacity re-settles the view,
+    // so a Touchable disabled mid-press does not stay stuck at its active opacity. NO `immediate` —
+    // RN does this on UPDATE only, and firing at mount would animate over the value the
+    // Animated.Value was just seeded with. Two getter sources, not one object: Vue compares an
+    // array source element-wise, so an unrelated attr change does not re-settle the opacity.
+    watch([() => normalizeVueAttrs(rawAttrs).disabled, restingOpacity], ([, resting]) => {
+        setOpacityTo(resting, OPACITY_INACTIVE_DURATION_MS);
+    });
+    // RN's componentWillUnmount: stop the animation and drop the value back, so a teardown
+    // mid-fade leaves no driver running against a node that is gone.
+    onUnmounted(() => {
+        opacity.resetAnimation();
+    });
     return () => {
         const attrs = normalizeVueAttrs(rawAttrs);
         const style = attrs.style;
@@ -66,16 +96,18 @@ export const TouchableOpacity = defineComponent((_props, { slots, attrs: rawAttr
         const { handlePressIn, handlePressOut } = createTouchableFeedbackHandlers({
             delayPressIn: numberOr(attrs.delayPressIn, 0),
             delayPressOut: numberOr(attrs.delayPressOut, 0),
-            minPressDuration: numberOr(attrs.minPressDuration, DEFAULT_MIN_PRESS_DURATION_MS),
+            // RN's Touchables override Pressability's 130ms floor with 0; what holds the active
+            // visual is the fade's own duration, not a press-duration floor.
+            minPressDuration: numberOr(attrs.minPressDuration, TOUCHABLE_MIN_PRESS_DURATION_MS),
             schedule: scheduleTimeout,
             now: Date.now,
         }, runtime, {
             activate(event) {
-                setOpacityTo(numberOr(attrs.activeOpacity, DEFAULT_ACTIVE_OPACITY), OPACITY_ACTIVE_DURATION_MS);
+                setOpacityTo(numberOr(attrs.activeOpacity, DEFAULT_ACTIVE_OPACITY), OPACITY_ACTIVE_GRANT_DURATION_MS);
                 emit('pressIn', event);
             },
             deactivate(event) {
-                setOpacityTo(RESTING_OPACITY, OPACITY_INACTIVE_DURATION_MS);
+                setOpacityTo(restingOpacity(), OPACITY_INACTIVE_DURATION_MS);
                 emit('pressOut', event);
             },
         });
@@ -94,34 +126,150 @@ export const TouchableOpacity = defineComponent((_props, { slots, attrs: rawAttr
     inheritAttrs: false,
     emits: PRESSABLE_EMITS,
 });
-const TOUCHABLE_HIGHLIGHT_HANDLED = ['activeOpacity', 'underlayColor', 'style'];
+// delayPressOut is CONSUMED here (the underlay hold), so it must not also forward to the host.
+// onPress/onPressIn/onPressOut/onShowUnderlay/onHideUnderlay never appear in attrs at all — they
+// are declared emits, which Vue strips from $attrs.
+const TOUCHABLE_HIGHLIGHT_HANDLED = [
+    'activeOpacity',
+    'underlayColor',
+    'style',
+    'delayPressOut',
+];
+// A vnode that can carry a style prop: a host tag (string) or a component (object/function).
+// Fragment / Text / Comment / Static are Symbols and fail all three — cloning one with a style
+// would silently drop it.
+function isStylableVNode(vnode) {
+    const type = vnode.type;
+    return (typeof type === 'string' ||
+        typeof type === 'function' ||
+        (typeof type === 'object' && type !== null));
+}
 export const TouchableHighlight = defineComponent((_props, { slots, attrs: rawAttrs, emit }) => {
+    // `shown` is NOT `pressed`: RN holds the underlay for delayPressOut past the tap so a fast tap
+    // still flashes, and the pressed flag is already false by then.
+    const shown = ref(false);
+    // The mutable underlay cell (the in-flight hide canceller). A plain setup-scope object, never
+    // a ref: the machine mutates it on every event and nothing reads it reactively.
+    const runtime = createHighlightUnderlayRuntime();
+    // The press callbacks are declared emits, so Vue has stripped their onX listeners from $attrs.
+    // RN's _hasPressHandler gate therefore reads what the PARENT actually passed, off the
+    // instance's own vnode props — the same shape FlatList/VirtualizedList use for this.
+    const instance = getCurrentInstance();
+    const listener = (onName) => {
+        const vnodeProps = instance?.vnode.props;
+        return vnodeProps == null ? undefined : vnodeProps[onName];
+    };
     return () => {
         const attrs = normalizeVueAttrs(rawAttrs);
-        const activeOpacity = numberOr(attrs.activeOpacity, DEFAULT_HIGHLIGHT_CHILD_OPACITY);
-        const underlayColor = typeof attrs.underlayColor === 'string' ? attrs.underlayColor : DEFAULT_UNDERLAY_COLOR;
-        const style = attrs.style;
-        function pressedStyle({ pressed }) {
-            return highlightPressedStyle(pressed, style, underlayColor, activeOpacity);
-        }
+        const hasPressHandler = hasTouchablePressHandler({
+            onPress: listener('onPress'),
+            onPressIn: listener('onPressIn'),
+            onPressOut: listener('onPressOut'),
+            onLongPress: listener('onLongPress'),
+        });
+        // Rebuilt each render over live attrs; the runtime persists, so an in-flight hide timer
+        // survives a rebuild.
+        const underlay = createHighlightUnderlayHandlers({
+            delayPressOut: numberOr(attrs.delayPressOut, 0),
+            hasPressHandler,
+            schedule: scheduleTimeout,
+        }, runtime, {
+            setShown: next => {
+                shown.value = next;
+            },
+            onShowUnderlay: () => emit('showUnderlay'),
+            onHideUnderlay: () => emit('hideUnderlay'),
+        });
+        const extra = resolveHighlightExtraStyles({
+            shown: shown.value,
+            hasPressHandler,
+            underlayColor: typeof attrs.underlayColor === 'string'
+                ? attrs.underlayColor
+                : undefined,
+            activeOpacity: typeof attrs.activeOpacity === 'number'
+                ? attrs.activeOpacity
+                : undefined,
+        });
+        const children = slots.default !== undefined ? slots.default() : [];
+        // RN's _createExtraStyles split: the backgroundColor on the CONTAINER, the lowered opacity
+        // on the CHILD (TouchableHighlight.js clones its single child). Vue can reach the child
+        // without a wrapper node — cloneVNode merges the style onto exactly one existing vnode, so
+        // nothing is inserted into the flex chain. It needs RN's own single-element-child shape
+        // though (React.Children.only): a fragment, a raw text node or several roots have no one
+        // child to clone, and there both styles fold onto the container — the pre-audit
+        // approximation, where the opacity fades the very underlay it should reveal.
+        const onlyChild = children.length === 1 && children[0] !== undefined
+            ? children[0]
+            : undefined;
+        const canStyleChild = onlyChild !== undefined && isStylableVNode(onlyChild);
+        const styledChildren = extra !== undefined && canStyleChild && onlyChild !== undefined
+            ? [cloneVNode(onlyChild, { style: extra.child })]
+            : children;
+        const containerStyle = extra === undefined
+            ? attrs.style
+            : canStyleChild
+                ? [attrs.style, extra.underlay]
+                : [attrs.style, extra.underlay, extra.child];
         const pressableProps = {
             ...forwardExcept(attrs, TOUCHABLE_HIGHLIGHT_HANDLED),
             ...emitPressableEvents(emit),
-            style: pressedStyle,
+            style: containerStyle,
+            // Visual first, then the caller's callback — RN's order in _createPressabilityConfig.
+            onPress: (event) => {
+                underlay.handlePress(event);
+                emit('press', event);
+            },
+            onPressIn: (event) => {
+                underlay.handlePressIn(event);
+                emit('pressIn', event);
+            },
+            onPressOut: (event) => {
+                underlay.handlePressOut(event);
+                emit('pressOut', event);
+            },
         };
-        const children = slots.default !== undefined ? slots.default() : [];
-        return h(Pressable, pressableProps, { default: () => children });
+        return h(Pressable, pressableProps, { default: () => styledChildren });
     };
 }, {
     name: 'TouchableHighlight',
     inheritAttrs: false,
-    emits: PRESSABLE_EMITS,
+    emits: TOUCHABLE_HIGHLIGHT_EMITS,
 });
+// RN's TouchableWithoutFeedback builds a FULL Pressability config — "without feedback" means no
+// VISUAL, not no timing — so the delay props are consumed by the shared machine here instead of
+// forwarding to the host as unknown Fabric props.
+const TOUCHABLE_WITHOUT_FEEDBACK_HANDLED = [
+    'delayPressIn',
+    'delayPressOut',
+    'minPressDuration',
+];
 export const TouchableWithoutFeedback = defineComponent((_props, { slots, attrs: rawAttrs, emit }) => {
+    const runtime = createTouchableFeedbackRuntime();
     return () => {
         const attrs = normalizeVueAttrs(rawAttrs);
+        // The same machine TouchableOpacity runs, with the visual half left empty.
+        const { handlePressIn, handlePressOut } = createTouchableFeedbackHandlers({
+            delayPressIn: numberOr(attrs.delayPressIn, 0),
+            delayPressOut: numberOr(attrs.delayPressOut, 0),
+            minPressDuration: numberOr(attrs.minPressDuration, TOUCHABLE_MIN_PRESS_DURATION_MS),
+            schedule: scheduleTimeout,
+            now: Date.now,
+        }, runtime, {
+            activate(event) {
+                emit('pressIn', event);
+            },
+            deactivate(event) {
+                emit('pressOut', event);
+            },
+        });
+        const pressableProps = {
+            ...forwardExcept(attrs, TOUCHABLE_WITHOUT_FEEDBACK_HANDLED),
+            ...emitPressableEvents(emit),
+            onPressIn: handlePressIn,
+            onPressOut: handlePressOut,
+        };
         const children = slots.default !== undefined ? slots.default() : [];
-        return h(Pressable, { ...attrs, ...emitPressableEvents(emit) }, { default: () => children });
+        return h(Pressable, pressableProps, { default: () => children });
     };
 }, {
     name: 'TouchableWithoutFeedback',

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

@@ -27,7 +27,7 @@
 // scroll commands would silently no-op. The folded listState is a PLAIN object (not reactive) —
 // mutating it never triggers Vue; the `version` ref is bumped when a transition changes render state.
 import { computed, defineComponent, getCurrentInstance, h, isVNode, onBeforeUnmount, ref, shallowRef, watch, } from '@vue/runtime-core';
-import { DEFAULT_END_REACHED_THRESHOLD, DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_START_REACHED_THRESHOLD, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_WINDOW_SIZE, EMPTY_OFFSET, FIRST_INDEX, INVERTED_X_STYLE, INVERTED_Y_STYLE, buildListPlan, buildViewabilityPairs, createInitialListState, isSeparatorGapInRange, listEffectSignature, readLayoutLength, readScrollOffset, reduceList, resolveItemKey, } from '@symbiote-native/components';
+import { DEFAULT_END_REACHED_THRESHOLD, DEFAULT_INITIAL_NUM_TO_RENDER, DEFAULT_MAX_TO_RENDER_PER_BATCH, DEFAULT_START_REACHED_THRESHOLD, DEFAULT_UPDATE_CELLS_BATCHING_PERIOD, DEFAULT_WINDOW_SIZE, EMPTY_OFFSET, FIRST_INDEX, INVERTED_X_STYLE, INVERTED_Y_STYLE, buildListPlan, buildViewabilityPairs, createInitialListState, isSeparatorGapInRange, listEffectSignature, readLayoutLength, readLayoutOffset, readScrollOffset, reduceList, resolveItemKey, } from '@symbiote-native/components';
 import { dlog, } from '@symbiote-native/engine';
 import { ScrollView } from '../scroll-view';
 import { RefreshControl } from '../refresh-control.js';
@@ -78,7 +78,7 @@ function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function isComponent(value) {
-    return typeof value === 'function' || (typeof value === 'object' && value !== null);
+    return (typeof value === 'function' || (typeof value === 'object' && value !== null));
 }
 function asNumber(value, fallback) {
     return typeof value === 'number' ? value : fallback;
@@ -181,7 +181,9 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
                 ? (info) => emit('startReached', info)
                 : undefined,
             onStartReachedThreshold: asNumber(props.onStartReachedThreshold, DEFAULT_START_REACHED_THRESHOLD),
-            onRefresh: listens('onRefresh') ? () => emit('refresh') : undefined,
+            onRefresh: listens('onRefresh')
+                ? () => emit('refresh')
+                : undefined,
             refreshing: props.refreshing === true,
             progressViewOffset: props.progressViewOffset,
             onViewableItemsChanged: listens('onViewableItemsChanged')
@@ -351,13 +353,17 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
         const length = readLayoutLength(event, narrowed.value.horizontal);
         if (length === undefined)
             return;
-        dlog(`Vue VirtualizedList cell ${index} measured length=${length}`);
-        dispatch({ kind: 'measure', index, length });
+        const offset = readLayoutOffset(event, narrowed.value.horizontal);
+        dlog(`Vue VirtualizedList cell ${index} measured length=${length} offset=${offset ?? 'none'}`);
+        dispatch({ kind: 'measure', index, length, offset });
     };
     const mergeSeparator = (gapIndex, patch) => {
         if (!isSeparatorGapInRange(gapIndex, listState.metrics.count))
             return;
-        separatorOverrides.set(gapIndex, { ...separatorOverrides.get(gapIndex), ...patch });
+        separatorOverrides.set(gapIndex, {
+            ...separatorOverrides.get(gapIndex),
+            ...patch,
+        });
         separatorVersion.value += 1;
     };
     const makeSeparators = (index) => ({
@@ -440,7 +446,9 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
         dlog(`Vue VirtualizedList window [${m.first}, ${m.last}] of ${m.count} ` +
             `(offset=${listState.scrollOffset}, viewport=${listState.viewportLength}, rendered=${Math.max(0, m.last - m.first + 1)})`);
         const children = [];
-        const stickySet = p.stickyHeaderIndices !== undefined ? new Set(p.stickyHeaderIndices) : undefined;
+        const stickySet = p.stickyHeaderIndices !== undefined
+            ? new Set(p.stickyHeaderIndices)
+            : undefined;
         const header = resolveElement(p.listHeaderComponent);
         if (header !== undefined) {
             children.push(h('symbiote-view', { key: 'list-header' }, [header]));
@@ -463,13 +471,14 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
                 keyFor,
                 stickyIndices: stickySet,
                 hasHeader: header !== undefined,
-                hasSeparators: p.itemSeparatorComponent !== undefined,
             });
             renderedStickyIndices = plan.stickyChildPositions;
             if (plan.leadingExtent > EMPTY_OFFSET) {
                 children.push(h('symbiote-view', {
                     key: 'spacer-leading',
-                    style: p.horizontal ? { width: plan.leadingExtent } : { height: plan.leadingExtent },
+                    style: p.horizontal
+                        ? { width: plan.leadingExtent }
+                        : { height: plan.leadingExtent },
                 }));
             }
             const cellInverted = p.inverted
@@ -479,6 +488,14 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
                 : undefined;
             // Wraps one cell identically whether it's the force-mounted sticky cell ahead of the
             // window or an in-window cell from the loop below — same measuring View, same key shape.
+            // RN renders the separator INSIDE the cell's own measuring wrapper
+            // (VirtualizedListCellRenderer.js:218-221), and that placement is load-bearing rather than
+            // cosmetic. As a SIBLING it is an extra flex child, so the chrome between two cells becomes
+            // gap + separator + gap while a spacer collapsing that region replaces it with one gap —
+            // the leading spacer then lands every cell below it short by (separator + gap), and the
+            // content visibly jumps by that amount each time the window's first index moves. Measured
+            // at exactly 17px on device 2026-08-19 (a 1px divider under a 16px container gap); see
+            // .claude/rules/list-geometry-feedback-loop.md.
             const pushCell = (cell) => {
                 const item = p.getItem(p.data, cell.index);
                 const content = p.renderItem?.({
@@ -486,11 +503,20 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
                     index: cell.index,
                     separators: makeSeparators(cell.index),
                 });
+                const separator = 
+                // RN gates the separator on the last index of the DATA, not of the WINDOW
+                // (VirtualizedList.js:793 `const end = getItemCount(data) - 1`), and now that the separator
+                // lives INSIDE the measuring wrapper that distinction is load-bearing: gating on the window
+                // would make a cell's own measured height change as the window slides past it. Device-measured
+                // 2026-08-19 as a run of cells all shifting by exactly the divider's 1px.
+                cell.index < m.count - 1
+                    ? renderSeparatorElement(p.itemSeparatorComponent, item, p.getItem(p.data, cell.index + 1), separatorOverrides.get(cell.index))
+                    : undefined;
                 children.push(h('symbiote-view', {
                     key: `cell-${cell.key}`,
                     onLayout: makeCellMeasure(cell.index),
                     style: cellInverted,
-                }, [content]));
+                }, separator === undefined ? [content] : [content, separator]));
             };
             // The nearest sticky section header below the window (RN _ensureClosestStickyHeader):
             // force-mounted so it never gets destroyed/recreated while pinned off-window. Rendered
@@ -500,19 +526,14 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
                 if (plan.gapExtent > EMPTY_OFFSET) {
                     children.push(h('symbiote-view', {
                         key: 'spacer-gap',
-                        style: p.horizontal ? { width: plan.gapExtent } : { height: plan.gapExtent },
+                        style: p.horizontal
+                            ? { width: plan.gapExtent }
+                            : { height: plan.gapExtent },
                     }));
                 }
             }
             for (let cellPos = 0; cellPos < plan.cells.length; cellPos += 1) {
-                const cell = plan.cells[cellPos];
-                pushCell(cell);
-                if (cell.index < m.last) {
-                    const separator = renderSeparatorElement(p.itemSeparatorComponent, p.getItem(p.data, cell.index), p.getItem(p.data, cell.index + 1), separatorOverrides.get(cell.index));
-                    if (separator !== undefined) {
-                        children.push(h('symbiote-view', { key: `sep-${cell.key}` }, [separator]));
-                    }
-                }
+                pushCell(plan.cells[cellPos]);
             }
             if (plan.trailingExtent > EMPTY_OFFSET) {
                 children.push(h('symbiote-view', {
@@ -563,7 +584,8 @@ export const VirtualizedList = defineComponent((props, { attrs, expose, emit, sl
         if (p.maintainVisibleContentPosition !== undefined) {
             scrollProps.maintainVisibleContentPosition = {
                 ...p.maintainVisibleContentPosition,
-                minIndexForVisible: p.maintainVisibleContentPosition.minIndexForVisible + (header !== undefined ? 1 : 0),
+                minIndexForVisible: p.maintainVisibleContentPosition.minIndexForVisible +
+                    (header !== undefined ? 1 : 0),
             };
         }
         // Pull-to-refresh: when a @refresh listener is present, build a RefreshControl for the

package/build/components/virtualized-section-list/index.d.ts

@@ -6,6 +6,11 @@ export type { IVirtualizedSectionListHandle };
 export interface IVirtualizedSectionListProps<ItemT> {
     sections: ReadonlyArray<ISection<ItemT>>;
     keyExtractor?: (item: ItemT, index: number) => string;
+    getItemLayout?: (data: ReadonlyArray<ISection<ItemT>> | null, index: number) => {
+        length: number;
+        offset: number;
+        index: number;
+    };
     stickySectionHeadersEnabled?: boolean;
     extraData?: unknown;
     onEndReachedThreshold?: number;

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

@@ -21,7 +21,14 @@ import { normalizeVueAttrs } from '../../utils/normalize-attrs.js';
 const VirtualizedListHost = VirtualizedList;
 // Listed for the runtime `props` declaration (keyof can't derive it: the index signature widens
 // keyof to `string`). The three emit events are deliberately absent (declared as emits below).
-const PROP_KEYS = ['sections', 'keyExtractor', 'stickySectionHeadersEnabled'];
+// getItemLayout is declared here, not left to $attrs: falling through would hand the user's
+// callback the flattened ENTRIES as its `data` argument instead of the sections (see below).
+const PROP_KEYS = [
+    'sections',
+    'keyExtractor',
+    'getItemLayout',
+    'stickySectionHeadersEnabled',
+];
 const EMIT_KEYS = ['endReached', 'startReached', 'refresh'];
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -87,10 +94,14 @@ export const VirtualizedSectionList = defineComponent((props, { attrs, expose, e
         const renderEntry = (info) => {
             const entry = info.item;
             if (entry.kind === 'header') {
-                return slots.sectionHeader ? slots.sectionHeader({ section: entry.section }) : [];
+                return slots.sectionHeader
+                    ? slots.sectionHeader({ section: entry.section })
+                    : [];
             }
             if (entry.kind === 'footer') {
-                return slots.sectionFooter ? slots.sectionFooter({ section: entry.section }) : [];
+                return slots.sectionFooter
+                    ? slots.sectionFooter({ section: entry.section })
+                    : [];
             }
             if (entry.kind === 'section-separator') {
                 return slots.sectionSeparator ? slots.sectionSeparator() : [];
@@ -114,6 +125,21 @@ export const VirtualizedSectionList = defineComponent((props, { attrs, expose, e
                 trailingItem: unwrapEntryItem(entryProps.trailingItem),
             });
         const entryKeyExtractor = (entry, index) => sectionEntryKey(entry, index, keyExtractor);
+        // Hand the callback `sections`, not the entries: RN's inner VirtualizedList gets
+        // `data={this.props.sections}` (VirtualizedSectionList.js:216) while ours streams the
+        // FLATTENED entries, so the same user code would otherwise see a different argument here
+        // than on RN.
+        //
+        // UPSTREAM-DIVERGENCE(react-native): the flat INDEX matches RN's (two rows per section,
+        // header and footer) only while the #sectionSeparator slot is unset. With it,
+        // flattenSections emits an extra 'section-separator' row per boundary that RN renders inside
+        // the neighbouring cell, so indices shift by one per boundary from the second section on.
+        // Deliberate - that row is how this adapter paints the separator; a caller combining the two
+        // must account for it.
+        const getItemLayout = props.getItemLayout;
+        const entryItemLayout = getItemLayout === undefined
+            ? undefined
+            : (_entries, index) => getItemLayout(sections, index);
         // The three synthesized events become inner-VL handlers ONLY when listened, so the inner list
         // keeps gating (no parasitic RefreshControl / edge-reached work for an unlistened event).
         const endReached = listens('onEndReached')
@@ -122,7 +148,9 @@ export const VirtualizedSectionList = defineComponent((props, { attrs, expose, e
         const startReached = listens('onStartReached')
             ? (eventInfo) => emit('startReached', eventInfo)
             : undefined;
-        const refresh = listens('onRefresh') ? () => emit('refresh') : undefined;
+        const refresh = listens('onRefresh')
+            ? () => emit('refresh')
+            : undefined;
         return h(VirtualizedListHost, {
             ...forwarded,
             ref: setInner,
@@ -130,6 +158,7 @@ export const VirtualizedSectionList = defineComponent((props, { attrs, expose, e
             getItem: (_source, index) => entries[index],
             getItemCount: () => entries.length,
             keyExtractor: entryKeyExtractor,
+            getItemLayout: entryItemLayout,
             stickyHeaderIndices,
             onEndReached: endReached,
             onStartReached: startReached,

package/build/components.js

@@ -9,16 +9,21 @@
 // stateful component's ref would resolve to a useless component proxy, which is why
 // createAnimatedComponent (which captures the host node via that ref) needs the fall-through.
 import { h } from '@vue/runtime-core';
+import { resolveTextProps } from '@symbiote-native/components';
 import { normalizeVueAttrs } from './utils/normalize-attrs.js';
-function hostComponent(intrinsic, name) {
+function hostComponent(intrinsic, name, 
+// An optional last fold over the normalized attrs. Text needs one (RN's ellipsizeMode /
+// allowFontScaling defaults); View does not, so it stays a straight pass-through.
+fold = attrs => attrs) {
     // normalizeVueAttrs folds kebab template props (:accessibility-label) to the RN camelCase contract.
-    const component = (_props, { slots, attrs }) => h(intrinsic, normalizeVueAttrs(attrs), slots.default !== undefined ? slots.default() : undefined);
+    const component = (_props, { slots, attrs }) => h(intrinsic, fold(normalizeVueAttrs(attrs)), slots.default !== undefined ? slots.default() : undefined);
     component.displayName = name;
     component.inheritAttrs = false;
     return component;
 }
 export const View = hostComponent('symbiote-view', 'View');
-export const Text = hostComponent('symbiote-text', 'Text');
+export const Text = hostComponent('symbiote-text', 'Text', resolveTextProps);
+// Text is no longer bare either — it carries RN's Text.js defaults through resolveTextProps.
 // Image is NOT a bare host primitive: it needs the shared fold (source/src/srcSet resolution,
 // width/height -> style, alt -> accessibility) + the Image statics, so it lives in ./image as a
 // functional component over renderImage. View/Text stay bare; they forward attrs verbatim.

package/build/create-portal/index.d.ts

@@ -0,0 +1,28 @@
+import { SymbioteSurface, type ISymbioteNode } from '@symbiote-native/engine';
+/** Anything already mounted in THIS surface: a host-node ref, or the surface root itself. */
+export type ITeleportTarget = ISymbioteNode | SymbioteSurface;
+export declare function isTeleportTarget(target: unknown): target is ITeleportTarget;
+export declare const Teleport: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    to: {
+        type: null;
+        default: null;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    to: {
+        type: null;
+        default: null;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{}>, {
+    to: any;
+    disabled: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/build/create-portal/index.js

@@ -0,0 +1,42 @@
+// The Vue adapter's portal — Vue's OWN `<Teleport>`, not a parallel API. Teleport lives in
+// @vue/runtime-core, not @vue/runtime-dom, and resolves its target through the RendererOptions we
+// already supply: `resolveTarget` only consults `querySelector` for the STRING form of `to`, and
+// returns an object target untouched. So stock Teleport drives this renderer as-is — target
+// change, unmount, disabled, call-site provide/inject and reactive updates all measured working
+// over the engine (create-portal.test.ts). This module adds exactly one thing on top: a runtime
+// guard on `to`.
+//
+// Why the guard: `to` is untyped at the template boundary, and a wrong value (a CSS selector
+// copied from web code, a forgotten `.value` on a ref, a plain object) would otherwise sink into
+// insert/remove deep in the engine and corrupt the retained tree silently. Vue's own dev warning
+// for the string form only fires in a dev build and still returns null, which paints nothing.
+//
+// Scope — same-surface targets only, the same PERMANENT boundary as React's createPortal
+// (adapters/react/src/create-portal/index.ts): a portal MOVES host nodes, and only the surface
+// that owns them ever commits them. Content whose target lives in a second, independently
+// mount()ed surface needs createTunnel instead, which copies rather than moves.
+import { defineComponent, h, Teleport as VueTeleport } from '@vue/runtime-core';
+import { isSymbioteNode, SymbioteSurface, } from '@symbiote-native/engine';
+export function isTeleportTarget(target) {
+    return target instanceof SymbioteSurface || isSymbioteNode(target);
+}
+export const Teleport = defineComponent({
+    name: 'Teleport',
+    inheritAttrs: false,
+    props: {
+        to: { type: null, default: null },
+        disabled: { type: Boolean, default: false },
+    },
+    setup(props, { slots }) {
+        return () => {
+            const { to } = props;
+            if (typeof to === 'string') {
+                throw new Error(`Teleport target must be a host node ref, not a CSS-selector string ("${to}") — symbiote has no querySelector. Pass a ref to an already-rendered element instead (e.g. <View ref="overlayHost" />, then :to="overlayHost").`);
+            }
+            if (to != null && !isTeleportTarget(to)) {
+                throw new Error('Teleport target is not a real host node — did you forget `.value` on a ref, or pass something symbiote never rendered?');
+            }
+            return h(VueTeleport, { to, disabled: props.disabled }, slots);
+        };
+    },
+});

package/build/host-instance/index.js

@@ -13,7 +13,9 @@
 import { isRef, toRaw } from '@vue/runtime-core';
 import { getNativeTag, isSymbioteNode, dlog } from '@symbiote-native/engine';
 export function findNodeHandle(componentOrHandle) {
-    const candidate = isRef(componentOrHandle) ? componentOrHandle.value : componentOrHandle;
+    const candidate = isRef(componentOrHandle)
+        ? componentOrHandle.value
+        : componentOrHandle;
     if (candidate === null || candidate === undefined)
         return null;
     if (typeof candidate === 'number')