@sigx/lynx-runtime-main 0.4.4 → 0.4.5

package/dist/list-mt.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Main Thread native `<list>` recycler support.
+ *
+ * Lynx's `<list>` is NOT a plain scrolling container — it's a managed recycler.
+ * Native pulls each visible cell by calling `componentAtIndex(cellIndex)` and
+ * recycles offscreen cells via `enqueueComponent(sign)`. If its
+ * `update-list-info` metadata is never set, native crashes during layout
+ * (`UIList.onLayoutCompleted` NPE — issue #120).
+ *
+ * The reference framework (`@lynx-js/react`) renders each `<list-item>` subtree
+ * on demand inside `componentAtIndex`. The sigx renderer is different: the
+ * Background Thread eagerly creates ALL `<list-item>` elements (and their
+ * subtrees) on the Main Thread, just like any other children. So here
+ * `componentAtIndex` does not render anything — it simply returns the sign of
+ * the already-built element for that index, appending it to the list on first
+ * pull so native can find it via its unique id.
+ *
+ * What this module owns:
+ *  - Creating `<list>` via `__CreateList` (so the callbacks are registered).
+ *  - Tracking each list's ordered `<list-item>` children (BG insertion order)
+ *    and their per-item platform info (item-key etc.).
+ *  - Emitting `update-list-info` diffs (insert/remove actions) at the end of
+ *    each ops batch so native knows how many cells exist and their keys.
+ *
+ * `<list-item>` children are intercepted here instead of being appended to the
+ * list element directly (the recycler owns attachment via `componentAtIndex`).
+ */
+/** True when `internalId` is a `<list>` element managed by this module. */
+export declare function isListElement(internalId: number): boolean;
+/** True when `internalId` is a direct `<list-item>` child of some `<list>`. */
+export declare function isListChild(internalId: number): boolean;
+/** Create a `<list>` element and register its recycler callbacks. */
+export declare function createListElement(internalId: number): MainThreadElement;
+/**
+ * Record a `<list-item>` inserted into a `<list>`. We do NOT append it to the
+ * list element here — the recycler attaches it on demand via
+ * `componentAtIndex`. `anchorInternalId` is the real sibling to insert before,
+ * or -1 to append.
+ */
+export declare function listInsertChild(listInternalId: number, childInternalId: number, anchorInternalId: number): void;
+/** Record a `<list-item>` removed from a `<list>` and detach its element. */
+export declare function listRemoveChild(listInternalId: number, childInternalId: number): void;
+/** Tear down a `<list>` element (detach callbacks, drop all state). */
+export declare function destroyListElement(internalId: number): void;
+/**
+ * Record a platform-info prop on a `<list-item>`. Returns true if `key` is a
+ * recognised platform-info key (the caller still sets it as a normal element
+ * attribute regardless). Safe to call before the item's insert op arrives —
+ * the info is stashed by child id and read at flush time.
+ */
+export declare function noteListItemProp(childInternalId: number, key: string, value: unknown): void;
+/**
+ * Emit `update-list-info` diffs for every list whose children changed during
+ * the current ops batch. Called once per batch, before the final
+ * `__FlushElementTree`.
+ *
+ * The diff is intentionally minimal — insert/remove only (no move/update). It
+ * covers the common cases (initial render, append, delete). `removeAction`
+ * carries ascending OLD indices; `insertAction` carries ascending NEW
+ * positions, each with the item's type and platform info. This matches the
+ * order the host/native recycler applies them (remove first, then insert).
+ */
+export declare function flushDirtyLists(): void;
+/** Reset all list state — for testing and hot reload. */
+export declare function resetListState(): void;

package/dist/list-mt.js

@@ -0,0 +1,236 @@
+/**
+ * Main Thread native `<list>` recycler support.
+ *
+ * Lynx's `<list>` is NOT a plain scrolling container — it's a managed recycler.
+ * Native pulls each visible cell by calling `componentAtIndex(cellIndex)` and
+ * recycles offscreen cells via `enqueueComponent(sign)`. If its
+ * `update-list-info` metadata is never set, native crashes during layout
+ * (`UIList.onLayoutCompleted` NPE — issue #120).
+ *
+ * The reference framework (`@lynx-js/react`) renders each `<list-item>` subtree
+ * on demand inside `componentAtIndex`. The sigx renderer is different: the
+ * Background Thread eagerly creates ALL `<list-item>` elements (and their
+ * subtrees) on the Main Thread, just like any other children. So here
+ * `componentAtIndex` does not render anything — it simply returns the sign of
+ * the already-built element for that index, appending it to the list on first
+ * pull so native can find it via its unique id.
+ *
+ * What this module owns:
+ *  - Creating `<list>` via `__CreateList` (so the callbacks are registered).
+ *  - Tracking each list's ordered `<list-item>` children (BG insertion order)
+ *    and their per-item platform info (item-key etc.).
+ *  - Emitting `update-list-info` diffs (insert/remove actions) at the end of
+ *    each ops batch so native knows how many cells exist and their keys.
+ *
+ * `<list-item>` children are intercepted here instead of being appended to the
+ * list element directly (the recycler owns attachment via `componentAtIndex`).
+ */
+import { elements, pageUniqueId } from './element-registry.js';
+/**
+ * Per-`<list-item>` platform-info attribute keys (kebab-case). These are
+ * forwarded to native both as element attributes (via the normal SET_PROP →
+ * __SetAttribute path) and inside `update-list-info`'s insertAction entries.
+ */
+const PLATFORM_INFO_KEYS = new Set([
+    'item-key',
+    'full-span',
+    'sticky-top',
+    'sticky-bottom',
+    'estimated-height',
+    'estimated-height-px',
+    'estimated-main-axis-size-px',
+    'reuse-identifier',
+    'recyclable',
+]);
+const listsByInternalId = new Map();
+const listByListID = new Map();
+/** child internal id → owning list internal id */
+const listItemOwner = new Map();
+/** child internal id → per-item platform info ({ 'item-key': … }) */
+const itemPlatformInfo = new Map();
+/** True when `internalId` is a `<list>` element managed by this module. */
+export function isListElement(internalId) {
+    return listsByInternalId.has(internalId);
+}
+/** True when `internalId` is a direct `<list-item>` child of some `<list>`. */
+export function isListChild(internalId) {
+    return listItemOwner.has(internalId);
+}
+// ---------------------------------------------------------------------------
+// Recycler callbacks (invoked by native during layout, on the Main Thread)
+// ---------------------------------------------------------------------------
+function componentAtIndex(_list, listID, cellIndex, operationID, _enableReuseNotification) {
+    const state = listByListID.get(listID);
+    if (!state)
+        return -1;
+    const childInternalId = state.order[cellIndex];
+    if (childInternalId === undefined)
+        return -1;
+    const root = elements.get(childInternalId);
+    if (!root)
+        return -1;
+    const sign = __GetElementUniqueID(root);
+    // The element already exists (BG built it eagerly). Append on first pull so
+    // native can resolve it by sign; the guard prevents a double-append when the
+    // cell scrolls back into view.
+    if (!state.appended.has(childInternalId)) {
+        __AppendElement(state.listEl, root);
+        state.appended.add(childInternalId);
+    }
+    __FlushElementTree(root, {
+        triggerLayout: true,
+        operationID,
+        elementID: sign,
+        listID,
+    });
+    return sign;
+}
+function enqueueComponent(_list, _listID, _sign) {
+    // No-op. Each `<list-item>` has its own dedicated, already-rendered element,
+    // so we never recycle one element's subtree to display a different item.
+    // Native detaches the offscreen view on its own; the element stays in the
+    // tree so `componentAtIndex` can re-surface it on scroll-back.
+}
+// ---------------------------------------------------------------------------
+// Lifecycle, invoked from ops-apply.ts
+// ---------------------------------------------------------------------------
+/** Create a `<list>` element and register its recycler callbacks. */
+export function createListElement(internalId) {
+    const listEl = __CreateList(pageUniqueId, componentAtIndex, enqueueComponent);
+    const listID = __GetElementUniqueID(listEl);
+    const state = {
+        internalId,
+        listEl,
+        listID,
+        order: [],
+        committed: [],
+        appended: new Set(),
+        dirty: false,
+    };
+    listsByInternalId.set(internalId, state);
+    listByListID.set(listID, state);
+    return listEl;
+}
+/**
+ * Record a `<list-item>` inserted into a `<list>`. We do NOT append it to the
+ * list element here — the recycler attaches it on demand via
+ * `componentAtIndex`. `anchorInternalId` is the real sibling to insert before,
+ * or -1 to append.
+ */
+export function listInsertChild(listInternalId, childInternalId, anchorInternalId) {
+    const state = listsByInternalId.get(listInternalId);
+    if (!state)
+        return;
+    const idx = anchorInternalId === -1 ? -1 : state.order.indexOf(anchorInternalId);
+    if (idx === -1)
+        state.order.push(childInternalId);
+    else
+        state.order.splice(idx, 0, childInternalId);
+    listItemOwner.set(childInternalId, listInternalId);
+    state.dirty = true;
+}
+/** Record a `<list-item>` removed from a `<list>` and detach its element. */
+export function listRemoveChild(listInternalId, childInternalId) {
+    const state = listsByInternalId.get(listInternalId);
+    if (!state)
+        return;
+    const idx = state.order.indexOf(childInternalId);
+    if (idx !== -1)
+        state.order.splice(idx, 1);
+    if (state.appended.delete(childInternalId)) {
+        const child = elements.get(childInternalId);
+        if (child)
+            __RemoveElement(state.listEl, child);
+    }
+    listItemOwner.delete(childInternalId);
+    itemPlatformInfo.delete(childInternalId);
+    state.dirty = true;
+}
+/** Tear down a `<list>` element (detach callbacks, drop all state). */
+export function destroyListElement(internalId) {
+    const state = listsByInternalId.get(internalId);
+    if (!state)
+        return;
+    __UpdateListCallbacks(state.listEl, null, null);
+    listByListID.delete(state.listID);
+    for (const childId of state.order) {
+        listItemOwner.delete(childId);
+        itemPlatformInfo.delete(childId);
+    }
+    listsByInternalId.delete(internalId);
+}
+/**
+ * Record a platform-info prop on a `<list-item>`. Returns true if `key` is a
+ * recognised platform-info key (the caller still sets it as a normal element
+ * attribute regardless). Safe to call before the item's insert op arrives —
+ * the info is stashed by child id and read at flush time.
+ */
+export function noteListItemProp(childInternalId, key, value) {
+    if (!PLATFORM_INFO_KEYS.has(key))
+        return;
+    let info = itemPlatformInfo.get(childInternalId);
+    if (!info) {
+        info = {};
+        itemPlatformInfo.set(childInternalId, info);
+    }
+    info[key] = value;
+    const owner = listItemOwner.get(childInternalId);
+    if (owner !== undefined) {
+        const st = listsByInternalId.get(owner);
+        if (st)
+            st.dirty = true;
+    }
+}
+/**
+ * Emit `update-list-info` diffs for every list whose children changed during
+ * the current ops batch. Called once per batch, before the final
+ * `__FlushElementTree`.
+ *
+ * The diff is intentionally minimal — insert/remove only (no move/update). It
+ * covers the common cases (initial render, append, delete). `removeAction`
+ * carries ascending OLD indices; `insertAction` carries ascending NEW
+ * positions, each with the item's type and platform info. This matches the
+ * order the host/native recycler applies them (remove first, then insert).
+ */
+export function flushDirtyLists() {
+    for (const state of listsByInternalId.values()) {
+        if (!state.dirty)
+            continue;
+        state.dirty = false;
+        const oldArr = state.committed;
+        const newArr = state.order;
+        const oldSet = new Set(oldArr);
+        const newSet = new Set(newArr);
+        const removeAction = [];
+        for (let i = 0; i < oldArr.length; i++) {
+            if (!newSet.has(oldArr[i]))
+                removeAction.push(i);
+        }
+        const insertAction = [];
+        for (let pos = 0; pos < newArr.length; pos++) {
+            const childInternalId = newArr[pos];
+            if (!oldSet.has(childInternalId)) {
+                const info = itemPlatformInfo.get(childInternalId) ?? {};
+                insertAction.push({ position: pos, type: 'list-item', ...info });
+            }
+        }
+        state.committed = newArr.slice();
+        if (removeAction.length === 0 && insertAction.length === 0)
+            continue;
+        __SetAttribute(state.listEl, 'update-list-info', {
+            insertAction,
+            removeAction,
+            updateAction: [],
+        });
+        // Re-affirm the callbacks after every diff (mirrors the reference runtime).
+        // Our closures read live state, so this is a defensive no-op rebind.
+        __UpdateListCallbacks(state.listEl, componentAtIndex, enqueueComponent);
+    }
+}
+/** Reset all list state — for testing and hot reload. */
+export function resetListState() {
+    listsByInternalId.clear();
+    listByListID.clear();
+    listItemOwner.clear();
+    itemPlatformInfo.clear();
+}

package/dist/ops-apply.js

@@ -11,6 +11,7 @@ import { elements, pageUniqueId, setPageUniqueId, } from './element-registry.js'
 import { resetWorkletEvents } from './worklet-events.js';
 import { setSlotBgSign, setSlotWorklet, flushDirtySlots, resetSlotStates, } from './event-slots.js';
 import { flushAvBridgePublishes, flushAnimatedStyleBindings, registerAnimatedStyleBinding, unregisterAnimatedStyleBinding, resetAnimatedStyleBindings, } from './animated-bridge-mt.js';
+import { createListElement, destroyListElement, flushDirtyLists, isListElement, listInsertChild, listRemoveChild, noteListItemProp, resetListState, } from './list-mt.js';
 /**
  * Placeholder element inserted by renderPage() to give the host a non-empty
  * tree immediately, suppressing the "loadCard failed USER_RUNTIME_ERROR"
@@ -127,6 +128,12 @@ export function applyOps(ops) {
                 if (type === '__comment') {
                     el = __CreateRawText('');
                 }
+                else if (type === 'list') {
+                    // `<list>` is created via __CreateList so its recycler callbacks are
+                    // registered up front (issue #120). list-mt.ts owns its state.
+                    el = createListElement(id);
+                    __SetCSSId([el], 0);
+                }
                 else {
                     el = createTypedElement(type, pageUniqueId);
                     __SetCSSId([el], 0);
@@ -149,6 +156,12 @@ export function applyOps(ops) {
                 const parentId = ops[i++];
                 const childId = ops[i++];
                 const anchorId = ops[i++];
+                // `<list>` children are owned by the recycler — record order instead of
+                // appending; native attaches them on demand via componentAtIndex.
+                if (isListElement(parentId)) {
+                    listInsertChild(parentId, childId, anchorId);
+                    break;
+                }
                 const parent = elements.get(parentId);
                 const child = elements.get(childId);
                 if (parent && child) {
@@ -166,6 +179,13 @@ export function applyOps(ops) {
             case OP.REMOVE: {
                 const _parentId = ops[i++];
                 const childId = ops[i++];
+                if (isListElement(_parentId)) {
+                    listRemoveChild(_parentId, childId);
+                    break;
+                }
+                // Tearing down a `<list>` itself — detach its recycler callbacks first.
+                if (isListElement(childId))
+                    destroyListElement(childId);
                 const parent = elements.get(_parentId);
                 const child = elements.get(childId);
                 if (parent && child) {
@@ -180,6 +200,9 @@ export function applyOps(ops) {
                 const el = elements.get(id);
                 if (el)
                     __SetAttribute(el, key, value);
+                // Mirror `<list-item>` platform-info props (item-key, full-span, …)
+                // into the list's update-list-info metadata (no-op for other keys).
+                noteListItemProp(id, key, value);
                 break;
             }
             case OP.SET_TEXT: {
@@ -424,6 +447,9 @@ export function applyOps(ops) {
     // during this batch. Runs after flushAvBridgePublishes so the BG mirror
     // stays consistent with the styles we're about to commit.
     flushAnimatedStyleBindings();
+    // Emit update-list-info diffs for any `<list>` whose children changed this
+    // batch, so native knows its cell count/keys before it lays out.
+    flushDirtyLists();
     // Flush all pending PAPI changes to the native layer in one shot.
     __FlushElementTree();
 }
@@ -442,6 +468,7 @@ export function resetMainThreadState() {
     lastTreeByElementWvid.clear();
     elementIdByWvid.clear();
     resetAnimatedStyleBindings();
+    resetListState();
     // Clear upstream's worklet ref map too on hard reset (HMR / test).
     const impl = globalThis['lynxWorkletImpl'];
     if (impl?._refImpl)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigx/lynx-runtime-main",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Main Thread (Lepus) entry and ops applier for SignalX Lynx renderer",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,7 +42,7 @@
     "url": "https://github.com/signalxjs/lynx/issues"
   },
   "dependencies": {
-    "@sigx/lynx-runtime-internal": "0.4.4"
+    "@sigx/lynx-runtime-internal": "0.4.5"
   },
   "peerDependencies": {
     "@lynx-js/types": ">=3.0.0"