@fictjs/runtime 0.8.0 → 0.10.0

package/src/binding.ts

@@ -112,6 +112,16 @@ export interface BindingHandle {
   dispose: Cleanup
 }
 
+export interface ConditionalBindingOptions {
+  /**
+   * When true, track signal reads inside active branch render callbacks and
+   * re-run the branch callback on updates even if the top-level condition stays
+   * the same. This preserves reactivity for control-flow callbacks that cannot
+   * be lowered into fine-grained bindings.
+   */
+  trackBranchReads?: boolean
+}
+
 /** Managed child node with its dispose function */
 // ============================================================================
 // Utility Functions
@@ -1743,7 +1753,9 @@ export function createConditional(
   renderFalse?: () => FictNode,
   startOverride?: Comment,
   endOverride?: Comment,
+  options?: ConditionalBindingOptions,
 ): BindingHandle {
+  const trackBranchReads = options?.trackBranchReads === true
   const useProvided = !!(startOverride && endOverride)
   const startMarker = useProvided ? startOverride! : document.createComment('fict:cond:start')
   const endMarker = useProvided ? endOverride! : document.createComment('fict:cond:end')
@@ -1805,7 +1817,7 @@ export function createConditional(
           endMarker,
           parent.ownerDocument ?? document,
           () => {
-            const output = untrack(render)
+            const output = trackBranchReads ? render() : untrack(render)
             if (output == null || output === false) {
               return
             }
@@ -1837,10 +1849,102 @@ export function createConditional(
       return
     }
 
-    if (lastCondition === cond && currentNodes.length > 0) {
-      return
-    }
-    if (lastCondition === cond && lastCondition === false && renderFalse === undefined) {
+    if (!trackBranchReads) {
+      if (lastCondition === cond && currentNodes.length > 0) {
+        return
+      }
+      if (lastCondition === cond && lastCondition === false && renderFalse === undefined) {
+        return
+      }
+    } else if (lastCondition === cond) {
+      const render = cond ? renderTrue : renderFalse
+      if (!render) {
+        return
+      }
+
+      let patched = false
+      const scratchRoot = createRootContext(hostRoot)
+      const prevScratch = pushRoot(scratchRoot)
+      let handledPatchError = false
+      let scratchOutput: FictNode = null
+      try {
+        const output = render()
+        scratchOutput = output
+        if (output != null && output !== false) {
+          if (currentNodes.length === 1) {
+            patched = patchNode(currentNodes[0] ?? null, output)
+          }
+          if (!patched && Array.isArray(output)) {
+            patched = _patchFragmentChildren(currentNodes, output)
+          }
+          if (!patched && _isFragmentVNode(output)) {
+            patched = _patchFragmentChildren(currentNodes, output.props?.children)
+          }
+        }
+      } catch (err) {
+        if (handleSuspend(err as any, scratchRoot)) {
+          handledPatchError = true
+          return
+        }
+        if (handleError(err, { source: 'renderChild' }, scratchRoot)) {
+          handledPatchError = true
+          return
+        }
+        throw err
+      } finally {
+        popRoot(prevScratch)
+      }
+
+      if (handledPatchError) {
+        destroyRoot(scratchRoot)
+        return
+      }
+
+      if (patched) {
+        destroyRoot(scratchRoot)
+        return
+      }
+
+      lastCondition = cond
+
+      if (currentRoot) {
+        destroyRoot(currentRoot)
+        currentRoot = null
+      }
+      removeNodes(currentNodes)
+      currentNodes = []
+
+      const prev = pushRoot(scratchRoot)
+      let handledError = false
+      try {
+        if (scratchOutput == null || scratchOutput === false) {
+          return
+        }
+        const el = createElementFn(scratchOutput)
+        const nodes = toNodeArray(el)
+        insertNodesBefore(parent, nodes, endMarker)
+        currentNodes = nodes
+      } catch (err) {
+        if (handleSuspend(err as any, scratchRoot)) {
+          handledError = true
+          destroyRoot(scratchRoot)
+          return
+        }
+        if (handleError(err, { source: 'renderChild' }, scratchRoot)) {
+          handledError = true
+          destroyRoot(scratchRoot)
+          return
+        }
+        throw err
+      } finally {
+        popRoot(prev)
+        if (!handledError) {
+          flushOnMount(scratchRoot)
+          currentRoot = scratchRoot
+        } else {
+          currentRoot = null
+        }
+      }
       return
     }
     lastCondition = cond
@@ -1865,7 +1969,7 @@ export function createConditional(
       // tracked by createConditional's effect. This ensures that signals used
       // inside the render function (e.g., nested if conditions) don't cause
       // createConditional to re-run, which would purge child effect deps.
-      const output = untrack(render)
+      const output = trackBranchReads ? render() : untrack(render)
       if (output == null || output === false) {
         return
       }
@@ -2050,23 +2154,6 @@ export function createPortal(
 }
 
 function patchElement(el: Element, output: FictNode): boolean {
-  if (
-    output === null ||
-    output === undefined ||
-    output === false ||
-    typeof output === 'string' ||
-    typeof output === 'number'
-  ) {
-    el.textContent =
-      output === null || output === undefined || output === false ? '' : String(output)
-    return true
-  }
-
-  if (output instanceof Text) {
-    el.textContent = output.data
-    return true
-  }
-
   if (output && typeof output === 'object' && !(output instanceof Node)) {
     const vnode = output as { type?: unknown; props?: Record<string, unknown> }
     if (typeof vnode.type === 'string' && vnode.type.toLowerCase() === el.tagName.toLowerCase()) {
@@ -2131,19 +2218,6 @@ function patchElement(el: Element, output: FictNode): boolean {
     }
   }
 
-  if (output instanceof Node) {
-    if (output.nodeType === Node.ELEMENT_NODE) {
-      const nextEl = output as Element
-      if (nextEl.tagName.toLowerCase() === el.tagName.toLowerCase()) {
-        el.textContent = nextEl.textContent
-        return true
-      }
-    } else if (output.nodeType === Node.TEXT_NODE) {
-      el.textContent = (output as Text).data
-      return true
-    }
-  }
-
   return false
 }
 
@@ -2207,6 +2281,9 @@ function normalizeChildren(
   if (children === null || children === false) {
     return result
   }
+  if (_isFragmentVNode(children)) {
+    return normalizeChildren(children.props?.children, result)
+  }
   result.push(children)
   return result
 }

package/src/cycle-guard.ts

@@ -6,7 +6,7 @@ const isDev =
     : typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production'
 
 export interface CycleProtectionOptions {
-  /** Enable cycle protection guards (enabled by default in all modes) */
+  /** Enable cycle protection guards (enabled by default in dev mode) */
   enabled?: boolean
   maxFlushCyclesPerMicrotask?: number
   maxEffectRunsPerFlush?: number
@@ -35,8 +35,8 @@ let enterRootGuard: (root: object) => boolean = () => true
 let exitRootGuard: (root: object) => void = () => {}
 
 const defaultOptions = {
-  // Keep cycle guards on in production to avoid infinite flush loops.
-  enabled: true,
+  // DX-first in development, performance-first in production.
+  enabled: isDev,
   maxFlushCyclesPerMicrotask: 10_000,
   maxEffectRunsPerFlush: 20_000,
   windowSize: 5,

package/src/devtools.ts

@@ -5,18 +5,35 @@ export interface FictDevtoolsHook {
     options?: { name?: string; source?: string; ownerId?: number },
   ) => void
   updateSignal: (id: number, value: unknown) => void
+  disposeSignal?: (id: number) => void
   registerComputed: (
     id: number,
     value: unknown,
-    options?: { name?: string; source?: string; ownerId?: number; hasValue?: boolean },
+    options?: {
+      name?: string
+      source?: string
+      ownerId?: number
+      hasValue?: boolean
+      internal?: boolean
+    },
   ) => void
   updateComputed: (id: number, value: unknown) => void
+  disposeComputed?: (id: number) => void
   registerEffect: (id: number, options?: { ownerId?: number; source?: string }) => void
-  effectRun: (id: number) => void
+  effectRun: (id: number, duration?: number) => void
+  effectCleanup?: (id: number) => void
+  disposeEffect?: (id: number) => void
   /** Track a dependency relationship between subscriber and dependency */
   trackDependency?: (subscriberId: number, dependencyId: number) => void
   /** Remove a dependency relationship when unlinked */
   untrackDependency?: (subscriberId: number, dependencyId: number) => void
+  registerRoot?: (id: number, name?: string) => void
+  disposeRoot?: (id: number) => void
+  rootSuspend?: (id: number, suspended: boolean) => void
+  batchStart?: () => void
+  batchEnd?: () => void
+  flushStart?: () => void
+  flushEnd?: () => void
   cycleDetected?: (payload: { reason: string; detail?: Record<string, unknown> }) => void
 
   // Component lifecycle

package/src/dom.ts

@@ -64,6 +64,46 @@ const isDev =
 
 let nextComponentId = 1
 
+type DevtoolsAnnotatedElement = HTMLElement & {
+  __fict_component_id__?: number
+  __fict_component_name__?: string
+}
+
+function collectComponentMountElements(node: Node): HTMLElement[] {
+  if (node instanceof DocumentFragment) {
+    return Array.from(node.childNodes).filter(
+      (child): child is HTMLElement => child instanceof HTMLElement,
+    )
+  }
+
+  if (node instanceof HTMLElement) {
+    // Resumable hosts use display: contents; surface concrete child elements for inspection.
+    if (node.hasAttribute('data-fict-host')) {
+      const children = Array.from(node.children).filter(
+        (child): child is HTMLElement => child instanceof HTMLElement,
+      )
+      if (children.length > 0) return children
+    }
+    return [node]
+  }
+
+  return []
+}
+
+function annotateComponentElements(
+  elements: HTMLElement[],
+  componentId: number,
+  componentName: string,
+): void {
+  for (const element of elements) {
+    element.setAttribute('data-fict-component', componentName)
+    element.setAttribute('data-fict-component-id', String(componentId))
+    const annotated = element as DevtoolsAnnotatedElement
+    annotated.__fict_component_id__ = componentId
+    annotated.__fict_component_name__ = componentName
+  }
+}
+
 // ============================================================================
 // Main Render Function
 // ============================================================================
@@ -282,12 +322,13 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
     // Create a fresh hook context for this component instance.
     // This preserves slot state across re-renders driven by __fictRender.
     const hook = isDev ? getDevtoolsHook() : undefined
+    const componentName = vnode.type.name || 'Anonymous'
     const parentId = hook ? __fictGetCurrentComponentId() : undefined
     const componentId = hook ? nextComponentId++ : undefined
 
     // Register component
     if (hook?.registerComponent && componentId !== undefined) {
-      hook.registerComponent(componentId, vnode.type.name || 'Anonymous', parentId)
+      hook.registerComponent(componentId, componentName, parentId)
     }
 
     const ctx = __fictPushContext()
@@ -300,11 +341,16 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
 
     try {
       const rendered = vnode.type(props)
+      let mountElements: HTMLElement[] | undefined
+
+      if (hook && componentId !== undefined) {
+        hook.componentRender?.(componentId)
+      }
 
       // Register lifecycle hooks
       if (hook && componentId !== undefined) {
         onMount(() => {
-          hook.componentMount?.(componentId)
+          hook.componentMount?.(componentId, mountElements)
         })
         onCleanup(() => hook.componentUnmount?.(componentId))
       }
@@ -332,10 +378,18 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
         } else {
           host.appendChild(content)
         }
+        if (hook && componentId !== undefined) {
+          mountElements = collectComponentMountElements(host)
+          annotateComponentElements(mountElements, componentId, componentName)
+        }
         return host as DOMElement
       }
-
-      return createElementWithContext(rendered as FictNode, namespace)
+      const componentRoot = createElementWithContext(rendered as FictNode, namespace)
+      if (hook && componentId !== undefined) {
+        mountElements = collectComponentMountElements(componentRoot)
+        annotateComponentElements(mountElements, componentId, componentName)
+      }
+      return componentRoot
     } catch (err) {
       if (handleSuspend(err as any)) {
         return document.createComment('fict:suspend')

package/src/effect.ts

@@ -6,7 +6,7 @@ import {
   runCleanupList,
   withEffectCleanups,
 } from './lifecycle'
-import { effectWithCleanup } from './signal'
+import { effectWithCleanup, type EffectOptions } from './signal'
 import type { Cleanup } from './types'
 
 /**
@@ -15,7 +15,7 @@ import type { Cleanup } from './types'
  */
 export type Effect = () => void | Cleanup
 
-export function createEffect(fn: Effect): () => void {
+export function createEffect(fn: Effect, options?: EffectOptions): () => void {
   let cleanups: Cleanup[] = []
   const rootForError = getCurrentRoot()
 
@@ -47,7 +47,7 @@ export function createEffect(fn: Effect): () => void {
     cleanups = bucket
   }
 
-  const disposeEffect = effectWithCleanup(run, doCleanup, rootForError)
+  const disposeEffect = effectWithCleanup(run, doCleanup, rootForError, options)
   const teardown = () => {
     runCleanupList(cleanups)
     disposeEffect()
@@ -60,7 +60,7 @@ export function createEffect(fn: Effect): () => void {
 
 export const $effect = createEffect
 
-export function createRenderEffect(fn: Effect): () => void {
+export function createRenderEffect(fn: Effect, options?: EffectOptions): () => void {
   let cleanup: Cleanup | undefined
   const rootForError = getCurrentRoot()
 
@@ -91,7 +91,7 @@ export function createRenderEffect(fn: Effect): () => void {
     }
   }
 
-  const disposeEffect = effectWithCleanup(run, doCleanup, rootForError)
+  const disposeEffect = effectWithCleanup(run, doCleanup, rootForError, options)
   const teardown = () => {
     if (cleanup) {
       cleanup()

package/src/hooks.ts

@@ -4,6 +4,7 @@ import {
   createSignal,
   type SignalAccessor,
   type ComputedAccessor,
+  type EffectOptions,
   type MemoOptions,
   type SignalOptions,
 } from './signal'
@@ -118,17 +119,24 @@ export function __fictUseMemo<T>(
   return ctx.slots[index] as ComputedAccessor<T>
 }
 
-export function __fictUseEffect(ctx: HookContext, fn: () => void, slot?: number): void {
+export function __fictUseEffect(
+  ctx: HookContext,
+  fn: () => void,
+  optionsOrSlot?: number | EffectOptions,
+  slot?: number,
+): void {
+  const options = typeof optionsOrSlot === 'number' ? undefined : optionsOrSlot
+  const resolvedSlot = typeof optionsOrSlot === 'number' ? optionsOrSlot : slot
   // fix: When a slot number is provided, we trust the compiler has allocated this slot.
   // This allows effects inside conditional callbacks to work even outside render context.
   // The slot number proves this is a known, statically-allocated effect location.
-  if (slot !== undefined) {
-    if (ctx.slots[slot]) {
+  if (resolvedSlot !== undefined) {
+    if (ctx.slots[resolvedSlot]) {
       // Effect already exists, nothing to do
       return
     }
     // Create the effect even outside render context - the slot number proves validity
-    ctx.slots[slot] = createEffect(fn)
+    ctx.slots[resolvedSlot] = createEffect(fn, options)
     return
   }
 
@@ -136,7 +144,7 @@ export function __fictUseEffect(ctx: HookContext, fn: () => void, slot?: number)
   assertRenderContext(ctx, '__fictUseEffect')
   const index = ctx.cursor++
   if (!ctx.slots[index]) {
-    ctx.slots[index] = createEffect(fn)
+    ctx.slots[index] = createEffect(fn, options)
   }
 }
 

package/src/internal/list.ts

@@ -0,0 +1,7 @@
+/**
+ * Lightweight internal list helpers for compiler-generated keyed list paths.
+ *
+ * This subpath avoids pulling the broad `@fictjs/runtime/internal` barrel when
+ * code only needs list primitives.
+ */
+export { createKeyedList, toNodeArray, type KeyedListBinding } from '../list-helpers'

package/src/internal.ts

@@ -62,6 +62,7 @@ export {
   __fictQrl,
   __fictRegisterResume,
   __fictGetResume,
+  FICT_SSR_SNAPSHOT_SCHEMA_VERSION,
   serializeValue,
   deserializeValue,
 } from './resume'

package/src/lifecycle.ts

@@ -1,4 +1,5 @@
 import { enterRootGuard, exitRootGuard } from './cycle-guard'
+import { getDevtoolsHook } from './devtools'
 import type { Cleanup, ErrorInfo, SuspenseToken } from './types'
 
 const isDev =
@@ -29,9 +30,39 @@ let currentRoot: RootContext | undefined
 let currentEffectCleanups: Cleanup[] | undefined
 const globalErrorHandlers = new WeakMap<RootContext, ErrorHandler[]>()
 const globalSuspenseHandlers = new WeakMap<RootContext, SuspenseHandler[]>()
+const rootDevtoolsIds = new WeakMap<RootContext, number>()
+let nextRootDevtoolsId = 0
+
+function registerRootDevtools(root: RootContext): void {
+  if (!isDev) return
+  const hook = getDevtoolsHook()
+  if (!hook?.registerRoot) return
+  const id = ++nextRootDevtoolsId
+  rootDevtoolsIds.set(root, id)
+  hook.registerRoot(id)
+}
+
+function disposeRootDevtools(root: RootContext): void {
+  if (!isDev) return
+  const id = rootDevtoolsIds.get(root)
+  if (id === undefined) return
+  const hook = getDevtoolsHook()
+  hook?.disposeRoot?.(id)
+  rootDevtoolsIds.delete(root)
+}
+
+function setRootSuspendDevtools(root: RootContext, suspended: boolean): void {
+  if (!isDev) return
+  const id = rootDevtoolsIds.get(root)
+  if (id === undefined) return
+  const hook = getDevtoolsHook()
+  hook?.rootSuspend?.(id, suspended)
+}
 
 export function createRootContext(parent?: RootContext): RootContext {
-  return { parent, cleanups: [], destroyCallbacks: [], suspended: false }
+  const root = { parent, cleanups: [], destroyCallbacks: [], suspended: false }
+  registerRootDevtools(root)
+  return root
 }
 
 export function pushRoot(root: RootContext): RootContext | undefined {
@@ -122,6 +153,7 @@ export function destroyRoot(root: RootContext): void {
   if (globalSuspenseHandlers.has(root)) {
     globalSuspenseHandlers.delete(root)
   }
+  disposeRootDevtools(root)
 }
 
 export function createRoot<T>(
@@ -285,7 +317,10 @@ export function handleSuspend(
         const handled = handler(token)
         if (handled !== false) {
           // Only set suspended = true when a handler actually handles the token
-          if (originRoot) originRoot.suspended = true
+          if (originRoot) {
+            originRoot.suspended = true
+            setRootSuspendDevtools(originRoot, true)
+          }
           return true
         }
       }
@@ -304,7 +339,10 @@ export function handleSuspend(
       const handled = handler(token)
       if (handled !== false) {
         // Only set suspended = true when a handler actually handles the token
-        if (originRoot) originRoot.suspended = true
+        if (originRoot) {
+          originRoot.suspended = true
+          setRootSuspendDevtools(originRoot, true)
+        }
         return true
       }
     }

package/src/list-helpers.ts

@@ -30,7 +30,7 @@ export { insertNodesBefore, removeNodes, toNodeArray }
 const isDev =
   typeof __DEV__ !== 'undefined'
     ? __DEV__
-    : typeof process === 'undefined' || process.env?.NODE_ENV !== 'production'
+    : typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production'
 
 const isShadowRoot = (node: Node): node is ShadowRoot =>
   typeof ShadowRoot !== 'undefined' && node instanceof ShadowRoot