@fictjs/runtime 0.0.2

package/src/node-ops.ts

@@ -0,0 +1,185 @@
+/**
+ * Low-level DOM node helpers shared across runtime modules.
+ * Keep this file dependency-free to avoid module cycles.
+ */
+
+/**
+ * Convert a value to a flat array of DOM nodes.
+ * Defensively handles proxies and non-DOM values.
+ */
+export function toNodeArray(node: Node | Node[] | unknown): Node[] {
+  try {
+    if (Array.isArray(node)) {
+      // Preserve original array reference when it's already a flat Node array
+      let allNodes = true
+      for (const item of node) {
+        let isItemNode = false
+        try {
+          isItemNode = item instanceof Node
+        } catch {
+          isItemNode = false
+        }
+        if (!isItemNode) {
+          allNodes = false
+          break
+        }
+      }
+      if (allNodes) {
+        return node as Node[]
+      }
+      const result: Node[] = []
+      for (const item of node) {
+        result.push(...toNodeArray(item))
+      }
+      return result
+    }
+    if (node === null || node === undefined || node === false) {
+      return []
+    }
+  } catch {
+    return []
+  }
+
+  let isNode = false
+  try {
+    isNode = node instanceof Node
+  } catch {
+    // If safe check fails, treat as primitive string
+    isNode = false
+  }
+
+  if (isNode) {
+    try {
+      if (node instanceof DocumentFragment) {
+        return Array.from(node.childNodes)
+      }
+    } catch {
+      // Ignore fragment check error
+    }
+    return [node as Node]
+  }
+
+  try {
+    // Duck-type BindingHandle-like values
+    if (typeof node === 'object' && node !== null && 'marker' in node) {
+      return toNodeArray((node as { marker: unknown }).marker)
+    }
+  } catch {
+    // Ignore property check error
+  }
+
+  // Primitive fallback
+  try {
+    return [document.createTextNode(String(node))]
+  } catch {
+    return [document.createTextNode('')]
+  }
+}
+
+/**
+ * Insert nodes before an anchor node, preserving order.
+ * Uses DocumentFragment for batch insertion when inserting multiple nodes.
+ */
+export function insertNodesBefore(
+  parent: ParentNode & Node,
+  nodes: Node[],
+  anchor: Node | null,
+): void {
+  if (nodes.length === 0) return
+
+  // Single node optimization - direct insertion
+  if (nodes.length === 1) {
+    const node = nodes[0]!
+    if (node === undefined || node === null) return
+    if (node.ownerDocument !== parent.ownerDocument && parent.ownerDocument) {
+      parent.ownerDocument.adoptNode(node)
+    }
+    try {
+      parent.insertBefore(node, anchor)
+    } catch (e: unknown) {
+      if (parent.ownerDocument) {
+        try {
+          const clone = parent.ownerDocument.importNode(node, true)
+          parent.insertBefore(clone, anchor)
+          return
+        } catch {
+          // Clone fallback failed
+        }
+      }
+      throw e
+    }
+    return
+  }
+
+  // Batch insertion using DocumentFragment for multiple nodes
+  const doc = parent.ownerDocument
+  if (doc) {
+    const frag = doc.createDocumentFragment()
+    for (let i = 0; i < nodes.length; i++) {
+      const node = nodes[i]!
+      if (node === undefined || node === null) continue
+      // Handle DocumentFragment - append children
+      if (node.nodeType === 11) {
+        const childrenArr = Array.from(node.childNodes)
+        for (let j = 0; j < childrenArr.length; j++) {
+          frag.appendChild(childrenArr[j]!)
+        }
+      } else {
+        if (node.ownerDocument !== doc) {
+          doc.adoptNode(node)
+        }
+        frag.appendChild(node)
+      }
+    }
+    parent.insertBefore(frag, anchor)
+    return
+  }
+
+  // Fallback for non-document contexts (rare)
+  const insertSingle = (nodeToInsert: Node, anchorNode: Node | null): Node => {
+    if (nodeToInsert.ownerDocument !== parent.ownerDocument && parent.ownerDocument) {
+      parent.ownerDocument.adoptNode(nodeToInsert)
+    }
+    try {
+      parent.insertBefore(nodeToInsert, anchorNode)
+      return nodeToInsert
+    } catch (e: unknown) {
+      if (parent.ownerDocument) {
+        try {
+          const clone = parent.ownerDocument.importNode(nodeToInsert, true)
+          parent.insertBefore(clone, anchorNode)
+          return clone
+        } catch {
+          // Clone fallback failed
+        }
+      }
+      throw e
+    }
+  }
+
+  for (let i = nodes.length - 1; i >= 0; i--) {
+    const node = nodes[i]!
+    if (node === undefined || node === null) continue
+
+    // Handle DocumentFragment - insert children in reverse order
+    const isFrag = node.nodeType === 11
+    if (isFrag) {
+      const childrenArr = Array.from(node.childNodes)
+      for (let j = childrenArr.length - 1; j >= 0; j--) {
+        const child = childrenArr[j]!
+        anchor = insertSingle(child, anchor)
+      }
+    } else {
+      anchor = insertSingle(node, anchor)
+    }
+  }
+}
+
+/**
+ * Remove an array of nodes from the DOM.
+ */
+export function removeNodes(nodes: Node[]): void {
+  for (const node of nodes) {
+    node.parentNode?.removeChild(node)
+  }
+}

package/src/props.ts

@@ -0,0 +1,212 @@
+import { createMemo } from './memo'
+
+const propGetters = new WeakSet<(...args: unknown[]) => unknown>()
+const rawToProxy = new WeakMap<object, object>()
+const proxyToRaw = new WeakMap<object, object>()
+
+/**
+ * @internal
+ * Marks a zero-arg getter so props proxy can lazily evaluate it.
+ * Users normally never call this directly; the compiler injects it.
+ */
+export function __fictProp<T>(getter: () => T): () => T {
+  if (typeof getter === 'function' && getter.length === 0) {
+    propGetters.add(getter)
+  }
+  return getter
+}
+
+function isPropGetter(value: unknown): value is () => unknown {
+  return typeof value === 'function' && propGetters.has(value as (...args: unknown[]) => unknown)
+}
+
+export function createPropsProxy<T extends Record<string, unknown>>(props: T): T {
+  if (!props || typeof props !== 'object') {
+    return props
+  }
+
+  if (proxyToRaw.has(props)) {
+    return props
+  }
+
+  const cached = rawToProxy.get(props)
+  if (cached) {
+    return cached as T
+  }
+
+  const proxy = new Proxy(props, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver)
+      if (isPropGetter(value)) {
+        return value()
+      }
+      return value
+    },
+    set(target, prop, value, receiver) {
+      return Reflect.set(target, prop, value, receiver)
+    },
+    has(target, prop) {
+      return prop in target
+    },
+    ownKeys(target) {
+      return Reflect.ownKeys(target)
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      return Object.getOwnPropertyDescriptor(target, prop)
+    },
+  })
+
+  rawToProxy.set(props, proxy)
+  proxyToRaw.set(proxy, props)
+
+  return proxy as T
+}
+
+export function unwrapProps<T extends Record<string, unknown>>(props: T): T {
+  if (!props || typeof props !== 'object') {
+    return props
+  }
+  return (proxyToRaw.get(props) as T | undefined) ?? props
+}
+
+/**
+ * Create a rest-like props object while preserving prop getters.
+ * Excludes the specified keys from the returned object.
+ */
+export function __fictPropsRest<T extends Record<string, unknown>>(
+  props: T,
+  exclude: (string | number | symbol)[],
+): Record<string, unknown> {
+  const raw = unwrapProps(props)
+  const out: Record<string, unknown> = {}
+  const excludeSet = new Set(exclude)
+
+  for (const key of Reflect.ownKeys(raw)) {
+    if (excludeSet.has(key)) continue
+    out[key as string] = (raw as Record<string | symbol, unknown>)[key]
+  }
+
+  // Wrap in props proxy so getters remain lazy when accessed via rest
+  return createPropsProxy(out)
+}
+
+/**
+ * Merge multiple props-like objects while preserving lazy getters.
+ * Later sources override earlier ones.
+ *
+ * Uses lazy lookup strategy - properties are only accessed when read,
+ * avoiding upfront iteration of all keys.
+ */
+type MergeSource<T extends Record<string, unknown>> = T | (() => T)
+
+export function mergeProps<T extends Record<string, unknown>>(
+  ...sources: (MergeSource<T> | null | undefined)[]
+): Record<string, unknown> {
+  // Filter out null/undefined sources upfront and store as concrete type
+  const validSources: MergeSource<T>[] = sources.filter(
+    (s): s is MergeSource<T> => s != null && (typeof s === 'object' || typeof s === 'function'),
+  )
+
+  if (validSources.length === 0) {
+    return {}
+  }
+
+  if (validSources.length === 1 && typeof validSources[0] === 'object') {
+    // Return source directly to preserve getter behavior (consistent with multi-source)
+    return validSources[0]!
+  }
+
+  const resolveSource = (src: MergeSource<T>): T | undefined => {
+    const value = typeof src === 'function' ? src() : src
+    if (!value || typeof value !== 'object') return undefined
+    return unwrapProps(value as T)
+  }
+
+  return new Proxy({} as Record<string, unknown>, {
+    get(_, prop) {
+      // Symbol properties (like Symbol.iterator) should return undefined
+      if (typeof prop === 'symbol') {
+        return undefined
+      }
+      // Search sources in reverse order (last wins)
+      for (let i = validSources.length - 1; i >= 0; i--) {
+        const src = validSources[i]!
+        const raw = resolveSource(src)
+        if (!raw || !(prop in raw)) continue
+
+        const value = (raw as Record<string | symbol, unknown>)[prop]
+        // Preserve prop getters - let child component's createPropsProxy unwrap lazily
+        if (typeof src === 'function' && !isPropGetter(value)) {
+          return __fictProp(() => {
+            const latest = resolveSource(src)
+            if (!latest || !(prop in latest)) return undefined
+            return (latest as Record<string | symbol, unknown>)[prop]
+          })
+        }
+        return value
+      }
+      return undefined
+    },
+
+    has(_, prop) {
+      for (const src of validSources) {
+        const raw = resolveSource(src)
+        if (raw && prop in raw) {
+          return true
+        }
+      }
+      return false
+    },
+
+    ownKeys() {
+      const keys = new Set<string | symbol>()
+      for (const src of validSources) {
+        const raw = resolveSource(src)
+        if (raw) {
+          for (const key of Reflect.ownKeys(raw)) {
+            keys.add(key)
+          }
+        }
+      }
+      return Array.from(keys)
+    },
+
+    getOwnPropertyDescriptor(_, prop) {
+      for (let i = validSources.length - 1; i >= 0; i--) {
+        const raw = resolveSource(validSources[i]!)
+        if (raw && prop in raw) {
+          return {
+            enumerable: true,
+            configurable: true,
+            get: () => {
+              const value = (raw as Record<string | symbol, unknown>)[prop]
+              // Preserve prop getters - let child component's createPropsProxy unwrap lazily
+              return value
+            },
+          }
+        }
+      }
+      return undefined
+    },
+  })
+}
+
+export type PropGetter<T> = (() => T) & { __fictProp: true }
+/**
+ * Memoize a prop getter to cache expensive computations.
+ * Use when prop expressions involve heavy calculations.
+ *
+ * @example
+ * ```tsx
+ * // Without useProp - recomputes on every access
+ * <Child data={expensiveComputation(list, filter)} />
+ *
+ * // With useProp - cached until dependencies change, auto-unwrapped by props proxy
+ * const memoizedData = useProp(() => expensiveComputation(list, filter))
+ * <Child data={memoizedData} />
+ * ```
+ */
+export function useProp<T>(getter: () => T): PropGetter<T> {
+  // Wrap in prop so component props proxy auto-unwraps when passed down.
+  return __fictProp(createMemo(getter)) as PropGetter<T>
+}

package/src/reconcile.ts

@@ -0,0 +1,151 @@
+/**
+ * Fict DOM Reconciliation
+ *
+ * Efficient array reconciliation algorithm based on udomdiff.
+ * https://github.com/WebReflection/udomdiff
+ *
+ * This algorithm uses a 5-step strategy:
+ * 1. Common prefix - skip matching nodes at start
+ * 2. Common suffix - skip matching nodes at end
+ * 3. Append - insert remaining new nodes
+ * 4. Remove - remove remaining old nodes
+ * 5. Swap/Map fallback - handle complex rearrangements
+ *
+ * Most real-world updates (95%+) use fast paths without building a Map.
+ */
+
+/**
+ * Reconcile two arrays of DOM nodes, efficiently updating the DOM.
+ *
+ * @param parentNode - The parent element containing the nodes
+ * @param a - The old array of nodes (currently in DOM)
+ * @param b - The new array of nodes (target state)
+ *
+ * @example
+ * ```ts
+ * const oldNodes = [node1, node2, node3]
+ * const newNodes = [node1, node4, node3]  // node2 replaced with node4
+ * reconcileArrays(parent, oldNodes, newNodes)
+ * ```
+ */
+export default function reconcileArrays(parentNode: ParentNode, a: Node[], b: Node[]): void {
+  const bLength = b.length
+  let aEnd = a.length
+  let bEnd = bLength
+  let aStart = 0
+  let bStart = 0
+  const after = aEnd > 0 ? a[aEnd - 1]!.nextSibling : null
+  let map: Map<Node, number> | null = null
+
+  while (aStart < aEnd || bStart < bEnd) {
+    // 1. Common prefix - nodes match at start
+    if (a[aStart] === b[bStart]) {
+      aStart++
+      bStart++
+      continue
+    }
+
+    // 2. Common suffix - nodes match at end
+    while (a[aEnd - 1] === b[bEnd - 1]) {
+      aEnd--
+      bEnd--
+    }
+
+    // 3. Append - old array exhausted, insert remaining new nodes
+    if (aEnd === aStart) {
+      const node: Node | null =
+        bEnd < bLength ? (bStart ? b[bStart - 1]!.nextSibling : (b[bEnd - bStart] ?? null)) : after
+
+      const count = bEnd - bStart
+      const doc = (parentNode as Node).ownerDocument
+      if (count > 1 && doc) {
+        const frag = doc.createDocumentFragment()
+        for (let i = bStart; i < bEnd; i++) {
+          frag.appendChild(b[i]!)
+        }
+        parentNode.insertBefore(frag, node)
+        bStart = bEnd
+      } else {
+        while (bStart < bEnd) {
+          parentNode.insertBefore(b[bStart++]!, node)
+        }
+      }
+    }
+    // 4. Remove - new array exhausted, remove remaining old nodes
+    else if (bEnd === bStart) {
+      while (aStart < aEnd) {
+        const nodeToRemove = a[aStart]!
+        if (!map || !map.has(nodeToRemove)) {
+          nodeToRemove.parentNode?.removeChild(nodeToRemove)
+        }
+        aStart++
+      }
+    }
+    // 5a. Swap backward - detect backward swap pattern
+    else if (a[aStart] === b[bEnd - 1] && b[bStart] === a[aEnd - 1]) {
+      const node = a[--aEnd]!.nextSibling
+      parentNode.insertBefore(b[bStart++]!, a[aStart++]!.nextSibling)
+      parentNode.insertBefore(b[--bEnd]!, node)
+      // Update reference in old array for potential future matches
+      a[aEnd] = b[bEnd]!
+    }
+    // 5b. Map fallback - use Map for complex rearrangements
+    else {
+      // Build map on first use (lazy initialization)
+      if (!map) {
+        map = new Map()
+        let i = bStart
+        while (i < bEnd) {
+          map.set(b[i]!, i++)
+        }
+      }
+
+      const index = map.get(a[aStart]!)
+
+      if (index != null) {
+        if (bStart < index && index < bEnd) {
+          // Check for longest increasing subsequence
+          let i = aStart
+          let sequence = 1
+          let t: number | undefined
+
+          while (++i < aEnd && i < bEnd) {
+            t = map.get(a[i]!)
+            if (t == null || t !== index + sequence) break
+            sequence++
+          }
+
+          // Use optimal strategy based on sequence length
+          if (sequence > index - bStart) {
+            // Sequence is long enough - insert nodes before current
+            const node = a[aStart]!
+            while (bStart < index) {
+              parentNode.insertBefore(b[bStart++]!, node)
+            }
+          } else {
+            // Short sequence - replace
+            parentNode.replaceChild(b[bStart++]!, a[aStart++]!)
+          }
+        } else {
+          aStart++
+        }
+      } else {
+        // Node not in new array - remove it
+        const nodeToRemove = a[aStart++]!
+        nodeToRemove.parentNode?.removeChild(nodeToRemove)
+      }
+    }
+  }
+}
+
+/**
+ * Simple reconciliation for keyed lists.
+ * Uses the same algorithm but works with keyed blocks.
+ *
+ * @param parentNode - The parent element
+ * @param oldNodes - Old nodes in DOM order
+ * @param newNodes - New nodes in target order
+ */
+export function reconcileNodes(parentNode: ParentNode, oldNodes: Node[], newNodes: Node[]): void {
+  reconcileArrays(parentNode, oldNodes, newNodes)
+}

package/src/ref.ts

@@ -0,0 +1,25 @@
+import type { RefObject } from './types'
+
+/**
+ * Create a ref object for DOM element references.
+ *
+ * @returns A ref object with a `current` property initialized to `null`
+ *
+ * @example
+ * ```tsx
+ * import { createRef } from 'fict'
+ *
+ * function Component() {
+ *   const inputRef = createRef<HTMLInputElement>()
+ *
+ *   $effect(() => {
+ *     inputRef.current?.focus()
+ *   })
+ *
+ *   return <input ref={inputRef} />
+ * }
+ * ```
+ */
+export function createRef<T extends HTMLElement = HTMLElement>(): RefObject<T> {
+  return { current: null }
+}

package/src/scheduler.ts

@@ -0,0 +1,12 @@
+import { batch as baseBatch, untrack as baseUntrack } from './signal'
+
+export function batch<T>(fn: () => T): T {
+  return baseBatch(fn)
+}
+
+export function untrack<T>(fn: () => T): T {
+  return baseUntrack(fn)
+}
+
+// Transition APIs for priority scheduling
+export { startTransition, useTransition, useDeferredValue } from './transition'