@fictjs/runtime 0.0.8 → 0.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fictjs/runtime",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Fict reactive runtime",
   "publishConfig": {
     "access": "public",

package/src/binding.ts

@@ -36,7 +36,9 @@ import {
   registerRootCleanup,
   type RootContext,
 } from './lifecycle'
+import { createVersionedSignalAccessor } from './list-helpers'
 import { toNodeArray, removeNodes, insertNodesBefore } from './node-ops'
+import { batch } from './scheduler'
 import { computed, createSignal, untrack, type Signal } from './signal'
 import type { Cleanup, FictNode } from './types'
 
@@ -66,10 +68,8 @@ interface ManagedBlock<T = unknown> {
   root: RootContext
   value: Signal<T>
   index: Signal<number>
-  version: Signal<number>
   start: Comment
   end: Comment
-  valueProxy: T
   renderCurrent: () => FictNode
 }
 
@@ -165,7 +165,7 @@ export function unwrapPrimitive<T>(value: T): T {
   return value
 }
 
-function createValueProxy<T>(read: () => T): T {
+function _createValueProxy<T>(read: () => T): T {
   const getPrimitivePrototype = (value: unknown): Record<PropertyKey, unknown> | undefined => {
     switch (typeof value) {
       case 'string':
@@ -339,7 +339,7 @@ function formatTextValue(value: unknown): string {
 // ============================================================================
 
 /** Attribute setter function type */
-export type AttributeSetter = (el: HTMLElement, key: string, value: unknown) => void
+export type AttributeSetter = (el: Element, key: string, value: unknown) => void
 
 /**
  * Create a reactive attribute binding on an element.
@@ -354,7 +354,7 @@ export type AttributeSetter = (el: HTMLElement, key: string, value: unknown) =>
  * ```
  */
 export function createAttributeBinding(
-  el: HTMLElement,
+  el: Element,
   key: string,
   value: MaybeReactive<unknown>,
   setter: AttributeSetter,
@@ -373,7 +373,7 @@ export function createAttributeBinding(
 /**
  * Bind a reactive value to an element's attribute.
  */
-export function bindAttribute(el: HTMLElement, key: string, getValue: () => unknown): Cleanup {
+export function bindAttribute(el: Element, key: string, getValue: () => unknown): Cleanup {
   let prevValue: unknown = undefined
   return createRenderEffect(() => {
     const value = getValue()
@@ -393,7 +393,7 @@ export function bindAttribute(el: HTMLElement, key: string, getValue: () => unkn
 /**
  * Bind a reactive value to an element's property.
  */
-export function bindProperty(el: HTMLElement, key: string, getValue: () => unknown): Cleanup {
+export function bindProperty(el: Element, key: string, getValue: () => unknown): Cleanup {
   // Keep behavior aligned with the legacy createElement+applyProps path in `dom.ts`,
   // where certain keys must behave like DOM properties and nullish clears should
   // reset to sensible defaults (e.g. value -> '', checked -> false).
@@ -430,18 +430,19 @@ export function bindProperty(el: HTMLElement, key: string, getValue: () => unkno
  * Apply styles to an element, supporting reactive style objects/strings.
  */
 export function createStyleBinding(
-  el: HTMLElement,
+  el: Element,
   value: MaybeReactive<string | Record<string, string | number> | null | undefined>,
 ): void {
+  const target = el as Element & { style: CSSStyleDeclaration }
   if (isReactive(value)) {
     let prev: unknown
     createRenderEffect(() => {
       const next = (value as () => unknown)()
-      applyStyle(el, next, prev)
+      applyStyle(target, next, prev)
       prev = next
     })
   } else {
-    applyStyle(el, value, undefined)
+    applyStyle(target, value, undefined)
   }
 }
 
@@ -449,13 +450,14 @@ export function createStyleBinding(
  * Bind a reactive style value to an existing element.
  */
 export function bindStyle(
-  el: HTMLElement,
+  el: Element,
   getValue: () => string | Record<string, string | number> | null | undefined,
 ): Cleanup {
+  const target = el as Element & { style: CSSStyleDeclaration }
   let prev: unknown
   return createRenderEffect(() => {
     const next = getValue()
-    applyStyle(el, next, prev)
+    applyStyle(target, next, prev)
     prev = next
   })
 }
@@ -463,7 +465,11 @@ export function bindStyle(
 /**
  * Apply a style value to an element
  */
-function applyStyle(el: HTMLElement, value: unknown, prev: unknown): void {
+function applyStyle(
+  el: Element & { style: CSSStyleDeclaration },
+  value: unknown,
+  prev: unknown,
+): void {
   if (typeof value === 'string') {
     el.style.cssText = value
   } else if (value && typeof value === 'object') {
@@ -525,7 +531,7 @@ function isUnitlessStyleProperty(prop: string): boolean {
  * Apply class to an element, supporting reactive class values.
  */
 export function createClassBinding(
-  el: HTMLElement,
+  el: Element,
   value: MaybeReactive<string | Record<string, boolean> | null | undefined>,
 ): void {
   if (isReactive(value)) {
@@ -543,12 +549,22 @@ export function createClassBinding(
  * Bind a reactive class value to an existing element.
  */
 export function bindClass(
-  el: HTMLElement,
+  el: Element,
   getValue: () => string | Record<string, boolean> | null | undefined,
 ): Cleanup {
   let prev: Record<string, boolean> = {}
+  let prevString: string | undefined
   return createRenderEffect(() => {
     const next = getValue()
+    // P2-1: Short-circuit for string values to avoid DOM writes when unchanged
+    if (typeof next === 'string') {
+      if (next === prevString) return
+      prevString = next
+      el.className = next
+      prev = {}
+      return
+    }
+    prevString = undefined
     prev = applyClass(el, next, prev)
   })
 }
@@ -556,7 +572,7 @@ export function bindClass(
 /**
  * Toggle a class key (supports space-separated class names)
  */
-function toggleClassKey(node: HTMLElement, key: string, value: boolean): void {
+function toggleClassKey(node: Element, key: string, value: boolean): void {
   const classNames = key.trim().split(/\s+/)
   for (let i = 0, len = classNames.length; i < len; i++) {
     node.classList.toggle(classNames[i]!, value)
@@ -567,7 +583,7 @@ function toggleClassKey(node: HTMLElement, key: string, value: boolean): void {
  * Apply a class value to an element using classList.toggle for efficient updates.
  * Returns the new prev state for tracking.
  */
-function applyClass(el: HTMLElement, value: unknown, prev: unknown): Record<string, boolean> {
+function applyClass(el: Element, value: unknown, prev: unknown): Record<string, boolean> {
   const prevState = (prev && typeof prev === 'object' ? prev : {}) as Record<string, boolean>
 
   // Handle string value - full replacement
@@ -620,7 +636,7 @@ function applyClass(el: HTMLElement, value: unknown, prev: unknown): Record<stri
  * Exported classList function for direct use (compatible with dom-expressions)
  */
 export function classList(
-  node: HTMLElement,
+  node: Element,
   value: Record<string, boolean> | null | undefined,
   prev: Record<string, boolean> = {},
 ): Record<string, boolean> {
@@ -631,19 +647,6 @@ export function classList(
 // Child/Insert Binding (Dynamic Children)
 // ============================================================================
 
-/** Managed child node with its dispose function */
-interface ManagedBlock<T = unknown> {
-  nodes: Node[]
-  root: RootContext
-  value: Signal<T>
-  index: Signal<number>
-  version: Signal<number>
-  start: Comment
-  end: Comment
-  valueProxy: T
-  renderCurrent: () => FictNode
-}
-
 /**
  * Insert reactive content into a parent element.
  * This is a simpler API than createChildBinding for basic cases.
@@ -654,11 +657,12 @@ interface ManagedBlock<T = unknown> {
  * @param createElementFn - Optional function to create DOM elements (when marker is provided)
  */
 export function insert(
-  parent: HTMLElement | DocumentFragment,
+  parent: ParentNode & Node,
   getValue: () => FictNode,
   markerOrCreateElement?: Node | CreateElementFn,
   createElementFn?: CreateElementFn,
 ): Cleanup {
+  const hostRoot = getCurrentRoot()
   let marker: Node
   let ownsMarker = false
   let createFn: CreateElementFn | undefined = createElementFn
@@ -736,7 +740,7 @@ export function insert(
     }
     clearCurrentNodes()
 
-    const root = createRootContext()
+    const root = createRootContext(hostRoot)
     const prev = pushRoot(root)
     let nodes: Node[] = []
     try {
@@ -748,7 +752,15 @@ export function insert(
         if (value.every(v => v instanceof Node)) {
           newNode = value as Node[]
         } else {
-          newNode = createFn ? createFn(value) : document.createTextNode(String(value))
+          if (createFn) {
+            const mapped: Node[] = []
+            for (const item of value) {
+              mapped.push(...toNodeArray(createFn(item as any)))
+            }
+            newNode = mapped
+          } else {
+            newNode = document.createTextNode(String(value))
+          }
         }
       } else {
         newNode = createFn ? createFn(value) : document.createTextNode(String(value))
@@ -794,15 +806,16 @@ export function insert(
  * ```
  */
 export function createChildBinding(
-  parent: HTMLElement | DocumentFragment,
+  parent: ParentNode & Node,
   getValue: () => FictNode,
   createElementFn: CreateElementFn,
 ): BindingHandle {
   const marker = document.createComment('fict:child')
   parent.appendChild(marker)
+  const hostRoot = getCurrentRoot()
 
   const dispose = createRenderEffect(() => {
-    const root = createRootContext()
+    const root = createRootContext(hostRoot)
     const prev = pushRoot(root)
     let nodes: Node[] = []
     let handledError = false
@@ -857,10 +870,10 @@ export function createChildBinding(
 // Event Delegation System
 // ============================================================================
 
-// Extend HTMLElement/Document type to support event delegation
+// Extend Element/Document type to support event delegation
 declare global {
-  interface HTMLElement {
-    _$host?: HTMLElement
+  interface Element {
+    _$host?: Element
     [key: `$$${string}`]: EventListener | [EventListener, unknown] | undefined
     [key: `$$${string}Data`]: unknown
   }
@@ -912,11 +925,21 @@ export function clearDelegatedEvents(doc: Document = window.document): void {
  * Walks up the DOM tree to find and call handlers stored as $$eventName properties.
  */
 function globalEventHandler(e: Event): void {
-  let node = e.target as HTMLElement | null
+  const asNode = (value: unknown): Node | null =>
+    value && typeof (value as Node).nodeType === 'number' ? (value as Node) : null
+  const asElement = (value: unknown): Element | null => {
+    const n = asNode(value)
+    if (!n) return null
+    if (n.nodeType === 1) return n as Element
+    return (n as ChildNode).parentElement
+  }
+
+  let node = asElement(e.target)
   const key = `$$${e.type}` as const
   const dataKey = `${key}Data` as `$$${string}Data`
   const oriTarget = e.target
   const oriCurrentTarget = e.currentTarget
+  let lastHandled: Element | null = null
 
   // Retarget helper for shadow DOM and portals
   const retarget = (value: EventTarget) =>
@@ -945,12 +968,15 @@ function globalEventHandler(e: Event): void {
       const rawData = (node as any)[dataKey] as unknown
       const hasData = rawData !== undefined
       const resolvedNodeData = hasData ? resolveData(rawData) : undefined
-      if (typeof handler === 'function') {
-        callEventHandler(handler, e, node, hasData ? resolvedNodeData : undefined)
-      } else if (Array.isArray(handler)) {
-        const tupleData = resolveData(handler[1])
-        callEventHandler(handler[0], e, node, tupleData)
-      }
+      // P2-3: Wrap event handler calls in batch for synchronous flush & reduced microtasks
+      batch(() => {
+        if (typeof handler === 'function') {
+          callEventHandler(handler, e, node, hasData ? resolvedNodeData : undefined)
+        } else if (Array.isArray(handler)) {
+          const tupleData = resolveData(handler[1])
+          callEventHandler(handler[0], e, node, tupleData)
+        }
+      })
       if (e.cancelBubble) return false
     }
     // Handle shadow DOM host retargeting
@@ -958,8 +984,11 @@ function globalEventHandler(e: Event): void {
     if (
       shadowHost &&
       typeof shadowHost !== 'string' &&
-      !(shadowHost as HTMLElement)._$host &&
-      node.contains(e.target as Node)
+      !(shadowHost as Element)._$host &&
+      (() => {
+        const targetNode = asNode(e.target)
+        return targetNode ? node.contains(targetNode) : false
+      })()
     ) {
       retarget(shadowHost as EventTarget)
     }
@@ -969,9 +998,7 @@ function globalEventHandler(e: Event): void {
   // Walk up tree helper
   const walkUpTree = (): void => {
     while (handleNode() && node) {
-      node = (node._$host ||
-        node.parentNode ||
-        (node as unknown as ShadowRoot).host) as HTMLElement | null
+      node = asElement(node._$host || node.parentNode || (node as unknown as ShadowRoot).host)
     }
   }
 
@@ -988,8 +1015,11 @@ function globalEventHandler(e: Event): void {
     const path = e.composedPath()
     retarget(path[0] as EventTarget)
     for (let i = 0; i < path.length - 2; i++) {
-      node = path[i] as HTMLElement
+      const nextNode = asElement(path[i] as EventTarget)
+      if (!nextNode || nextNode === lastHandled) continue
+      node = nextNode
       if (!handleNode()) break
+      lastHandled = node
       // Handle portal event bubbling
       if (node._$host) {
         node = node._$host
@@ -1020,7 +1050,7 @@ function globalEventHandler(e: Event): void {
  * @param delegate - Whether to use delegation (auto-detected based on event name)
  */
 export function addEventListener(
-  node: HTMLElement,
+  node: Element,
   name: string,
   handler: EventListener | [EventListener, unknown] | null | undefined,
   delegate?: boolean,
@@ -1066,7 +1096,7 @@ export function addEventListener(
  * ```
  */
 export function bindEvent(
-  el: HTMLElement,
+  el: Element,
   eventName: string,
   handler: EventListenerOrEventListenerObject | null | undefined,
   options?: boolean | AddEventListenerOptions,
@@ -1153,7 +1183,7 @@ export function bindEvent(
  * bindRef(el, () => props.ref)
  * ```
  */
-export function bindRef(el: HTMLElement, ref: unknown): Cleanup {
+export function bindRef(el: Element, ref: unknown): Cleanup {
   if (ref == null) return () => {}
 
   // Handle reactive refs (getters)
@@ -1164,10 +1194,10 @@ export function bindRef(el: HTMLElement, ref: unknown): Cleanup {
 
     if (typeof refValue === 'function') {
       // Callback ref: call with element
-      ;(refValue as (el: HTMLElement) => void)(el)
+      ;(refValue as (el: Element) => void)(el)
     } else if (typeof refValue === 'object' && 'current' in refValue) {
       // Ref object: set current property
-      ;(refValue as { current: HTMLElement | null }).current = el
+      ;(refValue as { current: Element | null }).current = el
     }
   }
 
@@ -1187,7 +1217,7 @@ export function bindRef(el: HTMLElement, ref: unknown): Cleanup {
     const nullifyCleanup = () => {
       const currentRef = getRef()
       if (currentRef && typeof currentRef === 'object' && 'current' in currentRef) {
-        ;(currentRef as { current: HTMLElement | null }).current = null
+        ;(currentRef as { current: Element | null }).current = null
       }
     }
     registerRootCleanup(nullifyCleanup)
@@ -1202,7 +1232,7 @@ export function bindRef(el: HTMLElement, ref: unknown): Cleanup {
   const cleanup = () => {
     const refValue = getRef()
     if (refValue && typeof refValue === 'object' && 'current' in refValue) {
-      ;(refValue as { current: HTMLElement | null }).current = null
+      ;(refValue as { current: Element | null }).current = null
     }
   }
   registerRootCleanup(cleanup)
@@ -1231,7 +1261,7 @@ export function bindRef(el: HTMLElement, ref: unknown): Cleanup {
  * ```
  */
 export function spread(
-  node: HTMLElement,
+  node: Element,
   props: Record<string, unknown> = {},
   isSVG = false,
   skipChildren = false,
@@ -1248,7 +1278,7 @@ export function spread(
   // Handle ref
   createRenderEffect(() => {
     if (typeof props.ref === 'function') {
-      ;(props.ref as (el: HTMLElement) => void)(node)
+      ;(props.ref as (el: Element) => void)(node)
     }
   })
 
@@ -1272,7 +1302,7 @@ export function spread(
  * @param skipRef - Whether to skip ref handling
  */
 export function assign(
-  node: HTMLElement,
+  node: Element,
   props: Record<string, unknown>,
   isSVG = false,
   skipChildren = false,
@@ -1307,7 +1337,7 @@ export function assign(
  * Assign a single prop to a node.
  */
 function assignProp(
-  node: HTMLElement,
+  node: Element,
   prop: string,
   value: unknown,
   prev: unknown,
@@ -1317,7 +1347,7 @@ function assignProp(
 ): unknown {
   // Style handling
   if (prop === 'style') {
-    applyStyle(node, value, prev)
+    applyStyle(node as Element & { style: CSSStyleDeclaration }, value, prev)
     return value
   }
 
@@ -1332,7 +1362,7 @@ function assignProp(
   // Ref handling
   if (prop === 'ref') {
     if (!skipRef && typeof value === 'function') {
-      ;(value as (el: HTMLElement) => void)(node)
+      ;(value as (el: Element) => void)(node)
     }
     return value
   }
@@ -1472,6 +1502,7 @@ export function createConditional(
   const endMarker = document.createComment('fict:cond:end')
   const fragment = document.createDocumentFragment()
   fragment.append(startMarker, endMarker)
+  const hostRoot = getCurrentRoot()
 
   let currentNodes: Node[] = []
   let currentRoot: RootContext | null = null
@@ -1513,7 +1544,7 @@ export function createConditional(
       return
     }
 
-    const root = createRootContext()
+    const root = createRootContext(hostRoot)
     const prev = pushRoot(root)
     let handledError = false
     try {
@@ -1583,10 +1614,11 @@ export type KeyFn<T> = (item: T, index: number) => string | number
 
 /**
  * Create a reactive list rendering binding with optional keying.
+ * The render callback receives signal accessors for the item and index.
  */
 export function createList<T>(
   items: () => T[],
-  renderItem: (item: T, index: number) => FictNode,
+  renderItem: (item: Signal<T>, index: Signal<number>) => FictNode,
   createElementFn: CreateElementFn,
   getKey?: KeyFn<T>,
 ): BindingHandle {
@@ -1594,6 +1626,7 @@ export function createList<T>(
   const endMarker = document.createComment('fict:list:end')
   const fragment = document.createDocumentFragment()
   fragment.append(startMarker, endMarker)
+  const hostRoot = getCurrentRoot()
 
   const nodeMap = new Map<string | number, ManagedBlock<T>>()
   let pendingItems: T[] | null = null
@@ -1621,21 +1654,17 @@ export function createList<T>(
         if (!getKey && previousValue !== item) {
           destroyRoot(existing.root)
           removeBlockNodes(existing)
-          block = mountBlock(item, i, renderItem, parent, endMarker, createElementFn)
+          block = mountBlock(item, i, renderItem, parent, endMarker, createElementFn, hostRoot)
         } else {
           const previousIndex = existing.index()
           existing.value(item)
           existing.index(i)
 
-          if (previousValue === item) {
-            bumpBlockVersion(existing)
-          }
-
           const needsRerender = getKey ? true : previousValue !== item || previousIndex !== i
           block = needsRerender ? rerenderBlock(existing, createElementFn) : existing
         }
       } else {
-        block = mountBlock(item, i, renderItem, parent, endMarker, createElementFn)
+        block = mountBlock(item, i, renderItem, parent, endMarker, createElementFn, hostRoot)
       }
 
       newNodeMap.set(key, block)
@@ -1699,7 +1728,11 @@ export function createList<T>(
  * createShow(container, () => $visible())
  * ```
  */
-export function createShow(el: HTMLElement, condition: () => boolean, displayValue?: string): void {
+export function createShow(
+  el: Element & { style: CSSStyleDeclaration },
+  condition: () => boolean,
+  displayValue?: string,
+): void {
   const originalDisplay = displayValue ?? el.style.display
   createRenderEffect(() => {
     el.style.display = condition() ? originalDisplay : 'none'
@@ -1723,7 +1756,7 @@ export function createShow(el: HTMLElement, condition: () => boolean, displayVal
  * ```
  */
 export function createPortal(
-  container: HTMLElement,
+  container: ParentNode & Node,
   render: () => FictNode,
   createElementFn: CreateElementFn,
 ): BindingHandle {
@@ -1749,7 +1782,7 @@ export function createPortal(
     }
 
     // Create new content
-    const root = createRootContext()
+    const root = createRootContext(parentRoot)
     const prev = pushRoot(root)
     let handledError = false
     try {
@@ -1820,22 +1853,18 @@ export function createPortal(
 function mountBlock<T>(
   initialValue: T,
   initialIndex: number,
-  renderItem: (item: T, index: number) => FictNode,
+  renderItem: (item: Signal<T>, index: Signal<number>) => FictNode,
   parent: ParentNode & Node,
   anchor: Node,
   createElementFn: CreateElementFn,
+  hostRoot?: RootContext | undefined,
 ): ManagedBlock<T> {
   const start = document.createComment('fict:block:start')
   const end = document.createComment('fict:block:end')
-  const valueSig = createSignal<T>(initialValue)
+  const valueSig = createVersionedSignalAccessor<T>(initialValue)
   const indexSig = createSignal<number>(initialIndex)
-  const versionSig = createSignal(0)
-  const valueProxy = createValueProxy(() => {
-    versionSig()
-    return valueSig()
-  }) as T
-  const renderCurrent = () => renderItem(valueProxy, indexSig())
-  const root = createRootContext()
+  const renderCurrent = () => renderItem(valueSig, indexSig)
+  const root = createRootContext(hostRoot)
   const prev = pushRoot(root)
   const nodes: Node[] = [start]
   let handledError = false
@@ -1873,10 +1902,8 @@ function mountBlock<T>(
     root,
     value: valueSig,
     index: indexSig,
-    version: versionSig,
     start,
     end,
-    valueProxy,
     renderCurrent,
   }
 }
@@ -1981,7 +2008,7 @@ function patchElement(el: Element, output: FictNode): boolean {
           if (key === 'class' || key === 'className') {
             el.setAttribute('class', value === false || value === null ? '' : String(value))
           } else if (key === 'style' && typeof value === 'string') {
-            ;(el as HTMLElement).style.cssText = value
+            ;(el as Element & { style: CSSStyleDeclaration }).style.cssText = value
           } else if (value === false || value === null || value === undefined) {
             el.removeAttribute(key)
           } else if (value === true) {
@@ -2138,8 +2165,4 @@ function removeBlockNodes<T>(block: ManagedBlock<T>): void {
   }
 }
 
-function bumpBlockVersion<T>(block: ManagedBlock<T>): void {
-  block.version(block.version() + 1)
-}
-
 // DOM utility functions are imported from './node-ops' to avoid duplication