@symbiote-native/engine 1.3.0 → 1.4.0

package/build/node-style.js

@@ -0,0 +1,214 @@
+// The declarative style slots and their publication: two halves an adapter may write in either
+// order, merged into the one array the payload carries
+import { recordSetUnderlayShown } from './mutation-buffer.js';
+import { EMPTY_STYLE, resolveActiveClassName, } from './style-registry/index.js';
+import { setProp } from './node-props.js';
+// Narrowed rather than cast: `routeProp` takes `unknown`, and a bare `typeof v === 'function'`
+// leaves TS with `Function`, callable with anything
+export function isStyleCallback(value) {
+    return typeof value === 'function';
+}
+// All slots present from the start rather than added as they are written, so a styled node keeps
+// one hidden class instead of paying a shape transition per slot
+export function stylePartsOf(node) {
+    return (node.styleParts ??= {
+        classStyle: undefined,
+        explicitStyle: undefined,
+        hiddenStyle: undefined,
+        className: undefined,
+        isPressed: false,
+        activeStyle: undefined,
+        activeStyleFromCallback: false,
+        published: undefined,
+    });
+}
+// Slot 1's twin of `baseStyleOf`: the variant replaces slot 1, not slot 0, so it beats the class
+// cascade the way the authored style does while a `:active` rule can still win slot 0 underneath
+function explicitStyleOf(parts) {
+    return parts.isPressed && parts.activeStyle !== undefined
+        ? parts.activeStyle
+        : parts.explicitStyle;
+}
+// `resolveActiveClassName` resolves the element's tokens PLUS `:active` through the same matcher,
+// so the result already contains everything the base class gave. Resolved LAZILY at press time,
+// т.к. eager would double the resolutions on every class WRITE to serve a rare state
+function baseStyleOf(parts) {
+    return parts.isPressed && typeof parts.className === 'string'
+        ? resolveActiveClassName(parts.className)
+        : parts.classStyle;
+}
+// What a node publishes when NOTHING resolves. Length 0 is the marker and needs no second field,
+// т.к. `pushClassStyle` never otherwise publishes an empty array
+const PUBLISHED_NOTHING = Object.freeze([]);
+// `mutation-buffer.ts` interns values BY IDENTITY, so distinct-but-equal arrays across a list
+// styled the same way cost distinct entries and separate conversions to `folly::dynamic`
+// `WeakMap` at both levels so nothing grows unbounded. The three-slot (hidden) form is deliberately
+// NOT cached: `display: 'none'` is rare, so a third map would be paid for on every write
+const sharedPairByExplicit = new WeakMap();
+const sharedPairByBase = new WeakMap();
+// The published array for this pair, the same object every time the same two parts are handed in.
+// `undefined` when the pair cannot be keyed, and the caller then builds its own array
+function sharedStylePair(base, explicit) {
+    const baseIsKeyable = typeof base === 'object' && base !== null;
+    const explicitIsKeyable = typeof explicit === 'object' && explicit !== null;
+    if (base === undefined && explicitIsKeyable) {
+        const cached = sharedPairByExplicit.get(explicit);
+        if (cached !== undefined)
+            return cached;
+        const made = [base, explicit];
+        sharedPairByExplicit.set(explicit, made);
+        return made;
+    }
+    if (!baseIsKeyable)
+        return undefined;
+    if (explicit === undefined) {
+        const cached = sharedPairByBase.get(base);
+        if (Array.isArray(cached))
+            return cached;
+        if (cached === undefined) {
+            const made = [base, explicit];
+            sharedPairByBase.set(base, made);
+            return made;
+        }
+        // A base already seen WITH an explicit half holds the second-level map here, and the base-only
+        // array has nowhere to live beside it. Rare enough not to earn a third map
+        return undefined;
+    }
+    if (!explicitIsKeyable)
+        return undefined;
+    const existing = sharedPairByBase.get(base);
+    const byExplicit = existing instanceof WeakMap ? existing : new WeakMap();
+    if (existing === undefined)
+        sharedPairByBase.set(base, byExplicit);
+    // The same clash the other way round: this base is holding its base-only array, so leave it
+    if (Array.isArray(existing))
+        return undefined;
+    const cached = byExplicit.get(explicit);
+    if (cached !== undefined)
+        return cached;
+    const made = [base, explicit];
+    byExplicit.set(explicit, made);
+    return made;
+}
+// A plain style bag: not an array of styles, not a callback, not null
+function isStyleRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Is this rebuilt style the same style, key for key? A component body writing its style inline
+// hands over a fresh object every render, equal to the one standing, which `Object.is` cannot see
+// Shallow and conservative: a nested value reports "not the same" rather than being deep-compared,
+// so being wrong here is slow and never incorrect
+export function isSameShallowStyle(next, standing) {
+    // THE SAME OBJECT IS THE SAME STYLE, checked first: without it a re-push of a hoisted constant
+    // allocates two key arrays and walks them to reach the answer identity gives for free
+    if (next === standing)
+        return isStyleRecord(next);
+    if (!isStyleRecord(next) || !isStyleRecord(standing))
+        return false;
+    const keys = Object.keys(next);
+    if (keys.length !== Object.keys(standing).length)
+        return false;
+    for (const key of keys) {
+        const value = next[key];
+        if (value === undefined || isStyleRecord(value) || Array.isArray(value)) {
+            return false;
+        }
+        if (!Object.is(value, standing[key]))
+            return false;
+    }
+    return true;
+}
+function contributesNothing(slot) {
+    return slot === undefined || slot === EMPTY_STYLE;
+}
+// Read through the same two resolvers as the publication: guard and publication disagreeing is a
+// silent wrong screen
+function hasNothingToPublish(parts) {
+    return (parts.hiddenStyle === undefined &&
+        contributesNothing(baseStyleOf(parts)) &&
+        contributesNothing(explicitStyleOf(parts)));
+}
+function isAlreadyPublished(parts) {
+    const published = parts.published;
+    if (published === undefined)
+        return false;
+    // The delete is already standing. Asked before the slot comparisons, т.к. an empty array would
+    // otherwise pass both on `undefined` and then fail the length check
+    if (published.length === 0)
+        return hasNothingToPublish(parts);
+    // Through the resolvers, not the raw slots: guard and publication must read slot 0 and slot 1 the
+    // same way, or a press is turned away as already-published and does nothing with nothing red
+    if (!Object.is(published[0], baseStyleOf(parts)))
+        return false;
+    if (!Object.is(published[1], explicitStyleOf(parts)))
+        return false;
+    return parts.hiddenStyle === undefined
+        ? published.length === 2
+        : published.length === 3 && Object.is(published[2], parts.hiddenStyle);
+}
+// The fresh ARRAY allocation stays DELIBERATELY: `setNativeProps` bypasses these parts, so a
+// hoisted style constant would be skipped by the identity guard and never restore the declarative
+// style an animation overwrote. The re-push IS the restore path
+export function pushClassStyle(node, parts) {
+    // An unchanged class still reaches this write, т.к. Solid has no diff. The guard keys off
+    // `published`, which `setNativeProps` clears, so an imperative restore still re-publishes
+    if (isAlreadyPublished(parts))
+        return;
+    // Emits NO_VALUE rather than `[undefined, undefined]`, so the host skips a real array with one
+    // pointer check instead of building and diffing a `folly::dynamic`
+    if (hasNothingToPublish(parts)) {
+        parts.published = PUBLISHED_NOTHING;
+        setProp(node, 'style', undefined);
+        return;
+    }
+    // Third slot only appended while hidden: a permanent 3-element array would add an allocation to
+    // every style write for a state most nodes never enter
+    const base = baseStyleOf(parts);
+    const explicit = explicitStyleOf(parts);
+    const published = parts.hiddenStyle === undefined
+        ? (sharedStylePair(base, explicit) ?? [base, explicit])
+        : [base, explicit, parts.hiddenStyle];
+    parts.published = published;
+    setProp(node, 'style', published);
+}
+// `display: 'none'` is a real RN style value (Yoga's DisplayNone), so a hidden node keeps its
+// place in the tree, its state and its children, and just stops laying out and painting
+const HIDDEN_STYLE = { display: 'none' };
+// The seam React's Activity/Suspense reach for through `hideInstance` / `unhideInstance`. In the
+// engine rather than an adapter, т.к. restoring the author's style byte belongs to the style merge
+export function setNodeHidden(node, hidden) {
+    const parts = stylePartsOf(node);
+    parts.hiddenStyle = hidden ? HIDDEN_STYLE : undefined;
+    pushClassStyle(node, parts);
+}
+// Put a node into (or out of) its pressed state so `:active` rules apply. Costs nothing when no
+// `:active` rule is registered, т.к. `isAlreadyPublished` turns the re-push away
+export function setNodePressed(node, pressed) {
+    const parts = stylePartsOf(node);
+    parts.isPressed = pressed;
+    pushClassStyle(node, parts);
+}
+// Tell the host a behavior's FEEDBACK is showing, which is TouchableHighlight's underlay and only
+// that. Not the same bit as `setNodePressed`, т.к. `shown` lags `pressed` by a timer
+export function setNodeUnderlayShown(node, shown) {
+    recordSetUnderlayShown(node, shown);
+}
+// Forget what was last published so the next `pushClassStyle` cannot be turned away. A no-op for a
+// node nobody has styled, which is why this is not `stylePartsOf(node).published = undefined`
+export function clearPublishedStyle(node) {
+    if (node.styleParts !== undefined)
+        node.styleParts.published = undefined;
+}
+// The explicit (non-class) style half, which an adapter building style key by key merges onto
+// rather than `node.props.style`, which may hold the pair `pushClassStyle` publishes
+export function getExplicitStyle(node) {
+    return node.styleParts?.explicitStyle;
+}
+// The `[classStyle, explicitStyle]` pair the node publishes, in the order `pushClassStyle` writes.
+// For a caller that wants the merged answer without a host, `core/css-parser` reads it here
+export function getPublishedStyle(node) {
+    const parts = node.styleParts;
+    if (parts === undefined)
+        return [];
+    return [parts.classStyle, parts.explicitStyle];
+}

package/build/node-tree.d.ts

@@ -0,0 +1,6 @@
+import { type ISymbioteNode } from './node-types';
+import type { ITreeCensus } from './tree-host';
+export declare function appendChild(requestedParent: ISymbioteNode, child: ISymbioteNode): void;
+export declare function insertBefore(requestedParent: ISymbioteNode, child: ISymbioteNode, beforeChild: ISymbioteNode | null | undefined): void;
+export declare function removeChild(requestedParent: ISymbioteNode, child: ISymbioteNode): void;
+export declare function censusRetainedTree(roots: readonly ISymbioteNode[]): ITreeCensus;

package/build/node-tree.js

@@ -0,0 +1,159 @@
+// The structural ops. Each is one op and nothing else: the host detaches a child from whatever
+// parent it currently has before linking it, so JS never tracks the old parent
+import { recordAppendChild, recordInsertBefore, recordRemoveChild, } from './mutation-buffer.js';
+import { claimModeFor, hasAttachedBehaviors, hasHostBehaviors, markDetachCandidate, notifyChildInserted, noteCommitHookNodeChanged, reattachHostBehaviors, slotTakesChildren, } from './host-behavior.js';
+import { hasAnimatedBindings, reattachAnimatedProps, } from './animated/host-binding.js';
+import { EMPTY_CENSUS, flushOps, treeHost } from './tree-host.js';
+import { isSymbioteNode } from './node-types.js';
+// The host's raw answer, surface INCLUDED, unlike `parentOf` in `host-access.ts`, which reports a
+// top-level node as parentless by design. The two swaps below have to NAME the holder in an op
+function holderOf(node) {
+    flushOps();
+    const parent = treeHost()?.parentOf(node);
+    return isSymbioteNode(parent) ? parent : undefined;
+}
+// Which node a child actually lands on: the adapter always names the OWNER, and a node whose
+// behavior built an internal subtree redirects the app's children into it unless the behavior
+// CLAIMS this particular child
+function hostFor(parent, child) {
+    const slot = parent.childHost;
+    if (slot === undefined)
+        return parent;
+    // A slot that is a built SIBLING rather than a container (ImageBackground's filled image) keeps
+    // the app's children on the owner
+    if (!slotTakesChildren(parent))
+        return parent;
+    return claimModeFor(parent, child.component) === undefined ? slot : parent;
+}
+// The node a child must be inserted before, or `undefined` for an ordinary append. A host that
+// still has a slot is an owner taking a claimed child, which goes before the slot whatever the
+// framework asked, т.к. RN renders `{refreshControl}{content}` in that order
+function slotAnchorOf(host) {
+    const slot = host.childHost;
+    if (slot === undefined || !slotTakesChildren(host))
+        return undefined;
+    return slot;
+}
+// Arm a parent's recurring post-commit hook for a STRUCTURAL change, not just a prop write: the
+// sticky-header machine drops a wrapper writing no prop at all, and a props-only beat left it stuck
+function armCommitHookForChildChange(parent) {
+    if (parent.hasCommitHook)
+        noteCommitHookNodeChanged(parent);
+}
+// `mayHaveChildren` is only sound if every op that gives a node a child raises it, so it is raised
+// in these two rather than at each of the five call sites
+function recordAppendInto(parent, child) {
+    parent.mayHaveChildren = true;
+    armCommitHookForChildChange(parent);
+    recordAppendChild(parent, child);
+}
+function recordInsertInto(parent, child, beforeChild) {
+    parent.mayHaveChildren = true;
+    armCommitHookForChildChange(parent);
+    recordInsertBefore(parent, child, beforeChild);
+}
+// What actually occupies this node's place in its parent's child list: a wrapped owner is what the
+// adapter names and the wrapper is what the tree holds
+function placedNode(node) {
+    return node.wrapper ?? node;
+}
+// Make `child` the owner's parent, in place, returning false when this is not a wrap claim. The
+// owner being unattached is the normal case, т.к. every adapter fills a node's children before
+// appending it to its own parent
+function wrapsOwner(owner, child) {
+    if (owner.childHost === undefined)
+        return false;
+    if (claimModeFor(owner, child.component) !== 'wrap')
+        return false;
+    if (hasHostBehaviors())
+        reattachHostBehaviors(child);
+    if (hasAnimatedBindings())
+        reattachAnimatedProps(child);
+    const holder = holderOf(owner);
+    // Wrapper takes the owner's place first, then the owner moves under it: the host's own detach on
+    // link is what unlinks the owner from `holder`, so no removal op is needed
+    if (holder !== undefined)
+        recordInsertInto(holder, child, owner);
+    owner.wrapper = child;
+    recordAppendInto(child, owner);
+    return true;
+}
+// Put the owner back where its wrapper stood, the mirror of `wrapsOwner`. It must leave the owner
+// ATTACHED: the framework is removing the RefreshControl, not the ScrollView
+function unwrapsOwner(owner, child) {
+    if (owner.wrapper !== child)
+        return false;
+    owner.wrapper = undefined;
+    const holder = holderOf(child);
+    if (holder === undefined) {
+        // The wrapper never reached a parent, so there is no place to take back
+        recordRemoveChild(child, owner);
+    }
+    else {
+        recordInsertInto(holder, owner, child);
+        recordRemoveChild(holder, child);
+    }
+    return true;
+}
+// The body both inserts share: only the anchor differs, and NO anchor means append. A real case
+// rather than a defensive guard, т.к. `solid-js/universal` spells "insert at end" as
+// `insertNode(parent, node, null)` and Vue passes `anchor` through
+function place(requestedParent, child, beforeChild) {
+    if (wrapsOwner(requestedParent, child))
+        return;
+    const parent = hostFor(requestedParent, child);
+    // A node the sweep tore down can be put back, т.к. Svelte parks live subtrees offscreen across
+    // commits. A `WeakSet` miss for anything freshly built, so the create path pays nothing
+    if (hasHostBehaviors())
+        reattachHostBehaviors(child);
+    if (hasAnimatedBindings())
+        reattachAnimatedProps(child);
+    const placed = placedNode(child);
+    const anchor = slotAnchorOf(parent) ??
+        (beforeChild === null || beforeChild === undefined
+            ? undefined
+            : placedNode(beforeChild));
+    if (anchor === undefined)
+        recordAppendInto(parent, placed);
+    else
+        recordInsertInto(parent, placed, anchor);
+    if (hasHostBehaviors())
+        notifyChildInserted(parent, placed);
+}
+export function appendChild(requestedParent, child) {
+    place(requestedParent, child, undefined);
+}
+export function insertBefore(requestedParent, child, beforeChild) {
+    place(requestedParent, child, beforeChild);
+}
+// Removal only NOMINATES a behavior for teardown and the commit sweep decides, т.к. a framework may
+// spell a move as remove-then-reinsert and the machine must survive it
+export function removeChild(requestedParent, child) {
+    // A wrap claim leaving: the owner takes its own place back and stays in the tree, nominated for
+    // teardown like any other removed node т.к. the wrapper IS leaving
+    if (unwrapsOwner(requestedParent, child)) {
+        if (hasAttachedBehaviors() || hasAnimatedBindings())
+            markDetachCandidate(child);
+        return;
+    }
+    // A slot that IS the child being removed stops being one. Without the clear, `hostFor` below
+    // redirects the removal into the node being removed and the next child nests inside the orphan
+    if (requestedParent.childHost === child)
+        requestedParent.childHost = undefined;
+    const parent = hostFor(requestedParent, child);
+    // `hasAttachedBehaviors`, not `hasHostBehaviors`: the latter is on from module load in every app
+    // just from registering Pressable as a type
+    if (hasAttachedBehaviors() || hasAnimatedBindings())
+        markDetachCandidate(child);
+    // BOTH, and the owner is the one that matters: a composed primitive's behavior lives on the node
+    // the adapter named, while `hostFor` redirects the mutation into its internal slot
+    armCommitHookForChildChange(requestedParent);
+    armCommitHookForChildChange(parent);
+    recordRemoveChild(parent, placedNode(child));
+}
+// A structural census of the tree the HOST holds. Walks nothing here, т.к. the walk needs
+// `props.text` and a child list, and JS has neither
+export function censusRetainedTree(roots) {
+    flushOps();
+    return treeHost()?.census(roots) ?? EMPTY_CENSUS;
+}

package/build/node-types.d.ts

@@ -0,0 +1,70 @@
+import type { IMeasureOnSuccess, IMeasureInWindowOnSuccess, IMeasureLayoutOnSuccess } from './fabric';
+import type { IHostBehavior, IPayloadFold } from './host-behavior';
+import type { IClassNameValue } from './style-registry';
+export declare const BRAND: unique symbol;
+export declare const RAW_TEXT_COMPONENT = "RCTRawText";
+export declare const TEXT_COMPONENT = "RCTText";
+export declare const VIRTUAL_TEXT_COMPONENT = "RCTVirtualText";
+export declare const ANCHOR_COMPONENT = "#anchor";
+export declare const VOID_COMPONENT = "#void";
+export declare const SURFACE_COMPONENT = "#surface";
+export interface ISymbioteEvent {
+    type: string;
+    target: ISymbioteNode;
+    currentTarget: ISymbioteNode;
+    nativeEvent: Record<string, unknown>;
+    stopPropagation: () => void;
+}
+export type IListener = (event: ISymbioteEvent) => unknown;
+export type IEventDispatch = {
+    readonly names: ReadonlySet<string>;
+    readonly deliver: (node: ISymbioteNode, name: string, event: ISymbioteEvent) => unknown;
+};
+export declare function isSymbioteEvent(value: unknown): value is ISymbioteEvent;
+export interface IClassStyleParts {
+    classStyle: unknown;
+    explicitStyle: unknown;
+    hiddenStyle: unknown;
+    className: IClassNameValue | undefined;
+    isPressed: boolean;
+    activeStyle: unknown;
+    activeStyleFromCallback: boolean;
+    published: readonly unknown[] | undefined;
+}
+export interface ISymbioteNode {
+    readonly [BRAND]: true;
+    component: string;
+    readonly isText: boolean;
+    listeners: Map<string, IListener> | undefined;
+    dispatch: IEventDispatch | undefined;
+    hasCommitHook: boolean;
+    resolvesImageSources: boolean;
+    nativeIdWinsOverId: boolean;
+    payloadFold: IPayloadFold | undefined;
+    hostBehavior: IHostBehavior | undefined;
+    styleParts: IClassStyleParts | undefined;
+    childHost: ISymbioteNode | undefined;
+    wrapper: ISymbioteNode | undefined;
+    mayHaveChildren: boolean;
+    isTornDown: boolean;
+    slot: number;
+    slotBatch: number;
+    createdBatch: number;
+    measure(callback: IMeasureOnSuccess): void;
+    measureInWindow(callback: IMeasureInWindowOnSuccess): void;
+    measureLayout(relativeToNativeNode: ISymbioteNode | number, onSuccess: IMeasureLayoutOnSuccess, onFail?: () => void): void;
+    setNativeProps(nativeProps: Record<string, unknown>): void;
+    focus(): void;
+    blur(): void;
+    scrollTo(options?: {
+        x?: number;
+        y?: number;
+        animated?: boolean;
+    }): void;
+    scrollToEnd(options?: {
+        animated?: boolean;
+    }): void;
+    flashScrollIndicators(): void;
+}
+export declare function isSymbioteNode(value: unknown): value is ISymbioteNode;
+export declare function isAnchor(node: ISymbioteNode): boolean;

package/build/node-types.js

@@ -0,0 +1,36 @@
+// The node's SHAPE and nothing that acts on it: the interface every sibling of `node.ts` writes
+// through, the Fabric view names, and the two guards
+export const BRAND = Symbol('symbiote.node');
+// A node carries the Fabric view name directly, so adding a primitive is just a new string from
+// the adapter. The one name resolved at commit time is text: `isText` marks a container, and a
+// `<Text>` nested inside another commits as a virtual span
+export const RAW_TEXT_COMPONENT = 'RCTRawText';
+export const TEXT_COMPONENT = 'RCTText';
+export const VIRTUAL_TEXT_COMPONENT = 'RCTVirtualText';
+// Vue's runtime-core needs anchor nodes (fragments, `v-if`, `v-for`) to track sibling order and
+// Fabric has no such concept. A real retained node keeps the ordering correct, and the commit walk
+// SKIPS it so no native view is created
+export const ANCHOR_COMPONENT = '#anchor';
+// The sentinel a primitive resolves to when its ENTIRE subtree must vanish from Fabric on this
+// platform (`input-accessory-view` on Android). An anchor hoists its children up, a void node does
+// not: the walk stops there, recursively
+export const VOID_COMPONENT = '#void';
+// The sentinel a SURFACE's own root node carries, so `parentOf` can stop there and a top-level node
+// answers `undefined` for its parent. JS-side name only, т.к. what goes over the wire is `RCTView`
+export const SURFACE_COMPONENT = '#surface';
+// Guard narrowing `unknown` to `ISymbioteEvent`, beside the interface it tests so every adapter
+// checking for a Symbiote event shares one instead of writing its own
+export function isSymbioteEvent(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const nativeEvent = Reflect.get(value, 'nativeEvent');
+    return typeof nativeEvent === 'object' && nativeEvent !== null;
+}
+// `instanceHandle` round-trips through Fabric unchanged and comes back as the event target, so our
+// nodes are branded and the handler can confirm one is ours
+export function isSymbioteNode(value) {
+    return typeof value === 'object' && value !== null && BRAND in value;
+}
+export function isAnchor(node) {
+    return node.component === ANCHOR_COMPONENT;
+}