@symbiote-native/engine 1.3.0 → 1.4.0

package/build/mutation-buffer.d.ts

@@ -1,10 +1,3 @@
-/**
- * The opcodes. These numbers ARE the contract: renumbering here without renumbering the C++ commits
- * a different tree, silently, and no test in either language can see across the boundary.
- *
- * Stride is fixed so the ops array is addressable as memory rather than parsed. Operands are either
- * a SLOT (an index into the batch's `handles` array — see below) or an index into a side table.
- */
 export declare const OP_STRIDE = 6;
 export declare const OP_CREATE_ELEMENT = 0;
 export declare const OP_CREATE_RAW_TEXT = 1;
@@ -16,123 +9,18 @@ export declare const OP_SET_PROP = 6;
 export declare const OP_SET_TEXT = 7;
 export declare const OP_COMMIT = 8;
 export declare const OP_SET_COMPONENT = 9;
-/**
- * The INTRINSIC TAG this node came from — `pressable`, not `RCTView`. `[slot, tag]`.
- *
- * Emitted only for a node a host behavior actually attached to, from `attachHostBehavior`, which is
- * where the tag is already in hand and already matched. Every other node pays nothing.
- *
- * WHY THE TAG HAS TO CROSS AT ALL. A tag's platform props are resolved natively now, and the native
- * side keys them off what it knows the node IS. For `<text-input>` the Fabric view name answers
- * that by itself (`RCTSinglelineTextInputView` names nothing else); for `<pressable>` it does not —
- * it commits as `RCTView`, byte-identical to a plain view. The tag is the only fact that separates
- * them, and it is the same fact a browser keys user-agent behavior off.
- */
 export declare const OP_SET_TAG = 10;
-/**
- * An app callback appeared on, or disappeared from, an event name the behavior OWNS.
- * `[slot, name, present]`. See `recordSetOwnedListener` for why the bit crosses and the closure
- * does not.
- */
 export declare const OP_SET_OWNED_LISTENER = 11;
-/**
- * A behavior's FEEDBACK state flipped — TouchableHighlight's underlay is showing, or stopped.
- * `[slot, shown]`.
- *
- * The second bit to cross for the same reason the first did. `OP_SET_OWNED_LISTENER` carries whether
- * the app wired a handler; this carries whether the control is currently giving feedback, which is
- * the platform's own `:active` in everything but the timing. `setNodePressed`'s header already calls
- * the press state "the engine-owned half of what `:active` is on the web", and this is its twin for
- * the one control whose feedback does NOT track the press exactly: RN holds the underlay past
- * release so a fast tap still flashes (`TouchableHighlight.js:270-293`).
- *
- * THE TIMER STAYS IN JS and that is the boundary, not an omission. WHEN the bit flips is Pressability
- * plus a `delayPressOut` hold, running at gesture rate and calling back into app code
- * (`onShowUnderlay` / `onHideUnderlay`). WHAT a showing underlay looks like — a background colour and
- * a dimmed child, from two props no ViewConfig declares — is the platform's, and it is
- * `foldTouchableHighlightUnderlay` now.
- *
- * A flip is a GESTURE-rate event rather than a per-render one: twice a tap, against a `payloadFold`
- * that was charged on every commit the node was dirty in for the life of the screen.
- */
 export declare const OP_SET_UNDERLAY_SHOWN = 12;
-/**
- * A VOID node: commits nothing of its own AND does not hoist its children into Fabric either —
- * unlike an anchor, which hoists. `[slot]`.
- *
- * `InputAccessoryView.js` renders `null` on Android: the whole component, children included,
- * contributes nothing to the host tree. An anchor cannot express that — it exists precisely to hand
- * its children up in its own place — so a node whose entire subtree must vanish from Fabric needs
- * its own kind. Everything else about it (the retained JS tree, `appendChild`, adapter bookkeeping)
- * is unaffected; only the commit walk treats it as contributing zero Fabric nodes, recursively.
- */
 export declare const OP_CREATE_VOID = 13;
-/**
- * A `setProp` whose value slot is this DELETES the key.
- *
- * `undefined` cannot carry it: `null` is a legitimate Fabric prop value meaning "reset to the
- * default", and the two must stay distinguishable — `cloneNodeWithNewProps` merges, so a removed
- * key has to be sent as an explicit `null` while a key that was never there must not be sent at
- * all. The JS `setProp` already collapses `undefined` to a delete before anything is encoded.
- */
 export declare const NO_VALUE = -1;
-/**
- * A node kind. Native needs it because two of the three never become a Fabric node the same way,
- * and both rules are decided at INSERT or at child-set build — never by a walk:
- *
- *   ELEMENT   an ordinary view. Its Fabric view name is fixed at creation, with ONE exception:
- *             a text element inside another text element commits as `RCTVirtualText` instead of
- *             `RCTText`. Native resolves that when the node acquires a parent, because that is when
- *             it first knows the answer, and re-resolves it on a reparent.
- *   RAW_TEXT  an `RCTRawText` leaf. Skipped from its parent's child set when its text is empty —
- *             an empty one would paint.
- *   ANCHOR    a position marker the frameworks insert (`{#if}`, a fragment, a `{@render}` slot).
- *             It never becomes a Fabric node at all: native keeps it in ITS OWN structure so
- *             `insertBefore(parent, node, anchor)` resolves, and hoists its children into its
- *             parent's child list when building the child set. This is why our own store cannot BE
- *             the Fabric tree — there is no Fabric node to hold an anchor, which is the one thing
- *             `IMirror` was genuinely for.
- *
- * A SURFACE is an anchor too, and that is not a trick: an anchor is a node whose children belong to
- * its parent's list, and a surface is a node whose children belong to the root's child set. Same
- * shape, so `OP_COMMIT` names one and the native side needs no `rootTag -> node` map — which keeps
- * the applier stateless, the property the whole lifetime design rests on.
- */
 export declare const KIND_ELEMENT = 0;
 export declare const KIND_RAW_TEXT = 1;
 export declare const KIND_ANCHOR = 2;
-/**
- * One recorded batch, flat.
- *
- * `handles` is the load-bearing table and it travels OUT rather than back: it holds the placeholder
- * object for every slot the ops address, and native attaches each created node to the object at
- * that slot as JSI `NativeState`. So the objects the adapter is already holding become the handles
- * in place, their lifetime is the nodes' lifetime, and nothing has to be freed explicitly.
- *
- * A slot is an index into THIS batch and is meaningless outside it. That is deliberate: an id that
- * outlives a batch forces a table on the far side, and a table is a second owner with nothing to
- * tell it when the first one let go — which is exactly the leak that took the previous applier from
- * 792 to 1492 MB.
- *
- * `values` carries whatever a prop is: a string, a number, a boolean, `null`, a style object, an
- * array. Native converts each to `folly::dynamic` ONCE, when the op is applied — never again per
- * commit, which is the half that ships today.
- */
-/**
- * What the buffer needs a handle to BE.
- *
- * Still an identity and nothing else as far as the ops are concerned — no parent, no children, no
- * order. The two fields are the buffer's own scratch space for `slotOf`, written by this file and
- * read by nobody else; `ISymbioteNode` declares them from its constructor so every real handle
- * carries the pair on one hidden class.
- *
- * Spelled as a requirement rather than as optional fields on purpose: a handle that cannot hold its
- * slot would fall back to nothing, and the failure would be a silently re-pushed node rather than a
- * type error.
- */
 export type IMutationHandle = {
     slot: number;
     slotBatch: number;
+    createdBatch: number;
 };
 export type IMutationBatch = {
     readonly ops: Int32Array;
@@ -141,38 +29,18 @@ export type IMutationBatch = {
     readonly instanceHandles: readonly unknown[];
     readonly handles: readonly object[];
 };
-/**
- * What native answers back, for the four things JS still asks.
- *
- * All four are per-node and none of them is structural — no parent, no children, no order. They
- * exist because a host behavior runs in JS and has to see the props it reacts to, and because an
- * app can measure a ref.
- *
- * Called at GESTURE rate, not commit rate, which is what makes the crossing cost irrelevant: ~10
- * reads per touch against the 19 009 per commit this whole design exists to remove.
- */
 export type INativeTree = {
     applyOps: (batch: IMutationBatch) => void;
     getProp: (handle: IMutationHandle, key: string) => unknown;
-    /** The resolved Fabric view name, which native may have changed at insert (see `KIND_ELEMENT`). */
     getViewName: (handle: IMutationHandle) => string;
 };
-/** Whether a commit would publish anything. See `changedSinceCommit`. */
 export declare function hasChangedSinceCommit(): boolean;
-/**
- * Called by `commitSurfaceOps` once it has drained. Separate from `takeBatch` because a READ drains
- * too, and a read is not a commit — clearing there would make the next commit believe its work had
- * already been published.
- */
 export declare function noteCommitDrained(): void;
-/**
- * The one dirtying route that writes no op: a behavior with a DERIVED payload asks the host to
- * rebuild a node the buffer never named. Without this the commit that follows would look idle and
- * be skipped, and the derived payload would sit unpublished until something unrelated changed.
- */
 export declare function noteHostSideChange(): void;
 /** Does the pending batch hold anything that could change what the host says this node's parent is? */
 export declare function hasPendingPlacement(handle: IMutationHandle): boolean;
+/** Has the host never heard of this node, т.к. the op that creates it is still in the buffer? */
+export declare function isPendingCreate(handle: IMutationHandle): boolean;
 export declare function recordCreateElement(handle: IMutationHandle, viewName: string, isText: boolean, instanceHandle: unknown): void;
 export declare function recordCreateRawText(handle: IMutationHandle, text: string): void;
 export declare function recordCreateAnchor(handle: IMutationHandle): void;
@@ -183,56 +51,14 @@ export declare function recordRemoveChild(parent: IMutationHandle, child: IMutat
 /** `undefined` DELETES the key — the collapse `setProp` has always performed, spelled on the wire. */
 export declare function recordSetProp(handle: IMutationHandle, key: string, value: unknown): void;
 export declare function recordSetText(handle: IMutationHandle, text: string): void;
-/**
- * Change a node's Fabric view name after creation.
- *
- * It exists for exactly one thing and would not otherwise: `TextInput`'s `multiline` decides between
- * `RCTSinglelineTextInputView` and `RCTMultilineTextInputView`, and an app can flip it. No prop write
- * moves a node between native views, so the host has to RE-CREATE the node under the new name and
- * re-parent its children — which is the same path a reparent already takes, and why this needs no
- * new machinery on the far side beyond honouring the name.
- *
- * A JS-only workaround was the alternative and it is the one thing this design rules out: to know
- * what to rebuild, JS would have to hold the tree.
- */
 export declare function recordSetComponent(handle: IMutationHandle, viewName: string): void;
 export declare function recordSetTag(handle: IMutationHandle, tag: string): void;
-/**
- * Whether an app callback is currently wired to an event name the BEHAVIOR owns. `[slot, name,
- * present]`, `present` being 1 or 0.
- *
- * The EXISTENCE, never the function. A name a behavior owns is diverted into a JS stash by
- * `setEventListener` and never becomes a prop, so the payload builder sees no trace of it — and
- * `focusable` on a touchable is `focusable !== false && onPress !== undefined && !disabled`
- * (`TouchableOpacity.js:336-339`), two props and one thing only JS knew. This is the one bit that
- * closes that gap.
- *
- * The browser is the argument rather than convenience: a UA computes focusability itself and CAN,
- * because `addEventListener` is its own API — it knows which elements carry a click handler, while
- * the handler's body stays the application's. Same split.
- *
- * Emitted on a FLIP only, from `setEventListener`, which already refuses to notify on listener
- * identity because a framework hands a fresh closure nearly every render. So this is a mount-time
- * op, not a per-render one — against the per-commit fold it replaces.
- */
 export declare function recordSetOwnedListener(handle: IMutationHandle, name: string, isPresent: boolean): void;
 /** See `OP_SET_UNDERLAY_SHOWN`. Emitted on a flip only, from the behavior that owns the timer. */
 export declare function recordSetUnderlayShown(handle: IMutationHandle, shown: boolean): void;
 export declare function recordCommit(rootTag: number, surface: IMutationHandle): void;
 /** Whether anything is pending. The commit path asks before paying for a drain. */
 export declare function hasPendingOps(): boolean;
-/**
- * Drain the buffer.
- *
- * Fresh arrays rather than reused ones: the batch outlives this call on the native path (`applyOps`
- * reads `handles` while attaching state), and a recycled array would be mutated under it by the next
- * mutation the adapter makes.
- *
- * `slice` for the ops and not `subarray` for exactly that reason — a subarray would share the
- * backing store the very next `push` writes into. It is a typed-array copy rather than the
- * element-by-element iterator walk this used to be, and the ops buffer itself is KEPT so its
- * capacity survives the drain.
- */
 export declare function takeBatch(): IMutationBatch;
 /** Test seam. Drops everything pending without applying it. */
 export declare function resetMutationBuffer(): void;