@fictjs/runtime 0.0.2

package/src/slim.ts

@@ -0,0 +1,68 @@
+/**
+ * Slim fine-grained runtime entry for bundle-sensitive builds.
+ *
+ * Exposes only the DOM + signals surface required by compiler output and
+ * leaves out stores, resources, SSR, devtools, etc.
+ */
+
+// Reactive primitives
+export { createSignal, createSelector, $state } from './signal'
+export { createMemo } from './memo'
+export { createEffect, createRenderEffect } from './effect'
+export { batch, untrack } from './scheduler'
+
+// DOM rendering
+export { render, template, createElement } from './dom'
+export { Fragment } from './jsx'
+
+// Core bindings used by compiler output
+export {
+  insert,
+  bindText,
+  bindAttribute,
+  bindProperty,
+  bindClass,
+  bindStyle,
+  bindEvent,
+  bindRef,
+  createConditional,
+  createList,
+  delegateEvents,
+  clearDelegatedEvents,
+} from './binding'
+
+// Keyed list helpers (fine-grained DOM)
+export {
+  createKeyedListContainer,
+  createKeyedList,
+  createKeyedBlock,
+  moveMarkerBlock,
+  destroyMarkerBlock,
+  insertNodesBefore,
+  removeNodes,
+  toNodeArray,
+  getFirstNodeAfter,
+} from './list-helpers'
+
+// Minimal hooks surface for builds that rely on hook helpers
+export {
+  __fictUseContext,
+  __fictUseSignal,
+  __fictUseMemo,
+  __fictUseEffect,
+  __fictRender,
+  __fictPushContext,
+  __fictPopContext,
+  __fictResetContext,
+} from './hooks'
+
+// Props helpers (kept minimal for compatibility with compiler output)
+export {
+  __fictProp,
+  __fictProp as prop,
+  __fictPropsRest,
+  mergeProps,
+  useProp,
+  createPropsProxy,
+} from './props'
+export { onDestroy } from './lifecycle'

package/src/store.ts

@@ -0,0 +1,210 @@
+import { signal, batch, type SignalAccessor } from './signal'
+
+const PROXY = Symbol('fict:store-proxy')
+const TARGET = Symbol('fict:store-target')
+
+// ============================================================================
+// Store (Deep Proxy)
+// ============================================================================
+
+export type Store<T> = T
+
+/**
+ * Create a Store: a reactive proxy that allows fine-grained access and mutation.
+ *
+ * @param initialValue - The initial state object
+ * @returns [store, setStore]
+ */
+export function createStore<T extends object>(
+  initialValue: T,
+): [Store<T>, (fn: (state: T) => void | T) => void] {
+  const unwrapped = unwrap(initialValue)
+  const wrapped = wrap(unwrapped)
+
+  function setStore(fn: (state: T) => void | T) {
+    batch(() => {
+      const result = fn(wrapped)
+      if (result !== undefined) {
+        reconcile(wrapped, result)
+      }
+    })
+  }
+
+  return [wrapped, setStore]
+}
+
+// Map of target object -> Proxy
+const proxyCache = new WeakMap<object, any>()
+// Map of target object -> Map<key, Signal>
+const signalCache = new WeakMap<object, Map<string | symbol, SignalAccessor<any>>>()
+
+function wrap<T>(value: T): T {
+  if (value === null || typeof value !== 'object') return value
+  if ((value as any)[PROXY]) return value
+
+  if (proxyCache.has(value)) return proxyCache.get(value)
+
+  const handler: ProxyHandler<any> = {
+    get(target, prop, receiver) {
+      if (prop === PROXY) return true
+      if (prop === TARGET) return target
+
+      const value = Reflect.get(target, prop, receiver)
+
+      // Track property access
+      track(target, prop)
+
+      // Recursively wrap objects
+      return wrap(value)
+    },
+    set(target, prop, value, receiver) {
+      if (prop === PROXY || prop === TARGET) return false
+
+      const oldValue = Reflect.get(target, prop, receiver)
+      if (oldValue === value) return true
+
+      const result = Reflect.set(target, prop, value, receiver)
+      if (result) {
+        trigger(target, prop)
+      }
+      return result
+    },
+    deleteProperty(target, prop) {
+      const result = Reflect.deleteProperty(target, prop)
+      if (result) {
+        trigger(target, prop)
+      }
+      return result
+    },
+  }
+
+  const proxy = new Proxy(value, handler)
+  proxyCache.set(value, proxy)
+  return proxy as T
+}
+
+function unwrap<T>(value: T): T {
+  if (value && typeof value === 'object' && (value as any)[PROXY]) {
+    return (value as any)[TARGET]
+  }
+  return value
+}
+
+function track(target: object, prop: string | symbol) {
+  let signals = signalCache.get(target)
+  if (!signals) {
+    signals = new Map()
+    signalCache.set(target, signals)
+  }
+
+  let s = signals.get(prop)
+  if (!s) {
+    s = signal(getLastValue(target, prop))
+    signals.set(prop, s)
+  }
+  s() // subscribe
+}
+
+function trigger(target: object, prop: string | symbol) {
+  const signals = signalCache.get(target)
+  if (signals) {
+    const s = signals.get(prop)
+    if (s) {
+      s(getLastValue(target, prop)) // notify with new value
+    }
+  }
+}
+
+function getLastValue(target: any, prop: string | symbol) {
+  return target[prop]
+}
+
+/**
+ * Reconcile a store path with a new value (shallow merge/diff)
+ */
+function reconcile(target: any, value: any) {
+  if (target === value) return
+  if (value === null || typeof value !== 'object') return // Should replace?
+
+  const realTarget = unwrap(target)
+  const realValue = unwrap(value)
+
+  const keys = new Set([...Object.keys(realTarget), ...Object.keys(realValue)])
+  for (const key of keys) {
+    if (realValue[key] === undefined && realTarget[key] !== undefined) {
+      // deleted
+      delete target[key] // Triggers proxy trap
+    } else if (realTarget[key] !== realValue[key]) {
+      target[key] = realValue[key] // Triggers proxy trap
+    }
+  }
+}
+
+// ============================================================================
+// Diffing Signal (for List Items)
+// ============================================================================
+
+/**
+ * Creates a signal that returns a Stable Proxy.
+ * Updates to the signal (via set) will diff the new value against the old value
+ * and trigger property-specific updates.
+ */
+export function createDiffingSignal<T extends object>(initialValue: T) {
+  let currentValue = unwrap(initialValue)
+  const signals = new Map<string | symbol, SignalAccessor<any>>()
+
+  // The stable proxy we return
+  const proxy = new Proxy({} as T, {
+    get(_, prop) {
+      if (prop === PROXY) return true
+      if (prop === TARGET) return currentValue
+
+      // Subscribe to property
+      let s = signals.get(prop)
+      if (!s) {
+        // Initialize signal with current property value
+        s = signal((currentValue as any)[prop])
+        signals.set(prop, s)
+      }
+      return s()
+    },
+    ownKeys() {
+      return Reflect.ownKeys(currentValue)
+    },
+  })
+
+  const read = () => proxy
+
+  const write = (newValue: T) => {
+    const next = unwrap(newValue)
+    const prev = currentValue
+    currentValue = next
+
+    if (prev === next) {
+      // Same ref update: re-evaluate all tracked signals
+      // This is necessary for in-place mutations
+      for (const [prop, s] of signals) {
+        const newVal = (next as any)[prop]
+        s(newVal)
+      }
+      return
+    }
+
+    // Diff logic
+    // We only trigger signals for properties that exist in our cache (tracked)
+    // and have changed.
+    for (const [prop, s] of signals) {
+      const oldVal = (prev as any)[prop]
+      const newVal = (next as any)[prop]
+      if (oldVal !== newVal) {
+        s(newVal)
+      }
+    }
+
+    // Note: If new properties appeared that weren't tracked, we don't care
+    // because no one is listening.
+    // If we assume shape stability (Keyed List), this is efficient.
+  }
+
+  return [read, write] as const
+}

package/src/suspense.ts

@@ -0,0 +1,187 @@
+import { createElement } from './dom'
+import { createEffect } from './effect'
+import {
+  createRootContext,
+  destroyRoot,
+  flushOnMount,
+  getCurrentRoot,
+  handleError,
+  pushRoot,
+  popRoot,
+  registerSuspenseHandler,
+} from './lifecycle'
+import { insertNodesBefore, removeNodes, toNodeArray } from './node-ops'
+import { createSignal } from './signal'
+import type { BaseProps, FictNode, SuspenseToken } from './types'
+
+export interface SuspenseProps extends BaseProps {
+  fallback: FictNode | ((err?: unknown) => FictNode)
+  onResolve?: () => void
+  onReject?: (err: unknown) => void
+  resetKeys?: unknown | (() => unknown)
+}
+
+export interface SuspenseHandle {
+  token: SuspenseToken
+  resolve: () => void
+  reject: (err: unknown) => void
+}
+
+export function createSuspenseToken(): SuspenseHandle {
+  let resolve!: () => void
+  let reject!: (err: unknown) => void
+  const promise = new Promise<void>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return {
+    token: {
+      then: promise.then.bind(promise),
+    },
+    resolve,
+    reject,
+  }
+}
+
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as PromiseLike<unknown>).then === 'function'
+
+export function Suspense(props: SuspenseProps): FictNode {
+  const currentView = createSignal<FictNode | null>(props.children ?? null)
+  const pending = createSignal(0)
+  let resolvedOnce = false
+  let epoch = 0
+  const hostRoot = getCurrentRoot()
+
+  const toFallback = (err?: unknown) =>
+    typeof props.fallback === 'function'
+      ? (props.fallback as (e?: unknown) => FictNode)(err)
+      : props.fallback
+
+  const switchView = (view: FictNode | null) => {
+    currentView(view)
+    renderView(view)
+  }
+
+  const renderView = (view: FictNode | null) => {
+    if (cleanup) {
+      cleanup()
+      cleanup = undefined
+    }
+    if (activeNodes.length) {
+      removeNodes(activeNodes)
+      activeNodes = []
+    }
+
+    if (view == null || view === false) {
+      return
+    }
+
+    const root = createRootContext(hostRoot)
+    const prev = pushRoot(root)
+    let nodes: Node[] = []
+    try {
+      const output = createElement(view)
+      nodes = toNodeArray(output)
+      // Suspended view: child threw a suspense token and was handled upstream.
+      // Avoid replacing existing fallback content; tear down this attempt.
+      const suspendedAttempt =
+        nodes.length > 0 &&
+        nodes.every(node => node instanceof Comment && (node as Comment).data === 'fict:suspend')
+      if (suspendedAttempt) {
+        popRoot(prev)
+        destroyRoot(root)
+        return
+      }
+      const parentNode = marker.parentNode as (ParentNode & Node) | null
+      if (parentNode) {
+        insertNodesBefore(parentNode, nodes, marker)
+      }
+    } catch (err) {
+      popRoot(prev)
+      flushOnMount(root)
+      destroyRoot(root)
+      handleError(err, { source: 'render' })
+      return
+    }
+    popRoot(prev)
+    flushOnMount(root)
+
+    cleanup = () => {
+      destroyRoot(root)
+      removeNodes(nodes)
+    }
+    activeNodes = nodes
+  }
+
+  const fragment = document.createDocumentFragment()
+  const marker = document.createComment('fict:suspense')
+  fragment.appendChild(marker)
+  let cleanup: (() => void) | undefined
+  let activeNodes: Node[] = []
+
+  const onResolveMaybe = () => {
+    if (!resolvedOnce) {
+      resolvedOnce = true
+      props.onResolve?.()
+    }
+  }
+
+  registerSuspenseHandler(token => {
+    const tokenEpoch = epoch
+    pending(pending() + 1)
+    switchView(toFallback())
+
+    const thenable = (token as SuspenseToken).then
+      ? (token as SuspenseToken)
+      : isThenable(token)
+        ? token
+        : null
+
+    if (thenable) {
+      thenable.then(
+        () => {
+          if (epoch !== tokenEpoch) return
+          pending(Math.max(0, pending() - 1))
+          if (pending() === 0) {
+            switchView(props.children ?? null)
+            onResolveMaybe()
+          }
+        },
+        err => {
+          if (epoch !== tokenEpoch) return
+          pending(Math.max(0, pending() - 1))
+          props.onReject?.(err)
+          handleError(err, { source: 'render' }, hostRoot)
+        },
+      )
+      return true
+    }
+
+    return false
+  })
+
+  createEffect(() => {
+    renderView(currentView())
+  })
+
+  if (props.resetKeys !== undefined) {
+    const isGetter =
+      typeof props.resetKeys === 'function' && (props.resetKeys as () => unknown).length === 0
+    const getter = isGetter ? (props.resetKeys as () => unknown) : undefined
+    let prev = isGetter ? getter!() : props.resetKeys
+    createEffect(() => {
+      const next = getter ? getter() : props.resetKeys
+      if (prev !== next) {
+        prev = next
+        epoch++
+        pending(0)
+        switchView(props.children ?? null)
+      }
+    })
+  }
+
+  return fragment
+}

package/src/transition.ts

@@ -0,0 +1,128 @@
+import { createEffect } from './effect'
+import { setTransitionContext, signal, scheduleFlush, untrack } from './signal'
+
+// ============================================================================
+// startTransition - Mark updates as low priority
+// ============================================================================
+
+/**
+ * Execute a function with low-priority scheduling.
+ * Updates triggered inside the callback will be processed after any high-priority updates.
+ * This keeps the UI responsive during expensive operations.
+ *
+ * @param fn - The function to execute in transition context
+ *
+ * @example
+ * ```tsx
+ * const handleInput = (e) => {
+ *   query = e.target.value  // High priority: immediate
+ *   startTransition(() => {
+ *     // Low priority: processed after high priority updates
+ *     filteredItems = allItems.filter(x => x.includes(query))
+ *   })
+ * }
+ * ```
+ */
+export function startTransition(fn: () => void): void {
+  const prev = setTransitionContext(true)
+  try {
+    fn()
+  } finally {
+    setTransitionContext(prev)
+    scheduleFlush()
+  }
+}
+
+// ============================================================================
+// useTransition - Hook for managing transition state
+// ============================================================================
+
+/**
+ * React-style useTransition hook.
+ * Returns a pending signal and a startTransition function.
+ *
+ * @returns A tuple of [isPending accessor, startTransition function]
+ *
+ * @example
+ * ```tsx
+ * function SearchComponent() {
+ *   let query = $state('')
+ *   const [isPending, start] = useTransition()
+ *
+ *   const handleChange = (e) => {
+ *     query = e.target.value
+ *     start(() => {
+ *       // Expensive filtering happens in low priority
+ *       filteredResults = expensiveFilter(allData, query)
+ *     })
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <input value={query} onInput={handleChange} />
+ *       {isPending() && <Spinner />}
+ *       <Results items={filteredResults} />
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export function useTransition(): [() => boolean, (fn: () => void) => void] {
+  const pending = signal(false)
+
+  const start = (fn: () => void) => {
+    pending(true)
+    startTransition(() => {
+      try {
+        fn()
+      } finally {
+        pending(false)
+      }
+    })
+  }
+
+  return [() => pending(), start]
+}
+
+// ============================================================================
+// useDeferredValue - Defer value updates to low priority
+// ============================================================================
+
+/**
+ * Creates a deferred version of a value that updates with low priority.
+ * The returned accessor will lag behind the source value during rapid updates,
+ * allowing high-priority work to complete first.
+ *
+ * @param getValue - Accessor function that returns the source value
+ * @returns Accessor function that returns the deferred value
+ *
+ * @example
+ * ```tsx
+ * function SearchResults({ query }) {
+ *   const deferredQuery = useDeferredValue(() => query)
+ *
+ *   // deferredQuery lags behind query during rapid typing
+ *   const results = expensiveSearch(deferredQuery())
+ *
+ *   return <ResultList items={results} />
+ * }
+ * ```
+ */
+export function useDeferredValue<T>(getValue: () => T): () => T {
+  const deferredValue = signal(getValue())
+
+  // Track source value changes and update deferred value in transition
+  createEffect(() => {
+    const newValue = getValue()
+    // Use untrack to read current deferred value without creating a dependency
+    // This prevents the effect from re-running when deferredValue changes
+    const currentDeferred = untrack(() => deferredValue())
+    if (currentDeferred !== newValue) {
+      startTransition(() => {
+        deferredValue(newValue)
+      })
+    }
+  })
+
+  return () => deferredValue()
+}