@symbiote-native/react 0.1.0

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

@@ -0,0 +1,99 @@
+// VirtualizedSectionList: sections flattened into one virtualized stream. Each section
+// contributes a header row, its item rows, then a footer row; the flattened sequence is fed to
+// VirtualizedList as a single tagged list, so headers, items, and footers are all windowed by the
+// same machinery. The flattening, entry keying, separator-item unwrap, and scrollToLocation
+// mapping are shared from @symbiote-native/components; this file wires React's lifecycle (refs +
+// useImperativeHandle + the per-entry render dispatch). Lower layer in RN's
+// SectionList -> VirtualizedSectionList -> VirtualizedList stack.
+import { createElement, useImperativeHandle, useRef, } from 'react';
+import { dlog, Platform } from '@symbiote-native/engine';
+import { flattenSections, scrollLocationToFlatIndex, sectionEntryKey, unwrapEntryItem, } from '@symbiote-native/components';
+import { VirtualizedList, } from '../virtualized-list';
+function resolveSeparator(component) {
+    if (component === undefined)
+        return undefined;
+    if (typeof component === 'function')
+        return createElement(component, {});
+    return component;
+}
+export function VirtualizedSectionList(props) {
+    const { ref, sections, renderItem, renderSectionHeader, renderSectionFooter, SectionSeparatorComponent, 
+    // Pulled out of `rest`: the user's separator is typed on ItemT, but the inner VirtualizedList
+    // streams ISectionEntry<ItemT>, so we wrap it to unwrap each entry back to its ItemT.
+    ItemSeparatorComponent, keyExtractor, stickySectionHeadersEnabled, ...rest } = props;
+    const { entries, headerIndices } = flattenSections(sections, SectionSeparatorComponent !== undefined);
+    // RN sticks section headers by default only on iOS; Android does not unless asked. headerIndices
+    // are the flat positions of every section header; VirtualizedList forwards the in-window ones.
+    const stickyDefault = Platform.OS === 'ios';
+    const stickyEnabled = stickySectionHeadersEnabled ?? stickyDefault;
+    const stickyHeaderIndices = stickyEnabled ? headerIndices : undefined;
+    // The handle reaches into the inner VirtualizedList to drive scrollToIndex.
+    const listRef = useRef(null);
+    dlog(`VirtualizedSectionList: ${sections.length} sections flattened to ${entries.length} entries`);
+    useImperativeHandle(ref ?? null, () => ({
+        scrollToLocation: (params) => {
+            const flatIndex = scrollLocationToFlatIndex(headerIndices, params.sectionIndex, params.itemIndex);
+            if (flatIndex === undefined) {
+                dlog(`VirtualizedSectionList scrollToLocation: section ${params.sectionIndex} out of range`);
+                return;
+            }
+            dlog(`VirtualizedSectionList scrollToLocation section=${params.sectionIndex} ` +
+                `item=${params.itemIndex} -> flat ${flatIndex}`);
+            listRef.current?.scrollToIndex({
+                index: flatIndex,
+                viewOffset: params.viewOffset,
+                viewPosition: params.viewPosition,
+                animated: params.animated,
+            });
+        },
+        flashScrollIndicators: () => {
+            listRef.current?.flashScrollIndicators();
+        },
+        getNativeScrollRef: () => listRef.current?.getNativeScrollRef() ?? null,
+        getScrollableNode: () => listRef.current?.getScrollableNode() ?? null,
+        getScrollResponder: () => listRef.current?.getScrollResponder() ?? null,
+        getScrollNode: () => listRef.current?.getScrollNode() ?? null,
+        recordInteraction: () => {
+            listRef.current?.recordInteraction();
+        },
+    }), [headerIndices]);
+    const renderEntry = (info) => {
+        const entry = info.item;
+        if (entry.kind === 'header') {
+            return renderSectionHeader ? renderSectionHeader({ section: entry.section }) : undefined;
+        }
+        if (entry.kind === 'footer') {
+            return renderSectionFooter ? renderSectionFooter({ section: entry.section }) : undefined;
+        }
+        if (entry.kind === 'section-separator') {
+            return resolveSeparator(SectionSeparatorComponent);
+        }
+        return renderItem({
+            item: entry.item,
+            index: entry.itemIndex,
+            section: entry.section,
+            separators: info.separators,
+        });
+    };
+    // The user's ItemSeparatorComponent is typed on ItemT; the inner stream is the entry wrapper, so
+    // unwrap each entry back to its ItemT (shared unwrapEntryItem) before handing it to the user.
+    const entrySeparatorComponent = ItemSeparatorComponent === undefined
+        ? undefined
+        : (entryProps) => createElement(ItemSeparatorComponent, {
+            ...entryProps,
+            leadingItem: unwrapEntryItem(entryProps.leadingItem),
+            trailingItem: unwrapEntryItem(entryProps.trailingItem),
+        });
+    const entryKeyExtractor = (entry, index) => sectionEntryKey(entry, index, keyExtractor);
+    return createElement((VirtualizedList), {
+        ref: listRef,
+        data: entries,
+        getItem: (_source, index) => entries[index],
+        getItemCount: () => entries.length,
+        renderItem: renderEntry,
+        keyExtractor: entryKeyExtractor,
+        stickyHeaderIndices,
+        ItemSeparatorComponent: entrySeparatorComponent,
+        ...rest,
+    });
+}

package/build/components.d.ts

@@ -0,0 +1,54 @@
+import { type FC, type Ref, type ReactNode } from 'react';
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import type { IHostInstance } from './host-instance';
+import { type IAccessibilityProps, type IAriaProps } from '@symbiote-native/components';
+import type { IResponderProps } from './utils/responder-props';
+import type { IStyleProp, ITextStyle, IViewStyle } from './utils/styles';
+export interface IViewProps extends IAccessibilityProps, IAriaProps, IResponderProps {
+    style?: IStyleProp<IViewStyle>;
+    className?: string;
+    onPress?: (event: ISymbioteEvent) => void;
+    onPressIn?: (event: ISymbioteEvent) => void;
+    onPressOut?: (event: ISymbioteEvent) => void;
+    onLayout?: (event: ISymbioteEvent) => void;
+    onFocus?: (event: ISymbioteEvent) => void;
+    onBlur?: (event: ISymbioteEvent) => void;
+    pointerEvents?: 'auto' | 'none' | 'box-none' | 'box-only';
+    hitSlop?: number | {
+        top?: number;
+        left?: number;
+        bottom?: number;
+        right?: number;
+    };
+    id?: string;
+    focusable?: boolean;
+    collapsable?: boolean;
+    removeClippedSubviews?: boolean;
+    renderToHardwareTextureAndroid?: boolean;
+    shouldRasterizeIOS?: boolean;
+    needsOffscreenAlphaCompositing?: boolean;
+    ref?: Ref<IHostInstance>;
+    children?: ReactNode;
+}
+export interface ITextProps extends IAccessibilityProps, IAriaProps {
+    style?: IStyleProp<ITextStyle>;
+    className?: string;
+    onPress?: (event: ISymbioteEvent) => void;
+    onLongPress?: (event: ISymbioteEvent) => void;
+    onPressIn?: (event: ISymbioteEvent) => void;
+    onPressOut?: (event: ISymbioteEvent) => void;
+    onLayout?: (event: ISymbioteEvent) => void;
+    onTextLayout?: (event: ISymbioteEvent) => void;
+    numberOfLines?: number;
+    ellipsizeMode?: 'head' | 'middle' | 'tail' | 'clip';
+    selectable?: boolean;
+    adjustsFontSizeToFit?: boolean;
+    minimumFontScale?: number;
+    allowFontScaling?: boolean;
+    maxFontSizeMultiplier?: number | null;
+    selectionColor?: string;
+    ref?: Ref<IHostInstance>;
+    children?: ReactNode;
+}
+export declare const View: FC<IViewProps>;
+export declare const Text: FC<ITextProps>;

package/build/components.js

@@ -0,0 +1,17 @@
+// Host primitives exposed to user code. They are thin wrappers that produce the
+// lowercase host elements the reconciler understands (`view` / `text`); the
+// reconciler maps those to shared's mutation API, which resolves them to Fabric
+// view names at commit.
+import { createElement } from 'react';
+import { resolveAccessibilityProps, } from '@symbiote-native/components';
+// RN's modern `id` is just a W3C-named alias for `nativeID`: View.js copies it over
+// (`processedProps.nativeID = id`), so `id` wins when both are set. We fold it here and
+// blank the alias so a raw `id` never reaches Fabric (every non-function prop passes
+// through to the slot otherwise).
+function resolveId({ id, ...rest }) {
+    if (id === undefined)
+        return rest;
+    return { ...rest, nativeID: id };
+}
+export const View = props => createElement('symbiote-view', resolveAccessibilityProps(resolveId(props)));
+export const Text = props => createElement('symbiote-text', resolveAccessibilityProps(props));

package/build/create-portal.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode, ReactPortal } from 'react';
+import { SymbioteSurface, type ISymbioteNode } from '@symbiote-native/engine';
+export type IPortalContainer = ISymbioteNode | SymbioteSurface;
+export declare function createPortal(children: ReactNode, container: IPortalContainer, key?: string | null): ReactPortal;

package/build/create-portal.js

@@ -0,0 +1,23 @@
+// createPortal — react-reconciler's Fiber-level portal primitive (HostPortal), not a
+// react-dom re-export. Stock React Native does NOT support this: real RN's Fabric host
+// config runs in PERSISTENT mode and never implements the mutation-mode container ops
+// (appendChildToContainer / insertInContainerBefore / removeChildFromContainer) createPortal
+// needs — see facebook/react-native#36273 ("Portal children gets overriden in Fabric").
+// @symbiote-native/react is deliberately MUTATION mode and already implements all three (host-config.ts),
+// so a portal here structurally works where it never could in real RN.
+//
+// Scope (v1): the target must be an already-mounted node WITHIN THE SAME SURFACE as the portal's
+// call site (e.g. a ref to a persistent "overlay host" View near your app root) — not a second,
+// independently-mounted SymbioteSurface. Cross-surface targets aren't wired: resetAfterCommit only
+// fires for the primary root's own container, so a different surface's tree would never repaint.
+import { isSymbioteNode, SymbioteSurface } from '@symbiote-native/engine';
+import reconciler from './host-config';
+export function createPortal(children, container, key) {
+    if (!(container instanceof SymbioteSurface) && !isSymbioteNode(container)) {
+        throw new Error('createPortal target must be an already-mounted host node (e.g. a ref to a rendered <View>) — got something else. Did you forget `.current`/`.value`, or pass a CSS-selector-style string?');
+    }
+    // @ts-expect-error @types/react-reconciler's ReactPortal (containerInfo/implementation) and
+    // react's own ReactPortal (type/props, a ReactElement) are different interfaces describing the
+    // SAME runtime object; react-reconciler's is what reconciler.createPortal actually returns.
+    return reconciler.createPortal(children, container, null, key ?? null);
+}

package/build/create-tunnel.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from 'react';
+export interface ITunnel {
+    /** Renders nothing; registers its children under the tunnel from wherever it's mounted —
+     *  any surface. */
+    In: (props: {
+        children: ReactNode;
+    }) => null;
+    /** Renders everything currently tunneled in, in registration order. Mount this in the
+     *  component that should actually paint the content. */
+    Out: () => ReactNode;
+}
+export declare function createTunnel(): ITunnel;

package/build/create-tunnel.js

@@ -0,0 +1,60 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// createTunnel — the cross-surface answer to createPortal's same-surface-only v1 scope
+// (react-adapter-portal skill). Prior art: pmndrs/tunnel-rat exists precisely because a real
+// createPortal cannot reach across two genuinely separate reconciler roots — see
+// github.com/facebook/react/issues/17147 ("react-reconciler & portals: missing root
+// instance"). The fix is the one the ecosystem already settled on: don't reach into a
+// foreign surface's commit machinery — let that surface commit ITSELF, normally, by reading
+// from a store it's already subscribed to.
+//
+// Both In and Out are COMPONENTS (the Vue twin's shape, and the same pattern as
+// Context.Provider/Context.Consumer) — NOT hooks. This isn't just nicer call-site ergonomics:
+// it's what makes the cascade in the first place structurally impossible. An earlier
+// hook-based version (`useTunnelIn`/`useTunnelOut`, called directly inside one component)
+// produced a genuine infinite render loop — a silent white screen on device, no thrown error
+// — because notify() forces a re-render of whichever component's useSyncExternalStore call
+// subscribed, and when THAT was the SAME component that also called useTunnelIn, its own
+// effect re-ran and notified again, forever (this custom renderer's synchronous commit loop
+// has no "Maximum update depth exceeded" guard to catch it). As separate components, notify()
+// only forces Out's OWN render scope — never In's, even when both are children of the same
+// parent — so the update has nowhere to bounce back to. `Out` lives inside whichever surface
+// should PAINT the content (e.g. a persistent overlay-host surface); `In` lives ANYWHERE, same
+// surface or a totally different one, and never touches a Fabric node directly, so there is
+// no "target must already be mounted" guard to satisfy at all.
+import { Fragment, useEffect, useId, useSyncExternalStore } from 'react';
+export function createTunnel() {
+    const items = new Map();
+    const listeners = new Set();
+    // useSyncExternalStore bails out via Object.is on the snapshot reference, so it must stay
+    // stable between reads — rebuilt only when the Map actually changes, never inline.
+    let snapshot = [];
+    function notify() {
+        snapshot = Array.from(items.values());
+        listeners.forEach(listener => listener());
+    }
+    function In({ children }) {
+        const id = useId();
+        // Every render of In: keep this id's content in sync. Safe to run unconditionally (no
+        // dependency array) — In and Out are separate components, so notify()'s forced re-render
+        // of Out never bounces back into In (see the file header for why that matters).
+        useEffect(() => {
+            // Wrapped in a keyed Fragment: Out renders `snapshot` as a list, and a bare ReactNode
+            // (possibly a fragment-less element or a string) has no key of its own.
+            items.set(id, _jsx(Fragment, { children: children }, id));
+            notify();
+        });
+        // Once, on real unmount: drop this id for good.
+        useEffect(() => () => {
+            items.delete(id);
+            notify();
+        }, [id]);
+        return null;
+    }
+    function Out() {
+        return useSyncExternalStore(listener => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        }, () => snapshot);
+    }
+    return { In, Out };
+}

package/build/descriptor-to-react/index.d.ts

@@ -0,0 +1,3 @@
+import type { ReactElement } from 'react';
+import type { IDescriptor } from '@symbiote-native/components';
+export declare function descriptorToReact(node: IDescriptor, index?: number): ReactElement;

package/build/descriptor-to-react/index.js

@@ -0,0 +1,15 @@
+// The descriptor→element bridge. A render function in @symbiote-native/components returns a
+// framework-agnostic `Descriptor` tree; this maps it onto React elements. The resulting
+// host element (`symbiote-view`, `symbiote-activity-indicator`, …) flows on through the
+// react-reconciler host config → engine → Fabric, exactly like a hand-written JSX host
+// element. The wolf-tui twin is `packages/react/src/wnode/wnode-to-react.tsx`.
+import { createElement } from 'react';
+export function descriptorToReact(node, index) {
+    const children = node.children.map(toChild);
+    // `key` first so a Descriptor that carries its own `key` in props still wins; list
+    // items (once components emit keyed children) diff correctly.
+    return createElement(node.type, { key: node.key ?? index, ...node.props }, ...children);
+}
+function toChild(child, index) {
+    return typeof child === 'string' ? child : descriptorToReact(child, index);
+}

package/build/hooks/use-color-scheme.d.ts

@@ -0,0 +1,2 @@
+import { type IColorSchemeName } from '../modules/appearance';
+export declare function useColorScheme(): IColorSchemeName | null;

package/build/hooks/use-color-scheme.js

@@ -0,0 +1,13 @@
+// useColorScheme subscribes a component to the device color scheme and re-renders
+// on change. Mirrors RN's Libraries/Utilities/useColorScheme.js: a thin
+// useSyncExternalStore over Appearance's change event + current scheme read.
+import { useSyncExternalStore } from 'react';
+import { Appearance } from '../modules/appearance';
+const subscribe = (onStoreChange) => {
+    const subscription = Appearance.addChangeListener(onStoreChange);
+    return () => subscription.remove();
+};
+const getSnapshot = () => Appearance.getColorScheme();
+export function useColorScheme() {
+    return useSyncExternalStore(subscribe, getSnapshot);
+}

package/build/hooks/use-window-dimensions.d.ts

@@ -0,0 +1,2 @@
+import { type IDisplayMetrics } from '../modules/dimensions';
+export declare function useWindowDimensions(): IDisplayMetrics;

package/build/hooks/use-window-dimensions.js

@@ -0,0 +1,30 @@
+// useWindowDimensions is the preferred API for components that need window metrics,
+// a port of RN's Libraries/Utilities/useWindowDimensions.js. It seeds from
+// Dimensions.get('window'), subscribes to 'change', and re-checks once after
+// subscribing to close the gap between the render-time get and the effect-time
+// listener. Only the window metrics changing triggers a re-render.
+import { useEffect, useState } from 'react';
+import { Dimensions } from '../modules/dimensions';
+export function useWindowDimensions() {
+    const [dimensions, setDimensions] = useState(() => Dimensions.get('window'));
+    useEffect(() => {
+        function handleChange(window) {
+            if (dimensions.width !== window.width ||
+                dimensions.height !== window.height ||
+                dimensions.scale !== window.scale ||
+                dimensions.fontScale !== window.fontScale) {
+                setDimensions(window);
+            }
+        }
+        const subscription = Dimensions.addEventListener('change', (set) => {
+            handleChange(set.window);
+        });
+        // We may have missed an update between calling `get` in render and subscribing
+        // here; re-check now. If nothing changed, React filters the no-op set.
+        handleChange(Dimensions.get('window'));
+        return () => {
+            subscription.remove();
+        };
+    }, [dimensions]);
+    return dimensions;
+}

package/build/host-config.d.ts

@@ -0,0 +1,7 @@
+import createReconciler from 'react-reconciler';
+import { SymbioteSurface, type ISymbioteNode } from '@symbiote-native/engine';
+import { type IHostInstance } from './host-instance';
+type IContainer = SymbioteSurface | ISymbioteNode;
+export declare function withDiscretePriority(run: () => void): void;
+declare const reconciler: createReconciler.Reconciler<IContainer, ISymbioteNode, ISymbioteNode, never, unknown, IHostInstance>;
+export default reconciler;

package/build/host-config.js

@@ -0,0 +1,169 @@
+// react-reconciler host config in MUTATION mode. Every host operation maps onto
+// shared's tiny mutation API; shared owns all Fabric-specific work (tag
+// allocation, view-name resolution, clone-on-write, events). This is the
+// canary: a known-good driver exercising shared end to end.
+import createReconciler from 'react-reconciler';
+import { createContext } from 'react';
+import { appendChild, createElement, createRawText, insertBefore, removeChild, routeProp, setText, SymbioteSurface, } from '@symbiote-native/engine';
+import { DefaultEventPriority, DiscreteEventPriority, NoEventPriority, } from './reconciler-constants';
+import { toPublicInstance } from './host-instance';
+// Intrinsic JSX type -> Fabric component name. The name table + resolver live once in
+// @symbiote-native/components, shared by every adapter so the names can't drift (one engine, one
+// Fabric). The table is Metro-split (.ios/.android, filename selects, no Platform.OS read,
+// per ADR 0020). Adding a primitive is one entry in each name table there, plus its thin
+// component in components.ts: no host-config logic per primitive.
+import { descriptorFor } from '@symbiote-native/components';
+// React-reserved prop keys that must never reach Fabric. `children` is the element
+// tree (handled via appendChild). `ref`/`key` are React 19 plain props: the reconciler
+// reads `props.ref` for commitAttachRef but does NOT strip it from the props it hands a
+// host config, so `ref.current` (the public instance, a bag of methods like measure /
+// focus) would serialize into folly::dynamic and throw "not convertible to dynamic" on
+// Android. Stripping here is the host config's job, exactly as RN's own renderer does.
+function isReservedProp(key) {
+    return key === 'children' || key === 'ref' || key === 'key';
+}
+function applyProps(node, props) {
+    for (const [key, value] of Object.entries(props)) {
+        if (isReservedProp(key))
+            continue;
+        routeProp(node, key, value);
+    }
+}
+function applyUpdate(node, oldProps, newProps) {
+    for (const key of Object.keys(oldProps)) {
+        if (isReservedProp(key))
+            continue;
+        if (!Object.hasOwn(newProps, key))
+            routeProp(node, key, undefined);
+    }
+    for (const [key, value] of Object.entries(newProps)) {
+        if (isReservedProp(key))
+            continue;
+        if (value !== oldProps[key])
+            routeProp(node, key, value);
+    }
+}
+function isSurfaceContainer(container) {
+    return container instanceof SymbioteSurface;
+}
+let currentUpdatePriority = NoEventPriority;
+// Run an externally-triggered update (a native event) at discrete priority so it
+// lands on the sync lane and flushSyncWork paints it immediately.
+export function withDiscretePriority(run) {
+    const previous = currentUpdatePriority;
+    currentUpdatePriority = DiscreteEventPriority;
+    try {
+        run();
+    }
+    finally {
+        currentUpdatePriority = previous;
+    }
+}
+const reconciler = createReconciler({
+    isPrimaryRenderer: true,
+    supportsMutation: true,
+    supportsPersistence: false,
+    supportsHydration: false,
+    noTimeout: -1,
+    scheduleTimeout: setTimeout,
+    cancelTimeout: clearTimeout,
+    getRootHostContext: () => ({ isInsideText: false }),
+    getChildHostContext(parentHostContext, type) {
+        const isInsideText = descriptorFor(type).isText;
+        return parentHostContext.isInsideText === isInsideText ? parentHostContext : { isInsideText };
+    },
+    getPublicInstance: instance => toPublicInstance(instance),
+    prepareForCommit: () => null,
+    // Called once per commit with the PRIMARY root's own container only — never with a portal's
+    // target (portal mutations recommit as part of the same surface's tree walk, since the target
+    // must be a node already inside that surface; see create-portal.ts).
+    resetAfterCommit: container => {
+        if (isSurfaceContainer(container))
+            container.commit();
+    },
+    preparePortalMount: () => { },
+    clearContainer: container => {
+        if (isSurfaceContainer(container))
+            container.clear();
+    },
+    shouldSetTextContent: () => false,
+    createInstance(type, props, _container, hostContext) {
+        const descriptor = descriptorFor(type);
+        if (hostContext.isInsideText && !descriptor.isText) {
+            throw new Error(`<${type}> can't be nested inside <Text>`);
+        }
+        const node = createElement(descriptor.component, descriptor.isText);
+        applyProps(node, props);
+        return node;
+    },
+    createTextInstance(text, _container, hostContext) {
+        if (!hostContext.isInsideText) {
+            throw new Error(`Text string "${text}" must be rendered inside a <Text>`);
+        }
+        return createRawText(text);
+    },
+    appendInitialChild: (parent, child) => appendChild(parent, child),
+    appendChild: (parent, child) => appendChild(parent, child),
+    appendChildToContainer: (container, child) => {
+        if (isSurfaceContainer(container))
+            container.appendChild(child);
+        else
+            appendChild(container, child);
+    },
+    insertBefore: (parent, child, before) => insertBefore(parent, child, before),
+    insertInContainerBefore: (container, child, before) => {
+        if (isSurfaceContainer(container))
+            container.insertBefore(child, before);
+        else
+            insertBefore(container, child, before);
+    },
+    removeChild: (parent, child) => removeChild(parent, child),
+    removeChildFromContainer: (container, child) => {
+        if (isSurfaceContainer(container))
+            container.removeChild(child);
+        else
+            removeChild(container, child);
+    },
+    finalizeInitialChildren: () => false,
+    commitUpdate(node, _type, oldProps, newProps) {
+        applyUpdate(node, oldProps, newProps);
+    },
+    commitTextUpdate(node, _oldText, newText) {
+        setText(node, newText);
+    },
+    resetTextContent: () => { },
+    hideTextInstance: node => setText(node, ''),
+    unhideTextInstance: (node, text) => setText(node, text),
+    hideInstance: () => { },
+    unhideInstance: () => { },
+    beforeActiveInstanceBlur: () => { },
+    afterActiveInstanceBlur: () => { },
+    detachDeletedInstance: () => { },
+    getInstanceFromNode: () => null,
+    prepareScopeUpdate: () => { },
+    getInstanceFromScope: () => null,
+    setCurrentUpdatePriority: priority => {
+        currentUpdatePriority = priority;
+    },
+    getCurrentUpdatePriority: () => currentUpdatePriority,
+    resolveUpdatePriority: () => currentUpdatePriority !== NoEventPriority ? currentUpdatePriority : DefaultEventPriority,
+    maySuspendCommit: () => false,
+    NotPendingTransition: null,
+    // react's Context IS the runtime value react-reconciler's ReactContext wants
+    // (it reads _currentValue off it); the two libraries' type defs model
+    // Consumer/Provider differently and cannot be reconciled structurally. This is
+    // a type-def mismatch only, flagged here so a future @types fix forces cleanup.
+    // @ts-expect-error cross-library Context type-def mismatch (runtime-correct)
+    HostTransitionContext: createContext(null),
+    resetFormInstance: () => { },
+    requestPostPaintCallback: () => { },
+    shouldAttemptEagerTransition: () => false,
+    trackSchedulerEvent: () => { },
+    resolveEventType: () => null,
+    resolveEventTimeStamp: () => -1.1,
+    preloadInstance: () => true,
+    startSuspendingCommit: () => { },
+    suspendInstance: () => { },
+    waitForCommitToBeReady: () => null,
+});
+export default reconciler;

package/build/host-instance.d.ts

@@ -0,0 +1,3 @@
+import { toPublicInstance, type ISymbioteNode, type IHostInstance } from '@symbiote-native/engine';
+export { toPublicInstance, type IHostInstance };
+export declare function findNodeHandle(componentOrHandle: IHostInstance | ISymbioteNode | number | null | undefined): number | null;

package/build/host-instance.js

@@ -0,0 +1,20 @@
+// The public instance a host ref hands back and the ref -> tag lookup. toPublicInstance and
+// IHostInstance now live in @symbiote-native/engine (they depend only on engine internals, so every
+// adapter inherits the SAME public instance); this module re-exports them so the React surface
+// (`@symbiote-native/react` exports findNodeHandle + IHostInstance, host-config grafts via
+// toPublicInstance) is unchanged. findNodeHandle stays here: it is the React-shaped "ref ->
+// native tag" lookup over the engine's getNativeTag.
+import { getNativeTag, isSymbioteNode, toPublicInstance, } from '@symbiote-native/engine';
+export { toPublicInstance };
+// The committed native tag of a host ref (or a bare tag, idempotent). RN's
+// findNodeHandle: a ref/instance resolves to its reactTag, a number passes through,
+// null/undefined yields null. Undefined-until-committed surfaces as null.
+export function findNodeHandle(componentOrHandle) {
+    if (componentOrHandle === null || componentOrHandle === undefined)
+        return null;
+    if (typeof componentOrHandle === 'number')
+        return componentOrHandle;
+    if (isSymbioteNode(componentOrHandle))
+        return getNativeTag(componentOrHandle) ?? null;
+    return null;
+}