@fictjs/runtime 0.0.9 → 0.0.11

package/package.json

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

package/src/binding.ts

@@ -36,9 +36,10 @@ 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 { createVersionedSignalAccessor } from './list-helpers'
 import type { Cleanup, FictNode } from './types'
 
 // ============================================================================
@@ -552,8 +553,18 @@ export function bindClass(
   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)
   })
 }
@@ -914,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 Element | 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) =>
@@ -947,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
@@ -961,7 +985,10 @@ function globalEventHandler(e: Event): void {
       shadowHost &&
       typeof shadowHost !== 'string' &&
       !(shadowHost as Element)._$host &&
-      node.contains(e.target as Node)
+      (() => {
+        const targetNode = asNode(e.target)
+        return targetNode ? node.contains(targetNode) : false
+      })()
     ) {
       retarget(shadowHost as EventTarget)
     }
@@ -971,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 Element | null
+      node = asElement(node._$host || node.parentNode || (node as unknown as ShadowRoot).host)
     }
   }
 
@@ -990,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 Element
+      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

package/src/dom.ts

@@ -143,11 +143,21 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
   if (typeof node === 'object' && node !== null && !(node instanceof Node)) {
     // Handle BindingHandle (createList, createConditional, etc)
     if ('marker' in node) {
-      const handle = node as { marker: unknown; dispose?: () => void }
+      const handle = node as { marker: unknown; dispose?: () => void; flush?: () => void }
       // Register dispose cleanup if available
       if (typeof handle.dispose === 'function') {
         registerRootCleanup(handle.dispose)
       }
+      if (typeof handle.flush === 'function') {
+        const runFlush = () => handle.flush && handle.flush()
+        if (typeof queueMicrotask === 'function') {
+          queueMicrotask(runFlush)
+        } else {
+          Promise.resolve()
+            .then(runFlush)
+            .catch(() => undefined)
+        }
+      }
       return createElement(handle.marker as FictNode)
     }
 
@@ -210,20 +220,20 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
           })
 
     const props = createPropsProxy(baseProps)
+    // Create a fresh hook context for this component instance.
+    // This preserves slot state across re-renders driven by __fictRender.
+    __fictPushContext()
     try {
-      // Create a fresh hook context for this component instance.
-      // This preserves slot state across re-renders driven by __fictRender.
-      __fictPushContext()
       const rendered = vnode.type(props)
-      __fictPopContext()
       return createElementWithContext(rendered as FictNode, namespace)
     } catch (err) {
-      __fictPopContext()
       if (handleSuspend(err as any)) {
         return document.createComment('fict:suspend')
       }
       handleError(err, { source: 'render', componentName: vnode.type.name })
       throw err
+    } finally {
+      __fictPopContext()
     }
   }
 

package/src/effect.ts

@@ -5,7 +5,7 @@ import {
   runCleanupList,
   withEffectCleanups,
 } from './lifecycle'
-import { effect } from './signal'
+import { effectWithCleanup } from './signal'
 import type { Cleanup } from './types'
 
 export type Effect = () => void | Cleanup
@@ -14,8 +14,14 @@ export function createEffect(fn: Effect): () => void {
   let cleanups: Cleanup[] = []
   const rootForError = getCurrentRoot()
 
-  const run = () => {
+  // Cleanup runner - called by runEffect BEFORE signal values are committed
+  const doCleanup = () => {
     runCleanupList(cleanups)
+    cleanups = []
+  }
+
+  const run = () => {
+    // Note: cleanups are now run by signal.ts runEffect before this function is called
     const bucket: Cleanup[] = []
     withEffectCleanups(bucket, () => {
       try {
@@ -33,7 +39,7 @@ export function createEffect(fn: Effect): () => void {
     cleanups = bucket
   }
 
-  const disposeEffect = effect(run)
+  const disposeEffect = effectWithCleanup(run, doCleanup)
   const teardown = () => {
     runCleanupList(cleanups)
     disposeEffect()
@@ -50,25 +56,31 @@ export function createRenderEffect(fn: Effect): () => void {
   let cleanup: Cleanup | undefined
   const rootForError = getCurrentRoot()
 
-  const run = () => {
+  // Cleanup runner - called by runEffect BEFORE signal values are committed
+  const doCleanup = () => {
     if (cleanup) {
       cleanup()
       cleanup = undefined
     }
+  }
+
+  const run = () => {
+    // Note: cleanups are now run by signal.ts runEffect before this function is called
     try {
       const maybeCleanup = fn()
       if (typeof maybeCleanup === 'function') {
         cleanup = maybeCleanup
       }
     } catch (err) {
-      if (handleError(err, { source: 'effect' }, rootForError)) {
+      const handled = handleError(err, { source: 'effect' }, rootForError)
+      if (handled) {
         return
       }
       throw err
     }
   }
 
-  const disposeEffect = effect(run)
+  const disposeEffect = effectWithCleanup(run, doCleanup)
   const teardown = () => {
     if (cleanup) {
       cleanup()

package/src/hooks.ts

@@ -5,18 +5,26 @@ import { createSignal, type SignalAccessor, type ComputedAccessor } from './sign
 interface HookContext {
   slots: unknown[]
   cursor: number
+  rendering?: boolean
 }
 
 const ctxStack: HookContext[] = []
 
+function assertRenderContext(ctx: HookContext, hookName: string): void {
+  if (!ctx.rendering) {
+    throw new Error(`${hookName} can only be used during render execution`)
+  }
+}
+
 export function __fictUseContext(): HookContext {
   if (ctxStack.length === 0) {
-    const ctx: HookContext = { slots: [], cursor: 0 }
+    const ctx: HookContext = { slots: [], cursor: 0, rendering: true }
     ctxStack.push(ctx)
     return ctx
   }
   const ctx = ctxStack[ctxStack.length - 1]!
   ctx.cursor = 0
+  ctx.rendering = true
   return ctx
 }
 
@@ -35,6 +43,7 @@ export function __fictResetContext(): void {
 }
 
 export function __fictUseSignal<T>(ctx: HookContext, initial: T, slot?: number): SignalAccessor<T> {
+  assertRenderContext(ctx, '__fictUseSignal')
   const index = slot ?? ctx.cursor++
   if (!ctx.slots[index]) {
     ctx.slots[index] = createSignal(initial)
@@ -47,6 +56,7 @@ export function __fictUseMemo<T>(
   fn: () => T,
   slot?: number,
 ): ComputedAccessor<T> {
+  assertRenderContext(ctx, '__fictUseMemo')
   const index = slot ?? ctx.cursor++
   if (!ctx.slots[index]) {
     ctx.slots[index] = createMemo(fn)
@@ -55,6 +65,7 @@ export function __fictUseMemo<T>(
 }
 
 export function __fictUseEffect(ctx: HookContext, fn: () => void, slot?: number): void {
+  assertRenderContext(ctx, '__fictUseEffect')
   const index = slot ?? ctx.cursor++
   if (!ctx.slots[index]) {
     ctx.slots[index] = createEffect(fn)
@@ -64,9 +75,11 @@ export function __fictUseEffect(ctx: HookContext, fn: () => void, slot?: number)
 export function __fictRender<T>(ctx: HookContext, fn: () => T): T {
   ctxStack.push(ctx)
   ctx.cursor = 0
+  ctx.rendering = true
   try {
     return fn()
   } finally {
+    ctx.rendering = false
     ctxStack.pop()
   }
 }

package/src/list-helpers.ts

@@ -19,7 +19,7 @@ import {
 import { insertNodesBefore, removeNodes, toNodeArray } from './node-ops'
 import reconcileArrays from './reconcile'
 import { batch } from './scheduler'
-import { createSignal, setActiveSub, type Signal } from './signal'
+import { createSignal, flush, setActiveSub, type Signal } from './signal'
 import type { FictNode } from './types'
 
 // Re-export shared DOM helpers for compiler-generated code
@@ -339,7 +339,6 @@ export function createKeyedBlock<T>(
   } finally {
     setActiveSub(prevSub)
     popRoot(prevRoot)
-    flushOnMount(root)
   }
 
   return {
@@ -414,16 +413,31 @@ function createFineGrainedKeyedList<T>(
   const hostRoot = getCurrentRoot()
   const fragment = document.createDocumentFragment()
   fragment.append(container.startMarker, container.endMarker)
-  let pendingItems: T[] | null = null
   let disposed = false
+  let effectDispose: (() => void) | undefined
+  let connectObserver: MutationObserver | null = null
+  let effectStarted = false
+  let startScheduled = false
+
+  const getConnectedParent = (): (ParentNode & Node) | null => {
+    const endParent = container.endMarker.parentNode
+    const startParent = container.startMarker.parentNode
+    if (
+      endParent &&
+      startParent &&
+      endParent === startParent &&
+      (endParent as Node).nodeType !== 11
+    ) {
+      return endParent as ParentNode & Node
+    }
+    return null
+  }
 
   const performDiff = () => {
     if (disposed) return
-
+    const parent = getConnectedParent()
+    if (!parent) return
     batch(() => {
-      const newItems = pendingItems || getItems()
-      pendingItems = null
-
       const oldBlocks = container.blocks
       const newBlocks = container.nextBlocks
       const prevOrderedBlocks = container.orderedBlocks
@@ -432,27 +446,20 @@ function createFineGrainedKeyedList<T>(
       newBlocks.clear()
       nextOrderedBlocks.length = 0
       orderedIndexByKey.clear()
-
-      const endParent = container.endMarker.parentNode
-      const startParent = container.startMarker.parentNode
-      const parent =
-        endParent && startParent && endParent === startParent && (endParent as Node).isConnected
-          ? (endParent as ParentNode & Node)
-          : null
-
-      // If markers aren't mounted yet, store items and retry in microtask
-      if (!parent) {
-        pendingItems = newItems
-        queueMicrotask(performDiff)
-        return
-      }
+      const createdBlocks: KeyedBlock<T>[] = []
+      const newItems = getItems()
 
       if (newItems.length === 0) {
         if (oldBlocks.size > 0) {
+          // Destroy all block roots first
           for (const block of oldBlocks.values()) {
             destroyRoot(block.root)
-            removeNodes(block.nodes)
           }
+          // Use Range.deleteContents for efficient bulk DOM removal
+          const range = document.createRange()
+          range.setStartAfter(container.startMarker)
+          range.setEndBefore(container.endMarker)
+          range.deleteContents()
         }
         oldBlocks.clear()
         newBlocks.clear()
@@ -472,8 +479,9 @@ function createFineGrainedKeyedList<T>(
       // Phase 1: Build new blocks map (reuse or create)
       newItems.forEach((item, index) => {
         const key = keyFn(item, index)
-        const existed = oldBlocks.has(key)
+        // Micro-optimization: single Map.get instead of has+get
         let block = oldBlocks.get(key)
+        const existed = block !== undefined
 
         if (block) {
           if (block.rawItem !== item) {
@@ -486,45 +494,30 @@ function createFineGrainedKeyedList<T>(
           }
         }
 
-        // If newBlocks already has this key (duplicate key case), clean up the previous block
-        const existingBlock = newBlocks.get(key)
-        if (existingBlock && existingBlock !== block) {
-          destroyRoot(existingBlock.root)
-          removeNodes(existingBlock.nodes)
-        }
-
         if (block) {
+          // Reusing existing block from oldBlocks
           newBlocks.set(key, block)
           oldBlocks.delete(key)
         } else {
+          // If newBlocks already has this key (duplicate key case), clean up the previous block
           const existingBlock = newBlocks.get(key)
           if (existingBlock) {
             destroyRoot(existingBlock.root)
             removeNodes(existingBlock.nodes)
           }
-
           // Create new block
           block = createKeyedBlock(key, item, index, renderItem, needsIndex, hostRoot)
+          createdBlocks.push(block)
         }
 
-        const resolvedBlock = block!
+        const resolvedBlock = block
 
         newBlocks.set(key, resolvedBlock)
 
+        // Micro-optimization: single Map.get instead of checking position multiple times
         const position = orderedIndexByKey.get(key)
         if (position !== undefined) {
           appendCandidate = false
-        }
-        if (appendCandidate) {
-          if (index < prevCount) {
-            if (!prevOrderedBlocks[index] || prevOrderedBlocks[index]!.key !== key) {
-              appendCandidate = false
-            }
-          } else if (existed) {
-            appendCandidate = false
-          }
-        }
-        if (position !== undefined) {
           const prior = nextOrderedBlocks[position]
           if (prior && prior !== resolvedBlock) {
             destroyRoot(prior.root)
@@ -532,6 +525,15 @@ function createFineGrainedKeyedList<T>(
           }
           nextOrderedBlocks[position] = resolvedBlock
         } else {
+          if (appendCandidate) {
+            if (index < prevCount) {
+              if (!prevOrderedBlocks[index] || prevOrderedBlocks[index]!.key !== key) {
+                appendCandidate = false
+              }
+            } else if (existed) {
+              appendCandidate = false
+            }
+          }
           orderedIndexByKey.set(key, nextOrderedBlocks.length)
           nextOrderedBlocks.push(resolvedBlock)
         }
@@ -568,6 +570,11 @@ function createFineGrainedKeyedList<T>(
         container.nextBlocks = oldBlocks
         container.orderedBlocks = nextOrderedBlocks
         container.nextOrderedBlocks = prevOrderedBlocks
+        for (const block of createdBlocks) {
+          if (newBlocks.get(block.key) === block) {
+            flushOnMount(block.root)
+          }
+        }
         return
       }
 
@@ -608,24 +615,95 @@ function createFineGrainedKeyedList<T>(
       container.nextBlocks = oldBlocks
       container.orderedBlocks = nextOrderedBlocks
       container.nextOrderedBlocks = prevOrderedBlocks
+      for (const block of createdBlocks) {
+        if (newBlocks.get(block.key) === block) {
+          flushOnMount(block.root)
+        }
+      }
     })
   }
 
-  const effectDispose = createRenderEffect(performDiff)
+  const disconnectObserver = () => {
+    connectObserver?.disconnect()
+    connectObserver = null
+  }
+
+  const ensureEffectStarted = (): boolean => {
+    if (disposed || effectStarted) return effectStarted
+    const parent = getConnectedParent()
+    if (!parent) return false
+    const start = () => {
+      effectDispose = createRenderEffect(performDiff)
+      effectStarted = true
+    }
+    if (hostRoot) {
+      const prev = pushRoot(hostRoot)
+      try {
+        start()
+      } finally {
+        popRoot(prev)
+      }
+    } else {
+      start()
+    }
+    return true
+  }
+
+  const waitForConnection = () => {
+    if (connectObserver || typeof MutationObserver === 'undefined') return
+    connectObserver = new MutationObserver(() => {
+      if (disposed) return
+      if (getConnectedParent()) {
+        disconnectObserver()
+        if (ensureEffectStarted()) {
+          flush()
+        }
+      }
+    })
+    connectObserver.observe(document, { childList: true, subtree: true })
+  }
+
+  const scheduleStart = () => {
+    if (startScheduled || disposed || effectStarted) return
+    startScheduled = true
+    const run = () => {
+      startScheduled = false
+      if (!ensureEffectStarted()) {
+        waitForConnection()
+      }
+    }
+    if (typeof queueMicrotask === 'function') {
+      queueMicrotask(run)
+    } else {
+      Promise.resolve()
+        .then(run)
+        .catch(() => undefined)
+    }
+  }
+
+  scheduleStart()
 
   return {
-    marker: fragment,
+    get marker() {
+      scheduleStart()
+      return fragment
+    },
     startMarker: container.startMarker,
     endMarker: container.endMarker,
     // Flush pending items - call after markers are inserted into DOM
     flush: () => {
-      if (pendingItems !== null) {
-        performDiff()
+      if (disposed) return
+      scheduleStart()
+      if (ensureEffectStarted()) {
+        flush()
+      } else {
+        waitForConnection()
       }
     },
     dispose: () => {
       disposed = true
       effectDispose?.()
+      disconnectObserver()
       container.dispose()
     },
   }