@symbiote-native/engine 1.1.0 → 1.3.0

package/build/toast-android/index.js

@@ -1,108 +1,3 @@
-// ToastAndroid module: pops a brief Android system toast from JS. Mirrors RN's
-// Libraries/Components/ToastAndroid/ToastAndroid.android.js: `show` takes a message
-// and a duration; `showWithGravity` adds a layout gravity; `showWithGravityAndOffset`
-// adds an x/y pixel offset. No Fabric view, pure JS->native.
-//
-// symbiote is iOS-first and this is an Android-only module. RN's iOS fallback
-// (ToastAndroid.ios.js) throws "not supported"; we prefer a no-op + dlog so a
-// cross-platform smoke never crashes when the native module is absent.
-//
-// The native contract is confirmed from RN's TurboModule spec at
-// specs_DEPRECATED/modules/INativeToastAndroid.js:
-//   getConstants(): { SHORT, LONG, TOP, BOTTOM, CENTER }
-//   show(message: string, duration: number)
-//   showWithGravity(message: string, duration: number, gravity: number)
-//   showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset)
-import { dlog } from '../debug.js';
-import { getNativeModule } from '../native-modules/index.js';
-// The native module name RN registers this under. NOTE: this is the name the spec
-// resolves via `TurboModuleRegistry.getEnforcing<Spec>('ToastAndroid')`, NOT the
-// spec filename `INativeToastAndroid`. A module name is only provable on a real
-// host (a headless fake answers to any name); this Android name is confirmed from
-// RN source but not yet exercised on a device.
-const TOAST_MODULE = 'ToastAndroid';
-// Conventional RN values for SHORT/LONG/TOP/BOTTOM/CENTER. On a real device the
-// numbers come from native getConstants() (resolved below); these are the fallbacks
-// that keep the constants object populated headless and on a host without the module.
-const FALLBACK_CONSTANTS = {
-    SHORT: 0,
-    LONG: 1,
-    TOP: 48,
-    BOTTOM: 80,
-    CENTER: 17,
-};
-// Lazily resolved so importing this module has no native side effect.
-let toastModule;
-function getModule() {
-    if (toastModule === undefined) {
-        toastModule = getNativeModule(TOAST_MODULE);
-        dlog(`ToastAndroid: ToastAndroid module ${toastModule ? 'resolved' : 'NOT resolved (null)'}`);
-    }
-    return toastModule;
-}
-// Read a single numeric constant from the native getConstants() payload, narrowing
-// with a `typeof` guard (no cast) and falling back to the conventional RN value when
-// the module or the key is absent.
-function readConstant(raw, key) {
-    const value = raw[key];
-    return typeof value === 'number' ? value : FALLBACK_CONSTANTS[key];
-}
-// Resolve the constants once: real numbers from native on a device, fallbacks
-// otherwise. Always returns a fully-populated object so the constants are never
-// undefined, even headless.
-function resolveConstants() {
-    const module = getModule();
-    if (module === null) {
-        dlog('ToastAndroid: constants from fallbacks (native module unavailable)');
-        return { ...FALLBACK_CONSTANTS };
-    }
-    const raw = module.getConstants();
-    return {
-        SHORT: readConstant(raw, 'SHORT'),
-        LONG: readConstant(raw, 'LONG'),
-        TOP: readConstant(raw, 'TOP'),
-        BOTTOM: readConstant(raw, 'BOTTOM'),
-        CENTER: readConstant(raw, 'CENTER'),
-    };
-}
-const constants = resolveConstants();
-export const ToastAndroid = {
-    // Toast duration constants.
-    SHORT: constants.SHORT,
-    LONG: constants.LONG,
-    // Toast gravity constants.
-    TOP: constants.TOP,
-    BOTTOM: constants.BOTTOM,
-    CENTER: constants.CENTER,
-    // Show a toast with the given message and duration. Degrades to a no-op (logged)
-    // when the module is absent; a missing optional native module must never throw.
-    show(message, duration) {
-        const module = getModule();
-        if (module === null) {
-            dlog('ToastAndroid.show -> ToastAndroid native module unavailable, no-op');
-            return;
-        }
-        dlog(`ToastAndroid.show -> "${message}" (${duration})`);
-        module.show(message, duration);
-    },
-    // Show a toast at the given layout gravity (TOP / BOTTOM / CENTER).
-    showWithGravity(message, duration, gravity) {
-        const module = getModule();
-        if (module === null) {
-            dlog('ToastAndroid.showWithGravity -> ToastAndroid native module unavailable, no-op');
-            return;
-        }
-        dlog(`ToastAndroid.showWithGravity -> "${message}" (${duration}, gravity=${gravity})`);
-        module.showWithGravity(message, duration, gravity);
-    },
-    // Show a toast at the given gravity, offset by xOffset/yOffset pixels.
-    showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset) {
-        const module = getModule();
-        if (module === null) {
-            dlog('ToastAndroid.showWithGravityAndOffset -> ToastAndroid native module unavailable, no-op');
-            return;
-        }
-        dlog(`ToastAndroid.showWithGravityAndOffset -> "${message}" (${duration}, gravity=${gravity}, ${xOffset}, ${yOffset})`);
-        module.showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset);
-    },
-};
+// ToastAndroid: base / headless build. Metro picks index.android.ts / index.ios.ts on a device; off
+// those, RN's non-Android fallback is the default, as RN's own ToastAndroid.js is.
+export * from './index.ios.js';

package/build/tree-host.d.ts

@@ -148,7 +148,45 @@ export declare function commitSurfaceOps(rootTag: IRootTag | undefined, surface:
 export interface ICommitProfile {
     commits: number;
     propWrites: number;
+    /**
+     * Fresh Fabric families minted in this window — the SAME quantity a stock React Native app counts
+     * by wrapping `global.nativeFabricUIManager.createNode`, and the only like-for-like census left
+     * between the two stacks: our creates are issued from C++ (`SymbioteTree.cpp`,
+     * `uiManager.createNode`) and never touch that global, so a JS wrapper over it reads zero here by
+     * construction. Two arms whose node counts differ are not one workload, whatever their
+     * milliseconds say, so this belongs next to the writes rather than behind a surface id.
+     */
+    nodesCreated: number;
+    /**
+     * How many times `applyOps` was ENTERED for this window — the number of JSI crossings the buffer
+     * actually cost, as against the one the architecture promises.
+     *
+     * A whole create should read 2. It reads more when something READS the tree while the tree is
+     * being built, because a read is a batch boundary: the buffer has to drain before the answer can
+     * be given, so a framework navigating what it is inserting enters `applyOps` once per mutation.
+     * `small-batch-crossing-cost.itest.ts` prices an empty prologue at 1.5-4.4 us, so ten thousand
+     * boundaries is tens of milliseconds that no node count and no write count can see — which is
+     * exactly the shape of a cost that shows up on a device and not in a fixture.
+     */
+    applyCalls: number;
+    /**
+     * `applyOps` end to end, and the part of it that reads the buffer out of JS.
+     *
+     * THE ONE QUESTION A DEVICE HAS TO ANSWER and a fixture cannot. Our crossing is a single call
+     * carrying a 12 000-entry array that C++ walks element by element through JSI; stock's is ten
+     * thousand calls carrying scalars. On the harness's JavaScriptCore that walk is ~4 ms of a ~48 ms
+     * `applyOps`. Hermes is a different JSI implementation with different array-read costs and nothing
+     * headless can price it, so the number has to be read on a phone — near 4 ms and the buffer is
+     * innocent, tens of milliseconds and it is most of the gap the device reports.
+     */
+    applyMs: number;
+    decodeMs: number;
 }
+/**
+ * NOTE: reading this now DRAINS the surface telemetry too — `nodesCreated` is folded in from
+ * `readSurfaceTelemetry`, which zeroes on read in C++. A sampler polling this on an interval
+ * therefore empties what a later `readSurfaceTelemetry` call would have reported.
+ */
 export declare function readCommitProfile(): ICommitProfile;
 export type ISurfaceTelemetry = {
     layoutMs: number;
@@ -261,6 +299,15 @@ export type ISurfaceTelemetry = {
      * `stringDecodeMs` / `structureMs` is what the op loop itself costs — the books close here.
      */
     applyMs: number;
+    /**
+     * How many nodes the C++ tree is holding right now — a LEVEL, not a total, and the one counter
+     * here that is not drained on read.
+     *
+     * What it is for: JS ownership anchors the C++ side (a node lives while a parent holds it or while
+     * JS names it through `NativeState`), so a heap reading proves the JS half was released and only
+     * infers the other. This is the other half as a reading.
+     */
+    liveNodes: number;
     stringDecodeMs: number;
     /** Every append / insert / remove op together. */
     structureMs: number;

package/build/tree-host.js

@@ -106,6 +106,11 @@ export function flushOps() {
 }
 // Commits this window, for readCommitProfile below.
 let commits = 0;
+// A surface to ask for this window's node counts. They live in C++ and this profile is id-less, so
+// the window has to keep a tag to ask WITH, and exactly one: `walkCost_` is file-scope in
+// `SymbioteTree.cpp`, shared by every surface and drained on read, so asking a second surface in the
+// same window reads zeroes and a sum would be wrong rather than merely redundant.
+let lastCommittedTag;
 /**
  * Record a surface's commit and drain the buffer into the host.
  *
@@ -158,13 +163,38 @@ export function commitSurfaceOps(rootTag, surface, others = []) {
     // `undefined` means this surface no longer OWNS its root — a re-mount on the same rootTag took
     // it. Its ops still drain, because a teardown is what carries the removals; completing the root
     // would hand Fabric the dead surface's emptied tree over the live one's.
-    if (rootTag !== undefined)
+    if (rootTag !== undefined) {
         recordCommit(rootTag, surface);
+        lastCommittedTag = rootTag;
+    }
     host.applyOps(takeBatch());
     noteCommitDrained();
 }
+/**
+ * NOTE: reading this now DRAINS the surface telemetry too — `nodesCreated` is folded in from
+ * `readSurfaceTelemetry`, which zeroes on read in C++. A sampler polling this on an interval
+ * therefore empties what a later `readSurfaceTelemetry` call would have reported.
+ */
 export function readCommitProfile() {
-    const snapshot = { commits, propWrites: takePropStats().writes };
+    // ONE read, not two: `readSurfaceTelemetry` zeroes the C++ accumulator, so asking it twice hands
+    // the second caller zeroes and the field would read as "the buffer never crossed".
+    //
+    // Gated on a commit having LANDED in this window, and not merely on a tag being known. Fabric's
+    // `TransactionTelemetry::getCommitStartTime` asserts that a commit has started, so asking a
+    // surface that has not committed since the last read aborts the process in a debug build and
+    // reads an undefined time point in a release one. The window's own `commits` is the only thing
+    // that answers "is there anything to ask about" without asking.
+    const telemetry = commits === 0 || lastCommittedTag === undefined
+        ? undefined
+        : readSurfaceTelemetry(lastCommittedTag);
+    const snapshot = {
+        commits,
+        propWrites: takePropStats().writes,
+        nodesCreated: telemetry?.nodesCreated ?? 0,
+        applyCalls: telemetry?.applyCalls ?? 0,
+        applyMs: telemetry?.applyMs ?? 0,
+        decodeMs: telemetry?.decodeMs ?? 0,
+    };
     commits = 0;
     return snapshot;
 }