@lynx-js/react 0.107.0 → 0.108.0

package/runtime/src/lifecycle/reload.ts

@@ -1,19 +1,27 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
+
+/**
+ * Implements the reload (thinking of "refresh" in browser) for both main thread
+ * and background thread.
+ */
+
+import { render } from 'preact';
+
 import { hydrate } from '../hydrate.js';
 import { LifecycleConstant } from '../lifecycleConstant.js';
 import { __pendingListUpdates } from '../list.js';
 import { __root, setRoot } from '../root.js';
-import { takeGlobalRefPatchMap } from '../snapshot/ref.js';
 import { SnapshotInstance, __page, snapshotInstanceManager } from '../snapshot.js';
+import { takeGlobalRefPatchMap } from '../snapshot/ref.js';
 import { isEmptyObject } from '../utils.js';
-import { destroyBackground } from './destroy.js';
 import { destroyWorklet } from '../worklet/destroy.js';
+import { destroyBackground } from './destroy.js';
 import { clearJSReadyEventIdSwap, isJSReady } from './event/jsReady.js';
 import { increaseReloadVersion } from './pass.js';
 import { deinitGlobalSnapshotPatch } from './patch/snapshotPatch.js';
-import { renderBackground, renderMainThread } from './render.js';
+import { renderMainThread } from './render.js';
 
 function reloadMainThread(data: any, options: UpdatePageOption): void {
   if (__PROFILE__) {
@@ -74,7 +82,7 @@ function reloadBackground(updateData: Record<string, any>): void {
   // COW when modify `lynx.__initData` to make sure Provider & Consumer works
   lynx.__initData = Object.assign({}, lynx.__initData, updateData);
 
-  renderBackground(__root.__jsx, __root as any);
+  render(__root.__jsx, __root as any);
 
   if (__PROFILE__) {
     console.profileEnd();

package/runtime/src/lifecycle/render.ts

@@ -1,13 +1,16 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
+
+/**
+ * Implements the IFR (Instant First-Frame Rendering) on main thread.
+ */
+
 import { render } from 'preact';
-import type { ComponentChild, ContainerNode } from 'preact';
 
 import { renderOpcodesInto } from '../opcodes.js';
 import { render as renderToString } from '../renderToOpcodes/index.js';
 import { __root } from '../root.js';
-import { commitToMainThread } from './patch/commit.js';
 
 function renderMainThread(): void {
   /* v8 ignore start */
@@ -47,9 +50,4 @@ function renderMainThread(): void {
   /* v8 ignore stop */
 }
 
-function renderBackground(vnode: ComponentChild, parent: ContainerNode): void {
-  render(vnode, parent);
-  void commitToMainThread();
-}
-
-export { renderMainThread, renderBackground };
+export { renderMainThread };

package/runtime/src/list.ts

@@ -78,10 +78,12 @@ export class ListUpdateInfoRecording implements ListUpdateInfo {
     //   __FlushElementTree(listElement);
     // });
     __SetAttribute(listElement, 'update-list-info', this.__toAttribute());
+    const [componentAtIndex, componentAtIndexes] = componentAtIndexFactory(this.list.childNodes);
     __UpdateListCallbacks(
       listElement,
-      componentAtIndexFactory(this.list.childNodes),
+      componentAtIndex,
       enqueueComponentFactory(),
+      componentAtIndexes,
     );
   }
 
@@ -243,13 +245,17 @@ export function clearListGlobal(): void {
   }
 }
 
-export function componentAtIndexFactory(ctx: SnapshotInstance[]): ComponentAtIndexCallback {
+export function componentAtIndexFactory(
+  ctx: SnapshotInstance[],
+): [ComponentAtIndexCallback, ComponentAtIndexesCallback] {
   const componentAtIndex = (
     list: FiberElement,
     listID: number,
     cellIndex: number,
     operationID: number,
     enableReuseNotification: boolean,
+    enableBatchRender: boolean = false,
+    asyncFlush: boolean = false,
   ) => {
     const signMap = gSignMap[listID];
     const recycleMap = gRecycleMap[listID];
@@ -284,7 +290,14 @@ export function componentAtIndexFactory(ctx: SnapshotInstance[]): ComponentAtInd
       if (recycleSignMap?.has(sign)) {
         signMap.set(sign, childCtx);
         recycleSignMap.delete(sign);
-        __FlushElementTree(root, { triggerLayout: true, operationID, elementID: sign, listID });
+        if (!enableBatchRender) {
+          __FlushElementTree(root, { triggerLayout: true, operationID, elementID: sign, listID });
+        } else if (enableBatchRender && asyncFlush) {
+          __FlushElementTree(root, { asyncFlush: true });
+        } else {
+          // enableBatchRender == true && asyncFlush == false
+          // in this case, no need to invoke __FlushElementTree because in the end of componentAtIndexes(), the list will invoke __FlushElementTree.
+        }
         return sign;
       } else {
         const newCtx = childCtx.takeElements();
@@ -299,24 +312,31 @@ export function componentAtIndexFactory(ctx: SnapshotInstance[]): ComponentAtInd
       hydrate(oldCtx, childCtx);
       oldCtx.unRenderElements();
       const root = childCtx.__element_root!;
-      if (enableReuseNotification) {
-        __FlushElementTree(root, {
+      if (!enableBatchRender) {
+        const flushOptions: FlushOptions = {
           triggerLayout: true,
           operationID,
           elementID: sign,
           listID,
-          listReuseNotification: {
+        };
+        if (enableReuseNotification) {
+          flushOptions.listReuseNotification = {
             listElement: list,
             itemKey: platformInfo['item-key'],
-          },
-        });
-      } else {
-        __FlushElementTree(root, {
-          triggerLayout: true,
-          operationID,
-          elementID: sign,
-          listID,
-        });
+          };
+        }
+        __FlushElementTree(root, flushOptions);
+      } else if (enableBatchRender && asyncFlush) {
+        const flushOptions: FlushOptions = {
+          asyncFlush: true,
+        };
+        if (enableReuseNotification) {
+          flushOptions.listReuseNotification = {
+            listElement: list,
+            itemKey: platformInfo['item-key'],
+          };
+        }
+        __FlushElementTree(root, flushOptions);
       }
       signMap.set(sign, childCtx);
       commitMainThreadPatchUpdate(undefined);
@@ -327,17 +347,43 @@ export function componentAtIndexFactory(ctx: SnapshotInstance[]): ComponentAtInd
     const root = childCtx.__element_root!;
     __AppendElement(list, root);
     const sign = __GetElementUniqueID(root);
-    __FlushElementTree(root, {
-      triggerLayout: true,
-      operationID,
-      elementID: sign,
-      listID,
-    });
+    if (!enableBatchRender) {
+      __FlushElementTree(root, {
+        triggerLayout: true,
+        operationID,
+        elementID: sign,
+        listID,
+      });
+    } else if (enableBatchRender && asyncFlush) {
+      __FlushElementTree(root, {
+        asyncFlush: true,
+      });
+    }
     signMap.set(sign, childCtx);
     commitMainThreadPatchUpdate(undefined);
     return sign;
   };
-  return componentAtIndex;
+
+  const componentAtIndexes = (
+    list: FiberElement,
+    listID: number,
+    cellIndexes: number[],
+    operationIDs: number[],
+    enableReuseNotification: boolean,
+    asyncFlush: boolean,
+  ) => {
+    const uiSigns = cellIndexes.map((cellIndex, index) => {
+      const operationID = operationIDs[index] ?? 0;
+      return componentAtIndex(list, listID, cellIndex, operationID, enableReuseNotification, true, asyncFlush);
+    });
+    __FlushElementTree(list, {
+      triggerLayout: true,
+      operationIDs: operationIDs,
+      elementIDs: uiSigns,
+      listID,
+    });
+  };
+  return [componentAtIndex, componentAtIndexes] as const;
 }
 
 export function enqueueComponentFactory(): EnqueueComponentCallback {
@@ -371,11 +417,13 @@ export function snapshotCreateList(
 ): FiberElement {
   const signMap = new Map<number, SnapshotInstance>();
   const recycleMap = new Map<string, Map<number, SnapshotInstance>>();
+  const [componentAtIndex, componentAtIndexes] = componentAtIndexFactory([]);
   const list = __CreateList(
     pageId,
-    componentAtIndexFactory([]),
+    componentAtIndex,
     enqueueComponentFactory(),
     {},
+    componentAtIndexes,
   );
   const listID = __GetElementUniqueID(list);
   gSignMap[listID] = signMap;

package/runtime/src/lynx/env.ts

@@ -3,7 +3,7 @@
 // LICENSE file in the root directory of this source tree.
 import type { DataProcessorDefinition } from '../lynx-api.js';
 
-export function setupLynxEnv(): void {
+export function setupLynxTestingEnv(): void {
   if (!__LEPUS__) {
     const { initData, updateData } = lynxCoreInject.tt._params;
     // @ts-ignore

package/runtime/src/lynx/performance.ts

@@ -6,6 +6,7 @@ import type { VNode } from 'preact';
 
 import { DIFF } from '../renderToOpcodes/constants.js';
 import { __globalSnapshotPatch } from '../lifecycle/patch/snapshotPatch.js';
+import { isSdkVersionGt } from '../utils.js';
 
 enum PerformanceTimingKeys {
   updateSetStateTrigger,
@@ -93,7 +94,11 @@ function beginPipeline(needTimestamps: boolean, pipelineOrigin: PipelineOrigin,
         break;
     }
 
-    lynx.performance?._onPipelineStart?.(globalPipelineOptions.pipelineID, globalPipelineOptions);
+    if (isSdkVersionGt(3, 0)) {
+      lynx.performance?._onPipelineStart?.(globalPipelineOptions.pipelineID, globalPipelineOptions);
+    } else {
+      lynx.performance?._onPipelineStart?.(globalPipelineOptions.pipelineID);
+    }
     if (timingFlag) {
       lynx.performance?._bindPipelineIdWithTimingFlag?.(globalPipelineOptions.pipelineID, timingFlag);
     }

package/runtime/src/lynx/runWithForce.ts

@@ -2,13 +2,17 @@ import { options } from 'preact';
 import type { VNode } from 'preact';
 import { COMPONENT, DIFF, DIFFED, FORCE } from '../renderToOpcodes/constants.js';
 
+const sForcedVNode = Symbol('FORCE');
+
+type PatchedVNode = VNode & { [sForcedVNode]?: true };
+
 export function runWithForce(cb: () => void): void {
   // save vnode and its `_component` in WeakMap
   const m = new WeakMap<VNode, any>();
 
   const oldDiff = options[DIFF];
 
-  options[DIFF] = (vnode: VNode) => {
+  options[DIFF] = (vnode: PatchedVNode) => {
     if (oldDiff) {
       oldDiff(vnode);
     }
@@ -28,19 +32,26 @@ export function runWithForce(cb: () => void): void {
         return m.get(vnode);
       },
     });
+    vnode[sForcedVNode] = true;
   };
 
   const oldDiffed = options[DIFFED];
 
-  options[DIFFED] = (vnode: VNode) => {
+  options[DIFFED] = (vnode: PatchedVNode) => {
     if (oldDiffed) {
       oldDiffed(vnode);
     }
 
-    // delete is a reverse operation of previous `Object.defineProperty`
-    delete vnode[COMPONENT];
-    // restore
-    vnode[COMPONENT] = m.get(vnode);
+    // There would be cases when `options[DIFF]` has been reset while options[DIFFED] is not,
+    // so we need to check if `vnode` is patched by `options[DIFF]`.
+    // We only want to change the patched vnode
+    if (vnode[sForcedVNode]) {
+      // delete is a reverse operation of previous `Object.defineProperty`
+      delete vnode[COMPONENT];
+      delete vnode[sForcedVNode];
+      // restore
+      vnode[COMPONENT] = m.get(vnode);
+    }
   };
 
   try {

package/runtime/src/lynx/tt.ts

@@ -1,34 +1,30 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
+import { render } from 'preact';
+
 import { LifecycleConstant, NativeUpdateDataType } from '../lifecycleConstant.js';
 import {
-  PerformanceTimingKeys,
   PerformanceTimingFlags,
+  PerformanceTimingKeys,
   PipelineOrigins,
   beginPipeline,
   markTiming,
 } from './performance.js';
 import { BackgroundSnapshotInstance, hydrate } from '../backgroundSnapshot.js';
+import { runWithForce } from './runWithForce.js';
 import { destroyBackground } from '../lifecycle/destroy.js';
 import { delayedEvents, delayedPublishEvent } from '../lifecycle/event/delayEvents.js';
 import { delayLifecycleEvent, delayedLifecycleEvents } from '../lifecycle/event/delayLifecycleEvents.js';
-import {
-  clearPatchesToCommit,
-  commitPatchUpdate,
-  genCommitTaskId,
-  globalCommitTaskMap,
-  patchesToCommit,
-  type PatchList,
-} from '../lifecycle/patch/commit.js';
+import { commitPatchUpdate, genCommitTaskId, globalCommitTaskMap } from '../lifecycle/patch/commit.js';
+import type { PatchList } from '../lifecycle/patch/commit.js';
 import { reloadBackground } from '../lifecycle/reload.js';
-import { renderBackground } from '../lifecycle/render.js';
 import { CHILDREN } from '../renderToOpcodes/constants.js';
 import { __root } from '../root.js';
 import { globalRefsToSet, updateBackgroundRefs } from '../snapshot/ref.js';
 import { backgroundSnapshotInstanceManager } from '../snapshot.js';
 import { destroyWorklet } from '../worklet/destroy.js';
-import { runWithForce } from './runWithForce.js';
+
 export { runWithForce };
 
 function injectTt(): void {
@@ -129,14 +125,11 @@ function onLifecycleEventImpl(type: string, data: any): void {
         console.profile('commitChanges');
       }
       const commitTaskId = genCommitTaskId();
-      patchesToCommit.push(
-        { snapshotPatch, id: commitTaskId },
-      );
       const patchList: PatchList = {
-        patchList: patchesToCommit,
+        patchList: [{ snapshotPatch, id: commitTaskId }],
       };
-      clearPatchesToCommit();
       const obj = commitPatchUpdate(patchList, { isHydration: true });
+
       lynx.getNativeApp().callLepusMethod(LifecycleConstant.patchUpdate, obj, () => {
         updateBackgroundRefs(commitTaskId);
         globalCommitTaskMap.forEach((commitTask, id) => {
@@ -212,7 +205,7 @@ function updateGlobalProps(newData: Record<string, any>): void {
   // This is already done because updateFromRoot will consume all dirty flags marked by
   // the setState, and setState's flush will be a noop. No extra diffs will be needed.
   Promise.resolve().then(() => {
-    runWithForce(() => renderBackground(__root.__jsx, __root as any));
+    runWithForce(() => render(__root.__jsx, __root as any));
   });
   lynxCoreInject.tt.GlobalEventEmitter.emit('onGlobalPropsChanged');
 }

package/runtime/src/lynx-api.ts

@@ -1,13 +1,13 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
+import { render } from 'preact';
 import { createContext, createElement } from 'preact/compat';
 import { useState } from 'preact/hooks';
 import type { Consumer, FC, ReactNode } from 'react';
 
 import { factory, withInitDataInState } from './compat/initData.js';
 import { useLynxGlobalEventListener } from './hooks/useLynxGlobalEventListener.js';
-import { renderBackground } from './lifecycle/render.js';
 import { LifecycleConstant } from './lifecycleConstant.js';
 import { flushDelayedLifecycleEvents } from './lynx/tt.js';
 import { __root } from './root.js';
@@ -43,13 +43,13 @@ export interface Root {
    *   return <view>...</view>
    * }
    *
-   * if (__LEPUS__) {
+   * if (__MAIN_THREAD__) {
    *   root.render(
    *     <DataProvider data={DEFAULT_DATA}>
    *        <App/>
    *     </DataProvider>
    *   );
-   * } else if (__JS__) {
+   * } else if (__BACKGROUND__) {
    *   fetchData().then((data) => {
    *     root.render(
    *       <DataProvider data={data}>
@@ -82,11 +82,11 @@ export interface Root {
  */
 export const root: Root = {
   render: (jsx: ReactNode): void => {
-    if (__LEPUS__) {
+    if (__MAIN_THREAD__) {
       __root.__jsx = jsx;
     } else {
       __root.__jsx = jsx;
-      renderBackground(jsx, __root as any);
+      render(jsx, __root as any);
       if (__FIRST_SCREEN_SYNC_TIMING__ === 'immediately') {
         // This is for cases where `root.render()` is called asynchronously,
         // `firstScreen` message might have been reached.
@@ -370,7 +370,7 @@ export interface Lynx {
   registerDataProcessors: (dataProcessorDefinition?: DataProcessorDefinition) => void;
 }
 
-export { runOnMainThread } from './worklet/runOnMainThread.js';
+export { useLynxGlobalEventListener } from './hooks/useLynxGlobalEventListener.js';
 export { runOnBackground } from './worklet/runOnBackground.js';
+export { runOnMainThread } from './worklet/runOnMainThread.js';
 export { MainThreadRef, useMainThreadRef } from './worklet/workletRef.js';
-export { useLynxGlobalEventListener } from './hooks/useLynxGlobalEventListener.js';

package/runtime/src/lynx.ts

@@ -11,21 +11,21 @@ import { initDelayUnmount } from './lifecycle/delayUnmount.js';
 import { replaceCommitHook, replaceRequestAnimationFrame } from './lifecycle/patch/commit.js';
 import { injectUpdateMainThread } from './lifecycle/patch/updateMainThread.js';
 import { injectCalledByNative } from './lynx/calledByNative.js';
-import { setupLynxEnv } from './lynx/env.js';
+import { setupLynxTestingEnv } from './lynx/env.js';
 import { injectLepusMethods } from './lynx/injectLepusMethods.js';
 import { initTimingAPI } from './lynx/performance.js';
 import { injectTt } from './lynx/tt.js';
 export { runWithForce } from './lynx/runWithForce.js';
 
 // @ts-expect-error Element implicitly has an 'any' type because type 'typeof globalThis' has no index signature
-if (__LEPUS__ && typeof globalThis.processEvalResult === 'undefined') {
+if (__MAIN_THREAD__ && typeof globalThis.processEvalResult === 'undefined') {
   // @ts-expect-error Element implicitly has an 'any' type because type 'typeof globalThis' has no index signature
   globalThis.processEvalResult = <T>(result: ((schema: string) => T) | undefined, schema: string) => {
     return result?.(schema);
   };
 }
 
-if (__LEPUS__) {
+if (__MAIN_THREAD__) {
   injectCalledByNative();
   injectUpdateMainThread();
   if (__DEV__) {
@@ -39,8 +39,9 @@ if (__PROFILE__) {
   initProfileHook();
 }
 
-if (__JS__) {
-  options.document = document;
+if (__BACKGROUND__) {
+  // Trick Preact and TypeScript to accept our custom document adapter.
+  options.document = document as any;
   setupBackgroundDocument();
   injectTt();
 
@@ -53,4 +54,4 @@ if (__JS__) {
   }
 }
 
-setupLynxEnv();
+setupLynxTestingEnv();

package/runtime/src/opcodes.ts

@@ -52,7 +52,7 @@ export function ssrHydrateByOpcodes(
           const signMap = gSignMap[listElementUniqueID] = new Map();
           gRecycleMap[listElementUniqueID] = new Map();
           const enqueueFunc = enqueueComponentFactory();
-          const componentAtIndex = componentAtIndexFactory(top.childNodes);
+          const [componentAtIndex, componentAtIndexes] = componentAtIndexFactory(top.childNodes);
           for (const child of top.childNodes) {
             if (child.__element_root) {
               const childElementUniqueID = __GetElementUniqueID(child.__element_root);
@@ -64,7 +64,7 @@ export function ssrHydrateByOpcodes(
               );
             }
           }
-          __UpdateListCallbacks(listElement, componentAtIndex, enqueueFunc);
+          __UpdateListCallbacks(listElement, componentAtIndex, enqueueFunc, componentAtIndexes);
         }
 
         stack.pop();

package/runtime/src/renderToOpcodes/index.ts

@@ -2,7 +2,12 @@
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
 
-// modified from preact-render-to-string@6.0.3
+/**
+ * Implements rendering to opcodes.
+ * This module is modified from preact-render-to-string@6.0.3 to generate
+ * opcodes instead of HTML strings for Lynx.
+ */
+
 // @ts-nocheck
 
 import { Fragment, h, options } from 'preact';

package/runtime/src/root.ts

@@ -4,15 +4,19 @@
 import { BackgroundSnapshotInstance } from './backgroundSnapshot.js';
 import { SnapshotInstance } from './snapshot.js';
 
+/**
+ * The internal ReactLynx's root.
+ * {@link @lynx-js/react!Root | root}.
+ */
 let __root: (SnapshotInstance | BackgroundSnapshotInstance) & { __jsx?: React.ReactNode; __opcodes?: any[] };
 
 function setRoot(root: typeof __root): void {
   __root = root;
 }
 
-if (__LEPUS__) {
+if (__MAIN_THREAD__) {
   setRoot(new SnapshotInstance('root'));
-} else if (__JS__) {
+} else if (__BACKGROUND__) {
   setRoot(new BackgroundSnapshotInstance('root'));
 }
 

package/runtime/src/snapshot/ref.ts

@@ -137,12 +137,12 @@ function markRefToRemove(sign: string, ref: unknown): void {
 }
 
 export {
-  updateRef,
-  takeGlobalRefPatchMap,
-  updateBackgroundRefs,
-  unref,
-  transformRef,
   globalRefsToRemove,
   globalRefsToSet,
   markRefToRemove,
+  takeGlobalRefPatchMap,
+  transformRef,
+  unref,
+  updateBackgroundRefs,
+  updateRef,
 };

package/runtime/src/snapshot/spread.ts

@@ -1,16 +1,24 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
+
+/**
+ * Handles JSX spread operator in the snapshot system.
+ *
+ * Spread operators in JSX (e.g., <div {...props}>) are transformed into
+ * optimized attribute updates at compile time, avoiding runtime object spreads.
+ */
+
+import { BackgroundSnapshotInstance } from '../backgroundSnapshot.js';
+import { __pendingListUpdates, ListUpdateInfoRecording } from '../list.js';
 import { SnapshotInstance } from '../snapshot.js';
+import { isDirectOrDeepEqual, isEmptyObject, pick } from '../utils.js';
 import { updateEvent } from './event.js';
-import { BackgroundSnapshotInstance } from '../backgroundSnapshot.js';
+import { updateGesture } from './gesture.js';
+import { platformInfoAttributes, updateListItemPlatformInfo } from './platformInfo.js';
 import { transformRef, updateRef } from './ref.js';
 import { updateWorkletEvent } from './workletEvent.js';
 import { updateWorkletRef } from './workletRef.js';
-import { updateGesture } from './gesture.js';
-import { platformInfoAttributes, updateListItemPlatformInfo } from './platformInfo.js';
-import { isDirectOrDeepEqual, isEmptyObject, pick } from '../utils.js';
-import { __pendingListUpdates, ListUpdateInfoRecording } from '../list.js';
 
 const eventRegExp = /^(([A-Za-z-]*):)?(bind|catch|capture-bind|capture-catch|global-bind)([A-Za-z]+)$/;
 const eventTypeMap: Record<string, string> = {
@@ -284,4 +292,4 @@ function transformSpread(
   return result;
 }
 
-export { updateSpread, transformSpread };
+export { transformSpread, updateSpread };

package/runtime/src/snapshot.ts

@@ -1,26 +1,44 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
+
+/**
+ * Core snapshot system that implements a compiler-hinted virtual DOM.
+ *
+ * Key components:
+ * 1. {@link Snapshot}: Template definition generated at compile time
+ * 2. {@link SnapshotInstance}: Runtime instance in the main thread
+ * 3. {@link BackgroundSnapshotInstance}: Runtime instance in the background thread
+ *
+ * The system uses static analysis to identify dynamic parts and generate
+ * optimized update instructions, avoiding full virtual DOM diffing.
+ */
+
 import type { Worklet, WorkletRefImpl } from '@lynx-js/react/worklet-runtime/bindings';
 
 import type { BackgroundSnapshotInstance } from './backgroundSnapshot.js';
+import { SnapshotOperation, __globalSnapshotPatch } from './lifecycle/patch/snapshotPatch.js';
 import { ListUpdateInfoRecording, __pendingListUpdates, snapshotDestroyList } from './list.js';
 import { unref } from './snapshot/ref.js';
-import { SnapshotOperation, __globalSnapshotPatch } from './lifecycle/patch/snapshotPatch.js';
 import { isDirectOrDeepEqual } from './utils.js';
 
+/**
+ * Types of dynamic parts that can be updated in a snapshot
+ * These are determined at compile time through static analysis
+ */
 export const enum DynamicPartType {
-  Attr = 0,
-  Spread,
-  Slot,
-  // Component,
-  Children,
-  ListChildren,
-
-  // Used by compat layer
-  MultiChildren,
+  Attr = 0, // Regular attribute updates
+  Spread, // Spread operator in JSX
+  Slot, // Slot for component children
+  Children, // Regular children updates
+  ListChildren, // List/array children updates
+  MultiChildren, // Multiple children updates (compat layer)
 }
 
+/**
+ * A snapshot definition that contains all the information needed to create and update elements
+ * This is generated at compile time through static analysis of the JSX
+ */
 interface Snapshot {
   create: null | ((ctx: SnapshotInstance) => FiberElement[]);
   update: null | ((ctx: SnapshotInstance, index: number, oldValue: any) => void)[];
@@ -234,6 +252,13 @@ export interface SerializedSnapshotInstance {
 const DEFAULT_ENTRY_NAME = '__Card__';
 const DEFAULT_CSS_ID = 0;
 
+/**
+ * The runtime instance of a {@link Snapshot} on the main thread that manages
+ * the actual elements and handles updates to dynamic parts.
+ *
+ * This class is designed to be compatible with Preact's {@link ContainerNode}
+ * interface for Preact's renderer to operate upon.
+ */
 export class SnapshotInstance {
   __id: number;
   __snapshot_def: Snapshot;

package/testing-library/README.md

@@ -58,7 +58,7 @@ test('renders options.wrapper around node', async () => {
 });
 ```
 
-💡 Since our testing environment (`@lynx-js/test-environment`) is based on jsdom, You may also be interested in installing `@testing-library/jest-dom` so you can use
+💡 Since our testing environment (`@lynx-js/testing-environment`) is based on jsdom, You may also be interested in installing `@testing-library/jest-dom` so you can use
 [the custom jest matchers](https://github.com/testing-library/jest-dom).
 
 ## Examples