@fictjs/runtime 0.2.3 → 0.3.0

package/src/cycle-guard.ts

@@ -15,6 +15,10 @@ export interface CycleProtectionOptions {
   maxRootReentrantDepth?: number
   enableWindowWarning?: boolean
   devMode?: boolean
+  /** Enable backoff warnings at 50% and 75% of limits */
+  enableBackoffWarning?: boolean
+  /** Ratio at which to show first backoff warning (default 0.5) */
+  backoffWarningRatio?: number
 }
 
 interface CycleWindowEntry {
@@ -31,14 +35,17 @@ let enterRootGuard: (root: object) => boolean = () => true
 let exitRootGuard: (root: object) => void = () => {}
 
 const defaultOptions = {
-  enabled: isDev,
+  enabled: true,
   maxFlushCyclesPerMicrotask: 10_000,
   maxEffectRunsPerFlush: 20_000,
   windowSize: 5,
   highUsageRatio: 0.8,
   maxRootReentrantDepth: 10,
   enableWindowWarning: true,
-  devMode: false,
+  devMode: isDev,
+  // Backoff warning options
+  enableBackoffWarning: isDev,
+  backoffWarningRatio: 0.5,
 }
 
 let enabled = defaultOptions.enabled
@@ -52,6 +59,9 @@ let rootDepth = new WeakMap<object, number>()
 let flushWarned = false
 let rootWarned = false
 let windowWarned = false
+// Backoff warning state
+let backoffWarned50 = false
+let backoffWarned75 = false
 
 setCycleProtectionOptions = opts => {
   if (typeof opts.enabled === 'boolean') {
@@ -69,6 +79,9 @@ resetCycleProtectionStateForTests = () => {
   flushWarned = false
   rootWarned = false
   windowWarned = false
+  // Reset backoff state
+  backoffWarned50 = false
+  backoffWarned75 = false
 }
 
 beginFlushGuard = () => {
@@ -76,19 +89,53 @@ beginFlushGuard = () => {
   effectRunsThisFlush = 0
   flushWarned = false
   windowWarned = false
+  // Reset backoff state for new flush
+  backoffWarned50 = false
+  backoffWarned75 = false
 }
 
 beforeEffectRunGuard = () => {
   if (!enabled) return true
   const next = ++effectRunsThisFlush
-  if (next > options.maxFlushCyclesPerMicrotask || next > options.maxEffectRunsPerFlush) {
+  const limit = Math.min(options.maxFlushCyclesPerMicrotask, options.maxEffectRunsPerFlush)
+
+  // Backoff warnings at 50% and 75% of limit
+  if (options.enableBackoffWarning && isDev) {
+    const ratio = next / limit
+    const backoffRatio = options.backoffWarningRatio ?? 0.5
+
+    if (!backoffWarned50 && ratio >= backoffRatio && ratio < backoffRatio + 0.25) {
+      backoffWarned50 = true
+      console.warn(
+        `[fict] cycle guard: approaching effect limit (${Math.round(ratio * 100)}% of budget used)\n` +
+          `  - Current: ${next} effects, Limit: ${limit}\n` +
+          `  - Tip: Check for effects that trigger other effects in a loop.\n` +
+          `  - Common causes: signal updates inside effects that read and write the same signal.`,
+      )
+    } else if (!backoffWarned75 && ratio >= backoffRatio + 0.25 && ratio < 1) {
+      backoffWarned75 = true
+      console.warn(
+        `[fict] cycle guard: nearing effect limit (${Math.round(ratio * 100)}% of budget used)\n` +
+          `  - Current: ${next} effects, Limit: ${limit}\n` +
+          `  - Warning: Consider breaking the reactive dependency cycle.\n` +
+          `  - Debug: Use browser devtools to identify the recursive effect chain.`,
+      )
+    }
+  }
+
+  if (next > limit) {
     const message = `[fict] cycle protection triggered: flush-budget-exceeded`
     if (options.devMode) {
-      throw new Error(message)
+      throw new Error(
+        message +
+          `\n  - Effect runs: ${next}, Limit: ${limit}` +
+          `\n  - This indicates a reactive cycle where effects keep triggering each other.` +
+          `\n  - Check for patterns like: createEffect(() => { signal(); signal(newValue); })`,
+      )
     }
     if (!flushWarned) {
       flushWarned = true
-      console.warn(message, { effectRuns: next })
+      console.warn(message, { effectRuns: next, limit })
     }
     return false
   }
@@ -107,11 +154,16 @@ enterRootGuard = root => {
   if (depth > options.maxRootReentrantDepth) {
     const message = `[fict] cycle protection triggered: root-reentry`
     if (options.devMode) {
-      throw new Error(message)
+      throw new Error(
+        message +
+          `\n  - Re-entry depth: ${depth}, Max allowed: ${options.maxRootReentrantDepth}` +
+          `\n  - This indicates recursive render() or component initialization.` +
+          `\n  - Check for components that trigger re-renders during their own render phase.`,
+      )
     }
     if (!rootWarned) {
       rootWarned = true
-      console.warn(message, { depth })
+      console.warn(message, { depth, maxAllowed: options.maxRootReentrantDepth })
     }
     return false
   }

package/src/devtools.ts

@@ -1,9 +1,29 @@
 export interface FictDevtoolsHook {
-  registerSignal: (id: number, value: unknown) => void
+  registerSignal: (
+    id: number,
+    value: unknown,
+    options?: { name?: string; source?: string; ownerId?: number },
+  ) => void
   updateSignal: (id: number, value: unknown) => void
-  registerEffect: (id: number) => void
+  registerComputed: (
+    id: number,
+    value: unknown,
+    options?: { name?: string; source?: string; ownerId?: number; hasValue?: boolean },
+  ) => void
+  updateComputed: (id: number, value: unknown) => void
+  registerEffect: (id: number, options?: { ownerId?: number; source?: string }) => void
   effectRun: (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
   cycleDetected?: (payload: { reason: string; detail?: Record<string, unknown> }) => void
+
+  // Component lifecycle
+  registerComponent?: (id: number, name: string, parentId?: number, source?: any) => void
+  componentMount?: (id: number, elements?: HTMLElement[]) => void
+  componentUnmount?: (id: number) => void
+  componentRender?: (id: number) => void
 }
 
 function getGlobalHook(): FictDevtoolsHook | undefined {

package/src/dom.ts

@@ -25,7 +25,8 @@ import {
   type BindingHandle,
 } from './binding'
 import { Properties, ChildProperties, getPropAlias, SVGElements, SVGNamespace } from './constants'
-import { __fictPushContext, __fictPopContext } from './hooks'
+import { getDevtoolsHook } from './devtools'
+import { __fictPushContext, __fictPopContext, __fictGetCurrentComponentId } from './hooks'
 import { Fragment } from './jsx'
 import {
   createRootContext,
@@ -37,6 +38,8 @@ import {
   popRoot,
   registerRootCleanup,
   getCurrentRoot,
+  onMount,
+  onCleanup,
 } from './lifecycle'
 import { createPropsProxy, unwrapProps } from './props'
 import { untrack } from './scheduler'
@@ -51,6 +54,8 @@ const isDev =
     ? __DEV__
     : typeof process === 'undefined' || process.env?.NODE_ENV !== 'production'
 
+let nextComponentId = 1
+
 // ============================================================================
 // Main Render Function
 // ============================================================================
@@ -209,9 +214,34 @@ 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()
+    const hook = isDev ? getDevtoolsHook() : undefined
+    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)
+    }
+
+    const ctx = __fictPushContext()
+    if (componentId !== undefined) {
+      ctx.componentId = componentId
+      if (parentId !== undefined) {
+        ctx.parentId = parentId
+      }
+    }
+
     try {
       const rendered = vnode.type(props)
+
+      // Register lifecycle hooks
+      if (hook && componentId !== undefined) {
+        onMount(() => {
+          hook.componentMount?.(componentId)
+        })
+        onCleanup(() => hook.componentUnmount?.(componentId))
+      }
+
       return createElementWithContext(rendered as FictNode, namespace)
     } catch (err) {
       if (handleSuspend(err as any)) {
@@ -268,19 +298,63 @@ export function template(
   let node: Node | null = null
 
   const create = (): Node => {
-    const t = isMathML
-      ? document.createElementNS(MATHML_NS, 'template')
-      : document.createElement('template')
-    t.innerHTML = html
+    const t = document.createElement('template')
 
     if (isSVG) {
-      // For SVG, get the nested content
-      return (t as HTMLTemplateElement).content.firstChild!.firstChild!
+      // fix: Wrap HTML in <svg> to parse content in SVG namespace
+      // Then extract the actual content (firstChild of the wrapper svg)
+      t.innerHTML = `<svg>${html}</svg>`
+      const wrapper = (t as HTMLTemplateElement).content.firstChild!
+      // Dev check for multi-root SVG templates
+      if (isDev && wrapper.childNodes.length !== 1) {
+        console.warn(
+          `[fict] template() received multi-root SVG content (${wrapper.childNodes.length} nodes). ` +
+            `Returning a DocumentFragment. This may indicate a compiler bug or invalid JSX structure.`,
+        )
+      }
+      if (wrapper.childNodes.length === 1) {
+        return wrapper.firstChild!
+      }
+      // Preserve all root nodes by returning a fragment
+      const fragment = document.createDocumentFragment()
+      fragment.append(...Array.from(wrapper.childNodes))
+      return fragment
     }
     if (isMathML) {
-      return t.firstChild!
+      // fix: Wrap HTML in <math> to parse content in MathML namespace
+      // Then extract the actual content (firstChild of the wrapper math)
+      t.innerHTML = `<math>${html}</math>`
+      const wrapper = (t as HTMLTemplateElement).content.firstChild!
+      // Dev check for multi-root MathML templates
+      if (isDev && wrapper.childNodes.length !== 1) {
+        console.warn(
+          `[fict] template() received multi-root MathML content (${wrapper.childNodes.length} nodes). ` +
+            `Returning a DocumentFragment. This may indicate a compiler bug or invalid JSX structure.`,
+        )
+      }
+      if (wrapper.childNodes.length === 1) {
+        return wrapper.firstChild!
+      }
+      // Preserve all root nodes by returning a fragment
+      const fragment = document.createDocumentFragment()
+      fragment.append(...Array.from(wrapper.childNodes))
+      return fragment
+    }
+
+    t.innerHTML = html
+    const content = (t as HTMLTemplateElement).content
+    // Dev check for multi-root templates
+    if (isDev && content.childNodes.length !== 1) {
+      console.warn(
+        `[fict] template() received multi-root content (${content.childNodes.length} nodes). ` +
+          `Returning a DocumentFragment. This may indicate a compiler bug or invalid JSX structure.`,
+      )
+    }
+    if (content.childNodes.length === 1) {
+      return content.firstChild!
     }
-    return (t as HTMLTemplateElement).content.firstChild!
+    // Preserve all root nodes by returning a fragment
+    return content
   }
 
   // Create the cloning function

package/src/hooks.ts

@@ -1,6 +1,12 @@
 import { createEffect } from './effect'
 import { createMemo } from './memo'
-import { createSignal, type SignalAccessor, type ComputedAccessor } from './signal'
+import {
+  createSignal,
+  type SignalAccessor,
+  type ComputedAccessor,
+  type MemoOptions,
+  type SignalOptions,
+} from './signal'
 
 const isDev =
   typeof __DEV__ !== 'undefined'
@@ -11,6 +17,8 @@ interface HookContext {
   slots: unknown[]
   cursor: number
   rendering?: boolean
+  componentId?: number
+  parentId?: number
 }
 
 const ctxStack: HookContext[] = []
@@ -26,13 +34,22 @@ function assertRenderContext(ctx: HookContext, hookName: string): void {
 
 export function __fictUseContext(): HookContext {
   if (ctxStack.length === 0) {
-    const ctx: HookContext = { slots: [], cursor: 0, rendering: true }
-    ctxStack.push(ctx)
-    return ctx
+    // fix: Don't silently create context when called outside render.
+    // This would cause a memory leak and undefined behavior.
+    const message = isDev
+      ? 'Invalid hook call: hooks can only be used while rendering a component. ' +
+        'Make sure you are not calling hooks in event handlers or outside of components.'
+      : 'FICT:E_HOOK_OUTSIDE_RENDER'
+    throw new Error(message)
   }
   const ctx = ctxStack[ctxStack.length - 1]!
-  ctx.cursor = 0
-  ctx.rendering = true
+  // fix: Only reset cursor when starting a new render, not during an existing render.
+  // This allows custom hooks to share the same hook slot sequence as the calling component,
+  // similar to React's "rules of hooks" where hooks are called in consistent order.
+  if (!ctx.rendering) {
+    ctx.cursor = 0
+    ctx.rendering = true
+  }
   return ctx
 }
 
@@ -42,19 +59,32 @@ export function __fictPushContext(): HookContext {
   return ctx
 }
 
+export function __fictGetCurrentComponentId(): number | undefined {
+  return ctxStack[ctxStack.length - 1]?.componentId
+}
+
 export function __fictPopContext(): void {
-  ctxStack.pop()
+  // fix: Reset rendering flag when popping to avoid state leakage
+  const ctx = ctxStack.pop()
+  if (ctx) ctx.rendering = false
 }
 
 export function __fictResetContext(): void {
   ctxStack.length = 0
 }
 
-export function __fictUseSignal<T>(ctx: HookContext, initial: T, slot?: number): SignalAccessor<T> {
+export function __fictUseSignal<T>(
+  ctx: HookContext,
+  initial: T,
+  optionsOrSlot?: number | SignalOptions<T>,
+  slot?: number,
+): SignalAccessor<T> {
   assertRenderContext(ctx, '__fictUseSignal')
-  const index = slot ?? ctx.cursor++
+  const options = typeof optionsOrSlot === 'number' ? undefined : optionsOrSlot
+  const resolvedSlot = typeof optionsOrSlot === 'number' ? optionsOrSlot : slot
+  const index = resolvedSlot ?? ctx.cursor++
   if (!ctx.slots[index]) {
-    ctx.slots[index] = createSignal(initial)
+    ctx.slots[index] = createSignal(initial, options)
   }
   return ctx.slots[index] as SignalAccessor<T>
 }
@@ -62,19 +92,36 @@ export function __fictUseSignal<T>(ctx: HookContext, initial: T, slot?: number):
 export function __fictUseMemo<T>(
   ctx: HookContext,
   fn: () => T,
+  optionsOrSlot?: number | MemoOptions<T>,
   slot?: number,
 ): ComputedAccessor<T> {
   assertRenderContext(ctx, '__fictUseMemo')
-  const index = slot ?? ctx.cursor++
+  const options = typeof optionsOrSlot === 'number' ? undefined : optionsOrSlot
+  const resolvedSlot = typeof optionsOrSlot === 'number' ? optionsOrSlot : slot
+  const index = resolvedSlot ?? ctx.cursor++
   if (!ctx.slots[index]) {
-    ctx.slots[index] = createMemo(fn)
+    ctx.slots[index] = createMemo(fn, options)
   }
   return ctx.slots[index] as ComputedAccessor<T>
 }
 
 export function __fictUseEffect(ctx: HookContext, fn: () => void, slot?: number): void {
+  // 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]) {
+      // Effect already exists, nothing to do
+      return
+    }
+    // Create the effect even outside render context - the slot number proves validity
+    ctx.slots[slot] = createEffect(fn)
+    return
+  }
+
+  // For cursor-based allocation (no slot number), we need render context
   assertRenderContext(ctx, '__fictUseEffect')
-  const index = slot ?? ctx.cursor++
+  const index = ctx.cursor++
   if (!ctx.slots[index]) {
     ctx.slots[index] = createEffect(fn)
   }

package/src/index.ts

@@ -73,7 +73,7 @@ export { createContext, useContext, hasContext, type Context, type ProviderProps
 // Props Utilities (Public)
 // ============================================================================
 
-export { prop, mergeProps } from './props'
+export { prop, mergeProps, keyed } from './props'
 
 // ============================================================================
 // Types
@@ -96,3 +96,5 @@ export type {
   ErrorInfo,
   SuspenseToken,
 } from './types'
+
+export type { FictDevtoolsHook } from './devtools'

package/src/internal.ts

@@ -12,7 +12,7 @@
 // Core Primitives (also exported from main, but needed by compiler)
 // ============================================================================
 
-export { createSignal, createSelector } from './signal'
+export { createSignal, createSelector, __resetReactiveState } from './signal'
 export { createStore, type Store } from './store'
 export { createMemo } from './memo'
 export { createEffect } from './effect'
@@ -37,7 +37,7 @@ export {
 // Props Helpers (Compiler-generated code)
 // ============================================================================
 
-export { __fictProp, __fictPropsRest, createPropsProxy, mergeProps, prop } from './props'
+export { __fictProp, __fictPropsRest, createPropsProxy, mergeProps, prop, keyed } from './props'
 
 // ============================================================================
 // DOM Bindings (Compiler-generated code)

package/src/lifecycle.ts

@@ -77,13 +77,21 @@ export function onCleanup(fn: Cleanup): void {
 export function flushOnMount(root: RootContext): void {
   const cbs = root.onMountCallbacks
   if (!cbs || cbs.length === 0) return
-  for (let i = 0; i < cbs.length; i++) {
-    const cleanup = cbs[i]!()
-    if (typeof cleanup === 'function') {
-      root.cleanups.push(cleanup)
+  // Temporarily restore root context so onCleanup calls inside
+  // mount callbacks register correctly
+  const prevRoot = currentRoot
+  currentRoot = root
+  try {
+    for (let i = 0; i < cbs.length; i++) {
+      const cleanup = cbs[i]!()
+      if (typeof cleanup === 'function') {
+        root.cleanups.push(cleanup)
+      }
     }
+  } finally {
+    currentRoot = prevRoot
+    cbs.length = 0
   }
-  cbs.length = 0
 }
 
 export function registerRootCleanup(fn: Cleanup): void {

package/src/memo.ts

@@ -1,10 +1,9 @@
-import { computed } from './signal'
-import type { Signal } from './signal'
+import { computed, type Signal, type MemoOptions } from './signal'
 
 export type Memo<T> = () => T
 
-export function createMemo<T>(fn: () => T): Memo<T> {
-  return computed(fn)
+export function createMemo<T>(fn: () => T, options?: MemoOptions<T>): Memo<T> {
+  return computed(fn, options)
 }
 
 export function fromSignal<T>(signal: Signal<T>): Memo<T> {

package/src/props.ts

@@ -203,6 +203,22 @@ export type PropGetter<T> = (() => T) & { __fictProp: true }
 export interface PropOptions {
   unwrap?: boolean
 }
+
+/**
+ * Create a keyed prop getter that tracks both the key and the target access.
+ * Useful for dynamic property access like obj[key] where key is reactive.
+ */
+export function keyed<T, K extends string | number | symbol>(
+  target: T | PropGetter<T>,
+  key: K | (() => K),
+  options?: PropOptions,
+): PropGetter<unknown> {
+  return prop(() => {
+    const resolvedTarget = isPropGetter(target) ? (target as () => T)() : target
+    const resolvedKey = typeof key === 'function' ? (key as () => K)() : key
+    return (resolvedTarget as Record<string | number | symbol, unknown>)[resolvedKey]
+  }, options)
+}
 /**
  * Memoize a prop getter to cache expensive computations.
  * Use when prop expressions involve heavy calculations or you need lazy, reactive props.