@fictjs/runtime 0.3.0 → 0.5.0

package/dist/signal-C4ISF17w.d.cts

@@ -0,0 +1,66 @@
+/**
+ * Options for creating a signal
+ */
+interface SignalOptions<T> {
+    /** Custom equality check */
+    equals?: false | ((prev: T, next: T) => boolean);
+    /** Debug name */
+    name?: string;
+    /** Source location */
+    devToolsSource?: string;
+}
+/**
+ * Options for creating a memo
+ */
+interface MemoOptions<T> {
+    /** Custom equality check */
+    equals?: false | ((prev: T, next: T) => boolean);
+    /** Debug name */
+    name?: string;
+    /** Source location */
+    devToolsSource?: string;
+}
+/**
+ * Signal accessor - function to get/set signal value
+ */
+interface SignalAccessor<T> {
+    (): T;
+    (value: T): void;
+}
+/**
+ * Computed accessor - function to get computed value
+ */
+type ComputedAccessor<T> = () => T;
+/**
+ * Effect scope disposer - function to dispose an effect scope
+ */
+type EffectScopeDisposer = () => void;
+/**
+ * Create a reactive signal
+ * @param initialValue - The initial value
+ * @returns A signal accessor function
+ */
+declare function signal<T>(initialValue: T, options?: SignalOptions<T>): SignalAccessor<T>;
+/**
+ * Create a reactive effect scope
+ * @param fn - The scope function
+ * @returns An effect scope disposer function
+ */
+declare function effectScope(fn: () => void): EffectScopeDisposer;
+/**
+ * Reset all global reactive state for test isolation.
+ * ONLY use this in test setup/teardown - never in production code.
+ * This clears effect queues, resets batch depth, and clears pending flushes.
+ */
+declare function __resetReactiveState(): void;
+/**
+ * Create a selector signal that efficiently updates only when the selected key matches.
+ * Useful for large lists where only one item is selected.
+ *
+ * @param source - The source signal returning the current key
+ * @param equalityFn - Optional equality function
+ * @returns A selector function that takes a key and returns a boolean signal accessor
+ */
+declare function createSelector<T>(source: () => T, equalityFn?: (a: T, b: T) => boolean): (key: T) => boolean;
+
+export { type ComputedAccessor as C, type MemoOptions as M, type SignalAccessor as S, __resetReactiveState as _, type SignalOptions as a, createSelector as c, effectScope as e, signal as s };

package/dist/signal-C4ISF17w.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Options for creating a signal
+ */
+interface SignalOptions<T> {
+    /** Custom equality check */
+    equals?: false | ((prev: T, next: T) => boolean);
+    /** Debug name */
+    name?: string;
+    /** Source location */
+    devToolsSource?: string;
+}
+/**
+ * Options for creating a memo
+ */
+interface MemoOptions<T> {
+    /** Custom equality check */
+    equals?: false | ((prev: T, next: T) => boolean);
+    /** Debug name */
+    name?: string;
+    /** Source location */
+    devToolsSource?: string;
+}
+/**
+ * Signal accessor - function to get/set signal value
+ */
+interface SignalAccessor<T> {
+    (): T;
+    (value: T): void;
+}
+/**
+ * Computed accessor - function to get computed value
+ */
+type ComputedAccessor<T> = () => T;
+/**
+ * Effect scope disposer - function to dispose an effect scope
+ */
+type EffectScopeDisposer = () => void;
+/**
+ * Create a reactive signal
+ * @param initialValue - The initial value
+ * @returns A signal accessor function
+ */
+declare function signal<T>(initialValue: T, options?: SignalOptions<T>): SignalAccessor<T>;
+/**
+ * Create a reactive effect scope
+ * @param fn - The scope function
+ * @returns An effect scope disposer function
+ */
+declare function effectScope(fn: () => void): EffectScopeDisposer;
+/**
+ * Reset all global reactive state for test isolation.
+ * ONLY use this in test setup/teardown - never in production code.
+ * This clears effect queues, resets batch depth, and clears pending flushes.
+ */
+declare function __resetReactiveState(): void;
+/**
+ * Create a selector signal that efficiently updates only when the selected key matches.
+ * Useful for large lists where only one item is selected.
+ *
+ * @param source - The source signal returning the current key
+ * @param equalityFn - Optional equality function
+ * @returns A selector function that takes a key and returns a boolean signal accessor
+ */
+declare function createSelector<T>(source: () => T, equalityFn?: (a: T, b: T) => boolean): (key: T) => boolean;
+
+export { type ComputedAccessor as C, type MemoOptions as M, type SignalAccessor as S, __resetReactiveState as _, type SignalOptions as a, createSelector as c, effectScope as e, signal as s };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fictjs/runtime",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Fict reactive runtime",
   "publishConfig": {
     "access": "public",
@@ -12,8 +12,6 @@
     "signals",
     "ui"
   ],
-  "author": "Michael Lin",
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/fictjs/fict.git",
@@ -40,6 +38,11 @@
       "import": "./dist/advanced.js",
       "require": "./dist/advanced.cjs"
     },
+    "./loader": {
+      "types": "./dist/loader.d.ts",
+      "import": "./dist/loader.js",
+      "require": "./dist/loader.cjs"
+    },
     "./jsx-runtime": {
       "types": "./dist/jsx-runtime.d.ts",
       "import": "./dist/jsx-runtime.js",
@@ -59,6 +62,8 @@
     "jsdom": "^27.4.0",
     "tsup": "^8.5.1"
   },
+  "author": "unadlib",
+  "license": "MIT",
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",

package/src/binding.ts

@@ -21,6 +21,7 @@ import {
   SVGNamespace,
 } from './constants'
 import { createRenderEffect } from './effect'
+import { withHydrationRange, isHydratingActive } from './hydration'
 import { Fragment } from './jsx'
 import {
   createRootContext,
@@ -35,6 +36,7 @@ import {
   type RootContext,
 } from './lifecycle'
 import { toNodeArray, removeNodes, insertNodesBefore } from './node-ops'
+import { __fictIsHydrating } from './resume'
 import { batch } from './scheduler'
 import { computed, untrack, isSignal, isComputed, isEffect, isEffectScope } from './signal'
 import type { Cleanup, FictNode } from './types'
@@ -716,6 +718,180 @@ export function insert(
   }
 }
 
+/**
+ * Insert reactive content between two marker comments.
+ * Supports hydration by claiming existing nodes between markers.
+ */
+export function insertBetween(
+  start: Comment,
+  end: Comment,
+  getValue: () => FictNode,
+  createElementFn?: CreateElementFn,
+): Cleanup {
+  const hostRoot = getCurrentRoot()
+  let currentNodes: Node[] = []
+  let currentText: Text | null = null
+  let currentRoot: RootContext | null = null
+  let initialHydrating = __fictIsHydrating()
+
+  const collectBetween = (): Node[] => {
+    const nodes: Node[] = []
+    let cursor = start.nextSibling
+    while (cursor && cursor !== end) {
+      nodes.push(cursor)
+      cursor = cursor.nextSibling
+    }
+    return nodes
+  }
+
+  const clearCurrentNodes = () => {
+    if (currentNodes.length > 0) {
+      removeNodes(currentNodes)
+      currentNodes = []
+    }
+  }
+
+  const setTextNode = (textValue: string, shouldInsert: boolean) => {
+    if (!currentText) {
+      currentText = document.createTextNode(textValue)
+    } else if (currentText.data !== textValue) {
+      currentText.data = textValue
+    }
+
+    if (!shouldInsert) {
+      clearCurrentNodes()
+      return
+    }
+
+    if (currentNodes.length === 1 && currentNodes[0] === currentText) {
+      return
+    }
+
+    clearCurrentNodes()
+    const parentNode = start.parentNode as (ParentNode & Node) | null
+    if (parentNode) {
+      insertNodesBefore(parentNode, [currentText], end)
+      currentNodes = [currentText]
+    }
+  }
+
+  const dispose = createRenderEffect(() => {
+    const value = getValue()
+    const parentNode = start.parentNode as (ParentNode & Node) | null
+    const isPrimitive =
+      value == null ||
+      value === false ||
+      typeof value === 'string' ||
+      typeof value === 'number' ||
+      typeof value === 'boolean'
+
+    if (isPrimitive) {
+      if (initialHydrating && isHydratingActive() && parentNode) {
+        const existing = collectBetween()
+        if (existing.length > 0) {
+          currentNodes = existing
+          const only = existing.length === 1 ? existing[0] : null
+          currentText = only && only.nodeType === 3 ? (only as Text) : null
+        }
+      }
+      if (currentRoot) {
+        destroyRoot(currentRoot)
+        currentRoot = null
+      }
+      if (!parentNode) {
+        clearCurrentNodes()
+        return
+      }
+      const textValue = value == null || value === false ? '' : String(value)
+      const shouldInsert = value != null && value !== false
+      setTextNode(textValue, shouldInsert)
+      initialHydrating = false
+      return
+    }
+
+    if (currentRoot) {
+      destroyRoot(currentRoot)
+      currentRoot = null
+    }
+    clearCurrentNodes()
+
+    const root = createRootContext(hostRoot)
+    const prev = pushRoot(root)
+    let nodes: Node[] = []
+    let handledError = false
+    try {
+      let newNode: Node | Node[] = undefined as unknown as Node | Node[]
+      const createValue = () => {
+        if (value instanceof Node) {
+          return value
+        }
+        if (Array.isArray(value)) {
+          if (value.every(v => v instanceof Node)) {
+            return value as Node[]
+          }
+          if (createElementFn) {
+            const mapped: Node[] = []
+            for (const item of value) {
+              mapped.push(...toNodeArray(createElementFn(item as any)))
+            }
+            return mapped
+          }
+          return document.createTextNode(String(value))
+        }
+        return createElementFn ? createElementFn(value) : document.createTextNode(String(value))
+      }
+
+      if (initialHydrating && isHydratingActive() && parentNode) {
+        withHydrationRange(start.nextSibling, end, parentNode.ownerDocument ?? document, () => {
+          newNode = createValue()
+        })
+      } else {
+        newNode = createValue()
+      }
+
+      nodes = toNodeArray(newNode)
+      if (root.suspended) {
+        handledError = true
+        destroyRoot(root)
+        return
+      }
+      if (parentNode && !initialHydrating) {
+        insertNodesBefore(parentNode, nodes, end)
+      }
+    } catch (err) {
+      if (handleSuspend(err as any, root)) {
+        handledError = true
+        destroyRoot(root)
+        return
+      }
+      if (handleError(err, { source: 'renderChild' }, root)) {
+        handledError = true
+        destroyRoot(root)
+        return
+      }
+      throw err
+    } finally {
+      popRoot(prev)
+      if (!handledError) {
+        flushOnMount(root)
+      }
+    }
+
+    currentRoot = root
+    currentNodes = initialHydrating ? collectBetween() : nodes
+    initialHydrating = false
+  })
+
+  return () => {
+    dispose()
+    if (currentRoot) {
+      destroyRoot(currentRoot)
+      currentRoot = null
+    }
+    clearCurrentNodes()
+  }
+}
+
 /**
  * Create a reactive child binding that updates when the child value changes.
  * This is used for dynamic expressions like `{show && <Modal />}` or `{items.map(...)}`.
@@ -1299,7 +1475,11 @@ function assignProp(
   // Event handling: on:eventname
   if (prop.slice(0, 3) === 'on:') {
     const eventName = prop.slice(3)
-    if (prev) node.removeEventListener(eventName, prev as EventListener)
+    if (typeof value === 'string') {
+      node.setAttribute(prop, value)
+      return value
+    }
+    if (prev && typeof prev !== 'string') node.removeEventListener(eventName, prev as EventListener)
     if (value) node.addEventListener(eventName, value as EventListener)
     return value
   }
@@ -1433,17 +1613,33 @@ export function createConditional(
   renderTrue: () => FictNode,
   createElementFn: CreateElementFn,
   renderFalse?: () => FictNode,
+  startOverride?: Comment,
+  endOverride?: Comment,
 ): BindingHandle {
-  const startMarker = document.createComment('fict:cond:start')
-  const endMarker = document.createComment('fict:cond:end')
-  const fragment = document.createDocumentFragment()
-  fragment.append(startMarker, endMarker)
+  const useProvided = !!(startOverride && endOverride)
+  const startMarker = useProvided ? startOverride! : document.createComment('fict:cond:start')
+  const endMarker = useProvided ? endOverride! : document.createComment('fict:cond:end')
+  const fragment = useProvided ? startMarker : document.createDocumentFragment()
+  if (!useProvided) {
+    ;(fragment as DocumentFragment).append(startMarker, endMarker)
+  }
   const hostRoot = getCurrentRoot()
 
   let currentNodes: Node[] = []
   let currentRoot: RootContext | null = null
   let lastCondition: boolean | undefined = undefined
   let pendingRender = false
+  let initialHydrating = __fictIsHydrating()
+
+  const collectBetween = (): Node[] => {
+    const nodes: Node[] = []
+    let cursor = startMarker.nextSibling
+    while (cursor && cursor !== endMarker) {
+      nodes.push(cursor)
+      cursor = cursor.nextSibling
+    }
+    return nodes
+  }
 
   // Use computed to memoize condition value - this prevents the effect from
   // re-running when condition dependencies change but the boolean result stays same.
@@ -1460,6 +1656,59 @@ export function createConditional(
     }
     pendingRender = false
 
+    if (initialHydrating && isHydratingActive()) {
+      initialHydrating = false
+      lastCondition = cond
+
+      const render = cond ? renderTrue : renderFalse
+      if (!render) {
+        currentNodes = collectBetween()
+        return
+      }
+
+      const root = createRootContext(hostRoot)
+      const prev = pushRoot(root)
+      let handledError = false
+      try {
+        // Call render() INSIDE withHydrationRange so that template() and insertBetween
+        // see the correct hydration context for the conditional content
+        withHydrationRange(
+          startMarker.nextSibling,
+          endMarker,
+          parent.ownerDocument ?? document,
+          () => {
+            const output = untrack(render)
+            if (output == null || output === false) {
+              return
+            }
+            createElementFn(output)
+          },
+        )
+        currentNodes = collectBetween()
+      } catch (err) {
+        if (handleSuspend(err as any, root)) {
+          handledError = true
+          destroyRoot(root)
+          return
+        }
+        if (handleError(err, { source: 'renderChild' }, root)) {
+          handledError = true
+          destroyRoot(root)
+          return
+        }
+        throw err
+      } finally {
+        popRoot(prev)
+        if (!handledError) {
+          flushOnMount(root)
+          currentRoot = root
+        } else {
+          currentRoot = null
+        }
+      }
+      return
+    }
+
     if (lastCondition === cond && currentNodes.length > 0) {
       return
     }

package/src/dom.ts

@@ -27,6 +27,7 @@ import {
 import { Properties, ChildProperties, getPropAlias, SVGElements, SVGNamespace } from './constants'
 import { getDevtoolsHook } from './devtools'
 import { __fictPushContext, __fictPopContext, __fictGetCurrentComponentId } from './hooks'
+import { claimNodes, isHydratingActive, withHydration } from './hydration'
 import { Fragment } from './jsx'
 import {
   createRootContext,
@@ -42,6 +43,13 @@ import {
   onCleanup,
 } from './lifecycle'
 import { createPropsProxy, unwrapProps } from './props'
+import {
+  __fictIsHydrating,
+  __fictIsResumable,
+  __fictRegisterScope,
+  __fictEnterHydration,
+  __fictExitHydration,
+} from './resume'
 import { untrack } from './scheduler'
 import type { DOMElement, FictNode, FictVNode, RefObject } from './types'
 
@@ -76,17 +84,25 @@ let nextComponentId = 1
 export function render(view: () => FictNode, container: HTMLElement): () => void {
   const root = createRootContext()
   const prev = pushRoot(root)
-  let dom: DOMElement
+  let dom: DOMElement = undefined as unknown as DOMElement
   try {
     const output = view()
     // createElement must be called within the root context
     // so that child components register their onMount callbacks correctly
-    dom = createElement(output)
+    if (__fictIsHydrating()) {
+      withHydration(container, () => {
+        dom = createElement(output)
+      })
+    } else {
+      dom = createElement(output)
+    }
   } finally {
     popRoot(prev)
   }
 
-  container.replaceChildren(dom)
+  if (!__fictIsHydrating()) {
+    container.replaceChildren(dom)
+  }
   container.setAttribute('data-fict-fine-grained', '1')
 
   flushOnMount(root)
@@ -99,6 +115,42 @@ export function render(view: () => FictNode, container: HTMLElement): () => void
   return teardown
 }
 
+/**
+ * Hydrate a component into an existing DOM container.
+ * Unlike render(), this runs the view function INSIDE the hydration context
+ * so that template() can claim existing DOM nodes.
+ *
+ * @param view - A function that returns the view to hydrate
+ * @param container - The DOM container with existing SSR content
+ * @returns A teardown function to unmount the view
+ */
+export function hydrateComponent(view: () => FictNode, container: HTMLElement): () => void {
+  const root = createRootContext()
+  const prev = pushRoot(root)
+
+  // Enable hydration flags for bindings that check __fictIsHydrating()
+  __fictEnterHydration()
+
+  try {
+    // Run the view function INSIDE withHydration so template() can claim nodes
+    withHydration(container, () => {
+      view()
+    })
+  } finally {
+    __fictExitHydration()
+    popRoot(prev)
+  }
+
+  container.setAttribute('data-fict-fine-grained', '1')
+  flushOnMount(root)
+
+  const teardown = () => {
+    destroyRoot(root)
+  }
+
+  return teardown
+}
+
 // ============================================================================
 // Element Creation
 // ============================================================================
@@ -140,6 +192,15 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
     return document.createTextNode('')
   }
 
+  // Reactive getter function - resolve to actual node
+  if (isReactive(node)) {
+    const resolved = (node as () => FictNode)()
+    if (resolved === node) {
+      return document.createTextNode('')
+    }
+    return createElementWithContext(resolved, namespace)
+  }
+
   if (typeof node === 'object' && node !== null && !(node instanceof Node)) {
     // Handle BindingHandle (list/conditional bindings, etc)
     if ('marker' in node) {
@@ -241,6 +302,32 @@ function createElementWithContext(node: FictNode, namespace: NamespaceContext):
         })
         onCleanup(() => hook.componentUnmount?.(componentId))
       }
+      if (__fictIsResumable() && !__fictIsHydrating()) {
+        const content = createElementWithContext(rendered as FictNode, namespace)
+        const host =
+          namespace === 'svg'
+            ? document.createElementNS(SVG_NS, 'fict-host')
+            : namespace === 'mathml'
+              ? document.createElementNS(MATHML_NS, 'fict-host')
+              : document.createElement('fict-host')
+        host.setAttribute('data-fict-host', '')
+        if (namespace === null && (host as HTMLElement).style) {
+          ;(host as HTMLElement).style.display = 'contents'
+        }
+        const meta = (vnode.type as unknown as { __fictMeta?: { id?: string; resume?: string } })
+          .__fictMeta
+        const typeKey = (meta?.id ?? vnode.type.name) || 'Anonymous'
+        __fictRegisterScope(ctx, host, typeKey, rawProps)
+        if (meta?.resume) {
+          host.setAttribute('data-fict-h', meta.resume)
+        }
+        if (content instanceof DocumentFragment) {
+          host.append(...Array.from(content.childNodes))
+        } else {
+          host.appendChild(content)
+        }
+        return host as DOMElement
+      }
 
       return createElementWithContext(rendered as FictNode, namespace)
     } catch (err) {
@@ -359,8 +446,19 @@ export function template(
 
   // Create the cloning function
   const fn = isImportNode
-    ? () => untrack(() => document.importNode(node || (node = create()), true))
-    : () => (node || (node = create())).cloneNode(true)
+    ? () =>
+        untrack(() => {
+          const base = node || (node = create())
+          return isHydratingActive()
+            ? claimNodes(base, () => document.importNode(base, true))
+            : document.importNode(base, true)
+        })
+    : () => {
+        const base = node || (node = create())
+        return isHydratingActive()
+          ? claimNodes(base, () => base.cloneNode(true))
+          : base.cloneNode(true)
+      }
 
   // Add cloneNode property for compatibility
   ;(fn as { cloneNode?: typeof fn }).cloneNode = fn

package/src/hooks.ts

@@ -13,15 +13,19 @@ const isDev =
     ? __DEV__
     : typeof process === 'undefined' || process.env?.NODE_ENV !== 'production'
 
-interface HookContext {
+export interface HookContext {
   slots: unknown[]
   cursor: number
   rendering?: boolean
   componentId?: number
   parentId?: number
+  scopeId?: string
+  scopeType?: string
+  slotMap?: Record<string, number>
 }
 
 const ctxStack: HookContext[] = []
+let preparedContext: HookContext | null = null
 
 function assertRenderContext(ctx: HookContext, hookName: string): void {
   if (!ctx.rendering) {
@@ -54,11 +58,16 @@ export function __fictUseContext(): HookContext {
 }
 
 export function __fictPushContext(): HookContext {
-  const ctx: HookContext = { slots: [], cursor: 0 }
+  const ctx: HookContext = preparedContext ?? { slots: [], cursor: 0 }
+  preparedContext = null
   ctxStack.push(ctx)
   return ctx
 }
 
+export function __fictPrepareContext(ctx: HookContext): void {
+  preparedContext = ctx
+}
+
 export function __fictGetCurrentComponentId(): number | undefined {
   return ctxStack[ctxStack.length - 1]?.componentId
 }
@@ -86,6 +95,10 @@ export function __fictUseSignal<T>(
   if (!ctx.slots[index]) {
     ctx.slots[index] = createSignal(initial, options)
   }
+  if (options?.name) {
+    if (!ctx.slotMap) ctx.slotMap = {}
+    ctx.slotMap[options.name] = index
+  }
   return ctx.slots[index] as SignalAccessor<T>
 }