@lynx-js/react 0.110.0 → 0.111.0

package/runtime/src/lynx-api.ts

@@ -86,6 +86,7 @@ export const root: Root = {
       __root.__jsx = jsx;
     } else {
       __root.__jsx = jsx;
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
       render(jsx, __root as any);
       if (__FIRST_SCREEN_SYNC_TIMING__ === 'immediately') {
         // This is for cases where `root.render()` is called asynchronously,
@@ -107,7 +108,7 @@ const _InitData = /* @__PURE__ */ factory<InitData>(
     useState,
     createElement,
     useLynxGlobalEventListener,
-  } as any,
+  },
   '__initData',
   'onDataChanged',
 );
@@ -137,6 +138,7 @@ const _InitData = /* @__PURE__ */ factory<InitData>(
  *
  * @public
  */
+// @ts-expect-error make preact and react types work
 export const InitDataProvider: FC<{ children?: ReactNode | undefined }> = /* @__PURE__ */ _InitData.Provider();
 /**
  * The {@link https://react.dev/reference/react/createContext#consumer | Consumer} Component that provide `initData`.
@@ -144,6 +146,7 @@ export const InitDataProvider: FC<{ children?: ReactNode | undefined }> = /* @__
  * @group Components
  * @public
  */
+// @ts-expect-error make preact and react types work
 export const InitDataConsumer: Consumer<InitData> = /* @__PURE__ */ _InitData.Consumer();
 /**
  * A React Hooks for you to get `initData`.
@@ -215,6 +218,82 @@ export interface InitData {}
 
 export { withInitDataInState };
 
+/**
+ * The data processors that registered with {@link Lynx.registerDataProcessors}.
+ *
+ * @example
+ *
+ * Extending `dataProcessors` interface
+ *
+ * ```ts
+ * import type { DataProcessors as WellKnownDataProcessors } from '@lynx-js/react';
+ *
+ * declare module '@lynx-js/react' {
+ *   interface DataProcessors extends WellKnownDataProcessors {
+ *     foo(bar: string): number;
+ *   }
+ * }
+ * ```
+ *
+ * Then you can use `lynx.registerDataProcessors` with types.
+ *
+ * ```js
+ * lynx.registerDataProcessors({
+ *   dataProcessors: {
+ *     foo(bar) {
+ *       return 1;
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @public
+ */
+export interface DataProcessors {
+  /**
+   * Optional processor to override screen metrics used by the app
+   *
+   * @param metrics - The physical screen dimensions in pixels
+   *
+   * @returns New screen dimensions to be used by the app
+   *
+   * @example
+   *
+   * ```ts
+   * lynx.registerDataProcessors({
+   *   dataProcessors: {
+   *     getScreenMetricsOverride: (metrics) => {
+   *       // Force a specific aspect ratio
+   *       return {
+   *         width: metrics.width,
+   *         height: metrics.width * (16/9)
+   *       };
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  getScreenMetricsOverride?(metrics: {
+    /**
+     * The physical pixel width of the screen
+     */
+    width: number;
+    /**
+     * The physical pixel height of the screen
+     */
+    height: number;
+  }): { width: number; height: number };
+
+  /**
+   * Custom unknown data processors.
+   *
+   * @remarks
+   *
+   * You may extends the `DataProcessors` interface for better TypeScript types. See {@link DataProcessors}.
+   */
+  [processorName: string]: (...args: any[]) => any;
+}
+
 /**
  * Definition of DataProcessor(s)
  * @public
@@ -235,7 +314,7 @@ export interface DataProcessorDefinition {
    *
    * @public
    */
-  dataProcessors?: Record<string, ((rawInitData: InitDataRaw) => InitData)>;
+  dataProcessors?: DataProcessors;
 }
 
 /**

package/runtime/src/lynx.ts

@@ -42,6 +42,7 @@ if (__PROFILE__) {
 
 if (__BACKGROUND__) {
   // Trick Preact and TypeScript to accept our custom document adapter.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
   options.document = document as any;
   setupBackgroundDocument();
   injectTt();

package/runtime/src/opcodes.ts

@@ -1,6 +1,7 @@
 // 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 { hydrate } from './hydrate.js';
 import { componentAtIndexFactory, enqueueComponentFactory, gRecycleMap, gSignMap } from './list.js';
 import { CHILDREN } from './renderToOpcodes/constants.js';
 import { SnapshotInstance } from './snapshot.js';
@@ -52,7 +53,7 @@ export function ssrHydrateByOpcodes(
           const signMap = gSignMap[listElementUniqueID] = new Map();
           gRecycleMap[listElementUniqueID] = new Map();
           const enqueueFunc = enqueueComponentFactory();
-          const [componentAtIndex, componentAtIndexes] = componentAtIndexFactory(top.childNodes);
+          const [componentAtIndex, componentAtIndexes] = componentAtIndexFactory(top.childNodes, hydrate);
           for (const child of top.childNodes) {
             if (child.__element_root) {
               const childElementUniqueID = __GetElementUniqueID(child.__element_root);

package/runtime/src/pendingListUpdates.ts

@@ -0,0 +1,18 @@
+// Copyright 2025 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 type { ListUpdateInfo } from './listUpdateInfo.js';
+
+export const __pendingListUpdates = {
+  values: {} as Record<number, ListUpdateInfo>,
+  clear(): void {
+    this.values = {};
+  },
+  flush(): void {
+    Object.values(this.values).forEach(update => {
+      update.flush();
+    });
+    this.clear();
+  },
+};

package/runtime/src/renderToOpcodes/index.ts

@@ -97,9 +97,9 @@ export const __OpText = 3;
  * @param {Record<string, unknown>} context
  */
 function renderClassComponent(vnode, context) {
-  let type = /** @type {import("preact").ComponentClass<typeof vnode.props>} */ (vnode.type);
+  const type = /** @type {import("preact").ComponentClass<typeof vnode.props>} */ (vnode.type);
 
-  let c = new type(vnode.props, context);
+  const c = new type(vnode.props, context);
 
   vnode[COMPONENT] = c;
   c[VNODE] = vnode;
@@ -162,7 +162,7 @@ function _renderToString(
   if (isArray(vnode)) {
     parent[CHILDREN] = vnode;
     for (let i = 0; i < vnode.length; i++) {
-      let child = vnode[i];
+      const child = vnode[i];
       if (child == null || typeof child === 'boolean') continue;
 
       _renderToString(child, context, isSvgMode, selectValue, parent, opcodes);
@@ -190,7 +190,7 @@ function _renderToString(
     } else {
       contextType = type.contextType;
       if (contextType != null) {
-        let provider = context[contextType.__c];
+        const provider = context[contextType.__c];
         cctx = provider ? provider.props.value : contextType.__;
       }
 
@@ -236,7 +236,7 @@ function _renderToString(
 
     // When a component returns a Fragment node we flatten it in core, so we
     // need to mirror that logic here too
-    let isTopLevelFragment = rendered != null && rendered.type === Fragment
+    const isTopLevelFragment = rendered != null && rendered.type === Fragment
       && rendered.key == null;
     rendered = isTopLevelFragment ? rendered.props.children : rendered;
 
@@ -254,8 +254,8 @@ function _renderToString(
 
   opcodes.push(__OpBegin, vnode);
 
-  for (let name in props) {
-    let v = props[name];
+  for (const name in props) {
+    const v = props[name];
 
     switch (name) {
       case 'children':

package/runtime/src/snapshot/dynamicPartType.ts

@@ -0,0 +1,16 @@
+// Copyright 2025 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.
+
+/**
+ * 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, // 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)
+}

package/runtime/src/snapshot/gesture.ts

@@ -1,3 +1,6 @@
+// Copyright 2025 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 { processGesture } from '../gesture/processGesture.js';
 import type { GestureKind } from '../gesture/types.js';
 import { isMainThreadHydrationFinished } from '../lifecycle/patch/isMainThreadHydrationFinished.js';

package/runtime/src/snapshot/list.ts

@@ -0,0 +1,36 @@
+// Copyright 2025 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 { hydrate } from '../hydrate.js';
+import { componentAtIndexFactory, enqueueComponentFactory, gRecycleMap, gSignMap } from '../list.js';
+import type { SnapshotInstance } from '../snapshot.js';
+
+export function snapshotCreateList(
+  pageId: number,
+  _ctx: SnapshotInstance,
+  _expIndex: number,
+): FiberElement {
+  const signMap = new Map<number, SnapshotInstance>();
+  const recycleMap = new Map<string, Map<number, SnapshotInstance>>();
+  const [componentAtIndex, componentAtIndexes] = componentAtIndexFactory([], hydrate);
+  const list = __CreateList(
+    pageId,
+    componentAtIndex,
+    enqueueComponentFactory(),
+    {},
+    componentAtIndexes,
+  );
+  const listID = __GetElementUniqueID(list);
+  gSignMap[listID] = signMap;
+  gRecycleMap[listID] = recycleMap;
+  return list;
+}
+
+export function snapshotDestroyList(si: SnapshotInstance): void {
+  const [, elementIndex] = si.__snapshot_def.slot[0]!;
+  const list = si.__elements![elementIndex]!;
+  const listID = __GetElementUniqueID(list);
+  delete gSignMap[listID];
+  delete gRecycleMap[listID];
+}

package/runtime/src/snapshot/platformInfo.ts

@@ -1,4 +1,8 @@
-import { __pendingListUpdates, ListUpdateInfoRecording } from '../list.js';
+// Copyright 2025 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 { ListUpdateInfoRecording } from '../listUpdateInfo.js';
+import { __pendingListUpdates } from '../pendingListUpdates.js';
 import { SnapshotInstance } from '../snapshot.js';
 
 const platformInfoVirtualAttributes: Set<string> = /* @__PURE__ */ new Set<string>(['reuse-identifier']);
@@ -13,16 +17,26 @@ const platformInfoAttributes: Set<string> = /* @__PURE__ */ new Set<string>([
   'estimated-main-axis-size-px',
 ]);
 
+export interface PlatformInfo {
+  'reuse-identifier'?: string;
+  'full-span'?: boolean;
+  'item-key'?: string;
+  'sticky-top'?: boolean;
+  'sticky-bottom'?: boolean;
+  'estimated-height'?: number;
+  'estimated-height-px'?: number;
+  'estimated-main-axis-size-px'?: number;
+}
+
 function updateListItemPlatformInfo(
   ctx: SnapshotInstance,
   index: number,
   oldValue: any,
   elementIndex: number,
 ): void {
-  const newValue = ctx.__listItemPlatformInfo = ctx.__values![index];
+  const newValue = ctx.__listItemPlatformInfo = ctx.__values![index] as PlatformInfo;
 
-  // @ts-ignore
-  const list = ctx.__parent;
+  const list = ctx.parentNode;
   if (list?.__snapshot_def.isListHolder) {
     (__pendingListUpdates.values[list.__id] ??= new ListUpdateInfoRecording(list)).onSetAttribute(
       ctx,
@@ -35,7 +49,7 @@ function updateListItemPlatformInfo(
   // No adding / removing keys.
   if (ctx.__elements) {
     const e = ctx.__elements[elementIndex]!;
-    const value = ctx.__values![index];
+    const value = ctx.__values![index] as Record<string, unknown>;
     for (const k in value) {
       if (platformInfoVirtualAttributes.has(k)) {
         continue;

package/runtime/src/snapshot/ref.ts

@@ -12,6 +12,7 @@ const refsToApply: (Ref | [snapshotInstanceId: number, expIndex: number])[] = []
 
 type Ref = (((ref: RefProxy) => () => void) | { current: RefProxy | null }) & {
   _unmount?: () => void;
+  __ref?: { value: number };
 };
 
 function unref(snapshot: SnapshotInstance, recursive: boolean): void {

package/runtime/src/snapshot/spread.ts

@@ -9,10 +9,11 @@
  * optimized attribute updates at compile time, avoiding runtime object spreads.
  */
 
-import type { Worklet } from '@lynx-js/react/worklet-runtime/bindings';
+import type { Element, Worklet, WorkletRefImpl } from '@lynx-js/react/worklet-runtime/bindings';
 
-import { BackgroundSnapshotInstance } from '../backgroundSnapshot.js';
-import { ListUpdateInfoRecording, __pendingListUpdates } from '../list.js';
+import type { BackgroundSnapshotInstance } from '../backgroundSnapshot.js';
+import { ListUpdateInfoRecording } from '../listUpdateInfo.js';
+import { __pendingListUpdates } from '../pendingListUpdates.js';
 import { SnapshotInstance } from '../snapshot.js';
 import { isDirectOrDeepEqual, isEmptyObject, pick } from '../utils.js';
 import { updateEvent } from './event.js';
@@ -22,6 +23,7 @@ import { transformRef, updateRef } from './ref.js';
 import { updateWorkletEvent } from './workletEvent.js';
 import { updateWorkletRef } from './workletRef.js';
 
+// eslint-disable-next-line regexp/no-unused-capturing-group
 const eventRegExp = /^(([A-Za-z-]*):)?(bind|catch|capture-bind|capture-catch|global-bind)([A-Za-z]+)$/;
 const eventTypeMap: Record<string, string> = {
   bind: 'bindEvent',
@@ -38,12 +40,16 @@ const noFlattenAttributes = /* @__PURE__ */ new Set<string>([
   'exposure-id',
 ]);
 
-function updateSpread(snapshot: SnapshotInstance, index: number, oldValue: any, elementIndex: number): void {
+function updateSpread(
+  snapshot: SnapshotInstance,
+  index: number,
+  oldValue: Record<string, unknown> | undefined | null,
+  elementIndex: number,
+): void {
   oldValue ??= {};
-  let newValue: Record<string, any> = snapshot.__values![index]; // compiler guarantee this must be an object;
+  let newValue: Record<string, unknown> = snapshot.__values![index] as Record<string, unknown>; // compiler guarantee this must be an object;
 
-  // @ts-ignore
-  const list = snapshot.__parent;
+  const list = snapshot.parentNode;
   if (list?.__snapshot_def.isListHolder) {
     const oldPlatformInfo = pick(oldValue, platformInfoAttributes);
     const platformInfo = pick(newValue, platformInfoAttributes);
@@ -79,17 +85,17 @@ function updateSpread(snapshot: SnapshotInstance, index: number, oldValue: any,
     snapshot.__values![index] = newValue;
   }
 
-  const dataset: Record<string, any> = {};
+  const dataset: Record<string, unknown> = {};
   let match: RegExpMatchArray | null = null;
   for (const key in newValue) {
     const v = newValue[key];
     if (v !== oldValue[key]) {
       if (key === 'className') {
-        __SetClasses(snapshot.__elements[elementIndex]!, v);
+        __SetClasses(snapshot.__elements[elementIndex]!, v as string);
       } else if (key === 'style') {
-        __SetInlineStyles(snapshot.__elements[elementIndex]!, v);
+        __SetInlineStyles(snapshot.__elements[elementIndex]!, v as string);
       } else if (key === 'id') {
-        __SetID(snapshot.__elements[elementIndex]!, v);
+        __SetID(snapshot.__elements[elementIndex]!, v as string);
       } else if (key.startsWith('data-')) {
         // collected below
       } else if (key === 'ref') {
@@ -106,7 +112,7 @@ function updateSpread(snapshot: SnapshotInstance, index: number, oldValue: any,
           __id: snapshot.__id,
           __elements: snapshot.__elements,
         } as SnapshotInstance;
-        updateRef(fakeSnapshot, index, oldValue[key], elementIndex);
+        updateRef(fakeSnapshot, index, oldValue[key] as string | null, elementIndex);
       } else if (key.endsWith(':ref')) {
         snapshot.__worklet_ref_set ??= new Set();
         const fakeSnapshot = {
@@ -119,7 +125,13 @@ function updateSpread(snapshot: SnapshotInstance, index: number, oldValue: any,
           __elements: snapshot.__elements,
           __worklet_ref_set: snapshot.__worklet_ref_set,
         } as SnapshotInstance;
-        updateWorkletRef(fakeSnapshot, index, oldValue[key], elementIndex, key.slice(0, -4));
+        updateWorkletRef(
+          fakeSnapshot,
+          index,
+          oldValue[key] as WorkletRefImpl<Element> | Worklet | null | undefined,
+          elementIndex,
+          key.slice(0, -4),
+        );
       } else if (key.endsWith(':gesture')) {
         const workletType = key.slice(0, -8);
         const fakeSnapshot = {
@@ -200,7 +212,7 @@ function updateSpread(snapshot: SnapshotInstance, index: number, oldValue: any,
           __id: snapshot.__id,
           __elements: snapshot.__elements,
         } as SnapshotInstance;
-        updateRef(fakeSnapshot, index, oldValue[key], elementIndex);
+        updateRef(fakeSnapshot, index, oldValue[key] as string | null, elementIndex);
       } else if (key.endsWith(':ref')) {
         snapshot.__worklet_ref_set ??= new Set();
         const fakeSnapshot = {
@@ -213,7 +225,13 @@ function updateSpread(snapshot: SnapshotInstance, index: number, oldValue: any,
           __elements: snapshot.__elements,
           __worklet_ref_set: snapshot.__worklet_ref_set,
         } as SnapshotInstance;
-        updateWorkletRef(fakeSnapshot, index, oldValue[key], elementIndex, key.slice(0, -4));
+        updateWorkletRef(
+          fakeSnapshot,
+          index,
+          oldValue[key] as WorkletRefImpl<Element> | Worklet | null | undefined,
+          elementIndex,
+          key.slice(0, -4),
+        );
       } else if (key.endsWith(':gesture')) {
         const workletType = key.slice(0, -8);
         const fakeSnapshot = {
@@ -243,7 +261,15 @@ function updateSpread(snapshot: SnapshotInstance, index: number, oldValue: any,
           __elements: snapshot.__elements,
         } as SnapshotInstance;
         if (workletType) {
-          updateWorkletEvent(fakeSnapshot, index, oldValue[key], elementIndex, workletType, eventType, eventName);
+          updateWorkletEvent(
+            fakeSnapshot,
+            index,
+            oldValue[key] as Worklet,
+            elementIndex,
+            workletType,
+            eventType,
+            eventName,
+          );
         } else {
           updateEvent(fakeSnapshot, index, oldValue[key], elementIndex, eventType, eventName, key);
         }
@@ -283,7 +309,6 @@ function transformSpread(
       if (__LEPUS__) {
         result[key] = value ? 1 : undefined;
       } else {
-        // @ts-ignore
         result[key] = transformRef(value)?.__ref;
       }
     } else if (typeof value === 'function') {

package/runtime/src/snapshot/workletEvent.ts

@@ -4,8 +4,8 @@
 import { onWorkletCtxUpdate } from '@lynx-js/react/worklet-runtime/bindings';
 import type { Worklet } from '@lynx-js/react/worklet-runtime/bindings';
 
-import { SnapshotInstance } from '../snapshot.js';
 import { isMainThreadHydrationFinished } from '../lifecycle/patch/isMainThreadHydrationFinished.js';
+import { SnapshotInstance } from '../snapshot.js';
 
 function updateWorkletEvent(
   snapshot: SnapshotInstance,

package/runtime/src/snapshot/workletRef.ts

@@ -43,7 +43,7 @@ export function workletUnRef(value: Worklet | WorkletRefImpl<Element>): void {
 export function updateWorkletRef(
   snapshot: SnapshotInstance,
   expIndex: number,
-  oldValue: WorkletRefImpl<Element> | Worklet | undefined,
+  oldValue: WorkletRefImpl<Element> | Worklet | null | undefined,
   elementIndex: number,
   _workletType: string,
 ): void {

package/runtime/src/snapshot.ts

@@ -18,23 +18,14 @@ import type { Worklet, WorkletRefImpl } from '@lynx-js/react/worklet-runtime/bin
 
 import type { BackgroundSnapshotInstance } from './backgroundSnapshot.js';
 import { SnapshotOperation, __globalSnapshotPatch } from './lifecycle/patch/snapshotPatch.js';
-import { ListUpdateInfoRecording, __pendingListUpdates, snapshotDestroyList } from './list.js';
+import { ListUpdateInfoRecording } from './listUpdateInfo.js';
+import { __pendingListUpdates } from './pendingListUpdates.js';
+import { DynamicPartType } from './snapshot/dynamicPartType.js';
+import { snapshotDestroyList } from './snapshot/list.js';
+import type { PlatformInfo } from './snapshot/platformInfo.js';
 import { unref } from './snapshot/ref.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, // 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
@@ -174,10 +165,17 @@ export const backgroundSnapshotInstanceManager: {
       return null;
     }
     const spreadKey = res[2];
-    if (spreadKey) {
-      return ctx.__values![expIndex][spreadKey];
+    if (res[1] === '__extraProps') {
+      if (spreadKey) {
+        return ctx.__extraProps![spreadKey];
+      }
+      throw new Error('unreachable');
     } else {
-      return ctx.__values![expIndex];
+      if (spreadKey) {
+        return (ctx.__values![expIndex] as { [spreadKey]: unknown })[spreadKey];
+      } else {
+        return ctx.__values![expIndex];
+      }
     }
   },
 };
@@ -250,6 +248,7 @@ export interface SerializedSnapshotInstance {
   id: number;
   type: string;
   values?: any[] | undefined;
+  extraProps?: Record<string, unknown> | undefined;
   children?: SerializedSnapshotInstance[] | undefined;
 }
 
@@ -268,10 +267,11 @@ export class SnapshotInstance {
   __snapshot_def: Snapshot;
   __elements?: FiberElement[] | undefined;
   __element_root?: FiberElement | undefined;
-  __values?: any[] | undefined;
+  __values?: unknown[] | undefined;
   __current_slot_index = 0;
   __worklet_ref_set?: Set<WorkletRefImpl<any> | Worklet>;
-  __listItemPlatformInfo?: any;
+  __listItemPlatformInfo?: PlatformInfo;
+  __extraProps?: Record<string, unknown> | undefined;
 
   constructor(public type: string, id?: number) {
     this.__snapshot_def = snapshotManager.values.get(type)!;
@@ -280,7 +280,7 @@ export class SnapshotInstance {
       throw new Error('Snapshot not found: ' + type);
     }
 
-    id ||= snapshotInstanceManager.nextId -= 1;
+    id ??= snapshotInstanceManager.nextId -= 1;
     this.__id = id;
     snapshotInstanceManager.values.set(id, this);
   }
@@ -589,31 +589,30 @@ export class SnapshotInstance {
   }
 
   setAttribute(key: string | number, value: any): void {
-    const helper = (index: number, oldValue: any, newValue: any) => {
-      if (isDirectOrDeepEqual(oldValue, newValue)) {}
-      else {
-        this.__snapshot_def.update![index]!(this, index, oldValue);
-      }
-    };
-
     if (key === 'values') {
       const oldValues = this.__values;
-      this.__values = value;
+      const values = value as unknown[];
+      this.__values = values;
       if (oldValues) {
-        for (let index = 0; index < value.length; index++) {
-          helper(index, oldValues[index], value[index]);
+        for (let index = 0; index < values.length; index++) {
+          this.callUpdateIfNotDirectOrDeepEqual(index, oldValues[index], values[index]);
         }
       } else {
-        for (let index = 0; index < value.length; index++) {
-          helper(index, undefined, value[index]);
+        for (let index = 0; index < values.length; index++) {
+          this.callUpdateIfNotDirectOrDeepEqual(index, undefined, values[index]);
         }
       }
       return;
     }
 
-    const index = typeof key === 'string' ? Number(key.slice(2)) : key;
+    if (typeof key === 'string') {
+      // for more flexible usage, we allow setting non-indexed attributes
+      (this.__extraProps ??= {})[key] = value;
+      return;
+    }
+
     this.__values ??= [];
-    helper(index, this.__values[index], this.__values[index] = value);
+    this.callUpdateIfNotDirectOrDeepEqual(key, this.__values[key], this.__values[key] = value);
   }
 
   toJSON(): Omit<SerializedSnapshotInstance, 'children'> & { children: SnapshotInstance[] | undefined } {
@@ -621,7 +620,15 @@ export class SnapshotInstance {
       id: this.__id,
       type: this.type,
       values: this.__values,
+      extraProps: this.__extraProps,
       children: this.__firstChild ? this.childNodes : undefined,
     };
   }
+
+  callUpdateIfNotDirectOrDeepEqual(index: number, oldValue: any, newValue: any): void {
+    if (isDirectOrDeepEqual(oldValue, newValue)) {}
+    else {
+      this.__snapshot_def.update![index]!(this, index, oldValue);
+    }
+  }
 }

package/runtime/src/snapshotInstanceHydrationMap.ts

@@ -9,7 +9,7 @@
  * The map is used by the ref system to translate between snapshot instance IDs when
  * operations need to cross the thread boundary during the commit phase.
  */
-const hydrationMap: Map<number, number> = new Map();
+const hydrationMap: Map<number, number> = new Map<number, number>();
 
 /**
  * @internal