@fictjs/runtime 0.4.0 → 0.5.1

package/src/resume.ts

@@ -0,0 +1,517 @@
+import type { HookContext } from './hooks'
+import { createSignal, isSignal } from './signal'
+import { createStore, isStoreProxy, unwrapStore } from './store'
+
+// ============================================================================
+// Serialization Types
+// ============================================================================
+
+/**
+ * Type markers for serialized values.
+ * These allow us to preserve type information through JSON serialization.
+ */
+type SerializedMarker =
+  | { __t: 'd'; v: number } // Date (as timestamp)
+  | { __t: 'm'; v: [unknown, unknown][] } // Map (as entries array)
+  | { __t: 's'; v: unknown[] } // Set (as array)
+  | { __t: 'r'; v: { s: string; f: string } } // RegExp (source + flags)
+  | { __t: 'u' } // undefined
+  | { __t: 'n' } // NaN
+  | { __t: '+i' } // Infinity
+  | { __t: '-i' } // -Infinity
+  | { __t: 'b'; v: string } // BigInt (as string)
+  | { __t: 'ref'; v: string } // Circular reference (path)
+
+export type SlotSnapshot =
+  | [index: number, type: 'sig', value: unknown]
+  | [index: number, type: 'store', value: unknown]
+  | [index: number, type: 'raw', value: unknown]
+
+export interface ScopeSnapshot {
+  id: string
+  t?: string
+  slots: SlotSnapshot[]
+  props?: Record<string, unknown>
+  vars?: Record<string, number>
+}
+
+export interface SSRState {
+  scopes: Record<string, ScopeSnapshot>
+}
+
+export interface ScopeRecord {
+  id: string
+  ctx: HookContext
+  host: Element
+  type?: string
+  props?: Record<string, unknown>
+}
+
+let ssrEnabled = false
+let resumableEnabled = false
+let hydrating = false
+let scopeCounter = 0
+let scopeRegistry = new Map<string, ScopeRecord>()
+let snapshotState: SSRState | null = null
+const resumedScopes = new Map<
+  string,
+  { ctx: HookContext; host: Element; props?: Record<string, unknown> }
+>()
+
+export function __fictEnableSSR(): void {
+  ssrEnabled = true
+  scopeCounter = 0
+  scopeRegistry = new Map()
+  resumedScopes.clear()
+  snapshotState = null
+}
+
+export function __fictDisableSSR(): void {
+  ssrEnabled = false
+}
+
+export function __fictEnableResumable(): void {
+  resumableEnabled = true
+}
+
+export function __fictDisableResumable(): void {
+  resumableEnabled = false
+  resumedScopes.clear()
+}
+
+export function __fictIsResumable(): boolean {
+  return ssrEnabled || resumableEnabled
+}
+
+export function __fictIsSSR(): boolean {
+  return ssrEnabled
+}
+
+export function __fictEnterHydration(): void {
+  hydrating = true
+}
+
+export function __fictExitHydration(): void {
+  hydrating = false
+}
+
+export function __fictIsHydrating(): boolean {
+  return hydrating
+}
+
+export function __fictRegisterScope(
+  ctx: HookContext,
+  host: Element,
+  type?: string,
+  props?: Record<string, unknown>,
+): string {
+  if (!__fictIsResumable()) return ''
+
+  const id = `s${++scopeCounter}`
+  ctx.scopeId = id
+  if (type !== undefined) {
+    ctx.scopeType = type
+  }
+  host.setAttribute('data-fict-s', id)
+  if (type) {
+    host.setAttribute('data-fict-t', type)
+  }
+
+  const record: ScopeRecord = { id, ctx, host }
+  if (type !== undefined) {
+    record.type = type
+  }
+  if (props !== undefined) {
+    record.props = props
+  }
+  scopeRegistry.set(id, record)
+  return id
+}
+
+export function __fictGetScopeRegistry(): Map<string, ScopeRecord> {
+  return scopeRegistry
+}
+
+export function __fictSerializeSSRState(): SSRState {
+  const scopes: Record<string, ScopeSnapshot> = {}
+
+  for (const [id, record] of scopeRegistry.entries()) {
+    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) {
+    resumedScopes.clear()
+  }
+}
+
+export function __fictGetSSRScope(id: string): ScopeSnapshot | undefined {
+  return snapshotState?.scopes[id]
+}
+
+export function __fictEnsureScope(
+  scopeId: string,
+  host: Element,
+  snapshot?: ScopeSnapshot,
+): HookContext {
+  const existing = resumedScopes.get(scopeId)
+  if (existing) return existing.ctx
+
+  const ctx = createContextFromSnapshot(snapshot)
+  ctx.scopeId = scopeId
+  if (snapshot?.t !== undefined) {
+    ctx.scopeType = snapshot.t
+  }
+  const entry: { ctx: HookContext; host: Element; props?: Record<string, unknown> } = { ctx, host }
+  if (snapshot?.props !== undefined) {
+    entry.props = snapshot.props
+  }
+  resumedScopes.set(scopeId, entry)
+  return ctx
+}
+
+export function __fictUseLexicalScope(scopeId: string, names: string[]): unknown[] {
+  const record = resumedScopes.get(scopeId)
+  if (!record) {
+    throw new Error(`[fict] Missing resumed scope for ${scopeId}`)
+  }
+  const ctx = record.ctx
+  const map = ctx.slotMap ?? {}
+  return names.map(name => ctx.slots[map[name] ?? -1])
+}
+
+export function __fictGetScopeProps(scopeId: string): Record<string, unknown> | undefined {
+  return resumedScopes.get(scopeId)?.props
+}
+
+export function __fictQrl(moduleId: string, exportName: string): string {
+  const manifest = (globalThis as Record<string, unknown>).__FICT_MANIFEST__ as
+    | Record<string, string>
+    | undefined
+
+  // Check manifest first (production builds)
+  if (manifest?.[moduleId]) {
+    return `${manifest[moduleId]}#${exportName}`
+  }
+
+  // Handle file:// URLs for Vite dev mode SSR
+  if (moduleId.startsWith('file://')) {
+    const filePath = moduleId.slice(7) // Remove 'file://'
+
+    // Check for configured SSR base path (project root)
+    const ssrBase = (globalThis as Record<string, unknown>).__FICT_SSR_BASE__ as string | undefined
+    if (ssrBase) {
+      // Strip base to get relative path (e.g., /src/App.tsx)
+      if (filePath.startsWith(ssrBase)) {
+        const relativePath = filePath.slice(ssrBase.length)
+        return `${relativePath}#${exportName}`
+      }
+    }
+
+    // Fallback: use Vite's /@fs/ convention for direct file system access
+    return `/@fs${filePath}#${exportName}`
+  }
+
+  return `${moduleId}#${exportName}`
+}
+
+// Registry for resume functions to prevent tree-shaking
+const resumeFunctionRegistry = new Map<string, (...args: unknown[]) => unknown>()
+
+/**
+ * Register a resume function to prevent it from being tree-shaken.
+ * This is called at module load time by compiled component code.
+ */
+export function __fictRegisterResume(name: string, fn: (...args: unknown[]) => unknown): void {
+  resumeFunctionRegistry.set(name, fn)
+}
+
+/**
+ * Get a registered resume function by name.
+ * Used by the loader to find resume functions.
+ */
+export function __fictGetResume(name: string): ((...args: unknown[]) => unknown) | undefined {
+  return resumeFunctionRegistry.get(name)
+}
+
+function serializeSlots(ctx: HookContext): SlotSnapshot[] {
+  const slots: SlotSnapshot[] = []
+  const values = ctx.slots ?? []
+  // Share the 'seen' map across all slots to handle cross-slot circular references
+  const seen = new Map<object, string>()
+
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i]
+    // Note: we don't skip undefined anymore since we can serialize it
+    if (value === undefined) {
+      slots.push([i, 'raw', serializeValue(undefined, seen, `$[${i}]`)])
+      continue
+    }
+
+    if (isSignal(value)) {
+      try {
+        const raw = (value as () => unknown)()
+        slots.push([i, 'sig', serializeValue(raw, seen, `$[${i}]`)])
+      } catch {
+        // ignore signal read errors during SSR
+      }
+      continue
+    }
+
+    if (isStoreProxy(value)) {
+      const raw = unwrapStore(value)
+      slots.push([i, 'store', serializeValue(raw, seen, `$[${i}]`)])
+      continue
+    }
+
+    // Fallback: serialize raw slot value with complex type support
+    slots.push([i, 'raw', serializeValue(value, seen, `$[${i}]`)])
+  }
+
+  return slots
+}
+
+function createContextFromSnapshot(snapshot?: ScopeSnapshot): HookContext {
+  const ctx: HookContext = { slots: [], cursor: 0 }
+  if (!snapshot) return ctx
+
+  for (const slot of snapshot.slots) {
+    const [index, type, value] = slot
+    if (type === 'sig') {
+      ctx.slots[index] = createSignal(deserializeValue(value))
+    } else if (type === 'store') {
+      ctx.slots[index] = createStore(deserializeValue(value) as object)[0]
+    } else {
+      ctx.slots[index] = deserializeValue(value)
+    }
+  }
+  if (snapshot.vars) {
+    ctx.slotMap = { ...snapshot.vars }
+  }
+
+  return ctx
+}
+
+// ============================================================================
+// Value Serialization - Complex Type Support
+// ============================================================================
+
+/**
+ * Check if value has a serialization marker
+ */
+function isSerializedMarker(value: unknown): value is SerializedMarker {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '__t' in value &&
+    typeof (value as SerializedMarker).__t === 'string'
+  )
+}
+
+/**
+ * Serialize a value with support for complex types.
+ * Handles: Date, Map, Set, RegExp, undefined, NaN, Infinity, -Infinity, BigInt, circular references
+ */
+export function serializeValue(
+  value: unknown,
+  seen = new Map<object, string>(),
+  path = '$',
+): unknown {
+  // Handle primitives that JSON can't represent correctly
+  if (value === undefined) {
+    return { __t: 'u' } as SerializedMarker
+  }
+
+  if (typeof value === 'number') {
+    if (Number.isNaN(value)) {
+      return { __t: 'n' } as SerializedMarker
+    }
+    if (value === Infinity) {
+      return { __t: '+i' } as SerializedMarker
+    }
+    if (value === -Infinity) {
+      return { __t: '-i' } as SerializedMarker
+    }
+    return value
+  }
+
+  if (typeof value === 'bigint') {
+    return { __t: 'b', v: value.toString() } as SerializedMarker
+  }
+
+  // Primitives that JSON handles correctly
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') {
+    return value
+  }
+
+  // Handle functions - can't serialize, skip
+  if (typeof value === 'function') {
+    return undefined
+  }
+
+  // Handle objects - check for circular references first
+  if (typeof value === 'object') {
+    // Check for circular reference
+    if (seen.has(value)) {
+      return { __t: 'ref', v: seen.get(value)! } as SerializedMarker
+    }
+
+    // Date
+    if (value instanceof Date) {
+      return { __t: 'd', v: value.getTime() } as SerializedMarker
+    }
+
+    // RegExp
+    if (value instanceof RegExp) {
+      return { __t: 'r', v: { s: value.source, f: value.flags } } as SerializedMarker
+    }
+
+    // Map
+    if (value instanceof Map) {
+      seen.set(value, path)
+      const entries: [unknown, unknown][] = []
+      let i = 0
+      for (const [k, v] of value) {
+        entries.push([
+          serializeValue(k, seen, `${path}.k${i}`),
+          serializeValue(v, seen, `${path}.v${i}`),
+        ])
+        i++
+      }
+      return { __t: 'm', v: entries } as SerializedMarker
+    }
+
+    // Set
+    if (value instanceof Set) {
+      seen.set(value, path)
+      const items: unknown[] = []
+      let i = 0
+      for (const item of value) {
+        items.push(serializeValue(item, seen, `${path}[${i}]`))
+        i++
+      }
+      return { __t: 's', v: items } as SerializedMarker
+    }
+
+    // Array
+    if (Array.isArray(value)) {
+      seen.set(value, path)
+      return value.map((item, i) => serializeValue(item, seen, `${path}[${i}]`))
+    }
+
+    // Plain object
+    seen.set(value, path)
+    const result: Record<string, unknown> = {}
+    for (const key of Object.keys(value)) {
+      const serialized = serializeValue(
+        (value as Record<string, unknown>)[key],
+        seen,
+        `${path}.${key}`,
+      )
+      if (serialized !== undefined) {
+        result[key] = serialized
+      }
+    }
+    return result
+  }
+
+  return value
+}
+
+/**
+ * Deserialize a value, restoring complex types from their serialized form.
+ */
+export function deserializeValue(
+  value: unknown,
+  refs = new Map<string, unknown>(),
+  path = '$',
+): unknown {
+  // Handle null
+  if (value === null) {
+    return null
+  }
+
+  // Handle primitives
+  if (typeof value !== 'object') {
+    return value
+  }
+
+  // Check for serialization markers
+  if (isSerializedMarker(value)) {
+    switch (value.__t) {
+      case 'u':
+        return undefined
+      case 'n':
+        return NaN
+      case '+i':
+        return Infinity
+      case '-i':
+        return -Infinity
+      case 'b':
+        return BigInt(value.v)
+      case 'd':
+        return new Date(value.v)
+      case 'r':
+        return new RegExp(value.v.s, value.v.f)
+      case 'm': {
+        const map = new Map<unknown, unknown>()
+        refs.set(path, map)
+        for (let i = 0; i < value.v.length; i++) {
+          const entry = value.v[i]
+          if (!entry) continue
+          const [k, v] = entry
+          map.set(
+            deserializeValue(k, refs, `${path}.k${i}`),
+            deserializeValue(v, refs, `${path}.v${i}`),
+          )
+        }
+        return map
+      }
+      case 's': {
+        const set = new Set<unknown>()
+        refs.set(path, set)
+        for (let i = 0; i < value.v.length; i++) {
+          set.add(deserializeValue(value.v[i], refs, `${path}[${i}]`))
+        }
+        return set
+      }
+      case 'ref':
+        return refs.get(value.v)
+    }
+  }
+
+  // Handle arrays
+  if (Array.isArray(value)) {
+    const arr: unknown[] = []
+    refs.set(path, arr)
+    for (let i = 0; i < value.length; i++) {
+      arr.push(deserializeValue(value[i], refs, `${path}[${i}]`))
+    }
+    return arr
+  }
+
+  // Handle plain objects
+  const obj: Record<string, unknown> = {}
+  refs.set(path, obj)
+  for (const key of Object.keys(value)) {
+    obj[key] = deserializeValue((value as Record<string, unknown>)[key], refs, `${path}.${key}`)
+  }
+  return obj
+}

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/store.ts

@@ -131,6 +131,14 @@ function unwrap<T>(value: T): T {
   return value
 }
 
+export function isStoreProxy(value: unknown): boolean {
+  return !!(value && typeof value === 'object' && Reflect.get(value as object, PROXY))
+}
+
+export function unwrapStore<T>(value: T): T {
+  return unwrap(value)
+}
+
 function track(target: object, prop: string | symbol) {
   let signals = signalCache.get(target)
   if (!signals) {