@symbiote-native/engine 0.5.0 → 1.0.0

package/build/structured-style.js

@@ -0,0 +1,180 @@
+// The ten style keys RN parses in JS before native, and the one place they are resolved.
+//
+// WHY THEY RUN AT WRITE TIME AND NOT AT PAYLOAD-BUILD TIME. On a device the payload is built by
+// `core/engine/cpp/SymbioteFabricProps.cpp`, which does not carry these — they are pure JS. So a
+// `boxShadow: '0 2px 4px #000'` resolved only inside `fabric-props.ts` is resolved only headless,
+// and the device gets the raw CSS string. Fabric's C++ parses a style string ONLY under
+// `enableNativeCSSParsing()`, which defaults to FALSE, so the declaration is dropped in silence:
+// no warning, no wrong value, just a gradient or a shadow that is not there. Resolving on the way
+// IN puts the structured value in `node.props` itself, which is the one thing both payload builders
+// read.
+//
+// This is the same move `configPayloadFold` makes for a third-party view's own processors, one
+// layer down: anything the C++ half cannot do has to happen before the C++ half sees the value.
+//
+// IDENTITY IS PART OF THE CONTRACT. A style object that needs nothing comes back BY IDENTITY, and
+// so does an array whose every entry did. The host's `OP_SET_PROP` skips a same-identity write, and
+// `pushClassStyle` compares what it is about to publish against what it published last — hand
+// either of them a fresh object per write and an unchanged style becomes a write and a dirty node
+// on every render.
+import { processAspectRatio } from './process-aspect-ratio.js';
+import { processBackgroundImage } from './process-background-image/index.js';
+import { processBackgroundPosition, processBackgroundRepeat, processBackgroundSize, } from './process-background-longhands.js';
+import { processBoxShadow } from './process-box-shadow/index.js';
+import { processFilter } from './process-filter.js';
+import { processFontVariant } from './process-font-variant.js';
+import { processTransform } from './process-transform/index.js';
+import { processTransformOrigin } from './process-transform-origin/index.js';
+import { isRecord, isString } from './type-guards.js';
+function isStringOrNumber(value) {
+    return typeof value === 'string' || typeof value === 'number';
+}
+// boxShadow accepts a CSS string or an array of shadow objects; anything else is
+// undefined to processBoxShadow (which returns []). Narrowing avoids an `as` cast.
+function asBoxShadowInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.filter(isRecord);
+    return undefined;
+}
+// filter accepts a CSS string or an array of single-key filter objects; same narrowing.
+function asFilterInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.filter(isRecord);
+    return undefined;
+}
+// experimental_backgroundImage accepts a CSS string (gradient functions) or an array of
+// structured gradient objects; same narrowing as boxShadow/filter.
+function asBackgroundImageInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.filter(isRecord);
+    return undefined;
+}
+// transformOrigin accepts a CSS string or a [x, y, z] array of strings/numbers; anything
+// else is undefined to processTransformOrigin (which defaults to center/center/0).
+function asTransformOriginInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.filter(isStringOrNumber);
+    return undefined;
+}
+// aspectRatio accepts a number (the common, working form) or a ratio string; otherwise
+// undefined, which processAspectRatio drops.
+function asAspectRatioInput(value) {
+    if (typeof value === 'number' || typeof value === 'string')
+        return value;
+    return undefined;
+}
+// fontVariant accepts an array of variant strings (the common, working form) or a
+// space-separated string; anything else becomes an empty string, which yields [].
+function asFontVariantInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.filter(isString);
+    return '';
+}
+// transform accepts a CSS string (processTransform parses it) or an array of single-key
+// transform records (the hot animated / sticky-header path). A non-string non-array value is NOT
+// dropped: it may already be processed, so it passes through verbatim rather than being coerced to
+// [] (which would erase a valid transform).
+function processTransformValue(value) {
+    if (typeof value === 'string')
+        return processTransform(value);
+    if (Array.isArray(value))
+        return processTransform(value.filter(isRecord));
+    return value;
+}
+const STYLE_PROCESSORS = new Map([
+    ['boxShadow', value => processBoxShadow(asBoxShadowInput(value))],
+    ['filter', value => processFilter(asFilterInput(value))],
+    [
+        'transformOrigin',
+        value => processTransformOrigin(asTransformOriginInput(value)),
+    ],
+    ['transform', processTransformValue],
+    ['aspectRatio', value => processAspectRatio(asAspectRatioInput(value))],
+    ['fontVariant', value => processFontVariant(asFontVariantInput(value))],
+    [
+        'experimental_backgroundImage',
+        value => processBackgroundImage(asBackgroundImageInput(value)),
+    ],
+    [
+        'experimental_backgroundSize',
+        value => processBackgroundSize(asBackgroundLonghandInput(value)),
+    ],
+    [
+        'experimental_backgroundPosition',
+        value => processBackgroundPosition(asBackgroundLonghandInput(value)),
+    ],
+    [
+        'experimental_backgroundRepeat',
+        value => processBackgroundRepeat(asBackgroundLonghandInput(value)),
+    ],
+]);
+// All three longhands take the same two shapes: a CSS string, or an already-structured array RN
+// passes through untouched. Anything else is undefined, which upstream answers with [] and the
+// wrapper turns into an absent key.
+function asBackgroundLonghandInput(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value;
+    return undefined;
+}
+// Keyed on the style object, so a class-resolved style shared by a thousand rows is resolved once.
+// The value is the object to USE — which is the input itself whenever nothing needed resolving, so
+// a hit costs one lookup and returns the same reference the caller already had.
+const resolvedStyles = new WeakMap();
+function resolveRecord(style) {
+    const cached = resolvedStyles.get(style);
+    if (cached !== undefined)
+        return cached;
+    let out;
+    for (const [key, process] of STYLE_PROCESSORS) {
+        if (!(key in style))
+            continue;
+        const value = style[key];
+        if (value === undefined)
+            continue;
+        const next = process(value);
+        if (Object.is(next, value))
+            continue;
+        const claimed = out ?? { ...style };
+        claimed[key] = next;
+        out = claimed;
+    }
+    const answer = out ?? style;
+    resolvedStyles.set(style, answer);
+    return answer;
+}
+/**
+ * A style value with its structured keys resolved — the same value by identity when there was
+ * nothing to resolve, which is nearly always.
+ *
+ * Accepts what a style slot can hold: one object, or a (nested) array of them. An array is not
+ * memoized — `pushClassStyle` mints a fresh one on every publish, so a cache keyed on it could
+ * never hit; its ENTRIES carry the memo instead, and the original array comes back untouched when
+ * none of them moved.
+ */
+export function resolveStructuredStyle(style) {
+    if (Array.isArray(style)) {
+        let out;
+        for (let at = 0; at < style.length; at += 1) {
+            const next = resolveStructuredStyle(style[at]);
+            if (Object.is(next, style[at]))
+                continue;
+            const claimed = out ?? [...style];
+            claimed[at] = next;
+            out = claimed;
+        }
+        return out ?? style;
+    }
+    return isRecord(style) ? resolveRecord(style) : style;
+}

package/build/style-registry/index.d.ts

@@ -13,6 +13,20 @@ export declare function registerRules(rules: readonly IStyleRule[]): void;
 export declare function clearGlobalStyles(): void;
 export declare function isClassNameValue(value: unknown): value is IClassNameValue;
 export declare function canonicalClassName(className: IClassNameValue): IClassNameValue;
+/**
+ * The one object every "this class styles nothing" answer hands back.
+ *
+ * A FRESH `{}` was the previous answer, and it quietly cost two things. `isAlreadyPublished`
+ * compares slot 0 with `Object.is`, so a node whose class is absent or matches no rule republished
+ * its whole style — and re-dirtied itself — on every class or style write, which is precisely the
+ * storm that guard exists to stop; and `pushClassStyle` had no way to tell "resolved to nothing"
+ * from "resolved to something", so the empty result crossed the wire as a real value.
+ *
+ * Frozen because it is now shared by every such node in the app: a caller that mutated the result
+ * used to corrupt one node's style and would now corrupt all of them. No caller does — every one
+ * spreads it — and freezing is what keeps that true.
+ */
+export declare const EMPTY_STYLE: IResolvedStyle;
 export declare function resolveClassName(className: IClassNameValue): IResolvedStyle;
 export declare function resolveActiveClassName(className: IClassNameValue): IResolvedStyle;
 export {};

package/build/style-registry/index.js

@@ -58,8 +58,9 @@ let ruleEpoch = 0;
 // flattenStyle shallow-copies.
 const resolvedCache = new Map();
 // Bounded so a screen generating unique class strings at runtime cannot grow it without limit.
-// Overflow drops everything rather than evicting one entry: the cache is a warm-up optimization,
-// not a working set, and an LRU's bookkeeping costs more than the rebuild it saves.
+// Overflow evicts ONE entry at random — see `memoise` for why random and not the obvious
+// alternatives. It used to drop everything, which turned a working set one entry too wide into a
+// total miss on every lookup.
 const RESOLVED_CACHE_LIMIT = 512;
 // The pressed variant, keyed by the SAME authored string. Separate from `resolvedCache` so the two
 // can never collide on one key, and string-keyed for the same reason that one is: identity is the
@@ -87,7 +88,45 @@ let hasActiveRules = false;
 // per commit, and only the second one is hot.
 function invalidateResolved() {
     resolvedCache.clear();
+    resolvedKeys.length = 0;
     activeCache.clear();
+    activeKeys.length = 0;
+}
+// The victim pool for the two caches below — a plain array of the keys each holds, so a random
+// eviction is an index rather than a scan. This is the entire bookkeeping cost of the policy, and
+// it is less than FIFO's would be: nothing about recency or order is tracked.
+const resolvedKeys = [];
+const activeKeys = [];
+/**
+ * Memoise, evicting a RANDOM entry when full.
+ *
+ * WHY RANDOM, since it looks arbitrary next to the obvious answers. The policy this replaced dropped
+ * the whole cache on overflow, and the reflex repair — evict the oldest — is no better on the access
+ * pattern that actually hurts. A working set slightly WIDER than the cache, walked in order, is
+ * Belady's worst case: FIFO and LRU each evict exactly the entry the next lookup wants, so both miss
+ * on every single access, exactly as the full clear did. Measured on a 512-entry cache cycling 513
+ * distinct class strings: clear 0%, FIFO 0%, random 94.7% (`cache-cliff.probe.test.ts`).
+ *
+ * Random also answers the objection that ruled LRU out here — it needs LESS bookkeeping, not more.
+ * There is no recency to maintain; a key array and a swap-remove is the whole of it.
+ *
+ * The cache stays a pure memo of a pure function either way, so which entries survive changes only
+ * which lookups pay the rebuild. `invalidateResolved` still drops everything when the cascade moves,
+ * because then nothing resolved earlier is true any more.
+ */
+function memoise(cache, keys, key, value) {
+    if (cache.size >= RESOLVED_CACHE_LIMIT) {
+        const victimAt = Math.floor(Math.random() * keys.length);
+        const victim = keys[victimAt];
+        if (victim !== undefined) {
+            cache.delete(victim);
+            const last = keys.pop();
+            if (last !== undefined && victimAt < keys.length)
+                keys[victimAt] = last;
+        }
+    }
+    cache.set(key, value);
+    keys.push(key);
 }
 export function registerRules(rules) {
     invalidateResolved();
@@ -142,9 +181,23 @@ export function canonicalClassName(className) {
         ? className.join(' ')
         : className;
 }
+/**
+ * The one object every "this class styles nothing" answer hands back.
+ *
+ * A FRESH `{}` was the previous answer, and it quietly cost two things. `isAlreadyPublished`
+ * compares slot 0 with `Object.is`, so a node whose class is absent or matches no rule republished
+ * its whole style — and re-dirtied itself — on every class or style write, which is precisely the
+ * storm that guard exists to stop; and `pushClassStyle` had no way to tell "resolved to nothing"
+ * from "resolved to something", so the empty result crossed the wire as a real value.
+ *
+ * Frozen because it is now shared by every such node in the app: a caller that mutated the result
+ * used to corrupt one node's style and would now corrupt all of them. No caller does — every one
+ * spreads it — and freezing is what keeps that true.
+ */
+export const EMPTY_STYLE = Object.freeze({});
 export function resolveClassName(className) {
     if (!className)
-        return {};
+        return EMPTY_STYLE;
     if (typeof className === 'object' && !Array.isArray(className)) {
         return className;
     }
@@ -162,9 +215,7 @@ export function resolveClassName(className) {
     if (cached !== undefined)
         return cached;
     const resolved = resolveClassString(className);
-    if (resolvedCache.size >= RESOLVED_CACHE_LIMIT)
-        resolvedCache.clear();
-    resolvedCache.set(className, resolved);
+    memoise(resolvedCache, resolvedKeys, className, resolved);
     return resolved;
 }
 // The same element's style with `:active` added to its token list — so a `.btn:active` rule joins
@@ -191,16 +242,14 @@ export function resolveActiveClassName(className) {
         return cached;
     const parts = className.trim().split(/\s+/).filter(Boolean);
     const resolved = parts.length === 0 ? {} : (matchRules([...parts, STATE_TOKEN]) ?? {});
-    if (activeCache.size >= RESOLVED_CACHE_LIMIT)
-        activeCache.clear();
-    activeCache.set(className, resolved);
+    memoise(activeCache, activeKeys, className, resolved);
     return resolved;
 }
 function resolveClassString(className) {
     const parts = className.trim().split(/\s+/).filter(Boolean);
     if (parts.length === 0)
-        return {};
-    return matchRules(parts) ?? {};
+        return EMPTY_STYLE;
+    return matchRules(parts) ?? EMPTY_STYLE;
 }
 // `null` rather than `{}` for "nothing matched", so the caller can skip the empty-object churn on
 // every class-prop set that has no rules.

package/build/surface.d.ts

@@ -2,15 +2,44 @@ import type { IRootTag } from './fabric';
 import { type ISymbioteNode } from './node';
 export declare class SymbioteSurface {
     readonly rootTag: IRootTag;
-    readonly children: ISymbioteNode[];
+    /** The AppContainer root every top-level node hangs off, and the handle `OP_COMMIT` names. */
+    private readonly node;
     private commitScheduled;
     constructor(rootTag: IRootTag);
+    /**
+     * Every OTHER live surface, so one commit names every root — see `commitSurfaceOps`.
+     *
+     * Static because it reads a sibling instance's private handle, which only a member of this class
+     * may do. One surface — the universal case — allocates nothing.
+     *
+     * `self` may already be OUT of the registry: a teardown unregisters and then commits, and that
+     * commit is the one carrying the removals. So the fast path cannot be a size check — with one
+     * live surface left, `size === 1` means either "only me" or "only the other one", and taking the
+     * shortcut on the second reading is how a surface loses the very batch that empties it.
+     */
+    private static others;
+    /**
+     * The top-level nodes, asked of the host.
+     *
+     * A getter rather than an array this class maintains: a second copy of a child list is the thing
+     * this design removes, and `nextSiblingOf` (host-access.ts) needs the same answer the host gives
+     * for a parented node.
+     */
+    get children(): readonly ISymbioteNode[];
     appendChild(child: ISymbioteNode): void;
     insertBefore(child: ISymbioteNode, beforeChild: ISymbioteNode): void;
     removeChild(child: ISymbioteNode): void;
     clear(): void;
+    /**
+     * Release every host behavior still standing under this surface, at unmount.
+     *
+     * The sweep above cannot answer this: it only sees nodes a `removeChild` NOMINATED, and an
+     * unmount removes nothing — the adapter drops the whole surface. Without it every node keeps its
+     * `afterCommit` registration and its timers, and a restarted surface's commits drain the dead
+     * one's hooks forever.
+     */
+    teardown(): void;
     commit(): void;
     requestCommit(): void;
-    private detach;
 }
 export declare function createSurface(rootTag: IRootTag): SymbioteSurface;

package/build/surface.js

@@ -1,57 +1,147 @@
-// A surface is one mounted root: it owns the rootTag handed down by the native
-// Fabric host and the list of top-level retained nodes. Adapters mutate it and
-// ask it to commit; the surface coalesces commits and drives the engine.
-import { commitChildren } from './commit.js';
+// A surface is one mounted root: it owns the rootTag handed down by the native Fabric host and the
+// top-level nodes under it. Adapters mutate it and ask it to commit.
+//
+// A SURFACE IS ONE ORDINARY NODE, and that is the whole implementation rather than a trick. It holds
+// a real handle, its child ops are the ordinary append / insertBefore / removeChild, and `OP_COMMIT`
+// names that one handle — so the host needs no `rootTag -> node` map, which is what keeps it
+// stateless.
+//
+// The node is RN's AppContainer (`createSurfaceRoot` in `node.ts` — `flex: 1`, `box-none`), so what
+// reaches the root child set is one view with the app under it. An ANCHOR in the same position
+// hoists its children instead, and the host takes both through the same call, so nothing here is a
+// special case.
 import { dlog } from './debug.js';
 import { installEventHandler } from './events/index.js';
-import { markStructureDirty } from './node.js';
-import { hasHostBehaviors, markDetachCandidate } from './host-behavior.js';
-import { hasAnimatedBindings } from './animated/host-binding.js';
+import { detachAnimatedProps } from './animated/host-binding.js';
+import { childrenOf } from './host-access.js';
+import { runCommittedHooks, runDeferredAttaches, hasDetachCandidates, sweepDetachedBehaviors, teardownSubtree, } from './host-behavior.js';
+import { getNativeTag, notifyCommitted, registerSurfaceCommit, } from './imperative.js';
+import { runPostCommitHooks } from './post-commit.js';
+import { appendChild, createSurfaceRoot, insertBefore, removeChild, } from './node.js';
+import { commitSurfaceOps, flushOps } from './tree-host.js';
+const NO_CO_COMMITTERS = [];
+// The predicate both behavior drains take. Passed in rather than imported by `host-behavior.ts`,
+// keeping that dependency one-directional — a cycle there is a live hazard under Metro's
+// `inlineRequires`.
+const isNodeCommitted = (node) => getNativeTag(node) !== undefined;
 export class SymbioteSurface {
     rootTag;
-    children = [];
+    /** The AppContainer root every top-level node hangs off, and the handle `OP_COMMIT` names. */
+    node;
     commitScheduled = false;
     constructor(rootTag) {
         this.rootTag = rootTag;
+        this.node = createSurfaceRoot();
+    }
+    /**
+     * Every OTHER live surface, so one commit names every root — see `commitSurfaceOps`.
+     *
+     * Static because it reads a sibling instance's private handle, which only a member of this class
+     * may do. One surface — the universal case — allocates nothing.
+     *
+     * `self` may already be OUT of the registry: a teardown unregisters and then commits, and that
+     * commit is the one carrying the removals. So the fast path cannot be a size check — with one
+     * live surface left, `size === 1` means either "only me" or "only the other one", and taking the
+     * shortcut on the second reading is how a surface loses the very batch that empties it.
+     */
+    static others(self) {
+        let out;
+        for (const other of surfaces.values()) {
+            if (other === self)
+                continue;
+            out ??= [];
+            out.push([other.rootTag, other.node]);
+        }
+        return out ?? NO_CO_COMMITTERS;
+    }
+    /**
+     * The top-level nodes, asked of the host.
+     *
+     * A getter rather than an array this class maintains: a second copy of a child list is the thing
+     * this design removes, and `nextSiblingOf` (host-access.ts) needs the same answer the host gives
+     * for a parented node.
+     */
+    get children() {
+        return childrenOf(this.node);
     }
     appendChild(child) {
-        this.detach(child);
-        child.parent = undefined;
-        this.children.push(child);
+        appendChild(this.node, child);
     }
     insertBefore(child, beforeChild) {
-        this.detach(child);
-        child.parent = undefined;
-        const index = this.children.indexOf(beforeChild);
-        this.children.splice(index < 0 ? this.children.length : index, 0, child);
+        insertBefore(this.node, child, beforeChild);
     }
-    // Nominates for teardown exactly as `node.ts`'s `removeChild` does, and for the same reason it
-    // only NOMINATES: a framework may spell a move as remove-then-reinsert, so the commit sweep
-    // decides. Without this the surface is the one removal path that never reaches the sweep, and a
-    // node's behavior — its timers included — outlives the surface with nothing red.
-    //
-    // `detach` above is deliberately NOT nominated: the two inserts call it to reposition a child
-    // that is staying.
+    // Nomination for teardown rides on `node.ts`'s `removeChild`, and only NOMINATES for the reason
+    // stated there: a framework may spell a move as remove-then-reinsert, so the commit sweep
+    // decides. The surface is one ordinary node, so it is not a second removal path that could miss
+    // the sweep and leave a behavior — its timers included — outliving the surface.
     removeChild(child) {
-        const index = this.children.indexOf(child);
-        if (index >= 0)
-            this.children.splice(index, 1);
-        if (hasHostBehaviors() || hasAnimatedBindings())
-            markDetachCandidate(child);
+        removeChild(this.node, child);
     }
     clear() {
-        if (hasHostBehaviors() || hasAnimatedBindings())
-            for (const child of this.children)
-                markDetachCandidate(child);
-        this.children.length = 0;
+        for (const child of this.children)
+            removeChild(this.node, child);
+    }
+    /**
+     * Release every host behavior still standing under this surface, at unmount.
+     *
+     * The sweep above cannot answer this: it only sees nodes a `removeChild` NOMINATED, and an
+     * unmount removes nothing — the adapter drops the whole surface. Without it every node keeps its
+     * `afterCommit` registration and its timers, and a restarted surface's commits drain the dead
+     * one's hooks forever.
+     */
+    teardown() {
+        // The nominations first: an adapter that empties the surface and disposes it without a commit
+        // in between (React's `clearContainer`) never reaches the commit sweep, and the walk below
+        // cannot see those nodes either — they already left the tree.
+        sweepDetachedBehaviors(this.children, detachAnimatedProps);
+        teardownSubtree(this.node, detachAnimatedProps);
     }
-    // Synchronous commit: used by React's resetAfterCommit, which already
-    // batches per logical update.
+    // Synchronous commit: used by React's resetAfterCommit, which already batches per logical update.
     commit() {
-        commitChildren(this.rootTag, this.children);
+        // A SUPERSEDED surface still flushes its ops and still names every other root — its teardown is
+        // what carries the removals — but it must not complete a root another surface now owns. Fast
+        // Refresh and the focus lifecycle re-mount the same rootTag, so the old surface's teardown
+        // commit lands AFTER the new one's mount commit and would hand Fabric the emptied tree.
+        // An UNREGISTERED surface is not superseded — nobody took the root, so its final emptied tree
+        // is still the truth for it. Only a live OTHER owner suppresses the op.
+        // The teardown half of the behavior lifecycle. It runs AFTER the ops are applied — it decides
+        // what really left by asking the host for a parent, and the host does not know about a removal
+        // it has not been handed — but BEFORE the root is completed, so a behavior's parting writes
+        // (ScrollView taking its forced `scrollEventThrottle` back) ride this commit instead of owing
+        // another one. `flushOps` is that split: apply, do not publish.
+        //
+        // `removeChild` only NOMINATES — a framework spells a move as remove-then-reinsert, so tearing
+        // down at the call would kill a machine that comes back in the same batch.
+        flushOps();
+        // GUARDED AT THE CALL SITE, not inside the sweep — `this.children` is a host read that builds
+        // the whole top-level list, and it would run on every commit for a sweep that had nothing to do.
+        if (hasDetachCandidates()) {
+            sweepDetachedBehaviors(this.children, detachAnimatedProps);
+        }
+        const owner = surfaces.get(this.rootTag);
+        const superseded = owner !== undefined && owner !== this;
+        commitSurfaceOps(superseded ? undefined : this.rootTag, this.node, SymbioteSurface.others(this));
+        // Fresh Fabric handles are now assigned, so the three things that could not run before one
+        // existed all drain here — this is the moment the old `commitChildren` drained them too.
+        //
+        // `notifyCommitted` releases the imperative waiters (`whenCommitted`); `runPostCommitHooks` the
+        // consumers that needed a committed TAG and ran too early, which is the Animated native driver
+        // binding a props node under an async-batched commit; `runDeferredAttaches` the half of a host
+        // behavior whose setup needs a tag (a view command, an event attach). The predicate is passed in
+        // rather than imported by `host-behavior.ts`, keeping that dependency one-directional — a cycle
+        // there is a live hazard under Metro's `inlineRequires`.
+        notifyCommitted();
+        runPostCommitHooks();
+        runDeferredAttaches(isNodeCommitted);
+        // After the setup half, never before it: a node carrying both hooks has `attachAfterCommit`
+        // seed the mirrors `afterCommit` then compares against. Unlike the two above it asks only
+        // "props were published", so it is NOT gated on the commit having made native calls — a fold
+        // that strips a prop makes its own commit byte-identical, and the hook that must react to the
+        // flip would be the one the flip cannot wake.
+        runCommittedHooks(isNodeCommitted);
     }
-    // Coalesced commit: for reactive frameworks that emit many mutations per
-    // tick. Collapses to a single completeRoot at the microtask boundary.
+    // Coalesced commit: for reactive frameworks that emit many mutations per tick. Collapses to a
+    // single completeRoot at the microtask boundary.
     requestCommit() {
         if (this.commitScheduled)
             return;
@@ -61,30 +151,22 @@ export class SymbioteSurface {
             this.commit();
         });
     }
-    // Splices `parent.children` directly instead of going through node.ts's removeChild, so it
-    // owes the same marks - otherwise a node pulled out of a subtree here leaves that subtree
-    // looking clean and the commit walk skips right over the hole, and commitTargeted would rebuild
-    // that parent's child set from a snapshot that still contains the removed node.
-    detach(child) {
-        const parent = child.parent;
-        if (parent) {
-            // Marks before the splice, like node.ts's own structural ops: the committed record may be
-            // aliasing `parent.children`, and this call is what copies it out of the way.
-            markStructureDirty(parent);
-            const index = parent.children.indexOf(child);
-            if (index >= 0)
-                parent.children.splice(index, 1);
-            child.parent = undefined;
-            return;
-        }
-        const topIndex = this.children.indexOf(child);
-        if (topIndex >= 0)
-            this.children.splice(topIndex, 1);
-    }
 }
+// Every live surface, so the microtask flush in `imperative.ts` can commit the one a queued write
+// named. Registered from here rather than imported there: a surface owns its own commit, and
+// reaching into it from the imperative half would put back the cycle that split exists to remove.
+const surfaces = new Map();
+registerSurfaceCommit(rootTag => {
+    surfaces.get(rootTag)?.commit();
+}, rootTag => {
+    const surface = surfaces.get(rootTag);
+    surfaces.delete(rootTag);
+    surface?.teardown();
+});
 export function createSurface(rootTag) {
     installEventHandler();
     const surface = new SymbioteSurface(rootTag);
+    surfaces.set(rootTag, surface);
     dlog(`surface created root=${rootTag}`);
     return surface;
 }

package/build/text-input-state.d.ts

@@ -3,3 +3,4 @@ export declare function currentlyFocusedInput(): ISymbioteNode | null;
 export declare function setInputFocused(node: ISymbioteNode): void;
 export declare function setInputBlurred(node: ISymbioteNode): void;
 export declare function blurTextInput(node: ISymbioteNode | null): void;
+export declare function focusTextInput(node: ISymbioteNode | null): void;

package/build/text-input-state.js

@@ -2,7 +2,7 @@
 // JS-side because native exposes no focus getter. TextInput reports focus/blur here so
 // Keyboard.dismiss can blur whatever holds focus without a ref, exactly how RN's
 // dismissKeyboard() works (blurTextInput(currentlyFocusedInput())).
-import { dispatchViewCommand } from './commit.js';
+import { dispatchViewCommand, propOf } from './imperative.js';
 import { dlog } from './debug.js';
 let currentlyFocused = null;
 // The input that last reported focus and hasn't reported blur, or null.
@@ -19,11 +19,25 @@ export function setInputBlurred(node) {
         currentlyFocused = null;
 }
 // Imperative blur: drive the native `blur` view command and drop the tracked focus.
-// Used by TextInput.blur() and Keyboard.dismiss().
+// Used by TextInput.blur() and Keyboard.dismiss(). A no-op if this node isn't the
+// currently-focused one — mirrors RN's TextInputState.blurTextInput, which guards the
+// same way so blurring an already-unfocused input never reaches native.
 export function blurTextInput(node) {
-    if (node === null)
+    if (node === null || currentlyFocused !== node)
         return;
     dlog('TextInputState.blurTextInput -> blur command');
     dispatchViewCommand(node, 'blur', []);
     setInputBlurred(node);
 }
+// Imperative focus: RN's `ReactNativeElement.focus()` routes a text input through
+// `TextInputState.focusTextInput`, not a raw command — same guard as blur, plus a check
+// this side of the pair also carries: already-focused or `editable: false` is a no-op.
+export function focusTextInput(node) {
+    if (node === null)
+        return;
+    if (currentlyFocused === node || propOf(node, 'editable') === false)
+        return;
+    dlog('TextInputState.focusTextInput -> focus command');
+    setInputFocused(node);
+    dispatchViewCommand(node, 'focus', []);
+}