@fictjs/runtime 0.9.0 → 0.10.0

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/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/loader.ts

@@ -507,9 +507,15 @@ function prefetchQrl(qrl: string): void {
 function handleResumableEvent(event: Event): void {
   const promise = handleResumableEventAsync(event)
   pendingHandlers.add(promise)
-  promise.finally(() => {
-    pendingHandlers.delete(promise)
-  })
+  void promise
+    .catch(error => {
+      if (typeof console !== 'undefined' && typeof console.error === 'function') {
+        console.error('[fict/loader] Failed to handle resumable event.', error)
+      }
+    })
+    .finally(() => {
+      pendingHandlers.delete(promise)
+    })
 }
 
 async function handleResumableEventAsync(event: Event): Promise<void> {
@@ -535,7 +541,7 @@ async function handleResumableEventAsync(event: Event): Promise<void> {
         expectedVersion: FICT_SSR_SNAPSHOT_SCHEMA_VERSION,
         scopeId,
       })
-      return
+      continue
     }
     __fictEnsureScope(scopeId, host, snapshot)