@symbiote-native/vue 0.1.0

package/build/components/safe-area-view.js

@@ -0,0 +1,33 @@
+// SafeAreaView, the Vue lifecycle half (ADR 0024 Phase 2). A plain view whose native side
+// insets its children to the safe area (notch, rounded corners, system bars); there is no
+// JS-side translation, so this maps style + children straight onto the intrinsic. The Vue twin
+// of the React adapter's SafeAreaView. Vue takes children via slots, folds aria/role through
+// the shared resolveAccessibilityProps (so every adapter normalizes the web aliases identically),
+// and forwards the rest onto the symbiote-safe-area-view host node.
+//
+// Inputs arrive as attrs (untyped), so the forwarded bag is BUILT at the a11y-intersection type
+// (a genuine narrowing, not a cast) before resolveAccessibilityProps folds aria-* into accessibility*.
+import { defineComponent, h } from '@vue/runtime-core';
+import { dlog } from '@symbiote-native/engine';
+import { resolveAccessibilityProps, } from '@symbiote-native/components';
+import { normalizeVueAttrs } from '../utils/normalize-attrs';
+// Copy every attr into a bag typed as the a11y intersection (the accumulator is BUILT at that
+// type, a real narrowing, not a cast), then fold aria-*/role into the canonical accessibility*
+// props before they reach the host. style / onLayout / testID forward unchanged.
+function foldAttrs(attrs) {
+    const bag = {};
+    for (const key of Object.keys(attrs))
+        bag[key] = attrs[key];
+    return resolveAccessibilityProps(bag);
+}
+export const SafeAreaView = defineComponent({
+    name: 'SafeAreaView',
+    inheritAttrs: false,
+    setup(_props, { attrs: rawAttrs, slots }) {
+        return () => {
+            dlog('SafeAreaView -> SafeAreaView');
+            const nativeProps = foldAttrs(normalizeVueAttrs(rawAttrs));
+            return h('symbiote-safe-area-view', nativeProps, slots.default !== undefined ? slots.default() : undefined);
+        };
+    },
+});

package/build/components/scroll-view/index.android.d.ts

@@ -0,0 +1,4 @@
+export type { IScrollViewProps, IScrollViewEmits, IScrollViewHandle } from './shared';
+export declare const ScrollView: import("vue").DefineSetupFnComponent<import("./shared").IScrollViewProps, import("./shared").IScrollViewEmits, {}, import("./shared").IScrollViewProps & {
+    onContentSizeChange?: ((width: number, height: number) => any) | undefined;
+}, import("vue").PublicProps>;

package/build/components/scroll-view/index.android.js

@@ -0,0 +1,74 @@
+// ScrollView on Android (ADR 0024 Phase 2). An Android ScrollView accepts only ONE child, so a
+// RefreshControl can't be a sibling of the content the way iOS allows ("addViewAt: failed to insert
+// view ... at index 1"). Instead the RefreshControl (AndroidSwipeRefreshLayout) WRAPS the scroll
+// view, with the scroll view nested inside and nestedScrollEnabled so the inner scroll handles the
+// gesture before the refresh parent, mirroring RN's ScrollView.js android branch.
+//
+// React does this with cloneElement(refreshControl, {style}, scrollView). Vue has NO cloneElement,
+// so the analog is to RE-INVOKE the user's RefreshControl component type via h(): same .type, its
+// own .props plus the injected outer/layout style, and the inner scroll view as its DEFAULT SLOT.
+// The slot is the seam: RefreshControl renders slots.default() as the host node's children. The
+// node ref stays on the INNER scroll view (not the wrapper), so dispatchViewCommand targets it.
+// Metro picks this on an Android host; no Platform.OS read.
+// device-verify-pending: the wrap shape mirrors RN, proven on a real host by the absence of the
+// "addViewAt: failed to insert" crash.
+import { h, isVNode } from '@vue/runtime-core';
+import { dlog } from '@symbiote-native/engine';
+import { splitLayoutProps } from '@symbiote-native/components';
+import { createScrollView } from './shared';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// A Vue VNode's `.type` is VNodeTypes (string | Component | nested VNode | the Fragment/Text/…
+// symbol constants). Re-invoking via h() needs it narrowed to what h accepts (string | Component):
+// the symbol constants fail the typeof checks and a nested VNode is ruled out by isVNode. A type
+// predicate (not a plain return) sidesteps the assignability gap; refreshControl is always a real
+// component element in practice.
+function isHostType(type) {
+    if (typeof type === 'string')
+        return true;
+    return ((typeof type === 'object' || typeof type === 'function') && type !== null && !isVNode(type));
+}
+export const ScrollView = createScrollView({
+    assemble: input => {
+        if (input.refreshControl === undefined) {
+            // No refresh: the same single-child path as Phase 1; the node ref rides input.scrollProps.
+            dlog('Vue ScrollView.ANDROID refreshControl=NONE(1child)');
+            return h(input.scrollViewIntrinsic, input.scrollProps, [input.content]);
+        }
+        // RN splits the flattened style across the two boxes (splitLayoutProps): LAYOUT props
+        // (margin/flex/size/position/…) drive the outer AndroidSwipeRefreshLayout frame; VISUAL props
+        // (background/padding/border/…) paint the inner scroll view. So the wrapper carries `outer`, and
+        // the inner scroll view its base (flexDirection/overflow) plus the visual `inner` composed over
+        // it, NOT a hardcoded flex:1 that would override an explicit user height/width.
+        //
+        // layoutSplitStyle (not userStyle): a class-only layout prop (flex/height/gap/…) is invisible
+        // to userStyle (it never carries the resolved `class` value — see isClassNameProp in
+        // shared.ts), so splitting on userStyle alone starves the wrapper of its layout style and it
+        // collapses to nothing. layoutSplitStyle is userStyle merged with the resolved class style.
+        const { outer, inner } = splitLayoutProps(input.layoutSplitStyle);
+        // `class` is stripped from the spread here: layoutSplitStyle already folded its resolved
+        // value into `outer`/`inner` above, so forwarding the raw prop too would re-apply its LAYOUT
+        // half onto the inner scroll view a second time (on top of the outer wrapper), the same
+        // wrapper/inner leak `style` already avoids by living in HANDLED_ATTRS.
+        const { class: _classAppliedViaSplit, ...innerScrollOuterProps } = input.scrollOuterProps;
+        const innerScrollView = h(input.scrollViewIntrinsic, {
+            ...innerScrollOuterProps,
+            style: [input.scrollViewBaseStyle, inner],
+            nestedScrollEnabled: true,
+            ref: input.setNodeRef,
+        }, [input.content]);
+        const rc = input.refreshControl;
+        if (!isHostType(rc.type)) {
+            // refreshControl is always a component VNode; a symbol/nested-VNode type can't host children.
+            // Degrade to the unwrapped scroll view rather than crash (the node ref is already on it).
+            dlog('Vue ScrollView.ANDROID refreshControl has no hostable type, rendering scroll view unwrapped');
+            return innerScrollView;
+        }
+        const rcProps = isRecord(rc.props) ? rc.props : {};
+        dlog('Vue ScrollView.ANDROID refreshControl=WRAP');
+        // Re-invoke the user's RefreshControl: same type, its own props + the outer/layout style, and the
+        // inner scroll view as the default slot (the Vue analog of cloneElement(refreshControl, {style}, sv)).
+        return h(rc.type, { ...rcProps, style: outer }, { default: () => [innerScrollView] });
+    },
+});

package/build/components/scroll-view/index.d.ts

@@ -0,0 +1 @@
+export * from './index.ios';

package/build/components/scroll-view/index.ios.d.ts

@@ -0,0 +1,4 @@
+export type { IScrollViewProps, IScrollViewEmits, IScrollViewHandle } from './shared';
+export declare const ScrollView: import("vue").DefineSetupFnComponent<import("./shared").IScrollViewProps, import("./shared").IScrollViewEmits, {}, import("./shared").IScrollViewProps & {
+    onContentSizeChange?: ((width: number, height: number) => any) | undefined;
+}, import("vue").PublicProps>;

package/build/components/scroll-view/index.ios.js

@@ -0,0 +1,15 @@
+// ScrollView on iOS (ADR 0024 Phase 2). The RefreshControl is a CHILD of the scroll view, rendered
+// as a SIBLING BEFORE the content container (RN ScrollView.js: {refreshControl}{contentContainer}).
+// The user's RefreshControl VNode renders as-is; its default slot is empty on iOS, so it is a
+// childless sibling. Also the base (scroll-view.ts re-exports it) for headless / web. Metro picks
+// this on an iOS host; no Platform.OS read. Mirrors the React adapter's iOS binding.
+import { h } from '@vue/runtime-core';
+import { createScrollView } from './shared';
+export const ScrollView = createScrollView({
+    assemble: input => {
+        // Sibling placement: RefreshControl before content (RN iOS). The node ref stays on the scroll
+        // view via input.scrollProps, so the imperative handle targets it whether or not refresh is on.
+        const children = input.refreshControl === undefined ? [input.content] : [input.refreshControl, input.content];
+        return h(input.scrollViewIntrinsic, input.scrollProps, children);
+    },
+});

package/build/components/scroll-view/index.js

@@ -0,0 +1,4 @@
+// Base / default ScrollView. Re-exports the iOS build. Metro overrides this with
+// scroll-view.ios.ts / scroll-view.android.ts on a real host; under tsx / tsc / web the host
+// resolves here. Filename is the selector, no Platform.OS read. See ADR 0020 / 0024.
+export * from './index.ios';

package/build/components/scroll-view/shared.d.ts

@@ -0,0 +1,96 @@
+import { type VNode } from '@vue/runtime-core';
+import { type IAccessibilityProps, type IAriaProps, type ISymbioteIntrinsic } from '@symbiote-native/components';
+import { type IClassNameValue, type IStyleProp, type ISymbioteEvent, type IViewStyle } from '@symbiote-native/engine';
+import { type IStickyHeaderComponentType } from './sticky-header';
+export type { IScrollViewHandle } from '@symbiote-native/components';
+type IScrollHandler = (event: ISymbioteEvent) => void;
+export interface IScrollViewProps extends IAccessibilityProps, IAriaProps {
+    style?: IStyleProp<IViewStyle>;
+    contentContainerStyle?: IStyleProp<IViewStyle> | string;
+    horizontal?: boolean;
+    scrollEnabled?: boolean;
+    showsVerticalScrollIndicator?: boolean;
+    showsHorizontalScrollIndicator?: boolean;
+    pagingEnabled?: boolean;
+    bounces?: boolean;
+    decelerationRate?: 'normal' | 'fast' | number;
+    scrollEventThrottle?: number;
+    contentInset?: {
+        top?: number;
+        left?: number;
+        bottom?: number;
+        right?: number;
+    };
+    contentOffset?: {
+        x: number;
+        y: number;
+    };
+    refreshControl?: VNode;
+    removeClippedSubviews?: boolean;
+    class?: IClassNameValue;
+    snapToInterval?: number;
+    snapToOffsets?: number[];
+    snapToAlignment?: 'start' | 'center' | 'end';
+    snapToStart?: boolean;
+    snapToEnd?: boolean;
+    disableIntervalMomentum?: boolean;
+    stickyHeaderIndices?: number[];
+    invertStickyHeaders?: boolean;
+    StickyHeaderComponent?: IStickyHeaderComponentType;
+    keyboardDismissMode?: 'none' | 'on-drag' | 'interactive';
+    keyboardShouldPersistTaps?: boolean | 'always' | 'never' | 'handled';
+    maintainVisibleContentPosition?: {
+        minIndexForVisible: number;
+        autoscrollToTopThreshold?: number;
+    };
+    alwaysBounceHorizontal?: boolean;
+    alwaysBounceVertical?: boolean;
+    centerContent?: boolean;
+    scrollIndicatorInsets?: {
+        top?: number;
+        left?: number;
+        bottom?: number;
+        right?: number;
+    };
+    indicatorStyle?: 'default' | 'black' | 'white';
+    directionalLockEnabled?: boolean;
+    automaticallyAdjustKeyboardInsets?: boolean;
+    contentInsetAdjustmentBehavior?: 'automatic' | 'scrollableAxes' | 'never' | 'always';
+    minimumZoomScale?: number;
+    maximumZoomScale?: number;
+    zoomScale?: number;
+    bouncesZoom?: boolean;
+    pinchGestureEnabled?: boolean;
+    nestedScrollEnabled?: boolean;
+    overScrollMode?: 'auto' | 'always' | 'never';
+    fadingEdgeLength?: number;
+    persistentScrollbar?: boolean;
+    endFillColor?: string;
+    onLayout?: IScrollHandler;
+    onScroll?: IScrollHandler;
+    onScrollBeginDrag?: IScrollHandler;
+    onScrollEndDrag?: IScrollHandler;
+    onMomentumScrollBegin?: IScrollHandler;
+    onMomentumScrollEnd?: IScrollHandler;
+    onScrollToTop?: IScrollHandler;
+}
+export type IScrollViewEmits = {
+    contentSizeChange: (width: number, height: number) => boolean;
+};
+export interface IScrollViewAssembleInput {
+    scrollViewIntrinsic: ISymbioteIntrinsic;
+    scrollProps: Record<string, unknown>;
+    content: VNode;
+    refreshControl: VNode | undefined;
+    scrollViewBaseStyle: IViewStyle;
+    userStyle: IStyleProp<IViewStyle> | undefined;
+    layoutSplitStyle: IStyleProp<IViewStyle>;
+    scrollOuterProps: Record<string, unknown>;
+    setNodeRef: (el: unknown) => void;
+}
+export interface IScrollViewPlatform {
+    assemble: (input: IScrollViewAssembleInput) => VNode;
+}
+export declare function createScrollView(platform: IScrollViewPlatform): import("vue").DefineSetupFnComponent<IScrollViewProps, IScrollViewEmits, {}, IScrollViewProps & {
+    onContentSizeChange?: ((width: number, height: number) => any) | undefined;
+}, import("vue").PublicProps>;

package/build/components/scroll-view/shared.js

@@ -0,0 +1,297 @@
+// ScrollView, the Vue lifecycle half (Phase 1: base, ADR 0024). The Fabric tree is nested:
+// a scroll view wraps a content view that holds the children (RN's ScrollView.js shape). The
+// platform-invariant math (decelerationRate, the per-axis intrinsics/base style, the
+// content-size dedupe, the imperative handle, the aria/role fold) lives in @symbiote-native/components,
+// shared verbatim with React. Here Vue supplies only the reactivity: a shallowRef holds the host
+// node, a setup-scope `lastContentSize` dedupes onContentSizeChange, and expose() wires the
+// imperative handle. This is the Vue twin of the React adapter's useRef + buildScrollViewHandle.
+//
+// Inputs arrive as attrs (untyped), so each is narrowed with a runtime guard rather than a cast.
+// contentSizeChange is synthesized as a typed Vue emit from the content onLayout. The legacy
+// onContentSizeChange callback key MUST be consumed if it arrives (it is NOT a ViewConfig event;
+// forwarding a function prop would reach Fabric and crash Android's folly::dynamic). Scroll events
+// (onScroll/onLayout/…) ARE ViewConfig events, so they forward raw and routeProp turns them into
+// listeners.
+//
+// Phase 2 (ADR 0024 §4): RefreshControl is wired through the platform assemble (iOS sibling /
+// Android wrap). Phase 3 (§5): sticky headers are real. The scroll AnimatedValue (markRaw, held by
+// identity), the headerLayoutYs cross-talk map + bump, the viewport-height capture, and the
+// onScroll composition (native attach vs Animated.event) all live here; the per-header component and
+// the children wrap live in scroll-view-sticky-header.ts (the Vue twin of the React file).
+import { defineComponent, h, isVNode, markRaw, onBeforeUnmount, ref, shallowRef, watch, } from '@vue/runtime-core';
+import { attachStickyScroll, buildScrollViewHandle, didContentSizeChange, forwardScrollEvent, readLayoutDimension, resolveAccessibilityProps, resolveDecelerationRate, selectScrollIntrinsics, } from '@symbiote-native/components';
+import { AnimatedValue, dlog, event as animatedEvent, isClassNameValue, isNativeAnimatedAvailable, isSymbioteNode, resolveClassName, } from '@symbiote-native/engine';
+import { wrapStickyHeaders } from './sticky-header';
+import { normalizeVueAttrs } from '../../utils/normalize-attrs';
+function isHandler(value) {
+    return typeof value === 'function';
+}
+// Objects and arrays are valid StyleProp<ViewStyle> (ViewStyle | RecursiveArray | falsy; the
+// engine omits RN's RegisteredStyle brand, so no numeric form). Primitives/null degrade to
+// undefined; the engine flattens whatever object/array reaches it.
+function isStyleProp(value) {
+    return typeof value === 'object' && value !== null;
+}
+// `class` is never in HANDLED_ATTRS (inheritAttrs:false means it also isn't auto-merged onto a
+// root), so it forwards raw to the inner scroll-view node via forwardAttrs, resolved later by
+// the renderer's own patchProp — fine for the single-node Phase 1 path. But the Android
+// RefreshControl wrap (index.android.ts) reads userStyle alone to splitLayoutProps() the outer
+// wrapper's layout style, BEFORE that later resolution ever runs, so a class-only layout prop
+// (flex, height, gap, …) never reaches the wrapper and it collapses to nothing. See the
+// symbiote-sfc-style-compiler skill for the failure this caused on a real Android device.
+// isClassNameProp is @symbiote-native/engine's own isClassNameValue guard (shared, not redeclared —
+// routeProp's centralized class+style merge needs the identical narrowing).
+const isClassNameProp = isClassNameValue;
+// decelerationRate is resolved per-platform (resolveDecelerationRate), so it must be narrowed to
+// its declared shape before that call, unlike the raw pass-through props.
+function asDecelerationRate(value) {
+    if (typeof value === 'number')
+        return value;
+    if (value === 'normal' || value === 'fast')
+        return value;
+    return undefined;
+}
+// stickyHeaderIndices arrives untyped (attrs); narrow to a number[] before the wrap reads it.
+function isNumberArray(value) {
+    return Array.isArray(value) && value.every(entry => typeof entry === 'number');
+}
+// A StickyHeaderComponent override is a Vue component: a function (functional) or an object
+// (defineComponent). Narrowed before it is handed to wrapStickyHeaders (no cast).
+function isComponent(value) {
+    return typeof value === 'function' || (typeof value === 'object' && value !== null);
+}
+// The prop/handler keys the lifecycle consumes itself; everything else (the scroll events,
+// snap/keyboard/zoom families, accessibility, testID, …) forwards onto the scroll-view node.
+// onContentSizeChange is consumed (synthesized from the content onLayout, never forwarded);
+// refreshControl is consumed by the platform assemble; the sticky-header props (indices / invert /
+// StickyHeaderComponent) are lifecycle-consumed by the children wrap and must NEVER reach Fabric.
+// style / contentContainerStyle / horizontal / decelerationRate are recomposed.
+const HANDLED_ATTRS = [
+    'style',
+    'contentContainerStyle',
+    'horizontal',
+    'decelerationRate',
+    'onContentSizeChange',
+    'refreshControl',
+    'stickyHeaderIndices',
+    'invertStickyHeaders',
+    'StickyHeaderComponent',
+];
+function forwardAttrs(attrs) {
+    const result = {};
+    for (const key of Object.keys(attrs)) {
+        if (!HANDLED_ATTRS.includes(key))
+            result[key] = attrs[key];
+    }
+    return result;
+}
+export function createScrollView(platform) {
+    return defineComponent((_props, { slots, attrs: rawAttrs, expose, emit }) => {
+        // 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 mirror (a WeakMap) is keyed on, so dispatchViewCommand would
+        // miss and every scrollTo/scrollToEnd/flashScrollIndicators silently no-op. See
+        // .claude/skills/vue-adapter-reactivity. This is the same rule as the Switch host node.
+        const nodeRef = shallowRef(null);
+        const setNodeRef = (el) => {
+            nodeRef.value = isSymbioteNode(el) ? el : null;
+        };
+        // The imperative handle reads the node through a LAZY getter (() => nodeRef.value), not the
+        // node captured once: it is null until the element commits, so an eager capture would freeze
+        // null and every command would no-op (ADR 0024 §3). expose() makes it the value a parent ref
+        // sees: the Vue twin of React's useImperativeHandle(forwardedRef, buildScrollViewHandle(…)).
+        expose(buildScrollViewHandle(() => nodeRef.value));
+        // The last-seen content size, kept here (setup scope, persists across renders) to dedupe
+        // contentSizeChange: RN fires the content onLayout on every layout pass; only real size
+        // changes emit to the user (didContentSizeChange).
+        let lastContentSize = null;
+        // A single AnimatedValue tracks the scroll offset and drives every sticky header's translateY
+        // (RN's _scrollAnimatedValue). A setup-scope const (allocated once, stable across renders) so
+        // the headers' bindings survive re-renders, the Vue twin of React's useRef-stable value.
+        // markRaw: it is an engine object, held by IDENTITY, never run through toReactive (the
+        // reactivity rule; a deep ref would hand back a Proxy the engine's mirror misses). Allocated
+        // unconditionally (like React's unconditional hook); unused when no sticky headers are flagged.
+        const scrollAnimatedValue = markRaw(new AnimatedValue(0));
+        // Inverted sticky headers stick to the BOTTOM, so they need the viewport height (RN reads it
+        // in _handleLayout). Tracked here and fed back into the wrapped headers on the next render.
+        const viewportHeight = ref(undefined);
+        // Sticky-header cross-talk (RN ScrollView.js _headerLayoutYs, line 754): a child-index→measured-y
+        // map the parent keeps so each header can learn where the NEXT sticky header starts (its push-off
+        // collision point). The map is a setup-scope const mutated imperatively from each header's onLayout
+        // (like RN's _onStickyHeaderLayout); a reactive bump ref forces the re-render that feeds the
+        // freshly-recorded y forward into the previous header's nextHeaderLayoutY (via nextStickyHeaderY).
+        const headerLayoutYs = new Map();
+        const bumpHeaderLayout = ref(0);
+        const onHeaderLayoutY = (index, y) => {
+            if (headerLayoutYs.get(index) === y)
+                return;
+            headerLayoutYs.set(index, y);
+            dlog(`Vue ScrollView sticky-header layoutY index=${index} y=${y}`);
+            bumpHeaderLayout.value += 1;
+        };
+        // Native sticky-scroll attach (RN attachNativeEvent / _updateAnimatedNodeAttachment): when the
+        // native module is available, the scroll value is driven on the UI thread so the interpolations
+        // ride scroll natively (no JS jitter). A plain flag set in render (like createAnimatedComponent's
+        // wantsNative: non-reactive so writing it in render triggers no effect); the post-commit watch
+        // reads it once the node commits. The JS path needs no attach: Animated.event drives the value
+        // each frame. flush:'post' so the engine has committed the node before attachStickyScroll reads
+        // its Fabric handle. Detached on unmount (and re-detached if the node identity changes).
+        let nativeStickyWanted = false;
+        let detachStickyScroll;
+        watch(() => nodeRef.value, node => {
+            if (detachStickyScroll !== undefined) {
+                detachStickyScroll();
+                detachStickyScroll = undefined;
+            }
+            if (!nativeStickyWanted || node === null)
+                return;
+            detachStickyScroll = attachStickyScroll(node, scrollAnimatedValue);
+        }, { flush: 'post' });
+        onBeforeUnmount(() => {
+            if (detachStickyScroll !== undefined)
+                detachStickyScroll();
+        });
+        return () => {
+            // Read the bump so a recorded header y re-runs render and feeds nextStickyHeaderY forward.
+            void bumpHeaderLayout.value;
+            // Fold kebab template props (:content-container-style) to the RN camelCase contract; idiomatic
+            // Vue templates use kebab, but the prop surface (and HANDLED_ATTRS below) is camelCase.
+            const attrs = normalizeVueAttrs(rawAttrs);
+            const isHorizontal = attrs.horizontal === true;
+            const userStyle = isStyleProp(attrs.style) ? attrs.style : undefined;
+            // resolveClassName(undefined) is a cheap {} no-op, so this is safe with no class prop too.
+            const classProp = isClassNameProp(attrs.class) ? attrs.class : undefined;
+            const layoutSplitStyle = [resolveClassName(classProp), userStyle];
+            // A class-name string resolves through the same style registry as `class`/`style` above;
+            // an object/array is already style-shaped and passes through as-is.
+            const contentContainerStyle = typeof attrs.contentContainerStyle === 'string'
+                ? resolveClassName(attrs.contentContainerStyle)
+                : isStyleProp(attrs.contentContainerStyle)
+                    ? attrs.contentContainerStyle
+                    : undefined;
+            // Sticky headers (Phase 3, ADR 0024): a pure-JS layer; the native scroll view ignores
+            // stickyHeaderIndices, so we wrap the flagged children below and drive their translateY off
+            // the scroll offset. invertStickyHeaders narrows to the inverted (stick-to-bottom) branch.
+            const stickyHeaderIndices = isNumberArray(attrs.stickyHeaderIndices)
+                ? attrs.stickyHeaderIndices
+                : undefined;
+            const hasStickyHeaders = stickyHeaderIndices !== undefined && stickyHeaderIndices.length > 0;
+            const invertStickyHeaders = attrs.invertStickyHeaders === true ? true : undefined;
+            const stickyHeaderComponent = isComponent(attrs.StickyHeaderComponent)
+                ? attrs.StickyHeaderComponent
+                : undefined;
+            const { scrollViewIntrinsic, contentIntrinsic, scrollViewBaseStyle, contentStyle } = selectScrollIntrinsics(isHorizontal, contentContainerStyle);
+            // Outer props: fold aria/role, then layer the lifecycle-managed values on top. RN defaults
+            // nested scrolling ON (ScrollView.js `nestedScrollEnabled ?? true`); horizontal forwards
+            // only when defined (load-bearing on iOS's RCTScrollView axis, ignored by Android's
+            // dedicated manager); decelerationRate is resolved per-platform.
+            const outerProps = {
+                ...resolveAccessibilityProps(forwardAttrs(attrs)),
+            };
+            outerProps.nestedScrollEnabled =
+                typeof attrs.nestedScrollEnabled === 'boolean' ? attrs.nestedScrollEnabled : true;
+            if (attrs.horizontal !== undefined)
+                outerProps.horizontal = attrs.horizontal;
+            const decel = asDecelerationRate(attrs.decelerationRate);
+            if (decel !== undefined)
+                outerProps.decelerationRate = resolveDecelerationRate(decel);
+            // onScroll: when sticky headers are active, the offset must reach the AnimatedValue. RN does
+            // the same with _scrollAnimatedValueAttachment. forwardAttrs already put the user's onScroll /
+            // onLayout / scrollEventThrottle on outerProps; here we override them for the sticky branch.
+            const nativeStickyAvailable = hasStickyHeaders && isNativeAnimatedAvailable();
+            nativeStickyWanted = nativeStickyAvailable;
+            if (hasStickyHeaders) {
+                const userOnScroll = isHandler(attrs.onScroll) ? attrs.onScroll : undefined;
+                const userThrottle = typeof attrs.scrollEventThrottle === 'number' ? attrs.scrollEventThrottle : undefined;
+                if (nativeStickyAvailable) {
+                    // Native path (RN attachNativeEvent): the scroll value is driven on the UI thread by the
+                    // post-commit watch above, so onScroll only forwards to the user: zero JS per frame. RN
+                    // uses throttle 1 when sticky (ScrollView.js:1798); the native driver can afford it. The
+                    // user onScroll is already on outerProps via forwardAttrs.
+                    outerProps.scrollEventThrottle = userThrottle ?? 1;
+                }
+                else {
+                    // JS fallback (no native module): Animated.event drives the value each frame and forwards
+                    // the user's handler as the listener passthrough. Correct, but lags a frame under fast
+                    // scroll (the jitter), which the native path above removes on a real host.
+                    outerProps.onScroll = animatedEvent([{ nativeEvent: { contentOffset: { y: scrollAnimatedValue } } }], userOnScroll === undefined
+                        ? undefined
+                        : { listener: (...args) => forwardScrollEvent(userOnScroll, args) });
+                    outerProps.scrollEventThrottle = userThrottle ?? 16;
+                }
+                // onLayout on the scroll-view node: capture the viewport height for inverted sticky headers
+                // (RN _handleLayout), then call the user's handler. Non-inverted leaves onLayout as forwarded.
+                if (invertStickyHeaders === true) {
+                    const userOnLayout = isHandler(attrs.onLayout) ? attrs.onLayout : undefined;
+                    outerProps.onLayout = (event) => {
+                        const height = readLayoutDimension(event, 'height');
+                        if (height !== undefined)
+                            viewportHeight.value = height;
+                        if (userOnLayout !== undefined)
+                            userOnLayout(event);
+                    };
+                }
+            }
+            dlog(`Vue ScrollView -> ${scrollViewIntrinsic} (horizontal=${isHorizontal} sticky=${hasStickyHeaders})`);
+            // Content props: `collapsable: false` keeps the layout-only content view as a real native
+            // view: Android Fabric view-flattens it away otherwise, hoisting the cells as direct
+            // children of the scroll view (which hosts exactly one), an addViewAt crash. collapsableChildren
+            // false also preserves the cell views maintainVisibleContentPosition / snapToAlignment
+            // anchor against (RN preserveChildren). iOS never flattens; both are no-ops there.
+            const contentProps = { style: contentStyle, collapsable: false };
+            if (attrs.maintainVisibleContentPosition !== undefined ||
+                attrs.snapToAlignment !== undefined) {
+                contentProps.collapsableChildren = false;
+            }
+            // contentSizeChange is synthesized from the content view's own onLayout (RN
+            // _handleContentOnLayout): read width/height and emit only on a real size change (dedupe via
+            // the setup-scope lastContentSize).
+            contentProps.onLayout = (event) => {
+                const width = readLayoutDimension(event, 'width');
+                const height = readLayoutDimension(event, 'height');
+                if (width === undefined || height === undefined)
+                    return;
+                if (!didContentSizeChange(lastContentSize, { width, height }))
+                    return;
+                lastContentSize = { width, height };
+                dlog(`Vue ScrollView contentSizeChange ${width}x${height}`);
+                emit('contentSizeChange', width, height);
+            };
+            // Sticky headers are a pure-JS layer (the native scroll view ignores stickyHeaderIndices);
+            // wrap the flagged children so they pin to the scroll offset. No-op when none are flagged.
+            const slotChildren = slots.default !== undefined ? slots.default() : [];
+            const contentChildren = hasStickyHeaders
+                ? wrapStickyHeaders(slotChildren, stickyHeaderIndices, scrollAnimatedValue, invertStickyHeaders, viewportHeight.value, stickyHeaderComponent, headerLayoutYs, onHeaderLayoutY)
+                : slotChildren;
+            const content = h(contentIntrinsic, contentProps, contentChildren);
+            // Base style UNDER user style so an explicit user value (height, flexDirection) still wins;
+            // the scroll node carries overflow:'scroll' (frame clipping) + the per-axis flexDirection.
+            const scrollProps = {
+                ...outerProps,
+                style: [scrollViewBaseStyle, userStyle],
+                ref: setNodeRef,
+            };
+            // refreshControl arrives as a Vue VNode the app passes (h(RefreshControl, …)); narrow it
+            // with isVNode (no cast). Stripped from forwardAttrs (it is in HANDLED_ATTRS) so it never
+            // reaches the host as a prop: it is lifecycle-consumed by the platform assemble.
+            const refreshControl = isVNode(attrs.refreshControl) ? attrs.refreshControl : undefined;
+            return platform.assemble({
+                scrollViewIntrinsic,
+                scrollProps,
+                content,
+                refreshControl,
+                scrollViewBaseStyle,
+                userStyle,
+                layoutSplitStyle,
+                scrollOuterProps: outerProps,
+                setNodeRef,
+            });
+        };
+    }, {
+        name: 'ScrollView',
+        inheritAttrs: false,
+        emits: {
+            contentSizeChange: (_width, _height) => true,
+        },
+    });
+}

package/build/components/scroll-view/sticky-header.d.ts

@@ -0,0 +1,7 @@
+import { type Component, type VNode } from '@vue/runtime-core';
+import { AnimatedValue } from '@symbiote-native/engine';
+export type IStickyHeaderComponentType = Component;
+export declare const ScrollViewStickyHeader: import("vue").DefineComponent<{}, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export declare function wrapStickyHeaders(children: VNode[], stickyHeaderIndices: number[] | undefined, scrollAnimatedValue: AnimatedValue, invertStickyHeaders: boolean | undefined, scrollViewHeight: number | undefined, StickyHeaderComponent: IStickyHeaderComponentType | undefined, headerLayoutYs: ReadonlyMap<number, number>, onHeaderLayoutY: (index: number, y: number) => void): VNode[];