@fictjs/runtime 0.0.11 → 0.0.13

package/src/list-helpers.ts

@@ -19,12 +19,17 @@ import {
 import { insertNodesBefore, removeNodes, toNodeArray } from './node-ops'
 import reconcileArrays from './reconcile'
 import { batch } from './scheduler'
-import { createSignal, flush, setActiveSub, type Signal } from './signal'
+import { createSignal, effectScope, flush, setActiveSub, type Signal } from './signal'
 import type { FictNode } from './types'
 
 // Re-export shared DOM helpers for compiler-generated code
 export { insertNodesBefore, removeNodes, toNodeArray }
 
+const isDev =
+  typeof __DEV__ !== 'undefined'
+    ? __DEV__
+    : typeof process === 'undefined' || process.env?.NODE_ENV !== 'production'
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -32,7 +37,7 @@ export { insertNodesBefore, removeNodes, toNodeArray }
 /**
  * A keyed block represents a single item in a list with its associated DOM nodes and state
  */
-export interface KeyedBlock<T = unknown> {
+interface KeyedBlock<T = unknown> {
   /** Unique key for this block */
   key: string | number
   /** DOM nodes belonging to this block */
@@ -52,7 +57,7 @@ export interface KeyedBlock<T = unknown> {
 /**
  * Container for managing keyed list blocks
  */
-export interface KeyedListContainer<T = unknown> {
+interface KeyedListContainer<T = unknown> {
   /** Start marker comment node */
   startMarker: Comment
   /** End marker comment node */
@@ -97,15 +102,6 @@ type FineGrainedRenderItem<T> = (
   key: string | number,
 ) => Node[]
 
-/**
- * A block identified by start/end comment markers.
- */
-export interface MarkerBlock {
-  start: Comment
-  end: Comment
-  root?: RootContext
-}
-
 // ============================================================================
 // DOM Manipulation Primitives
 // ============================================================================
@@ -124,7 +120,8 @@ export function moveNodesBefore(parent: Node, nodes: Node[], anchor: Node | null
   for (let i = nodes.length - 1; i >= 0; i--) {
     const node = nodes[i]!
     if (!node || !(node instanceof Node)) {
-      throw new Error('Invalid node in moveNodesBefore')
+      const message = isDev ? 'Invalid node in moveNodesBefore' : 'FICT:E_NODE'
+      throw new Error(message)
     }
     // Only move if not already in correct position
     if (node.nextSibling !== anchor) {
@@ -157,49 +154,8 @@ export function moveNodesBefore(parent: Node, nodes: Node[], anchor: Node | null
  *
  * @param nodes - Array of nodes to remove
  */
-/**
- * Move an entire marker-delimited block (including markers) before the anchor.
- */
-export function moveMarkerBlock(parent: Node, block: MarkerBlock, anchor: Node | null): void {
-  const nodes = collectBlockNodes(block)
-  if (nodes.length === 0) return
-  moveNodesBefore(parent, nodes, anchor)
-}
-
-/**
- * Destroy a marker-delimited block, removing nodes and destroying the associated root.
- */
-export function destroyMarkerBlock(block: MarkerBlock): void {
-  if (block.root) {
-    destroyRoot(block.root)
-  }
-  removeBlockRange(block)
-}
-
-function collectBlockNodes(block: MarkerBlock): Node[] {
-  const nodes: Node[] = []
-  let cursor: Node | null = block.start
-  while (cursor) {
-    nodes.push(cursor)
-    if (cursor === block.end) {
-      break
-    }
-    cursor = cursor.nextSibling
-  }
-  return nodes
-}
-
-function removeBlockRange(block: MarkerBlock): void {
-  let cursor: Node | null = block.start
-  while (cursor) {
-    const next: Node | null = cursor.nextSibling
-    cursor.parentNode?.removeChild(cursor)
-    if (cursor === block.end) {
-      break
-    }
-    cursor = next
-  }
-}
+// Number.MAX_SAFE_INTEGER is 2^53 - 1, but we reset earlier to avoid any precision issues
+const MAX_SAFE_VERSION = 0x1fffffffffffff // 2^53 - 1
 
 export function createVersionedSignalAccessor<T>(initialValue: T): Signal<T> {
   let current = initialValue
@@ -212,7 +168,8 @@ export function createVersionedSignalAccessor<T>(initialValue: T): Signal<T> {
       return current
     }
     current = value as T
-    version++
+    // This is safe because we only care about version changes, not absolute values
+    version = version >= MAX_SAFE_VERSION ? 1 : version + 1
     track(version)
   }
 
@@ -229,7 +186,7 @@ export function createVersionedSignalAccessor<T>(initialValue: T): Signal<T> {
  *
  * @returns Container object with markers, blocks map, and dispose function
  */
-export function createKeyedListContainer<T = unknown>(): KeyedListContainer<T> {
+function createKeyedListContainer<T = unknown>(): KeyedListContainer<T> {
   const startMarker = document.createComment('fict:list:start')
   const endMarker = document.createComment('fict:list:end')
 
@@ -297,7 +254,7 @@ export function createKeyedListContainer<T = unknown>(): KeyedListContainer<T> {
  * @param render - Function that creates the DOM nodes and sets up bindings
  * @returns New KeyedBlock
  */
-export function createKeyedBlock<T>(
+function createKeyedBlock<T>(
   key: string | number,
   item: T,
   index: number,
@@ -317,24 +274,36 @@ export function createKeyedBlock<T>(
       }) as Signal<number>)
   const root = createRootContext(hostRoot)
   const prevRoot = pushRoot(root)
+  // maintaining proper cleanup chain. The scope will be disposed when
+  // the root is destroyed, ensuring nested effects are properly cleaned up.
+  let nodes: Node[] = []
+  let scopeDispose: (() => void) | undefined
 
-  // Isolate child effects from the outer effect (e.g., performDiff) by clearing activeSub.
-  // This prevents child effects from being purged when the outer effect re-runs.
+  // First, isolate from parent effect to prevent child effects from being
+  // purged when the outer effect (e.g., performDiff) re-runs
   const prevSub = setActiveSub(undefined)
 
-  let nodes: Node[] = []
   try {
-    const rendered = render(itemSig, indexSig, key)
-    // If render returns real DOM nodes/arrays, preserve them to avoid
-    // reparenting side-effects (tests may pre-insert them).
-    if (
-      rendered instanceof Node ||
-      (Array.isArray(rendered) && rendered.every(n => n instanceof Node))
-    ) {
-      nodes = toNodeArray(rendered)
-    } else {
-      const element = createElement(rendered as unknown as FictNode)
-      nodes = toNodeArray(element)
+    // Create an effectScope that will track all effects created during render
+    scopeDispose = effectScope(() => {
+      const rendered = render(itemSig, indexSig, key)
+      // If render returns real DOM nodes/arrays, preserve them to avoid
+      // reparenting side-effects (tests may pre-insert them).
+      if (
+        rendered instanceof Node ||
+        (Array.isArray(rendered) && rendered.every(n => n instanceof Node))
+      ) {
+        nodes = toNodeArray(rendered)
+      } else {
+        const element = createElement(rendered as unknown as FictNode)
+        nodes = toNodeArray(element)
+      }
+    })
+
+    // Register the scope cleanup with the root so effects are cleaned up
+    // when the block is destroyed
+    if (scopeDispose) {
+      root.cleanups.push(scopeDispose)
     }
   } finally {
     setActiveSub(prevSub)
@@ -356,13 +325,6 @@ export function createKeyedBlock<T>(
 // Utilities
 // ============================================================================
 
-/**
- * Find the first node after the start marker (for getting current anchor)
- */
-export function getFirstNodeAfter(marker: Comment): Node | null {
-  return marker.nextSibling
-}
-
 /**
  * Check if a node is between two markers
  */
@@ -379,6 +341,107 @@ export function isNodeBetweenMarkers(
   return false
 }
 
+function reorderBySwap<T>(
+  parent: ParentNode & Node,
+  first: KeyedBlock<T>,
+  second: KeyedBlock<T>,
+): boolean {
+  if (first === second) return false
+  const firstNodes = first.nodes
+  const secondNodes = second.nodes
+  if (firstNodes.length === 0 || secondNodes.length === 0) return false
+  const lastFirst = firstNodes[firstNodes.length - 1]!
+  const lastSecond = secondNodes[secondNodes.length - 1]!
+  const afterFirst = lastFirst.nextSibling
+  const afterSecond = lastSecond.nextSibling
+  moveNodesBefore(parent, firstNodes, afterSecond)
+  moveNodesBefore(parent, secondNodes, afterFirst)
+  return true
+}
+
+function getLISIndices(sequence: number[]): number[] {
+  const predecessors = new Array<number>(sequence.length)
+  const result: number[] = []
+
+  for (let i = 0; i < sequence.length; i++) {
+    const value = sequence[i]!
+    if (value < 0) {
+      predecessors[i] = -1
+      continue
+    }
+
+    let low = 0
+    let high = result.length
+    while (low < high) {
+      const mid = (low + high) >> 1
+      if (sequence[result[mid]!]! < value) {
+        low = mid + 1
+      } else {
+        high = mid
+      }
+    }
+
+    predecessors[i] = low > 0 ? result[low - 1]! : -1
+    if (low === result.length) {
+      result.push(i)
+    } else {
+      result[low] = i
+    }
+  }
+
+  const lis: number[] = new Array(result.length)
+  let k = result.length > 0 ? result[result.length - 1]! : -1
+  for (let i = result.length - 1; i >= 0; i--) {
+    lis[i] = k
+    k = predecessors[k]!
+  }
+  return lis
+}
+
+function reorderByLIS<T>(
+  parent: ParentNode & Node,
+  endMarker: Comment,
+  prev: KeyedBlock<T>[],
+  next: KeyedBlock<T>[],
+): boolean {
+  const positions = new Map<KeyedBlock<T>, number>()
+  for (let i = 0; i < prev.length; i++) {
+    positions.set(prev[i]!, i)
+  }
+
+  const sequence = new Array<number>(next.length)
+  for (let i = 0; i < next.length; i++) {
+    const position = positions.get(next[i]!)
+    if (position === undefined) return false
+    sequence[i] = position
+  }
+
+  const lisIndices = getLISIndices(sequence)
+  if (lisIndices.length === sequence.length) return true
+
+  const inLIS = new Array<boolean>(sequence.length).fill(false)
+  for (let i = 0; i < lisIndices.length; i++) {
+    inLIS[lisIndices[i]!] = true
+  }
+
+  let anchor: Node | null = endMarker
+  let moved = false
+  for (let i = next.length - 1; i >= 0; i--) {
+    const block = next[i]!
+    const nodes = block.nodes
+    if (nodes.length === 0) continue
+    if (inLIS[i]) {
+      anchor = nodes[0]!
+      continue
+    }
+    moveNodesBefore(parent, nodes, anchor)
+    anchor = nodes[0]!
+    moved = true
+  }
+
+  return moved
+}
+
 // ============================================================================
 // High-Level List Binding (for compiler-generated code)
 // ============================================================================
@@ -443,10 +506,6 @@ function createFineGrainedKeyedList<T>(
       const prevOrderedBlocks = container.orderedBlocks
       const nextOrderedBlocks = container.nextOrderedBlocks
       const orderedIndexByKey = container.orderedIndexByKey
-      newBlocks.clear()
-      nextOrderedBlocks.length = 0
-      orderedIndexByKey.clear()
-      const createdBlocks: KeyedBlock<T>[] = []
       const newItems = getItems()
 
       if (newItems.length === 0) {
@@ -473,8 +532,45 @@ function createFineGrainedKeyedList<T>(
       }
 
       const prevCount = prevOrderedBlocks.length
+      if (prevCount > 0 && newItems.length === prevCount && orderedIndexByKey.size === prevCount) {
+        let stableOrder = true
+        const seen = new Set<string | number>()
+        for (let i = 0; i < prevCount; i++) {
+          const item = newItems[i]!
+          const key = keyFn(item, i)
+          if (seen.has(key) || prevOrderedBlocks[i]!.key !== key) {
+            stableOrder = false
+            break
+          }
+          seen.add(key)
+        }
+        if (stableOrder) {
+          for (let i = 0; i < prevCount; i++) {
+            const item = newItems[i]!
+            const block = prevOrderedBlocks[i]!
+            if (block.rawItem !== item) {
+              block.rawItem = item
+              block.item(item)
+            }
+            if (needsIndex && block.rawIndex !== i) {
+              block.rawIndex = i
+              block.index(i)
+            }
+          }
+          return
+        }
+      }
+
+      newBlocks.clear()
+      nextOrderedBlocks.length = 0
+      orderedIndexByKey.clear()
+      const createdBlocks: KeyedBlock<T>[] = []
       let appendCandidate = prevCount > 0 && newItems.length >= prevCount
       const appendedBlocks: KeyedBlock<T>[] = []
+      let mismatchCount = 0
+      let mismatchFirst = -1
+      let mismatchSecond = -1
+      let hasDuplicateKey = false
 
       // Phase 1: Build new blocks map (reuse or create)
       newItems.forEach((item, index) => {
@@ -502,6 +598,12 @@ function createFineGrainedKeyedList<T>(
           // If newBlocks already has this key (duplicate key case), clean up the previous block
           const existingBlock = newBlocks.get(key)
           if (existingBlock) {
+            if (isDev) {
+              console.warn(
+                `[fict] Duplicate key "${String(key)}" detected in list rendering. ` +
+                  `Each item should have a unique key. The previous item with this key will be replaced.`,
+              )
+            }
             destroyRoot(existingBlock.root)
             removeNodes(existingBlock.nodes)
           }
@@ -518,6 +620,7 @@ function createFineGrainedKeyedList<T>(
         const position = orderedIndexByKey.get(key)
         if (position !== undefined) {
           appendCandidate = false
+          hasDuplicateKey = true
           const prior = nextOrderedBlocks[position]
           if (prior && prior !== resolvedBlock) {
             destroyRoot(prior.root)
@@ -534,8 +637,20 @@ function createFineGrainedKeyedList<T>(
               appendCandidate = false
             }
           }
-          orderedIndexByKey.set(key, nextOrderedBlocks.length)
+          const nextIndex = nextOrderedBlocks.length
+          orderedIndexByKey.set(key, nextIndex)
           nextOrderedBlocks.push(resolvedBlock)
+          if (
+            mismatchCount < 3 &&
+            (nextIndex >= prevCount || prevOrderedBlocks[nextIndex] !== resolvedBlock)
+          ) {
+            if (mismatchCount === 0) {
+              mismatchFirst = nextIndex
+            } else if (mismatchCount === 1) {
+              mismatchSecond = nextIndex
+            }
+            mismatchCount++
+          }
         }
 
         if (appendCandidate && index >= prevCount) {
@@ -587,8 +702,41 @@ function createFineGrainedKeyedList<T>(
         oldBlocks.clear()
       }
 
+      const canReorderInPlace =
+        createdBlocks.length === 0 &&
+        oldBlocks.size === 0 &&
+        nextOrderedBlocks.length === prevOrderedBlocks.length
+
+      let skipReconcile = false
+      let updateNodeBuffer = true
+
+      if (canReorderInPlace && nextOrderedBlocks.length > 0 && !hasDuplicateKey) {
+        if (mismatchCount === 0) {
+          skipReconcile = true
+          updateNodeBuffer = false
+        } else if (
+          mismatchCount === 2 &&
+          prevOrderedBlocks[mismatchFirst] === nextOrderedBlocks[mismatchSecond] &&
+          prevOrderedBlocks[mismatchSecond] === nextOrderedBlocks[mismatchFirst]
+        ) {
+          if (
+            reorderBySwap(
+              parent,
+              prevOrderedBlocks[mismatchFirst]!,
+              prevOrderedBlocks[mismatchSecond]!,
+            )
+          ) {
+            skipReconcile = true
+          }
+        } else if (
+          reorderByLIS(parent, container.endMarker, prevOrderedBlocks, nextOrderedBlocks)
+        ) {
+          skipReconcile = true
+        }
+      }
+
       // Phase 3: Reconcile DOM with buffered node arrays
-      if (newBlocks.size > 0 || container.currentNodes.length > 0) {
+      if (!skipReconcile && (newBlocks.size > 0 || container.currentNodes.length > 0)) {
         const prevNodes = container.currentNodes
         const nextNodes = container.nextNodes
         nextNodes.length = 0
@@ -608,6 +756,20 @@ function createFineGrainedKeyedList<T>(
         // Swap buffers to reuse arrays on next diff
         container.currentNodes = nextNodes
         container.nextNodes = prevNodes
+      } else if (skipReconcile && updateNodeBuffer) {
+        const prevNodes = container.currentNodes
+        const nextNodes = container.nextNodes
+        nextNodes.length = 0
+        nextNodes.push(container.startMarker)
+        for (let i = 0; i < nextOrderedBlocks.length; i++) {
+          const nodes = nextOrderedBlocks[i]!.nodes
+          for (let j = 0; j < nodes.length; j++) {
+            nextNodes.push(nodes[j]!)
+          }
+        }
+        nextNodes.push(container.endMarker)
+        container.currentNodes = nextNodes
+        container.nextNodes = prevNodes
       }
 
       // Swap block maps for reuse

package/src/props.ts

@@ -124,10 +124,7 @@ export function mergeProps<T extends Record<string, unknown>>(
 
   return new Proxy({} as Record<string, unknown>, {
     get(_, prop) {
-      // Symbol properties (like Symbol.iterator) should return undefined
-      if (typeof prop === 'symbol') {
-        return undefined
-      }
+      // Only return undefined if no source has this Symbol property
       // Search sources in reverse order (last wins)
       for (let i = validSources.length - 1; i >= 0; i--) {
         const src = validSources[i]!
@@ -136,6 +133,7 @@ export function mergeProps<T extends Record<string, unknown>>(
 
         const value = (raw as Record<string | symbol, unknown>)[prop]
         // Preserve prop getters - let child component's createPropsProxy unwrap lazily
+        // Note: For Symbol properties, we still wrap in getter if source is dynamic
         if (typeof src === 'function' && !isPropGetter(value)) {
           return __fictProp(() => {
             const latest = resolveSource(src)

package/src/reconcile.ts

@@ -21,6 +21,10 @@
  * @param a - The old array of nodes (currently in DOM)
  * @param b - The new array of nodes (target state)
  *
+ * **Note:** This function may mutate the input array `a` during the swap
+ * optimization (step 5a). If you need to preserve the original array,
+ * pass a shallow copy: `reconcileArrays(parent, [...oldNodes], newNodes)`.
+ *
  * @example
  * ```ts
  * const oldNodes = [node1, node2, node3]