@fictjs/runtime 0.5.0 → 0.5.2

package/src/loader.ts

@@ -4,6 +4,7 @@ import {
   __fictEnsureScope,
   __fictGetResume,
   __fictGetSSRScope,
+  __fictMergeSSRState,
   __fictSetSSRState,
   __fictUseLexicalScope,
 } from './resume'
@@ -82,6 +83,8 @@ const hydratedScopes = new Set<string>()
 const prefetchedUrls = new Set<string>()
 let prefetchCleanup: (() => void) | null = null
 let eventListenerCleanup: (() => void) | null = null
+let snapshotObserver: MutationObserver | null = null
+const processedSnapshots = new Set<HTMLScriptElement>()
 
 /**
  * Reset the hydrated scopes set. Useful for testing.
@@ -131,6 +134,7 @@ export function installResumableLoader(options: ResumableLoaderOptions = {}): vo
   // Reset hydrated scopes for fresh loader installation
   hydratedScopes.clear()
   prefetchedUrls.clear()
+  processedSnapshots.clear()
 
   // Clean up previous event listeners
   if (eventListenerCleanup) {
@@ -144,6 +148,11 @@ export function installResumableLoader(options: ResumableLoaderOptions = {}): vo
     prefetchCleanup = null
   }
 
+  if (snapshotObserver) {
+    snapshotObserver.disconnect()
+    snapshotObserver = null
+  }
+
   const snapshotEl = doc.getElementById(scriptId)
   if (snapshotEl?.textContent) {
     try {
@@ -154,6 +163,38 @@ export function installResumableLoader(options: ResumableLoaderOptions = {}): vo
     }
   }
 
+  const snapshotScripts = doc.querySelectorAll(
+    'script[type="application/json"][data-fict-snapshot]',
+  )
+  for (const script of Array.from(snapshotScripts)) {
+    parseSnapshotScript(script as HTMLScriptElement)
+  }
+
+  if (typeof MutationObserver !== 'undefined') {
+    snapshotObserver = new MutationObserver(mutations => {
+      for (const mutation of mutations) {
+        for (const node of Array.from(mutation.addedNodes)) {
+          if (!(node instanceof Element)) continue
+          if (node.tagName === 'SCRIPT') {
+            const script = node as HTMLScriptElement
+            if (isSnapshotScript(script)) {
+              parseSnapshotScript(script)
+            }
+          }
+          const nested = node.querySelectorAll?.(
+            'script[type="application/json"][data-fict-snapshot]',
+          )
+          if (nested && nested.length) {
+            for (const script of Array.from(nested)) {
+              parseSnapshotScript(script as HTMLScriptElement)
+            }
+          }
+        }
+      }
+    })
+    snapshotObserver.observe(doc.documentElement ?? doc, { childList: true, subtree: true })
+  }
+
   __fictEnableResumable()
 
   const events = options.events ?? Array.from(DelegatedEvents)
@@ -174,6 +215,23 @@ export function installResumableLoader(options: ResumableLoaderOptions = {}): vo
   }
 }
 
+function isSnapshotScript(script: HTMLScriptElement): boolean {
+  return script.type === 'application/json' && script.hasAttribute('data-fict-snapshot')
+}
+
+function parseSnapshotScript(script: HTMLScriptElement): void {
+  if (processedSnapshots.has(script)) return
+  processedSnapshots.add(script)
+  const text = script.textContent
+  if (!text) return
+  try {
+    const state = JSON.parse(text)
+    __fictMergeSSRState(state)
+  } catch {
+    // Ignore parse errors
+  }
+}
+
 // ============================================================================
 // Prefetch Implementation
 // ============================================================================

package/src/resume.ts

@@ -1,5 +1,6 @@
 import type { HookContext } from './hooks'
 import { createSignal, isSignal } from './signal'
+import { __fictGetCurrentSSRBoundary } from './ssr-stream'
 import { createStore, isStoreProxy, unwrapStore } from './store'
 
 // ============================================================================
@@ -43,6 +44,7 @@ export interface ScopeRecord {
   id: string
   ctx: HookContext
   host: Element
+  boundaryId?: string
   type?: string
   props?: Record<string, unknown>
 }
@@ -52,6 +54,7 @@ let resumableEnabled = false
 let hydrating = false
 let scopeCounter = 0
 let scopeRegistry = new Map<string, ScopeRecord>()
+let boundaryScopes = new Map<string, Set<string>>()
 let snapshotState: SSRState | null = null
 const resumedScopes = new Map<
   string,
@@ -62,12 +65,14 @@ export function __fictEnableSSR(): void {
   ssrEnabled = true
   scopeCounter = 0
   scopeRegistry = new Map()
+  boundaryScopes = new Map()
   resumedScopes.clear()
   snapshotState = null
 }
 
 export function __fictDisableSSR(): void {
   ssrEnabled = false
+  boundaryScopes = new Map()
 }
 
 export function __fictEnableResumable(): void {
@@ -124,6 +129,16 @@ export function __fictRegisterScope(
   if (props !== undefined) {
     record.props = props
   }
+  const boundaryId = __fictGetCurrentSSRBoundary()
+  if (boundaryId) {
+    record.boundaryId = boundaryId
+    let scopes = boundaryScopes.get(boundaryId)
+    if (!scopes) {
+      scopes = new Set()
+      boundaryScopes.set(boundaryId, scopes)
+    }
+    scopes.add(id)
+  }
   scopeRegistry.set(id, record)
   return id
 }
@@ -132,6 +147,12 @@ export function __fictGetScopeRegistry(): Map<string, ScopeRecord> {
   return scopeRegistry
 }
 
+export function __fictGetScopesForBoundary(boundaryId: string): string[] {
+  const scopes = boundaryScopes.get(boundaryId)
+  if (!scopes) return []
+  return Array.from(scopes)
+}
+
 export function __fictSerializeSSRState(): SSRState {
   const scopes: Record<string, ScopeSnapshot> = {}
 
@@ -155,6 +176,31 @@ export function __fictSerializeSSRState(): SSRState {
   return { scopes }
 }
 
+export function __fictSerializeSSRStateForScopes(scopeIds: Iterable<string>): SSRState {
+  const scopes: Record<string, ScopeSnapshot> = {}
+
+  for (const id of scopeIds) {
+    const record = scopeRegistry.get(id)
+    if (!record) continue
+    const snapshot: ScopeSnapshot = {
+      id,
+      slots: serializeSlots(record.ctx),
+    }
+    if (record.type !== undefined) {
+      snapshot.t = record.type
+    }
+    if (record.props !== undefined) {
+      snapshot.props = record.props
+    }
+    if (record.ctx.slotMap !== undefined) {
+      snapshot.vars = record.ctx.slotMap
+    }
+    scopes[id] = snapshot
+  }
+
+  return { scopes }
+}
+
 export function __fictSetSSRState(state: SSRState | null): void {
   snapshotState = state
   if (!state) {
@@ -162,6 +208,15 @@ export function __fictSetSSRState(state: SSRState | null): void {
   }
 }
 
+export function __fictMergeSSRState(state: SSRState | null): void {
+  if (!state) return
+  if (!snapshotState) {
+    snapshotState = { scopes: { ...state.scopes } }
+    return
+  }
+  Object.assign(snapshotState.scopes, state.scopes)
+}
+
 export function __fictGetSSRScope(id: string): ScopeSnapshot | undefined {
   return snapshotState?.scopes[id]
 }

package/src/signal.ts

@@ -103,6 +103,10 @@ export interface SignalNode<T = unknown> extends BaseNode {
   currentValue: T
   /** Pending value to be committed */
   pendingValue: T
+  /** Previous committed value (for cleanup reads) */
+  prevValue?: T
+  /** Flush id when prevValue was recorded */
+  prevFlushId?: number
   /** Signals don't have dependencies */
   deps?: undefined
   depsTail?: undefined
@@ -123,6 +127,10 @@ export interface SignalNode<T = unknown> extends BaseNode {
 export interface ComputedNode<T = unknown> extends BaseNode {
   /** Current computed value */
   value: T
+  /** Previous computed value (for cleanup reads) */
+  prevValue?: T
+  /** Flush id when prevValue was recorded */
+  prevFlushId?: number
   /** First dependency link */
   deps: Link | undefined
   /** Last dependency link */
@@ -251,6 +259,8 @@ let cycle = 0
 let batchDepth = 0
 let activeSub: ReactiveNode | undefined
 let flushScheduled = false
+let currentFlushId = 0
+let activeCleanupFlushId = 0
 // Dual-priority queue for scheduler
 const highPriorityQueue: EffectNode[] = []
 const lowPriorityQueue: EffectNode[] = []
@@ -798,6 +808,8 @@ function updateSignal(s: SignalNode): boolean {
   const current = s.currentValue
   const pending = s.pendingValue
   if (valuesDiffer(s, current, pending)) {
+    s.prevValue = current
+    s.prevFlushId = currentFlushId
     s.currentValue = pending
     return true
   }
@@ -822,6 +834,8 @@ function updateComputed<T>(c: ComputedNode<T>): boolean {
     c.flags &= ~Running
     purgeDeps(c)
     if (valuesDiffer(c, oldValue, newValue)) {
+      c.prevValue = oldValue
+      c.prevFlushId = currentFlushId
       c.value = newValue
       if (isDev) updateComputedDevtools(c, newValue)
       return true
@@ -839,16 +853,20 @@ function updateComputed<T>(c: ComputedNode<T>): boolean {
  */
 function runEffect(e: EffectNode): void {
   const flags = e.flags
-  // Run cleanup BEFORE checkDirty so cleanup sees previous signal values
-  if (flags & Dirty) {
-    if (e.runCleanup) {
-      inCleanup = true
-      try {
-        e.runCleanup()
-      } finally {
-        inCleanup = false
-      }
+  const runCleanup = () => {
+    if (!e.runCleanup) return
+    inCleanup = true
+    activeCleanupFlushId = currentFlushId
+    try {
+      e.runCleanup()
+    } finally {
+      activeCleanupFlushId = 0
+      inCleanup = false
     }
+  }
+  if (flags & Dirty) {
+    // Run cleanup before re-run; values are still the previous commit.
+    runCleanup()
     ++cycle
     if (isDev) effectRunDevtools(e)
     e.depsTail = undefined
@@ -866,15 +884,6 @@ function runEffect(e: EffectNode): void {
       throw err
     }
   } else if (flags & Pending && e.deps) {
-    // Run cleanup before checkDirty which commits signal values
-    if (e.runCleanup) {
-      inCleanup = true
-      try {
-        e.runCleanup()
-      } finally {
-        inCleanup = false
-      }
-    }
     let isDirty = false
     try {
       isDirty = checkDirty(e.deps, e)
@@ -894,6 +903,9 @@ function runEffect(e: EffectNode): void {
       throw err
     }
     if (isDirty) {
+      // Only run cleanup if the effect will actually re-run.
+      // Cleanup reads should observe previous values for this flush.
+      runCleanup()
       ++cycle
       if (isDev) effectRunDevtools(e)
       e.depsTail = undefined
@@ -947,6 +959,7 @@ function flush(): void {
     endFlushGuard()
     return
   }
+  currentFlushId++
   flushScheduled = false
 
   // 1. Process all high-priority effects first
@@ -1071,6 +1084,12 @@ function signalOper<T>(this: SignalNode<T>, value?: T): T | void {
       if (subs !== undefined) shallowPropagate(subs)
     }
   }
+  if (inCleanup) {
+    if (this.prevFlushId === activeCleanupFlushId) {
+      return this.prevValue as T
+    }
+    return this.currentValue
+  }
 
   let sub = activeSub
   while (sub !== undefined) {
@@ -1118,10 +1137,14 @@ export function computed<T>(
   return bound as ComputedAccessor<T>
 }
 function computedOper<T>(this: ComputedNode<T>): T {
-  // fix: During cleanup, return cached value without triggering any updates.
-  // This ensures cleanup functions see the previous state, not the new pending values.
-  // Without this check, checkDirty() could commit pending signal values during cleanup.
-  if (inCleanup) return this.value
+  // fix: During cleanup, return previous value for this flush without triggering updates.
+  // This ensures cleanup functions observe the pre-commit state for this effect.
+  if (inCleanup) {
+    if (this.prevFlushId === activeCleanupFlushId) {
+      return this.prevValue as T
+    }
+    return this.value
+  }
 
   const flags = this.flags
 
@@ -1388,6 +1411,8 @@ export function __resetReactiveState(): void {
   isInTransition = false
   inCleanup = false
   cycle = 0
+  currentFlushId = 0
+  activeCleanupFlushId = 0
 }
 /**
  * Execute a function without tracking dependencies

package/src/ssr-stream.ts

@@ -0,0 +1,38 @@
+export interface SSRStreamHooks {
+  registerBoundary?: (start: Comment, end: Comment) => string | null
+  boundaryPending?: (id: string) => void
+  boundaryResolved?: (id: string) => void
+  onError?: (error: unknown, boundaryId?: string) => void
+}
+
+let ssrStreamHooks: SSRStreamHooks | null = null
+const boundaryStack: string[] = []
+
+export function __fictSetSSRStreamHooks(hooks: SSRStreamHooks | null): void {
+  ssrStreamHooks = hooks
+  if (!hooks) {
+    boundaryStack.length = 0
+  }
+}
+
+export function __fictGetSSRStreamHooks(): SSRStreamHooks | null {
+  return ssrStreamHooks
+}
+
+export function __fictPushSSRBoundary(id: string): void {
+  boundaryStack.push(id)
+}
+
+export function __fictPopSSRBoundary(expected?: string): void {
+  if (boundaryStack.length === 0) return
+  const top = boundaryStack[boundaryStack.length - 1]
+  if (expected && top !== expected) {
+    boundaryStack.pop()
+    return
+  }
+  boundaryStack.pop()
+}
+
+export function __fictGetCurrentSSRBoundary(): string | null {
+  return boundaryStack.length > 0 ? boundaryStack[boundaryStack.length - 1]! : null
+}

package/src/suspense.ts

@@ -12,6 +12,7 @@ import {
 } from './lifecycle'
 import { insertNodesBefore, removeNodes, toNodeArray } from './node-ops'
 import { createSignal } from './signal'
+import { __fictGetSSRStreamHooks, __fictPopSSRBoundary, __fictPushSSRBoundary } from './ssr-stream'
 import type { BaseProps, FictNode, SuspenseToken } from './types'
 
 export interface SuspenseProps extends BaseProps {
@@ -49,6 +50,7 @@ const isThenable = (value: unknown): value is PromiseLike<unknown> =>
   typeof (value as PromiseLike<unknown>).then === 'function'
 
 export function Suspense(props: SuspenseProps): FictNode {
+  const streamHooks = __fictGetSSRStreamHooks()
   const pending = createSignal(0)
   let resolvedOnce = false
   let epoch = 0
@@ -76,7 +78,12 @@ export function Suspense(props: SuspenseProps): FictNode {
     const root = createRootContext(hostRoot)
     const prev = pushRoot(root)
     let nodes: Node[] = []
+    let boundaryPushed = false
     try {
+      if (streamBoundaryId) {
+        __fictPushSSRBoundary(streamBoundaryId)
+        boundaryPushed = true
+      }
       const output = createElement(view)
       nodes = toNodeArray(output)
       // Suspended view: child threw a suspense token and was handled upstream.
@@ -90,9 +97,9 @@ export function Suspense(props: SuspenseProps): FictNode {
         destroyRoot(root)
         return
       }
-      const parentNode = marker.parentNode as (ParentNode & Node) | null
+      const parentNode = endMarker.parentNode as (ParentNode & Node) | null
       if (parentNode) {
-        insertNodesBefore(parentNode, nodes, marker)
+        insertNodesBefore(parentNode, nodes, endMarker)
       }
     } catch (err) {
       popRoot(prev)
@@ -101,6 +108,10 @@ export function Suspense(props: SuspenseProps): FictNode {
         throw err
       }
       return
+    } finally {
+      if (boundaryPushed) {
+        __fictPopSSRBoundary(streamBoundaryId ?? undefined)
+      }
     }
     popRoot(prev)
     flushOnMount(root)
@@ -113,10 +124,22 @@ export function Suspense(props: SuspenseProps): FictNode {
   }
 
   const fragment = document.createDocumentFragment()
-  const marker = document.createComment('fict:suspense')
-  fragment.appendChild(marker)
+  const startMarker = document.createComment('fict:suspense-start')
+  const endMarker = document.createComment('fict:suspense-end')
+  fragment.appendChild(startMarker)
+  fragment.appendChild(endMarker)
   let cleanup: (() => void) | undefined
   let activeNodes: Node[] = []
+  let streamBoundaryId: string | null = null
+  let streamPending = false
+
+  if (streamHooks?.registerBoundary) {
+    streamBoundaryId = streamHooks.registerBoundary(startMarker, endMarker) ?? null
+    if (streamBoundaryId) {
+      startMarker.data = `fict:suspense-start:${streamBoundaryId}`
+      endMarker.data = `fict:suspense-end:${streamBoundaryId}`
+    }
+  }
 
   const onResolveMaybe = () => {
     if (!resolvedOnce) {
@@ -127,6 +150,10 @@ export function Suspense(props: SuspenseProps): FictNode {
 
   registerSuspenseHandler(token => {
     const tokenEpoch = epoch
+    if (!streamPending && streamBoundaryId && streamHooks?.boundaryPending) {
+      streamPending = true
+      streamHooks.boundaryPending(streamBoundaryId)
+    }
     pending(pending() + 1)
     // Directly render fallback instead of using switchView to avoid
     // triggering the effect which would cause duplicate renders
@@ -155,6 +182,10 @@ export function Suspense(props: SuspenseProps): FictNode {
           if (newPending === 0) {
             // Directly render children instead of using switchView
             renderView(props.children ?? null)
+            if (streamPending && streamBoundaryId && streamHooks?.boundaryResolved) {
+              streamPending = false
+              streamHooks.boundaryResolved(streamBoundaryId)
+            }
             onResolveMaybe()
           }
         },
@@ -165,9 +196,29 @@ export function Suspense(props: SuspenseProps): FictNode {
           }
           const newPending = Math.max(0, pending() - 1)
           pending(newPending)
-          props.onReject?.(err)
-          if (!handleError(err, { source: 'render' }, hostRoot)) {
-            throw err
+          let rejectionError = err
+          try {
+            props.onReject?.(err)
+          } catch (callbackError) {
+            rejectionError = callbackError
+          }
+
+          const handled = handleError(rejectionError, { source: 'render' }, hostRoot)
+          if (!handled) {
+            if (streamHooks?.onError) {
+              streamHooks.onError(rejectionError, streamBoundaryId ?? undefined)
+              return
+            }
+            throw rejectionError
+          }
+          if (
+            newPending === 0 &&
+            streamPending &&
+            streamBoundaryId &&
+            streamHooks?.boundaryResolved
+          ) {
+            streamPending = false
+            streamHooks.boundaryResolved(streamBoundaryId)
           }
         },
       )
@@ -195,6 +246,10 @@ export function Suspense(props: SuspenseProps): FictNode {
         pending(0)
         // Directly render children instead of using switchView
         renderView(props.children ?? null)
+        if (streamPending && streamBoundaryId && streamHooks?.boundaryResolved) {
+          streamPending = false
+          streamHooks.boundaryResolved(streamBoundaryId)
+        }
       }
     })
   }