@fictjs/runtime 0.3.0 → 0.5.0

package/src/hydration.ts

@@ -0,0 +1,75 @@
+interface HydrationContext {
+  cursor: Node | null
+  boundary: Node | null
+  owner: Document
+}
+
+const hydrationStack: HydrationContext[] = []
+
+export function withHydration(root: ParentNode & Node, fn: () => void): void {
+  const owner = root.ownerDocument ?? document
+  hydrationStack.push({
+    cursor: root.firstChild,
+    boundary: null,
+    owner,
+  })
+  try {
+    fn()
+  } finally {
+    hydrationStack.pop()
+  }
+}
+
+export function withHydrationRange(
+  start: Node | null,
+  end: Node | null,
+  owner: Document,
+  fn: () => void,
+): void {
+  hydrationStack.push({
+    cursor: start,
+    boundary: end,
+    owner,
+  })
+  try {
+    fn()
+  } finally {
+    hydrationStack.pop()
+  }
+}
+
+export function claimNodes(templateRoot: Node, fallback: () => Node): Node {
+  const ctx = hydrationStack[hydrationStack.length - 1]
+  if (!ctx || !ctx.cursor) {
+    return fallback()
+  }
+
+  const count = templateRoot.nodeType === 11 ? templateRoot.childNodes.length : 1
+  if (count === 0) return fallback()
+
+  const claimed: Node[] = []
+  let cursor: Node | null = ctx.cursor
+  for (let i = 0; i < count; i++) {
+    if (!cursor || cursor === ctx.boundary) {
+      return fallback()
+    }
+    claimed.push(cursor)
+    cursor = cursor.nextSibling
+  }
+
+  ctx.cursor = cursor
+
+  if (claimed.length === 1) {
+    return claimed[0]!
+  }
+
+  const frag = ctx.owner.createDocumentFragment()
+  for (const node of claimed) {
+    frag.appendChild(node)
+  }
+  return frag
+}
+
+export function isHydratingActive(): boolean {
+  return hydrationStack.length > 0
+}

package/src/internal.ts

@@ -13,7 +13,7 @@
 // ============================================================================
 
 export { createSignal, createSelector, __resetReactiveState } from './signal'
-export { createStore, type Store } from './store'
+export { createStore, type Store, isStoreProxy, unwrapStore } from './store'
 export { createMemo } from './memo'
 export { createEffect } from './effect'
 export { Fragment } from './jsx'
@@ -31,8 +31,38 @@ export {
   __fictUseEffect,
   __fictRender,
   __fictResetContext,
+  __fictPrepareContext,
 } from './hooks'
 
+// ============================================================================
+// SSR / Resumability (Internal)
+// ============================================================================
+
+export {
+  __fictEnableSSR,
+  __fictDisableSSR,
+  __fictIsSSR,
+  __fictEnableResumable,
+  __fictDisableResumable,
+  __fictIsResumable,
+  __fictEnterHydration,
+  __fictExitHydration,
+  __fictIsHydrating,
+  __fictRegisterScope,
+  __fictGetScopeRegistry,
+  __fictSerializeSSRState,
+  __fictSetSSRState,
+  __fictGetSSRScope,
+  __fictEnsureScope,
+  __fictUseLexicalScope,
+  __fictGetScopeProps,
+  __fictQrl,
+  __fictRegisterResume,
+  __fictGetResume,
+  serializeValue,
+  deserializeValue,
+} from './resume'
+
 // ============================================================================
 // Props Helpers (Compiler-generated code)
 // ============================================================================
@@ -53,6 +83,7 @@ export {
   bindProperty,
   bindRef,
   insert,
+  insertBetween,
   createConditional,
   createPortal,
   spread,
@@ -61,6 +92,7 @@ export {
   isReactive,
   unwrap,
 } from './binding'
+export { resolvePath, getSlotEnd } from './node-ops'
 
 // ============================================================================
 // Event Delegation (Compiler-generated code)
@@ -86,7 +118,7 @@ export {
 // DOM Creation (Compiler-generated code)
 // ============================================================================
 
-export { createElement, template } from './dom'
+export { createElement, template, render, hydrateComponent } from './dom'
 export { createRenderEffect } from './effect'
 
 // ============================================================================

package/src/list-helpers.ts

@@ -7,6 +7,7 @@
 
 import { createElement } from './dom'
 import { createRenderEffect } from './effect'
+import { isHydratingActive, withHydrationRange } from './hydration'
 import {
   createRootContext,
   destroyRoot,
@@ -18,6 +19,7 @@ import {
 } from './lifecycle'
 import { insertNodesBefore, removeNodes, toNodeArray } from './node-ops'
 import reconcileArrays from './reconcile'
+import { __fictIsHydrating, __fictIsSSR } from './resume'
 import { batch } from './scheduler'
 import { createSignal, effectScope, flush, setActiveSub, type Signal } from './signal'
 import type { FictNode } from './types'
@@ -85,7 +87,7 @@ interface KeyedListContainer<T = unknown> {
  */
 export interface KeyedListBinding {
   /** Document fragment placeholder inserted by the compiler/runtime */
-  marker: DocumentFragment
+  marker: Comment | DocumentFragment
   /** Start marker comment node */
   startMarker: Comment
   /** End marker comment node */
@@ -195,9 +197,12 @@ export function createVersionedSignalAccessor<T>(initialValue: T): Signal<T> {
  *
  * @returns Container object with markers, blocks map, and dispose function
  */
-function createKeyedListContainer<T = unknown>(): KeyedListContainer<T> {
-  const startMarker = document.createComment('fict:list:start')
-  const endMarker = document.createComment('fict:list:end')
+function createKeyedListContainer<T = unknown>(
+  startOverride?: Comment,
+  endOverride?: Comment,
+): KeyedListContainer<T> {
+  const startMarker = startOverride ?? document.createComment('fict:list:start')
+  const endMarker = endOverride ?? document.createComment('fict:list:end')
 
   const dispose = () => {
     // Clean up all blocks
@@ -464,32 +469,57 @@ function reorderByLIS<T>(
  * @param renderItem - Function that creates DOM nodes for each item
  * @returns Binding handle with markers and dispose function
  */
-export function createKeyedList<T>(
+export function createKeyedList<T extends object>(
   getItems: () => T[],
   keyFn: (item: T, index: number) => string | number,
   renderItem: FineGrainedRenderItem<T>,
   needsIndex?: boolean,
+  startMarker?: Comment,
+  endMarker?: Comment,
 ): KeyedListBinding {
   const resolvedNeedsIndex =
     arguments.length >= 4 ? !!needsIndex : renderItem.length > 1 /* has index param */
-  return createFineGrainedKeyedList(getItems, keyFn, renderItem, resolvedNeedsIndex)
+  return createFineGrainedKeyedList(
+    getItems,
+    keyFn,
+    renderItem,
+    resolvedNeedsIndex,
+    startMarker,
+    endMarker,
+  )
 }
 
-function createFineGrainedKeyedList<T>(
+function createFineGrainedKeyedList<T extends object>(
   getItems: () => T[],
   keyFn: (item: T, index: number) => string | number,
   renderItem: FineGrainedRenderItem<T>,
   needsIndex: boolean,
+  startOverride?: Comment,
+  endOverride?: Comment,
 ): KeyedListBinding {
-  const container = createKeyedListContainer<T>()
+  const container = createKeyedListContainer<T>(startOverride, endOverride)
   const hostRoot = getCurrentRoot()
-  const fragment = document.createDocumentFragment()
-  fragment.append(container.startMarker, container.endMarker)
+  const useProvided = !!(startOverride && endOverride)
+  const fragment = useProvided ? container.startMarker : document.createDocumentFragment()
+  if (!useProvided) {
+    ;(fragment as DocumentFragment).append(container.startMarker, container.endMarker)
+  }
   let disposed = false
   let effectDispose: (() => void) | undefined
   let connectObserver: MutationObserver | null = null
   let effectStarted = false
   let startScheduled = false
+  let initialHydrating = __fictIsHydrating()
+
+  const collectBetween = (): Node[] => {
+    const nodes: Node[] = []
+    let cursor = container.startMarker.nextSibling
+    while (cursor && cursor !== container.endMarker) {
+      nodes.push(cursor)
+      cursor = cursor.nextSibling
+    }
+    return nodes
+  }
 
   const getConnectedParent = (): (ParentNode & Node) | null => {
     const endParent = container.endMarker.parentNode
@@ -509,7 +539,11 @@ function createFineGrainedKeyedList<T>(
 
   const performDiff = () => {
     if (disposed) return
-    const parent = getConnectedParent()
+    // During SSR, render synchronously without waiting for DOM connection
+    const isSSR = __fictIsSSR()
+    const parent = isSSR
+      ? (container.startMarker.parentNode as (ParentNode & Node) | null)
+      : getConnectedParent()
     if (!parent) return
     batch(() => {
       const oldBlocks = container.blocks
@@ -519,6 +553,69 @@ function createFineGrainedKeyedList<T>(
       const orderedIndexByKey = container.orderedIndexByKey
       const newItems = getItems()
 
+      if (initialHydrating && isHydratingActive()) {
+        initialHydrating = false
+        newBlocks.clear()
+        nextOrderedBlocks.length = 0
+        orderedIndexByKey.clear()
+
+        if (newItems.length === 0) {
+          oldBlocks.clear()
+          prevOrderedBlocks.length = 0
+          container.currentNodes = [container.startMarker, container.endMarker]
+          container.nextNodes.length = 0
+          return
+        }
+
+        const createdBlocks: KeyedBlock<T>[] = []
+        withHydrationRange(
+          container.startMarker.nextSibling,
+          container.endMarker,
+          parent.ownerDocument ?? document,
+          () => {
+            for (let index = 0; index < newItems.length; index++) {
+              const item = newItems[index]!
+              const key = keyFn(item, index)
+              if (newBlocks.has(key)) {
+                if (isDev) {
+                  console.warn(
+                    `[fict] Duplicate key "${String(key)}" detected in list hydration. ` +
+                      `Each item should have a unique key.`,
+                  )
+                }
+                const existing = newBlocks.get(key)
+                if (existing) {
+                  destroyRoot(existing.root)
+                  removeNodes(existing.nodes)
+                }
+              }
+              const block = createKeyedBlock(key, item, index, renderItem, needsIndex, hostRoot)
+              createdBlocks.push(block)
+              newBlocks.set(key, block)
+              orderedIndexByKey.set(key, nextOrderedBlocks.length)
+              nextOrderedBlocks.push(block)
+            }
+          },
+        )
+
+        container.blocks = newBlocks
+        container.nextBlocks = oldBlocks
+        container.orderedBlocks = nextOrderedBlocks
+        container.nextOrderedBlocks = prevOrderedBlocks
+        oldBlocks.clear()
+        prevOrderedBlocks.length = 0
+        container.currentNodes = [container.startMarker, ...collectBetween(), container.endMarker]
+        container.nextNodes.length = 0
+
+        for (const block of createdBlocks) {
+          if (newBlocks.get(block.key) === block) {
+            flushOnMount(block.root)
+          }
+        }
+
+        return
+      }
+
       if (newItems.length === 0) {
         if (oldBlocks.size > 0) {
           // Destroy all block roots first
@@ -803,7 +900,11 @@ function createFineGrainedKeyedList<T>(
 
   const ensureEffectStarted = (): boolean => {
     if (disposed || effectStarted) return effectStarted
-    const parent = getConnectedParent()
+    // During SSR, render synchronously without waiting for DOM connection
+    const isSSR = __fictIsSSR()
+    const parent = isSSR
+      ? (container.startMarker.parentNode as (ParentNode & Node) | null)
+      : getConnectedParent()
     if (!parent) return false
     const start = () => {
       effectDispose = createRenderEffect(performDiff)