@fictjs/runtime 0.9.0 → 0.11.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
 // ============================================================================
@@ -83,6 +123,7 @@ let nextComponentId = 1
  */
 export function render(view: () => FictNode, container: HTMLElement): () => void {
   const root = createRootContext()
+  root.ownerDocument = container.ownerDocument ?? document
   const prev = pushRoot(root)
   let dom: DOMElement = undefined as unknown as DOMElement
   try {
@@ -126,6 +167,7 @@ export function render(view: () => FictNode, container: HTMLElement): () => void
  */
 export function hydrateComponent(view: () => FictNode, container: HTMLElement): () => void {
   const root = createRootContext()
+  root.ownerDocument = container.ownerDocument ?? document
   const prev = pushRoot(root)
 
   // Enable hydration flags for bindings that check __fictIsHydrating()
@@ -169,7 +211,7 @@ export function hydrateComponent(view: () => FictNode, container: HTMLElement):
  * - Reactive values (functions returning any of the above)
  */
 export function createElement(node: FictNode): DOMElement {
-  return createElementWithContext(node, null)
+  return createElementWithContext(node, null, resolveOwnerDocument())
 }
 
 function resolveNamespace(tagName: string, namespace: NamespaceContext): NamespaceContext {
@@ -181,7 +223,15 @@ function resolveNamespace(tagName: string, namespace: NamespaceContext): Namespa
   return null
 }
 
-function createElementWithContext(node: FictNode, namespace: NamespaceContext): DOMElement {
+function resolveOwnerDocument(ownerDocument?: Document): Document {
+  return ownerDocument ?? getCurrentRoot()?.ownerDocument ?? document
+}
+
+function createElementWithContext(
+  node: FictNode,
+  namespace: NamespaceContext,
+  ownerDocument: Document,
+): DOMElement {
   // Already a DOM node - pass through
   if (node instanceof Node) {
     return node
@@ -189,22 +239,22 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
 
   // Null/undefined/false - empty placeholder
   if (node === null || node === undefined || node === false) {
-    return document.createTextNode('')
+    return ownerDocument.createTextNode('')
   }
 
   // Reactive getter function - resolve to actual node
   if (isReactive(node)) {
     const resolved = (node as () => FictNode)()
     if (resolved === node) {
-      return document.createTextNode('')
+      return ownerDocument.createTextNode('')
     }
-    return createElementWithContext(resolved, namespace)
+    return createElementWithContext(resolved, namespace, ownerDocument)
   }
 
   // Non-reactive function values are not valid DOM nodes.
   // Keep callback values inert instead of stringifying function source.
   if (typeof node === 'function') {
-    return document.createTextNode('')
+    return ownerDocument.createTextNode('')
   }
 
   if (typeof node === 'object' && node !== null && !(node instanceof Node)) {
@@ -225,26 +275,26 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
             .catch(() => undefined)
         }
       }
-      return createElement(handle.marker as FictNode)
+      return createElementWithContext(handle.marker as FictNode, namespace, ownerDocument)
     }
   }
 
   // Array - create fragment
   if (Array.isArray(node)) {
-    const frag = document.createDocumentFragment()
+    const frag = ownerDocument.createDocumentFragment()
     for (const child of node) {
-      appendChildNode(frag, child, namespace)
+      appendChildNode(frag, child, namespace, ownerDocument)
     }
     return frag
   }
 
   // Primitive values - text node
   if (typeof node === 'string' || typeof node === 'number') {
-    return document.createTextNode(String(node))
+    return ownerDocument.createTextNode(String(node))
   }
 
   if (typeof node === 'boolean') {
-    return document.createTextNode('')
+    return ownerDocument.createTextNode('')
   }
 
   // VNode
@@ -282,12 +332,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,22 +351,27 @@ 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))
       }
       if (__fictIsResumable() && !__fictIsHydrating()) {
-        const content = createElementWithContext(rendered as FictNode, namespace)
+        const content = createElementWithContext(rendered as FictNode, namespace, ownerDocument)
         const host =
           namespace === 'svg'
-            ? document.createElementNS(SVG_NS, 'fict-host')
+            ? ownerDocument.createElementNS(SVG_NS, 'fict-host')
             : namespace === 'mathml'
-              ? document.createElementNS(MATHML_NS, 'fict-host')
-              : document.createElement('fict-host')
+              ? ownerDocument.createElementNS(MATHML_NS, 'fict-host')
+              : ownerDocument.createElement('fict-host')
         host.setAttribute('data-fict-host', '')
         if (namespace === null && (host as HTMLElement).style) {
           ;(host as HTMLElement).style.display = 'contents'
@@ -332,13 +388,21 @@ 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, ownerDocument)
+      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')
+        return ownerDocument.createComment('fict:suspend')
       }
       handleError(err, { source: 'render', componentName: vnode.type.name })
       throw err
@@ -349,9 +413,9 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
 
   // Fragment
   if (vnode.type === Fragment) {
-    const frag = document.createDocumentFragment()
+    const frag = ownerDocument.createDocumentFragment()
     const children = vnode.props?.children as FictNode | FictNode[] | undefined
-    appendChildren(frag, children, namespace)
+    appendChildren(frag, children, namespace, ownerDocument)
     return frag
   }
 
@@ -360,15 +424,16 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
   const resolvedNamespace = resolveNamespace(tagName, namespace)
   const el =
     resolvedNamespace === 'svg'
-      ? document.createElementNS(SVG_NS, tagName)
+      ? ownerDocument.createElementNS(SVG_NS, tagName)
       : resolvedNamespace === 'mathml'
-        ? document.createElementNS(MATHML_NS, tagName)
-        : document.createElement(tagName)
+        ? ownerDocument.createElementNS(MATHML_NS, tagName)
+        : ownerDocument.createElement(tagName)
   applyProps(el, vnode.props ?? {}, resolvedNamespace === 'svg')
   appendChildren(
     el as unknown as ParentNode & Node,
     vnode.props?.children as FictNode | FictNode[] | undefined,
     tagName === 'foreignObject' ? null : resolvedNamespace,
+    ownerDocument,
   )
   return el as DOMElement
 }
@@ -388,10 +453,10 @@ export function template(
   isSVG?: boolean,
   isMathML?: boolean,
 ): () => Node {
-  let node: Node | null = null
+  const nodeByDocument = new WeakMap<Document, Node>()
 
-  const create = (): Node => {
-    const t = document.createElement('template')
+  const create = (ownerDocument: Document): Node => {
+    const t = ownerDocument.createElement('template')
 
     if (isSVG) {
       // fix: Wrap HTML in <svg> to parse content in SVG namespace
@@ -409,7 +474,7 @@ export function template(
         return wrapper.firstChild!
       }
       // Preserve all root nodes by returning a fragment
-      const fragment = document.createDocumentFragment()
+      const fragment = ownerDocument.createDocumentFragment()
       fragment.append(...Array.from(wrapper.childNodes))
       return fragment
     }
@@ -429,7 +494,7 @@ export function template(
         return wrapper.firstChild!
       }
       // Preserve all root nodes by returning a fragment
-      const fragment = document.createDocumentFragment()
+      const fragment = ownerDocument.createDocumentFragment()
       fragment.append(...Array.from(wrapper.childNodes))
       return fragment
     }
@@ -450,17 +515,26 @@ export function template(
     return content
   }
 
+  const getBase = (ownerDocument: Document): Node => {
+    const cached = nodeByDocument.get(ownerDocument)
+    if (cached) return cached
+    const created = create(ownerDocument)
+    nodeByDocument.set(ownerDocument, created)
+    return created
+  }
+
   // Create the cloning function
   const fn = isImportNode
     ? () =>
         untrack(() => {
-          const base = node || (node = create())
+          const ownerDocument = resolveOwnerDocument()
+          const base = getBase(ownerDocument)
           return isHydratingActive()
-            ? claimNodes(base, () => document.importNode(base, true))
-            : document.importNode(base, true)
+            ? claimNodes(base, () => ownerDocument.importNode(base, true))
+            : ownerDocument.importNode(base, true)
         })
     : () => {
-        const base = node || (node = create())
+        const base = getBase(resolveOwnerDocument())
         return isHydratingActive()
           ? claimNodes(base, () => base.cloneNode(true))
           : base.cloneNode(true)
@@ -499,7 +573,10 @@ function appendChildNode(
   parent: ParentNode & Node,
   child: FictNode,
   namespace: NamespaceContext,
+  ownerDocument: Document,
 ): void {
+  const parentOwnerDocument = parent.ownerDocument ?? ownerDocument
+
   // Skip nullish values
   if (child === null || child === undefined || child === false) {
     return
@@ -507,7 +584,7 @@ function appendChildNode(
 
   // Handle BindingHandle (recursive)
   if (isBindingHandle(child)) {
-    appendChildNode(parent, child.marker, namespace)
+    appendChildNode(parent, child.marker, namespace, parentOwnerDocument)
     // Flush pending nodes now that markers are in the DOM
     child.flush?.()
     return
@@ -519,7 +596,9 @@ function appendChildNode(
   if (typeof child === 'function') {
     const childGetter = child as () => FictNode
     if (isReactive(childGetter)) {
-      createChildBinding(parent, childGetter, node => createElementWithContext(node, namespace))
+      createChildBinding(parent, childGetter, node =>
+        createElementWithContext(node, namespace, parentOwnerDocument),
+      )
       return
     }
     return
@@ -528,7 +607,7 @@ function appendChildNode(
   // Static child - create element and append
   if (Array.isArray(child)) {
     for (const item of child) {
-      appendChildNode(parent, item, namespace)
+      appendChildNode(parent, item, namespace, parentOwnerDocument)
     }
     return
   }
@@ -536,16 +615,16 @@ function appendChildNode(
   // Cast to Node for remaining logic
   let domNode: Node
   if (typeof child !== 'object' || child === null) {
-    domNode = document.createTextNode(String(child ?? ''))
+    domNode = parentOwnerDocument.createTextNode(String(child ?? ''))
   } else {
-    domNode = createElementWithContext(child as any, namespace) as Node
+    domNode = createElementWithContext(child as any, namespace, parentOwnerDocument) as Node
   }
 
   // Handle DocumentFragment manually to avoid JSDOM issues
   if (domNode.nodeType === 11) {
     const children = Array.from(domNode.childNodes)
     for (const node of children) {
-      appendChildNode(parent, node as FictNode, namespace)
+      appendChildNode(parent, node as FictNode, namespace, parentOwnerDocument)
     }
     return
   }
@@ -573,17 +652,18 @@ function appendChildren(
   parent: ParentNode & Node,
   children: FictNode | FictNode[] | undefined,
   namespace: NamespaceContext,
+  ownerDocument: Document,
 ): void {
   if (children === undefined) return
 
   if (Array.isArray(children)) {
     for (const child of children) {
-      appendChildren(parent, child, namespace)
+      appendChildren(parent, child, namespace, ownerDocument)
     }
     return
   }
 
-  appendChildNode(parent, children, namespace)
+  appendChildNode(parent, children, namespace, ownerDocument)
 }
 
 // ============================================================================

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/error-boundary.ts

@@ -19,11 +19,11 @@ interface ErrorBoundaryProps extends BaseProps {
 }
 
 export function ErrorBoundary(props: ErrorBoundaryProps): FictNode {
-  const fragment = document.createDocumentFragment()
-  const marker = document.createComment('fict:error-boundary')
-  fragment.appendChild(marker)
-
   const hostRoot = getCurrentRoot()
+  const markerOwnerDocument = hostRoot?.ownerDocument ?? document
+  const fragment = markerOwnerDocument.createDocumentFragment()
+  const marker = markerOwnerDocument.createComment('fict:error-boundary')
+  fragment.appendChild(marker)
 
   let cleanup: (() => void) | undefined
   let activeNodes: Node[] = []
@@ -58,7 +58,7 @@ export function ErrorBoundary(props: ErrorBoundaryProps): FictNode {
     let nodes: Node[] = []
     try {
       const output = createElement(value)
-      nodes = toNodeArray(output)
+      nodes = toNodeArray(output, markerOwnerDocument)
       const parentNode = marker.parentNode as (ParentNode & Node) | null
       if (parentNode) {
         insertNodesBefore(parentNode, nodes, marker)

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 =
@@ -10,6 +11,7 @@ type LifecycleFn = () => void | Cleanup
 
 export interface RootContext {
   parent?: RootContext | undefined
+  ownerDocument?: Document | undefined
   onMountCallbacks?: LifecycleFn[]
   cleanups: Cleanup[]
   destroyCallbacks: Cleanup[]
@@ -29,9 +31,45 @@ 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,
+    ownerDocument: parent?.ownerDocument,
+    cleanups: [],
+    destroyCallbacks: [],
+    suspended: false,
+  }
+  registerRootDevtools(root)
+  return root
 }
 
 export function pushRoot(root: RootContext): RootContext | undefined {
@@ -122,6 +160,7 @@ export function destroyRoot(root: RootContext): void {
   if (globalSuspenseHandlers.has(root)) {
     globalSuspenseHandlers.delete(root)
   }
+  disposeRootDevtools(root)
 }
 
 export function createRoot<T>(
@@ -285,7 +324,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 +346,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
       }
     }