@symbiote-native/engine 1.2.0 → 1.3.1

package/build/host-behavior.d.ts

@@ -1,27 +1,11 @@
 import type { ISymbioteNode } from './node';
-/**
- * A pure props -> props mapping a behavior applies on the way to the Fabric payload.
- *
- * It exists because a tag has no component body, and a wrapper's body is where the per-primitive
- * prop FOLDS live — TextInput's W3C aliases (`inputMode` -> `keyboardType`, `readOnly` ->
- * `editable`), Pressable's `disabled` -> `accessibilityState`. Every one of those was silently
- * dropped the moment the wrapper went: the raw alias reached Fabric as a key no ViewConfig
- * declares, so nothing threw and nothing rendered differently in a headless test — only the device
- * showed a numeric keyboard that never appeared.
- *
- * NOT a hook on `setProp`, for the same reason `afterCommit` is not: `setProp` is the hottest path
- * in the engine. This runs once per node per payload build, and only for a node whose behavior
- * supplied one.
- *
- * MUST be pure and MUST NOT mutate its input — `node.props` is the live bag, and the folds beside
- * this one return their input by identity when there is nothing to do.
- */
 export type IPayloadFold = (props: Readonly<Record<string, unknown>>) => Record<string, unknown>;
 export type IClaimMode = 'beside' | 'wrap';
 export interface IHostBehavior {
     readonly ownedListeners?: readonly string[];
     readonly slotProps?: Readonly<Record<string, string>>;
     readonly slotPropsExcept?: readonly string[];
+    readonly slotValueFor?: (slotKey: string, value: unknown) => unknown;
     readonly slotTakesNoChildren?: boolean;
     readonly slotDerived?: readonly string[];
     readonly claimedChildren?: Readonly<Record<string, IClaimMode>>;
@@ -32,64 +16,13 @@ export interface IHostBehavior {
     onOwnedListenerChange?(node: ISymbioteNode, name: string, wired: boolean): void;
     afterCommit?(node: ISymbioteNode): void;
     detach(node: ISymbioteNode): void;
-    /**
-     * This primitive's own prop folds. See IPayloadFold.
-     *
-     * NO PRODUCTION BEHAVIOR DECLARES ONE since 2026-09-18 — the sticky header's was the last, and it
-     * is `foldStickyHeaderProps` in `SymbioteFabricProps.cpp` now. So this reads as a leftover, and
-     * the question this codebase asks of one is what it REACHES rather than who uses it today. Two
-     * answers, and either alone would keep it:
-     *
-     * - It is the JS ARM of every cost measurement in `tag-rule-cost.itest.ts`. That file prices a
-     *   rule by running it on both sides of the wire with the payloads asserted equal key by key
-     *   first; without a fold there is no second arm, and the ~9-31 us-per-node figures every port in
-     *   this migration was justified by could not be taken again.
-     * - It is the declared seam a third-party behavior would extend. A tag rule is ours to write in
-     *   C++; a package that ships its own primitive has no such option.
-     *
-     * What it is NOT any more is where a Symbiote primitive puts its platform props. A new one that
-     * reaches for this is one whose rule belongs in the engine — read `SymbioteFabricProps.h` first.
-     */
     readonly foldPayload?: IPayloadFold;
-    /**
-     * Resolve `source` / `defaultSource` / `loadingIndicatorSource` on the way IN — Image's, and only
-     * Image's. See `image-source-write.ts`.
-     *
-     * It is declared here rather than inferred from the tag because it is a statement about what the
-     * primitive's props MEAN, which is exactly what a behavior is for. And it is a flag rather than a
-     * function: `routeProp` is the hottest path in the engine, so what it can afford per write is a
-     * boolean read on the node, not a call into a behavior.
-     */
     readonly resolvesImageSources?: boolean;
-    /**
-     * Flips `id`/`nativeID` precedence to nativeID-over-id — TouchableWithoutFeedback's, and only
-     * its. See `routeIdAlias` in `node.ts` for why the flip exists and which vendor file demands it.
-     */
     readonly nativeIdWinsOverId?: boolean;
 }
 export declare function registerHostBehavior(component: string, behavior: IHostBehavior): void;
 export declare function hostBehaviorFor(tag: string): IHostBehavior | undefined;
 export declare function hasHostBehaviors(): boolean;
-/**
- * Has a behavior ever ATTACHED to a node, as opposed to a behavior TYPE having been registered?
- *
- * `hasBehaviors` answers the second, and it is on from module load in every app: registering
- * `Pressable` arms it whether or not one is ever mounted. It gates `createElement`'s attach probe
- * correctly — a node has to be offered to the registry to find out. It gates the TEARDOWN SWEEP
- * wrongly, and that is expensive: the sweep crosses every removed node into JS, which on a
- * 1 000-row clear is ten thousand handles. Measured on `build-release`
- * (`teardown-sweep-cost.itest.ts`): 1.8 ms with the sweep off against 6.3 ms with it on, i.e. 3.2x,
- * all of it inside the commit. `Clear` is the one row where stock React Native beats every adapter.
- *
- * Nothing the sweep does can matter before the first attach, and the four collections say so:
- * `node.hostBehavior` is written only by `attachHostBehavior`; `awaitingCommit` and `committedEachTime` are
- * written only inside a `behavior.` branch; `parked` only by `detachAnimatedProps`, which has its
- * own gate. The one remaining effect is marking `isTornDown`, which exists so a later re-insert knows
- * to re-arm — and there is nothing to re-arm.
- *
- * MONOTONE, deliberately: it turns on and never off, so it needs no accounting on a `WeakMap` that
- * has no size and no destructor. Being late is the only way it can be wrong, and it cannot be late.
- */
 export declare function hasAttachedBehaviors(): boolean;
 export declare function slotPropNameFor(node: ISymbioteNode, key: string): string | undefined;
 export declare function slotTakesChildren(node: ISymbioteNode): boolean;
@@ -98,48 +31,16 @@ export declare function derivedNodesOf(owner: ISymbioteNode): readonly ISymbiote
 export declare function notifyOwnedListenerChange(node: ISymbioteNode, name: string, wired: boolean): void;
 export declare function notifyChildInserted(node: ISymbioteNode, child: ISymbioteNode): void;
 export declare function claimModeFor(node: ISymbioteNode, component: string): IClaimMode | undefined;
-/**
- * Every owner key feeds the slot. The spelling for a `cloneElement` primitive, whose slot is not
- * derived from a named set at all — see `IHostBehavior.slotDerived`.
- *
- * A sentinel in the SAME array rather than a second field, so `slotDerivesFrom` stays one lookup and
- * a behavior that wants both spellings cannot express a contradiction.
- */
 export declare const SLOT_DERIVED_ALL = "*";
 export declare function slotDerivesFrom(node: ISymbioteNode, key: string): boolean;
 export declare function ownsListener(node: ISymbioteNode, name: string): boolean;
 export declare function stashAppListener(node: ISymbioteNode, name: string, listener: unknown): void;
 export declare function appListenerFor(node: ISymbioteNode, name: string): unknown;
 export declare function attachHostBehavior(node: ISymbioteNode, tag: string): void;
-/**
- * Run the deferred half of every behavior whose node has now been committed. Called from the commit
- * path immediately after `completeRoot`, where fresh Fabric tags have just been assigned.
- *
- * `isCommitted` is passed in for the same no-cycle reason — `committedOf` lives in `commit.ts`. A
- * still-uncommitted node stays in the set: a create superseded before it ever reached Fabric waits
- * for the commit that lands it, and `detachSubtree` drops it if that commit never comes.
- */
 export declare function runDeferredAttaches(isCommitted: (node: ISymbioteNode) => boolean): void;
-/**
- * Arm a node's recurring hook for the next commit.
- *
- * Called from `setProp` — gated there on `node.hasCommitHook`, a boolean field beside
- * `hasAriaAlias` on the same hidden class, so a node without a recurring hook pays one load and
- * one branch per write and never reaches this.
- */
 export declare function noteCommitHookNodeChanged(node: ISymbioteNode): void;
 export declare function runCommittedHooks(isCommitted: (node: ISymbioteNode) => boolean): void;
 export declare function markDetachCandidate(node: ISymbioteNode): void;
-/**
- * Whether the sweep has anything to do — asked BEFORE its arguments are built.
- *
- * The sweep's own first line already returns on an empty candidate set, and that was not enough:
- * its caller passes `surface.children`, which is a GETTER that crosses to the host, allocates the
- * whole top-level list and filters it into a second array. On a surface holding four thousand rows
- * that ran on every commit, including the ones with nothing to sweep, because an argument is
- * evaluated before the guard inside the callee can decline. Same shape as the `dlog` arguments that
- * cost Angular 5-10% while emitting nothing.
- */
 export declare function hasDetachCandidates(): boolean;
 export declare function sweepDetachedBehaviors(topLevel: readonly ISymbioteNode[], onDetached: (node: ISymbioteNode) => void): void;
 export declare function teardownSubtree(node: ISymbioteNode, onDetached: (node: ISymbioteNode) => void): void;