@fictjs/runtime 0.0.12 → 0.0.14

package/src/context.ts

@@ -0,0 +1,300 @@
+/**
+ * @fileoverview Context API for Fict
+ *
+ * Provides a way to pass data through the component tree without having to pass
+ * props down manually at every level. Context is designed for:
+ *
+ * - SSR isolation (different request = different context values)
+ * - Multi-instance support (multiple app roots with different values)
+ * - Subtree scoping (override values in specific parts of the tree)
+ *
+ * ## Design Principles
+ *
+ * 1. **Reuses existing RootContext hierarchy** - Uses parent chain for value lookup,
+ *    consistent with handleError/handleSuspend mechanisms.
+ *
+ * 2. **Zero extra root creation overhead** - Provider doesn't create new root,
+ *    only mounts value on current root.
+ *
+ * 3. **Auto-aligned with insert/suspense boundaries** - Because they create child
+ *    roots that inherit parent, context values propagate correctly.
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * // Create context with default value
+ * const ThemeContext = createContext<'light' | 'dark'>('light')
+ *
+ * // Provide value to subtree
+ * function App() {
+ *   return (
+ *     <ThemeContext.Provider value="dark">
+ *       <ThemedComponent />
+ *     </ThemeContext.Provider>
+ *   )
+ * }
+ *
+ * // Consume value
+ * function ThemedComponent() {
+ *   const theme = useContext(ThemeContext)
+ *   return <div class={theme}>...</div>
+ * }
+ * ```
+ *
+ * @module
+ */
+
+import { createElement } from './dom'
+import {
+  createRootContext,
+  destroyRoot,
+  flushOnMount,
+  getCurrentRoot,
+  popRoot,
+  pushRoot,
+  type RootContext,
+} from './lifecycle'
+import { insertNodesBefore, removeNodes, toNodeArray } from './node-ops'
+import { createRenderEffect } from './effect'
+import type { BaseProps, FictNode } from './types'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Context object created by createContext.
+ * Contains the Provider component and serves as a key for context lookup.
+ */
+export interface Context<T> {
+  /** Unique identifier for this context */
+  readonly id: symbol
+  /** Default value when no provider is found */
+  readonly defaultValue: T
+  /** Provider component for supplying context values */
+  Provider: ContextProvider<T>
+  /** Display name for debugging */
+  displayName?: string
+}
+
+/**
+ * Props for the Context Provider component
+ */
+export interface ProviderProps<T> extends BaseProps {
+  /** The value to provide to the subtree */
+  value: T
+}
+
+/**
+ * Provider component type
+ */
+export type ContextProvider<T> = (props: ProviderProps<T>) => FictNode
+
+// ============================================================================
+// Internal Context Storage
+// ============================================================================
+
+/**
+ * WeakMap to store context values per RootContext.
+ * Using WeakMap ensures proper garbage collection when roots are destroyed.
+ */
+const contextStorage = new WeakMap<RootContext, Map<symbol, unknown>>()
+
+/**
+ * Get the context map for a root, creating it if needed
+ */
+function getContextMap(root: RootContext): Map<symbol, unknown> {
+  let map = contextStorage.get(root)
+  if (!map) {
+    map = new Map()
+    contextStorage.set(root, map)
+  }
+  return map
+}
+
+// ============================================================================
+// Context API
+// ============================================================================
+
+/**
+ * Creates a new context with the given default value.
+ *
+ * Context provides a way to pass values through the component tree without
+ * explicit props drilling. It's especially useful for:
+ *
+ * - Theme data
+ * - Locale/i18n settings
+ * - Authentication state
+ * - Feature flags
+ * - Any data that many components at different nesting levels need
+ *
+ * @param defaultValue - The value to use when no Provider is found above in the tree
+ * @returns A context object with a Provider component
+ *
+ * @example
+ * ```tsx
+ * // Create a theme context
+ * const ThemeContext = createContext<'light' | 'dark'>('light')
+ *
+ * // Use the provider
+ * function App() {
+ *   return (
+ *     <ThemeContext.Provider value="dark">
+ *       <Content />
+ *     </ThemeContext.Provider>
+ *   )
+ * }
+ *
+ * // Consume the context
+ * function Content() {
+ *   const theme = useContext(ThemeContext)
+ *   return <div class={`theme-${theme}`}>Hello</div>
+ * }
+ * ```
+ */
+export function createContext<T>(defaultValue: T): Context<T> {
+  const id = Symbol('fict.context')
+
+  const context: Context<T> = {
+    id,
+    defaultValue,
+    Provider: null as unknown as ContextProvider<T>,
+  }
+
+  // Create the Provider component
+  context.Provider = function Provider(props: ProviderProps<T>): FictNode {
+    const hostRoot = getCurrentRoot()
+
+    // Create a child root for the provider's subtree
+    // This establishes the provider boundary - children will look up from here
+    const providerRoot = createRootContext(hostRoot)
+
+    // Store the context value on this root
+    const contextMap = getContextMap(providerRoot)
+    contextMap.set(id, props.value)
+
+    // Create DOM structure
+    const fragment = document.createDocumentFragment()
+    const marker = document.createComment('fict:ctx')
+    fragment.appendChild(marker)
+
+    let cleanup: (() => void) | undefined
+    let activeNodes: Node[] = []
+
+    const renderChildren = (children: FictNode) => {
+      // Cleanup previous render
+      if (cleanup) {
+        cleanup()
+        cleanup = undefined
+      }
+      if (activeNodes.length) {
+        removeNodes(activeNodes)
+        activeNodes = []
+      }
+
+      if (children == null || children === false) {
+        return
+      }
+
+      const prev = pushRoot(providerRoot)
+      let nodes: Node[] = []
+      try {
+        const output = createElement(children)
+        nodes = toNodeArray(output)
+        const parentNode = marker.parentNode as (ParentNode & Node) | null
+        if (parentNode) {
+          insertNodesBefore(parentNode, nodes, marker)
+        }
+      } finally {
+        popRoot(prev)
+        flushOnMount(providerRoot)
+      }
+
+      cleanup = () => {
+        destroyRoot(providerRoot)
+        removeNodes(nodes)
+      }
+      activeNodes = nodes
+    }
+
+    // Initial render
+    createRenderEffect(() => {
+      // Update context value on re-render (if value prop changes reactively)
+      contextMap.set(id, props.value)
+      renderChildren(props.children)
+    })
+
+    return fragment
+  }
+
+  return context
+}
+
+/**
+ * Reads the current value of a context.
+ *
+ * useContext looks up through the RootContext parent chain to find the
+ * nearest Provider for this context. If no Provider is found, returns
+ * the context's default value.
+ *
+ * @param context - The context object created by createContext
+ * @returns The current context value
+ *
+ * @example
+ * ```tsx
+ * const ThemeContext = createContext('light')
+ *
+ * function ThemedButton() {
+ *   const theme = useContext(ThemeContext)
+ *   return <button class={theme === 'dark' ? 'btn-dark' : 'btn-light'}>Click</button>
+ * }
+ * ```
+ */
+export function useContext<T>(context: Context<T>): T {
+  let root = getCurrentRoot()
+
+  // Walk up the parent chain looking for the context value
+  while (root) {
+    const contextMap = contextStorage.get(root)
+    if (contextMap && contextMap.has(context.id)) {
+      return contextMap.get(context.id) as T
+    }
+    root = root.parent
+  }
+
+  // No provider found, return default value
+  return context.defaultValue
+}
+
+/**
+ * Checks if a context value is currently provided in the tree.
+ *
+ * Useful for conditional behavior when a provider may or may not exist.
+ *
+ * @param context - The context object to check
+ * @returns true if a Provider exists above in the tree
+ *
+ * @example
+ * ```tsx
+ * function OptionalTheme() {
+ *   if (hasContext(ThemeContext)) {
+ *     const theme = useContext(ThemeContext)
+ *     return <div class={theme}>Themed content</div>
+ *   }
+ *   return <div>Default content</div>
+ * }
+ * ```
+ */
+export function hasContext<T>(context: Context<T>): boolean {
+  let root = getCurrentRoot()
+
+  while (root) {
+    const contextMap = contextStorage.get(root)
+    if (contextMap && contextMap.has(context.id)) {
+      return true
+    }
+    root = root.parent
+  }
+
+  return false
+}

package/src/cycle-guard.ts

@@ -1,5 +1,10 @@
 import { getDevtoolsHook } from './devtools'
 
+const isDev =
+  typeof __DEV__ !== 'undefined'
+    ? __DEV__
+    : typeof process === 'undefined' || process.env?.NODE_ENV !== 'production'
+
 export interface CycleProtectionOptions {
   maxFlushCyclesPerMicrotask?: number
   maxEffectRunsPerFlush?: number
@@ -15,120 +20,142 @@ interface CycleWindowEntry {
   budget: number
 }
 
-const defaultOptions = {
-  maxFlushCyclesPerMicrotask: 10_000,
-  maxEffectRunsPerFlush: 20_000,
-  windowSize: 5,
-  highUsageRatio: 0.8,
-  maxRootReentrantDepth: 10,
-  enableWindowWarning: true,
-  devMode: false,
-}
+let setCycleProtectionOptions: (opts: CycleProtectionOptions) => void = () => {}
+let resetCycleProtectionStateForTests: () => void = () => {}
+let beginFlushGuard: () => void = () => {}
+let beforeEffectRunGuard: () => boolean = () => true
+let endFlushGuard: () => void = () => {}
+let enterRootGuard: (root: object) => boolean = () => true
+let exitRootGuard: (root: object) => void = () => {}
 
-let options: Required<CycleProtectionOptions> = {
-  ...defaultOptions,
-} as Required<CycleProtectionOptions>
+if (isDev) {
+  const defaultOptions = {
+    maxFlushCyclesPerMicrotask: 10_000,
+    maxEffectRunsPerFlush: 20_000,
+    windowSize: 5,
+    highUsageRatio: 0.8,
+    maxRootReentrantDepth: 10,
+    enableWindowWarning: true,
+    devMode: false,
+  }
 
-let effectRunsThisFlush = 0
-let windowUsage: CycleWindowEntry[] = []
-let rootDepth = new WeakMap<object, number>()
-let flushWarned = false
-let rootWarned = false
-let windowWarned = false
+  let options: Required<CycleProtectionOptions> = {
+    ...defaultOptions,
+  } as Required<CycleProtectionOptions>
 
-export function setCycleProtectionOptions(opts: CycleProtectionOptions): void {
-  options = { ...options, ...opts }
-}
+  let effectRunsThisFlush = 0
+  let windowUsage: CycleWindowEntry[] = []
+  let rootDepth = new WeakMap<object, number>()
+  let flushWarned = false
+  let rootWarned = false
+  let windowWarned = false
 
-export function resetCycleProtectionStateForTests(): void {
-  options = { ...defaultOptions } as Required<CycleProtectionOptions>
-  effectRunsThisFlush = 0
-  windowUsage = []
-  rootDepth = new WeakMap<object, number>()
-  flushWarned = false
-  rootWarned = false
-  windowWarned = false
-}
+  setCycleProtectionOptions = opts => {
+    options = { ...options, ...opts }
+  }
 
-export function beginFlushGuard(): void {
-  effectRunsThisFlush = 0
-  flushWarned = false
-  windowWarned = false
-}
+  resetCycleProtectionStateForTests = () => {
+    options = { ...defaultOptions } as Required<CycleProtectionOptions>
+    effectRunsThisFlush = 0
+    windowUsage = []
+    rootDepth = new WeakMap<object, number>()
+    flushWarned = false
+    rootWarned = false
+    windowWarned = false
+  }
 
-export function beforeEffectRunGuard(): boolean {
-  const next = ++effectRunsThisFlush
-  if (next > options.maxFlushCyclesPerMicrotask || next > options.maxEffectRunsPerFlush) {
-    const message = `[fict] cycle protection triggered: flush-budget-exceeded`
-    if (options.devMode) {
-      throw new Error(message)
-    }
-    if (!flushWarned) {
-      flushWarned = true
-      console.warn(message, { effectRuns: next })
+  beginFlushGuard = () => {
+    effectRunsThisFlush = 0
+    flushWarned = false
+    windowWarned = false
+  }
+
+  beforeEffectRunGuard = () => {
+    const next = ++effectRunsThisFlush
+    if (next > options.maxFlushCyclesPerMicrotask || next > options.maxEffectRunsPerFlush) {
+      const message = `[fict] cycle protection triggered: flush-budget-exceeded`
+      if (options.devMode) {
+        throw new Error(message)
+      }
+      if (!flushWarned) {
+        flushWarned = true
+        console.warn(message, { effectRuns: next })
+      }
+      return false
     }
-    return false
+    return true
   }
-  return true
-}
 
-export function endFlushGuard(): void {
-  recordWindowUsage(effectRunsThisFlush, options.maxFlushCyclesPerMicrotask)
-  effectRunsThisFlush = 0
-}
+  endFlushGuard = () => {
+    recordWindowUsage(effectRunsThisFlush, options.maxFlushCyclesPerMicrotask)
+    effectRunsThisFlush = 0
+  }
 
-export function enterRootGuard(root: object): boolean {
-  const depth = (rootDepth.get(root) ?? 0) + 1
-  if (depth > options.maxRootReentrantDepth) {
-    const message = `[fict] cycle protection triggered: root-reentry`
-    if (options.devMode) {
-      throw new Error(message)
+  enterRootGuard = root => {
+    const depth = (rootDepth.get(root) ?? 0) + 1
+    if (depth > options.maxRootReentrantDepth) {
+      const message = `[fict] cycle protection triggered: root-reentry`
+      if (options.devMode) {
+        throw new Error(message)
+      }
+      if (!rootWarned) {
+        rootWarned = true
+        console.warn(message, { depth })
+      }
+      return false
     }
-    if (!rootWarned) {
-      rootWarned = true
-      console.warn(message, { depth })
-    }
-    return false
+    rootDepth.set(root, depth)
+    return true
   }
-  rootDepth.set(root, depth)
-  return true
-}
 
-export function exitRootGuard(root: object): void {
-  const depth = rootDepth.get(root)
-  if (depth === undefined) return
-  if (depth <= 1) {
-    rootDepth.delete(root)
-  } else {
-    rootDepth.set(root, depth - 1)
+  exitRootGuard = root => {
+    const depth = rootDepth.get(root)
+    if (depth === undefined) return
+    if (depth <= 1) {
+      rootDepth.delete(root)
+    } else {
+      rootDepth.set(root, depth - 1)
+    }
   }
-}
 
-function recordWindowUsage(used: number, budget: number): void {
-  if (!options.enableWindowWarning) return
-  const entry = { used, budget }
-  windowUsage.push(entry)
-  if (windowUsage.length > options.windowSize) {
-    windowUsage.shift()
+  const recordWindowUsage = (used: number, budget: number): void => {
+    if (!options.enableWindowWarning) return
+    const entry = { used, budget }
+    windowUsage.push(entry)
+    if (windowUsage.length > options.windowSize) {
+      windowUsage.shift()
+    }
+    if (windowWarned) return
+    if (
+      windowUsage.length >= options.windowSize &&
+      windowUsage.every(
+        item => item.budget > 0 && item.used / item.budget >= options.highUsageRatio,
+      )
+    ) {
+      windowWarned = true
+      reportCycle('high-usage-window', {
+        windowSize: options.windowSize,
+        ratio: options.highUsageRatio,
+      })
+    }
   }
-  if (windowWarned) return
-  if (
-    windowUsage.length >= options.windowSize &&
-    windowUsage.every(item => item.budget > 0 && item.used / item.budget >= options.highUsageRatio)
-  ) {
-    windowWarned = true
-    reportCycle('high-usage-window', {
-      windowSize: options.windowSize,
-      ratio: options.highUsageRatio,
-    })
+
+  const reportCycle = (
+    reason: string,
+    detail: Record<string, unknown> | undefined = undefined,
+  ): void => {
+    const hook = getDevtoolsHook()
+    hook?.cycleDetected?.(detail ? { reason, detail } : { reason })
+    console.warn(`[fict] cycle protection triggered: ${reason}`, detail ?? '')
   }
 }
 
-function reportCycle(
-  reason: string,
-  detail: Record<string, unknown> | undefined = undefined,
-): void {
-  const hook = getDevtoolsHook()
-  hook?.cycleDetected?.(detail ? { reason, detail } : { reason })
-  console.warn(`[fict] cycle protection triggered: ${reason}`, detail ?? '')
+export {
+  setCycleProtectionOptions,
+  resetCycleProtectionStateForTests,
+  beginFlushGuard,
+  beforeEffectRunGuard,
+  endFlushGuard,
+  enterRootGuard,
+  exitRootGuard,
 }

package/src/delegated-events.ts

@@ -0,0 +1,24 @@
+export const DelegatedEventNames = [
+  'beforeinput',
+  'click',
+  'dblclick',
+  'contextmenu',
+  'focusin',
+  'focusout',
+  'input',
+  'keydown',
+  'keyup',
+  'mousedown',
+  'mousemove',
+  'mouseout',
+  'mouseover',
+  'mouseup',
+  'pointerdown',
+  'pointermove',
+  'pointerout',
+  'pointerover',
+  'pointerup',
+  'touchend',
+  'touchmove',
+  'touchstart',
+] as const

package/src/dom.ts

@@ -20,19 +20,11 @@ import {
   createChildBinding,
   bindEvent,
   isReactive,
-  PRIMITIVE_PROXY,
   type MaybeReactive,
   type AttributeSetter,
   type BindingHandle,
 } from './binding'
-import {
-  Properties,
-  ChildProperties,
-  Aliases,
-  getPropAlias,
-  SVGElements,
-  SVGNamespace,
-} from './constants'
+import { Properties, ChildProperties, getPropAlias, SVGElements, SVGNamespace } from './constants'
 import { __fictPushContext, __fictPopContext } from './hooks'
 import { Fragment } from './jsx'
 import {
@@ -128,7 +120,7 @@ function resolveNamespace(tagName: string, namespace: NamespaceContext): Namespa
   if (tagName === 'math') return 'mathml'
   if (namespace === 'mathml') return 'mathml'
   if (namespace === 'svg') return 'svg'
-  if (SVGElements.has(tagName)) return 'svg'
+  if (isDev && SVGElements.has(tagName)) return 'svg'
   return null
 }
 
@@ -143,9 +135,8 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
     return document.createTextNode('')
   }
 
-  // Primitive proxy produced by keyed list binding
   if (typeof node === 'object' && node !== null && !(node instanceof Node)) {
-    // Handle BindingHandle (createList, createConditional, etc)
+    // Handle BindingHandle (list/conditional bindings, etc)
     if ('marker' in node) {
       const handle = node as { marker: unknown; dispose?: () => void; flush?: () => void }
       // Register dispose cleanup if available
@@ -164,14 +155,6 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
       }
       return createElement(handle.marker as FictNode)
     }
-
-    const nodeRecord = node as unknown as Record<PropertyKey, unknown>
-    if (nodeRecord[PRIMITIVE_PROXY]) {
-      const primitiveGetter = nodeRecord[Symbol.toPrimitive]
-      const value =
-        typeof primitiveGetter === 'function' ? primitiveGetter.call(node, 'default') : node
-      return document.createTextNode(value == null || value === false ? '' : String(value))
-    }
   }
 
   // Array - create fragment
@@ -559,7 +542,13 @@ function applyProps(el: Element, props: Record<string, unknown>, isSVG = false):
     }
 
     // Child properties (innerHTML, textContent, etc.)
-    if (ChildProperties.has(key)) {
+    if (
+      (isDev && ChildProperties.has(key)) ||
+      key === 'innerHTML' ||
+      key === 'textContent' ||
+      key === 'innerText' ||
+      key === 'children'
+    ) {
       createAttributeBinding(el, key, value as MaybeReactive<unknown>, setProperty)
       continue
     }
@@ -583,13 +572,18 @@ function applyProps(el: Element, props: Record<string, unknown>, isSVG = false):
     }
 
     // Check for property alias (element-specific mappings)
-    const propAlias = !isSVG ? getPropAlias(key, tagName) : undefined
+    const propAlias = !isSVG && isDev ? getPropAlias(key, tagName) : undefined
+    const isProperty = !isSVG
+      ? isDev
+        ? Properties.has(key)
+        : key in (el as unknown as Record<string, unknown>)
+      : false
 
     // Handle properties and element-specific attributes
-    if (propAlias || (!isSVG && Properties.has(key)) || (isCE && !isSVG)) {
+    if (propAlias || isProperty || (isCE && !isSVG)) {
       const propName = propAlias || key
       // Custom elements use toPropertyName conversion
-      if (isCE && !Properties.has(key)) {
+      if (isCE && !isProperty && !propAlias) {
         createAttributeBinding(
           el,
           toPropertyName(propName),
@@ -616,7 +610,7 @@ function applyProps(el: Element, props: Record<string, unknown>, isSVG = false):
 
     // Regular attributes (potentially reactive)
     // Apply alias mapping (className -> class, htmlFor -> for)
-    const attrName = Aliases[key] || key
+    const attrName = key === 'htmlFor' ? 'for' : key
     createAttributeBinding(el, attrName, value as MaybeReactive<unknown>, setAttribute)
   }
 }

package/src/effect.ts

@@ -8,6 +8,10 @@ import {
 import { effectWithCleanup } from './signal'
 import type { Cleanup } from './types'
 
+/**
+ * Effect callback run synchronously; async callbacks are not tracked after the first await.
+ * TypeScript will reject `async () => {}` here—split async work or read signals before awaiting.
+ */
 export type Effect = () => void | Cleanup
 
 export function createEffect(fn: Effect): () => void {