@fictjs/runtime 0.0.12 → 0.0.14

package/src/hooks.ts

@@ -2,6 +2,11 @@ import { createEffect } from './effect'
 import { createMemo } from './memo'
 import { createSignal, type SignalAccessor, type ComputedAccessor } from './signal'
 
+const isDev =
+  typeof __DEV__ !== 'undefined'
+    ? __DEV__
+    : typeof process === 'undefined' || process.env?.NODE_ENV !== 'production'
+
 interface HookContext {
   slots: unknown[]
   cursor: number
@@ -12,7 +17,10 @@ const ctxStack: HookContext[] = []
 
 function assertRenderContext(ctx: HookContext, hookName: string): void {
   if (!ctx.rendering) {
-    throw new Error(`${hookName} can only be used during render execution`)
+    const message = isDev
+      ? `${hookName} can only be used during render execution`
+      : 'FICT:E_HOOK_RENDER'
+    throw new Error(message)
   }
 }
 

package/src/index.ts

@@ -1,38 +1,37 @@
+/**
+ * @fileoverview Fict Runtime - Public API
+ *
+ * This module exports the public API for the Fict reactive UI framework.
+ *
+ * ## Recommended Import Pattern (v1.0+)
+ *
+ * ```typescript
+ * // Core public API (most users need only this)
+ * import { createEffect, render } from '@fictjs/runtime'
+ *
+ * // Advanced APIs (power users, escape hatches)
+ * import { createSignal, createContext, createScope } from '@fictjs/runtime/advanced'
+ *
+ * // Internal APIs (compiler/library authors only)
+ * import { bindText, __fictUseSignal } from '@fictjs/runtime/internal'
+ * ```
+ *
+ * @public
+ * @packageDocumentation
+ */
+
 // ============================================================================
 // Core Reactive Primitives
 // ============================================================================
 
-export { createSignal, createSelector, type Signal, $state } from './signal'
-export { effectScope } from './signal'
-export { createStore, type Store } from './store'
-export { createMemo, type Memo, $memo } from './memo'
-export { createEffect, createRenderEffect, type Effect, $effect } from './effect'
-export { createScope, runInScope, type ReactiveScope } from './scope'
-export {
-  __fictUseContext,
-  __fictPushContext,
-  __fictPopContext,
-  __fictUseSignal,
-  __fictUseMemo,
-  __fictUseEffect,
-  __fictRender,
-  __fictResetContext,
-} from './hooks'
-export {
-  createVersionedSignal,
-  type VersionedSignal,
-  type VersionedSignalOptions,
-} from './versioned-signal'
-
-// Props helpers
-export {
-  __fictProp,
-  __fictProp as prop,
-  __fictPropsRest,
-  mergeProps,
-  useProp,
-  createPropsProxy,
-} from './props'
+/**
+ * Note: createSignal is exported from ./advanced as an escape hatch.
+ * For most use cases, prefer:
+ * - $state: For component-local state (compiler-transformed, safe scoping)
+ * - $store: For cross-component shared state with deep reactivity
+ */
+export { createMemo, type Memo } from './memo'
+export { createEffect, type Effect } from './effect'
 
 // ============================================================================
 // Lifecycle
@@ -40,7 +39,10 @@ export {
 
 export { onMount, onDestroy, onCleanup, createRoot } from './lifecycle'
 
-// Ref utilities
+// ============================================================================
+// Ref
+// ============================================================================
+
 export { createRef } from './ref'
 
 // ============================================================================
@@ -48,9 +50,6 @@ export { createRef } from './ref'
 // ============================================================================
 
 export { batch, untrack } from './scheduler'
-export { setCycleProtectionOptions } from './cycle-guard'
-
-// Transition API for priority scheduling
 export { startTransition, useTransition, useDeferredValue } from './scheduler'
 
 // ============================================================================
@@ -64,79 +63,22 @@ export { Fragment } from './jsx'
 // DOM Rendering
 // ============================================================================
 
-export { createElement, render, template } from './dom'
+export { createElement, render } from './dom'
+export { createPortal } from './binding'
 export { ErrorBoundary } from './error-boundary'
 export { Suspense, createSuspenseToken } from './suspense'
+export { createContext, useContext, hasContext, type Context, type ProviderProps } from './context'
 
 // ============================================================================
-// Reactive DOM Bindings
-// ============================================================================
-
-export {
-  // Core binding utilities
-  createTextBinding,
-  createChildBinding,
-  createAttributeBinding,
-  createStyleBinding,
-  createClassBinding,
-  // Low-level binding helpers (for direct DOM manipulation)
-  bindText,
-  bindAttribute,
-  bindStyle,
-  bindClass,
-  bindEvent,
-  callEventHandler,
-  bindProperty,
-  bindRef,
-  insert,
-  // Event delegation
-  delegateEvents,
-  clearDelegatedEvents,
-  addEventListener,
-  // Spread props
-  spread,
-  assign,
-  classList,
-  // Reactive detection
-  isReactive,
-  // Advanced bindings
-  createConditional,
-  createList,
-  createPortal,
-  createShow,
-  // Utility functions
-  unwrap,
-  unwrapPrimitive,
-} from './binding'
-
-// Constants for DOM handling
-export {
-  Properties,
-  ChildProperties,
-  Aliases,
-  getPropAlias,
-  BooleanAttributes,
-  SVGElements,
-  SVGNamespace,
-  DelegatedEvents,
-  UnitlessStyles,
-} from './constants'
-
-// Reconcile algorithm
-export { default as reconcileArrays } from './reconcile'
+// Props Utilities (Public)
+// ============================================================================
+
+export { prop, mergeProps } from './props'
 
 // ============================================================================
 // Types
 // ============================================================================
 
-export type {
-  MaybeReactive,
-  BindingHandle,
-  KeyFn,
-  CreateElementFn,
-  AttributeSetter,
-} from './binding'
-
 export type {
   FictNode,
   FictVNode,
@@ -154,34 +96,3 @@ export type {
   ErrorInfo,
   SuspenseToken,
 } from './types'
-
-// Devtools hook (optional)
-export { getDevtoolsHook, type FictDevtoolsHook } from './devtools'
-
-// ============================================================================
-// List Helpers (for compiler-generated code)
-// ============================================================================
-
-export {
-  // DOM manipulation primitives
-  moveNodesBefore,
-  removeNodes,
-  insertNodesBefore,
-  moveMarkerBlock,
-  destroyMarkerBlock,
-  // Keyed list container
-  createKeyedListContainer,
-  // Block creation
-  createKeyedBlock,
-  // High-level list binding (for compiler-generated code)
-  createKeyedList,
-  // Utilities
-  toNodeArray,
-  getFirstNodeAfter,
-  isNodeBetweenMarkers,
-  // Types
-  type KeyedBlock,
-  type KeyedListContainer,
-  type KeyedListBinding,
-  type MarkerBlock,
-} from './list-helpers'

package/src/internal.ts

@@ -0,0 +1,130 @@
+/**
+ * @fileoverview Internal APIs for Fict Compiler
+ *
+ * This module exports internal APIs used by compiler-generated code.
+ * These APIs are NOT part of the public API and should NOT be used directly.
+ *
+ * @internal
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Core Primitives (also exported from main, but needed by compiler)
+// ============================================================================
+
+export { createSignal, createSelector } from './signal'
+export { createStore, type Store } from './store'
+export { createMemo } from './memo'
+export { createEffect } from './effect'
+export { Fragment } from './jsx'
+
+// ============================================================================
+// Hook Context Management (Compiler-generated code)
+// ============================================================================
+
+export {
+  __fictUseContext,
+  __fictPushContext,
+  __fictPopContext,
+  __fictUseSignal,
+  __fictUseMemo,
+  __fictUseEffect,
+  __fictRender,
+  __fictResetContext,
+} from './hooks'
+
+// ============================================================================
+// Props Helpers (Compiler-generated code)
+// ============================================================================
+
+export { __fictProp, __fictPropsRest, createPropsProxy, mergeProps, prop } from './props'
+
+// ============================================================================
+// DOM Bindings (Compiler-generated code)
+// ============================================================================
+
+export {
+  bindText,
+  bindAttribute,
+  bindStyle,
+  bindClass,
+  bindEvent,
+  callEventHandler,
+  bindProperty,
+  bindRef,
+  insert,
+  createConditional,
+  createPortal,
+  spread,
+  assign,
+  classList,
+  isReactive,
+  unwrap,
+} from './binding'
+
+// ============================================================================
+// Event Delegation (Compiler-generated code)
+// ============================================================================
+
+export { delegateEvents, clearDelegatedEvents, addEventListener } from './binding'
+
+// ============================================================================
+// List Helpers (Compiler-generated code)
+// ============================================================================
+
+export {
+  moveNodesBefore,
+  removeNodes,
+  insertNodesBefore,
+  createKeyedList,
+  toNodeArray,
+  isNodeBetweenMarkers,
+  type KeyedListBinding,
+} from './list-helpers'
+
+// ============================================================================
+// DOM Creation (Compiler-generated code)
+// ============================================================================
+
+export { createElement, template } from './dom'
+export { createRenderEffect } from './effect'
+
+// ============================================================================
+// Lifecycle (Compiler-generated code)
+// ============================================================================
+
+export { onDestroy } from './lifecycle'
+
+// ============================================================================
+// Scope (Compiler-generated code)
+// ============================================================================
+
+export { runInScope } from './scope'
+
+// ============================================================================
+// Constants (Compiler/Runtime shared)
+// ============================================================================
+
+export {
+  Properties,
+  ChildProperties,
+  Aliases,
+  getPropAlias,
+  BooleanAttributes,
+  SVGElements,
+  SVGNamespace,
+  DelegatedEvents,
+  UnitlessStyles,
+} from './constants'
+
+// ============================================================================
+// Reconciliation (Internal)
+// ============================================================================
+
+export { default as reconcileArrays } from './reconcile'
+
+// ============================================================================
+// Types (Internal)
+// ============================================================================
+
+export type { MaybeReactive, BindingHandle, CreateElementFn, AttributeSetter } from './binding'

package/src/lifecycle.ts

@@ -1,6 +1,11 @@
 import { enterRootGuard, exitRootGuard } from './cycle-guard'
 import type { Cleanup, ErrorInfo, SuspenseToken } from './types'
 
+const isDev =
+  typeof __DEV__ !== 'undefined'
+    ? __DEV__
+    : typeof process === 'undefined' || process.env?.NODE_ENV !== 'production'
+
 type LifecycleFn = () => void | Cleanup
 
 export interface RootContext {
@@ -169,7 +174,10 @@ function runLifecycle(fn: LifecycleFn): void {
 
 export function registerErrorHandler(fn: ErrorHandler): void {
   if (!currentRoot) {
-    throw new Error('registerErrorHandler must be called within a root')
+    const message = isDev
+      ? 'registerErrorHandler must be called within a root'
+      : 'FICT:E_ROOT_HANDLER'
+    throw new Error(message)
   }
   if (!currentRoot.errorHandlers) {
     currentRoot.errorHandlers = []
@@ -185,7 +193,10 @@ export function registerErrorHandler(fn: ErrorHandler): void {
 
 export function registerSuspenseHandler(fn: SuspenseHandler): void {
   if (!currentRoot) {
-    throw new Error('registerSuspenseHandler must be called within a root')
+    const message = isDev
+      ? 'registerSuspenseHandler must be called within a root'
+      : 'FICT:E_ROOT_SUSPENSE'
+    throw new Error(message)
   }
   if (!currentRoot.suspenseHandlers) {
     currentRoot.suspenseHandlers = []

package/src/list-helpers.ts

@@ -37,7 +37,7 @@ const isDev =
 /**
  * A keyed block represents a single item in a list with its associated DOM nodes and state
  */
-export interface KeyedBlock<T = unknown> {
+interface KeyedBlock<T = unknown> {
   /** Unique key for this block */
   key: string | number
   /** DOM nodes belonging to this block */
@@ -57,7 +57,7 @@ export interface KeyedBlock<T = unknown> {
 /**
  * Container for managing keyed list blocks
  */
-export interface KeyedListContainer<T = unknown> {
+interface KeyedListContainer<T = unknown> {
   /** Start marker comment node */
   startMarker: Comment
   /** End marker comment node */
@@ -102,15 +102,6 @@ type FineGrainedRenderItem<T> = (
   key: string | number,
 ) => Node[]
 
-/**
- * A block identified by start/end comment markers.
- */
-export interface MarkerBlock {
-  start: Comment
-  end: Comment
-  root?: RootContext
-}
-
 // ============================================================================
 // DOM Manipulation Primitives
 // ============================================================================
@@ -129,7 +120,8 @@ export function moveNodesBefore(parent: Node, nodes: Node[], anchor: Node | null
   for (let i = nodes.length - 1; i >= 0; i--) {
     const node = nodes[i]!
     if (!node || !(node instanceof Node)) {
-      throw new Error('Invalid node in moveNodesBefore')
+      const message = isDev ? 'Invalid node in moveNodesBefore' : 'FICT:E_NODE'
+      throw new Error(message)
     }
     // Only move if not already in correct position
     if (node.nextSibling !== anchor) {
@@ -162,50 +154,6 @@ export function moveNodesBefore(parent: Node, nodes: Node[], anchor: Node | null
  *
  * @param nodes - Array of nodes to remove
  */
-/**
- * Move an entire marker-delimited block (including markers) before the anchor.
- */
-export function moveMarkerBlock(parent: Node, block: MarkerBlock, anchor: Node | null): void {
-  const nodes = collectBlockNodes(block)
-  if (nodes.length === 0) return
-  moveNodesBefore(parent, nodes, anchor)
-}
-
-/**
- * Destroy a marker-delimited block, removing nodes and destroying the associated root.
- */
-export function destroyMarkerBlock(block: MarkerBlock): void {
-  if (block.root) {
-    destroyRoot(block.root)
-  }
-  removeBlockRange(block)
-}
-
-function collectBlockNodes(block: MarkerBlock): Node[] {
-  const nodes: Node[] = []
-  let cursor: Node | null = block.start
-  while (cursor) {
-    nodes.push(cursor)
-    if (cursor === block.end) {
-      break
-    }
-    cursor = cursor.nextSibling
-  }
-  return nodes
-}
-
-function removeBlockRange(block: MarkerBlock): void {
-  let cursor: Node | null = block.start
-  while (cursor) {
-    const next: Node | null = cursor.nextSibling
-    cursor.parentNode?.removeChild(cursor)
-    if (cursor === block.end) {
-      break
-    }
-    cursor = next
-  }
-}
-
 // Number.MAX_SAFE_INTEGER is 2^53 - 1, but we reset earlier to avoid any precision issues
 const MAX_SAFE_VERSION = 0x1fffffffffffff // 2^53 - 1
 
@@ -238,7 +186,7 @@ export function createVersionedSignalAccessor<T>(initialValue: T): Signal<T> {
  *
  * @returns Container object with markers, blocks map, and dispose function
  */
-export function createKeyedListContainer<T = unknown>(): KeyedListContainer<T> {
+function createKeyedListContainer<T = unknown>(): KeyedListContainer<T> {
   const startMarker = document.createComment('fict:list:start')
   const endMarker = document.createComment('fict:list:end')
 
@@ -306,7 +254,7 @@ export function createKeyedListContainer<T = unknown>(): KeyedListContainer<T> {
  * @param render - Function that creates the DOM nodes and sets up bindings
  * @returns New KeyedBlock
  */
-export function createKeyedBlock<T>(
+function createKeyedBlock<T>(
   key: string | number,
   item: T,
   index: number,
@@ -377,13 +325,6 @@ export function createKeyedBlock<T>(
 // Utilities
 // ============================================================================
 
-/**
- * Find the first node after the start marker (for getting current anchor)
- */
-export function getFirstNodeAfter(marker: Comment): Node | null {
-  return marker.nextSibling
-}
-
 /**
  * Check if a node is between two markers
  */

package/src/props.ts

@@ -122,38 +122,46 @@ export function mergeProps<T extends Record<string, unknown>>(
     return unwrapProps(value as T)
   }
 
+  const hasProp = (prop: string | symbol) => {
+    for (const src of validSources) {
+      const raw = resolveSource(src)
+      if (raw && prop in raw) {
+        return true
+      }
+    }
+    return false
+  }
+
+  const readProp = (prop: string | symbol) => {
+    // Only return undefined if no source has this Symbol property
+    // Search sources in reverse order (last wins)
+    for (let i = validSources.length - 1; i >= 0; i--) {
+      const src = validSources[i]!
+      const raw = resolveSource(src)
+      if (!raw || !(prop in raw)) continue
+
+      const value = (raw as Record<string | symbol, unknown>)[prop]
+      // Preserve prop getters - let child component's createPropsProxy unwrap lazily
+      // Note: For Symbol properties, we still wrap in getter if source is dynamic
+      if (typeof src === 'function' && !isPropGetter(value)) {
+        return __fictProp(() => {
+          const latest = resolveSource(src)
+          if (!latest || !(prop in latest)) return undefined
+          return (latest as Record<string | symbol, unknown>)[prop]
+        })
+      }
+      return value
+    }
+    return undefined
+  }
+
   return new Proxy({} as Record<string, unknown>, {
     get(_, prop) {
-      // Only return undefined if no source has this Symbol property
-      // Search sources in reverse order (last wins)
-      for (let i = validSources.length - 1; i >= 0; i--) {
-        const src = validSources[i]!
-        const raw = resolveSource(src)
-        if (!raw || !(prop in raw)) continue
-
-        const value = (raw as Record<string | symbol, unknown>)[prop]
-        // Preserve prop getters - let child component's createPropsProxy unwrap lazily
-        // Note: For Symbol properties, we still wrap in getter if source is dynamic
-        if (typeof src === 'function' && !isPropGetter(value)) {
-          return __fictProp(() => {
-            const latest = resolveSource(src)
-            if (!latest || !(prop in latest)) return undefined
-            return (latest as Record<string | symbol, unknown>)[prop]
-          })
-        }
-        return value
-      }
-      return undefined
+      return readProp(prop)
     },
 
     has(_, prop) {
-      for (const src of validSources) {
-        const raw = resolveSource(src)
-        if (raw && prop in raw) {
-          return true
-        }
-      }
-      return false
+      return hasProp(prop)
     },
 
     ownKeys() {
@@ -170,21 +178,12 @@ export function mergeProps<T extends Record<string, unknown>>(
     },
 
     getOwnPropertyDescriptor(_, prop) {
-      for (let i = validSources.length - 1; i >= 0; i--) {
-        const raw = resolveSource(validSources[i]!)
-        if (raw && prop in raw) {
-          return {
-            enumerable: true,
-            configurable: true,
-            get: () => {
-              const value = (raw as Record<string | symbol, unknown>)[prop]
-              // Preserve prop getters - let child component's createPropsProxy unwrap lazily
-              return value
-            },
-          }
-        }
+      if (!hasProp(prop)) return undefined
+      return {
+        enumerable: true,
+        configurable: true,
+        get: () => readProp(prop),
       }
-      return undefined
     },
   })
 }
@@ -192,19 +191,22 @@ export function mergeProps<T extends Record<string, unknown>>(
 export type PropGetter<T> = (() => T) & { __fictProp: true }
 /**
  * Memoize a prop getter to cache expensive computations.
- * Use when prop expressions involve heavy calculations.
+ * Use when prop expressions involve heavy calculations or you need lazy, reactive props.
  *
  * @example
  * ```tsx
- * // Without useProp - recomputes on every access
+ * // Without prop - recomputes on every access
  * <Child data={expensiveComputation(list, filter)} />
  *
- * // With useProp - cached until dependencies change, auto-unwrapped by props proxy
- * const memoizedData = useProp(() => expensiveComputation(list, filter))
+ * // With prop - cached until dependencies change, auto-unwrapped by props proxy
+ * const memoizedData = prop(() => expensiveComputation(list, filter))
  * <Child data={memoizedData} />
  * ```
  */
-export function useProp<T>(getter: () => T): PropGetter<T> {
+export function prop<T>(getter: () => T): PropGetter<T> {
+  if (isPropGetter(getter)) {
+    return getter as PropGetter<T>
+  }
   // Wrap in prop so component props proxy auto-unwraps when passed down.
   return __fictProp(createMemo(getter)) as PropGetter<T>
 }